From 3d08cd331c1adcf0d917392f7e527b3f00511748 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Merging upstream version 6.8. Signed-off-by: Daniel Baumann --- man/man1/getent.1 | 387 ++ man/man1/iconv.1 | 204 + man/man1/intro.1 | 305 ++ man/man1/ldd.1 | 180 + man/man1/locale.1 | 208 + man/man1/localedef.1 | 415 ++ man/man1/memusage.1 | 262 ++ man/man1/memusagestat.1 | 73 + man/man1/mtrace.1 | 47 + man/man1/pldd.1 | 105 + man/man1/sprof.1 | 282 ++ man/man1/time.1 | 329 ++ man/man2/_Exit.2 | 1 + man/man2/__clone2.2 | 1 + man/man2/_exit.2 | 138 + man/man2/_llseek.2 | 1 + man/man2/_newselect.2 | 1 + man/man2/_syscall.2 | 171 + man/man2/_sysctl.2 | 1 + man/man2/accept.2 | 349 ++ man/man2/accept4.2 | 1 + man/man2/access.2 | 468 ++ man/man2/acct.2 | 136 + man/man2/add_key.2 | 298 ++ man/man2/adjtimex.2 | 595 +++ man/man2/afs_syscall.2 | 1 + man/man2/alarm.2 | 81 + man/man2/alloc_hugepages.2 | 135 + man/man2/arch_prctl.2 | 176 + man/man2/arm_fadvise.2 | 1 + man/man2/arm_fadvise64_64.2 | 1 + man/man2/arm_sync_file_range.2 | 1 + man/man2/bdflush.2 | 103 + man/man2/bind.2 | 286 ++ man/man2/bpf.2 | 1273 ++++++ man/man2/break.2 | 1 + man/man2/brk.2 | 153 + man/man2/cacheflush.2 | 143 + man/man2/capget.2 | 260 ++ man/man2/capset.2 | 1 + man/man2/chdir.2 | 127 + man/man2/chmod.2 | 347 ++ man/man2/chown.2 | 472 +++ man/man2/chown32.2 | 1 + man/man2/chroot.2 | 166 + man/man2/clock_adjtime.2 | 1 + man/man2/clock_getres.2 | 539 +++ man/man2/clock_gettime.2 | 1 + man/man2/clock_nanosleep.2 | 253 ++ man/man2/clock_settime.2 | 1 + man/man2/clone.2 | 1950 +++++++++ man/man2/clone2.2 | 1 + man/man2/clone3.2 | 1 + man/man2/close.2 | 274 ++ man/man2/close_range.2 | 277 ++ man/man2/connect.2 | 253 ++ man/man2/copy_file_range.2 | 308 ++ man/man2/creat.2 | 1 + man/man2/create_module.2 | 72 + man/man2/delete_module.2 | 205 + man/man2/dup.2 | 284 ++ man/man2/dup2.2 | 1 + man/man2/dup3.2 | 1 + man/man2/epoll_create.2 | 144 + man/man2/epoll_create1.2 | 1 + man/man2/epoll_ctl.2 | 429 ++ man/man2/epoll_pwait.2 | 1 + man/man2/epoll_pwait2.2 | 1 + man/man2/epoll_wait.2 | 288 ++ man/man2/eventfd.2 | 447 ++ man/man2/eventfd2.2 | 1 + man/man2/execve.2 | 889 ++++ man/man2/execveat.2 | 220 + man/man2/exit.2 | 1 + man/man2/exit_group.2 | 38 + man/man2/faccessat.2 | 1 + man/man2/faccessat2.2 | 1 + man/man2/fadvise64.2 | 1 + man/man2/fadvise64_64.2 | 1 + man/man2/fallocate.2 | 481 +++ man/man2/fanotify_init.2 | 542 +++ man/man2/fanotify_mark.2 | 850 ++++ man/man2/fattach.2 | 1 + man/man2/fchdir.2 | 1 + man/man2/fchmod.2 | 1 + man/man2/fchmodat.2 | 1 + man/man2/fchown.2 | 1 + man/man2/fchown32.2 | 1 + man/man2/fchownat.2 | 1 + man/man2/fcntl.2 | 2113 +++++++++ man/man2/fcntl64.2 | 1 + man/man2/fdatasync.2 | 1 + man/man2/fdetach.2 | 1 + man/man2/fgetxattr.2 | 1 + man/man2/finit_module.2 | 1 + man/man2/flistxattr.2 | 1 + man/man2/flock.2 | 267 ++ man/man2/fork.2 | 349 ++ man/man2/free_hugepages.2 | 1 + man/man2/fremovexattr.2 | 1 + man/man2/fsetxattr.2 | 1 + man/man2/fstat.2 | 1 + man/man2/fstat64.2 | 1 + man/man2/fstatat.2 | 1 + man/man2/fstatat64.2 | 1 + man/man2/fstatfs.2 | 1 + man/man2/fstatfs64.2 | 1 + man/man2/fsync.2 | 200 + man/man2/ftruncate.2 | 1 + man/man2/ftruncate64.2 | 1 + man/man2/futex.2 | 1976 +++++++++ man/man2/futimesat.2 | 128 + man/man2/get_kernel_syms.2 | 88 + man/man2/get_mempolicy.2 | 239 ++ man/man2/get_robust_list.2 | 156 + man/man2/get_thread_area.2 | 1 + man/man2/getcpu.2 | 147 + man/man2/getcwd.2 | 2 + man/man2/getdents.2 | 324 ++ man/man2/getdents64.2 | 1 + man/man2/getdomainname.2 | 122 + man/man2/getegid.2 | 1 + man/man2/getegid32.2 | 1 + man/man2/geteuid.2 | 1 + man/man2/geteuid32.2 | 1 + man/man2/getgid.2 | 70 + man/man2/getgid32.2 | 1 + man/man2/getgroups.2 | 219 + man/man2/getgroups32.2 | 1 + man/man2/gethostname.2 | 176 + man/man2/getitimer.2 | 278 ++ man/man2/getmsg.2 | 1 + man/man2/getpagesize.2 | 67 + man/man2/getpeername.2 | 116 + man/man2/getpgid.2 | 1 + man/man2/getpgrp.2 | 1 + man/man2/getpid.2 | 150 + man/man2/getpmsg.2 | 1 + man/man2/getppid.2 | 1 + man/man2/getpriority.2 | 209 + man/man2/getrandom.2 | 295 ++ man/man2/getresgid.2 | 1 + man/man2/getresgid32.2 | 1 + man/man2/getresuid.2 | 70 + man/man2/getresuid32.2 | 1 + man/man2/getrlimit.2 | 853 ++++ man/man2/getrusage.2 | 250 ++ man/man2/getsid.2 | 75 + man/man2/getsockname.2 | 85 + man/man2/getsockopt.2 | 172 + man/man2/gettid.2 | 74 + man/man2/gettimeofday.2 | 296 ++ man/man2/getuid.2 | 80 + man/man2/getuid32.2 | 1 + man/man2/getunwind.2 | 87 + man/man2/getxattr.2 | 143 + man/man2/gtty.2 | 1 + man/man2/idle.2 | 44 + man/man2/inb.2 | 1 + man/man2/inb_p.2 | 1 + man/man2/init_module.2 | 393 ++ man/man2/inl.2 | 1 + man/man2/inl_p.2 | 1 + man/man2/inotify_add_watch.2 | 135 + man/man2/inotify_init.2 | 97 + man/man2/inotify_init1.2 | 1 + man/man2/inotify_rm_watch.2 | 60 + man/man2/insb.2 | 1 + man/man2/insl.2 | 1 + man/man2/insw.2 | 1 + man/man2/intro.2 | 115 + man/man2/inw.2 | 1 + man/man2/inw_p.2 | 1 + man/man2/io_cancel.2 | 106 + man/man2/io_destroy.2 | 97 + man/man2/io_getevents.2 | 137 + man/man2/io_setup.2 | 114 + man/man2/io_submit.2 | 289 ++ man/man2/ioctl.2 | 231 + man/man2/ioctl_console.2 | 915 ++++ man/man2/ioctl_fat.2 | 489 +++ man/man2/ioctl_ficlone.2 | 1 + man/man2/ioctl_ficlonerange.2 | 129 + man/man2/ioctl_fideduperange.2 | 200 + man/man2/ioctl_fslabel.2 | 72 + man/man2/ioctl_getfsmap.2 | 351 ++ man/man2/ioctl_iflags.2 | 202 + man/man2/ioctl_ns.2 | 342 ++ man/man2/ioctl_pagemap_scan.2 | 206 + man/man2/ioctl_pipe.2 | 64 + man/man2/ioctl_tty.2 | 922 ++++ man/man2/ioctl_userfaultfd.2 | 1072 +++++ man/man2/ioperm.2 | 105 + man/man2/iopl.2 | 92 + man/man2/ioprio_get.2 | 1 + man/man2/ioprio_set.2 | 362 ++ man/man2/ipc.2 | 63 + man/man2/isastream.2 | 1 + man/man2/kcmp.2 | 421 ++ man/man2/kexec_file_load.2 | 1 + man/man2/kexec_load.2 | 331 ++ man/man2/keyctl.2 | 2297 ++++++++++ man/man2/kill.2 | 165 + man/man2/landlock_add_rule.2 | 131 + man/man2/landlock_create_ruleset.2 | 124 + man/man2/landlock_restrict_self.2 | 116 + man/man2/lchown.2 | 1 + man/man2/lchown32.2 | 1 + man/man2/lgetxattr.2 | 1 + man/man2/link.2 | 425 ++ man/man2/linkat.2 | 1 + man/man2/listen.2 | 155 + man/man2/listxattr.2 | 322 ++ man/man2/llistxattr.2 | 1 + man/man2/llseek.2 | 92 + man/man2/lock.2 | 1 + man/man2/lookup_dcookie.2 | 86 + man/man2/lremovexattr.2 | 1 + man/man2/lseek.2 | 252 ++ man/man2/lsetxattr.2 | 1 + man/man2/lstat.2 | 1 + man/man2/lstat64.2 | 1 + man/man2/madvise.2 | 898 ++++ man/man2/madvise1.2 | 1 + man/man2/mbind.2 | 521 +++ man/man2/membarrier.2 | 460 ++ man/man2/memfd_create.2 | 550 +++ man/man2/memfd_secret.2 | 204 + man/man2/migrate_pages.2 | 174 + man/man2/mincore.2 | 158 + man/man2/mkdir.2 | 250 ++ man/man2/mkdirat.2 | 1 + man/man2/mknod.2 | 302 ++ man/man2/mknodat.2 | 1 + man/man2/mlock.2 | 507 +++ man/man2/mlock2.2 | 1 + man/man2/mlockall.2 | 1 + man/man2/mmap.2 | 1038 +++++ man/man2/mmap2.2 | 85 + man/man2/modify_ldt.2 | 196 + man/man2/mount.2 | 971 +++++ man/man2/mount_setattr.2 | 1067 +++++ man/man2/move_pages.2 | 253 ++ man/man2/mprotect.2 | 363 ++ man/man2/mpx.2 | 1 + man/man2/mq_getsetattr.2 | 33 + man/man2/mq_notify.2 | 2 + man/man2/mq_open.2 | 2 + man/man2/mq_timedreceive.2 | 2 + man/man2/mq_timedsend.2 | 2 + man/man2/mq_unlink.2 | 2 + man/man2/mremap.2 | 357 ++ man/man2/msgctl.2 | 424 ++ man/man2/msgget.2 | 217 + man/man2/msgop.2 | 684 +++ man/man2/msgrcv.2 | 1 + man/man2/msgsnd.2 | 1 + man/man2/msync.2 | 140 + man/man2/munlock.2 | 1 + man/man2/munlockall.2 | 1 + man/man2/munmap.2 | 1 + man/man2/name_to_handle_at.2 | 1 + man/man2/nanosleep.2 | 221 + man/man2/newfstatat.2 | 1 + man/man2/nfsservctl.2 | 70 + man/man2/nice.2 | 118 + man/man2/oldfstat.2 | 1 + man/man2/oldlstat.2 | 1 + man/man2/oldolduname.2 | 1 + man/man2/oldstat.2 | 1 + man/man2/olduname.2 | 1 + man/man2/open.2 | 1941 +++++++++ man/man2/open_by_handle_at.2 | 788 ++++ man/man2/openat.2 | 1 + man/man2/openat2.2 | 582 +++ man/man2/outb.2 | 84 + man/man2/outb_p.2 | 1 + man/man2/outl.2 | 1 + man/man2/outl_p.2 | 1 + man/man2/outsb.2 | 1 + man/man2/outsl.2 | 1 + man/man2/outsw.2 | 1 + man/man2/outw.2 | 1 + man/man2/outw_p.2 | 1 + man/man2/pause.2 | 50 + man/man2/pciconfig_iobase.2 | 1 + man/man2/pciconfig_read.2 | 122 + man/man2/pciconfig_write.2 | 1 + man/man2/perf_event_open.2 | 4037 ++++++++++++++++++ man/man2/perfmonctl.2 | 193 + man/man2/personality.2 | 296 ++ man/man2/phys.2 | 1 + man/man2/pidfd_getfd.2 | 144 + man/man2/pidfd_open.2 | 270 ++ man/man2/pidfd_send_signal.2 | 240 ++ man/man2/pipe.2 | 305 ++ man/man2/pipe2.2 | 1 + man/man2/pivot_root.2 | 409 ++ man/man2/pkey_alloc.2 | 115 + man/man2/pkey_free.2 | 1 + man/man2/pkey_mprotect.2 | 1 + man/man2/poll.2 | 650 +++ man/man2/posix_fadvise.2 | 227 + man/man2/ppoll.2 | 1 + man/man2/prctl.2 | 2577 +++++++++++ man/man2/pread.2 | 146 + man/man2/pread64.2 | 1 + man/man2/preadv.2 | 1 + man/man2/preadv2.2 | 1 + man/man2/prlimit.2 | 1 + man/man2/prlimit64.2 | 1 + man/man2/process_madvise.2 | 200 + man/man2/process_vm_readv.2 | 314 ++ man/man2/process_vm_writev.2 | 1 + man/man2/prof.2 | 1 + man/man2/pselect.2 | 1 + man/man2/pselect6.2 | 1 + man/man2/ptrace.2 | 2986 +++++++++++++ man/man2/putmsg.2 | 1 + man/man2/putpmsg.2 | 1 + man/man2/pwrite.2 | 1 + man/man2/pwrite64.2 | 1 + man/man2/pwritev.2 | 1 + man/man2/pwritev2.2 | 1 + man/man2/query_module.2 | 194 + man/man2/quotactl.2 | 806 ++++ man/man2/read.2 | 245 ++ man/man2/readahead.2 | 99 + man/man2/readdir.2 | 116 + man/man2/readlink.2 | 332 ++ man/man2/readlinkat.2 | 1 + man/man2/readv.2 | 427 ++ man/man2/reboot.2 | 241 ++ man/man2/recv.2 | 563 +++ man/man2/recvfrom.2 | 1 + man/man2/recvmmsg.2 | 276 ++ man/man2/recvmsg.2 | 1 + man/man2/remap_file_pages.2 | 170 + man/man2/removexattr.2 | 100 + man/man2/rename.2 | 549 +++ man/man2/renameat.2 | 1 + man/man2/renameat2.2 | 1 + man/man2/request_key.2 | 562 +++ man/man2/restart_syscall.2 | 123 + man/man2/rmdir.2 | 128 + man/man2/rt_sigaction.2 | 1 + man/man2/rt_sigpending.2 | 1 + man/man2/rt_sigprocmask.2 | 1 + man/man2/rt_sigqueueinfo.2 | 195 + man/man2/rt_sigreturn.2 | 1 + man/man2/rt_sigsuspend.2 | 1 + man/man2/rt_sigtimedwait.2 | 1 + man/man2/rt_tgsigqueueinfo.2 | 1 + man/man2/s390_guarded_storage.2 | 162 + man/man2/s390_pci_mmio_read.2 | 1 + man/man2/s390_pci_mmio_write.2 | 94 + man/man2/s390_runtime_instr.2 | 104 + man/man2/s390_sthyi.2 | 133 + man/man2/sbrk.2 | 1 + man/man2/sched_get_priority_max.2 | 112 + man/man2/sched_get_priority_min.2 | 1 + man/man2/sched_getaffinity.2 | 1 + man/man2/sched_getattr.2 | 1 + man/man2/sched_getparam.2 | 1 + man/man2/sched_getscheduler.2 | 1 + man/man2/sched_rr_get_interval.2 | 110 + man/man2/sched_setaffinity.2 | 427 ++ man/man2/sched_setattr.2 | 447 ++ man/man2/sched_setparam.2 | 121 + man/man2/sched_setscheduler.2 | 232 + man/man2/sched_yield.2 | 76 + man/man2/seccomp.2 | 1245 ++++++ man/man2/seccomp_unotify.2 | 2011 +++++++++ man/man2/security.2 | 1 + man/man2/select.2 | 765 ++++ man/man2/select_tut.2 | 639 +++ man/man2/semctl.2 | 623 +++ man/man2/semget.2 | 434 ++ man/man2/semop.2 | 523 +++ man/man2/semtimedop.2 | 1 + man/man2/send.2 | 506 +++ man/man2/sendfile.2 | 245 ++ man/man2/sendfile64.2 | 1 + man/man2/sendmmsg.2 | 232 + man/man2/sendmsg.2 | 1 + man/man2/sendto.2 | 1 + man/man2/set_mempolicy.2 | 343 ++ man/man2/set_robust_list.2 | 1 + man/man2/set_thread_area.2 | 229 + man/man2/set_tid_address.2 | 97 + man/man2/setdomainname.2 | 1 + man/man2/setegid.2 | 1 + man/man2/seteuid.2 | 134 + man/man2/setfsgid.2 | 109 + man/man2/setfsgid32.2 | 1 + man/man2/setfsuid.2 | 127 + man/man2/setfsuid32.2 | 1 + man/man2/setgid.2 | 92 + man/man2/setgid32.2 | 1 + man/man2/setgroups.2 | 1 + man/man2/setgroups32.2 | 1 + man/man2/sethostname.2 | 1 + man/man2/setitimer.2 | 1 + man/man2/setns.2 | 419 ++ man/man2/setpgid.2 | 329 ++ man/man2/setpgrp.2 | 1 + man/man2/setpriority.2 | 1 + man/man2/setregid.2 | 1 + man/man2/setregid32.2 | 1 + man/man2/setresgid.2 | 1 + man/man2/setresgid32.2 | 1 + man/man2/setresuid.2 | 147 + man/man2/setresuid32.2 | 1 + man/man2/setreuid.2 | 193 + man/man2/setreuid32.2 | 1 + man/man2/setrlimit.2 | 1 + man/man2/setsid.2 | 100 + man/man2/setsockopt.2 | 1 + man/man2/settimeofday.2 | 1 + man/man2/setuid.2 | 156 + man/man2/setuid32.2 | 1 + man/man2/setup.2 | 55 + man/man2/setxattr.2 | 159 + man/man2/sgetmask.2 | 70 + man/man2/shmat.2 | 1 + man/man2/shmctl.2 | 494 +++ man/man2/shmdt.2 | 1 + man/man2/shmget.2 | 412 ++ man/man2/shmop.2 | 508 +++ man/man2/shutdown.2 | 98 + man/man2/sigaction.2 | 1210 ++++++ man/man2/sigaltstack.2 | 362 ++ man/man2/signal.2 | 280 ++ man/man2/signalfd.2 | 526 +++ man/man2/signalfd4.2 | 1 + man/man2/sigpending.2 | 110 + man/man2/sigprocmask.2 | 224 + man/man2/sigreturn.2 | 151 + man/man2/sigsuspend.2 | 131 + man/man2/sigtimedwait.2 | 1 + man/man2/sigwaitinfo.2 | 231 + man/man2/socket.2 | 493 +++ man/man2/socketcall.2 | 185 + man/man2/socketpair.2 | 116 + man/man2/splice.2 | 266 ++ man/man2/spu_create.2 | 276 ++ man/man2/spu_run.2 | 260 ++ man/man2/ssetmask.2 | 1 + man/man2/stat.2 | 539 +++ man/man2/stat64.2 | 1 + man/man2/statfs.2 | 389 ++ man/man2/statfs64.2 | 1 + man/man2/statx.2 | 614 +++ man/man2/stime.2 | 73 + man/man2/stty.2 | 1 + man/man2/subpage_prot.2 | 118 + man/man2/swapoff.2 | 1 + man/man2/swapon.2 | 202 + man/man2/symlink.2 | 265 ++ man/man2/symlinkat.2 | 1 + man/man2/sync.2 | 148 + man/man2/sync_file_range.2 | 213 + man/man2/sync_file_range2.2 | 1 + man/man2/syncfs.2 | 1 + man/man2/syscall.2 | 368 ++ man/man2/syscalls.2 | 1172 +++++ man/man2/sysctl.2 | 160 + man/man2/sysfs.2 | 97 + man/man2/sysinfo.2 | 106 + man/man2/syslog.2 | 378 ++ man/man2/tee.2 | 200 + man/man2/tgkill.2 | 1 + man/man2/time.2 | 114 + man/man2/timer_create.2 | 487 +++ man/man2/timer_delete.2 | 58 + man/man2/timer_getoverrun.2 | 134 + man/man2/timer_gettime.2 | 1 + man/man2/timer_settime.2 | 187 + man/man2/timerfd_create.2 | 705 +++ man/man2/timerfd_gettime.2 | 1 + man/man2/timerfd_settime.2 | 1 + man/man2/times.2 | 222 + man/man2/tkill.2 | 130 + man/man2/truncate.2 | 251 ++ man/man2/truncate64.2 | 1 + man/man2/tuxcall.2 | 1 + man/man2/ugetrlimit.2 | 1 + man/man2/umask.2 | 149 + man/man2/umount.2 | 214 + man/man2/umount2.2 | 1 + man/man2/uname.2 | 134 + man/man2/unimplemented.2 | 48 + man/man2/unlink.2 | 298 ++ man/man2/unlinkat.2 | 1 + man/man2/unshare.2 | 572 +++ man/man2/uselib.2 | 106 + man/man2/userfaultfd.2 | 951 +++++ man/man2/ustat.2 | 104 + man/man2/utime.2 | 179 + man/man2/utimensat.2 | 633 +++ man/man2/utimes.2 | 1 + man/man2/vfork.2 | 316 ++ man/man2/vhangup.2 | 58 + man/man2/vm86.2 | 58 + man/man2/vm86old.2 | 1 + man/man2/vmsplice.2 | 162 + man/man2/vserver.2 | 1 + man/man2/wait.2 | 721 ++++ man/man2/wait3.2 | 1 + man/man2/wait4.2 | 169 + man/man2/waitid.2 | 1 + man/man2/waitpid.2 | 1 + man/man2/write.2 | 329 ++ man/man2/writev.2 | 1 + man/man2type/open_how.2type | 51 + man/man3/CIRCLEQ_EMPTY.3 | 1 + man/man3/CIRCLEQ_ENTRY.3 | 1 + man/man3/CIRCLEQ_FIRST.3 | 1 + man/man3/CIRCLEQ_FOREACH.3 | 1 + man/man3/CIRCLEQ_FOREACH_REVERSE.3 | 1 + man/man3/CIRCLEQ_HEAD.3 | 1 + man/man3/CIRCLEQ_HEAD_INITIALIZER.3 | 1 + man/man3/CIRCLEQ_INIT.3 | 1 + man/man3/CIRCLEQ_INSERT_AFTER.3 | 1 + man/man3/CIRCLEQ_INSERT_BEFORE.3 | 1 + man/man3/CIRCLEQ_INSERT_HEAD.3 | 1 + man/man3/CIRCLEQ_INSERT_TAIL.3 | 1 + man/man3/CIRCLEQ_LAST.3 | 1 + man/man3/CIRCLEQ_LOOP_NEXT.3 | 1 + man/man3/CIRCLEQ_LOOP_PREV.3 | 1 + man/man3/CIRCLEQ_NEXT.3 | 1 + man/man3/CIRCLEQ_PREV.3 | 1 + man/man3/CIRCLEQ_REMOVE.3 | 1 + man/man3/CMSG_ALIGN.3 | 1 + man/man3/CMSG_DATA.3 | 1 + man/man3/CMSG_FIRSTHDR.3 | 1 + man/man3/CMSG_LEN.3 | 1 + man/man3/CMSG_NXTHDR.3 | 1 + man/man3/CMSG_SPACE.3 | 1 + man/man3/CPU_ALLOC.3 | 1 + man/man3/CPU_ALLOC_SIZE.3 | 1 + man/man3/CPU_AND.3 | 1 + man/man3/CPU_AND_S.3 | 1 + man/man3/CPU_CLR.3 | 1 + man/man3/CPU_CLR_S.3 | 1 + man/man3/CPU_COUNT.3 | 1 + man/man3/CPU_COUNT_S.3 | 1 + man/man3/CPU_EQUAL.3 | 1 + man/man3/CPU_EQUAL_S.3 | 1 + man/man3/CPU_FREE.3 | 1 + man/man3/CPU_ISSET.3 | 1 + man/man3/CPU_ISSET_S.3 | 1 + man/man3/CPU_OR.3 | 1 + man/man3/CPU_OR_S.3 | 1 + man/man3/CPU_SET.3 | 348 ++ man/man3/CPU_SET_S.3 | 1 + man/man3/CPU_XOR.3 | 1 + man/man3/CPU_XOR_S.3 | 1 + man/man3/CPU_ZERO.3 | 1 + man/man3/CPU_ZERO_S.3 | 1 + man/man3/DES_FAILED.3 | 1 + man/man3/FD_CLR.3 | 1 + man/man3/FD_ISSET.3 | 1 + man/man3/FD_SET.3 | 1 + man/man3/FD_ZERO.3 | 1 + man/man3/HUGE_VAL.3 | 1 + man/man3/HUGE_VALF.3 | 1 + man/man3/HUGE_VALL.3 | 1 + man/man3/INFINITY.3 | 85 + man/man3/LIST_EMPTY.3 | 1 + man/man3/LIST_ENTRY.3 | 1 + man/man3/LIST_FIRST.3 | 1 + man/man3/LIST_FOREACH.3 | 1 + man/man3/LIST_HEAD.3 | 1 + man/man3/LIST_HEAD_INITIALIZER.3 | 1 + man/man3/LIST_INIT.3 | 1 + man/man3/LIST_INSERT_AFTER.3 | 1 + man/man3/LIST_INSERT_BEFORE.3 | 1 + man/man3/LIST_INSERT_HEAD.3 | 1 + man/man3/LIST_NEXT.3 | 1 + man/man3/LIST_REMOVE.3 | 1 + man/man3/MAX.3 | 75 + man/man3/MB_CUR_MAX.3 | 43 + man/man3/MB_LEN_MAX.3 | 51 + man/man3/MIN.3 | 1 + man/man3/NAN.3 | 1 + man/man3/SIMPLEQ_EMPTY.3 | 1 + man/man3/SIMPLEQ_ENTRY.3 | 1 + man/man3/SIMPLEQ_FIRST.3 | 1 + man/man3/SIMPLEQ_FOREACH.3 | 1 + man/man3/SIMPLEQ_HEAD.3 | 1 + man/man3/SIMPLEQ_HEAD_INITIALIZER.3 | 1 + man/man3/SIMPLEQ_INIT.3 | 1 + man/man3/SIMPLEQ_INSERT_AFTER.3 | 1 + man/man3/SIMPLEQ_INSERT_HEAD.3 | 1 + man/man3/SIMPLEQ_INSERT_TAIL.3 | 1 + man/man3/SIMPLEQ_NEXT.3 | 1 + man/man3/SIMPLEQ_REMOVE.3 | 1 + man/man3/SIMPLEQ_REMOVE_HEAD.3 | 1 + man/man3/SLIST_EMPTY.3 | 1 + man/man3/SLIST_ENTRY.3 | 1 + man/man3/SLIST_FIRST.3 | 1 + man/man3/SLIST_FOREACH.3 | 1 + man/man3/SLIST_HEAD.3 | 1 + man/man3/SLIST_HEAD_INITIALIZER.3 | 1 + man/man3/SLIST_INIT.3 | 1 + man/man3/SLIST_INSERT_AFTER.3 | 1 + man/man3/SLIST_INSERT_HEAD.3 | 1 + man/man3/SLIST_NEXT.3 | 1 + man/man3/SLIST_REMOVE.3 | 1 + man/man3/SLIST_REMOVE_HEAD.3 | 1 + man/man3/STAILQ_CONCAT.3 | 1 + man/man3/STAILQ_EMPTY.3 | 1 + man/man3/STAILQ_ENTRY.3 | 1 + man/man3/STAILQ_FIRST.3 | 1 + man/man3/STAILQ_FOREACH.3 | 1 + man/man3/STAILQ_HEAD.3 | 1 + man/man3/STAILQ_HEAD_INITIALIZER.3 | 1 + man/man3/STAILQ_INIT.3 | 1 + man/man3/STAILQ_INSERT_AFTER.3 | 1 + man/man3/STAILQ_INSERT_HEAD.3 | 1 + man/man3/STAILQ_INSERT_TAIL.3 | 1 + man/man3/STAILQ_NEXT.3 | 1 + man/man3/STAILQ_REMOVE.3 | 1 + man/man3/STAILQ_REMOVE_HEAD.3 | 1 + man/man3/S_ISBLK.3 | 1 + man/man3/S_ISCHR.3 | 1 + man/man3/S_ISDIR.3 | 1 + man/man3/S_ISFIFO.3 | 1 + man/man3/S_ISLNK.3 | 1 + man/man3/S_ISREG.3 | 1 + man/man3/S_ISSOCK.3 | 1 + man/man3/TAILQ_CONCAT.3 | 1 + man/man3/TAILQ_EMPTY.3 | 1 + man/man3/TAILQ_ENTRY.3 | 1 + man/man3/TAILQ_FIRST.3 | 1 + man/man3/TAILQ_FOREACH.3 | 1 + man/man3/TAILQ_FOREACH_REVERSE.3 | 1 + man/man3/TAILQ_HEAD.3 | 1 + man/man3/TAILQ_HEAD_INITIALIZER.3 | 1 + man/man3/TAILQ_INIT.3 | 1 + man/man3/TAILQ_INSERT_AFTER.3 | 1 + man/man3/TAILQ_INSERT_BEFORE.3 | 1 + man/man3/TAILQ_INSERT_HEAD.3 | 1 + man/man3/TAILQ_INSERT_TAIL.3 | 1 + man/man3/TAILQ_LAST.3 | 1 + man/man3/TAILQ_NEXT.3 | 1 + man/man3/TAILQ_PREV.3 | 1 + man/man3/TAILQ_REMOVE.3 | 1 + man/man3/TAILQ_SWAP.3 | 1 + man/man3/TIMESPEC_TO_TIMEVAL.3 | 1 + man/man3/TIMEVAL_TO_TIMESPEC.3 | 32 + man/man3/_Generic.3 | 64 + man/man3/_Static_assert.3 | 1 + man/man3/__after_morecore_hook.3 | 1 + man/man3/__fbufsize.3 | 1 + man/man3/__flbf.3 | 1 + man/man3/__fpending.3 | 1 + man/man3/__fpurge.3 | 1 + man/man3/__freadable.3 | 1 + man/man3/__freading.3 | 1 + man/man3/__free_hook.3 | 1 + man/man3/__fsetlocking.3 | 1 + man/man3/__fwritable.3 | 1 + man/man3/__fwriting.3 | 1 + man/man3/__malloc_hook.3 | 1 + man/man3/__malloc_initialize_hook.3 | 1 + man/man3/__memalign_hook.3 | 1 + man/man3/__ppc_get_timebase.3 | 99 + man/man3/__ppc_get_timebase_freq.3 | 1 + man/man3/__ppc_mdoio.3 | 1 + man/man3/__ppc_mdoom.3 | 1 + man/man3/__ppc_set_ppr_low.3 | 1 + man/man3/__ppc_set_ppr_med.3 | 113 + man/man3/__ppc_set_ppr_med_high.3 | 1 + man/man3/__ppc_set_ppr_med_low.3 | 1 + man/man3/__ppc_set_ppr_very_low.3 | 1 + man/man3/__ppc_yield.3 | 67 + man/man3/__realloc_hook.3 | 1 + man/man3/__setfpucw.3 | 72 + man/man3/_flushlbf.3 | 1 + man/man3/a64l.3 | 111 + man/man3/abort.3 | 99 + man/man3/abs.3 | 124 + man/man3/acos.3 | 121 + man/man3/acosf.3 | 1 + man/man3/acosh.3 | 124 + man/man3/acoshf.3 | 1 + man/man3/acoshl.3 | 1 + man/man3/acosl.3 | 1 + man/man3/addmntent.3 | 1 + man/man3/addseverity.3 | 87 + man/man3/adjtime.3 | 152 + man/man3/aio_cancel.3 | 125 + man/man3/aio_error.3 | 95 + man/man3/aio_fsync.3 | 112 + man/man3/aio_init.3 | 78 + man/man3/aio_read.3 | 159 + man/man3/aio_return.3 | 89 + man/man3/aio_suspend.3 | 143 + man/man3/aio_write.3 | 161 + man/man3/aligned_alloc.3 | 1 + man/man3/alloca.3 | 138 + man/man3/alphasort.3 | 1 + man/man3/arc4random.3 | 109 + man/man3/arc4random_buf.3 | 1 + man/man3/arc4random_uniform.3 | 1 + man/man3/argz.3 | 1 + man/man3/argz_add.3 | 237 ++ man/man3/argz_add_sep.3 | 1 + man/man3/argz_append.3 | 1 + man/man3/argz_count.3 | 1 + man/man3/argz_create.3 | 1 + man/man3/argz_create_sep.3 | 1 + man/man3/argz_delete.3 | 1 + man/man3/argz_extract.3 | 1 + man/man3/argz_insert.3 | 1 + man/man3/argz_next.3 | 1 + man/man3/argz_replace.3 | 1 + man/man3/argz_stringify.3 | 1 + man/man3/asctime.3 | 1 + man/man3/asctime_r.3 | 1 + man/man3/asin.3 | 117 + man/man3/asinf.3 | 1 + man/man3/asinh.3 | 109 + man/man3/asinhf.3 | 1 + man/man3/asinhl.3 | 1 + man/man3/asinl.3 | 1 + man/man3/asprintf.3 | 70 + man/man3/assert.3 | 96 + man/man3/assert_perror.3 | 73 + man/man3/atan.3 | 103 + man/man3/atan2.3 | 174 + man/man3/atan2f.3 | 1 + man/man3/atan2l.3 | 1 + man/man3/atanf.3 | 1 + man/man3/atanh.3 | 154 + man/man3/atanhf.3 | 1 + man/man3/atanhl.3 | 1 + man/man3/atanl.3 | 1 + man/man3/atexit.3 | 169 + man/man3/atof.3 | 67 + man/man3/atoi.3 | 125 + man/man3/atol.3 | 1 + man/man3/atoll.3 | 1 + man/man3/atoq.3 | 1 + man/man3/auth_destroy.3 | 1 + man/man3/authnone_create.3 | 1 + man/man3/authunix_create.3 | 1 + man/man3/authunix_create_default.3 | 1 + man/man3/backtrace.3 | 283 ++ man/man3/backtrace_symbols.3 | 1 + man/man3/backtrace_symbols_fd.3 | 1 + man/man3/basename.3 | 187 + man/man3/bcmp.3 | 30 + man/man3/bcopy.3 | 76 + man/man3/be16toh.3 | 1 + man/man3/be32toh.3 | 1 + man/man3/be64toh.3 | 1 + man/man3/bindresvport.3 | 116 + man/man3/bsd_signal.3 | 112 + man/man3/bsearch.3 | 139 + man/man3/bstring.3 | 76 + man/man3/bswap.3 | 68 + man/man3/bswap_16.3 | 1 + man/man3/bswap_32.3 | 1 + man/man3/bswap_64.3 | 1 + man/man3/btowc.3 | 86 + man/man3/btree.3 | 229 + man/man3/byteorder.3 | 83 + man/man3/bzero.3 | 158 + man/man3/cabs.3 | 54 + man/man3/cabsf.3 | 1 + man/man3/cabsl.3 | 1 + man/man3/cacos.3 | 93 + man/man3/cacosf.3 | 1 + man/man3/cacosh.3 | 95 + man/man3/cacoshf.3 | 1 + man/man3/cacoshl.3 | 1 + man/man3/cacosl.3 | 1 + man/man3/calloc.3 | 1 + man/man3/callrpc.3 | 1 + man/man3/canonicalize_file_name.3 | 80 + man/man3/carg.3 | 88 + man/man3/cargf.3 | 1 + man/man3/cargl.3 | 1 + man/man3/casin.3 | 57 + man/man3/casinf.3 | 1 + man/man3/casinh.3 | 61 + man/man3/casinhf.3 | 1 + man/man3/casinhl.3 | 1 + man/man3/casinl.3 | 1 + man/man3/catan.3 | 94 + man/man3/catanf.3 | 1 + man/man3/catanh.3 | 94 + man/man3/catanhf.3 | 1 + man/man3/catanhl.3 | 1 + man/man3/catanl.3 | 1 + man/man3/catclose.3 | 1 + man/man3/catgets.3 | 88 + man/man3/catopen.3 | 199 + man/man3/cbc_crypt.3 | 1 + man/man3/cbrt.3 | 90 + man/man3/cbrtf.3 | 1 + man/man3/cbrtl.3 | 1 + man/man3/ccos.3 | 57 + man/man3/ccosf.3 | 1 + man/man3/ccosh.3 | 40 + man/man3/ccoshf.3 | 1 + man/man3/ccoshl.3 | 1 + man/man3/ccosl.3 | 1 + man/man3/ceil.3 | 115 + man/man3/ceilf.3 | 1 + man/man3/ceill.3 | 1 + man/man3/cexp.3 | 58 + man/man3/cexp2.3 | 31 + man/man3/cexp2f.3 | 1 + man/man3/cexp2l.3 | 1 + man/man3/cexpf.3 | 1 + man/man3/cexpl.3 | 1 + man/man3/cfgetispeed.3 | 1 + man/man3/cfgetospeed.3 | 1 + man/man3/cfmakeraw.3 | 1 + man/man3/cfree.3 | 132 + man/man3/cfsetispeed.3 | 1 + man/man3/cfsetospeed.3 | 1 + man/man3/cfsetspeed.3 | 1 + man/man3/cimag.3 | 58 + man/man3/cimagf.3 | 1 + man/man3/cimagl.3 | 1 + man/man3/circleq.3 | 318 ++ man/man3/clearenv.3 | 137 + man/man3/clearerr.3 | 1 + man/man3/clearerr_unlocked.3 | 1 + man/man3/clnt_broadcast.3 | 1 + man/man3/clnt_call.3 | 1 + man/man3/clnt_control.3 | 1 + man/man3/clnt_create.3 | 1 + man/man3/clnt_destroy.3 | 1 + man/man3/clnt_freeres.3 | 1 + man/man3/clnt_geterr.3 | 1 + man/man3/clnt_pcreateerror.3 | 1 + man/man3/clnt_perrno.3 | 1 + man/man3/clnt_perror.3 | 1 + man/man3/clnt_spcreateerror.3 | 1 + man/man3/clnt_sperrno.3 | 1 + man/man3/clnt_sperror.3 | 1 + man/man3/clntraw_create.3 | 1 + man/man3/clnttcp_create.3 | 1 + man/man3/clntudp_bufcreate.3 | 1 + man/man3/clntudp_create.3 | 1 + man/man3/clock.3 | 101 + man/man3/clock_getcpuclockid.3 | 155 + man/man3/clog.3 | 71 + man/man3/clog10.3 | 75 + man/man3/clog10f.3 | 1 + man/man3/clog10l.3 | 1 + man/man3/clog2.3 | 45 + man/man3/clog2f.3 | 1 + man/man3/clog2l.3 | 1 + man/man3/clogf.3 | 1 + man/man3/clogl.3 | 1 + man/man3/closedir.3 | 75 + man/man3/closelog.3 | 1 + man/man3/cmsg.3 | 261 ++ man/man3/confstr.3 | 156 + man/man3/conj.3 | 56 + man/man3/conjf.3 | 1 + man/man3/conjl.3 | 1 + man/man3/copysign.3 | 92 + man/man3/copysignf.3 | 1 + man/man3/copysignl.3 | 1 + man/man3/cos.3 | 118 + man/man3/cosf.3 | 1 + man/man3/cosh.3 | 130 + man/man3/coshf.3 | 1 + man/man3/coshl.3 | 1 + man/man3/cosl.3 | 1 + man/man3/cpow.3 | 53 + man/man3/cpowf.3 | 1 + man/man3/cpowl.3 | 1 + man/man3/cproj.3 | 59 + man/man3/cprojf.3 | 1 + man/man3/cprojl.3 | 1 + man/man3/creal.3 | 56 + man/man3/crealf.3 | 1 + man/man3/creall.3 | 1 + man/man3/crypt.3 | 319 ++ man/man3/crypt_r.3 | 1 + man/man3/csin.3 | 57 + man/man3/csinf.3 | 1 + man/man3/csinh.3 | 57 + man/man3/csinhf.3 | 1 + man/man3/csinhl.3 | 1 + man/man3/csinl.3 | 1 + man/man3/csqrt.3 | 51 + man/man3/csqrtf.3 | 1 + man/man3/csqrtl.3 | 1 + man/man3/ctan.3 | 57 + man/man3/ctanf.3 | 1 + man/man3/ctanh.3 | 58 + man/man3/ctanhf.3 | 1 + man/man3/ctanhl.3 | 1 + man/man3/ctanl.3 | 1 + man/man3/ctermid.3 | 73 + man/man3/ctime.3 | 429 ++ man/man3/ctime_r.3 | 1 + man/man3/cuserid.3 | 1 + man/man3/daemon.3 | 129 + man/man3/daylight.3 | 1 + man/man3/db.3 | 1 + man/man3/dbopen.3 | 536 +++ man/man3/des_crypt.3 | 164 + man/man3/des_setparity.3 | 1 + man/man3/difftime.3 | 60 + man/man3/dirfd.3 | 93 + man/man3/dirname.3 | 1 + man/man3/div.3 | 105 + man/man3/dl_iterate_phdr.3 | 345 ++ man/man3/dladdr.3 | 275 ++ man/man3/dladdr1.3 | 1 + man/man3/dlclose.3 | 1 + man/man3/dlerror.3 | 78 + man/man3/dlinfo.3 | 317 ++ man/man3/dlmopen.3 | 1 + man/man3/dlopen.3 | 624 +++ man/man3/dlsym.3 | 171 + man/man3/dlvsym.3 | 1 + man/man3/dn_comp.3 | 1 + man/man3/dn_expand.3 | 1 + man/man3/dprintf.3 | 1 + man/man3/drand48.3 | 262 ++ man/man3/drand48_r.3 | 104 + man/man3/drem.3 | 1 + man/man3/dremf.3 | 1 + man/man3/dreml.3 | 1 + man/man3/duplocale.3 | 168 + man/man3/dysize.3 | 69 + man/man3/eaccess.3 | 1 + man/man3/ecb_crypt.3 | 1 + man/man3/ecvt.3 | 133 + man/man3/ecvt_r.3 | 100 + man/man3/edata.3 | 1 + man/man3/encrypt.3 | 211 + man/man3/encrypt_r.3 | 1 + man/man3/end.3 | 96 + man/man3/endaliasent.3 | 1 + man/man3/endfsent.3 | 1 + man/man3/endgrent.3 | 1 + man/man3/endhostent.3 | 1 + man/man3/endian.3 | 164 + man/man3/endmntent.3 | 1 + man/man3/endnetent.3 | 1 + man/man3/endnetgrent.3 | 1 + man/man3/endprotoent.3 | 1 + man/man3/endpwent.3 | 1 + man/man3/endrpcent.3 | 1 + man/man3/endservent.3 | 1 + man/man3/endspent.3 | 1 + man/man3/endttyent.3 | 1 + man/man3/endusershell.3 | 1 + man/man3/endutent.3 | 1 + man/man3/endutxent.3 | 1 + man/man3/envz.3 | 1 + man/man3/envz_add.3 | 168 + man/man3/envz_entry.3 | 1 + man/man3/envz_get.3 | 1 + man/man3/envz_merge.3 | 1 + man/man3/envz_remove.3 | 1 + man/man3/envz_strip.3 | 1 + man/man3/erand48.3 | 1 + man/man3/erand48_r.3 | 1 + man/man3/erf.3 | 131 + man/man3/erfc.3 | 134 + man/man3/erfcf.3 | 1 + man/man3/erfcl.3 | 1 + man/man3/erff.3 | 1 + man/man3/erfl.3 | 1 + man/man3/err.3 | 154 + man/man3/errno.3 | 655 +++ man/man3/error.3 | 171 + man/man3/error_at_line.3 | 1 + man/man3/error_message_count.3 | 1 + man/man3/error_one_per_line.3 | 1 + man/man3/error_print_progname.3 | 1 + man/man3/errx.3 | 1 + man/man3/etext.3 | 1 + man/man3/ether_aton.3 | 143 + man/man3/ether_aton_r.3 | 1 + man/man3/ether_hostton.3 | 1 + man/man3/ether_line.3 | 1 + man/man3/ether_ntoa.3 | 1 + man/man3/ether_ntoa_r.3 | 1 + man/man3/ether_ntohost.3 | 1 + man/man3/euidaccess.3 | 104 + man/man3/eventfd_read.3 | 1 + man/man3/eventfd_write.3 | 1 + man/man3/exec.3 | 311 ++ man/man3/execl.3 | 1 + man/man3/execle.3 | 1 + man/man3/execlp.3 | 1 + man/man3/execv.3 | 1 + man/man3/execvp.3 | 1 + man/man3/execvpe.3 | 1 + man/man3/exit.3 | 202 + man/man3/exp.3 | 133 + man/man3/exp10.3 | 82 + man/man3/exp10f.3 | 1 + man/man3/exp10l.3 | 1 + man/man3/exp2.3 | 92 + man/man3/exp2f.3 | 1 + man/man3/exp2l.3 | 1 + man/man3/expf.3 | 1 + man/man3/expl.3 | 1 + man/man3/explicit_bzero.3 | 1 + man/man3/expm1.3 | 165 + man/man3/expm1f.3 | 1 + man/man3/expm1l.3 | 1 + man/man3/fabs.3 | 92 + man/man3/fabsf.3 | 1 + man/man3/fabsl.3 | 1 + man/man3/fclose.3 | 102 + man/man3/fcloseall.3 | 64 + man/man3/fcvt.3 | 1 + man/man3/fcvt_r.3 | 1 + man/man3/fdim.3 | 96 + man/man3/fdimf.3 | 1 + man/man3/fdiml.3 | 1 + man/man3/fdopen.3 | 1 + man/man3/fdopendir.3 | 1 + man/man3/feclearexcept.3 | 1 + man/man3/fedisableexcept.3 | 1 + man/man3/feenableexcept.3 | 1 + man/man3/fegetenv.3 | 1 + man/man3/fegetexcept.3 | 1 + man/man3/fegetexceptflag.3 | 1 + man/man3/fegetround.3 | 1 + man/man3/feholdexcept.3 | 1 + man/man3/fenv.3 | 334 ++ man/man3/feof.3 | 1 + man/man3/feof_unlocked.3 | 1 + man/man3/feraiseexcept.3 | 1 + man/man3/ferror.3 | 118 + man/man3/ferror_unlocked.3 | 1 + man/man3/fesetenv.3 | 1 + man/man3/fesetexceptflag.3 | 1 + man/man3/fesetround.3 | 1 + man/man3/fetestexcept.3 | 1 + man/man3/feupdateenv.3 | 1 + man/man3/fexecve.3 | 172 + man/man3/fflush.3 | 115 + man/man3/fflush_unlocked.3 | 1 + man/man3/ffs.3 | 97 + man/man3/ffsl.3 | 1 + man/man3/ffsll.3 | 1 + man/man3/fgetc.3 | 152 + man/man3/fgetc_unlocked.3 | 1 + man/man3/fgetgrent.3 | 118 + man/man3/fgetgrent_r.3 | 1 + man/man3/fgetpos.3 | 1 + man/man3/fgetpwent.3 | 127 + man/man3/fgetpwent_r.3 | 1 + man/man3/fgets.3 | 1 + man/man3/fgets_unlocked.3 | 1 + man/man3/fgetspent.3 | 1 + man/man3/fgetspent_r.3 | 1 + man/man3/fgetwc.3 | 106 + man/man3/fgetwc_unlocked.3 | 1 + man/man3/fgetws.3 | 91 + man/man3/fgetws_unlocked.3 | 1 + man/man3/fileno.3 | 89 + man/man3/fileno_unlocked.3 | 1 + man/man3/finite.3 | 143 + man/man3/finitef.3 | 1 + man/man3/finitel.3 | 1 + man/man3/flockfile.3 | 133 + man/man3/floor.3 | 105 + man/man3/floorf.3 | 1 + man/man3/floorl.3 | 1 + man/man3/fma.3 | 167 + man/man3/fmaf.3 | 1 + man/man3/fmal.3 | 1 + man/man3/fmax.3 | 73 + man/man3/fmaxf.3 | 1 + man/man3/fmaxl.3 | 1 + man/man3/fmemopen.3 | 352 ++ man/man3/fmin.3 | 73 + man/man3/fminf.3 | 1 + man/man3/fminl.3 | 1 + man/man3/fmod.3 | 183 + man/man3/fmodf.3 | 1 + man/man3/fmodl.3 | 1 + man/man3/fmtmsg.3 | 337 ++ man/man3/fnmatch.3 | 141 + man/man3/fopen.3 | 405 ++ man/man3/fopencookie.3 | 466 ++ man/man3/forkpty.3 | 1 + man/man3/fpathconf.3 | 273 ++ man/man3/fpclassify.3 | 145 + man/man3/fprintf.3 | 1 + man/man3/fpurge.3 | 83 + man/man3/fputc.3 | 1 + man/man3/fputc_unlocked.3 | 1 + man/man3/fputs.3 | 1 + man/man3/fputs_unlocked.3 | 1 + man/man3/fputwc.3 | 104 + man/man3/fputwc_unlocked.3 | 1 + man/man3/fputws.3 | 78 + man/man3/fputws_unlocked.3 | 1 + man/man3/fread.3 | 164 + man/man3/fread_unlocked.3 | 1 + man/man3/free.3 | 1 + man/man3/freeaddrinfo.3 | 1 + man/man3/freehostent.3 | 1 + man/man3/freeifaddrs.3 | 1 + man/man3/freelocale.3 | 1 + man/man3/freopen.3 | 1 + man/man3/frexp.3 | 141 + man/man3/frexpf.3 | 1 + man/man3/frexpl.3 | 1 + man/man3/fscanf.3 | 1 + man/man3/fseek.3 | 177 + man/man3/fseeko.3 | 102 + man/man3/fsetpos.3 | 1 + man/man3/fstatvfs.3 | 1 + man/man3/ftell.3 | 1 + man/man3/ftello.3 | 1 + man/man3/ftime.3 | 105 + man/man3/ftok.3 | 110 + man/man3/ftrylockfile.3 | 1 + man/man3/fts.3 | 826 ++++ man/man3/fts_children.3 | 1 + man/man3/fts_close.3 | 1 + man/man3/fts_open.3 | 1 + man/man3/fts_read.3 | 1 + man/man3/fts_set.3 | 1 + man/man3/ftw.3 | 502 +++ man/man3/funlockfile.3 | 1 + man/man3/futimens.3 | 1 + man/man3/futimes.3 | 106 + man/man3/fwide.3 | 92 + man/man3/fwprintf.3 | 1 + man/man3/fwrite.3 | 1 + man/man3/fwrite_unlocked.3 | 1 + man/man3/gai_cancel.3 | 1 + man/man3/gai_error.3 | 1 + man/man3/gai_strerror.3 | 1 + man/man3/gai_suspend.3 | 1 + man/man3/gamma.3 | 121 + man/man3/gammaf.3 | 1 + man/man3/gammal.3 | 1 + man/man3/gcvt.3 | 82 + man/man3/get_avphys_pages.3 | 1 + man/man3/get_current_dir_name.3 | 1 + man/man3/get_myaddress.3 | 1 + man/man3/get_nprocs.3 | 93 + man/man3/get_nprocs_conf.3 | 1 + man/man3/get_phys_pages.3 | 90 + man/man3/getaddrinfo.3 | 854 ++++ man/man3/getaddrinfo_a.3 | 645 +++ man/man3/getaliasbyname.3 | 1 + man/man3/getaliasbyname_r.3 | 1 + man/man3/getaliasent.3 | 1 + man/man3/getaliasent_r.3 | 1 + man/man3/getauxval.3 | 272 ++ man/man3/getc.3 | 1 + man/man3/getc_unlocked.3 | 1 + man/man3/getchar.3 | 1 + man/man3/getchar_unlocked.3 | 1 + man/man3/getcontext.3 | 201 + man/man3/getcwd.3 | 311 ++ man/man3/getdate.3 | 322 ++ man/man3/getdate_err.3 | 1 + man/man3/getdate_r.3 | 1 + man/man3/getdelim.3 | 1 + man/man3/getdirentries.3 | 80 + man/man3/getdtablesize.3 | 88 + man/man3/getentropy.3 | 103 + man/man3/getenv.3 | 141 + man/man3/getfsent.3 | 155 + man/man3/getfsfile.3 | 1 + man/man3/getfsspec.3 | 1 + man/man3/getgrent.3 | 206 + man/man3/getgrent_r.3 | 228 + man/man3/getgrgid.3 | 1 + man/man3/getgrgid_r.3 | 1 + man/man3/getgrnam.3 | 260 ++ man/man3/getgrnam_r.3 | 1 + man/man3/getgrouplist.3 | 205 + man/man3/gethostbyaddr.3 | 1 + man/man3/gethostbyaddr_r.3 | 1 + man/man3/gethostbyname.3 | 553 +++ man/man3/gethostbyname2.3 | 1 + man/man3/gethostbyname2_r.3 | 1 + man/man3/gethostbyname_r.3 | 1 + man/man3/gethostent.3 | 1 + man/man3/gethostent_r.3 | 1 + man/man3/gethostid.3 | 149 + man/man3/getifaddrs.3 | 313 ++ man/man3/getipnodebyaddr.3 | 1 + man/man3/getipnodebyname.3 | 253 ++ man/man3/getline.3 | 182 + man/man3/getloadavg.3 | 71 + man/man3/getlogin.3 | 259 ++ man/man3/getlogin_r.3 | 1 + man/man3/getmntent.3 | 265 ++ man/man3/getmntent_r.3 | 1 + man/man3/getnameinfo.3 | 345 ++ man/man3/getnetbyaddr.3 | 1 + man/man3/getnetbyaddr_r.3 | 1 + man/man3/getnetbyname.3 | 1 + man/man3/getnetbyname_r.3 | 1 + man/man3/getnetent.3 | 206 + man/man3/getnetent_r.3 | 150 + man/man3/getnetgrent.3 | 1 + man/man3/getnetgrent_r.3 | 1 + man/man3/getopt.3 | 577 +++ man/man3/getopt_long.3 | 1 + man/man3/getopt_long_only.3 | 1 + man/man3/getpass.3 | 150 + man/man3/getprotobyname.3 | 1 + man/man3/getprotobyname_r.3 | 1 + man/man3/getprotobynumber.3 | 1 + man/man3/getprotobynumber_r.3 | 1 + man/man3/getprotoent.3 | 192 + man/man3/getprotoent_r.3 | 243 ++ man/man3/getpt.3 | 74 + man/man3/getpw.3 | 125 + man/man3/getpwent.3 | 191 + man/man3/getpwent_r.3 | 227 + man/man3/getpwnam.3 | 350 ++ man/man3/getpwnam_r.3 | 1 + man/man3/getpwuid.3 | 1 + man/man3/getpwuid_r.3 | 1 + man/man3/getrpcbyname.3 | 1 + man/man3/getrpcbyname_r.3 | 1 + man/man3/getrpcbynumber.3 | 1 + man/man3/getrpcbynumber_r.3 | 1 + man/man3/getrpcent.3 | 136 + man/man3/getrpcent_r.3 | 136 + man/man3/getrpcport.3 | 59 + man/man3/gets.3 | 107 + man/man3/getservbyname.3 | 1 + man/man3/getservbyname_r.3 | 1 + man/man3/getservbyport.3 | 1 + man/man3/getservbyport_r.3 | 1 + man/man3/getservent.3 | 209 + man/man3/getservent_r.3 | 249 ++ man/man3/getspent.3 | 1 + man/man3/getspent_r.3 | 1 + man/man3/getspnam.3 | 344 ++ man/man3/getspnam_r.3 | 1 + man/man3/getsubopt.3 | 251 ++ man/man3/getttyent.3 | 100 + man/man3/getttynam.3 | 1 + man/man3/getusershell.3 | 98 + man/man3/getutent.3 | 355 ++ man/man3/getutent_r.3 | 1 + man/man3/getutid.3 | 1 + man/man3/getutid_r.3 | 1 + man/man3/getutline.3 | 1 + man/man3/getutline_r.3 | 1 + man/man3/getutmp.3 | 71 + man/man3/getutmpx.3 | 1 + man/man3/getutxent.3 | 1 + man/man3/getutxid.3 | 1 + man/man3/getutxline.3 | 1 + man/man3/getw.3 | 84 + man/man3/getwc.3 | 1 + man/man3/getwc_unlocked.3 | 1 + man/man3/getwchar.3 | 87 + man/man3/getwchar_unlocked.3 | 1 + man/man3/getwd.3 | 1 + man/man3/glob.3 | 353 ++ man/man3/globfree.3 | 1 + man/man3/gmtime.3 | 1 + man/man3/gmtime_r.3 | 1 + man/man3/gnu_dev_major.3 | 1 + man/man3/gnu_dev_makedev.3 | 1 + man/man3/gnu_dev_minor.3 | 1 + man/man3/gnu_get_libc_release.3 | 1 + man/man3/gnu_get_libc_version.3 | 79 + man/man3/grantpt.3 | 107 + man/man3/group_member.3 | 48 + man/man3/gsignal.3 | 118 + man/man3/h_errno.3 | 1 + man/man3/hash.3 | 145 + man/man3/hasmntopt.3 | 1 + man/man3/hcreate.3 | 1 + man/man3/hcreate_r.3 | 1 + man/man3/hdestroy.3 | 1 + man/man3/hdestroy_r.3 | 1 + man/man3/herror.3 | 1 + man/man3/hsearch.3 | 355 ++ man/man3/hsearch_r.3 | 1 + man/man3/hstrerror.3 | 1 + man/man3/htobe16.3 | 1 + man/man3/htobe32.3 | 1 + man/man3/htobe64.3 | 1 + man/man3/htole16.3 | 1 + man/man3/htole32.3 | 1 + man/man3/htole64.3 | 1 + man/man3/htonl.3 | 1 + man/man3/htons.3 | 1 + man/man3/hypot.3 | 155 + man/man3/hypotf.3 | 1 + man/man3/hypotl.3 | 1 + man/man3/iconv.3 | 233 + man/man3/iconv_close.3 | 56 + man/man3/iconv_open.3 | 125 + man/man3/if_freenameindex.3 | 1 + man/man3/if_indextoname.3 | 1 + man/man3/if_nameindex.3 | 154 + man/man3/if_nametoindex.3 | 99 + man/man3/ilogb.3 | 150 + man/man3/ilogbf.3 | 1 + man/man3/ilogbl.3 | 1 + man/man3/imaxabs.3 | 1 + man/man3/imaxdiv.3 | 1 + man/man3/index.3 | 44 + man/man3/inet.3 | 336 ++ man/man3/inet_addr.3 | 1 + man/man3/inet_aton.3 | 1 + man/man3/inet_lnaof.3 | 1 + man/man3/inet_makeaddr.3 | 1 + man/man3/inet_net_ntop.3 | 1 + man/man3/inet_net_pton.3 | 369 ++ man/man3/inet_netof.3 | 1 + man/man3/inet_network.3 | 1 + man/man3/inet_ntoa.3 | 1 + man/man3/inet_ntop.3 | 122 + man/man3/inet_pton.3 | 223 + man/man3/initgroups.3 | 98 + man/man3/initstate.3 | 1 + man/man3/initstate_r.3 | 1 + man/man3/innetgr.3 | 1 + man/man3/insque.3 | 248 ++ man/man3/intro.3 | 135 + man/man3/iruserok.3 | 1 + man/man3/iruserok_af.3 | 1 + man/man3/isalnum.3 | 1 + man/man3/isalnum_l.3 | 1 + man/man3/isalpha.3 | 405 ++ man/man3/isalpha_l.3 | 1 + man/man3/isascii.3 | 1 + man/man3/isascii_l.3 | 1 + man/man3/isatty.3 | 68 + man/man3/isblank.3 | 1 + man/man3/isblank_l.3 | 1 + man/man3/iscntrl.3 | 1 + man/man3/iscntrl_l.3 | 1 + man/man3/isdigit.3 | 1 + man/man3/isdigit_l.3 | 1 + man/man3/isfdtype.3 | 77 + man/man3/isfinite.3 | 1 + man/man3/isgraph.3 | 1 + man/man3/isgraph_l.3 | 1 + man/man3/isgreater.3 | 144 + man/man3/isgreaterequal.3 | 1 + man/man3/isinf.3 | 1 + man/man3/isinff.3 | 1 + man/man3/isinfl.3 | 1 + man/man3/isless.3 | 1 + man/man3/islessequal.3 | 1 + man/man3/islessgreater.3 | 1 + man/man3/islower.3 | 1 + man/man3/islower_l.3 | 1 + man/man3/isnan.3 | 1 + man/man3/isnanf.3 | 1 + man/man3/isnanl.3 | 1 + man/man3/isnormal.3 | 1 + man/man3/isprint.3 | 1 + man/man3/isprint_l.3 | 1 + man/man3/ispunct.3 | 1 + man/man3/ispunct_l.3 | 1 + man/man3/isspace.3 | 1 + man/man3/isspace_l.3 | 1 + man/man3/isunordered.3 | 1 + man/man3/isupper.3 | 1 + man/man3/isupper_l.3 | 1 + man/man3/iswalnum.3 | 95 + man/man3/iswalpha.3 | 96 + man/man3/iswblank.3 | 89 + man/man3/iswcntrl.3 | 80 + man/man3/iswctype.3 | 94 + man/man3/iswdigit.3 | 95 + man/man3/iswgraph.3 | 88 + man/man3/iswlower.3 | 106 + man/man3/iswprint.3 | 74 + man/man3/iswpunct.3 | 90 + man/man3/iswspace.3 | 83 + man/man3/iswupper.3 | 100 + man/man3/iswxdigit.3 | 87 + man/man3/isxdigit.3 | 1 + man/man3/isxdigit_l.3 | 1 + man/man3/j0.3 | 195 + man/man3/j0f.3 | 1 + man/man3/j0l.3 | 1 + man/man3/j1.3 | 1 + man/man3/j1f.3 | 1 + man/man3/j1l.3 | 1 + man/man3/jn.3 | 1 + man/man3/jnf.3 | 1 + man/man3/jnl.3 | 1 + man/man3/jrand48.3 | 1 + man/man3/jrand48_r.3 | 1 + man/man3/key_decryptsession.3 | 1 + man/man3/key_encryptsession.3 | 1 + man/man3/key_gendes.3 | 1 + man/man3/key_secretkey_is_set.3 | 1 + man/man3/key_setsecret.3 | 87 + man/man3/killpg.3 | 113 + man/man3/klogctl.3 | 1 + man/man3/l64a.3 | 1 + man/man3/labs.3 | 1 + man/man3/lckpwdf.3 | 1 + man/man3/lcong48.3 | 1 + man/man3/lcong48_r.3 | 1 + man/man3/ldexp.3 | 131 + man/man3/ldexpf.3 | 1 + man/man3/ldexpl.3 | 1 + man/man3/ldiv.3 | 1 + man/man3/le16toh.3 | 1 + man/man3/le32toh.3 | 1 + man/man3/le64toh.3 | 1 + man/man3/lfind.3 | 1 + man/man3/lgamma.3 | 202 + man/man3/lgamma_r.3 | 1 + man/man3/lgammaf.3 | 1 + man/man3/lgammaf_r.3 | 1 + man/man3/lgammal.3 | 1 + man/man3/lgammal_r.3 | 1 + man/man3/lio_listio.3 | 224 + man/man3/list.3 | 308 ++ man/man3/llabs.3 | 1 + man/man3/lldiv.3 | 1 + man/man3/llrint.3 | 1 + man/man3/llrintf.3 | 1 + man/man3/llrintl.3 | 1 + man/man3/llround.3 | 1 + man/man3/llroundf.3 | 1 + man/man3/llroundl.3 | 1 + man/man3/localeconv.3 | 83 + man/man3/localtime.3 | 1 + man/man3/localtime_r.3 | 1 + man/man3/lockf.3 | 179 + man/man3/log.3 | 140 + man/man3/log10.3 | 94 + man/man3/log10f.3 | 1 + man/man3/log10l.3 | 1 + man/man3/log1p.3 | 150 + man/man3/log1pf.3 | 1 + man/man3/log1pl.3 | 1 + man/man3/log2.3 | 93 + man/man3/log2f.3 | 1 + man/man3/log2l.3 | 1 + man/man3/logb.3 | 142 + man/man3/logbf.3 | 1 + man/man3/logbl.3 | 1 + man/man3/logf.3 | 1 + man/man3/login.3 | 151 + man/man3/login_tty.3 | 1 + man/man3/logl.3 | 1 + man/man3/logout.3 | 1 + man/man3/logwtmp.3 | 1 + man/man3/longjmp.3 | 1 + man/man3/lrand48.3 | 1 + man/man3/lrand48_r.3 | 1 + man/man3/lrint.3 | 110 + man/man3/lrintf.3 | 1 + man/man3/lrintl.3 | 1 + man/man3/lround.3 | 113 + man/man3/lroundf.3 | 1 + man/man3/lroundl.3 | 1 + man/man3/lsearch.3 | 94 + man/man3/lseek64.3 | 206 + man/man3/lutimes.3 | 1 + man/man3/major.3 | 1 + man/man3/makecontext.3 | 236 ++ man/man3/makedev.3 | 92 + man/man3/mallinfo.3 | 338 ++ man/man3/mallinfo2.3 | 1 + man/man3/malloc.3 | 460 ++ man/man3/malloc_get_state.3 | 115 + man/man3/malloc_hook.3 | 154 + man/man3/malloc_info.3 | 257 ++ man/man3/malloc_set_state.3 | 1 + man/man3/malloc_stats.3 | 65 + man/man3/malloc_trim.3 | 81 + man/man3/malloc_usable_size.3 | 60 + man/man3/mallopt.3 | 619 +++ man/man3/matherr.3 | 428 ++ man/man3/mblen.3 | 117 + man/man3/mbrlen.3 | 130 + man/man3/mbrtowc.3 | 201 + man/man3/mbsinit.3 | 73 + man/man3/mbsnrtowcs.3 | 199 + man/man3/mbsrtowcs.3 | 170 + man/man3/mbstowcs.3 | 237 ++ man/man3/mbtowc.3 | 150 + man/man3/mcheck.3 | 213 + man/man3/mcheck_check_all.3 | 1 + man/man3/mcheck_pedantic.3 | 1 + man/man3/memalign.3 | 1 + man/man3/memccpy.3 | 79 + man/man3/memchr.3 | 142 + man/man3/memcmp.3 | 91 + man/man3/memcpy.3 | 106 + man/man3/memfrob.3 | 60 + man/man3/memmem.3 | 89 + man/man3/memmove.3 | 71 + man/man3/mempcpy.3 | 94 + man/man3/memrchr.3 | 1 + man/man3/memset.3 | 60 + man/man3/minor.3 | 1 + man/man3/mkdtemp.3 | 87 + man/man3/mkfifo.3 | 201 + man/man3/mkfifoat.3 | 1 + man/man3/mkostemp.3 | 1 + man/man3/mkostemps.3 | 1 + man/man3/mkstemp.3 | 247 ++ man/man3/mkstemps.3 | 1 + man/man3/mktemp.3 | 118 + man/man3/mktime.3 | 1 + man/man3/mmap64.3 | 1 + man/man3/modf.3 | 94 + man/man3/modff.3 | 1 + man/man3/modfl.3 | 1 + man/man3/mpool.3 | 205 + man/man3/mprobe.3 | 1 + man/man3/mq_close.3 | 70 + man/man3/mq_getattr.3 | 229 + man/man3/mq_notify.3 | 273 ++ man/man3/mq_open.3 | 298 ++ man/man3/mq_receive.3 | 163 + man/man3/mq_send.3 | 170 + man/man3/mq_setattr.3 | 1 + man/man3/mq_timedreceive.3 | 1 + man/man3/mq_timedsend.3 | 1 + man/man3/mq_unlink.3 | 68 + man/man3/mrand48.3 | 1 + man/man3/mrand48_r.3 | 1 + man/man3/mtrace.3 | 180 + man/man3/muntrace.3 | 1 + man/man3/nan.3 | 96 + man/man3/nanf.3 | 1 + man/man3/nanl.3 | 1 + man/man3/nearbyint.3 | 1 + man/man3/nearbyintf.3 | 1 + man/man3/nearbyintl.3 | 1 + man/man3/netlink.3 | 87 + man/man3/newlocale.3 | 356 ++ man/man3/nextafter.3 | 200 + man/man3/nextafterf.3 | 1 + man/man3/nextafterl.3 | 1 + man/man3/nextdown.3 | 1 + man/man3/nextdownf.3 | 1 + man/man3/nextdownl.3 | 1 + man/man3/nexttoward.3 | 1 + man/man3/nexttowardf.3 | 1 + man/man3/nexttowardl.3 | 1 + man/man3/nextup.3 | 94 + man/man3/nextupf.3 | 1 + man/man3/nextupl.3 | 1 + man/man3/nftw.3 | 1 + man/man3/nl_langinfo.3 | 353 ++ man/man3/nl_langinfo_l.3 | 1 + man/man3/nrand48.3 | 1 + man/man3/nrand48_r.3 | 1 + man/man3/ntohl.3 | 1 + man/man3/ntohs.3 | 1 + man/man3/ntp_adjtime.3 | 1 + man/man3/ntp_gettime.3 | 135 + man/man3/ntp_gettimex.3 | 1 + man/man3/offsetof.3 | 110 + man/man3/on_exit.3 | 105 + man/man3/open_memstream.3 | 141 + man/man3/open_wmemstream.3 | 1 + man/man3/opendir.3 | 145 + man/man3/openlog.3 | 1 + man/man3/openpty.3 | 179 + man/man3/optarg.3 | 1 + man/man3/opterr.3 | 1 + man/man3/optind.3 | 1 + man/man3/optopt.3 | 1 + man/man3/passwd2des.3 | 1 + man/man3/pathconf.3 | 1 + man/man3/pclose.3 | 1 + man/man3/perror.3 | 142 + man/man3/pmap_getmaps.3 | 1 + man/man3/pmap_getport.3 | 1 + man/man3/pmap_rmtcall.3 | 1 + man/man3/pmap_set.3 | 1 + man/man3/pmap_unset.3 | 1 + man/man3/popen.3 | 208 + man/man3/posix_fallocate.3 | 181 + man/man3/posix_madvise.3 | 112 + man/man3/posix_memalign.3 | 276 ++ man/man3/posix_openpt.3 | 107 + man/man3/posix_spawn.3 | 823 ++++ man/man3/posix_spawnp.3 | 1 + man/man3/pow.3 | 383 ++ man/man3/pow10.3 | 56 + man/man3/pow10f.3 | 1 + man/man3/pow10l.3 | 1 + man/man3/powerof2.3 | 46 + man/man3/powf.3 | 1 + man/man3/powl.3 | 1 + man/man3/printf.3 | 1239 ++++++ man/man3/profil.3 | 94 + man/man3/program_invocation_name.3 | 66 + man/man3/program_invocation_short_name.3 | 1 + man/man3/psiginfo.3 | 1 + man/man3/psignal.3 | 114 + man/man3/pthread_atfork.3 | 108 + man/man3/pthread_attr_destroy.3 | 1 + man/man3/pthread_attr_getaffinity_np.3 | 1 + man/man3/pthread_attr_getdetachstate.3 | 1 + man/man3/pthread_attr_getguardsize.3 | 1 + man/man3/pthread_attr_getinheritsched.3 | 1 + man/man3/pthread_attr_getschedparam.3 | 1 + man/man3/pthread_attr_getschedpolicy.3 | 1 + man/man3/pthread_attr_getscope.3 | 1 + man/man3/pthread_attr_getsigmask_np.3 | 1 + man/man3/pthread_attr_getstack.3 | 1 + man/man3/pthread_attr_getstackaddr.3 | 1 + man/man3/pthread_attr_getstacksize.3 | 1 + man/man3/pthread_attr_init.3 | 313 ++ man/man3/pthread_attr_setaffinity_np.3 | 120 + man/man3/pthread_attr_setdetachstate.3 | 115 + man/man3/pthread_attr_setguardsize.3 | 163 + man/man3/pthread_attr_setinheritsched.3 | 140 + man/man3/pthread_attr_setschedparam.3 | 125 + man/man3/pthread_attr_setschedpolicy.3 | 112 + man/man3/pthread_attr_setscope.3 | 139 + man/man3/pthread_attr_setsigmask_np.3 | 130 + man/man3/pthread_attr_setstack.3 | 164 + man/man3/pthread_attr_setstackaddr.3 | 115 + man/man3/pthread_attr_setstacksize.3 | 114 + man/man3/pthread_cancel.3 | 237 ++ man/man3/pthread_cleanup_pop.3 | 1 + man/man3/pthread_cleanup_pop_restore_np.3 | 1 + man/man3/pthread_cleanup_push.3 | 319 ++ man/man3/pthread_cleanup_push_defer_np.3 | 100 + man/man3/pthread_cond_broadcast.3 | 1 + man/man3/pthread_cond_destroy.3 | 1 + man/man3/pthread_cond_init.3 | 268 ++ man/man3/pthread_cond_signal.3 | 1 + man/man3/pthread_cond_timedwait.3 | 1 + man/man3/pthread_cond_wait.3 | 1 + man/man3/pthread_condattr_destroy.3 | 1 + man/man3/pthread_condattr_init.3 | 48 + man/man3/pthread_create.3 | 395 ++ man/man3/pthread_detach.3 | 105 + man/man3/pthread_equal.3 | 57 + man/man3/pthread_exit.3 | 106 + man/man3/pthread_getaffinity_np.3 | 1 + man/man3/pthread_getattr_default_np.3 | 192 + man/man3/pthread_getattr_np.3 | 356 ++ man/man3/pthread_getconcurrency.3 | 1 + man/man3/pthread_getcpuclockid.3 | 180 + man/man3/pthread_getname_np.3 | 1 + man/man3/pthread_getschedparam.3 | 1 + man/man3/pthread_getspecific.3 | 1 + man/man3/pthread_join.3 | 134 + man/man3/pthread_key_create.3 | 181 + man/man3/pthread_key_delete.3 | 1 + man/man3/pthread_kill.3 | 108 + man/man3/pthread_kill_other_threads_np.3 | 69 + man/man3/pthread_mutex_consistent.3 | 86 + man/man3/pthread_mutex_consistent_np.3 | 1 + man/man3/pthread_mutex_destroy.3 | 1 + man/man3/pthread_mutex_init.3 | 244 ++ man/man3/pthread_mutex_lock.3 | 1 + man/man3/pthread_mutex_trylock.3 | 1 + man/man3/pthread_mutex_unlock.3 | 1 + man/man3/pthread_mutexattr_destroy.3 | 1 + man/man3/pthread_mutexattr_getkind_np.3 | 1 + man/man3/pthread_mutexattr_getpshared.3 | 82 + man/man3/pthread_mutexattr_getrobust.3 | 1 + man/man3/pthread_mutexattr_getrobust_np.3 | 1 + man/man3/pthread_mutexattr_gettype.3 | 1 + man/man3/pthread_mutexattr_init.3 | 53 + man/man3/pthread_mutexattr_setkind_np.3 | 55 + man/man3/pthread_mutexattr_setpshared.3 | 1 + man/man3/pthread_mutexattr_setrobust.3 | 264 ++ man/man3/pthread_mutexattr_setrobust_np.3 | 1 + man/man3/pthread_mutexattr_settype.3 | 1 + man/man3/pthread_once.3 | 44 + man/man3/pthread_rwlockattr_getkind_np.3 | 1 + man/man3/pthread_rwlockattr_setkind_np.3 | 119 + man/man3/pthread_self.3 | 77 + man/man3/pthread_setaffinity_np.3 | 207 + man/man3/pthread_setattr_default_np.3 | 1 + man/man3/pthread_setcancelstate.3 | 200 + man/man3/pthread_setcanceltype.3 | 1 + man/man3/pthread_setconcurrency.3 | 100 + man/man3/pthread_setname_np.3 | 202 + man/man3/pthread_setschedparam.3 | 448 ++ man/man3/pthread_setschedprio.3 | 101 + man/man3/pthread_setspecific.3 | 1 + man/man3/pthread_sigmask.3 | 162 + man/man3/pthread_sigqueue.3 | 109 + man/man3/pthread_spin_destroy.3 | 1 + man/man3/pthread_spin_init.3 | 148 + man/man3/pthread_spin_lock.3 | 102 + man/man3/pthread_spin_trylock.3 | 1 + man/man3/pthread_spin_unlock.3 | 1 + man/man3/pthread_testcancel.3 | 64 + man/man3/pthread_timedjoin_np.3 | 1 + man/man3/pthread_tryjoin_np.3 | 154 + man/man3/pthread_yield.3 | 78 + man/man3/ptsname.3 | 146 + man/man3/ptsname_r.3 | 1 + man/man3/putc.3 | 1 + man/man3/putc_unlocked.3 | 1 + man/man3/putchar.3 | 1 + man/man3/putchar_unlocked.3 | 1 + man/man3/putenv.3 | 141 + man/man3/putgrent.3 | 66 + man/man3/putpwent.3 | 96 + man/man3/puts.3 | 124 + man/man3/putspent.3 | 1 + man/man3/pututline.3 | 1 + man/man3/pututxline.3 | 1 + man/man3/putw.3 | 1 + man/man3/putwc.3 | 1 + man/man3/putwc_unlocked.3 | 1 + man/man3/putwchar.3 | 92 + man/man3/putwchar_unlocked.3 | 1 + man/man3/pvalloc.3 | 1 + man/man3/qecvt.3 | 110 + man/man3/qecvt_r.3 | 1 + man/man3/qfcvt.3 | 1 + man/man3/qfcvt_r.3 | 1 + man/man3/qgcvt.3 | 1 + man/man3/qsort.3 | 157 + man/man3/qsort_r.3 | 1 + man/man3/queue.3 | 1 + man/man3/raise.3 | 83 + man/man3/rand.3 | 240 ++ man/man3/rand_r.3 | 1 + man/man3/random.3 | 193 + man/man3/random_r.3 | 176 + man/man3/rawmemchr.3 | 1 + man/man3/rcmd.3 | 304 ++ man/man3/rcmd_af.3 | 1 + man/man3/re_comp.3 | 75 + man/man3/re_exec.3 | 1 + man/man3/readdir.3 | 304 ++ man/man3/readdir_r.3 | 145 + man/man3/realloc.3 | 1 + man/man3/reallocarray.3 | 1 + man/man3/realpath.3 | 231 + man/man3/recno.3 | 207 + man/man3/regcomp.3 | 1 + man/man3/regerror.3 | 1 + man/man3/regex.3 | 411 ++ man/man3/regexec.3 | 1 + man/man3/regfree.3 | 1 + man/man3/register_printf_modifier.3 | 1 + man/man3/register_printf_specifier.3 | 1 + man/man3/register_printf_type.3 | 1 + man/man3/registerrpc.3 | 1 + man/man3/remainder.3 | 234 + man/man3/remainderf.3 | 1 + man/man3/remainderl.3 | 1 + man/man3/remove.3 | 93 + man/man3/remque.3 | 1 + man/man3/remquo.3 | 138 + man/man3/remquof.3 | 1 + man/man3/remquol.3 | 1 + man/man3/res_init.3 | 1 + man/man3/res_mkquery.3 | 1 + man/man3/res_nclose.3 | 1 + man/man3/res_ninit.3 | 1 + man/man3/res_nmkquery.3 | 1 + man/man3/res_nquery.3 | 1 + man/man3/res_nquerydomain.3 | 1 + man/man3/res_nsearch.3 | 1 + man/man3/res_nsend.3 | 1 + man/man3/res_query.3 | 1 + man/man3/res_querydomain.3 | 1 + man/man3/res_search.3 | 1 + man/man3/res_send.3 | 1 + man/man3/resolver.3 | 511 +++ man/man3/rewind.3 | 1 + man/man3/rewinddir.3 | 60 + man/man3/rexec.3 | 161 + man/man3/rexec_af.3 | 1 + man/man3/rindex.3 | 1 + man/man3/rint.3 | 145 + man/man3/rintf.3 | 1 + man/man3/rintl.3 | 1 + man/man3/round.3 | 110 + man/man3/roundf.3 | 1 + man/man3/roundl.3 | 1 + man/man3/roundup.3 | 56 + man/man3/rpc.3 | 1201 ++++++ man/man3/rpmatch.3 | 169 + man/man3/rresvport.3 | 1 + man/man3/rresvport_af.3 | 1 + man/man3/rtime.3 | 152 + man/man3/rtnetlink.3 | 122 + man/man3/ruserok.3 | 1 + man/man3/ruserok_af.3 | 1 + man/man3/scalb.3 | 196 + man/man3/scalbf.3 | 1 + man/man3/scalbl.3 | 1 + man/man3/scalbln.3 | 174 + man/man3/scalblnf.3 | 1 + man/man3/scalblnl.3 | 1 + man/man3/scalbn.3 | 1 + man/man3/scalbnf.3 | 1 + man/man3/scalbnl.3 | 1 + man/man3/scandir.3 | 310 ++ man/man3/scandirat.3 | 1 + man/man3/scanf.3 | 159 + man/man3/sched_getcpu.3 | 89 + man/man3/secure_getenv.3 | 1 + man/man3/seed48.3 | 1 + man/man3/seed48_r.3 | 1 + man/man3/seekdir.3 | 89 + man/man3/sem_close.3 | 63 + man/man3/sem_destroy.3 | 75 + man/man3/sem_getvalue.3 | 74 + man/man3/sem_init.3 | 108 + man/man3/sem_open.3 | 175 + man/man3/sem_post.3 | 73 + man/man3/sem_timedwait.3 | 1 + man/man3/sem_trywait.3 | 1 + man/man3/sem_unlink.3 | 66 + man/man3/sem_wait.3 | 251 ++ man/man3/setaliasent.3 | 184 + man/man3/setbuf.3 | 227 + man/man3/setbuffer.3 | 1 + man/man3/setcontext.3 | 1 + man/man3/setenv.3 | 150 + man/man3/setfsent.3 | 1 + man/man3/setgrent.3 | 1 + man/man3/sethostent.3 | 1 + man/man3/sethostid.3 | 1 + man/man3/setjmp.3 | 332 ++ man/man3/setkey.3 | 1 + man/man3/setkey_r.3 | 1 + man/man3/setlinebuf.3 | 1 + man/man3/setlocale.3 | 248 ++ man/man3/setlogmask.3 | 89 + man/man3/setmntent.3 | 1 + man/man3/setnetent.3 | 1 + man/man3/setnetgrent.3 | 170 + man/man3/setprotoent.3 | 1 + man/man3/setpwent.3 | 1 + man/man3/setrpcent.3 | 1 + man/man3/setservent.3 | 1 + man/man3/setspent.3 | 1 + man/man3/setstate.3 | 1 + man/man3/setstate_r.3 | 1 + man/man3/setttyent.3 | 1 + man/man3/setusershell.3 | 1 + man/man3/setutent.3 | 1 + man/man3/setutxent.3 | 1 + man/man3/setvbuf.3 | 1 + man/man3/sgetspent.3 | 1 + man/man3/sgetspent_r.3 | 1 + man/man3/shm_open.3 | 521 +++ man/man3/shm_unlink.3 | 1 + man/man3/sigabbrev_np.3 | 1 + man/man3/sigaddset.3 | 1 + man/man3/sigandset.3 | 1 + man/man3/sigblock.3 | 1 + man/man3/sigdelset.3 | 1 + man/man3/sigdescr_np.3 | 1 + man/man3/sigemptyset.3 | 1 + man/man3/sigfillset.3 | 1 + man/man3/siggetmask.3 | 1 + man/man3/sighold.3 | 1 + man/man3/sigignore.3 | 1 + man/man3/siginterrupt.3 | 98 + man/man3/sigisemptyset.3 | 1 + man/man3/sigismember.3 | 1 + man/man3/siglongjmp.3 | 1 + man/man3/sigmask.3 | 1 + man/man3/signbit.3 | 79 + man/man3/signgam.3 | 1 + man/man3/significand.3 | 78 + man/man3/significandf.3 | 1 + man/man3/significandl.3 | 1 + man/man3/sigorset.3 | 1 + man/man3/sigpause.3 | 125 + man/man3/sigqueue.3 | 162 + man/man3/sigrelse.3 | 1 + man/man3/sigset.3 | 265 ++ man/man3/sigsetjmp.3 | 1 + man/man3/sigsetmask.3 | 1 + man/man3/sigsetops.3 | 190 + man/man3/sigstack.3 | 3 + man/man3/sigvec.3 | 282 ++ man/man3/sigwait.3 | 112 + man/man3/simpleq.3 | 1 + man/man3/sin.3 | 122 + man/man3/sincos.3 | 112 + man/man3/sincosf.3 | 1 + man/man3/sincosl.3 | 1 + man/man3/sinf.3 | 1 + man/man3/sinh.3 | 129 + man/man3/sinhf.3 | 1 + man/man3/sinhl.3 | 1 + man/man3/sinl.3 | 1 + man/man3/sleep.3 | 79 + man/man3/slist.3 | 319 ++ man/man3/snprintf.3 | 1 + man/man3/sockatmark.3 | 138 + man/man3/sprintf.3 | 1 + man/man3/sqrt.3 | 109 + man/man3/sqrtf.3 | 1 + man/man3/sqrtl.3 | 1 + man/man3/srand.3 | 1 + man/man3/srand48.3 | 1 + man/man3/srand48_r.3 | 1 + man/man3/srandom.3 | 1 + man/man3/srandom_r.3 | 1 + man/man3/sscanf.3 | 730 ++++ man/man3/ssignal.3 | 1 + man/man3/stailq.3 | 377 ++ man/man3/static_assert.3 | 119 + man/man3/statvfs.3 | 256 ++ man/man3/stdarg.3 | 297 ++ man/man3/stderr.3 | 1 + man/man3/stdin.3 | 160 + man/man3/stdio.3 | 353 ++ man/man3/stdio_ext.3 | 137 + man/man3/stdout.3 | 1 + man/man3/stpcpy.3 | 1 + man/man3/stpncpy.3 | 178 + man/man3/strcasecmp.3 | 112 + man/man3/strcasestr.3 | 1 + man/man3/strcat.3 | 1 + man/man3/strchr.3 | 131 + man/man3/strchrnul.3 | 1 + man/man3/strcmp.3 | 208 + man/man3/strcoll.3 | 86 + man/man3/strcpy.3 | 204 + man/man3/strcspn.3 | 1 + man/man3/strdup.3 | 145 + man/man3/strdupa.3 | 1 + man/man3/strerror.3 | 324 ++ man/man3/strerror_l.3 | 1 + man/man3/strerror_r.3 | 1 + man/man3/strerrordesc_np.3 | 1 + man/man3/strerrorname_np.3 | 1 + man/man3/strfmon.3 | 209 + man/man3/strfmon_l.3 | 1 + man/man3/strfromd.3 | 231 + man/man3/strfromf.3 | 1 + man/man3/strfroml.3 | 1 + man/man3/strfry.3 | 55 + man/man3/strftime.3 | 777 ++++ man/man3/strftime_l.3 | 1 + man/man3/string.3 | 217 + man/man3/strlen.3 | 61 + man/man3/strncasecmp.3 | 1 + man/man3/strncat.3 | 132 + man/man3/strncmp.3 | 1 + man/man3/strncpy.3 | 1 + man/man3/strndup.3 | 1 + man/man3/strndupa.3 | 1 + man/man3/strnlen.3 | 83 + man/man3/strpbrk.3 | 66 + man/man3/strptime.3 | 413 ++ man/man3/strrchr.3 | 1 + man/man3/strsep.3 | 162 + man/man3/strsignal.3 | 169 + man/man3/strspn.3 | 85 + man/man3/strstr.3 | 98 + man/man3/strtod.3 | 205 + man/man3/strtof.3 | 1 + man/man3/strtoimax.3 | 68 + man/man3/strtok.3 | 288 ++ man/man3/strtok_r.3 | 1 + man/man3/strtol.3 | 321 ++ man/man3/strtold.3 | 1 + man/man3/strtoll.3 | 1 + man/man3/strtoq.3 | 1 + man/man3/strtoul.3 | 224 + man/man3/strtoull.3 | 1 + man/man3/strtoumax.3 | 1 + man/man3/strtouq.3 | 1 + man/man3/strverscmp.3 | 146 + man/man3/strxfrm.3 | 86 + man/man3/svc_destroy.3 | 1 + man/man3/svc_freeargs.3 | 1 + man/man3/svc_getargs.3 | 1 + man/man3/svc_getcaller.3 | 1 + man/man3/svc_getreq.3 | 1 + man/man3/svc_getreqset.3 | 1 + man/man3/svc_register.3 | 1 + man/man3/svc_run.3 | 1 + man/man3/svc_sendreply.3 | 1 + man/man3/svc_unregister.3 | 1 + man/man3/svcerr_auth.3 | 1 + man/man3/svcerr_decode.3 | 1 + man/man3/svcerr_noproc.3 | 1 + man/man3/svcerr_noprog.3 | 1 + man/man3/svcerr_progvers.3 | 1 + man/man3/svcerr_systemerr.3 | 1 + man/man3/svcerr_weakauth.3 | 1 + man/man3/svcfd_create.3 | 1 + man/man3/svcraw_create.3 | 1 + man/man3/svctcp_create.3 | 1 + man/man3/svcudp_bufcreate.3 | 1 + man/man3/svcudp_create.3 | 1 + man/man3/swab.3 | 76 + man/man3/swapcontext.3 | 1 + man/man3/swprintf.3 | 1 + man/man3/sys_errlist.3 | 1 + man/man3/sys_nerr.3 | 1 + man/man3/sys_siglist.3 | 1 + man/man3/sysconf.3 | 390 ++ man/man3/syslog.3 | 359 ++ man/man3/system.3 | 269 ++ man/man3/sysv_signal.3 | 90 + man/man3/tailq.3 | 397 ++ man/man3/tan.3 | 146 + man/man3/tanf.3 | 1 + man/man3/tanh.3 | 105 + man/man3/tanhf.3 | 1 + man/man3/tanhl.3 | 1 + man/man3/tanl.3 | 1 + man/man3/tcdrain.3 | 1 + man/man3/tcflow.3 | 1 + man/man3/tcflush.3 | 1 + man/man3/tcgetattr.3 | 1 + man/man3/tcgetpgrp.3 | 125 + man/man3/tcgetsid.3 | 73 + man/man3/tcsendbreak.3 | 1 + man/man3/tcsetattr.3 | 1 + man/man3/tcsetpgrp.3 | 1 + man/man3/tdelete.3 | 1 + man/man3/tdestroy.3 | 1 + man/man3/telldir.3 | 100 + man/man3/tempnam.3 | 175 + man/man3/termios.3 | 1235 ++++++ man/man3/tfind.3 | 1 + man/man3/tgamma.3 | 216 + man/man3/tgammaf.3 | 1 + man/man3/tgammal.3 | 1 + man/man3/timegm.3 | 92 + man/man3/timelocal.3 | 1 + man/man3/timeradd.3 | 143 + man/man3/timerclear.3 | 1 + man/man3/timercmp.3 | 1 + man/man3/timerisset.3 | 1 + man/man3/timersub.3 | 1 + man/man3/timezone.3 | 1 + man/man3/tmpfile.3 | 103 + man/man3/tmpnam.3 | 168 + man/man3/tmpnam_r.3 | 1 + man/man3/toascii.3 | 68 + man/man3/tolower.3 | 1 + man/man3/tolower_l.3 | 1 + man/man3/toupper.3 | 185 + man/man3/toupper_l.3 | 1 + man/man3/towctrans.3 | 82 + man/man3/towlower.3 | 131 + man/man3/towlower_l.3 | 1 + man/man3/towupper.3 | 130 + man/man3/towupper_l.3 | 1 + man/man3/trunc.3 | 83 + man/man3/truncf.3 | 1 + man/man3/truncl.3 | 1 + man/man3/tsearch.3 | 356 ++ man/man3/ttyname.3 | 111 + man/man3/ttyname_r.3 | 1 + man/man3/ttyslot.3 | 169 + man/man3/twalk.3 | 1 + man/man3/twalk_r.3 | 1 + man/man3/tzname.3 | 1 + man/man3/tzset.3 | 244 ++ man/man3/ualarm.3 | 140 + man/man3/ulckpwdf.3 | 1 + man/man3/ulimit.3 | 87 + man/man3/undocumented.3 | 164 + man/man3/ungetc.3 | 1 + man/man3/ungetwc.3 | 102 + man/man3/unlocked_stdio.3 | 202 + man/man3/unlockpt.3 | 84 + man/man3/unsetenv.3 | 1 + man/man3/updwtmp.3 | 81 + man/man3/updwtmpx.3 | 1 + man/man3/uselocale.3 | 102 + man/man3/usleep.3 | 123 + man/man3/utmpname.3 | 1 + man/man3/utmpxname.3 | 1 + man/man3/va_arg.3 | 1 + man/man3/va_copy.3 | 1 + man/man3/va_end.3 | 1 + man/man3/va_start.3 | 1 + man/man3/valloc.3 | 1 + man/man3/vasprintf.3 | 1 + man/man3/vdprintf.3 | 1 + man/man3/verr.3 | 1 + man/man3/verrx.3 | 1 + man/man3/versionsort.3 | 1 + man/man3/vfprintf.3 | 1 + man/man3/vfscanf.3 | 1 + man/man3/vfwprintf.3 | 1 + man/man3/vlimit.3 | 3 + man/man3/vprintf.3 | 1 + man/man3/vscanf.3 | 1 + man/man3/vsnprintf.3 | 1 + man/man3/vsprintf.3 | 1 + man/man3/vsscanf.3 | 1 + man/man3/vswprintf.3 | 1 + man/man3/vsyslog.3 | 1 + man/man3/vtimes.3 | 3 + man/man3/vwarn.3 | 1 + man/man3/vwarnx.3 | 1 + man/man3/vwprintf.3 | 1 + man/man3/warn.3 | 1 + man/man3/warnx.3 | 1 + man/man3/wcpcpy.3 | 79 + man/man3/wcpncpy.3 | 106 + man/man3/wcrtomb.3 | 144 + man/man3/wcscasecmp.3 | 99 + man/man3/wcscat.3 | 70 + man/man3/wcschr.3 | 69 + man/man3/wcscmp.3 | 79 + man/man3/wcscpy.3 | 72 + man/man3/wcscspn.3 | 81 + man/man3/wcsdup.3 | 83 + man/man3/wcslen.3 | 65 + man/man3/wcsncasecmp.3 | 105 + man/man3/wcsncat.3 | 72 + man/man3/wcsncmp.3 | 93 + man/man3/wcsncpy.3 | 89 + man/man3/wcsnlen.3 | 91 + man/man3/wcsnrtombs.3 | 189 + man/man3/wcspbrk.3 | 69 + man/man3/wcsrchr.3 | 66 + man/man3/wcsrtombs.3 | 164 + man/man3/wcsspn.3 | 78 + man/man3/wcsstr.3 | 75 + man/man3/wcstoimax.3 | 58 + man/man3/wcstok.3 | 117 + man/man3/wcstombs.3 | 125 + man/man3/wcstoumax.3 | 1 + man/man3/wcswidth.3 | 73 + man/man3/wctob.3 | 86 + man/man3/wctomb.3 | 119 + man/man3/wctrans.3 | 88 + man/man3/wctype.3 | 100 + man/man3/wcwidth.3 | 77 + man/man3/wmemchr.3 | 70 + man/man3/wmemcmp.3 | 90 + man/man3/wmemcpy.3 | 75 + man/man3/wmemmove.3 | 70 + man/man3/wmempcpy.3 | 1 + man/man3/wmemset.3 | 61 + man/man3/wordexp.3 | 245 ++ man/man3/wordfree.3 | 1 + man/man3/wprintf.3 | 273 ++ man/man3/xcrypt.3 | 95 + man/man3/xdecrypt.3 | 1 + man/man3/xdr.3 | 609 +++ man/man3/xdr_accepted_reply.3 | 1 + man/man3/xdr_array.3 | 1 + man/man3/xdr_authunix_parms.3 | 1 + man/man3/xdr_bool.3 | 1 + man/man3/xdr_bytes.3 | 1 + man/man3/xdr_callhdr.3 | 1 + man/man3/xdr_callmsg.3 | 1 + man/man3/xdr_char.3 | 1 + man/man3/xdr_destroy.3 | 1 + man/man3/xdr_double.3 | 1 + man/man3/xdr_enum.3 | 1 + man/man3/xdr_float.3 | 1 + man/man3/xdr_free.3 | 1 + man/man3/xdr_getpos.3 | 1 + man/man3/xdr_inline.3 | 1 + man/man3/xdr_int.3 | 1 + man/man3/xdr_long.3 | 1 + man/man3/xdr_opaque.3 | 1 + man/man3/xdr_opaque_auth.3 | 1 + man/man3/xdr_pmap.3 | 1 + man/man3/xdr_pmaplist.3 | 1 + man/man3/xdr_pointer.3 | 1 + man/man3/xdr_reference.3 | 1 + man/man3/xdr_rejected_reply.3 | 1 + man/man3/xdr_replymsg.3 | 1 + man/man3/xdr_setpos.3 | 1 + man/man3/xdr_short.3 | 1 + man/man3/xdr_string.3 | 1 + man/man3/xdr_u_char.3 | 1 + man/man3/xdr_u_int.3 | 1 + man/man3/xdr_u_long.3 | 1 + man/man3/xdr_u_short.3 | 1 + man/man3/xdr_union.3 | 1 + man/man3/xdr_vector.3 | 1 + man/man3/xdr_void.3 | 1 + man/man3/xdr_wrapstring.3 | 1 + man/man3/xdrmem_create.3 | 1 + man/man3/xdrrec_create.3 | 1 + man/man3/xdrrec_endofrecord.3 | 1 + man/man3/xdrrec_eof.3 | 1 + man/man3/xdrrec_skiprecord.3 | 1 + man/man3/xdrstdio_create.3 | 1 + man/man3/xencrypt.3 | 1 + man/man3/xprt_register.3 | 1 + man/man3/xprt_unregister.3 | 1 + man/man3/y0.3 | 276 ++ man/man3/y0f.3 | 1 + man/man3/y0l.3 | 1 + man/man3/y1.3 | 1 + man/man3/y1f.3 | 1 + man/man3/y1l.3 | 1 + man/man3/yn.3 | 1 + man/man3/ynf.3 | 1 + man/man3/ynl.3 | 1 + man/man3const/EOF.3const | 42 + man/man3const/EXIT_FAILURE.3const | 1 + man/man3const/EXIT_SUCCESS.3const | 61 + man/man3const/NULL.3const | 74 + man/man3const/PA_CHAR.3const | 1 + man/man3const/PA_DOUBLE.3const | 1 + man/man3const/PA_FLAG_LONG.3const | 1 + man/man3const/PA_FLAG_LONG_DOUBLE.3const | 1 + man/man3const/PA_FLAG_LONG_LONG.3const | 1 + man/man3const/PA_FLAG_PTR.3const | 1 + man/man3const/PA_FLAG_SHORT.3const | 1 + man/man3const/PA_FLOAT.3const | 1 + man/man3const/PA_INT.3const | 1 + man/man3const/PA_LAST.3const | 1 + man/man3const/PA_POINTER.3const | 1 + man/man3const/PA_STRING.3const | 1 + man/man3const/PA_WCHAR.3const | 1 + man/man3const/PA_WSTRING.3const | 1 + man/man3head/printf.h.3head | 582 +++ man/man3head/sysexits.h.3head | 200 + man/man3type/FILE.3type | 36 + man/man3type/aiocb.3type | 42 + man/man3type/blkcnt_t.3type | 30 + man/man3type/blksize_t.3type | 30 + man/man3type/cc_t.3type | 35 + man/man3type/clock_t.3type | 37 + man/man3type/clockid_t.3type | 28 + man/man3type/dev_t.3type | 33 + man/man3type/div_t.3type | 59 + man/man3type/double_t.3type | 56 + man/man3type/epoll_data.3type | 1 + man/man3type/epoll_data_t.3type | 1 + man/man3type/epoll_event.3type | 55 + man/man3type/fenv_t.3type | 35 + man/man3type/fexcept_t.3type | 1 + man/man3type/float_t.3type | 1 + man/man3type/gid_t.3type | 1 + man/man3type/id_t.3type | 110 + man/man3type/imaxdiv_t.3type | 1 + man/man3type/in6_addr.3type | 1 + man/man3type/in_addr.3type | 1 + man/man3type/in_addr_t.3type | 1 + man/man3type/in_port_t.3type | 1 + man/man3type/int16_t.3type | 1 + man/man3type/int32_t.3type | 1 + man/man3type/int64_t.3type | 1 + man/man3type/int8_t.3type | 1 + man/man3type/intN_t.3type | 177 + man/man3type/intmax_t.3type | 97 + man/man3type/intptr_t.3type | 107 + man/man3type/iovec.3type | 49 + man/man3type/itimerspec.3type | 32 + man/man3type/lconv.3type | 56 + man/man3type/ldiv_t.3type | 1 + man/man3type/lldiv_t.3type | 1 + man/man3type/locale_t.3type | 43 + man/man3type/loff_t.3type | 1 + man/man3type/mbstate_t.3type | 84 + man/man3type/mode_t.3type | 40 + man/man3type/off64_t.3type | 1 + man/man3type/off_t.3type | 92 + man/man3type/pid_t.3type | 1 + man/man3type/printf_arginfo_size_function.3type | 1 + man/man3type/printf_function.3type | 1 + man/man3type/printf_info.3type | 1 + man/man3type/printf_va_arg_function.3type | 1 + man/man3type/ptrdiff_t.3type | 47 + man/man3type/regex_t.3type | 1 + man/man3type/regmatch_t.3type | 1 + man/man3type/regoff_t.3type | 1 + man/man3type/sa_family_t.3type | 1 + man/man3type/sigevent.3type | 142 + man/man3type/siginfo_t.3type | 1 + man/man3type/sigset_t.3type | 1 + man/man3type/sigval.3type | 1 + man/man3type/size_t.3type | 181 + man/man3type/sockaddr.3type | 154 + man/man3type/sockaddr_in.3type | 1 + man/man3type/sockaddr_in6.3type | 1 + man/man3type/sockaddr_storage.3type | 1 + man/man3type/sockaddr_un.3type | 1 + man/man3type/socklen_t.3type | 1 + man/man3type/speed_t.3type | 1 + man/man3type/ssize_t.3type | 1 + man/man3type/stat.3type | 162 + man/man3type/suseconds_t.3type | 1 + man/man3type/tcflag_t.3type | 1 + man/man3type/time_t.3type | 111 + man/man3type/timer_t.3type | 34 + man/man3type/timespec.3type | 60 + man/man3type/timeval.3type | 43 + man/man3type/tm.3type | 112 + man/man3type/uid_t.3type | 1 + man/man3type/uint16_t.3type | 1 + man/man3type/uint32_t.3type | 1 + man/man3type/uint64_t.3type | 1 + man/man3type/uint8_t.3type | 1 + man/man3type/uintN_t.3type | 1 + man/man3type/uintmax_t.3type | 1 + man/man3type/uintptr_t.3type | 1 + man/man3type/useconds_t.3type | 1 + man/man3type/va_list.3type | 44 + man/man3type/void.3type | 76 + man/man3type/wchar_t.3type | 48 + man/man3type/wint_t.3type | 56 + man/man4/cciss.4 | 385 ++ man/man4/console_codes.4 | 811 ++++ man/man4/console_ioctl.4 | 2 + man/man4/cpuid.4 | 83 + man/man4/dsp56k.4 | 107 + man/man4/fd.4 | 232 + man/man4/full.4 | 46 + man/man4/fuse.4 | 535 +++ man/man4/hd.4 | 82 + man/man4/hpsa.4 | 240 ++ man/man4/initrd.4 | 479 +++ man/man4/intro.4 | 22 + man/man4/kmem.4 | 1 + man/man4/lirc.4 | 423 ++ man/man4/loop-control.4 | 1 + man/man4/loop.4 | 361 ++ man/man4/lp.4 | 137 + man/man4/mem.4 | 81 + man/man4/mouse.4 | 171 + man/man4/msr.4 | 42 + man/man4/null.4 | 52 + man/man4/port.4 | 1 + man/man4/ptmx.4 | 1 + man/man4/pts.4 | 75 + man/man4/ram.4 | 28 + man/man4/random.4 | 349 ++ man/man4/rtc.4 | 347 ++ man/man4/sd.4 | 117 + man/man4/sk98lin.4 | 580 +++ man/man4/smartpqi.4 | 496 +++ man/man4/st.4 | 950 +++++ man/man4/tty.4 | 67 + man/man4/ttyS.4 | 33 + man/man4/tty_ioctl.4 | 2 + man/man4/urandom.4 | 1 + man/man4/vcs.4 | 172 + man/man4/vcsa.4 | 1 + man/man4/veth.4 | 86 + man/man4/wavelan.4 | 142 + man/man4/zero.4 | 1 + man/man5/acct.5 | 161 + man/man5/charmap.5 | 105 + man/man5/core.5 | 684 +++ man/man5/dir_colors.5 | 406 ++ man/man5/elf.5 | 2213 ++++++++++ man/man5/erofs.5 | 97 + man/man5/filesystems.5 | 227 + man/man5/fs.5 | 1 + man/man5/ftpusers.5 | 42 + man/man5/gai.conf.5 | 89 + man/man5/group.5 | 55 + man/man5/host.conf.5 | 204 + man/man5/hosts.5 | 122 + man/man5/hosts.equiv.5 | 212 + man/man5/intro.5 | 23 + man/man5/issue.5 | 24 + man/man5/locale.5 | 1316 ++++++ man/man5/motd.5 | 25 + man/man5/networks.5 | 60 + man/man5/nologin.5 | 22 + man/man5/nscd.conf.5 | 342 ++ man/man5/nss.5 | 101 + man/man5/nsswitch.conf.5 | 427 ++ man/man5/passwd.5 | 160 + man/man5/proc.5 | 266 ++ man/man5/proc_apm.5 | 17 + man/man5/proc_buddyinfo.5 | 58 + man/man5/proc_bus.5 | 35 + man/man5/proc_cgroups.5 | 16 + man/man5/proc_cmdline.5 | 22 + man/man5/proc_config.gz.5 | 40 + man/man5/proc_cpuinfo.5 | 24 + man/man5/proc_crypto.5 | 26 + man/man5/proc_devices.5 | 16 + man/man5/proc_diskstats.5 | 21 + man/man5/proc_dma.5 | 16 + man/man5/proc_driver.5 | 15 + man/man5/proc_execdomains.5 | 16 + man/man5/proc_fb.5 | 17 + man/man5/proc_filesystems.5 | 33 + man/man5/proc_fs.5 | 18 + man/man5/proc_ide.5 | 37 + man/man5/proc_interrupts.5 | 22 + man/man5/proc_iomem.5 | 15 + man/man5/proc_ioports.5 | 16 + man/man5/proc_kallsyms.5 | 25 + man/man5/proc_kcore.5 | 24 + man/man5/proc_key-users.5 | 1 + man/man5/proc_keys.5 | 20 + man/man5/proc_kmsg.5 | 28 + man/man5/proc_kpagecgroup.5 | 25 + man/man5/proc_kpagecount.5 | 24 + man/man5/proc_kpageflags.5 | 75 + man/man5/proc_ksyms.5 | 1 + man/man5/proc_loadavg.5 | 27 + man/man5/proc_locks.5 | 122 + man/man5/proc_malloc.5 | 18 + man/man5/proc_meminfo.5 | 327 ++ man/man5/proc_modules.5 | 17 + man/man5/proc_mounts.5 | 1 + man/man5/proc_mtrr.5 | 24 + man/man5/proc_net.5 | 1 + man/man5/proc_partitions.5 | 16 + man/man5/proc_pci.5 | 28 + man/man5/proc_pid.5 | 73 + man/man5/proc_pid_attr.5 | 137 + man/man5/proc_pid_autogroup.5 | 17 + man/man5/proc_pid_auxv.5 | 27 + man/man5/proc_pid_cgroup.5 | 16 + man/man5/proc_pid_clear_refs.5 | 87 + man/man5/proc_pid_cmdline.5 | 49 + man/man5/proc_pid_comm.5 | 49 + man/man5/proc_pid_coredump_filter.5 | 16 + man/man5/proc_pid_cpuset.5 | 17 + man/man5/proc_pid_cwd.5 | 36 + man/man5/proc_pid_environ.5 | 48 + man/man5/proc_pid_exe.5 | 59 + man/man5/proc_pid_fd.5 | 161 + man/man5/proc_pid_fdinfo.5 | 300 ++ man/man5/proc_pid_gid_map.5 | 1 + man/man5/proc_pid_io.5 | 100 + man/man5/proc_pid_limits.5 | 25 + man/man5/proc_pid_map_files.5 | 72 + man/man5/proc_pid_maps.5 | 156 + man/man5/proc_pid_mem.5 | 24 + man/man5/proc_pid_mountinfo.5 | 124 + man/man5/proc_pid_mounts.5 | 49 + man/man5/proc_pid_mountstats.5 | 46 + man/man5/proc_pid_net.5 | 298 ++ man/man5/proc_pid_ns.5 | 20 + man/man5/proc_pid_numa_maps.5 | 16 + man/man5/proc_pid_oom_adj.5 | 1 + man/man5/proc_pid_oom_score.5 | 58 + man/man5/proc_pid_oom_score_adj.5 | 117 + man/man5/proc_pid_pagemap.5 | 77 + man/man5/proc_pid_personality.5 | 23 + man/man5/proc_pid_projid_map.5 | 17 + man/man5/proc_pid_root.5 | 75 + man/man5/proc_pid_seccomp.5 | 36 + man/man5/proc_pid_setgroups.5 | 16 + man/man5/proc_pid_smaps.5 | 129 + man/man5/proc_pid_stack.5 | 25 + man/man5/proc_pid_stat.5 | 380 ++ man/man5/proc_pid_statm.5 | 46 + man/man5/proc_pid_status.5 | 384 ++ man/man5/proc_pid_syscall.5 | 33 + man/man5/proc_pid_task.5 | 97 + man/man5/proc_pid_timers.5 | 82 + man/man5/proc_pid_timerslack_ns.5 | 41 + man/man5/proc_pid_uid_map.5 | 20 + man/man5/proc_pid_wchan.5 | 21 + man/man5/proc_profile.5 | 24 + man/man5/proc_scsi.5 | 66 + man/man5/proc_self.5 | 1 + man/man5/proc_slabinfo.5 | 18 + man/man5/proc_stat.5 | 140 + man/man5/proc_swaps.5 | 17 + man/man5/proc_sys.5 | 31 + man/man5/proc_sys_abi.5 | 24 + man/man5/proc_sys_debug.5 | 17 + man/man5/proc_sys_dev.5 | 20 + man/man5/proc_sys_fs.5 | 471 +++ man/man5/proc_sys_kernel.5 | 691 +++ man/man5/proc_sys_net.5 | 34 + man/man5/proc_sys_proc.5 | 17 + man/man5/proc_sys_sunrpc.5 | 19 + man/man5/proc_sys_user.5 | 18 + man/man5/proc_sys_vm.5 | 420 ++ man/man5/proc_sysrq-trigger.5 | 25 + man/man5/proc_sysvipc.5 | 25 + man/man5/proc_thread-self.5 | 1 + man/man5/proc_tid.5 | 1 + man/man5/proc_tid_children.5 | 37 + man/man5/proc_timer_list.5 | 18 + man/man5/proc_timer_stats.5 | 117 + man/man5/proc_tty.5 | 16 + man/man5/proc_uptime.5 | 17 + man/man5/proc_version.5 | 27 + man/man5/proc_vmstat.5 | 702 +++ man/man5/proc_zoneinfo.5 | 17 + man/man5/procfs.5 | 1 + man/man5/protocols.5 | 66 + man/man5/repertoiremap.5 | 58 + man/man5/resolv.conf.5 | 406 ++ man/man5/resolver.5 | 1 + man/man5/rpc.5 | 83 + man/man5/securetty.5 | 35 + man/man5/services.5 | 199 + man/man5/shells.5 | 40 + man/man5/slabinfo.5 | 220 + man/man5/sysfs.5 | 275 ++ man/man5/termcap.5 | 466 ++ man/man5/tmpfs.5 | 281 ++ man/man5/ttytype.5 | 56 + man/man5/tzfile.5 | 508 +++ man/man5/utmp.5 | 348 ++ man/man5/utmpx.5 | 1 + man/man5/wtmp.5 | 1 + man/man6/intro.6 | 17 + man/man7/address_families.7 | 392 ++ man/man7/aio.7 | 446 ++ man/man7/armscii-8.7 | 120 + man/man7/arp.7 | 306 ++ man/man7/ascii.7 | 169 + man/man7/attributes.7 | 865 ++++ man/man7/boot.7 | 230 + man/man7/bootparam.7 | 664 +++ man/man7/bpf-helpers.7 | 5171 +++++++++++++++++++++++ man/man7/capabilities.7 | 1872 ++++++++ man/man7/cgroup_namespaces.7 | 248 ++ man/man7/cgroups.7 | 1914 +++++++++ man/man7/charsets.7 | 335 ++ man/man7/complex.7 | 83 + man/man7/cp1251.7 | 166 + man/man7/cp1252.7 | 156 + man/man7/cpuset.7 | 1504 +++++++ man/man7/credentials.7 | 384 ++ man/man7/ddp.7 | 245 ++ man/man7/environ.7 | 354 ++ man/man7/epoll.7 | 610 +++ man/man7/fanotify.7 | 1456 +++++++ man/man7/feature_test_macros.7 | 937 ++++ man/man7/fifo.7 | 70 + man/man7/futex.7 | 121 + man/man7/glibc.7 | 1 + man/man7/glob.7 | 205 + man/man7/hier.7 | 654 +++ man/man7/hostname.7 | 97 + man/man7/icmp.7 | 196 + man/man7/inode.7 | 480 +++ man/man7/inotify.7 | 1100 +++++ man/man7/intro.7 | 23 + man/man7/ip.7 | 1541 +++++++ man/man7/ipc_namespaces.7 | 66 + man/man7/ipv6.7 | 416 ++ man/man7/iso-8859-1.7 | 1 + man/man7/iso-8859-10.7 | 1 + man/man7/iso-8859-11.7 | 1 + man/man7/iso-8859-13.7 | 1 + man/man7/iso-8859-14.7 | 1 + man/man7/iso-8859-15.7 | 1 + man/man7/iso-8859-16.7 | 1 + man/man7/iso-8859-2.7 | 1 + man/man7/iso-8859-3.7 | 1 + man/man7/iso-8859-4.7 | 1 + man/man7/iso-8859-5.7 | 1 + man/man7/iso-8859-6.7 | 1 + man/man7/iso-8859-7.7 | 1 + man/man7/iso-8859-8.7 | 1 + man/man7/iso-8859-9.7 | 1 + man/man7/iso_8859-1.7 | 150 + man/man7/iso_8859-10.7 | 146 + man/man7/iso_8859-11.7 | 143 + man/man7/iso_8859-13.7 | 146 + man/man7/iso_8859-14.7 | 146 + man/man7/iso_8859-15.7 | 149 + man/man7/iso_8859-16.7 | 147 + man/man7/iso_8859-2.7 | 151 + man/man7/iso_8859-3.7 | 139 + man/man7/iso_8859-4.7 | 146 + man/man7/iso_8859-5.7 | 151 + man/man7/iso_8859-6.7 | 104 + man/man7/iso_8859-7.7 | 150 + man/man7/iso_8859-8.7 | 114 + man/man7/iso_8859-9.7 | 146 + man/man7/iso_8859_1.7 | 1 + man/man7/iso_8859_10.7 | 1 + man/man7/iso_8859_11.7 | 1 + man/man7/iso_8859_13.7 | 1 + man/man7/iso_8859_14.7 | 1 + man/man7/iso_8859_15.7 | 1 + man/man7/iso_8859_16.7 | 1 + man/man7/iso_8859_2.7 | 1 + man/man7/iso_8859_3.7 | 1 + man/man7/iso_8859_4.7 | 1 + man/man7/iso_8859_5.7 | 1 + man/man7/iso_8859_6.7 | 1 + man/man7/iso_8859_7.7 | 1 + man/man7/iso_8859_8.7 | 1 + man/man7/iso_8859_9.7 | 1 + man/man7/kernel_lockdown.7 | 109 + man/man7/keyrings.7 | 901 ++++ man/man7/koi8-r.7 | 169 + man/man7/koi8-u.7 | 175 + man/man7/landlock.7 | 585 +++ man/man7/latin1.7 | 1 + man/man7/latin10.7 | 1 + man/man7/latin2.7 | 1 + man/man7/latin3.7 | 1 + man/man7/latin4.7 | 1 + man/man7/latin5.7 | 1 + man/man7/latin6.7 | 1 + man/man7/latin7.7 | 1 + man/man7/latin8.7 | 1 + man/man7/latin9.7 | 1 + man/man7/libc.7 | 115 + man/man7/locale.7 | 379 ++ man/man7/mailaddr.7 | 134 + man/man7/man-pages.7 | 1227 ++++++ man/man7/man.7 | 1 + man/man7/math_error.7 | 246 ++ man/man7/mount_namespaces.7 | 1371 ++++++ man/man7/mq_overview.7 | 389 ++ man/man7/namespaces.7 | 417 ++ man/man7/netdevice.7 | 449 ++ man/man7/netlink.7 | 611 +++ man/man7/network_namespaces.7 | 62 + man/man7/nptl.7 | 112 + man/man7/numa.7 | 170 + man/man7/operator.7 | 54 + man/man7/packet.7 | 694 +++ man/man7/path_resolution.7 | 264 ++ man/man7/persistent-keyring.7 | 124 + man/man7/pid_namespaces.7 | 388 ++ man/man7/pipe.7 | 407 ++ man/man7/pkeys.7 | 237 ++ man/man7/posixoptions.7 | 1014 +++++ man/man7/precedence.7 | 1 + man/man7/process-keyring.7 | 55 + man/man7/pthreads.7 | 937 ++++ man/man7/pty.7 | 161 + man/man7/queue.7 | 138 + man/man7/random.7 | 213 + man/man7/raw.7 | 281 ++ man/man7/regex.7 | 293 ++ man/man7/rtld-audit.7 | 606 +++ man/man7/rtnetlink.7 | 590 +++ man/man7/sched.7 | 992 +++++ man/man7/sem_overview.7 | 139 + man/man7/session-keyring.7 | 113 + man/man7/shm_overview.7 | 104 + man/man7/sigevent.7 | 1 + man/man7/signal-safety.7 | 341 ++ man/man7/signal.7 | 1019 +++++ man/man7/sock_diag.7 | 825 ++++ man/man7/socket.7 | 1274 ++++++ man/man7/spufs.7 | 804 ++++ man/man7/standards.7 | 307 ++ man/man7/string_copying.7 | 809 ++++ man/man7/suffixes.7 | 265 ++ man/man7/svipc.7 | 1 + man/man7/symlink.7 | 564 +++ man/man7/system_data_types.7 | 242 ++ man/man7/sysvipc.7 | 99 + man/man7/tcp.7 | 1563 +++++++ man/man7/termio.7 | 45 + man/man7/thread-keyring.7 | 50 + man/man7/time.7 | 218 + man/man7/time_namespaces.7 | 345 ++ man/man7/tis-620.7 | 1 + man/man7/udp.7 | 312 ++ man/man7/udplite.7 | 137 + man/man7/unicode.7 | 246 ++ man/man7/units.7 | 108 + man/man7/unix.7 | 1229 ++++++ man/man7/uri.7 | 761 ++++ man/man7/url.7 | 1 + man/man7/urn.7 | 1 + man/man7/user-keyring.7 | 81 + man/man7/user-session-keyring.7 | 92 + man/man7/user_namespaces.7 | 1469 +++++++ man/man7/utf-8.7 | 205 + man/man7/utf8.7 | 1 + man/man7/uts_namespaces.7 | 46 + man/man7/vdso.7 | 612 +++ man/man7/vsock.7 | 232 + man/man7/x25.7 | 124 + man/man7/xattr.7 | 180 + man/man8/iconvconfig.8 | 92 + man/man8/intro.8 | 29 + man/man8/ld-linux.8 | 1 + man/man8/ld-linux.so.8 | 1 + man/man8/ld.so.8 | 929 ++++ man/man8/ldconfig.8 | 204 + man/man8/nscd.8 | 84 + man/man8/sln.8 | 44 + man/man8/tzselect.8 | 125 + man/man8/zdump.8 | 230 + man/man8/zic.8 | 894 ++++ 2703 files changed, 290943 insertions(+) create mode 100644 man/man1/getent.1 create mode 100644 man/man1/iconv.1 create mode 100644 man/man1/intro.1 create mode 100644 man/man1/ldd.1 create mode 100644 man/man1/locale.1 create mode 100644 man/man1/localedef.1 create mode 100644 man/man1/memusage.1 create mode 100644 man/man1/memusagestat.1 create mode 100644 man/man1/mtrace.1 create mode 100644 man/man1/pldd.1 create mode 100644 man/man1/sprof.1 create mode 100644 man/man1/time.1 create mode 100644 man/man2/_Exit.2 create mode 100644 man/man2/__clone2.2 create mode 100644 man/man2/_exit.2 create mode 100644 man/man2/_llseek.2 create mode 100644 man/man2/_newselect.2 create mode 100644 man/man2/_syscall.2 create mode 100644 man/man2/_sysctl.2 create mode 100644 man/man2/accept.2 create mode 100644 man/man2/accept4.2 create mode 100644 man/man2/access.2 create mode 100644 man/man2/acct.2 create mode 100644 man/man2/add_key.2 create mode 100644 man/man2/adjtimex.2 create mode 100644 man/man2/afs_syscall.2 create mode 100644 man/man2/alarm.2 create mode 100644 man/man2/alloc_hugepages.2 create mode 100644 man/man2/arch_prctl.2 create mode 100644 man/man2/arm_fadvise.2 create mode 100644 man/man2/arm_fadvise64_64.2 create mode 100644 man/man2/arm_sync_file_range.2 create mode 100644 man/man2/bdflush.2 create mode 100644 man/man2/bind.2 create mode 100644 man/man2/bpf.2 create mode 100644 man/man2/break.2 create mode 100644 man/man2/brk.2 create mode 100644 man/man2/cacheflush.2 create mode 100644 man/man2/capget.2 create mode 100644 man/man2/capset.2 create mode 100644 man/man2/chdir.2 create mode 100644 man/man2/chmod.2 create mode 100644 man/man2/chown.2 create mode 100644 man/man2/chown32.2 create mode 100644 man/man2/chroot.2 create mode 100644 man/man2/clock_adjtime.2 create mode 100644 man/man2/clock_getres.2 create mode 100644 man/man2/clock_gettime.2 create mode 100644 man/man2/clock_nanosleep.2 create mode 100644 man/man2/clock_settime.2 create mode 100644 man/man2/clone.2 create mode 100644 man/man2/clone2.2 create mode 100644 man/man2/clone3.2 create mode 100644 man/man2/close.2 create mode 100644 man/man2/close_range.2 create mode 100644 man/man2/connect.2 create mode 100644 man/man2/copy_file_range.2 create mode 100644 man/man2/creat.2 create mode 100644 man/man2/create_module.2 create mode 100644 man/man2/delete_module.2 create mode 100644 man/man2/dup.2 create mode 100644 man/man2/dup2.2 create mode 100644 man/man2/dup3.2 create mode 100644 man/man2/epoll_create.2 create mode 100644 man/man2/epoll_create1.2 create mode 100644 man/man2/epoll_ctl.2 create mode 100644 man/man2/epoll_pwait.2 create mode 100644 man/man2/epoll_pwait2.2 create mode 100644 man/man2/epoll_wait.2 create mode 100644 man/man2/eventfd.2 create mode 100644 man/man2/eventfd2.2 create mode 100644 man/man2/execve.2 create mode 100644 man/man2/execveat.2 create mode 100644 man/man2/exit.2 create mode 100644 man/man2/exit_group.2 create mode 100644 man/man2/faccessat.2 create mode 100644 man/man2/faccessat2.2 create mode 100644 man/man2/fadvise64.2 create mode 100644 man/man2/fadvise64_64.2 create mode 100644 man/man2/fallocate.2 create mode 100644 man/man2/fanotify_init.2 create mode 100644 man/man2/fanotify_mark.2 create mode 100644 man/man2/fattach.2 create mode 100644 man/man2/fchdir.2 create mode 100644 man/man2/fchmod.2 create mode 100644 man/man2/fchmodat.2 create mode 100644 man/man2/fchown.2 create mode 100644 man/man2/fchown32.2 create mode 100644 man/man2/fchownat.2 create mode 100644 man/man2/fcntl.2 create mode 100644 man/man2/fcntl64.2 create mode 100644 man/man2/fdatasync.2 create mode 100644 man/man2/fdetach.2 create mode 100644 man/man2/fgetxattr.2 create mode 100644 man/man2/finit_module.2 create mode 100644 man/man2/flistxattr.2 create mode 100644 man/man2/flock.2 create mode 100644 man/man2/fork.2 create mode 100644 man/man2/free_hugepages.2 create mode 100644 man/man2/fremovexattr.2 create mode 100644 man/man2/fsetxattr.2 create mode 100644 man/man2/fstat.2 create mode 100644 man/man2/fstat64.2 create mode 100644 man/man2/fstatat.2 create mode 100644 man/man2/fstatat64.2 create mode 100644 man/man2/fstatfs.2 create mode 100644 man/man2/fstatfs64.2 create mode 100644 man/man2/fsync.2 create mode 100644 man/man2/ftruncate.2 create mode 100644 man/man2/ftruncate64.2 create mode 100644 man/man2/futex.2 create mode 100644 man/man2/futimesat.2 create mode 100644 man/man2/get_kernel_syms.2 create mode 100644 man/man2/get_mempolicy.2 create mode 100644 man/man2/get_robust_list.2 create mode 100644 man/man2/get_thread_area.2 create mode 100644 man/man2/getcpu.2 create mode 100644 man/man2/getcwd.2 create mode 100644 man/man2/getdents.2 create mode 100644 man/man2/getdents64.2 create mode 100644 man/man2/getdomainname.2 create mode 100644 man/man2/getegid.2 create mode 100644 man/man2/getegid32.2 create mode 100644 man/man2/geteuid.2 create mode 100644 man/man2/geteuid32.2 create mode 100644 man/man2/getgid.2 create mode 100644 man/man2/getgid32.2 create mode 100644 man/man2/getgroups.2 create mode 100644 man/man2/getgroups32.2 create mode 100644 man/man2/gethostname.2 create mode 100644 man/man2/getitimer.2 create mode 100644 man/man2/getmsg.2 create mode 100644 man/man2/getpagesize.2 create mode 100644 man/man2/getpeername.2 create mode 100644 man/man2/getpgid.2 create mode 100644 man/man2/getpgrp.2 create mode 100644 man/man2/getpid.2 create mode 100644 man/man2/getpmsg.2 create mode 100644 man/man2/getppid.2 create mode 100644 man/man2/getpriority.2 create mode 100644 man/man2/getrandom.2 create mode 100644 man/man2/getresgid.2 create mode 100644 man/man2/getresgid32.2 create mode 100644 man/man2/getresuid.2 create mode 100644 man/man2/getresuid32.2 create mode 100644 man/man2/getrlimit.2 create mode 100644 man/man2/getrusage.2 create mode 100644 man/man2/getsid.2 create mode 100644 man/man2/getsockname.2 create mode 100644 man/man2/getsockopt.2 create mode 100644 man/man2/gettid.2 create mode 100644 man/man2/gettimeofday.2 create mode 100644 man/man2/getuid.2 create mode 100644 man/man2/getuid32.2 create mode 100644 man/man2/getunwind.2 create mode 100644 man/man2/getxattr.2 create mode 100644 man/man2/gtty.2 create mode 100644 man/man2/idle.2 create mode 100644 man/man2/inb.2 create mode 100644 man/man2/inb_p.2 create mode 100644 man/man2/init_module.2 create mode 100644 man/man2/inl.2 create mode 100644 man/man2/inl_p.2 create mode 100644 man/man2/inotify_add_watch.2 create mode 100644 man/man2/inotify_init.2 create mode 100644 man/man2/inotify_init1.2 create mode 100644 man/man2/inotify_rm_watch.2 create mode 100644 man/man2/insb.2 create mode 100644 man/man2/insl.2 create mode 100644 man/man2/insw.2 create mode 100644 man/man2/intro.2 create mode 100644 man/man2/inw.2 create mode 100644 man/man2/inw_p.2 create mode 100644 man/man2/io_cancel.2 create mode 100644 man/man2/io_destroy.2 create mode 100644 man/man2/io_getevents.2 create mode 100644 man/man2/io_setup.2 create mode 100644 man/man2/io_submit.2 create mode 100644 man/man2/ioctl.2 create mode 100644 man/man2/ioctl_console.2 create mode 100644 man/man2/ioctl_fat.2 create mode 100644 man/man2/ioctl_ficlone.2 create mode 100644 man/man2/ioctl_ficlonerange.2 create mode 100644 man/man2/ioctl_fideduperange.2 create mode 100644 man/man2/ioctl_fslabel.2 create mode 100644 man/man2/ioctl_getfsmap.2 create mode 100644 man/man2/ioctl_iflags.2 create mode 100644 man/man2/ioctl_ns.2 create mode 100644 man/man2/ioctl_pagemap_scan.2 create mode 100644 man/man2/ioctl_pipe.2 create mode 100644 man/man2/ioctl_tty.2 create mode 100644 man/man2/ioctl_userfaultfd.2 create mode 100644 man/man2/ioperm.2 create mode 100644 man/man2/iopl.2 create mode 100644 man/man2/ioprio_get.2 create mode 100644 man/man2/ioprio_set.2 create mode 100644 man/man2/ipc.2 create mode 100644 man/man2/isastream.2 create mode 100644 man/man2/kcmp.2 create mode 100644 man/man2/kexec_file_load.2 create mode 100644 man/man2/kexec_load.2 create mode 100644 man/man2/keyctl.2 create mode 100644 man/man2/kill.2 create mode 100644 man/man2/landlock_add_rule.2 create mode 100644 man/man2/landlock_create_ruleset.2 create mode 100644 man/man2/landlock_restrict_self.2 create mode 100644 man/man2/lchown.2 create mode 100644 man/man2/lchown32.2 create mode 100644 man/man2/lgetxattr.2 create mode 100644 man/man2/link.2 create mode 100644 man/man2/linkat.2 create mode 100644 man/man2/listen.2 create mode 100644 man/man2/listxattr.2 create mode 100644 man/man2/llistxattr.2 create mode 100644 man/man2/llseek.2 create mode 100644 man/man2/lock.2 create mode 100644 man/man2/lookup_dcookie.2 create mode 100644 man/man2/lremovexattr.2 create mode 100644 man/man2/lseek.2 create mode 100644 man/man2/lsetxattr.2 create mode 100644 man/man2/lstat.2 create mode 100644 man/man2/lstat64.2 create mode 100644 man/man2/madvise.2 create mode 100644 man/man2/madvise1.2 create mode 100644 man/man2/mbind.2 create mode 100644 man/man2/membarrier.2 create mode 100644 man/man2/memfd_create.2 create mode 100644 man/man2/memfd_secret.2 create mode 100644 man/man2/migrate_pages.2 create mode 100644 man/man2/mincore.2 create mode 100644 man/man2/mkdir.2 create mode 100644 man/man2/mkdirat.2 create mode 100644 man/man2/mknod.2 create mode 100644 man/man2/mknodat.2 create mode 100644 man/man2/mlock.2 create mode 100644 man/man2/mlock2.2 create mode 100644 man/man2/mlockall.2 create mode 100644 man/man2/mmap.2 create mode 100644 man/man2/mmap2.2 create mode 100644 man/man2/modify_ldt.2 create mode 100644 man/man2/mount.2 create mode 100644 man/man2/mount_setattr.2 create mode 100644 man/man2/move_pages.2 create mode 100644 man/man2/mprotect.2 create mode 100644 man/man2/mpx.2 create mode 100644 man/man2/mq_getsetattr.2 create mode 100644 man/man2/mq_notify.2 create mode 100644 man/man2/mq_open.2 create mode 100644 man/man2/mq_timedreceive.2 create mode 100644 man/man2/mq_timedsend.2 create mode 100644 man/man2/mq_unlink.2 create mode 100644 man/man2/mremap.2 create mode 100644 man/man2/msgctl.2 create mode 100644 man/man2/msgget.2 create mode 100644 man/man2/msgop.2 create mode 100644 man/man2/msgrcv.2 create mode 100644 man/man2/msgsnd.2 create mode 100644 man/man2/msync.2 create mode 100644 man/man2/munlock.2 create mode 100644 man/man2/munlockall.2 create mode 100644 man/man2/munmap.2 create mode 100644 man/man2/name_to_handle_at.2 create mode 100644 man/man2/nanosleep.2 create mode 100644 man/man2/newfstatat.2 create mode 100644 man/man2/nfsservctl.2 create mode 100644 man/man2/nice.2 create mode 100644 man/man2/oldfstat.2 create mode 100644 man/man2/oldlstat.2 create mode 100644 man/man2/oldolduname.2 create mode 100644 man/man2/oldstat.2 create mode 100644 man/man2/olduname.2 create mode 100644 man/man2/open.2 create mode 100644 man/man2/open_by_handle_at.2 create mode 100644 man/man2/openat.2 create mode 100644 man/man2/openat2.2 create mode 100644 man/man2/outb.2 create mode 100644 man/man2/outb_p.2 create mode 100644 man/man2/outl.2 create mode 100644 man/man2/outl_p.2 create mode 100644 man/man2/outsb.2 create mode 100644 man/man2/outsl.2 create mode 100644 man/man2/outsw.2 create mode 100644 man/man2/outw.2 create mode 100644 man/man2/outw_p.2 create mode 100644 man/man2/pause.2 create mode 100644 man/man2/pciconfig_iobase.2 create mode 100644 man/man2/pciconfig_read.2 create mode 100644 man/man2/pciconfig_write.2 create mode 100644 man/man2/perf_event_open.2 create mode 100644 man/man2/perfmonctl.2 create mode 100644 man/man2/personality.2 create mode 100644 man/man2/phys.2 create mode 100644 man/man2/pidfd_getfd.2 create mode 100644 man/man2/pidfd_open.2 create mode 100644 man/man2/pidfd_send_signal.2 create mode 100644 man/man2/pipe.2 create mode 100644 man/man2/pipe2.2 create mode 100644 man/man2/pivot_root.2 create mode 100644 man/man2/pkey_alloc.2 create mode 100644 man/man2/pkey_free.2 create mode 100644 man/man2/pkey_mprotect.2 create mode 100644 man/man2/poll.2 create mode 100644 man/man2/posix_fadvise.2 create mode 100644 man/man2/ppoll.2 create mode 100644 man/man2/prctl.2 create mode 100644 man/man2/pread.2 create mode 100644 man/man2/pread64.2 create mode 100644 man/man2/preadv.2 create mode 100644 man/man2/preadv2.2 create mode 100644 man/man2/prlimit.2 create mode 100644 man/man2/prlimit64.2 create mode 100644 man/man2/process_madvise.2 create mode 100644 man/man2/process_vm_readv.2 create mode 100644 man/man2/process_vm_writev.2 create mode 100644 man/man2/prof.2 create mode 100644 man/man2/pselect.2 create mode 100644 man/man2/pselect6.2 create mode 100644 man/man2/ptrace.2 create mode 100644 man/man2/putmsg.2 create mode 100644 man/man2/putpmsg.2 create mode 100644 man/man2/pwrite.2 create mode 100644 man/man2/pwrite64.2 create mode 100644 man/man2/pwritev.2 create mode 100644 man/man2/pwritev2.2 create mode 100644 man/man2/query_module.2 create mode 100644 man/man2/quotactl.2 create mode 100644 man/man2/read.2 create mode 100644 man/man2/readahead.2 create mode 100644 man/man2/readdir.2 create mode 100644 man/man2/readlink.2 create mode 100644 man/man2/readlinkat.2 create mode 100644 man/man2/readv.2 create mode 100644 man/man2/reboot.2 create mode 100644 man/man2/recv.2 create mode 100644 man/man2/recvfrom.2 create mode 100644 man/man2/recvmmsg.2 create mode 100644 man/man2/recvmsg.2 create mode 100644 man/man2/remap_file_pages.2 create mode 100644 man/man2/removexattr.2 create mode 100644 man/man2/rename.2 create mode 100644 man/man2/renameat.2 create mode 100644 man/man2/renameat2.2 create mode 100644 man/man2/request_key.2 create mode 100644 man/man2/restart_syscall.2 create mode 100644 man/man2/rmdir.2 create mode 100644 man/man2/rt_sigaction.2 create mode 100644 man/man2/rt_sigpending.2 create mode 100644 man/man2/rt_sigprocmask.2 create mode 100644 man/man2/rt_sigqueueinfo.2 create mode 100644 man/man2/rt_sigreturn.2 create mode 100644 man/man2/rt_sigsuspend.2 create mode 100644 man/man2/rt_sigtimedwait.2 create mode 100644 man/man2/rt_tgsigqueueinfo.2 create mode 100644 man/man2/s390_guarded_storage.2 create mode 100644 man/man2/s390_pci_mmio_read.2 create mode 100644 man/man2/s390_pci_mmio_write.2 create mode 100644 man/man2/s390_runtime_instr.2 create mode 100644 man/man2/s390_sthyi.2 create mode 100644 man/man2/sbrk.2 create mode 100644 man/man2/sched_get_priority_max.2 create mode 100644 man/man2/sched_get_priority_min.2 create mode 100644 man/man2/sched_getaffinity.2 create mode 100644 man/man2/sched_getattr.2 create mode 100644 man/man2/sched_getparam.2 create mode 100644 man/man2/sched_getscheduler.2 create mode 100644 man/man2/sched_rr_get_interval.2 create mode 100644 man/man2/sched_setaffinity.2 create mode 100644 man/man2/sched_setattr.2 create mode 100644 man/man2/sched_setparam.2 create mode 100644 man/man2/sched_setscheduler.2 create mode 100644 man/man2/sched_yield.2 create mode 100644 man/man2/seccomp.2 create mode 100644 man/man2/seccomp_unotify.2 create mode 100644 man/man2/security.2 create mode 100644 man/man2/select.2 create mode 100644 man/man2/select_tut.2 create mode 100644 man/man2/semctl.2 create mode 100644 man/man2/semget.2 create mode 100644 man/man2/semop.2 create mode 100644 man/man2/semtimedop.2 create mode 100644 man/man2/send.2 create mode 100644 man/man2/sendfile.2 create mode 100644 man/man2/sendfile64.2 create mode 100644 man/man2/sendmmsg.2 create mode 100644 man/man2/sendmsg.2 create mode 100644 man/man2/sendto.2 create mode 100644 man/man2/set_mempolicy.2 create mode 100644 man/man2/set_robust_list.2 create mode 100644 man/man2/set_thread_area.2 create mode 100644 man/man2/set_tid_address.2 create mode 100644 man/man2/setdomainname.2 create mode 100644 man/man2/setegid.2 create mode 100644 man/man2/seteuid.2 create mode 100644 man/man2/setfsgid.2 create mode 100644 man/man2/setfsgid32.2 create mode 100644 man/man2/setfsuid.2 create mode 100644 man/man2/setfsuid32.2 create mode 100644 man/man2/setgid.2 create mode 100644 man/man2/setgid32.2 create mode 100644 man/man2/setgroups.2 create mode 100644 man/man2/setgroups32.2 create mode 100644 man/man2/sethostname.2 create mode 100644 man/man2/setitimer.2 create mode 100644 man/man2/setns.2 create mode 100644 man/man2/setpgid.2 create mode 100644 man/man2/setpgrp.2 create mode 100644 man/man2/setpriority.2 create mode 100644 man/man2/setregid.2 create mode 100644 man/man2/setregid32.2 create mode 100644 man/man2/setresgid.2 create mode 100644 man/man2/setresgid32.2 create mode 100644 man/man2/setresuid.2 create mode 100644 man/man2/setresuid32.2 create mode 100644 man/man2/setreuid.2 create mode 100644 man/man2/setreuid32.2 create mode 100644 man/man2/setrlimit.2 create mode 100644 man/man2/setsid.2 create mode 100644 man/man2/setsockopt.2 create mode 100644 man/man2/settimeofday.2 create mode 100644 man/man2/setuid.2 create mode 100644 man/man2/setuid32.2 create mode 100644 man/man2/setup.2 create mode 100644 man/man2/setxattr.2 create mode 100644 man/man2/sgetmask.2 create mode 100644 man/man2/shmat.2 create mode 100644 man/man2/shmctl.2 create mode 100644 man/man2/shmdt.2 create mode 100644 man/man2/shmget.2 create mode 100644 man/man2/shmop.2 create mode 100644 man/man2/shutdown.2 create mode 100644 man/man2/sigaction.2 create mode 100644 man/man2/sigaltstack.2 create mode 100644 man/man2/signal.2 create mode 100644 man/man2/signalfd.2 create mode 100644 man/man2/signalfd4.2 create mode 100644 man/man2/sigpending.2 create mode 100644 man/man2/sigprocmask.2 create mode 100644 man/man2/sigreturn.2 create mode 100644 man/man2/sigsuspend.2 create mode 100644 man/man2/sigtimedwait.2 create mode 100644 man/man2/sigwaitinfo.2 create mode 100644 man/man2/socket.2 create mode 100644 man/man2/socketcall.2 create mode 100644 man/man2/socketpair.2 create mode 100644 man/man2/splice.2 create mode 100644 man/man2/spu_create.2 create mode 100644 man/man2/spu_run.2 create mode 100644 man/man2/ssetmask.2 create mode 100644 man/man2/stat.2 create mode 100644 man/man2/stat64.2 create mode 100644 man/man2/statfs.2 create mode 100644 man/man2/statfs64.2 create mode 100644 man/man2/statx.2 create mode 100644 man/man2/stime.2 create mode 100644 man/man2/stty.2 create mode 100644 man/man2/subpage_prot.2 create mode 100644 man/man2/swapoff.2 create mode 100644 man/man2/swapon.2 create mode 100644 man/man2/symlink.2 create mode 100644 man/man2/symlinkat.2 create mode 100644 man/man2/sync.2 create mode 100644 man/man2/sync_file_range.2 create mode 100644 man/man2/sync_file_range2.2 create mode 100644 man/man2/syncfs.2 create mode 100644 man/man2/syscall.2 create mode 100644 man/man2/syscalls.2 create mode 100644 man/man2/sysctl.2 create mode 100644 man/man2/sysfs.2 create mode 100644 man/man2/sysinfo.2 create mode 100644 man/man2/syslog.2 create mode 100644 man/man2/tee.2 create mode 100644 man/man2/tgkill.2 create mode 100644 man/man2/time.2 create mode 100644 man/man2/timer_create.2 create mode 100644 man/man2/timer_delete.2 create mode 100644 man/man2/timer_getoverrun.2 create mode 100644 man/man2/timer_gettime.2 create mode 100644 man/man2/timer_settime.2 create mode 100644 man/man2/timerfd_create.2 create mode 100644 man/man2/timerfd_gettime.2 create mode 100644 man/man2/timerfd_settime.2 create mode 100644 man/man2/times.2 create mode 100644 man/man2/tkill.2 create mode 100644 man/man2/truncate.2 create mode 100644 man/man2/truncate64.2 create mode 100644 man/man2/tuxcall.2 create mode 100644 man/man2/ugetrlimit.2 create mode 100644 man/man2/umask.2 create mode 100644 man/man2/umount.2 create mode 100644 man/man2/umount2.2 create mode 100644 man/man2/uname.2 create mode 100644 man/man2/unimplemented.2 create mode 100644 man/man2/unlink.2 create mode 100644 man/man2/unlinkat.2 create mode 100644 man/man2/unshare.2 create mode 100644 man/man2/uselib.2 create mode 100644 man/man2/userfaultfd.2 create mode 100644 man/man2/ustat.2 create mode 100644 man/man2/utime.2 create mode 100644 man/man2/utimensat.2 create mode 100644 man/man2/utimes.2 create mode 100644 man/man2/vfork.2 create mode 100644 man/man2/vhangup.2 create mode 100644 man/man2/vm86.2 create mode 100644 man/man2/vm86old.2 create mode 100644 man/man2/vmsplice.2 create mode 100644 man/man2/vserver.2 create mode 100644 man/man2/wait.2 create mode 100644 man/man2/wait3.2 create mode 100644 man/man2/wait4.2 create mode 100644 man/man2/waitid.2 create mode 100644 man/man2/waitpid.2 create mode 100644 man/man2/write.2 create mode 100644 man/man2/writev.2 create mode 100644 man/man2type/open_how.2type create mode 100644 man/man3/CIRCLEQ_EMPTY.3 create mode 100644 man/man3/CIRCLEQ_ENTRY.3 create mode 100644 man/man3/CIRCLEQ_FIRST.3 create mode 100644 man/man3/CIRCLEQ_FOREACH.3 create mode 100644 man/man3/CIRCLEQ_FOREACH_REVERSE.3 create mode 100644 man/man3/CIRCLEQ_HEAD.3 create mode 100644 man/man3/CIRCLEQ_HEAD_INITIALIZER.3 create mode 100644 man/man3/CIRCLEQ_INIT.3 create mode 100644 man/man3/CIRCLEQ_INSERT_AFTER.3 create mode 100644 man/man3/CIRCLEQ_INSERT_BEFORE.3 create mode 100644 man/man3/CIRCLEQ_INSERT_HEAD.3 create mode 100644 man/man3/CIRCLEQ_INSERT_TAIL.3 create mode 100644 man/man3/CIRCLEQ_LAST.3 create mode 100644 man/man3/CIRCLEQ_LOOP_NEXT.3 create mode 100644 man/man3/CIRCLEQ_LOOP_PREV.3 create mode 100644 man/man3/CIRCLEQ_NEXT.3 create mode 100644 man/man3/CIRCLEQ_PREV.3 create mode 100644 man/man3/CIRCLEQ_REMOVE.3 create mode 100644 man/man3/CMSG_ALIGN.3 create mode 100644 man/man3/CMSG_DATA.3 create mode 100644 man/man3/CMSG_FIRSTHDR.3 create mode 100644 man/man3/CMSG_LEN.3 create mode 100644 man/man3/CMSG_NXTHDR.3 create mode 100644 man/man3/CMSG_SPACE.3 create mode 100644 man/man3/CPU_ALLOC.3 create mode 100644 man/man3/CPU_ALLOC_SIZE.3 create mode 100644 man/man3/CPU_AND.3 create mode 100644 man/man3/CPU_AND_S.3 create mode 100644 man/man3/CPU_CLR.3 create mode 100644 man/man3/CPU_CLR_S.3 create mode 100644 man/man3/CPU_COUNT.3 create mode 100644 man/man3/CPU_COUNT_S.3 create mode 100644 man/man3/CPU_EQUAL.3 create mode 100644 man/man3/CPU_EQUAL_S.3 create mode 100644 man/man3/CPU_FREE.3 create mode 100644 man/man3/CPU_ISSET.3 create mode 100644 man/man3/CPU_ISSET_S.3 create mode 100644 man/man3/CPU_OR.3 create mode 100644 man/man3/CPU_OR_S.3 create mode 100644 man/man3/CPU_SET.3 create mode 100644 man/man3/CPU_SET_S.3 create mode 100644 man/man3/CPU_XOR.3 create mode 100644 man/man3/CPU_XOR_S.3 create mode 100644 man/man3/CPU_ZERO.3 create mode 100644 man/man3/CPU_ZERO_S.3 create mode 100644 man/man3/DES_FAILED.3 create mode 100644 man/man3/FD_CLR.3 create mode 100644 man/man3/FD_ISSET.3 create mode 100644 man/man3/FD_SET.3 create mode 100644 man/man3/FD_ZERO.3 create mode 100644 man/man3/HUGE_VAL.3 create mode 100644 man/man3/HUGE_VALF.3 create mode 100644 man/man3/HUGE_VALL.3 create mode 100644 man/man3/INFINITY.3 create mode 100644 man/man3/LIST_EMPTY.3 create mode 100644 man/man3/LIST_ENTRY.3 create mode 100644 man/man3/LIST_FIRST.3 create mode 100644 man/man3/LIST_FOREACH.3 create mode 100644 man/man3/LIST_HEAD.3 create mode 100644 man/man3/LIST_HEAD_INITIALIZER.3 create mode 100644 man/man3/LIST_INIT.3 create mode 100644 man/man3/LIST_INSERT_AFTER.3 create mode 100644 man/man3/LIST_INSERT_BEFORE.3 create mode 100644 man/man3/LIST_INSERT_HEAD.3 create mode 100644 man/man3/LIST_NEXT.3 create mode 100644 man/man3/LIST_REMOVE.3 create mode 100644 man/man3/MAX.3 create mode 100644 man/man3/MB_CUR_MAX.3 create mode 100644 man/man3/MB_LEN_MAX.3 create mode 100644 man/man3/MIN.3 create mode 100644 man/man3/NAN.3 create mode 100644 man/man3/SIMPLEQ_EMPTY.3 create mode 100644 man/man3/SIMPLEQ_ENTRY.3 create mode 100644 man/man3/SIMPLEQ_FIRST.3 create mode 100644 man/man3/SIMPLEQ_FOREACH.3 create mode 100644 man/man3/SIMPLEQ_HEAD.3 create mode 100644 man/man3/SIMPLEQ_HEAD_INITIALIZER.3 create mode 100644 man/man3/SIMPLEQ_INIT.3 create mode 100644 man/man3/SIMPLEQ_INSERT_AFTER.3 create mode 100644 man/man3/SIMPLEQ_INSERT_HEAD.3 create mode 100644 man/man3/SIMPLEQ_INSERT_TAIL.3 create mode 100644 man/man3/SIMPLEQ_NEXT.3 create mode 100644 man/man3/SIMPLEQ_REMOVE.3 create mode 100644 man/man3/SIMPLEQ_REMOVE_HEAD.3 create mode 100644 man/man3/SLIST_EMPTY.3 create mode 100644 man/man3/SLIST_ENTRY.3 create mode 100644 man/man3/SLIST_FIRST.3 create mode 100644 man/man3/SLIST_FOREACH.3 create mode 100644 man/man3/SLIST_HEAD.3 create mode 100644 man/man3/SLIST_HEAD_INITIALIZER.3 create mode 100644 man/man3/SLIST_INIT.3 create mode 100644 man/man3/SLIST_INSERT_AFTER.3 create mode 100644 man/man3/SLIST_INSERT_HEAD.3 create mode 100644 man/man3/SLIST_NEXT.3 create mode 100644 man/man3/SLIST_REMOVE.3 create mode 100644 man/man3/SLIST_REMOVE_HEAD.3 create mode 100644 man/man3/STAILQ_CONCAT.3 create mode 100644 man/man3/STAILQ_EMPTY.3 create mode 100644 man/man3/STAILQ_ENTRY.3 create mode 100644 man/man3/STAILQ_FIRST.3 create mode 100644 man/man3/STAILQ_FOREACH.3 create mode 100644 man/man3/STAILQ_HEAD.3 create mode 100644 man/man3/STAILQ_HEAD_INITIALIZER.3 create mode 100644 man/man3/STAILQ_INIT.3 create mode 100644 man/man3/STAILQ_INSERT_AFTER.3 create mode 100644 man/man3/STAILQ_INSERT_HEAD.3 create mode 100644 man/man3/STAILQ_INSERT_TAIL.3 create mode 100644 man/man3/STAILQ_NEXT.3 create mode 100644 man/man3/STAILQ_REMOVE.3 create mode 100644 man/man3/STAILQ_REMOVE_HEAD.3 create mode 100644 man/man3/S_ISBLK.3 create mode 100644 man/man3/S_ISCHR.3 create mode 100644 man/man3/S_ISDIR.3 create mode 100644 man/man3/S_ISFIFO.3 create mode 100644 man/man3/S_ISLNK.3 create mode 100644 man/man3/S_ISREG.3 create mode 100644 man/man3/S_ISSOCK.3 create mode 100644 man/man3/TAILQ_CONCAT.3 create mode 100644 man/man3/TAILQ_EMPTY.3 create mode 100644 man/man3/TAILQ_ENTRY.3 create mode 100644 man/man3/TAILQ_FIRST.3 create mode 100644 man/man3/TAILQ_FOREACH.3 create mode 100644 man/man3/TAILQ_FOREACH_REVERSE.3 create mode 100644 man/man3/TAILQ_HEAD.3 create mode 100644 man/man3/TAILQ_HEAD_INITIALIZER.3 create mode 100644 man/man3/TAILQ_INIT.3 create mode 100644 man/man3/TAILQ_INSERT_AFTER.3 create mode 100644 man/man3/TAILQ_INSERT_BEFORE.3 create mode 100644 man/man3/TAILQ_INSERT_HEAD.3 create mode 100644 man/man3/TAILQ_INSERT_TAIL.3 create mode 100644 man/man3/TAILQ_LAST.3 create mode 100644 man/man3/TAILQ_NEXT.3 create mode 100644 man/man3/TAILQ_PREV.3 create mode 100644 man/man3/TAILQ_REMOVE.3 create mode 100644 man/man3/TAILQ_SWAP.3 create mode 100644 man/man3/TIMESPEC_TO_TIMEVAL.3 create mode 100644 man/man3/TIMEVAL_TO_TIMESPEC.3 create mode 100644 man/man3/_Generic.3 create mode 100644 man/man3/_Static_assert.3 create mode 100644 man/man3/__after_morecore_hook.3 create mode 100644 man/man3/__fbufsize.3 create mode 100644 man/man3/__flbf.3 create mode 100644 man/man3/__fpending.3 create mode 100644 man/man3/__fpurge.3 create mode 100644 man/man3/__freadable.3 create mode 100644 man/man3/__freading.3 create mode 100644 man/man3/__free_hook.3 create mode 100644 man/man3/__fsetlocking.3 create mode 100644 man/man3/__fwritable.3 create mode 100644 man/man3/__fwriting.3 create mode 100644 man/man3/__malloc_hook.3 create mode 100644 man/man3/__malloc_initialize_hook.3 create mode 100644 man/man3/__memalign_hook.3 create mode 100644 man/man3/__ppc_get_timebase.3 create mode 100644 man/man3/__ppc_get_timebase_freq.3 create mode 100644 man/man3/__ppc_mdoio.3 create mode 100644 man/man3/__ppc_mdoom.3 create mode 100644 man/man3/__ppc_set_ppr_low.3 create mode 100644 man/man3/__ppc_set_ppr_med.3 create mode 100644 man/man3/__ppc_set_ppr_med_high.3 create mode 100644 man/man3/__ppc_set_ppr_med_low.3 create mode 100644 man/man3/__ppc_set_ppr_very_low.3 create mode 100644 man/man3/__ppc_yield.3 create mode 100644 man/man3/__realloc_hook.3 create mode 100644 man/man3/__setfpucw.3 create mode 100644 man/man3/_flushlbf.3 create mode 100644 man/man3/a64l.3 create mode 100644 man/man3/abort.3 create mode 100644 man/man3/abs.3 create mode 100644 man/man3/acos.3 create mode 100644 man/man3/acosf.3 create mode 100644 man/man3/acosh.3 create mode 100644 man/man3/acoshf.3 create mode 100644 man/man3/acoshl.3 create mode 100644 man/man3/acosl.3 create mode 100644 man/man3/addmntent.3 create mode 100644 man/man3/addseverity.3 create mode 100644 man/man3/adjtime.3 create mode 100644 man/man3/aio_cancel.3 create mode 100644 man/man3/aio_error.3 create mode 100644 man/man3/aio_fsync.3 create mode 100644 man/man3/aio_init.3 create mode 100644 man/man3/aio_read.3 create mode 100644 man/man3/aio_return.3 create mode 100644 man/man3/aio_suspend.3 create mode 100644 man/man3/aio_write.3 create mode 100644 man/man3/aligned_alloc.3 create mode 100644 man/man3/alloca.3 create mode 100644 man/man3/alphasort.3 create mode 100644 man/man3/arc4random.3 create mode 100644 man/man3/arc4random_buf.3 create mode 100644 man/man3/arc4random_uniform.3 create mode 100644 man/man3/argz.3 create mode 100644 man/man3/argz_add.3 create mode 100644 man/man3/argz_add_sep.3 create mode 100644 man/man3/argz_append.3 create mode 100644 man/man3/argz_count.3 create mode 100644 man/man3/argz_create.3 create mode 100644 man/man3/argz_create_sep.3 create mode 100644 man/man3/argz_delete.3 create mode 100644 man/man3/argz_extract.3 create mode 100644 man/man3/argz_insert.3 create mode 100644 man/man3/argz_next.3 create mode 100644 man/man3/argz_replace.3 create mode 100644 man/man3/argz_stringify.3 create mode 100644 man/man3/asctime.3 create mode 100644 man/man3/asctime_r.3 create mode 100644 man/man3/asin.3 create mode 100644 man/man3/asinf.3 create mode 100644 man/man3/asinh.3 create mode 100644 man/man3/asinhf.3 create mode 100644 man/man3/asinhl.3 create mode 100644 man/man3/asinl.3 create mode 100644 man/man3/asprintf.3 create mode 100644 man/man3/assert.3 create mode 100644 man/man3/assert_perror.3 create mode 100644 man/man3/atan.3 create mode 100644 man/man3/atan2.3 create mode 100644 man/man3/atan2f.3 create mode 100644 man/man3/atan2l.3 create mode 100644 man/man3/atanf.3 create mode 100644 man/man3/atanh.3 create mode 100644 man/man3/atanhf.3 create mode 100644 man/man3/atanhl.3 create mode 100644 man/man3/atanl.3 create mode 100644 man/man3/atexit.3 create mode 100644 man/man3/atof.3 create mode 100644 man/man3/atoi.3 create mode 100644 man/man3/atol.3 create mode 100644 man/man3/atoll.3 create mode 100644 man/man3/atoq.3 create mode 100644 man/man3/auth_destroy.3 create mode 100644 man/man3/authnone_create.3 create mode 100644 man/man3/authunix_create.3 create mode 100644 man/man3/authunix_create_default.3 create mode 100644 man/man3/backtrace.3 create mode 100644 man/man3/backtrace_symbols.3 create mode 100644 man/man3/backtrace_symbols_fd.3 create mode 100644 man/man3/basename.3 create mode 100644 man/man3/bcmp.3 create mode 100644 man/man3/bcopy.3 create mode 100644 man/man3/be16toh.3 create mode 100644 man/man3/be32toh.3 create mode 100644 man/man3/be64toh.3 create mode 100644 man/man3/bindresvport.3 create mode 100644 man/man3/bsd_signal.3 create mode 100644 man/man3/bsearch.3 create mode 100644 man/man3/bstring.3 create mode 100644 man/man3/bswap.3 create mode 100644 man/man3/bswap_16.3 create mode 100644 man/man3/bswap_32.3 create mode 100644 man/man3/bswap_64.3 create mode 100644 man/man3/btowc.3 create mode 100644 man/man3/btree.3 create mode 100644 man/man3/byteorder.3 create mode 100644 man/man3/bzero.3 create mode 100644 man/man3/cabs.3 create mode 100644 man/man3/cabsf.3 create mode 100644 man/man3/cabsl.3 create mode 100644 man/man3/cacos.3 create mode 100644 man/man3/cacosf.3 create mode 100644 man/man3/cacosh.3 create mode 100644 man/man3/cacoshf.3 create mode 100644 man/man3/cacoshl.3 create mode 100644 man/man3/cacosl.3 create mode 100644 man/man3/calloc.3 create mode 100644 man/man3/callrpc.3 create mode 100644 man/man3/canonicalize_file_name.3 create mode 100644 man/man3/carg.3 create mode 100644 man/man3/cargf.3 create mode 100644 man/man3/cargl.3 create mode 100644 man/man3/casin.3 create mode 100644 man/man3/casinf.3 create mode 100644 man/man3/casinh.3 create mode 100644 man/man3/casinhf.3 create mode 100644 man/man3/casinhl.3 create mode 100644 man/man3/casinl.3 create mode 100644 man/man3/catan.3 create mode 100644 man/man3/catanf.3 create mode 100644 man/man3/catanh.3 create mode 100644 man/man3/catanhf.3 create mode 100644 man/man3/catanhl.3 create mode 100644 man/man3/catanl.3 create mode 100644 man/man3/catclose.3 create mode 100644 man/man3/catgets.3 create mode 100644 man/man3/catopen.3 create mode 100644 man/man3/cbc_crypt.3 create mode 100644 man/man3/cbrt.3 create mode 100644 man/man3/cbrtf.3 create mode 100644 man/man3/cbrtl.3 create mode 100644 man/man3/ccos.3 create mode 100644 man/man3/ccosf.3 create mode 100644 man/man3/ccosh.3 create mode 100644 man/man3/ccoshf.3 create mode 100644 man/man3/ccoshl.3 create mode 100644 man/man3/ccosl.3 create mode 100644 man/man3/ceil.3 create mode 100644 man/man3/ceilf.3 create mode 100644 man/man3/ceill.3 create mode 100644 man/man3/cexp.3 create mode 100644 man/man3/cexp2.3 create mode 100644 man/man3/cexp2f.3 create mode 100644 man/man3/cexp2l.3 create mode 100644 man/man3/cexpf.3 create mode 100644 man/man3/cexpl.3 create mode 100644 man/man3/cfgetispeed.3 create mode 100644 man/man3/cfgetospeed.3 create mode 100644 man/man3/cfmakeraw.3 create mode 100644 man/man3/cfree.3 create mode 100644 man/man3/cfsetispeed.3 create mode 100644 man/man3/cfsetospeed.3 create mode 100644 man/man3/cfsetspeed.3 create mode 100644 man/man3/cimag.3 create mode 100644 man/man3/cimagf.3 create mode 100644 man/man3/cimagl.3 create mode 100644 man/man3/circleq.3 create mode 100644 man/man3/clearenv.3 create mode 100644 man/man3/clearerr.3 create mode 100644 man/man3/clearerr_unlocked.3 create mode 100644 man/man3/clnt_broadcast.3 create mode 100644 man/man3/clnt_call.3 create mode 100644 man/man3/clnt_control.3 create mode 100644 man/man3/clnt_create.3 create mode 100644 man/man3/clnt_destroy.3 create mode 100644 man/man3/clnt_freeres.3 create mode 100644 man/man3/clnt_geterr.3 create mode 100644 man/man3/clnt_pcreateerror.3 create mode 100644 man/man3/clnt_perrno.3 create mode 100644 man/man3/clnt_perror.3 create mode 100644 man/man3/clnt_spcreateerror.3 create mode 100644 man/man3/clnt_sperrno.3 create mode 100644 man/man3/clnt_sperror.3 create mode 100644 man/man3/clntraw_create.3 create mode 100644 man/man3/clnttcp_create.3 create mode 100644 man/man3/clntudp_bufcreate.3 create mode 100644 man/man3/clntudp_create.3 create mode 100644 man/man3/clock.3 create mode 100644 man/man3/clock_getcpuclockid.3 create mode 100644 man/man3/clog.3 create mode 100644 man/man3/clog10.3 create mode 100644 man/man3/clog10f.3 create mode 100644 man/man3/clog10l.3 create mode 100644 man/man3/clog2.3 create mode 100644 man/man3/clog2f.3 create mode 100644 man/man3/clog2l.3 create mode 100644 man/man3/clogf.3 create mode 100644 man/man3/clogl.3 create mode 100644 man/man3/closedir.3 create mode 100644 man/man3/closelog.3 create mode 100644 man/man3/cmsg.3 create mode 100644 man/man3/confstr.3 create mode 100644 man/man3/conj.3 create mode 100644 man/man3/conjf.3 create mode 100644 man/man3/conjl.3 create mode 100644 man/man3/copysign.3 create mode 100644 man/man3/copysignf.3 create mode 100644 man/man3/copysignl.3 create mode 100644 man/man3/cos.3 create mode 100644 man/man3/cosf.3 create mode 100644 man/man3/cosh.3 create mode 100644 man/man3/coshf.3 create mode 100644 man/man3/coshl.3 create mode 100644 man/man3/cosl.3 create mode 100644 man/man3/cpow.3 create mode 100644 man/man3/cpowf.3 create mode 100644 man/man3/cpowl.3 create mode 100644 man/man3/cproj.3 create mode 100644 man/man3/cprojf.3 create mode 100644 man/man3/cprojl.3 create mode 100644 man/man3/creal.3 create mode 100644 man/man3/crealf.3 create mode 100644 man/man3/creall.3 create mode 100644 man/man3/crypt.3 create mode 100644 man/man3/crypt_r.3 create mode 100644 man/man3/csin.3 create mode 100644 man/man3/csinf.3 create mode 100644 man/man3/csinh.3 create mode 100644 man/man3/csinhf.3 create mode 100644 man/man3/csinhl.3 create mode 100644 man/man3/csinl.3 create mode 100644 man/man3/csqrt.3 create mode 100644 man/man3/csqrtf.3 create mode 100644 man/man3/csqrtl.3 create mode 100644 man/man3/ctan.3 create mode 100644 man/man3/ctanf.3 create mode 100644 man/man3/ctanh.3 create mode 100644 man/man3/ctanhf.3 create mode 100644 man/man3/ctanhl.3 create mode 100644 man/man3/ctanl.3 create mode 100644 man/man3/ctermid.3 create mode 100644 man/man3/ctime.3 create mode 100644 man/man3/ctime_r.3 create mode 100644 man/man3/cuserid.3 create mode 100644 man/man3/daemon.3 create mode 100644 man/man3/daylight.3 create mode 100644 man/man3/db.3 create mode 100644 man/man3/dbopen.3 create mode 100644 man/man3/des_crypt.3 create mode 100644 man/man3/des_setparity.3 create mode 100644 man/man3/difftime.3 create mode 100644 man/man3/dirfd.3 create mode 100644 man/man3/dirname.3 create mode 100644 man/man3/div.3 create mode 100644 man/man3/dl_iterate_phdr.3 create mode 100644 man/man3/dladdr.3 create mode 100644 man/man3/dladdr1.3 create mode 100644 man/man3/dlclose.3 create mode 100644 man/man3/dlerror.3 create mode 100644 man/man3/dlinfo.3 create mode 100644 man/man3/dlmopen.3 create mode 100644 man/man3/dlopen.3 create mode 100644 man/man3/dlsym.3 create mode 100644 man/man3/dlvsym.3 create mode 100644 man/man3/dn_comp.3 create mode 100644 man/man3/dn_expand.3 create mode 100644 man/man3/dprintf.3 create mode 100644 man/man3/drand48.3 create mode 100644 man/man3/drand48_r.3 create mode 100644 man/man3/drem.3 create mode 100644 man/man3/dremf.3 create mode 100644 man/man3/dreml.3 create mode 100644 man/man3/duplocale.3 create mode 100644 man/man3/dysize.3 create mode 100644 man/man3/eaccess.3 create mode 100644 man/man3/ecb_crypt.3 create mode 100644 man/man3/ecvt.3 create mode 100644 man/man3/ecvt_r.3 create mode 100644 man/man3/edata.3 create mode 100644 man/man3/encrypt.3 create mode 100644 man/man3/encrypt_r.3 create mode 100644 man/man3/end.3 create mode 100644 man/man3/endaliasent.3 create mode 100644 man/man3/endfsent.3 create mode 100644 man/man3/endgrent.3 create mode 100644 man/man3/endhostent.3 create mode 100644 man/man3/endian.3 create mode 100644 man/man3/endmntent.3 create mode 100644 man/man3/endnetent.3 create mode 100644 man/man3/endnetgrent.3 create mode 100644 man/man3/endprotoent.3 create mode 100644 man/man3/endpwent.3 create mode 100644 man/man3/endrpcent.3 create mode 100644 man/man3/endservent.3 create mode 100644 man/man3/endspent.3 create mode 100644 man/man3/endttyent.3 create mode 100644 man/man3/endusershell.3 create mode 100644 man/man3/endutent.3 create mode 100644 man/man3/endutxent.3 create mode 100644 man/man3/envz.3 create mode 100644 man/man3/envz_add.3 create mode 100644 man/man3/envz_entry.3 create mode 100644 man/man3/envz_get.3 create mode 100644 man/man3/envz_merge.3 create mode 100644 man/man3/envz_remove.3 create mode 100644 man/man3/envz_strip.3 create mode 100644 man/man3/erand48.3 create mode 100644 man/man3/erand48_r.3 create mode 100644 man/man3/erf.3 create mode 100644 man/man3/erfc.3 create mode 100644 man/man3/erfcf.3 create mode 100644 man/man3/erfcl.3 create mode 100644 man/man3/erff.3 create mode 100644 man/man3/erfl.3 create mode 100644 man/man3/err.3 create mode 100644 man/man3/errno.3 create mode 100644 man/man3/error.3 create mode 100644 man/man3/error_at_line.3 create mode 100644 man/man3/error_message_count.3 create mode 100644 man/man3/error_one_per_line.3 create mode 100644 man/man3/error_print_progname.3 create mode 100644 man/man3/errx.3 create mode 100644 man/man3/etext.3 create mode 100644 man/man3/ether_aton.3 create mode 100644 man/man3/ether_aton_r.3 create mode 100644 man/man3/ether_hostton.3 create mode 100644 man/man3/ether_line.3 create mode 100644 man/man3/ether_ntoa.3 create mode 100644 man/man3/ether_ntoa_r.3 create mode 100644 man/man3/ether_ntohost.3 create mode 100644 man/man3/euidaccess.3 create mode 100644 man/man3/eventfd_read.3 create mode 100644 man/man3/eventfd_write.3 create mode 100644 man/man3/exec.3 create mode 100644 man/man3/execl.3 create mode 100644 man/man3/execle.3 create mode 100644 man/man3/execlp.3 create mode 100644 man/man3/execv.3 create mode 100644 man/man3/execvp.3 create mode 100644 man/man3/execvpe.3 create mode 100644 man/man3/exit.3 create mode 100644 man/man3/exp.3 create mode 100644 man/man3/exp10.3 create mode 100644 man/man3/exp10f.3 create mode 100644 man/man3/exp10l.3 create mode 100644 man/man3/exp2.3 create mode 100644 man/man3/exp2f.3 create mode 100644 man/man3/exp2l.3 create mode 100644 man/man3/expf.3 create mode 100644 man/man3/expl.3 create mode 100644 man/man3/explicit_bzero.3 create mode 100644 man/man3/expm1.3 create mode 100644 man/man3/expm1f.3 create mode 100644 man/man3/expm1l.3 create mode 100644 man/man3/fabs.3 create mode 100644 man/man3/fabsf.3 create mode 100644 man/man3/fabsl.3 create mode 100644 man/man3/fclose.3 create mode 100644 man/man3/fcloseall.3 create mode 100644 man/man3/fcvt.3 create mode 100644 man/man3/fcvt_r.3 create mode 100644 man/man3/fdim.3 create mode 100644 man/man3/fdimf.3 create mode 100644 man/man3/fdiml.3 create mode 100644 man/man3/fdopen.3 create mode 100644 man/man3/fdopendir.3 create mode 100644 man/man3/feclearexcept.3 create mode 100644 man/man3/fedisableexcept.3 create mode 100644 man/man3/feenableexcept.3 create mode 100644 man/man3/fegetenv.3 create mode 100644 man/man3/fegetexcept.3 create mode 100644 man/man3/fegetexceptflag.3 create mode 100644 man/man3/fegetround.3 create mode 100644 man/man3/feholdexcept.3 create mode 100644 man/man3/fenv.3 create mode 100644 man/man3/feof.3 create mode 100644 man/man3/feof_unlocked.3 create mode 100644 man/man3/feraiseexcept.3 create mode 100644 man/man3/ferror.3 create mode 100644 man/man3/ferror_unlocked.3 create mode 100644 man/man3/fesetenv.3 create mode 100644 man/man3/fesetexceptflag.3 create mode 100644 man/man3/fesetround.3 create mode 100644 man/man3/fetestexcept.3 create mode 100644 man/man3/feupdateenv.3 create mode 100644 man/man3/fexecve.3 create mode 100644 man/man3/fflush.3 create mode 100644 man/man3/fflush_unlocked.3 create mode 100644 man/man3/ffs.3 create mode 100644 man/man3/ffsl.3 create mode 100644 man/man3/ffsll.3 create mode 100644 man/man3/fgetc.3 create mode 100644 man/man3/fgetc_unlocked.3 create mode 100644 man/man3/fgetgrent.3 create mode 100644 man/man3/fgetgrent_r.3 create mode 100644 man/man3/fgetpos.3 create mode 100644 man/man3/fgetpwent.3 create mode 100644 man/man3/fgetpwent_r.3 create mode 100644 man/man3/fgets.3 create mode 100644 man/man3/fgets_unlocked.3 create mode 100644 man/man3/fgetspent.3 create mode 100644 man/man3/fgetspent_r.3 create mode 100644 man/man3/fgetwc.3 create mode 100644 man/man3/fgetwc_unlocked.3 create mode 100644 man/man3/fgetws.3 create mode 100644 man/man3/fgetws_unlocked.3 create mode 100644 man/man3/fileno.3 create mode 100644 man/man3/fileno_unlocked.3 create mode 100644 man/man3/finite.3 create mode 100644 man/man3/finitef.3 create mode 100644 man/man3/finitel.3 create mode 100644 man/man3/flockfile.3 create mode 100644 man/man3/floor.3 create mode 100644 man/man3/floorf.3 create mode 100644 man/man3/floorl.3 create mode 100644 man/man3/fma.3 create mode 100644 man/man3/fmaf.3 create mode 100644 man/man3/fmal.3 create mode 100644 man/man3/fmax.3 create mode 100644 man/man3/fmaxf.3 create mode 100644 man/man3/fmaxl.3 create mode 100644 man/man3/fmemopen.3 create mode 100644 man/man3/fmin.3 create mode 100644 man/man3/fminf.3 create mode 100644 man/man3/fminl.3 create mode 100644 man/man3/fmod.3 create mode 100644 man/man3/fmodf.3 create mode 100644 man/man3/fmodl.3 create mode 100644 man/man3/fmtmsg.3 create mode 100644 man/man3/fnmatch.3 create mode 100644 man/man3/fopen.3 create mode 100644 man/man3/fopencookie.3 create mode 100644 man/man3/forkpty.3 create mode 100644 man/man3/fpathconf.3 create mode 100644 man/man3/fpclassify.3 create mode 100644 man/man3/fprintf.3 create mode 100644 man/man3/fpurge.3 create mode 100644 man/man3/fputc.3 create mode 100644 man/man3/fputc_unlocked.3 create mode 100644 man/man3/fputs.3 create mode 100644 man/man3/fputs_unlocked.3 create mode 100644 man/man3/fputwc.3 create mode 100644 man/man3/fputwc_unlocked.3 create mode 100644 man/man3/fputws.3 create mode 100644 man/man3/fputws_unlocked.3 create mode 100644 man/man3/fread.3 create mode 100644 man/man3/fread_unlocked.3 create mode 100644 man/man3/free.3 create mode 100644 man/man3/freeaddrinfo.3 create mode 100644 man/man3/freehostent.3 create mode 100644 man/man3/freeifaddrs.3 create mode 100644 man/man3/freelocale.3 create mode 100644 man/man3/freopen.3 create mode 100644 man/man3/frexp.3 create mode 100644 man/man3/frexpf.3 create mode 100644 man/man3/frexpl.3 create mode 100644 man/man3/fscanf.3 create mode 100644 man/man3/fseek.3 create mode 100644 man/man3/fseeko.3 create mode 100644 man/man3/fsetpos.3 create mode 100644 man/man3/fstatvfs.3 create mode 100644 man/man3/ftell.3 create mode 100644 man/man3/ftello.3 create mode 100644 man/man3/ftime.3 create mode 100644 man/man3/ftok.3 create mode 100644 man/man3/ftrylockfile.3 create mode 100644 man/man3/fts.3 create mode 100644 man/man3/fts_children.3 create mode 100644 man/man3/fts_close.3 create mode 100644 man/man3/fts_open.3 create mode 100644 man/man3/fts_read.3 create mode 100644 man/man3/fts_set.3 create mode 100644 man/man3/ftw.3 create mode 100644 man/man3/funlockfile.3 create mode 100644 man/man3/futimens.3 create mode 100644 man/man3/futimes.3 create mode 100644 man/man3/fwide.3 create mode 100644 man/man3/fwprintf.3 create mode 100644 man/man3/fwrite.3 create mode 100644 man/man3/fwrite_unlocked.3 create mode 100644 man/man3/gai_cancel.3 create mode 100644 man/man3/gai_error.3 create mode 100644 man/man3/gai_strerror.3 create mode 100644 man/man3/gai_suspend.3 create mode 100644 man/man3/gamma.3 create mode 100644 man/man3/gammaf.3 create mode 100644 man/man3/gammal.3 create mode 100644 man/man3/gcvt.3 create mode 100644 man/man3/get_avphys_pages.3 create mode 100644 man/man3/get_current_dir_name.3 create mode 100644 man/man3/get_myaddress.3 create mode 100644 man/man3/get_nprocs.3 create mode 100644 man/man3/get_nprocs_conf.3 create mode 100644 man/man3/get_phys_pages.3 create mode 100644 man/man3/getaddrinfo.3 create mode 100644 man/man3/getaddrinfo_a.3 create mode 100644 man/man3/getaliasbyname.3 create mode 100644 man/man3/getaliasbyname_r.3 create mode 100644 man/man3/getaliasent.3 create mode 100644 man/man3/getaliasent_r.3 create mode 100644 man/man3/getauxval.3 create mode 100644 man/man3/getc.3 create mode 100644 man/man3/getc_unlocked.3 create mode 100644 man/man3/getchar.3 create mode 100644 man/man3/getchar_unlocked.3 create mode 100644 man/man3/getcontext.3 create mode 100644 man/man3/getcwd.3 create mode 100644 man/man3/getdate.3 create mode 100644 man/man3/getdate_err.3 create mode 100644 man/man3/getdate_r.3 create mode 100644 man/man3/getdelim.3 create mode 100644 man/man3/getdirentries.3 create mode 100644 man/man3/getdtablesize.3 create mode 100644 man/man3/getentropy.3 create mode 100644 man/man3/getenv.3 create mode 100644 man/man3/getfsent.3 create mode 100644 man/man3/getfsfile.3 create mode 100644 man/man3/getfsspec.3 create mode 100644 man/man3/getgrent.3 create mode 100644 man/man3/getgrent_r.3 create mode 100644 man/man3/getgrgid.3 create mode 100644 man/man3/getgrgid_r.3 create mode 100644 man/man3/getgrnam.3 create mode 100644 man/man3/getgrnam_r.3 create mode 100644 man/man3/getgrouplist.3 create mode 100644 man/man3/gethostbyaddr.3 create mode 100644 man/man3/gethostbyaddr_r.3 create mode 100644 man/man3/gethostbyname.3 create mode 100644 man/man3/gethostbyname2.3 create mode 100644 man/man3/gethostbyname2_r.3 create mode 100644 man/man3/gethostbyname_r.3 create mode 100644 man/man3/gethostent.3 create mode 100644 man/man3/gethostent_r.3 create mode 100644 man/man3/gethostid.3 create mode 100644 man/man3/getifaddrs.3 create mode 100644 man/man3/getipnodebyaddr.3 create mode 100644 man/man3/getipnodebyname.3 create mode 100644 man/man3/getline.3 create mode 100644 man/man3/getloadavg.3 create mode 100644 man/man3/getlogin.3 create mode 100644 man/man3/getlogin_r.3 create mode 100644 man/man3/getmntent.3 create mode 100644 man/man3/getmntent_r.3 create mode 100644 man/man3/getnameinfo.3 create mode 100644 man/man3/getnetbyaddr.3 create mode 100644 man/man3/getnetbyaddr_r.3 create mode 100644 man/man3/getnetbyname.3 create mode 100644 man/man3/getnetbyname_r.3 create mode 100644 man/man3/getnetent.3 create mode 100644 man/man3/getnetent_r.3 create mode 100644 man/man3/getnetgrent.3 create mode 100644 man/man3/getnetgrent_r.3 create mode 100644 man/man3/getopt.3 create mode 100644 man/man3/getopt_long.3 create mode 100644 man/man3/getopt_long_only.3 create mode 100644 man/man3/getpass.3 create mode 100644 man/man3/getprotobyname.3 create mode 100644 man/man3/getprotobyname_r.3 create mode 100644 man/man3/getprotobynumber.3 create mode 100644 man/man3/getprotobynumber_r.3 create mode 100644 man/man3/getprotoent.3 create mode 100644 man/man3/getprotoent_r.3 create mode 100644 man/man3/getpt.3 create mode 100644 man/man3/getpw.3 create mode 100644 man/man3/getpwent.3 create mode 100644 man/man3/getpwent_r.3 create mode 100644 man/man3/getpwnam.3 create mode 100644 man/man3/getpwnam_r.3 create mode 100644 man/man3/getpwuid.3 create mode 100644 man/man3/getpwuid_r.3 create mode 100644 man/man3/getrpcbyname.3 create mode 100644 man/man3/getrpcbyname_r.3 create mode 100644 man/man3/getrpcbynumber.3 create mode 100644 man/man3/getrpcbynumber_r.3 create mode 100644 man/man3/getrpcent.3 create mode 100644 man/man3/getrpcent_r.3 create mode 100644 man/man3/getrpcport.3 create mode 100644 man/man3/gets.3 create mode 100644 man/man3/getservbyname.3 create mode 100644 man/man3/getservbyname_r.3 create mode 100644 man/man3/getservbyport.3 create mode 100644 man/man3/getservbyport_r.3 create mode 100644 man/man3/getservent.3 create mode 100644 man/man3/getservent_r.3 create mode 100644 man/man3/getspent.3 create mode 100644 man/man3/getspent_r.3 create mode 100644 man/man3/getspnam.3 create mode 100644 man/man3/getspnam_r.3 create mode 100644 man/man3/getsubopt.3 create mode 100644 man/man3/getttyent.3 create mode 100644 man/man3/getttynam.3 create mode 100644 man/man3/getusershell.3 create mode 100644 man/man3/getutent.3 create mode 100644 man/man3/getutent_r.3 create mode 100644 man/man3/getutid.3 create mode 100644 man/man3/getutid_r.3 create mode 100644 man/man3/getutline.3 create mode 100644 man/man3/getutline_r.3 create mode 100644 man/man3/getutmp.3 create mode 100644 man/man3/getutmpx.3 create mode 100644 man/man3/getutxent.3 create mode 100644 man/man3/getutxid.3 create mode 100644 man/man3/getutxline.3 create mode 100644 man/man3/getw.3 create mode 100644 man/man3/getwc.3 create mode 100644 man/man3/getwc_unlocked.3 create mode 100644 man/man3/getwchar.3 create mode 100644 man/man3/getwchar_unlocked.3 create mode 100644 man/man3/getwd.3 create mode 100644 man/man3/glob.3 create mode 100644 man/man3/globfree.3 create mode 100644 man/man3/gmtime.3 create mode 100644 man/man3/gmtime_r.3 create mode 100644 man/man3/gnu_dev_major.3 create mode 100644 man/man3/gnu_dev_makedev.3 create mode 100644 man/man3/gnu_dev_minor.3 create mode 100644 man/man3/gnu_get_libc_release.3 create mode 100644 man/man3/gnu_get_libc_version.3 create mode 100644 man/man3/grantpt.3 create mode 100644 man/man3/group_member.3 create mode 100644 man/man3/gsignal.3 create mode 100644 man/man3/h_errno.3 create mode 100644 man/man3/hash.3 create mode 100644 man/man3/hasmntopt.3 create mode 100644 man/man3/hcreate.3 create mode 100644 man/man3/hcreate_r.3 create mode 100644 man/man3/hdestroy.3 create mode 100644 man/man3/hdestroy_r.3 create mode 100644 man/man3/herror.3 create mode 100644 man/man3/hsearch.3 create mode 100644 man/man3/hsearch_r.3 create mode 100644 man/man3/hstrerror.3 create mode 100644 man/man3/htobe16.3 create mode 100644 man/man3/htobe32.3 create mode 100644 man/man3/htobe64.3 create mode 100644 man/man3/htole16.3 create mode 100644 man/man3/htole32.3 create mode 100644 man/man3/htole64.3 create mode 100644 man/man3/htonl.3 create mode 100644 man/man3/htons.3 create mode 100644 man/man3/hypot.3 create mode 100644 man/man3/hypotf.3 create mode 100644 man/man3/hypotl.3 create mode 100644 man/man3/iconv.3 create mode 100644 man/man3/iconv_close.3 create mode 100644 man/man3/iconv_open.3 create mode 100644 man/man3/if_freenameindex.3 create mode 100644 man/man3/if_indextoname.3 create mode 100644 man/man3/if_nameindex.3 create mode 100644 man/man3/if_nametoindex.3 create mode 100644 man/man3/ilogb.3 create mode 100644 man/man3/ilogbf.3 create mode 100644 man/man3/ilogbl.3 create mode 100644 man/man3/imaxabs.3 create mode 100644 man/man3/imaxdiv.3 create mode 100644 man/man3/index.3 create mode 100644 man/man3/inet.3 create mode 100644 man/man3/inet_addr.3 create mode 100644 man/man3/inet_aton.3 create mode 100644 man/man3/inet_lnaof.3 create mode 100644 man/man3/inet_makeaddr.3 create mode 100644 man/man3/inet_net_ntop.3 create mode 100644 man/man3/inet_net_pton.3 create mode 100644 man/man3/inet_netof.3 create mode 100644 man/man3/inet_network.3 create mode 100644 man/man3/inet_ntoa.3 create mode 100644 man/man3/inet_ntop.3 create mode 100644 man/man3/inet_pton.3 create mode 100644 man/man3/initgroups.3 create mode 100644 man/man3/initstate.3 create mode 100644 man/man3/initstate_r.3 create mode 100644 man/man3/innetgr.3 create mode 100644 man/man3/insque.3 create mode 100644 man/man3/intro.3 create mode 100644 man/man3/iruserok.3 create mode 100644 man/man3/iruserok_af.3 create mode 100644 man/man3/isalnum.3 create mode 100644 man/man3/isalnum_l.3 create mode 100644 man/man3/isalpha.3 create mode 100644 man/man3/isalpha_l.3 create mode 100644 man/man3/isascii.3 create mode 100644 man/man3/isascii_l.3 create mode 100644 man/man3/isatty.3 create mode 100644 man/man3/isblank.3 create mode 100644 man/man3/isblank_l.3 create mode 100644 man/man3/iscntrl.3 create mode 100644 man/man3/iscntrl_l.3 create mode 100644 man/man3/isdigit.3 create mode 100644 man/man3/isdigit_l.3 create mode 100644 man/man3/isfdtype.3 create mode 100644 man/man3/isfinite.3 create mode 100644 man/man3/isgraph.3 create mode 100644 man/man3/isgraph_l.3 create mode 100644 man/man3/isgreater.3 create mode 100644 man/man3/isgreaterequal.3 create mode 100644 man/man3/isinf.3 create mode 100644 man/man3/isinff.3 create mode 100644 man/man3/isinfl.3 create mode 100644 man/man3/isless.3 create mode 100644 man/man3/islessequal.3 create mode 100644 man/man3/islessgreater.3 create mode 100644 man/man3/islower.3 create mode 100644 man/man3/islower_l.3 create mode 100644 man/man3/isnan.3 create mode 100644 man/man3/isnanf.3 create mode 100644 man/man3/isnanl.3 create mode 100644 man/man3/isnormal.3 create mode 100644 man/man3/isprint.3 create mode 100644 man/man3/isprint_l.3 create mode 100644 man/man3/ispunct.3 create mode 100644 man/man3/ispunct_l.3 create mode 100644 man/man3/isspace.3 create mode 100644 man/man3/isspace_l.3 create mode 100644 man/man3/isunordered.3 create mode 100644 man/man3/isupper.3 create mode 100644 man/man3/isupper_l.3 create mode 100644 man/man3/iswalnum.3 create mode 100644 man/man3/iswalpha.3 create mode 100644 man/man3/iswblank.3 create mode 100644 man/man3/iswcntrl.3 create mode 100644 man/man3/iswctype.3 create mode 100644 man/man3/iswdigit.3 create mode 100644 man/man3/iswgraph.3 create mode 100644 man/man3/iswlower.3 create mode 100644 man/man3/iswprint.3 create mode 100644 man/man3/iswpunct.3 create mode 100644 man/man3/iswspace.3 create mode 100644 man/man3/iswupper.3 create mode 100644 man/man3/iswxdigit.3 create mode 100644 man/man3/isxdigit.3 create mode 100644 man/man3/isxdigit_l.3 create mode 100644 man/man3/j0.3 create mode 100644 man/man3/j0f.3 create mode 100644 man/man3/j0l.3 create mode 100644 man/man3/j1.3 create mode 100644 man/man3/j1f.3 create mode 100644 man/man3/j1l.3 create mode 100644 man/man3/jn.3 create mode 100644 man/man3/jnf.3 create mode 100644 man/man3/jnl.3 create mode 100644 man/man3/jrand48.3 create mode 100644 man/man3/jrand48_r.3 create mode 100644 man/man3/key_decryptsession.3 create mode 100644 man/man3/key_encryptsession.3 create mode 100644 man/man3/key_gendes.3 create mode 100644 man/man3/key_secretkey_is_set.3 create mode 100644 man/man3/key_setsecret.3 create mode 100644 man/man3/killpg.3 create mode 100644 man/man3/klogctl.3 create mode 100644 man/man3/l64a.3 create mode 100644 man/man3/labs.3 create mode 100644 man/man3/lckpwdf.3 create mode 100644 man/man3/lcong48.3 create mode 100644 man/man3/lcong48_r.3 create mode 100644 man/man3/ldexp.3 create mode 100644 man/man3/ldexpf.3 create mode 100644 man/man3/ldexpl.3 create mode 100644 man/man3/ldiv.3 create mode 100644 man/man3/le16toh.3 create mode 100644 man/man3/le32toh.3 create mode 100644 man/man3/le64toh.3 create mode 100644 man/man3/lfind.3 create mode 100644 man/man3/lgamma.3 create mode 100644 man/man3/lgamma_r.3 create mode 100644 man/man3/lgammaf.3 create mode 100644 man/man3/lgammaf_r.3 create mode 100644 man/man3/lgammal.3 create mode 100644 man/man3/lgammal_r.3 create mode 100644 man/man3/lio_listio.3 create mode 100644 man/man3/list.3 create mode 100644 man/man3/llabs.3 create mode 100644 man/man3/lldiv.3 create mode 100644 man/man3/llrint.3 create mode 100644 man/man3/llrintf.3 create mode 100644 man/man3/llrintl.3 create mode 100644 man/man3/llround.3 create mode 100644 man/man3/llroundf.3 create mode 100644 man/man3/llroundl.3 create mode 100644 man/man3/localeconv.3 create mode 100644 man/man3/localtime.3 create mode 100644 man/man3/localtime_r.3 create mode 100644 man/man3/lockf.3 create mode 100644 man/man3/log.3 create mode 100644 man/man3/log10.3 create mode 100644 man/man3/log10f.3 create mode 100644 man/man3/log10l.3 create mode 100644 man/man3/log1p.3 create mode 100644 man/man3/log1pf.3 create mode 100644 man/man3/log1pl.3 create mode 100644 man/man3/log2.3 create mode 100644 man/man3/log2f.3 create mode 100644 man/man3/log2l.3 create mode 100644 man/man3/logb.3 create mode 100644 man/man3/logbf.3 create mode 100644 man/man3/logbl.3 create mode 100644 man/man3/logf.3 create mode 100644 man/man3/login.3 create mode 100644 man/man3/login_tty.3 create mode 100644 man/man3/logl.3 create mode 100644 man/man3/logout.3 create mode 100644 man/man3/logwtmp.3 create mode 100644 man/man3/longjmp.3 create mode 100644 man/man3/lrand48.3 create mode 100644 man/man3/lrand48_r.3 create mode 100644 man/man3/lrint.3 create mode 100644 man/man3/lrintf.3 create mode 100644 man/man3/lrintl.3 create mode 100644 man/man3/lround.3 create mode 100644 man/man3/lroundf.3 create mode 100644 man/man3/lroundl.3 create mode 100644 man/man3/lsearch.3 create mode 100644 man/man3/lseek64.3 create mode 100644 man/man3/lutimes.3 create mode 100644 man/man3/major.3 create mode 100644 man/man3/makecontext.3 create mode 100644 man/man3/makedev.3 create mode 100644 man/man3/mallinfo.3 create mode 100644 man/man3/mallinfo2.3 create mode 100644 man/man3/malloc.3 create mode 100644 man/man3/malloc_get_state.3 create mode 100644 man/man3/malloc_hook.3 create mode 100644 man/man3/malloc_info.3 create mode 100644 man/man3/malloc_set_state.3 create mode 100644 man/man3/malloc_stats.3 create mode 100644 man/man3/malloc_trim.3 create mode 100644 man/man3/malloc_usable_size.3 create mode 100644 man/man3/mallopt.3 create mode 100644 man/man3/matherr.3 create mode 100644 man/man3/mblen.3 create mode 100644 man/man3/mbrlen.3 create mode 100644 man/man3/mbrtowc.3 create mode 100644 man/man3/mbsinit.3 create mode 100644 man/man3/mbsnrtowcs.3 create mode 100644 man/man3/mbsrtowcs.3 create mode 100644 man/man3/mbstowcs.3 create mode 100644 man/man3/mbtowc.3 create mode 100644 man/man3/mcheck.3 create mode 100644 man/man3/mcheck_check_all.3 create mode 100644 man/man3/mcheck_pedantic.3 create mode 100644 man/man3/memalign.3 create mode 100644 man/man3/memccpy.3 create mode 100644 man/man3/memchr.3 create mode 100644 man/man3/memcmp.3 create mode 100644 man/man3/memcpy.3 create mode 100644 man/man3/memfrob.3 create mode 100644 man/man3/memmem.3 create mode 100644 man/man3/memmove.3 create mode 100644 man/man3/mempcpy.3 create mode 100644 man/man3/memrchr.3 create mode 100644 man/man3/memset.3 create mode 100644 man/man3/minor.3 create mode 100644 man/man3/mkdtemp.3 create mode 100644 man/man3/mkfifo.3 create mode 100644 man/man3/mkfifoat.3 create mode 100644 man/man3/mkostemp.3 create mode 100644 man/man3/mkostemps.3 create mode 100644 man/man3/mkstemp.3 create mode 100644 man/man3/mkstemps.3 create mode 100644 man/man3/mktemp.3 create mode 100644 man/man3/mktime.3 create mode 100644 man/man3/mmap64.3 create mode 100644 man/man3/modf.3 create mode 100644 man/man3/modff.3 create mode 100644 man/man3/modfl.3 create mode 100644 man/man3/mpool.3 create mode 100644 man/man3/mprobe.3 create mode 100644 man/man3/mq_close.3 create mode 100644 man/man3/mq_getattr.3 create mode 100644 man/man3/mq_notify.3 create mode 100644 man/man3/mq_open.3 create mode 100644 man/man3/mq_receive.3 create mode 100644 man/man3/mq_send.3 create mode 100644 man/man3/mq_setattr.3 create mode 100644 man/man3/mq_timedreceive.3 create mode 100644 man/man3/mq_timedsend.3 create mode 100644 man/man3/mq_unlink.3 create mode 100644 man/man3/mrand48.3 create mode 100644 man/man3/mrand48_r.3 create mode 100644 man/man3/mtrace.3 create mode 100644 man/man3/muntrace.3 create mode 100644 man/man3/nan.3 create mode 100644 man/man3/nanf.3 create mode 100644 man/man3/nanl.3 create mode 100644 man/man3/nearbyint.3 create mode 100644 man/man3/nearbyintf.3 create mode 100644 man/man3/nearbyintl.3 create mode 100644 man/man3/netlink.3 create mode 100644 man/man3/newlocale.3 create mode 100644 man/man3/nextafter.3 create mode 100644 man/man3/nextafterf.3 create mode 100644 man/man3/nextafterl.3 create mode 100644 man/man3/nextdown.3 create mode 100644 man/man3/nextdownf.3 create mode 100644 man/man3/nextdownl.3 create mode 100644 man/man3/nexttoward.3 create mode 100644 man/man3/nexttowardf.3 create mode 100644 man/man3/nexttowardl.3 create mode 100644 man/man3/nextup.3 create mode 100644 man/man3/nextupf.3 create mode 100644 man/man3/nextupl.3 create mode 100644 man/man3/nftw.3 create mode 100644 man/man3/nl_langinfo.3 create mode 100644 man/man3/nl_langinfo_l.3 create mode 100644 man/man3/nrand48.3 create mode 100644 man/man3/nrand48_r.3 create mode 100644 man/man3/ntohl.3 create mode 100644 man/man3/ntohs.3 create mode 100644 man/man3/ntp_adjtime.3 create mode 100644 man/man3/ntp_gettime.3 create mode 100644 man/man3/ntp_gettimex.3 create mode 100644 man/man3/offsetof.3 create mode 100644 man/man3/on_exit.3 create mode 100644 man/man3/open_memstream.3 create mode 100644 man/man3/open_wmemstream.3 create mode 100644 man/man3/opendir.3 create mode 100644 man/man3/openlog.3 create mode 100644 man/man3/openpty.3 create mode 100644 man/man3/optarg.3 create mode 100644 man/man3/opterr.3 create mode 100644 man/man3/optind.3 create mode 100644 man/man3/optopt.3 create mode 100644 man/man3/passwd2des.3 create mode 100644 man/man3/pathconf.3 create mode 100644 man/man3/pclose.3 create mode 100644 man/man3/perror.3 create mode 100644 man/man3/pmap_getmaps.3 create mode 100644 man/man3/pmap_getport.3 create mode 100644 man/man3/pmap_rmtcall.3 create mode 100644 man/man3/pmap_set.3 create mode 100644 man/man3/pmap_unset.3 create mode 100644 man/man3/popen.3 create mode 100644 man/man3/posix_fallocate.3 create mode 100644 man/man3/posix_madvise.3 create mode 100644 man/man3/posix_memalign.3 create mode 100644 man/man3/posix_openpt.3 create mode 100644 man/man3/posix_spawn.3 create mode 100644 man/man3/posix_spawnp.3 create mode 100644 man/man3/pow.3 create mode 100644 man/man3/pow10.3 create mode 100644 man/man3/pow10f.3 create mode 100644 man/man3/pow10l.3 create mode 100644 man/man3/powerof2.3 create mode 100644 man/man3/powf.3 create mode 100644 man/man3/powl.3 create mode 100644 man/man3/printf.3 create mode 100644 man/man3/profil.3 create mode 100644 man/man3/program_invocation_name.3 create mode 100644 man/man3/program_invocation_short_name.3 create mode 100644 man/man3/psiginfo.3 create mode 100644 man/man3/psignal.3 create mode 100644 man/man3/pthread_atfork.3 create mode 100644 man/man3/pthread_attr_destroy.3 create mode 100644 man/man3/pthread_attr_getaffinity_np.3 create mode 100644 man/man3/pthread_attr_getdetachstate.3 create mode 100644 man/man3/pthread_attr_getguardsize.3 create mode 100644 man/man3/pthread_attr_getinheritsched.3 create mode 100644 man/man3/pthread_attr_getschedparam.3 create mode 100644 man/man3/pthread_attr_getschedpolicy.3 create mode 100644 man/man3/pthread_attr_getscope.3 create mode 100644 man/man3/pthread_attr_getsigmask_np.3 create mode 100644 man/man3/pthread_attr_getstack.3 create mode 100644 man/man3/pthread_attr_getstackaddr.3 create mode 100644 man/man3/pthread_attr_getstacksize.3 create mode 100644 man/man3/pthread_attr_init.3 create mode 100644 man/man3/pthread_attr_setaffinity_np.3 create mode 100644 man/man3/pthread_attr_setdetachstate.3 create mode 100644 man/man3/pthread_attr_setguardsize.3 create mode 100644 man/man3/pthread_attr_setinheritsched.3 create mode 100644 man/man3/pthread_attr_setschedparam.3 create mode 100644 man/man3/pthread_attr_setschedpolicy.3 create mode 100644 man/man3/pthread_attr_setscope.3 create mode 100644 man/man3/pthread_attr_setsigmask_np.3 create mode 100644 man/man3/pthread_attr_setstack.3 create mode 100644 man/man3/pthread_attr_setstackaddr.3 create mode 100644 man/man3/pthread_attr_setstacksize.3 create mode 100644 man/man3/pthread_cancel.3 create mode 100644 man/man3/pthread_cleanup_pop.3 create mode 100644 man/man3/pthread_cleanup_pop_restore_np.3 create mode 100644 man/man3/pthread_cleanup_push.3 create mode 100644 man/man3/pthread_cleanup_push_defer_np.3 create mode 100644 man/man3/pthread_cond_broadcast.3 create mode 100644 man/man3/pthread_cond_destroy.3 create mode 100644 man/man3/pthread_cond_init.3 create mode 100644 man/man3/pthread_cond_signal.3 create mode 100644 man/man3/pthread_cond_timedwait.3 create mode 100644 man/man3/pthread_cond_wait.3 create mode 100644 man/man3/pthread_condattr_destroy.3 create mode 100644 man/man3/pthread_condattr_init.3 create mode 100644 man/man3/pthread_create.3 create mode 100644 man/man3/pthread_detach.3 create mode 100644 man/man3/pthread_equal.3 create mode 100644 man/man3/pthread_exit.3 create mode 100644 man/man3/pthread_getaffinity_np.3 create mode 100644 man/man3/pthread_getattr_default_np.3 create mode 100644 man/man3/pthread_getattr_np.3 create mode 100644 man/man3/pthread_getconcurrency.3 create mode 100644 man/man3/pthread_getcpuclockid.3 create mode 100644 man/man3/pthread_getname_np.3 create mode 100644 man/man3/pthread_getschedparam.3 create mode 100644 man/man3/pthread_getspecific.3 create mode 100644 man/man3/pthread_join.3 create mode 100644 man/man3/pthread_key_create.3 create mode 100644 man/man3/pthread_key_delete.3 create mode 100644 man/man3/pthread_kill.3 create mode 100644 man/man3/pthread_kill_other_threads_np.3 create mode 100644 man/man3/pthread_mutex_consistent.3 create mode 100644 man/man3/pthread_mutex_consistent_np.3 create mode 100644 man/man3/pthread_mutex_destroy.3 create mode 100644 man/man3/pthread_mutex_init.3 create mode 100644 man/man3/pthread_mutex_lock.3 create mode 100644 man/man3/pthread_mutex_trylock.3 create mode 100644 man/man3/pthread_mutex_unlock.3 create mode 100644 man/man3/pthread_mutexattr_destroy.3 create mode 100644 man/man3/pthread_mutexattr_getkind_np.3 create mode 100644 man/man3/pthread_mutexattr_getpshared.3 create mode 100644 man/man3/pthread_mutexattr_getrobust.3 create mode 100644 man/man3/pthread_mutexattr_getrobust_np.3 create mode 100644 man/man3/pthread_mutexattr_gettype.3 create mode 100644 man/man3/pthread_mutexattr_init.3 create mode 100644 man/man3/pthread_mutexattr_setkind_np.3 create mode 100644 man/man3/pthread_mutexattr_setpshared.3 create mode 100644 man/man3/pthread_mutexattr_setrobust.3 create mode 100644 man/man3/pthread_mutexattr_setrobust_np.3 create mode 100644 man/man3/pthread_mutexattr_settype.3 create mode 100644 man/man3/pthread_once.3 create mode 100644 man/man3/pthread_rwlockattr_getkind_np.3 create mode 100644 man/man3/pthread_rwlockattr_setkind_np.3 create mode 100644 man/man3/pthread_self.3 create mode 100644 man/man3/pthread_setaffinity_np.3 create mode 100644 man/man3/pthread_setattr_default_np.3 create mode 100644 man/man3/pthread_setcancelstate.3 create mode 100644 man/man3/pthread_setcanceltype.3 create mode 100644 man/man3/pthread_setconcurrency.3 create mode 100644 man/man3/pthread_setname_np.3 create mode 100644 man/man3/pthread_setschedparam.3 create mode 100644 man/man3/pthread_setschedprio.3 create mode 100644 man/man3/pthread_setspecific.3 create mode 100644 man/man3/pthread_sigmask.3 create mode 100644 man/man3/pthread_sigqueue.3 create mode 100644 man/man3/pthread_spin_destroy.3 create mode 100644 man/man3/pthread_spin_init.3 create mode 100644 man/man3/pthread_spin_lock.3 create mode 100644 man/man3/pthread_spin_trylock.3 create mode 100644 man/man3/pthread_spin_unlock.3 create mode 100644 man/man3/pthread_testcancel.3 create mode 100644 man/man3/pthread_timedjoin_np.3 create mode 100644 man/man3/pthread_tryjoin_np.3 create mode 100644 man/man3/pthread_yield.3 create mode 100644 man/man3/ptsname.3 create mode 100644 man/man3/ptsname_r.3 create mode 100644 man/man3/putc.3 create mode 100644 man/man3/putc_unlocked.3 create mode 100644 man/man3/putchar.3 create mode 100644 man/man3/putchar_unlocked.3 create mode 100644 man/man3/putenv.3 create mode 100644 man/man3/putgrent.3 create mode 100644 man/man3/putpwent.3 create mode 100644 man/man3/puts.3 create mode 100644 man/man3/putspent.3 create mode 100644 man/man3/pututline.3 create mode 100644 man/man3/pututxline.3 create mode 100644 man/man3/putw.3 create mode 100644 man/man3/putwc.3 create mode 100644 man/man3/putwc_unlocked.3 create mode 100644 man/man3/putwchar.3 create mode 100644 man/man3/putwchar_unlocked.3 create mode 100644 man/man3/pvalloc.3 create mode 100644 man/man3/qecvt.3 create mode 100644 man/man3/qecvt_r.3 create mode 100644 man/man3/qfcvt.3 create mode 100644 man/man3/qfcvt_r.3 create mode 100644 man/man3/qgcvt.3 create mode 100644 man/man3/qsort.3 create mode 100644 man/man3/qsort_r.3 create mode 100644 man/man3/queue.3 create mode 100644 man/man3/raise.3 create mode 100644 man/man3/rand.3 create mode 100644 man/man3/rand_r.3 create mode 100644 man/man3/random.3 create mode 100644 man/man3/random_r.3 create mode 100644 man/man3/rawmemchr.3 create mode 100644 man/man3/rcmd.3 create mode 100644 man/man3/rcmd_af.3 create mode 100644 man/man3/re_comp.3 create mode 100644 man/man3/re_exec.3 create mode 100644 man/man3/readdir.3 create mode 100644 man/man3/readdir_r.3 create mode 100644 man/man3/realloc.3 create mode 100644 man/man3/reallocarray.3 create mode 100644 man/man3/realpath.3 create mode 100644 man/man3/recno.3 create mode 100644 man/man3/regcomp.3 create mode 100644 man/man3/regerror.3 create mode 100644 man/man3/regex.3 create mode 100644 man/man3/regexec.3 create mode 100644 man/man3/regfree.3 create mode 100644 man/man3/register_printf_modifier.3 create mode 100644 man/man3/register_printf_specifier.3 create mode 100644 man/man3/register_printf_type.3 create mode 100644 man/man3/registerrpc.3 create mode 100644 man/man3/remainder.3 create mode 100644 man/man3/remainderf.3 create mode 100644 man/man3/remainderl.3 create mode 100644 man/man3/remove.3 create mode 100644 man/man3/remque.3 create mode 100644 man/man3/remquo.3 create mode 100644 man/man3/remquof.3 create mode 100644 man/man3/remquol.3 create mode 100644 man/man3/res_init.3 create mode 100644 man/man3/res_mkquery.3 create mode 100644 man/man3/res_nclose.3 create mode 100644 man/man3/res_ninit.3 create mode 100644 man/man3/res_nmkquery.3 create mode 100644 man/man3/res_nquery.3 create mode 100644 man/man3/res_nquerydomain.3 create mode 100644 man/man3/res_nsearch.3 create mode 100644 man/man3/res_nsend.3 create mode 100644 man/man3/res_query.3 create mode 100644 man/man3/res_querydomain.3 create mode 100644 man/man3/res_search.3 create mode 100644 man/man3/res_send.3 create mode 100644 man/man3/resolver.3 create mode 100644 man/man3/rewind.3 create mode 100644 man/man3/rewinddir.3 create mode 100644 man/man3/rexec.3 create mode 100644 man/man3/rexec_af.3 create mode 100644 man/man3/rindex.3 create mode 100644 man/man3/rint.3 create mode 100644 man/man3/rintf.3 create mode 100644 man/man3/rintl.3 create mode 100644 man/man3/round.3 create mode 100644 man/man3/roundf.3 create mode 100644 man/man3/roundl.3 create mode 100644 man/man3/roundup.3 create mode 100644 man/man3/rpc.3 create mode 100644 man/man3/rpmatch.3 create mode 100644 man/man3/rresvport.3 create mode 100644 man/man3/rresvport_af.3 create mode 100644 man/man3/rtime.3 create mode 100644 man/man3/rtnetlink.3 create mode 100644 man/man3/ruserok.3 create mode 100644 man/man3/ruserok_af.3 create mode 100644 man/man3/scalb.3 create mode 100644 man/man3/scalbf.3 create mode 100644 man/man3/scalbl.3 create mode 100644 man/man3/scalbln.3 create mode 100644 man/man3/scalblnf.3 create mode 100644 man/man3/scalblnl.3 create mode 100644 man/man3/scalbn.3 create mode 100644 man/man3/scalbnf.3 create mode 100644 man/man3/scalbnl.3 create mode 100644 man/man3/scandir.3 create mode 100644 man/man3/scandirat.3 create mode 100644 man/man3/scanf.3 create mode 100644 man/man3/sched_getcpu.3 create mode 100644 man/man3/secure_getenv.3 create mode 100644 man/man3/seed48.3 create mode 100644 man/man3/seed48_r.3 create mode 100644 man/man3/seekdir.3 create mode 100644 man/man3/sem_close.3 create mode 100644 man/man3/sem_destroy.3 create mode 100644 man/man3/sem_getvalue.3 create mode 100644 man/man3/sem_init.3 create mode 100644 man/man3/sem_open.3 create mode 100644 man/man3/sem_post.3 create mode 100644 man/man3/sem_timedwait.3 create mode 100644 man/man3/sem_trywait.3 create mode 100644 man/man3/sem_unlink.3 create mode 100644 man/man3/sem_wait.3 create mode 100644 man/man3/setaliasent.3 create mode 100644 man/man3/setbuf.3 create mode 100644 man/man3/setbuffer.3 create mode 100644 man/man3/setcontext.3 create mode 100644 man/man3/setenv.3 create mode 100644 man/man3/setfsent.3 create mode 100644 man/man3/setgrent.3 create mode 100644 man/man3/sethostent.3 create mode 100644 man/man3/sethostid.3 create mode 100644 man/man3/setjmp.3 create mode 100644 man/man3/setkey.3 create mode 100644 man/man3/setkey_r.3 create mode 100644 man/man3/setlinebuf.3 create mode 100644 man/man3/setlocale.3 create mode 100644 man/man3/setlogmask.3 create mode 100644 man/man3/setmntent.3 create mode 100644 man/man3/setnetent.3 create mode 100644 man/man3/setnetgrent.3 create mode 100644 man/man3/setprotoent.3 create mode 100644 man/man3/setpwent.3 create mode 100644 man/man3/setrpcent.3 create mode 100644 man/man3/setservent.3 create mode 100644 man/man3/setspent.3 create mode 100644 man/man3/setstate.3 create mode 100644 man/man3/setstate_r.3 create mode 100644 man/man3/setttyent.3 create mode 100644 man/man3/setusershell.3 create mode 100644 man/man3/setutent.3 create mode 100644 man/man3/setutxent.3 create mode 100644 man/man3/setvbuf.3 create mode 100644 man/man3/sgetspent.3 create mode 100644 man/man3/sgetspent_r.3 create mode 100644 man/man3/shm_open.3 create mode 100644 man/man3/shm_unlink.3 create mode 100644 man/man3/sigabbrev_np.3 create mode 100644 man/man3/sigaddset.3 create mode 100644 man/man3/sigandset.3 create mode 100644 man/man3/sigblock.3 create mode 100644 man/man3/sigdelset.3 create mode 100644 man/man3/sigdescr_np.3 create mode 100644 man/man3/sigemptyset.3 create mode 100644 man/man3/sigfillset.3 create mode 100644 man/man3/siggetmask.3 create mode 100644 man/man3/sighold.3 create mode 100644 man/man3/sigignore.3 create mode 100644 man/man3/siginterrupt.3 create mode 100644 man/man3/sigisemptyset.3 create mode 100644 man/man3/sigismember.3 create mode 100644 man/man3/siglongjmp.3 create mode 100644 man/man3/sigmask.3 create mode 100644 man/man3/signbit.3 create mode 100644 man/man3/signgam.3 create mode 100644 man/man3/significand.3 create mode 100644 man/man3/significandf.3 create mode 100644 man/man3/significandl.3 create mode 100644 man/man3/sigorset.3 create mode 100644 man/man3/sigpause.3 create mode 100644 man/man3/sigqueue.3 create mode 100644 man/man3/sigrelse.3 create mode 100644 man/man3/sigset.3 create mode 100644 man/man3/sigsetjmp.3 create mode 100644 man/man3/sigsetmask.3 create mode 100644 man/man3/sigsetops.3 create mode 100644 man/man3/sigstack.3 create mode 100644 man/man3/sigvec.3 create mode 100644 man/man3/sigwait.3 create mode 100644 man/man3/simpleq.3 create mode 100644 man/man3/sin.3 create mode 100644 man/man3/sincos.3 create mode 100644 man/man3/sincosf.3 create mode 100644 man/man3/sincosl.3 create mode 100644 man/man3/sinf.3 create mode 100644 man/man3/sinh.3 create mode 100644 man/man3/sinhf.3 create mode 100644 man/man3/sinhl.3 create mode 100644 man/man3/sinl.3 create mode 100644 man/man3/sleep.3 create mode 100644 man/man3/slist.3 create mode 100644 man/man3/snprintf.3 create mode 100644 man/man3/sockatmark.3 create mode 100644 man/man3/sprintf.3 create mode 100644 man/man3/sqrt.3 create mode 100644 man/man3/sqrtf.3 create mode 100644 man/man3/sqrtl.3 create mode 100644 man/man3/srand.3 create mode 100644 man/man3/srand48.3 create mode 100644 man/man3/srand48_r.3 create mode 100644 man/man3/srandom.3 create mode 100644 man/man3/srandom_r.3 create mode 100644 man/man3/sscanf.3 create mode 100644 man/man3/ssignal.3 create mode 100644 man/man3/stailq.3 create mode 100644 man/man3/static_assert.3 create mode 100644 man/man3/statvfs.3 create mode 100644 man/man3/stdarg.3 create mode 100644 man/man3/stderr.3 create mode 100644 man/man3/stdin.3 create mode 100644 man/man3/stdio.3 create mode 100644 man/man3/stdio_ext.3 create mode 100644 man/man3/stdout.3 create mode 100644 man/man3/stpcpy.3 create mode 100644 man/man3/stpncpy.3 create mode 100644 man/man3/strcasecmp.3 create mode 100644 man/man3/strcasestr.3 create mode 100644 man/man3/strcat.3 create mode 100644 man/man3/strchr.3 create mode 100644 man/man3/strchrnul.3 create mode 100644 man/man3/strcmp.3 create mode 100644 man/man3/strcoll.3 create mode 100644 man/man3/strcpy.3 create mode 100644 man/man3/strcspn.3 create mode 100644 man/man3/strdup.3 create mode 100644 man/man3/strdupa.3 create mode 100644 man/man3/strerror.3 create mode 100644 man/man3/strerror_l.3 create mode 100644 man/man3/strerror_r.3 create mode 100644 man/man3/strerrordesc_np.3 create mode 100644 man/man3/strerrorname_np.3 create mode 100644 man/man3/strfmon.3 create mode 100644 man/man3/strfmon_l.3 create mode 100644 man/man3/strfromd.3 create mode 100644 man/man3/strfromf.3 create mode 100644 man/man3/strfroml.3 create mode 100644 man/man3/strfry.3 create mode 100644 man/man3/strftime.3 create mode 100644 man/man3/strftime_l.3 create mode 100644 man/man3/string.3 create mode 100644 man/man3/strlen.3 create mode 100644 man/man3/strncasecmp.3 create mode 100644 man/man3/strncat.3 create mode 100644 man/man3/strncmp.3 create mode 100644 man/man3/strncpy.3 create mode 100644 man/man3/strndup.3 create mode 100644 man/man3/strndupa.3 create mode 100644 man/man3/strnlen.3 create mode 100644 man/man3/strpbrk.3 create mode 100644 man/man3/strptime.3 create mode 100644 man/man3/strrchr.3 create mode 100644 man/man3/strsep.3 create mode 100644 man/man3/strsignal.3 create mode 100644 man/man3/strspn.3 create mode 100644 man/man3/strstr.3 create mode 100644 man/man3/strtod.3 create mode 100644 man/man3/strtof.3 create mode 100644 man/man3/strtoimax.3 create mode 100644 man/man3/strtok.3 create mode 100644 man/man3/strtok_r.3 create mode 100644 man/man3/strtol.3 create mode 100644 man/man3/strtold.3 create mode 100644 man/man3/strtoll.3 create mode 100644 man/man3/strtoq.3 create mode 100644 man/man3/strtoul.3 create mode 100644 man/man3/strtoull.3 create mode 100644 man/man3/strtoumax.3 create mode 100644 man/man3/strtouq.3 create mode 100644 man/man3/strverscmp.3 create mode 100644 man/man3/strxfrm.3 create mode 100644 man/man3/svc_destroy.3 create mode 100644 man/man3/svc_freeargs.3 create mode 100644 man/man3/svc_getargs.3 create mode 100644 man/man3/svc_getcaller.3 create mode 100644 man/man3/svc_getreq.3 create mode 100644 man/man3/svc_getreqset.3 create mode 100644 man/man3/svc_register.3 create mode 100644 man/man3/svc_run.3 create mode 100644 man/man3/svc_sendreply.3 create mode 100644 man/man3/svc_unregister.3 create mode 100644 man/man3/svcerr_auth.3 create mode 100644 man/man3/svcerr_decode.3 create mode 100644 man/man3/svcerr_noproc.3 create mode 100644 man/man3/svcerr_noprog.3 create mode 100644 man/man3/svcerr_progvers.3 create mode 100644 man/man3/svcerr_systemerr.3 create mode 100644 man/man3/svcerr_weakauth.3 create mode 100644 man/man3/svcfd_create.3 create mode 100644 man/man3/svcraw_create.3 create mode 100644 man/man3/svctcp_create.3 create mode 100644 man/man3/svcudp_bufcreate.3 create mode 100644 man/man3/svcudp_create.3 create mode 100644 man/man3/swab.3 create mode 100644 man/man3/swapcontext.3 create mode 100644 man/man3/swprintf.3 create mode 100644 man/man3/sys_errlist.3 create mode 100644 man/man3/sys_nerr.3 create mode 100644 man/man3/sys_siglist.3 create mode 100644 man/man3/sysconf.3 create mode 100644 man/man3/syslog.3 create mode 100644 man/man3/system.3 create mode 100644 man/man3/sysv_signal.3 create mode 100644 man/man3/tailq.3 create mode 100644 man/man3/tan.3 create mode 100644 man/man3/tanf.3 create mode 100644 man/man3/tanh.3 create mode 100644 man/man3/tanhf.3 create mode 100644 man/man3/tanhl.3 create mode 100644 man/man3/tanl.3 create mode 100644 man/man3/tcdrain.3 create mode 100644 man/man3/tcflow.3 create mode 100644 man/man3/tcflush.3 create mode 100644 man/man3/tcgetattr.3 create mode 100644 man/man3/tcgetpgrp.3 create mode 100644 man/man3/tcgetsid.3 create mode 100644 man/man3/tcsendbreak.3 create mode 100644 man/man3/tcsetattr.3 create mode 100644 man/man3/tcsetpgrp.3 create mode 100644 man/man3/tdelete.3 create mode 100644 man/man3/tdestroy.3 create mode 100644 man/man3/telldir.3 create mode 100644 man/man3/tempnam.3 create mode 100644 man/man3/termios.3 create mode 100644 man/man3/tfind.3 create mode 100644 man/man3/tgamma.3 create mode 100644 man/man3/tgammaf.3 create mode 100644 man/man3/tgammal.3 create mode 100644 man/man3/timegm.3 create mode 100644 man/man3/timelocal.3 create mode 100644 man/man3/timeradd.3 create mode 100644 man/man3/timerclear.3 create mode 100644 man/man3/timercmp.3 create mode 100644 man/man3/timerisset.3 create mode 100644 man/man3/timersub.3 create mode 100644 man/man3/timezone.3 create mode 100644 man/man3/tmpfile.3 create mode 100644 man/man3/tmpnam.3 create mode 100644 man/man3/tmpnam_r.3 create mode 100644 man/man3/toascii.3 create mode 100644 man/man3/tolower.3 create mode 100644 man/man3/tolower_l.3 create mode 100644 man/man3/toupper.3 create mode 100644 man/man3/toupper_l.3 create mode 100644 man/man3/towctrans.3 create mode 100644 man/man3/towlower.3 create mode 100644 man/man3/towlower_l.3 create mode 100644 man/man3/towupper.3 create mode 100644 man/man3/towupper_l.3 create mode 100644 man/man3/trunc.3 create mode 100644 man/man3/truncf.3 create mode 100644 man/man3/truncl.3 create mode 100644 man/man3/tsearch.3 create mode 100644 man/man3/ttyname.3 create mode 100644 man/man3/ttyname_r.3 create mode 100644 man/man3/ttyslot.3 create mode 100644 man/man3/twalk.3 create mode 100644 man/man3/twalk_r.3 create mode 100644 man/man3/tzname.3 create mode 100644 man/man3/tzset.3 create mode 100644 man/man3/ualarm.3 create mode 100644 man/man3/ulckpwdf.3 create mode 100644 man/man3/ulimit.3 create mode 100644 man/man3/undocumented.3 create mode 100644 man/man3/ungetc.3 create mode 100644 man/man3/ungetwc.3 create mode 100644 man/man3/unlocked_stdio.3 create mode 100644 man/man3/unlockpt.3 create mode 100644 man/man3/unsetenv.3 create mode 100644 man/man3/updwtmp.3 create mode 100644 man/man3/updwtmpx.3 create mode 100644 man/man3/uselocale.3 create mode 100644 man/man3/usleep.3 create mode 100644 man/man3/utmpname.3 create mode 100644 man/man3/utmpxname.3 create mode 100644 man/man3/va_arg.3 create mode 100644 man/man3/va_copy.3 create mode 100644 man/man3/va_end.3 create mode 100644 man/man3/va_start.3 create mode 100644 man/man3/valloc.3 create mode 100644 man/man3/vasprintf.3 create mode 100644 man/man3/vdprintf.3 create mode 100644 man/man3/verr.3 create mode 100644 man/man3/verrx.3 create mode 100644 man/man3/versionsort.3 create mode 100644 man/man3/vfprintf.3 create mode 100644 man/man3/vfscanf.3 create mode 100644 man/man3/vfwprintf.3 create mode 100644 man/man3/vlimit.3 create mode 100644 man/man3/vprintf.3 create mode 100644 man/man3/vscanf.3 create mode 100644 man/man3/vsnprintf.3 create mode 100644 man/man3/vsprintf.3 create mode 100644 man/man3/vsscanf.3 create mode 100644 man/man3/vswprintf.3 create mode 100644 man/man3/vsyslog.3 create mode 100644 man/man3/vtimes.3 create mode 100644 man/man3/vwarn.3 create mode 100644 man/man3/vwarnx.3 create mode 100644 man/man3/vwprintf.3 create mode 100644 man/man3/warn.3 create mode 100644 man/man3/warnx.3 create mode 100644 man/man3/wcpcpy.3 create mode 100644 man/man3/wcpncpy.3 create mode 100644 man/man3/wcrtomb.3 create mode 100644 man/man3/wcscasecmp.3 create mode 100644 man/man3/wcscat.3 create mode 100644 man/man3/wcschr.3 create mode 100644 man/man3/wcscmp.3 create mode 100644 man/man3/wcscpy.3 create mode 100644 man/man3/wcscspn.3 create mode 100644 man/man3/wcsdup.3 create mode 100644 man/man3/wcslen.3 create mode 100644 man/man3/wcsncasecmp.3 create mode 100644 man/man3/wcsncat.3 create mode 100644 man/man3/wcsncmp.3 create mode 100644 man/man3/wcsncpy.3 create mode 100644 man/man3/wcsnlen.3 create mode 100644 man/man3/wcsnrtombs.3 create mode 100644 man/man3/wcspbrk.3 create mode 100644 man/man3/wcsrchr.3 create mode 100644 man/man3/wcsrtombs.3 create mode 100644 man/man3/wcsspn.3 create mode 100644 man/man3/wcsstr.3 create mode 100644 man/man3/wcstoimax.3 create mode 100644 man/man3/wcstok.3 create mode 100644 man/man3/wcstombs.3 create mode 100644 man/man3/wcstoumax.3 create mode 100644 man/man3/wcswidth.3 create mode 100644 man/man3/wctob.3 create mode 100644 man/man3/wctomb.3 create mode 100644 man/man3/wctrans.3 create mode 100644 man/man3/wctype.3 create mode 100644 man/man3/wcwidth.3 create mode 100644 man/man3/wmemchr.3 create mode 100644 man/man3/wmemcmp.3 create mode 100644 man/man3/wmemcpy.3 create mode 100644 man/man3/wmemmove.3 create mode 100644 man/man3/wmempcpy.3 create mode 100644 man/man3/wmemset.3 create mode 100644 man/man3/wordexp.3 create mode 100644 man/man3/wordfree.3 create mode 100644 man/man3/wprintf.3 create mode 100644 man/man3/xcrypt.3 create mode 100644 man/man3/xdecrypt.3 create mode 100644 man/man3/xdr.3 create mode 100644 man/man3/xdr_accepted_reply.3 create mode 100644 man/man3/xdr_array.3 create mode 100644 man/man3/xdr_authunix_parms.3 create mode 100644 man/man3/xdr_bool.3 create mode 100644 man/man3/xdr_bytes.3 create mode 100644 man/man3/xdr_callhdr.3 create mode 100644 man/man3/xdr_callmsg.3 create mode 100644 man/man3/xdr_char.3 create mode 100644 man/man3/xdr_destroy.3 create mode 100644 man/man3/xdr_double.3 create mode 100644 man/man3/xdr_enum.3 create mode 100644 man/man3/xdr_float.3 create mode 100644 man/man3/xdr_free.3 create mode 100644 man/man3/xdr_getpos.3 create mode 100644 man/man3/xdr_inline.3 create mode 100644 man/man3/xdr_int.3 create mode 100644 man/man3/xdr_long.3 create mode 100644 man/man3/xdr_opaque.3 create mode 100644 man/man3/xdr_opaque_auth.3 create mode 100644 man/man3/xdr_pmap.3 create mode 100644 man/man3/xdr_pmaplist.3 create mode 100644 man/man3/xdr_pointer.3 create mode 100644 man/man3/xdr_reference.3 create mode 100644 man/man3/xdr_rejected_reply.3 create mode 100644 man/man3/xdr_replymsg.3 create mode 100644 man/man3/xdr_setpos.3 create mode 100644 man/man3/xdr_short.3 create mode 100644 man/man3/xdr_string.3 create mode 100644 man/man3/xdr_u_char.3 create mode 100644 man/man3/xdr_u_int.3 create mode 100644 man/man3/xdr_u_long.3 create mode 100644 man/man3/xdr_u_short.3 create mode 100644 man/man3/xdr_union.3 create mode 100644 man/man3/xdr_vector.3 create mode 100644 man/man3/xdr_void.3 create mode 100644 man/man3/xdr_wrapstring.3 create mode 100644 man/man3/xdrmem_create.3 create mode 100644 man/man3/xdrrec_create.3 create mode 100644 man/man3/xdrrec_endofrecord.3 create mode 100644 man/man3/xdrrec_eof.3 create mode 100644 man/man3/xdrrec_skiprecord.3 create mode 100644 man/man3/xdrstdio_create.3 create mode 100644 man/man3/xencrypt.3 create mode 100644 man/man3/xprt_register.3 create mode 100644 man/man3/xprt_unregister.3 create mode 100644 man/man3/y0.3 create mode 100644 man/man3/y0f.3 create mode 100644 man/man3/y0l.3 create mode 100644 man/man3/y1.3 create mode 100644 man/man3/y1f.3 create mode 100644 man/man3/y1l.3 create mode 100644 man/man3/yn.3 create mode 100644 man/man3/ynf.3 create mode 100644 man/man3/ynl.3 create mode 100644 man/man3const/EOF.3const create mode 100644 man/man3const/EXIT_FAILURE.3const create mode 100644 man/man3const/EXIT_SUCCESS.3const create mode 100644 man/man3const/NULL.3const create mode 100644 man/man3const/PA_CHAR.3const create mode 100644 man/man3const/PA_DOUBLE.3const create mode 100644 man/man3const/PA_FLAG_LONG.3const create mode 100644 man/man3const/PA_FLAG_LONG_DOUBLE.3const create mode 100644 man/man3const/PA_FLAG_LONG_LONG.3const create mode 100644 man/man3const/PA_FLAG_PTR.3const create mode 100644 man/man3const/PA_FLAG_SHORT.3const create mode 100644 man/man3const/PA_FLOAT.3const create mode 100644 man/man3const/PA_INT.3const create mode 100644 man/man3const/PA_LAST.3const create mode 100644 man/man3const/PA_POINTER.3const create mode 100644 man/man3const/PA_STRING.3const create mode 100644 man/man3const/PA_WCHAR.3const create mode 100644 man/man3const/PA_WSTRING.3const create mode 100644 man/man3head/printf.h.3head create mode 100644 man/man3head/sysexits.h.3head create mode 100644 man/man3type/FILE.3type create mode 100644 man/man3type/aiocb.3type create mode 100644 man/man3type/blkcnt_t.3type create mode 100644 man/man3type/blksize_t.3type create mode 100644 man/man3type/cc_t.3type create mode 100644 man/man3type/clock_t.3type create mode 100644 man/man3type/clockid_t.3type create mode 100644 man/man3type/dev_t.3type create mode 100644 man/man3type/div_t.3type create mode 100644 man/man3type/double_t.3type create mode 100644 man/man3type/epoll_data.3type create mode 100644 man/man3type/epoll_data_t.3type create mode 100644 man/man3type/epoll_event.3type create mode 100644 man/man3type/fenv_t.3type create mode 100644 man/man3type/fexcept_t.3type create mode 100644 man/man3type/float_t.3type create mode 100644 man/man3type/gid_t.3type create mode 100644 man/man3type/id_t.3type create mode 100644 man/man3type/imaxdiv_t.3type create mode 100644 man/man3type/in6_addr.3type create mode 100644 man/man3type/in_addr.3type create mode 100644 man/man3type/in_addr_t.3type create mode 100644 man/man3type/in_port_t.3type create mode 100644 man/man3type/int16_t.3type create mode 100644 man/man3type/int32_t.3type create mode 100644 man/man3type/int64_t.3type create mode 100644 man/man3type/int8_t.3type create mode 100644 man/man3type/intN_t.3type create mode 100644 man/man3type/intmax_t.3type create mode 100644 man/man3type/intptr_t.3type create mode 100644 man/man3type/iovec.3type create mode 100644 man/man3type/itimerspec.3type create mode 100644 man/man3type/lconv.3type create mode 100644 man/man3type/ldiv_t.3type create mode 100644 man/man3type/lldiv_t.3type create mode 100644 man/man3type/locale_t.3type create mode 100644 man/man3type/loff_t.3type create mode 100644 man/man3type/mbstate_t.3type create mode 100644 man/man3type/mode_t.3type create mode 100644 man/man3type/off64_t.3type create mode 100644 man/man3type/off_t.3type create mode 100644 man/man3type/pid_t.3type create mode 100644 man/man3type/printf_arginfo_size_function.3type create mode 100644 man/man3type/printf_function.3type create mode 100644 man/man3type/printf_info.3type create mode 100644 man/man3type/printf_va_arg_function.3type create mode 100644 man/man3type/ptrdiff_t.3type create mode 100644 man/man3type/regex_t.3type create mode 100644 man/man3type/regmatch_t.3type create mode 100644 man/man3type/regoff_t.3type create mode 100644 man/man3type/sa_family_t.3type create mode 100644 man/man3type/sigevent.3type create mode 100644 man/man3type/siginfo_t.3type create mode 100644 man/man3type/sigset_t.3type create mode 100644 man/man3type/sigval.3type create mode 100644 man/man3type/size_t.3type create mode 100644 man/man3type/sockaddr.3type create mode 100644 man/man3type/sockaddr_in.3type create mode 100644 man/man3type/sockaddr_in6.3type create mode 100644 man/man3type/sockaddr_storage.3type create mode 100644 man/man3type/sockaddr_un.3type create mode 100644 man/man3type/socklen_t.3type create mode 100644 man/man3type/speed_t.3type create mode 100644 man/man3type/ssize_t.3type create mode 100644 man/man3type/stat.3type create mode 100644 man/man3type/suseconds_t.3type create mode 100644 man/man3type/tcflag_t.3type create mode 100644 man/man3type/time_t.3type create mode 100644 man/man3type/timer_t.3type create mode 100644 man/man3type/timespec.3type create mode 100644 man/man3type/timeval.3type create mode 100644 man/man3type/tm.3type create mode 100644 man/man3type/uid_t.3type create mode 100644 man/man3type/uint16_t.3type create mode 100644 man/man3type/uint32_t.3type create mode 100644 man/man3type/uint64_t.3type create mode 100644 man/man3type/uint8_t.3type create mode 100644 man/man3type/uintN_t.3type create mode 100644 man/man3type/uintmax_t.3type create mode 100644 man/man3type/uintptr_t.3type create mode 100644 man/man3type/useconds_t.3type create mode 100644 man/man3type/va_list.3type create mode 100644 man/man3type/void.3type create mode 100644 man/man3type/wchar_t.3type create mode 100644 man/man3type/wint_t.3type create mode 100644 man/man4/cciss.4 create mode 100644 man/man4/console_codes.4 create mode 100644 man/man4/console_ioctl.4 create mode 100644 man/man4/cpuid.4 create mode 100644 man/man4/dsp56k.4 create mode 100644 man/man4/fd.4 create mode 100644 man/man4/full.4 create mode 100644 man/man4/fuse.4 create mode 100644 man/man4/hd.4 create mode 100644 man/man4/hpsa.4 create mode 100644 man/man4/initrd.4 create mode 100644 man/man4/intro.4 create mode 100644 man/man4/kmem.4 create mode 100644 man/man4/lirc.4 create mode 100644 man/man4/loop-control.4 create mode 100644 man/man4/loop.4 create mode 100644 man/man4/lp.4 create mode 100644 man/man4/mem.4 create mode 100644 man/man4/mouse.4 create mode 100644 man/man4/msr.4 create mode 100644 man/man4/null.4 create mode 100644 man/man4/port.4 create mode 100644 man/man4/ptmx.4 create mode 100644 man/man4/pts.4 create mode 100644 man/man4/ram.4 create mode 100644 man/man4/random.4 create mode 100644 man/man4/rtc.4 create mode 100644 man/man4/sd.4 create mode 100644 man/man4/sk98lin.4 create mode 100644 man/man4/smartpqi.4 create mode 100644 man/man4/st.4 create mode 100644 man/man4/tty.4 create mode 100644 man/man4/ttyS.4 create mode 100644 man/man4/tty_ioctl.4 create mode 100644 man/man4/urandom.4 create mode 100644 man/man4/vcs.4 create mode 100644 man/man4/vcsa.4 create mode 100644 man/man4/veth.4 create mode 100644 man/man4/wavelan.4 create mode 100644 man/man4/zero.4 create mode 100644 man/man5/acct.5 create mode 100644 man/man5/charmap.5 create mode 100644 man/man5/core.5 create mode 100644 man/man5/dir_colors.5 create mode 100644 man/man5/elf.5 create mode 100644 man/man5/erofs.5 create mode 100644 man/man5/filesystems.5 create mode 100644 man/man5/fs.5 create mode 100644 man/man5/ftpusers.5 create mode 100644 man/man5/gai.conf.5 create mode 100644 man/man5/group.5 create mode 100644 man/man5/host.conf.5 create mode 100644 man/man5/hosts.5 create mode 100644 man/man5/hosts.equiv.5 create mode 100644 man/man5/intro.5 create mode 100644 man/man5/issue.5 create mode 100644 man/man5/locale.5 create mode 100644 man/man5/motd.5 create mode 100644 man/man5/networks.5 create mode 100644 man/man5/nologin.5 create mode 100644 man/man5/nscd.conf.5 create mode 100644 man/man5/nss.5 create mode 100644 man/man5/nsswitch.conf.5 create mode 100644 man/man5/passwd.5 create mode 100644 man/man5/proc.5 create mode 100644 man/man5/proc_apm.5 create mode 100644 man/man5/proc_buddyinfo.5 create mode 100644 man/man5/proc_bus.5 create mode 100644 man/man5/proc_cgroups.5 create mode 100644 man/man5/proc_cmdline.5 create mode 100644 man/man5/proc_config.gz.5 create mode 100644 man/man5/proc_cpuinfo.5 create mode 100644 man/man5/proc_crypto.5 create mode 100644 man/man5/proc_devices.5 create mode 100644 man/man5/proc_diskstats.5 create mode 100644 man/man5/proc_dma.5 create mode 100644 man/man5/proc_driver.5 create mode 100644 man/man5/proc_execdomains.5 create mode 100644 man/man5/proc_fb.5 create mode 100644 man/man5/proc_filesystems.5 create mode 100644 man/man5/proc_fs.5 create mode 100644 man/man5/proc_ide.5 create mode 100644 man/man5/proc_interrupts.5 create mode 100644 man/man5/proc_iomem.5 create mode 100644 man/man5/proc_ioports.5 create mode 100644 man/man5/proc_kallsyms.5 create mode 100644 man/man5/proc_kcore.5 create mode 100644 man/man5/proc_key-users.5 create mode 100644 man/man5/proc_keys.5 create mode 100644 man/man5/proc_kmsg.5 create mode 100644 man/man5/proc_kpagecgroup.5 create mode 100644 man/man5/proc_kpagecount.5 create mode 100644 man/man5/proc_kpageflags.5 create mode 100644 man/man5/proc_ksyms.5 create mode 100644 man/man5/proc_loadavg.5 create mode 100644 man/man5/proc_locks.5 create mode 100644 man/man5/proc_malloc.5 create mode 100644 man/man5/proc_meminfo.5 create mode 100644 man/man5/proc_modules.5 create mode 100644 man/man5/proc_mounts.5 create mode 100644 man/man5/proc_mtrr.5 create mode 100644 man/man5/proc_net.5 create mode 100644 man/man5/proc_partitions.5 create mode 100644 man/man5/proc_pci.5 create mode 100644 man/man5/proc_pid.5 create mode 100644 man/man5/proc_pid_attr.5 create mode 100644 man/man5/proc_pid_autogroup.5 create mode 100644 man/man5/proc_pid_auxv.5 create mode 100644 man/man5/proc_pid_cgroup.5 create mode 100644 man/man5/proc_pid_clear_refs.5 create mode 100644 man/man5/proc_pid_cmdline.5 create mode 100644 man/man5/proc_pid_comm.5 create mode 100644 man/man5/proc_pid_coredump_filter.5 create mode 100644 man/man5/proc_pid_cpuset.5 create mode 100644 man/man5/proc_pid_cwd.5 create mode 100644 man/man5/proc_pid_environ.5 create mode 100644 man/man5/proc_pid_exe.5 create mode 100644 man/man5/proc_pid_fd.5 create mode 100644 man/man5/proc_pid_fdinfo.5 create mode 100644 man/man5/proc_pid_gid_map.5 create mode 100644 man/man5/proc_pid_io.5 create mode 100644 man/man5/proc_pid_limits.5 create mode 100644 man/man5/proc_pid_map_files.5 create mode 100644 man/man5/proc_pid_maps.5 create mode 100644 man/man5/proc_pid_mem.5 create mode 100644 man/man5/proc_pid_mountinfo.5 create mode 100644 man/man5/proc_pid_mounts.5 create mode 100644 man/man5/proc_pid_mountstats.5 create mode 100644 man/man5/proc_pid_net.5 create mode 100644 man/man5/proc_pid_ns.5 create mode 100644 man/man5/proc_pid_numa_maps.5 create mode 100644 man/man5/proc_pid_oom_adj.5 create mode 100644 man/man5/proc_pid_oom_score.5 create mode 100644 man/man5/proc_pid_oom_score_adj.5 create mode 100644 man/man5/proc_pid_pagemap.5 create mode 100644 man/man5/proc_pid_personality.5 create mode 100644 man/man5/proc_pid_projid_map.5 create mode 100644 man/man5/proc_pid_root.5 create mode 100644 man/man5/proc_pid_seccomp.5 create mode 100644 man/man5/proc_pid_setgroups.5 create mode 100644 man/man5/proc_pid_smaps.5 create mode 100644 man/man5/proc_pid_stack.5 create mode 100644 man/man5/proc_pid_stat.5 create mode 100644 man/man5/proc_pid_statm.5 create mode 100644 man/man5/proc_pid_status.5 create mode 100644 man/man5/proc_pid_syscall.5 create mode 100644 man/man5/proc_pid_task.5 create mode 100644 man/man5/proc_pid_timers.5 create mode 100644 man/man5/proc_pid_timerslack_ns.5 create mode 100644 man/man5/proc_pid_uid_map.5 create mode 100644 man/man5/proc_pid_wchan.5 create mode 100644 man/man5/proc_profile.5 create mode 100644 man/man5/proc_scsi.5 create mode 100644 man/man5/proc_self.5 create mode 100644 man/man5/proc_slabinfo.5 create mode 100644 man/man5/proc_stat.5 create mode 100644 man/man5/proc_swaps.5 create mode 100644 man/man5/proc_sys.5 create mode 100644 man/man5/proc_sys_abi.5 create mode 100644 man/man5/proc_sys_debug.5 create mode 100644 man/man5/proc_sys_dev.5 create mode 100644 man/man5/proc_sys_fs.5 create mode 100644 man/man5/proc_sys_kernel.5 create mode 100644 man/man5/proc_sys_net.5 create mode 100644 man/man5/proc_sys_proc.5 create mode 100644 man/man5/proc_sys_sunrpc.5 create mode 100644 man/man5/proc_sys_user.5 create mode 100644 man/man5/proc_sys_vm.5 create mode 100644 man/man5/proc_sysrq-trigger.5 create mode 100644 man/man5/proc_sysvipc.5 create mode 100644 man/man5/proc_thread-self.5 create mode 100644 man/man5/proc_tid.5 create mode 100644 man/man5/proc_tid_children.5 create mode 100644 man/man5/proc_timer_list.5 create mode 100644 man/man5/proc_timer_stats.5 create mode 100644 man/man5/proc_tty.5 create mode 100644 man/man5/proc_uptime.5 create mode 100644 man/man5/proc_version.5 create mode 100644 man/man5/proc_vmstat.5 create mode 100644 man/man5/proc_zoneinfo.5 create mode 100644 man/man5/procfs.5 create mode 100644 man/man5/protocols.5 create mode 100644 man/man5/repertoiremap.5 create mode 100644 man/man5/resolv.conf.5 create mode 100644 man/man5/resolver.5 create mode 100644 man/man5/rpc.5 create mode 100644 man/man5/securetty.5 create mode 100644 man/man5/services.5 create mode 100644 man/man5/shells.5 create mode 100644 man/man5/slabinfo.5 create mode 100644 man/man5/sysfs.5 create mode 100644 man/man5/termcap.5 create mode 100644 man/man5/tmpfs.5 create mode 100644 man/man5/ttytype.5 create mode 100644 man/man5/tzfile.5 create mode 100644 man/man5/utmp.5 create mode 100644 man/man5/utmpx.5 create mode 100644 man/man5/wtmp.5 create mode 100644 man/man6/intro.6 create mode 100644 man/man7/address_families.7 create mode 100644 man/man7/aio.7 create mode 100644 man/man7/armscii-8.7 create mode 100644 man/man7/arp.7 create mode 100644 man/man7/ascii.7 create mode 100644 man/man7/attributes.7 create mode 100644 man/man7/boot.7 create mode 100644 man/man7/bootparam.7 create mode 100644 man/man7/bpf-helpers.7 create mode 100644 man/man7/capabilities.7 create mode 100644 man/man7/cgroup_namespaces.7 create mode 100644 man/man7/cgroups.7 create mode 100644 man/man7/charsets.7 create mode 100644 man/man7/complex.7 create mode 100644 man/man7/cp1251.7 create mode 100644 man/man7/cp1252.7 create mode 100644 man/man7/cpuset.7 create mode 100644 man/man7/credentials.7 create mode 100644 man/man7/ddp.7 create mode 100644 man/man7/environ.7 create mode 100644 man/man7/epoll.7 create mode 100644 man/man7/fanotify.7 create mode 100644 man/man7/feature_test_macros.7 create mode 100644 man/man7/fifo.7 create mode 100644 man/man7/futex.7 create mode 100644 man/man7/glibc.7 create mode 100644 man/man7/glob.7 create mode 100644 man/man7/hier.7 create mode 100644 man/man7/hostname.7 create mode 100644 man/man7/icmp.7 create mode 100644 man/man7/inode.7 create mode 100644 man/man7/inotify.7 create mode 100644 man/man7/intro.7 create mode 100644 man/man7/ip.7 create mode 100644 man/man7/ipc_namespaces.7 create mode 100644 man/man7/ipv6.7 create mode 100644 man/man7/iso-8859-1.7 create mode 100644 man/man7/iso-8859-10.7 create mode 100644 man/man7/iso-8859-11.7 create mode 100644 man/man7/iso-8859-13.7 create mode 100644 man/man7/iso-8859-14.7 create mode 100644 man/man7/iso-8859-15.7 create mode 100644 man/man7/iso-8859-16.7 create mode 100644 man/man7/iso-8859-2.7 create mode 100644 man/man7/iso-8859-3.7 create mode 100644 man/man7/iso-8859-4.7 create mode 100644 man/man7/iso-8859-5.7 create mode 100644 man/man7/iso-8859-6.7 create mode 100644 man/man7/iso-8859-7.7 create mode 100644 man/man7/iso-8859-8.7 create mode 100644 man/man7/iso-8859-9.7 create mode 100644 man/man7/iso_8859-1.7 create mode 100644 man/man7/iso_8859-10.7 create mode 100644 man/man7/iso_8859-11.7 create mode 100644 man/man7/iso_8859-13.7 create mode 100644 man/man7/iso_8859-14.7 create mode 100644 man/man7/iso_8859-15.7 create mode 100644 man/man7/iso_8859-16.7 create mode 100644 man/man7/iso_8859-2.7 create mode 100644 man/man7/iso_8859-3.7 create mode 100644 man/man7/iso_8859-4.7 create mode 100644 man/man7/iso_8859-5.7 create mode 100644 man/man7/iso_8859-6.7 create mode 100644 man/man7/iso_8859-7.7 create mode 100644 man/man7/iso_8859-8.7 create mode 100644 man/man7/iso_8859-9.7 create mode 100644 man/man7/iso_8859_1.7 create mode 100644 man/man7/iso_8859_10.7 create mode 100644 man/man7/iso_8859_11.7 create mode 100644 man/man7/iso_8859_13.7 create mode 100644 man/man7/iso_8859_14.7 create mode 100644 man/man7/iso_8859_15.7 create mode 100644 man/man7/iso_8859_16.7 create mode 100644 man/man7/iso_8859_2.7 create mode 100644 man/man7/iso_8859_3.7 create mode 100644 man/man7/iso_8859_4.7 create mode 100644 man/man7/iso_8859_5.7 create mode 100644 man/man7/iso_8859_6.7 create mode 100644 man/man7/iso_8859_7.7 create mode 100644 man/man7/iso_8859_8.7 create mode 100644 man/man7/iso_8859_9.7 create mode 100644 man/man7/kernel_lockdown.7 create mode 100644 man/man7/keyrings.7 create mode 100644 man/man7/koi8-r.7 create mode 100644 man/man7/koi8-u.7 create mode 100644 man/man7/landlock.7 create mode 100644 man/man7/latin1.7 create mode 100644 man/man7/latin10.7 create mode 100644 man/man7/latin2.7 create mode 100644 man/man7/latin3.7 create mode 100644 man/man7/latin4.7 create mode 100644 man/man7/latin5.7 create mode 100644 man/man7/latin6.7 create mode 100644 man/man7/latin7.7 create mode 100644 man/man7/latin8.7 create mode 100644 man/man7/latin9.7 create mode 100644 man/man7/libc.7 create mode 100644 man/man7/locale.7 create mode 100644 man/man7/mailaddr.7 create mode 100644 man/man7/man-pages.7 create mode 100644 man/man7/man.7 create mode 100644 man/man7/math_error.7 create mode 100644 man/man7/mount_namespaces.7 create mode 100644 man/man7/mq_overview.7 create mode 100644 man/man7/namespaces.7 create mode 100644 man/man7/netdevice.7 create mode 100644 man/man7/netlink.7 create mode 100644 man/man7/network_namespaces.7 create mode 100644 man/man7/nptl.7 create mode 100644 man/man7/numa.7 create mode 100644 man/man7/operator.7 create mode 100644 man/man7/packet.7 create mode 100644 man/man7/path_resolution.7 create mode 100644 man/man7/persistent-keyring.7 create mode 100644 man/man7/pid_namespaces.7 create mode 100644 man/man7/pipe.7 create mode 100644 man/man7/pkeys.7 create mode 100644 man/man7/posixoptions.7 create mode 100644 man/man7/precedence.7 create mode 100644 man/man7/process-keyring.7 create mode 100644 man/man7/pthreads.7 create mode 100644 man/man7/pty.7 create mode 100644 man/man7/queue.7 create mode 100644 man/man7/random.7 create mode 100644 man/man7/raw.7 create mode 100644 man/man7/regex.7 create mode 100644 man/man7/rtld-audit.7 create mode 100644 man/man7/rtnetlink.7 create mode 100644 man/man7/sched.7 create mode 100644 man/man7/sem_overview.7 create mode 100644 man/man7/session-keyring.7 create mode 100644 man/man7/shm_overview.7 create mode 100644 man/man7/sigevent.7 create mode 100644 man/man7/signal-safety.7 create mode 100644 man/man7/signal.7 create mode 100644 man/man7/sock_diag.7 create mode 100644 man/man7/socket.7 create mode 100644 man/man7/spufs.7 create mode 100644 man/man7/standards.7 create mode 100644 man/man7/string_copying.7 create mode 100644 man/man7/suffixes.7 create mode 100644 man/man7/svipc.7 create mode 100644 man/man7/symlink.7 create mode 100644 man/man7/system_data_types.7 create mode 100644 man/man7/sysvipc.7 create mode 100644 man/man7/tcp.7 create mode 100644 man/man7/termio.7 create mode 100644 man/man7/thread-keyring.7 create mode 100644 man/man7/time.7 create mode 100644 man/man7/time_namespaces.7 create mode 100644 man/man7/tis-620.7 create mode 100644 man/man7/udp.7 create mode 100644 man/man7/udplite.7 create mode 100644 man/man7/unicode.7 create mode 100644 man/man7/units.7 create mode 100644 man/man7/unix.7 create mode 100644 man/man7/uri.7 create mode 100644 man/man7/url.7 create mode 100644 man/man7/urn.7 create mode 100644 man/man7/user-keyring.7 create mode 100644 man/man7/user-session-keyring.7 create mode 100644 man/man7/user_namespaces.7 create mode 100644 man/man7/utf-8.7 create mode 100644 man/man7/utf8.7 create mode 100644 man/man7/uts_namespaces.7 create mode 100644 man/man7/vdso.7 create mode 100644 man/man7/vsock.7 create mode 100644 man/man7/x25.7 create mode 100644 man/man7/xattr.7 create mode 100644 man/man8/iconvconfig.8 create mode 100644 man/man8/intro.8 create mode 100644 man/man8/ld-linux.8 create mode 100644 man/man8/ld-linux.so.8 create mode 100644 man/man8/ld.so.8 create mode 100644 man/man8/ldconfig.8 create mode 100644 man/man8/nscd.8 create mode 100644 man/man8/sln.8 create mode 100644 man/man8/tzselect.8 create mode 100644 man/man8/zdump.8 create mode 100644 man/man8/zic.8 (limited to 'man') diff --git a/man/man1/getent.1 b/man/man1/getent.1 new file mode 100644 index 0000000..98032ea --- /dev/null +++ b/man/man1/getent.1 @@ -0,0 +1,387 @@ +.\" Copyright (c) 2011, Mark R. Bannister +.\" Copyright (c) 2015, Robin H. Johnson +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH getent 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getent \- get entries from Name Service Switch libraries +.SH SYNOPSIS +.nf +.B getent [\fIoption\fP]... \fIdatabase\fP \fIkey\fP... +.fi +.SH DESCRIPTION +The +.B getent +command displays entries from databases supported by the +Name Service Switch libraries, +which are configured in +.IR /etc/nsswitch.conf . +If one or more +.I key +arguments are provided, +then only the entries that match the supplied keys will be displayed. +Otherwise, if no +.I key +is provided, all entries will be displayed (unless the database does not +support enumeration). +.P +The +.I database +may be any of those supported by the GNU C Library, listed below: +.TP +.B ahosts +When no +.I key +is provided, use +.BR sethostent (3), +.BR gethostent (3), +and +.BR endhostent (3) +to enumerate the hosts database. +This is identical to using +.BR hosts (5). +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getaddrinfo (3) +with the address family +.BR AF_UNSPEC , +enumerating each socket address structure returned. +.TP +.B ahostsv4 +Same as +.BR ahosts , +but use the address family +.BR AF_INET . +.TP +.B ahostsv6 +Same as +.BR ahosts , +but use the address family +.BR AF_INET6 . +The call to +.BR getaddrinfo (3) +in this case includes the +.B AI_V4MAPPED +flag. +.TP +.B aliases +When no +.I key +is provided, use +.BR setaliasent (3), +.BR getaliasent (3), +and +.BR endaliasent (3) +to enumerate the aliases database. +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getaliasbyname (3) +and display the result. +.TP +.B ethers +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR ether_aton (3) +and +.BR ether_hostton (3) +until a result is obtained, and display the result. +Enumeration is not supported on +.BR ethers , +so a +.I key +must be provided. +.TP +.B group +When no +.I key +is provided, use +.BR setgrent (3), +.BR getgrent (3), +and +.BR endgrent (3) +to enumerate the group database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getgrgid (3) +and each nonnumeric +.I key +to +.BR getgrnam (3) +and display the result. +.TP +.B gshadow +When no +.I key +is provided, use +.BR setsgent (3), +.BR getsgent (3), +and +.BR endsgent (3) +to enumerate the gshadow database. +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getsgnam (3) +and display the result. +.TP +.B hosts +When no +.I key +is provided, use +.BR sethostent (3), +.BR gethostent (3), +and +.BR endhostent (3) +to enumerate the hosts database. +When one or more +.I key +arguments are provided, pass each +.I key +to +.BR gethostbyaddr (3) +or +.BR gethostbyname2 (3), +depending on whether a call to +.BR inet_pton (3) +indicates that the +.I key +is an IPv6 or IPv4 address or not, and display the result. +.TP +.B initgroups +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getgrouplist (3) +and display the result. +Enumeration is not supported on +.BR initgroups , +so a +.I key +must be provided. +.TP +.B netgroup +When one +.I key +is provided, pass the +.I key +to +.BR setnetgrent (3) +and, using +.BR getnetgrent (3) +display the resulting string triple +.RI ( hostname ", " username ", " domainname ). +Alternatively, three +.I keys +may be provided, which are interpreted as the +.IR hostname , +.IR username , +and +.I domainname +to match to a netgroup name via +.BR innetgr (3). +Enumeration is not supported on +.BR netgroup , +so either one or three +.I keys +must be provided. +.TP +.B networks +When no +.I key +is provided, use +.BR setnetent (3), +.BR getnetent (3), +and +.BR endnetent (3) +to enumerate the networks database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getnetbyaddr (3) +and each nonnumeric +.I key +to +.BR getnetbyname (3) +and display the result. +.TP +.B passwd +When no +.I key +is provided, use +.BR setpwent (3), +.BR getpwent (3), +and +.BR endpwent (3) +to enumerate the passwd database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getpwuid (3) +and each nonnumeric +.I key +to +.BR getpwnam (3) +and display the result. +.TP +.B protocols +When no +.I key +is provided, use +.BR setprotoent (3), +.BR getprotoent (3), +and +.BR endprotoent (3) +to enumerate the protocols database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getprotobynumber (3) +and each nonnumeric +.I key +to +.BR getprotobyname (3) +and display the result. +.TP +.B rpc +When no +.I key +is provided, use +.BR setrpcent (3), +.BR getrpcent (3), +and +.BR endrpcent (3) +to enumerate the rpc database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getrpcbynumber (3) +and each nonnumeric +.I key +to +.BR getrpcbyname (3) +and display the result. +.TP +.B services +When no +.I key +is provided, use +.BR setservent (3), +.BR getservent (3), +and +.BR endservent (3) +to enumerate the services database. +When one or more +.I key +arguments are provided, pass each numeric +.I key +to +.BR getservbynumber (3) +and each nonnumeric +.I key +to +.BR getservbyname (3) +and display the result. +.TP +.B shadow +When no +.I key +is provided, use +.BR setspent (3), +.BR getspent (3), +and +.BR endspent (3) +to enumerate the shadow database. +When one or more +.I key +arguments are provided, pass each +.I key +in succession to +.BR getspnam (3) +and display the result. +.SH OPTIONS +.TP +.BI \-\-service\~ service +.TQ +.BI \-s\~ service +.\" commit 9d0881aa76b399e6a025c5cf44bebe2ae0efa8af (glibc) +Override all databases with the specified service. +(Since glibc 2.2.5.) +.TP +.BI \-\-service\~ database : service +.TQ +.BI \-s\~ database : service +.\" commit b4f6f4be85d32b9c03361c38376e36f08100e3e8 (glibc) +Override only specified databases with the specified service. +The option may be used multiple times, +but only the last service for each database will be used. +(Since glibc 2.4.) +.TP +.B \-\-no\-idn +.TQ +.B \-i +.\" commit a160f8d808cf8020b13bd0ef4a9eaf3c11f964ad (glibc) +Disables IDN encoding in lookups for +.BR ahosts / getaddrinfo (3) +(Since glibc-2.13.) +.TP +.B \-\-help +.TQ +.B \-? +Print a usage summary and exit. +.TP +.B \-\-usage +Print a short usage summary and exit. +.TP +.B \-\-version +.TQ +.B \-V +Print the version number, license, and disclaimer of warranty for +.BR getent . +.SH EXIT STATUS +One of the following exit values can be returned by +.BR getent : +.TP +.B 0 +Command completed successfully. +.TP +.B 1 +Missing arguments, or +.I database +unknown. +.TP +.B 2 +One or more supplied +.I key +could not be found in the +.IR database . +.TP +.B 3 +Enumeration not supported on this +.IR database . +.SH SEE ALSO +.BR nsswitch.conf (5) diff --git a/man/man1/iconv.1 b/man/man1/iconv.1 new file mode 100644 index 0000000..15c5471 --- /dev/null +++ b/man/man1/iconv.1 @@ -0,0 +1,204 @@ +.\" Copyright (C) 2014 Marko Myllynen +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH iconv 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iconv \- convert text from one character encoding to another +.SH SYNOPSIS +.B iconv +.RI [ options ] +.RI "[\-f " from-encoding "]" +.RI "[\-t " to-encoding "]" +.RI [ inputfile ]... +.SH DESCRIPTION +The +.B iconv +program reads in text in one encoding and outputs the text in another +encoding. +If no input files are given, or if it is given as a dash (\-), +.B iconv +reads from standard input. +If no output file is given, +.B iconv +writes to standard output. +.P +If no +.I from-encoding +is given, the default is derived +from the current locale's character encoding. +If no +.I to-encoding +is given, the default is derived +from the current locale's character +encoding. +.SH OPTIONS +.TP +.BI \-\-from\-code= from-encoding +.TQ +.BI \-f\~ from-encoding +Use +.I from-encoding +for input characters. +.TP +.BI \-\-to\-code= to-encoding +.TQ +.BI \-t\~ to-encoding +Use +.I to-encoding +for output characters. +.IP +If the string +.B //IGNORE +is appended to +.IR to-encoding , +characters that cannot be converted are discarded and an error is +printed after conversion. +.IP +If the string +.B //TRANSLIT +is appended to +.IR to-encoding , +characters being converted are transliterated when needed and possible. +This means that when a character cannot be represented in the target +character set, it can be approximated through one or several similar +looking characters. +Characters that are outside of the target character set and cannot be +transliterated are replaced with a question mark (?) in the output. +.TP +.B \-\-list +.TQ +.B \-l +List all known character set encodings. +.TP +.B \-c +Silently discard characters that cannot be converted instead of +terminating when encountering such characters. +.TP +.BI \-\-output= outputfile +.TQ +.BI \-o\~ outputfile +Use +.I outputfile +for output. +.TP +.B \-\-silent +.TQ +.B \-s +This option is ignored; it is provided only for compatibility. +.TP +.B \-\-verbose +Print progress information on standard error when processing +multiple files. +.TP +.B \-\-help +.TQ +.B \-? +Print a usage summary and exit. +.TP +.B \-\-usage +Print a short usage summary and exit. +.TP +.B \-\-version +.TQ +.B \-V +Print the version number, license, and disclaimer of warranty for +.BR iconv . +.SH EXIT STATUS +Zero on success, nonzero on errors. +.SH ENVIRONMENT +Internally, the +.B iconv +program uses the +.BR iconv (3) +function which in turn uses +.I gconv +modules (dynamically loaded shared libraries) +to convert to and from a character set. +Before calling +.BR iconv (3), +the +.B iconv +program must first allocate a conversion descriptor using +.BR iconv_open (3). +The operation of the latter function is influenced by the setting of the +.B GCONV_PATH +environment variable: +.IP \[bu] 3 +If +.B GCONV_PATH +is not set, +.BR iconv_open (3) +loads the system gconv module configuration cache file created by +.BR iconvconfig (8) +and then, based on the configuration, +loads the gconv modules needed to perform the conversion. +If the system gconv module configuration cache file is not available +then the system gconv module configuration file is used. +.IP \[bu] +If +.B GCONV_PATH +is defined (as a colon-separated list of pathnames), +the system gconv module configuration cache is not used. +Instead, +.BR iconv_open (3) +first tries to load the configuration files by searching the directories in +.B GCONV_PATH +in order, +followed by the system default gconv module configuration file. +If a directory does not contain a gconv module configuration file, +any gconv modules that it may contain are ignored. +If a directory contains a gconv module configuration file +and it is determined that a module needed for this conversion is +available in the directory, +then the needed module is loaded from that directory, +the order being such that the first suitable module found in +.B GCONV_PATH +is used. +This allows users to use custom modules and even replace system-provided +modules by providing such modules in +.B GCONV_PATH +directories. +.SH FILES +.TP +.I /usr/lib/gconv +Usual default gconv module path. +.TP +.I /usr/lib/gconv/gconv\-modules +Usual system default gconv module configuration file. +.TP +.I /usr/lib/gconv/gconv\-modules.cache +Usual system gconv module configuration cache. +.P +Depending on the architecture, +the above files may instead be located at directories with the path prefix +.IR /usr/lib64 . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +Convert text from the ISO/IEC\~8859-15 character encoding to UTF-8: +.P +.in +4n +.EX +$ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP +.EE +.in +.P +The next example converts from UTF-8 to ASCII, transliterating when +possible: +.P +.in +4n +.EX +$ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP +abc ss ? EUR abc +.EE +.in +.SH SEE ALSO +.BR locale (1), +.BR uconv (1), +.BR iconv (3), +.BR nl_langinfo (3), +.BR charsets (7), +.BR iconvconfig (8) diff --git a/man/man1/intro.1 b/man/man1/intro.1 new file mode 100644 index 0000000..9f5502a --- /dev/null +++ b/man/man1/intro.1 @@ -0,0 +1,305 @@ +.\" Copyright (c) 2002 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH intro 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intro \- introduction to user commands +.SH DESCRIPTION +Section 1 of the manual describes user commands and tools, +for example, file manipulation tools, shells, compilers, +web browsers, file and image viewers and editors, and so on. +.SH NOTES +Linux is a flavor of UNIX, and as a first approximation +all user commands under UNIX work precisely the same under +Linux (and FreeBSD and lots of other UNIX-like systems). +.P +Under Linux, there are GUIs (graphical user interfaces), where you +can point and click and drag, and hopefully get work done without +first reading lots of documentation. +The traditional UNIX environment +is a CLI (command line interface), where you type commands to +tell the computer what to do. +That is faster and more powerful, +but requires finding out what the commands are. +Below a bare minimum, to get started. +.SS Login +In order to start working, you probably first have to open a session by +giving your username and password. +The program +.BR login (1) +now starts a +.I shell +(command interpreter) for you. +In case of a graphical login, you get a screen with menus or icons +and a mouse click will start a shell in a window. +See also +.BR xterm (1). +.SS The shell +One types commands to the +.IR shell , +the command interpreter. +It is not built-in, but is just a program +and you can change your shell. +Everybody has their own favorite one. +The standard one is called +.IR sh . +See also +.BR ash (1), +.BR bash (1), +.BR chsh (1), +.BR csh (1), +.BR dash (1), +.BR ksh (1), +.BR zsh (1). +.P +A session might go like: +.P +.in +4n +.EX +.RB "knuth login: " aeb +.RB "Password: " ******** +.RB "$ " date +Tue Aug 6 23:50:44 CEST 2002 +.RB "$ " cal + August 2002 +Su Mo Tu We Th Fr Sa + 1 2 3 + 4 5 6 7 8 9 10 +11 12 13 14 15 16 17 +18 19 20 21 22 23 24 +25 26 27 28 29 30 31 +\& +.RB "$ " ls +bin tel +.RB "$ " "ls \-l" +total 2 +drwxrwxr\-x 2 aeb 1024 Aug 6 23:51 bin +\-rw\-rw\-r\-\- 1 aeb 37 Aug 6 23:52 tel +.RB "$ " "cat tel" +maja 0501\-1136285 +peter 0136\-7399214 +.RB "$ " "cp tel tel2" +.RB "$ " "ls \-l" +total 3 +drwxr\-xr\-x 2 aeb 1024 Aug 6 23:51 bin +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:52 tel +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:53 tel2 +.RB "$ " "mv tel tel1" +.RB "$ " "ls \-l" +total 3 +drwxr\-xr\-x 2 aeb 1024 Aug 6 23:51 bin +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:52 tel1 +\-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:53 tel2 +.RB "$ " "diff tel1 tel2" +.RB "$ " "rm tel1" +.RB "$ " "grep maja tel2" +maja 0501\-1136285 +$ +.EE +.in +.P +Here typing Control-D ended the session. +.P +The +.B $ +here was the command prompt\[em]it is the shell's way of indicating +that it is ready for the next command. +The prompt can be customized +in lots of ways, and one might include stuff like username, +machine name, current directory, time, and so on. +An assignment PS1="What next, master? " +would change the prompt as indicated. +.P +We see that there are commands +.I date +(that gives date and time), and +.I cal +(that gives a calendar). +.P +The command +.I ls +lists the contents of the current directory\[em]it tells you what +files you have. +With a +.I \-l +option it gives a long listing, +that includes the owner and size and date of the file, and the +permissions people have for reading and/or changing the file. +For example, the file "tel" here is 37 bytes long, owned by aeb +and the owner can read and write it, others can only read it. +Owner and permissions can be changed by the commands +.I chown +and +.IR chmod . +.P +The command +.I cat +will show the contents of a file. +(The name is from "concatenate and print": all files given as +parameters are concatenated and sent to "standard output" +(see +.BR stdout (3)), +here +the terminal screen.) +.P +The command +.I cp +(from "copy") will copy a file. +.P +The command +.I mv +(from "move"), on the other hand, only renames it. +.P +The command +.I diff +lists the differences between two files. +Here there was no output because there were no differences. +.P +The command +.I rm +(from "remove") deletes the file, and be careful! it is gone. +No wastepaper basket or anything. +Deleted means lost. +.P +The command +.I grep +(from "g/re/p") finds occurrences of a string in one or more files. +Here it finds Maja's telephone number. +.SS Pathnames and the current directory +Files live in a large tree, the file hierarchy. +Each has a +.I "pathname" +describing the path from the root of the tree (which is called +.IR / ) +to the file. +For example, such a full pathname might be +.IR /home/aeb/tel . +Always using full pathnames would be inconvenient, and the name +of a file in the current directory may be abbreviated by giving +only the last component. +That is why +.I /home/aeb/tel +can be abbreviated +to +.I tel +when the current directory is +.IR /home/aeb . +.P +The command +.I pwd +prints the current directory. +.P +The command +.I cd +changes the current directory. +.P +Try alternatively +.I cd +and +.I pwd +commands and explore +.I cd +usage: "cd", "cd .", "cd ..", "cd /", and "cd \[ti]". +.SS Directories +The command +.I mkdir +makes a new directory. +.P +The command +.I rmdir +removes a directory if it is empty, and complains otherwise. +.P +The command +.I find +(with a rather baroque syntax) will find files with given name +or other properties. +For example, "find . \-name tel" would find +the file +.I tel +starting in the present directory (which is called +.IR . ). +And "find / \-name tel" would do the same, but starting at the root +of the tree. +Large searches on a multi-GB disk will be time-consuming, +and it may be better to use +.BR locate (1). +.SS Disks and filesystems +The command +.I mount +will attach the filesystem found on some disk (or floppy, or CDROM or so) +to the big filesystem hierarchy. +And +.I umount +detaches it again. +The command +.I df +will tell you how much of your disk is still free. +.SS Processes +On a UNIX system many user and system processes run simultaneously. +The one you are talking to runs in the +.IR foreground , +the others in the +.IR background . +The command +.I ps +will show you which processes are active and what numbers these +processes have. +The command +.I kill +allows you to get rid of them. +Without option this is a friendly +request: please go away. +And "kill \-9" followed by the number +of the process is an immediate kill. +Foreground processes can often be killed by typing Control-C. +.SS Getting information +There are thousands of commands, each with many options. +Traditionally commands are documented on +.IR "man pages" , +(like this one), so that the command "man kill" will document +the use of the command "kill" (and "man man" document the command "man"). +The program +.I man +sends the text through some +.IR pager , +usually +.IR less . +Hit the space bar to get the next page, hit q to quit. +.P +In documentation it is customary to refer to man pages +by giving the name and section number, as in +.BR man (1). +Man pages are terse, and allow you to find quickly some forgotten +detail. +For newcomers an introductory text with more examples +and explanations is useful. +.P +A lot of GNU/FSF software is provided with info files. +Type "info info" +for an introduction on the use of the program +.IR info . +.P +Special topics are often treated in HOWTOs. +Look in +.I /usr/share/doc/howto/en +and use a browser if you find HTML files there. +.\" +.\" Actual examples? Separate section for each of cat, cp, ...? +.\" gzip, bzip2, tar, rpm +.SH SEE ALSO +.BR ash (1), +.BR bash (1), +.BR chsh (1), +.BR csh (1), +.BR dash (1), +.BR ksh (1), +.BR locate (1), +.BR login (1), +.BR man (1), +.BR xterm (1), +.BR zsh (1), +.BR wait (2), +.BR stdout (3), +.BR man\-pages (7), +.BR standards (7) diff --git a/man/man1/ldd.1 b/man/man1/ldd.1 new file mode 100644 index 0000000..8f97777 --- /dev/null +++ b/man/man1/ldd.1 @@ -0,0 +1,180 @@ +.\" Copyright 1995-2000 David Engel (david@ods.com) +.\" Copyright 1995 Rickard E. Faith (faith@cs.unc.edu) +.\" Copyright 2000 Ben Collins (bcollins@debian.org) +.\" Redone for glibc 2.2 +.\" Copyright 2000 Jakub Jelinek (jakub@redhat.com) +.\" Corrected. +.\" and Copyright (C) 2012, 2016, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ldd 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ldd \- print shared object dependencies +.SH SYNOPSIS +.nf +.BR ldd " [\fIoption\fP]... \fIfile\fP..." +.fi +.SH DESCRIPTION +.B ldd +prints the shared objects (shared libraries) required by each program or +shared object specified on the command line. +An example of its use and output +is the following: +.P +.in +4n +.EX +$ \fBldd /bin/ls\fP + linux\-vdso.so.1 (0x00007ffcc3563000) + libselinux.so.1 => /lib64/libselinux.so.1 (0x00007f87e5459000) + libcap.so.2 => /lib64/libcap.so.2 (0x00007f87e5254000) + libc.so.6 => /lib64/libc.so.6 (0x00007f87e4e92000) + libpcre.so.1 => /lib64/libpcre.so.1 (0x00007f87e4c22000) + libdl.so.2 => /lib64/libdl.so.2 (0x00007f87e4a1e000) + /lib64/ld\-linux\-x86\-64.so.2 (0x00005574bf12e000) + libattr.so.1 => /lib64/libattr.so.1 (0x00007f87e4817000) + libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f87e45fa000) +.EE +.in +.P +In the usual case, +.B ldd +invokes the standard dynamic linker (see +.BR ld.so (8)) +with the +.B LD_TRACE_LOADED_OBJECTS +environment variable set to 1. +This causes the dynamic linker to inspect the program's dynamic dependencies, +and find (according to the rules described in +.BR ld.so (8)) +and load the objects that satisfy those dependencies. +For each dependency, +.B ldd +displays the location of the matching object +and the (hexadecimal) address at which it is loaded. +(The +.I linux\-vdso +and +.I ld\-linux +shared dependencies are special; see +.BR vdso (7) +and +.BR ld.so (8).) +.\" +.SS Security +Be aware that in some circumstances +(e.g., where the program specifies an ELF interpreter other than +.IR ld\-linux.so ), +.\" The circumstances are where the program has an interpreter +.\" other than ld-linux.so. In this case, ldd tries to execute the +.\" program directly with LD_TRACE_LOADED_OBJECTS=1, with the +.\" result that the program interpreter gets control, and can do +.\" what it likes, or pass control to the program itself. +.\" Much more detail at +.\" http://www.catonmat.net/blog/ldd-arbitrary-code-execution/ +some versions of +.B ldd +may attempt to obtain the dependency information +by attempting to directly execute the program, +which may lead to the execution of whatever code is defined +in the program's ELF interpreter, +and perhaps to execution of the program itself. +.\" Mainline glibc's ldd allows this possibility (the line +.\" try_trace "$file" +.\" in glibc 2.15, for example), but many distro versions of +.\" ldd seem to remove that code path from the script. +(Before glibc 2.27, +.\" glibc commit eedca9772e99c72ab4c3c34e43cc764250aa3e3c +the upstream +.B ldd +implementation did this for example, +although most distributions provided a modified version that did not.) +.P +Thus, you should +.I never +employ +.B ldd +on an untrusted executable, +since this may result in the execution of arbitrary code. +A safer alternative when dealing with untrusted executables is: +.P +.in +4n +.EX +$ \fBobjdump \-p /path/to/program | grep NEEDED\fP +.EE +.in +.P +Note, however, that this alternative shows only the direct dependencies +of the executable, while +.B ldd +shows the entire dependency tree of the executable. +.SH OPTIONS +.TP +.B \-\-version +Print the version number of +.BR ldd . +.TP +.B \-\-verbose +.TQ +.B \-v +Print all information, including, for example, +symbol versioning information. +.TP +.B \-\-unused +.TQ +.B \-u +Print unused direct dependencies. +(Since glibc 2.3.4.) +.TP +.B \-\-data\-relocs +.TQ +.B \-d +Perform relocations and report any missing objects (ELF only). +.TP +.B \-\-function\-relocs +.TQ +.B \-r +Perform relocations for both data objects and functions, and +report any missing objects or functions (ELF only). +.TP +.B \-\-help +Usage information. +.\" .SH NOTES +.\" The standard version of +.\" .B ldd +.\" comes with glibc2. +.\" Libc5 came with an older version, still present +.\" on some systems. +.\" The long options are not supported by the libc5 version. +.\" On the other hand, the glibc2 version does not support +.\" .B \-V +.\" and only has the equivalent +.\" .BR \-\-version . +.\" .P +.\" The libc5 version of this program will use the name of a library given +.\" on the command line as-is when it contains a \[aq]/\[aq]; otherwise it +.\" searches for the library in the standard locations. +.\" To run it +.\" on a shared library in the current directory, prefix the name with "./". +.SH BUGS +.B ldd +does not work on a.out shared libraries. +.P +.B ldd +does not work with some extremely old a.out programs which were +built before +.B ldd +support was added to the compiler releases. +If you use +.B ldd +on one of these programs, the program will attempt to run with +.I argc += 0 and the results will be unpredictable. +.\" .SH AUTHOR +.\" David Engel. +.\" Roland McGrath and Ulrich Drepper. +.SH SEE ALSO +.BR pldd (1), +.BR sprof (1), +.BR ld.so (8), +.BR ldconfig (8) diff --git a/man/man1/locale.1 b/man/man1/locale.1 new file mode 100644 index 0000000..debe7ce --- /dev/null +++ b/man/man1/locale.1 @@ -0,0 +1,208 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH locale 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +locale \- get locale-specific information +.SH SYNOPSIS +.nf +.BR locale " [\fIoption\fP]" +.BR locale " [\fIoption\fP] " \-a +.BR locale " [\fIoption\fP] " \-m +.BR locale " [\fIoption\fP] \fIname\fP..." +.fi +.SH DESCRIPTION +The +.B locale +command displays information about the current locale, or all locales, +on standard output. +.P +When invoked without arguments, +.B locale +displays the current locale settings for each locale category (see +.BR locale (5)), +based on the settings of the environment variables that control the locale +(see +.BR locale (7)). +Values for variables set in the environment are printed without double +quotes, implied values are printed with double quotes. +.P +If either the +.B \-a +or the +.B \-m +option (or one of their long-format equivalents) is specified, +the behavior is as follows: +.TP +.B \-\-all\-locales +.TQ +.B \-a +Display a list of all available locales. +The +.B \-v +option causes the +.B LC_IDENTIFICATION +metadata about each locale to be included in the output. +.TP +.B \-\-charmaps +.TQ +.B \-m +Display the available charmaps (character set description files). +To display the current character set for the locale, use +\fBlocale \-c charmap\fR. +.P +The +.B locale +command can also be provided with one or more arguments, +which are the names of locale keywords (for example, +.IR date_fmt , +.IR ctype\-class\-names , +.IR yesexpr , +or +.IR decimal_point ) +or locale categories (for example, +.B LC_CTYPE +or +.BR LC_TIME ). +For each argument, the following is displayed: +.IP \[bu] 3 +For a locale keyword, the value of that keyword to be displayed. +.IP \[bu] +For a locale category, +the values of all keywords in that category are displayed. +.P +When arguments are supplied, the following options are meaningful: +.TP +.B \-\-category\-name +.TQ +.B \-c +For a category name argument, +write the name of the locale category +on a separate line preceding the list of keyword values for that category. +.IP +For a keyword name argument, +write the name of the locale category for this keyword +on a separate line preceding the keyword value. +.IP +This option improves readability when multiple name arguments are specified. +It can be combined with the +.B \-k +option. +.TP +.B \-\-keyword\-name +.TQ +.B \-k +For each keyword whose value is being displayed, +include also the name of that keyword, +so that the output has the format: +.IP +.in +4n +.EX +.IR keyword =\[dq] value \[dq] +.EE +.in +.P +The +.B locale +command also knows about the following options: +.TP +.B \-\-verbose +.TQ +.B \-v +Display additional information for some command-line option and argument +combinations. +.TP +.B \-\-help +.TQ +.B \-? +Display a summary of command-line options and arguments and exit. +.TP +.B \-\-usage +Display a short usage message and exit. +.TP +.B \-\-version +.TQ +.B \-V +Display the program version and exit. +.SH FILES +.TP +.I /usr/lib/locale/locale\-archive +Usual default locale archive location. +.TP +.I /usr/share/i18n/locales +Usual default path for locale definition files. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +.EX +$ \fBlocale\fP +LANG=en_US.UTF\-8 +LC_CTYPE="en_US.UTF\-8" +LC_NUMERIC="en_US.UTF\-8" +LC_TIME="en_US.UTF\-8" +LC_COLLATE="en_US.UTF\-8" +LC_MONETARY="en_US.UTF\-8" +LC_MESSAGES="en_US.UTF\-8" +LC_PAPER="en_US.UTF\-8" +LC_NAME="en_US.UTF\-8" +LC_ADDRESS="en_US.UTF\-8" +LC_TELEPHONE="en_US.UTF\-8" +LC_MEASUREMENT="en_US.UTF\-8" +LC_IDENTIFICATION="en_US.UTF\-8" +LC_ALL= +.P +$ \fBlocale date_fmt\fP +%a %b %e %H:%M:%S %Z %Y +.P +$ \fBlocale \-k date_fmt\fP +date_fmt="%a %b %e %H:%M:%S %Z %Y" +.P +$ \fBlocale \-ck date_fmt\fP +LC_TIME +date_fmt="%a %b %e %H:%M:%S %Z %Y" +.P +$ \fBlocale LC_TELEPHONE\fP ++%c (%a) %l +(%a) %l +11 +1 +UTF\-8 +.P +$ \fBlocale \-k LC_TELEPHONE\fP +tel_int_fmt="+%c (%a) %l" +tel_dom_fmt="(%a) %l" +int_select="11" +int_prefix="1" +telephone\-codeset="UTF\-8" +.EE +.P +The following example compiles a custom locale from the +.I ./wrk +directory with the +.BR localedef (1) +utility under the +.I $HOME/.locale +directory, then tests the result with the +.BR date (1) +command, and then sets the environment variables +.B LOCPATH +and +.B LANG +in the shell profile file so that the custom locale will be used in the +subsequent user sessions: +.P +.EX +$ \fBmkdir \-p $HOME/.locale\fP +$ \fBI18NPATH=./wrk/ localedef \-f UTF\-8 \-i fi_SE $HOME/.locale/fi_SE.UTF\-8\fP +$ \fBLOCPATH=$HOME/.locale LC_ALL=fi_SE.UTF\-8 date\fP +$ \fBecho "export LOCPATH=\e$HOME/.locale" >> $HOME/.bashrc\fP +$ \fBecho "export LANG=fi_SE.UTF\-8" >> $HOME/.bashrc\fP +.EE +.SH SEE ALSO +.BR localedef (1), +.BR charmap (5), +.BR locale (5), +.BR locale (7) diff --git a/man/man1/localedef.1 b/man/man1/localedef.1 new file mode 100644 index 0000000..f050592 --- /dev/null +++ b/man/man1/localedef.1 @@ -0,0 +1,415 @@ +.\" Copyright (C) 2001 Richard Braakman +.\" Copyright (C) 2004 Alastair McKinstry +.\" Copyright (C) 2005 Lars Wirzenius +.\" Copyright (C) 2014 Marko Myllynen +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" This manual page was initially written by Richard Braakman +.\" on behalf of the Debian GNU/Linux Project and anyone else +.\" who wants it. It was amended by Alastair McKinstry to +.\" explain new ISO/IEC 14652 elements, and amended further by +.\" Lars Wirzenius to document new functionality (as of GNU +.\" C library 2.3.5). +.\" +.TH localedef 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +localedef \- compile locale definition files +.SH SYNOPSIS +.SY localedef +.RI [ options ] +.I outputpath +.YS +.SY localedef +.B \-\-add\-to\-archive +.RI [ options ] +.I compiledpath +.YS +.SY localedef +.B \-\-delete\-from\-archive +.RI [ options ] +.IR localename " ..." +.YS +.SY localedef +.B \-\-list\-archive +.RI [ options ] +.YS +.SY localedef +.B \-\-help +.YS +.SY localedef +.B \-\-usage +.YS +.SY localedef +.B \-\-version +.YS +.SH DESCRIPTION +The +.B localedef +program reads the indicated +.I charmap +and +.I input +files, +compiles them to a binary form quickly usable by the +locale functions in the C library +.RB ( setlocale (3), +.BR localeconv (3), +etc.), +and places the output in +.IR outputpath . +.P +The +.I outputpath +argument is interpreted as follows: +.IP \[bu] 3 +If +.I outputpath +contains a slash character ('/'), +it is interpreted as the name of the +directory where the output definitions are to be stored. +In this case, +there is a separate output file for each locale category +.RI ( LC_TIME , +.IR LC_NUMERIC , +and so on). +.IP \[bu] +If the +.B \-\-no\-archive +option is used, +.I outputpath +is the name of a subdirectory in +.I /usr/lib/locale +where per-category compiled files are placed. +.IP \[bu] +Otherwise, +.I outputpath +is the name of a locale and the compiled locale data is added to the +archive file +.IR /usr/lib/locale/locale\-archive . +A locale archive is a memory-mapped file which contains all the +system-provided locales; +it is used by all localized programs when the environment variable +.B LOCPATH +is not set. +.P +In any case, +.B localedef +aborts if the directory in which it tries to write locale files has +not already been created. +.P +If no +.I charmapfile +is given, +the value +.I ANSI_X3.4\-1968 +(for ASCII) is used by default. +If no +.I inputfile +is given, +or if it is given as a dash +(\-), +.B localedef +reads from standard input. +.SH OPTIONS +.SS Operation-selection options +A few options direct +.B localedef +to do something other than compile locale definitions. +Only one of these options should be used at a time. +.TP +.B \-\-add\-to\-archive +Add the +.I compiledpath +directories to the locale archive file. +The directories should have been created by previous runs of +.BR localedef , +using +.BR \-\-no\-archive . +.TP +.B \-\-delete\-from\-archive +Delete the named locales from the locale archive file. +.TP +.B \-\-list\-archive +List the locales contained in the locale archive file. +.SS Other options +Some of the following options are sensible only for certain operations; +generally, +it should be self-evident which ones. +Notice that +.B \-f +and +.B \-c +are reversed from what you might expect; +that is, +.B \-f +is not the same as +.BR \-\-force . +.TP +.BI \-f " charmapfile" "\fR, \fP\-\-charmap=" charmapfile +Specify the file that defines the character set +that is used by the input file. +If +.I charmapfile +contains a slash character ('/'), +it is interpreted as the name of the character map. +Otherwise, +the file is sought in the current directory +and the default directory for character maps. +If the environment variable +.B I18NPATH +is set, +.I $I18NPATH/charmaps/ +and +.I $I18NPATH/ +are also searched after the current directory. +The default directory for character maps is printed by +.BR "localedef \-\-help" . +.TP +.BI \-i " inputfile" "\fR, \fP\-\-inputfile=" inputfile +Specify the locale definition file to compile. +The file is sought in the current directory +and the default directory for locale definition files. +If the environment variable +.B I18NPATH +is set, +.I $I18NPATH/locales/ +and +.I $I18NPATH +are also searched after the current directory. +The default directory for locale definition files is printed by +.BR "localedef \-\-help" . +.TP +.BI \-u " repertoirefile" "\fR, \fP\-\-repertoire\-map=" repertoirefile +Read mappings from symbolic names to Unicode code points from +.IR repertoirefile . +If +.I repertoirefile +contains a slash character ('/'), +it is interpreted as the pathname of the repertoire map. +Otherwise, +the file is sought in the current directory +and the default directory for repertoire maps. +If the environment variable +.B I18NPATH +is set, +.I $I18NPATH/repertoiremaps/ +and +.I $I18NPATH +are also searched after the current directory. +The default directory for repertoire maps is printed by +.BR "localedef \-\-help" . +.TP +.BI \-A " aliasfile" "\fR, \fP\-\-alias\-file=" aliasfile +Use +.I aliasfile +to look up aliases for locale names. +There is no default aliases file. +.TP +.B \-\-force +.TQ +.B \-c +Write the output files even if warnings were generated about the input +file. +.TP +.B \-\-verbose +.TQ +.B \-v +Generate extra warnings about errors that are normally ignored. +.TP +.B \-\-big\-endian +Generate big-endian output. +.TP +.B \-\-little\-endian +Generate little-endian output. +.TP +.B \-\-no\-archive +Do not use the locale archive file, +instead create +.I outputpath +as a subdirectory in the same directory as the locale archive file, +and create separate output files for locale categories in it. +This is helpful to prevent system locale archive updates from overwriting +custom locales created with +.BR localedef . +.TP +.B \-\-no\-hard\-links +Do not create hard links between installed locales. +.TP +.BI \-\-no\-warnings= warnings +Comma-separated list of warnings to disable. +Supported warnings are +.I ascii +and +.IR intcurrsym . +.TP +.B \-\-posix +Conform strictly to POSIX. +Implies +.BR \-\-verbose . +This option currently has no other effect. +POSIX conformance is assumed if the environment variable +.B POSIXLY_CORRECT +is set. +.TP +.BI \-\-prefix= pathname +Set the prefix to be prepended to the full archive pathname. +By default, +the prefix is empty. +Setting the prefix to +.IR foo , +the archive would be placed in +.IR foo/usr/lib/locale/locale\-archive . +.TP +.B \-\-quiet +Suppress all notifications and warnings, +and report only fatal errors. +.TP +.B \-\-replace +Replace a locale in the locale archive file. +Without this option, +if the locale is in the archive file already, +an error occurs. +.TP +.BI \-\-warnings= warnings +Comma-separated list of warnings to enable. +Supported warnings are +.I ascii +and +.IR intcurrsym . +.TP +.B \-\-help +.TQ +.B \-? +Print a usage summary and exit. +Also prints the default paths used by +.BR localedef . +.TP +.B \-\-usage +Print a short usage summary and exit. +.TP +.B \-\-version +.TQ +.B \-V +Print the version number, +license, +and disclaimer of warranty for +.BR localedef . +.SH EXIT STATUS +One of the following exit values can be returned by +.BR localedef : +.TP +.B 0 +Command completed successfully. +.TP +.B 1 +Warnings or errors occurred, +output files were written. +.TP +.B 4 +Errors encountered, +no output created. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +The +.B \-\-posix +flag is assumed if this environment variable is set. +.TP +.B I18NPATH +A colon-separated list of search directories for files. +.SH FILES +.TP +.I /usr/share/i18n/charmaps +Usual default character map path. +.TP +.I /usr/share/i18n/locales +Usual default path for locale definition files. +.TP +.I /usr/share/i18n/repertoiremaps +Usual default repertoire map path. +.TP +.I /usr/lib/locale/locale\-archive +Usual default locale archive location. +.TP +.I /usr/lib/locale +Usual default path for compiled individual locale data files. +.TP +.I outputpath/LC_ADDRESS +An output file that contains information about formatting of +addresses and geography-related items. +.TP +.I outputpath/LC_COLLATE +An output file that contains information about the rules for comparing +strings. +.TP +.I outputpath/LC_CTYPE +An output file that contains information about character classes. +.TP +.I outputpath/LC_IDENTIFICATION +An output file that contains metadata about the locale. +.TP +.I outputpath/LC_MEASUREMENT +An output file that contains information about locale measurements +(metric versus US customary). +.TP +.I outputpath/LC_MESSAGES/SYS_LC_MESSAGES +An output file that contains information about the language messages +should be printed in, +and what an affirmative or negative answer looks like. +.TP +.I outputpath/LC_MONETARY +An output file that contains information about formatting of monetary +values. +.TP +.I outputpath/LC_NAME +An output file that contains information about salutations for persons. +.TP +.I outputpath/LC_NUMERIC +An output file that contains information about formatting of nonmonetary +numeric values. +.TP +.I outputpath/LC_PAPER +An output file that contains information about settings related to +standard paper size. +.TP +.I outputpath/LC_TELEPHONE +An output file that contains information about formats to be used with +telephone services. +.TP +.I outputpath/LC_TIME +An output file that contains information about formatting of data and +time values. +.SH STANDARDS +POSIX.1-2008. +.SH EXAMPLES +Compile the locale files for Finnish in the UTF\-8 character set +and add it to the default locale archive with the name +.BR fi_FI.UTF\-8 : +.P +.in +4n +.EX +localedef \-f UTF\-8 \-i fi_FI fi_FI.UTF\-8 +.EE +.in +.P +The next example does the same thing, +but generates files into the +.I fi_FI.UTF\-8 +directory which can then be used by programs when the environment +variable +.B LOCPATH +is set to the current directory (note that the last argument must +contain a slash): +.P +.in +4n +.EX +localedef \-f UTF\-8 \-i fi_FI ./fi_FI.UTF\-8 +.EE +.in +.SH SEE ALSO +.BR locale (1), +.BR charmap (5), +.BR locale (5), +.BR repertoiremap (5), +.BR locale (7) diff --git a/man/man1/memusage.1 b/man/man1/memusage.1 new file mode 100644 index 0000000..9f38bf6 --- /dev/null +++ b/man/man1/memusage.1 @@ -0,0 +1,262 @@ +.\" Copyright (c) 2013, Peter Schiffer +.\" and Copyright (C) 2014, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH memusage 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memusage \- profile memory usage of a program +.SH SYNOPSIS +.nf +.BR memusage " [\fIoption\fR]... \fIprogram\fR [\fIprogramoption\fR]..." +.fi +.SH DESCRIPTION +.B memusage +is a bash script which profiles memory usage of the program, +.IR program . +It preloads the +.B libmemusage.so +library into the caller's environment (via the +.B LD_PRELOAD +environment variable; see +.BR ld.so (8)). +The +.B libmemusage.so +library traces memory allocation by intercepting calls to +.BR malloc (3), +.BR calloc (3), +.BR free (3), +and +.BR realloc (3); +optionally, calls to +.BR mmap (2), +.BR mremap (2), +and +.BR munmap (2) +can also be intercepted. +.P +.B memusage +can output the collected data in textual form, or it can use +.BR memusagestat (1) +(see the +.B \-p +option, below) +to create a PNG file containing graphical representation +of the collected data. +.SS Memory usage summary +The "Memory usage summary" line output by +.B memusage +contains three fields: +.RS 4 +.TP +\fBheap total\fR +Sum of \fIsize\fR arguments of all +.BR malloc (3) +calls, +products of arguments (\fInmemb\fR*\fIsize\fR) of all +.BR calloc (3) +calls, +and sum of \fIlength\fR arguments of all +.BR mmap (2) +calls. +In the case of +.BR realloc (3) +and +.BR mremap (2), +if the new size of an allocation is larger than the previous size, +the sum of all such differences (new size minus old size) is added. +.TP +.B "heap peak" +Maximum of all \fIsize\fR arguments of +.BR malloc (3), +all products of \fInmemb\fR*\fIsize\fR of +.BR calloc (3), +all \fIsize\fR arguments of +.BR realloc (3), +.I length +arguments of +.BR mmap (2), +and +\fInew_size\fR arguments of +.BR mremap (2). +.TP +.B "stack peak" +Before the first call to any monitored function, +the stack pointer address (base stack pointer) is saved. +After each function call, the actual stack pointer address is read and +the difference from the base stack pointer computed. +The maximum of these differences is then the stack peak. +.RE +.P +Immediately following this summary line, a table shows the number calls, +total memory allocated or deallocated, +and number of failed calls for each intercepted function. +For +.BR realloc (3) +and +.BR mremap (2), +the additional field "nomove" shows reallocations that +changed the address of a block, +and the additional "dec" field shows reallocations that +decreased the size of the block. +For +.BR realloc (3), +the additional field "free" shows reallocations that +caused a block to be freed (i.e., the reallocated size was 0). +.P +The "realloc/total memory" of the table output by +.B memusage +does not reflect cases where +.BR realloc (3) +is used to reallocate a block of memory +to have a smaller size than previously. +This can cause sum of all "total memory" cells (excluding "free") +to be larger than the "free/total memory" cell. +.SS Histogram for block sizes +The "Histogram for block sizes" provides a breakdown of memory +allocations into various bucket sizes. +.SH OPTIONS +.TP +.BI \-n\ name \fR,\ \fB\-\-progname= name +Name of the program file to profile. +.TP +.BI \-p\ file \fR,\ \fB\-\-png= file +Generate PNG graphic and store it in +.IR file . +.TP +.BI \-d\ file \fR,\ \fB\-\-data= file +Generate binary data file and store it in +.IR file . +.TP +.B \-u\fR,\ \fB\-\-unbuffered +Do not buffer output. +.TP +.BI \-b\ size \fR,\ \fB\-\-buffer= size +Collect +.I size +entries before writing them out. +.TP +.B \-\-no\-timer +Disable timer-based +.RB ( SIGPROF ) +sampling of stack pointer value. +.TP +.B \-m\fR,\ \fB\-\-mmap +Also trace +.BR mmap (2), +.BR mremap (2), +and +.BR munmap (2). +.TP +.B \-?\fR,\ \fB\-\-help +Print help and exit. +.TP +.B \-\-usage +Print a short usage message and exit. +.TP +.B \-V\fR,\ \fB\-\-version +Print version information and exit. +.TP +The following options apply only when generating graphical output: +.TP +.B \-t\fR,\ \fB\-\-time\-based +Use time (rather than number of function calls) as the scale for the X axis. +.TP +.B \-T\fR,\ \fB\-\-total +Also draw a graph of total memory use. +.TP +.BI \fB\-\-title= name +Use +.I name +as the title of the graph. +.TP +.BI \-x\ size \fR,\ \fB\-\-x\-size= size +Make the graph +.I size +pixels wide. +.TP +.BI \-y\ size \fR,\ \fB\-\-y\-size= size +Make the graph +.I size +pixels high. +.SH EXIT STATUS +The exit status of +.B memusage +is equal to the exit status of the profiled program. +.SH BUGS +To report bugs, see +.UR http://www.gnu.org/software/libc/bugs.html +.UE +.SH EXAMPLES +Below is a simple program that reallocates a block of +memory in cycles that rise to a peak before then cyclically +reallocating the memory in smaller blocks that return to zero. +After compiling the program and running the following commands, +a graph of the memory usage of the program can be found in the file +.IR memusage.png : +.P +.in +4n +.EX +$ \fBmemusage \-\-data=memusage.dat ./a.out\fP +\&... +Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224 + total calls total memory failed calls + malloc| 1 400 0 +realloc| 40 44800 0 (nomove:40, dec:19, free:0) + calloc| 0 0 0 + free| 1 440 +Histogram for block sizes: + 192\-207 1 2% ================ +\&... + 2192\-2207 1 2% ================ + 2240\-2255 2 4% ================================= + 2832\-2847 2 4% ================================= + 3440\-3455 2 4% ================================= + 4032\-4047 2 4% ================================= + 4640\-4655 2 4% ================================= + 5232\-5247 2 4% ================================= + 5840\-5855 2 4% ================================= + 6432\-6447 1 2% ================ +$ \fBmemusagestat memusage.dat memusage.png\fP +.EE +.in +.SS Program source +.EX +#include +#include +\& +#define CYCLES 20 +\& +int +main(int argc, char *argv[]) +{ + int i, j; + size_t size; + int *p; +\& + size = sizeof(*p) * 100; + printf("malloc: %zu\en", size); + p = malloc(size); +\& + for (i = 0; i < CYCLES; i++) { + if (i < CYCLES / 2) + j = i; + else + j\-\-; +\& + size = sizeof(*p) * (j * 50 + 110); + printf("realloc: %zu\en", size); + p = realloc(p, size); +\& + size = sizeof(*p) * ((j + 1) * 150 + 110); + printf("realloc: %zu\en", size); + p = realloc(p, size); + } +\& + free(p); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR memusagestat (1), +.BR mtrace (1), +.BR ld.so (8) diff --git a/man/man1/memusagestat.1 b/man/man1/memusagestat.1 new file mode 100644 index 0000000..906582f --- /dev/null +++ b/man/man1/memusagestat.1 @@ -0,0 +1,73 @@ +.\" Copyright (c) 2013, Peter Schiffer +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH memusagestat 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memusagestat \- generate graphic from memory profiling data +.SH SYNOPSIS +.nf +.BR memusagestat " [\fIoption\fR]... \fIdatafile\fR [\fIoutfile\fR]" +.fi +.SH DESCRIPTION +.B memusagestat +creates a PNG file containing a graphical representation of the +memory profiling data in the file +.IR datafile ; +that file is generated via the +.I \-d +(or +.IR \-\-data ) +option of +.BR memusage (1). +.P +The red line in the graph shows the heap usage (allocated memory) +and the green line shows the stack usage. +The x-scale is either the number of memory-handling function calls or +(if the +.I \-t +option is specified) +time. +.SH OPTIONS +.TP +.BI \-o\ file \fR,\ \fB\-\-output= file +Name of the output file. +.TP +.BI \-s\ string \fR,\ \fB\-\-string= string +Use +.I string +as the title inside the output graph. +.TP +.B \-t\fR,\ \fB\-\-time +Use time (rather than number of function calls) as the scale for the X axis. +.TP +.B \-T\fR,\ \fB\-\-total +Also draw a graph of total memory consumption. +.TP +.BI \-x\ size \fR,\ \fB\-\-x\-size= size +Make the output graph +.I size +pixels wide. +.TP +.BI \-y\ size \fR,\ \fB\-\-y\-size= size +Make the output graph +.I size +pixels high. +.TP +.B \-?\fR,\ \fB\-\-help +Print a help message and exit. +.TP +.B \-\-usage +Print a short usage message and exit. +.TP +.B \-V\fR,\ \fB\-\-version +Print version information and exit. +.SH BUGS +To report bugs, see +.UR http://www.gnu.org/software/libc/bugs.html +.UE +.SH EXAMPLES +See +.BR memusage (1). +.SH SEE ALSO +.BR memusage (1), +.BR mtrace (1) diff --git a/man/man1/mtrace.1 b/man/man1/mtrace.1 new file mode 100644 index 0000000..12819c7 --- /dev/null +++ b/man/man1/mtrace.1 @@ -0,0 +1,47 @@ +.\" Copyright (c) 2013, Peter Schiffer (pschiffe@redhat.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH mtrace 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mtrace \- interpret the malloc trace log +.SH SYNOPSIS +.nf +.BR mtrace " [\fIoption\fR]... [\fIbinary\fR] \fImtracedata\fR" +.fi +.SH DESCRIPTION +.B mtrace +is a Perl script used to interpret and provide human readable output +of the trace log contained in the file +.IR mtracedata , +whose contents were produced by +.BR mtrace (3). +If +.I binary +is provided, the output of +.B mtrace +also contains the source file name with line number information +for problem locations +(assuming that +.I binary +was compiled with debugging information). +.P +For more information about the +.BR mtrace (3) +function and +.B mtrace +script usage, see +.BR mtrace (3). +.SH OPTIONS +.TP +.B \-\-help +Print help and exit. +.TP +.B \-\-version +Print version information and exit. +.SH BUGS +For bug reporting instructions, please see: +.UR http://www.gnu.org/software/libc/bugs.html +.UE . +.SH SEE ALSO +.BR memusage (1), +.BR mtrace (3) diff --git a/man/man1/pldd.1 b/man/man1/pldd.1 new file mode 100644 index 0000000..2677551 --- /dev/null +++ b/man/man1/pldd.1 @@ -0,0 +1,105 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pldd 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pldd \- display dynamic shared objects linked into a process +.SH SYNOPSIS +.nf +.BI "pldd " "pid" +.BI pldd " option" +.fi +.SH DESCRIPTION +The +.B pldd +command displays a list of the dynamic shared objects (DSOs) that are +linked into the process with the specified process ID (PID). +The list includes the libraries that have been dynamically loaded using +.BR dlopen (3). +.SH OPTIONS +.TP +.B \-\-help +.TQ +.B \-? +Display a help message and exit. +.TP +.B \-\-usage +Display a short usage message and exit. +.TP +.B \-\-version +.TQ +.B \-V +Display program version information and exit. +.SH EXIT STATUS +On success, +.B pldd +exits with the status 0. +If the specified process does not exist, +the user does not have permission to access +its dynamic shared object list, +or no command-line arguments are supplied, +.B pldd +exists with a status of 1. +If given an invalid option, it exits with the status 64. +.SH VERSIONS +Some other systems +.\" There are man pages on Solaris and HP-UX. +have a similar command. +.SH STANDARDS +None. +.SH HISTORY +glibc 2.15. +.SH NOTES +The command +.P +.in +4n +.EX +lsof \-p PID +.EE +.in +.P +also shows output that includes the dynamic shared objects +that are linked into a process. +.P +The +.BR gdb (1) +.I "info shared" +command also shows the shared libraries being used by a process, +so that one can obtain similar output to +.B pldd +using a command such as the following +(to monitor the process with the specified +.IR pid ): +.P +.in +4n +.EX +$ \fBgdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \e\fP + \fB\-ex "quit" \-p $pid | grep \[aq]\[ha]0x.*0x\[aq]\fP +.EE +.in +.SH BUGS +From glibc 2.19 to glibc 2.29, +.B pldd +was broken: it just hung when executed. +.\" glibc commit 1a4c27355e146b6d8cc6487b998462c7fdd1048f +This problem was fixed in glibc 2.30, and the fix has been backported +to earlier glibc versions in some distributions. +.SH EXAMPLES +.EX +$ \fBecho $$\fP # Display PID of shell +1143 +$ \fBpldd $$\fP # Display DSOs linked into the shell +1143: /usr/bin/bash +linux\-vdso.so.1 +/lib64/libtinfo.so.5 +/lib64/libdl.so.2 +/lib64/libc.so.6 +/lib64/ld\-linux\-x86\-64.so.2 +/lib64/libnss_files.so.2 +.EE +.SH SEE ALSO +.BR ldd (1), +.BR lsof (1), +.BR dlopen (3), +.BR ld.so (8) diff --git a/man/man1/sprof.1 b/man/man1/sprof.1 new file mode 100644 index 0000000..88c52c9 --- /dev/null +++ b/man/man1/sprof.1 @@ -0,0 +1,282 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sprof 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sprof \- read and display shared object profiling data +.SH SYNOPSIS +.nf +.BR sprof " [\fIoption\fP]... \fIshared-object-path\fP \ +[\fIprofile-data-path\fP]" +.fi +.SH DESCRIPTION +The +.B sprof +command displays a profiling summary for the +shared object (shared library) specified as its first command-line argument. +The profiling summary is created using previously generated +profiling data in the (optional) second command-line argument. +If the profiling data pathname is omitted, then +.B sprof +will attempt to deduce it using the soname of the shared object, +looking for a file with the name +.I .profile +in the current directory. +.SH OPTIONS +The following command-line options specify the profile output +to be produced: +.TP +.B \-\-call\-pairs +.TQ +.B \-c +Print a list of pairs of call paths for the interfaces exported +by the shared object, +along with the number of times each path is used. +.TP +.B \-\-flat\-profile +.TQ +.B \-p +Generate a flat profile of all of the functions in the monitored object, +with counts and ticks. +.TP +.B \-\-graph +.TQ +.B \-q +Generate a call graph. +.P +If none of the above options is specified, +then the default behavior is to display a flat profile and a call graph. +.P +The following additional command-line options are available: +.TP +.B \-\-help +.TQ +.B \-? +Display a summary of command-line options and arguments and exit. +.TP +.B \-\-usage +Display a short usage message and exit. +.TP +.B \-\-version +.TQ +.B \-V +Display the program version and exit. +.SH STANDARDS +GNU. +.SH EXAMPLES +The following example demonstrates the use of +.BR sprof . +The example consists of a main program that calls two functions +in a shared object. +First, the code of the main program: +.P +.in +4n +.EX +$ \fBcat prog.c\fP +#include +\& +void x1(void); +void x2(void); +\& +int +main(int argc, char *argv[]) +{ + x1(); + x2(); + exit(EXIT_SUCCESS); +} +.EE +.in +.P +The functions +.IR x1 () +and +.IR x2 () +are defined in the following source file that is used to +construct the shared object: +.P +.in +4n +.EX +$ \fBcat libdemo.c\fP +#include +\& +void +consumeCpu1(int lim) +{ + for (unsigned int j = 0; j < lim; j++) + getppid(); +} +\& +void +x1(void) { + for (unsigned int j = 0; j < 100; j++) + consumeCpu1(200000); +} +\& +void +consumeCpu2(int lim) +{ + for (unsigned int j = 0; j < lim; j++) + getppid(); +} +\& +void +x2(void) +{ + for (unsigned int j = 0; j < 1000; j++) + consumeCpu2(10000); +} +.EE +.in +.P +Now we construct the shared object with the real name +.IR libdemo.so.1.0.1 , +and the soname +.IR libdemo.so.1 : +.P +.in +4n +.EX +$ \fBcc \-g \-fPIC \-shared \-Wl,\-soname,libdemo.so.1 \e\fP + \fB\-o libdemo.so.1.0.1 libdemo.c\fP +.EE +.in +.P +Then we construct symbolic links for the library soname and +the library linker name: +.P +.in +4n +.EX +$ \fBln \-sf libdemo.so.1.0.1 libdemo.so.1\fP +$ \fBln \-sf libdemo.so.1 libdemo.so\fP +.EE +.in +.P +Next, we compile the main program, linking it against the shared object, +and then list the dynamic dependencies of the program: +.P +.in +4n +.EX +$ \fBcc \-g \-o prog prog.c \-L. \-ldemo\fP +$ \fBldd prog\fP + linux\-vdso.so.1 => (0x00007fff86d66000) + libdemo.so.1 => not found + libc.so.6 => /lib64/libc.so.6 (0x00007fd4dc138000) + /lib64/ld\-linux\-x86\-64.so.2 (0x00007fd4dc51f000) +.EE +.in +.P +In order to get profiling information for the shared object, +we define the environment variable +.B LD_PROFILE +with the soname of the library: +.P +.in +4n +.EX +$ \fBexport LD_PROFILE=libdemo.so.1\fP +.EE +.in +.P +We then define the environment variable +.B LD_PROFILE_OUTPUT +with the pathname of the directory where profile output should be written, +and create that directory if it does not exist already: +.P +.in +4n +.EX +$ \fBexport LD_PROFILE_OUTPUT=$(pwd)/prof_data\fP +$ \fBmkdir \-p $LD_PROFILE_OUTPUT\fP +.EE +.in +.P +.B LD_PROFILE +causes profiling output to be +.I appended +to the output file if it already exists, +so we ensure that there is no preexisting profiling data: +.P +.in +4n +.EX +$ \fBrm \-f $LD_PROFILE_OUTPUT/$LD_PROFILE.profile\fP +.EE +.in +.P +We then run the program to produce the profiling output, +which is written to a file in the directory specified in +.BR LD_PROFILE_OUTPUT : +.P +.in +4n +.EX +$ \fBLD_LIBRARY_PATH=. ./prog\fP +$ \fBls prof_data\fP +libdemo.so.1.profile +.EE +.in +.P +We then use the +.B sprof \-p +option to generate a flat profile with counts and ticks: +.P +.in +4n +.EX +$ \fBsprof \-p libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP +Flat profile: +\& +Each sample counts as 0.01 seconds. + % cumulative self self total + time seconds seconds calls us/call us/call name + 60.00 0.06 0.06 100 600.00 consumeCpu1 + 40.00 0.10 0.04 1000 40.00 consumeCpu2 + 0.00 0.10 0.00 1 0.00 x1 + 0.00 0.10 0.00 1 0.00 x2 +.EE +.in +.P +The +.B sprof \-q +option generates a call graph: +.P +.in +4n +.EX +$ \fBsprof \-q libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP +\& +index % time self children called name +\& + 0.00 0.00 100/100 x1 [1] +[0] 100.0 0.00 0.00 100 consumeCpu1 [0] +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0.00 0.00 1/1 +[1] 0.0 0.00 0.00 1 x1 [1] + 0.00 0.00 100/100 consumeCpu1 [0] +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0.00 0.00 1000/1000 x2 [3] +[2] 0.0 0.00 0.00 1000 consumeCpu2 [2] +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0.00 0.00 1/1 +[3] 0.0 0.00 0.00 1 x2 [3] + 0.00 0.00 1000/1000 consumeCpu2 [2] +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +.EE +.in +.P +Above and below, the "" strings represent identifiers that +are outside of the profiled object (in this example, these are instances of +.IR main() ). +.P +The +.B sprof \-c +option generates a list of call pairs and the number of their occurrences: +.P +.in +4n +.EX +$ \fBsprof \-c libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP + x1 1 +x1 consumeCpu1 100 + x2 1 +x2 consumeCpu2 1000 +.EE +.in +.SH SEE ALSO +.BR gprof (1), +.BR ldd (1), +.BR ld.so (8) diff --git a/man/man1/time.1 b/man/man1/time.1 new file mode 100644 index 0000000..eb80248 --- /dev/null +++ b/man/man1/time.1 @@ -0,0 +1,329 @@ +.\" Copyright Andries Brouwer, 2000 +.\" Some fragments of text came from the time-1.7 info file. +.\" Inspired by kromJx@crosswinds.net. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH time 1 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +time \- time a simple command or give resource usage +.SH SYNOPSIS +.B time +.RI [ option \~.\|.\|.\&] " command " [ argument \~.\|.\|.] +.SH DESCRIPTION +The +.B time +command runs the specified program +.I command +with the given arguments. +When +.I command +finishes, +.B time +writes a message to standard error giving timing statistics +about this program run. +These statistics consist of (i) the elapsed real time +between invocation and termination, (ii) the user CPU time +(the sum of the +.I tms_utime +and +.I tms_cutime +values in a +.I "struct tms" +as returned by +.BR times (2)), +and (iii) the system CPU time (the sum of the +.I tms_stime +and +.I tms_cstime +values in a +.I "struct tms" +as returned by +.BR times (2)). +.P +Note: some shells (e.g., +.BR bash (1)) +have a built-in +.B time +command that provides similar information on the usage of time and +possibly other resources. +To access the real command, you may need to specify its pathname +(something like +.IR /usr/bin/time ). +.SH OPTIONS +.TP +.B \-p +When in the POSIX locale, use the precise traditional format +.IP +.in +4n +.EX +"real %f\enuser %f\ensys %f\en" +.EE +.in +.IP +(with numbers in seconds) +where the number of decimals in the output for %f is unspecified +but is sufficient to express the clock tick accuracy, and at least one. +.SH EXIT STATUS +If +.I command +was invoked, the exit status is that of +.IR command . +Otherwise, it is 127 if +.I command +could not be found, 126 if it could be found but could not be invoked, +and some other nonzero value (1\[en]125) if something else went wrong. +.SH ENVIRONMENT +The variables +.BR LANG , +.BR LC_ALL , +.BR LC_CTYPE , +.BR LC_MESSAGES , +.BR LC_NUMERIC , +and +.B NLSPATH +are used for the text and formatting of the output. +.B PATH +is used to search for +.IR command . +.SH GNU VERSION +Below a description of the GNU 1.7 version of +.BR time . +Disregarding the name of the utility, GNU makes it output lots of +useful information, not only about time used, but also on other +resources like memory, I/O and IPC calls (where available). +The output is formatted using a format string that can be specified +using the +.I \-f +option or the +.B TIME +environment variable. +.P +The default format string is: +.P +.in +4n +.EX +%Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k +%Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps +.EE +.in +.P +When the +.I \-p +option is given, the (portable) output format is used: +.P +.in +4n +.EX +real %e +user %U +sys %S +.EE +.in +.\" +.SS The format string +The format is interpreted in the usual printf-like way. +Ordinary characters are directly copied, tab, newline, +and backslash are escaped using \et, \en, and \e\e, +a percent sign is represented by %%, and otherwise % +indicates a conversion. +The program +.B time +will always add a trailing newline itself. +The conversions follow. +All of those used by +.BR tcsh (1) +are supported. +.P +.B "Time" +.TP +.B %E +Elapsed real time (in [hours:]minutes:seconds). +.TP +.B %e +(Not in +.BR tcsh (1).) +Elapsed real time (in seconds). +.TP +.B %S +Total number of CPU-seconds that the process spent in kernel mode. +.TP +.B %U +Total number of CPU-seconds that the process spent in user mode. +.TP +.B %P +Percentage of the CPU that this job got, computed as (%U + %S) / %E. +.P +.B "Memory" +.TP +.B %M +Maximum resident set size of the process during its lifetime, in Kbytes. +.TP +.B %t +(Not in +.BR tcsh (1).) +Average resident set size of the process, in Kbytes. +.TP +.B %K +Average total (data+stack+text) memory use of the process, +in Kbytes. +.TP +.B %D +Average size of the process's unshared data area, in Kbytes. +.TP +.B %p +(Not in +.BR tcsh (1).) +Average size of the process's unshared stack space, in Kbytes. +.TP +.B %X +Average size of the process's shared text space, in Kbytes. +.TP +.B %Z +(Not in +.BR tcsh (1).) +System's page size, in bytes. +This is a per-system constant, but varies between systems. +.TP +.B %F +Number of major page faults that occurred while the process was running. +These are faults where the page has to be read in from disk. +.TP +.B %R +Number of minor, or recoverable, page faults. +These are faults for pages that are not valid but which have +not yet been claimed by other virtual pages. +Thus the data +in the page is still valid but the system tables must be updated. +.TP +.B %W +Number of times the process was swapped out of main memory. +.TP +.B %c +Number of times the process was context-switched involuntarily +(because the time slice expired). +.TP +.B %w +Number of waits: times that the program was context-switched voluntarily, +for instance while waiting for an I/O operation to complete. +.P +.B "I/O" +.TP +.B %I +Number of filesystem inputs by the process. +.TP +.B %O +Number of filesystem outputs by the process. +.TP +.B %r +Number of socket messages received by the process. +.TP +.B %s +Number of socket messages sent by the process. +.TP +.B %k +Number of signals delivered to the process. +.TP +.B %C +(Not in +.BR tcsh (1).) +Name and command-line arguments of the command being timed. +.TP +.B %x +(Not in +.BR tcsh (1).) +Exit status of the command. +.SS GNU options +.TP +.BI "\-f " format ", \-\-format=" format +Specify output format, possibly overriding the format specified +in the environment variable TIME. +.TP +.B "\-p, \-\-portability" +Use the portable output format. +.TP +.BI "\-o " file ", \-\-output=" file +Do not send the results to +.IR stderr , +but overwrite the specified file. +.TP +.B "\-a, \-\-append" +(Used together with \-o.) Do not overwrite but append. +.TP +.B "\-v, \-\-verbose" +Give very verbose output about all the program knows about. +.TP +.B "\-q, \-\-quiet" +Don't report abnormal program termination (where +.I command +is terminated by a signal) or nonzero exit status. +.\" +.SS GNU standard options +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-V, \-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH BUGS +Not all resources are measured by all versions of UNIX, +so some of the values might be reported as zero. +The present selection was mostly inspired by the data +provided by 4.2 or 4.3BSD. +.P +GNU time version 1.7 is not yet localized. +Thus, it does not implement the POSIX requirements. +.P +The environment variable +.B TIME +was badly chosen. +It is not unusual for systems like +.BR autoconf (1) +or +.BR make (1) +to use environment variables with the name of a utility to override +the utility to be used. +Uses like MORE or TIME for options to programs +(instead of program pathnames) tend to lead to difficulties. +.P +It seems unfortunate that +.I \-o +overwrites instead of appends. +(That is, the +.I \-a +option should be the default.) +.P +Mail suggestions and bug reports for GNU +.B time +to +.IR bug\-time@gnu.org . +Please include the version of +.BR time , +which you can get by running +.P +.in +4n +.EX +time \-\-version +.EE +.in +.P +and the operating system +and C compiler you used. +.\" .SH AUTHORS +.\" .TP +.\" .IP "David Keppel" +.\" Original version +.\" .IP "David MacKenzie" +.\" POSIXization, autoconfiscation, GNU getoptization, +.\" documentation, other bug fixes and improvements. +.\" .IP "Arne Henrik Juul" +.\" Helped with portability +.\" .IP "Francois Pinard" +.\" Helped with portability +.SH SEE ALSO +.BR bash (1), +.BR tcsh (1), +.BR times (2), +.BR wait3 (2) diff --git a/man/man2/_Exit.2 b/man/man2/_Exit.2 new file mode 100644 index 0000000..9f9d2e7 --- /dev/null +++ b/man/man2/_Exit.2 @@ -0,0 +1 @@ +.so man2/_exit.2 diff --git a/man/man2/__clone2.2 b/man/man2/__clone2.2 new file mode 100644 index 0000000..68f41a5 --- /dev/null +++ b/man/man2/__clone2.2 @@ -0,0 +1 @@ +.so man2/clone.2 diff --git a/man/man2/_exit.2 b/man/man2/_exit.2 new file mode 100644 index 0000000..ccd5979 --- /dev/null +++ b/man/man2/_exit.2 @@ -0,0 +1,138 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 21 23:02:38 1993 by Rik Faith +.\" Modified 2001-11-17, aeb +.\" +.TH _exit 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +_exit, _Exit \- terminate the calling process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[noreturn]] void _exit(int " status ); +.P +.B #include +.P +.BI "[[noreturn]] void _Exit(int " status ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR _Exit (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR _exit () +terminates the calling process "immediately". +Any open file descriptors belonging to the process are closed. +Any children of the process are inherited by +.BR init (1) +(or by the nearest "subreaper" process as defined through the use of the +.BR prctl (2) +.B PR_SET_CHILD_SUBREAPER +operation). +The process's parent is sent a +.B SIGCHLD +signal. +.P +The value +.I "status & 0xFF" +is returned to the parent process as the process's exit status, and +can be collected by the parent using one of the +.BR wait (2) +family of calls. +.P +The function +.BR _Exit () +is equivalent to +.BR _exit (). +.SH RETURN VALUE +These functions do not return. +.SH STANDARDS +.TP +.BR _exit () +POSIX.1-2008. +.TP +.BR _Exit () +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.P +.BR _Exit () +was introduced by C99. +.SH NOTES +For a discussion on the effects of an exit, the transmission of +exit status, zombie processes, signals sent, and so on, see +.BR exit (3). +.P +The function +.BR _exit () +is like +.BR exit (3), +but does not call any +functions registered with +.BR atexit (3) +or +.BR on_exit (3). +Open +.BR stdio (3) +streams are not flushed. +On the other hand, +.BR _exit () +does close open file descriptors, and this may cause an unknown delay, +waiting for pending output to finish. +If the delay is undesired, +it may be useful to call functions like +.BR tcflush (3) +before calling +.BR _exit (). +Whether any pending I/O is canceled, and which pending I/O may be +canceled upon +.BR _exit (), +is implementation-dependent. +.SS C library/kernel differences +The text above in DESCRIPTION describes the traditional effect of +.BR _exit (), +which is to terminate a process, +and these are the semantics specified by POSIX.1 and implemented +by the C library wrapper function. +On modern systems, this means termination of all threads in the process. +.P +By contrast with the C library wrapper function, the raw Linux +.BR _exit () +system call terminates only the calling thread, and actions such as +reparenting child processes or sending +.B SIGCHLD +to the parent process are performed only if this is +the last thread in the thread group. +.\" _exit() is used by pthread_exit() to terminate the calling thread +.P +Up to glibc 2.3, the +.BR _exit () +wrapper function invoked the kernel system call of the same name. +Since glibc 2.3, the wrapper function invokes +.BR exit_group (2), +in order to terminate all of the threads in a process. +.SH SEE ALSO +.BR execve (2), +.BR exit_group (2), +.BR fork (2), +.BR kill (2), +.BR wait (2), +.BR wait4 (2), +.BR waitpid (2), +.BR atexit (3), +.BR exit (3), +.BR on_exit (3), +.BR termios (3) diff --git a/man/man2/_llseek.2 b/man/man2/_llseek.2 new file mode 100644 index 0000000..d15dbee --- /dev/null +++ b/man/man2/_llseek.2 @@ -0,0 +1 @@ +.so man2/llseek.2 diff --git a/man/man2/_newselect.2 b/man/man2/_newselect.2 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man2/_newselect.2 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man2/_syscall.2 b/man/man2/_syscall.2 new file mode 100644 index 0000000..f591bdc --- /dev/null +++ b/man/man2/_syscall.2 @@ -0,0 +1,171 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Tue Jul 6 12:42:46 MDT 1993 +.\" Added "Calling Directly" and supporting paragraphs +.\" +.\" Modified Sat Jul 24 15:19:12 1993 by Rik Faith +.\" +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" Added explanation of arg stacking when 6 or more args. +.\" +.\" Modified 10 June 1995 by Andries Brouwer +.\" +.\" 2007-10-23 mtk: created as a new page, by taking the content +.\" specific to the _syscall() macros from intro(2). +.\" +.TH _syscall 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +_syscall \- invoking a system call without library support (OBSOLETE) +.SH SYNOPSIS +.nf +.B #include +.P +A _syscall macro +.P +desired system call +.fi +.SH DESCRIPTION +The important thing to know about a system call is its prototype. +You need to know how many arguments, their types, +and the function return type. +There are seven macros that make the actual call into the system easier. +They have the form: +.P +.in +4n +.EX +.RI _syscall X ( type , name , type1 , arg1 , type2 , arg2 ,...) +.EE +.in +.P +where +.IP +.I X +is 0\[en]6, which are the number of arguments taken by the +system call +.IP +.I type +is the return type of the system call +.IP +.I name +is the name of the system call +.IP +.I typeN +is the Nth argument's type +.IP +.I argN +is the name of the Nth argument +.P +These macros create a function called +.I name +with the arguments you +specify. +Once you include the _syscall() in your source file, +you call the system call by +.IR name . +.SH FILES +.I /usr/include/linux/unistd.h +.SH STANDARDS +Linux. +.SH HISTORY +Starting around Linux 2.6.18, the _syscall macros were removed +from header files supplied to user space. +Use +.BR syscall (2) +instead. +(Some architectures, notably ia64, never provided the _syscall macros; +on those architectures, +.BR syscall (2) +was always required.) +.SH NOTES +The _syscall() macros +.I "do not" +produce a prototype. +You may have to +create one, especially for C++ users. +.P +System calls are not required to return only positive or negative error +codes. +You need to read the source to be sure how it will return errors. +Usually, it is the negative of a standard error code, +for example, +.RI \- EPERM . +The _syscall() macros will return the result +.I r +of the system call +when +.I r +is nonnegative, but will return \-1 and set the variable +.I errno +to +.RI \- r +when +.I r +is negative. +For the error codes, see +.BR errno (3). +.P +When defining a system call, the argument types +.I must +be +passed by-value or by-pointer (for aggregates like structs). +.\" The preferred way to invoke system calls that glibc does not know +.\" about yet is via +.\" .BR syscall (2). +.\" However, this mechanism can be used only if using a libc +.\" (such as glibc) that supports +.\" .BR syscall (2), +.\" and if the +.\" .I +.\" header file contains the required SYS_foo definition. +.\" Otherwise, the use of a _syscall macro is required. +.\" +.SH EXAMPLES +.\" SRC BEGIN (_syscall.c) +.EX +#include +#include +#include +#include /* for _syscallX macros/related stuff */ +#include /* for struct sysinfo */ +\& +_syscall1(int, sysinfo, struct sysinfo *, info); +\& +int +main(void) +{ + struct sysinfo s_info; + int error; +\& + error = sysinfo(&s_info); + printf("code error = %d\en", error); + printf("Uptime = %lds\enLoad: 1 min %lu / 5 min %lu / 15 min %lu\en" + "RAM: total %lu / free %lu / shared %lu\en" + "Memory in buffers = %lu\enSwap: total %lu / free %lu\en" + "Number of processes = %d\en", + s_info.uptime, s_info.loads[0], + s_info.loads[1], s_info.loads[2], + s_info.totalram, s_info.freeram, + s_info.sharedram, s_info.bufferram, + s_info.totalswap, s_info.freeswap, + s_info.procs); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS Sample output +.EX +code error = 0 +uptime = 502034s +Load: 1 min 13376 / 5 min 5504 / 15 min 1152 +RAM: total 15343616 / free 827392 / shared 8237056 +Memory in buffers = 5066752 +Swap: total 27881472 / free 24698880 +Number of processes = 40 +.EE +.SH SEE ALSO +.BR intro (2), +.BR syscall (2), +.BR errno (3) diff --git a/man/man2/_sysctl.2 b/man/man2/_sysctl.2 new file mode 100644 index 0000000..9e14d4b --- /dev/null +++ b/man/man2/_sysctl.2 @@ -0,0 +1 @@ +.so man2/sysctl.2 diff --git a/man/man2/accept.2 b/man/man2/accept.2 new file mode 100644 index 0000000..196700a --- /dev/null +++ b/man/man2/accept.2 @@ -0,0 +1,349 @@ +.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-21 by Eric S. Raymond +.\" Modified 1998-2000 by Andi Kleen to match Linux 2.2 reality +.\" Modified 2002-04-23 by Roger Luethi +.\" Modified 2004-06-17 by Michael Kerrisk +.\" 2008-12-04, mtk, Add documentation of accept4() +.\" +.TH accept 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +accept, accept4 \- accept a connection on a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int accept(int " sockfd ", struct sockaddr *_Nullable restrict " addr , +.BI " socklen_t *_Nullable restrict " addrlen ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int accept4(int " sockfd ", struct sockaddr *_Nullable restrict " addr , +.BI " socklen_t *_Nullable restrict " addrlen ", int " flags ); +.fi +.SH DESCRIPTION +The +.BR accept () +system call is used with connection-based socket types +.RB ( SOCK_STREAM , +.BR SOCK_SEQPACKET ). +It extracts the first connection request on the queue of pending +connections for the listening socket, +.IR sockfd , +creates a new connected socket, and returns a new file +descriptor referring to that socket. +The newly created socket is not in the listening state. +The original socket +.I sockfd +is unaffected by this call. +.P +The argument +.I sockfd +is a socket that has been created with +.BR socket (2), +bound to a local address with +.BR bind (2), +and is listening for connections after a +.BR listen (2). +.P +The argument +.I addr +is a pointer to a +.I sockaddr +structure. +This structure is filled in with the address of the peer socket, +as known to the communications layer. +The exact format of the address returned +.I addr +is determined by the socket's address family (see +.BR socket (2) +and the respective protocol man pages). +When +.I addr +is NULL, nothing is filled in; in this case, +.I addrlen +is not used, and should also be NULL. +.P +The +.I addrlen +argument is a value-result argument: +the caller must initialize it to contain the +size (in bytes) of the structure pointed to by +.IR addr ; +on return it will contain the actual size of the peer address. +.P +The returned address is truncated if the buffer provided is too small; +in this case, +.I addrlen +will return a value greater than was supplied to the call. +.P +If no pending +connections are present on the queue, and the socket is not marked as +nonblocking, +.BR accept () +blocks the caller until a connection is present. +If the socket is marked +nonblocking and no pending connections are present on the queue, +.BR accept () +fails with the error +.B EAGAIN +or +.BR EWOULDBLOCK . +.P +In order to be notified of incoming connections on a socket, you can use +.BR select (2), +.BR poll (2), +or +.BR epoll (7). +A readable event will be delivered when a new connection is attempted and you +may then call +.BR accept () +to get a socket for that connection. +Alternatively, you can set the socket to deliver +.B SIGIO +when activity occurs on a socket; see +.BR socket (7) +for details. +.P +If +.I flags +is 0, then +.BR accept4 () +is the same as +.BR accept (). +The following values can be bitwise ORed in +.I flags +to obtain different behavior: +.TP 16 +.B SOCK_NONBLOCK +Set the +.B O_NONBLOCK +file status flag on the open file description (see +.BR open (2)) +referred to by the new file descriptor. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B SOCK_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.SH RETURN VALUE +On success, +these system calls return a file descriptor +for the accepted socket (a nonnegative integer). +On error, \-1 is returned, +.I errno +is set to indicate the error, and +.I addrlen +is left unchanged. +.SS Error handling +Linux +.BR accept () +(and +.BR accept4 ()) +passes already-pending network errors on the new socket +as an error code from +.BR accept (). +This behavior differs from other BSD socket +implementations. +For reliable operation the application should detect +the network errors defined for the protocol after +.BR accept () +and treat +them like +.B EAGAIN +by retrying. +In the case of TCP/IP, these are +.BR ENETDOWN , +.BR EPROTO , +.BR ENOPROTOOPT , +.BR EHOSTDOWN , +.BR ENONET , +.BR EHOSTUNREACH , +.BR EOPNOTSUPP , +and +.BR ENETUNREACH . +.SH ERRORS +.TP +.BR EAGAIN " or " EWOULDBLOCK +.\" Actually EAGAIN on Linux +The socket is marked nonblocking and no connections are +present to be accepted. +POSIX.1-2001 and POSIX.1-2008 +allow either error to be returned for this case, +and do not require these constants to have the same value, +so a portable application should check for both possibilities. +.TP +.B EBADF +.I sockfd +is not an open file descriptor. +.TP +.B ECONNABORTED +A connection has been aborted. +.TP +.B EFAULT +The +.I addr +argument is not in a writable part of the user address space. +.TP +.B EINTR +The system call was interrupted by a signal that was caught +before a valid connection arrived; see +.BR signal (7). +.TP +.B EINVAL +Socket is not listening for connections, or +.I addrlen +is invalid (e.g., is negative). +.TP +.B EINVAL +.RB ( accept4 ()) +invalid value in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOBUFS +.TQ +.B ENOMEM +Not enough free memory. +This often means that the memory allocation is limited by the socket buffer +limits, not by the system memory. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.TP +.B EOPNOTSUPP +The referenced socket is not of type +.BR SOCK_STREAM . +.TP +.B EPERM +Firewall rules forbid connection. +.TP +.B EPROTO +Protocol error. +.P +In addition, network errors for the new socket and as defined +for the protocol may be returned. +Various Linux kernels can +return other errors such as +.BR ENOSR , +.BR ESOCKTNOSUPPORT , +.BR EPROTONOSUPPORT , +.BR ETIMEDOUT . +The value +.B ERESTARTSYS +may be seen during a trace. +.SH VERSIONS +On Linux, the new socket returned by +.BR accept () +does \fInot\fP inherit file status flags such as +.B O_NONBLOCK +and +.B O_ASYNC +from the listening socket. +This behavior differs from the canonical BSD sockets implementation. +.\" Some testing seems to show that Tru64 5.1 and HP-UX 11 also +.\" do not inherit file status flags -- MTK Jun 05 +Portable programs should not rely on inheritance or noninheritance +of file status flags and always explicitly set all required flags on +the socket returned from +.BR accept (). +.SH STANDARDS +.TP +.BR accept () +POSIX.1-2008. +.TP +.BR accept4 () +Linux. +.SH HISTORY +.TP +.BR accept () +POSIX.1-2001, SVr4, 4.4BSD +.RB ( accept () +first appeared in 4.2BSD). +.\" The BSD man page documents five possible error returns +.\" (EBADF, ENOTSOCK, EOPNOTSUPP, EWOULDBLOCK, EFAULT). +.\" POSIX.1-2001 documents errors +.\" EAGAIN, EBADF, ECONNABORTED, EINTR, EINVAL, EMFILE, +.\" ENFILE, ENOBUFS, ENOMEM, ENOTSOCK, EOPNOTSUPP, EPROTO, EWOULDBLOCK. +.\" In addition, SUSv2 documents EFAULT and ENOSR. +.TP +.BR accept4 () +Linux 2.6.28, +glibc 2.10. +.SH NOTES +There may not always be a connection waiting after a +.B SIGIO +is delivered or +.BR select (2), +.BR poll (2), +or +.BR epoll (7) +return a readability event because the connection might have been +removed by an asynchronous network error or another thread before +.BR accept () +is called. +If this happens, then the call will block waiting for the next +connection to arrive. +To ensure that +.BR accept () +never blocks, the passed socket +.I sockfd +needs to have the +.B O_NONBLOCK +flag set (see +.BR socket (7)). +.P +For certain protocols which require an explicit confirmation, +such as DECnet, +.BR accept () +can be thought of as merely dequeuing the next connection request and not +implying confirmation. +Confirmation can be implied by +a normal read or write on the new file descriptor, and rejection can be +implied by closing the new socket. +Currently, only DECnet has these semantics on Linux. +.\" +.SS The socklen_t type +In the original BSD sockets implementation (and on other older systems) +.\" such as Linux libc4 and libc5, SunOS 4, SGI +the third argument of +.BR accept () +was declared as an \fIint\ *\fP. +A POSIX.1g draft +standard wanted to change it into a \fIsize_t\ *\fPC; +.\" SunOS 5 has 'size_t *' +later POSIX standards and glibc 2.x have +.IR "socklen_t\ * ". +.SH EXAMPLES +See +.BR bind (2). +.SH SEE ALSO +.BR bind (2), +.BR connect (2), +.BR listen (2), +.BR select (2), +.BR socket (2), +.BR socket (7) diff --git a/man/man2/accept4.2 b/man/man2/accept4.2 new file mode 100644 index 0000000..963dfb5 --- /dev/null +++ b/man/man2/accept4.2 @@ -0,0 +1 @@ +.so man2/accept.2 diff --git a/man/man2/access.2 b/man/man2/access.2 new file mode 100644 index 0000000..3abfed0 --- /dev/null +++ b/man/man2/access.2 @@ -0,0 +1,468 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2004, 2006, 2007, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1993-07-21 Rik Faith (faith@cs.unc.edu) +.\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com): +.\" Removed note about old kernel (pre-1.1.44) using wrong id on path. +.\" Modified 1996-03-18 by Martin Schulze (joey@infodrom.north.de): +.\" Stated more clearly how it behaves with symbolic links. +.\" Added correction due to Nick Duffek (nsd@bbc.com), aeb, 960426 +.\" Modified 1996-09-07 by Michael Haardt: +.\" Restrictions for NFS +.\" Modified 1997-09-09 by Joseph S. Myers +.\" Modified 1998-01-13 by Michael Haardt: +.\" Using access is often insecure +.\" Modified 2001-10-16 by aeb +.\" Modified 2002-04-23 by Roger Luethi +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2007-06-10, mtk, various parts rewritten, and added BUGS section. +.\" +.TH access 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +access, faccessat, faccessat2 \- check user's permissions for a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int access(const char *" pathname ", int " mode ); +.P +.BR "#include " " /* Definition of " AT_* " constants */" +.B #include +.P +.BI "int faccessat(int " dirfd ", const char *" pathname ", int " \ +mode ", int " flags ); + /* But see C library/kernel differences, below */ +.P +.BR "#include " " /* Definition of " AT_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.B int syscall(SYS_faccessat2, +.BI " int " dirfd ", const char *" pathname ", int " mode \ +", int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR faccessat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +.BR access () +checks whether the calling process can access the file +.IR pathname . +If +.I pathname +is a symbolic link, it is dereferenced. +.P +The +.I mode +specifies the accessibility check(s) to be performed, +and is either the value +.BR F_OK , +.\" F_OK is defined as 0 on every system that I know of. +or a mask consisting of the bitwise OR of one or more of +.BR R_OK ", " W_OK ", and " X_OK . +.B F_OK +tests for the existence of the file. +.BR R_OK ", " W_OK ", and " X_OK +test whether the file exists and grants read, write, and +execute permissions, respectively. +.P +The check is done using the calling process's +.I real +UID and GID, rather than the effective IDs as is done when +actually attempting an operation (e.g., +.BR open (2)) +on the file. +Similarly, for the root user, the check uses the set of +permitted capabilities rather than the set of effective +capabilities; and for non-root users, the check uses an empty set +of capabilities. +.P +This allows set-user-ID programs and capability-endowed programs +to easily determine the invoking user's authority. +In other words, +.BR access () +does not answer the "can I read/write/execute this file?" question. +It answers a slightly different question: +"(assuming I'm a setuid binary) can +.I the user who invoked me +read/write/execute this file?", +which gives set-user-ID programs the possibility to +prevent malicious users from causing them to read files +which users shouldn't be able to read. +.P +If the calling process is privileged (i.e., its real UID is zero), +then an +.B X_OK +check is successful for a regular file if execute permission +is enabled for any of the file owner, group, or other. +.SS faccessat() +.BR faccessat () +operates in exactly the same way as +.BR access (), +except for the differences described here. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR access () +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR access ()). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +.I flags +is constructed by ORing together zero or more of the following values: +.TP +.B AT_EACCESS +Perform access checks using the effective user and group IDs. +By default, +.BR faccessat () +uses the real IDs (like +.BR access ()). +.TP +.BR AT_EMPTY_PATH " (since Linux 5.8)" +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +to obtain its definition. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead return information about the link itself. +.P +See +.BR openat (2) +for an explanation of the need for +.BR faccessat (). +.\" +.SS faccessat2() +The description of +.BR faccessat () +given above corresponds to POSIX.1 and +to the implementation provided by glibc. +However, the glibc implementation was an imperfect emulation (see BUGS) +that papered over the fact that the raw Linux +.BR faccessat () +system call does not have a +.I flags +argument. +To allow for a proper implementation, Linux 5.8 added the +.BR faccessat2 () +system call, which supports the +.I flags +argument and allows a correct implementation of the +.BR faccessat () +wrapper function. +.SH RETURN VALUE +On success (all requested permissions granted, or +.I mode +is +.B F_OK +and the file exists), zero is returned. +On error (at least one bit in +.I mode +asked for a permission that is denied, or +.I mode +is +.B F_OK +and the file does not exist, or some other error occurred), +\-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The requested access would be denied to the file, or search permission +is denied for one of the directories in the path prefix of +.IR pathname . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( faccessat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +.RB ( faccessat ()) +nor a valid file descriptor. +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EINVAL +.I mode +was incorrectly specified. +.TP +.B EINVAL +.RB ( faccessat ()) +Invalid flag specified in +.IR flags . +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A component of +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B ENOTDIR +.RB ( faccessat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B EPERM +Write permission was requested to a file that has the immutable flag set. +See also +.BR ioctl_iflags (2). +.TP +.B EROFS +Write permission was requested for a file on a read-only filesystem. +.TP +.B ETXTBSY +Write access was requested to an executable which is being +executed. +.SH VERSIONS +If the calling process has appropriate privileges (i.e., is superuser), +POSIX.1-2001 permits an implementation to indicate success for an +.B X_OK +check even if none of the execute file permission bits are set. +.\" HPU-UX 11 and Tru64 5.1 do this. +Linux does not do this. +.\" +.SS C library/kernel differences +The raw +.BR faccessat () +system call takes only the first three arguments. +The +.B AT_EACCESS +and +.B AT_SYMLINK_NOFOLLOW +flags are actually implemented within the glibc wrapper function for +.BR faccessat (). +If either of these flags is specified, then the wrapper function employs +.BR fstatat (2) +to determine access permissions, but see BUGS. +.\" +.SS glibc notes +On older kernels where +.BR faccessat () +is unavailable (and when the +.B AT_EACCESS +and +.B AT_SYMLINK_NOFOLLOW +flags are not specified), +the glibc wrapper function falls back to the use of +.BR access (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.I /proc/self/fd +that corresponds to the +.I dirfd +argument. +.SH STANDARDS +.TP +.BR access () +.TQ +.BR faccessat () +POSIX.1-2008. +.TP +.BR faccessat2 () +Linux. +.SH HISTORY +.TP +.BR access () +SVr4, 4.3BSD, POSIX.1-2001. +.TP +.BR faccessat () +Linux 2.6.16, +glibc 2.4. +.TP +.BR faccessat2 () +Linux 5.8. +.SH NOTES +.BR Warning : +Using these calls to check if a user is authorized to, for example, +open a file before actually doing so using +.BR open (2) +creates a security hole, because the user might exploit the short time +interval between checking and opening the file to manipulate it. +.BR "For this reason, the use of this system call should be avoided" . +(In the example just described, +a safer alternative would be to temporarily switch the process's +effective user ID to the real ID and then call +.BR open (2).) +.P +.BR access () +always dereferences symbolic links. +If you need to check the permissions on a symbolic link, use +.BR faccessat () +with the flag +.BR AT_SYMLINK_NOFOLLOW . +.P +These calls return an error if any of the access types in +.I mode +is denied, even if some of the other access types in +.I mode +are permitted. +.P +A file is accessible only if the permissions on each of the +directories in the path prefix of +.I pathname +grant search (i.e., execute) access. +If any directory is inaccessible, then the +.BR access () +call fails, regardless of the permissions on the file itself. +.P +Only access bits are checked, not the file type or contents. +Therefore, if a directory is found to be writable, +it probably means that files can be created in the directory, +and not that the directory can be written as a file. +Similarly, a DOS file may be reported as executable, but the +.BR execve (2) +call will still fail. +.P +These calls +may not work correctly on NFSv2 filesystems with UID mapping enabled, +because UID mapping is done on the server and hidden from the client, +which checks permissions. +(NFS versions 3 and higher perform the check on the server.) +Similar problems can occur to FUSE mounts. +.\" +.SH BUGS +Because the Linux kernel's +.BR faccessat () +system call does not support a +.I flags +argument, the glibc +.BR faccessat () +wrapper function provided in glibc 2.32 and earlier +emulates the required functionality using +a combination of the +.BR faccessat () +system call and +.BR fstatat (2). +However, this emulation does not take ACLs into account. +Starting with glibc 2.33, the wrapper function avoids this bug +by making use of the +.BR faccessat2 () +system call where it is provided by the underlying kernel. +.P +In Linux 2.4 (and earlier) there is some strangeness in the handling of +.B X_OK +tests for superuser. +If all categories of execute permission are disabled +for a nondirectory file, then the only +.BR access () +test that returns \-1 is when +.I mode +is specified as just +.BR X_OK ; +if +.B R_OK +or +.B W_OK +is also specified in +.IR mode , +then +.BR access () +returns 0 for such files. +.\" This behavior appears to have been an implementation accident. +Early Linux 2.6 (up to and including Linux 2.6.3) +also behaved in the same way as Linux 2.4. +.P +Before Linux 2.6.20, +these calls ignored the effect of the +.B MS_NOEXEC +flag if it was used to +.BR mount (2) +the underlying filesystem. +Since Linux 2.6.20, the +.B MS_NOEXEC +flag is honored. +.SH SEE ALSO +.BR chmod (2), +.BR chown (2), +.BR open (2), +.BR setgid (2), +.BR setuid (2), +.BR stat (2), +.BR euidaccess (3), +.BR credentials (7), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/acct.2 b/man/man2/acct.2 new file mode 100644 index 0000000..e246ff1 --- /dev/null +++ b/man/man2/acct.2 @@ -0,0 +1,136 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1993-07-22 by Rik Faith +.\" Modified 1993-08-10 by Alan Cox +.\" Modified 1998-11-04 by Tigran Aivazian +.\" Modified 2004-05-27, 2004-06-17, 2004-06-23 by Michael Kerrisk +.\" +.TH acct 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +acct \- switch process accounting on or off +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int acct(const char *_Nullable " filename ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR acct (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +The +.BR acct () +system call enables or disables process accounting. +If called with the name of an existing file as its argument, +accounting is turned on, +and records for each terminating process are appended to +.I filename +as it terminates. +An argument of NULL causes accounting to be turned off. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Write permission is denied for the specified file, +or search permission is denied for one of the directories +in the path prefix of +.I filename +(see also +.BR path_resolution (7)), +or +.I filename +is not a regular file. +.TP +.B EFAULT +.I filename +points outside your accessible address space. +.TP +.B EIO +Error writing to the file +.IR filename . +.TP +.B EISDIR +.I filename +is a directory. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR filename . +.TP +.B ENAMETOOLONG +.I filename +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +The specified file does not exist. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOSYS +BSD process accounting has not been enabled when the operating system +kernel was compiled. +The kernel configuration parameter controlling this feature is +.BR CONFIG_BSD_PROCESS_ACCT . +.TP +.B ENOTDIR +A component used as a directory in +.I filename +is not in fact a directory. +.TP +.B EPERM +The calling process has insufficient privilege to enable process accounting. +On Linux, the +.B CAP_SYS_PACCT +capability is required. +.TP +.B EROFS +.I filename +refers to a file on a read-only filesystem. +.TP +.B EUSERS +There are no more free file structures or we ran out of memory. +.SH STANDARDS +None. +.SH HISTORY +SVr4, 4.3BSD. +.\" SVr4 documents an EBUSY error condition, but no EISDIR or ENOSYS. +.\" Also AIX and HP-UX document EBUSY (attempt is made +.\" to enable accounting when it is already enabled), as does Solaris +.\" (attempt is made to enable accounting using the same file that is +.\" currently being used). +.SH NOTES +No accounting is produced for programs running when a system crash occurs. +In particular, nonterminating processes are never accounted for. +.P +The structure of the records written to the accounting file is described in +.BR acct (5). +.SH SEE ALSO +.BR acct (5) diff --git a/man/man2/add_key.2 b/man/man2/add_key.2 new file mode 100644 index 0000000..a98e483 --- /dev/null +++ b/man/man2/add_key.2 @@ -0,0 +1,298 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH add_key 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +add_key \- add a key to the kernel's key management facility +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "key_serial_t add_key(const char *" type ", const char *" description , +.BI " const void " payload [. plen "], size_t " plen , +.BI " key_serial_t " keyring ");" +.fi +.P +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.BR add_key () +creates or updates a key of the given +.I type +and +.IR description , +instantiates it with the +.I payload +of length +.IR plen , +attaches it to the nominated +.IR keyring , +and returns the key's serial number. +.P +The key may be rejected if the provided data is in the wrong format or +it is invalid in some other way. +.P +If the destination +.I keyring +already contains a key that matches the specified +.I type +and +.IR description , +then, if the key type supports it, +.\" FIXME The aforementioned phrases begs the question: +.\" which key types support this? +that key will be updated rather than a new key being created; +if not, a new key (with a different ID) will be created +and it will displace the link to the extant key from the keyring. +.\" FIXME Perhaps elaborate the implications here? Namely, the new +.\" key will have a new ID, and if the old key was a keyring that +.\" is consequently unlinked, then keys that it was anchoring +.\" will have their reference count decreased by one (and may +.\" consequently be garbage collected). Is this all correct? +.P +The destination +.I keyring +serial number may be that of a valid keyring for which the caller has +.I write +permission. +Alternatively, it may be one of the following special keyring IDs: +.\" FIXME . Perhaps have a separate page describing special keyring IDs? +.TP +.B KEY_SPEC_THREAD_KEYRING +This specifies the caller's thread-specific keyring +.RB ( thread\-keyring (7)). +.TP +.B KEY_SPEC_PROCESS_KEYRING +This specifies the caller's process-specific keyring +.RB ( process\-keyring (7)). +.TP +.B KEY_SPEC_SESSION_KEYRING +This specifies the caller's session-specific keyring +.RB ( session\-keyring (7)). +.TP +.B KEY_SPEC_USER_KEYRING +This specifies the caller's UID-specific keyring +.RB ( user\-keyring (7)). +.TP +.B KEY_SPEC_USER_SESSION_KEYRING +This specifies the caller's UID-session keyring +.RB ( user\-session\-keyring (7)). +.SS Key types +The key +.I type +is a string that specifies the key's type. +Internally, the kernel defines a number of key types that are +available in the core key management code. +Among the types that are available for user-space use +and can be specified as the +.I type +argument to +.BR add_key () +are the following: +.TP +.I \[dq]keyring\[dq] +Keyrings are special key types that may contain links to sequences of other +keys of any type. +If this interface is used to create a keyring, then +.I payload +should be NULL and +.I plen +should be zero. +.TP +.I \[dq]user\[dq] +This is a general purpose key type whose payload may be read and updated +by user-space applications. +The key is kept entirely within kernel memory. +The payload for keys of this type is a blob of arbitrary data +of up to 32,767 bytes. +.TP +.IR \[dq]logon\[dq] " (since Linux 3.3)" +.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b +This key type is essentially the same as +.IR \[dq]user\[dq] , +but it does not permit the key to read. +This is suitable for storing payloads +that you do not want to be readable from user space. +.P +This key type vets the +.I description +to ensure that it is qualified by a "service" prefix, +by checking to ensure that the +.I description +contains a ':' that is preceded by other characters. +.TP +.IR \[dq]big_key\[dq] " (since Linux 3.13)" +.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 +This key type is similar to +.IR \[dq]user\[dq] , +but may hold a payload of up to 1\ MiB. +If the key payload is large enough, +then it may be stored encrypted in tmpfs +(which can be swapped out) rather than kernel memory. +.P +For further details on these key types, see +.BR keyrings (7). +.SH RETURN VALUE +On success, +.BR add_key () +returns the serial number of the key it created or updated. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The keyring wasn't available for modification by the user. +.TP +.B EDQUOT +The key quota for this user would be exceeded by creating this key or linking +it to the keyring. +.TP +.B EFAULT +One or more of +.IR type , +.IR description , +and +.I payload +points outside process's accessible address space. +.TP +.B EINVAL +The size of the string (including the terminating null byte) specified in +.I type +or +.I description +exceeded the limit (32 bytes and 4096 bytes respectively). +.TP +.B EINVAL +The payload data was invalid. +.TP +.B EINVAL +.I type +was +.I \[dq]logon\[dq] +and the +.I description +was not qualified with a prefix string of the form +.IR \[dq]service:\[dq] . +.TP +.B EKEYEXPIRED +The keyring has expired. +.TP +.B EKEYREVOKED +The keyring has been revoked. +.TP +.B ENOKEY +The keyring doesn't exist. +.TP +.B ENOMEM +Insufficient memory to create a key. +.TP +.B EPERM +The +.I type +started with a period (\[aq].\[aq]). +Key types that begin with a period are reserved to the implementation. +.TP +.B EPERM +.I type +was +.I \[dq]keyring\[dq] +and the +.I description +started with a period (\[aq].\[aq]). +Keyrings with descriptions (names) +that begin with a period are reserved to the implementation. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.10. +.SH NOTES +glibc does not provide a wrapper for this system call. +A wrapper is provided in the +.I libkeyutils +library. +(The accompanying package provides the +.I +header file.) +When employing the wrapper in that library, link with +.IR \-lkeyutils . +.SH EXAMPLES +The program below creates a key with the type, description, and payload +specified in its command-line arguments, +and links that key into the session keyring. +The following shell session demonstrates the use of the program: +.P +.in +4n +.EX +$ \fB./a.out user mykey "Some payload"\fP +Key ID is 64a4dca +$ \fBgrep \[aq]64a4dca\[aq] /proc/keys\fP +064a4dca I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 12 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (add_key.c) +.EX +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + key_serial_t key; +\& + if (argc != 4) { + fprintf(stderr, "Usage: %s type description payload\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]), + KEY_SPEC_SESSION_KEYRING); + if (key == \-1) { + perror("add_key"); + exit(EXIT_FAILURE); + } +\& + printf("Key ID is %jx\en", (uintmax_t) key); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7) +.P +The kernel source files +.I Documentation/security/keys/core.rst +and +.I Documentation/keys/request\-key.rst +(or, before Linux 4.13, in the files +.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 +.I Documentation/security/keys.txt +and +.\" commit 3db38ed76890565772fcca3279cc8d454ea6176b +.IR Documentation/security/keys\-request\-key.txt ). diff --git a/man/man2/adjtimex.2 b/man/man2/adjtimex.2 new file mode 100644 index 0000000..0e9338e --- /dev/null +++ b/man/man2/adjtimex.2 @@ -0,0 +1,595 @@ +'\" t +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" and Copyright (C) 2014, 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1997-07-30 by Paul Slootman +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH adjtimex 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +adjtimex, clock_adjtime, ntp_adjtime \- tune kernel clock +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int adjtimex(struct timex *" "buf" ); +.P +.BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" ); +.P +.BI "int ntp_adjtime(struct timex *" buf ); +.fi +.SH DESCRIPTION +Linux uses David L.\& Mills' clock adjustment algorithm (see RFC\ 5905). +The system call +.BR adjtimex () +reads and optionally sets adjustment parameters for this algorithm. +It takes a pointer to a +.I timex +structure, updates kernel parameters from (selected) field values, +and returns the same structure updated with the current kernel values. +This structure is declared as follows: +.P +.in +4n +.EX +struct timex { + int modes; /* Mode selector */ + long offset; /* Time offset; nanoseconds, if STA_NANO + status flag is set, otherwise + microseconds */ + long freq; /* Frequency offset; see NOTES for units */ + long maxerror; /* Maximum error (microseconds) */ + long esterror; /* Estimated error (microseconds) */ + int status; /* Clock command/status */ + long constant; /* PLL (phase\-locked loop) time constant */ + long precision; /* Clock precision + (microseconds, read\-only) */ + long tolerance; /* Clock frequency tolerance (read\-only); + see NOTES for units */ + struct timeval time; + /* Current time (read\-only, except for + ADJ_SETOFFSET); upon return, time.tv_usec + contains nanoseconds, if STA_NANO status + flag is set, otherwise microseconds */ + long tick; /* Microseconds between clock ticks */ + long ppsfreq; /* PPS (pulse per second) frequency + (read\-only); see NOTES for units */ + long jitter; /* PPS jitter (read\-only); nanoseconds, if + STA_NANO status flag is set, otherwise + microseconds */ + int shift; /* PPS interval duration + (seconds, read\-only) */ + long stabil; /* PPS stability (read\-only); + see NOTES for units */ + long jitcnt; /* PPS count of jitter limit exceeded + events (read\-only) */ + long calcnt; /* PPS count of calibration intervals + (read\-only) */ + long errcnt; /* PPS count of calibration errors + (read\-only) */ + long stbcnt; /* PPS count of stability limit exceeded + events (read\-only) */ + int tai; /* TAI offset, as set by previous ADJ_TAI + operation (seconds, read\-only, + since Linux 2.6.26) */ + /* Further padding bytes to allow for future expansion */ +}; +.EE +.in +.P +The +.I modes +field determines which parameters, if any, to set. +(As described later in this page, +the constants used for +.BR ntp_adjtime () +are equivalent but differently named.) +It is a bit mask containing a +bitwise OR +combination of zero or more of the following bits: +.TP +.B ADJ_OFFSET +Set time offset from +.IR buf.offset . +Since Linux 2.6.26, +.\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23 +the supplied value is clamped to the range (\-0.5s, +0.5s). +In older kernels, an +.B EINVAL +error occurs if the supplied value is out of range. +.TP +.B ADJ_FREQUENCY +Set frequency offset from +.IR buf.freq . +Since Linux 2.6.26, +.\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23 +the supplied value is clamped to the range (\-32768000, +32768000). +In older kernels, an +.B EINVAL +error occurs if the supplied value is out of range. +.TP +.B ADJ_MAXERROR +Set maximum time error from +.IR buf.maxerror . +.TP +.B ADJ_ESTERROR +Set estimated time error from +.IR buf.esterror . +.TP +.B ADJ_STATUS +Set clock status bits from +.IR buf.status . +A description of these bits is provided below. +.TP +.B ADJ_TIMECONST +Set PLL time constant from +.IR buf.constant . +If the +.B STA_NANO +status flag (see below) is clear, the kernel adds 4 to this value. +.TP +.BR ADJ_SETOFFSET " (since Linux 2.6.39)" +.\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762 +.\" Author: Richard Cochran +Add +.I buf.time +to the current time. +If +.I buf.status +includes the +.B ADJ_NANO +flag, then +.I buf.time.tv_usec +is interpreted as a nanosecond value; +otherwise it is interpreted as microseconds. +.IP +The value of +.I buf.time +is the sum of its two fields, but the +field +.I buf.time.tv_usec +must always be nonnegative. +The following example shows how to +normalize a +.I timeval +with nanosecond resolution. +.IP +.in +4n +.EX +while (buf.time.tv_usec < 0) { + buf.time.tv_sec \-= 1; + buf.time.tv_usec += 1000000000; +} +.EE +.in +.TP +.BR ADJ_MICRO " (since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel +Select microsecond resolution. +.TP +.BR ADJ_NANO " (since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel +Select nanosecond resolution. +Only one of +.B ADJ_MICRO +and +.B ADJ_NANO +should be specified. +.TP +.BR ADJ_TAI " (since Linux 2.6.26)" +.\" commit 153b5d054ac2d98ea0d86504884326b6777f683d +Set TAI (Atomic International Time) offset from +.IR buf.constant . +.IP +.B ADJ_TAI +should not be used in conjunction with +.BR ADJ_TIMECONST , +since the latter mode also employs the +.I buf.constant +field. +.IP +For a complete explanation of TAI +and the difference between TAI and UTC, see +.UR http://www.bipm.org/en/bipm/tai/tai.html +.I BIPM +.UE +.TP +.B ADJ_TICK +Set tick value from +.IR buf.tick . +.P +Alternatively, +.I modes +can be specified as either of the following (multibit mask) values, +in which case other bits should not be specified in +.IR modes : +.\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001 +.\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!! +.TP +.B ADJ_OFFSET_SINGLESHOT +.\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001 +.\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000) +Old-fashioned +.BR adjtime (3): +(gradually) adjust time by value specified in +.IR buf.offset , +which specifies an adjustment in microseconds. +.TP +.BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)" +.\" In user space, ADJ_OFFSET_SS_READ is 0xa001 +.\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with +.\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001) +Return (in +.IR buf.offset ) +the remaining amount of time to be adjusted after an earlier +.B ADJ_OFFSET_SINGLESHOT +operation. +This feature was added in Linux 2.6.24, +.\" commit 52bfb36050c8529d9031d2c2513b281a360922ec +but did not work correctly +.\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1 +until Linux 2.6.28. +.P +Ordinary users are restricted to a value of either 0 or +.B ADJ_OFFSET_SS_READ +for +.IR modes . +Only the superuser may set any parameters. +.P +The +.I buf.status +field is a bit mask that is used to set and/or retrieve status +bits associated with the NTP implementation. +Some bits in the mask are both readable and settable, +while others are read-only. +.TP +.BR STA_PLL " (read-write)" +Enable phase-locked loop (PLL) updates via +.BR ADJ_OFFSET . +.TP +.BR STA_PPSFREQ " (read-write)" +Enable PPS (pulse-per-second) frequency discipline. +.TP +.BR STA_PPSTIME " (read-write)" +Enable PPS time discipline. +.TP +.BR STA_FLL " (read-write)" +Select frequency-locked loop (FLL) mode. +.TP +.BR STA_INS " (read-write)" +Insert a leap second after the last second of the UTC day, +thus extending the last minute of the day by one second. +Leap-second insertion will occur each day, so long as this flag remains set. +.\" John Stultz; +.\" Usually this is written as extending the day by one second, +.\" which is represented as: +.\" 23:59:59 +.\" 23:59:60 +.\" 00:00:00 +.\" +.\" But since posix cannot represent 23:59:60, we repeat the last second: +.\" 23:59:59 + TIME_INS +.\" 23:59:59 + TIME_OOP +.\" 00:00:00 + TIME_WAIT +.\" +.TP +.BR STA_DEL " (read-write)" +Delete a leap second at the last second of the UTC day. +.\" John Stultz: +.\" Similarly the progression here is: +.\" 23:59:57 + TIME_DEL +.\" 23:59:58 + TIME_DEL +.\" 00:00:00 + TIME_WAIT +Leap second deletion will occur each day, so long as this flag +remains set. +.\" FIXME Does there need to be a statement that it is nonsensical to set +.\" to set both STA_INS and STA_DEL? +.TP +.BR STA_UNSYNC " (read-write)" +Clock unsynchronized. +.TP +.BR STA_FREQHOLD " (read-write)" +Hold frequency. +.\" Following text from John Stultz: +Normally adjustments made via +.B ADJ_OFFSET +result in dampened frequency adjustments also being made. +So a single call corrects the current offset, +but as offsets in the same direction are made repeatedly, +the small frequency adjustments will accumulate to fix the long-term skew. +.IP +This flag prevents the small frequency adjustment from being made +when correcting for an +.B ADJ_OFFSET +value. +.\" According to the Kernel Application Program Interface document, +.\" STA_FREQHOLD is not used by the NTP version 4 daemon +.TP +.BR STA_PPSSIGNAL " (read-only)" +A valid PPS (pulse-per-second) signal is present. +.TP +.BR STA_PPSJITTER " (read-only)" +PPS signal jitter exceeded. +.TP +.BR STA_PPSWANDER " (read-only)" +PPS signal wander exceeded. +.TP +.BR STA_PPSERROR " (read-only)" +PPS signal calibration error. +.TP +.BR STA_CLOCKERR " (read-only)" +Clock hardware fault. +.\" Not set in current kernel (4.5), but checked in a few places +.TP +.BR STA_NANO " (read-only; since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel +Resolution (0 = microsecond, 1 = nanoseconds). +Set via +.BR ADJ_NANO , +cleared via +.BR ADJ_MICRO . +.TP +.BR STA_MODE " (since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel +Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop). +.TP +.BR STA_CLK " (read-only; since Linux 2.6.26)" +.\" commit eea83d896e318bda54be2d2770d2c5d6668d11db +.\" Author: Roman Zippel +Clock source (0 = A, 1 = B); currently unused. +.P +Attempts to set read-only +.I status +bits are silently ignored. +.\" +.SS clock_adjtime () +The +.BR clock_adjtime () +system call (added in Linux 2.6.39) behaves like +.BR adjtimex () +but takes an additional +.I clk_id +argument to specify the particular clock on which to act. +.SS ntp_adjtime () +The +.BR ntp_adjtime () +library function +(described in the NTP "Kernel Application Program API", KAPI) +is a more portable interface for performing the same task as +.BR adjtimex (). +Other than the following points, it is identical to +.BR adjtimex (): +.IP \[bu] 3 +The constants used in +.I modes +are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus, +.BR MOD_OFFSET , +.BR MOD_FREQUENCY , +and so on), other than the exceptions noted in the following points. +.IP \[bu] +.B MOD_CLKA +is the synonym for +.BR ADJ_OFFSET_SINGLESHOT . +.IP \[bu] +.B MOD_CLKB +is the synonym for +.BR ADJ_TICK . +.IP \[bu] +The is no synonym for +.BR ADJ_OFFSET_SS_READ , +which is not described in the KAPI. +.SH RETURN VALUE +On success, +.BR adjtimex () +and +.BR ntp_adjtime () +return the clock state; that is, one of the following values: +.TP 12 +.B TIME_OK +Clock synchronized, no leap second adjustment pending. +.TP +.B TIME_INS +Indicates that a leap second will be added at the end of the UTC day. +.TP +.B TIME_DEL +Indicates that a leap second will be deleted at the end of the UTC day. +.TP +.B TIME_OOP +Insertion of a leap second is in progress. +.TP +.B TIME_WAIT +A leap-second insertion or deletion has been completed. +This value will be returned until the next +.B ADJ_STATUS +operation clears the +.B STA_INS +and +.B STA_DEL +flags. +.TP +.B TIME_ERROR +The system clock is not synchronized to a reliable server. +This value is returned when any of the following holds true: +.RS +.IP \[bu] 3 +Either +.B STA_UNSYNC +or +.B STA_CLOCKERR +is set. +.IP \[bu] +.B STA_PPSSIGNAL +is clear and either +.B STA_PPSFREQ +or +.B STA_PPSTIME +is set. +.IP \[bu] +.B STA_PPSTIME +and +.B STA_PPSJITTER +are both set. +.IP \[bu] +.B STA_PPSFREQ +is set and either +.B STA_PPSWANDER +or +.B STA_PPSJITTER +is set. +.RE +.IP +The symbolic name +.B TIME_BAD +is a synonym for +.BR TIME_ERROR , +provided for backward compatibility. +.P +Note that starting with Linux 3.4, +.\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous +.\" operation, so we can no longer rely on the return code. +the call operates asynchronously and the return value usually will +not reflect a state change caused by the call itself. +.P +On failure, these calls return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I buf +does not point to writable memory. +.TP +.BR EINVAL " (before Linux 2.6.26)" +An attempt was made to set +.I buf.freq +to a value outside the range (\-33554432, +33554432). +.\" From a quick glance, it appears there was no clamping or range check +.\" for buf.freq before Linux 2.0 +.TP +.BR EINVAL " (before Linux 2.6.26)" +An attempt was made to set +.I buf.offset +to a value outside the permitted range. +Before Linux 2.0, the permitted range was (\-131072, +131072). +From Linux 2.0 onwards, the permitted range was (\-512000, +512000). +.TP +.B EINVAL +An attempt was made to set +.I buf.status +to a value other than those listed above. +.TP +.B EINVAL +The +.I clk_id +given to +.BR clock_adjtime () +is invalid for one of two reasons. +Either the System-V style hard-coded +positive clock ID value is out of range, or the dynamic +.I clk_id +does not refer to a valid instance of a clock object. +See +.BR clock_gettime (2) +for a discussion of dynamic clocks. +.TP +.B EINVAL +An attempt was made to set +.I buf.tick +to a value outside the range +.RB 900000/ HZ +to +.RB 1100000/ HZ , +where +.B HZ +is the system timer interrupt frequency. +.TP +.B ENODEV +The hot-pluggable device (like USB for example) represented by a +dynamic +.I clk_id +has disappeared after its character device was opened. +See +.BR clock_gettime (2) +for a discussion of dynamic clocks. +.TP +.B EOPNOTSUPP +The given +.I clk_id +does not support adjustment. +.TP +.B EPERM +.I buf.modes +is neither 0 nor +.BR ADJ_OFFSET_SS_READ , +and the caller does not have sufficient privilege. +Under Linux, the +.B CAP_SYS_TIME +capability is required. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR \%ntp_adjtime () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR adjtimex () +.TQ +.BR clock_adjtime () +Linux. +.P +The preferred API for the NTP daemon is +.BR ntp_adjtime (). +.SH NOTES +In struct +.IR timex , +.IR freq , +.IR ppsfreq , +and +.I stabil +are ppm (parts per million) with a 16-bit fractional part, +which means that a value of 1 in one of those fields +actually means 2\[ha]-16 ppm, and 2\[ha]16=65536 is 1 ppm. +This is the case for both input values (in the case of +.IR freq ) +and output values. +.P +The leap-second processing triggered by +.B STA_INS +and +.B STA_DEL +is done by the kernel in timer context. +Thus, it will take one tick into the second +for the leap second to be inserted or deleted. +.SH SEE ALSO +.BR clock_gettime (2), +.BR clock_settime (2), +.BR settimeofday (2), +.BR adjtime (3), +.BR ntp_gettime (3), +.BR capabilities (7), +.BR time (7), +.BR adjtimex (8), +.BR hwclock (8) +.P +.ad l +.UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm +NTP "Kernel Application Program Interface" +.UE diff --git a/man/man2/afs_syscall.2 b/man/man2/afs_syscall.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/afs_syscall.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/alarm.2 b/man/man2/alarm.2 new file mode 100644 index 0000000..65a53a1 --- /dev/null +++ b/man/man2/alarm.2 @@ -0,0 +1,81 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 21 19:42:57 1993 by Rik Faith +.\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer +.\" Modified Wed Nov 6 03:46:05 1996 by Eric S. Raymond +.\" +.TH alarm 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +alarm \- set an alarm clock for delivery of a signal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "unsigned int alarm(unsigned int " seconds ); +.fi +.SH DESCRIPTION +.BR alarm () +arranges for a +.B SIGALRM +signal to be delivered to the calling process in +.I seconds +seconds. +.P +If +.I seconds +is zero, any pending alarm is canceled. +.P +In any event any previously set +.BR alarm () +is canceled. +.SH RETURN VALUE +.BR alarm () +returns the number of seconds remaining until any previously scheduled +alarm was due to be delivered, or zero if there was no previously +scheduled alarm. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +.BR alarm () +and +.BR setitimer (2) +share the same timer; calls to one will interfere with use of the +other. +.P +Alarms created by +.BR alarm () +are preserved across +.BR execve (2) +and are not inherited by children created via +.BR fork (2). +.P +.BR sleep (3) +may be implemented using +.BR SIGALRM ; +mixing calls to +.BR alarm () +and +.BR sleep (3) +is a bad idea. +.P +Scheduling delays can, as ever, cause the execution of the process to +be delayed by an arbitrary amount of time. +.SH SEE ALSO +.BR gettimeofday (2), +.BR pause (2), +.BR select (2), +.BR setitimer (2), +.BR sigaction (2), +.BR signal (2), +.BR timer_create (2), +.BR timerfd_create (2), +.BR sleep (3), +.BR time (7) diff --git a/man/man2/alloc_hugepages.2 b/man/man2/alloc_hugepages.2 new file mode 100644 index 0000000..36c9d47 --- /dev/null +++ b/man/man2/alloc_hugepages.2 @@ -0,0 +1,135 @@ +.\" Copyright 2003 Andries E. Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH alloc_hugepages 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +alloc_hugepages, free_hugepages \- allocate or free huge pages +.SH SYNOPSIS +.nf +.BI "void *syscall(SYS_alloc_hugepages, int " key ", void " addr [. len "], \ +size_t " len , +.BI " int " prot ", int " flag ); +.\" asmlinkage unsigned long sys_alloc_hugepages(int key, unsigned long addr, +.\" unsigned long len, int prot, int flag); +.BI "int syscall(SYS_free_hugepages, void *" addr ); +.\" asmlinkage int sys_free_hugepages(unsigned long addr); +.fi +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The system calls +.BR alloc_hugepages () +and +.BR free_hugepages () +were introduced in Linux 2.5.36 and removed again in Linux 2.5.54. +They existed only on i386 and ia64 (when built with +.BR CONFIG_HUGETLB_PAGE ). +In Linux 2.4.20, the syscall numbers exist, +but the calls fail with the error +.BR ENOSYS . +.P +On i386 the memory management hardware knows about ordinary pages (4\ KiB) +and huge pages (2 or 4\ MiB). +Similarly ia64 knows about huge pages of +several sizes. +These system calls serve to map huge pages into the +process's memory or to free them again. +Huge pages are locked into memory, and are not swapped. +.P +The +.I key +argument is an identifier. +When zero the pages are private, and +not inherited by children. +When positive the pages are shared with other applications using the same +.IR key , +and inherited by child processes. +.P +The +.I addr +argument of +.BR free_hugepages () +tells which page is being freed: it was the return value of a +call to +.BR alloc_hugepages (). +(The memory is first actually freed when all users have released it.) +The +.I addr +argument of +.BR alloc_hugepages () +is a hint, that the kernel may or may not follow. +Addresses must be properly aligned. +.P +The +.I len +argument is the length of the required segment. +It must be a multiple of the huge page size. +.P +The +.I prot +argument specifies the memory protection of the segment. +It is one of +.BR PROT_READ , +.BR PROT_WRITE , +.BR PROT_EXEC . +.P +The +.I flag +argument is ignored, unless +.I key +is positive. +In that case, if +.I flag +is +.BR IPC_CREAT , +then a new huge page segment is created when none +with the given key existed. +If this flag is not set, then +.B ENOENT +is returned when no segment with the given key exists. +.SH RETURN VALUE +On success, +.BR alloc_hugepages () +returns the allocated virtual address, and +.BR free_hugepages () +returns zero. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOSYS +The system call is not supported on this kernel. +.SH FILES +.TP +.I /proc/sys/vm/nr_hugepages +Number of configured hugetlb pages. +This can be read and written. +.TP +.I /proc/meminfo +Gives info on the number of configured hugetlb pages and on their size +in the three variables HugePages_Total, HugePages_Free, Hugepagesize. +.SH STANDARDS +Linux on Intel processors. +.SH HISTORY +These system calls are gone; +they existed only in Linux 2.5.36 through to Linux 2.5.54. +.SH NOTES +Now the hugetlbfs filesystem can be used instead. +Memory backed by huge pages (if the CPU supports them) is obtained by +using +.BR mmap (2) +to map files in this virtual filesystem. +.P +The maximal number of huge pages can be specified using the +.B hugepages= +boot parameter. +.\".P +.\" requires CONFIG_HUGETLB_PAGE (under "Processor type and features") +.\" and CONFIG_HUGETLBFS (under "Filesystems"). +.\" mount \-t hugetlbfs hugetlbfs /huge +.\" SHM_HUGETLB diff --git a/man/man2/arch_prctl.2 b/man/man2/arch_prctl.2 new file mode 100644 index 0000000..1e97b72 --- /dev/null +++ b/man/man2/arch_prctl.2 @@ -0,0 +1,176 @@ +.\" Copyright (C) 2003 Andi Kleen +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH arch_prctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +arch_prctl \- set architecture-specific thread state +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " ARCH_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_arch_prctl, int " op ", unsigned long " addr ); +.BI "int syscall(SYS_arch_prctl, int " op ", unsigned long *" addr ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR arch_prctl (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR arch_prctl () +sets architecture-specific process or thread state. +.I op +selects an operation +and passes argument +.I addr +to it; +.I addr +is interpreted as either an +.I "unsigned long" +for the "set" operations, or as an +.IR "unsigned long\ *" , +for the "get" operations. +.P +Subfunctions for both x86 and x86-64 are: +.TP +.BR ARCH_SET_CPUID " (since Linux 4.12)" +.\" commit e9ea1e7f53b852147cbd568b0568c7ad97ec21a3 +Enable +.RI ( "addr != 0" ) +or disable +.RI ( "addr == 0" ) +the +.I cpuid +instruction for the calling thread. +The instruction is enabled by default. +If disabled, any execution of a +.I cpuid +instruction will instead generate a +.B SIGSEGV +signal. +This feature can be used to emulate +.I cpuid +results that differ from what the underlying +hardware would have produced (e.g., in a paravirtualization setting). +.IP +The +.B ARCH_SET_CPUID +setting is preserved across +.BR fork (2) +and +.BR clone (2) +but reset to the default (i.e., +.I cpuid +enabled) on +.BR execve (2). +.TP +.BR ARCH_GET_CPUID " (since Linux 4.12)" +Return the setting of the flag manipulated by +.B ARCH_SET_CPUID +as the result of the system call (1 for enabled, 0 for disabled). +.I addr +is ignored. +.TP +Subfunctions for x86-64 only are: +.TP +.B ARCH_SET_FS +Set the 64-bit base for the +.I FS +register to +.IR addr . +.TP +.B ARCH_GET_FS +Return the 64-bit base value for the +.I FS +register of the calling thread in the +.I unsigned long +pointed to by +.IR addr . +.TP +.B ARCH_SET_GS +Set the 64-bit base for the +.I GS +register to +.IR addr . +.TP +.B ARCH_GET_GS +Return the 64-bit base value for the +.I GS +register of the calling thread in the +.I unsigned long +pointed to by +.IR addr . +.SH RETURN VALUE +On success, +.BR arch_prctl () +returns 0; on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I addr +points to an unmapped address or is outside the process address space. +.TP +.B EINVAL +.I op +is not a valid operation. +.TP +.B ENODEV +.B ARCH_SET_CPUID +was requested, but the underlying hardware does not support CPUID faulting. +.TP +.B EPERM +.I addr +is outside the process address space. +.\" .SH AUTHOR +.\" Man page written by Andi Kleen. +.SH STANDARDS +Linux/x86-64. +.SH NOTES +.BR arch_prctl () +is supported only on Linux/x86-64 for 64-bit programs currently. +.P +The 64-bit base changes when a new 32-bit segment selector is loaded. +.P +.B ARCH_SET_GS +is disabled in some kernels. +.P +Context switches for 64-bit segment bases are rather expensive. +As an optimization, if a 32-bit TLS base address is used, +.BR arch_prctl () +may use a real TLS entry as if +.BR set_thread_area (2) +had been called, instead of manipulating the segment base register directly. +Memory in the first 2\ GB of address space can be allocated by using +.BR mmap (2) +with the +.B MAP_32BIT +flag. +.P +Because of the aforementioned optimization, using +.BR arch_prctl () +and +.BR set_thread_area (2) +in the same thread is dangerous, as they may overwrite each other's +TLS entries. +.P +.I FS +may be already used by the threading library. +Programs that use +.B ARCH_SET_FS +directly are very likely to crash. +.SH SEE ALSO +.BR mmap (2), +.BR modify_ldt (2), +.BR prctl (2), +.BR set_thread_area (2) +.P +AMD X86-64 Programmer's manual diff --git a/man/man2/arm_fadvise.2 b/man/man2/arm_fadvise.2 new file mode 100644 index 0000000..53f54a1 --- /dev/null +++ b/man/man2/arm_fadvise.2 @@ -0,0 +1 @@ +.so man2/posix_fadvise.2 diff --git a/man/man2/arm_fadvise64_64.2 b/man/man2/arm_fadvise64_64.2 new file mode 100644 index 0000000..53f54a1 --- /dev/null +++ b/man/man2/arm_fadvise64_64.2 @@ -0,0 +1 @@ +.so man2/posix_fadvise.2 diff --git a/man/man2/arm_sync_file_range.2 b/man/man2/arm_sync_file_range.2 new file mode 100644 index 0000000..ad7a1e6 --- /dev/null +++ b/man/man2/arm_sync_file_range.2 @@ -0,0 +1 @@ +.so man2/sync_file_range.2 diff --git a/man/man2/bdflush.2 b/man/man2/bdflush.2 new file mode 100644 index 0000000..dc0c0f8 --- /dev/null +++ b/man/man2/bdflush.2 @@ -0,0 +1,103 @@ +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH bdflush 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bdflush \- start, flush, or tune buffer-dirty-flush daemon +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int bdflush(int " func ", long *" address ); +.BI "[[deprecated]] int bdflush(int " func ", long " data ); +.fi +.SH DESCRIPTION +.IR Note : +Since Linux 2.6, +.\" As noted in changes in the 2.5.12 source +this system call is deprecated and does nothing. +It is likely to disappear altogether in a future kernel release. +Nowadays, the task performed by +.BR bdflush () +is handled by the kernel +.I pdflush +thread. +.P +.BR bdflush () +starts, flushes, or tunes the buffer-dirty-flush daemon. +Only a privileged process (one with the +.B CAP_SYS_ADMIN +capability) may call +.BR bdflush (). +.P +If +.I func +is negative or 0, and no daemon has been started, then +.BR bdflush () +enters the daemon code and never returns. +.P +If +.I func +is 1, +some dirty buffers are written to disk. +.P +If +.I func +is 2 or more and is even (low bit is 0), then +.I address +is the address of a long word, +and the tuning parameter numbered +.RI "(" "func" "\-2)/2" +is returned to the caller in that address. +.P +If +.I func +is 3 or more and is odd (low bit is 1), then +.I data +is a long word, +and the kernel sets tuning parameter numbered +.RI "(" "func" "\-3)/2" +to that value. +.P +The set of parameters, their values, and their valid ranges +are defined in the Linux kernel source file +.IR fs/buffer.c . +.SH RETURN VALUE +If +.I func +is negative or 0 and the daemon successfully starts, +.BR bdflush () +never returns. +Otherwise, the return value is 0 on success and \-1 on failure, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBUSY +An attempt was made to enter the daemon code after +another process has already entered. +.TP +.B EFAULT +.I address +points outside your accessible address space. +.TP +.B EINVAL +An attempt was made to read or write an invalid parameter number, +or to write an invalid value to a parameter. +.TP +.B EPERM +Caller does not have the +.B CAP_SYS_ADMIN +capability. +.SH STANDARDS +Linux. +.SH HISTORY +Since glibc 2.23, glibc no longer supports this obsolete system call. +.SH SEE ALSO +.BR sync (1), +.BR fsync (2), +.BR sync (2) diff --git a/man/man2/bind.2 b/man/man2/bind.2 new file mode 100644 index 0000000..9160550 --- /dev/null +++ b/man/man2/bind.2 @@ -0,0 +1,286 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" and Copyright 2005-2007, Michael Kerrisk +.\" Portions extracted from /usr/include/sys/socket.h, which does not have +.\" any authorship information in it. It is probably available under the GPL. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page: +.\" +.\" Copyright (c) 1983 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond +.\" Modified 1998 by Andi Kleen +.\" $Id: bind.2,v 1.3 1999/04/23 19:56:07 freitag Exp $ +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH bind 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bind \- bind a name to a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int bind(int " sockfd ", const struct sockaddr *" addr , +.BI " socklen_t " addrlen ); +.fi +.SH DESCRIPTION +When a socket is created with +.BR socket (2), +it exists in a name space (address family) but has no address assigned to it. +.BR bind () +assigns the address specified by +.I addr +to the socket referred to by the file descriptor +.IR sockfd . +.I addrlen +specifies the size, in bytes, of the address structure pointed to by +.IR addr . +Traditionally, this operation is called \[lq]assigning a name to a socket\[rq]. +.P +It is normally necessary to assign a local address using +.BR bind () +before a +.B SOCK_STREAM +socket may receive connections (see +.BR accept (2)). +.P +The rules used in name binding vary between address families. +Consult the manual entries in Section 7 for detailed information. +For +.BR AF_INET , +see +.BR ip (7); +for +.BR AF_INET6 , +see +.BR ipv6 (7); +for +.BR AF_UNIX , +see +.BR unix (7); +for +.BR AF_APPLETALK , +see +.BR ddp (7); +for +.BR AF_PACKET , +see +.BR packet (7); +for +.BR AF_X25 , +see +.BR x25 (7); +and for +.BR AF_NETLINK , +see +.BR netlink (7). +.P +The actual structure passed for the +.I addr +argument will depend on the address family. +The +.I sockaddr +structure is defined as something like: +.P +.in +4n +.EX +struct sockaddr { + sa_family_t sa_family; + char sa_data[14]; +} +.EE +.in +.P +The only purpose of this structure is to cast the structure +pointer passed in +.I addr +in order to avoid compiler warnings. +See EXAMPLES below. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.\" e.g., privileged port in AF_INET domain +The address is protected, and the user is not the superuser. +.TP +.B EADDRINUSE +The given address is already in use. +.TP +.B EADDRINUSE +(Internet domain sockets) +The port number was specified as zero in the socket address structure, +but, upon attempting to bind to an ephemeral port, +it was determined that all port numbers in the ephemeral port range +are currently in use. +See the discussion of +.I /proc/sys/net/ipv4/ip_local_port_range +.BR ip (7). +.TP +.B EBADF +.I sockfd +is not a valid file descriptor. +.TP +.B EINVAL +The socket is already bound to an address. +.\" This may change in the future: see +.\" .I linux/unix/sock.c for details. +.TP +.B EINVAL +.I addrlen +is wrong, or +.I addr +is not a valid address for this socket's domain. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.P +The following errors are specific to UNIX domain +.RB ( AF_UNIX ) +sockets: +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B EADDRNOTAVAIL +A nonexistent interface was requested or the requested +address was not local. +.TP +.B EFAULT +.I addr +points outside the user's accessible address space. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR addr . +.TP +.B ENAMETOOLONG +.I addr +is too long. +.TP +.B ENOENT +A component in the directory prefix of the socket pathname does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EROFS +The socket inode would reside on a read-only filesystem. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD +.RB ( bind () +first appeared in 4.2BSD). +.\" SVr4 documents an additional +.\" .B ENOSR +.\" general error condition, and +.\" additional +.\" .B EIO +.\" and +.\" .B EISDIR +.\" UNIX-domain error conditions. +.SH BUGS +The transparent proxy options are not described. +.\" FIXME Document transparent proxy options +.SH EXAMPLES +An example of the use of +.BR bind () +with Internet domain sockets can be found in +.BR getaddrinfo (3). +.P +The following example shows how to bind a stream socket in the UNIX +.RB ( AF_UNIX ) +domain, and accept connections: +.\" listen.7 refers to this example. +.\" accept.7 refers to this example. +.\" unix.7 refers to this example. +.P +.\" SRC BEGIN (bind.c) +.EX +#include +#include +#include +#include +#include +#include +\& +#define MY_SOCK_PATH "/somepath" +#define LISTEN_BACKLOG 50 +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +int +main(void) +{ + int sfd, cfd; + socklen_t peer_addr_size; + struct sockaddr_un my_addr, peer_addr; +\& + sfd = socket(AF_UNIX, SOCK_STREAM, 0); + if (sfd == \-1) + handle_error("socket"); +\& + memset(&my_addr, 0, sizeof(my_addr)); + my_addr.sun_family = AF_UNIX; + strncpy(my_addr.sun_path, MY_SOCK_PATH, + sizeof(my_addr.sun_path) \- 1); +\& + if (bind(sfd, (struct sockaddr *) &my_addr, + sizeof(my_addr)) == \-1) + handle_error("bind"); +\& + if (listen(sfd, LISTEN_BACKLOG) == \-1) + handle_error("listen"); +\& + /* Now we can accept incoming connections one + at a time using accept(2). */ +\& + peer_addr_size = sizeof(peer_addr); + cfd = accept(sfd, (struct sockaddr *) &peer_addr, + &peer_addr_size); + if (cfd == \-1) + handle_error("accept"); +\& + /* Code to deal with incoming connection(s)... */ +\& + if (close(sfd) == \-1) + handle_error("close"); +\& + if (unlink(MY_SOCK_PATH) == \-1) + handle_error("unlink"); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR accept (2), +.BR connect (2), +.BR getsockname (2), +.BR listen (2), +.BR socket (2), +.BR getaddrinfo (3), +.BR getifaddrs (3), +.BR ip (7), +.BR ipv6 (7), +.BR path_resolution (7), +.BR socket (7), +.BR unix (7) diff --git a/man/man2/bpf.2 b/man/man2/bpf.2 new file mode 100644 index 0000000..7ff1b39 --- /dev/null +++ b/man/man2/bpf.2 @@ -0,0 +1,1273 @@ +.\" Copyright (C) 2015 Alexei Starovoitov +.\" and Copyright (C) 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH bpf 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bpf \- perform a command on an extended BPF map or program +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int bpf(int " cmd ", union bpf_attr *" attr ", unsigned int " size ); +.fi +.SH DESCRIPTION +The +.BR bpf () +system call performs a range of operations related to extended +Berkeley Packet Filters. +Extended BPF (or eBPF) is similar to +the original ("classic") BPF (cBPF) used to filter network packets. +For both cBPF and eBPF programs, +the kernel statically analyzes the programs before loading them, +in order to ensure that they cannot harm the running system. +.P +eBPF extends cBPF in multiple ways, including the ability to call +a fixed set of in-kernel helper functions +.\" See 'enum bpf_func_id' in include/uapi/linux/bpf.h +(via the +.B BPF_CALL +opcode extension provided by eBPF) +and access shared data structures such as eBPF maps. +.\" +.SS Extended BPF Design/Architecture +eBPF maps are a generic data structure for storage of different data types. +Data types are generally treated as binary blobs, so a user just specifies +the size of the key and the size of the value at map-creation time. +In other words, a key/value for a given map can have an arbitrary structure. +.P +A user process can create multiple maps (with key/value-pairs being +opaque bytes of data) and access them via file descriptors. +Different eBPF programs can access the same maps in parallel. +It's up to the user process and eBPF program to decide what they store +inside maps. +.P +There's one special map type, called a program array. +This type of map stores file descriptors referring to other eBPF programs. +When a lookup in the map is performed, the program flow is +redirected in-place to the beginning of another eBPF program and does not +return back to the calling program. +The level of nesting has a fixed limit of 32, +.\" Defined by the kernel constant MAX_TAIL_CALL_CNT in include/linux/bpf.h +so that infinite loops cannot be crafted. +At run time, the program file descriptors stored in the map can be modified, +so program functionality can be altered based on specific requirements. +All programs referred to in a program-array map must +have been previously loaded into the kernel via +.BR bpf (). +If a map lookup fails, the current program continues its execution. +See +.B BPF_MAP_TYPE_PROG_ARRAY +below for further details. +.P +Generally, eBPF programs are loaded by the user process and automatically +unloaded when the process exits. +In some cases, for example, +.BR tc\-bpf (8), +the program will continue to stay alive inside the kernel even after the +process that loaded the program exits. +In that case, +the tc subsystem holds a reference to the eBPF program after the +file descriptor has been closed by the user-space program. +Thus, whether a specific program continues to live inside the kernel +depends on how it is further attached to a given kernel subsystem +after it was loaded via +.BR bpf (). +.P +Each eBPF program is a set of instructions that is safe to run until +its completion. +An in-kernel verifier statically determines that the eBPF program +terminates and is safe to execute. +During verification, the kernel increments reference counts for each of +the maps that the eBPF program uses, +so that the attached maps can't be removed until the program is unloaded. +.P +eBPF programs can be attached to different events. +These events can be the arrival of network packets, tracing +events, classification events by network queueing disciplines +(for eBPF programs attached to a +.BR tc (8) +classifier), and other types that may be added in the future. +A new event triggers execution of the eBPF program, which +may store information about the event in eBPF maps. +Beyond storing data, eBPF programs may call a fixed set of +in-kernel helper functions. +.P +The same eBPF program can be attached to multiple events and different +eBPF programs can access the same map: +.P +.in +4n +.EX +tracing tracing tracing packet packet packet +event A event B event C on eth0 on eth1 on eth2 + | | | | | \[ha] + | | | | v | + \-\-> tracing <\-\- tracing socket tc ingress tc egress + prog_1 prog_2 prog_3 classifier action + | | | | prog_4 prog_5 + |\-\-\- \-\-\-\-\-| |\-\-\-\-\-\-| map_3 | | + map_1 map_2 \-\-| map_4 |\-\- +.EE +.in +.\" +.SS Arguments +The operation to be performed by the +.BR bpf () +system call is determined by the +.I cmd +argument. +Each operation takes an accompanying argument, +provided via +.IR attr , +which is a pointer to a union of type +.I bpf_attr +(see below). +The unused fields and padding must be zeroed out before the call. +The +.I size +argument is the size of the union pointed to by +.IR attr . +.P +The value provided in +.I cmd +is one of the following: +.TP +.B BPF_MAP_CREATE +Create a map and return a file descriptor that refers to the map. +The close-on-exec file descriptor flag (see +.BR fcntl (2)) +is automatically enabled for the new file descriptor. +.TP +.B BPF_MAP_LOOKUP_ELEM +Look up an element by key in a specified map and return its value. +.TP +.B BPF_MAP_UPDATE_ELEM +Create or update an element (key/value pair) in a specified map. +.TP +.B BPF_MAP_DELETE_ELEM +Look up and delete an element by key in a specified map. +.TP +.B BPF_MAP_GET_NEXT_KEY +Look up an element by key in a specified map and return the key +of the next element. +.TP +.B BPF_PROG_LOAD +Verify and load an eBPF program, +returning a new file descriptor associated with the program. +The close-on-exec file descriptor flag (see +.BR fcntl (2)) +is automatically enabled for the new file descriptor. +.IP +The +.I bpf_attr +union consists of various anonymous structures that are used by different +.BR bpf () +commands: +.P +.in +4n +.EX +union bpf_attr { + struct { /* Used by BPF_MAP_CREATE */ + __u32 map_type; + __u32 key_size; /* size of key in bytes */ + __u32 value_size; /* size of value in bytes */ + __u32 max_entries; /* maximum number of entries + in a map */ + }; +\& + struct { /* Used by BPF_MAP_*_ELEM and BPF_MAP_GET_NEXT_KEY + commands */ + __u32 map_fd; + __aligned_u64 key; + union { + __aligned_u64 value; + __aligned_u64 next_key; + }; + __u64 flags; + }; +\& + struct { /* Used by BPF_PROG_LOAD */ + __u32 prog_type; + __u32 insn_cnt; + __aligned_u64 insns; /* \[aq]const struct bpf_insn *\[aq] */ + __aligned_u64 license; /* \[aq]const char *\[aq] */ + __u32 log_level; /* verbosity level of verifier */ + __u32 log_size; /* size of user buffer */ + __aligned_u64 log_buf; /* user supplied \[aq]char *\[aq] + buffer */ + __u32 kern_version; + /* checked when prog_type=kprobe + (since Linux 4.1) */ +.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 + }; +} __attribute__((aligned(8))); +.EE +.in +.\" +.SS eBPF maps +Maps are a generic data structure for storage of different types of data. +They allow sharing of data between eBPF kernel programs, +and also between kernel and user-space applications. +.P +Each map type has the following attributes: +.IP \[bu] 3 +type +.IP \[bu] +maximum number of elements +.IP \[bu] +key size in bytes +.IP \[bu] +value size in bytes +.P +The following wrapper functions demonstrate how various +.BR bpf () +commands can be used to access the maps. +The functions use the +.I cmd +argument to invoke different operations. +.TP +.B BPF_MAP_CREATE +The +.B BPF_MAP_CREATE +command creates a new map, +returning a new file descriptor that refers to the map. +.IP +.in +4n +.EX +int +bpf_create_map(enum bpf_map_type map_type, + unsigned int key_size, + unsigned int value_size, + unsigned int max_entries) +{ + union bpf_attr attr = { + .map_type = map_type, + .key_size = key_size, + .value_size = value_size, + .max_entries = max_entries + }; +\& + return bpf(BPF_MAP_CREATE, &attr, sizeof(attr)); +} +.EE +.in +.IP +The new map has the type specified by +.IR map_type , +and attributes as specified in +.IR key_size , +.IR value_size , +and +.IR max_entries . +On success, this operation returns a file descriptor. +On error, \-1 is returned and +.I errno +is set to +.BR EINVAL , +.BR EPERM , +or +.BR ENOMEM . +.IP +The +.I key_size +and +.I value_size +attributes will be used by the verifier during program loading +to check that the program is calling +.BR bpf_map_*_elem () +helper functions with a correctly initialized +.I key +and to check that the program doesn't access the map element +.I value +beyond the specified +.IR value_size . +For example, when a map is created with a +.I key_size +of 8 and the eBPF program calls +.IP +.in +4n +.EX +bpf_map_lookup_elem(map_fd, fp \- 4) +.EE +.in +.IP +the program will be rejected, +since the in-kernel helper function +.IP +.in +4n +.EX +bpf_map_lookup_elem(map_fd, void *key) +.EE +.in +.IP +expects to read 8 bytes from the location pointed to by +.IR key , +but the +.I fp\ \-\ 4 +(where +.I fp +is the top of the stack) +starting address will cause out-of-bounds stack access. +.IP +Similarly, when a map is created with a +.I value_size +of 1 and the eBPF program contains +.IP +.in +4n +.EX +value = bpf_map_lookup_elem(...); +*(u32 *) value = 1; +.EE +.in +.IP +the program will be rejected, since it accesses the +.I value +pointer beyond the specified 1 byte +.I value_size +limit. +.IP +Currently, the following values are supported for +.IR map_type : +.IP +.in +4n +.EX +enum bpf_map_type { + BPF_MAP_TYPE_UNSPEC, /* Reserve 0 as invalid map type */ + BPF_MAP_TYPE_HASH, + BPF_MAP_TYPE_ARRAY, + BPF_MAP_TYPE_PROG_ARRAY, + BPF_MAP_TYPE_PERF_EVENT_ARRAY, + BPF_MAP_TYPE_PERCPU_HASH, + BPF_MAP_TYPE_PERCPU_ARRAY, + BPF_MAP_TYPE_STACK_TRACE, + BPF_MAP_TYPE_CGROUP_ARRAY, + BPF_MAP_TYPE_LRU_HASH, + BPF_MAP_TYPE_LRU_PERCPU_HASH, + BPF_MAP_TYPE_LPM_TRIE, + BPF_MAP_TYPE_ARRAY_OF_MAPS, + BPF_MAP_TYPE_HASH_OF_MAPS, + BPF_MAP_TYPE_DEVMAP, + BPF_MAP_TYPE_SOCKMAP, + BPF_MAP_TYPE_CPUMAP, + BPF_MAP_TYPE_XSKMAP, + BPF_MAP_TYPE_SOCKHASH, + BPF_MAP_TYPE_CGROUP_STORAGE, + BPF_MAP_TYPE_REUSEPORT_SOCKARRAY, + BPF_MAP_TYPE_PERCPU_CGROUP_STORAGE, + BPF_MAP_TYPE_QUEUE, + BPF_MAP_TYPE_STACK, + /* See /usr/include/linux/bpf.h for the full list. */ +}; +.EE +.in +.IP +.I map_type +selects one of the available map implementations in the kernel. +.\" FIXME We need an explanation of why one might choose each of +.\" these map implementations +For all map types, +eBPF programs access maps with the same +.BR bpf_map_lookup_elem () +and +.BR bpf_map_update_elem () +helper functions. +Further details of the various map types are given below. +.TP +.B BPF_MAP_LOOKUP_ELEM +The +.B BPF_MAP_LOOKUP_ELEM +command looks up an element with a given +.I key +in the map referred to by the file descriptor +.IR fd . +.IP +.in +4n +.EX +int +bpf_lookup_elem(int fd, const void *key, void *value) +{ + union bpf_attr attr = { + .map_fd = fd, + .key = ptr_to_u64(key), + .value = ptr_to_u64(value), + }; +\& + return bpf(BPF_MAP_LOOKUP_ELEM, &attr, sizeof(attr)); +} +.EE +.in +.IP +If an element is found, +the operation returns zero and stores the element's value into +.IR value , +which must point to a buffer of +.I value_size +bytes. +.IP +If no element is found, the operation returns \-1 and sets +.I errno +to +.BR ENOENT . +.TP +.B BPF_MAP_UPDATE_ELEM +The +.B BPF_MAP_UPDATE_ELEM +command +creates or updates an element with a given +.I key/value +in the map referred to by the file descriptor +.IR fd . +.IP +.in +4n +.EX +int +bpf_update_elem(int fd, const void *key, const void *value, + uint64_t flags) +{ + union bpf_attr attr = { + .map_fd = fd, + .key = ptr_to_u64(key), + .value = ptr_to_u64(value), + .flags = flags, + }; +\& + return bpf(BPF_MAP_UPDATE_ELEM, &attr, sizeof(attr)); +} +.EE +.in +.IP +The +.I flags +argument should be specified as one of the following: +.RS +.TP +.B BPF_ANY +Create a new element or update an existing element. +.TP +.B BPF_NOEXIST +Create a new element only if it did not exist. +.TP +.B BPF_EXIST +Update an existing element. +.RE +.IP +On success, the operation returns zero. +On error, \-1 is returned and +.I errno +is set to +.BR EINVAL , +.BR EPERM , +.BR ENOMEM , +or +.BR E2BIG . +.B E2BIG +indicates that the number of elements in the map reached the +.I max_entries +limit specified at map creation time. +.B EEXIST +will be returned if +.I flags +specifies +.B BPF_NOEXIST +and the element with +.I key +already exists in the map. +.B ENOENT +will be returned if +.I flags +specifies +.B BPF_EXIST +and the element with +.I key +doesn't exist in the map. +.TP +.B BPF_MAP_DELETE_ELEM +The +.B BPF_MAP_DELETE_ELEM +command +deletes the element whose key is +.I key +from the map referred to by the file descriptor +.IR fd . +.IP +.in +4n +.EX +int +bpf_delete_elem(int fd, const void *key) +{ + union bpf_attr attr = { + .map_fd = fd, + .key = ptr_to_u64(key), + }; +\& + return bpf(BPF_MAP_DELETE_ELEM, &attr, sizeof(attr)); +} +.EE +.in +.IP +On success, zero is returned. +If the element is not found, \-1 is returned and +.I errno +is set to +.BR ENOENT . +.TP +.B BPF_MAP_GET_NEXT_KEY +The +.B BPF_MAP_GET_NEXT_KEY +command looks up an element by +.I key +in the map referred to by the file descriptor +.I fd +and sets the +.I next_key +pointer to the key of the next element. +.IP +.in +4n +.EX +int +bpf_get_next_key(int fd, const void *key, void *next_key) +{ + union bpf_attr attr = { + .map_fd = fd, + .key = ptr_to_u64(key), + .next_key = ptr_to_u64(next_key), + }; +\& + return bpf(BPF_MAP_GET_NEXT_KEY, &attr, sizeof(attr)); +} +.EE +.in +.IP +If +.I key +is found, the operation returns zero and sets the +.I next_key +pointer to the key of the next element. +If +.I key +is not found, the operation returns zero and sets the +.I next_key +pointer to the key of the first element. +If +.I key +is the last element, \-1 is returned and +.I errno +is set to +.BR ENOENT . +Other possible +.I errno +values are +.BR ENOMEM , +.BR EFAULT , +.BR EPERM , +and +.BR EINVAL . +This method can be used to iterate over all elements in the map. +.TP +.B close(map_fd) +Delete the map referred to by the file descriptor +.IR map_fd . +When the user-space program that created a map exits, all maps will +be deleted automatically (but see NOTES). +.\" +.SS eBPF map types +The following map types are supported: +.TP +.B BPF_MAP_TYPE_HASH +.\" commit 0f8e4bd8a1fc8c4185f1630061d0a1f2d197a475 +Hash-table maps have the following characteristics: +.RS +.IP \[bu] 3 +Maps are created and destroyed by user-space programs. +Both user-space and eBPF programs +can perform lookup, update, and delete operations. +.IP \[bu] +The kernel takes care of allocating and freeing key/value pairs. +.IP \[bu] +The +.BR map_update_elem () +helper will fail to insert new element when the +.I max_entries +limit is reached. +(This ensures that eBPF programs cannot exhaust memory.) +.IP \[bu] +.BR map_update_elem () +replaces existing elements atomically. +.RE +.IP +Hash-table maps are +optimized for speed of lookup. +.TP +.B BPF_MAP_TYPE_ARRAY +.\" commit 28fbcfa08d8ed7c5a50d41a0433aad222835e8e3 +Array maps have the following characteristics: +.RS +.IP \[bu] 3 +Optimized for fastest possible lookup. +In the future the verifier/JIT compiler +may recognize lookup() operations that employ a constant key +and optimize it into constant pointer. +It is possible to optimize a non-constant +key into direct pointer arithmetic as well, since pointers and +.I value_size +are constant for the life of the eBPF program. +In other words, +.BR array_map_lookup_elem () +may be 'inlined' by the verifier/JIT compiler +while preserving concurrent access to this map from user space. +.IP \[bu] +All array elements pre-allocated and zero initialized at init time +.IP \[bu] +The key is an array index, and must be exactly four bytes. +.IP \[bu] +.BR map_delete_elem () +fails with the error +.BR EINVAL , +since elements cannot be deleted. +.IP \[bu] +.BR map_update_elem () +replaces elements in a +.B nonatomic +fashion; +for atomic updates, a hash-table map should be used instead. +There is however one special case that can also be used with arrays: +the atomic built-in +.B __sync_fetch_and_add() +can be used on 32 and 64 bit atomic counters. +For example, it can be +applied on the whole value itself if it represents a single counter, +or in case of a structure containing multiple counters, it could be +used on individual counters. +This is quite often useful for aggregation and accounting of events. +.RE +.IP +Among the uses for array maps are the following: +.RS +.IP \[bu] 3 +As "global" eBPF variables: an array of 1 element whose key is (index) 0 +and where the value is a collection of 'global' variables which +eBPF programs can use to keep state between events. +.IP \[bu] +Aggregation of tracing events into a fixed set of buckets. +.IP \[bu] +Accounting of networking events, for example, number of packets and packet +sizes. +.RE +.TP +.BR BPF_MAP_TYPE_PROG_ARRAY " (since Linux 4.2)" +A program array map is a special kind of array map whose map values +contain only file descriptors referring to other eBPF programs. +Thus, both the +.I key_size +and +.I value_size +must be exactly four bytes. +This map is used in conjunction with the +.BR bpf_tail_call () +helper. +.IP +This means that an eBPF program with a program array map attached to it +can call from kernel side into +.IP +.in +4n +.EX +void bpf_tail_call(void *context, void *prog_map, + unsigned int index); +.EE +.in +.IP +and therefore replace its own program flow with the one from the program +at the given program array slot, if present. +This can be regarded as kind of a jump table to a different eBPF program. +The invoked program will then reuse the same stack. +When a jump into the new program has been performed, +it won't return to the old program anymore. +.IP +If no eBPF program is found at the given index of the program array +(because the map slot doesn't contain a valid program file descriptor, +the specified lookup index/key is out of bounds, +or the limit of 32 +.\" MAX_TAIL_CALL_CNT +nested calls has been exceed), +execution continues with the current eBPF program. +This can be used as a fall-through for default cases. +.IP +A program array map is useful, for example, in tracing or networking, to +handle individual system calls or protocols in their own subprograms and +use their identifiers as an individual map index. +This approach may result in performance benefits, +and also makes it possible to overcome the maximum +instruction limit of a single eBPF program. +In dynamic environments, +a user-space daemon might atomically replace individual subprograms +at run-time with newer versions to alter overall program behavior, +for instance, if global policies change. +.\" +.SS eBPF programs +The +.B BPF_PROG_LOAD +command is used to load an eBPF program into the kernel. +The return value for this command is a new file descriptor associated +with this eBPF program. +.P +.in +4n +.EX +char bpf_log_buf[LOG_BUF_SIZE]; +\& +int +bpf_prog_load(enum bpf_prog_type type, + const struct bpf_insn *insns, int insn_cnt, + const char *license) +{ + union bpf_attr attr = { + .prog_type = type, + .insns = ptr_to_u64(insns), + .insn_cnt = insn_cnt, + .license = ptr_to_u64(license), + .log_buf = ptr_to_u64(bpf_log_buf), + .log_size = LOG_BUF_SIZE, + .log_level = 1, + }; +\& + return bpf(BPF_PROG_LOAD, &attr, sizeof(attr)); +} +.EE +.in +.P +.I prog_type +is one of the available program types: +.IP +.in +4n +.EX +enum bpf_prog_type { + BPF_PROG_TYPE_UNSPEC, /* Reserve 0 as invalid + program type */ + BPF_PROG_TYPE_SOCKET_FILTER, + BPF_PROG_TYPE_KPROBE, + BPF_PROG_TYPE_SCHED_CLS, + BPF_PROG_TYPE_SCHED_ACT, + BPF_PROG_TYPE_TRACEPOINT, + BPF_PROG_TYPE_XDP, + BPF_PROG_TYPE_PERF_EVENT, + BPF_PROG_TYPE_CGROUP_SKB, + BPF_PROG_TYPE_CGROUP_SOCK, + BPF_PROG_TYPE_LWT_IN, + BPF_PROG_TYPE_LWT_OUT, + BPF_PROG_TYPE_LWT_XMIT, + BPF_PROG_TYPE_SOCK_OPS, + BPF_PROG_TYPE_SK_SKB, + BPF_PROG_TYPE_CGROUP_DEVICE, + BPF_PROG_TYPE_SK_MSG, + BPF_PROG_TYPE_RAW_TRACEPOINT, + BPF_PROG_TYPE_CGROUP_SOCK_ADDR, + BPF_PROG_TYPE_LWT_SEG6LOCAL, + BPF_PROG_TYPE_LIRC_MODE2, + BPF_PROG_TYPE_SK_REUSEPORT, + BPF_PROG_TYPE_FLOW_DISSECTOR, + /* See /usr/include/linux/bpf.h for the full list. */ +}; +.EE +.in +.P +For further details of eBPF program types, see below. +.P +The remaining fields of +.I bpf_attr +are set as follows: +.IP \[bu] 3 +.I insns +is an array of +.I "struct bpf_insn" +instructions. +.IP \[bu] +.I insn_cnt +is the number of instructions in the program referred to by +.IR insns . +.IP \[bu] +.I license +is a license string, which must be GPL compatible to call helper functions +marked +.IR gpl_only . +(The licensing rules are the same as for kernel modules, +so that also dual licenses, such as "Dual BSD/GPL", may be used.) +.IP \[bu] +.I log_buf +is a pointer to a caller-allocated buffer in which the in-kernel +verifier can store the verification log. +This log is a multi-line string that can be checked by +the program author in order to understand how the verifier came to +the conclusion that the eBPF program is unsafe. +The format of the output can change at any time as the verifier evolves. +.IP \[bu] +.I log_size +size of the buffer pointed to by +.IR log_buf . +If the size of the buffer is not large enough to store all +verifier messages, \-1 is returned and +.I errno +is set to +.BR ENOSPC . +.IP \[bu] +.I log_level +verbosity level of the verifier. +A value of zero means that the verifier will not provide a log; +in this case, +.I log_buf +must be a null pointer, and +.I log_size +must be zero. +.P +Applying +.BR close (2) +to the file descriptor returned by +.B BPF_PROG_LOAD +will unload the eBPF program (but see NOTES). +.P +Maps are accessible from eBPF programs and are used to exchange data between +eBPF programs and between eBPF programs and user-space programs. +For example, +eBPF programs can process various events (like kprobe, packets) and +store their data into a map, +and user-space programs can then fetch data from the map. +Conversely, user-space programs can use a map as a configuration mechanism, +populating the map with values checked by the eBPF program, +which then modifies its behavior on the fly according to those values. +.\" +.\" +.SS eBPF program types +The eBPF program type +.RI ( prog_type ) +determines the subset of kernel helper functions that the program +may call. +The program type also determines the program input (context)\[em]the +format of +.I "struct bpf_context" +(which is the data blob passed into the eBPF program as the first argument). +.\" +.\" FIXME +.\" Somewhere in this page we need a general introduction to the +.\" bpf_context. For example, how does a BPF program access the +.\" context? +.P +For example, a tracing program does not have the exact same +subset of helper functions as a socket filter program +(though they may have some helpers in common). +Similarly, +the input (context) for a tracing program is a set of register values, +while for a socket filter it is a network packet. +.P +The set of functions available to eBPF programs of a given type may increase +in the future. +.P +The following program types are supported: +.TP +.BR BPF_PROG_TYPE_SOCKET_FILTER " (since Linux 3.19)" +Currently, the set of functions for +.B BPF_PROG_TYPE_SOCKET_FILTER +is: +.IP +.in +4n +.EX +bpf_map_lookup_elem(map_fd, void *key) + /* look up key in a map_fd */ +bpf_map_update_elem(map_fd, void *key, void *value) + /* update key/value */ +bpf_map_delete_elem(map_fd, void *key) + /* delete key in a map_fd */ +.EE +.in +.IP +The +.I bpf_context +argument is a pointer to a +.IR "struct __sk_buff" . +.\" FIXME: We need some text here to explain how the program +.\" accesses __sk_buff. +.\" See 'struct __sk_buff' and commit 9bac3d6d548e5 +.\" +.\" Alexei commented: +.\" Actually now in case of SOCKET_FILTER, SCHED_CLS, SCHED_ACT +.\" the program can now access skb fields. +.\" +.TP +.BR BPF_PROG_TYPE_KPROBE " (since Linux 4.1)" +.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 +[To be documented] +.\" FIXME Document this program type +.\" Describe allowed helper functions for this program type +.\" Describe bpf_context for this program type +.\" +.\" FIXME We need text here to describe 'kern_version' +.TP +.BR BPF_PROG_TYPE_SCHED_CLS " (since Linux 4.1)" +.\" commit 96be4325f443dbbfeb37d2a157675ac0736531a1 +.\" commit e2e9b6541dd4b31848079da80fe2253daaafb549 +[To be documented] +.\" FIXME Document this program type +.\" Describe allowed helper functions for this program type +.\" Describe bpf_context for this program type +.TP +.BR BPF_PROG_TYPE_SCHED_ACT " (since Linux 4.1)" +.\" commit 94caee8c312d96522bcdae88791aaa9ebcd5f22c +.\" commit a8cb5f556b567974d75ea29c15181c445c541b1f +[To be documented] +.\" FIXME Document this program type +.\" Describe allowed helper functions for this program type +.\" Describe bpf_context for this program type +.SS Events +Once a program is loaded, it can be attached to an event. +Various kernel subsystems have different ways to do so. +.P +Since Linux 3.19, +.\" commit 89aa075832b0da4402acebd698d0411dcc82d03e +the following call will attach the program +.I prog_fd +to the socket +.IR sockfd , +which was created by an earlier call to +.BR socket (2): +.P +.in +4n +.EX +setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_BPF, + &prog_fd, sizeof(prog_fd)); +.EE +.in +.P +Since Linux 4.1, +.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 +the following call may be used to attach +the eBPF program referred to by the file descriptor +.I prog_fd +to a perf event file descriptor, +.IR event_fd , +that was created by a previous call to +.BR perf_event_open (2): +.P +.in +4n +.EX +ioctl(event_fd, PERF_EVENT_IOC_SET_BPF, prog_fd); +.EE +.in +.\" +.\" +.SH RETURN VALUE +For a successful call, the return value depends on the operation: +.TP +.B BPF_MAP_CREATE +The new file descriptor associated with the eBPF map. +.TP +.B BPF_PROG_LOAD +The new file descriptor associated with the eBPF program. +.TP +All other commands +Zero. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B E2BIG +The eBPF program is too large or a map reached the +.I max_entries +limit (maximum number of elements). +.TP +.B EACCES +For +.BR BPF_PROG_LOAD , +even though all program instructions are valid, the program has been +rejected because it was deemed unsafe. +This may be because it may have +accessed a disallowed memory region or an uninitialized stack/register or +because the function constraints don't match the actual types or because +there was a misaligned memory access. +In this case, it is recommended to call +.BR bpf () +again with +.I log_level = 1 +and examine +.I log_buf +for the specific reason provided by the verifier. +.TP +.B EAGAIN +For +.BR BPF_PROG_LOAD , +indicates that needed resources are blocked. +This happens when the verifier detects pending signals +while it is checking the validity of the bpf program. +In this case, just call +.BR bpf () +again with the same parameters. +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EFAULT +One of the pointers +.RI ( key +or +.I value +or +.I log_buf +or +.IR insns ) +is outside the accessible address space. +.TP +.B EINVAL +The value specified in +.I cmd +is not recognized by this kernel. +.TP +.B EINVAL +For +.BR BPF_MAP_CREATE , +either +.I map_type +or attributes are invalid. +.TP +.B EINVAL +For +.B BPF_MAP_*_ELEM +commands, +some of the fields of +.I "union bpf_attr" +that are not used by this command +are not set to zero. +.TP +.B EINVAL +For +.BR BPF_PROG_LOAD , +indicates an attempt to load an invalid program. +eBPF programs can be deemed +invalid due to unrecognized instructions, the use of reserved fields, jumps +out of range, infinite loops or calls of unknown functions. +.TP +.B ENOENT +For +.B BPF_MAP_LOOKUP_ELEM +or +.BR BPF_MAP_DELETE_ELEM , +indicates that the element with the given +.I key +was not found. +.TP +.B ENOMEM +Cannot allocate sufficient memory. +.TP +.B EPERM +The call was made without sufficient privilege +(without the +.B CAP_SYS_ADMIN +capability). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.18. +.SH NOTES +Prior to Linux 4.4, all +.BR bpf () +commands require the caller to have the +.B CAP_SYS_ADMIN +capability. +From Linux 4.4 onwards, +.\" commit 1be7f75d1668d6296b80bf35dcf6762393530afc +an unprivileged user may create limited programs of type +.B BPF_PROG_TYPE_SOCKET_FILTER +and associated maps. +However they may not store kernel pointers within +the maps and are presently limited to the following helper functions: +.\" [Linux 5.6] mtk: The list of available functions is, I think, governed +.\" by the check in net/core/filter.c::bpf_base_func_proto(). +.IP \[bu] 3 +get_random +.PD 0 +.IP \[bu] +get_smp_processor_id +.IP \[bu] +tail_call +.IP \[bu] +ktime_get_ns +.PD +.P +Unprivileged access may be blocked by writing the value 1 to the file +.IR /proc/sys/kernel/unprivileged_bpf_disabled . +.P +eBPF objects (maps and programs) can be shared between processes. +For example, after +.BR fork (2), +the child inherits file descriptors referring to the same eBPF objects. +In addition, file descriptors referring to eBPF objects can be +transferred over UNIX domain sockets. +File descriptors referring to eBPF objects can be duplicated +in the usual way, using +.BR dup (2) +and similar calls. +An eBPF object is deallocated only after all file descriptors +referring to the object have been closed. +.P +eBPF programs can be written in a restricted C that is compiled (using the +.B clang +compiler) into eBPF bytecode. +Various features are omitted from this restricted C, such as loops, +global variables, variadic functions, floating-point numbers, +and passing structures as function arguments. +Some examples can be found in the +.I samples/bpf/*_kern.c +files in the kernel source tree. +.\" There are also examples for the tc classifier, in the iproute2 +.\" project, in examples/bpf +.P +The kernel contains a just-in-time (JIT) compiler that translates +eBPF bytecode into native machine code for better performance. +Before Linux 4.15, +the JIT compiler is disabled by default, +but its operation can be controlled by writing one of the +following integer strings to the file +.IR /proc/sys/net/core/bpf_jit_enable : +.TP +.B 0 +Disable JIT compilation (default). +.TP +.B 1 +Normal compilation. +.TP +.B 2 +Debugging mode. +The generated opcodes are dumped in hexadecimal into the kernel log. +These opcodes can then be disassembled using the program +.I tools/net/bpf_jit_disasm.c +provided in the kernel source tree. +.P +Since Linux 4.15, +.\" commit 290af86629b25ffd1ed6232c4e9107da031705cb +the kernel may be configured with the +.B CONFIG_BPF_JIT_ALWAYS_ON +option. +In this case, the JIT compiler is always enabled, and the +.I bpf_jit_enable +is initialized to 1 and is immutable. +(This kernel configuration option was provided as a mitigation for +one of the Spectre attacks against the BPF interpreter.) +.P +The JIT compiler for eBPF is currently +.\" Last reviewed in Linux 4.18-rc by grepping for BPF_ALU64 in arch/ +.\" and by checking the documentation for bpf_jit_enable in +.\" Documentation/sysctl/net.txt +available for the following architectures: +.IP \[bu] 3 +x86-64 (since Linux 3.18; cBPF since Linux 3.0); +.\" commit 0a14842f5a3c0e88a1e59fac5c3025db39721f74 +.PD 0 +.IP \[bu] +ARM32 (since Linux 3.18; cBPF since Linux 3.4); +.\" commit ddecdfcea0ae891f782ae853771c867ab51024c2 +.IP \[bu] +SPARC 32 (since Linux 3.18; cBPF since Linux 3.5); +.\" commit 2809a2087cc44b55e4377d7b9be3f7f5d2569091 +.IP \[bu] +ARM-64 (since Linux 3.18); +.\" commit e54bcde3d69d40023ae77727213d14f920eb264a +.IP \[bu] +s390 (since Linux 4.1; cBPF since Linux 3.7); +.\" commit c10302efe569bfd646b4c22df29577a4595b4580 +.IP \[bu] +PowerPC 64 (since Linux 4.8; cBPF since Linux 3.1); +.\" commit 0ca87f05ba8bdc6791c14878464efc901ad71e99 +.\" commit 156d0e290e969caba25f1851c52417c14d141b24 +.IP \[bu] +SPARC 64 (since Linux 4.12); +.\" commit 7a12b5031c6b947cc13918237ae652b536243b76 +.IP \[bu] +x86-32 (since Linux 4.18); +.\" commit 03f5781be2c7b7e728d724ac70ba10799cc710d7 +.IP \[bu] +MIPS 64 (since Linux 4.18; cBPF since Linux 3.16); +.\" commit c6610de353da5ca6eee5b8960e838a87a90ead0c +.\" commit f381bf6d82f032b7410185b35d000ea370ac706b +.IP \[bu] +riscv (since Linux 5.1). +.\" commit 2353ecc6f91fd15b893fa01bf85a1c7a823ee4f2 +.PD +.SH EXAMPLES +.\" SRC BEGIN (bpf.c) +.EX +/* bpf+sockets example: + * 1. create array map of 256 elements + * 2. load program that counts number of packets received + * r0 = skb\->data[ETH_HLEN + offsetof(struct iphdr, protocol)] + * map[r0]++ + * 3. attach prog_fd to raw socket via setsockopt() + * 4. print number of received TCP/UDP packets every second + */ +int +main(int argc, char *argv[]) +{ + int sock, map_fd, prog_fd, key; + long long value = 0, tcp_cnt, udp_cnt; +\& + map_fd = bpf_create_map(BPF_MAP_TYPE_ARRAY, sizeof(key), + sizeof(value), 256); + if (map_fd < 0) { + printf("failed to create map \[aq]%s\[aq]\en", strerror(errno)); + /* likely not run as root */ + return 1; + } +\& + struct bpf_insn prog[] = { + BPF_MOV64_REG(BPF_REG_6, BPF_REG_1), /* r6 = r1 */ + BPF_LD_ABS(BPF_B, ETH_HLEN + offsetof(struct iphdr, protocol)), + /* r0 = ip\->proto */ + BPF_STX_MEM(BPF_W, BPF_REG_10, BPF_REG_0, \-4), + /* *(u32 *)(fp \- 4) = r0 */ + BPF_MOV64_REG(BPF_REG_2, BPF_REG_10), /* r2 = fp */ + BPF_ALU64_IMM(BPF_ADD, BPF_REG_2, \-4), /* r2 = r2 \- 4 */ + BPF_LD_MAP_FD(BPF_REG_1, map_fd), /* r1 = map_fd */ + BPF_CALL_FUNC(BPF_FUNC_map_lookup_elem), + /* r0 = map_lookup(r1, r2) */ + BPF_JMP_IMM(BPF_JEQ, BPF_REG_0, 0, 2), + /* if (r0 == 0) goto pc+2 */ + BPF_MOV64_IMM(BPF_REG_1, 1), /* r1 = 1 */ + BPF_XADD(BPF_DW, BPF_REG_0, BPF_REG_1, 0, 0), + /* lock *(u64 *) r0 += r1 */ +.\" == atomic64_add + BPF_MOV64_IMM(BPF_REG_0, 0), /* r0 = 0 */ + BPF_EXIT_INSN(), /* return r0 */ + }; +\& + prog_fd = bpf_prog_load(BPF_PROG_TYPE_SOCKET_FILTER, prog, + sizeof(prog) / sizeof(prog[0]), "GPL"); +\& + sock = open_raw_sock("lo"); +\& + assert(setsockopt(sock, SOL_SOCKET, SO_ATTACH_BPF, &prog_fd, + sizeof(prog_fd)) == 0); +\& + for (;;) { + key = IPPROTO_TCP; + assert(bpf_lookup_elem(map_fd, &key, &tcp_cnt) == 0); + key = IPPROTO_UDP; + assert(bpf_lookup_elem(map_fd, &key, &udp_cnt) == 0); + printf("TCP %lld UDP %lld packets\en", tcp_cnt, udp_cnt); + sleep(1); + } +\& + return 0; +} +.EE +.\" SRC END +.P +Some complete working code can be found in the +.I samples/bpf +directory in the kernel source tree. +.SH SEE ALSO +.BR seccomp (2), +.BR bpf\-helpers (7), +.BR socket (7), +.BR tc (8), +.BR tc\-bpf (8) +.P +Both classic and extended BPF are explained in the kernel source file +.IR Documentation/networking/filter.txt . diff --git a/man/man2/break.2 b/man/man2/break.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/break.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/brk.2 b/man/man2/brk.2 new file mode 100644 index 0000000..309dce2 --- /dev/null +++ b/man/man2/brk.2 @@ -0,0 +1,153 @@ +.\" Copyright (c) 1993 Michael Haardt, (michael@moria.de) +.\" and Copyright 2006, 2008, Michael Kerrisk +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Wed Jul 21 19:52:58 1993 by Rik Faith +.\" Modified Sun Aug 21 17:40:38 1994 by Rik Faith +.\" +.TH brk 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +brk, sbrk \- change data segment size +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int brk(void *" addr ); +.BI "void *sbrk(intptr_t " increment ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR brk (), +.BR sbrk (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + || ((_XOPEN_SOURCE >= 500) && + ! (_POSIX_C_SOURCE >= 200112L)) +.\" (_XOPEN_SOURCE >= 500 || +.\" _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) && + From glibc 2.12 to glibc 2.19: + _BSD_SOURCE || _SVID_SOURCE + || ((_XOPEN_SOURCE >= 500) && + ! (_POSIX_C_SOURCE >= 200112L)) +.\" (_XOPEN_SOURCE >= 500 || +.\" _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) && + Before glibc 2.12: + _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +.BR brk () +and +.BR sbrk () +change the location of the +.IR "program break" , +which defines the end of the process's data segment +(i.e., the program break is the first location after the end of the +uninitialized data segment). +Increasing the program break has the effect of +allocating memory to the process; +decreasing the break deallocates memory. +.P +.BR brk () +sets the end of the data segment to the value specified by +.IR addr , +when that value is reasonable, the system has enough memory, +and the process does not exceed its maximum data size (see +.BR setrlimit (2)). +.P +.BR sbrk () +increments the program's data space by +.I increment +bytes. +Calling +.BR sbrk () +with an +.I increment +of 0 can be used to find the current location of the program break. +.SH RETURN VALUE +On success, +.BR brk () +returns zero. +On error, \-1 is returned, and +.I errno +is set to +.BR ENOMEM . +.P +On success, +.BR sbrk () +returns the previous program break. +(If the break was increased, +then this value is a pointer to the start of the newly allocated memory). +On error, +.I "(void\ *)\ \-1" +is returned, and +.I errno +is set to +.BR ENOMEM . +.SH STANDARDS +None. +.SH HISTORY +4.3BSD; SUSv1, marked LEGACY in SUSv2, removed in POSIX.1-2001. +.\" +.\" .BR brk () +.\" and +.\" .BR sbrk () +.\" are not defined in the C Standard and are deliberately excluded from the +.\" POSIX.1-1990 standard (see paragraphs B.1.1.1.3 and B.8.3.3). +.SH NOTES +Avoid using +.BR brk () +and +.BR sbrk (): +the +.BR malloc (3) +memory allocation package is the +portable and comfortable way of allocating memory. +.P +Various systems use various types for the argument of +.BR sbrk (). +Common are \fIint\fP, \fIssize_t\fP, \fIptrdiff_t\fP, \fIintptr_t\fP. +.\" One sees +.\" \fIint\fP (e.g., XPGv4, DU 4.0, HP-UX 11, FreeBSD 4.0, OpenBSD 3.2), +.\" \fIssize_t\fP (OSF1 2.0, Irix 5.3, 6.5), +.\" \fIptrdiff_t\fP (libc4, libc5, ulibc, glibc 2.0, 2.1), +.\" \fIintptr_t\fP (e.g., XPGv5, AIX, SunOS 5.8, 5.9, FreeBSD 4.7, NetBSD 1.6, +.\" Tru64 5.1, glibc2.2). +.SS C library/kernel differences +The return value described above for +.BR brk () +is the behavior provided by the glibc wrapper function for the Linux +.BR brk () +system call. +(On most other implementations, the return value from +.BR brk () +is the same; this return value was also specified in SUSv2.) +However, +the actual Linux system call returns the new program break on success. +On failure, the system call returns the current break. +The glibc wrapper function does some work +(i.e., checks whether the new break is less than +.IR addr ) +to provide the 0 and \-1 return values described above. +.P +On Linux, +.BR sbrk () +is implemented as a library function that uses the +.BR brk () +system call, and does some internal bookkeeping so that it can +return the old break value. +.SH SEE ALSO +.BR execve (2), +.BR getrlimit (2), +.BR end (3), +.BR malloc (3) diff --git a/man/man2/cacheflush.2 b/man/man2/cacheflush.2 new file mode 100644 index 0000000..0f6afee --- /dev/null +++ b/man/man2/cacheflush.2 @@ -0,0 +1,143 @@ +.\" Written by Ralf Baechle (ralf@waldorf-gmbh.de), +.\" Copyright (c) 1994, 1995 Waldorf GMBH +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH cacheflush 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cacheflush \- flush contents of instruction and/or data cache +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int cacheflush(void " addr [. nbytes "], int "nbytes ", int "cache ); +.fi +.P +.IR Note : +On some architectures, +there is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +.BR cacheflush () +flushes the contents of the indicated cache(s) for the +user addresses in the range +.I addr +to +.IR (addr+nbytes\-1) . +.I cache +may be one of: +.TP +.B ICACHE +Flush the instruction cache. +.TP +.B DCACHE +Write back to memory and invalidate the affected valid cache lines. +.TP +.B BCACHE +Same as +.BR (ICACHE|DCACHE) . +.SH RETURN VALUE +.BR cacheflush () +returns 0 on success. +On error, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Some or all of the address range +.I addr +to +.I (addr+nbytes\-1) +is not accessible. +.TP +.B EINVAL +.I cache +is not one of +.BR ICACHE , +.BR DCACHE , +or +.B BCACHE +(but see BUGS). +.SH VERSIONS +.BR cacheflush () +should not be used in programs intended to be portable. +On Linux, this call first appeared on the MIPS architecture, +but nowadays, Linux provides a +.BR cacheflush () +system call on some other architectures, but with different arguments. +.SS Architecture-specific variants +glibc provides a wrapper for this system call, +with the prototype shown in SYNOPSIS, +for the following architectures: +ARC, CSKY, MIPS, and NIOS2. +.P +On some other architectures, +Linux provides this system call, with different arguments: +.TP +M68K: +.nf +.BI "int cacheflush(unsigned long " addr ", int " scope ", int " cache , +.BI " unsigned long " len ); +.fi +.TP +SH: +.nf +.BI "int cacheflush(unsigned long " addr ", unsigned long " len ", int " op ); +.fi +.TP +NDS32: +.nf +.BI "int cacheflush(unsigned int " start ", unsigned int " end ", int " cache ); +.fi +.P +On the above architectures, +glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +.SS GCC alternative +Unless you need the finer grained control that this system call provides, +you probably want to use the GCC built-in function +.BR __builtin___clear_cache (), +which provides a portable interface +across platforms supported by GCC and compatible compilers: +.P +.in +4n +.EX +.BI "void __builtin___clear_cache(void *" begin ", void *" end ); +.EE +.in +.P +On platforms that don't require instruction cache flushes, +.BR __builtin___clear_cache () +has no effect. +.P +.IR Note : +On some GCC-compatible compilers, +the prototype for this built-in function uses +.I char * +instead of +.I void * +for the parameters. +.SH STANDARDS +Historically, this system call was available on all MIPS UNIX variants +including RISC/os, IRIX, Ultrix, NetBSD, OpenBSD, and FreeBSD +(and also on some non-UNIX MIPS operating systems), so that +the existence of this call in MIPS operating systems is a de-facto +standard. +.SH BUGS +Linux kernels older than Linux 2.6.11 ignore the +.I addr +and +.I nbytes +arguments, making this function fairly expensive. +Therefore, the whole cache is always flushed. +.P +This function always behaves as if +.B BCACHE +has been passed for the +.I cache +argument and does not do any error checking on the +.I cache +argument. diff --git a/man/man2/capget.2 b/man/man2/capget.2 new file mode 100644 index 0000000..8857fcb --- /dev/null +++ b/man/man2/capget.2 @@ -0,0 +1,260 @@ +.\" Copyright: written by Andrew Morgan +.\" and Copyright 2006, 2008, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Modified by David A. Wheeler +.\" Modified 2004-05-27, mtk +.\" Modified 2004-06-21, aeb +.\" Modified 2008-04-28, morgan of kernel.org +.\" Update in line with addition of file capabilities and +.\" 64-bit capability sets in Linux 2.6.2[45]. +.\" Modified 2009-01-26, andi kleen +.\" +.TH capget 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +capget, capset \- set/get capabilities of thread(s) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " CAP_* " and" +.BR " _LINUX_CAPABILITY_*" " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_capget, cap_user_header_t " hdrp , +.BI " cap_user_data_t " datap ); +.BI "int syscall(SYS_capset, cap_user_header_t " hdrp , +.BI " const cap_user_data_t " datap ); +.fi +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +These two system calls are the raw kernel interface for getting and +setting thread capabilities. +Not only are these system calls specific to Linux, +but the kernel API is likely to change and use of +these system calls (in particular the format of the +.I cap_user_*_t +types) is subject to extension with each kernel revision, +but old programs will keep working. +.P +The portable interfaces are +.BR cap_set_proc (3) +and +.BR cap_get_proc (3); +if possible, you should use those interfaces in applications; see NOTES. +.\" +.SS Current details +Now that you have been warned, some current kernel details. +The structures are defined as follows. +.P +.in +4n +.EX +#define _LINUX_CAPABILITY_VERSION_1 0x19980330 +#define _LINUX_CAPABILITY_U32S_1 1 +\& + /* V2 added in Linux 2.6.25; deprecated */ +#define _LINUX_CAPABILITY_VERSION_2 0x20071026 +.\" commit e338d263a76af78fe8f38a72131188b58fceb591 +.\" Added 64 bit capability support +#define _LINUX_CAPABILITY_U32S_2 2 +\& + /* V3 added in Linux 2.6.26 */ +#define _LINUX_CAPABILITY_VERSION_3 0x20080522 +.\" commit ca05a99a54db1db5bca72eccb5866d2a86f8517f +#define _LINUX_CAPABILITY_U32S_3 2 +\& +typedef struct __user_cap_header_struct { + __u32 version; + int pid; +} *cap_user_header_t; +\& +typedef struct __user_cap_data_struct { + __u32 effective; + __u32 permitted; + __u32 inheritable; +} *cap_user_data_t; +.EE +.in +.P +The +.IR effective , +.IR permitted , +and +.I inheritable +fields are bit masks of the capabilities defined in +.BR capabilities (7). +Note that the +.B CAP_* +values are bit indexes and need to be bit-shifted before ORing into +the bit fields. +To define the structures for passing to the system call, you have to use the +.I struct __user_cap_header_struct +and +.I struct __user_cap_data_struct +names because the typedefs are only pointers. +.P +Kernels prior to Linux 2.6.25 prefer +32-bit capabilities with version +.BR _LINUX_CAPABILITY_VERSION_1 . +Linux 2.6.25 added 64-bit capability sets, with version +.BR _LINUX_CAPABILITY_VERSION_2 . +There was, however, an API glitch, and Linux 2.6.26 added +.B _LINUX_CAPABILITY_VERSION_3 +to fix the problem. +.P +Note that 64-bit capabilities use +.I datap[0] +and +.IR datap[1] , +whereas 32-bit capabilities use only +.IR datap[0] . +.P +On kernels that support file capabilities (VFS capabilities support), +these system calls behave slightly differently. +This support was added as an option in Linux 2.6.24, +and became fixed (nonoptional) in Linux 2.6.33. +.P +For +.BR capget () +calls, one can probe the capabilities of any process by specifying its +process ID with the +.I hdrp\->pid +field value. +.P +For details on the data, see +.BR capabilities (7). +.\" +.SS With VFS capabilities support +VFS capabilities employ a file extended attribute (see +.BR xattr (7)) +to allow capabilities to be attached to executables. +This privilege model obsoletes kernel support for one process +asynchronously setting the capabilities of another. +That is, on kernels that have VFS capabilities support, when calling +.BR capset (), +the only permitted values for +.I hdrp\->pid +are 0 or, equivalently, the value returned by +.BR gettid (2). +.\" +.SS Without VFS capabilities support +On older kernels that do not provide VFS capabilities support +.BR capset () +can, if the caller has the +.B CAP_SETPCAP +capability, be used to change not only the caller's own capabilities, +but also the capabilities of other threads. +The call operates on the capabilities of the thread specified by the +.I pid +field of +.I hdrp +when that is nonzero, or on the capabilities of the calling thread if +.I pid +is 0. +If +.I pid +refers to a single-threaded process, then +.I pid +can be specified as a traditional process ID; +operating on a thread of a multithreaded process requires a thread ID +of the type returned by +.BR gettid (2). +For +.BR capset (), +.I pid +can also be: \-1, meaning perform the change on all threads except the +caller and +.BR init (1); +or a value less than \-1, in which case the change is applied +to all members of the process group whose ID is \-\fIpid\fP. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +The calls fail with the error +.BR EINVAL , +and set the +.I version +field of +.I hdrp +to the kernel preferred value of +.B _LINUX_CAPABILITY_VERSION_? +when an unsupported +.I version +value is specified. +In this way, one can probe what the current +preferred capability revision is. +.SH ERRORS +.TP +.B EFAULT +Bad memory address. +.I hdrp +must not be NULL. +.I datap +may be NULL only when the user is trying to determine the preferred +capability version format supported by the kernel. +.TP +.B EINVAL +One of the arguments was invalid. +.TP +.B EPERM +An attempt was made to add a capability to the permitted set, or to set +a capability in the effective set that is not in the +permitted set. +.TP +.B EPERM +An attempt was made to add a capability to the inheritable set, and either: +.RS +.IP \[bu] 3 +that capability was not in the caller's bounding set; or +.IP \[bu] +the capability was not in the caller's permitted set +and the caller lacked the +.B CAP_SETPCAP +capability in its effective set. +.RE +.TP +.B EPERM +The caller attempted to use +.BR capset () +to modify the capabilities of a thread other than itself, +but lacked sufficient privilege. +For kernels supporting VFS +capabilities, this is never permitted. +For kernels lacking VFS +support, the +.B CAP_SETPCAP +capability is required. +(A bug in kernels before Linux 2.6.11 meant that this error could also +occur if a thread without this capability tried to change its +own capabilities by specifying the +.I pid +field as a nonzero value (i.e., the value returned by +.BR getpid (2)) +instead of 0.) +.TP +.B ESRCH +No such thread. +.SH STANDARDS +Linux. +.SH NOTES +The portable interface to the capability querying and setting +functions is provided by the +.I libcap +library and is available here: +.br +.UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git +.UE +.SH SEE ALSO +.BR clone (2), +.BR gettid (2), +.BR capabilities (7) diff --git a/man/man2/capset.2 b/man/man2/capset.2 new file mode 100644 index 0000000..9e829cb --- /dev/null +++ b/man/man2/capset.2 @@ -0,0 +1 @@ +.so man2/capget.2 diff --git a/man/man2/chdir.2 b/man/man2/chdir.2 new file mode 100644 index 0000000..8c0e4fe --- /dev/null +++ b/man/man2/chdir.2 @@ -0,0 +1,127 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1995-04-15 by Michael Chastain : +.\" Added 'fchdir'. Fixed bugs in error section. +.\" Modified 1996-10-21 by Eric S. Raymond +.\" Modified 1997-08-21 by Joseph S. Myers +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH chdir 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +chdir, fchdir \- change working directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int chdir(const char *" path ); +.BI "int fchdir(int " fd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fchdir (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc up to and including 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR chdir () +changes the current working directory of the calling process to the +directory specified in +.IR path . +.P +.BR fchdir () +is identical to +.BR chdir (); +the only difference is that the directory is given as an +open file descriptor. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Depending on the filesystem, other errors can be returned. +The more +general errors for +.BR chdir () +are listed below: +.TP +.B EACCES +Search permission is denied for one of the components of +.IR path . +(See also +.BR path_resolution (7).) +.TP +.B EFAULT +.I path +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is too long. +.TP +.B ENOENT +The directory specified in +.I path +does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of +.I path +is not a directory. +.P +The general errors for +.BR fchdir () +are listed below: +.TP +.B EACCES +Search permission was denied on the directory open on +.IR fd . +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOTDIR +.I fd +does not refer to a directory. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD. +.SH NOTES +The current working directory is the starting point for interpreting +relative pathnames (those not starting with \[aq]/\[aq]). +.P +A child process created via +.BR fork (2) +inherits its parent's current working directory. +The current working directory is left unchanged by +.BR execve (2). +.SH SEE ALSO +.BR chroot (2), +.BR getcwd (3), +.BR path_resolution (7) diff --git a/man/man2/chmod.2 b/man/man2/chmod.2 new file mode 100644 index 0000000..9ebbf23 --- /dev/null +++ b/man/man2/chmod.2 @@ -0,0 +1,347 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1997-01-12 by Michael Haardt +.\" : NFS details +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH chmod 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +chmod, fchmod, fchmodat \- change permissions of a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int chmod(const char *" pathname ", mode_t " mode ); +.BI "int fchmod(int " fd ", mode_t " mode ); +.P +.BR "#include " " /* Definition of AT_* constants */" +.B #include +.P +.BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \ +mode ", int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.nf +.BR fchmod (): + Since glibc 2.24: + _POSIX_C_SOURCE >= 199309L +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) + glibc 2.19 to glibc 2.23 + _POSIX_C_SOURCE + glibc 2.16 to glibc 2.19: + _BSD_SOURCE || _POSIX_C_SOURCE + glibc 2.12 to glibc 2.16: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 + || _POSIX_C_SOURCE >= 200809L + glibc 2.11 and earlier: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) +.fi +.P +.BR fchmodat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +The +.BR chmod () +and +.BR fchmod () +system calls change a file's mode bits. +(The file mode consists of the file permission bits plus the set-user-ID, +set-group-ID, and sticky bits.) +These system calls differ only in how the file is specified: +.IP \[bu] 3 +.BR chmod () +changes the mode of the file specified whose pathname is given in +.IR pathname , +which is dereferenced if it is a symbolic link. +.IP \[bu] +.BR fchmod () +changes the mode of the file referred to by the open file descriptor +.IR fd . +.P +The new file mode is specified in +.IR mode , +which is a bit mask created by ORing together zero or +more of the following: +.TP 18 +.BR S_ISUID " (04000)" +set-user-ID (set process effective user ID on +.BR execve (2)) +.TP +.BR S_ISGID " (02000)" +set-group-ID (set process effective group ID on +.BR execve (2); +mandatory locking, as described in +.BR fcntl (2); +take a new file's group from parent directory, as described in +.BR chown (2) +and +.BR mkdir (2)) +.TP +.BR S_ISVTX " (01000)" +sticky bit (restricted deletion flag, as described in +.BR unlink (2)) +.TP +.BR S_IRUSR " (00400)" +read by owner +.TP +.BR S_IWUSR " (00200)" +write by owner +.TP +.BR S_IXUSR " (00100)" +execute/search by owner ("search" applies for directories, +and means that entries within the directory can be accessed) +.TP +.BR S_IRGRP " (00040)" +read by group +.TP +.BR S_IWGRP " (00020)" +write by group +.TP +.BR S_IXGRP " (00010)" +execute/search by group +.TP +.BR S_IROTH " (00004)" +read by others +.TP +.BR S_IWOTH " (00002)" +write by others +.TP +.BR S_IXOTH " (00001)" +execute/search by others +.P +The effective UID of the calling process must match the owner of the file, +or the process must be privileged (Linux: it must have the +.B CAP_FOWNER +capability). +.P +If the calling process is not privileged (Linux: does not have the +.B CAP_FSETID +capability), and the group of the file does not match +the effective group ID of the process or one of its +supplementary group IDs, the +.B S_ISGID +bit will be turned off, +but this will not cause an error to be returned. +.P +As a security measure, depending on the filesystem, +the set-user-ID and set-group-ID execution bits +may be turned off if a file is written. +(On Linux, this occurs if the writing process does not have the +.B CAP_FSETID +capability.) +On some filesystems, only the superuser can set the sticky bit, +which may have a special meaning. +For the sticky bit, and for set-user-ID and set-group-ID bits on +directories, see +.BR inode (7). +.P +On NFS filesystems, restricting the permissions will immediately influence +already open files, because the access control is done on the server, but +open files are maintained by the client. +Widening the permissions may be +delayed for other clients if attribute caching is enabled on them. +.\" +.\" +.SS fchmodat() +The +.BR fchmodat () +system call operates in exactly the same way as +.BR chmod (), +except for the differences described here. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR chmod () +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR chmod ()). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +.I flags +can either be 0, or include the following flag: +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead operate on the link itself. +This flag is not currently implemented. +.P +See +.BR openat (2) +for an explanation of the need for +.BR fchmodat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Depending on the filesystem, +errors other than those listed below can be returned. +.P +The more general errors for +.BR chmod () +are listed below: +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( fchmod ()) +The file descriptor +.I fd +is not valid. +.TP +.B EBADF +.RB ( fchmodat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EINVAL +.RB ( fchmodat ()) +Invalid flag specified in +.IR flags . +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B ENOTDIR +.RB ( fchmodat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B ENOTSUP +.RB ( fchmodat ()) +.I flags +specified +.BR AT_SYMLINK_NOFOLLOW , +which is not supported. +.TP +.B EPERM +The effective UID does not match the owner of the file, +and the process is not privileged (Linux: it does not have the +.B CAP_FOWNER +capability). +.TP +.B EPERM +The file is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.TP +.B EROFS +The named file resides on a read-only filesystem. +.SH VERSIONS +.SS C library/kernel differences +The GNU C library +.BR fchmodat () +wrapper function implements the POSIX-specified +interface described in this page. +This interface differs from the underlying Linux system call, which does +.I not +have a +.I flags +argument. +.SS glibc notes +On older kernels where +.BR fchmodat () +is unavailable, the glibc wrapper function falls back to the use of +.BR chmod (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.I /proc/self/fd +that corresponds to the +.I dirfd +argument. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR chmod () +.TQ +.BR fchmod () +4.4BSD, SVr4, POSIX.1-2001. +.TP +.BR fchmodat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. +.SH SEE ALSO +.BR chmod (1), +.BR chown (2), +.BR execve (2), +.BR open (2), +.BR stat (2), +.BR inode (7), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/chown.2 b/man/man2/chown.2 new file mode 100644 index 0000000..56fa57e --- /dev/null +++ b/man/man2/chown.2 @@ -0,0 +1,472 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" and Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (c) 2006, 2007, 2008, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1996-07-09 by Andries Brouwer +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1997-05-18 by Michael Haardt +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2007-07-08, mtk, added an example program; updated SYNOPSIS +.\" 2008-05-08, mtk, Describe rules governing ownership of new files +.\" (bsdgroups versus sysvgroups, and the effect of the parent +.\" directory's set-group-ID mode bit). +.\" +.TH chown 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +chown, fchown, lchown, fchownat \- change ownership of a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int chown(const char *" pathname ", uid_t " owner ", gid_t " group ); +.BI "int fchown(int " fd ", uid_t " owner ", gid_t " group ); +.BI "int lchown(const char *" pathname ", uid_t " owner ", gid_t " group ); +.P +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.P +.BI "int fchownat(int " dirfd ", const char *" pathname , +.BI " uid_t " owner ", gid_t " group ", int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fchown (), +.BR lchown (): +.nf + /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.P +.BR fchownat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +These system calls change the owner and group of a file. +The +.BR chown (), +.BR fchown (), +and +.BR lchown () +system calls differ only in how the file is specified: +.IP \[bu] 3 +.BR chown () +changes the ownership of the file specified by +.IR pathname , +which is dereferenced if it is a symbolic link. +.IP \[bu] +.BR fchown () +changes the ownership of the file referred to by the open file descriptor +.IR fd . +.IP \[bu] +.BR lchown () +is like +.BR chown (), +but does not dereference symbolic links. +.P +Only a privileged process (Linux: one with the +.B CAP_CHOWN +capability) may change the owner of a file. +The owner of a file may change the group of the file +to any group of which that owner is a member. +A privileged process (Linux: with +.BR CAP_CHOWN ) +may change the group arbitrarily. +.P +If the +.I owner +or +.I group +is specified as \-1, then that ID is not changed. +.P +When the owner or group of an executable file is +changed by an unprivileged user, the +.B S_ISUID +and +.B S_ISGID +mode bits are cleared. +POSIX does not specify whether +this also should happen when root does the +.BR chown (); +the Linux behavior depends on the kernel version, +and since Linux 2.2.13, root is treated like other users. +.\" In Linux 2.0 kernels, superuser was like everyone else +.\" In Linux 2.2, up to Linux 2.2.12, these bits were not cleared for superuser. +.\" Since Linux 2.2.13, superuser is once more like everyone else. +In case of a non-group-executable file (i.e., one for which the +.B S_IXGRP +bit is not set) the +.B S_ISGID +bit indicates mandatory locking, and is not cleared by a +.BR chown (). +.P +When the owner or group of an executable file is changed (by any user), +all capability sets for the file are cleared. +.\" +.SS fchownat() +The +.BR fchownat () +system call operates in exactly the same way as +.BR chown (), +except for the differences described here. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR chown () +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR chown ()). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +The +.I flags +argument is a bit mask created by ORing together +0 or more of the following values; +.TP +.BR AT_EMPTY_PATH " (since Linux 2.6.39)" +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead operate on the link itself, like +.BR lchown (). +(By default, +.BR fchownat () +dereferences symbolic links, like +.BR chown ().) +.P +See +.BR openat (2) +for an explanation of the need for +.BR fchownat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Depending on the filesystem, +errors other than those listed below can be returned. +.P +The more general errors for +.BR chown () +are listed below. +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( fchown ()) +.I fd +is not a valid open file descriptor. +.TP +.B EBADF +.RB ( fchownat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EINVAL +.RB ( fchownat ()) +Invalid flag specified in +.IR flags . +.TP +.B EIO +.RB ( fchown ()) +A low-level I/O error occurred while modifying the inode. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B ENOTDIR +.RB ( fchownat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B EPERM +The calling process did not have the required permissions +(see above) to change owner and/or group. +.TP +.B EPERM +The file is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.TP +.B EROFS +The named file resides on a read-only filesystem. +.SH VERSIONS +The 4.4BSD version can be +used only by the superuser (that is, ordinary users cannot give away files). +.\" chown(): +.\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no +.\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions. +.\" fchown(): +.\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK +.\" error conditions. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR chown () +.TQ +.BR fchown () +.TQ +.BR lchown () +4.4BSD, SVr4, POSIX.1-2001. +.TP +.BR fchownat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. +.SH NOTES +.SS Ownership of new files +When a new file is created (by, for example, +.BR open (2) +or +.BR mkdir (2)), +its owner is made the same as the filesystem user ID of the +creating process. +The group of the file depends on a range of factors, +including the type of filesystem, +the options used to mount the filesystem, +and whether or not the set-group-ID mode bit is enabled +on the parent directory. +If the filesystem supports the +.B "\-o\ grpid" +(or, synonymously +.BR "\-o\ bsdgroups" ) +and +.B "\-o\ nogrpid" +(or, synonymously +.BR "\-o\ sysvgroups" ) +.BR mount (8) +options, then the rules are as follows: +.IP \[bu] 3 +If the filesystem is mounted with +.BR "\-o\ grpid" , +then the group of a new file is made +the same as that of the parent directory. +.IP \[bu] +If the filesystem is mounted with +.B \-o\ nogrpid +and the set-group-ID bit is disabled on the parent directory, +then the group of a new file is made the same as the +process's filesystem GID. +.IP \[bu] +If the filesystem is mounted with +.B \-o\ nogrpid +and the set-group-ID bit is enabled on the parent directory, +then the group of a new file is made +the same as that of the parent directory. +.P +As at Linux 4.12, +the +.B \-o\ grpid +and +.B \-o\ nogrpid +mount options are supported by ext2, ext3, ext4, and XFS. +Filesystems that don't support these mount options follow the +.B \-o\ nogrpid +rules. +.SS glibc notes +On older kernels where +.BR fchownat () +is unavailable, the glibc wrapper function falls back to the use of +.BR chown () +and +.BR lchown (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.I /proc/self/fd +that corresponds to the +.I dirfd +argument. +.SS NFS +The +.BR chown () +semantics are deliberately violated on NFS filesystems +which have UID mapping enabled. +Additionally, the semantics of all system +calls which access the file contents are violated, because +.BR chown () +may cause immediate access revocation on already open files. +Client side +caching may lead to a delay between the time where ownership have +been changed to allow access for a user and the time where the file can +actually be accessed by the user on other clients. +.SS Historical details +The original Linux +.BR chown (), +.BR fchown (), +and +.BR lchown () +system calls supported only 16-bit user and group IDs. +Subsequently, Linux 2.4 added +.BR chown32 (), +.BR fchown32 (), +and +.BR lchown32 (), +supporting 32-bit IDs. +The glibc +.BR chown (), +.BR fchown (), +and +.BR lchown () +wrapper functions transparently deal with the variations across kernel versions. +.P +Before Linux 2.1.81 (except 2.1.46), +.BR chown () +did not follow symbolic links. +Since Linux 2.1.81, +.BR chown () +does follow symbolic links, and there is a new system call +.BR lchown () +that does not follow symbolic links. +Since Linux 2.1.86, this new call (that has the same semantics +as the old +.BR chown ()) +has got the same syscall number, and +.BR chown () +got the newly introduced number. +.SH EXAMPLES +The following program changes the ownership of the file named in +its second command-line argument to the value specified in its +first command-line argument. +The new owner can be specified either as a numeric user ID, +or as a username (which is converted to a user ID by using +.BR getpwnam (3) +to perform a lookup in the system password file). +.SS Program source +.\" SRC BEGIN (chown.c) +.EX +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + char *endptr; + uid_t uid; + struct passwd *pwd; +\& + if (argc != 3 || argv[1][0] == \[aq]\e0\[aq]) { + fprintf(stderr, "%s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */ +\& + if (*endptr != \[aq]\e0\[aq]) { /* Was not pure numeric string */ + pwd = getpwnam(argv[1]); /* Try getting UID for username */ + if (pwd == NULL) { + perror("getpwnam"); + exit(EXIT_FAILURE); + } +\& + uid = pwd\->pw_uid; + } +\& + if (chown(argv[2], uid, \-1) == \-1) { + perror("chown"); + exit(EXIT_FAILURE); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR chgrp (1), +.BR chown (1), +.BR chmod (2), +.BR flock (2), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/chown32.2 b/man/man2/chown32.2 new file mode 100644 index 0000000..f0a5635 --- /dev/null +++ b/man/man2/chown32.2 @@ -0,0 +1 @@ +.so man2/chown.2 diff --git a/man/man2/chroot.2 b/man/man2/chroot.2 new file mode 100644 index 0000000..359d213 --- /dev/null +++ b/man/man2/chroot.2 @@ -0,0 +1,166 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1994-08-21 by Michael Chastain +.\" Modified 1996-06-13 by aeb +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1997-08-21 by Joseph S. Myers +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH chroot 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +chroot \- change root directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int chroot(const char *" path ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR chroot (): +.nf + Since glibc 2.2.2: + _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L) + || /* Since glibc 2.20: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.2.2: + none +.fi +.SH DESCRIPTION +.BR chroot () +changes the root directory of the calling process to that specified in +.IR path . +This directory will be used for pathnames beginning with \fI/\fP. +The root directory is inherited by all children of the calling process. +.P +Only a privileged process (Linux: one with the +.B CAP_SYS_CHROOT +capability in its user namespace) may call +.BR chroot (). +.P +This call changes an ingredient in the pathname resolution process +and does nothing else. +In particular, it is not intended to be used +for any kind of security purpose, neither to fully sandbox a process nor +to restrict filesystem system calls. +In the past, +.BR chroot () +has been used by daemons to restrict themselves prior to passing paths +supplied by untrusted users to system calls such as +.BR open (2). +However, if a folder is moved out of the chroot directory, an attacker +can exploit that to get out of the chroot directory as well. +The easiest way to do that is to +.BR chdir (2) +to the to-be-moved directory, wait for it to be moved out, then open a +path like ../../../etc/passwd. +.P +.\" This is how the "slightly trickier variation" works: +.\" https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-014-2015.txt#L142 +A slightly +trickier variation also works under some circumstances if +.BR chdir (2) +is not permitted. +If a daemon allows a "chroot directory" to be specified, +that usually means that if you want to prevent remote users from accessing +files outside the chroot directory, you must ensure that folders are never +moved out of it. +.P +This call does not change the current working directory, +so that after the call \[aq]\fI.\fP\[aq] can +be outside the tree rooted at \[aq]\fI/\fP\[aq]. +In particular, the superuser can escape from a "chroot jail" +by doing: +.P +.in +4n +.EX +mkdir foo; chroot foo; cd .. +.EE +.in +.P +This call does not close open file descriptors, and such file +descriptors may allow access to files outside the chroot tree. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Depending on the filesystem, other errors can be returned. +The more general errors are listed below: +.TP +.B EACCES +Search permission is denied on a component of the path prefix. +(See also +.BR path_resolution (7).) +.\" Also search permission is required on the final component, +.\" maybe just to guarantee that it is a directory? +.TP +.B EFAULT +.I path +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is too long. +.TP +.B ENOENT +The file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of +.I path +is not a directory. +.TP +.B EPERM +The caller has insufficient privilege. +.SH STANDARDS +None. +.SH HISTORY +SVr4, 4.4BSD, SUSv2 (marked LEGACY). +This function is not part of POSIX.1-2001. +.\" SVr4 documents additional EINTR, ENOLINK and EMULTIHOP error conditions. +.\" X/OPEN does not document EIO, ENOMEM or EFAULT error conditions. +.SH NOTES +A child process created via +.BR fork (2) +inherits its parent's root directory. +The root directory is left unchanged by +.BR execve (2). +.P +The magic symbolic link, +.IR /proc/ pid /root , +can be used to discover a process's root directory; see +.BR proc (5) +for details. +.P +FreeBSD has a stronger +.BR jail () +system call. +.SH SEE ALSO +.BR chroot (1), +.BR chdir (2), +.BR pivot_root (2), +.BR path_resolution (7), +.BR switch_root (8) diff --git a/man/man2/clock_adjtime.2 b/man/man2/clock_adjtime.2 new file mode 100644 index 0000000..b08b9c8 --- /dev/null +++ b/man/man2/clock_adjtime.2 @@ -0,0 +1 @@ +.so man2/adjtimex.2 diff --git a/man/man2/clock_getres.2 b/man/man2/clock_getres.2 new file mode 100644 index 0000000..51282df --- /dev/null +++ b/man/man2/clock_getres.2 @@ -0,0 +1,539 @@ +'\" t +.\" Copyright (c) 2003 Nick Clifford (zaf@nrc.co.nz), Jan 25, 2003 +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl), Aug 24, 2003 +.\" Copyright (c) 2020 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2003-08-23 Martin Schulze improvements +.\" 2003-08-24 aeb, large parts rewritten +.\" 2004-08-06 Christoph Lameter , SMP note +.\" +.TH clock_getres 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clock_getres, clock_gettime, clock_settime \- clock and time functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ), +since glibc 2.17 +.P +Before glibc 2.17, +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int clock_getres(clockid_t " clockid ", struct timespec *_Nullable " res ); +.P +.BI "int clock_gettime(clockid_t " clockid ", struct timespec *" tp ); +.BI "int clock_settime(clockid_t " clockid ", const struct timespec *" tp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR clock_getres (), +.BR clock_gettime (), +.BR clock_settime (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +The function +.BR clock_getres () +finds the resolution (precision) of the specified clock +.IR clockid , +and, if +.I res +is non-NULL, stores it in the \fIstruct timespec\fP pointed to by +.IR res . +The resolution of clocks depends on the implementation and cannot be +configured by a particular process. +If the time value pointed to by the argument +.I tp +of +.BR clock_settime () +is not a multiple of +.IR res , +then it is truncated to a multiple of +.IR res . +.P +The functions +.BR clock_gettime () +and +.BR clock_settime () +retrieve and set the time of the specified clock +.IR clockid . +.P +The +.I res +and +.I tp +arguments are +.BR timespec (3) +structures. +.P +The +.I clockid +argument is the identifier of the particular clock on which to act. +A clock may be system-wide and hence visible for all processes, or +per-process if it measures time only within a single process. +.P +All implementations support the system-wide real-time clock, +which is identified by +.BR CLOCK_REALTIME . +Its time represents seconds and nanoseconds since the Epoch. +When its time is changed, timers for a relative interval are +unaffected, but timers for an absolute point in time are affected. +.P +More clocks may be implemented. +The interpretation of the +corresponding time values and the effect on timers is unspecified. +.P +Sufficiently recent versions of glibc and the Linux kernel +support the following clocks: +.TP +.B CLOCK_REALTIME +A settable system-wide clock that measures real (i.e., wall-clock) time. +Setting this clock requires appropriate privileges. +This clock is affected by discontinuous jumps in the system time +(e.g., if the system administrator manually changes the clock), +and by frequency adjustments performed by NTP and similar applications via +.BR adjtime (3), +.BR adjtimex (2), +.BR clock_adjtime (2), +and +.BR ntp_adjtime (3). +This clock normally counts the number of seconds since +1970-01-01 00:00:00 Coordinated Universal Time (UTC) +except that it ignores leap seconds; +near a leap second it is typically adjusted by NTP +to stay roughly in sync with UTC. +.TP +.BR CLOCK_REALTIME_ALARM " (since Linux 3.0; Linux-specific)" +Like +.BR CLOCK_REALTIME , +but not settable. +See +.BR timer_create (2) +for further details. +.TP +.BR CLOCK_REALTIME_COARSE " (since Linux 2.6.32; Linux-specific)" +.\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3 +A faster but less precise version of +.BR CLOCK_REALTIME . +This clock is not settable. +Use when you need very fast, but not fine-grained timestamps. +Requires per-architecture support, +and probably also architecture support for this flag in the +.BR vdso (7). +.TP +.BR CLOCK_TAI " (since Linux 3.10; Linux-specific)" +.\" commit 1ff3c9677bff7e468e0c487d0ffefe4e901d33f4 +A nonsettable system-wide clock derived from wall-clock time +but counting leap seconds. +This clock does +not experience discontinuities or frequency adjustments caused by +inserting leap seconds as +.B CLOCK_REALTIME +does. +.IP +The acronym TAI refers to International Atomic Time. +.TP +.B CLOCK_MONOTONIC +A nonsettable system-wide clock that +represents monotonic time since\[em]as described +by POSIX\[em]"some unspecified point in the past". +On Linux, that point corresponds to the number of seconds that the system +has been running since it was booted. +.IP +The +.B CLOCK_MONOTONIC +clock is not affected by discontinuous jumps in the system time +(e.g., if the system administrator manually changes the clock), +but is affected by frequency adjustments. +This clock does not count time that the system is suspended. +All +.B CLOCK_MONOTONIC +variants guarantee that the time returned by consecutive calls will not go +backwards, but successive calls may\[em]depending on the architecture\[em]return +identical (not-increased) time values. +.TP +.BR CLOCK_MONOTONIC_COARSE " (since Linux 2.6.32; Linux-specific)" +.\" Added in commit da15cfdae03351c689736f8d142618592e3cebc3 +A faster but less precise version of +.BR CLOCK_MONOTONIC . +Use when you need very fast, but not fine-grained timestamps. +Requires per-architecture support, +and probably also architecture support for this flag in the +.BR vdso (7). +.TP +.BR CLOCK_MONOTONIC_RAW " (since Linux 2.6.28; Linux-specific)" +.\" Added in commit 2d42244ae71d6c7b0884b5664cf2eda30fb2ae68, John Stultz +Similar to +.BR CLOCK_MONOTONIC , +but provides access to a raw hardware-based time +that is not subject to frequency adjustments. +This clock does not count time that the system is suspended. +.TP +.BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)" +.\" commit 7fdd7f89006dd5a4c702fa0ce0c272345fa44ae0 +.\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0 +A nonsettable system-wide clock that is identical to +.BR CLOCK_MONOTONIC , +except that it also includes any time that the system is suspended. +This allows applications to get a suspend-aware monotonic clock +without having to deal with the complications of +.BR CLOCK_REALTIME , +which may have discontinuities if the time is changed using +.BR settimeofday (2) +or similar. +.TP +.BR CLOCK_BOOTTIME_ALARM " (since Linux 3.0; Linux-specific)" +Like +.BR CLOCK_BOOTTIME . +See +.BR timer_create (2) +for further details. +.TP +.BR CLOCK_PROCESS_CPUTIME_ID " (since Linux 2.6.12)" +This is a clock that measures CPU time consumed by this process +(i.e., CPU time consumed by all threads in the process). +On Linux, this clock is not settable. +.TP +.BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" +This is a clock that measures CPU time consumed by this thread. +On Linux, this clock is not settable. +.P +Linux also implements dynamic clock instances as described below. +.SS Dynamic clocks +In addition to the hard-coded System-V style clock IDs described above, +Linux also supports +POSIX clock operations on certain character devices. +Such devices are +called "dynamic" clocks, and are supported since Linux 2.6.39. +.P +Using the appropriate macros, open file +descriptors may be converted into clock IDs and passed to +.BR clock_gettime (), +.BR clock_settime (), +and +.BR clock_adjtime (2). +The following example shows how to convert a file descriptor into a +dynamic clock ID. +.P +.in +4n +.EX +#define CLOCKFD 3 +#define FD_TO_CLOCKID(fd) ((\[ti](clockid_t) (fd) << 3) | CLOCKFD) +#define CLOCKID_TO_FD(clk) ((unsigned int) \[ti]((clk) >> 3)) +\& +struct timespec ts; +clockid_t clkid; +int fd; +\& +fd = open("/dev/ptp0", O_RDWR); +clkid = FD_TO_CLOCKID(fd); +clock_gettime(clkid, &ts); +.EE +.in +.SH RETURN VALUE +.BR clock_gettime (), +.BR clock_settime (), +and +.BR clock_getres () +return 0 for success. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.BR clock_settime () +does not have write permission for the dynamic POSIX +clock device indicated. +.TP +.B EFAULT +.I tp +points outside the accessible address space. +.TP +.B EINVAL +The +.I clockid +specified is invalid for one of two reasons. +Either the System-V style +hard coded positive value is out of range, or the dynamic clock ID +does not refer to a valid instance of a clock object. +.\" Linux also gives this error on attempts to set CLOCK_PROCESS_CPUTIME_ID +.\" and CLOCK_THREAD_CPUTIME_ID, when probably the proper error should be +.\" EPERM. +.TP +.B EINVAL +.RB ( clock_settime ()): +.I tp.tv_sec +is negative or +.I tp.tv_nsec +is outside the range [0, 999,999,999]. +.TP +.B EINVAL +The +.I clockid +specified in a call to +.BR clock_settime () +is not a settable clock. +.TP +.BR EINVAL " (since Linux 4.3)" +.\" commit e1d7ba8735551ed79c7a0463a042353574b96da3 +A call to +.BR clock_settime () +with a +.I clockid +of +.B CLOCK_REALTIME +attempted to set the time to a value less than +the current value of the +.B CLOCK_MONOTONIC +clock. +.TP +.B ENODEV +The hot-pluggable device (like USB for example) represented by a +dynamic +.I clk_id +has disappeared after its character device was opened. +.TP +.B ENOTSUP +The operation is not supported by the dynamic POSIX clock device +specified. +.TP +.B EOVERFLOW +The timestamp would not fit in +.I time_t +range. +This can happen if an executable with 32-bit +.I time_t +is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later. +However, when the system time is out of +.I time_t +range in other situations, the behavior is undefined. +.TP +.B EPERM +.BR clock_settime () +does not have permission to set the clock indicated. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clock_getres (), +.BR clock_gettime (), +.BR clock_settime () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +POSIX.1 specifies the following: +.RS +.P +Setting the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime () +shall have no effect on threads that are blocked waiting for a relative time +service based upon this clock, including the +.BR nanosleep () +function; nor on the expiration of relative timers based upon this clock. +Consequently, these time services shall expire when the requested relative +interval elapses, independently of the new or old value of the clock. +.RE +.P +According to POSIX.1-2001, a process with "appropriate privileges" may set the +.B CLOCK_PROCESS_CPUTIME_ID +and +.B CLOCK_THREAD_CPUTIME_ID +clocks using +.BR clock_settime (). +On Linux, these clocks are not settable +(i.e., no process has "appropriate privileges"). +.\" See http://bugzilla.kernel.org/show_bug.cgi?id=11972 +.SS C library/kernel differences +On some architectures, an implementation of +.BR clock_gettime () +is provided in the +.BR vdso (7). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SUSv2. +Linux 2.6. +.P +On POSIX systems on which these functions are available, the symbol +.B _POSIX_TIMERS +is defined in \fI\fP to a value greater than 0. +POSIX.1-2008 makes these functions mandatory. +.P +The symbols +.BR _POSIX_MONOTONIC_CLOCK , +.BR _POSIX_CPUTIME , +.B _POSIX_THREAD_CPUTIME +indicate that +.BR CLOCK_MONOTONIC , +.BR CLOCK_PROCESS_CPUTIME_ID , +.B CLOCK_THREAD_CPUTIME_ID +are available. +(See also +.BR sysconf (3).) +.\" +.SS Historical note for SMP systems +Before Linux added kernel support for +.B CLOCK_PROCESS_CPUTIME_ID +and +.BR CLOCK_THREAD_CPUTIME_ID , +glibc implemented these clocks on many platforms using timer +registers from the CPUs +(TSC on i386, AR.ITC on Itanium). +These registers may differ between CPUs and as a consequence +these clocks may return +.B bogus results +if a process is migrated to another CPU. +.P +If the CPUs in an SMP system have different clock sources, then +there is no way to maintain a correlation between the timer registers since +each CPU will run at a slightly different frequency. +If that is the case, then +.I clock_getcpuclockid(0) +will return +.B ENOENT +to signify this condition. +The two clocks will then be useful only if it +can be ensured that a process stays on a certain CPU. +.P +The processors in an SMP system do not start all at exactly the same +time and therefore the timer registers are typically running at an offset. +Some architectures include code that attempts to limit these offsets on bootup. +However, the code cannot guarantee to accurately tune the offsets. +glibc contains no provisions to deal with these offsets (unlike the Linux +Kernel). +Typically these offsets are small and therefore the effects may be +negligible in most cases. +.P +Since glibc 2.4, +the wrapper functions for the system calls described in this page avoid +the abovementioned problems by employing the kernel implementation of +.B CLOCK_PROCESS_CPUTIME_ID +and +.BR CLOCK_THREAD_CPUTIME_ID , +on systems that provide such an implementation +(i.e., Linux 2.6.12 and later). +.SH EXAMPLES +The program below demonstrates the use of +.BR clock_gettime () +and +.BR clock_getres () +with various clocks. +This is an example of what we might see when running the program: +.P +.in +4n +.EX +$ \fB./clock_times x\fP +CLOCK_REALTIME : 1585985459.446 (18356 days + 7h 30m 59s) + resolution: 0.000000001 +CLOCK_TAI : 1585985496.447 (18356 days + 7h 31m 36s) + resolution: 0.000000001 +CLOCK_MONOTONIC: 52395.722 (14h 33m 15s) + resolution: 0.000000001 +CLOCK_BOOTTIME : 72691.019 (20h 11m 31s) + resolution: 0.000000001 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (clock_getres.c) +.EX +/* clock_times.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#define _XOPEN_SOURCE 600 +#include +#include +#include +#include +#include +\& +#define SECS_IN_DAY (24 * 60 * 60) +\& +static void +displayClock(clockid_t clock, const char *name, bool showRes) +{ + long days; + struct timespec ts; +\& + if (clock_gettime(clock, &ts) == \-1) { + perror("clock_gettime"); + exit(EXIT_FAILURE); + } +\& + printf("%\-15s: %10jd.%03ld (", name, + (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000); +\& + days = ts.tv_sec / SECS_IN_DAY; + if (days > 0) + printf("%ld days + ", days); +\& + printf("%2dh %2dm %2ds", + (int) (ts.tv_sec % SECS_IN_DAY) / 3600, + (int) (ts.tv_sec % 3600) / 60, + (int) ts.tv_sec % 60); + printf(")\en"); +\& + if (clock_getres(clock, &ts) == \-1) { + perror("clock_getres"); + exit(EXIT_FAILURE); + } +\& + if (showRes) + printf(" resolution: %10jd.%09ld\en", + (intmax_t) ts.tv_sec, ts.tv_nsec); +} +\& +int +main(int argc, char *argv[]) +{ + bool showRes = argc > 1; +\& + displayClock(CLOCK_REALTIME, "CLOCK_REALTIME", showRes); +#ifdef CLOCK_TAI + displayClock(CLOCK_TAI, "CLOCK_TAI", showRes); +#endif + displayClock(CLOCK_MONOTONIC, "CLOCK_MONOTONIC", showRes); +#ifdef CLOCK_BOOTTIME + displayClock(CLOCK_BOOTTIME, "CLOCK_BOOTTIME", showRes); +#endif + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR settimeofday (2), +.BR time (2), +.BR adjtime (3), +.BR clock_getcpuclockid (3), +.BR ctime (3), +.BR ftime (3), +.BR pthread_getcpuclockid (3), +.BR sysconf (3), +.BR timespec (3), +.BR time (7), +.BR time_namespaces (7), +.BR vdso (7), +.BR hwclock (8) diff --git a/man/man2/clock_gettime.2 b/man/man2/clock_gettime.2 new file mode 100644 index 0000000..5a599b4 --- /dev/null +++ b/man/man2/clock_gettime.2 @@ -0,0 +1 @@ +.so man2/clock_getres.2 diff --git a/man/man2/clock_nanosleep.2 b/man/man2/clock_nanosleep.2 new file mode 100644 index 0000000..9be2a75 --- /dev/null +++ b/man/man2/clock_nanosleep.2 @@ -0,0 +1,253 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH clock_nanosleep 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clock_nanosleep \- high-resolution sleep with specifiable clock +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ), +since glibc 2.17 +.P +Before glibc 2.17, +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.B #include +.nf +.P +.BI "int clock_nanosleep(clockid_t " clockid ", int " flags , +.BI " const struct timespec *" t , +.BI " struct timespec *_Nullable " remain ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR clock_nanosleep (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +Like +.BR nanosleep (2), +.BR clock_nanosleep () +allows the calling thread to sleep for an interval specified +with nanosecond precision. +It differs in allowing the caller to select the clock against +which the sleep interval is to be measured, +and in allowing the sleep interval to be specified as +either an absolute or a relative value. +.P +The time values passed to and returned by this call are specified using +.BR timespec (3) +structures. +.P +The +.I clockid +argument specifies the clock against which the sleep interval +is to be measured. +This argument can have one of the following values: +.\" Look in time/posix-timers.c (kernel 5.6 sources) for the +.\" 'struct k_clock' structures that have an 'nsleep' method +.TP +.B CLOCK_REALTIME +A settable system-wide real-time clock. +.TP +.BR CLOCK_TAI " (since Linux 3.10)" +A system-wide clock derived from wall-clock time but counting leap seconds. +.TP +.B CLOCK_MONOTONIC +A nonsettable, monotonically increasing clock that measures time +since some unspecified point in the past that does not change after +system startup. +.\" On Linux this clock measures time since boot. +.TP +.BR CLOCK_BOOTTIME " (since Linux 2.6.39)" +Identical to +.BR CLOCK_MONOTONIC , +except that it also includes any time that the system is suspended. +.TP +.B CLOCK_PROCESS_CPUTIME_ID +A settable per-process clock that measures CPU time consumed +by all threads in the process. +.\" There is some trickery between glibc and the kernel +.\" to deal with the CLOCK_PROCESS_CPUTIME_ID case. +.P +See +.BR clock_getres (2) +for further details on these clocks. +In addition, the CPU clock IDs returned by +.BR clock_getcpuclockid (3) +and +.BR pthread_getcpuclockid (3) +can also be passed in +.IR clockid . +.\" Sleeping against CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM +.\" is also possible (tested), with CAP_WAKE_ALARM, but I'm not +.\" sure if this is useful or needs to be documented. +.P +If +.I flags +is 0, then the value specified in +.I t +is interpreted as an interval relative to the current +value of the clock specified by +.IR clockid . +.P +If +.I flags +is +.BR TIMER_ABSTIME , +then +.I t +is interpreted as an absolute time as measured by the clock, +.IR clockid . +If +.I t +is less than or equal to the current value of the clock, +then +.BR clock_nanosleep () +returns immediately without suspending the calling thread. +.P +.BR clock_nanosleep () +suspends the execution of the calling thread +until either at least the time specified by +.I t +has elapsed, +or a signal is delivered that causes a signal handler to be called or +that terminates the process. +.P +If the call is interrupted by a signal handler, +.BR clock_nanosleep () +fails with the error +.BR EINTR . +In addition, if +.I remain +is not NULL, and +.I flags +was not +.BR TIMER_ABSTIME , +it returns the remaining unslept time in +.IR remain . +This value can then be used to call +.BR clock_nanosleep () +again and complete a (relative) sleep. +.SH RETURN VALUE +On successfully sleeping for the requested interval, +.BR clock_nanosleep () +returns 0. +If the call is interrupted by a signal handler or encounters an error, +then it returns one of the positive error number listed in ERRORS. +.SH ERRORS +.TP +.B EFAULT +.I t +or +.I remain +specified an invalid address. +.TP +.B EINTR +The sleep was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The value in the +.I tv_nsec +field was not in the range [0, 999999999] or +.I tv_sec +was negative. +.TP +.B EINVAL +.I clockid +was invalid. +.RB ( CLOCK_THREAD_CPUTIME_ID +is not a permitted value for +.IR clockid .) +.TP +.B ENOTSUP +The kernel does not support sleeping against this +.IR clockid . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +Linux 2.6, +glibc 2.1. +.SH NOTES +If the interval specified in +.I t +is not an exact multiple of the granularity underlying clock (see +.BR time (7)), +then the interval will be rounded up to the next multiple. +Furthermore, after the sleep completes, there may still be a delay before +the CPU becomes free to once again execute the calling thread. +.P +Using an absolute timer is useful for preventing +timer drift problems of the type described in +.BR nanosleep (2). +(Such problems are exacerbated in programs that try to restart +a relative sleep that is repeatedly interrupted by signals.) +To perform a relative sleep that avoids these problems, call +.BR clock_gettime (2) +for the desired clock, +add the desired interval to the returned time value, +and then call +.BR clock_nanosleep () +with the +.B TIMER_ABSTIME +flag. +.P +.BR clock_nanosleep () +is never restarted after being interrupted by a signal handler, +regardless of the use of the +.BR sigaction (2) +.B SA_RESTART +flag. +.P +The +.I remain +argument is unused, and unnecessary, when +.I flags +is +.BR TIMER_ABSTIME . +(An absolute sleep can be restarted using the same +.I t +argument.) +.P +POSIX.1 specifies that +.BR clock_nanosleep () +has no effect on signals dispositions or the signal mask. +.P +POSIX.1 specifies that after changing the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime (2), +the new clock value shall be used to determine the time +at which a thread blocked on an absolute +.BR clock_nanosleep () +will wake up; +if the new clock value falls past the end of the sleep interval, then the +.BR clock_nanosleep () +call will return immediately. +.P +POSIX.1 specifies that +changing the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime (2) +shall have no effect on a thread that is blocked on a relative +.BR clock_nanosleep (). +.SH SEE ALSO +.BR clock_getres (2), +.BR nanosleep (2), +.BR restart_syscall (2), +.BR timer_create (2), +.BR sleep (3), +.BR timespec (3), +.BR usleep (3), +.BR time (7) diff --git a/man/man2/clock_settime.2 b/man/man2/clock_settime.2 new file mode 100644 index 0000000..5a599b4 --- /dev/null +++ b/man/man2/clock_settime.2 @@ -0,0 +1 @@ +.so man2/clock_getres.2 diff --git a/man/man2/clone.2 b/man/man2/clone.2 new file mode 100644 index 0000000..9ea291a --- /dev/null +++ b/man/man2/clone.2 @@ -0,0 +1,1950 @@ +'\" t +.\" Copyright (c) 1992 Drew Eckhardt , March 28, 1992 +.\" and Copyright (c) Michael Kerrisk, 2001, 2002, 2005, 2013, 2019 +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Modified by Michael Haardt +.\" Modified 24 Jul 1993 by Rik Faith +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" New man page (copied from 'fork.2'). +.\" Modified 10 June 1995 by Andries Brouwer +.\" Modified 25 April 1998 by Xavier Leroy +.\" Modified 26 Jun 2001 by Michael Kerrisk +.\" Mostly upgraded to Linux 2.4.x +.\" Added prototype for sys_clone() plus description +.\" Added CLONE_THREAD with a brief description of thread groups +.\" Added CLONE_PARENT and revised entire page remove ambiguity +.\" between "calling process" and "parent process" +.\" Added CLONE_PTRACE and CLONE_VFORK +.\" Added EPERM and EINVAL error codes +.\" Renamed "__clone" to "clone" (which is the prototype in ) +.\" various other minor tidy ups and clarifications. +.\" Modified 26 Jun 2001 by Michael Kerrisk +.\" Updated notes for 2.4.7+ behavior of CLONE_THREAD +.\" Modified 15 Oct 2002 by Michael Kerrisk +.\" Added description for CLONE_NEWNS, which was added in Linux 2.4.19 +.\" Slightly rephrased, aeb. +.\" Modified 1 Feb 2003 - added CLONE_SIGHAND restriction, aeb. +.\" Modified 1 Jan 2004 - various updates, aeb +.\" Modified 2004-09-10 - added CLONE_PARENT_SETTID etc. - aeb. +.\" 2005-04-12, mtk, noted the PID caching behavior of NPTL's getpid() +.\" wrapper under BUGS. +.\" 2005-05-10, mtk, added CLONE_SYSVSEM, CLONE_UNTRACED, CLONE_STOPPED. +.\" 2005-05-17, mtk, Substantially enhanced discussion of CLONE_THREAD. +.\" 2008-11-18, mtk, order CLONE_* flags alphabetically +.\" 2008-11-18, mtk, document CLONE_NEWPID +.\" 2008-11-19, mtk, document CLONE_NEWUTS +.\" 2008-11-19, mtk, document CLONE_NEWIPC +.\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO +.\" +.TH clone 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clone, __clone2, clone3 \- create a child process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +/* Prototype for the glibc wrapper function */ +.P +.B #define _GNU_SOURCE +.B #include +.P +.BI "int clone(int (*" "fn" ")(void *_Nullable), void *" stack \ +", int " flags , +.BI " void *_Nullable " "arg" ", ..." \ +" \fR/*\fP" " pid_t *_Nullable " parent_tid , +.BI " void *_Nullable " tls , +.BI " pid_t *_Nullable " child_tid " \fR*/\fP );" +.P +/* For the prototype of the raw clone() system call, see NOTES */ +.P +.BR "#include " " /* Definition of " "struct clone_args" " */" +.BR "#include " " /* Definition of " CLONE_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "long syscall(SYS_clone3, struct clone_args *" cl_args ", size_t " size ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR clone3 (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +These system calls +create a new ("child") process, in a manner similar to +.BR fork (2). +.P +By contrast with +.BR fork (2), +these system calls provide more precise control over what pieces of execution +context are shared between the calling process and the child process. +For example, using these system calls, the caller can control whether +or not the two processes share the virtual address space, +the table of file descriptors, and the table of signal handlers. +These system calls also allow the new child process to be placed +in separate +.BR namespaces (7). +.P +Note that in this manual +page, "calling process" normally corresponds to "parent process". +But see the descriptions of +.B CLONE_PARENT +and +.B CLONE_THREAD +below. +.P +This page describes the following interfaces: +.IP \[bu] 3 +The glibc +.BR clone () +wrapper function and the underlying system call on which it is based. +The main text describes the wrapper function; +the differences for the raw system call +are described toward the end of this page. +.IP \[bu] +The newer +.BR clone3 () +system call. +.P +In the remainder of this page, the terminology "the clone call" is used +when noting details that apply to all of these interfaces. +.\" +.SS The clone() wrapper function +When the child process is created with the +.BR clone () +wrapper function, +it commences execution by calling the function pointed to by the argument +.IR fn . +(This differs from +.BR fork (2), +where execution continues in the child from the point +of the +.BR fork (2) +call.) +The +.I arg +argument is passed as the argument of the function +.IR fn . +.P +When the +.IR fn ( arg ) +function returns, the child process terminates. +The integer returned by +.I fn +is the exit status for the child process. +The child process may also terminate explicitly by calling +.BR exit (2) +or after receiving a fatal signal. +.P +The +.I stack +argument specifies the location of the stack used by the child process. +Since the child and calling process may share memory, +it is not possible for the child process to execute in the +same stack as the calling process. +The calling process must therefore +set up memory space for the child stack and pass a pointer to this +space to +.BR clone (). +Stacks grow downward on all processors that run Linux +(except the HP PA processors), so +.I stack +usually points to the topmost address of the memory space set up for +the child stack. +Note that +.BR clone () +does not provide a means whereby the caller can inform the kernel of the +size of the stack area. +.P +The remaining arguments to +.BR clone () +are discussed below. +.\" +.SS clone3() +The +.BR clone3 () +system call provides a superset of the functionality of the older +.BR clone () +interface. +It also provides a number of API improvements, including: +space for additional flags bits; +cleaner separation in the use of various arguments; +and the ability to specify the size of the child's stack area. +.P +As with +.BR fork (2), +.BR clone3 () +returns in both the parent and the child. +It returns 0 in the child process and returns the PID of the child +in the parent. +.P +The +.I cl_args +argument of +.BR clone3 () +is a structure of the following form: +.P +.in +4n +.EX +struct clone_args { + u64 flags; /* Flags bit mask */ + u64 pidfd; /* Where to store PID file descriptor + (\fIint *\fP) */ + u64 child_tid; /* Where to store child TID, + in child\[aq]s memory (\fIpid_t *\fP) */ + u64 parent_tid; /* Where to store child TID, + in parent\[aq]s memory (\fIpid_t *\fP) */ + u64 exit_signal; /* Signal to deliver to parent on + child termination */ + u64 stack; /* Pointer to lowest byte of stack */ + u64 stack_size; /* Size of stack */ + u64 tls; /* Location of new TLS */ + u64 set_tid; /* Pointer to a \fIpid_t\fP array + (since Linux 5.5) */ + u64 set_tid_size; /* Number of elements in \fIset_tid\fP + (since Linux 5.5) */ + u64 cgroup; /* File descriptor for target cgroup + of child (since Linux 5.7) */ +}; +.EE +.in +.P +The +.I size +argument that is supplied to +.BR clone3 () +should be initialized to the size of this structure. +(The existence of the +.I size +argument permits future extensions to the +.I clone_args +structure.) +.P +The stack for the child process is specified via +.IR cl_args.stack , +which points to the lowest byte of the stack area, +and +.IR cl_args.stack_size , +which specifies the size of the stack in bytes. +In the case where the +.B CLONE_VM +flag (see below) is specified, a stack must be explicitly allocated +and specified. +Otherwise, these two fields can be specified as NULL and 0, +which causes the child to use the same stack area as the parent +(in the child's own virtual address space). +.P +The remaining fields in the +.I cl_args +argument are discussed below. +.\" +.SS Equivalence between clone() and clone3() arguments +Unlike the older +.BR clone () +interface, where arguments are passed individually, in the newer +.BR clone3 () +interface the arguments are packaged into the +.I clone_args +structure shown above. +This structure allows for a superset of the information passed via the +.BR clone () +arguments. +.P +The following table shows the equivalence between the arguments of +.BR clone () +and the fields in the +.I clone_args +argument supplied to +.BR clone3 (): +.RS 4 +.TS +lb lb lb +l l l +li li l. +clone() clone3() Notes + \fIcl_args\fP field +flags & \[ti]0xff flags T{ +For most flags; details below +T} +parent_tid pidfd See CLONE_PIDFD +child_tid child_tid See CLONE_CHILD_SETTID +parent_tid parent_tid See CLONE_PARENT_SETTID +flags & 0xff exit_signal +stack stack +\fP---\fP stack_size +tls tls See CLONE_SETTLS +\fP---\fP set_tid See below for details +\fP---\fP set_tid_size +\fP---\fP cgroup See CLONE_INTO_CGROUP +.TE +.RE +.\" +.SS The child termination signal +When the child process terminates, a signal may be sent to the parent. +The termination signal is specified in the low byte of +.I flags +.RB ( clone ()) +or in +.I cl_args.exit_signal +.RB ( clone3 ()). +If this signal is specified as anything other than +.BR SIGCHLD , +then the parent process must specify the +.B __WALL +or +.B __WCLONE +options when waiting for the child with +.BR wait (2). +If no signal (i.e., zero) is specified, then the parent process is not signaled +when the child terminates. +.\" +.SS The set_tid array +By default, the kernel chooses the next sequential PID for the new +process in each of the PID namespaces where it is present. +When creating a process with +.BR clone3 (), +the +.I set_tid +array (available since Linux 5.5) +can be used to select specific PIDs for the process in some +or all of the PID namespaces where it is present. +If the PID of the newly created process should be set only for the current +PID namespace or in the newly created PID namespace (if +.I flags +contains +.BR CLONE_NEWPID ) +then the first element in the +.I set_tid +array has to be the desired PID and +.I set_tid_size +needs to be 1. +.P +If the PID of the newly created process should have a certain value in +multiple PID namespaces, then the +.I set_tid +array can have multiple entries. +The first entry defines the PID in the most +deeply nested PID namespace and each of the following entries contains +the PID in the +corresponding ancestor PID namespace. +The number of PID namespaces in which a PID +should be set is defined by +.I set_tid_size +which cannot be larger than the number of currently nested PID namespaces. +.P +To create a process with the following PIDs in a PID namespace hierarchy: +.RS 4 +.TS +lb lb lb +l l l. +PID NS level Requested PID Notes +0 31496 Outermost PID namespace +1 42 +2 7 Innermost PID namespace +.TE +.RE +.P +Set the array to: +.P +.in +4n +.EX +set_tid[0] = 7; +set_tid[1] = 42; +set_tid[2] = 31496; +set_tid_size = 3; +.EE +.in +.P +If only the PIDs in the two innermost PID namespaces +need to be specified, set the array to: +.P +.in +4n +.EX +set_tid[0] = 7; +set_tid[1] = 42; +set_tid_size = 2; +.EE +.in +.P +The PID in the PID namespaces outside the two innermost PID namespaces +is selected the same way as any other PID is selected. +.P +The +.I set_tid +feature requires +.B CAP_SYS_ADMIN +or +(since Linux 5.9) +.\" commit 124ea650d3072b005457faed69909221c2905a1f +.\" commit 1caef81da05a84a40dbf02110e967ce6d1135ff6 +.B CAP_CHECKPOINT_RESTORE +in all owning user namespaces of the target PID namespaces. +.P +Callers may only choose a PID greater than 1 in a given PID namespace +if an +.B init +process (i.e., a process with PID 1) already exists in that namespace. +Otherwise the PID +entry for this PID namespace must be 1. +.\" +.SS The flags mask +Both +.BR clone () +and +.BR clone3 () +allow a flags bit mask that modifies their behavior +and allows the caller to specify what is shared between the calling process +and the child process. +This bit mask\[em]the +.I flags +argument of +.BR clone () +or the +.I cl_args.flags +field passed to +.BR clone3 ()\[em]is +referred to as the +.I flags +mask in the remainder of this page. +.P +The +.I flags +mask is specified as a bitwise OR of zero or more of +the constants listed below. +Except as noted below, these flags are available +(and have the same effect) in both +.BR clone () +and +.BR clone3 (). +.TP +.BR CLONE_CHILD_CLEARTID " (since Linux 2.5.49)" +Clear (zero) the child thread ID at the location pointed to by +.I child_tid +.RB ( clone ()) +or +.I cl_args.child_tid +.RB ( clone3 ()) +in child memory when the child exits, and do a wakeup on the futex +at that address. +The address involved may be changed by the +.BR set_tid_address (2) +system call. +This is used by threading libraries. +.TP +.BR CLONE_CHILD_SETTID " (since Linux 2.5.49)" +Store the child thread ID at the location pointed to by +.I child_tid +.RB ( clone ()) +or +.I cl_args.child_tid +.RB ( clone3 ()) +in the child's memory. +The store operation completes before the clone call +returns control to user space in the child process. +(Note that the store operation may not have completed before the clone call +returns in the parent process, which is relevant if the +.B CLONE_VM +flag is also employed.) +.TP +.BR CLONE_CLEAR_SIGHAND " (since Linux 5.5)" +.\" commit b612e5df4587c934bd056bf05f4a1deca4de4f75 +By default, signal dispositions in the child thread are the same as +in the parent. +If this flag is specified, +then all signals that are handled in the parent +(and not set to +.BR SIG_IGN ) +are reset to their default dispositions +.RB ( SIG_DFL ) +in the child. +.IP +Specifying this flag together with +.B CLONE_SIGHAND +is nonsensical and disallowed. +.TP +.BR CLONE_DETACHED " (historical)" +For a while (during the Linux 2.5 development series) +.\" added in Linux 2.5.32; removed in Linux 2.6.0-test4 +there was a +.B CLONE_DETACHED +flag, +which caused the parent not to receive a signal when the child terminated. +Ultimately, the effect of this flag was subsumed under the +.B CLONE_THREAD +flag and by the time Linux 2.6.0 was released, this flag had no effect. +Starting in Linux 2.6.2, the need to give this flag together with +.B CLONE_THREAD +disappeared. +.IP +This flag is still defined, but it is usually ignored when calling +.BR clone (). +However, see the description of +.B CLONE_PIDFD +for some exceptions. +.TP +.BR CLONE_FILES " (since Linux 2.0)" +If +.B CLONE_FILES +is set, the calling process and the child process share the same file +descriptor table. +Any file descriptor created by the calling process or by the child +process is also valid in the other process. +Similarly, if one of the processes closes a file descriptor, +or changes its associated flags (using the +.BR fcntl (2) +.B F_SETFD +operation), the other process is also affected. +If a process sharing a file descriptor table calls +.BR execve (2), +its file descriptor table is duplicated (unshared). +.IP +If +.B CLONE_FILES +is not set, the child process inherits a copy of all file descriptors +opened in the calling process at the time of the clone call. +Subsequent operations that open or close file descriptors, +or change file descriptor flags, +performed by either the calling +process or the child process do not affect the other process. +Note, however, +that the duplicated file descriptors in the child refer to the same +open file descriptions as the corresponding file descriptors +in the calling process, +and thus share file offsets and file status flags (see +.BR open (2)). +.TP +.BR CLONE_FS " (since Linux 2.0)" +If +.B CLONE_FS +is set, the caller and the child process share the same filesystem +information. +This includes the root of the filesystem, the current +working directory, and the umask. +Any call to +.BR chroot (2), +.BR chdir (2), +or +.BR umask (2) +performed by the calling process or the child process also affects the +other process. +.IP +If +.B CLONE_FS +is not set, the child process works on a copy of the filesystem +information of the calling process at the time of the clone call. +Calls to +.BR chroot (2), +.BR chdir (2), +or +.BR umask (2) +performed later by one of the processes do not affect the other process. +.TP +.BR CLONE_INTO_CGROUP " (since Linux 5.7)" +.\" commit ef2c41cf38a7559bbf91af42d5b6a4429db8fc68 +By default, a child process is placed in the same version 2 +cgroup as its parent. +The +.B CLONE_INTO_CGROUP +flag allows the child process to be created in a different version 2 cgroup. +(Note that +.B CLONE_INTO_CGROUP +has effect only for version 2 cgroups.) +.IP +In order to place the child process in a different cgroup, +the caller specifies +.B CLONE_INTO_CGROUP +in +.I cl_args.flags +and passes a file descriptor that refers to a version 2 cgroup in the +.I cl_args.cgroup +field. +(This file descriptor can be obtained by opening a cgroup v2 directory +using either the +.B O_RDONLY +or the +.B O_PATH +flag.) +Note that all of the usual restrictions (described in +.BR cgroups (7)) +on placing a process into a version 2 cgroup apply. +.IP +Among the possible use cases for +.B CLONE_INTO_CGROUP +are the following: +.RS +.IP \[bu] 3 +Spawning a process into a cgroup different from the parent's cgroup +makes it possible for a service manager to directly spawn new +services into dedicated cgroups. +This eliminates the accounting +jitter that would be caused if the child process was first created in the +same cgroup as the parent and then +moved into the target cgroup. +Furthermore, spawning the child process directly into a target cgroup +is significantly cheaper than moving the child process into +the target cgroup after it has been created. +.IP \[bu] +The +.B CLONE_INTO_CGROUP +flag also allows the creation of +frozen child processes by spawning them into a frozen cgroup. +(See +.BR cgroups (7) +for a description of the freezer controller.) +.IP \[bu] +For threaded applications (or even thread implementations which +make use of cgroups to limit individual threads), it is possible to +establish a fixed cgroup layout before spawning each thread +directly into its target cgroup. +.RE +.TP +.BR CLONE_IO " (since Linux 2.6.25)" +If +.B CLONE_IO +is set, then the new process shares an I/O context with +the calling process. +If this flag is not set, then (as with +.BR fork (2)) +the new process has its own I/O context. +.IP +.\" The following based on text from Jens Axboe +The I/O context is the I/O scope of the disk scheduler (i.e., +what the I/O scheduler uses to model scheduling of a process's I/O). +If processes share the same I/O context, +they are treated as one by the I/O scheduler. +As a consequence, they get to share disk time. +For some I/O schedulers, +.\" the anticipatory and CFQ scheduler +if two processes share an I/O context, +they will be allowed to interleave their disk access. +If several threads are doing I/O on behalf of the same process +.RB ( aio_read (3), +for instance), they should employ +.B CLONE_IO +to get better I/O performance. +.\" with CFQ and AS. +.IP +If the kernel is not configured with the +.B CONFIG_BLOCK +option, this flag is a no-op. +.TP +.BR CLONE_NEWCGROUP " (since Linux 4.6)" +Create the process in a new cgroup namespace. +If this flag is not set, then (as with +.BR fork (2)) +the process is created in the same cgroup namespaces as the calling process. +.IP +For further information on cgroup namespaces, see +.BR cgroup_namespaces (7). +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWCGROUP . +.\" +.TP +.BR CLONE_NEWIPC " (since Linux 2.6.19)" +If +.B CLONE_NEWIPC +is set, then create the process in a new IPC namespace. +If this flag is not set, then (as with +.BR fork (2)), +the process is created in the same IPC namespace as +the calling process. +.IP +For further information on IPC namespaces, see +.BR ipc_namespaces (7). +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWIPC . +This flag can't be specified in conjunction with +.BR CLONE_SYSVSEM . +.TP +.BR CLONE_NEWNET " (since Linux 2.6.24)" +(The implementation of this flag was completed only +by about Linux 2.6.29.) +.IP +If +.B CLONE_NEWNET +is set, then create the process in a new network namespace. +If this flag is not set, then (as with +.BR fork (2)) +the process is created in the same network namespace as +the calling process. +.IP +For further information on network namespaces, see +.BR network_namespaces (7). +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWNET . +.TP +.BR CLONE_NEWNS " (since Linux 2.4.19)" +If +.B CLONE_NEWNS +is set, the cloned child is started in a new mount namespace, +initialized with a copy of the namespace of the parent. +If +.B CLONE_NEWNS +is not set, the child lives in the same mount +namespace as the parent. +.IP +For further information on mount namespaces, see +.BR namespaces (7) +and +.BR mount_namespaces (7). +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWNS . +It is not permitted to specify both +.B CLONE_NEWNS +and +.B CLONE_FS +.\" See https://lwn.net/Articles/543273/ +in the same clone call. +.TP +.BR CLONE_NEWPID " (since Linux 2.6.24)" +.\" This explanation draws a lot of details from +.\" http://lwn.net/Articles/259217/ +.\" Authors: Pavel Emelyanov +.\" and Kir Kolyshkin +.\" +.\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264 +.\" Author: Pavel Emelyanov +If +.B CLONE_NEWPID +is set, then create the process in a new PID namespace. +If this flag is not set, then (as with +.BR fork (2)) +the process is created in the same PID namespace as +the calling process. +.IP +For further information on PID namespaces, see +.BR namespaces (7) +and +.BR pid_namespaces (7). +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWPID . +This flag can't be specified in conjunction with +.BR CLONE_THREAD . +.TP +.B CLONE_NEWUSER +(This flag first became meaningful for +.BR clone () +in Linux 2.6.23, +the current +.BR clone () +semantics were merged in Linux 3.5, +and the final pieces to make the user namespaces completely usable were +merged in Linux 3.8.) +.IP +If +.B CLONE_NEWUSER +is set, then create the process in a new user namespace. +If this flag is not set, then (as with +.BR fork (2)) +the process is created in the same user namespace as the calling process. +.IP +For further information on user namespaces, see +.BR namespaces (7) +and +.BR user_namespaces (7). +.IP +Before Linux 3.8, use of +.B CLONE_NEWUSER +required that the caller have three capabilities: +.BR CAP_SYS_ADMIN , +.BR CAP_SETUID , +and +.BR CAP_SETGID . +.\" Before Linux 2.6.29, it appears that only CAP_SYS_ADMIN was needed +Starting with Linux 3.8, +no privileges are needed to create a user namespace. +.IP +This flag can't be specified in conjunction with +.B CLONE_THREAD +or +.BR CLONE_PARENT . +For security reasons, +.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 +.\" https://lwn.net/Articles/543273/ +.\" The fix actually went into Linux 3.9 and into Linux 3.8.3. However, user namespaces +.\" were, for practical purposes, unusable in earlier Linux 3.8.x because of the +.\" various filesystems that didn't support userns. +.B CLONE_NEWUSER +cannot be specified in conjunction with +.BR CLONE_FS . +.TP +.BR CLONE_NEWUTS " (since Linux 2.6.19)" +If +.B CLONE_NEWUTS +is set, then create the process in a new UTS namespace, +whose identifiers are initialized by duplicating the identifiers +from the UTS namespace of the calling process. +If this flag is not set, then (as with +.BR fork (2)) +the process is created in the same UTS namespace as +the calling process. +.IP +For further information on UTS namespaces, see +.BR uts_namespaces (7). +.IP +Only a privileged process +.RB ( CAP_SYS_ADMIN ) +can employ +.BR CLONE_NEWUTS . +.TP +.BR CLONE_PARENT " (since Linux 2.3.12)" +If +.B CLONE_PARENT +is set, then the parent of the new child (as returned by +.BR getppid (2)) +will be the same as that of the calling process. +.IP +If +.B CLONE_PARENT +is not set, then (as with +.BR fork (2)) +the child's parent is the calling process. +.IP +Note that it is the parent process, as returned by +.BR getppid (2), +which is signaled when the child terminates, so that +if +.B CLONE_PARENT +is set, then the parent of the calling process, rather than the +calling process itself, is signaled. +.IP +The +.B CLONE_PARENT +flag can't be used in clone calls by the +global init process (PID 1 in the initial PID namespace) +and init processes in other PID namespaces. +This restriction prevents the creation of multi-rooted process trees +as well as the creation of unreapable zombies in the initial PID namespace. +.TP +.BR CLONE_PARENT_SETTID " (since Linux 2.5.49)" +Store the child thread ID at the location pointed to by +.I parent_tid +.RB ( clone ()) +or +.I cl_args.parent_tid +.RB ( clone3 ()) +in the parent's memory. +(In Linux 2.5.32-2.5.48 there was a flag +.B CLONE_SETTID +that did this.) +The store operation completes before the clone call +returns control to user space. +.TP +.BR CLONE_PID " (Linux 2.0 to Linux 2.5.15)" +If +.B CLONE_PID +is set, the child process is created with the same process ID as +the calling process. +This is good for hacking the system, but otherwise +of not much use. +From Linux 2.3.21 onward, this flag could be +specified only by the system boot process (PID 0). +The flag disappeared completely from the kernel sources in Linux 2.5.16. +Subsequently, the kernel silently ignored this bit if it was specified in the +.I flags +mask. +Much later, the same bit was recycled for use as the +.B CLONE_PIDFD +flag. +.TP +.BR CLONE_PIDFD " (since Linux 5.2)" +.\" commit b3e5838252665ee4cfa76b82bdf1198dca81e5be +If this flag is specified, +a PID file descriptor referring to the child process is allocated +and placed at a specified location in the parent's memory. +The close-on-exec flag is set on this new file descriptor. +PID file descriptors can be used for the purposes described in +.BR pidfd_open (2). +.RS +.IP \[bu] 3 +When using +.BR clone3 (), +the PID file descriptor is placed at the location pointed to by +.IR cl_args.pidfd . +.IP \[bu] +When using +.BR clone (), +the PID file descriptor is placed at the location pointed to by +.IR parent_tid . +Since the +.I parent_tid +argument is used to return the PID file descriptor, +.B CLONE_PIDFD +cannot be used with +.B CLONE_PARENT_SETTID +when calling +.BR clone (). +.RE +.IP +It is currently not possible to use this flag together with +.B CLONE_THREAD. +This means that the process identified by the PID file descriptor +will always be a thread group leader. +.IP +If the obsolete +.B CLONE_DETACHED +flag is specified alongside +.B CLONE_PIDFD +when calling +.BR clone (), +an error is returned. +An error also results if +.B CLONE_DETACHED +is specified when calling +.BR clone3 (). +This error behavior ensures that the bit corresponding to +.B CLONE_DETACHED +can be reused for further PID file descriptor features in the future. +.TP +.BR CLONE_PTRACE " (since Linux 2.2)" +If +.B CLONE_PTRACE +is specified, and the calling process is being traced, +then trace the child also (see +.BR ptrace (2)). +.TP +.BR CLONE_SETTLS " (since Linux 2.5.32)" +The TLS (Thread Local Storage) descriptor is set to +.IR tls . +.IP +The interpretation of +.I tls +and the resulting effect is architecture dependent. +On x86, +.I tls +is interpreted as a +.I struct user_desc\~* +(see +.BR set_thread_area (2)). +On x86-64 it is the new value to be set for the %fs base register +(see the +.B ARCH_SET_FS +argument to +.BR arch_prctl (2)). +On architectures with a dedicated TLS register, it is the new value +of that register. +.IP +Use of this flag requires detailed knowledge and generally it +should not be used except in libraries implementing threading. +.TP +.BR CLONE_SIGHAND " (since Linux 2.0)" +If +.B CLONE_SIGHAND +is set, the calling process and the child process share the same table of +signal handlers. +If the calling process or child process calls +.BR sigaction (2) +to change the behavior associated with a signal, the behavior is +changed in the other process as well. +However, the calling process and child +processes still have distinct signal masks and sets of pending +signals. +So, one of them may block or unblock signals using +.BR sigprocmask (2) +without affecting the other process. +.IP +If +.B CLONE_SIGHAND +is not set, the child process inherits a copy of the signal handlers +of the calling process at the time of the clone call. +Calls to +.BR sigaction (2) +performed later by one of the processes have no effect on the other +process. +.IP +Since Linux 2.6.0, +.\" Precisely: Linux 2.6.0-test6 +the +.I flags +mask must also include +.B CLONE_VM +if +.B CLONE_SIGHAND +is specified. +.TP +.BR CLONE_STOPPED " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test2 +If +.B CLONE_STOPPED +is set, then the child is initially stopped (as though it was sent a +.B SIGSTOP +signal), and must be resumed by sending it a +.B SIGCONT +signal. +.IP +This flag was +.I deprecated +from Linux 2.6.25 onward, +and was +.I removed +altogether in Linux 2.6.38. +Since then, the kernel silently ignores it without error. +.\" glibc 2.8 removed this defn from bits/sched.h +Starting with Linux 4.6, the same bit was reused for the +.B CLONE_NEWCGROUP +flag. +.TP +.BR CLONE_SYSVSEM " (since Linux 2.5.10)" +If +.B CLONE_SYSVSEM +is set, then the child and the calling process share +a single list of System V semaphore adjustment +.RI ( semadj ) +values (see +.BR semop (2)). +In this case, the shared list accumulates +.I semadj +values across all processes sharing the list, +and semaphore adjustments are performed only when the last process +that is sharing the list terminates (or ceases sharing the list using +.BR unshare (2)). +If this flag is not set, then the child has a separate +.I semadj +list that is initially empty. +.TP +.BR CLONE_THREAD " (since Linux 2.4.0)" +.\" Precisely: Linux 2.6.0-test8 +If +.B CLONE_THREAD +is set, the child is placed in the same thread group as the calling process. +To make the remainder of the discussion of +.B CLONE_THREAD +more readable, the term "thread" is used to refer to the +processes within a thread group. +.IP +Thread groups were a feature added in Linux 2.4 to support the +POSIX threads notion of a set of threads that share a single PID. +Internally, this shared PID is the so-called +thread group identifier (TGID) for the thread group. +Since Linux 2.4, calls to +.BR getpid (2) +return the TGID of the caller. +.IP +The threads within a group can be distinguished by their (system-wide) +unique thread IDs (TID). +A new thread's TID is available as the function result +returned to the caller, +and a thread can obtain +its own TID using +.BR gettid (2). +.IP +When a clone call is made without specifying +.BR CLONE_THREAD , +then the resulting thread is placed in a new thread group +whose TGID is the same as the thread's TID. +This thread is the +.I leader +of the new thread group. +.IP +A new thread created with +.B CLONE_THREAD +has the same parent process as the process that made the clone call +(i.e., like +.BR CLONE_PARENT ), +so that calls to +.BR getppid (2) +return the same value for all of the threads in a thread group. +When a +.B CLONE_THREAD +thread terminates, the thread that created it is not sent a +.B SIGCHLD +(or other termination) signal; +nor can the status of such a thread be obtained +using +.BR wait (2). +(The thread is said to be +.IR detached .) +.IP +After all of the threads in a thread group terminate +the parent process of the thread group is sent a +.B SIGCHLD +(or other termination) signal. +.IP +If any of the threads in a thread group performs an +.BR execve (2), +then all threads other than the thread group leader are terminated, +and the new program is executed in the thread group leader. +.IP +If one of the threads in a thread group creates a child using +.BR fork (2), +then any thread in the group can +.BR wait (2) +for that child. +.IP +Since Linux 2.5.35, the +.I flags +mask must also include +.B CLONE_SIGHAND +if +.B CLONE_THREAD +is specified +(and note that, since Linux 2.6.0, +.\" Precisely: Linux 2.6.0-test6 +.B CLONE_SIGHAND +also requires +.B CLONE_VM +to be included). +.IP +Signal dispositions and actions are process-wide: +if an unhandled signal is delivered to a thread, then +it will affect (terminate, stop, continue, be ignored in) +all members of the thread group. +.IP +Each thread has its own signal mask, as set by +.BR sigprocmask (2). +.IP +A signal may be process-directed or thread-directed. +A process-directed signal is targeted at a thread group (i.e., a TGID), +and is delivered to an arbitrarily selected thread from among those +that are not blocking the signal. +A signal may be process-directed because it was generated by the kernel +for reasons other than a hardware exception, or because it was sent using +.BR kill (2) +or +.BR sigqueue (3). +A thread-directed signal is targeted at (i.e., delivered to) +a specific thread. +A signal may be thread directed because it was sent using +.BR tgkill (2) +or +.BR pthread_sigqueue (3), +or because the thread executed a machine language instruction that triggered +a hardware exception +(e.g., invalid memory access triggering +.B SIGSEGV +or a floating-point exception triggering +.BR SIGFPE ). +.IP +A call to +.BR sigpending (2) +returns a signal set that is the union of the pending process-directed +signals and the signals that are pending for the calling thread. +.IP +If a process-directed signal is delivered to a thread group, +and the thread group has installed a handler for the signal, then +the handler is invoked in exactly one, arbitrarily selected +member of the thread group that has not blocked the signal. +If multiple threads in a group are waiting to accept the same signal using +.BR sigwaitinfo (2), +the kernel will arbitrarily select one of these threads +to receive the signal. +.TP +.BR CLONE_UNTRACED " (since Linux 2.5.46)" +If +.B CLONE_UNTRACED +is specified, then a tracing process cannot force +.B CLONE_PTRACE +on this child process. +.TP +.BR CLONE_VFORK " (since Linux 2.2)" +If +.B CLONE_VFORK +is set, the execution of the calling process is suspended +until the child releases its virtual memory +resources via a call to +.BR execve (2) +or +.BR _exit (2) +(as with +.BR vfork (2)). +.IP +If +.B CLONE_VFORK +is not set, then both the calling process and the child are schedulable +after the call, and an application should not rely on execution occurring +in any particular order. +.TP +.BR CLONE_VM " (since Linux 2.0)" +If +.B CLONE_VM +is set, the calling process and the child process run in the same memory +space. +In particular, memory writes performed by the calling process +or by the child process are also visible in the other process. +Moreover, any memory mapping or unmapping performed with +.BR mmap (2) +or +.BR munmap (2) +by the child or calling process also affects the other process. +.IP +If +.B CLONE_VM +is not set, the child process runs in a separate copy of the memory +space of the calling process at the time of the clone call. +Memory writes or file mappings/unmappings performed by one of the +processes do not affect the other, as with +.BR fork (2). +.IP +If the +.B CLONE_VM +flag is specified and the +.B CLONE_VFORK +flag is not specified, +then any alternate signal stack that was established by +.BR sigaltstack (2) +is cleared in the child process. +.SH RETURN VALUE +.\" gettid(2) returns current->pid; +.\" getpid(2) returns current->tgid; +On success, the thread ID of the child process is returned +in the caller's thread of execution. +On failure, \-1 is returned +in the caller's context, no child process is created, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.BR EACCES " (" clone3 "() only)" +.B CLONE_INTO_CGROUP +was specified in +.IR cl_args.flags , +but the restrictions (described in +.BR cgroups (7)) +on placing the child process into the version 2 cgroup referred to by +.I cl_args.cgroup +are not met. +.TP +.B EAGAIN +Too many processes are already running; see +.BR fork (2). +.TP +.BR EBUSY " (" clone3 "() only)" +.B CLONE_INTO_CGROUP +was specified in +.IR cl_args.flags , +but the file descriptor specified in +.I cl_args.cgroup +refers to a version 2 cgroup in which a domain controller is enabled. +.TP +.BR EEXIST " (" clone3 "() only)" +One (or more) of the PIDs specified in +.I set_tid +already exists in the corresponding PID namespace. +.TP +.B EINVAL +Both +.B CLONE_SIGHAND +and +.B CLONE_CLEAR_SIGHAND +were specified in the +.I flags +mask. +.TP +.B EINVAL +.B CLONE_SIGHAND +was specified in the +.I flags +mask, but +.B CLONE_VM +was not. +(Since Linux 2.6.0.) +.\" Precisely: Linux 2.6.0-test6 +.TP +.B EINVAL +.B CLONE_THREAD +was specified in the +.I flags +mask, but +.B CLONE_SIGHAND +was not. +(Since Linux 2.5.35.) +.\" .TP +.\" .B EINVAL +.\" Precisely one of +.\" .B CLONE_DETACHED +.\" and +.\" .B CLONE_THREAD +.\" was specified. +.\" (Since Linux 2.6.0-test6.) +.TP +.B EINVAL +.B CLONE_THREAD +was specified in the +.I flags +mask, but the current process previously called +.BR unshare (2) +with the +.B CLONE_NEWPID +flag or used +.BR setns (2) +to reassociate itself with a PID namespace. +.TP +.B EINVAL +.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 +Both +.B CLONE_FS +and +.B CLONE_NEWNS +were specified in the +.I flags +mask. +.TP +.BR EINVAL " (since Linux 3.9)" +Both +.B CLONE_NEWUSER +and +.B CLONE_FS +were specified in the +.I flags +mask. +.TP +.B EINVAL +Both +.B CLONE_NEWIPC +and +.B CLONE_SYSVSEM +were specified in the +.I flags +mask. +.TP +.B EINVAL +.B CLONE_NEWPID +and one (or both) of +.B CLONE_THREAD +or +.B CLONE_PARENT +were specified in the +.I flags +mask. +.TP +.B EINVAL +.B CLONE_NEWUSER +and +.B CLONE_THREAD +were specified in the +.I flags +mask. +.TP +.BR EINVAL " (since Linux 2.6.32)" +.\" commit 123be07b0b399670a7cc3d82fef0cb4f93ef885c +.B CLONE_PARENT +was specified, and the caller is an init process. +.TP +.B EINVAL +Returned by the glibc +.BR clone () +wrapper function when +.I fn +or +.I stack +is specified as NULL. +.TP +.B EINVAL +.B CLONE_NEWIPC +was specified in the +.I flags +mask, +but the kernel was not configured with the +.B CONFIG_SYSVIPC +and +.B CONFIG_IPC_NS +options. +.TP +.B EINVAL +.B CLONE_NEWNET +was specified in the +.I flags +mask, +but the kernel was not configured with the +.B CONFIG_NET_NS +option. +.TP +.B EINVAL +.B CLONE_NEWPID +was specified in the +.I flags +mask, +but the kernel was not configured with the +.B CONFIG_PID_NS +option. +.TP +.B EINVAL +.B CLONE_NEWUSER +was specified in the +.I flags +mask, +but the kernel was not configured with the +.B CONFIG_USER_NS +option. +.TP +.B EINVAL +.B CLONE_NEWUTS +was specified in the +.I flags +mask, +but the kernel was not configured with the +.B CONFIG_UTS_NS +option. +.TP +.B EINVAL +.I stack +is not aligned to a suitable boundary for this architecture. +For example, on aarch64, +.I stack +must be a multiple of 16. +.TP +.BR EINVAL " (" clone3 "() only)" +.B CLONE_DETACHED +was specified in the +.I flags +mask. +.TP +.BR EINVAL " (" clone "() only)" +.B CLONE_PIDFD +was specified together with +.B CLONE_DETACHED +in the +.I flags +mask. +.TP +.B EINVAL +.B CLONE_PIDFD +was specified together with +.B CLONE_THREAD +in the +.I flags +mask. +.TP +.BR "EINVAL " "(" clone "() only)" +.B CLONE_PIDFD +was specified together with +.B CLONE_PARENT_SETTID +in the +.I flags +mask. +.TP +.BR EINVAL " (" clone3 "() only)" +.I set_tid_size +is greater than the number of nested PID namespaces. +.TP +.BR EINVAL " (" clone3 "() only)" +One of the PIDs specified in +.I set_tid +was an invalid. +.TP +.BR EINVAL " (" clone3 "() only)" +.\" commit 7f192e3cd316ba58c88dfa26796cf77789dd9872 +.B CLONE_THREAD +or +.B CLONE_PARENT +was specified in the +.I flags +mask, but a signal was specified in +.IR exit_signal . +.TP +.BR EINVAL " (AArch64 only, Linux 4.6 and earlier)" +.I stack +was not aligned to a 128-bit boundary. +.TP +.B ENOMEM +Cannot allocate sufficient memory to allocate a task structure for the +child, or to copy those parts of the caller's context that need to be +copied. +.TP +.BR ENOSPC " (since Linux 3.7)" +.\" commit f2302505775fd13ba93f034206f1e2a587017929 +.B CLONE_NEWPID +was specified in the +.I flags +mask, +but the limit on the nesting depth of PID namespaces +would have been exceeded; see +.BR pid_namespaces (7). +.TP +.BR ENOSPC " (since Linux 4.9; beforehand " EUSERS ) +.B CLONE_NEWUSER +was specified in the +.I flags +mask, and the call would cause the limit on the number of +nested user namespaces to be exceeded. +See +.BR user_namespaces (7). +.IP +From Linux 3.11 to Linux 4.8, the error diagnosed in this case was +.BR EUSERS . +.TP +.BR ENOSPC " (since Linux 4.9)" +One of the values in the +.I flags +mask specified the creation of a new user namespace, +but doing so would have caused the limit defined by the corresponding file in +.I /proc/sys/user +to be exceeded. +For further details, see +.BR namespaces (7). +.TP +.BR EOPNOTSUPP " (" clone3 "() only)" +.B CLONE_INTO_CGROUP +was specified in +.IR cl_args.flags , +but the file descriptor specified in +.I cl_args.cgroup +refers to a version 2 cgroup that is in the +.I domain invalid +state. +.TP +.B EPERM +.BR CLONE_NEWCGROUP , +.BR CLONE_NEWIPC , +.BR CLONE_NEWNET , +.BR CLONE_NEWNS , +.BR CLONE_NEWPID , +or +.B CLONE_NEWUTS +was specified by an unprivileged process (process without \fBCAP_SYS_ADMIN\fP). +.TP +.B EPERM +.B CLONE_PID +was specified by a process other than process 0. +(This error occurs only on Linux 2.5.15 and earlier.) +.TP +.B EPERM +.B CLONE_NEWUSER +was specified in the +.I flags +mask, +but either the effective user ID or the effective group ID of the caller +does not have a mapping in the parent namespace (see +.BR user_namespaces (7)). +.TP +.BR EPERM " (since Linux 3.9)" +.\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d +.B CLONE_NEWUSER +was specified in the +.I flags +mask and the caller is in a chroot environment +.\" FIXME What is the rationale for this restriction? +(i.e., the caller's root directory does not match the root directory +of the mount namespace in which it resides). +.TP +.BR EPERM " (" clone3 "() only)" +.I set_tid_size +was greater than zero, and the caller lacks the +.B CAP_SYS_ADMIN +capability in one or more of the user namespaces that own the +corresponding PID namespaces. +.TP +.BR ERESTARTNOINTR " (since Linux 2.6.17)" +.\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 +System call was interrupted by a signal and will be restarted. +(This can be seen only during a trace.) +.TP +.BR EUSERS " (Linux 3.11 to Linux 4.8)" +.B CLONE_NEWUSER +was specified in the +.I flags +mask, +and the limit on the number of nested user namespaces would be exceeded. +See the discussion of the +.B ENOSPC +error above. +.SH VERSIONS +The glibc +.BR clone () +wrapper function makes some changes +in the memory pointed to by +.I stack +(changes required to set the stack up correctly for the child) +.I before +invoking the +.BR clone () +system call. +So, in cases where +.BR clone () +is used to recursively create children, +do not use the buffer employed for the parent's stack +as the stack of the child. +.P +On i386, +.BR clone () +should not be called through vsyscall, but directly through +.IR "int $0x80" . +.SS C library/kernel differences +The raw +.BR clone () +system call corresponds more closely to +.BR fork (2) +in that execution in the child continues from the point of the +call. +As such, the +.I fn +and +.I arg +arguments of the +.BR clone () +wrapper function are omitted. +.P +In contrast to the glibc wrapper, the raw +.BR clone () +system call accepts NULL as a +.I stack +argument (and +.BR clone3 () +likewise allows +.I cl_args.stack +to be NULL). +In this case, the child uses a duplicate of the parent's stack. +(Copy-on-write semantics ensure that the child gets separate copies +of stack pages when either process modifies the stack.) +In this case, for correct operation, the +.B CLONE_VM +option should not be specified. +(If the child +.I shares +the parent's memory because of the use of the +.B CLONE_VM +flag, +then no copy-on-write duplication occurs and chaos is likely to result.) +.P +The order of the arguments also differs in the raw system call, +and there are variations in the arguments across architectures, +as detailed in the following paragraphs. +.P +The raw system call interface on x86-64 and some other architectures +(including sh, tile, and alpha) is: +.P +.in +4n +.EX +.BI "long clone(unsigned long " flags ", void *" stack , +.BI " int *" parent_tid ", int *" child_tid , +.BI " unsigned long " tls ); +.EE +.in +.P +On x86-32, and several other common architectures +(including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa, +and MIPS), +.\" CONFIG_CLONE_BACKWARDS +the order of the last two arguments is reversed: +.P +.in +4n +.EX +.BI "long clone(unsigned long " flags ", void *" stack , +.BI " int *" parent_tid ", unsigned long " tls , +.BI " int *" child_tid ); +.EE +.in +.P +On the cris and s390 architectures, +.\" CONFIG_CLONE_BACKWARDS2 +the order of the first two arguments is reversed: +.P +.in +4n +.EX +.BI "long clone(void *" stack ", unsigned long " flags , +.BI " int *" parent_tid ", int *" child_tid , +.BI " unsigned long " tls ); +.EE +.in +.P +On the microblaze architecture, +.\" CONFIG_CLONE_BACKWARDS3 +an additional argument is supplied: +.P +.in +4n +.EX +.BI "long clone(unsigned long " flags ", void *" stack , +.BI " int " stack_size , "\fR /* Size of stack */" +.BI " int *" parent_tid ", int *" child_tid , +.BI " unsigned long " tls ); +.EE +.in +.\" +.SS blackfin, m68k, and sparc +.\" Mike Frysinger noted in a 2013 mail: +.\" these arches don't define __ARCH_WANT_SYS_CLONE: +.\" blackfin ia64 m68k sparc +The argument-passing conventions on +blackfin, m68k, and sparc are different from the descriptions above. +For details, see the kernel (and glibc) source. +.SS ia64 +On ia64, a different interface is used: +.P +.in +4n +.EX +.BI "int __clone2(int (*" "fn" ")(void *)," +.BI " void *" stack_base ", size_t " stack_size , +.BI " int " flags ", void *" "arg" ", ..." +.BI " /* pid_t *" parent_tid ", struct user_desc *" tls , +.BI " pid_t *" child_tid " */ );" +.EE +.in +.P +The prototype shown above is for the glibc wrapper function; +for the system call itself, +the prototype can be described as follows (it is identical to the +.BR clone () +prototype on microblaze): +.P +.in +4n +.EX +.BI "long clone2(unsigned long " flags ", void *" stack_base , +.BI " int " stack_size , "\fR /* Size of stack */" +.BI " int *" parent_tid ", int *" child_tid , +.BI " unsigned long " tls ); +.EE +.in +.P +.BR __clone2 () +operates in the same way as +.BR clone (), +except that +.I stack_base +points to the lowest address of the child's stack area, +and +.I stack_size +specifies the size of the stack pointed to by +.IR stack_base . +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR clone3 () +Linux 5.3. +.\" There is no entry for +.\" .BR clone () +.\" in libc5. +.\" glibc2 provides +.\" .BR clone () +.\" as described in this manual page. +.SS Linux 2.4 and earlier +In the Linux 2.4.x series, +.B CLONE_THREAD +generally does not make the parent of the new thread the same +as the parent of the calling process. +However, from Linux 2.4.7 to Linux 2.4.18 the +.B CLONE_THREAD +flag implied the +.B CLONE_PARENT +flag (as in Linux 2.6.0 and later). +.P +In Linux 2.4 and earlier, +.BR clone () +does not take arguments +.IR parent_tid , +.IR tls , +and +.IR child_tid . +.SH NOTES +One use of these system calls +is to implement threads: multiple flows of control in a program that +run concurrently in a shared address space. +.P +The +.BR kcmp (2) +system call can be used to test whether two processes share various +resources such as a file descriptor table, +System V semaphore undo operations, or a virtual address space. +.P +Handlers registered using +.BR pthread_atfork (3) +are not executed during a clone call. +.SH BUGS +GNU C library versions 2.3.4 up to and including 2.24 +contained a wrapper function for +.BR getpid (2) +that performed caching of PIDs. +This caching relied on support in the glibc wrapper for +.BR clone (), +but limitations in the implementation +meant that the cache was not up to date in some circumstances. +In particular, +if a signal was delivered to the child immediately after the +.BR clone () +call, then a call to +.BR getpid (2) +in a handler for the signal could return the PID +of the calling process ("the parent"), +if the clone wrapper had not yet had a chance to update the PID +cache in the child. +(This discussion ignores the case where the child was created using +.BR CLONE_THREAD , +when +.BR getpid (2) +.I should +return the same value in the child and in the process that called +.BR clone (), +since the caller and the child are in the same thread group. +The stale-cache problem also does not occur if the +.I flags +argument includes +.BR CLONE_VM .) +To get the truth, it was sometimes necessary to use code such as the following: +.P +.in +4n +.EX +#include +\& +pid_t mypid; +\& +mypid = syscall(SYS_getpid); +.EE +.in +.\" See also the following bug reports +.\" https://bugzilla.redhat.com/show_bug.cgi?id=417521 +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910 +.P +Because of the stale-cache problem, as well as other problems noted in +.BR getpid (2), +the PID caching feature was removed in glibc 2.25. +.SH EXAMPLES +The following program demonstrates the use of +.BR clone () +to create a child process that executes in a separate UTS namespace. +The child changes the hostname in its UTS namespace. +Both parent and child then display the system hostname, +making it possible to see that the hostname +differs in the UTS namespaces of the parent and child. +For an example of the use of this program, see +.BR setns (2). +.P +Within the sample program, we allocate the memory that is to +be used for the child's stack using +.BR mmap (2) +rather than +.BR malloc (3) +for the following reasons: +.IP \[bu] 3 +.BR mmap (2) +allocates a block of memory that starts on a page +boundary and is a multiple of the page size. +This is useful if we want to establish a guard page (a page with protection +.BR PROT_NONE ) +at the end of the stack using +.BR mprotect (2). +.IP \[bu] +We can specify the +.B MAP_STACK +flag to request a mapping that is suitable for a stack. +For the moment, this flag is a no-op on Linux, +but it exists and has effect on some other systems, +so we should include it for portability. +.SS Program source +.\" SRC BEGIN (clone.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +static int /* Start function for cloned child */ +childFunc(void *arg) +{ + struct utsname uts; +\& + /* Change hostname in UTS namespace of child. */ +\& + if (sethostname(arg, strlen(arg)) == \-1) + err(EXIT_FAILURE, "sethostname"); +\& + /* Retrieve and display hostname. */ +\& + if (uname(&uts) == \-1) + err(EXIT_FAILURE, "uname"); + printf("uts.nodename in child: %s\en", uts.nodename); +\& + /* Keep the namespace open for a while, by sleeping. + This allows some experimentation\-\-for example, another + process might join the namespace. */ +\& + sleep(200); +\& + return 0; /* Child terminates now */ +} +\& +#define STACK_SIZE (1024 * 1024) /* Stack size for cloned child */ +\& +int +main(int argc, char *argv[]) +{ + char *stack; /* Start of stack buffer */ + char *stackTop; /* End of stack buffer */ + pid_t pid; + struct utsname uts; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_SUCCESS); + } +\& + /* Allocate memory to be used for the stack of the child. */ +\& + stack = mmap(NULL, STACK_SIZE, PROT_READ | PROT_WRITE, + MAP_PRIVATE | MAP_ANONYMOUS | MAP_STACK, \-1, 0); + if (stack == MAP_FAILED) + err(EXIT_FAILURE, "mmap"); +\& + stackTop = stack + STACK_SIZE; /* Assume stack grows downward */ +\& + /* Create child that has its own UTS namespace; + child commences execution in childFunc(). */ +\& + pid = clone(childFunc, stackTop, CLONE_NEWUTS | SIGCHLD, argv[1]); + if (pid == \-1) + err(EXIT_FAILURE, "clone"); + printf("clone() returned %jd\en", (intmax_t) pid); +\& + /* Parent falls through to here */ +\& + sleep(1); /* Give child time to change its hostname */ +\& + /* Display hostname in parent\[aq]s UTS namespace. This will be + different from hostname in child\[aq]s UTS namespace. */ +\& + if (uname(&uts) == \-1) + err(EXIT_FAILURE, "uname"); + printf("uts.nodename in parent: %s\en", uts.nodename); +\& + if (waitpid(pid, NULL, 0) == \-1) /* Wait for child */ + err(EXIT_FAILURE, "waitpid"); + printf("child has terminated\en"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fork (2), +.BR futex (2), +.BR getpid (2), +.BR gettid (2), +.BR kcmp (2), +.BR mmap (2), +.BR pidfd_open (2), +.BR set_thread_area (2), +.BR set_tid_address (2), +.BR setns (2), +.BR tkill (2), +.BR unshare (2), +.BR wait (2), +.BR capabilities (7), +.BR namespaces (7), +.BR pthreads (7) diff --git a/man/man2/clone2.2 b/man/man2/clone2.2 new file mode 100644 index 0000000..68f41a5 --- /dev/null +++ b/man/man2/clone2.2 @@ -0,0 +1 @@ +.so man2/clone.2 diff --git a/man/man2/clone3.2 b/man/man2/clone3.2 new file mode 100644 index 0000000..68f41a5 --- /dev/null +++ b/man/man2/clone3.2 @@ -0,0 +1 @@ +.so man2/clone.2 diff --git a/man/man2/close.2 b/man/man2/close.2 new file mode 100644 index 0000000..1ee6c44 --- /dev/null +++ b/man/man2/close.2 @@ -0,0 +1,274 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 21 22:40:25 1993 by Rik Faith +.\" Modified Sat Feb 18 15:27:48 1995 by Michael Haardt +.\" Modified Sun Apr 14 11:40:50 1996 by Andries Brouwer : +.\" corrected description of effect on locks (thanks to +.\" Tigran Aivazian ). +.\" Modified Fri Jan 31 16:21:46 1997 by Eric S. Raymond +.\" Modified 2000-07-22 by Nicolás Lichtmaier +.\" added note about close(2) not guaranteeing that data is safe on close. +.\" +.TH close 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +close \- close a file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int close(int " fd ); +.fi +.SH DESCRIPTION +.BR close () +closes a file descriptor, so that it no longer refers to any file and +may be reused. +Any record locks (see +.BR fcntl (2)) +held on the file it was associated with, +and owned by the process, +are removed regardless of the file descriptor that was used to obtain the lock. +This has some unfortunate consequences +and one should be extra careful when using advisory record locking. +See +.BR fcntl (2) +for discussion of the risks and consequences +as well as for the (probably preferred) open file description locks. +.P +If +.I fd +is the last file descriptor referring to the underlying +open file description (see +.BR open (2)), +the resources associated with the open file description are freed; +if the file descriptor was the last reference to a file which has been +removed using +.BR unlink (2), +the file is deleted. +.SH RETURN VALUE +.BR close () +returns zero on success. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +isn't a valid open file descriptor. +.TP +.B EINTR +.\" Though, it's in doubt whether this error can ever occur; see +.\" https://lwn.net/Articles/576478/ "Returning EINTR from close()" +The +.BR close () +call was interrupted by a signal; see +.BR signal (7). +.TP +.B EIO +An I/O error occurred. +.TP +.B ENOSPC +.TQ +.B EDQUOT +On NFS, these errors are not normally reported against the first write +which exceeds the available storage space, but instead against a +subsequent +.BR write (2), +.BR fsync (2), +or +.BR close (). +.P +See NOTES for a discussion of why +.BR close () +should not be retried after an error. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.\" SVr4 documents an additional ENOLINK error condition. +.SH NOTES +A successful close does not guarantee that the data has been successfully +saved to disk, as the kernel uses the buffer cache to defer writes. +Typically, filesystems do not flush buffers when a file is closed. +If you need to be sure that +the data is physically stored on the underlying disk, use +.BR fsync (2). +(It will depend on the disk hardware at this point.) +.P +The close-on-exec file descriptor flag can be used to ensure +that a file descriptor is automatically closed upon a successful +.BR execve (2); +see +.BR fcntl (2) +for details. +.\" +.SS Multithreaded processes and close() +It is probably unwise to close file descriptors while +they may be in use by system calls in +other threads in the same process. +Since a file descriptor may be reused, +there are some obscure race conditions +that may cause unintended side effects. +.\" Date: Tue, 4 Sep 2007 13:57:35 +0200 +.\" From: Fredrik Noring +.\" One such race involves signals and ERESTARTSYS. If a file descriptor +.\" in use by a system call is closed and then reused by e.g. an +.\" independent open() in some unrelated thread, before the original system +.\" call has restarted after ERESTARTSYS, the original system call will +.\" later restart with the reused file descriptor. This is most likely a +.\" serious programming error. +.P +Furthermore, consider the following scenario where two threads are +performing operations on the same file descriptor: +.IP (1) 5 +One thread is blocked in an I/O system call on the file descriptor. +For example, it is trying to +.BR write (2) +to a pipe that is already full, or trying to +.BR read (2) +from a stream socket which currently has no available data. +.IP (2) +Another thread closes the file descriptor. +.P +The behavior in this situation varies across systems. +On some systems, when the file descriptor is closed, +the blocking system call returns immediately with an error. +.P +On Linux (and possibly some other systems), the behavior is different: +the blocking I/O system call holds a reference to the underlying +open file description, and this reference keeps the description open +until the I/O system call completes. +.\" 'struct file' in kernel-speak +(See +.BR open (2) +for a discussion of open file descriptions.) +Thus, the blocking system call in the first thread may successfully +complete after the +.BR close () +in the second thread. +.\" +.SS Dealing with error returns from close() +A careful programmer will check the return value of +.BR close (), +since it is quite possible that errors on a previous +.BR write (2) +operation are reported only on the final +.BR close () +that releases the open file description. +Failing to check the return value when closing a file may lead to +.I silent +loss of data. +This can especially be observed with NFS and with disk quota. +.P +Note, however, that a failure return should be used only for +diagnostic purposes (i.e., a warning to the application that there +may still be I/O pending or there may have been failed I/O) +or remedial purposes +(e.g., writing the file once more or creating a backup). +.P +Retrying the +.BR close () +after a failure return is the wrong thing to do, +.\" The file descriptor is released early in close(); +.\" close() ==> __close_fd(): +.\" __put_unused_fd() ==> __clear_open_fd() +.\" return filp_close(file, files); +.\" +.\" The errors are returned by filp_close() after the FD has been +.\" cleared for re-use. +since this may cause a reused file descriptor +from another thread to be closed. +This can occur because the Linux kernel +.I always +releases the file descriptor early in the close +operation, freeing it for reuse; +the steps that may return an error, +.\" filp_close() +such as flushing data to the filesystem or device, +occur only later in the close operation. +.P +Many other implementations similarly always close the file descriptor +.\" FreeBSD documents this explicitly. From the look of the source code +.\" SVR4, ancient SunOS, later Solaris, and AIX all do this. +(except in the case of +.BR EBADF , +meaning that the file descriptor was invalid) +even if they subsequently report an error on return from +.BR close (). +POSIX.1 is currently silent on this point, +but there are plans to mandate this behavior in the next major release +.\" Issue 8 +of the standard. +.P +A careful programmer who wants to know about I/O errors may precede +.BR close () +with a call to +.BR fsync (2). +.P +The +.B EINTR +error is a somewhat special case. +Regarding the +.B EINTR +error, POSIX.1-2008 says: +.P +.RS +If +.BR close () +is interrupted by a signal that is to be caught, it shall return \-1 with +.I errno +set to +.B EINTR +and the state of +.I fildes +is unspecified. +.RE +.P +This permits the behavior that occurs on Linux and +many other implementations, where, +as with other errors that may be reported by +.BR close (), +the file descriptor is guaranteed to be closed. +However, it also permits another possibility: +that the implementation returns an +.B EINTR +error and keeps the file descriptor open. +(According to its documentation, HP-UX's +.BR close () +does this.) +The caller must then once more use +.BR close () +to close the file descriptor, to avoid file descriptor leaks. +This divergence in implementation behaviors provides +a difficult hurdle for portable applications, since on many implementations, +.BR close () +must not be called again after an +.B EINTR +error, and on at least one, +.BR close () +must be called again. +There are plans to address this conundrum for +the next major release of the POSIX.1 standard. +.\" FIXME . for later review when Issue 8 is one day released... +.\" POSIX proposes further changes for EINTR +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=529 +.\" +.\" FIXME . +.\" Review the following glibc bug later +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14627 +.SH SEE ALSO +.BR close_range (2), +.BR fcntl (2), +.BR fsync (2), +.BR open (2), +.BR shutdown (2), +.BR unlink (2), +.BR fclose (3) diff --git a/man/man2/close_range.2 b/man/man2/close_range.2 new file mode 100644 index 0000000..74da231 --- /dev/null +++ b/man/man2/close_range.2 @@ -0,0 +1,277 @@ +.\" Copyright (c) 2020 Stephen Kitt +.\" and Copyright (c) 2021 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH close_range 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +close_range \- close all file descriptors in a given range +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BR "#include " " /* Definition of " CLOSE_RANGE_* +.BR "" " constants */" +.P +.BI "int close_range(unsigned int " first ", unsigned int " last \ +", int " flags ); +.fi +.SH DESCRIPTION +The +.BR close_range () +system call closes all open file descriptors from +.I first +to +.I last +(included). +.P +Errors closing a given file descriptor are currently ignored. +.P +.I flags +is a bit mask containing 0 or more of the following: +.TP +.BR CLOSE_RANGE_CLOEXEC " (since Linux 5.11)" +Set the close-on-exec flag on the specified file descriptors, +rather than immediately closing them. +.TP +.B CLOSE_RANGE_UNSHARE +Unshare the specified file descriptors from any other processes +before closing them, +avoiding races with other threads sharing the file descriptor table. +.SH RETURN VALUE +On success, +.BR close_range () +returns 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I flags +is not valid, or +.I first +is greater than +.IR last . +.P +The following can occur with +.B CLOSE_RANGE_UNSHARE +(when constructing the new descriptor table): +.TP +.B EMFILE +The number of open file descriptors exceeds the limit specified in +.I /proc/sys/fs/nr_open +(see +.BR proc (5)). +This error can occur in situations where that limit was lowered before +a call to +.BR close_range () +where the +.B CLOSE_RANGE_UNSHARE +flag is specified. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.SH STANDARDS +None. +.SH HISTORY +FreeBSD. +Linux 5.9, +glibc 2.34. +.SH NOTES +.SS Closing all open file descriptors +.\" 278a5fbaed89dacd04e9d052f4594ffd0e0585de +To avoid blindly closing file descriptors +in the range of possible file descriptors, +this is sometimes implemented (on Linux) +by listing open file descriptors in +.I /proc/self/fd/ +and calling +.BR close (2) +on each one. +.BR close_range () +can take care of this without requiring +.I /proc +and within a single system call, +which provides significant performance benefits. +.SS Closing file descriptors before exec +.\" 60997c3d45d9a67daf01c56d805ae4fec37e0bd8 +File descriptors can be closed safely using +.P +.in +4n +.EX +/* we don't want anything past stderr here */ +close_range(3, \[ti]0U, CLOSE_RANGE_UNSHARE); +execve(....); +.EE +.in +.P +.B CLOSE_RANGE_UNSHARE +is conceptually equivalent to +.P +.in +4n +.EX +unshare(CLONE_FILES); +close_range(first, last, 0); +.EE +.in +.P +but can be more efficient: +if the unshared range extends past +the current maximum number of file descriptors allocated +in the caller's file descriptor table +(the common case when +.I last +is \[ti]0U), +the kernel will unshare a new file descriptor table for the caller up to +.IR first , +copying as few file descriptors as possible. +This avoids subsequent +.BR close (2) +calls entirely; +the whole operation is complete once the table is unshared. +.SS Closing files on \fBexec\fP +.\" 582f1fb6b721facf04848d2ca57f34468da1813e +This is particularly useful in cases where multiple +.RB pre- exec +setup steps risk conflicting with each other. +For example, setting up a +.BR seccomp (2) +profile can conflict with a +.BR close_range () +call: +if the file descriptors are closed before the +.BR seccomp (2) +profile is set up, +the profile setup can't use them itself, +or control their closure; +if the file descriptors are closed afterwards, +the seccomp profile can't block the +.BR close_range () +call or any fallbacks. +Using +.B CLOSE_RANGE_CLOEXEC +avoids this: +the descriptors can be marked before the +.BR seccomp (2) +profile is set up, +and the profile can control access to +.BR close_range () +without affecting the calling process. +.SH EXAMPLES +The program shown below opens the files named in its command-line arguments, +displays the list of files that it has opened +(by iterating through the entries in +.IR /proc/PID/fd ), +uses +.BR close_range () +to close all file descriptors greater than or equal to 3, +and then once more displays the process's list of open files. +The following example demonstrates the use of the program: +.P +.in +4n +.EX +$ \fBtouch /tmp/a /tmp/b /tmp/c\fP +$ \fB./a.out /tmp/a /tmp/b /tmp/c\fP +/tmp/a opened as FD 3 +/tmp/b opened as FD 4 +/tmp/c opened as FD 5 +/proc/self/fd/0 ==> /dev/pts/1 +/proc/self/fd/1 ==> /dev/pts/1 +/proc/self/fd/2 ==> /dev/pts/1 +/proc/self/fd/3 ==> /tmp/a +/proc/self/fd/4 ==> /tmp/b +/proc/self/fd/5 ==> /tmp/b +/proc/self/fd/6 ==> /proc/9005/fd +========= About to call close_range() ======= +/proc/self/fd/0 ==> /dev/pts/1 +/proc/self/fd/1 ==> /dev/pts/1 +/proc/self/fd/2 ==> /dev/pts/1 +/proc/self/fd/3 ==> /proc/9005/fd +.EE +.in +.P +Note that the lines showing the pathname +.I /proc/9005/fd +result from the calls to +.BR opendir (3). +.SS Program source +\& +.\" SRC BEGIN (close_range.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +\& +/* Show the contents of the symbolic links in /proc/self/fd */ +\& +static void +show_fds(void) +{ + DIR *dirp; + char path[PATH_MAX], target[PATH_MAX]; + ssize_t len; + struct dirent *dp; +\& + dirp = opendir("/proc/self/fd"); + if (dirp == NULL) { + perror("opendir"); + exit(EXIT_FAILURE); + } +\& + for (;;) { + dp = readdir(dirp); + if (dp == NULL) + break; +\& + if (dp\->d_type == DT_LNK) { + snprintf(path, sizeof(path), "/proc/self/fd/%s", + dp\->d_name); +\& + len = readlink(path, target, sizeof(target)); + printf("%s ==> %.*s\en", path, (int) len, target); + } + } +\& + closedir(dirp); +} +\& +int +main(int argc, char *argv[]) +{ + int fd; +\& + for (size_t j = 1; j < argc; j++) { + fd = open(argv[j], O_RDONLY); + if (fd == \-1) { + perror(argv[j]); + exit(EXIT_FAILURE); + } + printf("%s opened as FD %d\en", argv[j], fd); + } +\& + show_fds(); +\& + printf("========= About to call close_range() =======\en"); +\& + if (close_range(3, \[ti]0U, 0) == \-1) { + perror("close_range"); + exit(EXIT_FAILURE); + } +\& + show_fds(); + exit(EXIT_FAILURE); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR close (2) diff --git a/man/man2/connect.2 b/man/man2/connect.2 new file mode 100644 index 0000000..b35d991 --- /dev/null +++ b/man/man2/connect.2 @@ -0,0 +1,253 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from /usr/include/sys/socket.h, which does not have +.\" any authorship information in it. It is probably available under the GPL. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page: +.\" +.\" Copyright (c) 1983 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1998, 1999 by Andi Kleen +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH connect 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +connect \- initiate a connection on a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int connect(int " sockfd ", const struct sockaddr *" addr , +.BI " socklen_t " addrlen ); +.fi +.SH DESCRIPTION +The +.BR connect () +system call connects the socket referred to by the file descriptor +.I sockfd +to the address specified by +.IR addr . +The +.I addrlen +argument specifies the size of +.IR addr . +The format of the address in +.I addr +is determined by the address space of the socket +.IR sockfd ; +see +.BR socket (2) +for further details. +.P +If the socket +.I sockfd +is of type +.BR SOCK_DGRAM , +then +.I addr +is the address to which datagrams are sent by default, and the only +address from which datagrams are received. +If the socket is of type +.B SOCK_STREAM +or +.BR SOCK_SEQPACKET , +this call attempts to make a connection to the socket that is bound +to the address specified by +.IR addr . +.P +Some protocol sockets (e.g., UNIX domain stream sockets) +may successfully +.BR connect () +only once. +.P +Some protocol sockets +(e.g., datagram sockets in the UNIX and Internet domains) +may use +.BR connect () +multiple times to change their association. +.P +Some protocol sockets +(e.g., TCP sockets as well as datagram sockets in the UNIX and +Internet domains) +may dissolve the association by connecting to an address with the +.I sa_family +member of +.I sockaddr +set to +.BR AF_UNSPEC ; +thereafter, the socket can be connected to another address. +.RB ( AF_UNSPEC +is supported since Linux 2.2.) +.SH RETURN VALUE +If the connection or binding succeeds, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +The following are general socket errors only. +There may be other domain-specific error codes. +.TP +.B EACCES +For UNIX domain sockets, which are identified by pathname: +Write permission is denied on the socket file, +or search permission is denied for one of the directories +in the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B EACCES +.TQ +.B EPERM +The user tried to connect to a broadcast address without having the socket +broadcast flag enabled or the connection request failed because of a local +firewall rule. +.TP +.B EACCES +It can also be returned if an SELinux policy denied a connection (for +example, if there is a policy saying that an HTTP proxy can only +connect to ports associated with HTTP servers, and the proxy tries to +connect to a different port). +.TP +.B EADDRINUSE +Local address is already in use. +.TP +.B EADDRNOTAVAIL +(Internet domain sockets) +The socket referred to by +.I sockfd +had not previously been bound to an address and, +upon attempting to bind it to an ephemeral port, +it was determined that all port numbers in the ephemeral port range +are currently in use. +See the discussion of +.I /proc/sys/net/ipv4/ip_local_port_range +in +.BR ip (7). +.TP +.B EAFNOSUPPORT +The passed address didn't have the correct address family in its +.I sa_family +field. +.TP +.B EAGAIN +For nonblocking UNIX domain sockets, the socket is nonblocking, and the +connection cannot be completed immediately. +For other socket families, there are insufficient entries in the routing cache. +.TP +.B EALREADY +The socket is nonblocking and a previous connection attempt has not yet +been completed. +.TP +.B EBADF +.I sockfd +is not a valid open file descriptor. +.TP +.B ECONNREFUSED +A +.BR connect () +on a stream socket found no one listening on the remote address. +.TP +.B EFAULT +The socket structure address is outside the user's address space. +.TP +.B EINPROGRESS +The socket is nonblocking and the connection cannot be completed immediately. +(UNIX domain sockets failed with +.B EAGAIN +instead.) +It is possible to +.BR select (2) +or +.BR poll (2) +for completion by selecting the socket for writing. +After +.BR select (2) +indicates writability, use +.BR getsockopt (2) +to read the +.B SO_ERROR +option at level +.B SOL_SOCKET +to determine whether +.BR connect () +completed successfully +.RB ( SO_ERROR +is zero) or unsuccessfully +.RB ( SO_ERROR +is one of the usual error codes listed here, +explaining the reason for the failure). +.TP +.B EINTR +The system call was interrupted by a signal that was caught; see +.BR signal (7). +.\" For TCP, the connection will complete asynchronously. +.\" See http://lkml.org/lkml/2005/7/12/254 +.TP +.B EISCONN +The socket is already connected. +.TP +.B ENETUNREACH +Network is unreachable. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.TP +.B EPROTOTYPE +The socket type does not support the requested communications protocol. +This error can occur, for example, +on an attempt to connect a UNIX domain datagram socket to a stream socket. +.TP +.B ETIMEDOUT +Timeout while attempting connection. +The server may be too +busy to accept new connections. +Note that for IP sockets the timeout may +be very long when syncookies are enabled on the server. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD, +.RB ( connect () +first appeared in 4.2BSD). +.\" SVr4 documents the additional +.\" general error codes +.\" .BR EADDRNOTAVAIL , +.\" .BR EINVAL , +.\" .BR EAFNOSUPPORT , +.\" .BR EALREADY , +.\" .BR EINTR , +.\" .BR EPROTOTYPE , +.\" and +.\" .BR ENOSR . +.\" It also +.\" documents many additional error conditions not described here. +.SH NOTES +If +.BR connect () +fails, consider the state of the socket as unspecified. +Portable applications should close the socket and create a new one for +reconnecting. +.SH EXAMPLES +An example of the use of +.BR connect () +is shown in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR getsockname (2), +.BR listen (2), +.BR socket (2), +.BR path_resolution (7), +.BR selinux (8) diff --git a/man/man2/copy_file_range.2 b/man/man2/copy_file_range.2 new file mode 100644 index 0000000..bc68e7a --- /dev/null +++ b/man/man2/copy_file_range.2 @@ -0,0 +1,308 @@ +.\"This manpage is Copyright (C) 2015 Anna Schumaker +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH copy_file_range 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +copy_file_range \- Copy a range of data from one file to another +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #define _FILE_OFFSET_BITS 64 +.B #include +.P +.BI "ssize_t copy_file_range(int " fd_in ", off_t *_Nullable " off_in , +.BI " int " fd_out ", off_t *_Nullable " off_out , +.BI " size_t " len ", unsigned int " flags ); +.fi +.SH DESCRIPTION +The +.BR copy_file_range () +system call performs an in-kernel copy between two file descriptors +without the additional cost of transferring data from the kernel to user space +and then back into the kernel. +It copies up to +.I len +bytes of data from the source file descriptor +.I fd_in +to the target file descriptor +.IR fd_out , +overwriting any data that exists within the requested range of the target file. +.P +The following semantics apply for +.IR off_in , +and similar statements apply to +.IR off_out : +.IP \[bu] 3 +If +.I off_in +is NULL, then bytes are read from +.I fd_in +starting from the file offset, and the file offset is +adjusted by the number of bytes copied. +.IP \[bu] +If +.I off_in +is not NULL, then +.I off_in +must point to a buffer that specifies the starting +offset where bytes from +.I fd_in +will be read. +The file offset of +.I fd_in +is not changed, but +.I off_in +is adjusted appropriately. +.P +.I fd_in +and +.I fd_out +can refer to the same file. +If they refer to the same file, then the source and target ranges are not +allowed to overlap. +.P +The +.I flags +argument is provided to allow for future extensions +and currently must be set to 0. +.SH RETURN VALUE +Upon successful completion, +.BR copy_file_range () +will return the number of bytes copied between files. +This could be less than the length originally requested. +If the file offset of +.I fd_in +is at or past the end of file, no bytes are copied, and +.BR copy_file_range () +returns zero. +.P +On error, +.BR copy_file_range () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +One or more file descriptors are not valid. +.TP +.B EBADF +.I fd_in +is not open for reading; or +.I fd_out +is not open for writing. +.TP +.B EBADF +The +.B O_APPEND +flag is set for the open file description (see +.BR open (2)) +referred to by the file descriptor +.IR fd_out . +.TP +.B EFBIG +An attempt was made to write at a position past the maximum file offset the +kernel supports. +.TP +.B EFBIG +An attempt was made to write a range that exceeds the allowed maximum file size. +The maximum file size differs between filesystem implementations and can be +different from the maximum allowed file offset. +.TP +.B EFBIG +An attempt was made to write beyond the process's file size resource limit. +This may also result in the process receiving a +.B SIGXFSZ +signal. +.TP +.B EINVAL +The +.I flags +argument is not 0. +.TP +.B EINVAL +.I fd_in +and +.I fd_out +refer to the same file and the source and target ranges overlap. +.TP +.B EINVAL +Either +.I fd_in +or +.I fd_out +is not a regular file. +.TP +.B EIO +A low-level I/O error occurred while copying. +.TP +.B EISDIR +Either +.I fd_in +or +.I fd_out +refers to a directory. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOSPC +There is not enough space on the target filesystem to complete the copy. +.TP +.BR EOPNOTSUPP " (since Linux 5.19)" +.\" commit 868f9f2f8e004bfe0d3935b1976f625b2924893b +The filesystem does not support this operation. +.TP +.B EOVERFLOW +The requested source or destination range is too large to represent in the +specified data types. +.TP +.B EPERM +.I fd_out +refers to an immutable file. +.TP +.B ETXTBSY +Either +.I fd_in +or +.I fd_out +refers to an active swap file. +.TP +.BR EXDEV " (before Linux 5.3)" +.\" commit 5dae222a5ff0c269730393018a5539cc970a4726 +The files referred to by +.IR fd_in " and " fd_out +are not on the same filesystem. +.TP +.BR EXDEV " (since Linux 5.19)" +.\" commit 868f9f2f8e004bfe0d3935b1976f625b2924893b +The files referred to by +.IR fd_in " and " fd_out +are not on the same filesystem, +and the source and target filesystems are not of the same type, +or do not support cross-filesystem copy. +.SH VERSIONS +A major rework of the kernel implementation occurred in Linux 5.3. +Areas of the API that weren't clearly defined were clarified and the API bounds +are much more strictly checked than on earlier kernels. +.P +Since Linux 5.19, +cross-filesystem copies can be achieved +when both filesystems are of the same type, +and that filesystem implements support for it. +See BUGS for behavior prior to Linux 5.19. +.P +Applications should target the behaviour and requirements of Linux 5.19, +that was also backported to earlier stable kernels. +.SH STANDARDS +Linux, GNU. +.SH HISTORY +Linux 4.5, +but glibc 2.27 provides a user-space +emulation when it is not available. +.\" https://sourceware.org/git/?p=glibc.git;a=commit;f=posix/unistd.h;h=bad7a0c81f501fbbcc79af9eaa4b8254441c4a1f +.SH NOTES +If +.I fd_in +is a sparse file, then +.BR copy_file_range () +may expand any holes existing in the requested range. +Users may benefit from calling +.BR copy_file_range () +in a loop, and using the +.BR lseek (2) +.B SEEK_DATA +and +.B SEEK_HOLE +operations to find the locations of data segments. +.P +.BR copy_file_range () +gives filesystems an opportunity to implement "copy acceleration" techniques, +such as the use of reflinks (i.e., two or more inodes that share +pointers to the same copy-on-write disk blocks) +or server-side-copy (in the case of NFS). +.P +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that uses non-null +.I off_in +or +.I off_out +or that takes the address of +.BR copy_file_range , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. +.SH BUGS +In Linux 5.3 to Linux 5.18, +cross-filesystem copies were implemented by the kernel, +if the operation was not supported by individual filesystems. +However, on some virtual filesystems, +the call failed to copy, while still reporting success. +.SH EXAMPLES +.\" SRC BEGIN (copy_file_range.c) +.EX +#define _GNU_SOURCE +#define _FILE_OFFSET_BITS 64 +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int fd_in, fd_out; + off_t len, ret; + struct stat stat; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + fd_in = open(argv[1], O_RDONLY); + if (fd_in == \-1) { + perror("open (argv[1])"); + exit(EXIT_FAILURE); + } +\& + if (fstat(fd_in, &stat) == \-1) { + perror("fstat"); + exit(EXIT_FAILURE); + } +\& + len = stat.st_size; +\& + fd_out = open(argv[2], O_CREAT | O_WRONLY | O_TRUNC, 0644); + if (fd_out == \-1) { + perror("open (argv[2])"); + exit(EXIT_FAILURE); + } +\& + do { + ret = copy_file_range(fd_in, NULL, fd_out, NULL, len, 0); + if (ret == \-1) { + perror("copy_file_range"); + exit(EXIT_FAILURE); + } +\& + len \-= ret; + } while (len > 0 && ret > 0); +\& + close(fd_in); + close(fd_out); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR lseek (2), +.BR sendfile (2), +.BR splice (2) diff --git a/man/man2/creat.2 b/man/man2/creat.2 new file mode 100644 index 0000000..604e121 --- /dev/null +++ b/man/man2/creat.2 @@ -0,0 +1 @@ +.so man2/open.2 diff --git a/man/man2/create_module.2 b/man/man2/create_module.2 new file mode 100644 index 0000000..9b12dfa --- /dev/null +++ b/man/man2/create_module.2 @@ -0,0 +1,72 @@ +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" reformatting and rewordings by mtk +.\" +.TH create_module 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +create_module \- create a loadable module entry +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] caddr_t create_module(const char *" name ", size_t " size ); +.fi +.SH DESCRIPTION +.IR Note : +This system call is present only before Linux 2.6. +.P +.BR create_module () +attempts to create a loadable module entry and reserve the kernel memory +that will be needed to hold the module. +This system call requires privilege. +.SH RETURN VALUE +On success, returns the kernel address at which the module will reside. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EEXIST +A module by that name already exists. +.TP +.B EFAULT +.I name +is outside the program's accessible address space. +.TP +.B EINVAL +The requested size is too small even for the module header information. +.TP +.B ENOMEM +The kernel could not allocate a contiguous block of memory large +enough for the module. +.TP +.B ENOSYS +.BR create_module () +is not supported in this version of the kernel +(e.g., Linux 2.6 or later). +.TP +.B EPERM +The caller was not privileged +(did not have the +.B CAP_SYS_MODULE +capability). +.SH STANDARDS +Linux. +.SH HISTORY +Removed in Linux 2.6. +.\" Removed in Linux 2.5.48 +.P +This obsolete system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc versions before glibc 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it was sufficient to manually declare the interface in your code; +alternatively, you could invoke the system call using +.BR syscall (2). +.SH SEE ALSO +.BR delete_module (2), +.BR init_module (2), +.BR query_module (2) diff --git a/man/man2/delete_module.2 b/man/man2/delete_module.2 new file mode 100644 index 0000000..0199fe3 --- /dev/null +++ b/man/man2/delete_module.2 @@ -0,0 +1,205 @@ +.\" Copyright (C) 2012 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH delete_module 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +delete_module \- unload a kernel module +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " O_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR delete_module (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR delete_module () +system call attempts to remove the unused loadable module entry +identified by +.IR name . +If the module has an +.I exit +function, then that function is executed before unloading the module. +The +.I flags +argument is used to modify the behavior of the system call, +as described below. +This system call requires privilege. +.P +Module removal is attempted according to the following rules: +.IP (1) 5 +If there are other loaded modules that depend on +(i.e., refer to symbols defined in) this module, +then the call fails. +.IP (2) +Otherwise, if the reference count for the module +(i.e., the number of processes currently using the module) +is zero, then the module is immediately unloaded. +.IP (3) +If a module has a nonzero reference count, +then the behavior depends on the bits set in +.IR flags . +In normal usage (see NOTES), the +.B O_NONBLOCK +flag is always specified, and the +.B O_TRUNC +flag may additionally be specified. +.\" O_TRUNC == KMOD_REMOVE_FORCE in kmod library +.\" O_NONBLOCK == KMOD_REMOVE_NOWAIT in kmod library +.IP +The various combinations for +.I flags +have the following effect: +.RS +.TP +.B flags == O_NONBLOCK +The call returns immediately, with an error. +.TP +.B flags == (O_NONBLOCK | O_TRUNC) +The module is unloaded immediately, +regardless of whether it has a nonzero reference count. +.TP +.B (flags & O_NONBLOCK) == 0 +If +.I flags +does not specify +.BR O_NONBLOCK , +the following steps occur: +.RS +.IP \[bu] 3 +The module is marked so that no new references are permitted. +.IP \[bu] +If the module's reference count is nonzero, +the caller is placed in an uninterruptible sleep state +.RB ( TASK_UNINTERRUPTIBLE ) +until the reference count is zero, at which point the call unblocks. +.IP \[bu] +The module is unloaded in the usual way. +.RE +.RE +.P +The +.B O_TRUNC +flag has one further effect on the rules described above. +By default, if a module has an +.I init +function but no +.I exit +function, then an attempt to remove the module fails. +However, if +.B O_TRUNC +was specified, this requirement is bypassed. +.P +Using the +.B O_TRUNC +flag is dangerous! +If the kernel was not built with +.BR CONFIG_MODULE_FORCE_UNLOAD , +this flag is silently ignored. +(Normally, +.B CONFIG_MODULE_FORCE_UNLOAD +is enabled.) +Using this flag taints the kernel (TAINT_FORCED_RMMOD). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBUSY +The module is not "live" +(i.e., it is still being initialized or is already marked for removal); +or, the module has +an +.I init +function but has no +.I exit +function, and +.B O_TRUNC +was not specified in +.IR flags . +.TP +.B EFAULT +.I name +refers to a location outside the process's accessible address space. +.TP +.B ENOENT +No module by that name exists. +.TP +.B EPERM +The caller was not privileged +(did not have the +.B CAP_SYS_MODULE +capability), +or module unloading is disabled +(see +.I /proc/sys/kernel/modules_disabled +in +.BR proc (5)). +.TP +.B EWOULDBLOCK +Other modules depend on this module; +or, +.B O_NONBLOCK +was specified in +.IR flags , +but the reference count of this module is nonzero and +.B O_TRUNC +was not specified in +.IR flags . +.SH STANDARDS +Linux. +.SH HISTORY +The +.BR delete_module () +system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc versions before glibc 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it is (before glibc 2.23) sufficient to +manually declare the interface in your code; +alternatively, you can invoke the system call using +.BR syscall (2). +.SS Linux 2.4 and earlier +In Linux 2.4 and earlier, the system call took only one argument: +.P +.BI " int delete_module(const char *" name ); +.P +If +.I name +is NULL, all unused modules marked auto-clean are removed. +.P +Some further details of differences in the behavior of +.BR delete_module () +in Linux 2.4 and earlier are +.I not +currently explained in this manual page. +.SH NOTES +The uninterruptible sleep that may occur if +.B O_NONBLOCK +is omitted from +.I flags +is considered undesirable, because the sleeping process is left +in an unkillable state. +As at Linux 3.7, specifying +.B O_NONBLOCK +is optional, but in future kernels it is likely to become mandatory. +.SH SEE ALSO +.BR create_module (2), +.BR init_module (2), +.BR query_module (2), +.BR lsmod (8), +.BR modprobe (8), +.BR rmmod (8) diff --git a/man/man2/dup.2 b/man/man2/dup.2 new file mode 100644 index 0000000..a192868 --- /dev/null +++ b/man/man2/dup.2 @@ -0,0 +1,284 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2005, 2008 Michael Kerrisk +.\" and Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1993-07-21, Rik Faith +.\" Modified 1994-08-21, Michael Chastain : +.\" Fixed typos. +.\" Modified 1997-01-31, Eric S. Raymond +.\" Modified 2002-09-28, aeb +.\" 2009-01-12, mtk, reordered text in DESCRIPTION and added some +.\" details for dup2(). +.\" 2008-10-09, mtk: add description of dup3() +.\" +.TH dup 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dup, dup2, dup3 \- duplicate a file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int dup(int " oldfd ); +.BI "int dup2(int " oldfd ", int " newfd ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.BR "#include " " /* Definition of " O_* " constants */" +.B #include +.P +.BI "int dup3(int " oldfd ", int " newfd ", int " flags ); +.fi +.SH DESCRIPTION +The +.BR dup () +system call allocates a new file descriptor that refers to the same +open file description as the descriptor +.IR oldfd . +(For an explanation of open file descriptions, see +.BR open (2).) +The new file descriptor number is guaranteed to be the lowest-numbered +file descriptor that was unused in the calling process. +.P +After a successful return, +the old and new file descriptors may be used interchangeably. +Since the two file descriptors refer to the same open file description, +they share file offset and file status flags; +for example, if the file offset is modified by using +.BR lseek (2) +on one of the file descriptors, +the offset is also changed for the other file descriptor. +.P +The two file descriptors do not share file descriptor flags +(the close-on-exec flag). +The close-on-exec flag +.RB ( FD_CLOEXEC ; +see +.BR fcntl (2)) +for the duplicate descriptor is off. +.\" +.SS dup2() +The +.BR dup2 () +system call performs the same task as +.BR dup (), +but instead of using the lowest-numbered unused file descriptor, +it uses the file descriptor number specified in +.IR newfd . +In other words, +the file descriptor +.I newfd +is adjusted so that it now refers to the same open file description as +.IR oldfd . +.P +If the file descriptor +.I newfd +was previously open, it is closed before being reused; +the close is performed silently +(i.e., any errors during the close are not reported by +.BR dup2 ()). +.P +The steps of closing and reusing the file descriptor +.I newfd +are performed +.IR atomically . +This is important, because trying to implement equivalent functionality using +.BR close (2) +and +.BR dup () +would be +subject to race conditions, whereby +.I newfd +might be reused between the two steps. +Such reuse could happen because the main program is interrupted +by a signal handler that allocates a file descriptor, +or because a parallel thread allocates a file descriptor. +.P +Note the following points: +.IP \[bu] 3 +If +.I oldfd +is not a valid file descriptor, then the call fails, and +.I newfd +is not closed. +.IP \[bu] +If +.I oldfd +is a valid file descriptor, and +.I newfd +has the same value as +.IR oldfd , +then +.BR dup2 () +does nothing, and returns +.IR newfd . +.\" +.SS dup3() +.BR dup3 () +is the same as +.BR dup2 (), +except that: +.IP \[bu] 3 +The caller can force the close-on-exec flag to be set +for the new file descriptor by specifying +.B O_CLOEXEC +in +.IR flags . +See the description of the same flag in +.BR open (2) +for reasons why this may be useful. +.IP \[bu] +.\" Ulrich Drepper, LKML, 2008-10-09: +.\" We deliberately decided on this change. Otherwise, what is the +.\" result of dup3(fd, fd, O_CLOEXEC)? +If +.I oldfd +equals +.IR newfd , +then +.BR dup3 () +fails with the error +.BR EINVAL . +.SH RETURN VALUE +On success, these system calls +return the new file descriptor. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I oldfd +isn't an open file descriptor. +.TP +.B EBADF +.I newfd +is out of the allowed range for file descriptors (see the discussion of +.B RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B EBUSY +(Linux only) This may be returned by +.BR dup2 () +or +.BR dup3 () +during a race condition with +.BR open (2) +and +.BR dup (). +.TP +.B EINTR +The +.BR dup2 () +or +.BR dup3 () +call was interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +.RB ( dup3 ()) +.I flags +contain an invalid value. +.TP +.B EINVAL +.RB ( dup3 ()) +.I oldfd +was equal to +.IR newfd . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached +(see the discussion of +.B RLIMIT_NOFILE +in +.BR getrlimit (2)). +.SH STANDARDS +.TP +.BR dup () +.TQ +.BR dup2 () +POSIX.1-2008. +.TP +.BR dup3 () +Linux. +.SH HISTORY +.TP +.BR dup () +.TQ +.BR dup2 () +POSIX.1-2001, SVr4, 4.3BSD. +.\" SVr4 documents additional +.\" EINTR and ENOLINK error conditions. POSIX.1 adds EINTR. +.\" The EBUSY return is Linux-specific. +.TP +.BR dup3 () +Linux 2.6.27, +glibc 2.9. +.SH NOTES +The error returned by +.BR dup2 () +is different from that returned by +.BR fcntl( "..., " F_DUPFD ", ..." ) +when +.I newfd +is out of range. +On some systems, +.BR dup2 () +also sometimes returns +.B EINVAL +like +.BR F_DUPFD . +.P +If +.I newfd +was open, any errors that would have been reported at +.BR close (2) +time are lost. +If this is of concern, +then\[em]unless the program is single-threaded and does not allocate +file descriptors in signal handlers\[em]the correct approach is +.I not +to close +.I newfd +before calling +.BR dup2 (), +because of the race condition described above. +Instead, code something like the following could be used: +.P +.in +4n +.EX +/* Obtain a duplicate of \[aq]newfd\[aq] that can subsequently + be used to check for close() errors; an EBADF error + means that \[aq]newfd\[aq] was not open. */ +\& +tmpfd = dup(newfd); +if (tmpfd == \-1 && errno != EBADF) { + /* Handle unexpected dup() error. */ +} +\& +/* Atomically duplicate \[aq]oldfd\[aq] on \[aq]newfd\[aq]. */ +\& +if (dup2(oldfd, newfd) == \-1) { + /* Handle dup2() error. */ +} +\& +/* Now check for close() errors on the file originally + referred to by \[aq]newfd\[aq]. */ +\& +if (tmpfd != \-1) { + if (close(tmpfd) == \-1) { + /* Handle errors from close. */ + } +} +.EE +.in +.SH SEE ALSO +.BR close (2), +.BR fcntl (2), +.BR open (2), +.BR pidfd_getfd (2) diff --git a/man/man2/dup2.2 b/man/man2/dup2.2 new file mode 100644 index 0000000..49a65c6 --- /dev/null +++ b/man/man2/dup2.2 @@ -0,0 +1 @@ +.so man2/dup.2 diff --git a/man/man2/dup3.2 b/man/man2/dup3.2 new file mode 100644 index 0000000..49a65c6 --- /dev/null +++ b/man/man2/dup3.2 @@ -0,0 +1 @@ +.so man2/dup.2 diff --git a/man/man2/epoll_create.2 b/man/man2/epoll_create.2 new file mode 100644 index 0000000..2f73450 --- /dev/null +++ b/man/man2/epoll_create.2 @@ -0,0 +1,144 @@ +.\" Copyright (C) 2003 Davide Libenzi +.\" and Copyright 2008, 2009, 2012 Michael Kerrisk +.\" Davide Libenzi +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2005-04-04 by Marko Kohtala +.\" 2008-10-10, mtk: add description of epoll_create1() +.\" +.TH epoll_create 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +epoll_create, epoll_create1 \- open an epoll file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int epoll_create(int " size ); +.BI "int epoll_create1(int " flags ); +.fi +.SH DESCRIPTION +.BR epoll_create () +creates a new +.BR epoll (7) +instance. +Since Linux 2.6.8, the +.I size +argument is ignored, but must be greater than zero; see HISTORY. +.P +.BR epoll_create () +returns a file descriptor referring to the new epoll instance. +This file descriptor is used for all the subsequent calls to the +.B epoll +interface. +When no longer required, the file descriptor returned by +.BR epoll_create () +should be closed by using +.BR close (2). +When all file descriptors referring to an epoll instance have been closed, +the kernel destroys the instance +and releases the associated resources for reuse. +.SS epoll_create1() +If +.I flags +is 0, then, other than the fact that the obsolete +.I size +argument is dropped, +.BR epoll_create1 () +is the same as +.BR epoll_create (). +The following value can be included in +.I flags +to obtain different behavior: +.TP +.B EPOLL_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.SH RETURN VALUE +On success, +these system calls +return a file descriptor (a nonnegative integer). +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I size +is not positive. +.TP +.B EINVAL +.RB ( epoll_create1 ()) +Invalid value specified in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +There was insufficient memory to create the kernel object. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR epoll_create () +Linux 2.6, +glibc 2.3.2. +.\" To be precise: kernel 2.5.44. +.\" The interface should be finalized by Linux kernel 2.5.66. +.TP +.BR epoll_create1 () +Linux 2.6.27, +glibc 2.9. +.P +In the initial +.BR epoll_create () +implementation, the +.I size +argument informed the kernel of the number of file descriptors +that the caller expected to add to the +.B epoll +instance. +The kernel used this information as a hint for the amount of +space to initially allocate in internal data structures describing events. +(If necessary, the kernel would allocate more space +if the caller's usage exceeded the hint given in +.IR size .) +Nowadays, +this hint is no longer required +(the kernel dynamically sizes the required data structures +without needing the hint), but +.I size +must still be greater than zero, +in order to ensure backward compatibility when new +.B epoll +applications are run on older kernels. +.P +Prior to Linux 2.6.29, +.\" commit 9df04e1f25effde823a600e755b51475d438f56b +a +.I /proc/sys/fs/epoll/max_user_instances +kernel parameter limited live epolls for each real user ID, +and caused +.BR epoll_create () +to fail with +.B EMFILE +on overrun. +.SH SEE ALSO +.BR close (2), +.BR epoll_ctl (2), +.BR epoll_wait (2), +.BR epoll (7) diff --git a/man/man2/epoll_create1.2 b/man/man2/epoll_create1.2 new file mode 100644 index 0000000..69605b6 --- /dev/null +++ b/man/man2/epoll_create1.2 @@ -0,0 +1 @@ +.so man2/epoll_create.2 diff --git a/man/man2/epoll_ctl.2 b/man/man2/epoll_ctl.2 new file mode 100644 index 0000000..4984c2c --- /dev/null +++ b/man/man2/epoll_ctl.2 @@ -0,0 +1,429 @@ +.\" Copyright (C) 2003 Davide Libenzi +.\" Davide Libenzi +.\" and Copyright 2009, 2014, 2016, 2018, 2019 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH epoll_ctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +epoll_ctl \- control interface for an epoll file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int epoll_ctl(int " epfd ", int " op ", int " fd , +.BI " struct epoll_event *_Nullable " event ); +.fi +.SH DESCRIPTION +This system call is used to add, modify, or remove +entries in the interest list of the +.BR epoll (7) +instance +referred to by the file descriptor +.IR epfd . +It requests that the operation +.I op +be performed for the target file descriptor, +.IR fd . +.P +Valid values for the +.I op +argument are: +.TP +.B EPOLL_CTL_ADD +Add an entry to the interest list of the epoll file descriptor, +.IR epfd . +The entry includes the file descriptor, +.IR fd , +a reference to the corresponding open file description (see +.BR epoll (7) +and +.BR open (2)), +and the settings specified in +.IR event . +.TP +.B EPOLL_CTL_MOD +Change the settings associated with +.I fd +in the interest list to the new settings specified in +.IR event . +.TP +.B EPOLL_CTL_DEL +Remove (deregister) the target file descriptor +.I fd +from the interest list. +The +.I event +argument is ignored and can be NULL (but see BUGS below). +.P +The +.I event +argument describes the object linked to the file descriptor +.IR fd . +The +.I struct epoll_event +is described in +.BR epoll_event (3type). +.P +The +.I data +member of the +.I epoll_event +structure specifies data that the kernel should save and then return (via +.BR epoll_wait (2)) +when this file descriptor becomes ready. +.P +The +.I events +member of the +.I epoll_event +structure is a bit mask composed by ORing together zero or more event types, +returned by +.BR epoll_wait (2), +and input flags, which affect its behaviour, but aren't returned. +The available event types are: +.TP +.B EPOLLIN +The associated file is available for +.BR read (2) +operations. +.TP +.B EPOLLOUT +The associated file is available for +.BR write (2) +operations. +.TP +.BR EPOLLRDHUP " (since Linux 2.6.17)" +Stream socket peer closed connection, +or shut down writing half of connection. +(This flag is especially useful for writing simple code to detect +peer shutdown when using edge-triggered monitoring.) +.TP +.B EPOLLPRI +There is an exceptional condition on the file descriptor. +See the discussion of +.B POLLPRI +in +.BR poll (2). +.TP +.B EPOLLERR +Error condition happened on the associated file descriptor. +This event is also reported for the write end of a pipe when the read end +has been closed. +.IP +.BR epoll_wait (2) +will always report for this event; it is not necessary to set it in +.I events +when calling +.BR epoll_ctl (). +.TP +.B EPOLLHUP +Hang up happened on the associated file descriptor. +.IP +.BR epoll_wait (2) +will always wait for this event; it is not necessary to set it in +.I events +when calling +.BR epoll_ctl (). +.IP +Note that when reading from a channel such as a pipe or a stream socket, +this event merely indicates that the peer closed its end of the channel. +Subsequent reads from the channel will return 0 (end of file) +only after all outstanding data in the channel has been consumed. +.P +And the available input flags are: +.TP +.B EPOLLET +Requests edge-triggered notification for the associated file descriptor. +The default behavior for +.B epoll +is level-triggered. +See +.BR epoll (7) +for more detailed information about edge-triggered and +level-triggered notification. +.TP +.BR EPOLLONESHOT " (since Linux 2.6.2)" +Requests one-shot notification for the associated file descriptor. +This means that after an event notified for the file descriptor by +.BR epoll_wait (2), +the file descriptor is disabled in the interest list and no other events +will be reported by the +.B epoll +interface. +The user must call +.BR epoll_ctl () +with +.B EPOLL_CTL_MOD +to rearm the file descriptor with a new event mask. +.TP +.BR EPOLLWAKEUP " (since Linux 3.5)" +.\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238 +If +.B EPOLLONESHOT +and +.B EPOLLET +are clear and the process has the +.B CAP_BLOCK_SUSPEND +capability, +ensure that the system does not enter "suspend" or +"hibernate" while this event is pending or being processed. +The event is considered as being "processed" from the time +when it is returned by a call to +.BR epoll_wait (2) +until the next call to +.BR epoll_wait (2) +on the same +.BR epoll (7) +file descriptor, +the closure of that file descriptor, +the removal of the event file descriptor with +.BR EPOLL_CTL_DEL , +or the clearing of +.B EPOLLWAKEUP +for the event file descriptor with +.BR EPOLL_CTL_MOD . +See also BUGS. +.TP +.BR EPOLLEXCLUSIVE " (since Linux 4.5)" +Sets an exclusive wakeup mode for the epoll file descriptor that is being +attached to the target file descriptor, +.IR fd . +When a wakeup event occurs and multiple epoll file descriptors +are attached to the same target file using +.BR EPOLLEXCLUSIVE , +one or more of the epoll file descriptors will receive an event with +.BR epoll_wait (2). +The default in this scenario (when +.B EPOLLEXCLUSIVE +is not set) is for all epoll file descriptors to receive an event. +.B EPOLLEXCLUSIVE +is thus useful for avoiding thundering herd problems in certain scenarios. +.IP +If the same file descriptor is in multiple epoll instances, +some with the +.B EPOLLEXCLUSIVE +flag, and others without, then events will be provided to all epoll +instances that did not specify +.BR EPOLLEXCLUSIVE , +and at least one of the epoll instances that did specify +.BR EPOLLEXCLUSIVE . +.IP +The following values may be specified in conjunction with +.BR EPOLLEXCLUSIVE : +.BR EPOLLIN , +.BR EPOLLOUT , +.BR EPOLLWAKEUP , +and +.BR EPOLLET . +.B EPOLLHUP +and +.B EPOLLERR +can also be specified, but this is not required: +as usual, these events are always reported if they occur, +regardless of whether they are specified in +.IR events . +Attempts to specify other values in +.I events +yield the error +.BR EINVAL . +.IP +.B EPOLLEXCLUSIVE +may be used only in an +.B EPOLL_CTL_ADD +operation; attempts to employ it with +.B EPOLL_CTL_MOD +yield an error. +If +.B EPOLLEXCLUSIVE +has been set using +.BR epoll_ctl (), +then a subsequent +.B EPOLL_CTL_MOD +on the same +.IR epfd ,\~ fd +pair yields an error. +A call to +.BR epoll_ctl () +that specifies +.B EPOLLEXCLUSIVE +in +.I events +and specifies the target file descriptor +.I fd +as an epoll instance will likewise fail. +The error in all of these cases is +.BR EINVAL . +.SH RETURN VALUE +When successful, +.BR epoll_ctl () +returns zero. +When an error occurs, +.BR epoll_ctl () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I epfd +or +.I fd +is not a valid file descriptor. +.TP +.B EEXIST +.I op +was +.BR EPOLL_CTL_ADD , +and the supplied file descriptor +.I fd +is already registered with this epoll instance. +.TP +.B EINVAL +.I epfd +is not an +.B epoll +file descriptor, +or +.I fd +is the same as +.IR epfd , +or the requested operation +.I op +is not supported by this interface. +.TP +.B EINVAL +An invalid event type was specified along with +.B EPOLLEXCLUSIVE +in +.IR events . +.TP +.B EINVAL +.I op +was +.B EPOLL_CTL_MOD +and +.I events +included +.BR EPOLLEXCLUSIVE . +.TP +.B EINVAL +.I op +was +.B EPOLL_CTL_MOD +and the +.B EPOLLEXCLUSIVE +flag has previously been applied to this +.IR epfd ,\~ fd +pair. +.TP +.B EINVAL +.B EPOLLEXCLUSIVE +was specified in +.I event +and +.I fd +refers to an epoll instance. +.TP +.B ELOOP +.I fd +refers to an epoll instance and this +.B EPOLL_CTL_ADD +operation would result in a circular loop of epoll instances +monitoring one another or a nesting depth of epoll instances +greater than 5. +.TP +.B ENOENT +.I op +was +.B EPOLL_CTL_MOD +or +.BR EPOLL_CTL_DEL , +and +.I fd +is not registered with this epoll instance. +.TP +.B ENOMEM +There was insufficient memory to handle the requested +.I op +control operation. +.TP +.B ENOSPC +The limit imposed by +.I /proc/sys/fs/epoll/max_user_watches +was encountered while trying to register +.RB ( EPOLL_CTL_ADD ) +a new file descriptor on an epoll instance. +See +.BR epoll (7) +for further details. +.TP +.B EPERM +The target file +.I fd +does not support +.BR epoll . +This error can occur if +.I fd +refers to, for example, a regular file or a directory. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6, +.\" To be precise: Linux 2.5.44. +.\" The interface should be finalized by Linux 2.5.66. +glibc 2.3.2. +.SH NOTES +The +.B epoll +interface supports all file descriptors that support +.BR poll (2). +.SH BUGS +Before Linux 2.6.9, the +.B EPOLL_CTL_DEL +operation required a non-null pointer in +.IR event , +even though this argument is ignored. +Since Linux 2.6.9, +.I event +can be specified as NULL +when using +.BR EPOLL_CTL_DEL . +Applications that need to be portable to kernels before Linux 2.6.9 +should specify a non-null pointer in +.IR event . +.P +If +.B EPOLLWAKEUP +is specified in +.IR flags , +but the caller does not have the +.B CAP_BLOCK_SUSPEND +capability, then the +.B EPOLLWAKEUP +flag is +.IR "silently ignored" . +This unfortunate behavior is necessary because no validity +checks were performed on the +.I flags +argument in the original implementation, and the addition of the +.B EPOLLWAKEUP +with a check that caused the call to fail if the caller did not have the +.B CAP_BLOCK_SUSPEND +capability caused a breakage in at least one existing user-space +application that happened to randomly (and uselessly) specify this bit. +.\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change) +.\" https://lwn.net/Articles/520198/ +A robust application should therefore double check that it has the +.B CAP_BLOCK_SUSPEND +capability if attempting to use the +.B EPOLLWAKEUP +flag. +.SH SEE ALSO +.BR epoll_create (2), +.BR epoll_wait (2), +.BR poll (2), +.BR epoll (7) diff --git a/man/man2/epoll_pwait.2 b/man/man2/epoll_pwait.2 new file mode 100644 index 0000000..9282a70 --- /dev/null +++ b/man/man2/epoll_pwait.2 @@ -0,0 +1 @@ +.so man2/epoll_wait.2 diff --git a/man/man2/epoll_pwait2.2 b/man/man2/epoll_pwait2.2 new file mode 100644 index 0000000..9282a70 --- /dev/null +++ b/man/man2/epoll_pwait2.2 @@ -0,0 +1 @@ +.so man2/epoll_wait.2 diff --git a/man/man2/epoll_wait.2 b/man/man2/epoll_wait.2 new file mode 100644 index 0000000..3b1fbc8 --- /dev/null +++ b/man/man2/epoll_wait.2 @@ -0,0 +1,288 @@ +.\" Copyright (C) 2003 Davide Libenzi +.\" Davide Libenzi +.\" and Copyright 2007, 2012, 2014, 2018 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2007-04-30: mtk, Added description of epoll_pwait() +.\" +.TH epoll_wait 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +epoll_wait, epoll_pwait, epoll_pwait2 \- +wait for an I/O event on an epoll file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int epoll_wait(int " epfd ", struct epoll_event *" events , +.BI " int " maxevents ", int " timeout ); +.BI "int epoll_pwait(int " epfd ", struct epoll_event *" events , +.BI " int " maxevents ", int " timeout , +.BI " const sigset_t *_Nullable " sigmask ); +.BI "int epoll_pwait2(int " epfd ", struct epoll_event *" events , +.BI " int " maxevents ", \ +const struct timespec *_Nullable " timeout , +.BI " const sigset_t *_Nullable " sigmask ); +.fi +.SH DESCRIPTION +The +.BR epoll_wait () +system call waits for events on the +.BR epoll (7) +instance referred to by the file descriptor +.IR epfd . +The buffer pointed to by +.I events +is used to return information from the ready list +about file descriptors in the interest list that +have some events available. +Up to +.I maxevents +are returned by +.BR epoll_wait (). +The +.I maxevents +argument must be greater than zero. +.P +The +.I timeout +argument specifies the number of milliseconds that +.BR epoll_wait () +will block. +Time is measured against the +.B CLOCK_MONOTONIC +clock. +.P +A call to +.BR epoll_wait () +will block until either: +.IP \[bu] 3 +a file descriptor delivers an event; +.IP \[bu] +the call is interrupted by a signal handler; or +.IP \[bu] +the timeout expires. +.P +Note that the +.I timeout +interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the blocking interval +may overrun by a small amount. +Specifying a +.I timeout +of \-1 causes +.BR epoll_wait () +to block indefinitely, while specifying a +.I timeout +equal to zero causes +.BR epoll_wait () +to return immediately, even if no events are available. +.P +The +.I struct epoll_event +is described in +.BR epoll_event (3type). +.P +The +.I data +field of each returned +.I epoll_event +structure contains the same data as was specified +in the most recent call to +.BR epoll_ctl (2) +.RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD ) +for the corresponding open file descriptor. +.P +The +.I events +field is a bit mask that indicates the events that have occurred for the +corresponding open file description. +See +.BR epoll_ctl (2) +for a list of the bits that may appear in this mask. +.\" +.SS epoll_pwait() +The relationship between +.BR epoll_wait () +and +.BR epoll_pwait () +is analogous to the relationship between +.BR select (2) +and +.BR pselect (2): +like +.BR pselect (2), +.BR epoll_pwait () +allows an application to safely wait until either a file descriptor +becomes ready or until a signal is caught. +.P +The following +.BR epoll_pwait () +call: +.P +.in +4n +.EX +ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask); +.EE +.in +.P +is equivalent to +.I atomically +executing the following calls: +.P +.in +4n +.EX +sigset_t origmask; +\& +pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); +ready = epoll_wait(epfd, &events, maxevents, timeout); +pthread_sigmask(SIG_SETMASK, &origmask, NULL); +.EE +.in +.P +The +.I sigmask +argument may be specified as NULL, in which case +.BR epoll_pwait () +is equivalent to +.BR epoll_wait (). +.\" +.SS epoll_pwait2() +The +.BR epoll_pwait2 () +system call is equivalent to +.BR epoll_pwait () +except for the +.I timeout +argument. +It takes an argument of type +.I timespec +to be able to specify nanosecond resolution timeout. +This argument functions the same as in +.BR pselect (2) +and +.BR ppoll (2). +If +.I timeout +is NULL, then +.BR epoll_pwait2 () +can block indefinitely. +.SH RETURN VALUE +On success, +.BR epoll_wait () +returns the number of file descriptors ready for the requested I/O operation, +or zero if no file descriptor became ready during the requested +.I timeout +milliseconds. +On failure, +.BR epoll_wait () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I epfd +is not a valid file descriptor. +.TP +.B EFAULT +The memory area pointed to by +.I events +is not accessible with write permissions. +.TP +.B EINTR +The call was interrupted by a signal handler before either (1) any of the +requested events occurred or (2) the +.I timeout +expired; see +.BR signal (7). +.TP +.B EINVAL +.I epfd +is not an +.B epoll +file descriptor, or +.I maxevents +is less than or equal to zero. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR epoll_wait () +Linux 2.6, +.\" To be precise: Linux 2.5.44. +.\" The interface should be finalized by Linux 2.5.66. +glibc 2.3.2. +.TP +.BR epoll_pwait () +Linux 2.6.19, +glibc 2.6. +.TP +.BR epoll_pwait2 () +Linux 5.11. +.SH NOTES +While one thread is blocked in a call to +.BR epoll_wait (), +it is possible for another thread to add a file descriptor to the waited-upon +.B epoll +instance. +If the new file descriptor becomes ready, +it will cause the +.BR epoll_wait () +call to unblock. +.P +If more than +.I maxevents +file descriptors are ready when +.BR epoll_wait () +is called, then successive +.BR epoll_wait () +calls will round robin through the set of ready file descriptors. +This behavior helps avoid starvation scenarios, +where a process fails to notice that additional file descriptors +are ready because it focuses on a set of file descriptors that +are already known to be ready. +.P +Note that it is possible to call +.BR epoll_wait () +on an +.B epoll +instance whose interest list is currently empty +(or whose interest list becomes empty because file descriptors are closed +or removed from the interest in another thread). +The call will block until some file descriptor is later added to the +interest list (in another thread) and that file descriptor becomes ready. +.SS C library/kernel differences +The raw +.BR epoll_pwait () +and +.BR epoll_pwait2 () +system calls have a sixth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the +.I sigmask +argument. +The glibc +.BR epoll_pwait () +wrapper function specifies this argument as a fixed value +(equal to +.IR sizeof(sigset_t) ). +.SH BUGS +Before Linux 2.6.37, a +.I timeout +value larger than approximately +.I LONG_MAX / HZ +milliseconds is treated as \-1 (i.e., infinity). +Thus, for example, on a system where +.I sizeof(long) +is 4 and the kernel +.I HZ +value is 1000, +this means that timeouts greater than 35.79 minutes are treated as infinity. +.SH SEE ALSO +.BR epoll_create (2), +.BR epoll_ctl (2), +.BR epoll (7) diff --git a/man/man2/eventfd.2 b/man/man2/eventfd.2 new file mode 100644 index 0000000..e70612d --- /dev/null +++ b/man/man2/eventfd.2 @@ -0,0 +1,447 @@ +'\" t +.\" Copyright (C) 2008 Michael Kerrisk +.\" starting from a version by Davide Libenzi +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC +.\" +.TH eventfd 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +eventfd \- create a file descriptor for event notification +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int eventfd(unsigned int " initval ", int " flags ); +.fi +.SH DESCRIPTION +.BR eventfd () +creates an "eventfd object" that can be used as +an event wait/notify mechanism by user-space applications, +and by the kernel to notify user-space applications of events. +The object contains an unsigned 64-bit integer +.RI ( uint64_t ) +counter that is maintained by the kernel. +This counter is initialized with the value specified in the argument +.IR initval . +.P +As its return value, +.BR eventfd () +returns a new file descriptor that can be used to refer to the +eventfd object. +.P +The following values may be bitwise ORed in +.I flags +to change the behavior of +.BR eventfd (): +.TP +.BR EFD_CLOEXEC " (since Linux 2.6.27)" +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.TP +.BR EFD_NONBLOCK " (since Linux 2.6.27)" +Set the +.B O_NONBLOCK +file status flag on the open file description (see +.BR open (2)) +referred to by the new file descriptor. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.BR EFD_SEMAPHORE " (since Linux 2.6.30)" +Provide semaphore-like semantics for reads from the new file descriptor. +See below. +.P +Up to Linux 2.6.26, the +.I flags +argument is unused, and must be specified as zero. +.P +The following operations can be performed on the file descriptor returned by +.BR eventfd (): +.TP +.BR read (2) +Each successful +.BR read (2) +returns an 8-byte integer. +A +.BR read (2) +fails with the error +.B EINVAL +if the size of the supplied buffer is less than 8 bytes. +.IP +The value returned by +.BR read (2) +is in host byte order\[em]that is, +the native byte order for integers on the host machine. +.IP +The semantics of +.BR read (2) +depend on whether the eventfd counter currently has a nonzero value +and whether the +.B EFD_SEMAPHORE +flag was specified when creating the eventfd file descriptor: +.RS +.IP \[bu] 3 +If +.B EFD_SEMAPHORE +was not specified and the eventfd counter has a nonzero value, then a +.BR read (2) +returns 8 bytes containing that value, +and the counter's value is reset to zero. +.IP \[bu] +If +.B EFD_SEMAPHORE +was specified and the eventfd counter has a nonzero value, then a +.BR read (2) +returns 8 bytes containing the value 1, +and the counter's value is decremented by 1. +.IP \[bu] +If the eventfd counter is zero at the time of the call to +.BR read (2), +then the call either blocks until the counter becomes nonzero +(at which time, the +.BR read (2) +proceeds as described above) +or fails with the error +.B EAGAIN +if the file descriptor has been made nonblocking. +.RE +.TP +.BR write (2) +A +.BR write (2) +call adds the 8-byte integer value supplied in its +buffer to the counter. +The maximum value that may be stored in the counter is the largest +unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe). +If the addition would cause the counter's value to exceed +the maximum, then the +.BR write (2) +either blocks until a +.BR read (2) +is performed on the file descriptor, +or fails with the error +.B EAGAIN +if the file descriptor has been made nonblocking. +.IP +A +.BR write (2) +fails with the error +.B EINVAL +if the size of the supplied buffer is less than 8 bytes, +or if an attempt is made to write the value 0xffffffffffffffff. +.TP +.BR poll (2) +.TQ +.BR select (2) +.TQ +(and similar) +The returned file descriptor supports +.BR poll (2) +(and analogously +.BR epoll (7)) +and +.BR select (2), +as follows: +.RS +.IP \[bu] 3 +The file descriptor is readable +(the +.BR select (2) +.I readfds +argument; the +.BR poll (2) +.B POLLIN +flag) +if the counter has a value greater than 0. +.IP \[bu] +The file descriptor is writable +(the +.BR select (2) +.I writefds +argument; the +.BR poll (2) +.B POLLOUT +flag) +if it is possible to write a value of at least "1" without blocking. +.IP \[bu] +If an overflow of the counter value was detected, +then +.BR select (2) +indicates the file descriptor as being both readable and writable, and +.BR poll (2) +returns a +.B POLLERR +event. +As noted above, +.BR write (2) +can never overflow the counter. +However an overflow can occur if 2\[ha]64 +eventfd "signal posts" were performed by the KAIO +subsystem (theoretically possible, but practically unlikely). +If an overflow has occurred, then +.BR read (2) +will return that maximum +.I uint64_t +value (i.e., 0xffffffffffffffff). +.RE +.IP +The eventfd file descriptor also supports the other file-descriptor +multiplexing APIs: +.BR pselect (2) +and +.BR ppoll (2). +.TP +.BR close (2) +When the file descriptor is no longer required it should be closed. +When all file descriptors associated with the same eventfd object +have been closed, the resources for object are freed by the kernel. +.P +A copy of the file descriptor created by +.BR eventfd () +is inherited by the child produced by +.BR fork (2). +The duplicate file descriptor is associated with the same +eventfd object. +File descriptors created by +.BR eventfd () +are preserved across +.BR execve (2), +unless the close-on-exec flag has been set. +.SH RETURN VALUE +On success, +.BR eventfd () +returns a new eventfd file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +An unsupported value was specified in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been +reached. +.TP +.B ENODEV +.\" Note from Davide: +.\" The ENODEV error is basically never going to happen if +.\" the kernel boots correctly. That error happen only if during +.\" the kernel initialization, some error occur in the anonymous +.\" inode source initialization. +Could not mount (internal) anonymous inode device. +.TP +.B ENOMEM +There was insufficient memory to create a new +eventfd file descriptor. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR eventfd () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS C library/kernel differences +There are two underlying Linux system calls: +.BR eventfd () +and the more recent +.BR eventfd2 (). +The former system call does not implement a +.I flags +argument. +The latter system call implements the +.I flags +values described above. +The glibc wrapper function will use +.BR eventfd2 () +where it is available. +.SS Additional glibc features +The GNU C library defines an additional type, +and two functions that attempt to abstract some of the details of +reading and writing on an eventfd file descriptor: +.P +.in +4n +.EX +typedef uint64_t eventfd_t; +\& +int eventfd_read(int fd, eventfd_t *value); +int eventfd_write(int fd, eventfd_t value); +.EE +.in +.P +The functions perform the read and write operations on an +eventfd file descriptor, +returning 0 if the correct number of bytes was transferred, +or \-1 otherwise. +.SH STANDARDS +Linux, GNU. +.SH HISTORY +.TP +.BR eventfd () +Linux 2.6.22, +glibc 2.8. +.\" eventfd() is in glibc 2.7, but reportedly does not build +.TP +.BR eventfd2 () +Linux 2.6.27 (see VERSIONS). +Since glibc 2.9, the +.BR eventfd () +wrapper will employ the +.BR eventfd2 () +system call, if it is supported by the kernel. +.SH NOTES +Applications can use an eventfd file descriptor instead of a pipe (see +.BR pipe (2)) +in all cases where a pipe is used simply to signal events. +The kernel overhead of an eventfd file descriptor +is much lower than that of a pipe, +and only one file descriptor is +required (versus the two required for a pipe). +.P +When used in the kernel, an eventfd +file descriptor can provide a bridge from kernel to user space, allowing, +for example, functionalities like KAIO (kernel AIO) +.\" or eventually syslets/threadlets +to signal to a file descriptor that some operation is complete. +.P +A key point about an eventfd file descriptor is that it can be +monitored just like any other file descriptor using +.BR select (2), +.BR poll (2), +or +.BR epoll (7). +This means that an application can simultaneously monitor the +readiness of "traditional" files and the readiness of other +kernel mechanisms that support the eventfd interface. +(Without the +.BR eventfd () +interface, these mechanisms could not be multiplexed via +.BR select (2), +.BR poll (2), +or +.BR epoll (7).) +.P +The current value of an eventfd counter can be viewed +via the entry for the corresponding file descriptor in the process's +.IR /proc/ pid /fdinfo +directory. +See +.BR proc (5) +for further details. +.SH EXAMPLES +The following program creates an eventfd file descriptor +and then forks to create a child process. +While the parent briefly sleeps, +the child writes each of the integers supplied in the program's +command-line arguments to the eventfd file descriptor. +When the parent has finished sleeping, +it reads from the eventfd file descriptor. +.P +The following shell session shows a sample run of the program: +.P +.in +4n +.EX +.RB "$" " ./a.out 1 2 4 7 14" +Child writing 1 to efd +Child writing 2 to efd +Child writing 4 to efd +Child writing 7 to efd +Child writing 14 to efd +Child completed write loop +Parent about to read +Parent read 28 (0x1c) from efd +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (eventfd.c) +.EX +#include +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int efd; + uint64_t u; + ssize_t s; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s ...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + efd = eventfd(0, 0); + if (efd == \-1) + err(EXIT_FAILURE, "eventfd"); +\& + switch (fork()) { + case 0: + for (size_t j = 1; j < argc; j++) { + printf("Child writing %s to efd\en", argv[j]); + u = strtoull(argv[j], NULL, 0); + /* strtoull() allows various bases */ + s = write(efd, &u, sizeof(uint64_t)); + if (s != sizeof(uint64_t)) + err(EXIT_FAILURE, "write"); + } + printf("Child completed write loop\en"); +\& + exit(EXIT_SUCCESS); +\& + default: + sleep(2); +\& + printf("Parent about to read\en"); + s = read(efd, &u, sizeof(uint64_t)); + if (s != sizeof(uint64_t)) + err(EXIT_FAILURE, "read"); + printf("Parent read %"PRIu64" (%#"PRIx64") from efd\en", u, u); + exit(EXIT_SUCCESS); +\& + case \-1: + err(EXIT_FAILURE, "fork"); + } +} +.EE +.\" SRC END +.SH SEE ALSO +.BR futex (2), +.BR pipe (2), +.BR poll (2), +.BR read (2), +.BR select (2), +.BR signalfd (2), +.BR timerfd_create (2), +.BR write (2), +.BR epoll (7), +.BR sem_overview (7) diff --git a/man/man2/eventfd2.2 b/man/man2/eventfd2.2 new file mode 100644 index 0000000..eddfaa8 --- /dev/null +++ b/man/man2/eventfd2.2 @@ -0,0 +1 @@ +.so man2/eventfd.2 diff --git a/man/man2/execve.2 b/man/man2/execve.2 new file mode 100644 index 0000000..d318d80 --- /dev/null +++ b/man/man2/execve.2 @@ -0,0 +1,889 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" and Copyright (c) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1994-08-21 by Michael Chastain : +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1999-11-12 by Urs Thuermann +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2006-09-04 Michael Kerrisk +.\" Added list of process attributes that are not preserved on exec(). +.\" 2007-09-14 Ollie Wild , mtk +.\" Add text describing limits on command-line arguments + environment +.\" +.TH execve 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +execve \- execute program +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int execve(const char *" pathname ", char *const _Nullable " argv [], +.BI " char *const _Nullable " envp []); +.fi +.SH DESCRIPTION +.BR execve () +executes the program referred to by \fIpathname\fP. +This causes the program that is currently being run by the calling process +to be replaced with a new program, with newly initialized stack, heap, +and (initialized and uninitialized) data segments. +.P +\fIpathname\fP must be either a binary executable, or a script +starting with a line of the form: +.P +.in +4n +.EX +\fB#!\fP\fIinterpreter \fP[optional-arg] +.EE +.in +.P +For details of the latter case, see "Interpreter scripts" below. +.P +.I argv +is an array of pointers to strings passed to the new program +as its command-line arguments. +By convention, the first of these strings (i.e., +.IR argv[0] ) +should contain the filename associated with the file being executed. +The +.I argv +array must be terminated by a null pointer. +(Thus, in the new program, +.I argv[argc] +will be a null pointer.) +.P +.I envp +is an array of pointers to strings, conventionally of the form +.BR key=value , +which are passed as the environment of the new program. +The +.I envp +array must be terminated by a null pointer. +.P +This manual page describes the Linux system call in detail; +for an overview of the nomenclature and the many, often preferable, +standardised variants of this function provided by libc, +including ones that search the +.B PATH +environment variable, see +.BR exec (3). +.P +The argument vector and environment can be accessed by the +new program's main function, when it is defined as: +.P +.in +4n +.EX +int main(int argc, char *argv[], char *envp[]) +.EE +.in +.P +Note, however, that the use of a third argument to the main function +is not specified in POSIX.1; +according to POSIX.1, +the environment should be accessed via the external variable +.BR environ (7). +.P +.BR execve () +does not return on success, and the text, initialized data, +uninitialized data (bss), and stack of the calling process are overwritten +according to the contents of the newly loaded program. +.P +If the current program is being ptraced, a \fBSIGTRAP\fP signal is sent to it +after a successful +.BR execve (). +.P +If the set-user-ID bit is set on the program file referred to by +\fIpathname\fP, +then the effective user ID of the calling process is changed +to that of the owner of the program file. +Similarly, if the set-group-ID bit is set on the program file, +then the effective group ID of the calling +process is set to the group of the program file. +.P +The aforementioned transformations of the effective IDs are +.I not +performed (i.e., the set-user-ID and set-group-ID bits are ignored) +if any of the following is true: +.IP \[bu] 3 +the +.I no_new_privs +attribute is set for the calling thread (see +.BR prctl (2)); +.IP \[bu] +the underlying filesystem is mounted +.I nosuid +(the +.B MS_NOSUID +flag for +.BR mount (2)); +or +.IP \[bu] +the calling process is being ptraced. +.P +The capabilities of the program file (see +.BR capabilities (7)) +are also ignored if any of the above are true. +.P +The effective user ID of the process is copied to the saved set-user-ID; +similarly, the effective group ID is copied to the saved set-group-ID. +This copying takes place after any effective ID changes that occur +because of the set-user-ID and set-group-ID mode bits. +.P +The process's real UID and real GID, as well as its supplementary group IDs, +are unchanged by a call to +.BR execve (). +.P +If the executable is an a.out dynamically linked +binary executable containing +shared-library stubs, the Linux dynamic linker +.BR ld.so (8) +is called at the start of execution to bring +needed shared objects into memory +and link the executable with them. +.P +If the executable is a dynamically linked ELF executable, the +interpreter named in the PT_INTERP segment is used to load the needed +shared objects. +This interpreter is typically +.I /lib/ld\-linux.so.2 +for binaries linked with glibc (see +.BR ld\-linux.so (8)). +.\" +.SS Effect on process attributes +All process attributes are preserved during an +.BR execve (), +except the following: +.IP \[bu] 3 +The dispositions of any signals that are being caught are +reset to the default +.RB ( signal (7)). +.IP \[bu] +Any alternate signal stack is not preserved +.RB ( sigaltstack (2)). +.IP \[bu] +Memory mappings are not preserved +.RB ( mmap (2)). +.IP \[bu] +Attached System\ V shared memory segments are detached +.RB ( shmat (2)). +.IP \[bu] +POSIX shared memory regions are unmapped +.RB ( shm_open (3)). +.IP \[bu] +Open POSIX message queue descriptors are closed +.RB ( mq_overview (7)). +.IP \[bu] +Any open POSIX named semaphores are closed +.RB ( sem_overview (7)). +.IP \[bu] +POSIX timers are not preserved +.RB ( timer_create (2)). +.IP \[bu] +Any open directory streams are closed +.RB ( opendir (3)). +.IP \[bu] +Memory locks are not preserved +.RB ( mlock (2), +.BR mlockall (2)). +.IP \[bu] +Exit handlers are not preserved +.RB ( atexit (3), +.BR on_exit (3)). +.IP \[bu] +The floating-point environment is reset to the default (see +.BR fenv (3)). +.P +The process attributes in the preceding list are all specified +in POSIX.1. +The following Linux-specific process attributes are also +not preserved during an +.BR execve (): +.IP \[bu] 3 +The process's "dumpable" attribute is set to the value 1, +unless a set-user-ID program, a set-group-ID program, +or a program with capabilities is being executed, +in which case the dumpable flag may instead be reset to the value in +.IR /proc/sys/fs/suid_dumpable , +in the circumstances described under +.B PR_SET_DUMPABLE +in +.BR prctl (2). +Note that changes to the "dumpable" attribute may cause ownership +of files in the process's +.IR /proc/ pid +directory to change to +.IR root:root , +as described in +.BR proc (5). +.IP \[bu] +The +.BR prctl (2) +.B PR_SET_KEEPCAPS +flag is cleared. +.IP \[bu] +(Since Linux 2.4.36 / 2.6.23) +If a set-user-ID or set-group-ID program is being executed, +then the parent death signal set by +.BR prctl (2) +.B PR_SET_PDEATHSIG +flag is cleared. +.IP \[bu] +The process name, as set by +.BR prctl (2) +.B PR_SET_NAME +(and displayed by +.IR "ps\ \-o comm" ), +is reset to the name of the new executable file. +.IP \[bu] +The +.B SECBIT_KEEP_CAPS +.I securebits +flag is cleared. +See +.BR capabilities (7). +.IP \[bu] +The termination signal is reset to +.B SIGCHLD +(see +.BR clone (2)). +.IP \[bu] +The file descriptor table is unshared, undoing the effect of the +.B CLONE_FILES +flag of +.BR clone (2). +.P +Note the following further points: +.IP \[bu] 3 +All threads other than the calling thread are destroyed during an +.BR execve (). +Mutexes, condition variables, and other pthreads objects are not preserved. +.IP \[bu] +The equivalent of \fIsetlocale(LC_ALL, "C")\fP +is executed at program start-up. +.IP \[bu] +POSIX.1 specifies that the dispositions of any signals that +are ignored or set to the default are left unchanged. +POSIX.1 specifies one exception: if +.B SIGCHLD +is being ignored, +then an implementation may leave the disposition unchanged or +reset it to the default; Linux does the former. +.IP \[bu] +Any outstanding asynchronous I/O operations are canceled +.RB ( aio_read (3), +.BR aio_write (3)). +.IP \[bu] +For the handling of capabilities during +.BR execve (), +see +.BR capabilities (7). +.IP \[bu] +By default, file descriptors remain open across an +.BR execve (). +File descriptors that are marked close-on-exec are closed; +see the description of +.B FD_CLOEXEC +in +.BR fcntl (2). +(If a file descriptor is closed, this will cause the release +of all record locks obtained on the underlying file by this process. +See +.BR fcntl (2) +for details.) +POSIX.1 says that if file descriptors 0, 1, and 2 would +otherwise be closed after a successful +.BR execve (), +and the process would gain privilege because the set-user-ID or +set-group-ID mode bit was set on the executed file, +then the system may open an unspecified file for each of these +file descriptors. +As a general principle, no portable program, whether privileged or not, +can assume that these three file descriptors will remain +closed across an +.BR execve (). +.\" On Linux it appears that these file descriptors are +.\" always open after an execve(), and it looks like +.\" Solaris 8 and FreeBSD 6.1 are the same. -- mtk, 30 Apr 2007 +.SS Interpreter scripts +An interpreter script is a text file that has execute +permission enabled and whose first line is of the form: +.P +.in +4n +.EX +\fB#!\fP\fIinterpreter \fP[optional-arg] +.EE +.in +.P +The +.I interpreter +must be a valid pathname for an executable file. +.P +If the +.I pathname +argument of +.BR execve () +specifies an interpreter script, then +.I interpreter +will be invoked with the following arguments: +.P +.in +4n +.EX +\fIinterpreter\fP [optional-arg] \fIpathname\fP arg... +.EE +.in +.P +where +.I pathname +is the pathname of the file specified as the first argument of +.BR execve (), +and +.I arg... +is the series of words pointed to by the +.I argv +argument of +.BR execve (), +starting at +.IR argv[1] . +Note that there is no way to get the +.I argv[0] +that was passed to the +.BR execve () +call. +.\" See the P - preserve-argv[0] option. +.\" Documentation/admin-guide/binfmt-misc.rst +.\" https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html +.P +For portable use, +.I optional-arg +should either be absent, or be specified as a single word (i.e., it +should not contain white space); see NOTES below. +.P +Since Linux 2.6.28, +.\" commit bf2a9a39639b8b51377905397a5005f444e9a892 +the kernel permits the interpreter of a script to itself be a script. +This permission is recursive, up to a limit of four recursions, +so that the interpreter may be a script which is interpreted by a script, +and so on. +.SS Limits on size of arguments and environment +Most UNIX implementations impose some limit on the total size +of the command-line argument +.RI ( argv ) +and environment +.RI ( envp ) +strings that may be passed to a new program. +POSIX.1 allows an implementation to advertise this limit using the +.B ARG_MAX +constant (either defined in +.I +or available at run time using the call +.IR "sysconf(_SC_ARG_MAX)" ). +.P +Before Linux 2.6.23, the memory used to store the +environment and argument strings was limited to 32 pages +(defined by the kernel constant +.BR MAX_ARG_PAGES ). +On architectures with a 4-kB page size, +this yields a maximum size of 128\ kB. +.P +On Linux 2.6.23 and later, most architectures support a size limit +derived from the soft +.B RLIMIT_STACK +resource limit (see +.BR getrlimit (2)) +that is in force at the time of the +.BR execve () +call. +(Architectures with no memory management unit are excepted: +they maintain the limit that was in effect before Linux 2.6.23.) +This change allows programs to have a much larger +argument and/or environment list. +.\" For some background on the changes to ARG_MAX in Linux 2.6.23 and +.\" Linux 2.6.25, see: +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=5786 +.\" http://bugzilla.kernel.org/show_bug.cgi?id=10095 +.\" http://thread.gmane.org/gmane.linux.kernel/646709/focus=648101, +.\" checked into Linux 2.6.25 as commit a64e715fc74b1a7dcc5944f848acc38b2c4d4ee2. +For these architectures, the total size is limited to 1/4 of the allowed +stack size. +(Imposing the 1/4-limit +ensures that the new program always has some stack space.) +.\" Ollie: That doesn't include the lists of pointers, though, +.\" so the actual usage is a bit higher (1 pointer per argument). +Additionally, the total size is limited to 3/4 of the value +of the kernel constant +.B _STK_LIM +(8 MiB). +Since Linux 2.6.25, +the kernel also places a floor of 32 pages on this size limit, +so that, even when +.B RLIMIT_STACK +is set very low, +applications are guaranteed to have at least as much argument and +environment space as was provided by Linux 2.6.22 and earlier. +(This guarantee was not provided in Linux 2.6.23 and 2.6.24.) +Additionally, the limit per string is 32 pages (the kernel constant +.BR MAX_ARG_STRLEN ), +and the maximum number of strings is 0x7FFFFFFF. +.SH RETURN VALUE +On success, +.BR execve () +does not return, on error \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B E2BIG +The total number of bytes in the environment +.RI ( envp ) +and argument list +.RI ( argv ) +is too large, +an argument or environment string is too long, +or the full +.I pathname +of the executable is too long. +The terminating null byte is counted as part of the string length. +.TP +.B EACCES +Search permission is denied on a component of the path prefix of +.I pathname +or the name of a script interpreter. +(See also +.BR path_resolution (7).) +.TP +.B EACCES +The file or a script interpreter is not a regular file. +.TP +.B EACCES +Execute permission is denied for the file or a script or ELF interpreter. +.TP +.B EACCES +The filesystem is mounted +.IR noexec . +.TP +.BR EAGAIN " (since Linux 3.1)" +.\" commit 72fa59970f8698023045ab0713d66f3f4f96945c +Having changed its real UID using one of the +.BR set*uid () +calls, the caller was\[em]and is now still\[em]above its +.B RLIMIT_NPROC +resource limit (see +.BR setrlimit (2)). +For a more detailed explanation of this error, see NOTES. +.TP +.B EFAULT +.I pathname +or one of the pointers in the vectors +.I argv +or +.I envp +points outside your accessible address space. +.TP +.B EINVAL +An ELF executable had more than one PT_INTERP segment (i.e., tried to +name more than one interpreter). +.TP +.B EIO +An I/O error occurred. +.TP +.B EISDIR +An ELF interpreter was a directory. +.TP +.B ELIBBAD +An ELF interpreter was not in a recognized format. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.I pathname +or the name of a script or ELF interpreter. +.TP +.B ELOOP +The maximum recursion limit was reached during recursive script +interpretation (see "Interpreter scripts", above). +Before Linux 3.8, +.\" commit d740269867021faf4ce38a449353d2b986c34a67 +the error produced for this case was +.BR ENOEXEC . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +The file +.I pathname +or a script or ELF interpreter does not exist. +.TP +.B ENOEXEC +An executable is not in a recognized format, is for the wrong +architecture, or has some other format error that means it cannot be +executed. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix of +.I pathname +or a script or ELF interpreter is not a directory. +.TP +.B EPERM +The filesystem is mounted +.IR nosuid , +the user is not the superuser, +and the file has the set-user-ID or set-group-ID bit set. +.TP +.B EPERM +The process is being traced, the user is not the superuser and the +file has the set-user-ID or set-group-ID bit set. +.TP +.B EPERM +A "capability-dumb" applications would not obtain the full set of +permitted capabilities granted by the executable file. +See +.BR capabilities (7). +.TP +.B ETXTBSY +The specified executable was open for writing by one or more processes. +.SH VERSIONS +POSIX does not document the #! behavior, but it exists +(with some variations) on other UNIX systems. +.P +On Linux, +.I argv +and +.I envp +can be specified as NULL. +In both cases, this has the same effect as specifying the argument +as a pointer to a list containing a single null pointer. +.B "Do not take advantage of this nonstandard and nonportable misfeature!" +On many other UNIX systems, specifying +.I argv +as NULL will result in an error +.RB ( EFAULT ). +.I Some +other UNIX systems treat the +.I envp==NULL +case the same as Linux. +.\" e.g., EFAULT on Solaris 8 and FreeBSD 6.1; but +.\" HP-UX 11 is like Linux -- mtk, Apr 2007 +.\" Bug filed 30 Apr 2007: http://bugzilla.kernel.org/show_bug.cgi?id=8408 +.\" Bug rejected (because fix would constitute an ABI change). +.\" +.P +POSIX.1 says that values returned by +.BR sysconf (3) +should be invariant over the lifetime of a process. +However, since Linux 2.6.23, if the +.B RLIMIT_STACK +resource limit changes, then the value reported by +.B _SC_ARG_MAX +will also change, +to reflect the fact that the limit on space for holding +command-line arguments and environment variables has changed. +.\" +.SS Interpreter scripts +The kernel imposes a maximum length on the text that follows the +"#!" characters at the start of a script; +characters beyond the limit are ignored. +Before Linux 5.1, the limit is 127 characters. +Since Linux 5.1, +.\" commit 6eb3c3d0a52dca337e327ae8868ca1f44a712e02 +the limit is 255 characters. +.P +The semantics of the +.I optional-arg +argument of an interpreter script vary across implementations. +On Linux, the entire string following the +.I interpreter +name is passed as a single argument to the interpreter, +and this string can include white space. +However, behavior differs on some other systems. +Some systems +.\" e.g., Solaris 8 +use the first white space to terminate +.IR optional-arg . +On some systems, +.\" e.g., FreeBSD before 6.0, but not FreeBSD 6.0 onward +an interpreter script can have multiple arguments, +and white spaces in +.I optional-arg +are used to delimit the arguments. +.P +Linux (like most other modern UNIX systems) +ignores the set-user-ID and set-group-ID bits on scripts. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.\" SVr4 documents additional error +.\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not +.\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, +.\" EISDIR or ELIBBAD error conditions. +.P +With UNIX\ V6, the argument list of an +.BR exec () +call was ended by 0, +while the argument list of +.I main +was ended by \-1. +Thus, this argument list was not directly usable in a further +.BR exec () +call. +Since UNIX\ V7, both are NULL. +.SH NOTES +One sometimes sees +.BR execve () +(and the related functions described in +.BR exec (3)) +described as "executing a +.I new +process" (or similar). +This is a highly misleading description: +there is no new process; +many attributes of the calling process remain unchanged +(in particular, its PID). +All that +.BR execve () +does is arrange for an existing process (the calling process) +to execute a new program. +.P +Set-user-ID and set-group-ID processes can not be +.BR ptrace (2)d. +.P +The result of mounting a filesystem +.I nosuid +varies across Linux kernel versions: +some will refuse execution of set-user-ID and set-group-ID +executables when this would +give the user powers they did not have already (and return +.BR EPERM ), +some will just ignore the set-user-ID and set-group-ID bits and +.BR exec () +successfully. +.P +In most cases where +.BR execve () +fails, control returns to the original executable image, +and the caller of +.BR execve () +can then handle the error. +However, in (rare) cases (typically caused by resource exhaustion), +failure may occur past the point of no return: +the original executable image has been torn down, +but the new image could not be completely built. +In such cases, the kernel kills the process with a +.\" commit 19d860a140beac48a1377f179e693abe86a9dac9 +.B SIGSEGV +.RB ( SIGKILL +until Linux 3.17) +signal. +.SS execve() and EAGAIN +A more detailed explanation of the +.B EAGAIN +error that can occur (since Linux 3.1) when calling +.BR execve () +is as follows. +.P +The +.B EAGAIN +error can occur when a +.I preceding +call to +.BR setuid (2), +.BR setreuid (2), +or +.BR setresuid (2) +caused the real user ID of the process to change, +and that change caused the process to exceed its +.B RLIMIT_NPROC +resource limit (i.e., the number of processes belonging +to the new real UID exceeds the resource limit). +From Linux 2.6.0 to Linux 3.0, this caused the +.BR set*uid () +call to fail. +(Before Linux 2.6, +.\" commit 909cc4ae86f3380152a18e2a3c44523893ee11c4 +the resource limit was not imposed on processes that +changed their user IDs.) +.P +Since Linux 3.1, the scenario just described no longer causes the +.BR set*uid () +call to fail, +because it too often led to security holes where buggy applications +didn't check the return status and assumed +that\[em]if the caller had root privileges\[em]the call would always succeed. +Instead, the +.BR set*uid () +calls now successfully change the real UID, +but the kernel sets an internal flag, named +.BR PF_NPROC_EXCEEDED , +to note that the +.B RLIMIT_NPROC +resource limit has been exceeded. +If the +.B PF_NPROC_EXCEEDED +flag is set and the resource limit is still +exceeded at the time of a subsequent +.BR execve () +call, that call fails with the error +.BR EAGAIN . +This kernel logic ensures that the +.B RLIMIT_NPROC +resource limit is still enforced for the +common privileged daemon workflow\[em]namely, +.BR fork (2) ++ +.BR set*uid () ++ +.BR execve (). +.P +If the resource limit was not still exceeded at the time of the +.BR execve () +call +(because other processes belonging to this real UID terminated between the +.BR set*uid () +call and the +.BR execve () +call), then the +.BR execve () +call succeeds and the kernel clears the +.B PF_NPROC_EXCEEDED +process flag. +The flag is also cleared if a subsequent call to +.BR fork (2) +by this process succeeds. +.\" +.\" .SH BUGS +.\" Some Linux versions have failed to check permissions on ELF +.\" interpreters. This is a security hole, because it allows users to +.\" open any file, such as a rewinding tape device, for reading. Some +.\" Linux versions have also had other security holes in +.\" .BR execve () +.\" that could be exploited for denial of service by a suitably crafted +.\" ELF binary. There are no known problems with Linux 2.0.34 or Linux 2.2.15. +.SH EXAMPLES +The following program is designed to be execed by the second program below. +It just echoes its command-line arguments, one per line. +.P +.in +4n +.\" SRC BEGIN (myecho.c) +.EX +/* myecho.c */ +\& +#include +#include +\& +int +main(int argc, char *argv[]) +{ + for (size_t j = 0; j < argc; j++) + printf("argv[%zu]: %s\en", j, argv[j]); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.P +This program can be used to exec the program named in its command-line +argument: +.P +.in +4n +.\" SRC BEGIN (execve.c) +.EX +/* execve.c */ +\& +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + static char *newargv[] = { NULL, "hello", "world", NULL }; + static char *newenviron[] = { NULL }; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + newargv[0] = argv[1]; +\& + execve(argv[1], newargv, newenviron); + perror("execve"); /* execve() returns only on error */ + exit(EXIT_FAILURE); +} +.EE +.\" SRC END +.in +.P +We can use the second program to exec the first as follows: +.P +.in +4n +.EX +.RB "$" " cc myecho.c \-o myecho" +.RB "$" " cc execve.c \-o execve" +.RB "$" " ./execve ./myecho" +argv[0]: ./myecho +argv[1]: hello +argv[2]: world +.EE +.in +.P +We can also use these programs to demonstrate the use of a script +interpreter. +To do this we create a script whose "interpreter" is our +.I myecho +program: +.P +.in +4n +.EX +.RB "$" " cat > script" +.B #!./myecho script\-arg +.B \[ha]D +.RB "$" " chmod +x script" +.EE +.in +.P +We can then use our program to exec the script: +.P +.in +4n +.EX +.RB "$" " ./execve ./script" +argv[0]: ./myecho +argv[1]: script\-arg +argv[2]: ./script +argv[3]: hello +argv[4]: world +.EE +.in +.SH SEE ALSO +.BR chmod (2), +.BR execveat (2), +.BR fork (2), +.BR get_robust_list (2), +.BR ptrace (2), +.BR exec (3), +.BR fexecve (3), +.BR getauxval (3), +.BR getopt (3), +.BR system (3), +.BR capabilities (7), +.BR credentials (7), +.BR environ (7), +.BR path_resolution (7), +.BR ld.so (8) diff --git a/man/man2/execveat.2 b/man/man2/execveat.2 new file mode 100644 index 0000000..279a824 --- /dev/null +++ b/man/man2/execveat.2 @@ -0,0 +1,220 @@ +.\" Copyright (c) 2014 Google, Inc., written by David Drysdale +.\" and Copyright (c) 2015, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH execveat 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +execveat \- execute program relative to a directory file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " AT_* " constants */" +.B #include +.P +.BI "int execveat(int " dirfd ", const char *" pathname , +.BI " char *const _Nullable " argv [], +.BI " char *const _Nullable " envp [], +.BI " int " flags ); +.fi +.SH DESCRIPTION +.\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874 +The +.BR execveat () +system call executes the program referred to by the combination of +.I dirfd +and +.IR pathname . +It operates in exactly the same way as +.BR execve (2), +except for the differences described in this manual page. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR execve (2) +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR execve (2)). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +If +.I pathname +is an empty string and the +.B AT_EMPTY_PATH +flag is specified, then the file descriptor +.I dirfd +specifies the file to be executed (i.e., +.I dirfd +refers to an executable file, rather than a directory). +.P +The +.I flags +argument is a bit mask that can include zero or more of the following flags: +.TP +.B AT_EMPTY_PATH +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +.TP +.B AT_SYMLINK_NOFOLLOW +If the file identified by +.I dirfd +and a non-NULL +.I pathname +is a symbolic link, then the call fails with the error +.BR ELOOP . +.SH RETURN VALUE +On success, +.BR execveat () +does not return. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +The same errors that occur for +.BR execve (2) +can also occur for +.BR execveat (). +The following additional errors can occur for +.BR execveat (): +.TP +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B ELOOP +.I flags +includes +.B AT_SYMLINK_NOFOLLOW +and the file identified by +.I dirfd +and a non-NULL +.I pathname +is a symbolic link. +.TP +.B ENOENT +The program identified by +.I dirfd +and +.I pathname +requires the use of an interpreter program +(such as a script starting with "#!"), but the file descriptor +.I dirfd +was opened with the +.B O_CLOEXEC +flag, with the result that +the program file is inaccessible to the launched interpreter. +See BUGS. +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.19, +glibc 2.34. +.SH NOTES +In addition to the reasons explained in +.BR openat (2), +the +.BR execveat () +system call is also needed to allow +.BR fexecve (3) +to be implemented on systems that do not have the +.I /proc +filesystem mounted. +.P +When asked to execute a script file, the +.I argv[0] +that is passed to the script interpreter is a string of the form +.I /dev/fd/N +or +.IR /dev/fd/N/P , +where +.I N +is the number of the file descriptor passed via the +.I dirfd +argument. +A string of the first form occurs when +.B AT_EMPTY_PATH +is employed. +A string of the second form occurs when the script is specified via both +.I dirfd +and +.IR pathname ; +in this case, +.I P +is the value given in +.IR pathname . +.P +For the same reasons described in +.BR fexecve (3), +the natural idiom when using +.BR execveat () +is to set the close-on-exec flag on +.IR dirfd . +(But see BUGS.) +.SH BUGS +The +.B ENOENT +error described above means that it is not possible to set the +close-on-exec flag on the file descriptor given to a call of the form: +.P +.in +4n +.EX +execveat(fd, "", argv, envp, AT_EMPTY_PATH); +.EE +.in +.P +However, the inability to set the close-on-exec flag means that a file +descriptor referring to the script leaks through to the script itself. +As well as wasting a file descriptor, +this leakage can lead to file-descriptor exhaustion in scenarios +where scripts recursively employ +.BR execveat (). +.\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML +.\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229): +.\" +.\" Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\" for execveat(2 +.\" Date: Mon, 24 Nov 2014 11:53:59 +0000 +.SH SEE ALSO +.BR execve (2), +.BR openat (2), +.BR fexecve (3) diff --git a/man/man2/exit.2 b/man/man2/exit.2 new file mode 100644 index 0000000..9f9d2e7 --- /dev/null +++ b/man/man2/exit.2 @@ -0,0 +1 @@ +.so man2/_exit.2 diff --git a/man/man2/exit_group.2 b/man/man2/exit_group.2 new file mode 100644 index 0000000..32e0782 --- /dev/null +++ b/man/man2/exit_group.2 @@ -0,0 +1,38 @@ +.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH exit_group 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +exit_group \- exit all threads in a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "[[noreturn]] void syscall(SYS_exit_group, int " status ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR exit_group (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +This system call terminates all threads +in the calling process's thread group. +.SH RETURN VALUE +This system call does not return. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5.35. +.SH NOTES +Since glibc 2.3, this is the system call invoked when the +.BR _exit (2) +wrapper function is called. +.SH SEE ALSO +.BR _exit (2) diff --git a/man/man2/faccessat.2 b/man/man2/faccessat.2 new file mode 100644 index 0000000..9d4f76e --- /dev/null +++ b/man/man2/faccessat.2 @@ -0,0 +1 @@ +.so man2/access.2 diff --git a/man/man2/faccessat2.2 b/man/man2/faccessat2.2 new file mode 100644 index 0000000..9d4f76e --- /dev/null +++ b/man/man2/faccessat2.2 @@ -0,0 +1 @@ +.so man2/access.2 diff --git a/man/man2/fadvise64.2 b/man/man2/fadvise64.2 new file mode 100644 index 0000000..53f54a1 --- /dev/null +++ b/man/man2/fadvise64.2 @@ -0,0 +1 @@ +.so man2/posix_fadvise.2 diff --git a/man/man2/fadvise64_64.2 b/man/man2/fadvise64_64.2 new file mode 100644 index 0000000..53f54a1 --- /dev/null +++ b/man/man2/fadvise64_64.2 @@ -0,0 +1 @@ +.so man2/posix_fadvise.2 diff --git a/man/man2/fallocate.2 b/man/man2/fallocate.2 new file mode 100644 index 0000000..1d50425 --- /dev/null +++ b/man/man2/fallocate.2 @@ -0,0 +1,481 @@ +.\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved +.\" Written by Dave Chinner +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE +.\" 2011-09-19: Substantial restructuring of the page +.\" +.TH fallocate 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fallocate \- manipulate file space +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int fallocate(int " fd ", int " mode ", off_t " offset \ +", off_t " len ");" +.fi +.SH DESCRIPTION +This is a nonportable, Linux-specific system call. +For the portable, POSIX.1-specified method of ensuring that space +is allocated for a file, see +.BR posix_fallocate (3). +.P +.BR fallocate () +allows the caller to directly manipulate the allocated disk space +for the file referred to by +.I fd +for the byte range starting at +.I offset +and continuing for +.I len +bytes. +.P +The +.I mode +argument determines the operation to be performed on the given range. +Details of the supported operations are given in the subsections below. +.SS Allocating disk space +The default operation (i.e., +.I mode +is zero) of +.BR fallocate () +allocates the disk space within the range specified by +.I offset +and +.IR len . +The file size (as reported by +.BR stat (2)) +will be changed if +.IR offset + len +is greater than the file size. +Any subregion within the range specified by +.I offset +and +.I len +that did not contain data before the call will be initialized to zero. +This default behavior closely resembles the behavior of the +.BR posix_fallocate (3) +library function, +and is intended as a method of optimally implementing that function. +.P +After a successful call, subsequent writes into the range specified by +.I offset +and +.I len +are guaranteed not to fail because of lack of disk space. +.P +If the +.B FALLOC_FL_KEEP_SIZE +flag is specified in +.IR mode , +the behavior of the call is similar, +but the file size will not be changed even if +.IR offset + len +is greater than the file size. +Preallocating zeroed blocks beyond the end of the file in this manner +is useful for optimizing append workloads. +.P +If the +.B FALLOC_FL_UNSHARE_RANGE +flag is specified in +.IR mode , +shared file data extents will be made private to the file to guarantee +that a subsequent write will not fail due to lack of space. +Typically, this will be done by performing a copy-on-write operation on +all shared data in the file. +This flag may not be supported by all filesystems. +.P +Because allocation is done in block size chunks, +.BR fallocate () +may allocate a larger range of disk space than was specified. +.SS Deallocating file space +Specifying the +.B FALLOC_FL_PUNCH_HOLE +flag (available since Linux 2.6.38) in +.I mode +deallocates space (i.e., creates a hole) +in the byte range starting at +.I offset +and continuing for +.I len +bytes. +Within the specified range, partial filesystem blocks are zeroed, +and whole filesystem blocks are removed from the file. +After a successful call, +subsequent reads from this range will return zeros. +.P +The +.B FALLOC_FL_PUNCH_HOLE +flag must be ORed with +.B FALLOC_FL_KEEP_SIZE +in +.IR mode ; +in other words, even when punching off the end of the file, the file size +(as reported by +.BR stat (2)) +does not change. +.P +Not all filesystems support +.BR FALLOC_FL_PUNCH_HOLE ; +if a filesystem doesn't support the operation, an error is returned. +The operation is supported on at least the following filesystems: +.IP \[bu] 3 +XFS (since Linux 2.6.38) +.IP \[bu] +ext4 (since Linux 3.0) +.\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622 +.IP \[bu] +Btrfs (since Linux 3.7) +.IP \[bu] +.BR tmpfs (5) +(since Linux 3.5) +.\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe +.IP \[bu] +.BR gfs2 (5) +(since Linux 4.16) +.\" commit 4e56a6411fbce6f859566e17298114c2434391a4 +.SS Collapsing file space +.\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841 +Specifying the +.B FALLOC_FL_COLLAPSE_RANGE +flag (available since Linux 3.15) in +.I mode +removes a byte range from a file, without leaving a hole. +The byte range to be collapsed starts at +.I offset +and continues for +.I len +bytes. +At the completion of the operation, +the contents of the file starting at the location +.I offset+len +will be appended at the location +.IR offset , +and the file will be +.I len +bytes smaller. +.P +A filesystem may place limitations on the granularity of the operation, +in order to ensure efficient implementation. +Typically, +.I offset +and +.I len +must be a multiple of the filesystem logical block size, +which varies according to the filesystem type and configuration. +If a filesystem has such a requirement, +.BR fallocate () +fails with the error +.B EINVAL +if this requirement is violated. +.P +If the region specified by +.I offset +plus +.I len +reaches or passes the end of file, an error is returned; +instead, use +.BR ftruncate (2) +to truncate a file. +.P +No other flags may be specified in +.I mode +in conjunction with +.BR FALLOC_FL_COLLAPSE_RANGE . +.P +As at Linux 3.15, +.B FALLOC_FL_COLLAPSE_RANGE +is supported by +ext4 (only for extent-based files) +.\" commit 9eb79482a97152930b113b51dff530aba9e28c8e +and XFS. +.\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d +.SS Zeroing file space +Specifying the +.B FALLOC_FL_ZERO_RANGE +flag (available since Linux 3.15) +.\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642 +in +.I mode +zeros space in the byte range starting at +.I offset +and continuing for +.I len +bytes. +Within the specified range, blocks are preallocated for the regions +that span the holes in the file. +After a successful call, subsequent +reads from this range will return zeros. +.P +Zeroing is done within the filesystem preferably by converting the range into +unwritten extents. +This approach means that the specified range will not be physically zeroed +out on the device (except for partial blocks at the either end of the range), +and I/O is (otherwise) required only to update metadata. +.P +If the +.B FALLOC_FL_KEEP_SIZE +flag is additionally specified in +.IR mode , +the behavior of the call is similar, +but the file size will not be changed even if +.IR offset + len +is greater than the file size. +This behavior is the same as when preallocating space with +.B FALLOC_FL_KEEP_SIZE +specified. +.P +Not all filesystems support +.BR FALLOC_FL_ZERO_RANGE ; +if a filesystem doesn't support the operation, an error is returned. +The operation is supported on at least the following filesystems: +.IP \[bu] 3 +XFS (since Linux 3.15) +.\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa +.IP \[bu] +ext4, for extent-based files (since Linux 3.15) +.\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0 +.IP \[bu] +SMB3 (since Linux 3.17) +.\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556 +.IP \[bu] +Btrfs (since Linux 4.16) +.\" commit f27451f229966874a8793995b8e6b74326d125df +.SS Increasing file space +Specifying the +.B FALLOC_FL_INSERT_RANGE +flag +(available since Linux 4.1) +.\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d +in +.I mode +increases the file space by inserting a hole within the file size without +overwriting any existing data. +The hole will start at +.I offset +and continue for +.I len +bytes. +When inserting the hole inside file, the contents of the file starting at +.I offset +will be shifted upward (i.e., to a higher file offset) by +.I len +bytes. +Inserting a hole inside a file increases the file size by +.I len +bytes. +.P +This mode has the same limitations as +.B FALLOC_FL_COLLAPSE_RANGE +regarding the granularity of the operation. +If the granularity requirements are not met, +.BR fallocate () +fails with the error +.BR EINVAL . +If the +.I offset +is equal to or greater than the end of file, an error is returned. +For such operations (i.e., inserting a hole at the end of file), +.BR ftruncate (2) +should be used. +.P +No other flags may be specified in +.I mode +in conjunction with +.BR FALLOC_FL_INSERT_RANGE . +.P +.B FALLOC_FL_INSERT_RANGE +requires filesystem support. +Filesystems that support this operation include +XFS (since Linux 4.1) +.\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b +and ext4 (since Linux 4.2). +.\" commit 331573febb6a224bc50322e3670da326cb7f4cfc +.\" f2fs also has support since Linux 4.2 +.\" commit f62185d0e283e9d311e3ac1020f159d95f0aab39 +.SH RETURN VALUE +On success, +.BR fallocate () +returns zero. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor, or is not opened for writing. +.TP +.B EFBIG +.IR offset + len +exceeds the maximum file size. +.TP +.B EFBIG +.I mode +is +.BR FALLOC_FL_INSERT_RANGE , +and the current file size+\fIlen\fP exceeds the maximum file size. +.TP +.B EINTR +A signal was caught during execution; see +.BR signal (7). +.TP +.B EINVAL +.I offset +was less than 0, or +.I len +.\" FIXME . (raise a kernel bug) Probably the len==0 case should be +.\" a no-op, rather than an error. That would be consistent with +.\" similar APIs for the len==0 case. +.\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition" +.\" 21 Sep 2012 +.\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526 +was less than or equal to 0. +.TP +.B EINVAL +.I mode +is +.B FALLOC_FL_COLLAPSE_RANGE +and the range specified by +.I offset +plus +.I len +reaches or passes the end of the file. +.TP +.B EINVAL +.I mode +is +.B FALLOC_FL_INSERT_RANGE +and the range specified by +.I offset +reaches or passes the end of the file. +.TP +.B EINVAL +.I mode +is +.B FALLOC_FL_COLLAPSE_RANGE +or +.BR FALLOC_FL_INSERT_RANGE , +but either +.I offset +or +.I len +is not a multiple of the filesystem block size. +.TP +.B EINVAL +.I mode +contains one of +.B FALLOC_FL_COLLAPSE_RANGE +or +.B FALLOC_FL_INSERT_RANGE +and also other flags; +no other flags are permitted with +.B FALLOC_FL_COLLAPSE_RANGE +or +.BR FALLOC_FL_INSERT_RANGE . +.TP +.B EINVAL +.I mode +is +.BR FALLOC_FL_COLLAPSE_RANGE , +.BR FALLOC_FL_ZERO_RANGE , +or +.BR FALLOC_FL_INSERT_RANGE , +but the file referred to by +.I fd +is not a regular file. +.\" There was an inconsistency in Linux 3.15-rc1, that should be resolved so that all +.\" filesystems use this error for this case. (Tytso says ex4 will change.) +.\" http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521 +.\" From: Michael Kerrisk (man-pages +.\" Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate +.\" Newsgroups: gmane.linux.man, gmane.linux.file-systems +.\" Date: 2014-04-17 13:40:05 GMT +.TP +.B EIO +An I/O error occurred while reading from or writing to a filesystem. +.TP +.B ENODEV +.I fd +does not refer to a regular file or a directory. +(If +.I fd +is a pipe or FIFO, a different error results.) +.TP +.B ENOSPC +There is not enough space left on the device containing the file +referred to by +.IR fd . +.TP +.B ENOSYS +This kernel does not implement +.BR fallocate (). +.TP +.B EOPNOTSUPP +The filesystem containing the file referred to by +.I fd +does not support this operation; +or the +.I mode +is not supported by the filesystem containing the file referred to by +.IR fd . +.TP +.B EPERM +The file referred to by +.I fd +is marked immutable (see +.BR chattr (1)). +.TP +.B EPERM +.I mode +specifies +.BR FALLOC_FL_PUNCH_HOLE , +.BR FALLOC_FL_COLLAPSE_RANGE , +or +.B FALLOC_FL_INSERT_RANGE +and +the file referred to by +.I fd +is marked append-only +(see +.BR chattr (1)). +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B ESPIPE +.I fd +refers to a pipe or FIFO. +.TP +.B ETXTBSY +.I mode +specifies +.B FALLOC_FL_COLLAPSE_RANGE +or +.BR FALLOC_FL_INSERT_RANGE , +but the file referred to by +.I fd +is currently being executed. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR fallocate () +Linux 2.6.23, +glibc 2.10. +.TP +.B FALLOC_FL_* +glibc 2.18. +.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964 +.SH SEE ALSO +.BR fallocate (1), +.BR ftruncate (2), +.BR posix_fadvise (3), +.BR posix_fallocate (3) diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2 new file mode 100644 index 0000000..19b3fe3 --- /dev/null +++ b/man/man2/fanotify_init.2 @@ -0,0 +1,542 @@ +.\" Copyright (C) 2013, Heinrich Schuchardt +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH fanotify_init 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fanotify_init \- create and initialize fanotify group +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " O_* " constants */" +.B #include +.P +.BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags ); +.fi +.SH DESCRIPTION +For an overview of the fanotify API, see +.BR fanotify (7). +.P +.BR fanotify_init () +initializes a new fanotify group and returns a file descriptor for the event +queue associated with the group. +.P +The file descriptor is used in calls to +.BR fanotify_mark (2) +to specify the files, directories, mounts, or filesystems for which fanotify +events shall be created. +These events are received by reading from the file descriptor. +Some events are only informative, indicating that a file has been accessed. +Other events can be used to determine whether +another application is permitted to access a file or directory. +Permission to access filesystem objects is granted by writing to the file +descriptor. +.P +Multiple programs may be using the fanotify interface at the same time to +monitor the same files. +.P +The number of fanotify groups per user is limited. +See +.BR fanotify (7) +for details about this limit. +.P +The +.I flags +argument contains a multi-bit field defining the notification class of the +listening application and further single bit fields specifying the behavior +of the file descriptor. +.P +If multiple listeners for permission events exist, +the notification class is used to establish the sequence +in which the listeners receive the events. +.P +Only one of the following notification classes may be specified in +.IR flags : +.TP +.B FAN_CLASS_PRE_CONTENT +This value allows the receipt of events notifying that a file has been +accessed and events for permission decisions if a file may be accessed. +It is intended for event listeners that need to access files before they +contain their final data. +This notification class might be used by hierarchical storage managers, +for example. +Use of this flag requires the +.B CAP_SYS_ADMIN +capability. +.TP +.B FAN_CLASS_CONTENT +This value allows the receipt of events notifying that a file has been +accessed and events for permission decisions if a file may be accessed. +It is intended for event listeners that need to access files when they +already contain their final content. +This notification class might be used by malware detection programs, for +example. +Use of this flag requires the +.B CAP_SYS_ADMIN +capability. +.TP +.B FAN_CLASS_NOTIF +This is the default value. +It does not need to be specified. +This value only allows the receipt of events notifying that a file has been +accessed. +Permission decisions before the file is accessed are not possible. +.P +Listeners with different notification classes will receive events in the +order +.BR FAN_CLASS_PRE_CONTENT , +.BR FAN_CLASS_CONTENT , +.BR FAN_CLASS_NOTIF . +The order of notification for listeners in the same notification class +is undefined. +.P +The following bits can additionally be set in +.IR flags : +.TP +.B FAN_CLOEXEC +Set the close-on-exec flag +.RB ( FD_CLOEXEC ) +on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2). +.TP +.B FAN_NONBLOCK +Enable the nonblocking flag +.RB ( O_NONBLOCK ) +for the file descriptor. +Reading from the file descriptor will not block. +Instead, if no data is available, +.BR read (2) +fails with the error +.BR EAGAIN . +.TP +.B FAN_UNLIMITED_QUEUE +Remove the limit on the number of events in the event queue. +See +.BR fanotify (7) +for details about this limit. +Use of this flag requires the +.B CAP_SYS_ADMIN +capability. +.TP +.B FAN_UNLIMITED_MARKS +Remove the limit on the number of fanotify marks per user. +See +.BR fanotify (7) +for details about this limit. +Use of this flag requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR FAN_REPORT_TID " (since Linux 4.20)" +.\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29 +Report thread ID (TID) instead of process ID (PID) +in the +.I pid +field of the +.I "struct fanotify_event_metadata" +supplied to +.BR read (2) +(see +.BR fanotify (7)). +Use of this flag requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR FAN_ENABLE_AUDIT " (since Linux 4.15)" +.\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269 +Enable generation of audit log records about access mediation performed by +permission events. +The permission event response has to be marked with the +.B FAN_AUDIT +flag for an audit log record to be generated. +Use of this flag requires the +.B CAP_AUDIT_WRITE +capability. +.TP +.BR FAN_REPORT_FID " (since Linux 5.1)" +.\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360 +This value allows the receipt of events which contain additional information +about the underlying filesystem object correlated to an event. +An additional record of type +.B FAN_EVENT_INFO_TYPE_FID +encapsulates the information about the object and is included alongside the +generic event metadata structure. +The file descriptor that is used to represent the object correlated to an +event is instead substituted with a file handle. +It is intended for applications that may find the use of a file handle to +identify an object more suitable than a file descriptor. +Additionally, it may be used for applications monitoring a directory or a +filesystem that are interested in the directory entry modification events +.BR FAN_CREATE , +.BR FAN_DELETE , +.BR FAN_MOVE , +and +.BR FAN_RENAME , +or in events such as +.BR FAN_ATTRIB , +.BR FAN_DELETE_SELF , +and +.BR FAN_MOVE_SELF . +All the events above require an fanotify group that identifies filesystem +objects by file handles. +Note that without the flag +.BR FAN_REPORT_TARGET_FID , +for the directory entry modification events, +there is an information record that identifies the modified directory +and not the created/deleted/moved child object. +The use of +.B FAN_CLASS_CONTENT +or +.B FAN_CLASS_PRE_CONTENT +is not permitted with this flag and will result in the error +.BR EINVAL . +See +.BR fanotify (7) +for additional details. +.TP +.BR FAN_REPORT_DIR_FID " (since Linux 5.9)" +.\" commit 83b7a59896dd24015a34b7f00027f0ff3747972f +Events for fanotify groups initialized with this flag will contain +(see exceptions below) additional information about a directory object +correlated to an event. +An additional record of type +.B FAN_EVENT_INFO_TYPE_DFID +encapsulates the information about the directory object and is included +alongside the generic event metadata structure. +For events that occur on a non-directory object, the additional structure +includes a file handle that identifies the parent directory filesystem object. +Note that there is no guarantee that the directory filesystem object will be +found at the location described by the file handle information at the time +the event is received. +When combined with the flag +.BR FAN_REPORT_FID , +two records may be reported with events that occur on a non-directory object, +one to identify the non-directory object itself and one to identify the parent +directory object. +Note that in some cases, a filesystem object does not have a parent, +for example, when an event occurs on an unlinked but open file. +In that case, with the +.B FAN_REPORT_FID +flag, the event will be reported with only one record to identify the +non-directory object itself, because there is no directory associated with +the event. +Without the +.B FAN_REPORT_FID +flag, no event will be reported. +See +.BR fanotify (7) +for additional details. +.TP +.BR FAN_REPORT_NAME " (since Linux 5.9)" +.\" commit 929943b38daf817f2e6d303ea04401651fc3bc05 +Events for fanotify groups initialized with this flag will contain additional +information about the name of the directory entry correlated to an event. +This flag must be provided in conjunction with the flag +.BR FAN_REPORT_DIR_FID . +Providing this flag value without +.B FAN_REPORT_DIR_FID +will result in the error +.BR EINVAL . +This flag may be combined with the flag +.BR FAN_REPORT_FID . +An additional record of type +.BR FAN_EVENT_INFO_TYPE_DFID_NAME , +which encapsulates the information about the directory entry, is included +alongside the generic event metadata structure and substitutes the additional +information record of type +.BR FAN_EVENT_INFO_TYPE_DFID . +The additional record includes a file handle that identifies a directory +filesystem object followed by a name that identifies an entry in that +directory. +For the directory entry modification events +.BR FAN_CREATE , +.BR FAN_DELETE , +and +.BR FAN_MOVE , +the reported name is that of the created/deleted/moved directory entry. +The event +.B FAN_RENAME +may contain two information records. +One of type +.B FAN_EVENT_INFO_TYPE_OLD_DFID_NAME +identifying the old directory entry, +and another of type +.B FAN_EVENT_INFO_TYPE_NEW_DFID_NAME +identifying the new directory entry. +For other events that occur on a directory object, the reported file handle +is that of the directory object itself and the reported name is '.'. +For other events that occur on a non-directory object, the reported file handle +is that of the parent directory object and the reported name is the name of a +directory entry where the object was located at the time of the event. +The rationale behind this logic is that the reported directory file handle can +be passed to +.BR open_by_handle_at (2) +to get an open directory file descriptor and that file descriptor along with +the reported name can be used to call +.BR fstatat (2). +The same rule that applies to record type +.B FAN_EVENT_INFO_TYPE_DFID +also applies to record type +.BR FAN_EVENT_INFO_TYPE_DFID_NAME : +if a non-directory object has no parent, either the event will not be reported +or it will be reported without the directory entry information. +Note that there is no guarantee that the filesystem object will be found at the +location described by the directory entry information at the time the event is +received. +See +.BR fanotify (7) +for additional details. +.TP +.B FAN_REPORT_DFID_NAME +This is a synonym for +.RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ). +.TP +.BR FAN_REPORT_TARGET_FID " (since Linux 5.17)" +.\" commit d61fd650e9d206a71fda789f02a1ced4b19944c4 +Events for fanotify groups initialized with this flag +will contain additional information about the child +correlated with directory entry modification events. +This flag must be provided in conjunction with the flags +.BR FAN_REPORT_FID , +.B FAN_REPORT_DIR_FID +and +.BR FAN_REPORT_NAME . +or else the error +.B EINVAL +will be returned. +For the directory entry modification events +.BR FAN_CREATE , +.BR FAN_DELETE , +.BR FAN_MOVE , +and +.BR FAN_RENAME , +an additional record of type +.BR FAN_EVENT_INFO_TYPE_FID , +is reported in addition to the information records of type +.BR FAN_EVENT_INFO_TYPE_DFID , +.BR FAN_EVENT_INFO_TYPE_DFID_NAME , +.BR FAN_EVENT_INFO_TYPE_OLD_DFID_NAME , +and +.BR FAN_EVENT_INFO_TYPE_NEW_DFID_NAME . +The additional record includes a file handle +that identifies the filesystem child object +that the directory entry is referring to. +.TP +.B FAN_REPORT_DFID_NAME_TARGET +This is a synonym for +.RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ). +.TP +.BR FAN_REPORT_PIDFD " (since Linux 5.15)" +.\" commit af579beb666aefb17e9a335c12c788c92932baf1 +Events for fanotify groups initialized with this flag will contain +an additional information record alongside the generic +.I fanotify_event_metadata +structure. +This information record will be of type +.B FAN_EVENT_INFO_TYPE_PIDFD +and will contain a pidfd for the process that +was responsible for generating an event. +A pidfd returned in this information record object is +no different to the pidfd that is returned when calling +.BR pidfd_open (2). +Usage of this information record are for applications that +may be interested in reliably determining whether +the process responsible for generating an event +has been recycled or terminated. +The use of the +.B FAN_REPORT_TID +flag along with +.B FAN_REPORT_PIDFD +is currently not supported and +attempting to do so will result in the error +.B EINVAL +being returned. +This limitation is currently imposed by the pidfd API +as it currently only supports +the creation of pidfds for thread-group leaders. +Creating pidfds for non-thread-group leaders +may be supported at some point in the future, +so this restriction may eventually be lifted. +For more details on information records, +see +.BR fanotify (7). +.P +The +.I event_f_flags +argument +defines the file status flags that will be set on the open file descriptions +that are created for fanotify events. +For details of these flags, see the description of the +.I flags +values in +.BR open (2). +.I event_f_flags +includes a multi-bit field for the access mode. +This field can take the following values: +.TP +.B O_RDONLY +This value allows only read access. +.TP +.B O_WRONLY +This value allows only write access. +.TP +.B O_RDWR +This value allows read and write access. +.P +Additional bits can be set in +.IR event_f_flags . +The most useful values are: +.TP +.B O_LARGEFILE +Enable support for files exceeding 2\ GB. +Failing to set this flag will result in an +.B EOVERFLOW +error when trying to open a large file which is monitored by +an fanotify group on a 32-bit system. +.TP +.BR O_CLOEXEC " (since Linux 3.18)" +.\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 +Enable the close-on-exec flag for the file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.P +The following are also allowable: +.BR O_APPEND , +.BR O_DSYNC , +.BR O_NOATIME , +.BR O_NONBLOCK , +and +.BR O_SYNC . +Specifying any other flag in +.I event_f_flags +yields the error +.B EINVAL +(but see BUGS). +.SH RETURN VALUE +On success, +.BR fanotify_init () +returns a new file descriptor. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +An invalid value was passed in +.I flags +or +.IR event_f_flags . +.B FAN_ALL_INIT_FLAGS +(deprecated since Linux 4.20) +.\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4 +defines all allowable bits for +.IR flags . +.TP +.B EMFILE +The number of fanotify groups for this user exceeds the limit. +See +.BR fanotify (7) +for details about this limit. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENOMEM +The allocation of memory for the notification group failed. +.TP +.B ENOSYS +This kernel does not implement +.BR fanotify_init (). +The fanotify API is available only if the kernel was configured with +.BR CONFIG_FANOTIFY . +.TP +.B EPERM +The operation is not permitted because the caller lacks a required capability. +.SH VERSIONS +Prior to Linux 5.13, +.\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7 +calling +.BR fanotify_init () +required the +.B CAP_SYS_ADMIN +capability. +Since Linux 5.13, +.\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7 +users may call +.BR fanotify_init () +without the +.B CAP_SYS_ADMIN +capability to create and initialize +an fanotify group with limited functionality. +.TP +The limitations imposed on an event listener created by a user without the +.B CAP_SYS_ADMIN +capability are as follows: +.RS +.IP \[bu] 3 +The user cannot request for an unlimited event queue by using +.BR FAN_UNLIMITED_QUEUE . +.IP \[bu] +The user cannot request for an unlimited number of marks by using +.BR FAN_UNLIMITED_MARKS . +.IP \[bu] +The user cannot request to use either notification classes +.B FAN_CLASS_CONTENT +or +.BR FAN_CLASS_PRE_CONTENT . +This means that user cannot request permission events. +.IP \[bu] +The user is required to create a group that identifies filesystem objects by +file handles, for example, by providing the +.B FAN_REPORT_FID +flag. +.IP \[bu] +The user is limited to only mark inodes. +The ability to mark a mount or filesystem via +.BR fanotify_mark () +through the use of +.B FAN_MARK_MOUNT +or +.B FAN_MARK_FILESYSTEM +is not permitted. +.IP \[bu] +The event object in the event queue is limited in terms of the information +that is made available to the unprivileged user. +A user will also not receive the pid that generated the event, unless the +listening process itself generated the event. +.RE +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.37. +.\" was introduced in Linux 2.6.36 and enabled in Linux 2.6.37. +.SH BUGS +The following bug was present before Linux 3.18: +.IP \[bu] 3 +.\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 +The +.B O_CLOEXEC +is ignored when passed in +.IR event_f_flags . +.P +The following bug was present before Linux 3.14: +.IP \[bu] 3 +.\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580 +The +.I event_f_flags +argument is not checked for invalid flags. +Flags that are intended only for internal use, +such as +.BR FMODE_EXEC , +can be set, and will consequently be set for the file descriptors +returned when reading from the fanotify file descriptor. +.SH SEE ALSO +.BR fanotify_mark (2), +.BR fanotify (7) diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2 new file mode 100644 index 0000000..f88b1e5 --- /dev/null +++ b/man/man2/fanotify_mark.2 @@ -0,0 +1,850 @@ +.\" Copyright (C) 2013, Heinrich Schuchardt +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH fanotify_mark 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem +object +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags , +.BI " uint64_t " mask ", int " dirfd , +.BI " const char *_Nullable " pathname ); +.fi +.SH DESCRIPTION +For an overview of the fanotify API, see +.BR fanotify (7). +.P +.BR fanotify_mark () +adds, removes, or modifies an fanotify mark on a filesystem object. +The caller must have read permission on the filesystem object that +is to be marked. +.P +The +.I fanotify_fd +argument is a file descriptor returned by +.BR fanotify_init (2). +.P +.I flags +is a bit mask describing the modification to perform. +It must include exactly one of the following values: +.TP +.B FAN_MARK_ADD +The events in +.I mask +will be added to the mark mask (or to the ignore mask). +.I mask +must be nonempty or the error +.B EINVAL +will occur. +.TP +.B FAN_MARK_REMOVE +The events in argument +.I mask +will be removed from the mark mask (or from the ignore mask). +.I mask +must be nonempty or the error +.B EINVAL +will occur. +.TP +.B FAN_MARK_FLUSH +Remove either all marks for filesystems, all marks for mounts, or all +marks for directories and files from the fanotify group. +If +.I flags +contains +.BR FAN_MARK_MOUNT , +all marks for mounts are removed from the group. +If +.I flags +contains +.BR FAN_MARK_FILESYSTEM , +all marks for filesystems are removed from the group. +Otherwise, all marks for directories and files are removed. +No flag other than, and at most one of, the flags +.B FAN_MARK_MOUNT +or +.B FAN_MARK_FILESYSTEM +can be used in conjunction with +.BR FAN_MARK_FLUSH . +.I mask +is ignored. +.P +If none of the values above is specified, or more than one is specified, +the call fails with the error +.BR EINVAL . +.P +In addition, +zero or more of the following values may be ORed into +.IR flags : +.TP +.B FAN_MARK_DONT_FOLLOW +If +.I pathname +is a symbolic link, mark the link itself, rather than the file to which it +refers. +(By default, +.BR fanotify_mark () +dereferences +.I pathname +if it is a symbolic link.) +.TP +.B FAN_MARK_ONLYDIR +If the filesystem object to be marked is not a directory, the error +.B ENOTDIR +shall be raised. +.TP +.B FAN_MARK_MOUNT +Mark the mount specified by +.IR pathname . +If +.I pathname +is not itself a mount point, the mount containing +.I pathname +will be marked. +All directories, subdirectories, and the contained files of the mount +will be monitored. +The events which require that filesystem objects are identified by file handles, +such as +.BR FAN_CREATE , +.BR FAN_ATTRIB , +.BR FAN_MOVE , +and +.BR FAN_DELETE_SELF , +cannot be provided as a +.I mask +when +.I flags +contains +.BR FAN_MARK_MOUNT . +Attempting to do so will result in the error +.B EINVAL +being returned. +Use of this flag requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR FAN_MARK_FILESYSTEM " (since Linux 4.20)" +.\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2 +Mark the filesystem specified by +.IR pathname . +The filesystem containing +.I pathname +will be marked. +All the contained files and directories of the filesystem from any mount +point will be monitored. +Use of this flag requires the +.B CAP_SYS_ADMIN +capability. +.TP +.B FAN_MARK_IGNORED_MASK +The events in +.I mask +shall be added to or removed from the ignore mask. +Note that the flags +.BR FAN_ONDIR , +and +.B FAN_EVENT_ON_CHILD +have no effect when provided with this flag. +The effect of setting the flags +.BR FAN_ONDIR , +and +.B FAN_EVENT_ON_CHILD +in the mark mask +on the events that are set in the ignore mask +is undefined and depends on the Linux kernel version. +Specifically, prior to Linux 5.9, +.\" commit 497b0c5a7c0688c1b100a9c2e267337f677c198e +setting a mark mask on a file +and a mark with ignore mask on its parent directory +would not result in ignoring events on the file, +regardless of the +.B FAN_EVENT_ON_CHILD +flag in the parent directory's mark mask. +When the ignore mask is updated with the +.B FAN_MARK_IGNORED_MASK +flag +on a mark that was previously updated with the +.B FAN_MARK_IGNORE +flag, +the update fails with +.B EEXIST +error. +.TP +.BR FAN_MARK_IGNORE " (since Linux 6.0)" +.\" commit e252f2ed1c8c6c3884ab5dd34e003ed21f1fe6e0 +This flag has a similar effect as setting the +.B FAN_MARK_IGNORED_MASK +flag. +The events in +.I mask +shall be added to or removed from the ignore mask. +Unlike the +.B FAN_MARK_IGNORED_MASK +flag, +this flag also has the effect that the +.BR FAN_ONDIR , +and +.B FAN_EVENT_ON_CHILD +flags take effect on the ignore mask. +Specifically, unless the +.B FAN_ONDIR +flag is set with +.BR FAN_MARK_IGNORE , +events on directories will not be ignored. +If the flag +.B FAN_EVENT_ON_CHILD +is set with +.BR FAN_MARK_IGNORE , +events on children will be ignored. +For example, +a mark on a directory with combination of +a mask with +.B FAN_CREATE +event +and +.B FAN_ONDIR +flag +and an ignore mask with +.B FAN_CREATE +event +and without +.B FAN_ONDIR +flag, +will result in getting only +the events for creation of sub-directories. +When using the +.B FAN_MARK_IGNORE +flag to add to an ignore mask +of a mount, +filesystem, +or directory inode mark, +the +.B FAN_MARK_IGNORED_SURV_MODIFY +flag must be specified. +Failure to do so will results with +.B EINVAL +or +.B EISDIR +error. +.TP +.B FAN_MARK_IGNORED_SURV_MODIFY +The ignore mask shall survive modify events. +If this flag is not set, +the ignore mask is cleared when a modify event occurs +on the marked object. +Omitting this flag is typically used to suppress events +(e.g., +.BR FAN_OPEN ) +for a specific file, +until that specific file's content has been modified. +It is far less useful to suppress events +on an entire filesystem, +or mount, +or on all files inside a directory, +until some file's content has been modified. +For this reason, +the +.B FAN_MARK_IGNORE +flag requires the +.B FAN_MARK_IGNORED_SURV_MODIFY +flag on a mount, +filesystem, +or directory inode mark. +This flag cannot be removed from a mark once set. +When the ignore mask is updated without this flag +on a mark that was previously updated with the +.B FAN_MARK_IGNORE +and +.B FAN_MARK_IGNORED_SURV_MODIFY +flags, +the update fails with +.B EEXIST +error. +.TP +.B FAN_MARK_IGNORE_SURV +This is a synonym for +.RB ( FAN_MARK_IGNORE | FAN_MARK_IGNORED_SURV_MODIFY ). +.TP +.BR FAN_MARK_EVICTABLE " (since Linux 5.19)" +.\" commit 5f9d3bd520261fd7a850818c71809fd580e0f30c +When an inode mark is created with this flag, +the inode object will not be pinned to the inode cache, +therefore, +allowing the inode object to be evicted from the inode cache +when the memory pressure on the system is high. +The eviction of the inode object +results in the evictable mark also being lost. +When the mask of an evictable inode mark is updated +without using the +.B FAN_MARK_EVICATBLE +flag, +the marked inode is pinned to inode cache +and the mark is no longer evictable. +When the mask of a non-evictable inode mark is updated +with the +.B FAN_MARK_EVICTABLE +flag, +the inode mark remains non-evictable +and the update fails with +.B EEXIST +error. +Mounts and filesystems are not evictable objects, +therefore, +an attempt to create a mount mark or a filesystem mark +with the +.B FAN_MARK_EVICTABLE +flag, +will result in the error +.BR EINVAL . +For example, +inode marks can be used in combination with mount marks +to reduce the amount of events from noninteresting paths. +The event listener reads events, +checks if the path reported in the event is of interest, +and if it is not, +the listener sets a mark with an ignore mask on the directory. +Evictable inode marks allow using this method for a large number of directories +without the concern of pinning all inodes and exhausting the system's memory. +.P +.I mask +defines which events shall be listened for (or which shall be ignored). +It is a bit mask composed of the following values: +.TP +.B FAN_ACCESS +Create an event when a file or directory (but see BUGS) is accessed (read). +.TP +.B FAN_MODIFY +Create an event when a file is modified (write). +.TP +.B FAN_CLOSE_WRITE +Create an event when a writable file is closed. +.TP +.B FAN_CLOSE_NOWRITE +Create an event when a read-only file or directory is closed. +.TP +.B FAN_OPEN +Create an event when a file or directory is opened. +.TP +.BR FAN_OPEN_EXEC " (since Linux 5.0)" +.\" commit 9b076f1c0f4869b838a1b7aa0edb5664d47ec8aa +Create an event when a file is opened with the intent to be executed. +See NOTES for additional details. +.TP +.BR FAN_ATTRIB " (since Linux 5.1)" +.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 +Create an event when the metadata for a file or directory has changed. +An fanotify group that identifies filesystem objects by file handles +is required. +.TP +.BR FAN_CREATE " (since Linux 5.1)" +.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 +Create an event when a file or directory has been created in a marked +parent directory. +An fanotify group that identifies filesystem objects by file handles +is required. +.TP +.BR FAN_DELETE " (since Linux 5.1)" +.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 +Create an event when a file or directory has been deleted in a marked +parent directory. +An fanotify group that identifies filesystem objects by file handles +is required. +.TP +.BR FAN_DELETE_SELF " (since Linux 5.1)" +.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 +Create an event when a marked file or directory itself is deleted. +An fanotify group that identifies filesystem objects by file handles +is required. +.TP +.BR FAN_FS_ERROR " (since Linux 5.16)" +.\" commit 9709bd548f11a092d124698118013f66e1740f9b +Create an event when a filesystem error +leading to inconsistent filesystem metadata is detected. +An additional information record of type +.B FAN_EVENT_INFO_TYPE_ERROR +is returned for each event in the read buffer. +An fanotify group that identifies filesystem objects by file handles +is required. +.IP +Events of such type are dependent on support +from the underlying filesystem. +At the time of writing, +only the +.B ext4 +filesystem reports +.B FAN_FS_ERROR +events. +.IP +See +.BR fanotify (7) +for additional details. +.TP +.BR FAN_MOVED_FROM " (since Linux 5.1)" +.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 +Create an event when a file or directory has been moved from a marked +parent directory. +An fanotify group that identifies filesystem objects by file handles +is required. +.TP +.BR FAN_MOVED_TO " (since Linux 5.1)" +.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 +Create an event when a file or directory has been moved to a marked parent +directory. +An fanotify group that identifies filesystem objects by file handles +is required. +.TP +.BR FAN_RENAME " (since Linux 5.17)" +.\" commit 8cc3b1ccd930fe6971e1527f0c4f1bdc8cb56026 +This event contains the same information provided by events +.B FAN_MOVED_FROM +and +.BR FAN_MOVED_TO , +however is represented by a single event with up to two information records. +An fanotify group that identifies filesystem objects by file handles +is required. +If the filesystem object to be marked is not a directory, the error +.B ENOTDIR +shall be raised. +.TP +.BR FAN_MOVE_SELF " (since Linux 5.1)" +.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 +Create an event when a marked file or directory itself has been moved. +An fanotify group that identifies filesystem objects by file handles +is required. +.TP +.B FAN_OPEN_PERM +Create an event when a permission to open a file or directory is requested. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +or +.B FAN_CLASS_CONTENT +is required. +.TP +.BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)" +.\" commit 66917a3130f218dcef9eeab4fd11a71cd00cd7c9 +Create an event when a permission to open a file for execution is +requested. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +or +.B FAN_CLASS_CONTENT +is required. +See NOTES for additional details. +.TP +.B FAN_ACCESS_PERM +Create an event when a permission to read a file or directory is requested. +An fanotify file descriptor created with +.B FAN_CLASS_PRE_CONTENT +or +.B FAN_CLASS_CONTENT +is required. +.TP +.B FAN_ONDIR +Create events for directories\[em]for example, when +.BR opendir (3), +.BR readdir (3) +(but see BUGS), and +.BR closedir (3) +are called. +Without this flag, events are created only for files. +In the context of directory entry events, such as +.BR FAN_CREATE , +.BR FAN_DELETE , +.BR FAN_MOVED_FROM , +and +.BR FAN_MOVED_TO , +specifying the flag +.B FAN_ONDIR +is required in order to create events when subdirectory entries are +modified (i.e., +.BR mkdir (2)/ +.BR rmdir (2)). +.TP +.B FAN_EVENT_ON_CHILD +Events for the immediate children of marked directories shall be created. +The flag has no effect when marking mounts and filesystems. +Note that events are not generated for children of the subdirectories +of marked directories. +More specifically, the directory entry modification events +.BR FAN_CREATE , +.BR FAN_DELETE , +.BR FAN_MOVED_FROM , +and +.B FAN_MOVED_TO +are not generated for any entry modifications performed inside subdirectories +of marked directories. +Note that the events +.B FAN_DELETE_SELF +and +.B FAN_MOVE_SELF +are not generated for children of marked directories. +To monitor complete directory trees it is necessary to mark the relevant +mount or filesystem. +.P +The following composed values are defined: +.TP +.B FAN_CLOSE +A file is closed +.RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ). +.TP +.B FAN_MOVE +A file or directory has been moved +.RB ( FAN_MOVED_FROM | FAN_MOVED_TO ). +.P +The filesystem object to be marked is determined by the file descriptor +.I dirfd +and the pathname specified in +.IR pathname : +.IP \[bu] 3 +If +.I pathname +is NULL, +.I dirfd +defines the filesystem object to be marked. +.IP \[bu] +If +.I pathname +is NULL, and +.I dirfd +takes the special value +.BR AT_FDCWD , +the current working directory is to be marked. +.IP \[bu] +If +.I pathname +is absolute, it defines the filesystem object to be marked, and +.I dirfd +is ignored. +.IP \[bu] +If +.I pathname +is relative, and +.I dirfd +does not have the value +.BR AT_FDCWD , +then the filesystem object to be marked is determined by interpreting +.I pathname +relative the directory referred to by +.IR dirfd . +.IP \[bu] +If +.I pathname +is relative, and +.I dirfd +has the value +.BR AT_FDCWD , +then the filesystem object to be marked is determined by interpreting +.I pathname +relative to the current working directory. +(See +.BR openat (2) +for an explanation of why the +.I dirfd +argument is useful.) +.SH RETURN VALUE +On success, +.BR fanotify_mark () +returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +An invalid file descriptor was passed in +.IR fanotify_fd . +.TP +.B EBADF +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EEXIST +The filesystem object indicated by +.I dirfd +and +.I pathname +has a mark that was updated without the +.B FAN_MARK_EVICTABLE +flag, +and the user attempted to update the mark with +.B FAN_MARK_EVICTABLE +flag. +.TP +.B EEXIST +The filesystem object indicated by +.I dirfd +and +.I pathname +has a mark that was updated with the +.B FAN_MARK_IGNORE +flag, +and the user attempted to update the mark with +.B FAN_MARK_IGNORED_MASK +flag. +.TP +.B EEXIST +The filesystem object indicated by +.I dirfd +and +.I pathname +has a mark that was updated with the +.B FAN_MARK_IGNORE +and +.B FAN_MARK_IGNORED_SURV_MODIFY +flags, +and the user attempted to update the mark only with +.B FAN_MARK_IGNORE +flag. +.TP +.B EINVAL +An invalid value was passed in +.I flags +or +.IR mask , +or +.I fanotify_fd +was not an fanotify file descriptor. +.TP +.B EINVAL +The fanotify file descriptor was opened with +.B FAN_CLASS_NOTIF +or the fanotify group identifies filesystem objects by file handles +and mask contains a flag for permission events +.RB ( FAN_OPEN_PERM +or +.BR FAN_ACCESS_PERM ). +.TP +.B EINVAL +The group was initialized without +.B FAN_REPORT_FID +but one or more event types specified in the +.I mask +require it. +.TP +.B EINVAL +.I flags +contains +.BR FAN_MARK_IGNORE , +and either +.B FAN_MARK_MOUNT +or +.BR FAN_MARK_FILESYSTEM , +but does not contain +.BR FAN_MARK_IGNORED_SURV_MODIFY . +.TP +.B EISDIR +.I flags +contains +.BR FAN_MARK_IGNORE , +but does not contain +.BR FAN_MARK_IGNORED_SURV_MODIFY , +and +.I dirfd +and +.I pathname +specify a directory. +.TP +.B ENODEV +The filesystem object indicated by +.I dirfd +and +.I pathname +is not associated with a filesystem that supports +.I fsid +(e.g., +.BR fuse (4)). +.BR tmpfs (5) +did not support +.I fsid +prior to Linux 5.13. +.\" commit 59cda49ecf6c9a32fae4942420701b6e087204f6 +This error can be returned only with an fanotify group that identifies +filesystem objects by file handles. +.TP +.B ENOENT +The filesystem object indicated by +.I dirfd +and +.I pathname +does not exist. +This error also occurs when trying to remove a mark from an object +which is not marked. +.TP +.B ENOMEM +The necessary memory could not be allocated. +.TP +.B ENOSPC +The number of marks for this user exceeds the limit and the +.B FAN_UNLIMITED_MARKS +flag was not specified when the fanotify file descriptor was created with +.BR fanotify_init (2). +See +.BR fanotify (7) +for details about this limit. +.TP +.B ENOSYS +This kernel does not implement +.BR fanotify_mark (). +The fanotify API is available only if the kernel was configured with +.BR CONFIG_FANOTIFY . +.TP +.B ENOTDIR +.I flags +contains +.BR FAN_MARK_ONLYDIR , +and +.I dirfd +and +.I pathname +do not specify a directory. +.TP +.B ENOTDIR +.I mask +contains +.BR FAN_RENAME , +and +.I dirfd +and +.I pathname +do not specify a directory. +.TP +.B ENOTDIR +.I flags +contains +.BR FAN_MARK_IGNORE , +or the fanotify group was initialized with flag +.BR FAN_REPORT_TARGET_FID , +and +.I mask +contains directory entry modification events +(e.g., +.BR FAN_CREATE , +.BR FAN_DELETE ), +or directory event flags +(e.g., +.BR FAN_ONDIR , +.BR FAN_EVENT_ON_CHILD ), +and +.I dirfd +and +.I pathname +do not specify a directory. +.TP +.B EOPNOTSUPP +The object indicated by +.I pathname +is associated with a filesystem +that does not support the encoding of file handles. +This error can be returned only with an fanotify group that identifies +filesystem objects by file handles. +Calling +.BR name_to_handle_at (2) +with the flag +.BR AT_HANDLE_FID " (since Linux 6.5)" +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8 +can be used as a test +to check if a filesystem supports reporting events with file handles. +.TP +.B EPERM +The operation is not permitted because the caller lacks a required capability. +.TP +.B EXDEV +The filesystem object indicated by +.I pathname +resides within a filesystem subvolume (e.g., +.BR btrfs (5)) +which uses a different +.I fsid +than its root superblock. +This error can be returned only with an fanotify group that identifies +filesystem objects by file handles. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.37. +.\" was introduced in Linux 2.6.36 and enabled in Linux 2.6.37. +.SH NOTES +.SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM +When using either +.B FAN_OPEN_EXEC +or +.B FAN_OPEN_EXEC_PERM +within the +.IR mask , +events of these types will be returned only when the direct execution of a +program occurs. +More specifically, this means that events of these types will be generated +for files that are opened using +.BR execve (2), +.BR execveat (2), +or +.BR uselib (2). +Events of these types will not be raised in the situation where an +interpreter is passed (or reads) a file for interpretation. +.P +Additionally, if a mark has also been placed on the Linux dynamic +linker, a user should also expect to receive an event for it when +an ELF object has been successfully opened using +.BR execve (2) +or +.BR execveat (2). +.P +For example, if the following ELF binary were to be invoked and a +.B FAN_OPEN_EXEC +mark has been placed on /: +.P +.in +4n +.EX +$ /bin/echo foo +.EE +.in +.P +The listening application in this case would receive +.B FAN_OPEN_EXEC +events for both the ELF binary and interpreter, respectively: +.P +.in +4n +.EX +/bin/echo +/lib64/ld\-linux\-x86\-64.so.2 +.EE +.in +.SH BUGS +The following bugs were present in before Linux 3.16: +.IP \[bu] 3 +.\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563 +If +.I flags +contains +.BR FAN_MARK_FLUSH , +.IR dirfd , +and +.I pathname +must specify a valid filesystem object, even though this object is not used. +.IP \[bu] +.\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b +.BR readdir (2) +does not generate a +.B FAN_ACCESS +event. +.IP \[bu] +.\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406 +If +.BR fanotify_mark () +is called with +.BR FAN_MARK_FLUSH , +.I flags +is not checked for invalid values. +.SH SEE ALSO +.BR fanotify_init (2), +.BR fanotify (7) diff --git a/man/man2/fattach.2 b/man/man2/fattach.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/fattach.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/fchdir.2 b/man/man2/fchdir.2 new file mode 100644 index 0000000..60b9685 --- /dev/null +++ b/man/man2/fchdir.2 @@ -0,0 +1 @@ +.so man2/chdir.2 diff --git a/man/man2/fchmod.2 b/man/man2/fchmod.2 new file mode 100644 index 0000000..92647d2 --- /dev/null +++ b/man/man2/fchmod.2 @@ -0,0 +1 @@ +.so man2/chmod.2 diff --git a/man/man2/fchmodat.2 b/man/man2/fchmodat.2 new file mode 100644 index 0000000..92647d2 --- /dev/null +++ b/man/man2/fchmodat.2 @@ -0,0 +1 @@ +.so man2/chmod.2 diff --git a/man/man2/fchown.2 b/man/man2/fchown.2 new file mode 100644 index 0000000..f0a5635 --- /dev/null +++ b/man/man2/fchown.2 @@ -0,0 +1 @@ +.so man2/chown.2 diff --git a/man/man2/fchown32.2 b/man/man2/fchown32.2 new file mode 100644 index 0000000..b8b9452 --- /dev/null +++ b/man/man2/fchown32.2 @@ -0,0 +1 @@ +.so man2/fchown.2 diff --git a/man/man2/fchownat.2 b/man/man2/fchownat.2 new file mode 100644 index 0000000..f0a5635 --- /dev/null +++ b/man/man2/fchownat.2 @@ -0,0 +1 @@ +.so man2/chown.2 diff --git a/man/man2/fcntl.2 b/man/man2/fcntl.2 new file mode 100644 index 0000000..9f5e197 --- /dev/null +++ b/man/man2/fcntl.2 @@ -0,0 +1,2113 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson; +.\" and Copyright (C) 1998 Jamie Lokier; +.\" and Copyright (C) 2002-2010, 2014 Michael Kerrisk; +.\" and Copyright (C) 2014 Jeff Layton +.\" and Copyright (C) 2014 David Herrmann +.\" and Copyright (C) 2017 Jens Axboe +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-09-26 by Andries Brouwer +.\" and again on 960413 and 980804 and 981223. +.\" Modified 1998-12-11 by Jamie Lokier +.\" Applied correction by Christian Ehrhardt - aeb, 990712 +.\" Modified 2002-04-23 by Michael Kerrisk +.\" Added note on F_SETFL and O_DIRECT +.\" Complete rewrite + expansion of material on file locking +.\" Incorporated description of F_NOTIFY, drawing on +.\" Stephen Rothwell's notes in Documentation/dnotify.txt. +.\" Added description of F_SETLEASE and F_GETLEASE +.\" Corrected and polished, aeb, 020527. +.\" Modified 2004-03-03 by Michael Kerrisk +.\" Modified description of file leases: fixed some errors of detail +.\" Replaced the term "lease contestant" by "lease breaker" +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified 2004-12-08, added O_NOATIME after note from Martin Pool +.\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb. +.\" 2005-04-08 Jamie Lokier , mtk +.\" Described behavior of F_SETOWN/F_SETSIG in +.\" multithreaded processes, and generally cleaned +.\" up the discussion of F_SETOWN. +.\" 2005-05-20, Johannes Nicolai , +.\" mtk: Noted F_SETOWN bug for socket file descriptor in Linux 2.4 +.\" and earlier. Added text on permissions required to send signal. +.\" 2009-09-30, Michael Kerrisk +.\" Note obsolete F_SETOWN behavior with threads. +.\" Document F_SETOWN_EX and F_GETOWN_EX +.\" 2010-06-17, Michael Kerrisk +.\" Document F_SETPIPE_SZ and F_GETPIPE_SZ. +.\" 2014-07-08, David Herrmann +.\" Document F_ADD_SEALS and F_GET_SEALS +.\" 2017-06-26, Jens Axboe +.\" Document F_{GET,SET}_RW_HINT and F_{GET,SET}_FILE_RW_HINT +.\" +.TH fcntl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fcntl \- manipulate file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fcntl(int " fd ", int " op ", ... /* " arg " */ );" +.fi +.SH DESCRIPTION +.BR fcntl () +performs one of the operations described below on the open file descriptor +.IR fd . +The operation is determined by +.IR op . +.P +.BR fcntl () +can take an optional third argument. +Whether or not this argument is required is determined by +.IR op . +The required argument type is indicated in parentheses after each +.I op +name (in most cases, the required type is +.IR int , +and we identify the argument using the name +.IR arg ), +or +.I void +is specified if the argument is not required. +.P +Certain of the operations below are supported only since a particular +Linux kernel version. +The preferred method of checking whether the host kernel supports +a particular operation is to invoke +.BR fcntl () +with the desired +.I op +value and then test whether the call failed with +.BR EINVAL , +indicating that the kernel does not recognize this value. +.SS Duplicating a file descriptor +.TP +.BR F_DUPFD " (\fIint\fP)" +Duplicate the file descriptor +.I fd +using the lowest-numbered available file descriptor greater than or equal to +.IR arg . +This is different from +.BR dup2 (2), +which uses exactly the file descriptor specified. +.IP +On success, the new file descriptor is returned. +.IP +See +.BR dup (2) +for further details. +.TP +.BR F_DUPFD_CLOEXEC " (\fIint\fP; since Linux 2.6.24)" +As for +.BR F_DUPFD , +but additionally set the +close-on-exec flag for the duplicate file descriptor. +Specifying this flag permits a program to avoid an additional +.BR fcntl () +.B F_SETFD +operation to set the +.B FD_CLOEXEC +flag. +For an explanation of why this flag is useful, +see the description of +.B O_CLOEXEC +in +.BR open (2). +.SS File descriptor flags +The following operations manipulate the flags associated with +a file descriptor. +Currently, only one such flag is defined: +.BR FD_CLOEXEC , +the close-on-exec flag. +If the +.B FD_CLOEXEC +bit is set, +the file descriptor will automatically be closed during a successful +.BR execve (2). +(If the +.BR execve (2) +fails, the file descriptor is left open.) +If the +.B FD_CLOEXEC +bit is not set, the file descriptor will remain open across an +.BR execve (2). +.TP +.BR F_GETFD " (\fIvoid\fP)" +Return (as the function result) the file descriptor flags; +.I arg +is ignored. +.TP +.BR F_SETFD " (\fIint\fP)" +Set the file descriptor flags to the value specified by +.IR arg . +.P +In multithreaded programs, using +.BR fcntl () +.B F_SETFD +to set the close-on-exec flag at the same time as another thread performs a +.BR fork (2) +plus +.BR execve (2) +is vulnerable to a race condition that may unintentionally leak +the file descriptor to the program executed in the child process. +See the discussion of the +.B O_CLOEXEC +flag in +.BR open (2) +for details and a remedy to the problem. +.SS File status flags +Each open file description has certain associated status flags, +initialized by +.BR open (2) +.\" or +.\" .BR creat (2), +and possibly modified by +.BR fcntl (). +Duplicated file descriptors +(made with +.BR dup (2), +.BR fcntl (F_DUPFD), +.BR fork (2), +etc.) refer to the same open file description, and thus +share the same file status flags. +.P +The file status flags and their semantics are described in +.BR open (2). +.TP +.BR F_GETFL " (\fIvoid\fP)" +Return (as the function result) +the file access mode and the file status flags; +.I arg +is ignored. +.TP +.BR F_SETFL " (\fIint\fP)" +Set the file status flags to the value specified by +.IR arg . +File access mode +.RB ( O_RDONLY ", " O_WRONLY ", " O_RDWR ) +and file creation flags +(i.e., +.BR O_CREAT ", " O_EXCL ", " O_NOCTTY ", " O_TRUNC ) +in +.I arg +are ignored. +On Linux, this operation can change only the +.BR O_APPEND , +.BR O_ASYNC , +.BR O_DIRECT , +.BR O_NOATIME , +and +.B O_NONBLOCK +flags. +It is not possible to change the +.B O_DSYNC +and +.B O_SYNC +flags; see BUGS, below. +.SS Advisory record locking +Linux implements traditional ("process-associated") UNIX record locks, +as standardized by POSIX. +For a Linux-specific alternative with better semantics, +see the discussion of open file description locks below. +.P +.BR F_SETLK , +.BR F_SETLKW , +and +.B F_GETLK +are used to acquire, release, and test for the existence of record +locks (also known as byte-range, file-segment, or file-region locks). +The third argument, +.IR lock , +is a pointer to a structure that has at least the following fields +(in unspecified order). +.P +.in +4n +.EX +struct flock { + ... + short l_type; /* Type of lock: F_RDLCK, + F_WRLCK, F_UNLCK */ + short l_whence; /* How to interpret l_start: + SEEK_SET, SEEK_CUR, SEEK_END */ + off_t l_start; /* Starting offset for lock */ + off_t l_len; /* Number of bytes to lock */ + pid_t l_pid; /* PID of process blocking our lock + (set by F_GETLK and F_OFD_GETLK) */ + ... +}; +.EE +.in +.P +The +.IR l_whence ", " l_start ", and " l_len +fields of this structure specify the range of bytes we wish to lock. +Bytes past the end of the file may be locked, +but not bytes before the start of the file. +.P +.I l_start +is the starting offset for the lock, and is interpreted +relative to either: +the start of the file (if +.I l_whence +is +.BR SEEK_SET ); +the current file offset (if +.I l_whence +is +.BR SEEK_CUR ); +or the end of the file (if +.I l_whence +is +.BR SEEK_END ). +In the final two cases, +.I l_start +can be a negative number provided the +offset does not lie before the start of the file. +.P +.I l_len +specifies the number of bytes to be locked. +If +.I l_len +is positive, then the range to be locked covers bytes +.I l_start +up to and including +.IR l_start + l_len \-1. +Specifying 0 for +.I l_len +has the special meaning: lock all bytes starting at the +location specified by +.IR l_whence " and " l_start +through to the end of file, no matter how large the file grows. +.P +POSIX.1-2001 allows (but does not require) +an implementation to support a negative +.I l_len +value; if +.I l_len +is negative, the interval described by +.I lock +covers bytes +.IR l_start + l_len +up to and including +.IR l_start \-1. +This is supported since Linux 2.4.21 and Linux 2.5.49. +.P +The +.I l_type +field can be used to place a read +.RB ( F_RDLCK ) +or a write +.RB ( F_WRLCK ) +lock on a file. +Any number of processes may hold a read lock (shared lock) +on a file region, but only one process may hold a write lock +(exclusive lock). +An exclusive lock excludes all other locks, +both shared and exclusive. +A single process can hold only one type of lock on a file region; +if a new lock is applied to an already-locked region, +then the existing lock is converted to the new lock type. +(Such conversions may involve splitting, shrinking, or coalescing with +an existing lock if the byte range specified by the new lock does not +precisely coincide with the range of the existing lock.) +.TP +.BR F_SETLK " (\fIstruct flock *\fP)" +Acquire a lock (when +.I l_type +is +.B F_RDLCK +or +.BR F_WRLCK ) +or release a lock (when +.I l_type +is +.BR F_UNLCK ) +on the bytes specified by the +.IR l_whence ", " l_start ", and " l_len +fields of +.IR lock . +If a conflicting lock is held by another process, +this call returns \-1 and sets +.I errno +to +.B EACCES +or +.BR EAGAIN . +(The error returned in this case differs across implementations, +so POSIX requires a portable application to check for both errors.) +.TP +.BR F_SETLKW " (\fIstruct flock *\fP)" +As for +.BR F_SETLK , +but if a conflicting lock is held on the file, then wait for that +lock to be released. +If a signal is caught while waiting, then the call is interrupted +and (after the signal handler has returned) +returns immediately (with return value \-1 and +.I errno +set to +.BR EINTR ; +see +.BR signal (7)). +.TP +.BR F_GETLK " (\fIstruct flock *\fP)" +On input to this call, +.I lock +describes a lock we would like to place on the file. +If the lock could be placed, +.BR fcntl () +does not actually place it, but returns +.B F_UNLCK +in the +.I l_type +field of +.I lock +and leaves the other fields of the structure unchanged. +.IP +If one or more incompatible locks would prevent +this lock being placed, then +.BR fcntl () +returns details about one of those locks in the +.IR l_type ", " l_whence ", " l_start ", and " l_len +fields of +.IR lock . +If the conflicting lock is a traditional (process-associated) record lock, +then the +.I l_pid +field is set to the PID of the process holding that lock. +If the conflicting lock is an open file description lock, then +.I l_pid +is set to \-1. +Note that the returned information +may already be out of date by the time the caller inspects it. +.P +In order to place a read lock, +.I fd +must be open for reading. +In order to place a write lock, +.I fd +must be open for writing. +To place both types of lock, open a file read-write. +.P +When placing locks with +.BR F_SETLKW , +the kernel detects +.IR deadlocks , +whereby two or more processes have their +lock requests mutually blocked by locks held by the other processes. +For example, suppose process A holds a write lock on byte 100 of a file, +and process B holds a write lock on byte 200. +If each process then attempts to lock the byte already +locked by the other process using +.BR F_SETLKW , +then, without deadlock detection, +both processes would remain blocked indefinitely. +When the kernel detects such deadlocks, +it causes one of the blocking lock requests to immediately fail with the error +.BR EDEADLK ; +an application that encounters such an error should release +some of its locks to allow other applications to proceed before +attempting regain the locks that it requires. +Circular deadlocks involving more than two processes are also detected. +Note, however, that there are limitations to the kernel's +deadlock-detection algorithm; see BUGS. +.P +As well as being removed by an explicit +.BR F_UNLCK , +record locks are automatically released when the process terminates. +.P +Record locks are not inherited by a child created via +.BR fork (2), +but are preserved across an +.BR execve (2). +.P +Because of the buffering performed by the +.BR stdio (3) +library, the use of record locking with routines in that package +should be avoided; use +.BR read (2) +and +.BR write (2) +instead. +.P +The record locks described above are associated with the process +(unlike the open file description locks described below). +This has some unfortunate consequences: +.IP \[bu] 3 +If a process closes +.I any +file descriptor referring to a file, +then all of the process's locks on that file are released, +regardless of the file descriptor(s) on which the locks were obtained. +.\" (Additional file descriptors referring to the same file +.\" may have been obtained by calls to +.\" .BR open "(2), " dup "(2), " dup2 "(2), or " fcntl ().) +This is bad: it means that a process can lose its locks on +a file such as +.I /etc/passwd +or +.I /etc/mtab +when for some reason a library function decides to open, read, +and close the same file. +.IP \[bu] +The threads in a process share locks. +In other words, +a multithreaded program can't use record locking to ensure +that threads don't simultaneously access the same region of a file. +.P +Open file description locks solve both of these problems. +.SS Open file description locks (non-POSIX) +Open file description locks are advisory byte-range locks whose operation is +in most respects identical to the traditional record locks described above. +This lock type is Linux-specific, +and available since Linux 3.15. +(There is a proposal with the Austin Group +.\" FIXME . Review progress into POSIX +.\" http://austingroupbugs.net/view.php?id=768 +to include this lock type in the next revision of POSIX.1.) +For an explanation of open file descriptions, see +.BR open (2). +.P +The principal difference between the two lock types +is that whereas traditional record locks +are associated with a process, +open file description locks are associated with the +open file description on which they are acquired, +much like locks acquired with +.BR flock (2). +Consequently (and unlike traditional advisory record locks), +open file description locks are inherited across +.BR fork (2) +(and +.BR clone (2) +with +.BR CLONE_FILES ), +and are only automatically released on the last close +of the open file description, +instead of being released on any close of the file. +.P +Conflicting lock combinations +(i.e., a read lock and a write lock or two write locks) +where one lock is an open file description lock and the other +is a traditional record lock conflict +even when they are acquired by the same process on the same file descriptor. +.P +Open file description locks placed via the same open file description +(i.e., via the same file descriptor, +or via a duplicate of the file descriptor created by +.BR fork (2), +.BR dup (2), +.BR fcntl () +.BR F_DUPFD , +and so on) are always compatible: +if a new lock is placed on an already locked region, +then the existing lock is converted to the new lock type. +(Such conversions may result in splitting, shrinking, or coalescing with +an existing lock as discussed above.) +.P +On the other hand, open file description locks may conflict with +each other when they are acquired via different open file descriptions. +Thus, the threads in a multithreaded program can use +open file description locks to synchronize access to a file region +by having each thread perform its own +.BR open (2) +on the file and applying locks via the resulting file descriptor. +.P +As with traditional advisory locks, the third argument to +.BR fcntl (), +.IR lock , +is a pointer to an +.I flock +structure. +By contrast with traditional record locks, the +.I l_pid +field of that structure must be set to zero +when using the operations described below. +.P +The operations for working with open file description locks are analogous +to those used with traditional locks: +.TP +.BR F_OFD_SETLK " (\fIstruct flock *\fP)" +Acquire an open file description lock (when +.I l_type +is +.B F_RDLCK +or +.BR F_WRLCK ) +or release an open file description lock (when +.I l_type +is +.BR F_UNLCK ) +on the bytes specified by the +.IR l_whence ", " l_start ", and " l_len +fields of +.IR lock . +If a conflicting lock is held by another process, +this call returns \-1 and sets +.I errno +to +.BR EAGAIN . +.TP +.BR F_OFD_SETLKW " (\fIstruct flock *\fP)" +As for +.BR F_OFD_SETLK , +but if a conflicting lock is held on the file, then wait for that lock to be +released. +If a signal is caught while waiting, then the call is interrupted +and (after the signal handler has returned) returns immediately +(with return value \-1 and +.I errno +set to +.BR EINTR ; +see +.BR signal (7)). +.TP +.BR F_OFD_GETLK " (\fIstruct flock *\fP)" +On input to this call, +.I lock +describes an open file description lock we would like to place on the file. +If the lock could be placed, +.BR fcntl () +does not actually place it, but returns +.B F_UNLCK +in the +.I l_type +field of +.I lock +and leaves the other fields of the structure unchanged. +If one or more incompatible locks would prevent this lock being placed, +then details about one of these locks are returned via +.IR lock , +as described above for +.BR F_GETLK . +.P +In the current implementation, +.\" commit 57b65325fe34ec4c917bc4e555144b4a94d9e1f7 +no deadlock detection is performed for open file description locks. +(This contrasts with process-associated record locks, +for which the kernel does perform deadlock detection.) +.\" +.SS Mandatory locking +.IR Warning : +the Linux implementation of mandatory locking is unreliable. +See BUGS below. +Because of these bugs, +and the fact that the feature is believed to be little used, +since Linux 4.5, mandatory locking has been made an optional feature, +governed by a configuration option +.RB ( CONFIG_MANDATORY_FILE_LOCKING ). +This feature is no longer supported at all in Linux 5.15 and above. +.P +By default, both traditional (process-associated) and open file description +record locks are advisory. +Advisory locks are not enforced and are useful only between +cooperating processes. +.P +Both lock types can also be mandatory. +Mandatory locks are enforced for all processes. +If a process tries to perform an incompatible access (e.g., +.BR read (2) +or +.BR write (2)) +on a file region that has an incompatible mandatory lock, +then the result depends upon whether the +.B O_NONBLOCK +flag is enabled for its open file description. +If the +.B O_NONBLOCK +flag is not enabled, then +the system call is blocked until the lock is removed +or converted to a mode that is compatible with the access. +If the +.B O_NONBLOCK +flag is enabled, then the system call fails with the error +.BR EAGAIN . +.P +To make use of mandatory locks, mandatory locking must be enabled +both on the filesystem that contains the file to be locked, +and on the file itself. +Mandatory locking is enabled on a filesystem +using the "\-o mand" option to +.BR mount (8), +or the +.B MS_MANDLOCK +flag for +.BR mount (2). +Mandatory locking is enabled on a file by disabling +group execute permission on the file and enabling the set-group-ID +permission bit (see +.BR chmod (1) +and +.BR chmod (2)). +.P +Mandatory locking is not specified by POSIX. +Some other systems also support mandatory locking, +although the details of how to enable it vary across systems. +.\" +.SS Lost locks +When an advisory lock is obtained on a networked filesystem such as +NFS it is possible that the lock might get lost. +This may happen due to administrative action on the server, or due to a +network partition (i.e., loss of network connectivity with the server) +which lasts long enough for the server to assume +that the client is no longer functioning. +.P +When the filesystem determines that a lock has been lost, future +.BR read (2) +or +.BR write (2) +requests may fail with the error +.BR EIO . +This error will persist until the lock is removed or the file +descriptor is closed. +Since Linux 3.12, +.\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d +this happens at least for NFSv4 (including all minor versions). +.P +Some versions of UNIX send a signal +.RB ( SIGLOST ) +in this circumstance. +Linux does not define this signal, and does not provide any +asynchronous notification of lost locks. +.\" +.SS Managing signals +.BR F_GETOWN , +.BR F_SETOWN , +.BR F_GETOWN_EX , +.BR F_SETOWN_EX , +.BR F_GETSIG , +and +.B F_SETSIG +are used to manage I/O availability signals: +.TP +.BR F_GETOWN " (\fIvoid\fP)" +Return (as the function result) +the process ID or process group ID currently receiving +.B SIGIO +and +.B SIGURG +signals for events on file descriptor +.IR fd . +Process IDs are returned as positive values; +process group IDs are returned as negative values (but see BUGS below). +.I arg +is ignored. +.TP +.BR F_SETOWN " (\fIint\fP)" +Set the process ID or process group ID that will receive +.B SIGIO +and +.B SIGURG +signals for events on the file descriptor +.IR fd . +The target process or process group ID is specified in +.IR arg . +A process ID is specified as a positive value; +a process group ID is specified as a negative value. +Most commonly, the calling process specifies itself as the owner +(that is, +.I arg +is specified as +.BR getpid (2)). +.IP +As well as setting the file descriptor owner, +one must also enable generation of signals on the file descriptor. +This is done by using the +.BR fcntl () +.B F_SETFL +operation to set the +.B O_ASYNC +file status flag on the file descriptor. +Subsequently, a +.B SIGIO +signal is sent whenever input or output becomes possible +on the file descriptor. +The +.BR fcntl () +.B F_SETSIG +operation can be used to obtain delivery of a signal other than +.BR SIGIO . +.IP +Sending a signal to the owner process (group) specified by +.B F_SETOWN +is subject to the same permissions checks as are described for +.BR kill (2), +where the sending process is the one that employs +.B F_SETOWN +(but see BUGS below). +If this permission check fails, then the signal is +silently discarded. +.IR Note : +The +.B F_SETOWN +operation records the caller's credentials at the time of the +.BR fcntl () +call, +and it is these saved credentials that are used for the permission checks. +.IP +If the file descriptor +.I fd +refers to a socket, +.B F_SETOWN +also selects +the recipient of +.B SIGURG +signals that are delivered when out-of-band +data arrives on that socket. +.RB ( SIGURG +is sent in any situation where +.BR select (2) +would report the socket as having an "exceptional condition".) +.\" The following appears to be rubbish. It doesn't seem to +.\" be true according to the kernel source, and I can write +.\" a program that gets a terminal-generated SIGIO even though +.\" it is not the foreground process group of the terminal. +.\" -- MTK, 8 Apr 05 +.\" +.\" If the file descriptor +.\" .I fd +.\" refers to a terminal device, then SIGIO +.\" signals are sent to the foreground process group of the terminal. +.IP +The following was true in Linux 2.6.x up to and including Linux 2.6.11: +.RS +.IP +If a nonzero value is given to +.B F_SETSIG +in a multithreaded process running with a threading library +that supports thread groups (e.g., NPTL), +then a positive value given to +.B F_SETOWN +has a different meaning: +.\" The relevant place in the (2.6) kernel source is the +.\" 'switch' in fs/fcntl.c::send_sigio_to_task() -- MTK, Apr 2005 +instead of being a process ID identifying a whole process, +it is a thread ID identifying a specific thread within a process. +Consequently, it may be necessary to pass +.B F_SETOWN +the result of +.BR gettid (2) +instead of +.BR getpid (2) +to get sensible results when +.B F_SETSIG +is used. +(In current Linux threading implementations, +a main thread's thread ID is the same as its process ID. +This means that a single-threaded program can equally use +.BR gettid (2) +or +.BR getpid (2) +in this scenario.) +Note, however, that the statements in this paragraph do not apply +to the +.B SIGURG +signal generated for out-of-band data on a socket: +this signal is always sent to either a process or a process group, +depending on the value given to +.BR F_SETOWN . +.\" send_sigurg()/send_sigurg_to_task() bypasses +.\" kill_fasync()/send_sigio()/send_sigio_to_task() +.\" to directly call send_group_sig_info() +.\" -- MTK, Apr 2005 (kernel 2.6.11) +.RE +.IP +The above behavior was accidentally dropped in Linux 2.6.12, +and won't be restored. +From Linux 2.6.32 onward, use +.B F_SETOWN_EX +to target +.B SIGIO +and +.B SIGURG +signals at a particular thread. +.TP +.BR F_GETOWN_EX " (\fIstruct f_owner_ex *\fP) (since Linux 2.6.32)" +Return the current file descriptor owner settings +as defined by a previous +.B F_SETOWN_EX +operation. +The information is returned in the structure pointed to by +.IR arg , +which has the following form: +.IP +.in +4n +.EX +struct f_owner_ex { + int type; + pid_t pid; +}; +.EE +.in +.IP +The +.I type +field will have one of the values +.BR F_OWNER_TID , +.BR F_OWNER_PID , +or +.BR F_OWNER_PGRP . +The +.I pid +field is a positive integer representing a thread ID, process ID, +or process group ID. +See +.B F_SETOWN_EX +for more details. +.TP +.BR F_SETOWN_EX " (\fIstruct f_owner_ex *\fP) (since Linux 2.6.32)" +This operation performs a similar task to +.BR F_SETOWN . +It allows the caller to direct I/O availability signals +to a specific thread, process, or process group. +The caller specifies the target of signals via +.IR arg , +which is a pointer to a +.I f_owner_ex +structure. +The +.I type +field has one of the following values, which define how +.I pid +is interpreted: +.RS +.TP +.B F_OWNER_TID +Send the signal to the thread whose thread ID +(the value returned by a call to +.BR clone (2) +or +.BR gettid (2)) +is specified in +.IR pid . +.TP +.B F_OWNER_PID +Send the signal to the process whose ID +is specified in +.IR pid . +.TP +.B F_OWNER_PGRP +Send the signal to the process group whose ID +is specified in +.IR pid . +(Note that, unlike with +.BR F_SETOWN , +a process group ID is specified as a positive value here.) +.RE +.TP +.BR F_GETSIG " (\fIvoid\fP)" +Return (as the function result) +the signal sent when input or output becomes possible. +A value of zero means +.B SIGIO +is sent. +Any other value (including +.BR SIGIO ) +is the +signal sent instead, and in this case additional info is available to +the signal handler if installed with +.BR SA_SIGINFO . +.I arg +is ignored. +.TP +.BR F_SETSIG " (\fIint\fP)" +Set the signal sent when input or output becomes possible +to the value given in +.IR arg . +A value of zero means to send the default +.B SIGIO +signal. +Any other value (including +.BR SIGIO ) +is the signal to send instead, and in this case additional info +is available to the signal handler if installed with +.BR SA_SIGINFO . +.\" +.\" The following was true only up until Linux 2.6.11: +.\" +.\" Additionally, passing a nonzero value to +.\" .B F_SETSIG +.\" changes the signal recipient from a whole process to a specific thread +.\" within a process. +.\" See the description of +.\" .B F_SETOWN +.\" for more details. +.IP +By using +.B F_SETSIG +with a nonzero value, and setting +.B SA_SIGINFO +for the +signal handler (see +.BR sigaction (2)), +extra information about I/O events is passed to +the handler in a +.I siginfo_t +structure. +If the +.I si_code +field indicates the source is +.BR SI_SIGIO , +the +.I si_fd +field gives the file descriptor associated with the event. +Otherwise, +there is no indication which file descriptors are pending, and you +should use the usual mechanisms +.RB ( select (2), +.BR poll (2), +.BR read (2) +with +.B O_NONBLOCK +set etc.) to determine which file descriptors are available for I/O. +.IP +Note that the file descriptor provided in +.I si_fd +is the one that was specified during the +.B F_SETSIG +operation. +This can lead to an unusual corner case. +If the file descriptor is duplicated +.RB ( dup (2) +or similar), and the original file descriptor is closed, +then I/O events will continue to be generated, but the +.I si_fd +field will contain the number of the now closed file descriptor. +.IP +By selecting a real time signal (value >= +.BR SIGRTMIN ), +multiple I/O events may be queued using the same signal numbers. +(Queuing is dependent on available memory.) +Extra information is available +if +.B SA_SIGINFO +is set for the signal handler, as above. +.IP +Note that Linux imposes a limit on the +number of real-time signals that may be queued to a +process (see +.BR getrlimit (2) +and +.BR signal (7)) +and if this limit is reached, then the kernel reverts to +delivering +.BR SIGIO , +and this signal is delivered to the entire +process rather than to a specific thread. +.\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05 +.P +Using these mechanisms, a program can implement fully asynchronous I/O +without using +.BR select (2) +or +.BR poll (2) +most of the time. +.P +The use of +.B O_ASYNC +is specific to BSD and Linux. +The only use of +.B F_GETOWN +and +.B F_SETOWN +specified in POSIX.1 is in conjunction with the use of the +.B SIGURG +signal on sockets. +(POSIX does not specify the +.B SIGIO +signal.) +.BR F_GETOWN_EX , +.BR F_SETOWN_EX , +.BR F_GETSIG , +and +.B F_SETSIG +are Linux-specific. +POSIX has asynchronous I/O and the +.I aio_sigevent +structure to achieve similar things; these are also available +in Linux as part of the GNU C Library (glibc). +.SS Leases +.B F_SETLEASE +and +.B F_GETLEASE +(Linux 2.4 onward) are used to establish a new lease, +and retrieve the current lease, on the open file description +referred to by the file descriptor +.IR fd . +A file lease provides a mechanism whereby the process holding +the lease (the "lease holder") is notified (via delivery of a signal) +when a process (the "lease breaker") tries to +.BR open (2) +or +.BR truncate (2) +the file referred to by that file descriptor. +.TP +.BR F_SETLEASE " (\fIint\fP)" +Set or remove a file lease according to which of the following +values is specified in the integer +.IR arg : +.RS +.TP +.B F_RDLCK +Take out a read lease. +This will cause the calling process to be notified when +the file is opened for writing or is truncated. +.\" The following became true in Linux 2.6.10: +.\" See the man-pages-2.09 Changelog for further info. +A read lease can be placed only on a file descriptor that +is opened read-only. +.TP +.B F_WRLCK +Take out a write lease. +This will cause the caller to be notified when +the file is opened for reading or writing or is truncated. +A write lease may be placed on a file only if there are no +other open file descriptors for the file. +.TP +.B F_UNLCK +Remove our lease from the file. +.RE +.P +Leases are associated with an open file description (see +.BR open (2)). +This means that duplicate file descriptors (created by, for example, +.BR fork (2) +or +.BR dup (2)) +refer to the same lease, and this lease may be modified +or released using any of these descriptors. +Furthermore, the lease is released by either an explicit +.B F_UNLCK +operation on any of these duplicate file descriptors, or when all +such file descriptors have been closed. +.P +Leases may be taken out only on regular files. +An unprivileged process may take out a lease only on a file whose +UID (owner) matches the filesystem UID of the process. +A process with the +.B CAP_LEASE +capability may take out leases on arbitrary files. +.TP +.BR F_GETLEASE " (\fIvoid\fP)" +Indicates what type of lease is associated with the file descriptor +.I fd +by returning either +.BR F_RDLCK ", " F_WRLCK ", or " F_UNLCK , +indicating, respectively, a read lease , a write lease, or no lease. +.I arg +is ignored. +.P +When a process (the "lease breaker") performs an +.BR open (2) +or +.BR truncate (2) +that conflicts with a lease established via +.BR F_SETLEASE , +the system call is blocked by the kernel and +the kernel notifies the lease holder by sending it a signal +.RB ( SIGIO +by default). +The lease holder should respond to receipt of this signal by doing +whatever cleanup is required in preparation for the file to be +accessed by another process (e.g., flushing cached buffers) and +then either remove or downgrade its lease. +A lease is removed by performing an +.B F_SETLEASE +operation specifying +.I arg +as +.BR F_UNLCK . +If the lease holder currently holds a write lease on the file, +and the lease breaker is opening the file for reading, +then it is sufficient for the lease holder to downgrade +the lease to a read lease. +This is done by performing an +.B F_SETLEASE +operation specifying +.I arg +as +.BR F_RDLCK . +.P +If the lease holder fails to downgrade or remove the lease within +the number of seconds specified in +.IR /proc/sys/fs/lease\-break\-time , +then the kernel forcibly removes or downgrades the lease holder's lease. +.P +Once a lease break has been initiated, +.B F_GETLEASE +returns the target lease type (either +.B F_RDLCK +or +.BR F_UNLCK , +depending on what would be compatible with the lease breaker) +until the lease holder voluntarily downgrades or removes the lease or +the kernel forcibly does so after the lease break timer expires. +.P +Once the lease has been voluntarily or forcibly removed or downgraded, +and assuming the lease breaker has not unblocked its system call, +the kernel permits the lease breaker's system call to proceed. +.P +If the lease breaker's blocked +.BR open (2) +or +.BR truncate (2) +is interrupted by a signal handler, +then the system call fails with the error +.BR EINTR , +but the other steps still occur as described above. +If the lease breaker is killed by a signal while blocked in +.BR open (2) +or +.BR truncate (2), +then the other steps still occur as described above. +If the lease breaker specifies the +.B O_NONBLOCK +flag when calling +.BR open (2), +then the call immediately fails with the error +.BR EWOULDBLOCK , +but the other steps still occur as described above. +.P +The default signal used to notify the lease holder is +.BR SIGIO , +but this can be changed using the +.B F_SETSIG +operation to +.BR fcntl (). +If a +.B F_SETSIG +operation is performed (even one specifying +.BR SIGIO ), +and the signal +handler is established using +.BR SA_SIGINFO , +then the handler will receive a +.I siginfo_t +structure as its second argument, and the +.I si_fd +field of this argument will hold the file descriptor of the leased file +that has been accessed by another process. +(This is useful if the caller holds leases against multiple files.) +.SS File and directory change notification (dnotify) +.TP +.BR F_NOTIFY " (\fIint\fP)" +(Linux 2.4 onward) +Provide notification when the directory referred to by +.I fd +or any of the files that it contains is changed. +The events to be notified are specified in +.IR arg , +which is a bit mask specified by ORing together zero or more of +the following bits: +.P +.RS +.PD 0 +.TP +.B DN_ACCESS +A file was accessed +.RB ( read (2), +.BR pread (2), +.BR readv (2), +and similar) +.TP +.B DN_MODIFY +A file was modified +.RB ( write (2), +.BR pwrite (2), +.BR writev (2), +.BR truncate (2), +.BR ftruncate (2), +and similar). +.TP +.B DN_CREATE +A file was created +.RB ( open (2), +.BR creat (2), +.BR mknod (2), +.BR mkdir (2), +.BR link (2), +.BR symlink (2), +.BR rename (2) +into this directory). +.TP +.B DN_DELETE +A file was unlinked +.RB ( unlink (2), +.BR rename (2) +to another directory, +.BR rmdir (2)). +.TP +.B DN_RENAME +A file was renamed within this directory +.RB ( rename (2)). +.TP +.B DN_ATTRIB +The attributes of a file were changed +.RB ( chown (2), +.BR chmod (2), +.BR utime (2), +.BR utimensat (2), +and similar). +.PD +.RE +.IP +(In order to obtain these definitions, the +.B _GNU_SOURCE +feature test macro must be defined before including +.I any +header files.) +.IP +Directory notifications are normally "one-shot", and the application +must reregister to receive further notifications. +Alternatively, if +.B DN_MULTISHOT +is included in +.IR arg , +then notification will remain in effect until explicitly removed. +.IP +.\" The following does seem a poor API-design choice... +A series of +.B F_NOTIFY +requests is cumulative, with the events in +.I arg +being added to the set already monitored. +To disable notification of all events, make an +.B F_NOTIFY +call specifying +.I arg +as 0. +.IP +Notification occurs via delivery of a signal. +The default signal is +.BR SIGIO , +but this can be changed using the +.B F_SETSIG +operation to +.BR fcntl (). +(Note that +.B SIGIO +is one of the nonqueuing standard signals; +switching to the use of a real-time signal means that +multiple notifications can be queued to the process.) +In the latter case, the signal handler receives a +.I siginfo_t +structure as its second argument (if the handler was +established using +.BR SA_SIGINFO ) +and the +.I si_fd +field of this structure contains the file descriptor which +generated the notification (useful when establishing notification +on multiple directories). +.IP +Especially when using +.BR DN_MULTISHOT , +a real time signal should be used for notification, +so that multiple notifications can be queued. +.IP +.B NOTE: +New applications should use the +.I inotify +interface (available since Linux 2.6.13), +which provides a much superior interface for obtaining notifications of +filesystem events. +See +.BR inotify (7). +.SS Changing the capacity of a pipe +.TP +.BR F_SETPIPE_SZ " (\fIint\fP; since Linux 2.6.35)" +Change the capacity of the pipe referred to by +.I fd +to be at least +.I arg +bytes. +An unprivileged process can adjust the pipe capacity to any value +between the system page size and the limit defined in +.I /proc/sys/fs/pipe\-max\-size +(see +.BR proc (5)). +Attempts to set the pipe capacity below the page size are silently +rounded up to the page size. +Attempts by an unprivileged process to set the pipe capacity above the limit in +.I /proc/sys/fs/pipe\-max\-size +yield the error +.BR EPERM ; +a privileged process +.RB ( CAP_SYS_RESOURCE ) +can override the limit. +.IP +When allocating the buffer for the pipe, +the kernel may use a capacity larger than +.IR arg , +if that is convenient for the implementation. +(In the current implementation, +the allocation is the next higher power-of-two page-size multiple +of the requested size.) +The actual capacity (in bytes) that is set is returned as the function result. +.IP +Attempting to set the pipe capacity smaller than the amount +of buffer space currently used to store data produces the error +.BR EBUSY . +.IP +Note that because of the way the pages of the pipe buffer +are employed when data is written to the pipe, +the number of bytes that can be written may be less than the nominal size, +depending on the size of the writes. +.TP +.BR F_GETPIPE_SZ " (\fIvoid\fP; since Linux 2.6.35)" +Return (as the function result) the capacity of the pipe referred to by +.IR fd . +.\" +.SS File Sealing +File seals limit the set of allowed operations on a given file. +For each seal that is set on a file, +a specific set of operations will fail with +.B EPERM +on this file from now on. +The file is said to be sealed. +The default set of seals depends on the type of the underlying +file and filesystem. +For an overview of file sealing, a discussion of its purpose, +and some code examples, see +.BR memfd_create (2). +.P +Currently, +file seals can be applied only to a file descriptor returned by +.BR memfd_create (2) +(if the +.B MFD_ALLOW_SEALING +was employed). +On other filesystems, all +.BR fcntl () +operations that operate on seals will return +.BR EINVAL . +.P +Seals are a property of an inode. +Thus, all open file descriptors referring to the same inode share +the same set of seals. +Furthermore, seals can never be removed, only added. +.TP +.BR F_ADD_SEALS " (\fIint\fP; since Linux 3.17)" +Add the seals given in the bit-mask argument +.I arg +to the set of seals of the inode referred to by the file descriptor +.IR fd . +Seals cannot be removed again. +Once this call succeeds, the seals are enforced by the kernel immediately. +If the current set of seals includes +.B F_SEAL_SEAL +(see below), then this call will be rejected with +.BR EPERM . +Adding a seal that is already set is a no-op, in case +.B F_SEAL_SEAL +is not set already. +In order to place a seal, the file descriptor +.I fd +must be writable. +.TP +.BR F_GET_SEALS " (\fIvoid\fP; since Linux 3.17)" +Return (as the function result) the current set of seals +of the inode referred to by +.IR fd . +If no seals are set, 0 is returned. +If the file does not support sealing, \-1 is returned and +.I errno +is set to +.BR EINVAL . +.P +The following seals are available: +.TP +.B F_SEAL_SEAL +If this seal is set, any further call to +.BR fcntl () +with +.B F_ADD_SEALS +fails with the error +.BR EPERM . +Therefore, this seal prevents any modifications to the set of seals itself. +If the initial set of seals of a file includes +.BR F_SEAL_SEAL , +then this effectively causes the set of seals to be constant and locked. +.TP +.B F_SEAL_SHRINK +If this seal is set, the file in question cannot be reduced in size. +This affects +.BR open (2) +with the +.B O_TRUNC +flag as well as +.BR truncate (2) +and +.BR ftruncate (2). +Those calls fail with +.B EPERM +if you try to shrink the file in question. +Increasing the file size is still possible. +.TP +.B F_SEAL_GROW +If this seal is set, the size of the file in question cannot be increased. +This affects +.BR write (2) +beyond the end of the file, +.BR truncate (2), +.BR ftruncate (2), +and +.BR fallocate (2). +These calls fail with +.B EPERM +if you use them to increase the file size. +If you keep the size or shrink it, those calls still work as expected. +.TP +.B F_SEAL_WRITE +If this seal is set, you cannot modify the contents of the file. +Note that shrinking or growing the size of the file is +still possible and allowed. +.\" One or more other seals are typically used with F_SEAL_WRITE +.\" because, given a file with the F_SEAL_WRITE seal set, then, +.\" while it would no longer be possible to (say) write zeros into +.\" the last 100 bytes of a file, it would still be possible +.\" to (say) shrink the file by 100 bytes using ftruncate(), and +.\" then increase the file size by 100 bytes, which would have +.\" the effect of replacing the last hundred bytes by zeros. +.\" +Thus, this seal is normally used in combination with one of the other seals. +This seal affects +.BR write (2) +and +.BR fallocate (2) +(only in combination with the +.B FALLOC_FL_PUNCH_HOLE +flag). +Those calls fail with +.B EPERM +if this seal is set. +Furthermore, trying to create new shared, writable memory-mappings via +.BR mmap (2) +will also fail with +.BR EPERM . +.IP +Using the +.B F_ADD_SEALS +operation to set the +.B F_SEAL_WRITE +seal fails with +.B EBUSY +if any writable, shared mapping exists. +Such mappings must be unmapped before you can add this seal. +Furthermore, if there are any asynchronous I/O operations +.RB ( io_submit (2)) +pending on the file, +all outstanding writes will be discarded. +.TP +.BR F_SEAL_FUTURE_WRITE " (since Linux 5.1)" +The effect of this seal is similar to +.BR F_SEAL_WRITE , +but the contents of the file can still be modified via +shared writable mappings that were created prior to the seal being set. +Any attempt to create a new writable mapping on the file via +.BR mmap (2) +will fail with +.BR EPERM . +Likewise, an attempt to write to the file via +.BR write (2) +will fail with +.BR EPERM . +.IP +Using this seal, +one process can create a memory buffer that it can continue to modify +while sharing that buffer on a "read-only" basis with other processes. +.\" +.SS File read/write hints +Write lifetime hints can be used to inform the kernel about the relative +expected lifetime of writes on a given inode or +via a particular open file description. +(See +.BR open (2) +for an explanation of open file descriptions.) +In this context, the term "write lifetime" means +the expected time the data will live on media, before +being overwritten or erased. +.P +An application may use the different hint values specified below to +separate writes into different write classes, +so that multiple users or applications running on a single storage back-end +can aggregate their I/O patterns in a consistent manner. +However, there are no functional semantics implied by these flags, +and different I/O classes can use the write lifetime hints +in arbitrary ways, so long as the hints are used consistently. +.P +The following operations can be applied to the file descriptor, +.IR fd : +.TP +.BR F_GET_RW_HINT " (\fIuint64_t *\fP; since Linux 4.13)" +Returns the value of the read/write hint associated with the underlying inode +referred to by +.IR fd . +.TP +.BR F_SET_RW_HINT " (\fIuint64_t *\fP; since Linux 4.13)" +Sets the read/write hint value associated with the +underlying inode referred to by +.IR fd . +This hint persists until either it is explicitly modified or +the underlying filesystem is unmounted. +.TP +.BR F_GET_FILE_RW_HINT " (\fIuint64_t *\fP; since Linux 4.13)" +Returns the value of the read/write hint associated with +the open file description referred to by +.IR fd . +.TP +.BR F_SET_FILE_RW_HINT " (\fIuint64_t *\fP; since Linux 4.13)" +Sets the read/write hint value associated with the open file description +referred to by +.IR fd . +.P +If an open file description has not been assigned a read/write hint, +then it shall use the value assigned to the inode, if any. +.P +The following read/write +hints are valid since Linux 4.13: +.TP +.B RWH_WRITE_LIFE_NOT_SET +No specific hint has been set. +This is the default value. +.TP +.B RWH_WRITE_LIFE_NONE +No specific write lifetime is associated with this file or inode. +.TP +.B RWH_WRITE_LIFE_SHORT +Data written to this inode or via this open file description +is expected to have a short lifetime. +.TP +.B RWH_WRITE_LIFE_MEDIUM +Data written to this inode or via this open file description +is expected to have a lifetime longer than +data written with +.BR RWH_WRITE_LIFE_SHORT . +.TP +.B RWH_WRITE_LIFE_LONG +Data written to this inode or via this open file description +is expected to have a lifetime longer than +data written with +.BR RWH_WRITE_LIFE_MEDIUM . +.TP +.B RWH_WRITE_LIFE_EXTREME +Data written to this inode or via this open file description +is expected to have a lifetime longer than +data written with +.BR RWH_WRITE_LIFE_LONG . +.P +All the write-specific hints are relative to each other, +and no individual absolute meaning should be attributed to them. +.SH RETURN VALUE +For a successful call, the return value depends on the operation: +.TP +.B F_DUPFD +The new file descriptor. +.TP +.B F_GETFD +Value of file descriptor flags. +.TP +.B F_GETFL +Value of file status flags. +.TP +.B F_GETLEASE +Type of lease held on file descriptor. +.TP +.B F_GETOWN +Value of file descriptor owner. +.TP +.B F_GETSIG +Value of signal sent when read or write becomes possible, or zero +for traditional +.B SIGIO +behavior. +.TP +.B F_GETPIPE_SZ +.TQ +.B F_SETPIPE_SZ +The pipe capacity. +.TP +.B F_GET_SEALS +A bit mask identifying the seals that have been set +for the inode referred to by +.IR fd . +.TP +All other operations +Zero. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.BR EACCES " or " EAGAIN +Operation is prohibited by locks held by other processes. +.TP +.B EAGAIN +The operation is prohibited because the file has been memory-mapped by +another process. +.TP +.B EBADF +.I fd +is not an open file descriptor +.TP +.B EBADF +.I op +is +.B F_SETLK +or +.B F_SETLKW +and the file descriptor open mode doesn't match with the +type of lock requested. +.TP +.B EBUSY +.I op +is +.B F_SETPIPE_SZ +and the new pipe capacity specified in +.I arg +is smaller than the amount of buffer space currently +used to store data in the pipe. +.TP +.B EBUSY +.I op +is +.BR F_ADD_SEALS , +.I arg +includes +.BR F_SEAL_WRITE , +and there exists a writable, shared mapping on the file referred to by +.IR fd . +.TP +.B EDEADLK +It was detected that the specified +.B F_SETLKW +operation would cause a deadlock. +.TP +.B EFAULT +.I lock +is outside your accessible address space. +.TP +.B EINTR +.I op +is +.B F_SETLKW +or +.B F_OFD_SETLKW +and the operation was interrupted by a signal; see +.BR signal (7). +.TP +.B EINTR +.I op +is +.BR F_GETLK , +.BR F_SETLK , +.BR F_OFD_GETLK , +or +.BR F_OFD_SETLK , +and the operation was interrupted by a signal before the lock was checked or +acquired. +Most likely when locking a remote file (e.g., locking over +NFS), but can sometimes happen locally. +.TP +.B EINVAL +The value specified in +.I op +is not recognized by this kernel. +.TP +.B EINVAL +.I op +is +.B F_ADD_SEALS +and +.I arg +includes an unrecognized sealing bit. +.TP +.B EINVAL +.I op +is +.B F_ADD_SEALS +or +.B F_GET_SEALS +and the filesystem containing the inode referred to by +.I fd +does not support sealing. +.TP +.B EINVAL +.I op +is +.B F_DUPFD +and +.I arg +is negative or is greater than the maximum allowable value +(see the discussion of +.B RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B EINVAL +.I op +is +.B F_SETSIG +and +.I arg +is not an allowable signal number. +.TP +.B EINVAL +.I op +is +.BR F_OFD_SETLK , +.BR F_OFD_SETLKW , +or +.BR F_OFD_GETLK , +and +.I l_pid +was not specified as zero. +.TP +.B EMFILE +.I op +is +.B F_DUPFD +and the per-process limit on the number of open file descriptors +has been reached. +.TP +.B ENOLCK +Too many segment locks open, lock table is full, or a remote locking +protocol failed (e.g., locking over NFS). +.TP +.B ENOTDIR +.B F_NOTIFY +was specified in +.IR op , +but +.I fd +does not refer to a directory. +.TP +.B EPERM +.I op +is +.B F_SETPIPE_SZ +and the soft or hard user pipe limit has been reached; see +.BR pipe (7). +.TP +.B EPERM +Attempted to clear the +.B O_APPEND +flag on a file that has the append-only attribute set. +.TP +.B EPERM +.I op +was +.BR F_ADD_SEALS , +but +.I fd +was not open for writing +or the current set of seals on the file already includes +.BR F_SEAL_SEAL . +.SH STANDARDS +POSIX.1-2008. +.P +.BR F_GETOWN_EX , +.BR F_SETOWN_EX , +.BR F_SETPIPE_SZ , +.BR F_GETPIPE_SZ , +.BR F_GETSIG , +.BR F_SETSIG , +.BR F_NOTIFY , +.BR F_GETLEASE , +and +.B F_SETLEASE +are Linux-specific. +(Define the +.B _GNU_SOURCE +macro to obtain these definitions.) +.\" .P +.\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions. +.P +.BR F_OFD_SETLK , +.BR F_OFD_SETLKW , +and +.B F_OFD_GETLK +are Linux-specific (and one must define +.B _GNU_SOURCE +to obtain their definitions), +but work is being done to have them included in the next version of POSIX.1. +.P +.B F_ADD_SEALS +and +.B F_GET_SEALS +are Linux-specific. +.\" FIXME . Once glibc adds support, add a note about FTM requirements +.SH HISTORY +SVr4, 4.3BSD, POSIX.1-2001. +.P +Only the operations +.BR F_DUPFD , +.BR F_GETFD , +.BR F_SETFD , +.BR F_GETFL , +.BR F_SETFL , +.BR F_GETLK , +.BR F_SETLK , +and +.B F_SETLKW +are specified in POSIX.1-2001. +.P +.B F_GETOWN +and +.B F_SETOWN +are specified in POSIX.1-2001. +(To get their definitions, define either +.\" .BR _BSD_SOURCE , +.\" or +.B _XOPEN_SOURCE +with the value 500 or greater, or +.B _POSIX_C_SOURCE +with the value 200809L or greater.) +.P +.B F_DUPFD_CLOEXEC +is specified in POSIX.1-2008. +(To get this definition, define +.B _POSIX_C_SOURCE +with the value 200809L or greater, or +.B _XOPEN_SOURCE +with the value 700 or greater.) +.SH NOTES +The errors returned by +.BR dup2 (2) +are different from those returned by +.BR F_DUPFD . +.\" +.SS File locking +The original Linux +.BR fcntl () +system call was not designed to handle large file offsets +(in the +.I flock +structure). +Consequently, an +.BR fcntl64 () +system call was added in Linux 2.4. +The newer system call employs a different structure for file locking, +.IR flock64 , +and corresponding operations, +.BR F_GETLK64 , +.BR F_SETLK64 , +and +.BR F_SETLKW64 . +However, these details can be ignored by applications using glibc, whose +.BR fcntl () +wrapper function transparently employs the more recent system call +where it is available. +.\" +.SS Record locks +Since Linux 2.0, there is no interaction between the types of lock +placed by +.BR flock (2) +and +.BR fcntl (). +.P +Several systems have more fields in +.I "struct flock" +such as, for example, +.I l_sysid +(to identify the machine where the lock is held). +.\" e.g., Solaris 8 documents this field in fcntl(2), and Irix 6.5 +.\" documents it in fcntl(5). mtk, May 2007 +.\" Also, FreeBSD documents it (Apr 2014). +Clearly, +.I l_pid +alone is not going to be very useful if the process holding the lock +may live on a different machine; +on Linux, while present on some architectures (such as MIPS32), +this field is not used. +.P +The original Linux +.BR fcntl () +system call was not designed to handle large file offsets +(in the +.I flock +structure). +Consequently, an +.BR fcntl64 () +system call was added in Linux 2.4. +The newer system call employs a different structure for file locking, +.IR flock64 , +and corresponding operations, +.BR F_GETLK64 , +.BR F_SETLK64 , +and +.BR F_SETLKW64 . +However, these details can be ignored by applications using glibc, whose +.BR fcntl () +wrapper function transparently employs the more recent system call +where it is available. +.SS Record locking and NFS +Before Linux 3.12, if an NFSv4 client +loses contact with the server for a period of time +(defined as more than 90 seconds with no communication), +.\" +.\" Neil Brown: With NFSv3 the failure mode is the reverse. If +.\" the server loses contact with a client then any lock stays in place +.\" indefinitely ("why can't I read my mail"... I remember it well). +.\" +it might lose and regain a lock without ever being aware of the fact. +(The period of time after which contact is assumed lost is known as +the NFSv4 leasetime. +On a Linux NFS server, this can be determined by looking at +.IR /proc/fs/nfsd/nfsv4leasetime , +which expresses the period in seconds. +The default value for this file is 90.) +.\" +.\" Jeff Layton: +.\" Note that this is not a firm timeout. The server runs a job +.\" periodically to clean out expired stateful objects, and it's likely +.\" that there is some time (maybe even up to another whole lease period) +.\" between when the timeout expires and the job actually runs. If the +.\" client gets a RENEW in there within that window, its lease will be +.\" renewed and its state preserved. +.\" +This scenario potentially risks data corruption, +since another process might acquire a lock in the intervening period +and perform file I/O. +.P +Since Linux 3.12, +.\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d +if an NFSv4 client loses contact with the server, +any I/O to the file by a process which "thinks" it holds +a lock will fail until that process closes and reopens the file. +A kernel parameter, +.IR nfs.recover_lost_locks , +can be set to 1 to obtain the pre-3.12 behavior, +whereby the client will attempt to recover lost locks +when contact is reestablished with the server. +Because of the attendant risk of data corruption, +.\" commit f6de7a39c181dfb8a2c534661a53c73afb3081cd +this parameter defaults to 0 (disabled). +.SH BUGS +.SS F_SETFL +It is not possible to use +.B F_SETFL +to change the state of the +.B O_DSYNC +and +.B O_SYNC +flags. +.\" FIXME . According to POSIX.1-2001, O_SYNC should also be modifiable +.\" via fcntl(2), but currently Linux does not permit this +.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5994 +Attempts to change the state of these flags are silently ignored. +.SS F_GETOWN +A limitation of the Linux system call conventions on some +architectures (notably i386) means that if a (negative) +process group ID to be returned by +.B F_GETOWN +falls in the range \-1 to \-4095, then the return value is wrongly +interpreted by glibc as an error in the system call; +.\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h +that is, the return value of +.BR fcntl () +will be \-1, and +.I errno +will contain the (positive) process group ID. +The Linux-specific +.B F_GETOWN_EX +operation avoids this problem. +.\" mtk, Dec 04: some limited testing on alpha and ia64 seems to +.\" indicate that ANY negative PGID value will cause F_GETOWN +.\" to misinterpret the return as an error. Some other architectures +.\" seem to have the same range check as i386. +Since glibc 2.11, glibc makes the kernel +.B F_GETOWN +problem invisible by implementing +.B F_GETOWN +using +.BR F_GETOWN_EX . +.SS F_SETOWN +In Linux 2.4 and earlier, there is bug that can occur +when an unprivileged process uses +.B F_SETOWN +to specify the owner +of a socket file descriptor +as a process (group) other than the caller. +In this case, +.BR fcntl () +can return \-1 with +.I errno +set to +.BR EPERM , +even when the owner process (group) is one that the caller +has permission to send signals to. +Despite this error return, the file descriptor owner is set, +and signals will be sent to the owner. +.\" +.SS Deadlock detection +The deadlock-detection algorithm employed by the kernel when dealing with +.B F_SETLKW +requests can yield both +false negatives (failures to detect deadlocks, +leaving a set of deadlocked processes blocked indefinitely) +and false positives +.RB ( EDEADLK +errors when there is no deadlock). +For example, +the kernel limits the lock depth of its dependency search to 10 steps, +meaning that circular deadlock chains that exceed +that size will not be detected. +In addition, the kernel may falsely indicate a deadlock +when two or more processes created using the +.BR clone (2) +.B CLONE_FILES +flag place locks that appear (to the kernel) to conflict. +.\" +.SS Mandatory locking +The Linux implementation of mandatory locking +is subject to race conditions which render it unreliable: +.\" http://marc.info/?l=linux-kernel&m=119013491707153&w=2 +.\" +.\" Reconfirmed by Jeff Layton +.\" From: Jeff Layton redhat.com> +.\" Subject: Re: Status of fcntl() mandatory locking +.\" Newsgroups: gmane.linux.file-systems +.\" Date: 2014-04-28 10:07:57 GMT +.\" http://thread.gmane.org/gmane.linux.file-systems/84481/focus=84518 +a +.BR write (2) +call that overlaps with a lock may modify data after the mandatory lock is +acquired; +a +.BR read (2) +call that overlaps with a lock may detect changes to data that were made +only after a write lock was acquired. +Similar races exist between mandatory locks and +.BR mmap (2). +It is therefore inadvisable to rely on mandatory locking. +.SH SEE ALSO +.BR dup2 (2), +.BR flock (2), +.BR open (2), +.BR socket (2), +.BR lockf (3), +.BR capabilities (7), +.BR feature_test_macros (7), +.BR lslocks (8) +.P +.IR locks.txt , +.IR mandatory\-locking.txt , +and +.I dnotify.txt +in the Linux kernel source directory +.I Documentation/filesystems/ +(on older kernels, these files are directly under the +.I Documentation/ +directory, and +.I mandatory\-locking.txt +is called +.IR mandatory.txt ) diff --git a/man/man2/fcntl64.2 b/man/man2/fcntl64.2 new file mode 100644 index 0000000..fc8ddc1 --- /dev/null +++ b/man/man2/fcntl64.2 @@ -0,0 +1 @@ +.so man2/fcntl.2 diff --git a/man/man2/fdatasync.2 b/man/man2/fdatasync.2 new file mode 100644 index 0000000..3c7494f --- /dev/null +++ b/man/man2/fdatasync.2 @@ -0,0 +1 @@ +.so man2/fsync.2 diff --git a/man/man2/fdetach.2 b/man/man2/fdetach.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/fdetach.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/fgetxattr.2 b/man/man2/fgetxattr.2 new file mode 100644 index 0000000..d9e5d90 --- /dev/null +++ b/man/man2/fgetxattr.2 @@ -0,0 +1 @@ +.so man2/getxattr.2 diff --git a/man/man2/finit_module.2 b/man/man2/finit_module.2 new file mode 100644 index 0000000..20c5c51 --- /dev/null +++ b/man/man2/finit_module.2 @@ -0,0 +1 @@ +.so man2/init_module.2 diff --git a/man/man2/flistxattr.2 b/man/man2/flistxattr.2 new file mode 100644 index 0000000..117bd2b --- /dev/null +++ b/man/man2/flistxattr.2 @@ -0,0 +1 @@ +.so man2/listxattr.2 diff --git a/man/man2/flock.2 b/man/man2/flock.2 new file mode 100644 index 0000000..e376c22 --- /dev/null +++ b/man/man2/flock.2 @@ -0,0 +1,267 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and +.\" and Copyright 2002 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Fri Jan 31 16:26:07 1997 by Eric S. Raymond +.\" Modified Fri Dec 11 17:57:27 1998 by Jamie Lokier +.\" Modified 24 Apr 2002 by Michael Kerrisk +.\" Substantial rewrites and additions +.\" 2005-05-10 mtk, noted that lock conversions are not atomic. +.\" +.\" FIXME Maybe document LOCK_MAND, LOCK_RW, LOCK_READ, LOCK_WRITE +.\" which only have effect for SAMBA. +.\" +.TH flock 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +flock \- apply or remove an advisory lock on an open file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int flock(int " fd ", int " op ); +.fi +.SH DESCRIPTION +Apply or remove an advisory lock on the open file specified by +.IR fd . +The argument +.I op +is one of the following: +.RS 4 +.TP 9 +.B LOCK_SH +Place a shared lock. +More than one process may hold a shared lock for a given file +at a given time. +.TP +.B LOCK_EX +Place an exclusive lock. +Only one process may hold an exclusive lock for a given +file at a given time. +.TP +.B LOCK_UN +Remove an existing lock held by this process. +.RE +.P +A call to +.BR flock () +may block if an incompatible lock is held by another process. +To make a nonblocking request, include +.B LOCK_NB +(by ORing) +with any of the above operations. +.P +A single file may not simultaneously have both shared and exclusive locks. +.P +Locks created by +.BR flock () +are associated with an open file description (see +.BR open (2)). +This means that duplicate file descriptors (created by, for example, +.BR fork (2) +or +.BR dup (2)) +refer to the same lock, and this lock may be modified +or released using any of these file descriptors. +Furthermore, the lock is released either by an explicit +.B LOCK_UN +operation on any of these duplicate file descriptors, or when all +such file descriptors have been closed. +.P +If a process uses +.BR open (2) +(or similar) to obtain more than one file descriptor for the same file, +these file descriptors are treated independently by +.BR flock (). +An attempt to lock the file using one of these file descriptors +may be denied by a lock that the calling process has +already placed via another file descriptor. +.P +A process may hold only one type of lock (shared or exclusive) +on a file. +Subsequent +.BR flock () +calls on an already locked file will convert an existing lock to the new +lock mode. +.P +Locks created by +.BR flock () +are preserved across an +.BR execve (2). +.P +A shared or exclusive lock can be placed on a file regardless of the +mode in which the file was opened. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EINTR +While waiting to acquire a lock, the call was interrupted by +delivery of a signal caught by a handler; see +.BR signal (7). +.TP +.B EINVAL +.I op +is invalid. +.TP +.B ENOLCK +The kernel ran out of memory for allocating lock records. +.TP +.B EWOULDBLOCK +The file is locked and the +.B LOCK_NB +flag was selected. +.SH VERSIONS +Since Linux 2.0, +.BR flock () +is implemented as a system call in its own right rather +than being emulated in the GNU C library as a call to +.BR fcntl (2). +With this implementation, +there is no interaction between the types of lock +placed by +.BR flock () +and +.BR fcntl (2), +and +.BR flock () +does not detect deadlock. +(Note, however, that on some systems, such as the modern BSDs, +.\" E.g., according to the flock(2) man page, FreeBSD since at least 5.3 +.BR flock () +and +.BR fcntl (2) +locks +.I do +interact with one another.) +.SS CIFS details +Up to Linux 5.4, +.BR flock () +is not propagated over SMB. +A file with such locks will not appear locked for remote clients. +.P +Since Linux 5.5, +.BR flock () +locks are emulated with SMB byte-range locks on the entire file. +Similarly to NFS, this means that +.BR fcntl (2) +and +.BR flock () +locks interact with one another. +Another important side-effect is that the locks are not advisory anymore: +any IO on a locked file will always fail with +.B EACCES +when done from a separate file descriptor. +This difference originates from the design of locks in the SMB protocol, +which provides mandatory locking semantics. +.P +Remote and mandatory locking semantics may vary with +SMB protocol, mount options and server type. +See +.BR mount.cifs (8) +for additional information. +.SH STANDARDS +BSD. +.SH HISTORY +4.4BSD (the +.BR flock () +call first appeared in 4.2BSD). +A version of +.BR flock (), +possibly implemented in terms of +.BR fcntl (2), +appears on most UNIX systems. +.SS NFS details +Up to Linux 2.6.11, +.BR flock () +does not lock files over NFS +(i.e., the scope of locks was limited to the local system). +Instead, one could use +.BR fcntl (2) +byte-range locking, which does work over NFS, +given a sufficiently recent version of +Linux and a server which supports locking. +.P +Since Linux 2.6.12, NFS clients support +.BR flock () +locks by emulating them as +.BR fcntl (2) +byte-range locks on the entire file. +This means that +.BR fcntl (2) +and +.BR flock () +locks +.I do +interact with one another over NFS. +It also means that in order to place an exclusive lock, +the file must be opened for writing. +.P +Since Linux 2.6.37, +.\" commit 5eebde23223aeb0ad2d9e3be6590ff8bbfab0fc2 +the kernel supports a compatibility mode that allows +.BR flock () +locks (and also +.BR fcntl (2) +byte region locks) to be treated as local; +see the discussion of the +.I "local_lock" +option in +.BR nfs (5). +.SH NOTES +.BR flock () +places advisory locks only; given suitable permissions on a file, +a process is free to ignore the use of +.BR flock () +and perform I/O on the file. +.P +.BR flock () +and +.BR fcntl (2) +locks have different semantics with respect to forked processes and +.BR dup (2). +On systems that implement +.BR flock () +using +.BR fcntl (2), +the semantics of +.BR flock () +will be different from those described in this manual page. +.P +Converting a lock +(shared to exclusive, or vice versa) is not guaranteed to be atomic: +the existing lock is first removed, and then a new lock is established. +Between these two steps, +a pending lock request by another process may be granted, +with the result that the conversion either blocks, or fails if +.B LOCK_NB +was specified. +(This is the original BSD behavior, +and occurs on many other implementations.) +.\" Kernel 2.5.21 changed things a little: during lock conversion +.\" it is now the highest priority process that will get the lock -- mtk +.SH SEE ALSO +.BR flock (1), +.BR close (2), +.BR dup (2), +.BR execve (2), +.BR fcntl (2), +.BR fork (2), +.BR open (2), +.BR lockf (3), +.BR lslocks (8) +.P +.I Documentation/filesystems/locks.txt +in the Linux kernel source tree +.RI ( Documentation/locks.txt +in older kernels) diff --git a/man/man2/fork.2 b/man/man2/fork.2 new file mode 100644 index 0000000..4857165 --- /dev/null +++ b/man/man2/fork.2 @@ -0,0 +1,349 @@ +.\" Copyright (C) 2006 Michael Kerrisk +.\" A few fragments remain from an earlier (1992) page by +.\" Drew Eckhardt (drew@cs.colorado.edu), +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified Sat Jul 24 13:22:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 21 Aug 1994 by Michael Chastain (mec@shell.portal.com): +.\" Referenced 'clone(2)'. +.\" Modified 1995-06-10, 1996-04-18, 1999-11-01, 2000-12-24 +.\" by Andries Brouwer (aeb@cwi.nl) +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" 2006-09-04, Michael Kerrisk +.\" Greatly expanded, to describe all attributes that differ +.\" parent and child. +.\" +.TH fork 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fork \- create a child process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B pid_t fork(void); +.fi +.SH DESCRIPTION +.BR fork () +creates a new process by duplicating the calling process. +The new process is referred to as the +.I child +process. +The calling process is referred to as the +.I parent +process. +.P +The child process and the parent process run in separate memory spaces. +At the time of +.BR fork () +both memory spaces have the same content. +Memory writes, file mappings +.RB ( mmap (2)), +and unmappings +.RB ( munmap (2)) +performed by one of the processes do not affect the other. +.P +The child process is an exact duplicate of the parent +process except for the following points: +.IP \[bu] 3 +The child has its own unique process ID, +and this PID does not match the ID of any existing process group +.RB ( setpgid (2)) +or session. +.IP \[bu] +The child's parent process ID is the same as the parent's process ID. +.IP \[bu] +The child does not inherit its parent's memory locks +.RB ( mlock (2), +.BR mlockall (2)). +.IP \[bu] +Process resource utilizations +.RB ( getrusage (2)) +and CPU time counters +.RB ( times (2)) +are reset to zero in the child. +.IP \[bu] +The child's set of pending signals is initially empty +.RB ( sigpending (2)). +.IP \[bu] +The child does not inherit semaphore adjustments from its parent +.RB ( semop (2)). +.IP \[bu] +The child does not inherit process-associated record locks from its parent +.RB ( fcntl (2)). +(On the other hand, it does inherit +.BR fcntl (2) +open file description locks and +.BR flock (2) +locks from its parent.) +.IP \[bu] +The child does not inherit timers from its parent +.RB ( setitimer (2), +.BR alarm (2), +.BR timer_create (2)). +.IP \[bu] +The child does not inherit outstanding asynchronous I/O operations +from its parent +.RB ( aio_read (3), +.BR aio_write (3)), +nor does it inherit any asynchronous I/O contexts from its parent (see +.BR io_setup (2)). +.P +The process attributes in the preceding list are all specified +in POSIX.1. +The parent and child also differ with respect to the following +Linux-specific process attributes: +.IP \[bu] 3 +The child does not inherit directory change notifications (dnotify) +from its parent +(see the description of +.B F_NOTIFY +in +.BR fcntl (2)). +.IP \[bu] +The +.BR prctl (2) +.B PR_SET_PDEATHSIG +setting is reset so that the child does not receive a signal +when its parent terminates. +.IP \[bu] +The default timer slack value is set to the parent's +current timer slack value. +See the description of +.B PR_SET_TIMERSLACK +in +.BR prctl (2). +.IP \[bu] +Memory mappings that have been marked with the +.BR madvise (2) +.B MADV_DONTFORK +flag are not inherited across a +.BR fork (). +.IP \[bu] +Memory in address ranges that have been marked with the +.BR madvise (2) +.B MADV_WIPEONFORK +flag is zeroed in the child after a +.BR fork (). +(The +.B MADV_WIPEONFORK +setting remains in place for those address ranges in the child.) +.IP \[bu] +The termination signal of the child is always +.B SIGCHLD +(see +.BR clone (2)). +.IP \[bu] +The port access permission bits set by +.BR ioperm (2) +are not inherited by the child; +the child must turn on any bits that it requires using +.BR ioperm (2). +.P +Note the following further points: +.IP \[bu] 3 +The child process is created with a single thread\[em]the +one that called +.BR fork (). +The entire virtual address space of the parent is replicated in the child, +including the states of mutexes, condition variables, +and other pthreads objects; the use of +.BR pthread_atfork (3) +may be helpful for dealing with problems that this can cause. +.IP \[bu] +After a +.BR fork () +in a multithreaded program, +the child can safely call only async-signal-safe functions (see +.BR signal\-safety (7)) +until such time as it calls +.BR execve (2). +.IP \[bu] +The child inherits copies of the parent's set of open file descriptors. +Each file descriptor in the child refers to the same +open file description (see +.BR open (2)) +as the corresponding file descriptor in the parent. +This means that the two file descriptors share open file status flags, +file offset, +and signal-driven I/O attributes (see the description of +.B F_SETOWN +and +.B F_SETSIG +in +.BR fcntl (2)). +.IP \[bu] +The child inherits copies of the parent's set of open message +queue descriptors (see +.BR mq_overview (7)). +Each file descriptor in the child refers to the same +open message queue description +as the corresponding file descriptor in the parent. +This means that the two file descriptors share the same flags +.RI ( mq_flags ). +.IP \[bu] +The child inherits copies of the parent's set of open directory streams (see +.BR opendir (3)). +POSIX.1 says that the corresponding directory streams +in the parent and child +.I may +share the directory stream positioning; +on Linux/glibc they do not. +.SH RETURN VALUE +On success, the PID of the child process is returned in the parent, +and 0 is returned in the child. +On failure, \-1 is returned in the parent, +no child process is created, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +.\" NOTE! The following should match the description in pthread_create(3) +A system-imposed limit on the number of threads was encountered. +There are a number of limits that may trigger this error: +.RS +.IP \[bu] 3 +the +.B RLIMIT_NPROC +soft resource limit (set via +.BR setrlimit (2)), +which limits the number of processes and threads for a real user ID, +was reached; +.IP \[bu] +the kernel's system-wide limit on the number of processes and threads, +.IR /proc/sys/kernel/threads\-max , +was reached (see +.BR proc (5)); +.IP \[bu] +the maximum number of PIDs, +.IR /proc/sys/kernel/pid_max , +was reached (see +.BR proc (5)); +or +.IP \[bu] +the PID limit +.RI ( pids.max ) +imposed by the cgroup "process number" (PIDs) controller was reached. +.RE +.TP +.B EAGAIN +The caller is operating under the +.B SCHED_DEADLINE +scheduling policy and does not have the reset-on-fork flag set. +See +.BR sched (7). +.TP +.B ENOMEM +.BR fork () +failed to allocate the necessary kernel structures because memory is tight. +.TP +.B ENOMEM +An attempt was made to create a child process in a PID namespace +whose "init" process has terminated. +See +.BR pid_namespaces (7). +.TP +.B ENOSYS +.BR fork () +is not supported on this platform (for example, +.\" e.g., arm (optionally), blackfin, c6x, frv, h8300, microblaze, xtensa +hardware without a Memory-Management Unit). +.TP +.BR ERESTARTNOINTR " (since Linux 2.6.17)" +.\" commit 4a2c7a7837da1b91468e50426066d988050e4d56 +System call was interrupted by a signal and will be restarted. +(This can be seen only during a trace.) +.SH VERSIONS +.SS C library/kernel differences +Since glibc 2.3.3, +.\" nptl/sysdeps/unix/sysv/linux/fork.c +rather than invoking the kernel's +.BR fork () +system call, +the glibc +.BR fork () +wrapper that is provided as part of the +NPTL threading implementation invokes +.BR clone (2) +with flags that provide the same effect as the traditional system call. +(A call to +.BR fork () +is equivalent to a call to +.BR clone (2) +specifying +.I flags +as just +.BR SIGCHLD .) +The glibc wrapper invokes any fork handlers that have been +established using +.BR pthread_atfork (3). +.\" and does some magic to ensure that getpid(2) returns the right value. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +Under Linux, +.BR fork () +is implemented using copy-on-write pages, so the only penalty that it incurs +is the time and memory required to duplicate the parent's page tables, +and to create a unique task structure for the child. +.SH EXAMPLES +See +.BR pipe (2) +and +.BR wait (2) +for more examples. +.P +.\" SRC BEGIN (fork.c) +.EX +#include +#include +#include +#include +#include +#include +\& +int +main(void) +{ + pid_t pid; +\& + if (signal(SIGCHLD, SIG_IGN) == SIG_ERR) { + perror("signal"); + exit(EXIT_FAILURE); + } + pid = fork(); + switch (pid) { + case \-1: + perror("fork"); + exit(EXIT_FAILURE); + case 0: + puts("Child exiting."); + exit(EXIT_SUCCESS); + default: + printf("Child is PID %jd\en", (intmax_t) pid); + puts("Parent exiting."); + exit(EXIT_SUCCESS); + } +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clone (2), +.BR execve (2), +.BR exit (2), +.BR setrlimit (2), +.BR unshare (2), +.BR vfork (2), +.BR wait (2), +.BR daemon (3), +.BR pthread_atfork (3), +.BR capabilities (7), +.BR credentials (7) diff --git a/man/man2/free_hugepages.2 b/man/man2/free_hugepages.2 new file mode 100644 index 0000000..d4b906a --- /dev/null +++ b/man/man2/free_hugepages.2 @@ -0,0 +1 @@ +.so man2/alloc_hugepages.2 diff --git a/man/man2/fremovexattr.2 b/man/man2/fremovexattr.2 new file mode 100644 index 0000000..38d01cc --- /dev/null +++ b/man/man2/fremovexattr.2 @@ -0,0 +1 @@ +.so man2/removexattr.2 diff --git a/man/man2/fsetxattr.2 b/man/man2/fsetxattr.2 new file mode 100644 index 0000000..dc07807 --- /dev/null +++ b/man/man2/fsetxattr.2 @@ -0,0 +1 @@ +.so man2/setxattr.2 diff --git a/man/man2/fstat.2 b/man/man2/fstat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man/man2/fstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man/man2/fstat64.2 b/man/man2/fstat64.2 new file mode 100644 index 0000000..2b9971d --- /dev/null +++ b/man/man2/fstat64.2 @@ -0,0 +1 @@ +.so man2/fstat.2 diff --git a/man/man2/fstatat.2 b/man/man2/fstatat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man/man2/fstatat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man/man2/fstatat64.2 b/man/man2/fstatat64.2 new file mode 100644 index 0000000..7791269 --- /dev/null +++ b/man/man2/fstatat64.2 @@ -0,0 +1 @@ +.so man2/fstatat.2 diff --git a/man/man2/fstatfs.2 b/man/man2/fstatfs.2 new file mode 100644 index 0000000..923d3c0 --- /dev/null +++ b/man/man2/fstatfs.2 @@ -0,0 +1 @@ +.so man2/statfs.2 diff --git a/man/man2/fstatfs64.2 b/man/man2/fstatfs64.2 new file mode 100644 index 0000000..fde2b22 --- /dev/null +++ b/man/man2/fstatfs64.2 @@ -0,0 +1 @@ +.so man2/fstatfs.2 diff --git a/man/man2/fsync.2 b/man/man2/fsync.2 new file mode 100644 index 0000000..8817ea1 --- /dev/null +++ b/man/man2/fsync.2 @@ -0,0 +1,200 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and +.\" and Copyright 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" Removed note about old libc (pre-4.5.26) translating to 'sync'. +.\" Modified 15 Apr 1995 by Michael Chastain : +.\" Added `see also' section. +.\" Modified 13 Apr 1996 by Markus Kuhn +.\" Added remarks about fdatasync. +.\" Modified 31 Jan 1997 by Eric S. Raymond +.\" Modified 18 Apr 2001 by Andi Kleen +.\" Fix description to describe what it really does; add a few caveats. +.\" 2006-04-28, mtk, substantial rewrite of various parts. +.\" 2012-02-27 Various changes by Christoph Hellwig +.\" +.TH fsync 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fsync, fdatasync \- synchronize a file's in-core state with storage device +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fsync(int " fd ); +.P +.BI "int fdatasync(int " fd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.nf +.BR fsync (): + glibc 2.16 and later: + No feature test macros need be defined + glibc up to and including 2.15: + _BSD_SOURCE || _XOPEN_SOURCE + || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L +.fi +.P +.BR fdatasync (): +.nf + _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500 +.fi +.SH DESCRIPTION +.BR fsync () +transfers ("flushes") all modified in-core data of +(i.e., modified buffer cache pages for) the +file referred to by the file descriptor +.I fd +to the disk device (or other permanent storage device) so that all +changed information can be retrieved even if the system crashes or +is rebooted. +This includes writing through or flushing a disk cache if present. +The call blocks until the device reports that the transfer has completed. +.P +As well as flushing the file data, +.BR fsync () +also flushes the metadata information associated with the file (see +.BR inode (7)). +.P +Calling +.BR fsync () +does not necessarily ensure +that the entry in the directory containing the file has also reached disk. +For that an explicit +.BR fsync () +on a file descriptor for the directory is also needed. +.P +.BR fdatasync () +is similar to +.BR fsync (), +but does not flush modified metadata unless that metadata +is needed in order to allow a subsequent data retrieval to be +correctly handled. +For example, changes to +.I st_atime +or +.I st_mtime +(respectively, time of last access and +time of last modification; see +.BR inode (7)) +do not require flushing because they are not necessary for +a subsequent data read to be handled correctly. +On the other hand, a change to the file size +.RI ( st_size , +as made by say +.BR ftruncate (2)), +would require a metadata flush. +.P +The aim of +.BR fdatasync () +is to reduce disk activity for applications that do not +require all metadata to be synchronized with the disk. +.SH RETURN VALUE +On success, these system calls return zero. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid open file descriptor. +.TP +.B EINTR +The function was interrupted by a signal; see +.BR signal (7). +.TP +.B EIO +An error occurred during synchronization. +This error may relate to data written to some other file descriptor +on the same file. +Since Linux 4.13, +.\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750 +errors from write-back will be reported to +all file descriptors that might have written the data which triggered +the error. +Some filesystems (e.g., NFS) keep close track of which data +came through which file descriptor, and give more precise reporting. +Other filesystems (e.g., most local filesystems) will report errors to +all file descriptors that were open on the file when the error was recorded. +.TP +.B ENOSPC +Disk space was exhausted while synchronizing. +.TP +.B EROFS +.TQ +.B EINVAL +.I fd +is bound to a special file (e.g., a pipe, FIFO, or socket) +which does not support synchronization. +.TP +.B ENOSPC +.TQ +.B EDQUOT +.I fd +is bound to a file on NFS or another filesystem which does not allocate +space at the time of a +.BR write (2) +system call, and some previous write failed due to insufficient +storage space. +.SH VERSIONS +On POSIX systems on which +.BR fdatasync () +is available, +.B _POSIX_SYNCHRONIZED_IO +is defined in +.I +to a value greater than 0. +(See also +.BR sysconf (3).) +.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines them to 1. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.2BSD. +.P +In Linux 2.2 and earlier, +.BR fdatasync () +is equivalent to +.BR fsync (), +and so has no performance advantage. +.P +The +.BR fsync () +implementations in older kernels and lesser used filesystems +do not know how to flush disk caches. +In these cases disk caches need to be disabled using +.BR hdparm (8) +or +.BR sdparm (8) +to guarantee safe operation. +.P +Under AT&T UNIX System V Release 4 +.I fd +needs to be opened for writing. +This is by itself incompatible with the original BSD interface +and forbidden by POSIX, +but nevertheless survives in HP-UX and AIX. +.SH SEE ALSO +.BR sync (1), +.BR bdflush (2), +.BR open (2), +.BR posix_fadvise (2), +.BR pwritev (2), +.BR sync (2), +.BR sync_file_range (2), +.BR fflush (3), +.BR fileno (3), +.BR hdparm (8), +.BR mount (8) diff --git a/man/man2/ftruncate.2 b/man/man2/ftruncate.2 new file mode 100644 index 0000000..2ed34f1 --- /dev/null +++ b/man/man2/ftruncate.2 @@ -0,0 +1 @@ +.so man2/truncate.2 diff --git a/man/man2/ftruncate64.2 b/man/man2/ftruncate64.2 new file mode 100644 index 0000000..a8862d3 --- /dev/null +++ b/man/man2/ftruncate64.2 @@ -0,0 +1 @@ +.so man2/ftruncate.2 diff --git a/man/man2/futex.2 b/man/man2/futex.2 new file mode 100644 index 0000000..f001e7b --- /dev/null +++ b/man/man2/futex.2 @@ -0,0 +1,1976 @@ +.\" Page by b.hubert +.\" and Copyright (C) 2015, Thomas Gleixner +.\" and Copyright (C) 2015, Michael Kerrisk +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" may be freely modified and distributed +.\" %%%LICENSE_END +.\" +.\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com) +.\" added ERRORS section. +.\" +.\" Modified 2004-06-17 mtk +.\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE +.\" +.\" FIXME Still to integrate are some points from Torvald Riegel's mail of +.\" 2015-01-23: +.\" http://thread.gmane.org/gmane.linux.kernel/1703405/focus=7977 +.\" +.\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail +.\" http://thread.gmane.org/gmane.linux.kernel/1703405/focus=1873242 +.\" +.TH futex 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +futex \- fast user-space locking +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.P +.BR "#include " " /* Definition of " FUTEX_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "long syscall(SYS_futex, uint32_t *" uaddr ", int " futex_op \ +", uint32_t " val , +.BI " const struct timespec *" timeout , \ +" \fR /* or: \fBuint32_t \fIval2\fP */" +.BI " uint32_t *" uaddr2 ", uint32_t " val3 ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR futex (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR futex () +system call provides a method for waiting until a certain condition becomes +true. +It is typically used as a blocking construct in the context of +shared-memory synchronization. +When using futexes, the majority of +the synchronization operations are performed in user space. +A user-space program employs the +.BR futex () +system call only when it is likely that the program has to block for +a longer time until the condition becomes true. +Other +.BR futex () +operations can be used to wake any processes or threads waiting +for a particular condition. +.P +A futex is a 32-bit value\[em]referred to below as a +.IR "futex word" \[em]whose +address is supplied to the +.BR futex () +system call. +(Futexes are 32 bits in size on all platforms, including 64-bit systems.) +All futex operations are governed by this value. +In order to share a futex between processes, +the futex is placed in a region of shared memory, +created using (for example) +.BR mmap (2) +or +.BR shmat (2). +(Thus, the futex word may have different +virtual addresses in different processes, +but these addresses all refer to the same location in physical memory.) +In a multithreaded program, it is sufficient to place the futex word +in a global variable shared by all threads. +.P +When executing a futex operation that requests to block a thread, +the kernel will block only if the futex word has the value that the +calling thread supplied (as one of the arguments of the +.BR futex () +call) as the expected value of the futex word. +The loading of the futex word's value, +the comparison of that value with the expected value, +and the actual blocking will happen atomically and will be totally ordered +with respect to concurrent operations performed by other threads +on the same futex word. +.\" Notes from Darren Hart (Dec 2015): +.\" Totally ordered with respect futex operations refers to semantics +.\" of the ACQUIRE/RELEASE operations and how they impact ordering of +.\" memory reads and writes. The kernel futex operations are protected +.\" by spinlocks, which ensure that all operations are serialized +.\" with respect to one another. +.\" +.\" This is a lot to attempt to define in this document. Perhaps a +.\" reference to linux/Documentation/memory-barriers.txt as a footnote +.\" would be sufficient? Or perhaps for this manual, "serialized" would +.\" be sufficient, with a footnote regarding "totally ordered" and a +.\" pointer to the memory-barrier documentation? +Thus, the futex word is used to connect the synchronization in user space +with the implementation of blocking by the kernel. +Analogously to an atomic +compare-and-exchange operation that potentially changes shared memory, +blocking via a futex is an atomic compare-and-block operation. +.\" FIXME(Torvald Riegel): +.\" Eventually we want to have some text in NOTES to satisfy +.\" the reference in the following sentence +.\" See NOTES for a detailed specification of +.\" the synchronization semantics. +.P +One use of futexes is for implementing locks. +The state of the lock (i.e., acquired or not acquired) +can be represented as an atomically accessed flag in shared memory. +In the uncontended case, +a thread can access or modify the lock state with atomic instructions, +for example atomically changing it from not acquired to acquired +using an atomic compare-and-exchange instruction. +(Such instructions are performed entirely in user mode, +and the kernel maintains no information about the lock state.) +On the other hand, a thread may be unable to acquire a lock because +it is already acquired by another thread. +It then may pass the lock's flag as a futex word and the value +representing the acquired state as the expected value to a +.BR futex () +wait operation. +This +.BR futex () +operation will block if and only if the lock is still acquired +(i.e., the value in the futex word still matches the "acquired state"). +When releasing the lock, a thread has to first reset the +lock state to not acquired and then execute a futex +operation that wakes threads blocked on the lock flag used as a futex word +(this can be further optimized to avoid unnecessary wake-ups). +See +.BR futex (7) +for more detail on how to use futexes. +.P +Besides the basic wait and wake-up futex functionality, there are further +futex operations aimed at supporting more complex use cases. +.P +Note that +no explicit initialization or destruction is necessary to use futexes; +the kernel maintains a futex +(i.e., the kernel-internal implementation artifact) +only while operations such as +.BR FUTEX_WAIT , +described below, are being performed on a particular futex word. +.\" +.SS Arguments +The +.I uaddr +argument points to the futex word. +On all platforms, futexes are four-byte +integers that must be aligned on a four-byte boundary. +The operation to perform on the futex is specified in the +.I futex_op +argument; +.I val +is a value whose meaning and purpose depends on +.IR futex_op . +.P +The remaining arguments +.RI ( timeout , +.IR uaddr2 , +and +.IR val3 ) +are required only for certain of the futex operations described below. +Where one of these arguments is not required, it is ignored. +.P +For several blocking operations, the +.I timeout +argument is a pointer to a +.I timespec +structure that specifies a timeout for the operation. +However, notwithstanding the prototype shown above, for some operations, +the least significant four bytes of this argument are instead +used as an integer whose meaning is determined by the operation. +For these operations, the kernel casts the +.I timeout +value first to +.IR "unsigned long", +then to +.IR uint32_t , +and in the remainder of this page, this argument is referred to as +.I val2 +when interpreted in this fashion. +.P +Where it is required, the +.I uaddr2 +argument is a pointer to a second futex word that is employed +by the operation. +.P +The interpretation of the final integer argument, +.IR val3 , +depends on the operation. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SS Futex operations +The +.I futex_op +argument consists of two parts: +a command that specifies the operation to be performed, +bitwise ORed with zero or more options that +modify the behaviour of the operation. +The options that may be included in +.I futex_op +are as follows: +.TP +.BR FUTEX_PRIVATE_FLAG " (since Linux 2.6.22)" +.\" commit 34f01cc1f512fa783302982776895c73714ebbc2 +This option bit can be employed with all futex operations. +It tells the kernel that the futex is process-private and not shared +with another process (i.e., it is being used for synchronization +only between threads of the same process). +This allows the kernel to make some additional performance optimizations. +.\" I.e., It allows the kernel choose the fast path for validating +.\" the user-space address and avoids expensive VMA lookups, +.\" taking reference counts on file backing store, and so on. +.IP +As a convenience, +.I +defines a set of constants with the suffix +.B _PRIVATE +that are equivalents of all of the operations listed below, +.\" except the obsolete FUTEX_FD, for which the "private" flag was +.\" meaningless +but with the +.B FUTEX_PRIVATE_FLAG +ORed into the constant value. +Thus, there are +.BR FUTEX_WAIT_PRIVATE , +.BR FUTEX_WAKE_PRIVATE , +and so on. +.TP +.BR FUTEX_CLOCK_REALTIME " (since Linux 2.6.28)" +.\" commit 1acdac104668a0834cfa267de9946fac7764d486 +This option bit can be employed only with the +.BR FUTEX_WAIT_BITSET , +.BR FUTEX_WAIT_REQUEUE_PI , +(since Linux 4.5) +.\" commit 337f13046ff03717a9e99675284a817527440a49 +.BR FUTEX_WAIT , +and +(since Linux 5.14) +.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae +.B FUTEX_LOCK_PI2 +operations. +.IP +If this option is set, the kernel measures the +.I timeout +against the +.B CLOCK_REALTIME +clock. +.IP +If this option is not set, the kernel measures the +.I timeout +against the +.B CLOCK_MONOTONIC +clock. +.P +The operation specified in +.I futex_op +is one of the following: +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAIT " (since Linux 2.6.0)" +.\" Strictly speaking, since some time in Linux 2.5.x +This operation tests that the value at the +futex word pointed to by the address +.I uaddr +still contains the expected value +.IR val , +and if so, then sleeps waiting for a +.B FUTEX_WAKE +operation on the futex word. +The load of the value of the futex word is an atomic memory +access (i.e., using atomic machine instructions of the respective +architecture). +This load, the comparison with the expected value, and +starting to sleep are performed atomically +.\" FIXME: Torvald, I think we may need to add some explanation of +.\" "totally ordered" here. +and totally ordered +with respect to other futex operations on the same futex word. +If the thread starts to sleep, +it is considered a waiter on this futex word. +If the futex value does not match +.IR val , +then the call fails immediately with the error +.BR EAGAIN . +.IP +The purpose of the comparison with the expected value is to prevent lost +wake-ups. +If another thread changed the value of the futex word after the +calling thread decided to block based on the prior value, +and if the other thread executed a +.B FUTEX_WAKE +operation (or similar wake-up) after the value change and before this +.B FUTEX_WAIT +operation, then the calling thread will observe the +value change and will not start to sleep. +.IP +If the +.I timeout +is not NULL, the structure it points to specifies a +timeout for the wait. +(This interval will be rounded up to the system clock granularity, +and is guaranteed not to expire early.) +The timeout is by default measured according to the +.B CLOCK_MONOTONIC +clock, but, since Linux 4.5, the +.B CLOCK_REALTIME +clock can be selected by specifying +.B FUTEX_CLOCK_REALTIME +in +.IR futex_op . +If +.I timeout +is NULL, the call blocks indefinitely. +.IP +.IR Note : +for +.BR FUTEX_WAIT , +.I timeout +is interpreted as a +.I relative +value. +This differs from other futex operations, where +.I timeout +is interpreted as an absolute value. +To obtain the equivalent of +.B FUTEX_WAIT +with an absolute timeout, employ +.B FUTEX_WAIT_BITSET +with +.I val3 +specified as +.BR FUTEX_BITSET_MATCH_ANY . +.IP +The arguments +.I uaddr2 +and +.I val3 +are ignored. +.\" FIXME . (Torvald) I think we should remove this. Or maybe adapt to a +.\" different example. +.\" +.\" For +.\" .BR futex (7), +.\" this call is executed if decrementing the count gave a negative value +.\" (indicating contention), +.\" and will sleep until another process or thread releases +.\" the futex and executes the +.\" .B FUTEX_WAKE +.\" operation. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAKE " (since Linux 2.6.0)" +.\" Strictly speaking, since Linux 2.5.x +This operation wakes at most +.I val +of the waiters that are waiting (e.g., inside +.BR FUTEX_WAIT ) +on the futex word at the address +.IR uaddr . +Most commonly, +.I val +is specified as either 1 (wake up a single waiter) or +.B INT_MAX +(wake up all waiters). +No guarantee is provided about which waiters are awoken +(e.g., a waiter with a higher scheduling priority is not guaranteed +to be awoken in preference to a waiter with a lower priority). +.IP +The arguments +.IR timeout , +.IR uaddr2 , +and +.I val3 +are ignored. +.\" FIXME . (Torvald) I think we should remove this. Or maybe adapt to +.\" a different example. +.\" +.\" For +.\" .BR futex (7), +.\" this is executed if incrementing the count showed that +.\" there were waiters, +.\" once the futex value has been set to 1 +.\" (indicating that it is available). +.\" +.\" How does "incrementing the count show that there were waiters"? +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_FD " (from Linux 2.6.0 up to and including Linux 2.6.25)" +.\" Strictly speaking, from Linux 2.5.x to Linux 2.6.25 +This operation creates a file descriptor that is associated with +the futex at +.IR uaddr . +The caller must close the returned file descriptor after use. +When another process or thread performs a +.B FUTEX_WAKE +on the futex word, the file descriptor indicates as being readable with +.BR select (2), +.BR poll (2), +and +.BR epoll (7) +.IP +The file descriptor can be used to obtain asynchronous notifications: if +.I val +is nonzero, then, when another process or thread executes a +.BR FUTEX_WAKE , +the caller will receive the signal number that was passed in +.IR val . +.IP +The arguments +.IR timeout , +.IR uaddr2 , +and +.I val3 +are ignored. +.IP +Because it was inherently racy, +.B FUTEX_FD +has been removed +.\" commit 82af7aca56c67061420d618cc5a30f0fd4106b80 +from Linux 2.6.26 onward. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_REQUEUE " (since Linux 2.6.0)" +This operation performs the same task as +.B FUTEX_CMP_REQUEUE +(see below), except that no check is made using the value in +.IR val3 . +(The argument +.I val3 +is ignored.) +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)" +This operation first checks whether the location +.I uaddr +still contains the value +.IR val3 . +If not, the operation fails with the error +.BR EAGAIN . +Otherwise, the operation wakes up a maximum of +.I val +waiters that are waiting on the futex at +.IR uaddr . +If there are more than +.I val +waiters, then the remaining waiters are removed +from the wait queue of the source futex at +.I uaddr +and added to the wait queue of the target futex at +.IR uaddr2 . +The +.I val2 +argument specifies an upper limit on the number of waiters +that are requeued to the futex at +.IR uaddr2 . +.IP +.\" FIXME(Torvald) Is the following correct? Or is just the decision +.\" which threads to wake or requeue part of the atomic operation? +The load from +.I uaddr +is an atomic memory access (i.e., using atomic machine instructions of +the respective architecture). +This load, the comparison with +.IR val3 , +and the requeueing of any waiters are performed atomically and totally +ordered with respect to other operations on the same futex word. +.\" Notes from a f2f conversation with Thomas Gleixner (Aug 2015): ### +.\" The operation is serialized with respect to operations on both +.\" source and target futex. No other waiter can enqueue itself +.\" for waiting and no other waiter can dequeue itself because of +.\" a timeout or signal. +.IP +Typical values to specify for +.I val +are 0 or 1. +(Specifying +.B INT_MAX +is not useful, because it would make the +.B FUTEX_CMP_REQUEUE +operation equivalent to +.BR FUTEX_WAKE .) +The limit value specified via +.I val2 +is typically either 1 or +.BR INT_MAX . +(Specifying the argument as 0 is not useful, because it would make the +.B FUTEX_CMP_REQUEUE +operation equivalent to +.BR FUTEX_WAIT .) +.IP +The +.B FUTEX_CMP_REQUEUE +operation was added as a replacement for the earlier +.BR FUTEX_REQUEUE . +The difference is that the check of the value at +.I uaddr +can be used to ensure that requeueing happens only under certain +conditions, which allows race conditions to be avoided in certain use cases. +.\" But, as Rich Felker points out, there remain valid use cases for +.\" FUTEX_REQUEUE, for example, when the calling thread is requeuing +.\" the target(s) to a lock that the calling thread owns +.\" From: Rich Felker +.\" Date: Wed, 29 Oct 2014 22:43:17 -0400 +.\" To: Darren Hart +.\" CC: libc-alpha@sourceware.org, ... +.\" Subject: Re: Add futex wrapper to glibc? +.IP +Both +.B FUTEX_REQUEUE +and +.B FUTEX_CMP_REQUEUE +can be used to avoid "thundering herd" wake-ups that could occur when using +.B FUTEX_WAKE +in cases where all of the waiters that are woken need to acquire +another futex. +Consider the following scenario, +where multiple waiter threads are waiting on B, +a wait queue implemented using a futex: +.IP +.in +4n +.EX +lock(A) +while (!check_value(V)) { + unlock(A); + block_on(B); + lock(A); +}; +unlock(A); +.EE +.in +.IP +If a waker thread used +.BR FUTEX_WAKE , +then all waiters waiting on B would be woken up, +and they would all try to acquire lock A. +However, waking all of the threads in this manner would be pointless because +all except one of the threads would immediately block on lock A again. +By contrast, a requeue operation wakes just one waiter and moves +the other waiters to lock A, +and when the woken waiter unlocks A then the next waiter can proceed. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAKE_OP " (since Linux 2.6.14)" +.\" commit 4732efbeb997189d9f9b04708dc26bf8613ed721 +.\" Author: Jakub Jelinek +.\" Date: Tue Sep 6 15:16:25 2005 -0700 +.\" FIXME. (Torvald) The glibc condvar implementation is currently being +.\" revised (e.g., to not use an internal lock anymore). +.\" It is probably more future-proof to remove this paragraph. +.\" [Torvald, do you have an update here?] +This operation was added to support some user-space use cases +where more than one futex must be handled at the same time. +The most notable example is the implementation of +.BR pthread_cond_signal (3), +which requires operations on two futexes, +the one used to implement the mutex and the one used in the implementation +of the wait queue associated with the condition variable. +.B FUTEX_WAKE_OP +allows such cases to be implemented without leading to +high rates of contention and context switching. +.IP +The +.B FUTEX_WAKE_OP +operation is equivalent to executing the following code atomically +and totally ordered with respect to other futex operations on +any of the two supplied futex words: +.IP +.in +4n +.EX +uint32_t oldval = *(uint32_t *) uaddr2; +*(uint32_t *) uaddr2 = oldval \fIop\fP \fIoparg\fP; +futex(uaddr, FUTEX_WAKE, val, 0, 0, 0); +if (oldval \fIcmp\fP \fIcmparg\fP) + futex(uaddr2, FUTEX_WAKE, val2, 0, 0, 0); +.EE +.in +.IP +In other words, +.B FUTEX_WAKE_OP +does the following: +.RS +.IP \[bu] 3 +saves the original value of the futex word at +.I uaddr2 +and performs an operation to modify the value of the futex at +.IR uaddr2 ; +this is an atomic read-modify-write memory access (i.e., using atomic +machine instructions of the respective architecture) +.IP \[bu] +wakes up a maximum of +.I val +waiters on the futex for the futex word at +.IR uaddr ; +and +.IP \[bu] +dependent on the results of a test of the original value of the +futex word at +.IR uaddr2 , +wakes up a maximum of +.I val2 +waiters on the futex for the futex word at +.IR uaddr2 . +.RE +.IP +The operation and comparison that are to be performed are encoded +in the bits of the argument +.IR val3 . +Pictorially, the encoding is: +.IP +.in +4n +.EX ++---+---+-----------+-----------+ +|op |cmp| oparg | cmparg | ++---+---+-----------+-----------+ + 4 4 12 12 <== # of bits +.EE +.in +.IP +Expressed in code, the encoding is: +.IP +.in +4n +.EX +#define FUTEX_OP(op, oparg, cmp, cmparg) \e + (((op & 0xf) << 28) | \e + ((cmp & 0xf) << 24) | \e + ((oparg & 0xfff) << 12) | \e + (cmparg & 0xfff)) +.EE +.in +.IP +In the above, +.I op +and +.I cmp +are each one of the codes listed below. +The +.I oparg +and +.I cmparg +components are literal numeric values, except as noted below. +.IP +The +.I op +component has one of the following values: +.IP +.in +4n +.EX +FUTEX_OP_SET 0 /* uaddr2 = oparg; */ +FUTEX_OP_ADD 1 /* uaddr2 += oparg; */ +FUTEX_OP_OR 2 /* uaddr2 |= oparg; */ +FUTEX_OP_ANDN 3 /* uaddr2 &= \[ti]oparg; */ +FUTEX_OP_XOR 4 /* uaddr2 \[ha]= oparg; */ +.EE +.in +.IP +In addition, bitwise ORing the following value into +.I op +causes +.I (1\~<<\~oparg) +to be used as the operand: +.IP +.in +4n +.EX +FUTEX_OP_ARG_SHIFT 8 /* Use (1 << oparg) as operand */ +.EE +.in +.IP +The +.I cmp +field is one of the following: +.IP +.in +4n +.EX +FUTEX_OP_CMP_EQ 0 /* if (oldval == cmparg) wake */ +FUTEX_OP_CMP_NE 1 /* if (oldval != cmparg) wake */ +FUTEX_OP_CMP_LT 2 /* if (oldval < cmparg) wake */ +FUTEX_OP_CMP_LE 3 /* if (oldval <= cmparg) wake */ +FUTEX_OP_CMP_GT 4 /* if (oldval > cmparg) wake */ +FUTEX_OP_CMP_GE 5 /* if (oldval >= cmparg) wake */ +.EE +.in +.IP +The return value of +.B FUTEX_WAKE_OP +is the sum of the number of waiters woken on the futex +.I uaddr +plus the number of waiters woken on the futex +.IR uaddr2 . +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAIT_BITSET " (since Linux 2.6.25)" +.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d +This operation is like +.B FUTEX_WAIT +except that +.I val3 +is used to provide a 32-bit bit mask to the kernel. +This bit mask, in which at least one bit must be set, +is stored in the kernel-internal state of the waiter. +See the description of +.B FUTEX_WAKE_BITSET +for further details. +.IP +If +.I timeout +is not NULL, the structure it points to specifies +an absolute timeout for the wait operation. +If +.I timeout +is NULL, the operation can block indefinitely. +.IP +The +.I uaddr2 +argument is ignored. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAKE_BITSET " (since Linux 2.6.25)" +.\" commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d +This operation is the same as +.B FUTEX_WAKE +except that the +.I val3 +argument is used to provide a 32-bit bit mask to the kernel. +This bit mask, in which at least one bit must be set, +is used to select which waiters should be woken up. +The selection is done by a bitwise AND of the "wake" bit mask +(i.e., the value in +.IR val3 ) +and the bit mask which is stored in the kernel-internal +state of the waiter (the "wait" bit mask that is set using +.BR FUTEX_WAIT_BITSET ). +All of the waiters for which the result of the AND is nonzero are woken up; +the remaining waiters are left sleeping. +.IP +The effect of +.B FUTEX_WAIT_BITSET +and +.B FUTEX_WAKE_BITSET +is to allow selective wake-ups among multiple waiters that are blocked +on the same futex. +However, note that, depending on the use case, +employing this bit-mask multiplexing feature on a +futex can be less efficient than simply using multiple futexes, +because employing bit-mask multiplexing requires the kernel +to check all waiters on a futex, +including those that are not interested in being woken up +(i.e., they do not have the relevant bit set in their "wait" bit mask). +.\" According to http://locklessinc.com/articles/futex_cheat_sheet/: +.\" +.\" "The original reason for the addition of these extensions +.\" was to improve the performance of pthread read-write locks +.\" in glibc. However, the pthreads library no longer uses the +.\" same locking algorithm, and these extensions are not used +.\" without the bitset parameter being all ones. +.\" +.\" The page goes on to note that the FUTEX_WAIT_BITSET operation +.\" is nevertheless used (with a bit mask of all ones) in order to +.\" obtain the absolute timeout functionality that is useful +.\" for efficiently implementing Pthreads APIs (which use absolute +.\" timeouts); FUTEX_WAIT provides only relative timeouts. +.IP +The constant +.BR FUTEX_BITSET_MATCH_ANY , +which corresponds to all 32 bits set in the bit mask, can be used as the +.I val3 +argument for +.B FUTEX_WAIT_BITSET +and +.BR FUTEX_WAKE_BITSET . +Other than differences in the handling of the +.I timeout +argument, the +.B FUTEX_WAIT +operation is equivalent to +.B FUTEX_WAIT_BITSET +with +.I val3 +specified as +.BR FUTEX_BITSET_MATCH_ANY ; +that is, allow a wake-up by any waker. +The +.B FUTEX_WAKE +operation is equivalent to +.B FUTEX_WAKE_BITSET +with +.I val3 +specified as +.BR FUTEX_BITSET_MATCH_ANY ; +that is, wake up any waiter(s). +.IP +The +.I uaddr2 +and +.I timeout +arguments are ignored. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SS Priority-inheritance futexes +Linux supports priority-inheritance (PI) futexes in order to handle +priority-inversion problems that can be encountered with +normal futex locks. +Priority inversion is the problem that occurs when a high-priority +task is blocked waiting to acquire a lock held by a low-priority task, +while tasks at an intermediate priority continuously preempt +the low-priority task from the CPU. +Consequently, the low-priority task makes no progress toward +releasing the lock, and the high-priority task remains blocked. +.P +Priority inheritance is a mechanism for dealing with +the priority-inversion problem. +With this mechanism, when a high-priority task becomes blocked +by a lock held by a low-priority task, +the priority of the low-priority task is temporarily raised +to that of the high-priority task, +so that it is not preempted by any intermediate level tasks, +and can thus make progress toward releasing the lock. +To be effective, priority inheritance must be transitive, +meaning that if a high-priority task blocks on a lock +held by a lower-priority task that is itself blocked by a lock +held by another intermediate-priority task +(and so on, for chains of arbitrary length), +then both of those tasks +(or more generally, all of the tasks in a lock chain) +have their priorities raised to be the same as the high-priority task. +.P +From a user-space perspective, +what makes a futex PI-aware is a policy agreement (described below) +between user space and the kernel about the value of the futex word, +coupled with the use of the PI-futex operations described below. +(Unlike the other futex operations described above, +the PI-futex operations are designed +for the implementation of very specific IPC mechanisms.) +.\" +.\" Quoting Darren Hart: +.\" These opcodes paired with the PI futex value policy (described below) +.\" defines a "futex" as PI aware. These were created very specifically +.\" in support of PI pthread_mutexes, so it makes a lot more sense to +.\" talk about a PI aware pthread_mutex, than a PI aware futex, since +.\" there is a lot of policy and scaffolding that has to be built up +.\" around it to use it properly (this is what a PI pthread_mutex is). +.P +.\" mtk: The following text is drawn from the Hart/Guniguntala paper +.\" (listed in SEE ALSO), but I have reworded some pieces +.\" significantly. +.\" +The PI-futex operations described below differ from the other +futex operations in that they impose policy on the use of the value of the +futex word: +.IP \[bu] 3 +If the lock is not acquired, the futex word's value shall be 0. +.IP \[bu] +If the lock is acquired, the futex word's value shall +be the thread ID (TID; +see +.BR gettid (2)) +of the owning thread. +.IP \[bu] +If the lock is owned and there are threads contending for the lock, +then the +.B FUTEX_WAITERS +bit shall be set in the futex word's value; in other words, this value is: +.IP +.in +4n +.EX +FUTEX_WAITERS | TID +.EE +.in +.IP +(Note that is invalid for a PI futex word to have no owner and +.B FUTEX_WAITERS +set.) +.P +With this policy in place, +a user-space application can acquire an unacquired +lock or release a lock using atomic instructions executed in user mode +(e.g., a compare-and-swap operation such as +.I cmpxchg +on the x86 architecture). +Acquiring a lock simply consists of using compare-and-swap to atomically +set the futex word's value to the caller's TID if its previous value was 0. +Releasing a lock requires using compare-and-swap to set the futex word's +value to 0 if the previous value was the expected TID. +.P +If a futex is already acquired (i.e., has a nonzero value), +waiters must employ the +.B FUTEX_LOCK_PI +or +.B FUTEX_LOCK_PI2 +operations to acquire the lock. +If other threads are waiting for the lock, then the +.B FUTEX_WAITERS +bit is set in the futex value; +in this case, the lock owner must employ the +.B FUTEX_UNLOCK_PI +operation to release the lock. +.P +In the cases where callers are forced into the kernel +(i.e., required to perform a +.BR futex () +call), +they then deal directly with a so-called RT-mutex, +a kernel locking mechanism which implements the required +priority-inheritance semantics. +After the RT-mutex is acquired, the futex value is updated accordingly, +before the calling thread returns to user space. +.P +It is important to note +.\" tglx (July 2015): +.\" If there are multiple waiters on a pi futex then a wake pi operation +.\" will wake the first waiter and hand over the lock to this waiter. This +.\" includes handing over the rtmutex which represents the futex in the +.\" kernel. The strict requirement is that the futex owner and the rtmutex +.\" owner must be the same, except for the update period which is +.\" serialized by the futex internal locking. That means the kernel must +.\" update the user-space value prior to returning to user space +that the kernel will update the futex word's value prior +to returning to user space. +(This prevents the possibility of the futex word's value ending +up in an invalid state, such as having an owner but the value being 0, +or having waiters but not having the +.B FUTEX_WAITERS +bit set.) +.P +If a futex has an associated RT-mutex in the kernel +(i.e., there are blocked waiters) +and the owner of the futex/RT-mutex dies unexpectedly, +then the kernel cleans up the RT-mutex and hands it over to the next waiter. +This in turn requires that the user-space value is updated accordingly. +To indicate that this is required, the kernel sets the +.B FUTEX_OWNER_DIED +bit in the futex word along with the thread ID of the new owner. +User space can detect this situation via the presence of the +.B FUTEX_OWNER_DIED +bit and is then responsible for cleaning up the stale state left over by +the dead owner. +.\" tglx (July 2015): +.\" The FUTEX_OWNER_DIED bit can also be set on uncontended futexes, where +.\" the kernel has no state associated. This happens via the robust futex +.\" mechanism. In that case the futex value will be set to +.\" FUTEX_OWNER_DIED. The robust futex mechanism is also available for non +.\" PI futexes. +.P +PI futexes are operated on by specifying one of the values listed below in +.IR futex_op . +Note that the PI futex operations must be used as paired operations +and are subject to some additional requirements: +.IP \[bu] 3 +.BR FUTEX_LOCK_PI , +.BR FUTEX_LOCK_PI2 , +and +.B FUTEX_TRYLOCK_PI +pair with +.BR FUTEX_UNLOCK_PI . +.B FUTEX_UNLOCK_PI +must be called only on a futex owned by the calling thread, +as defined by the value policy, otherwise the error +.B EPERM +results. +.IP \[bu] +.B FUTEX_WAIT_REQUEUE_PI +pairs with +.BR FUTEX_CMP_REQUEUE_PI . +This must be performed from a non-PI futex to a distinct PI futex +(or the error +.B EINVAL +results). +Additionally, +.I val +(the number of waiters to be woken) must be 1 +(or the error +.B EINVAL +results). +.P +The PI futex operations are as follows: +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_LOCK_PI " (since Linux 2.6.18)" +.\" commit c87e2837be82df479a6bae9f155c43516d2feebc +This operation is used after an attempt to acquire +the lock via an atomic user-mode instruction failed +because the futex word has a nonzero value\[em]specifically, +because it contained the (PID-namespace-specific) TID of the lock owner. +.IP +The operation checks the value of the futex word at the address +.IR uaddr . +If the value is 0, then the kernel tries to atomically set +the futex value to the caller's TID. +If the futex word's value is nonzero, +the kernel atomically sets the +.B FUTEX_WAITERS +bit, which signals the futex owner that it cannot unlock the futex in +user space atomically by setting the futex value to 0. +.\" tglx (July 2015): +.\" The operation here is similar to the FUTEX_WAIT logic. When the user +.\" space atomic acquire does not succeed because the futex value was non +.\" zero, then the waiter goes into the kernel, takes the kernel internal +.\" lock and retries the acquisition under the lock. If the acquisition +.\" does not succeed either, then it sets the FUTEX_WAITERS bit, to signal +.\" the lock owner that it needs to go into the kernel. Here is the pseudo +.\" code: +.\" +.\" lock(kernel_lock); +.\" retry: +.\" +.\" /* +.\" * Owner might have unlocked in user space before we +.\" * were able to set the waiter bit. +.\" */ +.\" if (atomic_acquire(futex) == SUCCESS) { +.\" unlock(kernel_lock()); +.\" return 0; +.\" } +.\" +.\" /* +.\" * Owner might have unlocked after the above atomic_acquire() +.\" * attempt. +.\" */ +.\" if (atomic_set_waiters_bit(futex) != SUCCESS) +.\" goto retry; +.\" +.\" queue_waiter(); +.\" unlock(kernel_lock); +.\" block(); +.\" +After that, the kernel: +.RS +.IP (1) 5 +Tries to find the thread which is associated with the owner TID. +.IP (2) +Creates or reuses kernel state on behalf of the owner. +(If this is the first waiter, there is no kernel state for this +futex, so kernel state is created by locking the RT-mutex +and the futex owner is made the owner of the RT-mutex. +If there are existing waiters, then the existing state is reused.) +.IP (3) +Attaches the waiter to the futex +(i.e., the waiter is enqueued on the RT-mutex waiter list). +.RE +.IP +If more than one waiter exists, +the enqueueing of the waiter is in descending priority order. +(For information on priority ordering, see the discussion of the +.BR SCHED_DEADLINE , +.BR SCHED_FIFO , +and +.B SCHED_RR +scheduling policies in +.BR sched (7).) +The owner inherits either the waiter's CPU bandwidth +(if the waiter is scheduled under the +.B SCHED_DEADLINE +policy) or the waiter's priority (if the waiter is scheduled under the +.B SCHED_RR +or +.B SCHED_FIFO +policy). +.\" August 2015: +.\" mtk: If the realm is restricted purely to SCHED_OTHER (SCHED_NORMAL) +.\" processes, does the nice value come into play also? +.\" +.\" tglx: No. SCHED_OTHER/NORMAL tasks are handled in FIFO order +This inheritance follows the lock chain in the case of nested locking +.\" (i.e., task 1 blocks on lock A, held by task 2, +.\" while task 2 blocks on lock B, held by task 3) +and performs deadlock detection. +.IP +The +.I timeout +argument provides a timeout for the lock attempt. +If +.I timeout +is not NULL, the structure it points to specifies +an absolute timeout, measured against the +.B CLOCK_REALTIME +clock. +.\" 2016-07-07 response from Thomas Gleixner on LKML: +.\" From: Thomas Gleixner +.\" Date: 6 July 2016 at 20:57 +.\" Subject: Re: futex: Allow FUTEX_CLOCK_REALTIME with FUTEX_WAIT op +.\" +.\" On Thu, 23 Jun 2016, Michael Kerrisk (man-pages) wrote: +.\" > On 06/23/2016 08:28 PM, Darren Hart wrote: +.\" > > And as a follow-on, what is the reason for FUTEX_LOCK_PI only using +.\" > > CLOCK_REALTIME? It seems reasonable to me that a user may want to wait a +.\" > > specific amount of time, regardless of wall time. +.\" > +.\" > Yes, that's another weird inconsistency. +.\" +.\" The reason is that phtread_mutex_timedlock() uses absolute timeouts based on +.\" CLOCK_REALTIME. glibc folks asked to make that the default behaviour back +.\" then when we added LOCK_PI. +If +.I timeout +is NULL, the operation will block indefinitely. +.IP +The +.IR uaddr2 , +.IR val , +and +.I val3 +arguments are ignored. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_LOCK_PI2 " (since Linux 5.14)" +.\" commit bf22a6976897977b0a3f1aeba6823c959fc4fdae +This operation is the same as +.BR FUTEX_LOCK_PI , +except that the clock against which +.I timeout +is measured is selectable. +By default, the (absolute) timeout specified in +.I timeout +is measured against the +.B CLOCK_MONOTONIC +clock, but if the +.B FUTEX_CLOCK_REALTIME +flag is specified in +.IR futex_op , +then the timeout is measured against the +.B CLOCK_REALTIME +clock. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_TRYLOCK_PI " (since Linux 2.6.18)" +.\" commit c87e2837be82df479a6bae9f155c43516d2feebc +This operation tries to acquire the lock at +.IR uaddr . +It is invoked when a user-space atomic acquire did not +succeed because the futex word was not 0. +.IP +Because the kernel has access to more state information than user space, +acquisition of the lock might succeed if performed by the +kernel in cases where the futex word +(i.e., the state information accessible to use-space) contains stale state +.RB ( FUTEX_WAITERS +and/or +.BR FUTEX_OWNER_DIED ). +This can happen when the owner of the futex died. +User space cannot handle this condition in a race-free manner, +but the kernel can fix this up and acquire the futex. +.\" Paraphrasing a f2f conversation with Thomas Gleixner about the +.\" above point (Aug 2015): ### +.\" There is a rare possibility of a race condition involving an +.\" uncontended futex with no owner, but with waiters. The +.\" kernel-user-space contract is that if a futex is nonzero, you must +.\" go into kernel. The futex was owned by a task, and that task dies +.\" but there are no waiters, so the futex value is non zero. +.\" Therefore, the next locker has to go into the kernel, +.\" so that the kernel has a chance to clean up. (CMXCH on zero +.\" in user space would fail, so kernel has to clean up.) +.\" Darren Hart (Oct 2015): +.\" The trylock in the kernel has more state, so it can independently +.\" verify the flags that user space must trust implicitly. +.IP +The +.IR uaddr2 , +.IR val , +.IR timeout , +and +.I val3 +arguments are ignored. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_UNLOCK_PI " (since Linux 2.6.18)" +.\" commit c87e2837be82df479a6bae9f155c43516d2feebc +This operation wakes the top priority waiter that is waiting in +.B FUTEX_LOCK_PI +or +.B FUTEX_LOCK_PI2 +on the futex address provided by the +.I uaddr +argument. +.IP +This is called when the user-space value at +.I uaddr +cannot be changed atomically from a TID (of the owner) to 0. +.IP +The +.IR uaddr2 , +.IR val , +.IR timeout , +and +.I val3 +arguments are ignored. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_CMP_REQUEUE_PI " (since Linux 2.6.31)" +.\" commit 52400ba946759af28442dee6265c5c0180ac7122 +This operation is a PI-aware variant of +.BR FUTEX_CMP_REQUEUE . +It requeues waiters that are blocked via +.B FUTEX_WAIT_REQUEUE_PI +on +.I uaddr +from a non-PI source futex +.RI ( uaddr ) +to a PI target futex +.RI ( uaddr2 ). +.IP +As with +.BR FUTEX_CMP_REQUEUE , +this operation wakes up a maximum of +.I val +waiters that are waiting on the futex at +.IR uaddr . +However, for +.BR FUTEX_CMP_REQUEUE_PI , +.I val +is required to be 1 +(since the main point is to avoid a thundering herd). +The remaining waiters are removed from the wait queue of the source futex at +.I uaddr +and added to the wait queue of the target futex at +.IR uaddr2 . +.IP +The +.I val2 +.\" val2 is the cap on the number of requeued waiters. +.\" In the glibc pthread_cond_broadcast() implementation, this argument +.\" is specified as INT_MAX, and for pthread_cond_signal() it is 0. +and +.I val3 +arguments serve the same purposes as for +.BR FUTEX_CMP_REQUEUE . +.\" +.\" The page at http://locklessinc.com/articles/futex_cheat_sheet/ +.\" notes that "priority-inheritance Futex to priority-inheritance +.\" Futex requeues are currently unsupported". However, probably +.\" the page does not need to say nothing about this, since +.\" Thomas Gleixner commented (July 2015): "they never will be +.\" supported because they make no sense at all" +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.TP +.BR FUTEX_WAIT_REQUEUE_PI " (since Linux 2.6.31)" +.\" commit 52400ba946759af28442dee6265c5c0180ac7122 +.\" +Wait on a non-PI futex at +.I uaddr +and potentially be requeued (via a +.B FUTEX_CMP_REQUEUE_PI +operation in another task) onto a PI futex at +.IR uaddr2 . +The wait operation on +.I uaddr +is the same as for +.BR FUTEX_WAIT . +.IP +The waiter can be removed from the wait on +.I uaddr +without requeueing on +.I uaddr2 +via a +.B FUTEX_WAKE +operation in another task. +In this case, the +.B FUTEX_WAIT_REQUEUE_PI +operation fails with the error +.BR EAGAIN . +.IP +If +.I timeout +is not NULL, the structure it points to specifies +an absolute timeout for the wait operation. +If +.I timeout +is NULL, the operation can block indefinitely. +.IP +The +.I val3 +argument is ignored. +.IP +The +.B FUTEX_WAIT_REQUEUE_PI +and +.B FUTEX_CMP_REQUEUE_PI +were added to support a fairly specific use case: +support for priority-inheritance-aware POSIX threads condition variables. +The idea is that these operations should always be paired, +in order to ensure that user space and the kernel remain in sync. +Thus, in the +.B FUTEX_WAIT_REQUEUE_PI +operation, the user-space application pre-specifies the target +of the requeue that takes place in the +.B FUTEX_CMP_REQUEUE_PI +operation. +.\" +.\" Darren Hart notes that a patch to allow glibc to fully support +.\" PI-aware pthreads condition variables has not yet been accepted into +.\" glibc. The story is complex, and can be found at +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=11588 +.\" Darren notes that in the meantime, the patch is shipped with various +.\" PREEMPT_RT-enabled Linux systems. +.\" +.\" Related to the preceding, Darren proposed that somewhere, man-pages +.\" should document the following point: +.\" +.\" While the Linux kernel, since Linux 2.6.31, supports requeueing of +.\" priority-inheritance (PI) aware mutexes via the +.\" FUTEX_WAIT_REQUEUE_PI and FUTEX_CMP_REQUEUE_PI futex operations, +.\" the glibc implementation does not yet take full advantage of this. +.\" Specifically, the condvar internal data lock remains a non-PI aware +.\" mutex, regardless of the type of the pthread_mutex associated with +.\" the condvar. This can lead to an unbounded priority inversion on +.\" the internal data lock even when associating a PI aware +.\" pthread_mutex with a condvar during a pthread_cond*_wait +.\" operation. For this reason, it is not recommended to rely on +.\" priority inheritance when using pthread condition variables. +.\" +.\" The problem is that the obvious location for this text is +.\" the pthread_cond*wait(3) man page. However, such a man page +.\" does not currently exist. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SH RETURN VALUE +In the event of an error (and assuming that +.BR futex () +was invoked via +.BR syscall (2)), +all operations return \-1 and set +.I errno +to indicate the error. +.P +The return value on success depends on the operation, +as described in the following list: +.TP +.B FUTEX_WAIT +Returns 0 if the caller was woken up. +Note that a wake-up can also be caused by common futex usage patterns +in unrelated code that happened to have previously used the futex word's +memory location (e.g., typical futex-based implementations of +Pthreads mutexes can cause this under some conditions). +Therefore, callers should always conservatively assume that a return +value of 0 can mean a spurious wake-up, and use the futex word's value +(i.e., the user-space synchronization scheme) +to decide whether to continue to block or not. +.TP +.B FUTEX_WAKE +Returns the number of waiters that were woken up. +.TP +.B FUTEX_FD +Returns the new file descriptor associated with the futex. +.TP +.B FUTEX_REQUEUE +Returns the number of waiters that were woken up. +.TP +.B FUTEX_CMP_REQUEUE +Returns the total number of waiters that were woken up or +requeued to the futex for the futex word at +.IR uaddr2 . +If this value is greater than +.IR val , +then the difference is the number of waiters requeued to the futex for the +futex word at +.IR uaddr2 . +.TP +.B FUTEX_WAKE_OP +Returns the total number of waiters that were woken up. +This is the sum of the woken waiters on the two futexes for +the futex words at +.I uaddr +and +.IR uaddr2 . +.TP +.B FUTEX_WAIT_BITSET +Returns 0 if the caller was woken up. +See +.B FUTEX_WAIT +for how to interpret this correctly in practice. +.TP +.B FUTEX_WAKE_BITSET +Returns the number of waiters that were woken up. +.TP +.B FUTEX_LOCK_PI +Returns 0 if the futex was successfully locked. +.TP +.B FUTEX_LOCK_PI2 +Returns 0 if the futex was successfully locked. +.TP +.B FUTEX_TRYLOCK_PI +Returns 0 if the futex was successfully locked. +.TP +.B FUTEX_UNLOCK_PI +Returns 0 if the futex was successfully unlocked. +.TP +.B FUTEX_CMP_REQUEUE_PI +Returns the total number of waiters that were woken up or +requeued to the futex for the futex word at +.IR uaddr2 . +If this value is greater than +.IR val , +then difference is the number of waiters requeued to the futex for +the futex word at +.IR uaddr2 . +.TP +.B FUTEX_WAIT_REQUEUE_PI +Returns 0 if the caller was successfully requeued to the futex for +the futex word at +.IR uaddr2 . +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SH ERRORS +.TP +.B EACCES +No read access to the memory of a futex word. +.TP +.B EAGAIN +.RB ( FUTEX_WAIT , +.BR FUTEX_WAIT_BITSET , +.BR FUTEX_WAIT_REQUEUE_PI ) +The value pointed to by +.I uaddr +was not equal to the expected value +.I val +at the time of the call. +.IP +.BR Note : +on Linux, the symbolic names +.B EAGAIN +and +.B EWOULDBLOCK +(both of which appear in different parts of the kernel futex code) +have the same value. +.TP +.B EAGAIN +.RB ( FUTEX_CMP_REQUEUE , +.BR FUTEX_CMP_REQUEUE_PI ) +The value pointed to by +.I uaddr +is not equal to the expected value +.IR val3 . +.TP +.B EAGAIN +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_LOCK_PI2 , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI ) +The futex owner thread ID of +.I uaddr +(for +.BR FUTEX_CMP_REQUEUE_PI : +.IR uaddr2 ) +is about to exit, +but has not yet handled the internal state cleanup. +Try again. +.TP +.B EDEADLK +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_LOCK_PI2 , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI ) +The futex word at +.I uaddr +is already locked by the caller. +.TP +.B EDEADLK +.\" FIXME . I see that kernel/locking/rtmutex.c uses EDEADLK in some +.\" places, and EDEADLOCK in others. On almost all architectures +.\" these constants are synonymous. Is there a reason that both +.\" names are used? +.\" +.\" tglx (July 2015): "No. We should probably fix that." +.\" +.RB ( FUTEX_CMP_REQUEUE_PI ) +While requeueing a waiter to the PI futex for the futex word at +.IR uaddr2 , +the kernel detected a deadlock. +.TP +.B EFAULT +A required pointer argument (i.e., +.IR uaddr , +.IR uaddr2 , +or +.IR timeout ) +did not point to a valid user-space address. +.TP +.B EINTR +A +.B FUTEX_WAIT +or +.B FUTEX_WAIT_BITSET +operation was interrupted by a signal (see +.BR signal (7)). +Before Linux 2.6.22, this error could also be returned for +a spurious wakeup; since Linux 2.6.22, this no longer happens. +.TP +.B EINVAL +The operation in +.I futex_op +is one of those that employs a timeout, but the supplied +.I timeout +argument was invalid +.RI ( tv_sec +was less than zero, or +.I tv_nsec +was not less than 1,000,000,000). +.TP +.B EINVAL +The operation specified in +.I futex_op +employs one or both of the pointers +.I uaddr +and +.IR uaddr2 , +but one of these does not point to a valid object\[em]that is, +the address is not four-byte-aligned. +.TP +.B EINVAL +.RB ( FUTEX_WAIT_BITSET , +.BR FUTEX_WAKE_BITSET ) +The bit mask supplied in +.I val3 +is zero. +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +.I uaddr +equals +.I uaddr2 +(i.e., an attempt was made to requeue to the same futex). +.TP +.B EINVAL +.RB ( FUTEX_FD ) +The signal number supplied in +.I val +is invalid. +.TP +.B EINVAL +.RB ( FUTEX_WAKE , +.BR FUTEX_WAKE_OP , +.BR FUTEX_WAKE_BITSET , +.BR FUTEX_REQUEUE , +.BR FUTEX_CMP_REQUEUE ) +The kernel detected an inconsistency between the user-space state at +.I uaddr +and the kernel state\[em]that is, it detected a waiter which waits in +.B FUTEX_LOCK_PI +or +.B FUTEX_LOCK_PI2 +on +.IR uaddr . +.TP +.B EINVAL +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_LOCK_PI2 , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_UNLOCK_PI ) +The kernel detected an inconsistency between the user-space state at +.I uaddr +and the kernel state. +This indicates either state corruption +or that the kernel found a waiter on +.I uaddr +which is waiting via +.B FUTEX_WAIT +or +.BR FUTEX_WAIT_BITSET . +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +The kernel detected an inconsistency between the user-space state at +.I uaddr2 +and the kernel state; +.\" From a conversation with Thomas Gleixner (Aug 2015): ### +.\" The kernel sees: I have non PI state for a futex you tried to +.\" tell me was PI +that is, the kernel detected a waiter which waits via +.B FUTEX_WAIT +or +.B FUTEX_WAIT_BITSET +on +.IR uaddr2 . +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +The kernel detected an inconsistency between the user-space state at +.I uaddr +and the kernel state; +that is, the kernel detected a waiter which waits via +.B FUTEX_WAIT +or +.B FUTEX_WAIT_BITSET +on +.IR uaddr . +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +The kernel detected an inconsistency between the user-space state at +.I uaddr +and the kernel state; +that is, the kernel detected a waiter which waits on +.I uaddr +via +.B FUTEX_LOCK_PI +or +.B FUTEX_LOCK_PI2 +(instead of +.BR FUTEX_WAIT_REQUEUE_PI ). +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +.\" This deals with the case: +.\" wait_requeue_pi(A, B); +.\" requeue_pi(A, C); +An attempt was made to requeue a waiter to a futex other than that +specified by the matching +.B FUTEX_WAIT_REQUEUE_PI +call for that waiter. +.TP +.B EINVAL +.RB ( FUTEX_CMP_REQUEUE_PI ) +The +.I val +argument is not 1. +.TP +.B EINVAL +Invalid argument. +.TP +.B ENFILE +.RB ( FUTEX_FD ) +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_LOCK_PI2 , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI ) +The kernel could not allocate memory to hold state information. +.TP +.B ENOSYS +Invalid operation specified in +.IR futex_op . +.TP +.B ENOSYS +The +.B FUTEX_CLOCK_REALTIME +option was specified in +.IR futex_op , +but the accompanying operation was neither +.BR FUTEX_WAIT , +.BR FUTEX_WAIT_BITSET , +.BR FUTEX_WAIT_REQUEUE_PI , +nor +.BR FUTEX_LOCK_PI2 . +.TP +.B ENOSYS +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_LOCK_PI2 , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_UNLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI , +.BR FUTEX_WAIT_REQUEUE_PI ) +A run-time check determined that the operation is not available. +The PI-futex operations are not implemented on all architectures and +are not supported on some CPU variants. +.TP +.B EPERM +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_LOCK_PI2 , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI ) +The caller is not allowed to attach itself to the futex at +.I uaddr +(for +.BR FUTEX_CMP_REQUEUE_PI : +the futex at +.IR uaddr2 ). +(This may be caused by a state corruption in user space.) +.TP +.B EPERM +.RB ( FUTEX_UNLOCK_PI ) +The caller does not own the lock represented by the futex word. +.TP +.B ESRCH +.RB ( FUTEX_LOCK_PI , +.BR FUTEX_LOCK_PI2 , +.BR FUTEX_TRYLOCK_PI , +.BR FUTEX_CMP_REQUEUE_PI ) +The thread ID in the futex word at +.I uaddr +does not exist. +.TP +.B ESRCH +.RB ( FUTEX_CMP_REQUEUE_PI ) +The thread ID in the futex word at +.I uaddr2 +does not exist. +.TP +.B ETIMEDOUT +The operation in +.I futex_op +employed the timeout specified in +.IR timeout , +and the timeout expired before the operation completed. +.\" +.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.0. +.P +Initial futex support was merged in Linux 2.5.7 but with different +semantics from what was described above. +A four-argument system call with the semantics +described in this page was introduced in Linux 2.5.40. +A fifth argument was added in Linux 2.5.70, +and a sixth argument was added in Linux 2.6.7. +.SH EXAMPLES +The program below demonstrates use of futexes in a program where a parent +process and a child process use a pair of futexes located inside a +shared anonymous mapping to synchronize access to a shared resource: +the terminal. +The two processes each write +.I nloops +(a command-line argument that defaults to 5 if omitted) +messages to the terminal and employ a synchronization protocol +that ensures that they alternate in writing messages. +Upon running this program we see output such as the following: +.P +.in +4n +.EX +$ \fB./futex_demo\fP +Parent (18534) 0 +Child (18535) 0 +Parent (18534) 1 +Child (18535) 1 +Parent (18534) 2 +Child (18535) 2 +Parent (18534) 3 +Child (18535) 3 +Parent (18534) 4 +Child (18535) 4 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (futex.c) +.EX +/* futex_demo.c +\& + Usage: futex_demo [nloops] + (Default: 5) +\& + Demonstrate the use of futexes in a program where parent and child + use a pair of futexes located inside a shared anonymous mapping to + synchronize access to a shared resource: the terminal. The two + processes each write \[aq]num\-loops\[aq] messages to the terminal and employ + a synchronization protocol that ensures that they alternate in + writing messages. +*/ +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +static uint32_t *futex1, *futex2, *iaddr; +\& +static int +futex(uint32_t *uaddr, int futex_op, uint32_t val, + const struct timespec *timeout, uint32_t *uaddr2, uint32_t val3) +{ + return syscall(SYS_futex, uaddr, futex_op, val, + timeout, uaddr2, val3); +} +\& +/* Acquire the futex pointed to by \[aq]futexp\[aq]: wait for its value to + become 1, and then set the value to 0. */ +\& +static void +fwait(uint32_t *futexp) +{ + long s; + const uint32_t one = 1; +\& + /* atomic_compare_exchange_strong(ptr, oldval, newval) + atomically performs the equivalent of: +\& + if (*ptr == *oldval) + *ptr = newval; +\& + It returns true if the test yielded true and *ptr was updated. */ +\& + while (1) { +\& + /* Is the futex available? */ + if (atomic_compare_exchange_strong(futexp, &one, 0)) + break; /* Yes */ +\& + /* Futex is not available; wait. */ +\& + s = futex(futexp, FUTEX_WAIT, 0, NULL, NULL, 0); + if (s == \-1 && errno != EAGAIN) + err(EXIT_FAILURE, "futex\-FUTEX_WAIT"); + } +} +\& +/* Release the futex pointed to by \[aq]futexp\[aq]: if the futex currently + has the value 0, set its value to 1 and then wake any futex waiters, + so that if the peer is blocked in fwait(), it can proceed. */ +\& +static void +fpost(uint32_t *futexp) +{ + long s; + const uint32_t zero = 0; +\& + /* atomic_compare_exchange_strong() was described + in comments above. */ +\& + if (atomic_compare_exchange_strong(futexp, &zero, 1)) { + s = futex(futexp, FUTEX_WAKE, 1, NULL, NULL, 0); + if (s == \-1) + err(EXIT_FAILURE, "futex\-FUTEX_WAKE"); + } +} +\& +int +main(int argc, char *argv[]) +{ + pid_t childPid; + unsigned int nloops; +\& + setbuf(stdout, NULL); +\& + nloops = (argc > 1) ? atoi(argv[1]) : 5; +\& + /* Create a shared anonymous mapping that will hold the futexes. + Since the futexes are being shared between processes, we + subsequently use the "shared" futex operations (i.e., not the + ones suffixed "_PRIVATE"). */ +\& + iaddr = mmap(NULL, sizeof(*iaddr) * 2, PROT_READ | PROT_WRITE, + MAP_ANONYMOUS | MAP_SHARED, \-1, 0); + if (iaddr == MAP_FAILED) + err(EXIT_FAILURE, "mmap"); +\& + futex1 = &iaddr[0]; + futex2 = &iaddr[1]; +\& + *futex1 = 0; /* State: unavailable */ + *futex2 = 1; /* State: available */ +\& + /* Create a child process that inherits the shared anonymous + mapping. */ +\& + childPid = fork(); + if (childPid == \-1) + err(EXIT_FAILURE, "fork"); +\& + if (childPid == 0) { /* Child */ + for (unsigned int j = 0; j < nloops; j++) { + fwait(futex1); + printf("Child (%jd) %u\en", (intmax_t) getpid(), j); + fpost(futex2); + } +\& + exit(EXIT_SUCCESS); + } +\& + /* Parent falls through to here. */ +\& + for (unsigned int j = 0; j < nloops; j++) { + fwait(futex2); + printf("Parent (%jd) %u\en", (intmax_t) getpid(), j); + fpost(futex1); + } +\& + wait(NULL); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.BR get_robust_list (2), +.BR restart_syscall (2), +.BR pthread_mutexattr_getprotocol (3), +.BR futex (7), +.BR sched (7) +.P +The following kernel source files: +.IP \[bu] 3 +.I Documentation/pi\-futex.txt +.IP \[bu] +.I Documentation/futex\-requeue\-pi.txt +.IP \[bu] +.I Documentation/locking/rt\-mutex.txt +.IP \[bu] +.I Documentation/locking/rt\-mutex\-design.txt +.IP \[bu] +.I Documentation/robust\-futex\-ABI.txt +.P +Franke, H., Russell, R., and Kirwood, M., 2002. +\fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP +(from proceedings of the Ottawa Linux Symposium 2002), +.br +.UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002\-pages\-479\-495.pdf +.UE +.P +Hart, D., 2009. \fIA futex overview and update\fP, +.UR http://lwn.net/Articles/360699/ +.UE +.P +Hart, D.\& and Guniguntala, D., 2009. +\fIRequeue-PI: Making glibc Condvars PI-Aware\fP +(from proceedings of the 2009 Real-Time Linux Workshop), +.UR http://lwn.net/images/conf/rtlws11/papers/proc/p10.pdf +.UE +.P +Drepper, U., 2011. \fIFutexes Are Tricky\fP, +.UR http://www.akkadia.org/drepper/futex.pdf +.UE +.P +Futex example library, futex\-*.tar.bz2 at +.br +.UR https://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ +.UE +.\" +.\" FIXME(Torvald) We should probably refer to the glibc code here, in +.\" particular the glibc-internal futex wrapper functions that are +.\" WIP, and the generic pthread_mutex_t and perhaps condvar +.\" implementations. diff --git a/man/man2/futimesat.2 b/man/man2/futimesat.2 new file mode 100644 index 0000000..8a0c3cd --- /dev/null +++ b/man/man2/futimesat.2 @@ -0,0 +1,128 @@ +.\" This manpage is Copyright (C) 2006, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH futimesat 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +futimesat \- change timestamps of a file relative to a \ +directory file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " AT_* " constants */" +.B #include +.P +.BI "[[deprecated]] int futimesat(int " dirfd ", const char *" pathname , +.BI " const struct timeval " times [2]); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR futimesat (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +This system call is obsolete. +Use +.BR utimensat (2) +instead. +.P +The +.BR futimesat () +system call operates in exactly the same way as +.BR utimes (2), +except for the differences described in this manual page. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR utimes (2) +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR utimes (2)). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +(See +.BR openat (2) +for an explanation of why the +.I dirfd +argument is useful.) +.SH RETURN VALUE +On success, +.BR futimesat () +returns a 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +The same errors that occur for +.BR utimes (2) +can also occur for +.BR futimesat (). +The following additional errors can occur for +.BR futimesat (): +.TP +.B EBADF +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.SS glibc +If +.I pathname +is NULL, then the glibc +.BR futimesat () +wrapper function updates the times for the file referred to by +.IR dirfd . +.\" The Solaris futimesat() also has this strangeness. +.SH STANDARDS +None. +.SH HISTORY +Linux 2.6.16, +glibc 2.4. +.P +It was implemented from a specification that was proposed for POSIX.1, +but that specification was replaced by the one for +.BR utimensat (2). +.P +A similar system call exists on Solaris. +.SH NOTES +.SH SEE ALSO +.BR stat (2), +.BR utimensat (2), +.BR utimes (2), +.BR futimes (3), +.BR path_resolution (7) diff --git a/man/man2/get_kernel_syms.2 b/man/man2/get_kernel_syms.2 new file mode 100644 index 0000000..edef20b --- /dev/null +++ b/man/man2/get_kernel_syms.2 @@ -0,0 +1,88 @@ +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" reformatting and rewordings by mtk +.\" +.TH get_kernel_syms 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +get_kernel_syms \- retrieve exported kernel and module symbols +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int get_kernel_syms(struct kernel_sym *" table ); +.fi +.SH DESCRIPTION +.BR Note : +This system call is present only before Linux 2.6. +.P +If +.I table +is NULL, +.BR get_kernel_syms () +returns the number of symbols available for query. +Otherwise, it fills in a table of structures: +.P +.in +4n +.EX +struct kernel_sym { + unsigned long value; + char name[60]; +}; +.EE +.in +.P +The symbols are interspersed with magic symbols of the form +.BI # module-name +with the kernel having an empty name. +The value associated with a symbol of this form is the address at +which the module is loaded. +.P +The symbols exported from each module follow their magic module tag +and the modules are returned in the reverse of the +order in which they were loaded. +.SH RETURN VALUE +On success, returns the number of symbols copied to +.IR table . +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +There is only one possible error return: +.TP +.B ENOSYS +.BR get_kernel_syms () +is not supported in this version of the kernel. +.SH STANDARDS +Linux. +.SH HISTORY +Removed in Linux 2.6. +.\" Removed in Linux 2.5.48 +.P +This obsolete system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc versions before glibc 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it was sufficient to manually declare the interface in your code; +alternatively, you could invoke the system call using +.BR syscall (2). +.SH BUGS +There is no way to indicate the size of the buffer allocated for +.IR table . +If symbols have been added to the kernel since the +program queried for the symbol table size, memory will be corrupted. +.P +The length of exported symbol names is limited to 59 characters. +.P +Because of these limitations, this system call is deprecated in +favor of +.BR query_module (2) +(which is itself nowadays deprecated +in favor of other interfaces described on its manual page). +.SH SEE ALSO +.BR create_module (2), +.BR delete_module (2), +.BR init_module (2), +.BR query_module (2) diff --git a/man/man2/get_mempolicy.2 b/man/man2/get_mempolicy.2 new file mode 100644 index 0000000..b70f529 --- /dev/null +++ b/man/man2/get_mempolicy.2 @@ -0,0 +1,239 @@ +.\" SPDX-License-Identifier: Linux-man-pages-copyleft-var +.\" +.\" Copyright 2003,2004 Andi Kleen, SuSE Labs. +.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard +.\" +.\" 2006-02-03, mtk, substantial wording changes and other improvements +.\" 2007-08-27, Lee Schermerhorn +.\" more precise specification of behavior. +.\" +.TH get_mempolicy 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +get_mempolicy \- retrieve NUMA memory policy for a thread +.SH LIBRARY +NUMA (Non-Uniform Memory Access) policy library +.RI ( libnuma ", " \-lnuma ) +.SH SYNOPSIS +.B "#include " +.nf +.P +.BI "long get_mempolicy(int *" mode , +.BI " unsigned long " nodemask [(. maxnode " + ULONG_WIDTH - 1)" +.B " / ULONG_WIDTH]," +.BI " unsigned long " maxnode ", void *" addr , +.BI " unsigned long " flags ); +.fi +.SH DESCRIPTION +.BR get_mempolicy () +retrieves the NUMA policy of the calling thread or of a memory address, +depending on the setting of +.IR flags . +.P +A NUMA machine has different +memory controllers with different distances to specific CPUs. +The memory policy defines from which node memory is allocated for +the thread. +.P +If +.I flags +is specified as 0, +then information about the calling thread's default policy +(as set by +.BR set_mempolicy (2)) +is returned, in the buffers pointed to by +.I mode +and +.IR nodemask . +The value returned in these arguments +may be used to restore the thread's policy to its state at +the time of the call to +.BR get_mempolicy () +using +.BR set_mempolicy (2). +When +.I flags +is 0, +.I addr +must be specified as NULL. +.P +If +.I flags +specifies +.B MPOL_F_MEMS_ALLOWED +(available since Linux 2.6.24), the +.I mode +argument is ignored and the set of nodes (memories) that the +thread is allowed to specify in subsequent calls to +.BR mbind (2) +or +.BR set_mempolicy (2) +(in the absence of any +.IR "mode flags" ) +is returned in +.IR nodemask . +It is not permitted to combine +.B MPOL_F_MEMS_ALLOWED +with either +.B MPOL_F_ADDR +or +.BR MPOL_F_NODE . +.P +If +.I flags +specifies +.BR MPOL_F_ADDR , +then information is returned about the policy governing the memory +address given in +.IR addr . +This policy may be different from the thread's default policy if +.BR mbind (2) +or one of the helper functions described in +.BR numa (3) +has been used to establish a policy for the memory range containing +.IR addr . +.P +If the +.I mode +argument is not NULL, then +.BR get_mempolicy () +will store the policy mode and any optional +.I "mode flags" +of the requested NUMA policy in the location pointed to by this argument. +If +.I nodemask +is not NULL, then the nodemask associated with the policy will be stored +in the location pointed to by this argument. +.I maxnode +specifies the number of node IDs +that can be stored into +.IR nodemask \[em]that +is, the maximum node ID plus one. +The value specified by +.I maxnode +is always rounded to a multiple of +.IR "sizeof(unsigned\ long)*8" . +.P +If +.I flags +specifies both +.B MPOL_F_NODE +and +.BR MPOL_F_ADDR , +.BR get_mempolicy () +will return the node ID of the node on which the address +.I addr +is allocated into the location pointed to by +.IR mode . +If no page has yet been allocated for the specified address, +.BR get_mempolicy () +will allocate a page as if the thread had performed a read +(load) access to that address, and return the ID of the node +where that page was allocated. +.P +If +.I flags +specifies +.BR MPOL_F_NODE , +but not +.BR MPOL_F_ADDR , +and the thread's current policy is +.B MPOL_INTERLEAVE +or +.BR MPOL_WEIGHTED_INTERLEAVE , +then +.BR get_mempolicy () +will return in the location pointed to by a non-NULL +.I mode +argument, +the node ID of the next node that will be used for +interleaving of internal kernel pages allocated on behalf of the thread. +.\" Note: code returns next interleave node via 'mode' argument -Lee Schermerhorn +These allocations include pages for memory-mapped files in +process memory ranges mapped using the +.BR mmap (2) +call with the +.B MAP_PRIVATE +flag for read accesses, and in memory ranges mapped with the +.B MAP_SHARED +flag for all accesses. +.P +Other flag values are reserved. +.P +For an overview of the possible policies see +.BR set_mempolicy (2). +.SH RETURN VALUE +On success, +.BR get_mempolicy () +returns 0; +on error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Part of all of the memory range specified by +.I nodemask +and +.I maxnode +points outside your accessible address space. +.TP +.B EINVAL +The value specified by +.I maxnode +is less than the number of node IDs supported by the system. +Or +.I flags +specified values other than +.B MPOL_F_NODE +or +.BR MPOL_F_ADDR ; +or +.I flags +specified +.B MPOL_F_ADDR +and +.I addr +is NULL, +or +.I flags +did not specify +.B MPOL_F_ADDR +and +.I addr +is not NULL. +Or, +.I flags +specified +.B MPOL_F_NODE +but not +.B MPOL_F_ADDR +and the current thread policy is neither +.B MPOL_INTERLEAVE +nor +.BR MPOL_WEIGHTED_INTERLEAVE . +Or, +.I flags +specified +.B MPOL_F_MEMS_ALLOWED +with either +.B MPOL_F_ADDR +or +.BR MPOL_F_NODE . +(And there are other +.B EINVAL +cases.) +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.7. +.SH NOTES +For information on library support, see +.BR numa (7). +.SH SEE ALSO +.BR getcpu (2), +.BR mbind (2), +.BR mmap (2), +.BR set_mempolicy (2), +.BR numa (3), +.BR numa (7), +.BR numactl (8) diff --git a/man/man2/get_robust_list.2 b/man/man2/get_robust_list.2 new file mode 100644 index 0000000..b519ca6 --- /dev/null +++ b/man/man2/get_robust_list.2 @@ -0,0 +1,156 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" Written by Ivana Varekova +.\" and Copyright (c) 2017, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" FIXME Something could be added to this page (or exit(2)) +.\" about exit_robust_list processing +.\" +.TH get_robust_list 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +get_robust_list, set_robust_list \- get/set list of robust futexes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " \ +" /* Definition of " "struct robust_list_head" " */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "long syscall(SYS_get_robust_list, int " pid , +.BI " struct robust_list_head **" head_ptr ", size_t *" len_ptr ); +.B long syscall(SYS_set_robust_list, +.BI " struct robust_list_head *" head ", size_t " len ); +.fi +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +These system calls deal with per-thread robust futex lists. +These lists are managed in user space: +the kernel knows only about the location of the head of the list. +A thread can inform the kernel of the location of its robust futex list using +.BR set_robust_list (). +The address of a thread's robust futex list can be obtained using +.BR get_robust_list (). +.P +The purpose of the robust futex list is to ensure that if a thread +accidentally fails to unlock a futex before terminating or calling +.BR execve (2), +another thread that is waiting on that futex is notified that +the former owner of the futex has died. +This notification consists of two pieces: the +.B FUTEX_OWNER_DIED +bit is set in the futex word, and the kernel performs a +.BR futex (2) +.B FUTEX_WAKE +operation on one of the threads waiting on the futex. +.P +The +.BR get_robust_list () +system call returns the head of the robust futex list of the thread +whose thread ID is specified in +.IR pid . +If +.I pid +is 0, +the head of the list for the calling thread is returned. +The list head is stored in the location pointed to by +.IR head_ptr . +The size of the object pointed to by +.I **head_ptr +is stored in +.IR len_ptr . +.P +Permission to employ +.BR get_robust_list () +is governed by a ptrace access mode +.B PTRACE_MODE_READ_REALCREDS +check; see +.BR ptrace (2). +.P +The +.BR set_robust_list () +system call requests the kernel to record the head of the list of +robust futexes owned by the calling thread. +The +.I head +argument is the list head to record. +The +.I len +argument should be +.IR sizeof(*head) . +.SH RETURN VALUE +The +.BR set_robust_list () +and +.BR get_robust_list () +system calls return zero when the operation is successful, +an error code otherwise. +.SH ERRORS +The +.BR set_robust_list () +system call can fail with the following error: +.TP +.B EINVAL +.I len +does not equal +.IR "sizeof(struct\ robust_list_head)" . +.P +The +.BR get_robust_list () +system call can fail with the following errors: +.TP +.B EFAULT +The head of the robust futex list can't be stored at the location +.IR head . +.TP +.B EPERM +The calling process does not have permission to see the robust futex list of +the thread with the thread ID +.IR pid , +and does not have the +.B CAP_SYS_PTRACE +capability. +.TP +.B ESRCH +No thread with the thread ID +.I pid +could be found. +.SH VERSIONS +These system calls were added in Linux 2.6.17. +.SH NOTES +These system calls are not needed by normal applications. +.P +A thread can have only one robust futex list; +therefore applications that wish +to use this functionality should use the robust mutexes provided by glibc. +.P +In the initial implementation, +a thread waiting on a futex was notified that the owner had died +only if the owner terminated. +Starting with Linux 2.6.28, +.\" commit 8141c7f3e7aee618312fa1c15109e1219de784a7 +notification was extended to include the case where the owner performs an +.BR execve (2). +.P +The thread IDs mentioned in the main text are +.I kernel +thread IDs of the kind returned by +.BR clone (2) +and +.BR gettid (2). +.SH SEE ALSO +.BR futex (2), +.BR pthread_mutexattr_setrobust (3) +.P +.I Documentation/robust\-futexes.txt +and +.I Documentation/robust\-futex\-ABI.txt +in the Linux kernel source tree +.\" http://lwn.net/Articles/172149/ diff --git a/man/man2/get_thread_area.2 b/man/man2/get_thread_area.2 new file mode 100644 index 0000000..a03fe54 --- /dev/null +++ b/man/man2/get_thread_area.2 @@ -0,0 +1 @@ +.so man2/set_thread_area.2 diff --git a/man/man2/getcpu.2 b/man/man2/getcpu.2 new file mode 100644 index 0000000..f2097f9 --- /dev/null +++ b/man/man2/getcpu.2 @@ -0,0 +1,147 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 2006 Andi Kleen . +.\" +.\" 2008, mtk, various edits +.\" +.TH getcpu 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getcpu \- determine CPU and NUMA node on which the calling thread is running +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int getcpu(unsigned int *_Nullable " cpu ", \ +unsigned int *_Nullable " node ); +.fi +.SH DESCRIPTION +The +.BR getcpu () +system call identifies the processor and node on which the calling +thread or process is currently running and writes them into the +integers pointed to by the +.I cpu +and +.I node +arguments. +The processor is a unique small integer identifying a CPU. +The node is a unique small identifier identifying a NUMA node. +When either +.I cpu +or +.I node +is NULL nothing is written to the respective pointer. +.P +The information placed in +.I cpu +is guaranteed to be current only at the time of the call: +unless the CPU affinity has been fixed using +.BR sched_setaffinity (2), +the kernel might change the CPU at any time. +(Normally this does not happen +because the scheduler tries to minimize movements between CPUs to +keep caches hot, but it is possible.) +The caller must allow for the possibility that the information returned in +.I cpu +and +.I node +is no longer current by the time the call returns. +.SH RETURN VALUE +On success, 0 is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Arguments point outside the calling process's address space. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.19 (x86-64 and i386), +glibc 2.29. +.\" +.SS C library/kernel differences +The kernel system call has a third argument: +.P +.in +4n +.nf +.BI "int getcpu(unsigned int *" cpu ", unsigned int *" node , +.BI " struct getcpu_cache *" tcache ); +.fi +.in +.P +The +.I tcache +argument is unused since Linux 2.6.24, +and (when invoking the system call directly) +should be specified as NULL, +unless portability to Linux 2.6.23 or earlier is required. +.P +.\" commit 4307d1e5ada595c87f9a4d16db16ba5edb70dcb1 +.\" Author: Ingo Molnar +.\" Date: Wed Nov 7 18:37:48 2007 +0100 +.\" x86: ignore the sys_getcpu() tcache parameter +In Linux 2.6.23 and earlier, if the +.I tcache +argument was non-NULL, +then it specified a pointer to a caller-allocated buffer in thread-local +storage that was used to provide a caching mechanism for +.BR getcpu (). +Use of the cache could speed +.BR getcpu () +calls, at the cost that there was a very small chance that +the returned information would be out of date. +The caching mechanism was considered to cause problems when +migrating threads between CPUs, and so the argument is now ignored. +.\" +.\" ===== Before Linux 2.6.24: ===== +.\" .I tcache +.\" is a pointer to a +.\" .IR "struct getcpu_cache" +.\" that is used as a cache by +.\" .BR getcpu (). +.\" The caller should put the cache into a thread-local variable +.\" if the process is multithreaded, +.\" because the cache cannot be shared between different threads. +.\" .I tcache +.\" can be NULL. +.\" If it is not NULL +.\" .BR getcpu () +.\" will use it to speed up operation. +.\" The information inside the cache is private to the system call +.\" and should not be accessed by the user program. +.\" The information placed in the cache can change between Linux releases. +.\" +.\" When no cache is specified +.\" .BR getcpu () +.\" will be slower, +.\" but always retrieve the current CPU and node information. +.\" With a cache +.\" .BR getcpu () +.\" is faster. +.\" However, the cached information is updated only once per jiffy (see +.\" .BR time (7)). +.\" This means that the information could theoretically be out of date, +.\" although in practice the scheduler's attempt to maintain +.\" soft CPU affinity means that the information is unlikely to change +.\" over the course of the caching interval. +.SH NOTES +Linux makes a best effort to make this call as fast as possible. +(On some architectures, this is done via an implementation in the +.BR vdso (7).) +The intention of +.BR getcpu () +is to allow programs to make optimizations with per-CPU data +or for NUMA optimization. +.SH SEE ALSO +.BR mbind (2), +.BR sched_setaffinity (2), +.BR set_mempolicy (2), +.BR sched_getcpu (3), +.BR cpuset (7), +.BR vdso (7) diff --git a/man/man2/getcwd.2 b/man/man2/getcwd.2 new file mode 100644 index 0000000..f080be0 --- /dev/null +++ b/man/man2/getcwd.2 @@ -0,0 +1,2 @@ +.so man3/getcwd.3 +.\" Because getcwd(3) is layered on a system call of the same name diff --git a/man/man2/getdents.2 b/man/man2/getdents.2 new file mode 100644 index 0000000..5b26de7 --- /dev/null +++ b/man/man2/getdents.2 @@ -0,0 +1,324 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright 2008, 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Written 11 June 1995 by Andries Brouwer +.\" Modified 22 July 1995 by Michael Chastain : +.\" Derived from 'readdir.2'. +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" +.TH getdents 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getdents, getdents64 \- get directory entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "long syscall(SYS_getdents, unsigned int " fd \ +", struct linux_dirent *" dirp , +.BI " unsigned int " count ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "ssize_t getdents64(int " fd ", void " dirp [. count "], size_t " count ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR getdents (), +necessitating the use of +.BR syscall (2). +.P +.IR Note : +There is no definition of +.I struct linux_dirent +in glibc; see NOTES. +.SH DESCRIPTION +These are not the interfaces you are interested in. +Look at +.BR readdir (3) +for the POSIX-conforming C library interface. +This page documents the bare kernel system call interfaces. +.SS getdents() +The system call +.BR getdents () +reads several +.I linux_dirent +structures from the directory +referred to by the open file descriptor +.I fd +into the buffer pointed to by +.IR dirp . +The argument +.I count +specifies the size of that buffer. +.P +The +.I linux_dirent +structure is declared as follows: +.P +.in +4n +.EX +struct linux_dirent { + unsigned long d_ino; /* Inode number */ + unsigned long d_off; /* Not an offset; see below */ + unsigned short d_reclen; /* Length of this \fIlinux_dirent\fP */ + char d_name[]; /* Filename (null\-terminated) */ + /* length is actually (d_reclen \- 2 \- + offsetof(struct linux_dirent, d_name)) */ + /* + char pad; // Zero padding byte + char d_type; // File type (only since Linux + // 2.6.4); offset is (d_reclen \- 1) + */ +} +.EE +.in +.P +.I d_ino +is an inode number. +.I d_off +is a filesystem-specific value with no specific meaning to user space, +though on older filesystems it used to be +the distance from the start of the directory to the start of the next +.IR linux_dirent ; +see +.BR readdir (3) . +.I d_reclen +is the size of this entire +.IR linux_dirent . +.I d_name +is a null-terminated filename. +.P +.I d_type +is a byte at the end of the structure that indicates the file type. +It contains one of the following values (defined in +.IR ): +.TP 12 +.B DT_BLK +This is a block device. +.TP +.B DT_CHR +This is a character device. +.TP +.B DT_DIR +This is a directory. +.TP +.B DT_FIFO +This is a named pipe (FIFO). +.TP +.B DT_LNK +This is a symbolic link. +.TP +.B DT_REG +This is a regular file. +.TP +.B DT_SOCK +This is a UNIX domain socket. +.TP +.B DT_UNKNOWN +The file type is unknown. +.P +The +.I d_type +field is implemented since Linux 2.6.4. +It occupies a space that was previously a zero-filled padding byte in the +.I linux_dirent +structure. +Thus, on kernels up to and including Linux 2.6.3, +attempting to access this field always provides the value 0 +.RB ( DT_UNKNOWN ). +.P +Currently, +.\" kernel 2.6.27 +.\" The same sentence is in readdir.2 +only some filesystems (among them: Btrfs, ext2, ext3, and ext4) +have full support for returning the file type in +.IR d_type . +All applications must properly handle a return of +.BR DT_UNKNOWN . +.SS getdents64() +The original Linux +.BR getdents () +system call did not handle large filesystems and large file offsets. +Consequently, Linux 2.4 added +.BR getdents64 (), +with wider types for the +.I d_ino +and +.I d_off +fields. +In addition, +.BR getdents64 () +supports an explicit +.I d_type +field. +.P +The +.BR getdents64 () +system call is like +.BR getdents (), +except that its second argument is a pointer to a buffer containing +structures of the following type: +.P +.in +4n +.EX +struct linux_dirent64 { + ino64_t d_ino; /* 64\-bit inode number */ + off64_t d_off; /* Not an offset; see getdents() */ + unsigned short d_reclen; /* Size of this dirent */ + unsigned char d_type; /* File type */ + char d_name[]; /* Filename (null\-terminated) */ +}; +.EE +.in +.SH RETURN VALUE +On success, the number of bytes read is returned. +On end of directory, 0 is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +Invalid file descriptor +.IR fd . +.TP +.B EFAULT +Argument points outside the calling process's address space. +.TP +.B EINVAL +Result buffer is too small. +.TP +.B ENOENT +No such directory. +.TP +.B ENOTDIR +File descriptor does not refer to a directory. +.SH STANDARDS +None. +.SH HISTORY +SVr4. +.\" SVr4 documents additional ENOLINK, EIO error conditions. +.TP +.BR getdents64 () +glibc 2.30. +.SH NOTES +glibc does not provide a wrapper for +.BR getdents (); +call +.BR getdents () +using +.BR syscall (2). +In that case you will need to define the +.I linux_dirent +or +.I linux_dirent64 +structure yourself. +.P +Probably, you want to use +.BR readdir (3) +instead of these system calls. +.P +These calls supersede +.BR readdir (2). +.SH EXAMPLES +.\" FIXME The example program needs to be revised, since it uses the older +.\" getdents() system call and the structure with smaller field widths. +The program below demonstrates the use of +.BR getdents (). +The following output shows an example of what we see when running this +program on an ext2 directory: +.P +.in +4n +.EX +.RB "$" " ./a.out /testfs/" +-\-\-\-\-\-\-\-\-\-\-\-\-\-\- nread=120 \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +inode# file type d_reclen d_off d_name + 2 directory 16 12 . + 2 directory 16 24 .. + 11 directory 24 44 lost+found + 12 regular 16 56 a + 228929 directory 16 68 sub + 16353 directory 16 80 sub2 + 130817 directory 16 4096 sub3 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (getdents.c) +.EX +#define _GNU_SOURCE +#include /* Defines DT_* constants */ +#include +#include +#include +#include +#include +#include +#include +#include +\& +struct linux_dirent { + unsigned long d_ino; + off_t d_off; + unsigned short d_reclen; + char d_name[]; +}; +\& +#define BUF_SIZE 1024 +\& +int +main(int argc, char *argv[]) +{ + int fd; + char d_type; + char buf[BUF_SIZE]; + long nread; + struct linux_dirent *d; +\& + fd = open(argc > 1 ? argv[1] : ".", O_RDONLY | O_DIRECTORY); + if (fd == \-1) + err(EXIT_FAILURE, "open"); +\& + for (;;) { + nread = syscall(SYS_getdents, fd, buf, BUF_SIZE); + if (nread == \-1) + err(EXIT_FAILURE, "getdents"); +\& + if (nread == 0) + break; +\& + printf("\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- nread=%ld \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\en", nread); + printf("inode# file type d_reclen d_off d_name\en"); + for (size_t bpos = 0; bpos < nread;) { + d = (struct linux_dirent *) (buf + bpos); + printf("%8lu ", d\->d_ino); + d_type = *(buf + bpos + d\->d_reclen \- 1); + printf("%\-10s ", (d_type == DT_REG) ? "regular" : + (d_type == DT_DIR) ? "directory" : + (d_type == DT_FIFO) ? "FIFO" : + (d_type == DT_SOCK) ? "socket" : + (d_type == DT_LNK) ? "symlink" : + (d_type == DT_BLK) ? "block dev" : + (d_type == DT_CHR) ? "char dev" : "???"); + printf("%4d %10jd %s\en", d\->d_reclen, + (intmax_t) d\->d_off, d\->d_name); + bpos += d\->d_reclen; + } + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR readdir (2), +.BR readdir (3), +.BR inode (7) diff --git a/man/man2/getdents64.2 b/man/man2/getdents64.2 new file mode 100644 index 0000000..f3674ba --- /dev/null +++ b/man/man2/getdents64.2 @@ -0,0 +1 @@ +.so man2/getdents.2 diff --git a/man/man2/getdomainname.2 b/man/man2/getdomainname.2 new file mode 100644 index 0000000..8bee80e --- /dev/null +++ b/man/man2/getdomainname.2 @@ -0,0 +1,122 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1997-08-25 by Nicolás Lichtmaier +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2008-11-27 by mtk +.\" +.TH getdomainname 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getdomainname, setdomainname \- get/set NIS domain name +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getdomainname(char *" name ", size_t " len ); +.BI "int setdomainname(const char *" name ", size_t " len ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getdomainname (), +.BR setdomainname (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +These functions are used to access or to change the NIS domain name of the +host system. +More precisely, they operate on the NIS domain name associated with the calling +process's UTS namespace. +.P +.BR setdomainname () +sets the domain name to the value given in the character array +.IR name . +The +.I len +argument specifies the number of bytes in +.IR name . +(Thus, +.I name +does not require a terminating null byte.) +.P +.BR getdomainname () +returns the null-terminated domain name in the character array +.IR name , +which has a length of +.I len +bytes. +If the null-terminated domain name requires more than \fIlen\fP bytes, +.BR getdomainname () +returns the first \fIlen\fP bytes (glibc) or gives an error (libc). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR setdomainname () +can fail with the following errors: +.TP +.B EFAULT +.I name +pointed outside of user address space. +.TP +.B EINVAL +.I len +was negative or too large. +.TP +.B EPERM +The caller did not have the +.B CAP_SYS_ADMIN +capability in the user namespace associated with its UTS namespace (see +.BR namespaces (7)). +.P +.BR getdomainname () +can fail with the following errors: +.TP +.B EINVAL +For +.BR getdomainname () +under libc: +.I name +is NULL or +.I name +is longer than +.I len +bytes. +.SH VERSIONS +On most Linux architectures (including x86), +there is no +.BR getdomainname () +system call; instead, glibc implements +.BR getdomainname () +as a library function that returns a copy of the +.I domainname +field returned from a call to +.BR uname (2). +.SH STANDARDS +None. +.\" But they appear on most systems... +.SH HISTORY +Since Linux 1.0, the limit on the length of a domain name, +including the terminating null byte, is 64 bytes. +In older kernels, it was 8 bytes. +.SH SEE ALSO +.BR gethostname (2), +.BR sethostname (2), +.BR uname (2), +.BR uts_namespaces (7) diff --git a/man/man2/getegid.2 b/man/man2/getegid.2 new file mode 100644 index 0000000..d9b10e7 --- /dev/null +++ b/man/man2/getegid.2 @@ -0,0 +1 @@ +.so man2/getgid.2 diff --git a/man/man2/getegid32.2 b/man/man2/getegid32.2 new file mode 100644 index 0000000..d7da708 --- /dev/null +++ b/man/man2/getegid32.2 @@ -0,0 +1 @@ +.so man2/getegid.2 diff --git a/man/man2/geteuid.2 b/man/man2/geteuid.2 new file mode 100644 index 0000000..165cfe1 --- /dev/null +++ b/man/man2/geteuid.2 @@ -0,0 +1 @@ +.so man2/getuid.2 diff --git a/man/man2/geteuid32.2 b/man/man2/geteuid32.2 new file mode 100644 index 0000000..8e60b77 --- /dev/null +++ b/man/man2/geteuid32.2 @@ -0,0 +1 @@ +.so man2/geteuid.2 diff --git a/man/man2/getgid.2 b/man/man2/getgid.2 new file mode 100644 index 0000000..2d4dd50 --- /dev/null +++ b/man/man2/getgid.2 @@ -0,0 +1,70 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getgid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getgid, getegid \- get group identity +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B gid_t getgid(void); +.B gid_t getegid(void); +.fi +.SH DESCRIPTION +.BR getgid () +returns the real group ID of the calling process. +.P +.BR getegid () +returns the effective group ID of the calling process. +.SH ERRORS +These functions are always successful +and never modify +.\" https://www.austingroupbugs.net/view.php?id=511 +.\" 0000511: getuid and friends should not modify errno +.IR errno . +.SH VERSIONS +On Alpha, instead of a pair of +.BR getgid () +and +.BR getegid () +system calls, a single +.BR getxgid () +system call is provided, which returns a pair of real and effective GIDs. +The glibc +.BR getgid () +and +.BR getegid () +wrapper functions transparently deal with this. +See +.BR syscall (2) +for details regarding register mapping. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.P +The original Linux +.BR getgid () +and +.BR getegid () +system calls supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR getgid32 () +and +.BR getegid32 (), +supporting 32-bit IDs. +The glibc +.BR getgid () +and +.BR getegid () +wrapper functions transparently deal with the variations across kernel versions. +.SH SEE ALSO +.BR getresgid (2), +.BR setgid (2), +.BR setregid (2), +.BR credentials (7) diff --git a/man/man2/getgid32.2 b/man/man2/getgid32.2 new file mode 100644 index 0000000..d9b10e7 --- /dev/null +++ b/man/man2/getgid32.2 @@ -0,0 +1 @@ +.so man2/getgid.2 diff --git a/man/man2/getgroups.2 b/man/man2/getgroups.2 new file mode 100644 index 0000000..9859cf5 --- /dev/null +++ b/man/man2/getgroups.2 @@ -0,0 +1,219 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" and Copyright (C) 2008, 2010, 2015, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Thu Oct 31 12:04:29 1996 by Eric S. Raymond +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" 2008-05-03, mtk, expanded and rewrote parts of DESCRIPTION and RETURN +.\" VALUE, made style of page more consistent with man-pages style. +.\" +.TH getgroups 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getgroups, setgroups \- get/set list of supplementary group IDs +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getgroups(int " size ", gid_t " list []); +.P +.B #include +.P +.BI "int setgroups(size_t " size ", const gid_t *_Nullable " list ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setgroups (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR getgroups () +returns the supplementary group IDs of the calling process in +.IR list . +The argument +.I size +should be set to the maximum number of items that can be stored in the +buffer pointed to by +.IR list . +If the calling process is a member of more than +.I size +supplementary groups, then an error results. +.P +It is unspecified whether the effective group ID of the calling process +is included in the returned list. +(Thus, an application should also call +.BR getegid (2) +and add or remove the resulting value.) +.P +If +.I size +is zero, +.I list +is not modified, but the total number of supplementary group IDs for the +process is returned. +This allows the caller to determine the size of a dynamically allocated +.I list +to be used in a further call to +.BR getgroups (). +.P +.BR setgroups () +sets the supplementary group IDs for the calling process. +Appropriate privileges are required (see the description of the +.B EPERM +error, below). +The +.I size +argument specifies the number of supplementary group IDs +in the buffer pointed to by +.IR list . +A process can drop all of its supplementary groups with the call: +.P +.in +4n +.EX +setgroups(0, NULL); +.EE +.in +.SH RETURN VALUE +On success, +.BR getgroups () +returns the number of supplementary group IDs. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +On success, +.BR setgroups () +returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I list +has an invalid address. +.P +.BR getgroups () +can additionally fail with the following error: +.TP +.B EINVAL +.I size +is less than the number of supplementary group IDs, but is not zero. +.P +.BR setgroups () +can additionally fail with the following errors: +.TP +.B EINVAL +.I size +is greater than +.B NGROUPS_MAX +(32 before Linux 2.6.4; 65536 since Linux 2.6.4). +.TP +.B ENOMEM +Out of memory. +.TP +.B EPERM +The calling process has insufficient privilege +(the caller does not have the +.B CAP_SETGID +capability in the user namespace in which it resides). +.TP +.BR EPERM " (since Linux 3.19)" +The use of +.BR setgroups () +is denied in this user namespace. +See the description of +.IR /proc/ pid /setgroups +in +.BR user_namespaces (7). +.SH VERSIONS +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including the one for +.BR setgroups ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). +.SH STANDARDS +.TP +.BR getgroups () +POSIX.1-2008. +.TP +.BR setgroups () +None. +.SH HISTORY +.TP +.BR getgroups () +SVr4, 4.3BSD, POSIX.1-2001. +.TP +.BR setgroups () +SVr4, 4.3BSD. +Since +.BR setgroups () +requires privilege, it is not covered by POSIX.1. +.P +The original Linux +.BR getgroups () +system call supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR getgroups32 (), +supporting 32-bit IDs. +The glibc +.BR getgroups () +wrapper function transparently deals with the variation across kernel versions. +.SH NOTES +A process can have up to +.B NGROUPS_MAX +supplementary group IDs +in addition to the effective group ID. +The constant +.B NGROUPS_MAX +is defined in +.IR . +The set of supplementary group IDs +is inherited from the parent process, and preserved across an +.BR execve (2). +.P +The maximum number of supplementary group IDs can be found at run time using +.BR sysconf (3): +.P +.in +4n +.EX +long ngroups_max; +ngroups_max = sysconf(_SC_NGROUPS_MAX); +.EE +.in +.P +The maximum return value of +.BR getgroups () +cannot be larger than one more than this value. +Since Linux 2.6.4, the maximum number of supplementary group IDs is also +exposed via the Linux-specific read-only file, +.IR /proc/sys/kernel/ngroups_max . +.SH SEE ALSO +.BR getgid (2), +.BR setgid (2), +.BR getgrouplist (3), +.BR group_member (3), +.BR initgroups (3), +.BR capabilities (7), +.BR credentials (7) diff --git a/man/man2/getgroups32.2 b/man/man2/getgroups32.2 new file mode 100644 index 0000000..0ae4cc0 --- /dev/null +++ b/man/man2/getgroups32.2 @@ -0,0 +1 @@ +.so man2/getgroups.2 diff --git a/man/man2/gethostname.2 b/man/man2/gethostname.2 new file mode 100644 index 0000000..f2720fb --- /dev/null +++ b/man/man2/gethostname.2 @@ -0,0 +1,176 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1995-07-22 by Michael Chastain : +.\" 'gethostname' is real system call on Linux/Alpha. +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2000-06-04, 2001-12-15 by aeb +.\" Modified 2004-06-17 by mtk +.\" Modified 2008-11-27 by mtk +.\" +.TH gethostname 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gethostname, sethostname \- get/set hostname +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int gethostname(char *" name ", size_t " len ); +.BI "int sethostname(const char *" name ", size_t " len ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gethostname (): +.nf + _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L + || /* glibc 2.19 and earlier */ _BSD_SOURCE +.\" The above is something of a simplification +.\" also before glibc 2.3 there was a bit churn +.fi +.P +.BR sethostname (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +These system calls are used to access or to change the system hostname. +More precisely, they operate on the hostname associated with the calling +process's UTS namespace. +.P +.BR sethostname () +sets the hostname to the value given in the character array +.IR name . +The +.I len +argument specifies the number of bytes in +.IR name . +(Thus, +.I name +does not require a terminating null byte.) +.P +.BR gethostname () +returns the null-terminated hostname in the character array +.IR name , +which has a length of +.I len +bytes. +If the null-terminated hostname is too large to fit, +then the name is truncated, and no error is returned (but see NOTES below). +POSIX.1 says that if such truncation occurs, +then it is unspecified whether the returned buffer +includes a terminating null byte. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I name +is an invalid address. +.TP +.B EINVAL +.I len +is negative +.\" Can't occur for gethostbyname() wrapper, since 'len' has an +.\" unsigned type; can occur for the underlying system call. +or, for +.BR sethostname (), +.I len +is larger than the maximum allowed size. +.TP +.B ENAMETOOLONG +.RB "(glibc " gethostname ()) +.I len +is smaller than the actual size. +(Before glibc 2.1, glibc uses +.B EINVAL +for this case.) +.TP +.B EPERM +For +.BR sethostname (), +the caller did not have the +.B CAP_SYS_ADMIN +capability in the user namespace associated with its UTS namespace (see +.BR namespaces (7)). +.SH VERSIONS +SUSv2 guarantees that "Host names are limited to 255 bytes". +POSIX.1 guarantees that "Host names (not including +the terminating null byte) are limited to +.B HOST_NAME_MAX +bytes". +On Linux, +.B HOST_NAME_MAX +is defined with the value 64, which has been the limit since Linux 1.0 +(earlier kernels imposed a limit of 8 bytes). +.SS C library/kernel differences +The GNU C library does not employ the +.BR gethostname () +system call; instead, it implements +.BR gethostname () +as a library function that calls +.BR uname (2) +and copies up to +.I len +bytes from the returned +.I nodename +field into +.IR name . +Having performed the copy, the function then checks if the length of the +.I nodename +was greater than or equal to +.IR len , +and if it is, then the function returns \-1 with +.I errno +set to +.BR ENAMETOOLONG ; +in this case, a terminating null byte is not included in the returned +.IR name . +.SH STANDARDS +.TP +.BR gethostname () +POSIX.1-2008. +.TP +.BR sethostname () +None. +.SH HISTORY +SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). +POSIX.1-2001 and POSIX.1-2008 specify +.BR gethostname () +but not +.BR sethostname (). +.P +Versions of glibc before glibc 2.2 +.\" At least glibc 2.0 and glibc 2.1, older versions not checked +handle the case where the length of the +.I nodename +was greater than or equal to +.I len +differently: nothing is copied into +.I name +and the function returns \-1 with +.I errno +set to +.BR ENAMETOOLONG . +.SH SEE ALSO +.BR hostname (1), +.BR getdomainname (2), +.BR setdomainname (2), +.BR uname (2), +.BR uts_namespaces (7) diff --git a/man/man2/getitimer.2 b/man/man2/getitimer.2 new file mode 100644 index 0000000..729765d --- /dev/null +++ b/man/man2/getitimer.2 @@ -0,0 +1,278 @@ +.\" Copyright 7/93 by Darren Senn +.\" and Copyright (C) 2016, Michael Kerrisk +.\" Based on a similar page Copyright 1992 by Rick Faith +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" May be freely distributed and modified +.\" %%%LICENSE_END +.\" +.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond +.\" 2005-04-06 mtk, Matthias Lang +.\" Noted MAX_SEC_IN_JIFFIES ceiling +.\" +.TH getitimer 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getitimer, setitimer \- get or set value of an interval timer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getitimer(int " which ", struct itimerval *" curr_value ); +.BI "int setitimer(int " which ", const struct itimerval *restrict " new_value , +.BI " struct itimerval *_Nullable restrict " old_value ); +.fi +.SH DESCRIPTION +These system calls provide access to interval timers, that is, +timers that initially expire at some point in the future, +and (optionally) at regular intervals after that. +When a timer expires, a signal is generated for the calling process, +and the timer is reset to the specified interval +(if the interval is nonzero). +.P +Three types of timers\[em]specified via the +.I which +argument\[em]are provided, +each of which counts against a different clock and +generates a different signal on timer expiration: +.TP +.B ITIMER_REAL +This timer counts down in real (i.e., wall clock) time. +At each expiration, a +.B SIGALRM +signal is generated. +.TP +.B ITIMER_VIRTUAL +This timer counts down against the user-mode CPU time consumed by the process. +(The measurement includes CPU time consumed by all threads in the process.) +At each expiration, a +.B SIGVTALRM +signal is generated. +.TP +.B ITIMER_PROF +This timer counts down against the total (i.e., both user and system) +CPU time consumed by the process. +(The measurement includes CPU time consumed by all threads in the process.) +At each expiration, a +.B SIGPROF +signal is generated. +.IP +In conjunction with +.BR ITIMER_VIRTUAL , +this timer can be used to profile user and system CPU time +consumed by the process. +.P +A process has only one of each of the three types of timers. +.P +Timer values are defined by the following structures: +.P +.in +4n +.EX +struct itimerval { + struct timeval it_interval; /* Interval for periodic timer */ + struct timeval it_value; /* Time until next expiration */ +}; +\& +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.\" +.SS getitimer() +The function +.BR getitimer () +places the current value of the timer specified by +.I which +in the buffer pointed to by +.IR curr_value . +.P +The +.I it_value +substructure is populated with the amount of time remaining until +the next expiration of the specified timer. +This value changes as the timer counts down, and will be reset to +.I it_interval +when the timer expires. +If both fields of +.I it_value +are zero, then this timer is currently disarmed (inactive). +.P +The +.I it_interval +substructure is populated with the timer interval. +If both fields of +.I it_interval +are zero, then this is a single-shot timer (i.e., it expires just once). +.SS setitimer() +The function +.BR setitimer () +arms or disarms the timer specified by +.IR which , +by setting the timer to the value specified by +.IR new_value . +If +.I old_value +is non-NULL, +the buffer it points to is used to return the previous value of the timer +(i.e., the same information that is returned by +.BR getitimer ()). +.P +If either field in +.I new_value.it_value +is nonzero, +then the timer is armed to initially expire at the specified time. +If both fields in +.I new_value.it_value +are zero, then the timer is disarmed. +.P +The +.I new_value.it_interval +field specifies the new interval for the timer; +if both of its subfields are zero, the timer is single-shot. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.IR new_value , +.IR old_value , +or +.I curr_value +is not valid a pointer. +.TP +.B EINVAL +.I which +is not one of +.BR ITIMER_REAL , +.BR ITIMER_VIRTUAL , +or +.BR ITIMER_PROF ; +or (since Linux 2.6.22) one of the +.I tv_usec +fields in the structure pointed to by +.I new_value +contains a value outside the range [0, 999999]. +.SH VERSIONS +The standards are silent on the meaning of the call: +.P +.in +4n +.EX +setitimer(which, NULL, &old_value); +.EE +.in +.P +Many systems (Solaris, the BSDs, and perhaps others) +treat this as equivalent to: +.P +.in +4n +.EX +getitimer(which, &old_value); +.EE +.in +.P +In Linux, this is treated as being equivalent to a call in which the +.I new_value +fields are zero; that is, the timer is disabled. +.IR "Don't use this Linux misfeature" : +it is nonportable and unnecessary. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD). +POSIX.1-2008 marks +.BR getitimer () +and +.BR setitimer () +obsolete, recommending the use of the POSIX timers API +.RB ( timer_gettime (2), +.BR timer_settime (2), +etc.) instead. +.SH NOTES +Timers will never expire before the requested time, +but may expire some (short) time afterward, which depends +on the system timer resolution and on the system load; see +.BR time (7). +(But see BUGS below.) +If the timer expires while the process is active (always true for +.BR ITIMER_VIRTUAL ), +the signal will be delivered immediately when generated. +.P +A child created via +.BR fork (2) +does not inherit its parent's interval timers. +Interval timers are preserved across an +.BR execve (2). +.P +POSIX.1 leaves the +interaction between +.BR setitimer () +and the three interfaces +.BR alarm (2), +.BR sleep (3), +and +.BR usleep (3) +unspecified. +.SH BUGS +The generation and delivery of a signal are distinct, and +only one instance of each of the signals listed above may be pending +for a process. +Under very heavy loading, an +.B ITIMER_REAL +timer may expire before the signal from a previous expiration +has been delivered. +The second signal in such an event will be lost. +.P +Before Linux 2.6.16, timer values are represented in jiffies. +If a request is made set a timer with a value whose jiffies +representation exceeds +.B MAX_SEC_IN_JIFFIES +(defined in +.IR include/linux/jiffies.h ), +then the timer is silently truncated to this ceiling value. +On Linux/i386 (where, since Linux 2.6.13, +the default jiffy is 0.004 seconds), +this means that the ceiling value for a timer is +approximately 99.42 days. +Since Linux 2.6.16, +the kernel uses a different internal representation for times, +and this ceiling is removed. +.P +On certain systems (including i386), +Linux kernels before Linux 2.6.12 have a bug which will produce +premature timer expirations of up to one jiffy under some circumstances. +This bug is fixed in Linux 2.6.12. +.\" 4 Jul 2005: It looks like this bug may remain in Linux 2.4.x. +.\" http://lkml.org/lkml/2005/7/1/165 +.P +POSIX.1-2001 says that +.BR setitimer () +should fail if a +.I tv_usec +value is specified that is outside of the range [0, 999999]. +However, up to and including Linux 2.6.21, +Linux does not give an error, but instead silently +adjusts the corresponding seconds value for the timer. +From Linux 2.6.22 onward, +this nonconformance has been repaired: +an improper +.I tv_usec +value results in an +.B EINVAL +error. +.\" Bugzilla report 25 Apr 2006: +.\" http://bugzilla.kernel.org/show_bug.cgi?id=6443 +.\" "setitimer() should reject noncanonical arguments" +.SH SEE ALSO +.BR gettimeofday (2), +.BR sigaction (2), +.BR signal (2), +.BR timer_create (2), +.BR timerfd_create (2), +.BR time (7) diff --git a/man/man2/getmsg.2 b/man/man2/getmsg.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/getmsg.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/getpagesize.2 b/man/man2/getpagesize.2 new file mode 100644 index 0000000..1bfcad3 --- /dev/null +++ b/man/man2/getpagesize.2 @@ -0,0 +1,67 @@ +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getpagesize 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpagesize \- get memory page size +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B int getpagesize(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getpagesize (): +.nf + Since glibc 2.20: + _DEFAULT_SOURCE || ! (_POSIX_C_SOURCE >= 200112L) + glibc 2.12 to glibc 2.19: + _BSD_SOURCE || ! (_POSIX_C_SOURCE >= 200112L) + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +The function +.BR getpagesize () +returns the number of bytes in a memory page, +where "page" is a fixed-length block, +the unit for memory allocation and file mapping performed by +.BR mmap (2). +.SH VERSIONS +A user program should not hard-code a page size, +neither as a literal nor using the +.B PAGE_SIZE +macro, +because some architectures support multiple page sizes. +.P +This manual page is in section 2 because +Alpha, SPARC, and SPARC64 +all have a Linux system call +.BR getpagesize () +though other architectures do not, +and use the ELF auxiliary vector instead. +.SH STANDARDS +None. +.SH HISTORY +This call first appeared in 4.2BSD. +SVr4, 4.4BSD, SUSv2. +In SUSv2 the +.BR getpagesize () +call was labeled LEGACY, +and it was removed in POSIX.1-2001. +.P +glibc 2.0 returned a constant +even on architectures with multiple page sizes. +.SH SEE ALSO +.BR mmap (2), +.BR sysconf (3) diff --git a/man/man2/getpeername.2 b/man/man2/getpeername.2 new file mode 100644 index 0000000..81089bc --- /dev/null +++ b/man/man2/getpeername.2 @@ -0,0 +1,116 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)getpeername.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 16:37:50 1993 by Rik Faith +.\" Modified Thu Jul 30 14:37:50 1993 by Martin Schulze +.\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer +.\" Modified 17 Jul 2002, Michael Kerrisk +.\" Added 'socket' to NAME, so that "man -k socket" will show this page. +.\" +.TH getpeername 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpeername \- get name of connected peer socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getpeername(int " sockfd ", struct sockaddr *restrict " addr , +.BI " socklen_t *restrict " addrlen ); +.fi +.SH DESCRIPTION +.BR getpeername () +returns the address of the peer connected to the socket +.IR sockfd , +in the buffer pointed to by +.IR addr . +The +.I addrlen +argument should be initialized to indicate the amount of space pointed to +by +.IR addr . +On return it contains the actual size of the name returned (in bytes). +The name is truncated if the buffer provided is too small. +.P +The returned address is truncated if the buffer provided is too small; +in this case, +.I addrlen +will return a value greater than was supplied to the call. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The argument +.I sockfd +is not a valid file descriptor. +.TP +.B EFAULT +The +.I addr +argument points to memory not in a valid part of the +process address space. +.TP +.B EINVAL +.I addrlen +is invalid (e.g., is negative). +.TP +.B ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.TP +.B ENOTCONN +The socket is not connected. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD +(first appeared in 4.2BSD). +.SH NOTES +For stream sockets, once a +.BR connect (2) +has been performed, either socket can call +.BR getpeername () +to obtain the address of the peer socket. +On the other hand, datagram sockets are connectionless. +Calling +.BR connect (2) +on a datagram socket merely sets the peer address for outgoing +datagrams sent with +.BR write (2) +or +.BR recv (2). +The caller of +.BR connect (2) +can use +.BR getpeername () +to obtain the peer address that it earlier set for the socket. +However, the peer socket is unaware of this information, and calling +.BR getpeername () +on the peer socket will return no useful information (unless a +.BR connect (2) +call was also executed on the peer). +Note also that the receiver of a datagram can obtain +the address of the sender when using +.BR recvfrom (2). +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR getsockname (2), +.BR ip (7), +.BR socket (7), +.BR unix (7) diff --git a/man/man2/getpgid.2 b/man/man2/getpgid.2 new file mode 100644 index 0000000..d6b107a --- /dev/null +++ b/man/man2/getpgid.2 @@ -0,0 +1 @@ +.so man2/setpgid.2 diff --git a/man/man2/getpgrp.2 b/man/man2/getpgrp.2 new file mode 100644 index 0000000..d6b107a --- /dev/null +++ b/man/man2/getpgrp.2 @@ -0,0 +1 @@ +.so man2/setpgid.2 diff --git a/man/man2/getpid.2 b/man/man2/getpid.2 new file mode 100644 index 0000000..fafcb6c --- /dev/null +++ b/man/man2/getpid.2 @@ -0,0 +1,150 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getpid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpid, getppid \- get process identification +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B pid_t getpid(void); +.B pid_t getppid(void); +.fi +.SH DESCRIPTION +.BR getpid () +returns the process ID (PID) of the calling process. +(This is often used by +routines that generate unique temporary filenames.) +.P +.BR getppid () +returns the process ID of the parent of the calling process. +This will be either the ID of the process that created this process using +.BR fork (), +or, if that process has already terminated, +the ID of the process to which this process has been reparented (either +.BR init (1) +or a "subreaper" process defined via the +.BR prctl (2) +.B PR_SET_CHILD_SUBREAPER +operation). +.SH ERRORS +These functions are always successful. +.SH VERSIONS +On Alpha, instead of a pair of +.BR getpid () +and +.BR getppid () +system calls, a single +.BR getxpid () +system call is provided, which returns a pair of PID and parent PID. +The glibc +.BR getpid () +and +.BR getppid () +wrapper functions transparently deal with this. +See +.BR syscall (2) +for details regarding register mapping. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD, SVr4. +.SS C library/kernel differences +From glibc 2.3.4 up to and including glibc 2.24, +the glibc wrapper function for +.BR getpid () +cached PIDs, +with the goal of avoiding additional system calls when a process calls +.BR getpid () +repeatedly. +Normally this caching was invisible, +but its correct operation relied on support in the wrapper functions for +.BR fork (2), +.BR vfork (2), +and +.BR clone (2): +if an application bypassed the glibc wrappers for these system calls by using +.BR syscall (2), +then a call to +.BR getpid () +in the child would return the wrong value +(to be precise: it would return the PID of the parent process). +.\" The following program demonstrates this "feature": +.\" +.\" #define _GNU_SOURCE +.\" #include +.\" #include +.\" #include +.\" #include +.\" #include +.\" #include +.\" +.\" int +.\" main(int argc, char *argv[]) +.\" { +.\" /* The following statement fills the getpid() cache */ +.\" +.\" printf("parent PID = %ld\n", (intmax_t) getpid()); +.\" +.\" if (syscall(SYS_fork) == 0) { +.\" if (getpid() != syscall(SYS_getpid)) +.\" printf("child getpid() mismatch: getpid()=%jd; " +.\" "syscall(SYS_getpid)=%ld\n", +.\" (intmax_t) getpid(), (long) syscall(SYS_getpid)); +.\" exit(EXIT_SUCCESS); +.\" } +.\" wait(NULL); +.\"} +In addition, there were cases where +.BR getpid () +could return the wrong value even when invoking +.BR clone (2) +via the glibc wrapper function. +(For a discussion of one such case, see BUGS in +.BR clone (2).) +Furthermore, the complexity of the caching code had been +the source of a few bugs within glibc over the years. +.P +Because of the aforementioned problems, +since glibc 2.25, the PID cache is removed: +.\" commit c579f48edba88380635ab98cb612030e3ed8691e +.\" https://sourceware.org/glibc/wiki/Release/2.25#pid_cache_removal +calls to +.BR getpid () +always invoke the actual system call, rather than returning a cached value. +.\" FIXME . +.\" Review progress of https://bugzilla.redhat.com/show_bug.cgi?id=1469757 +.SH NOTES +If the caller's parent is in a different PID namespace (see +.BR pid_namespaces (7)), +.BR getppid () +returns 0. +.P +From a kernel perspective, +the PID (which is shared by all of the threads in a multithreaded process) +is sometimes also known as the thread group ID (TGID). +This contrasts with the kernel thread ID (TID), +which is unique for each thread. +For further details, see +.BR gettid (2) +and the discussion of the +.B CLONE_THREAD +flag in +.BR clone (2). +.SH SEE ALSO +.BR clone (2), +.BR fork (2), +.BR gettid (2), +.BR kill (2), +.BR exec (3), +.BR mkstemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3), +.BR credentials (7), +.BR pid_namespaces (7) diff --git a/man/man2/getpmsg.2 b/man/man2/getpmsg.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/getpmsg.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/getppid.2 b/man/man2/getppid.2 new file mode 100644 index 0000000..fca885e --- /dev/null +++ b/man/man2/getppid.2 @@ -0,0 +1 @@ +.so man2/getpid.2 diff --git a/man/man2/getpriority.2 b/man/man2/getpriority.2 new file mode 100644 index 0000000..075e3c5 --- /dev/null +++ b/man/man2/getpriority.2 @@ -0,0 +1,209 @@ +.\" Copyright (c) 1980, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)getpriority.2 6.9 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-07-01 by Andries Brouwer +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 2001-10-21 by Michael Kerrisk +.\" Corrected statement under EPERM to clarify privileges required +.\" Modified 2002-06-21 by Michael Kerrisk +.\" Clarified meaning of 0 value for 'who' argument +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH getpriority 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpriority, setpriority \- get/set program scheduling priority +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getpriority(int " which ", id_t " who ); +.BI "int setpriority(int " which ", id_t " who ", int " prio ); +.fi +.SH DESCRIPTION +The scheduling priority of the process, process group, or user, as +indicated by +.I which +and +.I who +is obtained with the +.BR getpriority () +call and set with the +.BR setpriority () +call. +The process attribute dealt with by these system calls is +the same attribute (also known as the "nice" value) that is dealt with by +.BR nice (2). +.P +The value +.I which +is one of +.BR PRIO_PROCESS , +.BR PRIO_PGRP , +or +.BR PRIO_USER , +and +.I who +is interpreted relative to +.I which +(a process identifier for +.BR PRIO_PROCESS , +process group +identifier for +.BR PRIO_PGRP , +and a user ID for +.BR PRIO_USER ). +A zero value for +.I who +denotes (respectively) the calling process, the process group of the +calling process, or the real user ID of the calling process. +.P +The +.I prio +argument is a value in the range \-20 to 19 (but see NOTES below), +with \-20 being the highest priority and 19 being the lowest priority. +Attempts to set a priority outside this range +are silently clamped to the range. +The default priority is 0; +lower values give a process a higher scheduling priority. +.P +The +.BR getpriority () +call returns the highest priority (lowest numerical value) +enjoyed by any of the specified processes. +The +.BR setpriority () +call sets the priorities of all of the specified processes +to the specified value. +.P +Traditionally, only a privileged process could lower the nice value +(i.e., set a higher priority). +However, since Linux 2.6.12, an unprivileged process can decrease +the nice value of a target process that has a suitable +.B RLIMIT_NICE +soft limit; see +.BR getrlimit (2) +for details. +.SH RETURN VALUE +On success, +.BR getpriority () +returns the calling thread's nice value, which may be a negative number. +On error, it returns \-1 and sets +.I errno +to indicate the error. +.P +Since a successful call to +.BR getpriority () +can legitimately return the value \-1, it is necessary +to clear +.I errno +prior to the +call, then check +.I errno +afterward to determine +if \-1 is an error or a legitimate value. +.P +.BR setpriority () +returns 0 on success. +On failure, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EACCES +The caller attempted to set a lower nice value +(i.e., a higher process priority), but did not +have the required privilege (on Linux: did not have the +.B CAP_SYS_NICE +capability). +.TP +.B EINVAL +.I which +was not one of +.BR PRIO_PROCESS , +.BR PRIO_PGRP , +or +.BR PRIO_USER . +.TP +.B EPERM +A process was located, but its effective user ID did not match +either the effective or the real user ID of the caller, +and was not privileged (on Linux: did not have the +.B CAP_SYS_NICE +capability). +But see NOTES below. +.TP +.B ESRCH +No process was located using the +.I which +and +.I who +values specified. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, +SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). +.SH NOTES +For further details on the nice value, see +.BR sched (7). +.P +.IR Note : +the addition of the "autogroup" feature in Linux 2.6.38 means that +the nice value no longer has its traditional effect in many circumstances. +For details, see +.BR sched (7). +.P +A child created by +.BR fork (2) +inherits its parent's nice value. +The nice value is preserved across +.BR execve (2). +.P +The details on the condition for +.B EPERM +depend on the system. +The above description is what POSIX.1-2001 says, and seems to be followed on +all System\ V-like systems. +Linux kernels before Linux 2.6.12 required the real or +effective user ID of the caller to match +the real user of the process \fIwho\fP (instead of its effective user ID). +Linux 2.6.12 and later require +the effective user ID of the caller to match +the real or effective user ID of the process \fIwho\fP. +All BSD-like systems (SunOS 4.1.3, Ultrix 4.2, +4.3BSD, FreeBSD 4.3, OpenBSD-2.5, ...) behave in the same +manner as Linux 2.6.12 and later. +.\" +.SS C library/kernel differences +The getpriority system call returns nice values translated to the range 40..1, +since a negative return value would be interpreted as an error. +The glibc wrapper function for +.BR getpriority () +translates the value back according to the formula +.I unice\~=\~20\~\-\~knice +(thus, the 40..1 range returned by the kernel +corresponds to the range \-20..19 as seen by user space). +.SH BUGS +According to POSIX, the nice value is a per-process setting. +However, under the current Linux/NPTL implementation of POSIX threads, +the nice value is a per-thread attribute: +different threads in the same process can have different nice values. +Portable applications should avoid relying on the Linux behavior, +which may be made standards conformant in the future. +.SH SEE ALSO +.BR nice (1), +.BR renice (1), +.BR fork (2), +.BR capabilities (7), +.BR sched (7) +.P +.I Documentation/scheduler/sched\-nice\-design.txt +in the Linux kernel source tree (since Linux 2.6.23) diff --git a/man/man2/getrandom.2 b/man/man2/getrandom.2 new file mode 100644 index 0000000..fb96cf2 --- /dev/null +++ b/man/man2/getrandom.2 @@ -0,0 +1,295 @@ +.\" Copyright (C) 2014, Theodore Ts'o +.\" Copyright (C) 2014,2015 Heinrich Schuchardt +.\" Copyright (C) 2015, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getrandom 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getrandom \- obtain a series of random bytes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t getrandom(void " buf [. buflen "], size_t " buflen ", \ +unsigned int " flags ); +.fi +.SH DESCRIPTION +The +.BR getrandom () +system call fills the buffer pointed to by +.I buf +with up to +.I buflen +random bytes. +These bytes can be used to seed user-space random number generators +or for cryptographic purposes. +.P +By default, +.BR getrandom () +draws entropy from the +.I urandom +source (i.e., the same source as the +.I /dev/urandom +device). +This behavior can be changed via the +.I flags +argument. +.P +If the +.I urandom +source has been initialized, +reads of up to 256 bytes will always return as many bytes as +requested and will not be interrupted by signals. +No such guarantees apply for larger buffer sizes. +For example, if the call is interrupted by a signal handler, +it may return a partially filled buffer, or fail with the error +.BR EINTR . +.P +If the +.I urandom +source has not yet been initialized, then +.BR getrandom () +will block, unless +.B GRND_NONBLOCK +is specified in +.IR flags . +.P +The +.I flags +argument is a bit mask that can contain zero or more of the following values +ORed together: +.TP +.B GRND_RANDOM +If this bit is set, then random bytes are drawn from the +.I random +source +(i.e., the same source as the +.I /dev/random +device) +instead of the +.I urandom +source. +The +.I random +source is limited based on the entropy that can be obtained from environmental +noise. +If the number of available bytes in the +.I random +source is less than requested in +.IR buflen , +the call returns just the available random bytes. +If no random bytes are available, the behavior depends on the presence of +.B GRND_NONBLOCK +in the +.I flags +argument. +.TP +.B GRND_NONBLOCK +By default, when reading from the +.I random +source, +.BR getrandom () +blocks if no random bytes are available, +and when reading from the +.I urandom +source, it blocks if the entropy pool has not yet been initialized. +If the +.B GRND_NONBLOCK +flag is set, then +.BR getrandom () +does not block in these cases, but instead immediately returns \-1 with +.I errno +set to +.BR EAGAIN . +.SH RETURN VALUE +On success, +.BR getrandom () +returns the number of bytes that were copied to the buffer +.IR buf . +This may be less than the number of bytes requested via +.I buflen +if either +.B GRND_RANDOM +was specified in +.I flags +and insufficient entropy was present in the +.I random +source or the system call was interrupted by a signal. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The requested entropy was not available, and +.BR getrandom () +would have blocked if the +.B GRND_NONBLOCK +flag was not set. +.TP +.B EFAULT +The address referred to by +.I buf +is outside the accessible address space. +.TP +.B EINTR +The call was interrupted by a signal +handler; see the description of how interrupted +.BR read (2) +calls on "slow" devices are handled with and without the +.B SA_RESTART +flag in the +.BR signal (7) +man page. +.TP +.B EINVAL +An invalid flag was specified in +.IR flags . +.TP +.B ENOSYS +The glibc wrapper function for +.BR getrandom () +determined that the underlying kernel does not implement this system call. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.17, +glibc 2.25. +.SH NOTES +For an overview and comparison of the various interfaces that +can be used to obtain randomness, see +.BR random (7). +.P +Unlike +.I /dev/random +and +.IR /dev/urandom , +.BR getrandom () +does not involve the use of pathnames or file descriptors. +Thus, +.BR getrandom () +can be useful in cases where +.BR chroot (2) +makes +.I /dev +pathnames invisible, +and where an application (e.g., a daemon during start-up) +closes a file descriptor for one of these files +that was opened by a library. +.\" +.SS Maximum number of bytes returned +As of Linux 3.19 the following limits apply: +.IP \[bu] 3 +When reading from the +.I urandom +source, a maximum of 32Mi-1 bytes is returned by a single call to +.BR getrandom () +on systems where +.I int +has a size of 32 bits. +.IP \[bu] +When reading from the +.I random +source, a maximum of 512 bytes is returned. +.SS Interruption by a signal handler +When reading from the +.I urandom +source +.RB ( GRND_RANDOM +is not set), +.BR getrandom () +will block until the entropy pool has been initialized +(unless the +.B GRND_NONBLOCK +flag was specified). +If a request is made to read a large number of bytes (more than 256), +.BR getrandom () +will block until those bytes have been generated and transferred +from kernel memory to +.IR buf . +When reading from the +.I random +source +.RB ( GRND_RANDOM +is set), +.BR getrandom () +will block until some random bytes become available +(unless the +.B GRND_NONBLOCK +flag was specified). +.P +The behavior when a call to +.BR getrandom () +that is blocked while reading from the +.I urandom +source is interrupted by a signal handler +depends on the initialization state of the entropy buffer +and on the request size, +.IR buflen . +If the entropy is not yet initialized, then the call fails with the +.B EINTR +error. +If the entropy pool has been initialized +and the request size is large +.RI ( buflen "\ >\ 256)," +the call either succeeds, returning a partially filled buffer, +or fails with the error +.BR EINTR . +If the entropy pool has been initialized and the request size is small +.RI ( buflen "\ <=\ 256)," +then +.BR getrandom () +will not fail with +.BR EINTR . +Instead, it will return all of the bytes that have been requested. +.P +When reading from the +.I random +source, blocking requests of any size can be interrupted by a signal handler +(the call fails with the error +.BR EINTR ). +.P +Using +.BR getrandom () +to read small buffers (<=\ 256 bytes) from the +.I urandom +source is the preferred mode of usage. +.P +The special treatment of small values of +.I buflen +was designed for compatibility with +OpenBSD's +.BR getentropy (3), +which is nowadays supported by glibc. +.P +The user of +.BR getrandom () +.I must +always check the return value, +to determine whether either an error occurred +or fewer bytes than requested were returned. +In the case where +.B GRND_RANDOM +is not specified and +.I buflen +is less than or equal to 256, +a return of fewer bytes than requested should never happen, +but the careful programmer will check for this anyway! +.SH BUGS +As of Linux 3.19, the following bug exists: +.\" FIXME patch proposed https://lkml.org/lkml/2014/11/29/16 +.IP \[bu] 3 +Depending on CPU load, +.BR getrandom () +does not react to interrupts before reading all bytes requested. +.SH SEE ALSO +.BR getentropy (3), +.BR random (4), +.BR urandom (4), +.BR random (7), +.BR signal (7) diff --git a/man/man2/getresgid.2 b/man/man2/getresgid.2 new file mode 100644 index 0000000..ac4fb7c --- /dev/null +++ b/man/man2/getresgid.2 @@ -0,0 +1 @@ +.so man2/getresuid.2 diff --git a/man/man2/getresgid32.2 b/man/man2/getresgid32.2 new file mode 100644 index 0000000..2b3240f --- /dev/null +++ b/man/man2/getresgid32.2 @@ -0,0 +1 @@ +.so man2/getresgid.2 diff --git a/man/man2/getresuid.2 b/man/man2/getresuid.2 new file mode 100644 index 0000000..51faf87 --- /dev/null +++ b/man/man2/getresuid.2 @@ -0,0 +1,70 @@ +.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (c) 2007, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified, 2003-05-26, Michael Kerrisk, +.\" +.TH getresuid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getresuid, getresgid \- get real, effective, and saved user/group IDs +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int getresuid(uid_t *" ruid ", uid_t *" euid ", uid_t *" suid ); +.BI "int getresgid(gid_t *" rgid ", gid_t *" egid ", gid_t *" sgid ); +.fi +.SH DESCRIPTION +.BR getresuid () +returns the real UID, the effective UID, and the saved set-user-ID +of the calling process, in the arguments +.IR ruid , +.IR euid , +and +.IR suid , +respectively. +.BR getresgid () +performs the analogous task for the process's group IDs. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +One of the arguments specified an address outside the calling program's +address space. +.SH STANDARDS +None. +These calls also appear on HP-UX and some of the BSDs. +.SH HISTORY +Linux 2.1.44, +glibc 2.3.2. +.P +The original Linux +.BR getresuid () +and +.BR getresgid () +system calls supported only 16-bit user and group IDs. +Subsequently, Linux 2.4 added +.BR getresuid32 () +and +.BR getresgid32 (), +supporting 32-bit IDs. +The glibc +.BR getresuid () +and +.BR getresgid () +wrapper functions transparently deal with the variations across kernel versions. +.SH SEE ALSO +.BR getuid (2), +.BR setresuid (2), +.BR setreuid (2), +.BR setuid (2), +.BR credentials (7) diff --git a/man/man2/getresuid32.2 b/man/man2/getresuid32.2 new file mode 100644 index 0000000..ac4fb7c --- /dev/null +++ b/man/man2/getresuid32.2 @@ -0,0 +1 @@ +.so man2/getresuid.2 diff --git a/man/man2/getrlimit.2 b/man/man2/getrlimit.2 new file mode 100644 index 0000000..6551373 --- /dev/null +++ b/man/man2/getrlimit.2 @@ -0,0 +1,853 @@ +'\" t +.\" Copyright (c) 1992 Drew Eckhardt, March 28, 1992 +.\" and Copyright (c) 2002, 2004, 2005, 2008, 2010 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1996-01-13 by Arnt Gulbrandsen +.\" Modified 1996-01-22 by aeb, following a remark by +.\" Tigran Aivazian +.\" Modified 1996-04-14 by aeb, following a remark by +.\" Robert Bihlmeyer +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2001-05-04 by aeb, following a remark by +.\" Håvard Lygre +.\" Modified 2001-04-17 by Michael Kerrisk +.\" Modified 2002-06-13 by Michael Kerrisk +.\" Added note on nonstandard behavior when SIGCHLD is ignored. +.\" Modified 2002-07-09 by Michael Kerrisk +.\" Enhanced descriptions of 'resource' values +.\" Modified 2003-11-28 by aeb, added RLIMIT_CORE +.\" Modified 2004-03-26 by aeb, added RLIMIT_AS +.\" Modified 2004-06-16 by Michael Kerrisk +.\" Added notes on CAP_SYS_RESOURCE +.\" +.\" 2004-11-16 -- mtk: the getrlimit.2 page, which formally included +.\" coverage of getrusage(2), has been split, so that the latter +.\" is now covered in its own getrusage.2. +.\" +.\" Modified 2004-11-16, mtk: A few other minor changes +.\" Modified 2004-11-23, mtk +.\" Added notes on RLIMIT_MEMLOCK, RLIMIT_NPROC, and RLIMIT_RSS +.\" to "CONFORMING TO" +.\" Modified 2004-11-25, mtk +.\" Rewrote discussion on RLIMIT_MEMLOCK to incorporate kernel +.\" 2.6.9 changes. +.\" Added note on RLIMIT_CPU error in older kernels +.\" 2004-11-03, mtk, Added RLIMIT_SIGPENDING +.\" 2005-07-13, mtk, documented RLIMIT_MSGQUEUE limit. +.\" 2005-07-28, mtk, Added descriptions of RLIMIT_NICE and RLIMIT_RTPRIO +.\" 2008-05-07, mtk / Peter Zijlstra, Added description of RLIMIT_RTTIME +.\" 2010-11-06, mtk: Added documentation of prlimit() +.\" +.TH getrlimit 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getrlimit, setrlimit, prlimit \- get/set resource limits +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getrlimit(int " resource ", struct rlimit *" rlim ); +.BI "int setrlimit(int " resource ", const struct rlimit *" rlim ); +.P +.BI "int prlimit(pid_t " pid ", int " resource , +.BI " const struct rlimit *_Nullable " new_limit , +.BI " struct rlimit *_Nullable " old_limit ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR prlimit (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR getrlimit () +and +.BR setrlimit () +system calls get and set resource limits. +Each resource has an associated soft and hard limit, as defined by the +.I rlimit +structure: +.P +.in +4n +.EX +struct rlimit { + rlim_t rlim_cur; /* Soft limit */ + rlim_t rlim_max; /* Hard limit (ceiling for rlim_cur) */ +}; +.EE +.in +.P +The soft limit is the value that the kernel enforces for the +corresponding resource. +The hard limit acts as a ceiling for the soft limit: +an unprivileged process may set only its soft limit to a value in the +range from 0 up to the hard limit, and (irreversibly) lower its hard limit. +A privileged process (under Linux: one with the +.B CAP_SYS_RESOURCE +capability in the initial user namespace) +may make arbitrary changes to either limit value. +.P +The value +.B RLIM_INFINITY +denotes no limit on a resource (both in the structure returned by +.BR getrlimit () +and in the structure passed to +.BR setrlimit ()). +.P +The +.I resource +argument must be one of: +.TP +.B RLIMIT_AS +This is the maximum size of the process's virtual memory +(address space). +The limit is specified in bytes, and is rounded down to the system page size. +.\" since Linux 2.0.27 / Linux 2.1.12 +This limit affects calls to +.BR brk (2), +.BR mmap (2), +and +.BR mremap (2), +which fail with the error +.B ENOMEM +upon exceeding this limit. +In addition, automatic stack expansion fails +(and generates a +.B SIGSEGV +that kills the process if no alternate stack +has been made available via +.BR sigaltstack (2)). +Since the value is a \fIlong\fP, on machines with a 32-bit \fIlong\fP +either this limit is at most 2\ GiB, or this resource is unlimited. +.TP +.B RLIMIT_CORE +This is the maximum size of a +.I core +file (see +.BR core (5)) +in bytes that the process may dump. +When 0 no core dump files are created. +When nonzero, larger dumps are truncated to this size. +.TP +.B RLIMIT_CPU +This is a limit, in seconds, +on the amount of CPU time that the process can consume. +When the process reaches the soft limit, it is sent a +.B SIGXCPU +signal. +The default action for this signal is to terminate the process. +However, the signal can be caught, and the handler can return control to +the main program. +If the process continues to consume CPU time, it will be sent +.B SIGXCPU +once per second until the hard limit is reached, at which time +it is sent +.BR SIGKILL . +(This latter point describes Linux behavior. +Implementations vary in how they treat processes which continue to +consume CPU time after reaching the soft limit. +Portable applications that need to catch this signal should +perform an orderly termination upon first receipt of +.BR SIGXCPU .) +.TP +.B RLIMIT_DATA +This is the maximum size +of the process's data segment (initialized data, +uninitialized data, and heap). +The limit is specified in bytes, and is rounded down to the system page size. +This limit affects calls to +.BR brk (2), +.BR sbrk (2), +and (since Linux 4.7) +.BR mmap (2), +.\" commits 84638335900f1995495838fe1bd4870c43ec1f67 +.\" ("mm: rework virtual memory accounting"), +.\" f4fcd55841fc9e46daac553b39361572453c2b88 +.\" (mm: enable RLIMIT_DATA by default with workaround for valgrind). +which fail with the error +.B ENOMEM +upon encountering the soft limit of this resource. +.TP +.B RLIMIT_FSIZE +This is the maximum size in bytes of files that the process may create. +Attempts to extend a file beyond this limit result in delivery of a +.B SIGXFSZ +signal. +By default, this signal terminates a process, but a process can +catch this signal instead, in which case the relevant system call (e.g., +.BR write (2), +.BR truncate (2)) +fails with the error +.BR EFBIG . +.TP +.BR RLIMIT_LOCKS " (Linux 2.4.0 to Linux 2.4.24)" +.\" to be precise: Linux 2.4.0-test9; no longer in Linux 2.4.25 / Linux 2.5.65 +This is a limit on the combined number of +.BR flock (2) +locks and +.BR fcntl (2) +leases that this process may establish. +.TP +.B RLIMIT_MEMLOCK +This is the maximum number of bytes of memory that may be locked +into RAM. +This limit is in effect rounded down to the nearest multiple +of the system page size. +This limit affects +.BR mlock (2), +.BR mlockall (2), +and the +.BR mmap (2) +.B MAP_LOCKED +operation. +Since Linux 2.6.9, it also affects the +.BR shmctl (2) +.B SHM_LOCK +operation, where it sets a maximum on the total bytes in +shared memory segments (see +.BR shmget (2)) +that may be locked by the real user ID of the calling process. +The +.BR shmctl (2) +.B SHM_LOCK +locks are accounted for separately from the per-process memory +locks established by +.BR mlock (2), +.BR mlockall (2), +and +.BR mmap (2) +.BR MAP_LOCKED ; +a process can lock bytes up to this limit in each of these +two categories. +.IP +Before Linux 2.6.9, this limit controlled the amount of +memory that could be locked by a privileged process. +Since Linux 2.6.9, no limits are placed on the amount of memory +that a privileged process may lock, and this limit instead governs +the amount of memory that an unprivileged process may lock. +.TP +.BR RLIMIT_MSGQUEUE " (since Linux 2.6.8)" +This is a limit on the number of bytes that can be allocated +for POSIX message queues for the real user ID of the calling process. +This limit is enforced for +.BR mq_open (3). +Each message queue that the user creates counts (until it is removed) +against this limit according to the formula: +.RS 4 +.IP +Since Linux 3.5: +.IP +.in +4n +.EX +bytes = attr.mq_maxmsg * sizeof(struct msg_msg) + + MIN(attr.mq_maxmsg, MQ_PRIO_MAX) * + sizeof(struct posix_msg_tree_node)+ + /* For overhead */ + attr.mq_maxmsg * attr.mq_msgsize; + /* For message data */ +.EE +.in +.IP +Linux 3.4 and earlier: +.IP +.in +4n +.EX +bytes = attr.mq_maxmsg * sizeof(struct msg_msg *) + + /* For overhead */ + attr.mq_maxmsg * attr.mq_msgsize; + /* For message data */ +.EE +.in +.RE +.IP +where +.I attr +is the +.I mq_attr +structure specified as the fourth argument to +.BR mq_open (3), +and the +.I msg_msg +and +.I posix_msg_tree_node +structures are kernel-internal structures. +.IP +The "overhead" addend in the formula accounts for overhead +bytes required by the implementation +and ensures that the user cannot +create an unlimited number of zero-length messages (such messages +nevertheless each consume some system memory for bookkeeping overhead). +.TP +.BR RLIMIT_NICE " (since Linux 2.6.12, but see BUGS below)" +This specifies a ceiling to which the process's nice value can be raised using +.BR setpriority (2) +or +.BR nice (2). +The actual ceiling for the nice value is calculated as +.IR "20\ \-\ rlim_cur" . +The useful range for this limit is thus from 1 +(corresponding to a nice value of 19) to 40 +(corresponding to a nice value of \-20). +This unusual choice of range was necessary +because negative numbers cannot be specified +as resource limit values, since they typically have special meanings. +For example, +.B RLIM_INFINITY +typically is the same as \-1. +For more detail on the nice value, see +.BR sched (7). +.TP +.B RLIMIT_NOFILE +This specifies a value one greater than the maximum file descriptor number +that can be opened by this process. +Attempts +.RB ( open (2), +.BR pipe (2), +.BR dup (2), +etc.) +to exceed this limit yield the error +.BR EMFILE . +(Historically, this limit was named +.B RLIMIT_OFILE +on BSD.) +.IP +Since Linux 4.5, +this limit also defines the maximum number of file descriptors that +an unprivileged process (one without the +.B CAP_SYS_RESOURCE +capability) may have "in flight" to other processes, +by being passed across UNIX domain sockets. +This limit applies to the +.BR sendmsg (2) +system call. +For further details, see +.BR unix (7). +.TP +.B RLIMIT_NPROC +This is a limit on the number of extant process +(or, more precisely on Linux, threads) +for the real user ID of the calling process. +So long as the current number of processes belonging to this +process's real user ID is greater than or equal to this limit, +.BR fork (2) +fails with the error +.BR EAGAIN . +.IP +The +.B RLIMIT_NPROC +limit is not enforced for processes that have either the +.B CAP_SYS_ADMIN +or the +.B CAP_SYS_RESOURCE +capability, +or run with real user ID 0. +.TP +.B RLIMIT_RSS +This is a limit (in bytes) on the process's resident set +(the number of virtual pages resident in RAM). +This limit has effect only in Linux 2.4.x, x < 30, and there +affects only calls to +.BR madvise (2) +specifying +.BR MADV_WILLNEED . +.\" As at Linux 2.6.12, this limit still does nothing in Linux 2.6 though +.\" talk of making it do something has surfaced from time to time in LKML +.\" -- MTK, Jul 05 +.TP +.BR RLIMIT_RTPRIO " (since Linux 2.6.12, but see BUGS)" +This specifies a ceiling on the real-time priority that may be set for +this process using +.BR sched_setscheduler (2) +and +.BR sched_setparam (2). +.IP +For further details on real-time scheduling policies, see +.BR sched (7) +.TP +.BR RLIMIT_RTTIME " (since Linux 2.6.25)" +This is a limit (in microseconds) +on the amount of CPU time that a process scheduled +under a real-time scheduling policy may consume without making a blocking +system call. +For the purpose of this limit, +each time a process makes a blocking system call, +the count of its consumed CPU time is reset to zero. +The CPU time count is not reset if the process continues trying to +use the CPU but is preempted, its time slice expires, or it calls +.BR sched_yield (2). +.IP +Upon reaching the soft limit, the process is sent a +.B SIGXCPU +signal. +If the process catches or ignores this signal and +continues consuming CPU time, then +.B SIGXCPU +will be generated once each second until the hard limit is reached, +at which point the process is sent a +.B SIGKILL +signal. +.IP +The intended use of this limit is to stop a runaway +real-time process from locking up the system. +.IP +For further details on real-time scheduling policies, see +.BR sched (7) +.TP +.BR RLIMIT_SIGPENDING " (since Linux 2.6.8)" +This is a limit on the number of signals +that may be queued for the real user ID of the calling process. +Both standard and real-time signals are counted for the purpose of +checking this limit. +However, the limit is enforced only for +.BR sigqueue (3); +it is always possible to use +.BR kill (2) +to queue one instance of any of the signals that are not already +queued to the process. +.\" This replaces the /proc/sys/kernel/rtsig-max system-wide limit +.\" that was present in Linux <= 2.6.7. MTK Dec 04 +.TP +.B RLIMIT_STACK +This is the maximum size of the process stack, in bytes. +Upon reaching this limit, a +.B SIGSEGV +signal is generated. +To handle this signal, a process must employ an alternate signal stack +.RB ( sigaltstack (2)). +.IP +Since Linux 2.6.23, +this limit also determines the amount of space used for the process's +command-line arguments and environment variables; for details, see +.BR execve (2). +.SS prlimit() +.\" commit c022a0acad534fd5f5d5f17280f6d4d135e74e81 +.\" Author: Jiri Slaby +.\" Date: Tue May 4 18:03:50 2010 +0200 +.\" +.\" rlimits: implement prlimit64 syscall +.\" +.\" commit 6a1d5e2c85d06da35cdfd93f1a27675bfdc3ad8c +.\" Author: Jiri Slaby +.\" Date: Wed Mar 24 17:06:58 2010 +0100 +.\" +.\" rlimits: add rlimit64 structure +.\" +The Linux-specific +.BR prlimit () +system call combines and extends the functionality of +.BR setrlimit () +and +.BR getrlimit (). +It can be used to both set and get the resource limits of an arbitrary process. +.P +The +.I resource +argument has the same meaning as for +.BR setrlimit () +and +.BR getrlimit (). +.P +If the +.I new_limit +argument is not NULL, then the +.I rlimit +structure to which it points is used to set new values for +the soft and hard limits for +.IR resource . +If the +.I old_limit +argument is not NULL, then a successful call to +.BR prlimit () +places the previous soft and hard limits for +.I resource +in the +.I rlimit +structure pointed to by +.IR old_limit . +.P +The +.I pid +argument specifies the ID of the process on which the call is to operate. +If +.I pid +is 0, then the call applies to the calling process. +To set or get the resources of a process other than itself, +the caller must have the +.B CAP_SYS_RESOURCE +capability in the user namespace of the process +whose resource limits are being changed, or the +real, effective, and saved set user IDs of the target process +must match the real user ID of the caller +.I and +the real, effective, and saved set group IDs of the target process +must match the real group ID of the caller. +.\" FIXME . this permission check is strange +.\" Asked about this on LKML, 7 Nov 2010 +.\" "Inconsistent credential checking in prlimit() syscall" +.SH RETURN VALUE +On success, these system calls return 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +A pointer argument points to a location +outside the accessible address space. +.TP +.B EINVAL +The value specified in +.I resource +is not valid; +or, for +.BR setrlimit () +or +.BR prlimit (): +.I rlim\->rlim_cur +was greater than +.IR rlim\->rlim_max . +.TP +.B EPERM +An unprivileged process tried to raise the hard limit; the +.B CAP_SYS_RESOURCE +capability is required to do this. +.TP +.B EPERM +The caller tried to increase the hard +.B RLIMIT_NOFILE +limit above the maximum defined by +.I /proc/sys/fs/nr_open +(see +.BR proc (5)) +.TP +.B EPERM +.RB ( prlimit ()) +The calling process did not have permission to set limits +for the process specified by +.IR pid . +.TP +.B ESRCH +Could not find a process with the ID specified in +.IR pid . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getrlimit (), +.BR setrlimit (), +.BR prlimit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR getrlimit () +.TQ +.BR setrlimit () +POSIX.1-2008. +.TP +.BR prlimit () +Linux. +.P +.B RLIMIT_MEMLOCK +and +.B RLIMIT_NPROC +derive from BSD and are not specified in POSIX.1; +they are present on the BSDs and Linux, but on few other implementations. +.B RLIMIT_RSS +derives from BSD and is not specified in POSIX.1; +it is nevertheless present on most implementations. +.BR \%RLIMIT_MSGQUEUE , +.BR RLIMIT_NICE , +.BR RLIMIT_RTPRIO , +.BR RLIMIT_RTTIME , +and +.B \%RLIMIT_SIGPENDING +are Linux-specific. +.SH HISTORY +.TP +.BR getrlimit () +.TQ +.BR setrlimit () +POSIX.1-2001, SVr4, 4.3BSD. +.TP +.BR prlimit () +Linux 2.6.36, +glibc 2.13. +.SH NOTES +A child process created via +.BR fork (2) +inherits its parent's resource limits. +Resource limits are preserved across +.BR execve (2). +.P +Resource limits are per-process attributes that are shared +by all of the threads in a process. +.P +Lowering the soft limit for a resource below the process's +current consumption of that resource will succeed +(but will prevent the process from further increasing +its consumption of the resource). +.P +One can set the resource limits of the shell using the built-in +.I ulimit +command +.RI ( limit +in +.BR csh (1)). +The shell's resource limits are inherited by the processes that +it creates to execute commands. +.P +Since Linux 2.6.24, the resource limits of any process can be inspected via +.IR /proc/ pid /limits ; +see +.BR proc (5). +.P +Ancient systems provided a +.BR vlimit () +function with a similar purpose to +.BR setrlimit (). +For backward compatibility, glibc also provides +.BR vlimit (). +All new applications should be written using +.BR setrlimit (). +.SS C library/kernel ABI differences +Since glibc 2.13, the glibc +.BR getrlimit () +and +.BR setrlimit () +wrapper functions no longer invoke the corresponding system calls, +but instead employ +.BR prlimit (), +for the reasons described in BUGS. +.P +The name of the glibc wrapper function is +.BR prlimit (); +the underlying system call is +.BR prlimit64 (). +.SH BUGS +In older Linux kernels, the +.B SIGXCPU +and +.B SIGKILL +signals delivered when a process encountered the soft and hard +.B RLIMIT_CPU +limits were delivered one (CPU) second later than they should have been. +This was fixed in Linux 2.6.8. +.P +In Linux 2.6.x kernels before Linux 2.6.17, a +.B RLIMIT_CPU +limit of 0 is wrongly treated as "no limit" (like +.BR RLIM_INFINITY ). +Since Linux 2.6.17, setting a limit of 0 does have an effect, +but is actually treated as a limit of 1 second. +.\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=114008066530167&w=2 +.P +A kernel bug means that +.\" See https://lwn.net/Articles/145008/ +.B RLIMIT_RTPRIO +does not work in Linux 2.6.12; the problem is fixed in Linux 2.6.13. +.P +In Linux 2.6.12, there was an off-by-one mismatch +between the priority ranges returned by +.BR getpriority (2) +and +.BR RLIMIT_NICE . +This had the effect that the actual ceiling for the nice value +was calculated as +.IR "19\ \-\ rlim_cur" . +This was fixed in Linux 2.6.13. +.\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=112256338703880&w=2 +.P +Since Linux 2.6.12, +.\" The relevant patch, sent to LKML, seems to be +.\" http://thread.gmane.org/gmane.linux.kernel/273462 +.\" From: Roland McGrath redhat.com> +.\" Subject: [PATCH 7/7] make RLIMIT_CPU/SIGXCPU per-process +.\" Date: 2005-01-23 23:27:46 GMT +if a process reaches its soft +.B RLIMIT_CPU +limit and has a handler installed for +.BR SIGXCPU , +then, in addition to invoking the signal handler, +the kernel increases the soft limit by one second. +This behavior repeats if the process continues to consume CPU time, +until the hard limit is reached, +at which point the process is killed. +Other implementations +.\" Tested Solaris 10, FreeBSD 9, OpenBSD 5.0 +do not change the +.B RLIMIT_CPU +soft limit in this manner, +and the Linux behavior is probably not standards conformant; +portable applications should avoid relying on this Linux-specific behavior. +.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=50951 +The Linux-specific +.B RLIMIT_RTTIME +limit exhibits the same behavior when the soft limit is encountered. +.P +Kernels before Linux 2.4.22 did not diagnose the error +.B EINVAL +for +.BR setrlimit () +when +.I rlim\->rlim_cur +was greater than +.IR rlim\->rlim_max . +.\" d3561f78fd379a7110e46c87964ba7aa4120235c +.P +Linux doesn't return an error when an attempt to set +.B RLIMIT_CPU +has failed, for compatibility reasons. +.\" +.SS Representation of \[dq]large\[dq] resource limit values on 32-bit platforms +The glibc +.BR getrlimit () +and +.BR setrlimit () +wrapper functions use a 64-bit +.I rlim_t +data type, even on 32-bit platforms. +However, the +.I rlim_t +data type used in the +.BR getrlimit () +and +.BR setrlimit () +system calls is a (32-bit) +.IR "unsigned long" . +.\" Linux still uses long for limits internally: +.\" c022a0acad534fd5f5d5f17280f6d4d135e74e81 +.\" kernel/sys.c:do_prlimit() still uses struct rlimit which +.\" uses kernel_ulong_t for its members, i.e. 32-bit on 32-bit kernel. +Furthermore, in Linux, +the kernel represents resource limits on 32-bit platforms as +.IR "unsigned long" . +However, a 32-bit data type is not wide enough. +.\" https://bugzilla.kernel.org/show_bug.cgi?id=5042 +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201 +The most pertinent limit here is +.BR \%RLIMIT_FSIZE , +which specifies the maximum size to which a file can grow: +to be useful, this limit must be represented using a type +that is as wide as the type used to +represent file offsets\[em]that is, as wide as a 64-bit +.B off_t +(assuming a program compiled with +.IR _FILE_OFFSET_BITS=64 ). +.P +To work around this kernel limitation, +if a program tried to set a resource limit to a value larger than +can be represented in a 32-bit +.IR "unsigned long" , +then the glibc +.BR setrlimit () +wrapper function silently converted the limit value to +.BR RLIM_INFINITY . +In other words, the requested resource limit setting was silently ignored. +.P +Since glibc 2.13, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201 +glibc works around the limitations of the +.BR \%getrlimit () +and +.BR setrlimit () +system calls by implementing +.BR setrlimit () +and +.BR \%getrlimit () +as wrapper functions that call +.BR prlimit (). +.SH EXAMPLES +The program below demonstrates the use of +.BR prlimit (). +.P +.\" SRC BEGIN (getrlimit.c) +.EX +#define _GNU_SOURCE +#define _FILE_OFFSET_BITS 64 +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + pid_t pid; + struct rlimit old, new; + struct rlimit *newp; +\& + if (!(argc == 2 || argc == 4)) { + fprintf(stderr, "Usage: %s [ " + "]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + pid = atoi(argv[1]); /* PID of target process */ +\& + newp = NULL; + if (argc == 4) { + new.rlim_cur = atoi(argv[2]); + new.rlim_max = atoi(argv[3]); + newp = &new; + } +\& + /* Set CPU time limit of target process; retrieve and display + previous limit */ +\& + if (prlimit(pid, RLIMIT_CPU, newp, &old) == \-1) + err(EXIT_FAILURE, "prlimit\-1"); + printf("Previous limits: soft=%jd; hard=%jd\en", + (intmax_t) old.rlim_cur, (intmax_t) old.rlim_max); +\& + /* Retrieve and display new CPU time limit */ +\& + if (prlimit(pid, RLIMIT_CPU, NULL, &old) == \-1) + err(EXIT_FAILURE, "prlimit\-2"); + printf("New limits: soft=%jd; hard=%jd\en", + (intmax_t) old.rlim_cur, (intmax_t) old.rlim_max); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR prlimit (1), +.BR dup (2), +.BR fcntl (2), +.BR fork (2), +.BR getrusage (2), +.BR mlock (2), +.BR mmap (2), +.BR open (2), +.BR quotactl (2), +.BR sbrk (2), +.BR shmctl (2), +.BR malloc (3), +.BR sigqueue (3), +.BR ulimit (3), +.BR core (5), +.BR capabilities (7), +.BR cgroups (7), +.BR credentials (7), +.BR signal (7) diff --git a/man/man2/getrusage.2 b/man/man2/getrusage.2 new file mode 100644 index 0000000..ff640e2 --- /dev/null +++ b/man/man2/getrusage.2 @@ -0,0 +1,250 @@ +'\" t +.\" Copyright (c) 1992 Drew Eckhardt, March 28, 1992 +.\" and Copyright (c) 2002 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2004-11-16 -- mtk: the getrlimit.2 page, which formerly included +.\" coverage of getrusage(2), has been split, so that the latter is +.\" now covered in its own getrusage.2. For older details of change +.\" history, etc., see getrlimit.2 +.\" +.\" Modified 2004-11-16, mtk, Noted that the nonconformance +.\" when SIGCHLD is being ignored is fixed in Linux 2.6.9. +.\" 2008-02-22, Sripathi Kodi : Document RUSAGE_THREAD +.\" 2008-05-25, mtk, clarify RUSAGE_CHILDREN + other clean-ups. +.\" 2010-05-24, Mark Hills : Description of fields, +.\" document ru_maxrss +.\" 2010-05-24, mtk, enhanced description of various fields +.\" +.TH getrusage 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getrusage \- get resource usage +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getrusage(int " who ", struct rusage *" usage ); +.fi +.SH DESCRIPTION +.BR getrusage () +returns resource usage measures for +.IR who , +which can be one of the following: +.TP +.B RUSAGE_SELF +Return resource usage statistics for the calling process, +which is the sum of resources used by all threads in the process. +.TP +.B RUSAGE_CHILDREN +Return resource usage statistics for all children of the +calling process that have terminated and been waited for. +These statistics will include the resources used by grandchildren, +and further removed descendants, +if all of the intervening descendants waited on their terminated children. +.TP +.BR RUSAGE_THREAD " (since Linux 2.6.26)" +Return resource usage statistics for the calling thread. +The +.B _GNU_SOURCE +feature test macro must be defined (before including +.I any +header file) +in order to obtain the definition of this constant from +.IR . +.P +The resource usages are returned in the structure pointed to by +.IR usage , +which has the following form: +.P +.in +4n +.EX +struct rusage { + struct timeval ru_utime; /* user CPU time used */ + struct timeval ru_stime; /* system CPU time used */ + long ru_maxrss; /* maximum resident set size */ + long ru_ixrss; /* integral shared memory size */ + long ru_idrss; /* integral unshared data size */ + long ru_isrss; /* integral unshared stack size */ + long ru_minflt; /* page reclaims (soft page faults) */ + long ru_majflt; /* page faults (hard page faults) */ + long ru_nswap; /* swaps */ + long ru_inblock; /* block input operations */ + long ru_oublock; /* block output operations */ + long ru_msgsnd; /* IPC messages sent */ + long ru_msgrcv; /* IPC messages received */ + long ru_nsignals; /* signals received */ + long ru_nvcsw; /* voluntary context switches */ + long ru_nivcsw; /* involuntary context switches */ +}; +.EE +.in +.P +Not all fields are completed; +unmaintained fields are set to zero by the kernel. +(The unmaintained fields are provided for compatibility with other systems, +and because they may one day be supported on Linux.) +The fields are interpreted as follows: +.TP +.I ru_utime +This is the total amount of time spent executing in user mode, +expressed in a +.I timeval +structure (seconds plus microseconds). +.TP +.I ru_stime +This is the total amount of time spent executing in kernel mode, +expressed in a +.I timeval +structure (seconds plus microseconds). +.TP +.IR ru_maxrss " (since Linux 2.6.32)" +This is the maximum resident set size used (in kilobytes). +For +.BR RUSAGE_CHILDREN , +this is the resident set size of the largest child, not the maximum +resident set size of the process tree. +.TP +.IR ru_ixrss " (unmaintained)" +This field is currently unused on Linux. +.\" On some systems, +.\" this is the integral of the text segment memory consumption, +.\" expressed in kilobyte-seconds. +.TP +.IR ru_idrss " (unmaintained)" +This field is currently unused on Linux. +.\" On some systems, this is the integral of the data segment memory consumption, +.\" expressed in kilobyte-seconds. +.TP +.IR ru_isrss " (unmaintained)" +This field is currently unused on Linux. +.\" On some systems, this is the integral of the stack memory consumption, +.\" expressed in kilobyte-seconds. +.TP +.I ru_minflt +The number of page faults serviced without any I/O activity; here +I/O activity is avoided by \*(lqreclaiming\*(rq a page frame from +the list of pages awaiting reallocation. +.TP +.I ru_majflt +The number of page faults serviced that required I/O activity. +.TP +.IR ru_nswap " (unmaintained)" +This field is currently unused on Linux. +.\" On some systems, this is the number of swaps out of physical memory. +.TP +.IR ru_inblock " (since Linux 2.6.22)" +The number of times the filesystem had to perform input. +.TP +.IR ru_oublock " (since Linux 2.6.22)" +The number of times the filesystem had to perform output. +.TP +.IR ru_msgsnd " (unmaintained)" +This field is currently unused on Linux. +.\" On FreeBSD 6.2, this appears to measure messages sent over sockets +.\" On some systems, +.\" this field records the number of messages sent over sockets. +.TP +.IR ru_msgrcv " (unmaintained)" +This field is currently unused on Linux. +.\" On FreeBSD 6.2, this appears to measure messages received over sockets +.\" On some systems, +.\" this field records the number of messages received over sockets. +.TP +.IR ru_nsignals " (unmaintained)" +This field is currently unused on Linux. +.\" On some systems, this field records the number of signals received. +.TP +.IR ru_nvcsw " (since Linux 2.6)" +The number of times a context switch resulted due to a process +voluntarily giving up the processor before its time slice was +completed (usually to await availability of a resource). +.TP +.IR ru_nivcsw " (since Linux 2.6)" +The number of times a context switch resulted due to a higher +priority process becoming runnable or because the current process +exceeded its time slice. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I usage +points outside the accessible address space. +.TP +.B EINVAL +.I who +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getrusage () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.P +POSIX.1 specifies +.BR getrusage (), +but specifies only the fields +.I ru_utime +and +.IR ru_stime . +.P +.B RUSAGE_THREAD +is Linux-specific. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.P +Before Linux 2.6.9, if the disposition of +.B SIGCHLD +is set to +.B SIG_IGN +then the resource usages of child processes +are automatically included in the value returned by +.BR RUSAGE_CHILDREN , +although POSIX.1-2001 explicitly prohibits this. +This nonconformance is rectified in Linux 2.6.9 and later. +.\" See the description of getrusage() in XSH. +.\" A similar statement was also in SUSv2. +.P +The structure definition shown at the start of this page +was taken from 4.3BSD Reno. +.P +Ancient systems provided a +.BR vtimes () +function with a similar purpose to +.BR getrusage (). +For backward compatibility, glibc (up until Linux 2.32) also provides +.BR vtimes (). +All new applications should be written using +.BR getrusage (). +(Since Linux 2.33, glibc no longer provides an +.BR vtimes () +implementation.) +.SH NOTES +Resource usage metrics are preserved across an +.BR execve (2). +.SH SEE ALSO +.BR clock_gettime (2), +.BR getrlimit (2), +.BR times (2), +.BR wait (2), +.BR wait4 (2), +.BR clock (3), +.BR proc_pid_stat (5), +.BR proc_pid_io (5) diff --git a/man/man2/getsid.2 b/man/man2/getsid.2 new file mode 100644 index 0000000..232b019 --- /dev/null +++ b/man/man2/getsid.2 @@ -0,0 +1,75 @@ +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Thu Oct 31 14:18:40 1996 by Eric S. Raymond +.\" Modified 2001-12-17, aeb +.TH getsid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getsid \- get session ID +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "pid_t getsid(pid_t" " pid" ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getsid (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +.BR getsid () +returns the session ID of the process with process ID +.IR pid . +If +.I pid +is 0, +.BR getsid () +returns the session ID of the calling process. +.SH RETURN VALUE +On success, a session ID is returned. +On error, \fI(pid_t)\ \-1\fP is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EPERM +A process with process ID +.I pid +exists, but it is not in the same session as the calling process, +and the implementation considers this an error. +.TP +.B ESRCH +No process with process ID +.I pid +was found. +.SH VERSIONS +Linux does not return +.BR EPERM . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +Linux 2.0. +.\" Linux has this system call since Linux 1.3.44. +.\" There is libc support since libc 5.2.19. +.SH NOTES +See +.BR credentials (7) +for a description of sessions and session IDs. +.SH SEE ALSO +.BR getpgid (2), +.BR setsid (2), +.BR credentials (7) diff --git a/man/man2/getsockname.2 b/man/man2/getsockname.2 new file mode 100644 index 0000000..1f73883 --- /dev/null +++ b/man/man2/getsockname.2 @@ -0,0 +1,85 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)getsockname.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 16:30:29 1993 by Rik Faith +.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond +.\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer +.\" +.TH getsockname 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getsockname \- get socket name +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getsockname(int " sockfd ", struct sockaddr *restrict " addr , +.BI " socklen_t *restrict " addrlen ); +.fi +.SH DESCRIPTION +.BR getsockname () +returns the current address to which the socket +.I sockfd +is bound, in the buffer pointed to by +.IR addr . +The +.I addrlen +argument should be initialized to indicate +the amount of space (in bytes) pointed to by +.IR addr . +On return it contains the actual size of the socket address. +.P +The returned address is truncated if the buffer provided is too small; +in this case, +.I addrlen +will return a value greater than was supplied to the call. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The argument +.I sockfd +is not a valid file descriptor. +.TP +.B EFAULT +The +.I addr +argument points to memory not in a valid part of the +process address space. +.TP +.B EINVAL +.I addrlen +is invalid (e.g., is negative). +.TP +.B ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD +(first appeared in 4.2BSD). +.\" SVr4 documents additional ENOMEM +.\" and ENOSR error codes. +.SH SEE ALSO +.BR bind (2), +.BR socket (2), +.BR getifaddrs (3), +.BR ip (7), +.BR socket (7), +.BR unix (7) diff --git a/man/man2/getsockopt.2 b/man/man2/getsockopt.2 new file mode 100644 index 0000000..8393d49 --- /dev/null +++ b/man/man2/getsockopt.2 @@ -0,0 +1,172 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" $Id: getsockopt.2,v 1.1 1999/05/24 14:57:04 freitag Exp $ +.\" +.\" Modified Sat Jul 24 16:19:32 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Apr 22 02:29:06 1996 by Martin Schulze (joey@infodrom.north.de) +.\" Modified Tue Aug 27 10:52:51 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Thu Jan 23 13:29:34 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 1999 by Andi Kleen . +.\" Removed most stuff because it is in socket.7 now. +.\" +.TH getsockopt 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getsockopt, setsockopt \- get and set options on sockets +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getsockopt(int " sockfd ", int " level ", int " optname , +.BI " void " optval "[restrict *." optlen ], +.BI " socklen_t *restrict " optlen ); +.BI "int setsockopt(int " sockfd ", int " level ", int " optname , +.BI " const void " optval [. optlen ], +.BI " socklen_t " optlen ); +.fi +.SH DESCRIPTION +.BR getsockopt () +and +.BR setsockopt () +manipulate options for the socket referred to by the file descriptor +.IR sockfd . +Options may exist at multiple +protocol levels; they are always present at the uppermost +socket level. +.P +When manipulating socket options, the level at which the +option resides and the name of the option must be specified. +To manipulate options at the sockets API level, +.I level +is specified as +.BR SOL_SOCKET . +To manipulate options at any +other level the protocol number of the appropriate protocol +controlling the option is supplied. +For example, +to indicate that an option is to be interpreted by the +.B TCP +protocol, +.I level +should be set to the protocol number of +.BR TCP ; +see +.BR getprotoent (3). +.P +The arguments +.I optval +and +.I optlen +are used to access option values for +.BR setsockopt (). +For +.BR getsockopt () +they identify a buffer in which the value for the +requested option(s) are to be returned. +For +.BR getsockopt (), +.I optlen +is a value-result argument, initially containing the +size of the buffer pointed to by +.IR optval , +and modified on return to indicate the actual size of +the value returned. +If no option value is to be supplied or returned, +.I optval +may be NULL. +.P +.I Optname +and any specified options are passed uninterpreted to the appropriate +protocol module for interpretation. +The include file +.I +contains definitions for socket level options, described below. +Options at +other protocol levels vary in format and name; consult the appropriate +entries in section 4 of the manual. +.P +Most socket-level options utilize an +.I int +argument for +.IR optval . +For +.BR setsockopt (), +the argument should be nonzero to enable a boolean option, or zero if the +option is to be disabled. +.P +For a description of the available socket options see +.BR socket (7) +and the appropriate protocol man pages. +.SH RETURN VALUE +On success, zero is returned for the standard options. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +Netfilter allows the programmer +to define custom socket options with associated handlers; for such +options, the return value on success is the value returned by the handler. +.SH ERRORS +.TP +.B EBADF +The argument +.I sockfd +is not a valid file descriptor. +.TP +.B EFAULT +The address pointed to by +.I optval +is not in a valid part of the process address space. +For +.BR getsockopt (), +this error may also be returned if +.I optlen +is not in a valid part of the process address space. +.TP +.B EINVAL +.I optlen +invalid in +.BR setsockopt (). +In some cases this error can also occur for an invalid value in +.I optval +(e.g., for the +.B IP_ADD_MEMBERSHIP +option described in +.BR ip (7)). +.TP +.B ENOPROTOOPT +The option is unknown at the level indicated. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, +SVr4, 4.4BSD (first appeared in 4.2BSD). +.\" SVr4 documents additional ENOMEM and ENOSR error codes, but does +.\" not document the +.\" .BR SO_SNDLOWAT ", " SO_RCVLOWAT ", " SO_SNDTIMEO ", " SO_RCVTIMEO +.\" options +.SH BUGS +Several of the socket options should be handled at lower levels of the +system. +.SH SEE ALSO +.BR ioctl (2), +.BR socket (2), +.BR getprotoent (3), +.BR protocols (5), +.BR ip (7), +.BR packet (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) diff --git a/man/man2/gettid.2 b/man/man2/gettid.2 new file mode 100644 index 0000000..fa1fb2c --- /dev/null +++ b/man/man2/gettid.2 @@ -0,0 +1,74 @@ +.\" Copyright 2003 Abhijit Menon-Sen +.\" and Copyright (C) 2008 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH gettid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gettid \- get thread identification +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.P +.B pid_t gettid(void); +.fi +.SH DESCRIPTION +.BR gettid () +returns the caller's thread ID (TID). +In a single-threaded process, the thread ID +is equal to the process ID (PID, as returned by +.BR getpid (2)). +In a multithreaded process, all threads +have the same PID, but each one has a unique TID. +For further details, see the discussion of +.B CLONE_THREAD +in +.BR clone (2). +.SH RETURN VALUE +On success, returns the thread ID of the calling thread. +.SH ERRORS +This call is always successful. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.4.11, +glibc 2.30. +.SH NOTES +The thread ID returned by this call is not the same thing as a +POSIX thread ID (i.e., the opaque value returned by +.BR pthread_self (3)). +.P +In a new thread group created by a +.BR clone (2) +call that does not specify the +.B CLONE_THREAD +flag (or, equivalently, a new process created by +.BR fork (2)), +the new process is a thread group leader, +and its thread group ID (the value returned by +.BR getpid (2)) +is the same as its thread ID (the value returned by +.BR gettid ()). +.SH SEE ALSO +.BR capget (2), +.BR clone (2), +.BR fcntl (2), +.BR fork (2), +.BR get_robust_list (2), +.BR getpid (2), +.\" .BR kcmp (2), +.BR ioprio_set (2), +.\" .BR move_pages (2), +.\" .BR migrate_pages (2), +.BR perf_event_open (2), +.\" .BR process_vm_readv (2), +.\" .BR ptrace (2), +.BR sched_setaffinity (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR tgkill (2), +.BR timer_create (2) diff --git a/man/man2/gettimeofday.2 b/man/man2/gettimeofday.2 new file mode 100644 index 0000000..d963e1b --- /dev/null +++ b/man/man2/gettimeofday.2 @@ -0,0 +1,296 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified 1993-07-23 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com): +.\" Fixed necessary '#include' lines. +.\" Modified 1995-04-15 by Michael Chastain (mec@shell.portal.com): +.\" Added reference to adjtimex. +.\" Removed some nonsense lines pointed out by Urs Thuermann, +.\" (urs@isnogud.escape.de), aeb, 950722. +.\" Modified 1997-01-14 by Austin Donnelly (and1000@debian.org): +.\" Added return values section, and bit on EFAULT +.\" Added clarification on timezone, aeb, 971210. +.\" Removed "#include ", aeb, 010316. +.\" Modified, 2004-05-27 by Michael Kerrisk +.\" Added notes on capability requirement. +.\" +.TH gettimeofday 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gettimeofday, settimeofday \- get / set time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int gettimeofday(struct timeval *restrict " tv , +.BI " struct timezone *_Nullable restrict " tz ); +.BI "int settimeofday(const struct timeval *" tv , +.BI " const struct timezone *_Nullable " tz ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR settimeofday (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR gettimeofday () +and +.BR settimeofday () +can get and set the time as well as a timezone. +.P +The +.I tv +argument is a +.I struct timeval +(as specified in +.IR ): +.P +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.P +and gives the number of seconds and microseconds since the Epoch (see +.BR time (2)). +.P +The +.I tz +argument is a +.IR "struct timezone" : +.P +.in +4n +.EX +struct timezone { + int tz_minuteswest; /* minutes west of Greenwich */ + int tz_dsttime; /* type of DST correction */ +}; +.EE +.in +.P +If either +.I tv +or +.I tz +is NULL, the corresponding structure is not set or returned. +.\" FIXME . The compilation warning looks to be going away in glibc 2.17 +.\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8 +(However, compilation warnings will result if +.I tv +is NULL.) +.\" The following is covered under EPERM below: +.\" .P +.\" Only the superuser may use +.\" .BR settimeofday (). +.P +The use of the +.I timezone +structure is obsolete; the +.I tz +argument should normally be specified as NULL. +(See NOTES below.) +.P +Under Linux, there are some peculiar "warp clock" semantics associated +with the +.BR settimeofday () +system call if on the very first call (after booting) +that has a non-NULL +.I tz +argument, the +.I tv +argument is NULL and the +.I tz_minuteswest +field is nonzero. +(The +.I tz_dsttime +field should be zero for this case.) +In such a case it is assumed that the CMOS clock +is on local time, and that it has to be incremented by this amount +to get UTC system time. +No doubt it is a bad idea to use this feature. +.SH RETURN VALUE +.BR gettimeofday () +and +.BR settimeofday () +return 0 for success. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +One of +.I tv +or +.I tz +pointed outside the accessible address space. +.TP +.B EINVAL +.RB ( settimeofday ()): +.I timezone +is invalid. +.TP +.B EINVAL +.RB ( settimeofday ()): +.I tv.tv_sec +is negative or +.I tv.tv_usec +is outside the range [0, 999,999]. +.TP +.BR EINVAL " (since Linux 4.3)" +.\" commit e1d7ba8735551ed79c7a0463a042353574b96da3 +.RB ( settimeofday ()): +An attempt was made to set the time to a value less than +the current value of the +.B CLOCK_MONOTONIC +clock (see +.BR clock_gettime (2)). +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR settimeofday (); +under Linux the +.B CAP_SYS_TIME +capability is required. +.SH VERSIONS +.SS C library/kernel differences +On some architectures, an implementation of +.BR gettimeofday () +is provided in the +.BR vdso (7). +.P +The kernel accepts NULL for both +.I tv +and +.IR tz . +The timezone argument is ignored by glibc and musl, +and not passed to/from the kernel. +Android's bionic passes the timezone argument to/from the kernel, +but Android does not update the kernel timezone +based on the device timezone in Settings, +so the kernel's timezone is typically UTC. +.SH STANDARDS +.TP +.BR gettimeofday () +POSIX.1-2008 (obsolete). +.TP +.BR settimeofday () +None. +.SH HISTORY +SVr4, 4.3BSD. +POSIX.1-2001 describes +.BR gettimeofday () +but not +.BR settimeofday (). +POSIX.1-2008 marks +.BR gettimeofday () +as obsolete, recommending the use of +.BR clock_gettime (2) +instead. +.P +Traditionally, the fields of +.I struct timeval +were of type +.IR long . +.\" +.SS The tz_dsttime field +On a non-Linux kernel, with glibc, the +.I tz_dsttime +field of +.I struct timezone +will be set to a nonzero value by +.BR gettimeofday () +if the current timezone has ever had or will have a daylight saving +rule applied. +In this sense it exactly mirrors the meaning of +.BR daylight (3) +for the current zone. +On Linux, with glibc, the setting of the +.I tz_dsttime +field of +.I struct timezone +has never been used by +.BR settimeofday () +or +.BR gettimeofday (). +.\" it has not +.\" been and will not be supported by libc or glibc. +.\" Each and every occurrence of this field in the kernel source +.\" (other than the declaration) is a bug. +Thus, the following is purely of historical interest. +.P +On old systems, the field +.I tz_dsttime +contains a symbolic constant (values are given below) +that indicates in which part of the year Daylight Saving Time +is in force. +(Note: this value is constant throughout the year: +it does not indicate that DST is in force, it just selects an +algorithm.) +The daylight saving time algorithms defined are as follows: +.P +.in +4n +.EX +\fBDST_NONE\fP /* not on DST */ +\fBDST_USA\fP /* USA style DST */ +\fBDST_AUST\fP /* Australian style DST */ +\fBDST_WET\fP /* Western European DST */ +\fBDST_MET\fP /* Middle European DST */ +\fBDST_EET\fP /* Eastern European DST */ +\fBDST_CAN\fP /* Canada */ +\fBDST_GB\fP /* Great Britain and Eire */ +\fBDST_RUM\fP /* Romania */ +\fBDST_TUR\fP /* Turkey */ +\fBDST_AUSTALT\fP /* Australian style with shift in 1986 */ +.EE +.in +.P +Of course it turned out that the period in which +Daylight Saving Time is in force cannot be given +by a simple algorithm, one per country; indeed, +this period is determined by unpredictable political +decisions. +So this method of representing timezones +has been abandoned. +.SH NOTES +The time returned by +.BR gettimeofday () +.I is +affected by discontinuous jumps in the system time +(e.g., if the system administrator manually changes the system time). +If you need a monotonically increasing clock, see +.BR clock_gettime (2). +.P +Macros for operating on +.I timeval +structures are described in +.BR timeradd (3). +.SH SEE ALSO +.BR date (1), +.BR adjtimex (2), +.BR clock_gettime (2), +.BR time (2), +.BR ctime (3), +.BR ftime (3), +.BR timeradd (3), +.BR capabilities (7), +.BR time (7), +.BR vdso (7), +.BR hwclock (8) diff --git a/man/man2/getuid.2 b/man/man2/getuid.2 new file mode 100644 index 0000000..0660a28 --- /dev/null +++ b/man/man2/getuid.2 @@ -0,0 +1,80 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Historical remark, aeb, 2004-06-05 +.TH getuid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getuid, geteuid \- get user identity +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B uid_t getuid(void); +.B uid_t geteuid(void); +.fi +.SH DESCRIPTION +.BR getuid () +returns the real user ID of the calling process. +.P +.BR geteuid () +returns the effective user ID of the calling process. +.SH ERRORS +These functions are always successful +and never modify +.\" https://www.austingroupbugs.net/view.php?id=511 +.\" 0000511: getuid and friends should not modify errno +.IR errno . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.P +In UNIX\ V6 the +.BR getuid () +call returned +.IR "(euid << 8) + uid" . +UNIX\ V7 introduced separate calls +.BR getuid () +and +.BR geteuid (). +.P +The original Linux +.BR getuid () +and +.BR geteuid () +system calls supported only 16-bit user IDs. +Subsequently, Linux 2.4 added +.BR getuid32 () +and +.BR geteuid32 (), +supporting 32-bit IDs. +The glibc +.BR getuid () +and +.BR geteuid () +wrapper functions transparently deal with the variations across kernel versions. +.P +On Alpha, instead of a pair of +.BR getuid () +and +.BR geteuid () +system calls, a single +.BR getxuid () +system call is provided, which returns a pair of real and effective UIDs. +The glibc +.BR getuid () +and +.BR geteuid () +wrapper functions transparently deal with this. +See +.BR syscall (2) +for details regarding register mapping. +.SH SEE ALSO +.BR getresuid (2), +.BR setreuid (2), +.BR setuid (2), +.BR credentials (7) diff --git a/man/man2/getuid32.2 b/man/man2/getuid32.2 new file mode 100644 index 0000000..165cfe1 --- /dev/null +++ b/man/man2/getuid32.2 @@ -0,0 +1 @@ +.so man2/getuid.2 diff --git a/man/man2/getunwind.2 b/man/man2/getunwind.2 new file mode 100644 index 0000000..64343aa --- /dev/null +++ b/man/man2/getunwind.2 @@ -0,0 +1,87 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" Written by Marcela Maslanova +.\" and Copyright 2013, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getunwind 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getunwind \- copy the unwind data to caller's buffer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "[[deprecated]] long syscall(SYS_getunwind, void " buf [. buf_size ], +.BI " size_t " buf_size ); +.fi +.SH DESCRIPTION +.I Note: this system call is obsolete. +.P +The +IA-64-specific +.BR getunwind () +system call copies the kernel's call frame +unwind data into the buffer pointed to by +.I buf +and returns the size of the unwind data; +this data describes the gate page (kernel code that +is mapped into user space). +.P +The size of the buffer +.I buf +is specified in +.IR buf_size . +The data is copied only if +.I buf_size +is greater than or equal to the size of the unwind data and +.I buf +is not NULL; +otherwise, no data is copied, and the call succeeds, +returning the size that would be needed to store the unwind data. +.P +The first part of the unwind data contains an unwind table. +The rest contains the associated unwind information, in no particular order. +The unwind table contains entries of the following form: +.P +.in +4n +.EX +u64 start; (64\-bit address of start of function) +u64 end; (64\-bit address of end of function) +u64 info; (BUF\-relative offset to unwind info) +.EE +.in +.P +An entry whose +.I start +value is zero indicates the end of the table. +For more information about the format, see the +.I IA-64 Software Conventions and Runtime Architecture +manual. +.SH RETURN VALUE +On success, +.BR getunwind () +returns the size of the unwind data. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.BR getunwind () +fails with the error +.B EFAULT +if the unwind info can't be stored in the space specified by +.IR buf . +.SH STANDARDS +Linux on IA-64. +.SH HISTORY +Linux 2.4. +.P +This system call has been deprecated. +The modern way to obtain the kernel's unwind data is via the +.BR vdso (7). +.SH SEE ALSO +.BR getauxval (3) diff --git a/man/man2/getxattr.2 b/man/man2/getxattr.2 new file mode 100644 index 0000000..e4c67a6 --- /dev/null +++ b/man/man2/getxattr.2 @@ -0,0 +1,143 @@ +.\" Copyright (C) Andreas Gruenbacher, February 2001 +.\" Copyright (C) Silicon Graphics Inc, September 2001 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH getxattr 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getxattr, lgetxattr, fgetxattr \- retrieve an extended attribute value +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t getxattr(const char *" path ", const char *" name , +.BI " void " value [. size "], size_t " size ); +.BI "ssize_t lgetxattr(const char *" path ", const char *" name , +.BI " void " value [. size "], size_t " size ); +.BI "ssize_t fgetxattr(int " fd ", const char *" name , +.BI " void " value [. size "], size_t " size ); +.fi +.SH DESCRIPTION +Extended attributes are +.IR name : value +pairs associated with inodes (files, directories, symbolic links, etc.). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e., the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR xattr (7). +.P +.BR getxattr () +retrieves the value of the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +The attribute value is placed in the buffer pointed to by +.IR value ; +.I size +specifies the size of that buffer. +The return value of the call is the number of bytes placed in +.IR value . +.P +.BR lgetxattr () +is identical to +.BR getxattr (), +except in the case of a symbolic link, where the link itself is +interrogated, not the file that it refers to. +.P +.BR fgetxattr () +is identical to +.BR getxattr (), +only the open file referred to by +.I fd +(as returned by +.BR open (2)) +is interrogated in place of +.IR path . +.P +An extended attribute +.I name +is a null-terminated string. +The name includes a namespace prefix; there may be several, disjoint +namespaces associated with an individual inode. +The value of an extended attribute is a chunk of arbitrary textual or +binary data that was assigned using +.BR setxattr (2). +.P +If +.I size +is specified as zero, these calls return the current size of the +named extended attribute (and leave +.I value +unchanged). +This can be used to determine the size of the buffer that +should be supplied in a subsequent call. +(But, bear in mind that there is a possibility that the +attribute value may change between the two calls, +so that it is still necessary to check the return status +from the second call.) +.SH RETURN VALUE +On success, these calls return a nonnegative value which is +the size (in bytes) of the extended attribute value. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B E2BIG +The size of the attribute value is larger than the maximum size allowed; the +attribute cannot be retrieved. +This can happen on filesystems that support +very large attribute values such as NFSv4, for example. +.TP +.B ENODATA +The named attribute does not exist, or the process has no access to +this attribute. +.\" .RB ( ENOATTR +.\" is defined to be a synonym for +.\" .BR ENODATA +.\" in +.\" .IR .) +.TP +.B ENOTSUP +Extended attributes are not supported by the filesystem, or are disabled. +.TP +.B ERANGE +The +.I size +of the +.I value +buffer is too small to hold the result. +.P +In addition, the errors documented in +.BR stat (2) +can also occur. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.4, +glibc 2.3. +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@computer.org > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.\" Please send any bug reports or comments to these addresses. +.SH EXAMPLES +See +.BR listxattr (2). +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR listxattr (2), +.BR open (2), +.BR removexattr (2), +.BR setxattr (2), +.BR stat (2), +.BR symlink (7), +.BR xattr (7) diff --git a/man/man2/gtty.2 b/man/man2/gtty.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/gtty.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/idle.2 b/man/man2/idle.2 new file mode 100644 index 0000000..15d7a09 --- /dev/null +++ b/man/man2/idle.2 @@ -0,0 +1,44 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from linux/mm/swap.c: +.\" Copyright (C) 1991, 1992 Linus Torvalds +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 21 Aug 1994 by Michael Chastain : +.\" Added text about calling restriction (new in Linux 1.1.20 I believe). +.\" N.B. calling "idle" from user process used to hang process! +.\" Modified Thu Oct 31 14:41:15 1996 by Eric S. Raymond +.\" " +.TH idle 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +idle \- make process 0 idle +.SH SYNOPSIS +.nf +.B #include +.P +.B [[deprecated]] int idle(void); +.fi +.SH DESCRIPTION +.BR idle () +is an internal system call used during bootstrap. +It marks the process's pages as swappable, lowers its priority, +and enters the main scheduling loop. +.BR idle () +never returns. +.P +Only process 0 may call +.BR idle (). +Any user process, even a process with superuser permission, +will receive +.BR EPERM . +.SH RETURN VALUE +.BR idle () +never returns for process 0, and always returns \-1 for a user process. +.SH ERRORS +.TP +.B EPERM +Always, for a user process. +.SH STANDARDS +Linux. +.SH HISTORY +Removed in Linux 2.3.13. diff --git a/man/man2/inb.2 b/man/man2/inb.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/inb.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/inb_p.2 b/man/man2/inb_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/inb_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/init_module.2 b/man/man2/init_module.2 new file mode 100644 index 0000000..98b3c5c --- /dev/null +++ b/man/man2/init_module.2 @@ -0,0 +1,393 @@ +.\" Copyright (C) 2012 Michael Kerrisk +.\" A few fragments remain from a version +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH init_module 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +init_module, finit_module \- load a kernel module +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " MODULE_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_init_module, void " module_image [. len "], \ +unsigned long " len , +.BI " const char *" param_values ); +.BI "int syscall(SYS_finit_module, int " fd , +.BI " const char *" param_values ", int " flags ); +.fi +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR init_module () +loads an ELF image into kernel space, +performs any necessary symbol relocations, +initializes module parameters to values provided by the caller, +and then runs the module's +.I init +function. +This system call requires privilege. +.P +The +.I module_image +argument points to a buffer containing the binary image +to be loaded; +.I len +specifies the size of that buffer. +The module image should be a valid ELF image, built for the running kernel. +.P +The +.I param_values +argument is a string containing space-delimited specifications of the +values for module parameters (defined inside the module using +.BR module_param () +and +.BR module_param_array ()). +The kernel parses this string and initializes the specified +parameters. +Each of the parameter specifications has the form: +.P +.RI " " name [\c +.BI = value\c +.RB [ ,\c +.IR value ...]] +.P +The parameter +.I name +is one of those defined within the module using +.IR module_param () +(see the Linux kernel source file +.IR include/linux/moduleparam.h ). +The parameter +.I value +is optional in the case of +.I bool +and +.I invbool +parameters. +Values for array parameters are specified as a comma-separated list. +.SS finit_module() +The +.BR finit_module () +.\" commit 34e1169d996ab148490c01b65b4ee371cf8ffba2 +.\" https://lwn.net/Articles/519010/ +system call is like +.BR init_module (), +but reads the module to be loaded from the file descriptor +.IR fd . +It is useful when the authenticity of a kernel module +can be determined from its location in the filesystem; +in cases where that is possible, +the overhead of using cryptographically signed modules to +determine the authenticity of a module can be avoided. +The +.I param_values +argument is as for +.BR init_module (). +.P +The +.I flags +argument modifies the operation of +.BR finit_module (). +It is a bit mask value created by ORing +together zero or more of the following flags: +.\" commit 2f3238aebedb243804f58d62d57244edec4149b2 +.TP +.B MODULE_INIT_IGNORE_MODVERSIONS +Ignore symbol version hashes. +.TP +.B MODULE_INIT_IGNORE_VERMAGIC +Ignore kernel version magic. +.TP +.BR MODULE_INIT_COMPRESSED_FILE " (since Linux 5.17)" +.\" commit b1ae6dc41eaaa98bb75671e0f3665bfda248c3e7 +Use in-kernel module decompression. +.P +There are some safety checks built into a module to ensure that +it matches the kernel against which it is loaded. +.\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html +.\" is dated, but informative +These checks are recorded when the module is built and +verified when the module is loaded. +First, the module records a "vermagic" string containing +the kernel version number and prominent features (such as the CPU type). +Second, if the module was built with the +.B CONFIG_MODVERSIONS +configuration option enabled, +a version hash is recorded for each symbol the module uses. +This hash is based on the types of the arguments and return value +for the function named by the symbol. +In this case, the kernel version number within the +"vermagic" string is ignored, +as the symbol version hashes are assumed to be sufficiently reliable. +.P +Using the +.B MODULE_INIT_IGNORE_VERMAGIC +flag indicates that the "vermagic" string is to be ignored, and the +.B MODULE_INIT_IGNORE_MODVERSIONS +flag indicates that the symbol version hashes are to be ignored. +If the kernel is built to permit forced loading (i.e., configured with +.BR CONFIG_MODULE_FORCE_LOAD ), +then loading continues, otherwise it fails with the error +.B ENOEXEC +as expected for malformed modules. +.P +If the kernel was build with +.BR CONFIG_MODULE_DECOMPRESS , +the in-kernel decompression feature can be used. +User-space code can check if the kernel supports decompression +by reading the +.I /sys/module/compression +attribute. +If the kernel supports decompression, +the compressed file can directly be passed to +.BR finit_module () +using the +.B MODULE_INIT_COMPRESSED_FILE +flag. +The in-kernel module decompressor supports the following compression algorithms: +.P +.RS 4 +.PD 0 +.IP \[bu] 3 +.I gzip +(since Linux 5.17) +.IP \[bu] +.I xz +(since Linux 5.17) +.IP \[bu] +.I zstd +.\" commit 169a58ad824d896b9e291a27193342616e651b82 +(since Linux 6.2) +.PD +.RE +.P +The kernel only implements a single decompression method. +This is selected during module generation accordingly to the compression method +chosen in the kernel configuration. +.SH RETURN VALUE +On success, these system calls return 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.BR EBADMSG " (since Linux 3.7)" +Module signature is misformatted. +.TP +.B EBUSY +Timeout while trying to resolve a symbol reference by this module. +.TP +.B EFAULT +An address argument referred to a location that +is outside the process's accessible address space. +.TP +.BR ENOKEY " (since Linux 3.7)" +.\" commit 48ba2462ace6072741fd8d0058207d630ce93bf1 +.\" commit 1d0059f3a468825b5fc5405c636a2f6e02707ffa +.\" commit 106a4ee258d14818467829bf0e12aeae14c16cd7 +Module signature is invalid or +the kernel does not have a key for this module. +This error is returned only if the kernel was configured with +.BR CONFIG_MODULE_SIG_FORCE ; +if the kernel was not configured with this option, +then an invalid or unsigned module simply taints the kernel. +.TP +.B ENOMEM +Out of memory. +.TP +.B EPERM +The caller was not privileged +(did not have the +.B CAP_SYS_MODULE +capability), +or module loading is disabled +(see +.I /proc/sys/kernel/modules_disabled +in +.BR proc (5)). +.P +The following errors may additionally occur for +.BR init_module (): +.TP +.B EEXIST +A module with this name is already loaded. +.TP +.B EINVAL +.I param_values +is invalid, or some part of the ELF image in +.I module_image +contains inconsistencies. +.\" .TP +.\" .BR EINVAL " (Linux 2.4 and earlier)" +.\" Some +.\" .I image +.\" slot is filled in incorrectly, +.\" .I image\->name +.\" does not correspond to the original module name, some +.\" .I image\->deps +.\" entry does not correspond to a loaded module, +.\" or some other similar inconsistency. +.TP +.B ENOEXEC +The binary image supplied in +.I module_image +is not an ELF image, +or is an ELF image that is invalid or for a different architecture. +.P +The following errors may additionally occur for +.BR finit_module (): +.TP +.B EBADF +The file referred to by +.I fd +is not opened for reading. +.TP +.B EFBIG +The file referred to by +.I fd +is too large. +.TP +.B EINVAL +.I flags +is invalid. +.TP +.B EINVAL +The decompressor sanity checks failed, +while loading a compressed module with flag +.B MODULE_INIT_COMPRESSED_FILE +set. +.TP +.B ENOEXEC +.I fd +does not refer to an open file. +.TP +.BR EOPNOTSUPP " (since Linux 5.17)" +The flag +.B MODULE_INIT_COMPRESSED_FILE +is set to load a compressed module, +and the kernel was built without +.BR CONFIG_MODULE_DECOMPRESS . +.TP +.BR ETXTBSY " (since Linux 4.7)" +.\" commit 39d637af5aa7577f655c58b9e55587566c63a0af +The file referred to by +.I fd +is opened for read-write. +.P +In addition to the above errors, if the module's +.I init +function is executed and returns an error, then +.BR init_module () +or +.BR finit_module () +fails and +.I errno +is set to the value returned by the +.I init +function. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR finit_module () +Linux 3.8. +.P +The +.BR init_module () +system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc versions before glibc 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it is (before glibc 2.23) sufficient to +manually declare the interface in your code; +alternatively, you can invoke the system call using +.BR syscall (2). +.SS Linux 2.4 and earlier +In Linux 2.4 and earlier, the +.BR init_module () +system call was rather different: +.P +.B " #include " +.P +.BI " int init_module(const char *" name ", struct module *" image ); +.P +(User-space applications can detect which version of +.BR init_module () +is available by calling +.BR query_module (); +the latter call fails with the error +.B ENOSYS +on Linux 2.6 and later.) +.P +The older version of the system call +loads the relocated module image pointed to by +.I image +into kernel space and runs the module's +.I init +function. +The caller is responsible for providing the relocated image (since +Linux 2.6, the +.BR init_module () +system call does the relocation). +.P +The module image begins with a module structure and is followed by +code and data as appropriate. +Since Linux 2.2, the module structure is defined as follows: +.P +.in +4n +.EX +struct module { + unsigned long size_of_struct; + struct module *next; + const char *name; + unsigned long size; + long usecount; + unsigned long flags; + unsigned int nsyms; + unsigned int ndeps; + struct module_symbol *syms; + struct module_ref *deps; + struct module_ref *refs; + int (*init)(void); + void (*cleanup)(void); + const struct exception_table_entry *ex_table_start; + const struct exception_table_entry *ex_table_end; +#ifdef __alpha__ + unsigned long gp; +#endif +}; +.EE +.in +.P +All of the pointer fields, with the exception of +.I next +and +.IR refs , +are expected to point within the module body and be +initialized as appropriate for kernel space, that is, relocated with +the rest of the module. +.SH NOTES +Information about currently loaded modules can be found in +.I /proc/modules +and in the file trees under the per-module subdirectories under +.IR /sys/module . +.P +See the Linux kernel source file +.I include/linux/module.h +for some useful background information. +.SH SEE ALSO +.BR create_module (2), +.BR delete_module (2), +.BR query_module (2), +.BR lsmod (8), +.BR modprobe (8) diff --git a/man/man2/inl.2 b/man/man2/inl.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/inl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/inl_p.2 b/man/man2/inl_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/inl_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/inotify_add_watch.2 b/man/man2/inotify_add_watch.2 new file mode 100644 index 0000000..a430f39 --- /dev/null +++ b/man/man2/inotify_add_watch.2 @@ -0,0 +1,135 @@ +.\" Copyright (C) 2005 Robert Love +.\" and Copyright, 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2005-07-19 Robert Love - initial version +.\" 2006-02-07 mtk, various changes +.\" +.TH inotify_add_watch 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inotify_add_watch \- add a watch to an initialized inotify instance +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int inotify_add_watch(int " fd ", const char *" pathname ", uint32_t " mask ); +.fi +.SH DESCRIPTION +.BR inotify_add_watch () +adds a new watch, or modifies an existing watch, +for the file whose location is specified in +.IR pathname ; +the caller must have read permission for this file. +The +.I fd +argument is a file descriptor referring to the +inotify instance whose watch list is to be modified. +The events to be monitored for +.I pathname +are specified in the +.I mask +bit-mask argument. +See +.BR inotify (7) +for a description of the bits that can be set in +.IR mask . +.P +A successful call to +.BR inotify_add_watch () +returns a unique watch descriptor for this inotify instance, +for the filesystem object (inode) that corresponds to +.IR pathname . +If the filesystem object +was not previously being watched by this inotify instance, +then the watch descriptor is newly allocated. +If the filesystem object was already being watched +(perhaps via a different link to the same object), then the descriptor +for the existing watch is returned. +.P +The watch descriptor is returned by later +.BR read (2)s +from the inotify file descriptor. +These reads fetch +.I inotify_event +structures (see +.BR inotify (7)) +indicating filesystem events; +the watch descriptor inside this structure identifies +the object for which the event occurred. +.SH RETURN VALUE +On success, +.BR inotify_add_watch () +returns a watch descriptor (a nonnegative integer). +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Read access to the given file is not permitted. +.TP +.B EBADF +The given file descriptor is not valid. +.TP +.B EEXIST +.I mask +contains +.B IN_MASK_CREATE +and +.I pathname +refers to a file already being watched by the same +.IR fd . +.TP +.B EFAULT +.I pathname +points outside of the process's accessible address space. +.TP +.B EINVAL +The given event mask contains no valid events; or +.I mask +contains both +.B IN_MASK_ADD +and +.BR IN_MASK_CREATE ; +or +.I fd +is not an inotify file descriptor. +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The user limit on the total number of inotify watches was reached or the +kernel failed to allocate a needed resource. +.TP +.B ENOTDIR +.I mask +contains +.B IN_ONLYDIR +and +.I pathname +is not a directory. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.13. +.SH EXAMPLES +See +.BR inotify (7). +.SH SEE ALSO +.BR inotify_init (2), +.BR inotify_rm_watch (2), +.BR inotify (7) diff --git a/man/man2/inotify_init.2 b/man/man2/inotify_init.2 new file mode 100644 index 0000000..44f6203 --- /dev/null +++ b/man/man2/inotify_init.2 @@ -0,0 +1,97 @@ +.\" Copyright (C) 2005 Robert Love +.\" and Copyright (C) 2008, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2005-07-19 Robert Love - initial version +.\" 2006-02-07 mtk, minor changes +.\" 2008-10-10 mtk: add description of inotify_init1() +.\" +.TH inotify_init 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inotify_init, inotify_init1 \- initialize an inotify instance +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B "int inotify_init(void);" +.BI "int inotify_init1(int " flags ); +.fi +.SH DESCRIPTION +For an overview of the inotify API, see +.BR inotify (7). +.P +.BR inotify_init () +initializes a new inotify instance and returns a file descriptor associated +with a new inotify event queue. +.P +If +.I flags +is 0, then +.BR inotify_init1 () +is the same as +.BR inotify_init (). +The following values can be bitwise ORed in +.I flags +to obtain different behavior: +.TP +.B IN_NONBLOCK +Set the +.B O_NONBLOCK +file status flag on the open file description (see +.BR open (2)) +referred to by the new file descriptor. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B IN_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.SH RETURN VALUE +On success, these system calls return a new file descriptor. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.RB ( inotify_init1 ()) +An invalid value was specified in +.IR flags . +.TP +.B EMFILE +The user limit on the total number of inotify instances has been reached. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +Insufficient kernel memory is available. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR inotify_init () +Linux 2.6.13, +glibc 2.4. +.TP +.BR inotify_init1 () +Linux 2.6.27, +glibc 2.9. +.SH SEE ALSO +.BR inotify_add_watch (2), +.BR inotify_rm_watch (2), +.BR inotify (7) diff --git a/man/man2/inotify_init1.2 b/man/man2/inotify_init1.2 new file mode 100644 index 0000000..62c5b44 --- /dev/null +++ b/man/man2/inotify_init1.2 @@ -0,0 +1 @@ +.so man2/inotify_init.2 diff --git a/man/man2/inotify_rm_watch.2 b/man/man2/inotify_rm_watch.2 new file mode 100644 index 0000000..2f6a811 --- /dev/null +++ b/man/man2/inotify_rm_watch.2 @@ -0,0 +1,60 @@ +.\" Copyright (C) 2005 Robert Love +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2005-07-19 Robert Love - initial version +.\" 2006-02-07 mtk, minor changes +.\" +.TH inotify_rm_watch 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inotify_rm_watch \- remove an existing watch from an inotify instance +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int inotify_rm_watch(int " fd ", int " wd ); +.\" Before glibc 2.10, the second argument was types as uint32_t. +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=7040 +.fi +.SH DESCRIPTION +.BR inotify_rm_watch () +removes the watch associated with the watch descriptor +.I wd +from the inotify instance associated with the file descriptor +.IR fd . +.P +Removing a watch causes an +.B IN_IGNORED +event to be generated for this watch descriptor. +(See +.BR inotify (7).) +.SH RETURN VALUE +On success, +.BR inotify_rm_watch () +returns zero. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +The watch descriptor +.I wd +is not valid; or +.I fd +is not an inotify file descriptor. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.13. +.SH SEE ALSO +.BR inotify_add_watch (2), +.BR inotify_init (2), +.BR inotify (7) diff --git a/man/man2/insb.2 b/man/man2/insb.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/insb.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/insl.2 b/man/man2/insl.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/insl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/insw.2 b/man/man2/insw.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/insw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/intro.2 b/man/man2/intro.2 new file mode 100644 index 0000000..f9455ee --- /dev/null +++ b/man/man2/intro.2 @@ -0,0 +1,115 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-10-23 mtk: moved the _syscallN specific material to the +.\" new _syscall(2) page, and substantially enhanced and rewrote +.\" the remaining material on this page. +.\" +.TH intro 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intro \- introduction to system calls +.SH DESCRIPTION +Section 2 of the manual describes the Linux system calls. +A system call is an entry point into the Linux kernel. +Usually, system calls are not invoked directly: +instead, most system calls have corresponding C library +wrapper functions which perform the steps required +(e.g., trapping to kernel mode) in order to invoke +the system call. +Thus, making a system call looks the same as invoking a normal +library function. +.P +In many cases, the C library wrapper function does nothing more than: +.IP \[bu] 3 +copying arguments and the unique system call number to the +registers where the kernel expects them; +.IP \[bu] +trapping to kernel mode, +at which point the kernel does the real work of the system call; +.IP \[bu] +setting +.I errno +if the system call returns an error number when the kernel returns the +CPU to user mode. +.P +However, in a few cases, a wrapper function may do rather more than this, +for example, performing some preprocessing +of the arguments before trapping to kernel mode, +or postprocessing of values returned by the system call. +Where this is the case, the manual pages in Section 2 generally +try to note the details of both the (usually GNU) C library API +interface and the raw system call. +Most commonly, the main DESCRIPTION will focus on the C library interface, +and differences for the system call are covered in the NOTES section. +.P +For a list of the Linux system calls, see +.BR syscalls (2). +.SH RETURN VALUE +On error, most system calls return a negative error number +(i.e., the negated value of one of the constants described in +.BR errno (3)). +The C library wrapper hides this detail from the caller: when a +system call returns a negative value, the wrapper copies the +absolute value into the +.I errno +variable, and returns \-1 as the return value of the wrapper. +.P +The value returned by a successful system call depends on the call. +Many system calls return 0 on success, but some can return nonzero +values from a successful call. +The details are described in the individual manual pages. +.P +In some cases, +the programmer must define a feature test macro in order to obtain +the declaration of a system call from the header file specified +in the man page SYNOPSIS section. +(Where required, these feature test macros must be defined before including +.I any +header files.) +In such cases, the required macro is described in the man page. +For further information on feature test macros, see +.BR feature_test_macros (7). +.SH STANDARDS +Certain terms and abbreviations are used to indicate UNIX variants +and standards to which calls in this section conform. +See +.BR standards (7). +.SH NOTES +.SS Calling directly +In most cases, it is unnecessary to invoke a system call directly, +but there are times when the Standard C library does not implement +a nice wrapper function for you. +In this case, the programmer must manually invoke the system call using +.BR syscall (2). +Historically, this was also possible using one of the _syscall macros +described in +.BR _syscall (2). +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.ad l +.nh +.BR _syscall (2), +.BR syscall (2), +.BR syscalls (2), +.BR errno (3), +.BR intro (3), +.BR capabilities (7), +.BR credentials (7), +.BR feature_test_macros (7), +.BR mq_overview (7), +.BR path_resolution (7), +.BR pipe (7), +.BR pty (7), +.BR sem_overview (7), +.BR shm_overview (7), +.BR signal (7), +.BR socket (7), +.BR standards (7), +.BR symlink (7), +.BR system_data_types (7), +.BR sysvipc (7), +.BR time (7) diff --git a/man/man2/inw.2 b/man/man2/inw.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/inw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/inw_p.2 b/man/man2/inw_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/inw_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/io_cancel.2 b/man/man2/io_cancel.2 new file mode 100644 index 0000000..6864dee --- /dev/null +++ b/man/man2/io_cancel.2 @@ -0,0 +1,106 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH io_cancel 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +io_cancel \- cancel an outstanding asynchronous I/O operation +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.P +Alternatively, Asynchronous I/O library +.RI ( libaio ", " \-laio ); +see VERSIONS. +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of needed types */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_io_cancel, aio_context_t " ctx_id ", struct iocb *" iocb , +.BI " struct io_event *" result ); +.fi +.SH DESCRIPTION +.IR Note : +this page describes the raw Linux system call interface. +The wrapper function provided by +.I libaio +uses a different type for the +.I ctx_id +argument. +See VERSIONS. +.P +The +.BR io_cancel () +system call +attempts to cancel an asynchronous I/O operation previously submitted with +.BR io_submit (2). +The +.I iocb +argument describes the operation to be canceled and the +.I ctx_id +argument is the AIO context to which the operation was submitted. +If the operation is successfully canceled, the event will be copied into +the memory pointed to by +.I result +without being placed into the +completion queue. +.SH RETURN VALUE +On success, +.BR io_cancel () +returns 0. +For the failure return, see VERSIONS. +.SH ERRORS +.TP +.B EAGAIN +The \fIiocb\fP specified was not canceled. +.TP +.B EFAULT +One of the data structures points to invalid data. +.TP +.B EINVAL +The AIO context specified by \fIctx_id\fP is invalid. +.TP +.B ENOSYS +.BR io_cancel () +is not implemented on this architecture. +.SH VERSIONS +You probably want to use the +.BR io_cancel () +wrapper function provided by +.\" http://git.fedorahosted.org/git/?p=libaio.git +.IR libaio . +.P +Note that the +.I libaio +wrapper function uses a different type +.RI ( io_context_t ) +.\" But glibc is confused, since uses 'io_context_t' to declare +.\" the system call. +for the +.I ctx_id +argument. +Note also that the +.I libaio +wrapper does not follow the usual C library conventions for indicating errors: +on error it returns a negated error number +(the negative of one of the values listed in ERRORS). +If the system call is invoked via +.BR syscall (2), +then the return value follows the usual conventions for +indicating an error: \-1, with +.I errno +set to a (positive) value that indicates the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5. +.SH SEE ALSO +.BR io_destroy (2), +.BR io_getevents (2), +.BR io_setup (2), +.BR io_submit (2), +.BR aio (7) +.\" .SH AUTHOR +.\" Kent Yoder. diff --git a/man/man2/io_destroy.2 b/man/man2/io_destroy.2 new file mode 100644 index 0000000..a5ddbf8 --- /dev/null +++ b/man/man2/io_destroy.2 @@ -0,0 +1,97 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH io_destroy 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +io_destroy \- destroy an asynchronous I/O context +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " aio_context_t " */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_io_destroy, aio_context_t " ctx_id ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR io_destroy (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.IR Note : +this page describes the raw Linux system call interface. +The wrapper function provided by +.I libaio +uses a different type for the +.I ctx_id +argument. +See VERSIONS. +.P +The +.BR io_destroy () +system call +will attempt to cancel all outstanding asynchronous I/O operations against +.IR ctx_id , +will block on the completion of all operations +that could not be canceled, and will destroy the +.IR ctx_id . +.SH RETURN VALUE +On success, +.BR io_destroy () +returns 0. +For the failure return, see VERSIONS. +.SH ERRORS +.TP +.B EFAULT +The context pointed to is invalid. +.TP +.B EINVAL +The AIO context specified by \fIctx_id\fP is invalid. +.TP +.B ENOSYS +.BR io_destroy () +is not implemented on this architecture. +.SH VERSIONS +You probably want to use the +.BR io_destroy () +wrapper function provided by +.\" http://git.fedorahosted.org/git/?p=libaio.git +.IR libaio . +.P +Note that the +.I libaio +wrapper function uses a different type +.RI ( io_context_t ) +.\" But glibc is confused, since uses 'io_context_t' to declare +.\" the system call. +for the +.I ctx_id +argument. +Note also that the +.I libaio +wrapper does not follow the usual C library conventions for indicating errors: +on error it returns a negated error number +(the negative of one of the values listed in ERRORS). +If the system call is invoked via +.BR syscall (2), +then the return value follows the usual conventions for +indicating an error: \-1, with +.I errno +set to a (positive) value that indicates the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5. +.SH SEE ALSO +.BR io_cancel (2), +.BR io_getevents (2), +.BR io_setup (2), +.BR io_submit (2), +.BR aio (7) +.\" .SH AUTHOR +.\" Kent Yoder. diff --git a/man/man2/io_getevents.2 b/man/man2/io_getevents.2 new file mode 100644 index 0000000..d81514c --- /dev/null +++ b/man/man2/io_getevents.2 @@ -0,0 +1,137 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH io_getevents 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +io_getevents \- read asynchronous I/O events from the completion queue +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.P +Alternatively, Asynchronous I/O library +.RI ( libaio ", " \-laio ); +see VERSIONS. +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " *io_* " types */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_io_getevents, aio_context_t " ctx_id , +.BI " long " min_nr ", long " nr ", struct io_event *" events , +.BI " struct timespec *" timeout ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR io_getevents (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.IR Note : +this page describes the raw Linux system call interface. +The wrapper function provided by +.I libaio +uses a different type for the +.I ctx_id +argument. +See VERSIONS. +.P +The +.BR io_getevents () +system call +attempts to read at least \fImin_nr\fP events and +up to \fInr\fP events from the completion queue of the AIO context +specified by \fIctx_id\fP. +.P +The \fItimeout\fP argument specifies the amount of time to wait for events, +and is specified as a relative timeout in a +.BR timespec (3) +structure. +.P +The specified time will be rounded up to the system clock granularity +and is guaranteed not to expire early. +.P +Specifying +.I timeout +as NULL means block indefinitely until at least +.I min_nr +events have been obtained. +.SH RETURN VALUE +On success, +.BR io_getevents () +returns the number of events read. +This may be 0, or a value less than +.IR min_nr , +if the +.I timeout +expired. +It may also be a nonzero value less than +.IR min_nr , +if the call was interrupted by a signal handler. +.P +For the failure return, see VERSIONS. +.SH ERRORS +.TP +.B EFAULT +Either \fIevents\fP or \fItimeout\fP is an invalid pointer. +.TP +.B EINTR +Interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +\fIctx_id\fP is invalid. +\fImin_nr\fP is out of range or \fInr\fP is +out of range. +.TP +.B ENOSYS +.BR io_getevents () +is not implemented on this architecture. +.SH VERSIONS +You probably want to use the +.BR io_getevents () +wrapper function provided by +.\" http://git.fedorahosted.org/git/?p=libaio.git +.IR libaio . +.P +Note that the +.I libaio +wrapper function uses a different type +.RI ( io_context_t ) +.\" But glibc is confused, since uses 'io_context_t' to declare +.\" the system call. +for the +.I ctx_id +argument. +Note also that the +.I libaio +wrapper does not follow the usual C library conventions for indicating errors: +on error it returns a negated error number +(the negative of one of the values listed in ERRORS). +If the system call is invoked via +.BR syscall (2), +then the return value follows the usual conventions for +indicating an error: \-1, with +.I errno +set to a (positive) value that indicates the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5. +.SH BUGS +An invalid +.I ctx_id +may cause a segmentation fault instead of generating the error +.BR EINVAL . +.SH SEE ALSO +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_setup (2), +.BR io_submit (2), +.BR timespec (3), +.BR aio (7), +.BR time (7) +.\" .SH AUTHOR +.\" Kent Yoder. diff --git a/man/man2/io_setup.2 b/man/man2/io_setup.2 new file mode 100644 index 0000000..2e4cb10 --- /dev/null +++ b/man/man2/io_setup.2 @@ -0,0 +1,114 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH io_setup 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +io_setup \- create an asynchronous I/O context +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.P +Alternatively, Asynchronous I/O library +.RI ( libaio ", " \-laio ); +see VERSIONS. +.SH SYNOPSIS +.nf +.BR "#include " " /* Defines needed types */" +.P +.BI "long io_setup(unsigned int " nr_events ", aio_context_t *" ctx_idp ); +.fi +.P +.IR Note : +There is no glibc wrapper for this system call; see VERSIONS. +.SH DESCRIPTION +.IR Note : +this page describes the raw Linux system call interface. +The wrapper function provided by +.I libaio +uses a different type for the +.I ctx_idp +argument. +See VERSIONS. +.P +The +.BR io_setup () +system call +creates an asynchronous I/O context suitable for concurrently processing +\fInr_events\fP operations. +The +.I ctx_idp +argument must not point to an AIO context that already exists, and must +be initialized to 0 prior to the call. +On successful creation of the AIO context, \fI*ctx_idp\fP is filled in +with the resulting handle. +.SH RETURN VALUE +On success, +.BR io_setup () +returns 0. +For the failure return, see VERSIONS. +.SH ERRORS +.TP +.B EAGAIN +The specified \fInr_events\fP exceeds the limit of available events, +as defined in +.I /proc/sys/fs/aio\-max\-nr +(see +.BR proc (5)). +.TP +.B EFAULT +An invalid pointer is passed for \fIctx_idp\fP. +.TP +.B EINVAL +\fIctx_idp\fP is not initialized, or the specified \fInr_events\fP +exceeds internal limits. +\fInr_events\fP should be greater than 0. +.TP +.B ENOMEM +Insufficient kernel resources are available. +.TP +.B ENOSYS +.BR io_setup () +is not implemented on this architecture. +.SH VERSIONS +glibc does not provide a wrapper for this system call. +You could invoke it using +.BR syscall (2). +But instead, you probably want to use the +.BR io_setup () +wrapper function provided by +.\" http://git.fedorahosted.org/git/?p=libaio.git +.IR libaio . +.P +Note that the +.I libaio +wrapper function uses a different type +.RI ( "io_context_t\ *" ) +.\" But glibc is confused, since uses 'io_context_t' to declare +.\" the system call. +for the +.I ctx_idp +argument. +Note also that the +.I libaio +wrapper does not follow the usual C library conventions for indicating errors: +on error it returns a negated error number +(the negative of one of the values listed in ERRORS). +If the system call is invoked via +.BR syscall (2), +then the return value follows the usual conventions for +indicating an error: \-1, with +.I errno +set to a (positive) value that indicates the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5. +.SH SEE ALSO +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_getevents (2), +.BR io_submit (2), +.BR aio (7) +.\" .SH AUTHOR +.\" Kent Yoder. diff --git a/man/man2/io_submit.2 b/man/man2/io_submit.2 new file mode 100644 index 0000000..cf41297 --- /dev/null +++ b/man/man2/io_submit.2 @@ -0,0 +1,289 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" and Copyright (C) 2017 Goldwyn Rodrigues +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH io_submit 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +io_submit \- submit asynchronous I/O blocks for processing +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.P +Alternatively, Asynchronous I/O library +.RI ( libaio ", " \-laio ); +see VERSIONS. +.SH SYNOPSIS +.nf +.BR "#include " " /* Defines needed types */" +.P +.BI "int io_submit(aio_context_t " ctx_id ", long " nr \ +", struct iocb **" iocbpp ); +.fi +.P +.IR Note : +There is no glibc wrapper for this system call; see VERSIONS. +.SH DESCRIPTION +.IR Note : +this page describes the raw Linux system call interface. +The wrapper function provided by +.I libaio +uses a different type for the +.I ctx_id +argument. +See VERSIONS. +.P +The +.BR io_submit () +system call +queues \fInr\fP I/O request blocks for processing in +the AIO context \fIctx_id\fP. +The +.I iocbpp +argument should be an array of \fInr\fP AIO control blocks, +which will be submitted to context \fIctx_id\fP. +.P +The +.I iocb +(I/O control block) structure defined in +.I linux/aio_abi.h +defines the parameters that control the I/O operation. +.P +.in +4n +.EX +#include +\& +struct iocb { + __u64 aio_data; + __u32 PADDED(aio_key, aio_rw_flags); + __u16 aio_lio_opcode; + __s16 aio_reqprio; + __u32 aio_fildes; + __u64 aio_buf; + __u64 aio_nbytes; + __s64 aio_offset; + __u64 aio_reserved2; + __u32 aio_flags; + __u32 aio_resfd; +}; +.EE +.in +.P +The fields of this structure are as follows: +.TP +.I aio_data +This data is copied into the +.I data +field of the +.I io_event +structure upon I/O completion (see +.BR io_getevents (2)). +.TP +.I aio_key +This is an internal field used by the kernel. +Do not modify this field after an +.BR io_submit () +call. +.TP +.I aio_rw_flags +This defines the R/W flags passed with structure. +The valid values are: +.RS +.TP +.BR RWF_APPEND " (since Linux 4.16)" +.\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb +Append data to the end of the file. +See the description of the flag of the same name in +.BR pwritev2 (2) +as well as the description of +.B O_APPEND +in +.BR open (2). +The +.I aio_offset +field is ignored. +The file offset is not changed. +.TP +.BR RWF_DSYNC " (since Linux 4.13)" +Write operation complete according to requirement of +synchronized I/O data integrity. +See the description of the flag of the same name in +.BR pwritev2 (2) +as well the description of +.B O_DSYNC +in +.BR open (2). +.TP +.BR RWF_HIPRI " (since Linux 4.13)" +High priority request, poll if possible +.TP +.BR RWF_NOWAIT " (since Linux 4.14)" +Don't wait if the I/O will block for operations such as +file block allocations, dirty page flush, mutex locks, +or a congested block device inside the kernel. +If any of these conditions are met, the control block is returned +immediately with a return value of +.B \-EAGAIN +in the +.I res +field of the +.I io_event +structure (see +.BR io_getevents (2)). +.TP +.BR RWF_SYNC " (since Linux 4.13)" +Write operation complete according to requirement of +synchronized I/O file integrity. +See the description of the flag of the same name in +.BR pwritev2 (2) +as well the description of +.B O_SYNC +in +.BR open (2). +.RE +.TP +.I aio_lio_opcode +This defines the type of I/O to be performed by the +.I iocb +structure. +The +valid values are defined by the enum defined in +.IR linux/aio_abi.h : +.IP +.in +4n +.EX +enum { + IOCB_CMD_PREAD = 0, + IOCB_CMD_PWRITE = 1, + IOCB_CMD_FSYNC = 2, + IOCB_CMD_FDSYNC = 3, + IOCB_CMD_POLL = 5, + IOCB_CMD_NOOP = 6, + IOCB_CMD_PREADV = 7, + IOCB_CMD_PWRITEV = 8, +}; +.EE +.in +.TP +.I aio_reqprio +This defines the requests priority. +.TP +.I aio_fildes +The file descriptor on which the I/O operation is to be performed. +.TP +.I aio_buf +This is the buffer used to transfer data for a read or write operation. +.TP +.I aio_nbytes +This is the size of the buffer pointed to by +.IR aio_buf . +.TP +.I aio_offset +This is the file offset at which the I/O operation is to be performed. +.TP +.I aio_flags +This is the set of flags associated with the +.I iocb +structure. +The valid values are: +.RS +.TP +.B IOCB_FLAG_RESFD +Asynchronous I/O control must signal the file +descriptor mentioned in +.I aio_resfd +upon completion. +.TP +.BR IOCB_FLAG_IOPRIO " (since Linux 4.18)" +.\" commit d9a08a9e616beeccdbd0e7262b7225ffdfa49e92 +Interpret the +.I aio_reqprio +field as an +.B IOPRIO_VALUE +as defined by +.IR linux/ioprio.h . +.RE +.TP +.I aio_resfd +The file descriptor to signal in the event of asynchronous I/O completion. +.SH RETURN VALUE +On success, +.BR io_submit () +returns the number of \fIiocb\fPs submitted (which may be +less than \fInr\fP, or 0 if \fInr\fP is zero). +For the failure return, see VERSIONS. +.SH ERRORS +.TP +.B EAGAIN +Insufficient resources are available to queue any \fIiocb\fPs. +.TP +.B EBADF +The file descriptor specified in the first \fIiocb\fP is invalid. +.TP +.B EFAULT +One of the data structures points to invalid data. +.TP +.B EINVAL +The AIO context specified by \fIctx_id\fP is invalid. +\fInr\fP is less than 0. +The \fIiocb\fP at +.I *iocbpp[0] +is not properly initialized, the operation specified is invalid for the file +descriptor in the \fIiocb\fP, or the value in the +.I aio_reqprio +field is invalid. +.TP +.B ENOSYS +.BR io_submit () +is not implemented on this architecture. +.TP +.B EPERM +The +.I aio_reqprio +field is set with the class +.BR IOPRIO_CLASS_RT , +but the submitting context does not have the +.B CAP_SYS_ADMIN +capability. +.SH VERSIONS +glibc does not provide a wrapper for this system call. +You could invoke it using +.BR syscall (2). +But instead, you probably want to use the +.BR io_submit () +wrapper function provided by +.\" http://git.fedorahosted.org/git/?p=libaio.git +.IR libaio . +.P +Note that the +.I libaio +wrapper function uses a different type +.RI ( io_context_t ) +.\" But glibc is confused, since uses 'io_context_t' to declare +.\" the system call. +for the +.I ctx_id +argument. +Note also that the +.I libaio +wrapper does not follow the usual C library conventions for indicating errors: +on error it returns a negated error number +(the negative of one of the values listed in ERRORS). +If the system call is invoked via +.BR syscall (2), +then the return value follows the usual conventions for +indicating an error: \-1, with +.I errno +set to a (positive) value that indicates the error. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5. +.SH SEE ALSO +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_getevents (2), +.BR io_setup (2), +.BR aio (7) +.\" .SH AUTHOR +.\" Kent Yoder. diff --git a/man/man2/ioctl.2 b/man/man2/ioctl.2 new file mode 100644 index 0000000..705f5db --- /dev/null +++ b/man/man2/ioctl.2 @@ -0,0 +1,231 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)ioctl.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1999-06-25 by Rachael Munns +.\" Modified 2000-09-21 by Andries Brouwer +.\" +.TH ioctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl \- control device +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int ioctl(int " fd ", unsigned long " op ", ...);" "\f[R] /* glibc, BSD */\f[]" +.BI "int ioctl(int " fd ", int " op ", ...);" "\f[R] /* musl, other UNIX */\f[]" +.fi +.SH DESCRIPTION +The +.BR ioctl () +system call manipulates the underlying device parameters of special files. +In particular, many operating characteristics of character special files +(e.g., terminals) may be controlled with +.BR ioctl () +operations. +The argument +.I fd +must be an open file descriptor. +.P +The second argument is a device-dependent operation code. +The third argument is an untyped pointer to memory. +It's traditionally +.BI "char *" argp +(from the days before +.B "void *" +was valid C), and will be so named for this discussion. +.P +An +.BR ioctl () +.I op +has encoded in it whether the argument is an +.I in +parameter or +.I out +parameter, and the size of the argument +.I argp +in bytes. +Macros and defines used in specifying an +.BR ioctl () +.I op +are located in the file +.IR . +See NOTES. +.SH RETURN VALUE +Usually, on success zero is returned. +A few +.BR ioctl () +operations use the return value as an output parameter +and return a nonnegative value on success. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EFAULT +.I argp +references an inaccessible memory area. +.TP +.B EINVAL +.I op +or +.I argp +is not valid. +.TP +.B ENOTTY +.I fd +is not associated with a character special device. +.TP +.B ENOTTY +The specified operation does not apply to the kind of object that the +file descriptor +.I fd +references. +.SH VERSIONS +Arguments, returns, and semantics of +.BR ioctl () +vary according to the device driver in question (the call is used as a +catch-all for operations that don't cleanly fit the UNIX stream I/O +model). +.SH STANDARDS +None. +.SH HISTORY +Version\~7 AT&T UNIX has +.PD 0 +.in +4n +.nf +.BI "ioctl(int " fildes ", int " op ", struct sgttyb *" argp ); +.fi +.in +.P +.PD +(where +.B struct sgttyb +has historically been used by +.BR stty (2) +and +.BR gtty (2), +and is polymorphic by operation type (like a +.B void * +would be, if it had been available)). +.P +SysIII documents +.I arg +without a type at all. +.P +4.3BSD has +.PD 0 +.in +4n +.nf +.BI "ioctl(int " d ", unsigned long " op ", char *" argp ); +.fi +.in +.P +.PD +(with +.B char * +similarly in for +.BR "void *" ). +.P +SysVr4 has +.PD 0 +.in +4n +.nf +.BI "int ioctl(int " fildes ", int " op ", ... /* " arg " */);" +.fi +.in +.P +.PD +.SH NOTES +In order to use this call, one needs an open file descriptor. +Often the +.BR open (2) +call has unwanted side effects, that can be avoided under Linux +by giving it the +.B O_NONBLOCK +flag. +.\" +.SS ioctl structure +.\" added two sections - aeb +Ioctl +.I op +values are 32-bit constants. +In principle these constants are completely arbitrary, but people have +tried to build some structure into them. +.P +The old Linux situation was that of mostly 16-bit constants, where the +last byte is a serial number, and the preceding byte(s) give a type +indicating the driver. +Sometimes the major number was used: 0x03 +for the +.B HDIO_* +ioctls, 0x06 for the +.B LP* +ioctls. +And sometimes +one or more ASCII letters were used. +For example, +.B TCGETS +has value +0x00005401, with 0x54 = \[aq]T\[aq] indicating the terminal driver, and +.B CYGETTIMEOUT +has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq] +indicating the cyclades driver. +.P +Later (0.98p5) some more information was built into the number. +One has 2 direction bits +(00: none, 01: write, 10: read, 11: read/write) +followed by 14 size bits (giving the size of the argument), +followed by an 8-bit type (collecting the ioctls in groups +for a common purpose or a common driver), and an 8-bit +serial number. +.P +The macros describing this structure live in +.I +and are +.B _IO(type,nr) +and +.BR "{_IOR,_IOW,_IOWR}(type,nr,size)" . +They use +.I sizeof(size) +so that size is a +misnomer here: this third argument is a data type. +.P +Note that the size bits are very unreliable: in lots of cases +they are wrong, either because of buggy macros using +.IR sizeof(sizeof(struct)) , +or because of legacy values. +.P +Thus, it seems that the new structure only gave disadvantages: +it does not help in checking, but it causes varying values +for the various architectures. +.SH SEE ALSO +.BR execve (2), +.BR fcntl (2), +.BR ioctl_console (2), +.BR ioctl_fat (2), +.BR ioctl_ficlone (2), +.BR ioctl_ficlonerange (2), +.BR ioctl_fideduperange (2), +.BR ioctl_fslabel (2), +.BR ioctl_getfsmap (2), +.BR ioctl_iflags (2), +.BR ioctl_ns (2), +.BR ioctl_tty (2), +.BR ioctl_userfaultfd (2), +.BR open (2), +.\" .BR mt (4), +.BR sd (4), +.BR tty (4) diff --git a/man/man2/ioctl_console.2 b/man/man2/ioctl_console.2 new file mode 100644 index 0000000..e3e6a08 --- /dev/null +++ b/man/man2/ioctl_console.2 @@ -0,0 +1,915 @@ +'\" t +.\" Copyright (c) 1995 Jim Van Zandt and aeb +.\" Sun Feb 26 11:46:23 MET 1995 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, Sun Feb 26 15:04:20 1995, faith@cs.unc.edu +.\" Modified, Thu Apr 20 22:08:17 1995, jrv@vanzandt.mv.com +.\" Modified, Mon Sep 18 22:32:47 1995, hpa@storm.net (H. Peter Anvin) +.\" FIXME The following are not documented: +.\" KDFONTOP (since Linux 2.1.111) +.\" KDGKBDIACRUC (since Linux 2.6.24) +.\" KDSKBDIACR +.\" KDSKBDIACRUC (since Linux 2.6.24) +.\" KDKBDREP (since Linux 2.1.113) +.\" KDMAPDISP (not implemented as at Linux 2.6.27) +.\" KDUNMAPDISP (not implemented as at Linux 2.6.27) +.\" VT_LOCKSWITCH (since Linux 1.3.47, needs CAP_SYS_TTY_CONFIG) +.\" VT_UNLOCKSWITCH (since Linux 1.3.47, needs CAP_SYS_TTY_CONFIG) +.\" VT_GETHIFONTMASK (since Linux 2.6.18) +.\" +.TH ioctl_console 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_console \- ioctls for console terminal and virtual consoles +.SH DESCRIPTION +The following Linux-specific +.BR ioctl (2) +operations are supported for console terminals and virtual consoles. +Each operation requires a third argument, assumed here to be +.IR argp . +.TP +.B KDGETLED +Get state of LEDs. +.I argp +points to a +.IR char . +The lower three bits +of +.I *argp +are set to the state of the LEDs, as follows: +.TS +l l l. +LED_CAP 0x04 caps lock led +LED_NUM 0x02 num lock led +LED_SCR 0x01 scroll lock led +.TE +.TP +.B KDSETLED +Set the LEDs. +The LEDs are set to correspond to the lower three bits of the +unsigned long integer in +.IR argp . +However, if a higher order bit is set, +the LEDs revert to normal: displaying the state of the +keyboard functions of caps lock, num lock, and scroll lock. +.P +Before Linux 1.1.54, the LEDs just reflected the state of the corresponding +keyboard flags, and KDGETLED/KDSETLED would also change the keyboard +flags. +Since Linux 1.1.54 the LEDs can be made to display arbitrary +information, but by default they display the keyboard flags. +The following two ioctls are used to access the keyboard flags. +.TP +.B KDGKBLED +Get keyboard flags CapsLock, NumLock, ScrollLock (not lights). +.I argp +points to a char which is set to the flag state. +The low order three bits (mask 0x7) get the current flag state, +and the low order bits of the next nibble (mask 0x70) get +the default flag state. +(Since Linux 1.1.54.) +.TP +.B KDSKBLED +Set keyboard flags CapsLock, NumLock, ScrollLock (not lights). +.I argp +is an unsigned long integer that has the desired flag state. +The low order three bits (mask 0x7) have the flag state, +and the low order bits of the next nibble (mask 0x70) have +the default flag state. +(Since Linux 1.1.54.) +.TP +.B KDGKBTYPE +Get keyboard type. +This returns the value KB_101, defined as 0x02. +.TP +.B KDADDIO +Add I/O port as valid. +Equivalent to +.IR ioperm(arg,1,1) . +.TP +.B KDDELIO +Delete I/O port as valid. +Equivalent to +.IR ioperm(arg,1,0) . +.TP +.B KDENABIO +Enable I/O to video board. +Equivalent to +.IR "ioperm(0x3b4, 0x3df\-0x3b4+1, 1)" . +.TP +.B KDDISABIO +Disable I/O to video board. +Equivalent to +.IR "ioperm(0x3b4, 0x3df\-0x3b4+1, 0)" . +.TP +.B KDSETMODE +Set text/graphics mode. +.I argp +is an unsigned integer containing one of: +.TS +l l. +KD_TEXT 0x00 +KD_GRAPHICS 0x01 +.TE +.TP +.B KDGETMODE +Get text/graphics mode. +.I argp +points to an +.I int +which is set to one +of the values shown above for +.BR KDSETMODE . +.TP +.B KDMKTONE +Generate tone of specified length. +The lower 16 bits of the unsigned long integer in +.I argp +specify the period in clock cycles, +and the upper 16 bits give the duration in msec. +If the duration is zero, the sound is turned off. +Control returns immediately. +For example, +.I argp += (125<<16) + 0x637 would specify +the beep normally associated with a ctrl-G. +(Thus since Linux 0.99pl1; broken in Linux 2.1.49-50.) +.TP +.B KIOCSOUND +Start or stop sound generation. +The lower 16 bits of +.I argp +specify the period in clock cycles +(that is, +.I argp += 1193180/frequency). +.I argp += 0 turns sound off. +In either case, control returns immediately. +.TP +.B GIO_CMAP +Get the current default color map from kernel. +.I argp +points to +a 48-byte array. +(Since Linux 1.3.3.) +.TP +.B PIO_CMAP +Change the default text-mode color map. +.I argp +points to a +48-byte array which contains, in order, the Red, Green, and Blue +values for the 16 available screen colors: 0 is off, and 255 is full +intensity. +The default colors are, in order: black, dark red, dark +green, brown, dark blue, dark purple, dark cyan, light grey, dark +grey, bright red, bright green, yellow, bright blue, bright purple, +bright cyan, and white. +(Since Linux 1.3.3.) +.TP +.B GIO_FONT +Gets 256-character screen font in expanded form. +.I argp +points to an 8192-byte array. +Fails with error code +.B EINVAL +if the +currently loaded font is a 512-character font, or if the console is +not in text mode. +.TP +.B GIO_FONTX +Gets screen font and associated information. +.I argp +points to a +.I "struct consolefontdesc" +(see +.BR PIO_FONTX ). +On call, the +.I charcount +field should be set to the maximum number of +characters that would fit in the buffer pointed to by +.IR chardata . +On return, the +.I charcount +and +.I charheight +are filled with +the respective data for the currently loaded font, and the +.I chardata +array contains the font data if the initial value of +.I charcount +indicated enough space was available; otherwise the +buffer is untouched and +.I errno +is set to +.BR ENOMEM . +(Since Linux 1.3.1.) +.TP +.B PIO_FONT +Sets 256-character screen font. +Load font into the EGA/VGA character +generator. +.I argp +points to an 8192-byte map, with 32 bytes per +character. +Only the first +.I N +of them are used for an 8x\fIN\fP font +(0 < +.I N +<= 32). +This call also invalidates the Unicode mapping. +.TP +.B PIO_FONTX +Sets screen font and associated rendering information. +.I argp +points to a +.IP +.in +4n +.EX +struct consolefontdesc { + unsigned short charcount; /* characters in font + (256 or 512) */ + unsigned short charheight; /* scan lines per + character (1\-32) */ + char *chardata; /* font data in + expanded form */ +}; +.EE +.in +.IP +If necessary, the screen will be appropriately resized, and +.B SIGWINCH +sent to the appropriate processes. +This call also invalidates the Unicode mapping. +(Since Linux 1.3.1.) +.TP +.B PIO_FONTRESET +Resets the screen font, size, and Unicode mapping to the bootup +defaults. +.I argp +is unused, but should be set to NULL to +ensure compatibility with future versions of Linux. +(Since Linux 1.3.28.) +.TP +.B GIO_SCRNMAP +Get screen mapping from kernel. +.I argp +points to an area of size +E_TABSZ, which is loaded with the font positions used to display each +character. +This call is likely to return useless information if the +currently loaded font is more than 256 characters. +.TP +.B GIO_UNISCRNMAP +Get full Unicode screen mapping from kernel. +.I argp +points to an +area of size +.IR "E_TABSZ*sizeof(unsigned short)" , +which is loaded with the +Unicodes each character represent. +A special set of Unicodes, +starting at U+F000, are used to represent "direct to font" mappings. +(Since Linux 1.3.1.) +.TP +.B PIO_SCRNMAP +Loads the "user definable" (fourth) table in the kernel which maps +bytes into console screen symbols. +.I argp +points to an area of +size E_TABSZ. +.TP +.B PIO_UNISCRNMAP +Loads the "user definable" (fourth) table in the kernel which maps +bytes into Unicodes, which are then translated into screen symbols +according to the currently loaded Unicode-to-font map. +Special Unicodes starting at U+F000 can be used to map directly to the font +symbols. +(Since Linux 1.3.1.) +.TP +.B GIO_UNIMAP +Get Unicode-to-font mapping from kernel. +.I argp +points to a +.IP +.in +4n +.EX +struct unimapdesc { + unsigned short entry_ct; + struct unipair *entries; +}; +.EE +.in +.IP +where +.I entries +points to an array of +.IP +.in +4n +.EX +struct unipair { + unsigned short unicode; + unsigned short fontpos; +}; +.EE +.in +.IP +(Since Linux 1.1.92.) +.TP +.B PIO_UNIMAP +Put unicode-to-font mapping in kernel. +.I argp +points to a +.IR "struct unimapdesc" . +(Since Linux 1.1.92) +.TP +.B PIO_UNIMAPCLR +Clear table, possibly advise hash algorithm. +.I argp +points to a +.IP +.in +4n +.EX +struct unimapinit { + unsigned short advised_hashsize; /* 0 if no opinion */ + unsigned short advised_hashstep; /* 0 if no opinion */ + unsigned short advised_hashlevel; /* 0 if no opinion */ +}; +.EE +.in +.IP +(Since Linux 1.1.92.) +.TP +.B KDGKBMODE +Gets current keyboard mode. +.I argp +points to a +.I long +which is set to one +of these: +.TS +l l. +K_RAW 0x00 /* Raw (scancode) mode */ +K_XLATE 0x01 /* Translate keycodes using keymap */ +K_MEDIUMRAW 0x02 /* Medium raw (scancode) mode */ +K_UNICODE 0x03 /* Unicode mode */ +K_OFF 0x04 /* Disabled mode; since Linux 2.6.39 */ +.\" K_OFF: commit 9fc3de9c83565fcaa23df74c2fc414bb6e7efb0a +.TE +.TP +.B KDSKBMODE +Sets current keyboard mode. +.I argp +is a +.I long +equal to one of the values shown for +.BR KDGKBMODE . +.TP +.B KDGKBMETA +Gets meta key handling mode. +.I argp +points to a +.I long +which is +set to one of these: +.TS +l l l. +K_METABIT 0x03 set high order bit +K_ESCPREFIX 0x04 escape prefix +.TE +.TP +.B KDSKBMETA +Sets meta key handling mode. +.I argp +is a +.I long +equal to one of the values shown above for +.BR KDGKBMETA . +.TP +.B KDGKBENT +Gets one entry in key translation table (keycode to action code). +.I argp +points to a +.IP +.in +4n +.EX +struct kbentry { + unsigned char kb_table; + unsigned char kb_index; + unsigned short kb_value; +}; +.EE +.in +.IP +with the first two members filled in: +.I kb_table +selects the key table (0 <= +.I kb_table +< MAX_NR_KEYMAPS), +and +.I kb_index +is the keycode (0 <= +.I kb_index +< NR_KEYS). +.I kb_value +is set to the corresponding action code, +or K_HOLE if there is no such key, +or K_NOSUCHMAP if +.I kb_table +is invalid. +.TP +.B KDSKBENT +Sets one entry in translation table. +.I argp +points to a +.IR "struct kbentry" . +.TP +.B KDGKBSENT +Gets one function key string. +.I argp +points to a +.IP +.in +4n +.EX +struct kbsentry { + unsigned char kb_func; + unsigned char kb_string[512]; +}; +.EE +.in +.IP +.I kb_string +is set to the (null-terminated) string corresponding to +the +.IR kb_func th +function key action code. +.TP +.B KDSKBSENT +Sets one function key string entry. +.I argp +points to a +.IR "struct kbsentry" . +.TP +.B KDGKBDIACR +Read kernel accent table. +.I argp +points to a +.IP +.in +4n +.EX +struct kbdiacrs { + unsigned int kb_cnt; + struct kbdiacr kbdiacr[256]; +}; +.EE +.in +.IP +where +.I kb_cnt +is the number of entries in the array, each of which +is a +.IP +.in +4n +.EX +struct kbdiacr { + unsigned char diacr; + unsigned char base; + unsigned char result; +}; +.EE +.in +.TP +.B KDGETKEYCODE +Read kernel keycode table entry (scan code to keycode). +.I argp +points to a +.IP +.in +4n +.EX +struct kbkeycode { + unsigned int scancode; + unsigned int keycode; +}; +.EE +.in +.IP +.I keycode +is set to correspond to the given +.IR scancode . +(89 <= +.I scancode +<= 255 only. +For 1 <= +.I scancode +<= 88, +.IR keycode == scancode .) +(Since Linux 1.1.63.) +.TP +.B KDSETKEYCODE +Write kernel keycode table entry. +.I argp +points to a +.IR "struct kbkeycode" . +(Since Linux 1.1.63.) +.TP +.B KDSIGACCEPT +The calling process indicates its willingness to accept the signal +.I argp +when it is generated by pressing an appropriate key combination. +(1 <= +.I argp +<= NSIG). +(See +.IR spawn_console () +in +.IR linux/drivers/char/keyboard.c .) +.TP +.B VT_OPENQRY +Returns the first available (non-opened) console. +.I argp +points to an +.I int +which is set to the +number of the vt (1 <= +.I *argp +<= MAX_NR_CONSOLES). +.TP +.B VT_GETMODE +Get mode of active vt. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_mode { + char mode; /* vt mode */ + char waitv; /* if set, hang on writes if not active */ + short relsig; /* signal to raise on release op */ + short acqsig; /* signal to raise on acquisition */ + short frsig; /* unused (set to 0) */ +}; +.EE +.in +.IP +which is set to the mode of the active vt. +.I mode +is set to one of these values: +.TS +l l. +VT_AUTO auto vt switching +VT_PROCESS process controls switching +VT_ACKACQ acknowledge switch +.TE +.TP +.B VT_SETMODE +Set mode of active vt. +.I argp +points to a +.IR "struct vt_mode" . +.TP +.B VT_GETSTATE +Get global vt state info. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_stat { + unsigned short v_active; /* active vt */ + unsigned short v_signal; /* signal to send */ + unsigned short v_state; /* vt bit mask */ +}; +.EE +.in +.IP +For each vt in use, the corresponding bit in the +.I v_state +member is set. +(Linux 1.0 through Linux 1.1.92.) +.TP +.B VT_RELDISP +Release a display. +.TP +.B VT_ACTIVATE +Switch to vt +.I argp +(1 <= +.I argp +<= MAX_NR_CONSOLES). +.TP +.B VT_WAITACTIVE +Wait until vt +.I argp +has been activated. +.TP +.B VT_DISALLOCATE +Deallocate the memory associated with vt +.IR argp . +(Since Linux 1.1.54.) +.TP +.B VT_RESIZE +Set the kernel's idea of screensize. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_sizes { + unsigned short v_rows; /* # rows */ + unsigned short v_cols; /* # columns */ + unsigned short v_scrollsize; /* no longer used */ +}; +.EE +.in +.IP +Note that this does not change the videomode. +See +.BR resizecons (8). +(Since Linux 1.1.54.) +.TP +.B VT_RESIZEX +Set the kernel's idea of various screen parameters. +.I argp +points to a +.IP +.in +4n +.EX +struct vt_consize { + unsigned short v_rows; /* number of rows */ + unsigned short v_cols; /* number of columns */ + unsigned short v_vlin; /* number of pixel rows + on screen */ + unsigned short v_clin; /* number of pixel rows + per character */ + unsigned short v_vcol; /* number of pixel columns + on screen */ + unsigned short v_ccol; /* number of pixel columns + per character */ +}; +.EE +.in +.IP +Any parameter may be set to zero, indicating "no change", but if +multiple parameters are set, they must be self-consistent. +Note that this does not change the videomode. +See +.BR resizecons (8). +(Since Linux 1.3.3.) +.P +The action of the following ioctls depends on the first byte in the struct +pointed to by +.IR argp , +referred to here as the +.IR subcode . +These are legal only for the superuser or the owner of the current terminal. +Symbolic +.IR subcode s +are available in +.I +since +Linux 2.5.71. +.TP +.BR TIOCLINUX ", " subcode = 0 +Dump the screen. +Disappeared in Linux 1.1.92. +(With Linux 1.1.92 or later, read from +.I /dev/vcsN +or +.I /dev/vcsaN +instead.) +.TP +.BR TIOCLINUX ", " subcode = 1 +Get task information. +Disappeared in Linux 1.1.92. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_SETSEL +Set selection. +.I argp +points to a +.IP +.in +4n +.EX +struct { + char subcode; + short xs, ys, xe, ye; + short sel_mode; +}; +.EE +.in +.IP +.I xs +and +.I ys +are the starting column and row. +.I xe +and +.I ye +are the ending +column and row. +(Upper left corner is row=column=1.) +.I sel_mode +is 0 for character-by-character selection, +1 for word-by-word selection, +or 2 for line-by-line selection. +The indicated screen characters are highlighted and saved +in a kernel buffer. +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_PASTESEL +Paste selection. +The characters in the selection buffer are +written to +.IR fd . +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_UNBLANKSCREEN +Unblank the screen. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_SELLOADLUT +Sets contents of a 256-bit look up table defining characters in a "word", +for word-by-word selection. +(Since Linux 1.1.32.) +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_GETSHIFTSTATE +.I argp +points to a char which is set to the value of the kernel +variable +.IR shift_state . +(Since Linux 1.1.32.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_GETMOUSEREPORTING +.I argp +points to a char which is set to the value of the kernel +variable +.IR report_mouse . +(Since Linux 1.1.33.) +.TP +.BR TIOCLINUX ", " subcode = 8 +Dump screen width and height, cursor position, and all the +character-attribute pairs. +(Linux 1.1.67 through Linux 1.1.91 only. +With Linux 1.1.92 or later, read from +.I /dev/vcsa* +instead.) +.TP +.BR TIOCLINUX ", " subcode = 9 +Restore screen width and height, cursor position, and all the +character-attribute pairs. +(Linux 1.1.67 through Linux 1.1.91 only. +With Linux 1.1.92 or later, write to +.I /dev/vcsa* +instead.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_SETVESABLANK +Handles the Power Saving +feature of the new generation of monitors. +VESA screen blanking mode is set to +.IR argp[1] , +which governs what +screen blanking does: +.RS +.TP +.B 0 +Screen blanking is disabled. +.TP +.B 1 +The current video adapter +register settings are saved, then the controller is programmed to turn off +the vertical synchronization pulses. +This puts the monitor into "standby" mode. +If your monitor has an Off_Mode timer, then +it will eventually power down by itself. +.TP +.B 2 +The current settings are saved, then both the vertical and horizontal +synchronization pulses are turned off. +This puts the monitor into "off" mode. +If your monitor has no Off_Mode timer, +or if you want your monitor to power down immediately when the +blank_timer times out, then you choose this option. +.RI ( Caution: +Powering down frequently will damage the monitor.) +(Since Linux 1.1.76.) +.RE +.TP +.BR TIOCLINUX ", " subcode = TIOCL_SETKMSGREDIRECT +Change target of kernel messages ("console"): +by default, and if this is set to +.BR 0 , +messages are written to the currently active VT. +The VT to write to is a single byte following +.BR subcode . +(Since Linux 2.5.36.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_GETFGCONSOLE +Returns the number of VT currently in foreground. +(Since Linux 2.5.36.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_SCROLLCONSOLE +Scroll the foreground VT by the specified amount of +.I lines +down, +or half the screen if +.BR 0 . +.I lines +is *(((int32_t *)&subcode) + 1). +(Since Linux 2.5.67.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_BLANKSCREEN +Blank the foreground VT, ignoring "pokes" (typing): +can only be unblanked explicitly (by switching VTs, to text mode, etc.). +(Since Linux 2.5.71.) +.TP +.BR TIOCLINUX ", " subcode = TIOCL_BLANKEDSCREEN +Returns the number of VT currently blanked, +.B 0 +if none. +(Since Linux 2.5.71.) +.TP +.BR TIOCLINUX ", " subcode = 16 +Never used. +.TP +.BR TIOCLINUX ", " subcode = TIOCL_GETKMSGREDIRECT +Returns target of kernel messages. +(Since Linux 2.6.17.) +.SH RETURN VALUE +On success, 0 is returned (except where indicated). +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The file descriptor is invalid. +.TP +.B EINVAL +The file descriptor or +.I argp +is invalid. +.TP +.B ENOTTY +The file descriptor is not associated with a character special device, +or the specified operation does not apply to it. +.TP +.B EPERM +Insufficient permission. +.SH NOTES +.BR Warning : +Do not regard this man page as documentation of the Linux console ioctls. +This is provided for the curious only, as an alternative to reading the +source. +Ioctl's are undocumented Linux internals, liable to be changed +without warning. +(And indeed, this page more or less describes the +situation as of kernel version 1.1.94; +there are many minor and not-so-minor +differences with earlier versions.) +.P +Very often, ioctls are introduced for communication between the +kernel and one particular well-known program (fdisk, hdparm, setserial, +tunelp, loadkeys, selection, setfont, etc.), and their behavior will be +changed when required by this particular program. +.P +Programs using these ioctls will not be portable to other versions +of UNIX, will not work on older versions of Linux, and will not work +on future versions of Linux. +.P +Use POSIX functions. +.SH SEE ALSO +.BR dumpkeys (1), +.BR kbd_mode (1), +.BR loadkeys (1), +.BR mknod (1), +.BR setleds (1), +.BR setmetamode (1), +.BR execve (2), +.BR fcntl (2), +.BR ioctl_tty (2), +.BR ioperm (2), +.BR termios (3), +.BR console_codes (4), +.BR mt (4), +.BR sd (4), +.BR tty (4), +.BR ttyS (4), +.BR vcs (4), +.BR vcsa (4), +.BR charsets (7), +.BR mapscrn (8), +.BR resizecons (8), +.BR setfont (8) +.P +.IR /usr/include/linux/kd.h , +.I /usr/include/linux/vt.h diff --git a/man/man2/ioctl_fat.2 b/man/man2/ioctl_fat.2 new file mode 100644 index 0000000..57b0e6f --- /dev/null +++ b/man/man2/ioctl_fat.2 @@ -0,0 +1,489 @@ +.\" Copyright (C) 2014, Heinrich Schuchardt +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH ioctl_fat 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_fat \- manipulating the FAT filesystem +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of [" V ] FAT_* " and" +.BR " ATTR_* " constants */" +.B #include +.P +.BI "int ioctl(int " fd ", FAT_IOCTL_GET_ATTRIBUTES, uint32_t *" attr ); +.BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t *" attr ); +.BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t *" id ); +.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_BOTH," +.BI " struct __fat_dirent " entry [2]); +.BI "int ioctl(int " fd ", VFAT_IOCTL_READDIR_SHORT," +.BI " struct __fat_dirent " entry [2]); +.fi +.SH DESCRIPTION +The +.BR ioctl (2) +system call can be used to read and write metadata of FAT filesystems that +are not accessible using other system calls. +.SS Reading and setting file attributes +Files and directories in the FAT filesystem possess an attribute bit mask that +can be read with +.B FAT_IOCTL_GET_ATTRIBUTES +and written with +.BR FAT_IOCTL_SET_ATTRIBUTES . +.P +The +.I fd +argument contains a file descriptor for a file or directory. +It is sufficient to create the file descriptor by calling +.BR open (2) +with the +.B O_RDONLY +flag. +.P +The +.I attr +argument contains a pointer to a bit mask. +The bits of the bit mask are: +.TP +.B ATTR_RO +This bit specifies that the file or directory is read-only. +.TP +.B ATTR_HIDDEN +This bit specifies that the file or directory is hidden. +.TP +.B ATTR_SYS +This bit specifies that the file is a system file. +.TP +.B ATTR_VOLUME +This bit specifies that the file is a volume label. +This attribute is read-only. +.TP +.B ATTR_DIR +This bit specifies that this is a directory. +This attribute is read-only. +.TP +.B ATTR_ARCH +This bit indicates that this file or directory should be archived. +It is set when a file is created or modified. +It is reset by an archiving system. +.P +The zero value +.B ATTR_NONE +can be used to indicate that no attribute bit is set. +.SS Reading the volume ID +FAT filesystems are identified by a volume ID. +The volume ID can be read with +.BR FAT_IOCTL_GET_VOLUME_ID . +.P +The +.I fd +argument can be a file descriptor for any file or directory of the +filesystem. +It is sufficient to create the file descriptor by calling +.BR open (2) +with the +.B O_RDONLY +flag. +.P +The +.I id +argument is a pointer to the field that will be filled with the volume ID. +Typically the volume ID is displayed to the user as a group of two +16-bit fields: +.P +.in +4n +.EX +printf("Volume ID %04x\-%04x\en", id >> 16, id & 0xFFFF); +.EE +.in +.SS Reading short filenames of a directory +A file or directory on a FAT filesystem always has a short filename +consisting of up to 8 capital letters, optionally followed by a period +and up to 3 capital letters for the file extension. +If the actual filename does not fit into this scheme, it is stored +as a long filename of up to 255 UTF-16 characters. +.P +The short filenames in a directory can be read with +.BR VFAT_IOCTL_READDIR_SHORT . +.B VFAT_IOCTL_READDIR_BOTH +reads both the short and the long filenames. +.P +The +.I fd +argument must be a file descriptor for a directory. +It is sufficient to create the file descriptor by calling +.BR open (2) +with the +.B O_RDONLY +flag. +The file descriptor can be used only once to iterate over the directory +entries by calling +.BR ioctl (2) +repeatedly. +.P +The +.I entry +argument is a two-element array of the following structures: +.P +.in +4n +.EX +struct __fat_dirent { + long d_ino; + __kernel_off_t d_off; + uint32_t short d_reclen; + char d_name[256]; +}; +.EE +.in +.P +The first entry in the array is for the short filename. +The second entry is for the long filename. +.P +The +.I d_ino +and +.I d_off +fields are filled only for long filenames. +The +.I d_ino +field holds the inode number of the directory. +The +.I d_off +field holds the offset of the file entry in the directory. +As these values are not available for short filenames, the user code should +simply ignore them. +.P +The field +.I d_reclen +contains the length of the filename in the field +.IR d_name . +To keep backward compatibility, a length of 0 for the short filename signals +that the end of the directory has been reached. +However, the preferred method for detecting the end of the directory +is to test the +.BR ioctl (2) +return value. +If no long filename exists, field +.I d_reclen +is set to 0 and +.I d_name +is a character string of length 0 for the long filename. +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +For +.B VFAT_IOCTL_READDIR_BOTH +and +.B VFAT_IOCTL_READDIR_SHORT +a return value of 1 signals that a new directory entry has been read and +a return value of 0 signals that the end of the directory has been reached. +.SH ERRORS +.TP +.B ENOENT +This error is returned by +.B VFAT_IOCTL_READDIR_BOTH +and +.B VFAT_IOCTL_READDIR_SHORT +if the file descriptor +.I fd +refers to a removed, but still open directory. +.TP +.B ENOTDIR +This error is returned by +.B VFAT_IOCTL_READDIR_BOTH +and +.B VFAT_IOCTL_READDIR_SHORT +if the file descriptor +.I fd +does not refer to a directory. +.TP +.B ENOTTY +The file descriptor +.I fd +does not refer to an object in a FAT filesystem. +.P +For further error values, see +.BR ioctl (2). +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.B VFAT_IOCTL_READDIR_BOTH +.TQ +.B VFAT_IOCTL_READDIR_SHORT +Linux 2.0. +.TP +.B FAT_IOCTL_GET_ATTRIBUTES +.TQ +.B FAT_IOCTL_SET_ATTRIBUTES +.\" just before we got Git history +Linux 2.6.12. +.TP +.B FAT_IOCTL_GET_VOLUME_ID +Linux 3.11. +.\" commit 6e5b93ee55d401f1619092fb675b57c28c9ed7ec +.SH EXAMPLES +.SS Toggling the archive flag +The following program demonstrates the usage of +.BR ioctl (2) +to manipulate file attributes. +The program reads and displays the archive attribute of a file. +After inverting the value of the attribute, +the program reads and displays the attribute again. +.P +The following was recorded when applying the program for the file +.IR /mnt/user/foo : +.P +.in +4n +.EX +# ./toggle_fat_archive_flag /mnt/user/foo +Archive flag is set +Toggling archive flag +Archive flag is not set +.EE +.in +.SS Program source (toggle_fat_archive_flag.c) +\& +.\" SRC BEGIN (toggle_fat_archive_flag.c) +.EX +#include +#include +#include +#include +#include +#include +#include +\& +/* + * Read file attributes of a file on a FAT filesystem. + * Output the state of the archive flag. + */ +static uint32_t +readattr(int fd) +{ + int ret; + uint32_t attr; +\& + ret = ioctl(fd, FAT_IOCTL_GET_ATTRIBUTES, &attr); + if (ret == \-1) { + perror("ioctl"); + exit(EXIT_FAILURE); + } +\& + if (attr & ATTR_ARCH) + printf("Archive flag is set\en"); + else + printf("Archive flag is not set\en"); +\& + return attr; +} +\& +int +main(int argc, char *argv[]) +{ + int fd; + int ret; + uint32_t attr; +\& + if (argc != 2) { + printf("Usage: %s FILENAME\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + fd = open(argv[1], O_RDONLY); + if (fd == \-1) { + perror("open"); + exit(EXIT_FAILURE); + } +\& + /* + * Read and display the FAT file attributes. + */ + attr = readattr(fd); +\& + /* + * Invert archive attribute. + */ + printf("Toggling archive flag\en"); + attr \[ha]= ATTR_ARCH; +\& + /* + * Write the changed FAT file attributes. + */ + ret = ioctl(fd, FAT_IOCTL_SET_ATTRIBUTES, &attr); + if (ret == \-1) { + perror("ioctl"); + exit(EXIT_FAILURE); + } +\& + /* + * Read and display the FAT file attributes. + */ + readattr(fd); +\& + close(fd); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS Reading the volume ID +The following program demonstrates the use of +.BR ioctl (2) +to display the volume ID of a FAT filesystem. +.P +The following output was recorded when applying the program for +directory +.IR /mnt/user : +.P +.in +4n +.EX +$ ./display_fat_volume_id /mnt/user +Volume ID 6443\-6241 +.EE +.in +.SS Program source (display_fat_volume_id.c) +\& +.\" SRC BEGIN (display_fat_volume_id.c) +.EX +#include +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int fd; + int ret; + uint32_t id; +\& + if (argc != 2) { + printf("Usage: %s FILENAME\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + fd = open(argv[1], O_RDONLY); + if (fd == \-1) { + perror("open"); + exit(EXIT_FAILURE); + } +\& + /* + * Read volume ID. + */ + ret = ioctl(fd, FAT_IOCTL_GET_VOLUME_ID, &id); + if (ret == \-1) { + perror("ioctl"); + exit(EXIT_FAILURE); + } +\& + /* + * Format the output as two groups of 16 bits each. + */ + printf("Volume ID %04x\-%04x\en", id >> 16, id & 0xFFFF); +\& + close(fd); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS Listing a directory +The following program demonstrates the use of +.BR ioctl (2) +to list a directory. +.P +The following was recorded when applying the program to the directory +.IR /mnt/user : +.P +.in +4n +.EX +$ \fB./fat_dir /mnt/user\fP +\&. \-> \[aq]\[aq] +\&.. \-> \[aq]\[aq] +ALONGF\[ti]1.TXT \-> \[aq]a long filename.txt\[aq] +UPPER.TXT \-> \[aq]\[aq] +LOWER.TXT \-> \[aq]lower.txt\[aq] +.EE +.in +.\" +.SS Program source +.in +4n +.\" SRC BEGIN (ioctl_fat.c) +.EX +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int fd; + int ret; + struct __fat_dirent entry[2]; +\& + if (argc != 2) { + printf("Usage: %s DIRECTORY\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* + * Open file descriptor for the directory. + */ + fd = open(argv[1], O_RDONLY | O_DIRECTORY); + if (fd == \-1) { + perror("open"); + exit(EXIT_FAILURE); + } +\& + for (;;) { +\& + /* + * Read next directory entry. + */ + ret = ioctl(fd, VFAT_IOCTL_READDIR_BOTH, entry); +\& + /* + * If an error occurs, the return value is \-1. + * If the end of the directory list has been reached, + * the return value is 0. + * For backward compatibility the end of the directory + * list is also signaled by d_reclen == 0. + */ + if (ret < 1) + break; +\& + /* + * Write both the short name and the long name. + */ + printf("%s \-> \[aq]%s\[aq]\en", entry[0].d_name, entry[1].d_name); + } +\& + if (ret == \-1) { + perror("VFAT_IOCTL_READDIR_BOTH"); + exit(EXIT_FAILURE); + } +\& + /* + * Close the file descriptor. + */ + close(fd); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR ioctl (2) diff --git a/man/man2/ioctl_ficlone.2 b/man/man2/ioctl_ficlone.2 new file mode 100644 index 0000000..19bb348 --- /dev/null +++ b/man/man2/ioctl_ficlone.2 @@ -0,0 +1 @@ +.so man2/ioctl_ficlonerange.2 diff --git a/man/man2/ioctl_ficlonerange.2 b/man/man2/ioctl_ficlonerange.2 new file mode 100644 index 0000000..0b9b154 --- /dev/null +++ b/man/man2/ioctl_ficlonerange.2 @@ -0,0 +1,129 @@ +.\" Copyright (c) 2016, Oracle. All rights reserved. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH ioctl_ficlonerange 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_ficlonerange, ioctl_ficlone \- +share some the data of one file with another file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " FICLONE* " constants */" +.B #include +.P +.BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg ); +.BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd ); +.fi +.SH DESCRIPTION +If a filesystem supports files sharing physical storage between multiple +files ("reflink"), this +.BR ioctl (2) +operation can be used to make some of the data in the +.I src_fd +file appear in the +.I dest_fd +file by sharing the underlying storage, which is faster than making a separate +physical copy of the data. +Both files must reside within the same filesystem. +If a file write should occur to a shared region, +the filesystem must ensure that the changes remain private to the file being +written. +This behavior is commonly referred to as "copy on write". +.P +This ioctl reflinks up to +.I src_length +bytes from file descriptor +.I src_fd +at offset +.I src_offset +into the file +.I dest_fd +at offset +.IR dest_offset , +provided that both are files. +If +.I src_length +is zero, the ioctl reflinks to the end of the source file. +This information is conveyed in a structure of +the following form: +.P +.in +4n +.EX +struct file_clone_range { + __s64 src_fd; + __u64 src_offset; + __u64 src_length; + __u64 dest_offset; +}; +.EE +.in +.P +Clones are atomic with regards to concurrent writes, so no locks need to be +taken to obtain a consistent cloned copy. +.P +The +.B FICLONE +ioctl clones entire files. +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Error codes can be one of, but are not limited to, the following: +.TP +.B EBADF +.I src_fd +is not open for reading; +.I dest_fd +is not open for writing or is open for append-only writes; +or the filesystem which +.I src_fd +resides on does not support reflink. +.TP +.B EINVAL +The filesystem does not support reflinking the ranges of the given files. +This error can also appear if either file descriptor represents +a device, FIFO, or socket. +Disk filesystems generally require the offset and length arguments +to be aligned to the fundamental block size. +XFS and Btrfs do not support +overlapping reflink ranges in the same file. +.TP +.B EISDIR +One of the files is a directory and the filesystem does not support shared +regions in directories. +.TP +.B EOPNOTSUPP +This can appear if the filesystem does not support reflinking either file +descriptor, or if either file descriptor refers to special inodes. +.TP +.B EPERM +.I dest_fd +is immutable. +.TP +.B ETXTBSY +One of the files is a swap file. +Swap files cannot share storage. +.TP +.B EXDEV +.IR dest_fd " and " src_fd +are not on the same mounted filesystem. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.5. +.P +They were previously known as +.B BTRFS_IOC_CLONE +and +.BR BTRFS_IOC_CLONE_RANGE , +and were private to Btrfs. +.SH NOTES +Because a copy-on-write operation requires the allocation of new storage, the +.BR fallocate (2) +operation may unshare shared blocks to guarantee that subsequent writes will +not fail because of lack of disk space. +.SH SEE ALSO +.BR ioctl (2) diff --git a/man/man2/ioctl_fideduperange.2 b/man/man2/ioctl_fideduperange.2 new file mode 100644 index 0000000..ba00ac3 --- /dev/null +++ b/man/man2/ioctl_fideduperange.2 @@ -0,0 +1,200 @@ +.\" Copyright (c) 2016, Oracle. All rights reserved. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH ioctl_fideduperange 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_fideduperange \- share some the data of one file with another file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " FIDEDUPERANGE " and" +.BR " FILE_DEDUPE_* " constants */ +.B #include +.P +.BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg ); +.fi +.SH DESCRIPTION +If a filesystem supports files sharing physical storage between multiple +files, this +.BR ioctl (2) +operation can be used to make some of the data in the +.B src_fd +file appear in the +.B dest_fd +file by sharing the underlying storage if the file data is identical +("deduplication"). +Both files must reside within the same filesystem. +This reduces storage consumption by allowing the filesystem +to store one shared copy of the data. +If a file write should occur to a shared +region, the filesystem must ensure that the changes remain private to the file +being written. +This behavior is commonly referred to as "copy on write". +.P +This ioctl performs the "compare and share if identical" operation on up to +.I src_length +bytes from file descriptor +.I src_fd +at offset +.IR src_offset . +This information is conveyed in a structure of the following form: +.P +.in +4n +.EX +struct file_dedupe_range { + __u64 src_offset; + __u64 src_length; + __u16 dest_count; + __u16 reserved1; + __u32 reserved2; + struct file_dedupe_range_info info[0]; +}; +.EE +.in +.P +Deduplication is atomic with regards to concurrent writes, so no locks need to +be taken to obtain a consistent deduplicated copy. +.P +The fields +.IR reserved1 " and " reserved2 +must be zero. +.P +Destinations for the deduplication operation are conveyed in the array at the +end of the structure. +The number of destinations is given in +.IR dest_count , +and the destination information is conveyed in the following form: +.P +.in +4n +.EX +struct file_dedupe_range_info { + __s64 dest_fd; + __u64 dest_offset; + __u64 bytes_deduped; + __s32 status; + __u32 reserved; +}; +.EE +.in +.P +Each deduplication operation targets +.I src_length +bytes in file descriptor +.I dest_fd +at offset +.IR dest_offset . +The field +.I reserved +must be zero. +During the call, +.I src_fd +must be open for reading and +.I dest_fd +must be open for writing. +The combined size of the struct +.I file_dedupe_range +and the struct +.I file_dedupe_range_info +array must not exceed the system page size. +The maximum size of +.I src_length +is filesystem dependent and is typically 16\~MiB. +This limit will be enforced silently by the filesystem. +By convention, the storage used by +.I src_fd +is mapped into +.I dest_fd +and the previous contents in +.I dest_fd +are freed. +.P +Upon successful completion of this ioctl, the number of bytes successfully +deduplicated is returned in +.I bytes_deduped +and a status code for the deduplication operation is returned in +.IR status . +If even a single byte in the range does not match, the deduplication +operation request will be ignored and +.I status +set to +.BR FILE_DEDUPE_RANGE_DIFFERS . +The +.I status +code is set to +.B FILE_DEDUPE_RANGE_SAME +for success, a negative error code in case of error, or +.B FILE_DEDUPE_RANGE_DIFFERS +if the data did not match. +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Possible errors include (but are not limited to) the following: +.TP +.B EBADF +.I src_fd +is not open for reading; +.I dest_fd +is not open for writing or is open for append-only writes; or the filesystem +which +.I src_fd +resides on does not support deduplication. +.TP +.B EINVAL +The filesystem does not support deduplicating the ranges of the given files. +This error can also appear if either file descriptor represents +a device, FIFO, or socket. +Disk filesystems generally require the offset and length arguments +to be aligned to the fundamental block size. +Neither Btrfs nor XFS support +overlapping deduplication ranges in the same file. +.TP +.B EISDIR +One of the files is a directory and the filesystem does not support shared +regions in directories. +.TP +.B ENOMEM +The kernel was unable to allocate sufficient memory to perform the +operation or +.I dest_count +is so large that the input argument description spans more than a single +page of memory. +.TP +.B EOPNOTSUPP +This can appear if the filesystem does not support deduplicating either file +descriptor, or if either file descriptor refers to special inodes. +.TP +.B EPERM +.I dest_fd +is immutable. +.TP +.B ETXTBSY +One of the files is a swap file. +Swap files cannot share storage. +.TP +.B EXDEV +.I dest_fd +and +.I src_fd +are not on the same mounted filesystem. +.SH VERSIONS +Some filesystems may limit the amount of data that can be deduplicated in a +single call. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.5. +.P +It was previously known as +.B BTRFS_IOC_FILE_EXTENT_SAME +and was private to Btrfs. +.SH NOTES +Because a copy-on-write operation requires the allocation of new storage, the +.BR fallocate (2) +operation may unshare shared blocks to guarantee that subsequent writes will +not fail because of lack of disk space. +.SH SEE ALSO +.BR ioctl (2) diff --git a/man/man2/ioctl_fslabel.2 b/man/man2/ioctl_fslabel.2 new file mode 100644 index 0000000..61a3b35 --- /dev/null +++ b/man/man2/ioctl_fslabel.2 @@ -0,0 +1,72 @@ +.\" Copyright (c) 2018, Red Hat, Inc. All rights reserved. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH ioctl_fslabel 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_fslabel \- get or set a filesystem label +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " *FSLABEL* " constants */" +.B #include +.P +.BI "int ioctl(int " fd ", FS_IOC_GETFSLABEL, char " label [FSLABEL_MAX]); +.BI "int ioctl(int " fd ", FS_IOC_SETFSLABEL, char " label [FSLABEL_MAX]); +.fi +.SH DESCRIPTION +If a filesystem supports online label manipulation, these +.BR ioctl (2) +operations can be used to get or set the filesystem label for the filesystem +on which +.I fd +resides. +The +.B FS_IOC_SETFSLABEL +operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.SH RETURN VALUE +On success zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Possible errors include (but are not limited to) the following: +.TP +.B EFAULT +.I label +references an inaccessible memory area. +.TP +.B EINVAL +The specified label exceeds the maximum label length for the filesystem. +.TP +.B ENOTTY +This can appear if the filesystem does not support online label manipulation. +.TP +.B EPERM +The calling process does not have sufficient permissions to set the label. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.18. +.P +They were previously known as +.B BTRFS_IOC_GET_FSLABEL +and +.B BTRFS_IOC_SET_FSLABEL +and were private to Btrfs. +.SH NOTES +The maximum string length for this interface is +.BR FSLABEL_MAX , +including the terminating null byte (\[aq]\\0\[aq]). +Filesystems have differing maximum label lengths, which may or +may not include the terminating null. +The string provided to +.B FS_IOC_SETFSLABEL +must always be null-terminated, and the string returned by +.B FS_IOC_GETFSLABEL +will always be null-terminated. +.SH SEE ALSO +.BR ioctl (2), +.BR blkid (8) diff --git a/man/man2/ioctl_getfsmap.2 b/man/man2/ioctl_getfsmap.2 new file mode 100644 index 0000000..e10134c --- /dev/null +++ b/man/man2/ioctl_getfsmap.2 @@ -0,0 +1,351 @@ +.\" Copyright (c) 2017, Oracle. All rights reserved. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH ioctl_getfsmap 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_getfsmap \- retrieve the physical layout of the filesystem +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " "/* Definition of " FS_IOC_GETFSMAP , +.BR " FM?_OF_*" ", and " *FMR_OWN_* " constants */" +.B #include +.P +.BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg ); +.fi +.SH DESCRIPTION +This +.BR ioctl (2) +operation retrieves physical extent mappings for a filesystem. +This information can be used to discover which files are mapped to a physical +block, examine free space, or find known bad blocks, among other things. +.P +The sole argument to this operation should be a pointer to a single +.IR "struct fsmap_head" ":" +.P +.in +4n +.EX +struct fsmap { + __u32 fmr_device; /* Device ID */ + __u32 fmr_flags; /* Mapping flags */ + __u64 fmr_physical; /* Device offset of segment */ + __u64 fmr_owner; /* Owner ID */ + __u64 fmr_offset; /* File offset of segment */ + __u64 fmr_length; /* Length of segment */ + __u64 fmr_reserved[3]; /* Must be zero */ +}; +\& +struct fsmap_head { + __u32 fmh_iflags; /* Control flags */ + __u32 fmh_oflags; /* Output flags */ + __u32 fmh_count; /* # of entries in array incl. input */ + __u32 fmh_entries; /* # of entries filled in (output) */ + __u64 fmh_reserved[6]; /* Must be zero */ +\& + struct fsmap fmh_keys[2]; /* Low and high keys for + the mapping search */ + struct fsmap fmh_recs[]; /* Returned records */ +}; +.EE +.in +.P +The two +.I fmh_keys +array elements specify the lowest and highest reverse-mapping +key for which the application would like physical mapping +information. +A reverse mapping key consists of the tuple (device, block, owner, offset). +The owner and offset fields are part of the key because some filesystems +support sharing physical blocks between multiple files and +therefore may return multiple mappings for a given physical block. +.P +Filesystem mappings are copied into the +.I fmh_recs +array, which immediately follows the header data. +.\" +.SS Fields of struct fsmap_head +The +.I fmh_iflags +field is a bit mask passed to the kernel to alter the output. +No flags are currently defined, so the caller must set this value to zero. +.P +The +.I fmh_oflags +field is a bit mask of flags set by the kernel concerning the returned mappings. +If +.B FMH_OF_DEV_T +is set, then the +.I fmr_device +field represents a +.I dev_t +structure containing the major and minor numbers of the block device. +.P +The +.I fmh_count +field contains the number of elements in the array being passed to the +kernel. +If this value is 0, +.I fmh_entries +will be set to the number of records that would have been returned had +the array been large enough; +no mapping information will be returned. +.P +The +.I fmh_entries +field contains the number of elements in the +.I fmh_recs +array that contain useful information. +.P +The +.I fmh_reserved +fields must be set to zero. +.\" +.SS Keys +The two key records in +.I fsmap_head.fmh_keys +specify the lowest and highest extent records in the keyspace that the caller +wants returned. +A filesystem that can share blocks between files likely requires the tuple +.RI "(" "device" ", " "physical" ", " "owner" ", " "offset" ", " "flags" ")" +to uniquely index any filesystem mapping record. +Classic non-sharing filesystems might be able to identify any record with only +.RI "(" "device" ", " "physical" ", " "flags" ")." +For example, if the low key is set to (8:0, 36864, 0, 0, 0), the filesystem will +only return records for extents starting at or above 36\ KiB on disk. +If the high key is set to (8:0, 1048576, 0, 0, 0), +only records below 1\ MiB will be returned. +The format of +.I fmr_device +in the keys must match the format of the same field in the output records, +as defined below. +By convention, the field +.I fsmap_head.fmh_keys[0] +must contain the low key and +.I fsmap_head.fmh_keys[1] +must contain the high key for the operation. +.P +For convenience, if +.I fmr_length +is set in the low key, it will be added to +.IR fmr_block " or " fmr_offset +as appropriate. +The caller can take advantage of this subtlety to set up subsequent calls +by copying +.I fsmap_head.fmh_recs[fsmap_head.fmh_entries \- 1] +into the low key. +The function +.I fsmap_advance +(defined in +.IR linux/fsmap.h ) +provides this functionality. +.\" +.SS Fields of struct fsmap +The +.I fmr_device +field uniquely identifies the underlying storage device. +If the +.B FMH_OF_DEV_T +flag is set in the header's +.I fmh_oflags +field, this field contains a +.I dev_t +from which major and minor numbers can be extracted. +If the flag is not set, this field contains a value that must be unique +for each unique storage device. +.P +The +.I fmr_physical +field contains the disk address of the extent in bytes. +.P +The +.I fmr_owner +field contains the owner of the extent. +This is an inode number unless +.B FMR_OF_SPECIAL_OWNER +is set in the +.I fmr_flags +field, in which case the value is determined by the filesystem. +See the section below about owner values for more details. +.P +The +.I fmr_offset +field contains the logical address in the mapping record in bytes. +This field has no meaning if the +.BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP +flags are set in +.IR fmr_flags "." +.P +The +.I fmr_length +field contains the length of the extent in bytes. +.P +The +.I fmr_flags +field is a bit mask of extent state flags. +The bits are: +.RS 0.4i +.TP +.B FMR_OF_PREALLOC +The extent is allocated but not yet written. +.TP +.B FMR_OF_ATTR_FORK +This extent contains extended attribute data. +.TP +.B FMR_OF_EXTENT_MAP +This extent contains extent map information for the owner. +.TP +.B FMR_OF_SHARED +Parts of this extent may be shared. +.TP +.B FMR_OF_SPECIAL_OWNER +The +.I fmr_owner +field contains a special value instead of an inode number. +.TP +.B FMR_OF_LAST +This is the last record in the data set. +.RE +.P +The +.I fmr_reserved +field will be set to zero. +.\" +.SS Owner values +Generally, the value of the +.I fmr_owner +field for non-metadata extents should be an inode number. +However, filesystems are under no obligation to report inode numbers; +they may instead report +.B FMR_OWN_UNKNOWN +if the inode number cannot easily be retrieved, if the caller lacks +sufficient privilege, if the filesystem does not support stable +inode numbers, or for any other reason. +If a filesystem wishes to condition the reporting of inode numbers based +on process capabilities, it is strongly urged that the +.B CAP_SYS_ADMIN +capability be used for this purpose. +.TP +The following special owner values are generic to all filesystems: +.RS 0.4i +.TP +.B FMR_OWN_FREE +Free space. +.TP +.B FMR_OWN_UNKNOWN +This extent is in use but its owner is not known or not easily retrieved. +.TP +.B FMR_OWN_METADATA +This extent is filesystem metadata. +.RE +.P +XFS can return the following special owner values: +.RS 0.4i +.TP +.B XFS_FMR_OWN_FREE +Free space. +.TP +.B XFS_FMR_OWN_UNKNOWN +This extent is in use but its owner is not known or not easily retrieved. +.TP +.B XFS_FMR_OWN_FS +Static filesystem metadata which exists at a fixed address. +These are the AG superblock, the AGF, the AGFL, and the AGI headers. +.TP +.B XFS_FMR_OWN_LOG +The filesystem journal. +.TP +.B XFS_FMR_OWN_AG +Allocation group metadata, such as the free space btrees and the +reverse mapping btrees. +.TP +.B XFS_FMR_OWN_INOBT +The inode and free inode btrees. +.TP +.B XFS_FMR_OWN_INODES +Inode records. +.TP +.B XFS_FMR_OWN_REFC +Reference count information. +.TP +.B XFS_FMR_OWN_COW +This extent is being used to stage a copy-on-write. +.TP +.B XFS_FMR_OWN_DEFECTIVE: +This extent has been marked defective either by the filesystem or the +underlying device. +.RE +.P +ext4 can return the following special owner values: +.RS 0.4i +.TP +.B EXT4_FMR_OWN_FREE +Free space. +.TP +.B EXT4_FMR_OWN_UNKNOWN +This extent is in use but its owner is not known or not easily retrieved. +.TP +.B EXT4_FMR_OWN_FS +Static filesystem metadata which exists at a fixed address. +This is the superblock and the group descriptors. +.TP +.B EXT4_FMR_OWN_LOG +The filesystem journal. +.TP +.B EXT4_FMR_OWN_INODES +Inode records. +.TP +.B EXT4_FMR_OWN_BLKBM +Block bit map. +.TP +.B EXT4_FMR_OWN_INOBM +Inode bit map. +.RE +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +The error placed in +.I errno +can be one of, but is not limited to, the following: +.TP +.B EBADF +.I fd +is not open for reading. +.TP +.B EBADMSG +The filesystem has detected a checksum error in the metadata. +.TP +.B EFAULT +The pointer passed in was not mapped to a valid memory address. +.TP +.B EINVAL +The array is not long enough, the keys do not point to a valid part of +the filesystem, the low key points to a higher point in the filesystem's +physical storage address space than the high key, or a nonzero value +was passed in one of the fields that must be zero. +.TP +.B ENOMEM +Insufficient memory to process the operation. +.TP +.B EOPNOTSUPP +The filesystem does not support this operation. +.TP +.B EUCLEAN +The filesystem metadata is corrupt and needs repair. +.SH STANDARDS +Linux. +.P +Not all filesystems support it. +.SH HISTORY +Linux 4.12. +.SH EXAMPLES +See +.I io/fsmap.c +in the +.I xfsprogs +distribution for a sample program. +.SH SEE ALSO +.BR ioctl (2) diff --git a/man/man2/ioctl_iflags.2 b/man/man2/ioctl_iflags.2 new file mode 100644 index 0000000..5677030 --- /dev/null +++ b/man/man2/ioctl_iflags.2 @@ -0,0 +1,202 @@ +.\" Copyright (c) 2017 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH ioctl_iflags 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_iflags \- ioctl() operations for inode flags +.SH DESCRIPTION +Various Linux filesystems support the notion of +.IR "inode flags" \[em]attributes +that modify the semantics of files and directories. +These flags can be retrieved and modified using two +.BR ioctl (2) +operations: +.P +.in +4n +.EX +int attr; +fd = open("pathname", ...); +\& +ioctl(fd, FS_IOC_GETFLAGS, &attr); /* Place current flags + in \[aq]attr\[aq] */ +attr |= FS_NOATIME_FL; /* Tweak returned bit mask */ +ioctl(fd, FS_IOC_SETFLAGS, &attr); /* Update flags for inode + referred to by \[aq]fd\[aq] */ +.EE +.in +.P +The +.BR lsattr (1) +and +.BR chattr (1) +shell commands provide interfaces to these two operations, +allowing a user to view and modify the inode flags associated with a file. +.P +The following flags are supported +(shown along with the corresponding letter used to indicate the flag by +.BR lsattr (1) +and +.BR chattr (1)): +.TP +.BR FS_APPEND_FL " \[aq]a\[aq]" +The file can be opened only with the +.B O_APPEND +flag. +(This restriction applies even to the superuser.) +Only a privileged process +.RB ( CAP_LINUX_IMMUTABLE ) +can set or clear this attribute. +.TP +.BR FS_COMPR_FL " \[aq]c\[aq]" +Store the file in a compressed format on disk. +This flag is +.I not +supported by most of the mainstream filesystem implementations; +one exception is +.BR btrfs (5). +.TP +.BR FS_DIRSYNC_FL " \[aq]D\[aq] (since Linux 2.6.0)" +Write directory changes synchronously to disk. +This flag provides semantics equivalent to the +.BR mount (2) +.B MS_DIRSYNC +option, but on a per-directory basis. +This flag can be applied only to directories. +.\" .TP +.\" .BR FS_EXTENT_FL " \[aq]e\[aq]" +.\" FIXME Some support on ext4? (EXT4_EXTENTS_FL) +.TP +.BR FS_IMMUTABLE_FL " \[aq]i\[aq]" +The file is immutable: +no changes are permitted to the file contents or metadata +(permissions, timestamps, ownership, link count, and so on). +(This restriction applies even to the superuser.) +Only a privileged process +.RB ( CAP_LINUX_IMMUTABLE ) +can set or clear this attribute. +.TP +.BR FS_JOURNAL_DATA_FL " \[aq]j\[aq]" +Enable journaling of file data on +.BR ext3 (5) +and +.BR ext4 (5) +filesystems. +On a filesystem that is journaling in +.I ordered +or +.I writeback +mode, a privileged +.RB ( CAP_SYS_RESOURCE ) +process can set this flag to enable journaling of data updates on +a per-file basis. +.TP +.BR FS_NOATIME_FL " \[aq]A\[aq]" +Don't update the file last access time when the file is accessed. +This can provide I/O performance benefits for applications that do not care +about the accuracy of this timestamp. +This flag provides functionality similar to the +.BR mount (2) +.B MS_NOATIME +flag, but on a per-file basis. +.\" .TP +.\" .BR FS_NOCOMP_FL " \[aq]\[aq]" +.\" FIXME Support for FS_NOCOMP_FL on Btrfs? +.TP +.BR FS_NOCOW_FL " \[aq]C\[aq] (since Linux 2.6.39)" +The file will not be subject to copy-on-write updates. +This flag has an effect only on filesystems that support copy-on-write +semantics, such as Btrfs. +See +.BR chattr (1) +and +.BR btrfs (5). +.TP +.BR FS_NODUMP_FL " \[aq]d\[aq]" +Don't include this file in backups made using +.BR dump (8). +.TP +.BR FS_NOTAIL_FL " \[aq]t\[aq]" +This flag is supported only on Reiserfs. +It disables the Reiserfs tail-packing feature, +which tries to pack small files (and the final fragment of larger files) +into the same disk block as the file metadata. +.TP +.BR FS_PROJINHERIT_FL " \[aq]P\[aq] (since Linux 4.5)" +.\" commit 040cb3786d9b25293b8b0b05b90da0f871e1eb9b +.\" Flag name was added in Linux 4.4 +.\" FIXME Not currently supported because not in FS_FL_USER_MODIFIABLE? +Inherit the quota project ID. +Files and subdirectories will inherit the project ID of the directory. +This flag can be applied only to directories. +.TP +.BR FS_SECRM_FL " \[aq]s\[aq]" +Mark the file for secure deletion. +This feature is not implemented by any filesystem, +since the task of securely erasing a file from a recording medium +is surprisingly difficult. +.TP +.BR FS_SYNC_FL " \[aq]S\[aq]" +Make file updates synchronous. +For files, this makes all writes synchronous +(as though all opens of the file were with the +.B O_SYNC +flag). +For directories, this has the same effect as the +.B FS_DIRSYNC_FL +flag. +.TP +.BR FS_TOPDIR_FL " \[aq]T\[aq]" +Mark a directory for special treatment under the Orlov block-allocation +strategy. +See +.BR chattr (1) +for details. +This flag can be applied only to directories and +has an effect only for ext2, ext3, and ext4. +.TP +.BR FS_UNRM_FL " \[aq]u\[aq]" +Allow the file to be undeleted if it is deleted. +This feature is not implemented by any filesystem, +since it is possible to implement file-recovery mechanisms outside the kernel. +.P +In most cases, +when any of the above flags is set on a directory, +the flag is inherited by files and subdirectories +created inside that directory. +Exceptions include +.BR FS_TOPDIR_FL , +which is not inheritable, and +.BR FS_DIRSYNC_FL , +which is inherited only by subdirectories. +.SH STANDARDS +Linux. +.SH NOTES +In order to change the inode flags of a file using the +.B FS_IOC_SETFLAGS +operation, +the effective user ID of the caller must match the owner of the file, +or the caller must have the +.B CAP_FOWNER +capability. +.P +The type of the argument given to the +.B FS_IOC_GETFLAGS +and +.B FS_IOC_SETFLAGS +operations is +.IR int\~* , +notwithstanding the implication in the kernel source file +.I include/uapi/linux/fs.h +that the argument is +.IR long\~* . +.SH SEE ALSO +.BR chattr (1), +.BR lsattr (1), +.BR mount (2), +.BR btrfs (5), +.BR ext4 (5), +.BR xfs (5), +.BR xattr (7), +.BR mount (8) diff --git a/man/man2/ioctl_ns.2 b/man/man2/ioctl_ns.2 new file mode 100644 index 0000000..0f6aede --- /dev/null +++ b/man/man2/ioctl_ns.2 @@ -0,0 +1,342 @@ +.\" Copyright (c) 2017 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH ioctl_ns 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_ns \- ioctl() operations for Linux namespaces +.SH DESCRIPTION +.\" ============================================================ +.\" +.SS Discovering namespace relationships +The following +.BR ioctl (2) +operations are provided to allow discovery of namespace relationships (see +.BR user_namespaces (7) +and +.BR pid_namespaces (7)). +The form of the calls is: +.P +.in +4n +.EX +new_fd = ioctl(fd, op); +.EE +.in +.P +In each case, +.I fd +refers to a +.IR /proc/ pid /ns/* +file. +Both operations return a new file descriptor on success. +.TP +.BR NS_GET_USERNS " (since Linux 4.9)" +.\" commit bcac25a58bfc6bd79191ac5d7afb49bea96da8c9 +.\" commit 6786741dbf99e44fb0c0ed85a37582b8a26f1c3b +Returns a file descriptor that refers to the owning user namespace +for the namespace referred to by +.IR fd . +.TP +.BR NS_GET_PARENT " (since Linux 4.9)" +.\" commit a7306ed8d94af729ecef8b6e37506a1c6fc14788 +Returns a file descriptor that refers to the parent namespace of +the namespace referred to by +.IR fd . +This operation is valid only for hierarchical namespaces +(i.e., PID and user namespaces). +For user namespaces, +.B NS_GET_PARENT +is synonymous with +.BR NS_GET_USERNS . +.P +The new file descriptor returned by these operations is opened with the +.B O_RDONLY +and +.B O_CLOEXEC +(close-on-exec; see +.BR fcntl (2)) +flags. +.P +By applying +.BR fstat (2) +to the returned file descriptor, one obtains a +.I stat +structure whose +.I st_dev +(resident device) and +.I st_ino +(inode number) fields together identify the owning/parent namespace. +This inode number can be matched with the inode number of another +.IR /proc/ pid /ns/ { pid , user } +file to determine whether that is the owning/parent namespace. +.P +Either of these +.BR ioctl (2) +operations can fail with the following errors: +.TP +.B EPERM +The requested namespace is outside of the caller's namespace scope. +This error can occur if, for example, the owning user namespace is an +ancestor of the caller's current user namespace. +It can also occur on attempts to obtain the parent of the initial +user or PID namespace. +.TP +.B ENOTTY +The operation is not supported by this kernel version. +.P +Additionally, the +.B NS_GET_PARENT +operation can fail with the following error: +.TP +.B EINVAL +.I fd +refers to a nonhierarchical namespace. +.P +See the EXAMPLES section for an example of the use of these operations. +.\" ============================================================ +.\" +.SS Discovering the namespace type +The +.B NS_GET_NSTYPE +.\" commit e5ff5ce6e20ee22511398bb31fb912466cf82a36 +operation (available since Linux 4.11) can be used to discover +the type of namespace referred to by the file descriptor +.IR fd : +.P +.in +4n +.EX +nstype = ioctl(fd, NS_GET_NSTYPE); +.EE +.in +.P +.I fd +refers to a +.IR /proc/ pid /ns/* +file. +.P +The return value is one of the +.B CLONE_NEW* +values that can be specified to +.BR clone (2) +or +.BR unshare (2) +in order to create a namespace. +.\" ============================================================ +.\" +.SS Discovering the owner of a user namespace +The +.B NS_GET_OWNER_UID +.\" commit 015bb305b8ebe8d601a238ab70ebdc394c7a19ba +operation (available since Linux 4.11) can be used to discover +the owner user ID of a user namespace (i.e., the effective user ID +of the process that created the user namespace). +The form of the call is: +.P +.in +4n +.EX +uid_t uid; +ioctl(fd, NS_GET_OWNER_UID, &uid); +.EE +.in +.P +.I fd +refers to a +.IR /proc/ pid /ns/user +file. +.P +The owner user ID is returned in the +.I uid_t +pointed to by the third argument. +.P +This operation can fail with the following error: +.TP +.B EINVAL +.I fd +does not refer to a user namespace. +.SH ERRORS +Any of the above +.BR ioctl () +operations can return the following errors: +.TP +.B ENOTTY +.I fd +does not refer to a +.IR /proc/ pid /ns/ * +file. +.SH STANDARDS +Linux. +.SH EXAMPLES +The example shown below uses the +.BR ioctl (2) +operations described above to perform simple +discovery of namespace relationships. +The following shell sessions show various examples of the use +of this program. +.P +Trying to get the parent of the initial user namespace fails, +since it has no parent: +.P +.in +4n +.EX +$ \fB./ns_show /proc/self/ns/user p\fP +The parent namespace is outside your namespace scope +.EE +.in +.P +Create a process running +.BR sleep (1) +that resides in new user and UTS namespaces, +and show that the new UTS namespace is associated with the new user namespace: +.P +.in +4n +.EX +$ \fBunshare \-Uu sleep 1000 &\fP +[1] 23235 +$ \fB./ns_show /proc/23235/ns/uts u\fP +Device/Inode of owning user namespace is: [0,3] / 4026532448 +$ \fBreadlink /proc/23235/ns/user\fP +user:[4026532448] +.EE +.in +.P +Then show that the parent of the new user namespace in the preceding +example is the initial user namespace: +.P +.in +4n +.EX +$ \fBreadlink /proc/self/ns/user\fP +user:[4026531837] +$ \fB./ns_show /proc/23235/ns/user p\fP +Device/Inode of parent namespace is: [0,3] / 4026531837 +.EE +.in +.P +Start a shell in a new user namespace, and show that from within +this shell, the parent user namespace can't be discovered. +Similarly, the UTS namespace +(which is associated with the initial user namespace) +can't be discovered. +.P +.in +4n +.EX +$ \fBPS1="sh2$ " unshare \-U bash\fP +sh2$ \fB./ns_show /proc/self/ns/user p\fP +The parent namespace is outside your namespace scope +sh2$ \fB./ns_show /proc/self/ns/uts u\fP +The owning user namespace is outside your namespace scope +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (ns_show.c) +.EX +/* ns_show.c +\& + Licensed under the GNU General Public License v2 or later. +*/ +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int fd, userns_fd, parent_fd; + struct stat sb; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s /proc/[pid]/ns/[file] [p|u]\en", + argv[0]); + fprintf(stderr, "\enDisplay the result of one or both " + "of NS_GET_USERNS (u) or NS_GET_PARENT (p)\en" + "for the specified /proc/[pid]/ns/[file]. If neither " + "\[aq]p\[aq] nor \[aq]u\[aq] is specified,\en" + "NS_GET_USERNS is the default.\en"); + exit(EXIT_FAILURE); + } +\& + /* Obtain a file descriptor for the \[aq]ns\[aq] file specified + in argv[1]. */ +\& + fd = open(argv[1], O_RDONLY); + if (fd == \-1) { + perror("open"); + exit(EXIT_FAILURE); + } +\& + /* Obtain a file descriptor for the owning user namespace and + then obtain and display the inode number of that namespace. */ +\& + if (argc < 3 || strchr(argv[2], \[aq]u\[aq])) { + userns_fd = ioctl(fd, NS_GET_USERNS); +\& + if (userns_fd == \-1) { + if (errno == EPERM) + printf("The owning user namespace is outside " + "your namespace scope\en"); + else + perror("ioctl\-NS_GET_USERNS"); + exit(EXIT_FAILURE); + } +\& + if (fstat(userns_fd, &sb) == \-1) { + perror("fstat\-userns"); + exit(EXIT_FAILURE); + } + printf("Device/Inode of owning user namespace is: " + "[%x,%x] / %ju\en", + major(sb.st_dev), + minor(sb.st_dev), + (uintmax_t) sb.st_ino); +\& + close(userns_fd); + } +\& + /* Obtain a file descriptor for the parent namespace and + then obtain and display the inode number of that namespace. */ +\& + if (argc > 2 && strchr(argv[2], \[aq]p\[aq])) { + parent_fd = ioctl(fd, NS_GET_PARENT); +\& + if (parent_fd == \-1) { + if (errno == EINVAL) + printf("Can\[aq] get parent namespace of a " + "nonhierarchical namespace\en"); + else if (errno == EPERM) + printf("The parent namespace is outside " + "your namespace scope\en"); + else + perror("ioctl\-NS_GET_PARENT"); + exit(EXIT_FAILURE); + } +\& + if (fstat(parent_fd, &sb) == \-1) { + perror("fstat\-parentns"); + exit(EXIT_FAILURE); + } + printf("Device/Inode of parent namespace is: [%x,%x] / %ju\en", + major(sb.st_dev), + minor(sb.st_dev), + (uintmax_t) sb.st_ino); +\& + close(parent_fd); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fstat (2), +.BR ioctl (2), +.BR proc (5), +.BR namespaces (7) diff --git a/man/man2/ioctl_pagemap_scan.2 b/man/man2/ioctl_pagemap_scan.2 new file mode 100644 index 0000000..19d7da1 --- /dev/null +++ b/man/man2/ioctl_pagemap_scan.2 @@ -0,0 +1,206 @@ +.\" This manpage is Copyright (C) 2023 Collabora; +.\" Written by Muhammad Usama Anjum +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH ioctl_pagemap_scan 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_pagemap_scan \- get and/or clear page flags +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " "struct pm_scan_arg" , +.BR " struct page_region" ", and " PAGE_IS_* " constants */" +.B #include +.P +.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg ); +.fi +.SH DESCRIPTION +This +.BR ioctl (2) +is used to get and optionally clear some specific flags from page table entries. +The information is returned with +.B PAGE_SIZE +granularity. +.P +To start tracking the written state (flag) of a page or range of memory, +the +.B UFFD_FEATURE_WP_ASYNC +must be enabled by +.B UFFDIO_API +.BR ioctl (2) +on +.B userfaultfd +and memory range must be registered with +.B UFFDIO_REGISTER +.BR ioctl (2) +in +.B UFFDIO_REGISTER_MODE_WP +mode. +.SS Supported page flags +The following page table entry flags are supported: +.TP +.B PAGE_IS_WPALLOWED +The page has asynchronous write-protection enabled. +.TP +.B PAGE_IS_WRITTEN +The page has been written to from the time it was write protected. +.TP +.B PAGE_IS_FILE +The page is file backed. +.TP +.B PAGE_IS_PRESENT +The page is present in the memory. +.TP +.B PAGE_IS_SWAPPED +The page is swapped. +.TP +.B PAGE_IS_PFNZERO +The page has zero PFN. +.TP +.B PAGE_IS_HUGE +The page is THP or Hugetlb backed. +.SS Supported operations +The get operation is always performed +if the output buffer is specified. +The other operations are as following: +.TP +.B PM_SCAN_WP_MATCHING +Write protect the matched pages. +.TP +.B PM_SCAN_CHECK_WPASYNC +Abort the scan +when a page is found +which doesn't have the Userfaultfd Asynchronous Write protection enabled. +.SS The \f[I]struct pm_scan_arg\f[] argument +.EX +struct pm_scan_arg { + __u64 size; + __u64 flags; + __u64 start; + __u64 end; + __u64 walk_end; + __u64 vec; + __u64 vec_len; + __u64 max_pages + __u64 category_inverted; + __u64 category_mask; + __u64 category_anyof_mask + __u64 return_mask; +}; +.EE +.TP +.B size +This field should be set to the size of the structure in bytes, +as in +.IR sizeof(struct\~pm_scan_arg) . +.TP +.B flags +The operations to be performed are specified in it. +.TP +.B start +The starting address of the scan is specified in it. +.TP +.B end +The ending address of the scan is specified in it. +.TP +.B walk_end +The kernel returns the scan's ending address in it. +The +.I walk_end +equal to +.I end +means that scan has completed on the entire range. +.TP +.B vec +The address of +.I page_region +array for output. +.IP +.in +4n +.EX +struct page_region { + __u64 start; + __u64 end; + __u64 categories; +}; +.EE +.in +.TP +.B vec_len +The length of the +.I page_region +struct array. +.TP +.B max_pages +It is the optional limit for the number of output pages required. +.TP +.B category_inverted +.BI PAGE_IS_ * +categories which values match if 0 instead of 1. +.TP +.B category_mask +Skip pages for which any +.BI PAGE_IS_ * +category doesn't match. +.TP +.B category_anyof_mask +Skip pages for which no +.BI PAGE_IS_ * +category matches. +.TP +.B return_mask +.BI PAGE_IS_ * +categories that are to be reported in +.IR page_region . +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Error codes can be one of, but are not limited to, the following: +.TP +.B EINVAL +Invalid arguments i.e., +invalid +.I size +of the argument, +invalid +.IR flags , +invalid +.IR categories , +the +.I start +address isn't aligned with +.BR PAGE_SIZE , +or +.I vec_len +is specified when +.I vec +is NULL. +.TP +.B EFAULT +Invalid +.I arg +pointer, +invalid +.I vec +pointer, +or invalid address range specified by +.I start +and +.IR end . +.TP +.B ENOMEM +No memory is available. +.TP +.B EINTR +Fetal signal is pending. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 6.7. +.SH SEE ALSO +.BR ioctl (2) diff --git a/man/man2/ioctl_pipe.2 b/man/man2/ioctl_pipe.2 new file mode 100644 index 0000000..f895142 --- /dev/null +++ b/man/man2/ioctl_pipe.2 @@ -0,0 +1,64 @@ +.\" Copyright (c) 2022 by Cyril Hrubis +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH ioctl_pipe 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_pipe \- ioctl() operations for General notification mechanism +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " IOC_WATCH_QUEUE_ "* */" +.B #include +.P +.BI "int ioctl(int " pipefd "[1], IOC_WATCH_QUEUE_SET_SIZE, int " size ); +.BI "int ioctl(int " pipefd "[1], IOC_WATCH_QUEUE_SET_FILTER," +.BI " struct watch_notification_filter *" filter ); +.fi +.SH DESCRIPTION +The following +.BR ioctl (2) +operations are provided to set up general notification queue parameters. +The notification queue is built on the top of a +.BR pipe (2) +opened with the +.B O_NOTIFICATION_PIPE +flag. +.TP +.BR IOC_WATCH_QUEUE_SET_SIZE " (since Linux 5.8)" +.\" commit c73be61cede5882f9605a852414db559c0ebedfd +Preallocates the pipe buffer memory so that +it can fit +.I size +notification messages. +Currently, +.I size +must be between 1 and 512. +.TP +.BR IOC_WATCH_QUEUE_SET_FILTER " (since Linux 5.8)" +.\" commit c73be61cede5882f9605a852414db559c0ebedfd +Watch queue filter can limit events that are received. +Filters are passed in a +.I struct watch_notification_filter +and each filter is described by a +.I struct watch_notification_type_filter +structure. +.IP +.in +4n +.EX +struct watch_notification_filter { + __u32 nr_filters; + __u32 __reserved; + struct watch_notification_type_filter filters[]; +}; +\& +struct watch_notification_type_filter { + __u32 type; + __u32 info_filter; + __u32 info_mask; + __u32 subtype_filter[8]; +}; +.EE +.in +.SH SEE ALSO +.BR pipe (2), +.BR ioctl (2) diff --git a/man/man2/ioctl_tty.2 b/man/man2/ioctl_tty.2 new file mode 100644 index 0000000..6731d4e --- /dev/null +++ b/man/man2/ioctl_tty.2 @@ -0,0 +1,922 @@ +'\" t +.\" Copyright 2002 Walter Harms +.\" and Andries Brouwer . +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ioctl_tty 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_tty \- ioctls for terminals and serial lines +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.BR "#include " " /* Definition of " "struct termios" , +.BR " struct termios2" ", and" +.BR " Bnnn" ", " BOTHER ", " CBAUD ", " CLOCAL , +.BR " TC*" { FLUSH , ON , OFF "} and other constants */" +.P +.BI "int ioctl(int " fd ", int " op ", ...);" +.fi +.SH DESCRIPTION +The +.BR ioctl (2) +call for terminals and serial ports accepts many possible operation arguments. +Most require a third argument, of varying type, here called +.I argp +or +.IR arg . +.P +Use of +.BR ioctl () +makes for nonportable programs. +Use the POSIX interface described in +.BR termios (3) +whenever possible. +.P +Please note that +.B struct termios +from +.I +is different and incompatible with +.B struct termios +from +.IR . +These ioctl calls require +.B struct termios +from +.IR . +.SS Get and set terminal attributes +.TP +.B TCGETS +Argument: +.BI "struct termios\~*" argp +.IP +Equivalent to +.IR "tcgetattr(fd, argp)" . +.IP +Get the current serial port settings. +.TP +.B TCSETS +Argument: +.BI "const struct termios\~*" argp +.IP +Equivalent to +.IR "tcsetattr(fd, TCSANOW, argp)" . +.IP +Set the current serial port settings. +.TP +.B TCSETSW +Argument: +.BI "const struct termios\~*" argp +.IP +Equivalent to +.IR "tcsetattr(fd, TCSADRAIN, argp)" . +.IP +Allow the output buffer to drain, and +set the current serial port settings. +.TP +.B TCSETSF +Argument: +.BI "const struct termios\~*" argp +.IP +Equivalent to +.IR "tcsetattr(fd, TCSAFLUSH, argp)" . +.IP +Allow the output buffer to drain, discard pending input, and +set the current serial port settings. +.P +The following four ioctls, added in Linux 2.6.20, +.\" commit 64bb6c5e1ddcd47c951740485026ef08975ee2e6 +.\" commit 592ee3a5e5e2a981ef2829a0380093006d045661 +are just like +.BR TCGETS , +.BR TCSETS , +.BR TCSETSW , +.BR TCSETSF , +except that they take a +.I "struct termios2\~*" +instead of a +.IR "struct termios\~*" . +If the structure member +.B c_cflag +contains the flag +.BR BOTHER , +then the baud rate is stored in the structure members +.B c_ispeed +and +.B c_ospeed +as integer values. +These ioctls are not supported on all architectures. +.RS +.TS +lb l. +TCGETS2 \fBstruct termios2 *\fPargp +TCSETS2 \fBconst struct termios2 *\fPargp +TCSETSW2 \fBconst struct termios2 *\fPargp +TCSETSF2 \fBconst struct termios2 *\fPargp +.TE +.RE +.P +The following four ioctls are just like +.BR TCGETS , +.BR TCSETS , +.BR TCSETSW , +.BR TCSETSF , +except that they take a +.I "struct termio\~*" +instead of a +.IR "struct termios\~*" . +.RS +.TS +lb l. +TCGETA \fBstruct termio *\fPargp +TCSETA \fBconst struct termio *\fPargp +TCSETAW \fBconst struct termio *\fPargp +TCSETAF \fBconst struct termio *\fPargp +.TE +.RE +.SS Locking the termios structure +The +.I termios +structure of a terminal can be locked. +The lock is itself a +.I termios +structure, with nonzero bits or fields indicating a +locked value. +.TP +.B TIOCGLCKTRMIOS +Argument: +.BI "struct termios\~*" argp +.IP +Gets the locking status of the +.I termios +structure of the terminal. +.TP +.B TIOCSLCKTRMIOS +Argument: +.BI "const struct termios\~*" argp +.IP +Sets the locking status of the +.I termios +structure of the terminal. +Only a process with the +.B CAP_SYS_ADMIN +capability can do this. +.SS Get and set window size +Window sizes are kept in the kernel, but not used by the kernel +(except in the case of virtual consoles, where the kernel will +update the window size when the size of the virtual console changes, +for example, by loading a new font). +.TP +.B TIOCGWINSZ +Argument: +.BI "struct winsize\~*" argp +.IP +Get window size. +.TP +.B TIOCSWINSZ +Argument: +.BI "const struct winsize\~*" argp +.IP +Set window size. +.P +The struct used by these ioctls is defined as +.P +.in +4n +.EX +struct winsize { + unsigned short ws_row; + unsigned short ws_col; + unsigned short ws_xpixel; /* unused */ + unsigned short ws_ypixel; /* unused */ +}; +.EE +.in +.P +When the window size changes, a +.B SIGWINCH +signal is sent to the +foreground process group. +.SS Sending a break +.TP +.B TCSBRK +Argument: +.BI "int " arg +.IP +Equivalent to +.IR "tcsendbreak(fd, arg)" . +.IP +If the terminal is using asynchronous serial data transmission, and +.I arg +is zero, then send a break (a stream of zero bits) for between +0.25 and 0.5 seconds. +If the terminal is not using asynchronous +serial data transmission, then either a break is sent, or the function +returns without doing anything. +When +.I arg +is nonzero, nobody knows what will happen. +.IP +(SVr4, UnixWare, Solaris, and Linux treat +.I "tcsendbreak(fd,arg)" +with nonzero +.I arg +like +.IR "tcdrain(fd)" . +SunOS treats +.I arg +as a multiplier, and sends a stream of bits +.I arg +times as long as done for zero +.IR arg . +DG/UX and AIX treat +.I arg +(when nonzero) as a time interval measured in milliseconds. +HP-UX ignores +.IR arg .) +.TP +.B TCSBRKP +Argument: +.BI "int " arg +.IP +So-called "POSIX version" of +.BR TCSBRK . +It treats nonzero +.I arg +as a time interval measured in deciseconds, and does nothing +when the driver does not support breaks. +.TP +.B TIOCSBRK +Argument: +.B void +.IP +Turn break on, that is, start sending zero bits. +.TP +.B TIOCCBRK +Argument: +.B void +.IP +Turn break off, that is, stop sending zero bits. +.SS Software flow control +.TP +.B TCXONC +Argument: +.BI "int " arg +.IP +Equivalent to +.IR "tcflow(fd, arg)" . +.IP +See +.BR tcflow (3) +for the argument values +.BR TCOOFF , +.BR TCOON , +.BR TCIOFF , +.BR TCION . +.SS Buffer count and flushing +.TP +.B FIONREAD +Argument: +.BI "int\~*" argp +.IP +Get the number of bytes in the input buffer. +.TP +.B TIOCINQ +Argument: +.BI "int\~*" argp +.IP +Same as +.BR FIONREAD . +.TP +.B TIOCOUTQ +Argument: +.BI "int\~*" argp +.IP +Get the number of bytes in the output buffer. +.TP +.B TCFLSH +Argument: +.BI "int " arg +.IP +Equivalent to +.IR "tcflush(fd, arg)" . +.IP +See +.BR tcflush (3) +for the argument values +.BR TCIFLUSH , +.BR TCOFLUSH , +.BR TCIOFLUSH . +.TP +.B TIOCSERGETLSR +Argument: +.BI "int\~*" argp +.IP +Get line status register. +Status register has +.B TIOCSER_TEMT +bit set when +output buffer is empty and also hardware transmitter is physically empty. +.IP +Does not have to be supported by all serial tty drivers. +.IP +.BR tcdrain (3) +does not wait and returns immediately when +.B TIOCSER_TEMT +bit is set. +.SS Faking input +.TP +.B TIOCSTI +Argument: +.BI "const char\~*" argp +.IP +Insert the given byte in the input queue. +.IP +Since Linux 6.2, +.\" commit 690c8b804ad2eafbd35da5d3c95ad325ca7d5061 +.\" commit 83efeeeb3d04b22aaed1df99bc70a48fe9d22c4d +this operation may require the +.B CAP_SYS_ADMIN +capability (if the +.I dev.tty.legacy_tiocsti +sysctl variable is set to false). +.SS Redirecting console output +.TP +.B TIOCCONS +Argument: +.B void +.IP +Redirect output that would have gone to +.I /dev/console +or +.I /dev/tty0 +to the given terminal. +If that was a pseudoterminal master, send it to the slave. +Before Linux 2.6.10, +anybody can do this as long as the output was not redirected yet; +since Linux 2.6.10, only a process with the +.B CAP_SYS_ADMIN +capability may do this. +If output was redirected already, then +.B EBUSY +is returned, +but redirection can be stopped by using this ioctl with +.I fd +pointing at +.I /dev/console +or +.IR /dev/tty0 . +.SS Controlling terminal +.TP +.B TIOCSCTTY +Argument: +.BI "int " arg +.IP +Make the given terminal the controlling terminal of the calling process. +The calling process must be a session leader and not have a +controlling terminal already. +For this case, +.I arg +should be specified as zero. +.IP +If this terminal is already the controlling terminal +of a different session group, then the ioctl fails with +.BR EPERM , +unless the caller has the +.B CAP_SYS_ADMIN +capability and +.I arg +equals 1, in which case the terminal is stolen, and all processes that had +it as controlling terminal lose it. +.TP +.B TIOCNOTTY +Argument: +.B void +.IP +If the given terminal was the controlling terminal of the calling process, +give up this controlling terminal. +If the process was session leader, +then send +.B SIGHUP +and +.B SIGCONT +to the foreground process group +and all processes in the current session lose their controlling terminal. +.SS Process group and session ID +.TP +.B TIOCGPGRP +Argument: +.BI "pid_t\~*" argp +.IP +When successful, equivalent to +.IR "*argp = tcgetpgrp(fd)" . +.IP +Get the process group ID of the foreground process group on this terminal. +.TP +.B TIOCSPGRP +Argument: +.BI "const pid_t\~*" argp +.IP +Equivalent to +.IR "tcsetpgrp(fd, *argp)" . +.IP +Set the foreground process group ID of this terminal. +.TP +.B TIOCGSID +Argument: +.BI "pid_t\~*" argp +.IP +When successful, equivalent to +.IR "*argp = tcgetsid(fd)" . +.IP +Get the session ID of the given terminal. +This fails with the error +.B ENOTTY +if the terminal is not a master pseudoterminal +and not our controlling terminal. +Strange. +.SS Exclusive mode +.TP +.B TIOCEXCL +Argument: +.B void +.IP +Put the terminal into exclusive mode. +No further +.BR open (2) +operations on the terminal are permitted. +(They fail with +.BR EBUSY , +except for a process with the +.B CAP_SYS_ADMIN +capability.) +.TP +.B TIOCGEXCL +Argument: +.BI "int\~*" argp +.IP +(since Linux 3.8) +If the terminal is currently in exclusive mode, +place a nonzero value in the location pointed to by +.IR argp ; +otherwise, place zero in +.IR *argp . +.TP +.B TIOCNXCL +Argument: +.B void +.IP +Disable exclusive mode. +.SS Line discipline +.TP +.B TIOCGETD +Argument: +.BI "int\~*" argp +.IP +Get the line discipline of the terminal. +.TP +.B TIOCSETD +Argument: +.BI "const int\~*" argp +.IP +Set the line discipline of the terminal. +.SS Pseudoterminal ioctls +.TP +.B TIOCPKT +Argument: +.BI "const int\~*" argp +.IP +Enable (when +.RI * argp +is nonzero) or disable packet mode. +Can be applied to the master side of a pseudoterminal only (and will return +.B ENOTTY +otherwise). +In packet mode, each subsequent +.BR read (2) +will return a packet that either contains a single nonzero control byte, +or has a single byte containing zero (\[aq]\e0\[aq]) followed by data +written on the slave side of the pseudoterminal. +If the first byte is not +.B TIOCPKT_DATA +(0), it is an OR of one +or more of the following bits: +.IP +.ad l +.TS +lb l. +TIOCPKT_FLUSHREAD T{ +The read queue for the terminal is flushed. +T} +TIOCPKT_FLUSHWRITE T{ +The write queue for the terminal is flushed. +T} +TIOCPKT_STOP T{ +Output to the terminal is stopped. +T} +TIOCPKT_START T{ +Output to the terminal is restarted. +T} +TIOCPKT_DOSTOP T{ +The start and stop characters are \fB\[ha]S\fP/\fB\[ha]Q\fP. +T} +TIOCPKT_NOSTOP T{ +The start and stop characters are not \fB\[ha]S\fP/\fB\[ha]Q\fP. +T} +.TE +.ad +.IP +While packet mode is in use, the presence +of control status information to be read +from the master side may be detected by a +.BR select (2) +for exceptional conditions or a +.BR poll (2) +for the +.B POLLPRI +event. +.IP +This mode is used by +.BR rlogin (1) +and +.BR rlogind (8) +to implement a remote-echoed, +locally \fB\[ha]S\fP/\fB\[ha]Q\fP flow-controlled remote login. +.TP +.B TIOCGPKT +Argument: +.BI "const int\~*" argp +.IP +(since Linux 3.8) +Return the current packet mode setting in the integer pointed to by +.IR argp . +.TP +.B TIOCSPTLCK +Argument: +.BI "int\~*" argp +.IP +Set (if +.I *argp +is nonzero) or remove (if +.I *argp +is zero) the lock on the pseudoterminal slave device. +(See also +.BR unlockpt (3).) +.TP +.B TIOCGPTLCK +Argument: +.BI "int\~*" argp +.IP +(since Linux 3.8) +Place the current lock state of the pseudoterminal slave device +in the location pointed to by +.IR argp . +.TP +.B TIOCGPTPEER +Argument: +.BI "int " flags +.IP +.\" commit 54ebbfb1603415d9953c150535850d30609ef077 +(since Linux 4.13) +Given a file descriptor in +.I fd +that refers to a pseudoterminal master, +open (with the given +.BR open (2)-style +.IR flags ) +and return a new file descriptor that refers to the peer +pseudoterminal slave device. +This operation can be performed +regardless of whether the pathname of the slave device +is accessible through the calling process's mount namespace. +.IP +Security-conscious programs interacting with namespaces may wish to use this +operation rather than +.BR open (2) +with the pathname returned by +.BR ptsname (3), +and similar library functions that have insecure APIs. +(For example, confusion can occur in some cases using +.BR ptsname (3) +with a pathname where a devpts filesystem +has been mounted in a different mount namespace.) +.P +The BSD ioctls +.BR TIOCSTOP , +.BR TIOCSTART , +.BR TIOCUCNTL , +and +.B TIOCREMOTE +have not been implemented under Linux. +.SS Modem control +.TP +.B TIOCMGET +Argument: +.BI "int\~*" argp +.IP +Get the status of modem bits. +.TP +.B TIOCMSET +Argument: +.BI "const int\~*" argp +.IP +Set the status of modem bits. +.TP +.B TIOCMBIC +Argument: +.BI "const int\~*" argp +.IP +Clear the indicated modem bits. +.TP +.B TIOCMBIS +Argument: +.BI "const int\~*" argp +.IP +Set the indicated modem bits. +.P +The following bits are used by the above ioctls: +.P +.TS +lb l. +TIOCM_LE DSR (data set ready/line enable) +TIOCM_DTR DTR (data terminal ready) +TIOCM_RTS RTS (request to send) +TIOCM_ST Secondary TXD (transmit) +TIOCM_SR Secondary RXD (receive) +TIOCM_CTS CTS (clear to send) +TIOCM_CAR DCD (data carrier detect) +TIOCM_CD see TIOCM_CAR +TIOCM_RNG RNG (ring) +TIOCM_RI see TIOCM_RNG +TIOCM_DSR DSR (data set ready) +.TE +.TP +.B TIOCMIWAIT +Argument: +.BI "int " arg +.IP +Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change. +The bits of interest are specified as a bit mask in +.IR arg , +by ORing together any of the bit values, +.BR TIOCM_RNG , +.BR TIOCM_DSR , +.BR TIOCM_CD , +and +.BR TIOCM_CTS . +The caller should use +.B TIOCGICOUNT +to see which bit has changed. +.TP +.B TIOCGICOUNT +Argument: +.BI "struct serial_icounter_struct\~*" argp +.IP +Get counts of input serial line interrupts (DCD, RI, DSR, CTS). +The counts are written to the +.I serial_icounter_struct +structure pointed to by +.IR argp . +.IP +Note: both 1->0 and 0->1 transitions are counted, except for +RI, where only 0->1 transitions are counted. +.SS Marking a line as local +.TP +.B TIOCGSOFTCAR +Argument: +.BI "int\~*" argp +.IP +("Get software carrier flag") +Get the status of the CLOCAL flag in the c_cflag field of the +.I termios +structure. +.TP +.B TIOCSSOFTCAR +Argument: +.BI "const int\~*" argp +.IP +("Set software carrier flag") +Set the CLOCAL flag in the +.I termios +structure when +.RI * argp +is nonzero, and clear it otherwise. +.P +If the +.B CLOCAL +flag for a line is off, the hardware carrier detect (DCD) +signal is significant, and an +.BR open (2) +of the corresponding terminal will block until DCD is asserted, +unless the +.B O_NONBLOCK +flag is given. +If +.B CLOCAL +is set, the line behaves as if DCD is always asserted. +The software carrier flag is usually turned on for local devices, +and is off for lines with modems. +.SS Linux-specific +For the +.B TIOCLINUX +ioctl, see +.BR ioctl_console (2). +.SS Kernel debugging +.B "#include " +.TP +.B TIOCTTYGSTRUCT +Argument: +.BI "struct tty_struct\~*" argp +.IP +Get the +.I tty_struct +corresponding to +.IR fd . +This operation was removed in Linux 2.5.67. +.\" commit b3506a09d15dc5aee6d4bb88d759b157016e1864 +.\" Author: Andries E. Brouwer +.\" Date: Tue Apr 1 04:42:46 2003 -0800 +.\" +.\" [PATCH] kill TIOCTTYGSTRUCT +.\" +.\" Only used for (dubious) debugging purposes, and exposes +.\" internal kernel state. +.\" +.\" .SS Serial info +.\" .BR "#include " +.\" .P +.\" .TP +.\" .BI "TIOCGSERIAL struct serial_struct *" argp +.\" Get serial info. +.\" .TP +.\" .BI "TIOCSSERIAL const struct serial_struct *" argp +.\" Set serial info. +.SH RETURN VALUE +The +.BR ioctl (2) +system call returns 0 on success. +On error, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Invalid operation parameter. +.TP +.B ENOIOCTLCMD +Unknown operation. +.TP +.B ENOTTY +Inappropriate +.IR fd . +.TP +.B EPERM +Insufficient permission. +.SH EXAMPLES +Check the condition of DTR on the serial port. +.P +.\" SRC BEGIN (tiocmget.c) +.EX +#include +#include +#include +#include +\& +int +main(void) +{ + int fd, serial; +\& + fd = open("/dev/ttyS0", O_RDONLY); + ioctl(fd, TIOCMGET, &serial); + if (serial & TIOCM_DTR) + puts("TIOCM_DTR is set"); + else + puts("TIOCM_DTR is not set"); + close(fd); +} +.EE +.\" SRC END +.P +Get or set arbitrary baudrate on the serial port. +.P +.\" SRC BEGIN (tcgets.c) +.EX +/* SPDX-License-Identifier: GPL-2.0-or-later */ +\& +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ +#if !defined BOTHER + fprintf(stderr, "BOTHER is unsupported\en"); + /* Program may fallback to TCGETS/TCSETS with Bnnn constants */ + exit(EXIT_FAILURE); +#else + /* Declare tio structure, its type depends on supported ioctl */ +# if defined TCGETS2 + struct termios2 tio; +# else + struct termios tio; +# endif + int fd, rc; +\& + if (argc != 2 && argc != 3 && argc != 4) { + fprintf(stderr, "Usage: %s device [output [input] ]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY); + if (fd < 0) { + perror("open"); + exit(EXIT_FAILURE); + } +\& + /* Get the current serial port settings via supported ioctl */ +# if defined TCGETS2 + rc = ioctl(fd, TCGETS2, &tio); +# else + rc = ioctl(fd, TCGETS, &tio); +# endif + if (rc) { + perror("TCGETS"); + close(fd); + exit(EXIT_FAILURE); + } +\& + /* Change baud rate when more arguments were provided */ + if (argc == 3 || argc == 4) { + /* Clear the current output baud rate and fill a new value */ + tio.c_cflag &= \[ti]CBAUD; + tio.c_cflag |= BOTHER; + tio.c_ospeed = atoi(argv[2]); +\& + /* Clear the current input baud rate and fill a new value */ + tio.c_cflag &= \[ti](CBAUD << IBSHIFT); + tio.c_cflag |= BOTHER << IBSHIFT; + /* When 4th argument is not provided reuse output baud rate */ + tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]); +\& + /* Set new serial port settings via supported ioctl */ +# if defined TCSETS2 + rc = ioctl(fd, TCSETS2, &tio); +# else + rc = ioctl(fd, TCSETS, &tio); +# endif + if (rc) { + perror("TCSETS"); + close(fd); + exit(EXIT_FAILURE); + } +\& + /* And get new values which were really configured */ +# if defined TCGETS2 + rc = ioctl(fd, TCGETS2, &tio); +# else + rc = ioctl(fd, TCGETS, &tio); +# endif + if (rc) { + perror("TCGETS"); + close(fd); + exit(EXIT_FAILURE); + } + } +\& + close(fd); +\& + printf("output baud rate: %u\en", tio.c_ospeed); + printf("input baud rate: %u\en", tio.c_ispeed); +\& + exit(EXIT_SUCCESS); +#endif +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ldattach (8), +.BR ioctl (2), +.BR ioctl_console (2), +.BR termios (3), +.BR pty (7) +.\" +.\" FIONBIO const int * +.\" FIONCLEX void +.\" FIOCLEX void +.\" FIOASYNC const int * +.\" from serial.c: +.\" TIOCSERCONFIG void +.\" TIOCSERGWILD int * +.\" TIOCSERSWILD const int * +.\" TIOCSERGSTRUCT struct async_struct * +.\" TIOCSERGETMULTI struct serial_multiport_struct * +.\" TIOCSERSETMULTI const struct serial_multiport_struct * +.\" TIOCGSERIAL, TIOCSSERIAL (see above) diff --git a/man/man2/ioctl_userfaultfd.2 b/man/man2/ioctl_userfaultfd.2 new file mode 100644 index 0000000..2d24130 --- /dev/null +++ b/man/man2/ioctl_userfaultfd.2 @@ -0,0 +1,1072 @@ +.\" Copyright (c) 2016, IBM Corporation. +.\" Written by Mike Rapoport +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH ioctl_userfaultfd 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioctl_userfaultfd \- create a file descriptor for handling page faults in user +space +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " UFFD* " constants */" +.B #include +.P +.BI "int ioctl(int " fd ", int " op ", ...);" +.fi +.SH DESCRIPTION +Various +.BR ioctl (2) +operations can be performed on a userfaultfd object (created by a call to +.BR userfaultfd (2)) +using calls of the form: +.P +.in +4n +.EX +ioctl(fd, op, argp); +.EE +.in +.P +In the above, +.I fd +is a file descriptor referring to a userfaultfd object, +.I op +is one of the operations listed below, and +.I argp +is a pointer to a data structure that is specific to +.IR op . +.P +The various +.BR ioctl (2) +operations are described below. +The +.BR UFFDIO_API , +.BR UFFDIO_REGISTER , +and +.B UFFDIO_UNREGISTER +operations are used to +.I configure +userfaultfd behavior. +These operations allow the caller to choose what features will be enabled and +what kinds of events will be delivered to the application. +The remaining operations are +.I range +operations. +These operations enable the calling application to resolve page-fault +events. +.\" +.SS UFFDIO_API +(Since Linux 4.3.) +Enable operation of the userfaultfd and perform API handshake. +.P +The +.I argp +argument is a pointer to a +.I uffdio_api +structure, defined as: +.P +.in +4n +.EX +struct uffdio_api { + __u64 api; /* Requested API version (input) */ + __u64 features; /* Requested features (input/output) */ + __u64 ioctls; /* Available ioctl() operations (output) */ +}; +.EE +.in +.P +The +.I api +field denotes the API version requested by the application. +The kernel verifies that it can support the requested API version, +and sets the +.I features +and +.I ioctls +fields to bit masks representing all the available features and the generic +.BR ioctl (2) +operations available. +.P +Since Linux 4.11, +applications should use the +.I features +field to perform a two-step handshake. +First, +.B UFFDIO_API +is called with the +.I features +field set to zero. +The kernel responds by setting all supported feature bits. +.P +Applications which do not require any specific features +can begin using the userfaultfd immediately. +Applications which do need specific features +should call +.B UFFDIO_API +again with a subset of the reported feature bits set +to enable those features. +.P +Before Linux 4.11, the +.I features +field must be initialized to zero before the call to +.BR UFFDIO_API , +and zero (i.e., no feature bits) is placed in the +.I features +field by the kernel upon return from +.BR ioctl (2). +.P +If the application sets unsupported feature bits, +the kernel will zero out the returned +.I uffdio_api +structure and return +.BR EINVAL . +.P +The following feature bits may be set: +.TP +.BR UFFD_FEATURE_EVENT_FORK " (since Linux 4.11)" +When this feature is enabled, +the userfaultfd objects associated with a parent process are duplicated +into the child process during +.BR fork (2) +and a +.B UFFD_EVENT_FORK +event is delivered to the userfaultfd monitor +.TP +.BR UFFD_FEATURE_EVENT_REMAP " (since Linux 4.11)" +If this feature is enabled, +when the faulting process invokes +.BR mremap (2), +the userfaultfd monitor will receive an event of type +.BR UFFD_EVENT_REMAP . +.TP +.BR UFFD_FEATURE_EVENT_REMOVE " (since Linux 4.11)" +If this feature is enabled, +when the faulting process calls +.BR madvise (2) +with the +.B MADV_DONTNEED +or +.B MADV_REMOVE +advice value to free a virtual memory area +the userfaultfd monitor will receive an event of type +.BR UFFD_EVENT_REMOVE . +.TP +.BR UFFD_FEATURE_EVENT_UNMAP " (since Linux 4.11)" +If this feature is enabled, +when the faulting process unmaps virtual memory either explicitly with +.BR munmap (2), +or implicitly during either +.BR mmap (2) +or +.BR mremap (2), +the userfaultfd monitor will receive an event of type +.BR UFFD_EVENT_UNMAP . +.TP +.BR UFFD_FEATURE_MISSING_HUGETLBFS " (since Linux 4.11)" +If this feature bit is set, +the kernel supports registering userfaultfd ranges on hugetlbfs +virtual memory areas +.TP +.BR UFFD_FEATURE_MISSING_SHMEM " (since Linux 4.11)" +If this feature bit is set, +the kernel supports registering userfaultfd ranges on shared memory areas. +This includes all kernel shared memory APIs: +System V shared memory, +.BR tmpfs (5), +shared mappings of +.IR /dev/zero , +.BR mmap (2) +with the +.B MAP_SHARED +flag set, +.BR memfd_create (2), +and so on. +.TP +.BR UFFD_FEATURE_SIGBUS " (since Linux 4.14)" +.\" commit 2d6d6f5a09a96cc1fec7ed992b825e05f64cb50e +If this feature bit is set, no page-fault events +.RB ( UFFD_EVENT_PAGEFAULT ) +will be delivered. +Instead, a +.B SIGBUS +signal will be sent to the faulting process. +Applications using this +feature will not require the use of a userfaultfd monitor for processing +memory accesses to the regions registered with userfaultfd. +.TP +.BR UFFD_FEATURE_THREAD_ID " (since Linux 4.14)" +If this feature bit is set, +.I uffd_msg.pagefault.feat.ptid +will be set to the faulted thread ID for each page-fault message. +.TP +.BR UFFD_FEATURE_PAGEFAULT_FLAG_WP " (since Linux 5.10)" +If this feature bit is set, +userfaultfd supports write-protect faults +for anonymous memory. +(Note that shmem / hugetlbfs support +is indicated by a separate feature.) +.TP +.BR UFFD_FEATURE_MINOR_HUGETLBFS " (since Linux 5.13)" +If this feature bit is set, +the kernel supports registering userfaultfd ranges +in minor mode on hugetlbfs-backed memory areas. +.TP +.BR UFFD_FEATURE_MINOR_SHMEM " (since Linux 5.14)" +If this feature bit is set, +the kernel supports registering userfaultfd ranges +in minor mode on shmem-backed memory areas. +.TP +.BR UFFD_FEATURE_EXACT_ADDRESS " (since Linux 5.18)" +If this feature bit is set, +.I uffd_msg.pagefault.address +will be set to the exact page-fault address that was reported by the hardware, +and will not mask the offset within the page. +Note that old Linux versions might indicate the exact address as well, +even though the feature bit is not set. +.TP +.BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM " (since Linux 5.19)" +If this feature bit is set, +userfaultfd supports write-protect faults +for hugetlbfs and shmem / tmpfs memory. +.TP +.BR UFFD_FEATURE_WP_UNPOPULATED " (since Linux 6.4)" +If this feature bit is set, +the kernel will handle anonymous memory the same way as file memory, +by allowing the user to write-protect unpopulated page table entries. +.TP +.BR UFFD_FEATURE_POISON " (since Linux 6.6)" +If this feature bit is set, +the kernel supports resolving faults with the +.B UFFDIO_POISON +ioctl. +.TP +.BR UFFD_FEATURE_WP_ASYNC " (since Linux 6.7)" +If this feature bit is set, +the write protection faults would be asynchronously resolved +by the kernel. +.P +The returned +.I ioctls +field can contain the following bits: +.\" FIXME This user-space API seems not fully polished. Why are there +.\" not constants defined for each of the bit-mask values listed below? +.TP +.B 1 << _UFFDIO_API +The +.B UFFDIO_API +operation is supported. +.TP +.B 1 << _UFFDIO_REGISTER +The +.B UFFDIO_REGISTER +operation is supported. +.TP +.B 1 << _UFFDIO_UNREGISTER +The +.B UFFDIO_UNREGISTER +operation is supported. +.P +This +.BR ioctl (2) +operation returns 0 on success. +On error, \-1 is returned and +.I errno +is set to indicate the error. +If an error occurs, +the kernel may zero the provided +.I uffdio_api +structure. +The caller should treat its contents as unspecified, +and reinitialize it before re-attempting another +.B UFFDIO_API +call. +Possible errors include: +.TP +.B EFAULT +.I argp +refers to an address that is outside the calling process's +accessible address space. +.TP +.B EINVAL +The API version requested in the +.I api +field is not supported by this kernel, or the +.I features +field passed to the kernel includes feature bits that are not supported +by the current kernel version. +.TP +.B EINVAL +A previous +.B UFFDIO_API +call already enabled one or more features for this userfaultfd. +Calling +.B UFFDIO_API +twice, +the first time with no features set, +is explicitly allowed +as per the two-step feature detection handshake. +.TP +.B EPERM +The +.B UFFD_FEATURE_EVENT_FORK +feature was enabled, +but the calling process doesn't have the +.B CAP_SYS_PTRACE +capability. +.SS UFFDIO_REGISTER +(Since Linux 4.3.) +Register a memory address range with the userfaultfd object. +The pages in the range must be \[lq]compatible\[rq]. +Please refer to the list of register modes below +for the compatible memory backends for each mode. +.P +The +.I argp +argument is a pointer to a +.I uffdio_register +structure, defined as: +.P +.in +4n +.EX +struct uffdio_range { + __u64 start; /* Start of range */ + __u64 len; /* Length of range (bytes) */ +}; +\& +struct uffdio_register { + struct uffdio_range range; + __u64 mode; /* Desired mode of operation (input) */ + __u64 ioctls; /* Available ioctl() operations (output) */ +}; +.EE +.in +.P +The +.I range +field defines a memory range starting at +.I start +and continuing for +.I len +bytes that should be handled by the userfaultfd. +.P +The +.I mode +field defines the mode of operation desired for this memory region. +The following values may be bitwise ORed to set the userfaultfd mode for +the specified range: +.TP +.B UFFDIO_REGISTER_MODE_MISSING +Track page faults on missing pages. +Since Linux 4.3, +only private anonymous ranges are compatible. +Since Linux 4.11, +hugetlbfs and shared memory ranges are also compatible. +.TP +.B UFFDIO_REGISTER_MODE_WP +Track page faults on write-protected pages. +Since Linux 5.7, +only private anonymous ranges are compatible. +.TP +.B UFFDIO_REGISTER_MODE_MINOR +Track minor page faults. +Since Linux 5.13, +only hugetlbfs ranges are compatible. +Since Linux 5.14, +compatibility with shmem ranges was added. +.P +If the operation is successful, the kernel modifies the +.I ioctls +bit-mask field to indicate which +.BR ioctl (2) +operations are available for the specified range. +This returned bit mask can contain the following bits: +.TP +.B 1 << _UFFDIO_COPY +The +.B UFFDIO_COPY +operation is supported. +.TP +.B 1 << _UFFDIO_WAKE +The +.B UFFDIO_WAKE +operation is supported. +.TP +.B 1 << _UFFDIO_WRITEPROTECT +The +.B UFFDIO_WRITEPROTECT +operation is supported. +.TP +.B 1 << _UFFDIO_ZEROPAGE +The +.B UFFDIO_ZEROPAGE +operation is supported. +.TP +.B 1 << _UFFDIO_CONTINUE +The +.B UFFDIO_CONTINUE +operation is supported. +.TP +.B 1 << _UFFDIO_POISON +The +.B UFFDIO_POISON +operation is supported. +.P +This +.BR ioctl (2) +operation returns 0 on success. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.\" FIXME Is the following error list correct? +.\" +.TP +.B EBUSY +A mapping in the specified range is registered with another +userfaultfd object. +.TP +.B EFAULT +.I argp +refers to an address that is outside the calling process's +accessible address space. +.TP +.B EINVAL +An invalid or unsupported bit was specified in the +.I mode +field; or the +.I mode +field was zero. +.TP +.B EINVAL +There is no mapping in the specified address range. +.TP +.B EINVAL +.I range.start +or +.I range.len +is not a multiple of the system page size; or, +.I range.len +is zero; or these fields are otherwise invalid. +.TP +.B EINVAL +There as an incompatible mapping in the specified address range. +.\" Mike Rapoport: +.\" ENOMEM if the process is exiting and the +.\" mm_struct has gone by the time userfault grabs it. +.SS UFFDIO_UNREGISTER +(Since Linux 4.3.) +Unregister a memory address range from userfaultfd. +The pages in the range must be \[lq]compatible\[rq] +(see the description of +.BR UFFDIO_REGISTER .) +.P +The address range to unregister is specified in the +.I uffdio_range +structure pointed to by +.IR argp . +.P +This +.BR ioctl (2) +operation returns 0 on success. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.TP +.B EINVAL +Either the +.I start +or the +.I len +field of the +.I ufdio_range +structure was not a multiple of the system page size; or the +.I len +field was zero; or these fields were otherwise invalid. +.TP +.B EINVAL +There as an incompatible mapping in the specified address range. +.TP +.B EINVAL +There was no mapping in the specified address range. +.\" +.SS UFFDIO_COPY +(Since Linux 4.3.) +Atomically copy a continuous memory chunk into the userfault registered +range and optionally wake up the blocked thread. +The source and destination addresses and the number of bytes to copy are +specified by the +.IR src , +.IR dst , +and +.I len +fields of the +.I uffdio_copy +structure pointed to by +.IR argp : +.P +.in +4n +.EX +struct uffdio_copy { + __u64 dst; /* Destination of copy */ + __u64 src; /* Source of copy */ + __u64 len; /* Number of bytes to copy */ + __u64 mode; /* Flags controlling behavior of copy */ + __s64 copy; /* Number of bytes copied, or negated error */ +}; +.EE +.in +.P +The following value may be bitwise ORed in +.I mode +to change the behavior of the +.B UFFDIO_COPY +operation: +.TP +.B UFFDIO_COPY_MODE_DONTWAKE +Do not wake up the thread that waits for page-fault resolution +.TP +.B UFFDIO_COPY_MODE_WP +Copy the page with read-only permission. +This allows the user to trap the next write to the page, +which will block and generate another write-protect userfault message. +This is used only when both +.B UFFDIO_REGISTER_MODE_MISSING +and +.B UFFDIO_REGISTER_MODE_WP +modes are enabled for the registered range. +.P +The +.I copy +field is used by the kernel to return the number of bytes +that was actually copied, or an error (a negated +.IR errno -style +value). +.\" FIXME Above: Why is the 'copy' field used to return error values? +.\" This should be explained in the manual page. +If the value returned in +.I copy +doesn't match the value that was specified in +.IR len , +the operation fails with the error +.BR EAGAIN . +The +.I copy +field is output-only; +it is not read by the +.B UFFDIO_COPY +operation. +.P +This +.BR ioctl (2) +operation returns 0 on success. +In this case, the entire area was copied. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.TP +.B EAGAIN +The number of bytes copied (i.e., the value returned in the +.I copy +field) +does not equal the value that was specified in the +.I len +field. +.TP +.B EINVAL +Either +.I dst +or +.I len +was not a multiple of the system page size, or the range specified by +.I src +and +.I len +or +.I dst +and +.I len +was invalid. +.TP +.B EINVAL +An invalid bit was specified in the +.I mode +field. +.TP +.BR ENOENT " (since Linux 4.11)" +The faulting process has changed +its virtual memory layout simultaneously with an outstanding +.B UFFDIO_COPY +operation. +.TP +.BR ENOSPC " (from Linux 4.11 until Linux 4.13)" +The faulting process has exited at the time of a +.B UFFDIO_COPY +operation. +.TP +.BR ESRCH " (since Linux 4.13)" +The faulting process has exited at the time of a +.B UFFDIO_COPY +operation. +.\" +.SS UFFDIO_ZEROPAGE +(Since Linux 4.3.) +Zero out a memory range registered with userfaultfd. +.P +The requested range is specified by the +.I range +field of the +.I uffdio_zeropage +structure pointed to by +.IR argp : +.P +.in +4n +.EX +struct uffdio_zeropage { + struct uffdio_range range; + __u64 mode; /* Flags controlling behavior of copy */ + __s64 zeropage; /* Number of bytes zeroed, or negated error */ +}; +.EE +.in +.P +The following value may be bitwise ORed in +.I mode +to change the behavior of the +.B UFFDIO_ZEROPAGE +operation: +.TP +.B UFFDIO_ZEROPAGE_MODE_DONTWAKE +Do not wake up the thread that waits for page-fault resolution. +.P +The +.I zeropage +field is used by the kernel to return the number of bytes +that was actually zeroed, +or an error in the same manner as +.BR UFFDIO_COPY . +.\" FIXME Why is the 'zeropage' field used to return error values? +.\" This should be explained in the manual page. +If the value returned in the +.I zeropage +field doesn't match the value that was specified in +.IR range.len , +the operation fails with the error +.BR EAGAIN . +The +.I zeropage +field is output-only; +it is not read by the +.B UFFDIO_ZEROPAGE +operation. +.P +This +.BR ioctl (2) +operation returns 0 on success. +In this case, the entire area was zeroed. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.TP +.B EAGAIN +The number of bytes zeroed (i.e., the value returned in the +.I zeropage +field) +does not equal the value that was specified in the +.I range.len +field. +.TP +.B EINVAL +Either +.I range.start +or +.I range.len +was not a multiple of the system page size; or +.I range.len +was zero; or the range specified was invalid. +.TP +.B EINVAL +An invalid bit was specified in the +.I mode +field. +.TP +.BR ESRCH " (since Linux 4.13)" +The faulting process has exited at the time of a +.B UFFDIO_ZEROPAGE +operation. +.\" +.SS UFFDIO_WAKE +(Since Linux 4.3.) +Wake up the thread waiting for page-fault resolution on +a specified memory address range. +.P +The +.B UFFDIO_WAKE +operation is used in conjunction with +.B UFFDIO_COPY +and +.B UFFDIO_ZEROPAGE +operations that have the +.B UFFDIO_COPY_MODE_DONTWAKE +or +.B UFFDIO_ZEROPAGE_MODE_DONTWAKE +bit set in the +.I mode +field. +The userfault monitor can perform several +.B UFFDIO_COPY +and +.B UFFDIO_ZEROPAGE +operations in a batch and then explicitly wake up the faulting thread using +.BR UFFDIO_WAKE . +.P +The +.I argp +argument is a pointer to a +.I uffdio_range +structure (shown above) that specifies the address range. +.P +This +.BR ioctl (2) +operation returns 0 on success. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.TP +.B EINVAL +The +.I start +or the +.I len +field of the +.I ufdio_range +structure was not a multiple of the system page size; or +.I len +was zero; or the specified range was otherwise invalid. +.SS UFFDIO_WRITEPROTECT +(Since Linux 5.7.) +Write-protect or write-unprotect a userfaultfd-registered memory range +registered with mode +.BR UFFDIO_REGISTER_MODE_WP . +.P +The +.I argp +argument is a pointer to a +.I uffdio_range +structure as shown below: +.P +.in +4n +.EX +struct uffdio_writeprotect { + struct uffdio_range range; /* Range to change write permission*/ + __u64 mode; /* Mode to change write permission */ +}; +.EE +.in +.P +There are two mode bits that are supported in this structure: +.TP +.B UFFDIO_WRITEPROTECT_MODE_WP +When this mode bit is set, +the ioctl will be a write-protect operation upon the memory range specified by +.IR range . +Otherwise it will be a write-unprotect operation upon the specified range, +which can be used to resolve a userfaultfd write-protect page fault. +.TP +.B UFFDIO_WRITEPROTECT_MODE_DONTWAKE +When this mode bit is set, +do not wake up any thread that waits for +page-fault resolution after the operation. +This can be specified only if +.B UFFDIO_WRITEPROTECT_MODE_WP +is not specified. +.P +This +.BR ioctl (2) +operation returns 0 on success. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.TP +.B EINVAL +The +.I start +or the +.I len +field of the +.I ufdio_range +structure was not a multiple of the system page size; or +.I len +was zero; or the specified range was otherwise invalid. +.TP +.B EAGAIN +The process was interrupted; retry this call. +.TP +.B ENOENT +The range specified in +.I range +is not valid. +For example, the virtual address does not exist, +or not registered with userfaultfd write-protect mode. +.TP +.B EFAULT +Encountered a generic fault during processing. +.\" +.SS UFFDIO_CONTINUE +(Since Linux 5.13.) +Resolve a minor page fault +by installing page table entries +for existing pages in the page cache. +.P +The +.I argp +argument is a pointer to a +.I uffdio_continue +structure as shown below: +.P +.in +4n +.EX +struct uffdio_continue { + struct uffdio_range range; + /* Range to install PTEs for and continue */ + __u64 mode; /* Flags controlling the behavior of continue */ + __s64 mapped; /* Number of bytes mapped, or negated error */ +}; +.EE +.in +.P +The following value may be bitwise ORed in +.I mode +to change the behavior of the +.B UFFDIO_CONTINUE +operation: +.TP +.B UFFDIO_CONTINUE_MODE_DONTWAKE +Do not wake up the thread that waits for page-fault resolution. +.P +The +.I mapped +field is used by the kernel +to return the number of bytes that were actually mapped, +or an error in the same manner as +.BR UFFDIO_COPY . +If the value returned in the +.I mapped +field doesn't match the value that was specified in +.IR range.len , +the operation fails with the error +.BR EAGAIN . +The +.I mapped +field is output-only; +it is not read by the +.B UFFDIO_CONTINUE +operation. +.P +This +.BR ioctl (2) +operation returns 0 on success. +In this case, +the entire area was mapped. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.TP +.B EAGAIN +The number of bytes mapped +(i.e., the value returned in the +.I mapped +field) +does not equal the value that was specified in the +.I range.len +field. +.TP +.B EEXIST +One or more pages were already mapped in the given range. +.TP +.B EFAULT +No existing page could be found in the page cache for the given range. +.TP +.B EINVAL +Either +.I range.start +or +.I range.len +was not a multiple of the system page size; or +.I range.len +was zero; or the range specified was invalid. +.TP +.B EINVAL +An invalid bit was specified in the +.I mode +field. +.TP +.B ENOENT +The faulting process has changed its virtual memory layout simultaneously with +an outstanding +.B UFFDIO_CONTINUE +operation. +.TP +.B ENOMEM +Allocating memory needed to setup the page table mappings failed. +.TP +.B ESRCH +The faulting process has exited at the time of a +.B UFFDIO_CONTINUE +operation. +.\" +.SS UFFDIO_POISON +(Since Linux 6.6.) +Mark an address range as "poisoned". +Future accesses to these addresses will raise a +.B SIGBUS +signal. +Unlike +.B MADV_HWPOISON +this works by installing page table entries, +rather than "really" poisoning the underlying physical pages. +This means it only affects this particular address space. +.P +The +.I argp +argument is a pointer to a +.I uffdio_poison +structure as shown below: +.P +.in +4n +.EX +struct uffdio_poison { + struct uffdio_range range; + /* Range to install poison PTE markers in */ + __u64 mode; /* Flags controlling the behavior of poison */ + __s64 updated; /* Number of bytes poisoned, or negated error */ +}; +.EE +.in +.P +The following value may be bitwise ORed in +.I mode +to change the behavior of the +.B UFFDIO_POISON +operation: +.TP +.B UFFDIO_POISON_MODE_DONTWAKE +Do not wake up the thread that waits for page-fault resolution. +.P +The +.I updated +field is used by the kernel +to return the number of bytes that were actually poisoned, +or an error in the same manner as +.BR UFFDIO_COPY . +If the value returned in the +.I updated +field doesn't match the value that was specified in +.IR range.len , +the operation fails with the error +.BR EAGAIN . +The +.I updated +field is output-only; +it is not read by the +.B UFFDIO_POISON +operation. +.P +This +.BR ioctl (2) +operation returns 0 on success. +In this case, +the entire area was poisoned. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.TP +.B EAGAIN +The number of bytes mapped +(i.e., the value returned in the +.I updated +field) +does not equal the value that was specified in the +.I range.len +field. +.TP +.B EINVAL +Either +.I range.start +or +.I range.len +was not a multiple of the system page size; or +.I range.len +was zero; or the range specified was invalid. +.TP +.B EINVAL +An invalid bit was specified in the +.I mode +field. +.TP +.B EEXIST +One or more pages were already mapped in the given range. +.TP +.B ENOENT +The faulting process has changed its virtual memory layout simultaneously with +an outstanding +.B UFFDIO_POISON +operation. +.TP +.B ENOMEM +Allocating memory for page table entries failed. +.TP +.B ESRCH +The faulting process has exited at the time of a +.B UFFDIO_POISON +operation. +.\" +.SH RETURN VALUE +See descriptions of the individual operations, above. +.SH ERRORS +See descriptions of the individual operations, above. +In addition, the following general errors can occur for all of the +operations described above: +.TP +.B EFAULT +.I argp +does not point to a valid memory address. +.TP +.B EINVAL +(For all operations except +.BR UFFDIO_API .) +The userfaultfd object has not yet been enabled (via the +.B UFFDIO_API +operation). +.SH STANDARDS +Linux. +.SH BUGS +In order to detect available userfault features and +enable some subset of those features +the userfaultfd file descriptor must be closed after the first +.B UFFDIO_API +operation that queries features availability and reopened before +the second +.B UFFDIO_API +operation that actually enables the desired features. +.SH EXAMPLES +See +.BR userfaultfd (2). +.SH SEE ALSO +.BR ioctl (2), +.BR mmap (2), +.BR userfaultfd (2) +.P +.I Documentation/admin\-guide/mm/userfaultfd.rst +in the Linux kernel source tree diff --git a/man/man2/ioperm.2 b/man/man2/ioperm.2 new file mode 100644 index 0000000..1378dbd --- /dev/null +++ b/man/man2/ioperm.2 @@ -0,0 +1,105 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 15:12:05 1993 by Rik Faith +.\" Modified Tue Aug 1 16:27 1995 by Jochen Karrer +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified Mon Feb 15 17:28:41 CET 1999 by Andries E. Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH ioperm 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioperm \- set port input/output permissions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int ioperm(unsigned long " from ", unsigned long " num ", int " turn_on ); +.fi +.SH DESCRIPTION +.BR ioperm () +sets the port access permission bits for the calling thread for +.I num +bits starting from port address +.IR from . +If +.I turn_on +is nonzero, then permission for the specified bits is enabled; +otherwise it is disabled. +If +.I turn_on +is nonzero, the calling thread must be privileged +.RB ( CAP_SYS_RAWIO ). +.P +Before Linux 2.6.8, +only the first 0x3ff I/O ports could be specified in this manner. +For more ports, the +.BR iopl (2) +system call had to be used (with a +.I level +argument of 3). +Since Linux 2.6.8, 65,536 I/O ports can be specified. +.P +Permissions are inherited by the child created by +.BR fork (2) +(but see NOTES). +Permissions are preserved across +.BR execve (2); +this is useful for giving port access permissions to unprivileged +programs. +.P +This call is mostly for the i386 architecture. +On many other architectures it does not exist or will always +return an error. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Invalid values for +.I from +or +.IR num . +.TP +.B EIO +(on PowerPC) This call is not supported. +.TP +.B ENOMEM +.\" Could not allocate I/O bitmap. +Out of memory. +.TP +.B EPERM +The calling thread has insufficient privilege. +.SH VERSIONS +glibc has an +.BR ioperm () +prototype both in +.I +and in +.IR . +Avoid the latter, it is available on i386 only. +.SH STANDARDS +Linux. +.SH HISTORY +Before Linux 2.4, +permissions were not inherited by a child created by +.BR fork (2). +.SH NOTES +The +.I /proc/ioports +file shows the I/O ports that are currently allocated on the system. +.SH SEE ALSO +.BR iopl (2), +.BR outb (2), +.BR capabilities (7) diff --git a/man/man2/iopl.2 b/man/man2/iopl.2 new file mode 100644 index 0000000..2a566fb --- /dev/null +++ b/man/man2/iopl.2 @@ -0,0 +1,92 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from linux/kernel/ioport.c (no copyright notice). +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Tue Aug 1 16:47 1995 by Jochen Karrer +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified Fri Nov 27 14:50:36 CET 1998 by Andries Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH iopl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iopl \- change I/O privilege level +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int iopl(int " level ); +.fi +.SH DESCRIPTION +.BR iopl () +changes the I/O privilege level of the calling thread, +as specified by the two least significant bits in +.IR level . +.P +The I/O privilege level for a normal thread is 0. +Permissions are inherited from parents to children. +.P +This call is deprecated, is significantly slower than +.BR ioperm (2), +and is only provided for older X servers which require +access to all 65536 I/O ports. +It is mostly for the i386 architecture. +On many other architectures it does not exist or will always +return an error. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I level +is greater than 3. +.TP +.B ENOSYS +This call is unimplemented. +.TP +.B EPERM +The calling thread has insufficient privilege to call +.BR iopl (); +the +.B CAP_SYS_RAWIO +capability is required to raise the I/O privilege level +above its current value. +.SH VERSIONS +.\" Libc5 treats it as a system call and has a prototype in +.\" .IR . +.\" glibc1 does not have a prototype. +glibc2 has a prototype both in +.I +and in +.IR . +Avoid the latter, it is available on i386 only. +.SH STANDARDS +Linux. +.SH HISTORY +Prior to Linux 5.5 +.BR iopl () +allowed the thread to disable interrupts while running +at a higher I/O privilege level. +This will probably crash the system, and is not recommended. +.P +Prior to Linux 3.7, +on some architectures (such as i386), permissions +.I were +inherited by the child produced by +.BR fork (2) +and were preserved across +.BR execve (2). +This behavior was inadvertently changed in Linux 3.7, +and won't be reinstated. +.SH SEE ALSO +.BR ioperm (2), +.BR outb (2), +.BR capabilities (7) diff --git a/man/man2/ioprio_get.2 b/man/man2/ioprio_get.2 new file mode 100644 index 0000000..d6d5b3b --- /dev/null +++ b/man/man2/ioprio_get.2 @@ -0,0 +1 @@ +.so man2/ioprio_set.2 diff --git a/man/man2/ioprio_set.2 b/man/man2/ioprio_set.2 new file mode 100644 index 0000000..ae744ba --- /dev/null +++ b/man/man2/ioprio_set.2 @@ -0,0 +1,362 @@ +.\" Copyright (c) International Business Machines orp., 2006 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" HISTORY: +.\" 2006-04-27, created by Eduardo M. Fleury +.\" with various additions by Michael Kerrisk +.\" +.\" +.TH ioprio_set 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ioprio_get, ioprio_set \- get/set I/O scheduling class and priority +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " "/* Definition of " IOPRIO_* " constants */" +.BR "#include " "/* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_ioprio_get, int " which ", int " who ); +.BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio ); +.fi +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR ioprio_get () +and +.BR ioprio_set () +system calls get and set the I/O scheduling class and +priority of one or more threads. +.P +The +.I which +and +.I who +arguments identify the thread(s) on which the system +calls operate. +The +.I which +argument determines how +.I who +is interpreted, and has one of the following values: +.TP +.B IOPRIO_WHO_PROCESS +.I who +is a process ID or thread ID identifying a single process or thread. +If +.I who +is 0, then operate on the calling thread. +.TP +.B IOPRIO_WHO_PGRP +.I who +is a process group ID identifying all the members of a process group. +If +.I who +is 0, then operate on the process group of which the caller is a member. +.TP +.B IOPRIO_WHO_USER +.I who +is a user ID identifying all of the processes that +have a matching real UID. +.\" FIXME . Need to document the behavior when 'who" is specified as 0 +.\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443 +.P +If +.I which +is specified as +.B IOPRIO_WHO_PGRP +or +.B IOPRIO_WHO_USER +when calling +.BR ioprio_get (), +and more than one process matches +.IR who , +then the returned priority will be the highest one found among +all of the matching processes. +One priority is said to be +higher than another one if it belongs to a higher priority +class +.RB ( IOPRIO_CLASS_RT +is the highest priority class; +.B IOPRIO_CLASS_IDLE +is the lowest) +or if it belongs to the same priority class as the other process but +has a higher priority level (a lower priority number means a +higher priority level). +.P +The +.I ioprio +argument given to +.BR ioprio_set () +is a bit mask that specifies both the scheduling class and the +priority to be assigned to the target process(es). +The following macros are used for assembling and dissecting +.I ioprio +values: +.TP +.BI IOPRIO_PRIO_VALUE( class ", " data ) +Given a scheduling +.I class +and priority +.RI ( data ), +this macro combines the two values to produce an +.I ioprio +value, which is returned as the result of the macro. +.TP +.BI IOPRIO_PRIO_CLASS( mask ) +Given +.I mask +(an +.I ioprio +value), this macro returns its I/O class component, that is, +one of the values +.BR IOPRIO_CLASS_RT , +.BR IOPRIO_CLASS_BE , +or +.BR IOPRIO_CLASS_IDLE . +.TP +.BI IOPRIO_PRIO_DATA( mask ) +Given +.I mask +(an +.I ioprio +value), this macro returns its priority +.RI ( data ) +component. +.P +See the NOTES section for more +information on scheduling classes and priorities, +as well as the meaning of specifying +.I ioprio +as 0. +.P +I/O priorities are supported for reads and for synchronous +.RB ( O_DIRECT , +.BR O_SYNC ) +writes. +I/O priorities are not supported for asynchronous +writes because they are issued outside the context of the program +dirtying the memory, and thus program-specific priorities do not apply. +.SH RETURN VALUE +On success, +.BR ioprio_get () +returns the +.I ioprio +value of the process with highest I/O priority of any of the processes +that match the criteria specified in +.I which +and +.IR who . +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +On success, +.BR ioprio_set () +returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Invalid value for +.I which +or +.IR ioprio . +Refer to the NOTES section for available scheduler +classes and priority levels for +.IR ioprio . +.TP +.B EPERM +The calling process does not have the privilege needed to assign this +.I ioprio +to the specified process(es). +See the NOTES section for more information on required +privileges for +.BR ioprio_set (). +.TP +.B ESRCH +No process(es) could be found that matched the specification in +.I which +and +.IR who . +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.13. +.SH NOTES +Two or more processes or threads can share an I/O context. +This will be the case when +.BR clone (2) +was called with the +.B CLONE_IO +flag. +However, by default, the distinct threads of a process will +.B not +share the same I/O context. +This means that if you want to change the I/O +priority of all threads in a process, you may need to call +.BR ioprio_set () +on each of the threads. +The thread ID that you would need for this operation +is the one that is returned by +.BR gettid (2) +or +.BR clone (2). +.P +These system calls have an effect only when used +in conjunction with an I/O scheduler that supports I/O priorities. +As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing +(CFQ) I/O scheduler. +.P +If no I/O scheduler has been set for a thread, +then by default the I/O priority will follow the CPU nice value +.RB ( setpriority (2)). +Before Linux 2.6.24, +once an I/O priority had been set using +.BR ioprio_set (), +there was no way to reset the I/O scheduling behavior to the default. +Since Linux 2.6.24, +.\" commit 8ec680e4c3ec818efd1652f15199ed1c216ab550 +specifying +.I ioprio +as 0 can be used to reset to the default I/O scheduling behavior. +.SS Selecting an I/O scheduler +I/O schedulers are selected on a per-device basis via the special +file +.IR /sys/block/ device /queue/scheduler . +.P +One can view the current I/O scheduler via the +.I /sys +filesystem. +For example, the following command +displays a list of all schedulers currently loaded in the kernel: +.P +.in +4n +.EX +.RB "$" " cat /sys/block/sda/queue/scheduler" +noop anticipatory deadline [cfq] +.EE +.in +.P +The scheduler surrounded by brackets is the one actually +in use for the device +.RI ( sda +in the example). +Setting another scheduler is done by writing the name of the +new scheduler to this file. +For example, the following command will set the +scheduler for the +.I sda +device to +.IR cfq : +.P +.in +4n +.EX +.RB "$" " su" +Password: +.RB "#" " echo cfq > /sys/block/sda/queue/scheduler" +.EE +.in +.\" +.SS The Completely Fair Queuing (CFQ) I/O scheduler +Since version 3 (also known as CFQ Time Sliced), CFQ implements +I/O nice levels similar to those +of CPU scheduling. +These nice levels are grouped into three scheduling classes, +each one containing one or more priority levels: +.TP +.BR IOPRIO_CLASS_RT " (1)" +This is the real-time I/O class. +This scheduling class is given +higher priority than any other class: +processes from this class are +given first access to the disk every time. +Thus, this I/O class needs to be used with some +care: one I/O real-time process can starve the entire system. +Within the real-time class, +there are 8 levels of class data (priority) that determine exactly +how much time this process needs the disk for on each service. +The highest real-time priority level is 0; the lowest is 7. +In the future, this might change to be more directly mappable to +performance, by passing in a desired data rate instead. +.TP +.BR IOPRIO_CLASS_BE " (2)" +This is the best-effort scheduling class, +which is the default for any process +that hasn't set a specific I/O priority. +The class data (priority) determines how much +I/O bandwidth the process will get. +Best-effort priority levels are analogous to CPU nice values +(see +.BR getpriority (2)). +The priority level determines a priority relative +to other processes in the best-effort scheduling class. +Priority levels range from 0 (highest) to 7 (lowest). +.TP +.BR IOPRIO_CLASS_IDLE " (3)" +This is the idle scheduling class. +Processes running at this level get I/O +time only when no one else needs the disk. +The idle class has no class data. +Attention is required when assigning this priority class to a process, +since it may become starved if higher priority processes are +constantly accessing the disk. +.P +Refer to the kernel source file +.I Documentation/block/ioprio.txt +for more information on the CFQ I/O Scheduler and an example program. +.SS Required permissions to set I/O priorities +Permission to change a process's priority is granted or denied based +on two criteria: +.TP +.B "Process ownership" +An unprivileged process may set the I/O priority only for a process +whose real UID +matches the real or effective UID of the calling process. +A process which has the +.B CAP_SYS_NICE +capability can change the priority of any process. +.TP +.B "What is the desired priority" +Attempts to set very high priorities +.RB ( IOPRIO_CLASS_RT ) +require the +.B CAP_SYS_ADMIN +capability. +Up to Linux 2.6.24 also required +.B CAP_SYS_ADMIN +to set a very low priority +.RB ( IOPRIO_CLASS_IDLE ), +but since Linux 2.6.25, this is no longer required. +.P +A call to +.BR ioprio_set () +must follow both rules, or the call will fail with the error +.BR EPERM . +.SH BUGS +.\" 6 May 07: Bug report raised: +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=4464 +.\" Ulrich Drepper replied that he wasn't going to add these +.\" to glibc. +glibc does not yet provide a suitable header file defining +the function prototypes and macros described on this page. +Suitable definitions can be found in +.IR linux/ioprio.h . +.SH SEE ALSO +.BR ionice (1), +.BR getpriority (2), +.BR open (2), +.BR capabilities (7), +.BR cgroups (7) +.P +.I Documentation/block/ioprio.txt +in the Linux kernel source tree diff --git a/man/man2/ipc.2 b/man/man2/ipc.2 new file mode 100644 index 0000000..120693d --- /dev/null +++ b/man/man2/ipc.2 @@ -0,0 +1,63 @@ +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.TH ipc 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ipc \- System V IPC system calls +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of needed constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_ipc, unsigned int " call ", int " first , +.BI " unsigned long " second ", unsigned long " third \ +", void *" ptr , +.BI " long " fifth ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR ipc (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR ipc () +is a common kernel entry point for the System\ V IPC calls +for messages, semaphores, and shared memory. +.I call +determines which IPC function to invoke; +the other arguments are passed through to the appropriate call. +.P +User-space programs should call the appropriate functions by their usual names. +Only standard library implementors and kernel hackers need to know about +.BR ipc (). +.SH VERSIONS +On some architectures\[em]for example x86-64 and ARM\[em]there is no +.BR ipc () +system call; instead, +.BR msgctl (2), +.BR semctl (2), +.BR shmctl (2), +and so on really are implemented as separate system calls. +.SH STANDARDS +Linux. +.SH SEE ALSO +.BR msgctl (2), +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR semctl (2), +.BR semget (2), +.BR semop (2), +.BR semtimedop (2), +.BR shmat (2), +.BR shmctl (2), +.BR shmdt (2), +.BR shmget (2), +.BR sysvipc (7) diff --git a/man/man2/isastream.2 b/man/man2/isastream.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/isastream.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/kcmp.2 b/man/man2/kcmp.2 new file mode 100644 index 0000000..0add272 --- /dev/null +++ b/man/man2/kcmp.2 @@ -0,0 +1,421 @@ +.\" Copyright (C) 2012, Cyrill Gorcunov +.\" and Copyright (C) 2012, 2016, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Kernel commit d97b46a64674a267bc41c9e16132ee2a98c3347d +.\" +.TH kcmp 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +kcmp \- compare two processes to determine if they share a kernel resource +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " KCMP_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_kcmp, pid_t " pid1 ", pid_t " pid2 ", int " type , +.BI " unsigned long " idx1 ", unsigned long " idx2 ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR kcmp (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR kcmp () +system call can be used to check whether the two processes identified by +.I pid1 +and +.I pid2 +share a kernel resource such as virtual memory, file descriptors, +and so on. +.P +Permission to employ +.BR kcmp () +is governed by ptrace access mode +.B PTRACE_MODE_READ_REALCREDS +checks against both +.I pid1 +and +.IR pid2 ; +see +.BR ptrace (2). +.P +The +.I type +argument specifies which resource is to be compared in the two processes. +It has one of the following values: +.TP +.B KCMP_FILE +Check whether a file descriptor +.I idx1 +in the process +.I pid1 +refers to the same open file description (see +.BR open (2)) +as file descriptor +.I idx2 +in the process +.IR pid2 . +The existence of two file descriptors that refer to the same +open file description can occur as a result of +.BR dup (2) +(and similar) +.BR fork (2), +or passing file descriptors via a domain socket (see +.BR unix (7)). +.TP +.B KCMP_FILES +Check whether the processes share the same set of open file descriptors. +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.B CLONE_FILES +flag in +.BR clone (2). +.TP +.B KCMP_FS +Check whether the processes share the same filesystem information +(i.e., file mode creation mask, working directory, and filesystem root). +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.B CLONE_FS +flag in +.BR clone (2). +.TP +.B KCMP_IO +Check whether the processes share I/O context. +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.B CLONE_IO +flag in +.BR clone (2). +.TP +.B KCMP_SIGHAND +Check whether the processes share the same table of signal dispositions. +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.B CLONE_SIGHAND +flag in +.BR clone (2). +.TP +.B KCMP_SYSVSEM +Check whether the processes share the same +list of System\ V semaphore undo operations. +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.B CLONE_SYSVSEM +flag in +.BR clone (2). +.TP +.B KCMP_VM +Check whether the processes share the same address space. +The arguments +.I idx1 +and +.I idx2 +are ignored. +See the discussion of the +.B CLONE_VM +flag in +.BR clone (2). +.TP +.BR KCMP_EPOLL_TFD " (since Linux 4.13)" +.\" commit 0791e3644e5ef21646fe565b9061788d05ec71d4 +Check whether the file descriptor +.I idx1 +of the process +.I pid1 +is present in the +.BR epoll (7) +instance described by +.I idx2 +of the process +.IR pid2 . +The argument +.I idx2 +is a pointer to a structure where the target file is described. +This structure has the form: +.P +.in +4n +.EX +struct kcmp_epoll_slot { + __u32 efd; + __u32 tfd; + __u64 toff; +}; +.EE +.in +.P +Within this structure, +.I efd +is an epoll file descriptor returned from +.BR epoll_create (2), +.I tfd +is a target file descriptor number, and +.I toff +is a target file offset counted from zero. +Several different targets may be registered with +the same file descriptor number and setting a specific +offset helps to investigate each of them. +.P +Note the +.BR kcmp () +is not protected against false positives which may occur if +the processes are currently running. +One should stop the processes by sending +.B SIGSTOP +(see +.BR signal (7)) +prior to inspection with this system call to obtain meaningful results. +.SH RETURN VALUE +The return value of a successful call to +.BR kcmp () +is simply the result of arithmetic comparison +of kernel pointers (when the kernel compares resources, it uses their +memory addresses). +.P +The easiest way to explain is to consider an example. +Suppose that +.I v1 +and +.I v2 +are the addresses of appropriate resources, then the return value +is one of the following: +.RS +.TP +.B 0 +.I v1 +is equal to +.IR v2 ; +in other words, the two processes share the resource. +.TP +.B 1 +.I v1 +is less than +.IR v2 . +.TP +.B 2 +.I v1 +is greater than +.IR v2 . +.TP +.B 3 +.I v1 +is not equal to +.IR v2 , +but ordering information is unavailable. +.RE +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +.BR kcmp () +was designed to return values suitable for sorting. +This is particularly handy if one needs to compare +a large number of file descriptors. +.SH ERRORS +.TP +.B EBADF +.I type +is +.B KCMP_FILE +and +.I fd1 +or +.I fd2 +is not an open file descriptor. +.TP +.B EFAULT +The epoll slot addressed by +.I idx2 +is outside of the user's address space. +.TP +.B EINVAL +.I type +is invalid. +.TP +.B ENOENT +The target file is not present in +.BR epoll (7) +instance. +.TP +.B EPERM +Insufficient permission to inspect process resources. +The +.B CAP_SYS_PTRACE +capability is required to inspect processes that you do not own. +Other ptrace limitations may also apply, such as +.BR CONFIG_SECURITY_YAMA , +which, when +.I /proc/sys/kernel/yama/ptrace_scope +is 2, limits +.BR kcmp () +to child processes; +see +.BR ptrace (2). +.TP +.B ESRCH +Process +.I pid1 +or +.I pid2 +does not exist. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.5. +.P +Before Linux 5.12, +this system call is available only if the kernel is configured with +.BR CONFIG_CHECKPOINT_RESTORE , +since the original purpose of the system call was for the +checkpoint/restore in user space (CRIU) feature. +(The alternative to this system call would have been to expose suitable +process information via the +.BR proc (5) +filesystem; this was deemed to be unsuitable for security reasons.) +Since Linux 5.12, +this system call is also available if the kernel is configured with +.BR CONFIG_KCMP . +.SH NOTES +See +.BR clone (2) +for some background information on the shared resources +referred to on this page. +.SH EXAMPLES +The program below uses +.BR kcmp () +to test whether pairs of file descriptors refer to +the same open file description. +The program tests different cases for the file descriptor pairs, +as described in the program output. +An example run of the program is as follows: +.P +.in +4n +.EX +$ \fB./a.out\fP +Parent PID is 1144 +Parent opened file on FD 3 +\& +PID of child of fork() is 1145 + Compare duplicate FDs from different processes: + kcmp(1145, 1144, KCMP_FILE, 3, 3) ==> same +Child opened file on FD 4 + Compare FDs from distinct open()s in same process: + kcmp(1145, 1145, KCMP_FILE, 3, 4) ==> different +Child duplicated FD 3 to create FD 5 + Compare duplicated FDs in same process: + kcmp(1145, 1145, KCMP_FILE, 3, 5) ==> same +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (kcmp.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +static int +kcmp(pid_t pid1, pid_t pid2, int type, + unsigned long idx1, unsigned long idx2) +{ + return syscall(SYS_kcmp, pid1, pid2, type, idx1, idx2); +} +\& +static void +test_kcmp(char *msg, pid_t pid1, pid_t pid2, int fd_a, int fd_b) +{ + printf("\et%s\en", msg); + printf("\et\etkcmp(%jd, %jd, KCMP_FILE, %d, %d) ==> %s\en", + (intmax_t) pid1, (intmax_t) pid2, fd_a, fd_b, + (kcmp(pid1, pid2, KCMP_FILE, fd_a, fd_b) == 0) ? + "same" : "different"); +} +\& +int +main(void) +{ + int fd1, fd2, fd3; + static const char pathname[] = "/tmp/kcmp.test"; +\& + fd1 = open(pathname, O_CREAT | O_RDWR, 0600); + if (fd1 == \-1) + err(EXIT_FAILURE, "open"); +\& + printf("Parent PID is %jd\en", (intmax_t) getpid()); + printf("Parent opened file on FD %d\en\en", fd1); +\& + switch (fork()) { + case \-1: + err(EXIT_FAILURE, "fork"); +\& + case 0: + printf("PID of child of fork() is %jd\en", (intmax_t) getpid()); +\& + test_kcmp("Compare duplicate FDs from different processes:", + getpid(), getppid(), fd1, fd1); +\& + fd2 = open(pathname, O_CREAT | O_RDWR, 0600); + if (fd2 == \-1) + err(EXIT_FAILURE, "open"); + printf("Child opened file on FD %d\en", fd2); +\& + test_kcmp("Compare FDs from distinct open()s in same process:", + getpid(), getpid(), fd1, fd2); +\& + fd3 = dup(fd1); + if (fd3 == \-1) + err(EXIT_FAILURE, "dup"); + printf("Child duplicated FD %d to create FD %d\en", fd1, fd3); +\& + test_kcmp("Compare duplicated FDs in same process:", + getpid(), getpid(), fd1, fd3); + break; +\& + default: + wait(NULL); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clone (2), +.BR unshare (2) diff --git a/man/man2/kexec_file_load.2 b/man/man2/kexec_file_load.2 new file mode 100644 index 0000000..6c20331 --- /dev/null +++ b/man/man2/kexec_file_load.2 @@ -0,0 +1 @@ +.so man2/kexec_load.2 diff --git a/man/man2/kexec_load.2 b/man/man2/kexec_load.2 new file mode 100644 index 0000000..99e018d --- /dev/null +++ b/man/man2/kexec_load.2 @@ -0,0 +1,331 @@ +.\" Copyright (C) 2010 Intel Corporation, Author: Andi Kleen +.\" and Copyright 2014, Vivek Goyal +.\" and Copyright (c) 2015, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH kexec_load 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +kexec_load, kexec_file_load \- load a new kernel for later execution +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " KEXEC_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "long syscall(SYS_kexec_load, unsigned long " entry , +.BI " unsigned long " nr_segments \ +", struct kexec_segment *" segments , +.BI " unsigned long " flags ); +.BI "long syscall(SYS_kexec_file_load, int " kernel_fd ", int " initrd_fd , +.BI " unsigned long " cmdline_len ", const char *" cmdline , +.BI " unsigned long " flags ); +.fi +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR kexec_load () +system call loads a new kernel that can be executed later by +.BR reboot (2). +.P +The +.I flags +argument is a bit mask that controls the operation of the call. +The following values can be specified in +.IR flags : +.TP +.BR KEXEC_ON_CRASH " (since Linux 2.6.13)" +Execute the new kernel automatically on a system crash. +This "crash kernel" is loaded into an area of reserved memory that +is determined at boot time using the +.I crashkernel +kernel command-line parameter. +The location of this reserved memory is exported to user space via the +.I /proc/iomem +file, in an entry labeled "Crash kernel". +A user-space application can parse this file and prepare a list of +segments (see below) that specify this reserved memory as destination. +If this flag is specified, the kernel checks that the +target segments specified in +.I segments +fall within the reserved region. +.TP +.BR KEXEC_PRESERVE_CONTEXT " (since Linux 2.6.27)" +Preserve the system hardware and +software states before executing the new kernel. +This could be used for system suspend. +This flag is available only if the kernel was configured with +.BR CONFIG_KEXEC_JUMP , +and is effective only if +.I nr_segments +is greater than 0. +.P +The high-order bits (corresponding to the mask 0xffff0000) of +.I flags +contain the architecture of the to-be-executed kernel. +Specify (OR) the constant +.B KEXEC_ARCH_DEFAULT +to use the current architecture, +or one of the following architecture constants +.BR KEXEC_ARCH_386 , +.BR KEXEC_ARCH_68K , +.BR KEXEC_ARCH_X86_64 , +.BR KEXEC_ARCH_PPC , +.BR KEXEC_ARCH_PPC64 , +.BR KEXEC_ARCH_IA_64 , +.BR KEXEC_ARCH_ARM , +.BR KEXEC_ARCH_S390 , +.BR KEXEC_ARCH_SH , +.BR KEXEC_ARCH_MIPS , +and +.BR KEXEC_ARCH_MIPS_LE . +The architecture must be executable on the CPU of the system. +.P +The +.I entry +argument is the physical entry address in the kernel image. +The +.I nr_segments +argument is the number of segments pointed to by the +.I segments +pointer; +the kernel imposes an (arbitrary) limit of 16 on the number of segments. +The +.I segments +argument is an array of +.I kexec_segment +structures which define the kernel layout: +.P +.in +4n +.EX +struct kexec_segment { + void *buf; /* Buffer in user space */ + size_t bufsz; /* Buffer length in user space */ + void *mem; /* Physical address of kernel */ + size_t memsz; /* Physical address length */ +}; +.EE +.in +.P +The kernel image defined by +.I segments +is copied from the calling process into +the kernel either in regular +memory or in reserved memory (if +.B KEXEC_ON_CRASH +is set). +The kernel first performs various sanity checks on the +information passed in +.IR segments . +If these checks pass, the kernel copies the segment data to kernel memory. +Each segment specified in +.I segments +is copied as follows: +.IP \[bu] 3 +.I buf +and +.I bufsz +identify a memory region in the caller's virtual address space +that is the source of the copy. +The value in +.I bufsz +may not exceed the value in the +.I memsz +field. +.IP \[bu] +.I mem +and +.I memsz +specify a physical address range that is the target of the copy. +The values specified in both fields must be multiples of +the system page size. +.IP \[bu] +.I bufsz +bytes are copied from the source buffer to the target kernel buffer. +If +.I bufsz +is less than +.IR memsz , +then the excess bytes in the kernel buffer are zeroed out. +.P +In case of a normal kexec (i.e., the +.B KEXEC_ON_CRASH +flag is not set), the segment data is loaded in any available memory +and is moved to the final destination at kexec reboot time (e.g., when the +.BR kexec (8) +command is executed with the +.I \-e +option). +.P +In case of kexec on panic (i.e., the +.B KEXEC_ON_CRASH +flag is set), the segment data is +loaded to reserved memory at the time of the call, and, after a crash, +the kexec mechanism simply passes control to that kernel. +.P +The +.BR kexec_load () +system call is available only if the kernel was configured with +.BR CONFIG_KEXEC . +.SS kexec_file_load() +The +.BR kexec_file_load () +system call is similar to +.BR kexec_load (), +but it takes a different set of arguments. +It reads the kernel to be loaded from the file referred to by +the file descriptor +.IR kernel_fd , +and the initrd (initial RAM disk) +to be loaded from file referred to by the file descriptor +.IR initrd_fd . +The +.I cmdline +argument is a pointer to a buffer containing the command line +for the new kernel. +The +.I cmdline_len +argument specifies size of the buffer. +The last byte in the buffer must be a null byte (\[aq]\e0\[aq]). +.P +The +.I flags +argument is a bit mask which modifies the behavior of the call. +The following values can be specified in +.IR flags : +.TP +.B KEXEC_FILE_UNLOAD +Unload the currently loaded kernel. +.TP +.B KEXEC_FILE_ON_CRASH +Load the new kernel in the memory region reserved for the crash kernel +(as for +.BR KEXEC_ON_CRASH ). +This kernel is booted if the currently running kernel crashes. +.TP +.B KEXEC_FILE_NO_INITRAMFS +Loading initrd/initramfs is optional. +Specify this flag if no initramfs is being loaded. +If this flag is set, the value passed in +.I initrd_fd +is ignored. +.P +The +.BR kexec_file_load () +.\" See also http://lwn.net/Articles/603116/ +system call was added to provide support for systems +where "kexec" loading should be restricted to +only kernels that are signed. +This system call is available only if the kernel was configured with +.BR CONFIG_KEXEC_FILE . +.SH RETURN VALUE +On success, these system calls returns 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EADDRNOTAVAIL +.\" See kernel/kexec.::sanity_check_segment_list in the 3.19 kernel source +The +.B KEXEC_ON_CRASH +flags was specified, but the region specified by the +.I mem +and +.I memsz +fields of one of the +.I segments +entries lies outside the range of memory reserved for the crash kernel. +.TP +.B EADDRNOTAVAIL +The value in a +.I mem +or +.I memsz +field in one of the +.I segments +entries is not a multiple of the system page size. +.TP +.B EBADF +.I kernel_fd +or +.I initrd_fd +is not a valid file descriptor. +.TP +.B EBUSY +Another crash kernel is already being loaded +or a crash kernel is already in use. +.TP +.B EINVAL +.I flags +is invalid. +.TP +.B EINVAL +The value of a +.I bufsz +field in one of the +.I segments +entries exceeds the value in the corresponding +.I memsz +field. +.TP +.B EINVAL +.I nr_segments +exceeds +.B KEXEC_SEGMENT_MAX +(16). +.TP +.B EINVAL +Two or more of the kernel target buffers overlap. +.TP +.B EINVAL +The value in +.I cmdline[cmdline_len\-1] +is not \[aq]\e0\[aq]. +.TP +.B EINVAL +The file referred to by +.I kernel_fd +or +.I initrd_fd +is empty (length zero). +.TP +.B ENOEXEC +.I kernel_fd +does not refer to an open file, or the kernel can't load this file. +Currently, the file must be a bzImage and contain an x86 kernel that +is loadable above 4\ GiB in memory (see the kernel source file +.IR Documentation/x86/boot.txt ). +.TP +.B ENOMEM +Could not allocate memory. +.TP +.B EPERM +The caller does not have the +.B CAP_SYS_BOOT +capability. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR kexec_load () +Linux 2.6.13. +.TP +.BR kexec_file_load () +Linux 3.17. +.SH SEE ALSO +.BR reboot (2), +.BR syscall (2), +.BR kexec (8) +.P +The kernel source files +.I Documentation/kdump/kdump.txt +and +.I Documentation/admin\-guide/kernel\-parameters.txt diff --git a/man/man2/keyctl.2 b/man/man2/keyctl.2 new file mode 100644 index 0000000..fbde8cd --- /dev/null +++ b/man/man2/keyctl.2 @@ -0,0 +1,2297 @@ +.\" Copyright (C) 2016 Michael Kerrisk +.\" and Copyright (C) 2016 Eugene Syromyatnikov +.\" A very few fragments remain from an earlier version of this page +.\" written by David Howells (dhowells@redhat.com) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH keyctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +keyctl \- manipulate the kernel's key management facility +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.P +Alternatively, Linux Key Management Utilities +.RI ( libkeyutils ", " \-lkeyutils ); +see VERSIONS. +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " KEY* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "long syscall(SYS_keyctl, int " operation ", unsigned long " arg2 , +.BI " unsigned long " arg3 ", unsigned long " arg4 , +.BI " unsigned long " arg5 ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR keyctl (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR keyctl () +allows user-space programs to perform key manipulation. +.P +The operation performed by +.BR keyctl () +is determined by the value of the +.I operation +argument. +Each of these operations is wrapped by the +.I libkeyutils +library (provided by the +.I keyutils +package) into individual functions (noted below) +to permit the compiler to check types. +.P +The permitted values for +.I operation +are: +.TP +.BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.10)" +Map a special key ID to a real key ID for this process. +.IP +This operation looks up the special key whose ID is provided in +.I arg2 +(cast to +.IR key_serial_t ). +If the special key is found, +the ID of the corresponding real key is returned as the function result. +The following values may be specified in +.IR arg2 : +.RS +.TP +.B KEY_SPEC_THREAD_KEYRING +This specifies the calling thread's thread-specific keyring. +See +.BR thread\-keyring (7). +.TP +.B KEY_SPEC_PROCESS_KEYRING +This specifies the caller's process-specific keyring. +See +.BR process\-keyring (7). +.TP +.B KEY_SPEC_SESSION_KEYRING +This specifies the caller's session-specific keyring. +See +.BR session\-keyring (7). +.TP +.B KEY_SPEC_USER_KEYRING +This specifies the caller's UID-specific keyring. +See +.BR user\-keyring (7). +.TP +.B KEY_SPEC_USER_SESSION_KEYRING +This specifies the caller's UID-session keyring. +See +.BR user\-session\-keyring (7). +.TP +.BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)" +.\" commit b5f545c880a2a47947ba2118b2509644ab7a2969 +This specifies the authorization key created by +.BR request_key (2) +and passed to the process it spawns to generate a key. +This key is available only in a +.BR request\-key (8)-style +program that was passed an authorization key by the kernel and +ceases to be available once the requested key has been instantiated; see +.BR request_key (2). +.TP +.BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)" +.\" commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 +This specifies the key ID for the +.BR request_key (2) +destination keyring. +This keyring is available only in a +.BR request\-key (8)-style +program that was passed an authorization key by the kernel and +ceases to be available once the requested key has been instantiated; see +.BR request_key (2). +.RE +.IP +The behavior if the key specified in +.I arg2 +does not exist depends on the value of +.I arg3 +(cast to +.IR int ). +If +.I arg3 +contains a nonzero value, then\[em]if it is appropriate to do so +(e.g., when looking up the user, user-session, or session key)\[em]a new key +is created and its real key ID returned as the function result. +.\" The keyctl_get_keyring_ID.3 page says that a new key +.\" "will be created *if it is appropriate to do so**. What is the +.\" determiner for appropriate? +.\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY +.\" wouldn't get created but user/user-session/session keyring would +.\" be created. +Otherwise, the operation fails with the error +.BR ENOKEY . +.IP +If a valid key ID is specified in +.IR arg2 , +and the key exists, then this operation simply returns the key ID. +If the key does not exist, the call fails with error +.BR ENOKEY . +.IP +The caller must have +.I search +permission on a keyring in order for it to be found. +.IP +The arguments +.I arg4 +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_get_keyring_ID (3). +.TP +.BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.10)" +Replace the session keyring this process subscribes to with +a new session keyring. +.\" This may be useful in conjunction with some sort of +.\" session management framework that is employed by the application. +.IP +If +.I arg2 +is NULL, +an anonymous keyring with the description "_ses" is created +and the process is subscribed to that keyring as its session keyring, +displacing the previous session keyring. +.IP +Otherwise, +.I arg2 +(cast to +.IR "char\ *" ) +is treated as the description (name) of a keyring, +and the behavior is as follows: +.RS +.IP \[bu] 3 +If a keyring with a matching description exists, +the process will attempt to subscribe to that keyring +as its session keyring if possible; +if that is not possible, an error is returned. +In order to subscribe to the keyring, +the caller must have +.I search +permission on the keyring. +.IP \[bu] +If a keyring with a matching description does not exist, +then a new keyring with the specified description is created, +and the process is subscribed to that keyring as its session keyring. +.RE +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_join_session_keyring (3). +.TP +.BR KEYCTL_UPDATE " (since Linux 2.6.10)" +Update a key's data payload. +.IP +The +.I arg2 +argument (cast to +.IR key_serial_t ) +specifies the ID of the key to be updated. +The +.I arg3 +argument (cast to +.IR "void\ *" ) +points to the new payload and +.I arg4 +(cast to +.IR size_t ) +contains the new payload size in bytes. +.IP +The caller must have +.I write +permission on the key specified and the key type must support updating. +.IP +A negatively instantiated key (see the description of +.BR KEYCTL_REJECT ) +can be positively instantiated with this operation. +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_update (3). +.TP +.BR KEYCTL_REVOKE " (since Linux 2.6.10)" +Revoke the key with the ID provided in +.I arg2 +(cast to +.IR key_serial_t ). +The key is scheduled for garbage collection; +it will no longer be findable, +and will be unavailable for further operations. +Further attempts to use the key will fail with the error +.BR EKEYREVOKED . +.IP +The caller must have +.I write +or +.I setattr +permission on the key. +.\" Keys with the KEY_FLAG_KEEP bit set cause an EPERM +.\" error for KEYCTL_REVOKE. Does this need to be documented? +.\" David Howells: No significance for user space. +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_revoke (3). +.TP +.BR KEYCTL_CHOWN " (since Linux 2.6.10)" +Change the ownership (user and group ID) of a key. +.IP +The +.I arg2 +argument (cast to +.IR key_serial_t ) +contains the key ID. +The +.I arg3 +argument (cast to +.IR uid_t ) +contains the new user ID (or \-1 in case the user ID shouldn't be changed). +The +.I arg4 +argument (cast to +.IR gid_t ) +contains the new group ID (or \-1 in case the group ID shouldn't be changed). +.IP +The key must grant the caller +.I setattr +permission. +.IP +For the UID to be changed, or for the GID to be changed to a group +the caller is not a member of, the caller must have the +.B CAP_SYS_ADMIN +capability (see +.BR capabilities (7)). +.IP +If the UID is to be changed, the new user must have sufficient +quota to accept the key. +The quota deduction will be removed from the old user +to the new user should the UID be changed. +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_chown (3). +.TP +.BR KEYCTL_SETPERM " (since Linux 2.6.10)" +Change the permissions of the key with the ID provided in the +.I arg2 +argument (cast to +.IR key_serial_t ) +to the permissions provided in the +.I arg3 +argument (cast to +.IR key_perm_t ). +.IP +If the caller doesn't have the +.B CAP_SYS_ADMIN +capability, it can change permissions only for the keys it owns. +(More precisely: the caller's filesystem UID must match the UID of the key.) +.IP +The key must grant +.I setattr +permission to the caller +.I regardless +of the caller's capabilities. +.\" FIXME Above, is it really intended that a privileged process can't +.\" override the lack of the 'setattr' permission? +.IP +The permissions in +.I arg3 +specify masks of available operations +for each of the following user categories: +.RS +.TP +.IR possessor " (since Linux 2.6.14)" +.\" commit 664cceb0093b755739e56572b836a99104ee8a75 +This is the permission granted to a process that possesses the key +(has it attached searchably to one of the process's keyrings); +see +.BR keyrings (7). +.TP +.I user +This is the permission granted to a process +whose filesystem UID matches the UID of the key. +.TP +.I group +This is the permission granted to a process +whose filesystem GID or any of its supplementary GIDs +matches the GID of the key. +.TP +.I other +This is the permission granted to other processes +that do not match the +.I user +and +.I group +categories. +.RE +.IP +The +.IR user , +.IR group , +and +.I other +categories are exclusive: if a process matches the +.I user +category, it will not receive permissions granted in the +.I group +category; if a process matches the +.I user +or +.I group +category, then it will not receive permissions granted in the +.I other +category. +.IP +The +.I possessor +category grants permissions that are cumulative with the grants from the +.IR user , +.IR group , +or +.I other +category. +.IP +Each permission mask is eight bits in size, +with only six bits currently used. +The available permissions are: +.RS +.TP +.I view +This permission allows reading attributes of a key. +.IP +This permission is required for the +.B KEYCTL_DESCRIBE +operation. +.IP +The permission bits for each category are +.BR KEY_POS_VIEW , +.BR KEY_USR_VIEW , +.BR KEY_GRP_VIEW , +and +.BR KEY_OTH_VIEW . +.TP +.I read +This permission allows reading a key's payload. +.IP +This permission is required for the +.B KEYCTL_READ +operation. +.IP +The permission bits for each category are +.BR KEY_POS_READ , +.BR KEY_USR_READ , +.BR KEY_GRP_READ , +and +.BR KEY_OTH_READ . +.TP +.I write +This permission allows update or instantiation of a key's payload. +For a keyring, it allows keys to be linked and unlinked from the keyring, +.IP +This permission is required for the +.BR KEYCTL_UPDATE , +.BR KEYCTL_REVOKE , +.BR KEYCTL_CLEAR , +.BR KEYCTL_LINK , +and +.B KEYCTL_UNLINK +operations. +.IP +The permission bits for each category are +.BR KEY_POS_WRITE , +.BR KEY_USR_WRITE , +.BR KEY_GRP_WRITE , +and +.BR KEY_OTH_WRITE . +.TP +.I search +This permission allows keyrings to be searched and keys to be found. +Searches can recurse only into nested keyrings that have +.I search +permission set. +.IP +This permission is required for the +.BR KEYCTL_GET_KEYRING_ID , +.BR KEYCTL_JOIN_SESSION_KEYRING , +.BR KEYCTL_SEARCH , +and +.B KEYCTL_INVALIDATE +operations. +.IP +The permission bits for each category are +.BR KEY_POS_SEARCH , +.BR KEY_USR_SEARCH , +.BR KEY_GRP_SEARCH , +and +.BR KEY_OTH_SEARCH . +.TP +.I link +This permission allows a key or keyring to be linked to. +.IP +This permission is required for the +.B KEYCTL_LINK +and +.B KEYCTL_SESSION_TO_PARENT +operations. +.IP +The permission bits for each category are +.BR KEY_POS_LINK , +.BR KEY_USR_LINK , +.BR KEY_GRP_LINK , +and +.BR KEY_OTH_LINK . +.TP +.IR setattr " (since Linux 2.6.15)." +This permission allows a key's UID, GID, and permissions mask to be changed. +.IP +This permission is required for the +.BR KEYCTL_REVOKE , +.BR KEYCTL_CHOWN , +and +.B KEYCTL_SETPERM +operations. +.IP +The permission bits for each category are +.BR KEY_POS_SETATTR , +.BR KEY_USR_SETATTR , +.BR KEY_GRP_SETATTR , +and +.BR KEY_OTH_SETATTR . +.RE +.IP +As a convenience, the following macros are defined as masks for +all of the permission bits in each of the user categories: +.BR KEY_POS_ALL , +.BR KEY_USR_ALL , +.BR KEY_GRP_ALL , +and +.BR KEY_OTH_ALL . +.IP +The +.I arg4 +and +.I arg5 +arguments are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_setperm (3). +.TP +.BR KEYCTL_DESCRIBE " (since Linux 2.6.10)" +Obtain a string describing the attributes of a specified key. +.IP +The ID of the key to be described is specified in +.I arg2 +(cast to +.IR key_serial_t ). +The descriptive string is returned in the buffer pointed to by +.I arg3 +(cast to +.IR char\~* ); +.I arg4 +(cast to +.IR size_t ) +specifies the size of that buffer in bytes. +.IP +The key must grant the caller +.I view +permission. +.IP +The returned string is null-terminated and +contains the following information about the key: +.IP +.in +4n +.IR type ; uid ; gid ; perm ; description +.in +.IP +In the above, +.I type +and +.I description +are strings, +.I uid +and +.I gid +are decimal strings, and +.I perm +is a hexadecimal permissions mask. +The descriptive string is written with the following format: +.IP +.in +4n +.EX +%s;%d;%d;%08x;%s +.EE +.in +.IP +.B Note: the intention is that the descriptive string should +.B be extensible in future kernel versions. +In particular, the +.I description +field will not contain semicolons; +.\" FIXME But, the kernel does not enforce the requirement +.\" that the key description contains no semicolons! +.\" So, user space has no guarantee here?? +.\" Either something more needs to be said here, +.\" or a kernel fix is required. +it should be parsed by working backwards from the end of the string +to find the last semicolon. +This allows future semicolon-delimited fields to be inserted +in the descriptive string in the future. +.IP +Writing to the buffer is attempted only when +.I arg3 +is non-NULL and the specified buffer size +is large enough to accept the descriptive string +(including the terminating null byte). +.\" Function commentary says it copies up to buflen bytes, but see the +.\" (buffer && buflen >= ret) condition in keyctl_describe_key() in +.\" security/keyctl.c +In order to determine whether the buffer size was too small, +check to see if the return value of the operation is greater than +.IR arg4 . +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_describe (3). +.TP +.B KEYCTL_CLEAR +Clear the contents of (i.e., unlink all keys from) a keyring. +.IP +The ID of the key +(which must be of keyring type) +.\" or the error ENOTDIR results +is provided in +.I arg2 +(cast to +.IR key_serial_t ). +.\" According to Documentation/security/keys.txt: +.\" This function can also be used to clear special kernel keyrings if they +.\" are appropriately marked if the user has CAP_SYS_ADMIN capability. The +.\" DNS resolver cache keyring is an example of this. +.IP +The caller must have +.I write +permission on the keyring. +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_clear (3). +.TP +.BR KEYCTL_LINK " (since Linux 2.6.10)" +Create a link from a keyring to a key. +.IP +The key to be linked is specified in +.I arg2 +(cast to +.IR key_serial_t ); +the keyring is specified in +.I arg3 +(cast to +.IR key_serial_t ). +.IP +If a key with the same type and description is already linked in the keyring, +then that key is displaced from the keyring. +.IP +Before creating the link, +the kernel checks the nesting of the keyrings and returns appropriate errors +if the link would produce a cycle +or if the nesting of keyrings would be too deep +(The limit on the nesting of keyrings is determined by the kernel constant +.BR KEYRING_SEARCH_MAX_DEPTH , +defined with the value 6, and is necessary to prevent overflows +on the kernel stack when recursively searching keyrings). +.IP +The caller must have +.I link +permission on the key being added and +.I write +permission on the keyring. +.IP +The arguments +.I arg4 +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_link (3). +.TP +.BR KEYCTL_UNLINK " (since Linux 2.6.10)" +Unlink a key from a keyring. +.IP +The ID of the key to be unlinked is specified in +.I arg2 +(cast to +.IR key_serial_t ); +the ID of the keyring from which it is to be unlinked is specified in +.I arg3 +(cast to +.IR key_serial_t ). +.IP +If the key is not currently linked into the keyring, an error results. +.IP +The caller must have +.I write +permission on the keyring from which the key is being removed. +.IP +If the last link to a key is removed, +then that key will be scheduled for destruction. +.IP +The arguments +.I arg4 +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_unlink (3). +.TP +.BR KEYCTL_SEARCH " (since Linux 2.6.10)" +Search for a key in a keyring tree, +returning its ID and optionally linking it to a specified keyring. +.IP +The tree to be searched is specified by passing +the ID of the head keyring in +.I arg2 +(cast to +.IR key_serial_t ). +The search is performed breadth-first and recursively. +.IP +The +.I arg3 +and +.I arg4 +arguments specify the key to be searched for: +.I arg3 +(cast as +.IR char\~* ) +contains the key type +(a null-terminated character string up to 32 bytes in size, +including the terminating null byte), and +.I arg4 +(cast as +.IR char\~* ) +contains the description of the key +(a null-terminated character string up to 4096 bytes in size, +including the terminating null byte). +.IP +The source keyring must grant +.I search +permission to the caller. +When performing the recursive search, only keyrings that grant the caller +.I search +permission will be searched. +Only keys with for which the caller has +.I search +permission can be found. +.IP +If the key is found, its ID is returned as the function result. +.IP +If the key is found and +.I arg5 +(cast to +.IR key_serial_t ) +is nonzero, then, subject to the same constraints and rules as +.BR KEYCTL_LINK , +the key is linked into the keyring whose ID is specified in +.IR arg5 . +If the destination keyring specified in +.I arg5 +already contains a link to a key that has the same type and description, +then that link will be displaced by a link to +the key found by this operation. +.IP +Instead of valid existing keyring IDs, the source +.RI ( arg2 ) +and destination +.RI ( arg5 ) +keyrings can be one of the special keyring IDs listed under +.BR KEYCTL_GET_KEYRING_ID . +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_search (3). +.TP +.BR KEYCTL_READ " (since Linux 2.6.10)" +Read the payload data of a key. +.IP +The ID of the key whose payload is to be read is specified in +.I arg2 +(cast to +.IR key_serial_t ). +This can be the ID of an existing key, +or any of the special key IDs listed for +.BR KEYCTL_GET_KEYRING_ID . +.\" including KEY_SPEC_REQKEY_AUTH_KEY +.IP +The payload is placed in the buffer pointed by +.I arg3 +(cast to +.IR "char\ *" ); +the size of that buffer must be specified in +.I arg4 +(cast to +.IR size_t ). +.IP +The returned data will be processed for presentation +according to the key type. +For example, a keyring will return an array of +.I key_serial_t +entries representing the IDs of all the keys that are linked to it. +The +.I user +key type will return its data as is. +If a key type does not implement this function, +the operation fails with the error +.BR EOPNOTSUPP . +.IP +If +.I arg3 +is not NULL, +as much of the payload data as will fit is copied into the buffer. +On a successful return, +the return value is always the total size of the payload data. +To determine whether the buffer was of sufficient size, +check to see that the return value is less than or equal to +the value supplied in +.IR arg4 . +.IP +The key must either grant the caller +.I read +permission, or grant the caller +.I search +permission when searched for from the process keyrings +(i.e., the key is possessed). +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_read (3). +.TP +.BR KEYCTL_INSTANTIATE " (since Linux 2.6.10)" +(Positively) instantiate an uninstantiated key with a specified payload. +.IP +The ID of the key to be instantiated is provided in +.I arg2 +(cast to +.IR key_serial_t ). +.IP +The key payload is specified in the buffer pointed to by +.I arg3 +(cast to +.IR "void\ *"); +the size of that buffer is specified in +.I arg4 +(cast to +.IR size_t ). +.IP +The payload may be a null pointer and the buffer size may be 0 +if this is supported by the key type (e.g., it is a keyring). +.IP +The operation may be fail if the payload data is in the wrong format +or is otherwise invalid. +.IP +If +.I arg5 +(cast to +.IR key_serial_t ) +is nonzero, then, subject to the same constraints and rules as +.BR KEYCTL_LINK , +the instantiated key is linked into the keyring whose ID specified in +.IR arg5 . +.IP +The caller must have the appropriate authorization key, +and once the uninstantiated key has been instantiated, +the authorization key is revoked. +In other words, this operation is available only from a +.BR request\-key (8)-style +program. +See +.BR request_key (2) +for an explanation of uninstantiated keys and key instantiation. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_instantiate (3). +.TP +.BR KEYCTL_NEGATE " (since Linux 2.6.10)" +Negatively instantiate an uninstantiated key. +.IP +This operation is equivalent to the call: +.IP +.in +4n +.EX +keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4); +.EE +.in +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_negate (3). +.TP +.BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)" +Set the default keyring to which implicitly requested keys +will be linked for this thread, and return the previous setting. +Implicit key requests are those made by internal kernel components, +.\" I.e., calls to the kernel's internal request_key() interface, +.\" which is distinct from the request_key(2) system call (which +.\" ultimately employs the kernel-internal interface). +such as can occur when, for example, opening files +on an AFS or NFS filesystem. +Setting the default keyring also has an effect when requesting +a key from user space; see +.BR request_key (2) +for details. +.IP +The +.I arg2 +argument (cast to +.IR int ) +should contain one of the following values, +to specify the new default keyring: +.RS +.TP +.B KEY_REQKEY_DEFL_NO_CHANGE +Don't change the default keyring. +This can be used to discover the current default keyring +(without changing it). +.TP +.B KEY_REQKEY_DEFL_DEFAULT +This selects the default behaviour, +which is to use the thread-specific keyring if there is one, +otherwise the process-specific keyring if there is one, +otherwise the session keyring if there is one, +otherwise the UID-specific session keyring, +otherwise the user-specific keyring. +.TP +.B KEY_REQKEY_DEFL_THREAD_KEYRING +Use the thread-specific keyring +.RB ( thread\-keyring (7)) +as the new default keyring. +.TP +.B KEY_REQKEY_DEFL_PROCESS_KEYRING +Use the process-specific keyring +.RB ( process\-keyring (7)) +as the new default keyring. +.TP +.B KEY_REQKEY_DEFL_SESSION_KEYRING +Use the session-specific keyring +.RB ( session\-keyring (7)) +as the new default keyring. +.TP +.B KEY_REQKEY_DEFL_USER_KEYRING +Use the UID-specific keyring +.RB ( user\-keyring (7)) +as the new default keyring. +.TP +.B KEY_REQKEY_DEFL_USER_SESSION_KEYRING +Use the UID-specific session keyring +.RB ( user\-session\-keyring (7)) +as the new default keyring. +.TP +.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)" +.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 +Use the requestor keyring. +.\" FIXME The preceding explanation needs to be expanded. +.\" Is the following correct: +.\" +.\" The requestor keyring is the dest_keyring that +.\" was supplied to a call to request_key(2)? +.\" +.\" David Howells said: to be checked +.RE +.IP +All other values are invalid. +.\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING) +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.IP +The setting controlled by this operation is inherited by the child of +.BR fork (2) +and preserved across +.BR execve (2). +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_set_reqkey_keyring (3). +.TP +.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)" +Set a timeout on a key. +.IP +The ID of the key is specified in +.I arg2 +(cast to +.IR key_serial_t ). +The timeout value, in seconds from the current time, +is specified in +.I arg3 +(cast to +.IR "unsigned int" ). +The timeout is measured against the realtime clock. +.IP +Specifying the timeout value as 0 clears any existing timeout on the key. +.IP +The +.I /proc/keys +file displays the remaining time until each key will expire. +(This is the only method of discovering the timeout on a key.) +.IP +The caller must either have the +.I setattr +permission on the key +or hold an instantiation authorization token for the key (see +.BR request_key (2)). +.IP +The key and any links to the key will be +automatically garbage collected after the timeout expires. +Subsequent attempts to access the key will then fail with the error +.BR EKEYEXPIRED . +.IP +This operation cannot be used to set timeouts on revoked, expired, +or negatively instantiated keys. +.IP +The arguments +.I arg4 +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_set_timeout (3). +.TP +.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)" +Assume (or divest) the authority for the calling thread +to instantiate a key. +.IP +The +.I arg2 +argument (cast to +.IR key_serial_t ) +specifies either a nonzero key ID to assume authority, +or the value 0 to divest authority. +.IP +If +.I arg2 +is nonzero, then it specifies the ID of an uninstantiated key for which +authority is to be assumed. +That key can then be instantiated using one of +.BR KEYCTL_INSTANTIATE , +.BR KEYCTL_INSTANTIATE_IOV , +.BR KEYCTL_REJECT , +or +.BR KEYCTL_NEGATE . +Once the key has been instantiated, +the thread is automatically divested of authority to instantiate the key. +.IP +Authority over a key can be assumed only if the calling thread has present +in its keyrings the authorization key that is +associated with the specified key. +(In other words, the +.B KEYCTL_ASSUME_AUTHORITY +operation is available only from a +.BR request\-key (8)-style +program; see +.BR request_key (2) +for an explanation of how this operation is used.) +The caller must have +.I search +permission on the authorization key. +.IP +If the specified key has a matching authorization key, +then the ID of that key is returned. +The authorization key can be read +.RB ( KEYCTL_READ ) +to obtain the callout information passed to +.BR request_key (2). +.IP +If the ID given in +.I arg2 +is 0, then the currently assumed authority is cleared (divested), +and the value 0 is returned. +.IP +The +.B KEYCTL_ASSUME_AUTHORITY +mechanism allows a program such as +.BR request\-key (8) +to assume the necessary authority to instantiate a new uninstantiated key +that was created as a consequence of a call to +.BR request_key (2). +For further information, see +.BR request_key (2) +and the kernel source file +.IR Documentation/security/keys\-request\-key.txt . +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_assume_authority (3). +.TP +.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)" +.\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d +Get the LSM (Linux Security Module) security label of the specified key. +.IP +The ID of the key whose security label is to be fetched is specified in +.I arg2 +(cast to +.IR key_serial_t ). +The security label (terminated by a null byte) +will be placed in the buffer pointed to by +.I arg3 +argument (cast to +.IR "char\ *" ); +the size of the buffer must be provided in +.I arg4 +(cast to +.IR size_t ). +.IP +If +.I arg3 +is specified as NULL or the buffer size specified in +.I arg4 +is too small, the full size of the security label string +(including the terminating null byte) +is returned as the function result, +and nothing is copied to the buffer. +.IP +The caller must have +.I view +permission on the specified key. +.IP +The returned security label string will be rendered in a form appropriate +to the LSM in force. +For example, with SELinux, it may look like: +.IP +.in +4n +.EX +unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023 +.EE +.in +.IP +If no LSM is currently in force, +then an empty string is placed in the buffer. +.IP +The +.I arg5 +argument is ignored. +.IP +This operation is exposed by +.I libkeyutils +via the functions +.BR keyctl_get_security (3) +and +.BR keyctl_get_security_alloc (3). +.TP +.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)" +.\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f +Replace the session keyring to which the +.I parent +of the calling process +subscribes with the session keyring of the calling process. +.\" What is the use case for KEYCTL_SESSION_TO_PARENT? +.\" David Howells: the Process Authentication Groups people requested this, +.\" but then didn't use it; maybe there are no users. +.IP +The keyring will be replaced in the parent process at the point +where the parent next transitions from kernel space to user space. +.IP +The keyring must exist and must grant the caller +.I link +permission. +The parent process must be single-threaded and have +the same effective ownership as this process +and must not be set-user-ID or set-group-ID. +The UID of the parent process's existing session keyring (f it has one), +as well as the UID of the caller's session keyring +much match the caller's effective UID. +.IP +The fact that it is the parent process that is affected by this operation +allows a program such as the shell to start a child process that +uses this operation to change the shell's session keyring. +(This is what the +.BR keyctl (1) +.B new_session +command does.) +.IP +The arguments +.IR arg2 , +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_session_to_parent (3). +.TP +.BR KEYCTL_REJECT " (since Linux 2.6.39)" +.\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c +Mark a key as negatively instantiated and set an expiration timer +on the key. +This operation provides a superset of the functionality of the earlier +.B KEYCTL_NEGATE +operation. +.IP +The ID of the key that is to be negatively instantiated is specified in +.I arg2 +(cast to +.IR key_serial_t ). +The +.I arg3 +(cast to +.IR "unsigned int" ) +argument specifies the lifetime of the key, in seconds. +The +.I arg4 +argument (cast to +.IR "unsigned int" ) +specifies the error to be returned when a search hits this key; +typically, this is one of +.BR EKEYREJECTED , +.BR EKEYREVOKED , +or +.BR EKEYEXPIRED . +.IP +If +.I arg5 +(cast to +.IR key_serial_t ) +is nonzero, then, subject to the same constraints and rules as +.BR KEYCTL_LINK , +the negatively instantiated key is linked into the keyring +whose ID is specified in +.IR arg5 . +.IP +The caller must have the appropriate authorization key. +In other words, this operation is available only from a +.BR request\-key (8)-style +program. +See +.BR request_key (2). +.IP +The caller must have the appropriate authorization key, +and once the uninstantiated key has been instantiated, +the authorization key is revoked. +In other words, this operation is available only from a +.BR request\-key (8)-style +program. +See +.BR request_key (2) +for an explanation of uninstantiated keys and key instantiation. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_reject (3). +.TP +.BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)" +.\" commit ee009e4a0d4555ed522a631bae9896399674f063 +Instantiate an uninstantiated key with a payload specified +via a vector of buffers. +.IP +This operation is the same as +.BR KEYCTL_INSTANTIATE , +but the payload data is specified as an array of +.I iovec +structures (see +.BR iovec (3type)). +.IP +The pointer to the payload vector is specified in +.I arg3 +(cast as +.IR "const struct iovec\~*" ). +The number of items in the vector is specified in +.I arg4 +(cast as +.IR "unsigned int" ). +.IP +The +.I arg2 +(key ID) +and +.I arg5 +(keyring ID) +are interpreted as for +.BR KEYCTL_INSTANTIATE . +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_instantiate_iov (3). +.TP +.BR KEYCTL_INVALIDATE " (since Linux 3.5)" +.\" commit fd75815f727f157a05f4c96b5294a4617c0557da +Mark a key as invalid. +.IP +The ID of the key to be invalidated is specified in +.I arg2 +(cast to +.IR key_serial_t ). +.IP +To invalidate a key, +the caller must have +.I search +permission on the key. +.\" CAP_SYS_ADMIN is permitted to invalidate certain special keys +.IP +This operation marks the key as invalid +and schedules immediate garbage collection. +The garbage collector removes the invalidated key from all keyrings and +deletes the key when its reference count reaches zero. +After this operation, +the key will be ignored by all searches, +even if it is not yet deleted. +.IP +Keys that are marked invalid become invisible to normal key operations +immediately, though they are still visible in +.I /proc/keys +(marked with an 'i' flag) +until they are actually removed. +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_invalidate (3). +.TP +.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)" +.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e +Get the persistent keyring +.RB ( persistent\-keyring (7)) +for a specified user and link it to a specified keyring. +.IP +The user ID is specified in +.I arg2 +(cast to +.IR uid_t ). +If the value \-1 is specified, the caller's real user ID is used. +The ID of the destination keyring is specified in +.I arg3 +(cast to +.IR key_serial_t ). +.IP +The caller must have the +.B CAP_SETUID +capability in its user namespace in order to fetch the persistent keyring +for a user ID that does not match either the real or effective user ID +of the caller. +.IP +If the call is successful, +a link to the persistent keyring is added to the keyring +whose ID was specified in +.IR arg3 . +.IP +The caller must have +.I write +permission on the keyring. +.IP +The persistent keyring will be created by the kernel +if it does not yet exist. +.IP +Each time the +.B KEYCTL_GET_PERSISTENT +operation is performed, the persistent keyring will +have its expiration timeout reset to the value in: +.IP +.in +4n +.EX +/proc/sys/kernel/keys/persistent_keyring_expiry +.EE +.in +.IP +Should the timeout be reached, +the persistent keyring will be removed and +everything it pins can then be garbage collected. +.IP +Persistent keyrings were added in Linux 3.13. +.IP +The arguments +.I arg4 +and +.I arg5 +are ignored. +.IP +This operation is exposed by +.I libkeyutils +via the function +.BR keyctl_get_persistent (3). +.TP +.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)" +.\" commit ddbb41148724367394d0880c516bfaeed127b52e +Compute a Diffie-Hellman shared secret or public key, +optionally applying key derivation function (KDF) to the result. +.IP +The +.I arg2 +argument is a pointer to a set of parameters containing +serial numbers for three +.I \[dq]user\[dq] +keys used in the Diffie-Hellman calculation, +packaged in a structure of the following form: +.IP +.in +4n +.EX +struct keyctl_dh_params { + int32_t private; /* The local private key */ + int32_t prime; /* The prime, known to both parties */ + int32_t base; /* The base integer: either a shared + generator or the remote public key */ +}; +.EE +.in +.IP +Each of the three keys specified in this structure must grant the caller +.I read +permission. +The payloads of these keys are used to calculate the Diffie-Hellman +result as: +.IP +.in +4n +.EX +base \[ha] private mod prime +.EE +.in +.IP +If the base is the shared generator, the result is the local public key. +If the base is the remote public key, the result is the shared secret. +.IP +The +.I arg3 +argument (cast to +.IR char\~* ) +points to a buffer where the result of the calculation is placed. +The size of that buffer is specified in +.I arg4 +(cast to +.IR size_t ). +.IP +The buffer must be large enough to accommodate the output data, +otherwise an error is returned. +If +.I arg4 +is specified zero, +in which case the buffer is not used and +the operation returns the minimum required buffer size +(i.e., the length of the prime). +.IP +Diffie-Hellman computations can be performed in user space, +but require a multiple-precision integer (MPI) library. +Moving the implementation into the kernel gives access to +the kernel MPI implementation, +and allows access to secure or acceleration hardware. +.IP +Adding support for DH computation to the +.BR keyctl () +system call was considered a good fit due to the DH algorithm's use +for deriving shared keys; +it also allows the type of the key to determine +which DH implementation (software or hardware) is appropriate. +.\" commit f1c316a3ab9d24df6022682422fe897492f2c0c8 +.IP +If the +.I arg5 +argument is +.BR NULL , +then the DH result itself is returned. +Otherwise (since Linux 4.12), it is a pointer to a structure which specifies +parameters of the KDF operation to be applied: +.IP +.in +4n +.EX +struct keyctl_kdf_params { + char *hashname; /* Hash algorithm name */ + char *otherinfo; /* SP800\-56A OtherInfo */ + __u32 otherinfolen; /* Length of otherinfo data */ + __u32 __spare[8]; /* Reserved */ +}; +.EE +.in +.IP +The +.I hashname +field is a null-terminated string which specifies a hash name +(available in the kernel's crypto API; the list of the hashes available +is rather tricky to observe; please refer to the +.UR https://www.kernel.org\:/doc\:/html\:/latest\:/crypto\:/architecture.html +"Kernel Crypto API Architecture" +.UE +documentation for the information regarding how hash names are constructed and +your kernel's source and configuration regarding what ciphers +and templates with type +.B CRYPTO_ALG_TYPE_SHASH +are available) +to be applied to DH result in KDF operation. +.IP +The +.I otherinfo +field is an +.I OtherInfo +data as described in SP800-56A section 5.8.1.2 and is algorithm-specific. +This data is concatenated with the result of DH operation and is provided as +an input to the KDF operation. +Its size is provided in the +.I otherinfolen +field and is limited by +.B KEYCTL_KDF_MAX_OI_LEN +constant that defined in +.I security/keys/internal.h +to a value of 64. +.IP +The +.B __spare +field is currently unused. +.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538 +It was ignored until Linux 4.13 (but still should be +user-addressable since it is copied to the kernel), +and should contain zeros since Linux 4.13. +.IP +The KDF implementation complies with SP800-56A as well +as with SP800-108 (the counter KDF). +.IP +.\" keyutils commit 742c9d7b94051d3b21f9f61a73ed6b5f3544cb82 +.\" keyutils commit d68a981e5db41d059ac782071c35d1e8f3aaf61c +This operation is exposed by +.I libkeyutils +(from +.I libkeyutils +1.5.10 onwards) via the functions +.BR keyctl_dh_compute (3) +and +.BR keyctl_dh_compute_alloc (3). +.TP +.BR KEYCTL_RESTRICT_KEYRING " (since Linux 4.12)" +.\" commit 6563c91fd645556c7801748f15bc727c77fcd311 +.\" commit 7228b66aaf723a623e578aa4db7d083bb39546c9 +Apply a key-linking restriction to the keyring with the ID provided in +.I arg2 +(cast to +.IR key_serial_t ). +The caller must have +.I setattr +permission on the key. +If +.I arg3 +is NULL, any attempt to add a key to the keyring is blocked; +otherwise it contains a pointer to a string with a key type name and +.I arg4 +contains a pointer to string that describes the type-specific restriction. +As of Linux 4.12, only the type "asymmetric" has restrictions defined: +.RS +.TP +.B builtin_trusted +Allows only keys that are signed by a key linked to the built-in keyring +(".builtin_trusted_keys"). +.TP +.B builtin_and_secondary_trusted +Allows only keys that are signed by a key linked to the secondary keyring +(".secondary_trusted_keys") or, by extension, a key in a built-in keyring, +as the latter is linked to the former. +.TP +.BI key_or_keyring: key +.TQ +.BI key_or_keyring: key :chain +If +.I key +specifies the ID of a key of type "asymmetric", +then only keys that are signed by this key are allowed. +.IP +If +.I key +specifies the ID of a keyring, +then only keys that are signed by a key linked +to this keyring are allowed. +.IP +If ":chain" is specified, keys that are signed by a keys linked to the +destination keyring (that is, the keyring with the ID specified in the +.I arg2 +argument) are also allowed. +.RE +.IP +Note that a restriction can be configured only once for the specified keyring; +once a restriction is set, it can't be overridden. +.IP +The argument +.I arg5 +is ignored. +.\" FIXME Document KEYCTL_RESTRICT_KEYRING, added in Linux 4.12 +.\" commit 6563c91fd645556c7801748f15bc727c77fcd311 +.\" Author: Mat Martineau +.\" See Documentation/security/keys.txt +.SH RETURN VALUE +For a successful call, the return value depends on the operation: +.TP +.B KEYCTL_GET_KEYRING_ID +The ID of the requested keyring. +.TP +.B KEYCTL_JOIN_SESSION_KEYRING +The ID of the joined session keyring. +.TP +.B KEYCTL_DESCRIBE +The size of the description (including the terminating null byte), +irrespective of the provided buffer size. +.TP +.B KEYCTL_SEARCH +The ID of the key that was found. +.TP +.B KEYCTL_READ +The amount of data that is available in the key, +irrespective of the provided buffer size. +.TP +.B KEYCTL_SET_REQKEY_KEYRING +The ID of the previous default keyring +to which implicitly requested keys were linked +(one of +.BR KEY_REQKEY_DEFL_USER_* ). +.TP +.B KEYCTL_ASSUME_AUTHORITY +Either 0, if the ID given was 0, +or the ID of the authorization key matching the specified key, +if a nonzero key ID was provided. +.TP +.B KEYCTL_GET_SECURITY +The size of the LSM security label string +(including the terminating null byte), +irrespective of the provided buffer size. +.TP +.B KEYCTL_GET_PERSISTENT +The ID of the persistent keyring. +.TP +.B KEYCTL_DH_COMPUTE +The number of bytes copied to the buffer, or, if +.I arg4 +is 0, the required buffer size. +.TP +All other operations +Zero. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The requested operation wasn't permitted. +.TP +.B EAGAIN +.I operation +was +.B KEYCTL_DH_COMPUTE +and there was an error during crypto module initialization. +.TP +.B EDEADLK +.I operation +was +.B KEYCTL_LINK +and the requested link would result in a cycle. +.TP +.B EDEADLK +.I operation +was +.B KEYCTL_RESTRICT_KEYRING +and the requested keyring restriction would result in a cycle. +.TP +.B EDQUOT +The key quota for the caller's user would be exceeded by creating a key or +linking it to the keyring. +.TP +.B EEXIST +.I operation +was +.B KEYCTL_RESTRICT_KEYRING +and keyring provided in +.I arg2 +argument already has a restriction set. +.TP +.B EFAULT +.I operation +was +.B KEYCTL_DH_COMPUTE +and one of the following has failed: +.RS +.IP \[bu] 3 +copying of the +.IR "struct keyctl_dh_params" , +provided in the +.I arg2 +argument, from user space; +.IP \[bu] +copying of the +.IR "struct keyctl_kdf_params" , +provided in the non-NULL +.I arg5 +argument, from user space +(in case kernel supports performing KDF operation on DH operation result); +.IP \[bu] +copying of data pointed by the +.I hashname +field of the +.I "struct keyctl_kdf_params" +from user space; +.IP \[bu] +copying of data pointed by the +.I otherinfo +field of the +.I struct keyctl_kdf_params +from user space if the +.I otherinfolen +field was nonzero; +.IP \[bu] +copying of the result to user space. +.RE +.TP +.B EINVAL +.I operation +was +.B KEYCTL_SETPERM +and an invalid permission bit was specified in +.IR arg3 . +.TP +.B EINVAL +.I operation +was +.B KEYCTL_SEARCH +and the size of the description in +.I arg4 +(including the terminating null byte) exceeded 4096 bytes. +.TP +.B EINVAL +size of the string (including the terminating null byte) specified in +.I arg3 +(the key type) +or +.I arg4 +(the key description) +exceeded the limit (32 bytes and 4096 bytes respectively). +.TP +.BR EINVAL " (before Linux 4.12)" +.I operation +was +.BR KEYCTL_DH_COMPUTE , +argument +.I arg5 +was non-NULL. +.TP +.B EINVAL +.I operation +was +.B KEYCTL_DH_COMPUTE +And the digest size of the hashing algorithm supplied is zero. +.TP +.B EINVAL +.I operation +was +.B KEYCTL_DH_COMPUTE +and the buffer size provided is not enough to hold the result. +Provide 0 as a buffer size in order to obtain the minimum buffer size. +.TP +.B EINVAL +.I operation +was +.B KEYCTL_DH_COMPUTE +and the hash name provided in the +.I hashname +field of the +.I struct keyctl_kdf_params +pointed by +.I arg5 +argument is too big (the limit is implementation-specific and varies between +kernel versions, but it is deemed big enough for all valid algorithm names). +.TP +.B EINVAL +.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538 +.I operation +was +.B KEYCTL_DH_COMPUTE +and the +.I __spare +field of the +.I struct keyctl_kdf_params +provided in the +.I arg5 +argument contains nonzero values. +.TP +.B EKEYEXPIRED +An expired key was found or specified. +.TP +.B EKEYREJECTED +A rejected key was found or specified. +.TP +.B EKEYREVOKED +A revoked key was found or specified. +.TP +.B ELOOP +.I operation +was +.B KEYCTL_LINK +and the requested link would cause the maximum nesting depth +for keyrings to be exceeded. +.TP +.B EMSGSIZE +.I operation +was +.B KEYCTL_DH_COMPUTE +and the buffer length exceeds +.B KEYCTL_KDF_MAX_OUTPUT_LEN +(which is 1024 currently) +or the +.I otherinfolen +field of the +.I struct keyctl_kdf_parms +passed in +.I arg5 +exceeds +.B KEYCTL_KDF_MAX_OI_LEN +(which is 64 currently). +.TP +.BR ENFILE " (before Linux 3.13)" +.I operation +was +.B KEYCTL_LINK +and the keyring is full. +(Before Linux 3.13, +.\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69 +the available space for storing keyring links was limited to +a single page of memory; since Linux 3.13, there is no fixed limit.) +.TP +.B ENOENT +.I operation +was +.B KEYCTL_UNLINK +and the key to be unlinked isn't linked to the keyring. +.TP +.B ENOENT +.I operation +was +.B KEYCTL_DH_COMPUTE +and the hashing algorithm specified in the +.I hashname +field of the +.I struct keyctl_kdf_params +pointed by +.I arg5 +argument hasn't been found. +.TP +.B ENOENT +.I operation +was +.B KEYCTL_RESTRICT_KEYRING +and the type provided in +.I arg3 +argument doesn't support setting key linking restrictions. +.TP +.B ENOKEY +No matching key was found or an invalid key was specified. +.TP +.B ENOKEY +The value +.B KEYCTL_GET_KEYRING_ID +was specified in +.IR operation , +the key specified in +.I arg2 +did not exist, and +.I arg3 +was zero (meaning don't create the key if it didn't exist). +.TP +.B ENOMEM +One of kernel memory allocation routines failed during the execution of the +syscall. +.TP +.B ENOTDIR +A key of keyring type was expected but the ID of a key with +a different type was provided. +.TP +.B EOPNOTSUPP +.I operation +was +.B KEYCTL_READ +and the key type does not support reading +(e.g., the type is +.IR \[dq]login\[dq] ). +.TP +.B EOPNOTSUPP +.I operation +was +.B KEYCTL_UPDATE +and the key type does not support updating. +.TP +.B EOPNOTSUPP +.I operation +was +.BR KEYCTL_RESTRICT_KEYRING , +the type provided in +.I arg3 +argument was "asymmetric", +and the key specified in the restriction specification provided in +.I arg4 +has type other than "asymmetric" or "keyring". +.TP +.B EPERM +.I operation +was +.BR KEYCTL_GET_PERSISTENT , +.I arg2 +specified a UID other than the calling thread's real or effective UID, +and the caller did not have the +.B CAP_SETUID +capability. +.TP +.B EPERM +.I operation +was +.B KEYCTL_SESSION_TO_PARENT +and either: +all of the UIDs (GIDs) of the parent process do not match +the effective UID (GID) of the calling process; +the UID of the parent's existing session keyring or +the UID of the caller's session keyring did not match +the effective UID of the caller; +the parent process is not single-thread; +or the parent process is +.BR init (1) +or a kernel thread. +.TP +.B ETIMEDOUT +.I operation +was +.B KEYCTL_DH_COMPUTE +and the initialization of crypto modules has timed out. +.SH VERSIONS +A wrapper is provided in the +.I libkeyutils +library. +(The accompanying package provides the +.I +header file.) +However, rather than using this system call directly, +you probably want to use the various library functions +mentioned in the descriptions of individual operations above. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.10. +.SH EXAMPLES +The program below provide subset of the functionality of the +.BR request\-key (8) +program provided by the +.I keyutils +package. +For informational purposes, +the program records various information in a log file. +.P +As described in +.BR request_key (2), +the +.BR request\-key (8) +program is invoked with command-line arguments that +describe a key that is to be instantiated. +The example program fetches and logs these arguments. +The program assumes authority to instantiate the requested key, +and then instantiates that key. +.P +The following shell session demonstrates the use of this program. +In the session, +we compile the program and then use it to temporarily replace the standard +.BR request\-key (8) +program. +(Note that temporarily disabling the standard +.BR request\-key (8) +program may not be safe on some systems.) +While our example program is installed, +we use the example program shown in +.BR request_key (2) +to request a key. +.P +.in +4n +.EX +$ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP +$ \fBsudo mv /sbin/request\-key /sbin/request\-key.backup\fP +$ \fBsudo cp key_instantiate /sbin/request\-key\fP +$ \fB./t_request_key user mykey somepayloaddata\fP +Key ID is 20d035bf +$ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP +.EE +.in +.P +Looking at the log file created by this program, +we can see the command-line arguments supplied to our example program: +.P +.in +4n +.EX +$ \fBcat /tmp/key_instantiate.log\fP +Time: Mon Nov 7 13:06:47 2016 +\& +Command line arguments: + argv[0]: /sbin/request\-key + operation: create + key_to_instantiate: 20d035bf + UID: 1000 + GID: 1000 + thread_keyring: 0 + process_keyring: 0 + session_keyring: 256e6a6 +\& +Key description: user;1000;1000;3f010000;mykey +Auth key payload: somepayloaddata +Destination keyring: 256e6a6 +Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf +.EE +.in +.P +The last few lines of the above output show that the example program +was able to fetch: +.IP \[bu] 3 +the description of the key to be instantiated, +which included the name of the key +.RI ( mykey ); +.IP \[bu] +the payload of the authorization key, which consisted of the data +.RI ( somepayloaddata ) +passed to +.BR request_key (2); +.IP \[bu] +the destination keyring that was specified in the call to +.BR request_key (2); +and +.IP \[bu] +the description of the authorization key, +where we can see that the name of the authorization key matches +the ID of the key that is to be instantiated +.RI ( 20d035bf ). +.P +The example program in +.BR request_key (2) +specified the destination keyring as +.BR KEY_SPEC_SESSION_KEYRING . +By examining the contents of +.IR /proc/keys , +we can see that this was translated to the ID of the destination keyring +.RI ( 0256e6a6 ) +shown in the log output above; +we can also see the newly created key with the name +.I mykey +and ID +.IR 20d035bf . +.P +.in +4n +.EX +$ \fBcat /proc/keys | egrep \[aq]mykey|256e6a6\[aq]\fP +0256e6a6 I\-\-Q\-\-\- 194 perm 3f030000 1000 1000 keyring _ses: 3 +20d035bf I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 16 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (key_instantiate.c) +.EX +/* key_instantiate.c */ +\& +#include +#include +#include +#include +#include +#include +#include +#include +\& +#ifndef KEY_SPEC_REQUESTOR_KEYRING +#define KEY_SPEC_REQUESTOR_KEYRING (\-8) +#endif +\& +int +main(int argc, char *argv[]) +{ + int akp_size; /* Size of auth_key_payload */ + int auth_key; + char dbuf[256]; + char auth_key_payload[256]; + char *operation; + FILE *fp; + gid_t gid; + uid_t uid; + time_t t; + key_serial_t key_to_instantiate, dest_keyring; + key_serial_t thread_keyring, process_keyring, session_keyring; +\& + if (argc != 8) { + fprintf(stderr, "Usage: %s op key uid gid thread_keyring " + "process_keyring session_keyring\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + fp = fopen("/tmp/key_instantiate.log", "w"); + if (fp == NULL) + exit(EXIT_FAILURE); +\& + setbuf(fp, NULL); +\& + t = time(NULL); + fprintf(fp, "Time: %s\en", ctime(&t)); +\& + /* + * The kernel passes a fixed set of arguments to the program + * that it execs; fetch them. + */ + operation = argv[1]; + key_to_instantiate = atoi(argv[2]); + uid = atoi(argv[3]); + gid = atoi(argv[4]); + thread_keyring = atoi(argv[5]); + process_keyring = atoi(argv[6]); + session_keyring = atoi(argv[7]); +\& + fprintf(fp, "Command line arguments:\en"); + fprintf(fp, " argv[0]: %s\en", argv[0]); + fprintf(fp, " operation: %s\en", operation); + fprintf(fp, " key_to_instantiate: %jx\en", + (uintmax_t) key_to_instantiate); + fprintf(fp, " UID: %jd\en", (intmax_t) uid); + fprintf(fp, " GID: %jd\en", (intmax_t) gid); + fprintf(fp, " thread_keyring: %jx\en", + (uintmax_t) thread_keyring); + fprintf(fp, " process_keyring: %jx\en", + (uintmax_t) process_keyring); + fprintf(fp, " session_keyring: %jx\en", + (uintmax_t) session_keyring); + fprintf(fp, "\en"); +\& + /* + * Assume the authority to instantiate the key named in argv[2]. + */ + if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == \-1) { + fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\en", + strerror(errno)); + exit(EXIT_FAILURE); + } +\& + /* + * Fetch the description of the key that is to be instantiated. + */ + if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate, + dbuf, sizeof(dbuf)) == \-1) { + fprintf(fp, "KEYCTL_DESCRIBE failed: %s\en", strerror(errno)); + exit(EXIT_FAILURE); + } +\& + fprintf(fp, "Key description: %s\en", dbuf); +\& + /* + * Fetch the payload of the authorization key, which is + * actually the callout data given to request_key(). + */ + akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY, + auth_key_payload, sizeof(auth_key_payload)); + if (akp_size == \-1) { + fprintf(fp, "KEYCTL_READ failed: %s\en", strerror(errno)); + exit(EXIT_FAILURE); + } +\& + auth_key_payload[akp_size] = \[aq]\e0\[aq]; + fprintf(fp, "Auth key payload: %s\en", auth_key_payload); +\& + /* + * For interest, get the ID of the authorization key and + * display it. + */ + auth_key = keyctl(KEYCTL_GET_KEYRING_ID, + KEY_SPEC_REQKEY_AUTH_KEY); + if (auth_key == \-1) { + fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\en", + strerror(errno)); + exit(EXIT_FAILURE); + } +\& + fprintf(fp, "Auth key ID: %jx\en", (uintmax_t) auth_key); +\& + /* + * Fetch key ID for the request_key(2) destination keyring. + */ + dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID, + KEY_SPEC_REQUESTOR_KEYRING); + if (dest_keyring == \-1) { + fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\en", + strerror(errno)); + exit(EXIT_FAILURE); + } +\& + fprintf(fp, "Destination keyring: %jx\en", (uintmax_t) dest_keyring); +\& + /* + * Fetch the description of the authorization key. This + * allows us to see the key type, UID, GID, permissions, + * and description (name) of the key. Among other things, + * we will see that the name of the key is a hexadecimal + * string representing the ID of the key to be instantiated. + */ + if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY, + dbuf, sizeof(dbuf)) == \-1) + { + fprintf(fp, "KEYCTL_DESCRIBE failed: %s\en", strerror(errno)); + exit(EXIT_FAILURE); + } +\& + fprintf(fp, "Auth key description: %s\en", dbuf); +\& + /* + * Instantiate the key using the callout data that was supplied + * in the payload of the authorization key. + */ + if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate, + auth_key_payload, akp_size + 1, dest_keyring) == \-1) + { + fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\en", + strerror(errno)); + exit(EXIT_FAILURE); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR request_key (2), +.\" .BR find_key_by_type_and_name (3) +.\" There is a man page, but this function seems not to exist +.BR keyctl (3), +.BR keyctl_assume_authority (3), +.BR keyctl_chown (3), +.BR keyctl_clear (3), +.BR keyctl_describe (3), +.BR keyctl_describe_alloc (3), +.BR keyctl_dh_compute (3), +.BR keyctl_dh_compute_alloc (3), +.BR keyctl_get_keyring_ID (3), +.BR keyctl_get_persistent (3), +.BR keyctl_get_security (3), +.BR keyctl_get_security_alloc (3), +.BR keyctl_instantiate (3), +.BR keyctl_instantiate_iov (3), +.BR keyctl_invalidate (3), +.BR keyctl_join_session_keyring (3), +.BR keyctl_link (3), +.BR keyctl_negate (3), +.BR keyctl_read (3), +.BR keyctl_read_alloc (3), +.BR keyctl_reject (3), +.BR keyctl_revoke (3), +.BR keyctl_search (3), +.BR keyctl_session_to_parent (3), +.BR keyctl_set_reqkey_keyring (3), +.BR keyctl_set_timeout (3), +.BR keyctl_setperm (3), +.BR keyctl_unlink (3), +.BR keyctl_update (3), +.BR recursive_key_scan (3), +.BR recursive_session_key_scan (3), +.BR capabilities (7), +.BR credentials (7), +.BR keyrings (7), +.BR keyutils (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user_namespaces (7), +.BR user\-session\-keyring (7), +.BR request\-key (8) +.P +The kernel source files under +.I Documentation/security/keys/ +(or, before Linux 4.13, in the file +.IR Documentation/security/keys.txt ). diff --git a/man/man2/kill.2 b/man/man2/kill.2 new file mode 100644 index 0000000..d70feb8 --- /dev/null +++ b/man/man2/kill.2 @@ -0,0 +1,165 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified by Thomas Koenig +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1993-07-25 by Rik Faith +.\" Modified 1995-11-01 by Michael Haardt +.\" +.\" Modified 1996-04-14 by Andries Brouwer +.\" [added some polishing contributed by Mike Battersby ] +.\" Modified 1996-07-21 by Andries Brouwer +.\" Modified 1997-01-17 by Andries Brouwer +.\" Modified 2001-12-18 by Andries Brouwer +.\" Modified 2002-07-24 by Michael Kerrisk +.\" Added note on historical rules enforced when an unprivileged process +.\" sends a signal. +.\" Modified 2004-06-16 by Michael Kerrisk +.\" Added note on CAP_KILL +.\" Modified 2004-06-24 by aeb +.\" Modified, 2004-11-30, after idea from emmanuel.colbus@ensimag.imag.fr +.\" +.TH kill 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +kill \- send signal to a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int kill(pid_t " pid ", int " sig ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR kill (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR kill () +system call +can be used to send any signal to any process group or process. +.P +If \fIpid\fP is positive, then signal \fIsig\fP is sent to the +process with the ID specified by \fIpid\fP. +.P +If \fIpid\fP equals 0, then \fIsig\fP is sent to every process in the +process group of the calling process. +.P +If \fIpid\fP equals \-1, then \fIsig\fP is sent to every process +for which the calling process has permission to send signals, +except for process 1 (\fIinit\fP), but see below. +.P +If \fIpid\fP is less than \-1, then \fIsig\fP is sent to every process +in the process group whose ID is \fI\-pid\fP. +.P +If \fIsig\fP is 0, then no signal is sent, +but existence and permission checks are still performed; +this can be used to check for the existence of a process ID or +process group ID that the caller is permitted to signal. +.P +For a process to have permission to send a signal, +it must either be privileged (under Linux: have the +.B CAP_KILL +capability in the user namespace of the target process), +or the real or effective user ID of the sending process must equal +the real or saved set-user-ID of the target process. +In the case of +.BR SIGCONT , +it suffices when the sending and receiving +processes belong to the same session. +(Historically, the rules were different; see NOTES.) +.SH RETURN VALUE +On success (at least one signal was sent), zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +An invalid signal was specified. +.TP +.B EPERM +The calling process does not have permission to send the signal +to any of the target processes. +.TP +.B ESRCH +The target process or process group does not exist. +Note that an existing process might be a zombie, +a process that has terminated execution, but +has not yet been +.BR wait (2)ed +for. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SS Linux notes +Across different kernel versions, Linux has enforced different rules +for the permissions required for an unprivileged process +to send a signal to another process. +.\" In the 0.* kernels things chopped and changed quite +.\" a bit - MTK, 24 Jul 02 +In Linux 1.0 to 1.2.2, a signal could be sent if the +effective user ID of the sender matched effective user ID of the target, +or the real user ID of the sender matched the real user ID of the target. +From Linux 1.2.3 until 1.3.77, a signal could be sent if the +effective user ID of the sender matched either the real or effective +user ID of the target. +The current rules, which conform to POSIX.1, were adopted +in Linux 1.3.78. +.SH NOTES +The only signals that can be sent to process ID 1, the +.I init +process, are those for which +.I init +has explicitly installed signal handlers. +This is done to assure the +system is not brought down accidentally. +.P +POSIX.1 requires that \fIkill(\-1,sig)\fP send \fIsig\fP +to all processes that the calling process may send signals to, +except possibly for some implementation-defined system processes. +Linux allows a process to signal itself, but on Linux the call +\fIkill(\-1,sig)\fP does not signal the calling process. +.P +POSIX.1 requires that if a process sends a signal to itself, +and the sending thread does not have the signal blocked, +and no other thread +has it unblocked or is waiting for it in +.BR sigwait (3), +at least one +unblocked signal must be delivered to the sending thread before the +.BR kill () +returns. +.SH BUGS +In Linux 2.6 up to and including Linux 2.6.7, +there was a bug that meant that when sending signals to a process group, +.BR kill () +failed with the error +.B EPERM +if the caller did not have permission to send the signal to \fIany\fP (rather +than \fIall\fP) of the members of the process group. +Notwithstanding this error return, the signal was still delivered +to all of the processes for which the caller had permission to signal. +.SH SEE ALSO +.BR kill (1), +.BR _exit (2), +.BR pidfd_send_signal (2), +.BR signal (2), +.BR tkill (2), +.BR exit (3), +.BR killpg (3), +.BR sigqueue (3), +.BR capabilities (7), +.BR credentials (7), +.BR signal (7) diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2 new file mode 100644 index 0000000..e873a39 --- /dev/null +++ b/man/man2/landlock_add_rule.2 @@ -0,0 +1,131 @@ +.\" Copyright © 2017-2020 Mickaël Salaün +.\" Copyright © 2019-2020 ANSSI +.\" Copyright © 2021 Microsoft Corporation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH landlock_add_rule 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +landlock_add_rule \- add a new Landlock rule to a ruleset +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " LANDLOCK_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.P +.BI "int syscall(SYS_landlock_add_rule, int " ruleset_fd , +.BI " enum landlock_rule_type " rule_type , +.BI " const void *" rule_attr ", uint32_t " flags ); +.fi +.SH DESCRIPTION +A Landlock rule describes an action on an object. +An object is currently a file hierarchy, +and the related filesystem actions +are defined with a set of access rights. +This +.BR landlock_add_rule () +system call enables adding a new Landlock rule to an existing ruleset +created with +.BR landlock_create_ruleset (2). +See +.BR landlock (7) +for a global overview. +.P +.I ruleset_fd +is a Landlock ruleset file descriptor obtained with +.BR landlock_create_ruleset (2). +.P +.I rule_type +identifies the structure type pointed to by +.IR rule_attr . +Currently, Linux supports the following +.I rule_type +value: +.TP +.B LANDLOCK_RULE_PATH_BENEATH +This defines the object type as a file hierarchy. +In this case, +.I rule_attr +points to the following structure: +.IP +.in +4n +.EX +struct landlock_path_beneath_attr { + __u64 allowed_access; + __s32 parent_fd; +} __attribute__((packed)); +.EE +.in +.IP +.I allowed_access +contains a bitmask of allowed filesystem actions for this file hierarchy +(see +.B Filesystem actions +in +.BR landlock (7)). +.IP +.I parent_fd +is an opened file descriptor, preferably with the +.I O_PATH +flag, +which identifies the parent directory of the file hierarchy or +just a file. +.P +.I flags +must be 0. +.SH RETURN VALUE +On success, +.BR landlock_add_rule () +returns 0. +.SH ERRORS +.BR landlock_add_rule () +can fail for the following reasons: +.TP +.B EOPNOTSUPP +Landlock is supported by the kernel but disabled at boot time. +.TP +.B EINVAL +.I flags +is not 0, or the rule accesses are inconsistent (i.e., +.I rule_attr\->allowed_access +is not a subset of the ruleset handled accesses). +.TP +.B ENOMSG +Empty accesses (i.e., +.I rule_attr\->allowed_access +is 0). +.TP +.B EBADF +.I ruleset_fd +is not a file descriptor for the current thread, +or a member of +.I rule_attr +is not a file descriptor as expected. +.TP +.B EBADFD +.I ruleset_fd +is not a ruleset file descriptor, +or a member of +.I rule_attr +is not the expected file descriptor type. +.TP +.B EPERM +.I ruleset_fd +has no write access to the underlying ruleset. +.TP +.B EFAULT +.I rule_attr +was not a valid address. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.13. +.SH EXAMPLES +See +.BR landlock (7). +.SH SEE ALSO +.BR landlock_create_ruleset (2), +.BR landlock_restrict_self (2), +.BR landlock (7) diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2 new file mode 100644 index 0000000..d2d1001 --- /dev/null +++ b/man/man2/landlock_create_ruleset.2 @@ -0,0 +1,124 @@ +.\" Copyright © 2017-2020 Mickaël Salaün +.\" Copyright © 2019-2020 ANSSI +.\" Copyright © 2021 Microsoft Corporation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH landlock_create_ruleset 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +landlock_create_ruleset \- create a new Landlock ruleset +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " LANDLOCK_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.P +.B int syscall(SYS_landlock_create_ruleset, +.BI " const struct landlock_ruleset_attr *" attr , +.BI " size_t " size " , uint32_t " flags ); +.fi +.SH DESCRIPTION +A Landlock ruleset identifies a set of rules (i.e., actions on objects). +This +.BR landlock_create_ruleset () +system call enables creating a new file descriptor identifying a ruleset. +This file descriptor can then be used by +.BR landlock_add_rule (2) +and +.BR landlock_restrict_self (2). +See +.BR landlock (7) +for a global overview. +.P +.I attr +specifies the properties of the new ruleset. +It points to the following structure: +.IP +.in +4n +.EX +struct landlock_ruleset_attr { + __u64 handled_access_fs; +}; +.EE +.in +.IP +.I handled_access_fs +is a bitmask of actions that is handled by this ruleset and +should then be forbidden if no rule explicitly allows them +(see +.B Filesystem actions +in +.BR landlock (7)). +This enables simply restricting ambient rights +(e.g., global filesystem access) and is needed for compatibility reasons. +.P +.I size +must be specified as +.I sizeof(struct landlock_ruleset_attr) +for compatibility reasons. +.P +.I flags +must be 0 if +.I attr +is used. +Otherwise, +.I flags +can be set to: +.TP +.B LANDLOCK_CREATE_RULESET_VERSION +If +.I attr +is NULL and +.I size +is 0, then the returned value is the highest supported Landlock ABI version +(starting at 1). +This version can be used for a best-effort security approach, +which is encouraged when user space is not pinned to a specific kernel +version. +All features documented in these man pages are available with the version +1. +.SH RETURN VALUE +On success, +.BR landlock_create_ruleset () +returns a new Landlock ruleset file descriptor, +or a Landlock ABI version, +according to +.IR flags . +.SH ERRORS +.BR landlock_create_ruleset () +can fail for the following reasons: +.TP +.B EOPNOTSUPP +Landlock is supported by the kernel but disabled at boot time. +.TP +.B EINVAL +Unknown +.IR flags , +or unknown access, or too small +.IR size . +.TP +.B E2BIG +.I size +is too big. +.TP +.B EFAULT +.I attr +was not a valid address. +.TP +.B ENOMSG +Empty accesses (i.e., +.I attr\->handled_access_fs +is 0). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.13. +.SH EXAMPLES +See +.BR landlock (7). +.SH SEE ALSO +.BR landlock_add_rule (2), +.BR landlock_restrict_self (2), +.BR landlock (7) diff --git a/man/man2/landlock_restrict_self.2 b/man/man2/landlock_restrict_self.2 new file mode 100644 index 0000000..1ac611e --- /dev/null +++ b/man/man2/landlock_restrict_self.2 @@ -0,0 +1,116 @@ +.\" Copyright © 2017-2020 Mickaël Salaün +.\" Copyright © 2019-2020 ANSSI +.\" Copyright © 2021 Microsoft Corporation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH landlock_restrict_self 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +landlock_restrict_self \- enforce a Landlock ruleset +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " LANDLOCK_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.P +.BI "int syscall(SYS_landlock_restrict_self, int " ruleset_fd , +.BI " uint32_t " flags ); +.SH DESCRIPTION +Once a Landlock ruleset is populated with the desired rules, the +.BR landlock_restrict_self () +system call enables enforcing this ruleset on the calling thread. +See +.BR landlock (7) +for a global overview. +.P +A thread can be restricted with multiple rulesets that are then +composed together to form the thread's Landlock domain. +This can be seen as a stack of rulesets but +it is implemented in a more efficient way. +A domain can only be updated in such a way that +the constraints of each past and future composed rulesets +will restrict the thread and its future children for their entire life. +It is then possible to gradually enforce tailored access control policies +with multiple independent rulesets coming from different sources +(e.g., init system configuration, user session policy, +built-in application policy). +However, most applications should only need one call to +.BR landlock_restrict_self () +and they should avoid arbitrary numbers of such calls because of the +composed rulesets limit. +Instead, developers are encouraged to build a tailored ruleset thanks to +multiple calls to +.BR landlock_add_rule (2). +.P +In order to enforce a ruleset, either the caller must have the +.B CAP_SYS_ADMIN +capability in its user namespace, or the thread must already have the +.I no_new_privs +bit set. +As for +.BR seccomp (2), +this avoids scenarios where unprivileged processes can affect +the behavior of privileged children (e.g., because of set-user-ID binaries). +If that bit was not already set by an ancestor of this thread, +the thread must make the following call: +.IP +.EX +prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0); +.EE +.P +.I ruleset_fd +is a Landlock ruleset file descriptor obtained with +.BR landlock_create_ruleset (2) +and fully populated with a set of calls to +.BR landlock_add_rule (2). +.P +.I flags +must be 0. +.SH RETURN VALUE +On success, +.BR landlock_restrict_self () +returns 0. +.SH ERRORS +.BR landlock_restrict_self () +can fail for the following reasons: +.TP +.B EOPNOTSUPP +Landlock is supported by the kernel but disabled at boot time. +.TP +.B EINVAL +.I flags +is not 0. +.TP +.B EBADF +.I ruleset_fd +is not a file descriptor for the current thread. +.TP +.B EBADFD +.I ruleset_fd +is not a ruleset file descriptor. +.TP +.B EPERM +.I ruleset_fd +has no read access to the underlying ruleset, +or the calling thread is not running with +.IR no_new_privs , +or it doesn't have the +.B CAP_SYS_ADMIN +in its user namespace. +.TP +.B E2BIG +The maximum number of composed rulesets is reached for the calling thread. +This limit is currently 64. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.13. +.SH EXAMPLES +See +.BR landlock (7). +.SH SEE ALSO +.BR landlock_create_ruleset (2), +.BR landlock_add_rule (2), +.BR landlock (7) diff --git a/man/man2/lchown.2 b/man/man2/lchown.2 new file mode 100644 index 0000000..f0a5635 --- /dev/null +++ b/man/man2/lchown.2 @@ -0,0 +1 @@ +.so man2/chown.2 diff --git a/man/man2/lchown32.2 b/man/man2/lchown32.2 new file mode 100644 index 0000000..8ed3964 --- /dev/null +++ b/man/man2/lchown32.2 @@ -0,0 +1 @@ +.so man2/lchown.2 diff --git a/man/man2/lgetxattr.2 b/man/man2/lgetxattr.2 new file mode 100644 index 0000000..d9e5d90 --- /dev/null +++ b/man/man2/lgetxattr.2 @@ -0,0 +1 @@ +.so man2/getxattr.2 diff --git a/man/man2/link.2 b/man/man2/link.2 new file mode 100644 index 0000000..9f09b0b --- /dev/null +++ b/man/man2/link.2 @@ -0,0 +1,425 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1994-08-21 by Michael Haardt +.\" Modified 2004-06-23 by Michael Kerrisk +.\" Modified 2005-04-04, as per suggestion by Michael Hardt for rename.2 +.\" +.TH link 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +link, linkat \- make a new name for a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int link(const char *" oldpath ", const char *" newpath ); +.P +.BR "#include " "/* Definition of " AT_* " constants */" +.B #include +.P +.BI "int linkat(int " olddirfd ", const char *" oldpath , +.BI " int " newdirfd ", const char *" newpath ", int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR linkat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +.BR link () +creates a new link (also known as a hard link) to an existing file. +.P +If +.I newpath +exists, it will +.I not +be overwritten. +.P +This new name may be used exactly as the old one for any operation; +both names refer to the same file (and so have the same permissions +and ownership) and it is impossible to tell which name was the +"original". +.SS linkat() +The +.BR linkat () +system call operates in exactly the same way as +.BR link (), +except for the differences described here. +.P +If the pathname given in +.I oldpath +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I olddirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR link () +for a relative pathname). +.P +If +.I oldpath +is relative and +.I olddirfd +is the special value +.BR AT_FDCWD , +then +.I oldpath +is interpreted relative to the current working +directory of the calling process (like +.BR link ()). +.P +If +.I oldpath +is absolute, then +.I olddirfd +is ignored. +.P +The interpretation of +.I newpath +is as for +.IR oldpath , +except that a relative pathname is interpreted relative +to the directory referred to by the file descriptor +.IR newdirfd . +.P +The following values can be bitwise ORed in +.IR flags : +.TP +.BR AT_EMPTY_PATH " (since Linux 2.6.39)" +.\" commit 11a7b371b64ef39fc5fb1b6f2218eef7c4d035e3 +If +.I oldpath +is an empty string, create a link to the file referenced by +.I olddirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I olddirfd +can refer to any type of file except a directory. +This will generally not work if the file has a link count of zero (files +created with +.B O_TMPFILE +and without +.B O_EXCL +are an exception). +The caller must have the +.B CAP_DAC_READ_SEARCH +capability in order to use this flag. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.BR AT_SYMLINK_FOLLOW " (since Linux 2.6.18)" +By default, +.BR linkat (), +does not dereference +.I oldpath +if it is a symbolic link (like +.BR link ()). +The flag +.B AT_SYMLINK_FOLLOW +can be specified in +.I flags +to cause +.I oldpath +to be dereferenced if it is a symbolic link. +If procfs is mounted, +this can be used as an alternative to +.BR AT_EMPTY_PATH , +like this: +.IP +.in +4n +.EX +linkat(AT_FDCWD, "/proc/self/fd/", newdirfd, + newname, AT_SYMLINK_FOLLOW); +.EE +.in +.P +Before Linux 2.6.18, the +.I flags +argument was unused, and had to be specified as 0. +.P +See +.BR openat (2) +for an explanation of the need for +.BR linkat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I newpath +is denied, or search permission is denied for one of the directories +in the path prefix of +.I oldpath +or +.IR newpath . +(See also +.BR path_resolution (7).) +.TP +.B EDQUOT +The user's quota of disk blocks on the filesystem has been exhausted. +.TP +.B EEXIST +.I newpath +already exists. +.TP +.B EFAULT +.IR oldpath " or " newpath " points outside your accessible address space." +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR oldpath " or " newpath . +.TP +.B EMLINK +The file referred to by +.I oldpath +already has the maximum number of links to it. +For example, on an +.BR ext4 (5) +filesystem that does not employ the +.I dir_index +feature, the limit on the number of hard links to a file is 65,000; on +.BR btrfs (5), +the limit is 65,535 links. +.TP +.B ENAMETOOLONG +.IR oldpath " or " newpath " was too long." +.TP +.B ENOENT +A directory component in +.IR oldpath " or " newpath +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing the file has no room for the new directory +entry. +.TP +.B ENOTDIR +A component used as a directory in +.IR oldpath " or " newpath +is not, in fact, a directory. +.TP +.B EPERM +.I oldpath +is a directory. +.TP +.B EPERM +The filesystem containing +.IR oldpath " and " newpath +does not support the creation of hard links. +.TP +.BR EPERM " (since Linux 3.6)" +The caller does not have permission to create a hard link to this file +(see the description of +.I /proc/sys/fs/protected_hardlinks +in +.BR proc (5)). +.TP +.B EPERM +.I oldpath +is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.TP +.B EROFS +The file is on a read-only filesystem. +.TP +.B EXDEV +.IR oldpath " and " newpath +are not on the same mounted filesystem. +(Linux permits a filesystem to be mounted at multiple points, but +.BR link () +does not work across different mounts, +even if the same filesystem is mounted on both.) +.P +The following additional errors can occur for +.BR linkat (): +.TP +.B EBADF +.I oldpath +.RI ( newpath ) +is relative but +.I olddirfd +.RI ( newdirfd ) +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EINVAL +An invalid flag value was specified in +.IR flags . +.TP +.B ENOENT +.B AT_EMPTY_PATH +was specified in +.IR flags , +but the caller did not have the +.B CAP_DAC_READ_SEARCH +capability. +.TP +.B ENOENT +An attempt was made to link to the +.I /proc/self/fd/NN +file corresponding to a file descriptor created with +.IP +.in +4n +.EX +open(path, O_TMPFILE | O_EXCL, mode); +.EE +.in +.IP +See +.BR open (2). +.TP +.B ENOENT +An attempt was made to link to a +.I /proc/self/fd/NN +file corresponding to a file that has been deleted. +.TP +.B ENOENT +.I oldpath +is a relative pathname and +.I olddirfd +refers to a directory that has been deleted, +or +.I newpath +is a relative pathname and +.I newdirfd +refers to a directory that has been deleted. +.TP +.B ENOTDIR +.I oldpath +is relative and +.I olddirfd +is a file descriptor referring to a file other than a directory; +or similar for +.I newpath +and +.I newdirfd +.TP +.B EPERM +.B AT_EMPTY_PATH +was specified in +.IR flags , +.I oldpath +is an empty string, and +.I olddirfd +refers to a directory. +.SH VERSIONS +POSIX.1-2001 says that +.BR link () +should dereference +.I oldpath +if it is a symbolic link. +However, since Linux 2.0, +.\" more precisely: since Linux 1.3.56 +Linux does not do so: if +.I oldpath +is a symbolic link, then +.I newpath +is created as a (hard) link to the same symbolic link file +(i.e., +.I newpath +becomes a symbolic link to the same file that +.I oldpath +refers to). +Some other implementations behave in the same manner as Linux. +.\" For example, the default Solaris compilation environment +.\" behaves like Linux, and contributors to a March 2005 +.\" thread in the Austin mailing list reported that some +.\" other (System V) implementations did/do the same -- MTK, Apr 05 +POSIX.1-2008 changes the specification of +.BR link (), +making it implementation-dependent whether or not +.I oldpath +is dereferenced if it is a symbolic link. +For precise control over the treatment of symbolic links when +creating a link, use +.BR linkat (). +.SS glibc +On older kernels where +.BR linkat () +is unavailable, the glibc wrapper function falls back to the use of +.BR link (), +unless the +.B AT_SYMLINK_FOLLOW +is specified. +When +.I oldpath +and +.I newpath +are relative pathnames, +glibc constructs pathnames based on the symbolic links in +.I /proc/self/fd +that correspond to the +.I olddirfd +and +.I newdirfd +arguments. +.SH STANDARDS +.TP +.BR link () +POSIX.1-2008. +.SH HISTORY +.TP +.BR link () +SVr4, 4.3BSD, POSIX.1-2001 (but see VERSIONS). +.\" SVr4 documents additional ENOLINK and +.\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP. +.\" X/OPEN does not document EFAULT, ENOMEM or EIO. +.TP +.BR linkat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. +.SH NOTES +Hard links, as created by +.BR link (), +cannot span filesystems. +Use +.BR symlink (2) +if this is required. +.SH BUGS +On NFS filesystems, the return code may be wrong in case the NFS server +performs the link creation and dies before it can say so. +Use +.BR stat (2) +to find out if the link got created. +.SH SEE ALSO +.BR ln (1), +.BR open (2), +.BR rename (2), +.BR stat (2), +.BR symlink (2), +.BR unlink (2), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/linkat.2 b/man/man2/linkat.2 new file mode 100644 index 0000000..a7d6da5 --- /dev/null +++ b/man/man2/linkat.2 @@ -0,0 +1 @@ +.so man2/link.2 diff --git a/man/man2/listen.2 b/man/man2/listen.2 new file mode 100644 index 0000000..22f6ac6 --- /dev/null +++ b/man/man2/listen.2 @@ -0,0 +1,155 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" and Copyright (C) 2007, Michael Kerrisk +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" $Id: listen.2,v 1.6 1999/05/18 14:10:32 freitag Exp $ +.\" +.\" Modified Fri Jul 23 22:07:54 1993 by Rik Faith +.\" Modified 950727 by aeb, following a suggestion by Urs Thuermann +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified 1998 by Andi Kleen +.\" Modified 11 May 2001 by Sam Varshavchik +.\" +.\" +.TH listen 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +listen \- listen for connections on a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int listen(int " sockfd ", int " backlog ); +.fi +.SH DESCRIPTION +.BR listen () +marks the socket referred to by +.I sockfd +as a passive socket, that is, as a socket that will +be used to accept incoming connection requests using +.BR accept (2). +.P +The +.I sockfd +argument is a file descriptor that refers to a socket of type +.B SOCK_STREAM +or +.BR SOCK_SEQPACKET . +.P +The +.I backlog +argument defines the maximum length +to which the queue of pending connections for +.I sockfd +may grow. +If a connection request arrives when the queue is full, the client +may receive an error with an indication of +.B ECONNREFUSED +or, if the underlying protocol supports retransmission, the request may be +ignored so that a later reattempt at connection succeeds. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EADDRINUSE +Another socket is already listening on the same port. +.TP +.B EADDRINUSE +(Internet domain sockets) +The socket referred to by +.I sockfd +had not previously been bound to an address and, +upon attempting to bind it to an ephemeral port, +it was determined that all port numbers in the ephemeral port range +are currently in use. +See the discussion of +.I /proc/sys/net/ipv4/ip_local_port_range +in +.BR ip (7). +.TP +.B EBADF +The argument +.I sockfd +is not a valid file descriptor. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.TP +.B EOPNOTSUPP +The socket is not of a type that supports the +.BR listen () +operation. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.4BSD +(first appeared in 4.2BSD). +.SH NOTES +To accept connections, the following steps are performed: +.RS 4 +.IP (1) 5 +A socket is created with +.BR socket (2). +.IP (2) +The socket is bound to a local address using +.BR bind (2), +so that other sockets may be +.BR connect (2)ed +to it. +.IP (3) +A willingness to accept incoming connections and a queue limit for incoming +connections are specified with +.BR listen (). +.IP (4) +Connections are accepted with +.BR accept (2). +.RE +.P +The behavior of the +.I backlog +argument on TCP sockets changed with Linux 2.2. +Now it specifies the queue length for +.I completely +established sockets waiting to be accepted, +instead of the number of incomplete connection requests. +The maximum length of the queue for incomplete sockets +can be set using +.IR /proc/sys/net/ipv4/tcp_max_syn_backlog . +When syncookies are enabled there is no logical maximum +length and this setting is ignored. +See +.BR tcp (7) +for more information. +.P +If the +.I backlog +argument is greater than the value in +.IR /proc/sys/net/core/somaxconn , +then it is silently capped to that value. +Since Linux 5.4, the default in this file is 4096; +in earlier kernels, the default value is 128. +Before Linux 2.4.25, this limit was a hard coded value, +.BR SOMAXCONN , +with the value 128. +.\" The following is now rather historic information (MTK, Jun 05) +.\" Don't rely on this value in portable applications since BSD +.\" (and some BSD-derived systems) limit the backlog to 5. +.SH EXAMPLES +See +.BR bind (2). +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR connect (2), +.BR socket (2), +.BR socket (7) diff --git a/man/man2/listxattr.2 b/man/man2/listxattr.2 new file mode 100644 index 0000000..0697b15 --- /dev/null +++ b/man/man2/listxattr.2 @@ -0,0 +1,322 @@ +.\" Copyright (C) Andreas Gruenbacher, February 2001 +.\" Copyright (C) Silicon Graphics Inc, September 2001 +.\" Copyright (C) 2015 Heinrich Schuchardt +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH listxattr 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +listxattr, llistxattr, flistxattr \- list extended attribute names +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t listxattr(const char *" path ", char *_Nullable " list \ +", size_t " size ); +.BI "ssize_t llistxattr(const char *" path ", char *_Nullable " list \ +", size_t " size ); +.BI "ssize_t flistxattr(int " fd ", char *_Nullable " list ", size_t " size ); +.fi +.SH DESCRIPTION +Extended attributes are +.IR name : value +pairs associated with inodes (files, directories, symbolic links, etc.). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e., the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR xattr (7). +.P +.BR listxattr () +retrieves the list +of extended attribute names associated with the given +.I path +in the filesystem. +The retrieved list is placed in +.IR list , +a caller-allocated buffer whose size (in bytes) is specified in the argument +.IR size . +The list is the set of (null-terminated) names, one after the other. +Names of extended attributes to which the calling process does not +have access may be omitted from the list. +The length of the attribute name +.I list +is returned. +.P +.BR llistxattr () +is identical to +.BR listxattr (), +except in the case of a symbolic link, where the list of names of +extended attributes associated with the link itself is retrieved, +not the file that it refers to. +.P +.BR flistxattr () +is identical to +.BR listxattr (), +only the open file referred to by +.I fd +(as returned by +.BR open (2)) +is interrogated in place of +.IR path . +.P +A single extended attribute +.I name +is a null-terminated string. +The name includes a namespace prefix; there may be several, disjoint +namespaces associated with an individual inode. +.P +If +.I size +is specified as zero, these calls return the current size of the +list of extended attribute names (and leave +.I list +unchanged). +This can be used to determine the size of the buffer that +should be supplied in a subsequent call. +(But, bear in mind that there is a possibility that the +set of extended attributes may change between the two calls, +so that it is still necessary to check the return status +from the second call.) +.SS Example +The +.I list +of names is returned as an unordered array of null-terminated character strings +(attribute names are separated by null bytes (\[aq]\e0\[aq])), +like this: +.P +.in +4n +.EX +user.name1\e0system.name1\e0user.name2\e0 +.EE +.in +.P +Filesystems that implement POSIX ACLs using +extended attributes might return a +.I list +like this: +.P +.in +4n +.EX +system.posix_acl_access\e0system.posix_acl_default\e0 +.EE +.in +.SH RETURN VALUE +On success, a nonnegative number is returned indicating the size of the +extended attribute name list. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B E2BIG +The size of the list of extended attribute names is larger than the maximum +size allowed; the list cannot be retrieved. +This can happen on filesystems that support an unlimited number of +extended attributes per file such as XFS, for example. +See BUGS. +.TP +.B ENOTSUP +Extended attributes are not supported by the filesystem, or are disabled. +.TP +.B ERANGE +The +.I size +of the +.I list +buffer is too small to hold the result. +.P +In addition, the errors documented in +.BR stat (2) +can also occur. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.4, +glibc 2.3. +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@computer.org > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.\" Please send any bug reports or comments to these addresses. +.SH BUGS +.\" The xattr(7) page refers to this text: +As noted in +.BR xattr (7), +the VFS imposes a limit of 64\ kB on the size of the extended +attribute name list returned by +.BR listxattr (). +If the total size of attribute names attached to a file exceeds this limit, +it is no longer possible to retrieve the list of attribute names. +.SH EXAMPLES +The following program demonstrates the usage of +.BR listxattr () +and +.BR getxattr (2). +For the file whose pathname is provided as a command-line argument, +it lists all extended file attributes and their values. +.P +To keep the code simple, the program assumes that attribute keys and +values are constant during the execution of the program. +A production program should expect and handle changes during +execution of the program. +For example, +the number of bytes required for attribute keys +might increase between the two calls to +.BR listxattr (). +An application could handle this possibility using +a loop that retries the call +(perhaps up to a predetermined maximum number of attempts) +with a larger buffer each time it fails with the error +.BR ERANGE . +Calls to +.BR getxattr (2) +could be handled similarly. +.P +The following output was recorded by first creating a file, setting +some extended file attributes, +and then listing the attributes with the example program. +.SS Example output +.in +4n +.EX +$ \fBtouch /tmp/foo\fP +$ \fBsetfattr \-n user.fred \-v chocolate /tmp/foo\fP +$ \fBsetfattr \-n user.frieda \-v bar /tmp/foo\fP +$ \fBsetfattr \-n user.empty /tmp/foo\fP +$ \fB./listxattr /tmp/foo\fP +user.fred: chocolate +user.frieda: bar +user.empty: +.EE +.in +.SS Program source (listxattr.c) +.\" SRC BEGIN (listxattr.c) +.EX +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + char *buf, *key, *val; + ssize_t buflen, keylen, vallen; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s path\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* + * Determine the length of the buffer needed. + */ + buflen = listxattr(argv[1], NULL, 0); + if (buflen == \-1) { + perror("listxattr"); + exit(EXIT_FAILURE); + } + if (buflen == 0) { + printf("%s has no attributes.\en", argv[1]); + exit(EXIT_SUCCESS); + } +\& + /* + * Allocate the buffer. + */ + buf = malloc(buflen); + if (buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + /* + * Copy the list of attribute keys to the buffer. + */ + buflen = listxattr(argv[1], buf, buflen); + if (buflen == \-1) { + perror("listxattr"); + exit(EXIT_FAILURE); + } +\& + /* + * Loop over the list of zero terminated strings with the + * attribute keys. Use the remaining buffer length to determine + * the end of the list. + */ + key = buf; + while (buflen > 0) { +\& + /* + * Output attribute key. + */ + printf("%s: ", key); +\& + /* + * Determine length of the value. + */ + vallen = getxattr(argv[1], key, NULL, 0); + if (vallen == \-1) + perror("getxattr"); +\& + if (vallen > 0) { +\& + /* + * Allocate value buffer. + * One extra byte is needed to append 0x00. + */ + val = malloc(vallen + 1); + if (val == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + /* + * Copy value to buffer. + */ + vallen = getxattr(argv[1], key, val, vallen); + if (vallen == \-1) { + perror("getxattr"); + } else { + /* + * Output attribute value. + */ + val[vallen] = 0; + printf("%s", val); + } +\& + free(val); + } else if (vallen == 0) { + printf(""); + } +\& + printf("\en"); +\& + /* + * Forward to next attribute key. + */ + keylen = strlen(key) + 1; + buflen \-= keylen; + key += keylen; + } +\& + free(buf); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR open (2), +.BR removexattr (2), +.BR setxattr (2), +.BR stat (2), +.BR symlink (7), +.BR xattr (7) diff --git a/man/man2/llistxattr.2 b/man/man2/llistxattr.2 new file mode 100644 index 0000000..117bd2b --- /dev/null +++ b/man/man2/llistxattr.2 @@ -0,0 +1 @@ +.so man2/listxattr.2 diff --git a/man/man2/llseek.2 b/man/man2/llseek.2 new file mode 100644 index 0000000..d885dd9 --- /dev/null +++ b/man/man2/llseek.2 @@ -0,0 +1,92 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" Written 10 June 1995 by Andries Brouwer +.\" and Copyright (C) 2007, 2015, 2020, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Thu Oct 31 15:16:23 1996 by Eric S. Raymond +.\" +.TH _llseek 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +_llseek \- reposition read/write file offset +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS__llseek, unsigned int " fd ", unsigned long " offset_high , +.BI " unsigned long " offset_low ", loff_t *" result , +.BI " unsigned int " whence ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR _llseek (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +Note: for information about the +.BR llseek (3) +library function, see +.BR lseek64 (3). +.P +The +.BR _llseek () +system call repositions the offset of the open file description associated +with the file descriptor +.I fd +to the value +.IP +(offset_high << 32) | offset_low +.P +This new offset is a byte offset +relative to the beginning of the file, the current file offset, +or the end of the file, depending on whether +.I whence +is +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +respectively. +.P +The new file offset is returned in the argument +.IR result . +The type +.I loff_t +is a 64-bit signed type. +.P +This system call exists on various 32-bit platforms to support +seeking to large file offsets. +.SH RETURN VALUE +Upon successful completion, +.BR _llseek () +returns 0. +Otherwise, a value of \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EFAULT +Problem with copying results to user space. +.TP +.B EINVAL +.I whence +is invalid. +.SH VERSIONS +You probably want to use the +.BR lseek (2) +wrapper function instead. +.SH STANDARDS +Linux. +.SH SEE ALSO +.BR lseek (2), +.BR open (2), +.BR lseek64 (3) diff --git a/man/man2/lock.2 b/man/man2/lock.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/lock.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/lookup_dcookie.2 b/man/man2/lookup_dcookie.2 new file mode 100644 index 0000000..8131b98 --- /dev/null +++ b/man/man2/lookup_dcookie.2 @@ -0,0 +1,86 @@ +.\" Copyright (C) 2003 John Levon +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2004-06-17 Michael Kerrisk +.\" +.TH lookup_dcookie 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lookup_dcookie \- return a directory entry's path +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_lookup_dcookie, uint64_t " cookie ", char *" buffer , +.BI " size_t " len ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR lookup_dcookie (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +Look up the full path of the directory entry specified by the value +.IR cookie . +The cookie is an opaque identifier uniquely identifying a particular +directory entry. +The buffer given is filled in with the full path of the directory entry. +.P +For +.BR lookup_dcookie () +to return successfully, +the kernel must still hold a cookie reference to the directory entry. +.SH RETURN VALUE +On success, +.BR lookup_dcookie () +returns the length of the path string copied into the buffer. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +The buffer was not valid. +.TP +.B EINVAL +The kernel has no registered cookie/directory entry mappings at the +time of lookup, or the cookie does not refer to a valid directory entry. +.TP +.B ENAMETOOLONG +The name could not fit in the buffer. +.TP +.B ENOMEM +The kernel could not allocate memory for the temporary buffer holding +the path. +.TP +.B EPERM +The process does not have the capability +.B CAP_SYS_ADMIN +required to look up cookie values. +.TP +.B ERANGE +The buffer was not large enough to hold the path of the directory entry. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5.43. +.P +The +.B ENAMETOOLONG +error was added in Linux 2.5.70. +.SH NOTES +.BR lookup_dcookie () +is a special-purpose system call, currently used only by the +.BR oprofile (1) +profiler. +It relies on a kernel driver to register cookies for directory entries. +.P +The path returned may be suffixed by the string " (deleted)" if the directory +entry has been removed. +.SH SEE ALSO +.BR oprofile (1) diff --git a/man/man2/lremovexattr.2 b/man/man2/lremovexattr.2 new file mode 100644 index 0000000..38d01cc --- /dev/null +++ b/man/man2/lremovexattr.2 @@ -0,0 +1 @@ +.so man2/removexattr.2 diff --git a/man/man2/lseek.2 b/man/man2/lseek.2 new file mode 100644 index 0000000..5e458f4 --- /dev/null +++ b/man/man2/lseek.2 @@ -0,0 +1,252 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" and Copyright (c) 2011, Michael Kerrisk +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)lseek.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1995-06-10 by Andries Brouwer +.\" Modified 1996-10-31 by Eric S. Raymond +.\" Modified 1998-01-17 by Michael Haardt +.\" +.\" Modified 2001-09-24 by Michael Haardt +.\" Modified 2003-08-21 by Andries Brouwer +.\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE +.\" +.TH lseek 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lseek \- reposition read/write file offset +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); +.fi +.SH DESCRIPTION +.BR lseek () +repositions the file offset of the open file description +associated with the file descriptor +.I fd +to the argument +.I offset +according to the directive +.I whence +as follows: +.TP +.B SEEK_SET +The file offset is set to +.I offset +bytes. +.TP +.B SEEK_CUR +The file offset is set to its current location plus +.I offset +bytes. +.TP +.B SEEK_END +The file offset is set to the size of the file plus +.I offset +bytes. +.P +.BR lseek () +allows the file offset to be set beyond the end +of the file (but this does not change the size of the file). +If data is later written at this point, subsequent reads of the data +in the gap (a "hole") return null bytes (\[aq]\e0\[aq]) until +data is actually written into the gap. +.SS Seeking file data and holes +Since Linux 3.1, Linux supports the following additional values for +.IR whence : +.TP +.B SEEK_DATA +Adjust the file offset to the next location +in the file greater than or equal to +.I offset +containing data. +If +.I offset +points to data, +then the file offset is set to +.IR offset . +.TP +.B SEEK_HOLE +Adjust the file offset to the next hole in the file +greater than or equal to +.IR offset . +If +.I offset +points into the middle of a hole, +then the file offset is set to +.IR offset . +If there is no hole past +.IR offset , +then the file offset is adjusted to the end of the file +(i.e., there is an implicit hole at the end of any file). +.P +In both of the above cases, +.BR lseek () +fails if +.I offset +points past the end of the file. +.P +These operations allow applications to map holes in a sparsely +allocated file. +This can be useful for applications such as file backup tools, +which can save space when creating backups and preserve holes, +if they have a mechanism for discovering holes. +.P +For the purposes of these operations, a hole is a sequence of zeros that +(normally) has not been allocated in the underlying file storage. +However, a filesystem is not obliged to report holes, +so these operations are not a guaranteed mechanism for +mapping the storage space actually allocated to a file. +(Furthermore, a sequence of zeros that actually has been written +to the underlying storage may not be reported as a hole.) +In the simplest implementation, +a filesystem can support the operations by making +.B SEEK_HOLE +always return the offset of the end of the file, +and making +.B SEEK_DATA +always return +.I offset +(i.e., even if the location referred to by +.I offset +is a hole, +it can be considered to consist of data that is a sequence of zeros). +.\" https://lkml.org/lkml/2011/4/22/79 +.\" http://lwn.net/Articles/440255/ +.\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data +.P +The +.B _GNU_SOURCE +feature test macro must be defined in order to obtain the definitions of +.B SEEK_DATA +and +.B SEEK_HOLE +from +.IR . +.P +The +.B SEEK_HOLE +and +.B SEEK_DATA +operations are supported for the following filesystems: +.IP \[bu] 3 +Btrfs (since Linux 3.1) +.IP \[bu] +OCFS (since Linux 3.2) +.\" commit 93862d5e1ab875664c6cc95254fc365028a48bb1 +.IP \[bu] +XFS (since Linux 3.5) +.IP \[bu] +ext4 (since Linux 3.8) +.IP \[bu] +.BR tmpfs (5) +(since Linux 3.8) +.IP \[bu] +NFS (since Linux 3.18) +.\" commit 1c6dcbe5ceff81c2cf8d929646af675cd59fe7c0 +.\" commit 24bab491220faa446d945624086d838af41d616c +.IP \[bu] +FUSE (since Linux 4.5) +.\" commit 0b5da8db145bfd44266ac964a2636a0cf8d7c286 +.IP \[bu] +GFS2 (since Linux 4.15) +.\" commit 3a27411cb4bc3ce31db228e3569ad01b462a4310 +.SH RETURN VALUE +Upon successful completion, +.BR lseek () +returns the resulting offset location as measured in bytes from the +beginning of the file. +On error, the value \fI(off_t)\ \-1\fP is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not an open file descriptor. +.TP +.B EINVAL +.I whence +is not valid. +Or: the resulting file offset would be negative, +or beyond the end of a seekable device. +.\" Some systems may allow negative offsets for character devices +.\" and/or for remote filesystems. +.TP +.B ENXIO +.I whence +is +.B SEEK_DATA +or +.BR SEEK_HOLE , +and +.I offset +is beyond the end of the file, or +.I whence +is +.B SEEK_DATA +and +.I offset +is within a hole at the end of the file. +.TP +.B EOVERFLOW +.\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW) +The resulting file offset cannot be represented in an +.IR off_t . +.TP +.B ESPIPE +.I fd +is associated with a pipe, socket, or FIFO. +.SH VERSIONS +On Linux, using +.BR lseek () +on a terminal device fails with the error +.BR ESPIPE . +.\" Other systems return the number of written characters, +.\" using SEEK_SET to set the counter. (Of written characters.) +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.P +.B SEEK_DATA +and +.B SEEK_HOLE +are nonstandard extensions also present in Solaris, +FreeBSD, and DragonFly BSD; +they are proposed for inclusion in the next POSIX revision (Issue 8). +.\" FIXME . Review http://austingroupbugs.net/view.php?id=415 in the future +.SH NOTES +See +.BR open (2) +for a discussion of the relationship between file descriptors, +open file descriptions, and files. +.P +If the +.B O_APPEND +file status flag is set on the open file description, +then a +.BR write (2) +.I always +moves the file offset to the end of the file, regardless of the use of +.BR lseek (). +.P +Some devices are incapable of seeking and POSIX does not specify which +devices must support +.BR lseek (). +.SH SEE ALSO +.BR dup (2), +.BR fallocate (2), +.BR fork (2), +.BR open (2), +.BR fseek (3), +.BR lseek64 (3), +.BR posix_fallocate (3) diff --git a/man/man2/lsetxattr.2 b/man/man2/lsetxattr.2 new file mode 100644 index 0000000..dc07807 --- /dev/null +++ b/man/man2/lsetxattr.2 @@ -0,0 +1 @@ +.so man2/setxattr.2 diff --git a/man/man2/lstat.2 b/man/man2/lstat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man/man2/lstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man/man2/lstat64.2 b/man/man2/lstat64.2 new file mode 100644 index 0000000..89b1c84 --- /dev/null +++ b/man/man2/lstat64.2 @@ -0,0 +1 @@ +.so man2/lstat.2 diff --git a/man/man2/madvise.2 b/man/man2/madvise.2 new file mode 100644 index 0000000..d08ca71 --- /dev/null +++ b/man/man2/madvise.2 @@ -0,0 +1,898 @@ +.\" Copyright (C) 2001 David Gómez +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Based on comments from mm/filemap.c. Last modified on 10-06-2001 +.\" Modified, 25 Feb 2002, Michael Kerrisk, +.\" Added notes on MADV_DONTNEED +.\" 2010-06-19, mtk, Added documentation of MADV_MERGEABLE and +.\" MADV_UNMERGEABLE +.\" 2010-06-15, Andi Kleen, Add documentation of MADV_HWPOISON. +.\" 2010-06-19, Andi Kleen, Add documentation of MADV_SOFT_OFFLINE. +.\" 2011-09-18, Doug Goldstein +.\" Document MADV_HUGEPAGE and MADV_NOHUGEPAGE +.\" +.TH madvise 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +madvise \- give advice about use of memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int madvise(void " addr [. length "], size_t " length ", int " advice ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR madvise (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + Up to and including glibc 2.19: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR madvise () +system call is used to give advice or directions to the kernel +about the address range beginning at address +.I addr +and with size +.IR length . +.BR madvise () +only operates on whole pages, therefore +.I addr +must be page-aligned. +The value of +.I length +is rounded up to a multiple of page size. +In most cases, +the goal of such advice is to improve system or application performance. +.P +Initially, the system call supported a set of "conventional" +.I advice +values, which are also available on several other implementations. +(Note, though, that +.BR madvise () +is not specified in POSIX.) +Subsequently, a number of Linux-specific +.I advice +values have been added. +.\" +.\" ====================================================================== +.\" +.SS Conventional advice values +The +.I advice +values listed below +allow an application to tell the kernel how it expects to use +some mapped or shared memory areas, so that the kernel can choose +appropriate read-ahead and caching techniques. +These +.I advice +values do not influence the semantics of the application +(except in the case of +.BR MADV_DONTNEED ), +but may influence its performance. +All of the +.I advice +values listed here have analogs in the POSIX-specified +.BR posix_madvise (3) +function, and the values have the same meanings, with the exception of +.BR MADV_DONTNEED . +.P +The advice is indicated in the +.I advice +argument, which is one of the following: +.TP +.B MADV_NORMAL +No special treatment. +This is the default. +.TP +.B MADV_RANDOM +Expect page references in random order. +(Hence, read ahead may be less useful than normally.) +.TP +.B MADV_SEQUENTIAL +Expect page references in sequential order. +(Hence, pages in the given range can be aggressively read ahead, +and may be freed soon after they are accessed.) +.TP +.B MADV_WILLNEED +Expect access in the near future. +(Hence, it might be a good idea to read some pages ahead.) +.TP +.B MADV_DONTNEED +Do not expect access in the near future. +(For the time being, the application is finished with the given range, +so the kernel can free resources associated with it.) +.IP +After a successful +.B MADV_DONTNEED +operation, +the semantics of memory access in the specified region are changed: +subsequent accesses of pages in the range will succeed, but will result +in either repopulating the memory contents from the +up-to-date contents of the underlying mapped file +(for shared file mappings, shared anonymous mappings, +and shmem-based techniques such as System V shared memory segments) +or zero-fill-on-demand pages for anonymous private mappings. +.IP +Note that, when applied to shared mappings, +.B MADV_DONTNEED +might not lead to immediate freeing of the pages in the range. +The kernel is free to delay freeing the pages until an appropriate moment. +The resident set size (RSS) of the calling process will be immediately +reduced however. +.IP +.B MADV_DONTNEED +cannot be applied to locked pages, or +.B VM_PFNMAP +pages. +(Pages marked with the kernel-internal +.B VM_PFNMAP +.\" http://lwn.net/Articles/162860/ +flag are special memory areas that are not managed +by the virtual memory subsystem. +Such pages are typically created by device drivers that +map the pages into user space.) +.IP +Support for Huge TLB pages was added in Linux v5.18. +Addresses within a mapping backed by Huge TLB pages must be aligned +to the underlying Huge TLB page size, +and the range length is rounded up +to a multiple of the underlying Huge TLB page size. +.\" +.\" ====================================================================== +.\" +.SS Linux-specific advice values +The following Linux-specific +.I advice +values have no counterparts in the POSIX-specified +.BR posix_madvise (3), +and may or may not have counterparts in the +.BR madvise () +interface available on other implementations. +Note that some of these operations change the semantics of memory accesses. +.TP +.BR MADV_REMOVE " (since Linux 2.6.16)" +.\" commit f6b3ec238d12c8cc6cc71490c6e3127988460349 +Free up a given range of pages +and its associated backing store. +This is equivalent to punching a hole in the corresponding +range of the backing store (see +.BR fallocate (2)). +Subsequent accesses in the specified address range will see +data with a value of zero. +.\" Databases want to use this feature to drop a section of their +.\" bufferpool (shared memory segments) - without writing back to +.\" disk/swap space. This feature is also useful for supporting +.\" hot-plug memory on UML. +.IP +The specified address range must be mapped shared and writable. +This flag cannot be applied to locked pages, or +.B VM_PFNMAP +pages. +.IP +In the initial implementation, only +.BR tmpfs (5) +supported +.BR MADV_REMOVE ; +but since Linux 3.5, +.\" commit 3f31d07571eeea18a7d34db9af21d2285b807a17 +any filesystem which supports the +.BR fallocate (2) +.B FALLOC_FL_PUNCH_HOLE +mode also supports +.BR MADV_REMOVE . +Filesystems which do not support +.B MADV_REMOVE +fail with the error +.BR EOPNOTSUPP . +.IP +Support for the Huge TLB filesystem was added in Linux v4.3. +.TP +.BR MADV_DONTFORK " (since Linux 2.6.16)" +.\" commit f822566165dd46ff5de9bf895cfa6c51f53bb0c4 +.\" See http://lwn.net/Articles/171941/ +Do not make the pages in this range available to the child after a +.BR fork (2). +This is useful to prevent copy-on-write semantics from changing +the physical location of a page if the parent writes to it after a +.BR fork (2). +(Such page relocations cause problems for hardware that +DMAs into the page.) +.\" [PATCH] madvise MADV_DONTFORK/MADV_DOFORK +.\" Currently, copy-on-write may change the physical address of +.\" a page even if the user requested that the page is pinned in +.\" memory (either by mlock or by get_user_pages). This happens +.\" if the process forks meanwhile, and the parent writes to that +.\" page. As a result, the page is orphaned: in case of +.\" get_user_pages, the application will never see any data hardware +.\" DMA's into this page after the COW. In case of mlock'd memory, +.\" the parent is not getting the realtime/security benefits of mlock. +.\" +.\" In particular, this affects the Infiniband modules which do DMA from +.\" and into user pages all the time. +.\" +.\" This patch adds madvise options to control whether memory range is +.\" inherited across fork. Useful e.g. for when hardware is doing DMA +.\" from/into these pages. Could also be useful to an application +.\" wanting to speed up its forks by cutting large areas out of +.\" consideration. +.\" +.\" SEE ALSO: http://lwn.net/Articles/171941/ +.\" "Tweaks to madvise() and posix_fadvise()", 14 Feb 2006 +.TP +.BR MADV_DOFORK " (since Linux 2.6.16)" +Undo the effect of +.BR MADV_DONTFORK , +restoring the default behavior, whereby a mapping is inherited across +.BR fork (2). +.TP +.BR MADV_HWPOISON " (since Linux 2.6.32)" +.\" commit 9893e49d64a4874ea67849ee2cfbf3f3d6817573 +Poison the pages in the range specified by +.I addr +and +.I length +and handle subsequent references to those pages +like a hardware memory corruption. +This operation is available only for privileged +.RB ( CAP_SYS_ADMIN ) +processes. +This operation may result in the calling process receiving a +.B SIGBUS +and the page being unmapped. +.IP +This feature is intended for testing of memory error-handling code; +it is available only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.BR MADV_MERGEABLE " (since Linux 2.6.32)" +.\" commit f8af4da3b4c14e7267c4ffb952079af3912c51c5 +Enable Kernel Samepage Merging (KSM) for the pages in the range specified by +.I addr +and +.IR length . +The kernel regularly scans those areas of user memory that have +been marked as mergeable, +looking for pages with identical content. +These are replaced by a single write-protected page (which is automatically +copied if a process later wants to update the content of the page). +KSM merges only private anonymous pages (see +.BR mmap (2)). +.IP +The KSM feature is intended for applications that generate many +instances of the same data (e.g., virtualization systems such as KVM). +It can consume a lot of processing power; use with care. +See the Linux kernel source file +.I Documentation/admin\-guide/mm/ksm.rst +for more details. +.IP +The +.B MADV_MERGEABLE +and +.B MADV_UNMERGEABLE +operations are available only if the kernel was configured with +.BR CONFIG_KSM . +.TP +.BR MADV_UNMERGEABLE " (since Linux 2.6.32)" +Undo the effect of an earlier +.B MADV_MERGEABLE +operation on the specified address range; +KSM unmerges whatever pages it had merged in the address range specified by +.I addr +and +.IR length . +.TP +.BR MADV_SOFT_OFFLINE " (since Linux 2.6.33)" +.\" commit afcf938ee0aac4ef95b1a23bac704c6fbeb26de6 +Soft offline the pages in the range specified by +.I addr +and +.IR length . +The memory of each page in the specified range is preserved +(i.e., when next accessed, the same content will be visible, +but in a new physical page frame), +and the original page is offlined +(i.e., no longer used, and taken out of normal memory management). +The effect of the +.B MADV_SOFT_OFFLINE +operation is invisible to (i.e., does not change the semantics of) +the calling process. +.IP +This feature is intended for testing of memory error-handling code; +it is available only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.BR MADV_HUGEPAGE " (since Linux 2.6.38)" +.\" commit 0af4e98b6b095c74588af04872f83d333c958c32 +.\" http://lwn.net/Articles/358904/ +.\" https://lwn.net/Articles/423584/ +Enable Transparent Huge Pages (THP) for pages in the range specified by +.I addr +and +.IR length . +The kernel will regularly scan the areas marked as huge page candidates +to replace them with huge pages. +The kernel will also allocate huge pages directly when the region is +naturally aligned to the huge page size (see +.BR posix_memalign (2)). +.IP +This feature is primarily aimed at applications that use large mappings of +data and access large regions of that memory at a time (e.g., virtualization +systems such as QEMU). +It can very easily waste memory (e.g., a 2\ MB mapping that only ever accesses +1 byte will result in 2\ MB of wired memory instead of one 4\ KB page). +See the Linux kernel source file +.I Documentation/admin\-guide/mm/transhuge.rst +for more details. +.IP +Most common kernels configurations provide +.BR MADV_HUGEPAGE -style +behavior by default, and thus +.B MADV_HUGEPAGE +is normally not necessary. +It is mostly intended for embedded systems, where +.BR MADV_HUGEPAGE -style +behavior may not be enabled by default in the kernel. +On such systems, +this flag can be used in order to selectively enable THP. +Whenever +.B MADV_HUGEPAGE +is used, it should always be in regions of memory with +an access pattern that the developer knows in advance won't risk +to increase the memory footprint of the application when transparent +hugepages are enabled. +.IP +.\" commit 99cb0dbd47a15d395bf3faa78dc122bc5efe3fc0 +Since Linux 5.4, +automatic scan of eligible areas and replacement by huge pages works with +private anonymous pages (see +.BR mmap (2)), +shmem pages, +and file-backed pages. +For all memory types, +memory may only be replaced by huge pages on hugepage-aligned boundaries. +For file-mapped memory +\[em]including tmpfs (see +.BR tmpfs (2))\[em] +the mapping must also be naturally hugepage-aligned within the file. +Additionally, +for file-backed, +non-tmpfs memory, +the file must not be open for write and the mapping must be executable. +.IP +The VMA must not be marked +.BR VM_NOHUGEPAGE , +.BR VM_HUGETLB , +.BR VM_IO , +.BR VM_DONTEXPAND , +.BR VM_MIXEDMAP , +or +.BR VM_PFNMAP , +nor can it be stack memory or backed by a DAX-enabled device +(unless the DAX device is hot-plugged as System RAM). +The process must also not have +.B PR_SET_THP_DISABLE +set (see +.BR prctl (2)). +.IP +The +.BR MADV_HUGEPAGE , +.BR MADV_NOHUGEPAGE , +and +.B MADV_COLLAPSE +operations are available only if the kernel was configured with +.B CONFIG_TRANSPARENT_HUGEPAGE +and file/shmem memory is only supported if the kernel was configured with +.BR CONFIG_READ_ONLY_THP_FOR_FS . +.TP +.BR MADV_NOHUGEPAGE " (since Linux 2.6.38)" +Ensures that memory in the address range specified by +.I addr +and +.I length +will not be backed by transparent hugepages. +.TP +.BR MADV_COLLAPSE " (since Linux 6.1)" +.\" commit 7d8faaf155454f8798ec56404faca29a82689c77 +.\" commit 34488399fa08faaf664743fa54b271eb6f9e1321 +Perform a best-effort synchronous collapse of +the native pages mapped by the memory range +into Transparent Huge Pages (THPs). +.B MADV_COLLAPSE +operates on the current state of memory of the calling process and +makes no persistent changes or guarantees on how pages will be mapped, +constructed, +or faulted in the future. +.IP +.B MADV_COLLAPSE +supports private anonymous pages (see +.BR mmap (2)), +shmem pages, +and file-backed pages. +See +.B MADV_HUGEPAGE +for general information on memory requirements for THP. +If the range provided spans multiple VMAs, +the semantics of the collapse over each VMA is independent from the others. +If collapse of a given huge page-aligned/sized region fails, +the operation may continue to attempt collapsing +the remainder of the specified memory. +.B MADV_COLLAPSE +will automatically clamp the provided range to be hugepage-aligned. +.IP +All non-resident pages covered by the range +will first be swapped/faulted-in, +before being copied onto a freshly allocated hugepage. +If the native pages compose the same PTE-mapped hugepage, +and are suitably aligned, +allocation of a new hugepage may be elided and +collapse may happen in-place. +Unmapped pages will have their data directly initialized to 0 +in the new hugepage. +However, +for every eligible hugepage-aligned/sized region to be collapsed, +at least one page must currently be backed by physical memory. +.IP +.B MADV_COLLAPSE +is independent of any sysfs +(see +.BR sysfs (5)) +setting under +.IR /sys/kernel/mm/transparent_hugepage , +both in terms of determining THP eligibility, +and allocation semantics. +See Linux kernel source file +.I Documentation/admin\-guide/mm/transhuge.rst +for more information. +.B MADV_COLLAPSE +also ignores +.B huge= +tmpfs mount when operating on tmpfs files. +Allocation for the new hugepage may enter direct reclaim and/or compaction, +regardless of VMA flags +(though +.B VM_NOHUGEPAGE +is still respected). +.IP +When the system has multiple NUMA nodes, +the hugepage will be allocated from +the node providing the most native pages. +.IP +If all hugepage-sized/aligned regions covered by the provided range were +either successfully collapsed, +or were already PMD-mapped THPs, +this operation will be deemed successful. +Note that this doesn't guarantee anything about +other possible mappings of the memory. +In the event multiple hugepage-aligned/sized areas fail to collapse, +only the most-recently\[en]failed code will be set in +.IR errno . +.TP +.BR MADV_DONTDUMP " (since Linux 3.4)" +.\" commit 909af768e88867016f427264ae39d27a57b6a8ed +.\" commit accb61fe7bb0f5c2a4102239e4981650f9048519 +Exclude from a core dump those pages in the range specified by +.I addr +and +.IR length . +This is useful in applications that have large areas of memory +that are known not to be useful in a core dump. +The effect of +.B MADV_DONTDUMP +takes precedence over the bit mask that is set via the +.IR /proc/ pid /coredump_filter +file (see +.BR core (5)). +.TP +.BR MADV_DODUMP " (since Linux 3.4)" +Undo the effect of an earlier +.BR MADV_DONTDUMP . +.TP +.BR MADV_FREE " (since Linux 4.5)" +The application no longer requires the pages in the range specified by +.I addr +and +.IR len . +The kernel can thus free these pages, +but the freeing could be delayed until memory pressure occurs. +For each of the pages that has been marked to be freed +but has not yet been freed, +the free operation will be canceled if the caller writes into the page. +After a successful +.B MADV_FREE +operation, any stale data (i.e., dirty, unwritten pages) will be lost +when the kernel frees the pages. +However, subsequent writes to pages in the range will succeed +and then kernel cannot free those dirtied pages, +so that the caller can always see just written data. +If there is no subsequent write, +the kernel can free the pages at any time. +Once pages in the range have been freed, the caller will +see zero-fill-on-demand pages upon subsequent page references. +.IP +The +.B MADV_FREE +operation +can be applied only to private anonymous pages (see +.BR mmap (2)). +Before Linux 4.12, +.\" commit 93e06c7a645343d222c9a838834a51042eebbbf7 +when freeing pages on a swapless system, +the pages in the given range are freed instantly, +regardless of memory pressure. +.TP +.BR MADV_WIPEONFORK " (since Linux 4.14)" +.\" commit d2cd9ede6e193dd7d88b6d27399e96229a551b19 +Present the child process with zero-filled memory in this range after a +.BR fork (2). +This is useful in forking servers in order to ensure +that sensitive per-process data +(for example, PRNG seeds, cryptographic secrets, and so on) +is not handed to child processes. +.IP +The +.B MADV_WIPEONFORK +operation can be applied only to private anonymous pages (see +.BR mmap (2)). +.IP +Within the child created by +.BR fork (2), +the +.B MADV_WIPEONFORK +setting remains in place on the specified address range. +This setting is cleared during +.BR execve (2). +.TP +.BR MADV_KEEPONFORK " (since Linux 4.14)" +.\" commit d2cd9ede6e193dd7d88b6d27399e96229a551b19 +Undo the effect of an earlier +.BR MADV_WIPEONFORK . +.TP +.BR MADV_COLD " (since Linux 5.4)" +.\" commit 9c276cc65a58faf98be8e56962745ec99ab87636 +Deactivate a given range of pages. +This will make the pages a more probable +reclaim target should there be a memory pressure. +This is a nondestructive operation. +The advice might be ignored for some pages in the range when it is not +applicable. +.TP +.BR MADV_PAGEOUT " (since Linux 5.4)" +.\" commit 1a4e58cce84ee88129d5d49c064bd2852b481357 +Reclaim a given range of pages. +This is done to free up memory occupied by these pages. +If a page is anonymous, it will be swapped out. +If a page is file-backed and dirty, it will be written back to the backing +storage. +The advice might be ignored for some pages in the range when it is not +applicable. +.TP +.BR MADV_POPULATE_READ " (since Linux 5.14)" +"Populate (prefault) page tables readable, +faulting in all pages in the range just as if manually reading from each page; +however, +avoid the actual memory access that would have been performed after handling +the fault. +.IP +In contrast to +.BR MAP_POPULATE , +.B MADV_POPULATE_READ +does not hide errors, +can be applied to (parts of) existing mappings and will always populate +(prefault) page tables readable. +One example use case is prefaulting a file mapping, +reading all file content from disk; +however, +pages won't be dirtied and consequently won't have to be written back to disk +when evicting the pages from memory. +.IP +Depending on the underlying mapping, +map the shared zeropage, +preallocate memory or read the underlying file; +files with holes might or might not preallocate blocks. +If populating fails, +a +.B SIGBUS +signal is not generated; instead, an error is returned. +.IP +If +.B MADV_POPULATE_READ +succeeds, +all page tables have been populated (prefaulted) readable once. +If +.B MADV_POPULATE_READ +fails, +some page tables might have been populated. +.IP +.B MADV_POPULATE_READ +cannot be applied to mappings without read permissions +and special mappings, +for example, +mappings marked with kernel-internal flags such as +.B VM_PFNMAP +or +.BR VM_IO , +or secret memory regions created using +.BR memfd_secret(2) . +.IP +Note that with +.BR MADV_POPULATE_READ , +the process can be killed at any moment when the system runs out of memory. +.TP +.BR MADV_POPULATE_WRITE " (since Linux 5.14)" +Populate (prefault) page tables writable, +faulting in all pages in the range just as if manually writing to each +each page; +however, +avoid the actual memory access that would have been performed after handling +the fault. +.IP +In contrast to +.BR MAP_POPULATE , +MADV_POPULATE_WRITE does not hide errors, +can be applied to (parts of) existing mappings and will always populate +(prefault) page tables writable. +One example use case is preallocating memory, +breaking any CoW (Copy on Write). +.IP +Depending on the underlying mapping, +preallocate memory or read the underlying file; +files with holes will preallocate blocks. +If populating fails, +a +.B SIGBUS +signal is not generated; instead, an error is returned. +.IP +If +.B MADV_POPULATE_WRITE +succeeds, +all page tables have been populated (prefaulted) writable once. +If +.B MADV_POPULATE_WRITE +fails, +some page tables might have been populated. +.IP +.B MADV_POPULATE_WRITE +cannot be applied to mappings without write permissions +and special mappings, +for example, +mappings marked with kernel-internal flags such as +.B VM_PFNMAP +or +.BR VM_IO , +or secret memory regions created using +.BR memfd_secret(2) . +.IP +Note that with +.BR MADV_POPULATE_WRITE , +the process can be killed at any moment when the system runs out of memory. +.SH RETURN VALUE +On success, +.BR madvise () +returns zero. +On error, it returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.I advice +is +.BR MADV_REMOVE , +but the specified address range is not a shared writable mapping. +.TP +.B EAGAIN +A kernel resource was temporarily unavailable. +.TP +.B EBADF +The map exists, but the area maps something that isn't a file. +.TP +.B EBUSY +(for +.BR MADV_COLLAPSE ) +Could not charge hugepage to cgroup: cgroup limit exceeded. +.TP +.B EFAULT +.I advice +is +.B MADV_POPULATE_READ +or +.BR MADV_POPULATE_WRITE , +and populating (prefaulting) page tables failed because a +.B SIGBUS +would have been generated on actual memory access and the reason is not a +HW poisoned page +(HW poisoned pages can, +for example, +be created using the +.B MADV_HWPOISON +flag described elsewhere in this page). +.TP +.B EINVAL +.I addr +is not page-aligned or +.I length +is negative. +.\" .I length +.\" is zero, +.TP +.B EINVAL +.I advice +is not a valid. +.TP +.B EINVAL +.I advice +is +.B MADV_COLD +or +.B MADV_PAGEOUT +and the specified address range includes locked, Huge TLB pages, or +.B VM_PFNMAP +pages. +.TP +.B EINVAL +.I advice +is +.B MADV_DONTNEED +or +.B MADV_REMOVE +and the specified address range includes locked, Huge TLB pages, or +.B VM_PFNMAP +pages. +.TP +.B EINVAL +.I advice +is +.B MADV_MERGEABLE +or +.BR MADV_UNMERGEABLE , +but the kernel was not configured with +.BR CONFIG_KSM . +.TP +.B EINVAL +.I advice +is +.B MADV_FREE +or +.B MADV_WIPEONFORK +but the specified address range includes file, Huge TLB, +.BR MAP_SHARED , +or +.B VM_PFNMAP +ranges. +.TP +.B EINVAL +.I advice +is +.B MADV_POPULATE_READ +or +.BR MADV_POPULATE_WRITE , +but the specified address range includes ranges with insufficient permissions +or special mappings, +for example, +mappings marked with kernel-internal flags such a +.B VM_IO +or +.BR VM_PFNMAP , +or secret memory regions created using +.BR memfd_secret(2) . +.TP +.B EIO +(for +.BR MADV_WILLNEED ) +Paging in this area would exceed the process's +maximum resident set size. +.TP +.B ENOMEM +(for +.BR MADV_WILLNEED ) +Not enough memory: paging in failed. +.TP +.B ENOMEM +(for +.BR MADV_COLLAPSE ) +Not enough memory: could not allocate hugepage. +.TP +.B ENOMEM +Addresses in the specified range are not currently +mapped, or are outside the address space of the process. +.TP +.B ENOMEM +.I advice +is +.B MADV_POPULATE_READ +or +.BR MADV_POPULATE_WRITE , +and populating (prefaulting) page tables failed because there was not enough +memory. +.TP +.B EPERM +.I advice +is +.BR MADV_HWPOISON , +but the caller does not have the +.B CAP_SYS_ADMIN +capability. +.TP +.B EHWPOISON +.I advice +is +.B MADV_POPULATE_READ +or +.BR MADV_POPULATE_WRITE , +and populating (prefaulting) page tables failed because a HW poisoned page +(HW poisoned pages can, +for example, +be created using the +.B MADV_HWPOISON +flag described elsewhere in this page) +was encountered. +.SH VERSIONS +Versions of this system call, implementing a wide variety of +.I advice +values, exist on many other implementations. +Other implementations typically implement at least the flags listed +above under +.IR "Conventional advice flags" , +albeit with some variation in semantics. +.P +POSIX.1-2001 describes +.BR posix_madvise (3) +with constants +.BR POSIX_MADV_NORMAL , +.BR POSIX_MADV_RANDOM , +.BR POSIX_MADV_SEQUENTIAL , +.BR POSIX_MADV_WILLNEED , +and +.BR POSIX_MADV_DONTNEED , +and so on, with behavior close to the similarly named flags listed above. +.SS Linux +The Linux implementation requires that the address +.I addr +be page-aligned, and allows +.I length +to be zero. +If there are some parts of the specified address range +that are not mapped, the Linux version of +.BR madvise () +ignores them and applies the call to the rest (but returns +.B ENOMEM +from the system call, as it should). +.P +.I madvise(0,\ 0,\ advice) +will return zero iff +.I advice +is supported by the kernel and can be relied on to probe for support. +.SH STANDARDS +None. +.SH HISTORY +First appeared in 4.4BSD. +.P +Since Linux 3.18, +.\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb +support for this system call is optional, +depending on the setting of the +.B CONFIG_ADVISE_SYSCALLS +configuration option. +.SH SEE ALSO +.BR getrlimit (2), +.BR memfd_secret (2), +.BR mincore (2), +.BR mmap (2), +.BR mprotect (2), +.BR msync (2), +.BR munmap (2), +.BR prctl (2), +.BR process_madvise (2), +.BR posix_madvise (3), +.BR core (5) diff --git a/man/man2/madvise1.2 b/man/man2/madvise1.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/madvise1.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/mbind.2 b/man/man2/mbind.2 new file mode 100644 index 0000000..67c958d --- /dev/null +++ b/man/man2/mbind.2 @@ -0,0 +1,521 @@ +.\" SPDX-License-Identifier: Linux-man-pages-copyleft-var +.\" +.\" Copyright 2003,2004 Andi Kleen, SuSE Labs. +.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard +.\" +.\" 2006-02-03, mtk, substantial wording changes and other improvements +.\" 2007-08-27, Lee Schermerhorn +.\" more precise specification of behavior. +.\" +.\" FIXME +.\" Linux 3.8 added MPOL_MF_LAZY, which needs to be documented. +.\" Does it also apply for move_pages()? +.\" +.\" commit b24f53a0bea38b266d219ee651b22dba727c44ae +.\" Author: Lee Schermerhorn +.\" Date: Thu Oct 25 14:16:32 2012 +0200 +.\" +.TH mbind 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbind \- set memory policy for a memory range +.SH LIBRARY +NUMA (Non-Uniform Memory Access) policy library +.RI ( libnuma ", " \-lnuma ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "long mbind(void " addr [. len "], unsigned long " len ", int " mode , +.BI " const unsigned long " nodemask [(. maxnode " + ULONG_WIDTH - 1)" +.B " / ULONG_WIDTH]," +.BI " unsigned long " maxnode ", unsigned int " flags ); +.fi +.SH DESCRIPTION +.BR mbind () +sets the NUMA memory policy, +which consists of a policy mode and zero or more nodes, +for the memory range starting with +.I addr +and continuing for +.I len +bytes. +The memory policy defines from which node memory is allocated. +.P +If the memory range specified by the +.IR addr " and " len +arguments includes an "anonymous" region of memory\[em]that is +a region of memory created using the +.BR mmap (2) +system call with the +.BR MAP_ANONYMOUS \[em]or +a memory-mapped file, mapped using the +.BR mmap (2) +system call with the +.B MAP_PRIVATE +flag, pages will be allocated only according to the specified +policy when the application writes (stores) to the page. +For anonymous regions, an initial read access will use a shared +page in the kernel containing all zeros. +For a file mapped with +.BR MAP_PRIVATE , +an initial read access will allocate pages according to the +memory policy of the thread that causes the page to be allocated. +This may not be the thread that called +.BR mbind (). +.P +The specified policy will be ignored for any +.B MAP_SHARED +mappings in the specified memory range. +Rather the pages will be allocated according to the memory policy +of the thread that caused the page to be allocated. +Again, this may not be the thread that called +.BR mbind (). +.P +If the specified memory range includes a shared memory region +created using the +.BR shmget (2) +system call and attached using the +.BR shmat (2) +system call, +pages allocated for the anonymous or shared memory region will +be allocated according to the policy specified, regardless of which +process attached to the shared memory segment causes the allocation. +If, however, the shared memory region was created with the +.B SHM_HUGETLB +flag, +the huge pages will be allocated according to the policy specified +only if the page allocation is caused by the process that calls +.BR mbind () +for that region. +.P +By default, +.BR mbind () +has an effect only for new allocations; if the pages inside +the range have been already touched before setting the policy, +then the policy has no effect. +This default behavior may be overridden by the +.B MPOL_MF_MOVE +and +.B MPOL_MF_MOVE_ALL +flags described below. +.P +The +.I mode +argument must specify one of +.BR MPOL_DEFAULT , +.BR MPOL_BIND , +.BR MPOL_INTERLEAVE , +.BR MPOL_WEIGHTED_INTERLEAVE , +.BR MPOL_PREFERRED , +or +.B MPOL_LOCAL +(which are described in detail below). +All policy modes except +.B MPOL_DEFAULT +require the caller to specify the node or nodes to which the mode applies, +via the +.I nodemask +argument. +.P +The +.I mode +argument may also include an optional +.IR "mode flag" . +The supported +.I "mode flags" +are: +.TP +.BR MPOL_F_NUMA_BALANCING " (since Linux 5.15)" +.\" commit bda420b985054a3badafef23807c4b4fa38a3dff +.\" commit 6d2aec9e123bb9c49cb5c7fc654f25f81e688e8c +When +.I mode +is +.BR MPOL_BIND , +enable the kernel NUMA balancing for the task if it is supported by the kernel. +If the flag isn't supported by the kernel, or is used with +.I mode +other than +.BR MPOL_BIND , +\-1 is returned and +.I errno +is set to +.BR EINVAL . +.TP +.BR MPOL_F_STATIC_NODES " (since Linux-2.6.26)" +A nonempty +.I nodemask +specifies physical node IDs. +Linux does not remap the +.I nodemask +when the thread moves to a different cpuset context, +nor when the set of nodes allowed by the thread's +current cpuset context changes. +.TP +.BR MPOL_F_RELATIVE_NODES " (since Linux-2.6.26)" +A nonempty +.I nodemask +specifies node IDs that are relative to the set of +node IDs allowed by the thread's current cpuset. +.P +.I nodemask +points to a bit mask of nodes containing up to +.I maxnode +bits. +The bit mask size is rounded to the next multiple of +.IR "sizeof(unsigned long)" , +but the kernel will use bits only up to +.IR maxnode . +A NULL value of +.I nodemask +or a +.I maxnode +value of zero specifies the empty set of nodes. +If the value of +.I maxnode +is zero, +the +.I nodemask +argument is ignored. +Where a +.I nodemask +is required, it must contain at least one node that is on-line, +allowed by the thread's current cpuset context +(unless the +.B MPOL_F_STATIC_NODES +mode flag is specified), +and contains memory. +.P +The +.I mode +argument must include one of the following values: +.TP +.B MPOL_DEFAULT +This mode requests that any nondefault policy be removed, +restoring default behavior. +When applied to a range of memory via +.BR mbind (), +this means to use the thread memory policy, +which may have been set with +.BR set_mempolicy (2). +If the mode of the thread memory policy is also +.BR MPOL_DEFAULT , +the system-wide default policy will be used. +The system-wide default policy allocates +pages on the node of the CPU that triggers the allocation. +For +.BR MPOL_DEFAULT , +the +.I nodemask +and +.I maxnode +arguments must be specify the empty set of nodes. +.TP +.B MPOL_BIND +This mode specifies a strict policy that restricts memory allocation to +the nodes specified in +.IR nodemask . +If +.I nodemask +specifies more than one node, page allocations will come from +the node with sufficient free memory that is closest to +the node where the allocation takes place. +Pages will not be allocated from any node not specified in the +IR nodemask . +(Before Linux 2.6.26, +.\" commit 19770b32609b6bf97a3dece2529089494cbfc549 +page allocations came from +the node with the lowest numeric node ID first, until that node +contained no free memory. +Allocations then came from the node with the next highest +node ID specified in +.I nodemask +and so forth, until none of the specified nodes contained free memory.) +.TP +.B MPOL_INTERLEAVE +This mode specifies that page allocations be interleaved across the +set of nodes specified in +.IR nodemask . +This optimizes for bandwidth instead of latency +by spreading out pages and memory accesses to those pages across +multiple nodes. +To be effective the memory area should be fairly large, +at least 1\ MB or bigger with a fairly uniform access pattern. +Accesses to a single page of the area will still be limited to +the memory bandwidth of a single node. +.TP +.BR MPOL_WEIGHTED_INTERLEAVE " (since Linux 6.9)" +.\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758 +This mode interleaves page allocations across the nodes specified in +.I nodemask +according to the weights in +.IR /sys/kernel/mm/mempolicy/weighted_interleave . +For example, if bits 0, 2, and 5 are set in +.IR nodemask , +and the contents of +.IR /sys/kernel/mm/mempolicy/weighted_interleave/node0 , +.IR /sys/ .\|.\|. /node2 , +and +.IR /sys/ .\|.\|. /node5 +are 4, 7, and 9, respectively, +then pages in this region will be allocated on nodes 0, 2, and 5 +in a 4:7:9 ratio. +.TP +.B MPOL_PREFERRED +This mode sets the preferred node for allocation. +The kernel will try to allocate pages from this +node first and fall back to other nodes if the +preferred nodes is low on free memory. +If +.I nodemask +specifies more than one node ID, the first node in the +mask will be selected as the preferred node. +If the +.I nodemask +and +.I maxnode +arguments specify the empty set, then the memory is allocated on +the node of the CPU that triggered the allocation. +.TP +.BR MPOL_LOCAL " (since Linux 3.8)" +.\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8 +.\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f +This mode specifies "local allocation"; the memory is allocated on +the node of the CPU that triggered the allocation (the "local node"). +The +.I nodemask +and +.I maxnode +arguments must specify the empty set. +If the "local node" is low on free memory, +the kernel will try to allocate memory from other nodes. +The kernel will allocate memory from the "local node" +whenever memory for this node is available. +If the "local node" is not allowed by the thread's current cpuset context, +the kernel will try to allocate memory from other nodes. +The kernel will allocate memory from the "local node" whenever +it becomes allowed by the thread's current cpuset context. +By contrast, +.B MPOL_DEFAULT +reverts to the memory policy of the thread (which may be set via +.BR set_mempolicy (2)); +that policy may be something other than "local allocation". +.P +If +.B MPOL_MF_STRICT +is passed in +.I flags +and +.I mode +is not +.BR MPOL_DEFAULT , +then the call fails with the error +.B EIO +if the existing pages in the memory range don't follow the policy. +.\" According to the kernel code, the following is not true +.\" --Lee Schermerhorn +.\" In Linux 2.6.16 or later the kernel will also try to move pages +.\" to the requested node with this flag. +.P +If +.B MPOL_MF_MOVE +is specified in +.IR flags , +then the kernel will attempt to move all the existing pages +in the memory range so that they follow the policy. +Pages that are shared with other processes will not be moved. +If +.B MPOL_MF_STRICT +is also specified, then the call fails with the error +.B EIO +if some pages could not be moved. +If the +.B MPOL_INTERLEAVE +policy was specified, +pages already residing on the specified nodes +will not be moved such that they are interleaved. +.P +If +.B MPOL_MF_MOVE_ALL +is passed in +.IR flags , +then the kernel will attempt to move all existing pages in the memory range +regardless of whether other processes use the pages. +The calling thread must be privileged +.RB ( CAP_SYS_NICE ) +to use this flag. +If +.B MPOL_MF_STRICT +is also specified, then the call fails with the error +.B EIO +if some pages could not be moved. +If the +.B MPOL_INTERLEAVE +policy was specified, +pages already residing on the specified nodes +will not be moved such that they are interleaved. +.\" --------------------------------------------------------------- +.SH RETURN VALUE +On success, +.BR mbind () +returns 0; +on error, \-1 is returned and +.I errno +is set to indicate the error. +.\" --------------------------------------------------------------- +.SH ERRORS +.\" I think I got all of the error returns. --Lee Schermerhorn +.TP +.B EFAULT +Part or all of the memory range specified by +.I nodemask +and +.I maxnode +points outside your accessible address space. +Or, there was an unmapped hole in the specified memory range specified by +.I addr +and +.IR len . +.TP +.B EINVAL +An invalid value was specified for +.I flags +or +.IR mode ; +or +.I addr + len +was less than +.IR addr ; +or +.I addr +is not a multiple of the system page size. +Or, +.I mode +is +.B MPOL_DEFAULT +and +.I nodemask +specified a nonempty set; +or +.I mode +is +.B MPOL_BIND +or +.B MPOL_INTERLEAVE +and +.I nodemask +is empty. +Or, +.I maxnode +exceeds a kernel-imposed limit. +.\" As at 2.6.23, this limit is "a page worth of bits", e.g., +.\" 8 * 4096 bits, assuming a 4kB page size. +Or, +.I nodemask +specifies one or more node IDs that are +greater than the maximum supported node ID. +Or, none of the node IDs specified by +.I nodemask +are on-line and allowed by the thread's current cpuset context, +or none of the specified nodes contain memory. +Or, the +.I mode +argument specified both +.B MPOL_F_STATIC_NODES +and +.BR MPOL_F_RELATIVE_NODES . +.TP +.B EIO +.B MPOL_MF_STRICT +was specified and an existing page was already on a node +that does not follow the policy; +or +.B MPOL_MF_MOVE +or +.B MPOL_MF_MOVE_ALL +was specified and the kernel was unable to move all existing +pages in the range. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B EPERM +The +.I flags +argument included the +.B MPOL_MF_MOVE_ALL +flag and the caller does not have the +.B CAP_SYS_NICE +privilege. +.\" --------------------------------------------------------------- +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.7. +.P +Support for huge page policy was added with Linux 2.6.16. +For interleave policy to be effective on huge page mappings the +policied memory needs to be tens of megabytes or larger. +.P +Before Linux 5.7. +.\" commit dcf1763546d76c372f3136c8d6b2b6e77f140cf0 +.B MPOL_MF_STRICT +was ignored on huge page mappings. +.P +.B MPOL_MF_MOVE +and +.B MPOL_MF_MOVE_ALL +are available only on Linux 2.6.16 and later. +.SH NOTES +For information on library support, see +.BR numa (7). +.P +NUMA policy is not supported on a memory-mapped file range +that was mapped with the +.B MAP_SHARED +flag. +.P +The +.B MPOL_DEFAULT +mode can have different effects for +.BR mbind () +and +.BR set_mempolicy (2). +When +.B MPOL_DEFAULT +is specified for +.BR set_mempolicy (2), +the thread's memory policy reverts to the system default policy +or local allocation. +When +.B MPOL_DEFAULT +is specified for a range of memory using +.BR mbind (), +any pages subsequently allocated for that range will use +the thread's memory policy, as set by +.BR set_mempolicy (2). +This effectively removes the explicit policy from the +specified range, "falling back" to a possibly nondefault +policy. +To select explicit "local allocation" for a memory range, +specify a +.I mode +of +.B MPOL_LOCAL +or +.B MPOL_PREFERRED +with an empty set of nodes. +This method will work for +.BR set_mempolicy (2), +as well. +.SH SEE ALSO +.BR get_mempolicy (2), +.BR getcpu (2), +.BR mmap (2), +.BR set_mempolicy (2), +.BR shmat (2), +.BR shmget (2), +.BR numa (3), +.BR cpuset (7), +.BR numa (7), +.BR numactl (8) diff --git a/man/man2/membarrier.2 b/man/man2/membarrier.2 new file mode 100644 index 0000000..38f774f --- /dev/null +++ b/man/man2/membarrier.2 @@ -0,0 +1,460 @@ +'\" t +.\" Copyright 2015-2017 Mathieu Desnoyers +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH membarrier 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +membarrier \- issue memory barriers on a set of threads +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.P +.BR "#include " \ +" /* Definition of " MEMBARRIER_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_membarrier, int " cmd ", unsigned int " flags \ +", int " cpu_id ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR membarrier (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR membarrier () +system call helps reducing the overhead of the memory barrier +instructions required to order memory accesses on multi-core systems. +However, this system call is heavier than a memory barrier, so using it +effectively is +.I not +as simple as replacing memory barriers with this +system call, but requires understanding of the details below. +.P +Use of memory barriers needs to be done taking into account that a +memory barrier always needs to be either matched with its memory barrier +counterparts, or that the architecture's memory model doesn't require the +matching barriers. +.P +There are cases where one side of the matching barriers (which we will +refer to as "fast side") is executed much more often than the other +(which we will refer to as "slow side"). +This is a prime target for the use of +.BR membarrier (). +The key idea is to replace, for these matching +barriers, the fast-side memory barriers by simple compiler barriers, +for example: +.P +.in +4n +.EX +asm volatile ("" : : : "memory") +.EE +.in +.P +and replace the slow-side memory barriers by calls to +.BR membarrier (). +.P +This will add overhead to the slow side, and remove overhead from the +fast side, thus resulting in an overall performance increase as long as +the slow side is infrequent enough that the overhead of the +.BR membarrier () +calls does not outweigh the performance gain on the fast side. +.P +The +.I cmd +argument is one of the following: +.TP +.BR MEMBARRIER_CMD_QUERY " (since Linux 4.3)" +Query the set of supported commands. +The return value of the call is a bit mask of supported +commands. +.BR MEMBARRIER_CMD_QUERY , +which has the value 0, +is not itself included in this bit mask. +This command is always supported (on kernels where +.BR membarrier () +is provided). +.TP +.BR MEMBARRIER_CMD_GLOBAL " (since Linux 4.16)" +Ensure that all threads from all processes on the system pass through a +state where all memory accesses to user-space addresses match program +order between entry to and return from the +.BR membarrier () +system call. +All threads on the system are targeted by this command. +.TP +.BR MEMBARRIER_CMD_GLOBAL_EXPEDITED " (since Linux 4.16)" +Execute a memory barrier on all running threads of all processes that +previously registered with +.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED . +.IP +Upon return from the system call, the calling thread has a guarantee that all +running threads have passed through a state where all memory accesses to +user-space addresses match program order between entry to and return +from the system call (non-running threads are de facto in such a state). +This guarantee is provided only for the threads of processes that +previously registered with +.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED . +.IP +Given that registration is about the intent to receive the barriers, it +is valid to invoke +.B MEMBARRIER_CMD_GLOBAL_EXPEDITED +from a process that has not employed +.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED . +.IP +The "expedited" commands complete faster than the non-expedited ones; +they never block, but have the downside of causing extra overhead. +.TP +.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED " (since Linux 4.16)" +Register the process's intent to receive +.B MEMBARRIER_CMD_GLOBAL_EXPEDITED +memory barriers. +.TP +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED " (since Linux 4.14)" +Execute a memory barrier on each running thread belonging to the same +process as the calling thread. +.IP +Upon return from the system call, the calling +thread has a guarantee that all its running thread siblings have passed +through a state where all memory accesses to user-space addresses match +program order between entry to and return from the system call +(non-running threads are de facto in such a state). +This guarantee is provided only for threads in +the same process as the calling thread. +.IP +The "expedited" commands complete faster than the non-expedited ones; +they never block, but have the downside of causing extra overhead. +.IP +A process must register its intent to use the private +expedited command prior to using it. +.TP +.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED " (since Linux 4.14)" +Register the process's intent to use +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED . +.TP +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE " (since Linux 4.16)" +In addition to providing the memory ordering guarantees described in +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED , +upon return from system call the calling thread has a guarantee that all its +running thread siblings have executed a core serializing instruction. +This guarantee is provided only for threads in +the same process as the calling thread. +.IP +The "expedited" commands complete faster than the non-expedited ones, +they never block, but have the downside of causing extra overhead. +.IP +A process must register its intent to use the private expedited sync +core command prior to using it. +.TP +.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE " (since Linux 4.16)" +Register the process's intent to use +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE . +.TP +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ " (since Linux 5.10)" +Ensure the caller thread, upon return from system call, that all its +running thread siblings have any currently running rseq critical sections +restarted if +.I flags +parameter is 0; if +.I flags +parameter is +.BR MEMBARRIER_CMD_FLAG_CPU , +then this operation is performed only on CPU indicated by +.IR cpu_id . +This guarantee is provided only for threads in +the same process as the calling thread. +.IP +RSEQ membarrier is only available in the "private expedited" form. +.IP +A process must register its intent to use the private expedited rseq +command prior to using it. +.TP +.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_RSEQ " (since Linux 5.10)" +Register the process's intent to use +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ . +.TP +.BR MEMBARRIER_CMD_SHARED " (since Linux 4.3)" +This is an alias for +.B MEMBARRIER_CMD_GLOBAL +that exists for header backward compatibility. +.P +The +.I flags +argument must be specified as 0 unless the command is +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ , +in which case +.I flags +can be either 0 or +.BR MEMBARRIER_CMD_FLAG_CPU . +.P +The +.I cpu_id +argument is ignored unless +.I flags +is +.BR MEMBARRIER_CMD_FLAG_CPU , +in which case it must specify the CPU targeted by this membarrier +command. +.P +All memory accesses performed in program order from each targeted thread +are guaranteed to be ordered with respect to +.BR membarrier (). +.P +If we use the semantic +.I barrier() +to represent a compiler barrier forcing memory +accesses to be performed in program order across the barrier, and +.I smp_mb() +to represent explicit memory barriers forcing full memory +ordering across the barrier, we have the following ordering table for +each pairing of +.IR barrier() , +.BR membarrier (), +and +.IR smp_mb() . +The pair ordering is detailed as (O: ordered, X: not ordered): +.P +.RS +.TS +l c c c. +\& barrier() smp_mb() membarrier() +barrier() X X O +smp_mb() X O O +membarrier() O O O +.TE +.RE +.SH RETURN VALUE +On success, the +.B MEMBARRIER_CMD_QUERY +operation returns a bit mask of supported commands, and the +.BR MEMBARRIER_CMD_GLOBAL , +.BR MEMBARRIER_CMD_GLOBAL_EXPEDITED , +.BR MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED , +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED , +.BR MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED , +.BR MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE , +and +.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE +operations return zero. +On error, \-1 is returned, +and +.I errno +is set to indicate the error. +.P +For a given command, with +.I flags +set to 0, this system call is +guaranteed to always return the same value until reboot. +Further calls with the same arguments will lead to the same result. +Therefore, with +.I flags +set to 0, error handling is required only for the first call to +.BR membarrier (). +.SH ERRORS +.TP +.B EINVAL +.I cmd +is invalid, or +.I flags +is nonzero, or the +.B MEMBARRIER_CMD_GLOBAL +command is disabled because the +.I nohz_full +CPU parameter has been set, or the +.B MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE +and +.B MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE +commands are not implemented by the architecture. +.TP +.B ENOSYS +The +.BR membarrier () +system call is not implemented by this kernel. +.TP +.B EPERM +The current process was not registered prior to using private expedited +commands. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.3. +.P +Before Linux 5.10, the prototype was: +.P +.in +4n +.EX +.BI "int membarrier(int " cmd ", int " flags ); +.EE +.in +.SH NOTES +A memory barrier instruction is part of the instruction set of +architectures with weakly ordered memory models. +It orders memory +accesses prior to the barrier and after the barrier with respect to +matching barriers on other cores. +For instance, a load fence can order +loads prior to and following that fence with respect to stores ordered +by store fences. +.P +Program order is the order in which instructions are ordered in the +program assembly code. +.P +Examples where +.BR membarrier () +can be useful include implementations +of Read-Copy-Update libraries and garbage collectors. +.SH EXAMPLES +Assuming a multithreaded application where "fast_path()" is executed +very frequently, and where "slow_path()" is executed infrequently, the +following code (x86) can be transformed using +.BR membarrier (): +.P +.in +4n +.\" SRC BEGIN (membarrier.c) +.EX +#include +\& +static volatile int a, b; +\& +static void +fast_path(int *read_b) +{ + a = 1; + asm volatile ("mfence" : : : "memory"); + *read_b = b; +} +\& +static void +slow_path(int *read_a) +{ + b = 1; + asm volatile ("mfence" : : : "memory"); + *read_a = a; +} +\& +int +main(void) +{ + int read_a, read_b; +\& + /* + * Real applications would call fast_path() and slow_path() + * from different threads. Call those from main() to keep + * this example short. + */ +\& + slow_path(&read_a); + fast_path(&read_b); +\& + /* + * read_b == 0 implies read_a == 1 and + * read_a == 0 implies read_b == 1. + */ +\& + if (read_b == 0 && read_a == 0) + abort(); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.P +The code above transformed to use +.BR membarrier () +becomes: +.P +.in +4n +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +\& +static volatile int a, b; +\& +static int +membarrier(int cmd, unsigned int flags, int cpu_id) +{ + return syscall(__NR_membarrier, cmd, flags, cpu_id); +} +\& +static int +init_membarrier(void) +{ + int ret; +\& + /* Check that membarrier() is supported. */ +\& + ret = membarrier(MEMBARRIER_CMD_QUERY, 0, 0); + if (ret < 0) { + perror("membarrier"); + return \-1; + } +\& + if (!(ret & MEMBARRIER_CMD_GLOBAL)) { + fprintf(stderr, + "membarrier does not support MEMBARRIER_CMD_GLOBAL\en"); + return \-1; + } +\& + return 0; +} +\& +static void +fast_path(int *read_b) +{ + a = 1; + asm volatile ("" : : : "memory"); + *read_b = b; +} +\& +static void +slow_path(int *read_a) +{ + b = 1; + membarrier(MEMBARRIER_CMD_GLOBAL, 0, 0); + *read_a = a; +} +\& +int +main(int argc, char *argv[]) +{ + int read_a, read_b; +\& + if (init_membarrier()) + exit(EXIT_FAILURE); +\& + /* + * Real applications would call fast_path() and slow_path() + * from different threads. Call those from main() to keep + * this example short. + */ +\& + slow_path(&read_a); + fast_path(&read_b); +\& + /* + * read_b == 0 implies read_a == 1 and + * read_a == 0 implies read_b == 1. + */ +\& + if (read_b == 0 && read_a == 0) + abort(); +\& + exit(EXIT_SUCCESS); +} +.EE +.in +.\" .SH SEE ALSO +.\" FIXME See if the following syscalls make it into Linux 4.15 or later +.\" .BR cpu_opv (2), +.\" .BR rseq (2) diff --git a/man/man2/memfd_create.2 b/man/man2/memfd_create.2 new file mode 100644 index 0000000..525bd43 --- /dev/null +++ b/man/man2/memfd_create.2 @@ -0,0 +1,550 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" and Copyright (C) 2014 David Herrmann +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH memfd_create 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memfd_create \- create an anonymous file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int memfd_create(const char *" name ", unsigned int " flags ");" +.fi +.SH DESCRIPTION +.BR memfd_create () +creates an anonymous file and returns a file descriptor that refers to it. +The file behaves like a regular file, and so can be modified, +truncated, memory-mapped, and so on. +However, unlike a regular file, +it lives in RAM and has a volatile backing storage. +Once all references to the file are dropped, it is automatically released. +Anonymous memory is used for all backing pages of the file. +Therefore, files created by +.BR memfd_create () +have the same semantics as other anonymous +.\" David Herrmann: +.\" memfd uses VM_NORESERVE so each page is accounted on first access. +.\" This means, the overcommit-limits (see __vm_enough_memory()) and the +.\" memory-cgroup limits (mem_cgroup_try_charge()) are applied. Note that +.\" those are accounted on "current" and "current->mm", that is, the +.\" process doing the first page access. +memory allocations such as those allocated using +.BR mmap (2) +with the +.B MAP_ANONYMOUS +flag. +.P +The initial size of the file is set to 0. +Following the call, the file size should be set using +.BR ftruncate (2). +(Alternatively, the file may be populated by calls to +.BR write (2) +or similar.) +.P +The name supplied in +.I name +is used as a filename and will be displayed +as the target of the corresponding symbolic link in the directory +.IR /proc/self/fd/ . +The displayed name is always prefixed with +.I memfd: +and serves only for debugging purposes. +Names do not affect the behavior of the file descriptor, +and as such multiple files can have the same name without any side effects. +.P +The following values may be bitwise ORed in +.I flags +to change the behavior of +.BR memfd_create (): +.TP +.B MFD_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.TP +.B MFD_ALLOW_SEALING +Allow sealing operations on this file. +See the discussion of the +.B F_ADD_SEALS +and +.B F_GET_SEALS +operations in +.BR fcntl (2), +and also NOTES, below. +The initial set of seals is empty. +If this flag is not set, the initial set of seals will be +.BR F_SEAL_SEAL , +meaning that no other seals can be set on the file. +.\" FIXME Why is the MFD_ALLOW_SEALING behavior not simply the default? +.\" Is it worth adding some text explaining this? +.TP +.BR MFD_HUGETLB " (since Linux 4.14)" +.\" commit 749df87bd7bee5a79cef073f5d032ddb2b211de8 +The anonymous file will be created in the hugetlbfs filesystem using +huge pages. +See the Linux kernel source file +.I Documentation/admin\-guide/mm/hugetlbpage.rst +for more information about hugetlbfs. +.\" commit 47b9012ecdc747f6936395265e677d41e11a31ff +Specifying both +.B MFD_HUGETLB +and +.B MFD_ALLOW_SEALING +in +.I flags +is supported since Linux 4.16. +.TP +.B MFD_HUGE_2MB +.TQ +.B MFD_HUGE_1GB +.TQ +\&.\|.\|. +Used in conjunction with +.B MFD_HUGETLB +to select alternative hugetlb page sizes (respectively, 2\ MB, 1\ GB, ...) +on systems that support multiple hugetlb page sizes. +Definitions for known +huge page sizes are included in the header file +.I . +.IP +For details on encoding huge page sizes not included in the header file, +see the discussion of the similarly named constants in +.BR mmap (2). +.P +Unused bits in +.I flags +must be 0. +.P +As its return value, +.BR memfd_create () +returns a new file descriptor that can be used to refer to the file. +This file descriptor is opened for both reading and writing +.RB ( O_RDWR ) +and +.B O_LARGEFILE +is set for the file descriptor. +.P +With respect to +.BR fork (2) +and +.BR execve (2), +the usual semantics apply for the file descriptor created by +.BR memfd_create (). +A copy of the file descriptor is inherited by the child produced by +.BR fork (2) +and refers to the same file. +The file descriptor is preserved across +.BR execve (2), +unless the close-on-exec flag has been set. +.SH RETURN VALUE +On success, +.BR memfd_create () +returns a new file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +The address in +.I name +points to invalid memory. +.TP +.B EINVAL +.I flags +included unknown bits. +.TP +.B EINVAL +.I name +was too long. +(The limit is +.\" NAME_MAX - strlen("memfd:") +249 bytes, excluding the terminating null byte.) +.TP +.B EINVAL +Both +.B MFD_HUGETLB +and +.B MFD_ALLOW_SEALING +were specified in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +There was insufficient memory to create a new anonymous file. +.TP +.B EPERM +The +.B MFD_HUGETLB +flag was specified, but the caller was not privileged (did not have the +.B CAP_IPC_LOCK +capability) +and is not a member of the +.I sysctl_hugetlb_shm_group +group; see the description of +.I /proc/sys/vm/sysctl_hugetlb_shm_group +in +.BR proc (5). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.17, +glibc 2.27. +.SH NOTES +.\" See also http://lwn.net/Articles/593918/ +.\" and http://lwn.net/Articles/594919/ and http://lwn.net/Articles/591108/ +The +.BR memfd_create () +system call provides a simple alternative to manually mounting a +.BR tmpfs (5) +filesystem and creating and opening a file in that filesystem. +The primary purpose of +.BR memfd_create () +is to create files and associated file descriptors that are +used with the file-sealing APIs provided by +.BR fcntl (2). +.P +The +.BR memfd_create () +system call also has uses without file sealing +(which is why file-sealing is disabled, unless explicitly requested with the +.B MFD_ALLOW_SEALING +flag). +In particular, it can be used as an alternative to creating files in +.I tmp +or as an alternative to using the +.BR open (2) +.B O_TMPFILE +in cases where there is no intention to actually link the +resulting file into the filesystem. +.SS File sealing +In the absence of file sealing, +processes that communicate via shared memory must either trust each other, +or take measures to deal with the possibility that an untrusted peer +may manipulate the shared memory region in problematic ways. +For example, an untrusted peer might modify the contents of the +shared memory at any time, or shrink the shared memory region. +The former possibility leaves the local process vulnerable to +time-of-check-to-time-of-use race conditions +(typically dealt with by copying data from +the shared memory region before checking and using it). +The latter possibility leaves the local process vulnerable to +.B SIGBUS +signals when an attempt is made to access a now-nonexistent +location in the shared memory region. +(Dealing with this possibility necessitates the use of a handler for the +.B SIGBUS +signal.) +.P +Dealing with untrusted peers imposes extra complexity on +code that employs shared memory. +Memory sealing enables that extra complexity to be eliminated, +by allowing a process to operate secure in the knowledge that +its peer can't modify the shared memory in an undesired fashion. +.P +An example of the usage of the sealing mechanism is as follows: +.IP (1) 5 +The first process creates a +.BR tmpfs (5) +file using +.BR memfd_create (). +The call yields a file descriptor used in subsequent steps. +.IP (2) +The first process +sizes the file created in the previous step using +.BR ftruncate (2), +maps it using +.BR mmap (2), +and populates the shared memory with the desired data. +.IP (3) +The first process uses the +.BR fcntl (2) +.B F_ADD_SEALS +operation to place one or more seals on the file, +in order to restrict further modifications on the file. +(If placing the seal +.BR F_SEAL_WRITE , +then it will be necessary to first unmap the shared writable mapping +created in the previous step. +Otherwise, behavior similar to +.B F_SEAL_WRITE +can be achieved by using +.BR F_SEAL_FUTURE_WRITE , +which will prevent future writes via +.BR mmap (2) +and +.BR write (2) +from succeeding while keeping existing shared writable mappings). +.IP (4) +A second process obtains a file descriptor for the +.BR tmpfs (5) +file and maps it. +Among the possible ways in which this could happen are the following: +.RS +.IP \[bu] 3 +The process that called +.BR memfd_create () +could transfer the resulting file descriptor to the second process +via a UNIX domain socket (see +.BR unix (7) +and +.BR cmsg (3)). +The second process then maps the file using +.BR mmap (2). +.IP \[bu] +The second process is created via +.BR fork (2) +and thus automatically inherits the file descriptor and mapping. +(Note that in this case and the next, +there is a natural trust relationship between the two processes, +since they are running under the same user ID. +Therefore, file sealing would not normally be necessary.) +.IP \[bu] +The second process opens the file +.IR /proc/ pid /fd/ fd, +where +.I +is the PID of the first process (the one that called +.BR memfd_create ()), +and +.I +is the number of the file descriptor returned by the call to +.BR memfd_create () +in that process. +The second process then maps the file using +.BR mmap (2). +.RE +.IP (5) +The second process uses the +.BR fcntl (2) +.B F_GET_SEALS +operation to retrieve the bit mask of seals +that has been applied to the file. +This bit mask can be inspected in order to determine +what kinds of restrictions have been placed on file modifications. +If desired, the second process can apply further seals +to impose additional restrictions (so long as the +.B F_SEAL_SEAL +seal has not yet been applied). +.SH EXAMPLES +Below are shown two example programs that demonstrate the use of +.BR memfd_create () +and the file sealing API. +.P +The first program, +.IR t_memfd_create.c , +creates a +.BR tmpfs (5) +file using +.BR memfd_create (), +sets a size for the file, maps it into memory, +and optionally places some seals on the file. +The program accepts up to three command-line arguments, +of which the first two are required. +The first argument is the name to associate with the file, +the second argument is the size to be set for the file, +and the optional third argument is a string of characters that specify +seals to be set on the file. +.P +The second program, +.IR t_get_seals.c , +can be used to open an existing file that was created via +.BR memfd_create () +and inspect the set of seals that have been applied to that file. +.P +The following shell session demonstrates the use of these programs. +First we create a +.BR tmpfs (5) +file and set some seals on it: +.P +.in +4n +.EX +$ \fB./t_memfd_create my_memfd_file 4096 sw &\fP +[1] 11775 +PID: 11775; fd: 3; /proc/11775/fd/3 +.EE +.in +.P +At this point, the +.I t_memfd_create +program continues to run in the background. +From another program, we can obtain a file descriptor for the +file created by +.BR memfd_create () +by opening the +.IR /proc/ pid /fd +file that corresponds to the file descriptor opened by +.BR memfd_create (). +Using that pathname, we inspect the content of the +.IR /proc/ pid /fd +symbolic link, and use our +.I t_get_seals +program to view the seals that have been placed on the file: +.P +.in +4n +.EX +$ \fBreadlink /proc/11775/fd/3\fP +/memfd:my_memfd_file (deleted) +$ \fB./t_get_seals /proc/11775/fd/3\fP +Existing seals: WRITE SHRINK +.EE +.in +.SS Program source: t_memfd_create.c +\& +.\" SRC BEGIN (t_memfd_create.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int fd; + char *name, *seals_arg; + ssize_t len; + unsigned int seals; +\& + if (argc < 3) { + fprintf(stderr, "%s name size [seals]\en", argv[0]); + fprintf(stderr, "\et\[aq]seals\[aq] can contain any of the " + "following characters:\en"); + fprintf(stderr, "\et\etg \- F_SEAL_GROW\en"); + fprintf(stderr, "\et\ets \- F_SEAL_SHRINK\en"); + fprintf(stderr, "\et\etw \- F_SEAL_WRITE\en"); + fprintf(stderr, "\et\etW \- F_SEAL_FUTURE_WRITE\en"); + fprintf(stderr, "\et\etS \- F_SEAL_SEAL\en"); + exit(EXIT_FAILURE); + } +\& + name = argv[1]; + len = atoi(argv[2]); + seals_arg = argv[3]; +\& + /* Create an anonymous file in tmpfs; allow seals to be + placed on the file. */ +\& + fd = memfd_create(name, MFD_ALLOW_SEALING); + if (fd == \-1) + err(EXIT_FAILURE, "memfd_create"); +\& + /* Size the file as specified on the command line. */ +\& + if (ftruncate(fd, len) == \-1) + err(EXIT_FAILURE, "truncate"); +\& + printf("PID: %jd; fd: %d; /proc/%jd/fd/%d\en", + (intmax_t) getpid(), fd, (intmax_t) getpid(), fd); +\& + /* Code to map the file and populate the mapping with data + omitted. */ +\& + /* If a \[aq]seals\[aq] command\-line argument was supplied, set some + seals on the file. */ +\& + if (seals_arg != NULL) { + seals = 0; +\& + if (strchr(seals_arg, \[aq]g\[aq]) != NULL) + seals |= F_SEAL_GROW; + if (strchr(seals_arg, \[aq]s\[aq]) != NULL) + seals |= F_SEAL_SHRINK; + if (strchr(seals_arg, \[aq]w\[aq]) != NULL) + seals |= F_SEAL_WRITE; + if (strchr(seals_arg, \[aq]W\[aq]) != NULL) + seals |= F_SEAL_FUTURE_WRITE; + if (strchr(seals_arg, \[aq]S\[aq]) != NULL) + seals |= F_SEAL_SEAL; +\& + if (fcntl(fd, F_ADD_SEALS, seals) == \-1) + err(EXIT_FAILURE, "fcntl"); + } +\& + /* Keep running, so that the file created by memfd_create() + continues to exist. */ +\& + pause(); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS Program source: t_get_seals.c +\& +.\" SRC BEGIN (t_get_seals.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int fd; + unsigned int seals; +\& + if (argc != 2) { + fprintf(stderr, "%s /proc/PID/fd/FD\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + fd = open(argv[1], O_RDWR); + if (fd == \-1) + err(EXIT_FAILURE, "open"); +\& + seals = fcntl(fd, F_GET_SEALS); + if (seals == \-1) + err(EXIT_FAILURE, "fcntl"); +\& + printf("Existing seals:"); + if (seals & F_SEAL_SEAL) + printf(" SEAL"); + if (seals & F_SEAL_GROW) + printf(" GROW"); + if (seals & F_SEAL_WRITE) + printf(" WRITE"); + if (seals & F_SEAL_FUTURE_WRITE) + printf(" FUTURE_WRITE"); + if (seals & F_SEAL_SHRINK) + printf(" SHRINK"); + printf("\en"); +\& + /* Code to map the file and access the contents of the + resulting mapping omitted. */ +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fcntl (2), +.BR ftruncate (2), +.BR memfd_secret (2), +.BR mmap (2), +.BR shmget (2), +.BR shm_open (3) diff --git a/man/man2/memfd_secret.2 b/man/man2/memfd_secret.2 new file mode 100644 index 0000000..029dbd9 --- /dev/null +++ b/man/man2/memfd_secret.2 @@ -0,0 +1,204 @@ +.\" Copyright (c) 2021, IBM Corporation. +.\" Written by Mike Rapoport +.\" +.\" Based on memfd_create(2) man page +.\" Copyright (C) 2014 Michael Kerrisk +.\" and Copyright (C) 2014 David Herrmann +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH memfd_secret 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memfd_secret \- create an anonymous RAM-based file +to access secret memory regions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.P +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_memfd_secret, unsigned int " flags ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR memfd_secret (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR memfd_secret () +creates an anonymous RAM-based file and returns a file descriptor +that refers to it. +The file provides a way to create and access memory regions +with stronger protection than usual RAM-based files and +anonymous memory mappings. +Once all open references to the file are closed, +it is automatically released. +The initial size of the file is set to 0. +Following the call, the file size should be set using +.BR ftruncate (2). +.P +The memory areas backing the file created with +.BR memfd_secret (2) +are visible only to the processes that have access to the file descriptor. +The memory region is removed from the kernel page tables +and only the page tables of the processes holding the file descriptor +map the corresponding physical memory. +(Thus, the pages in the region can't be accessed by the kernel itself, +so that, for example, pointers to the region can't be passed to +system calls.) +.P +The following values may be bitwise ORed in +.I flags +to control the behavior of +.BR memfd_secret (): +.TP +.B FD_CLOEXEC +Set the close-on-exec flag on the new file descriptor, +which causes the region to be removed from the process on +.BR execve (2). +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +.P +As its return value, +.BR memfd_secret () +returns a new file descriptor that refers to an anonymous file. +This file descriptor is opened for both reading and writing +.RB ( O_RDWR ) +and +.B O_LARGEFILE +is set for the file descriptor. +.P +With respect to +.BR fork (2) +and +.BR execve (2), +the usual semantics apply for the file descriptor created by +.BR memfd_secret (). +A copy of the file descriptor is inherited by the child produced by +.BR fork (2) +and refers to the same file. +The file descriptor is preserved across +.BR execve (2), +unless the close-on-exec flag has been set. +.P +The memory region is locked into memory in the same way as with +.BR mlock (2), +so that it will never be written into swap, +and hibernation is inhibited for as long as any +.BR memfd_secret () +descriptions exist. +However the implementation of +.BR memfd_secret () +will not try to populate the whole range during the +.BR mmap (2) +call that attaches the region into the process's address space; +instead, the pages are only actually allocated +as they are faulted in. +The amount of memory allowed for memory mappings +of the file descriptor obeys the same rules as +.BR mlock (2) +and cannot exceed +.BR RLIMIT_MEMLOCK . +.SH RETURN VALUE +On success, +.BR memfd_secret () +returns a new file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I flags +included unknown bits. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B EMFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +There was insufficient memory to create a new anonymous file. +.TP +.B ENOSYS +.BR memfd_secret () +is not implemented on this architecture, +or has not been enabled on the kernel command-line with +.BR secretmem_enable =1. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.14. +.SH NOTES +The +.BR memfd_secret () +system call is designed to allow a user-space process +to create a range of memory that is inaccessible to anybody else - +kernel included. +There is no 100% guarantee that kernel won't be able to access +memory ranges backed by +.BR memfd_secret () +in any circumstances, but nevertheless, +it is much harder to exfiltrate data from these regions. +.P +.BR memfd_secret () +provides the following protections: +.IP \[bu] 3 +Enhanced protection +(in conjunction with all the other in-kernel attack prevention systems) +against ROP attacks. +Absence of any in-kernel primitive for accessing memory backed by +.BR memfd_secret () +means that one-gadget ROP attack +can't work to perform data exfiltration. +The attacker would need to find enough ROP gadgets +to reconstruct the missing page table entries, +which significantly increases difficulty of the attack, +especially when other protections like the kernel stack size limit +and address space layout randomization are in place. +.IP \[bu] +Prevent cross-process user-space memory exposures. +Once a region for a +.BR memfd_secret () +memory mapping is allocated, +the user can't accidentally pass it into the kernel +to be transmitted somewhere. +The memory pages in this region cannot be accessed via the direct map +and they are disallowed in get_user_pages. +.IP \[bu] +Harden against exploited kernel flaws. +In order to access memory areas backed by +.BR memfd_secret (), +a kernel-side attack would need to +either walk the page tables and create new ones, +or spawn a new privileged user-space process to perform +secrets exfiltration using +.BR ptrace (2). +.P +The way +.BR memfd_secret () +allocates and locks the memory may impact overall system performance, +therefore the system call is disabled by default and only available +if the system administrator turned it on using +"secretmem.enable=y" kernel parameter. +.P +To prevent potential data leaks of memory regions backed by +.BR memfd_secret () +from a hybernation image, +hybernation is prevented when there are active +.BR memfd_secret () +users. +.SH SEE ALSO +.BR fcntl (2), +.BR ftruncate (2), +.BR mlock (2), +.BR memfd_create (2), +.BR mmap (2), +.BR setrlimit (2) diff --git a/man/man2/migrate_pages.2 b/man/man2/migrate_pages.2 new file mode 100644 index 0000000..d5a54c1 --- /dev/null +++ b/man/man2/migrate_pages.2 @@ -0,0 +1,174 @@ +.\" SPDX-License-Identifier: Linux-man-pages-copyleft-2-para +.\" +.\" Copyright 2009 Intel Corporation +.\" Author: Andi Kleen +.\" Based on the move_pages manpage which was +.\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc. +.\" Christoph Lameter +.\" +.TH migrate_pages 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +migrate_pages \- move all pages in a process to another set of nodes +.SH LIBRARY +NUMA (Non-Uniform Memory Access) policy library +.RI ( libnuma ", " \-lnuma ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long migrate_pages(int " pid ", unsigned long " maxnode, +.BI " const unsigned long *" old_nodes, +.BI " const unsigned long *" new_nodes ); +.fi +.SH DESCRIPTION +.BR migrate_pages () +attempts to move all pages of the process +.I pid +that are in memory nodes +.I old_nodes +to the memory nodes in +.IR new_nodes . +Pages not located in any node in +.I old_nodes +will not be migrated. +As far as possible, +the kernel maintains the relative topology relationship inside +.I old_nodes +during the migration to +.IR new_nodes . +.P +The +.I old_nodes +and +.I new_nodes +arguments are pointers to bit masks of node numbers, with up to +.I maxnode +bits in each mask. +These masks are maintained as arrays of unsigned +.I long +integers (in the last +.I long +integer, the bits beyond those specified by +.I maxnode +are ignored). +The +.I maxnode +argument is the maximum node number in the bit mask plus one (this is the same +as in +.BR mbind (2), +but different from +.BR select (2)). +.P +The +.I pid +argument is the ID of the process whose pages are to be moved. +To move pages in another process, +the caller must be privileged +.RB ( CAP_SYS_NICE ) +or the real or effective user ID of the calling process must match the +real or saved-set user ID of the target process. +If +.I pid +is 0, then +.BR migrate_pages () +moves pages of the calling process. +.P +Pages shared with another process will be moved only if the initiating +process has the +.B CAP_SYS_NICE +privilege. +.SH RETURN VALUE +On success +.BR migrate_pages () +returns the number of pages that could not be moved +(i.e., a return of zero means that all pages were successfully moved). +On error, it returns \-1, and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Part or all of the memory range specified by +.IR old_nodes / new_nodes +and +.I maxnode +points outside your accessible address space. +.TP +.B EINVAL +The value specified by +.I maxnode +exceeds a kernel-imposed limit. +.\" As at 3.5, this limit is "a page worth of bits", e.g., +.\" 8 * 4096 bits, assuming a 4kB page size. +Or, +.I old_nodes +or +.I new_nodes +specifies one or more node IDs that are +greater than the maximum supported node ID. +Or, none of the node IDs specified by +.I new_nodes +are on-line and allowed by the process's current cpuset context, +or none of the specified nodes contain memory. +.TP +.B EPERM +Insufficient privilege +.RB ( CAP_SYS_NICE ) +to move pages of the process specified by +.IR pid , +or insufficient privilege +.RB ( CAP_SYS_NICE ) +to access the specified target nodes. +.TP +.B ESRCH +No process matching +.I pid +could be found. +.\" FIXME Document the other errors that can occur for migrate_pages() +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.16. +.SH NOTES +For information on library support, see +.BR numa (7). +.P +Use +.BR get_mempolicy (2) +with the +.B MPOL_F_MEMS_ALLOWED +flag to obtain the set of nodes that are allowed by +the calling process's cpuset. +Note that this information is subject to change at any +time by manual or automatic reconfiguration of the cpuset. +.P +Use of +.BR migrate_pages () +may result in pages whose location +(node) violates the memory policy established for the +specified addresses (see +.BR mbind (2)) +and/or the specified process (see +.BR set_mempolicy (2)). +That is, memory policy does not constrain the destination +nodes used by +.BR migrate_pages (). +.P +The +.I +header is not included with glibc, but requires installing +.I libnuma\-devel +or a similar package. +.SH SEE ALSO +.BR get_mempolicy (2), +.BR mbind (2), +.BR set_mempolicy (2), +.BR numa (3), +.BR numa_maps (5), +.BR cpuset (7), +.BR numa (7), +.BR migratepages (8), +.BR numastat (8) +.P +.I Documentation/vm/page_migration.rst +in the Linux kernel source tree diff --git a/man/man2/mincore.2 b/man/man2/mincore.2 new file mode 100644 index 0000000..e69d83a --- /dev/null +++ b/man/man2/mincore.2 @@ -0,0 +1,158 @@ +.\" Copyright (C) 2001 Bert Hubert +.\" and Copyright (C) 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created Sun Jun 3 17:23:32 2001 by bert hubert +.\" Slightly adapted, following comments by Hugh Dickins, aeb, 2001-06-04. +.\" Modified, 20 May 2003, Michael Kerrisk +.\" Modified, 30 Apr 2004, Michael Kerrisk +.\" 2005-04-05 mtk, Fixed error descriptions +.\" after message from +.\" 2007-01-08 mtk, rewrote various parts +.\" +.TH mincore 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mincore \- determine whether pages are resident in memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mincore(void " addr [. length "], size_t " length ", unsigned char *" vec ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mincore (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +.BR mincore () +returns a vector that indicates whether pages +of the calling process's virtual memory are resident in core (RAM), +and so will not cause a disk access (page fault) if referenced. +The kernel returns residency information about the pages +starting at the address +.IR addr , +and continuing for +.I length +bytes. +.P +The +.I addr +argument must be a multiple of the system page size. +The +.I length +argument need not be a multiple of the page size, +but since residency information is returned for whole pages, +.I length +is effectively rounded up to the next multiple of the page size. +One may obtain the page size +.RB ( PAGE_SIZE ) +using +.IR sysconf(_SC_PAGESIZE) . +.P +The +.I vec +argument must point to an array containing at least +.I "(length+PAGE_SIZE\-1) / PAGE_SIZE" +bytes. +On return, +the least significant bit of each byte will be set if +the corresponding page is currently resident in memory, +and be clear otherwise. +(The settings of the other bits in each byte are undefined; +these bits are reserved for possible later use.) +Of course the information returned in +.I vec +is only a snapshot: pages that are not +locked in memory can come and go at any moment, and the contents of +.I vec +may already be stale by the time this call returns. +.SH RETURN VALUE +On success, +.BR mincore () +returns zero. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.B EAGAIN +kernel is temporarily out of resources. +.TP +.B EFAULT +.I vec +points to an invalid address. +.TP +.B EINVAL +.I addr +is not a multiple of the page size. +.TP +.B ENOMEM +.I length +is greater than +.RI ( TASK_SIZE " \- " addr ). +(This could occur if a negative value is specified for +.IR length , +since that value will be interpreted as a large +unsigned integer.) +In Linux 2.6.11 and earlier, the error +.B EINVAL +was returned for this condition. +.TP +.B ENOMEM +.I addr +to +.I addr ++ +.I length +contained unmapped memory. +.SH STANDARDS +None. +.SH HISTORY +Linux 2.3.99pre1, +glibc 2.2. +.P +First appeared in 4.4BSD. +.P +NetBSD, FreeBSD, OpenBSD, Solaris 8, +AIX 5.1, SunOS 4.1. +.SH BUGS +Before Linux 2.6.21, +.BR mincore () +did not return correct information for +.B MAP_PRIVATE +mappings, or for nonlinear mappings (established using +.BR remap_file_pages (2)). +.\" Linux (up to now, 2.6.5), +.\" .B mincore +.\" does not return correct information for MAP_PRIVATE mappings: +.\" for a MAP_PRIVATE file mapping, +.\" .B mincore +.\" returns the residency of the file pages, rather than any +.\" modified process-private pages that have been copied on write; +.\" for a MAP_PRIVATE mapping of +.\" .IR /dev/zero , +.\" .B mincore +.\" always reports pages as nonresident; +.\" and for a MAP_PRIVATE, MAP_ANONYMOUS mapping, +.\" .B mincore +.\" always fails with the error +.\" .BR ENOMEM . +.SH SEE ALSO +.BR fincore (1), +.BR madvise (2), +.BR mlock (2), +.BR mmap (2), +.BR posix_fadvise (2), +.BR posix_madvise (3) diff --git a/man/man2/mkdir.2 b/man/man2/mkdir.2 new file mode 100644 index 0000000..132195f --- /dev/null +++ b/man/man2/mkdir.2 @@ -0,0 +1,250 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt +.\" and Copyright (C) 1993,1994 Ian Jackson +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH mkdir 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mkdir, mkdirat \- create a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.\" .B #include +.P +.BI "int mkdir(const char *" pathname ", mode_t " mode ); +.P +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.P +.BI "int mkdirat(int " dirfd ", const char *" pathname ", mode_t " mode ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mkdirat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +.BR mkdir () +attempts to create a directory named +.IR pathname . +.P +The argument +.I mode +specifies the mode for the new directory (see +.BR inode (7)). +It is modified by the process's +.I umask +in the usual way: in the absence of a default ACL, the mode of the +created directory is +.RI ( mode " & \[ti]" umask " & 0777)." +Whether other +.I mode +bits are honored for the created directory depends on the operating system. +For Linux, see NOTES below. +.P +The newly created directory will be owned by the effective user ID of the +process. +If the directory containing the file has the set-group-ID +bit set, or if the filesystem is mounted with BSD group semantics +.RI ( "mount \-o bsdgroups" +or, synonymously +.IR "mount \-o grpid" ), +the new directory will inherit the group ownership from its parent; +otherwise it will be owned by the effective group ID of the process. +.P +If the parent directory has the set-group-ID bit set, then so will the +newly created directory. +.\" +.\" +.SS mkdirat() +The +.BR mkdirat () +system call operates in exactly the same way as +.BR mkdir (), +except for the differences described here. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR mkdir () +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR mkdir ()). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +See +.BR openat (2) +for an explanation of the need for +.BR mkdirat (). +.SH RETURN VALUE +.BR mkdir () +and +.BR mkdirat () +return zero on success. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The parent directory does not allow write permission to the process, +or one of the directories in +.I pathname +did not allow search permission. +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( mkdirat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EDQUOT +The user's quota of disk blocks or inodes on the filesystem has been +exhausted. +.TP +.B EEXIST +.I pathname +already exists (not necessarily as a directory). +This includes the case where +.I pathname +is a symbolic link, dangling or not. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B EINVAL +The final component ("basename") of the new directory's +.I pathname +is invalid +(e.g., it contains characters not permitted by the underlying filesystem). +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B EMLINK +The number of links to the parent directory would exceed +.BR LINK_MAX . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing +.I pathname +has no room for the new directory. +.TP +.B ENOSPC +The new directory cannot be created because the user's disk quota is +exhausted. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B ENOTDIR +.RB ( mkdirat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B EPERM +The filesystem containing +.I pathname +does not support the creation of directories. +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem. +.SH VERSIONS +Under Linux, apart from the permission bits, the +.B S_ISVTX +.I mode +bit is also honored. +.SS glibc notes +On older kernels where +.BR mkdirat () +is unavailable, the glibc wrapper function falls back to the use of +.BR mkdir (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.I /proc/self/fd +that corresponds to the +.I dirfd +argument. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR mkdir () +SVr4, BSD, POSIX.1-2001. +.\" SVr4 documents additional EIO, EMULTIHOP +.TP +.BR mkdirat () +Linux 2.6.16, +glibc 2.4. +.SH NOTES +There are many infelicities in the protocol underlying NFS. +Some of these affect +.BR mkdir (). +.SH SEE ALSO +.BR mkdir (1), +.BR chmod (2), +.BR chown (2), +.BR mknod (2), +.BR mount (2), +.BR rmdir (2), +.BR stat (2), +.BR umask (2), +.BR unlink (2), +.BR acl (5), +.BR path_resolution (7) diff --git a/man/man2/mkdirat.2 b/man/man2/mkdirat.2 new file mode 100644 index 0000000..467b98a --- /dev/null +++ b/man/man2/mkdirat.2 @@ -0,0 +1 @@ +.so man2/mkdir.2 diff --git a/man/man2/mknod.2 b/man/man2/mknod.2 new file mode 100644 index 0000000..4add083 --- /dev/null +++ b/man/man2/mknod.2 @@ -0,0 +1,302 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt +.\" and Copyright (C) 1993,1994 Ian Jackson +.\" and Copyright (C) 2006, 2014, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Modified 1996-08-18 by urs +.\" Modified 2003-04-23 by Michael Kerrisk +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH mknod 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mknod, mknodat \- create a special or ordinary file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mknod(const char *" pathname ", mode_t " mode ", dev_t " dev ); +.P +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.P +.BI "int mknodat(int " dirfd ", const char *" pathname ", mode_t " mode \ +", dev_t " dev ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mknod (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The system call +.BR mknod () +creates a filesystem node (file, device special file, or +named pipe) named +.IR pathname , +with attributes specified by +.I mode +and +.IR dev . +.P +The +.I mode +argument specifies both the file mode to use and the type of node +to be created. +It should be a combination (using bitwise OR) of one of the file types +listed below and zero or more of the file mode bits listed in +.BR inode (7). +.P +The file mode is modified by the process's +.I umask +in the usual way: in the absence of a default ACL, the permissions of the +created node are +.RI ( mode " & \[ti]" umask ). +.P +The file type must be one of +.BR S_IFREG , +.BR S_IFCHR , +.BR S_IFBLK , +.BR S_IFIFO , +or +.B S_IFSOCK +.\" (S_IFSOCK since Linux 1.2.4) +to specify a regular file (which will be created empty), character +special file, block special file, FIFO (named pipe), or UNIX domain socket, +respectively. +(Zero file type is equivalent to type +.BR S_IFREG .) +.P +If the file type is +.B S_IFCHR +or +.BR S_IFBLK , +then +.I dev +specifies the major and minor numbers of the newly created device +special file +.RB ( makedev (3) +may be useful to build the value for +.IR dev ); +otherwise it is ignored. +.P +If +.I pathname +already exists, or is a symbolic link, this call fails with an +.B EEXIST +error. +.P +The newly created node will be owned by the effective user ID of the +process. +If the directory containing the node has the set-group-ID +bit set, or if the filesystem is mounted with BSD group semantics, the +new node will inherit the group ownership from its parent directory; +otherwise it will be owned by the effective group ID of the process. +.\" +.\" +.SS mknodat() +The +.BR mknodat () +system call operates in exactly the same way as +.BR mknod (), +except for the differences described here. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR mknod () +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR mknod ()). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +See +.BR openat (2) +for an explanation of the need for +.BR mknodat (). +.SH RETURN VALUE +.BR mknod () +and +.BR mknodat () +return zero on success. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The parent directory does not allow write permission to the process, +or one of the directories in the path prefix of +.I pathname +did not allow search permission. +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( mknodat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EDQUOT +The user's quota of disk blocks or inodes on the filesystem has been +exhausted. +.TP +.B EEXIST +.I pathname +already exists. +This includes the case where +.I pathname +is a symbolic link, dangling or not. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B EINVAL +.I mode +requested creation of something other than a regular file, device +special file, FIFO or socket. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing +.I pathname +has no room for the new node. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B ENOTDIR +.RB ( mknodat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B EPERM +.I mode +requested creation of something other than a regular file, +FIFO (named pipe), or UNIX domain socket, and the caller +is not privileged (Linux: does not have the +.B CAP_MKNOD +capability); +.\" For UNIX domain sockets and regular files, EPERM is returned only in +.\" Linux 2.2 and earlier; in Linux 2.4 and later, unprivileged can +.\" use mknod() to make these files. +also returned if the filesystem containing +.I pathname +does not support the type of node requested. +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem. +.SH VERSIONS +POSIX.1-2001 says: "The only portable use of +.BR mknod () +is to create a FIFO-special file. +If +.I mode +is not +.B S_IFIFO +or +.I dev +is not 0, the behavior of +.BR mknod () +is unspecified." +However, nowadays one should never use +.BR mknod () +for this purpose; one should use +.BR mkfifo (3), +a function especially defined for this purpose. +.P +Under Linux, +.BR mknod () +cannot be used to create directories. +One should make directories with +.BR mkdir (2). +.\" and one should make UNIX domain sockets with socket(2) and bind(2). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR mknod () +SVr4, 4.4BSD, POSIX.1-2001 (but see VERSIONS). +.\" The Linux version differs from the SVr4 version in that it +.\" does not require root permission to create pipes, also in that no +.\" EMULTIHOP, ENOLINK, or EINTR error is documented. +.TP +.BR mknodat () +Linux 2.6.16, +glibc 2.4. +POSIX.1-2008. +.SH NOTES +There are many infelicities in the protocol underlying NFS. +Some of these affect +.BR mknod () +and +.BR mknodat (). +.SH SEE ALSO +.BR mknod (1), +.BR chmod (2), +.BR chown (2), +.BR fcntl (2), +.BR mkdir (2), +.BR mount (2), +.BR socket (2), +.BR stat (2), +.BR umask (2), +.BR unlink (2), +.BR makedev (3), +.BR mkfifo (3), +.BR acl (5), +.BR path_resolution (7) diff --git a/man/man2/mknodat.2 b/man/man2/mknodat.2 new file mode 100644 index 0000000..3db2282 --- /dev/null +++ b/man/man2/mknodat.2 @@ -0,0 +1 @@ +.so man2/mknod.2 diff --git a/man/man2/mlock.2 b/man/man2/mlock.2 new file mode 100644 index 0000000..eb00a46 --- /dev/null +++ b/man/man2/mlock.2 @@ -0,0 +1,507 @@ +.\" Copyright (C) Michael Kerrisk, 2004 +.\" using some material drawn from earlier man pages +.\" written by Thomas Kuhn, Copyright 1996 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH mlock 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mlock(const void " addr [. len "], size_t " len ); +.BI "int mlock2(const void " addr [. len "], size_t " len ", \ +unsigned int " flags ); +.BI "int munlock(const void " addr [. len "], size_t " len ); +.P +.BI "int mlockall(int " flags ); +.B int munlockall(void); +.fi +.SH DESCRIPTION +.BR mlock (), +.BR mlock2 (), +and +.BR mlockall () +lock part or all of the calling process's virtual address +space into RAM, preventing that memory from being paged to the +swap area. +.P +.BR munlock () +and +.BR munlockall () +perform the converse operation, +unlocking part or all of the calling process's virtual address space, +so that pages in the specified virtual address range +can be swapped out again if required by the kernel memory manager. +.P +Memory locking and unlocking are performed in units of whole pages. +.SS mlock(), mlock2(), and munlock() +.BR mlock () +locks pages in the address range starting at +.I addr +and continuing for +.I len +bytes. +All pages that contain a part of the specified address range are +guaranteed to be resident in RAM when the call returns successfully; +the pages are guaranteed to stay in RAM until later unlocked. +.P +.BR mlock2 () +.\" commit a8ca5d0ecbdde5cc3d7accacbd69968b0c98764e +.\" commit de60f5f10c58d4f34b68622442c0e04180367f3f +.\" commit b0f205c2a3082dd9081f9a94e50658c5fa906ff1 +also locks pages in the specified range starting at +.I addr +and continuing for +.I len +bytes. +However, the state of the pages contained in that range after the call +returns successfully will depend on the value in the +.I flags +argument. +.P +The +.I flags +argument can be either 0 or the following constant: +.TP +.B MLOCK_ONFAULT +Lock pages that are currently resident and mark the entire range so +that the remaining nonresident pages are locked when they are populated +by a page fault. +.P +If +.I flags +is 0, +.BR mlock2 () +behaves exactly the same as +.BR mlock (). +.P +.BR munlock () +unlocks pages in the address range starting at +.I addr +and continuing for +.I len +bytes. +After this call, all pages that contain a part of the specified +memory range can be moved to external swap space again by the kernel. +.SS mlockall() and munlockall() +.BR mlockall () +locks all pages mapped into the address space of the +calling process. +This includes the pages of the code, data, and stack +segment, as well as shared libraries, user space kernel data, shared +memory, and memory-mapped files. +All mapped pages are guaranteed +to be resident in RAM when the call returns successfully; +the pages are guaranteed to stay in RAM until later unlocked. +.P +The +.I flags +argument is constructed as the bitwise OR of one or more of the +following constants: +.TP +.B MCL_CURRENT +Lock all pages which are currently mapped into the address space of +the process. +.TP +.B MCL_FUTURE +Lock all pages which will become mapped into the address space of the +process in the future. +These could be, for instance, new pages required +by a growing heap and stack as well as new memory-mapped files or +shared memory regions. +.TP +.BR MCL_ONFAULT " (since Linux 4.4)" +Used together with +.BR MCL_CURRENT , +.BR MCL_FUTURE , +or both. +Mark all current (with +.BR MCL_CURRENT ) +or future (with +.BR MCL_FUTURE ) +mappings to lock pages when they are faulted in. +When used with +.BR MCL_CURRENT , +all present pages are locked, but +.BR mlockall () +will not fault in non-present pages. +When used with +.BR MCL_FUTURE , +all future mappings will be marked to lock pages when they are faulted +in, but they will not be populated by the lock when the mapping is +created. +.B MCL_ONFAULT +must be used with either +.B MCL_CURRENT +or +.B MCL_FUTURE +or both. +.P +If +.B MCL_FUTURE +has been specified, then a later system call (e.g., +.BR mmap (2), +.BR sbrk (2), +.BR malloc (3)), +may fail if it would cause the number of locked bytes to exceed +the permitted maximum (see below). +In the same circumstances, stack growth may likewise fail: +the kernel will deny stack expansion and deliver a +.B SIGSEGV +signal to the process. +.P +.BR munlockall () +unlocks all pages mapped into the address space of the +calling process. +.SH RETURN VALUE +On success, these system calls return 0. +On error, \-1 is returned, +.I errno +is set to indicate the error, +and no changes are made to any locks in the +address space of the process. +.SH ERRORS +.\"SVr4 documents an additional EAGAIN error code. +.TP +.B EAGAIN +.RB ( mlock (), +.BR mlock2 (), +and +.BR munlock ()) +Some or all of the specified address range could not be locked. +.TP +.B EINVAL +.RB ( mlock (), +.BR mlock2 (), +and +.BR munlock ()) +The result of the addition +.IR addr + len +was less than +.I addr +(e.g., the addition may have resulted in an overflow). +.TP +.B EINVAL +.RB ( mlock2 ()) +Unknown \fIflags\fP were specified. +.TP +.B EINVAL +.RB ( mlockall ()) +Unknown \fIflags\fP were specified or +.B MCL_ONFAULT +was specified without either +.B MCL_FUTURE +or +.BR MCL_CURRENT . +.TP +.B EINVAL +(Not on Linux) +.I addr +was not a multiple of the page size. +.TP +.B ENOMEM +.RB ( mlock (), +.BR mlock2 (), +and +.BR munlock ()) +Some of the specified address range does not correspond to mapped +pages in the address space of the process. +.TP +.B ENOMEM +.RB ( mlock (), +.BR mlock2 (), +and +.BR munlock ()) +Locking or unlocking a region would result in the total number of +mappings with distinct attributes (e.g., locked versus unlocked) +exceeding the allowed maximum. +.\" I.e., the number of VMAs would exceed the 64kB maximum +(For example, unlocking a range in the middle of a currently locked +mapping would result in three mappings: +two locked mappings at each end and an unlocked mapping in the middle.) +.TP +.B ENOMEM +(Linux 2.6.9 and later) the caller had a nonzero +.B RLIMIT_MEMLOCK +soft resource limit, but tried to lock more memory than the limit +permitted. +This limit is not enforced if the process is privileged +.RB ( CAP_IPC_LOCK ). +.TP +.B ENOMEM +(Linux 2.4 and earlier) the calling process tried to lock more than +half of RAM. +.\" In the case of mlock(), this check is somewhat buggy: it doesn't +.\" take into account whether the to-be-locked range overlaps with +.\" already locked pages. Thus, suppose we allocate +.\" (num_physpages / 4 + 1) of memory, and lock those pages once using +.\" mlock(), and then lock the *same* page range a second time. +.\" In the case, the second mlock() call will fail, since the check +.\" calculates that the process is trying to lock (num_physpages / 2 + 2) +.\" pages, which of course is not true. (MTK, Nov 04, kernel 2.4.28) +.TP +.B EPERM +The caller is not privileged, but needs privilege +.RB ( CAP_IPC_LOCK ) +to perform the requested operation. +.TP +.B EPERM +.RB ( munlockall ()) +(Linux 2.6.8 and earlier) The caller was not privileged +.RB ( CAP_IPC_LOCK ). +.SH VERSIONS +.SS Linux +Under Linux, +.BR mlock (), +.BR mlock2 (), +and +.BR munlock () +automatically round +.I addr +down to the nearest page boundary. +However, the POSIX.1 specification of +.BR mlock () +and +.BR munlock () +allows an implementation to require that +.I addr +is page aligned, so portable applications should ensure this. +.P +The +.I VmLck +field of the Linux-specific +.IR /proc/ pid /status +file shows how many kilobytes of memory the process with ID +.I PID +has locked using +.BR mlock (), +.BR mlock2 (), +.BR mlockall (), +and +.BR mmap (2) +.BR MAP_LOCKED . +.SH STANDARDS +.TP +.BR mlock () +.TQ +.BR munlock () +.TQ +.BR mlockall () +.TQ +.BR munlockall () +POSIX.1-2008. +.TP +.BR mlock2 () +Linux. +.P +On POSIX systems on which +.BR mlock () +and +.BR munlock () +are available, +.B _POSIX_MEMLOCK_RANGE +is defined in \fI\fP and the number of bytes in a page +can be determined from the constant +.B PAGESIZE +(if defined) in \fI\fP or by calling +.IR sysconf(_SC_PAGESIZE) . +.P +On POSIX systems on which +.BR mlockall () +and +.BR munlockall () +are available, +.B _POSIX_MEMLOCK +is defined in \fI\fP to a value greater than 0. +(See also +.BR sysconf (3).) +.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines it to 1. +.SH HISTORY +.TP +.BR mlock () +.TQ +.BR munlock () +.TQ +.BR mlockall () +.TQ +.BR munlockall () +POSIX.1-2001, POSIX.1-2008, SVr4. +.TP +.BR mlock2 () +Linux 4.4, +glibc 2.27. +.SH NOTES +Memory locking has two main applications: real-time algorithms and +high-security data processing. +Real-time applications require +deterministic timing, and, like scheduling, paging is one major cause +of unexpected program execution delays. +Real-time applications will +usually also switch to a real-time scheduler with +.BR sched_setscheduler (2). +Cryptographic security software often handles critical bytes like +passwords or secret keys as data structures. +As a result of paging, +these secrets could be transferred onto a persistent swap store medium, +where they might be accessible to the enemy long after the security +software has erased the secrets in RAM and terminated. +(But be aware that the suspend mode on laptops and some desktop +computers will save a copy of the system's RAM to disk, regardless +of memory locks.) +.P +Real-time processes that are using +.BR mlockall () +to prevent delays on page faults should reserve enough +locked stack pages before entering the time-critical section, +so that no page fault can be caused by function calls. +This can be achieved by calling a function that allocates a +sufficiently large automatic variable (an array) and writes to the +memory occupied by this array in order to touch these stack pages. +This way, enough pages will be mapped for the stack and can be +locked into RAM. +The dummy writes ensure that not even copy-on-write +page faults can occur in the critical section. +.P +Memory locks are not inherited by a child created via +.BR fork (2) +and are automatically removed (unlocked) during an +.BR execve (2) +or when the process terminates. +The +.BR mlockall () +.B MCL_FUTURE +and +.B MCL_FUTURE | MCL_ONFAULT +settings are not inherited by a child created via +.BR fork (2) +and are cleared during an +.BR execve (2). +.P +Note that +.BR fork (2) +will prepare the address space for a copy-on-write operation. +The consequence is that any write access that follows will cause +a page fault that in turn may cause high latencies for a real-time process. +Therefore, it is crucial not to invoke +.BR fork (2) +after an +.BR mlockall () +or +.BR mlock () +operation\[em]not even from a thread which runs at a low priority within +a process which also has a thread running at elevated priority. +.P +The memory lock on an address range is automatically removed +if the address range is unmapped via +.BR munmap (2). +.P +Memory locks do not stack, that is, pages which have been locked several times +by calls to +.BR mlock (), +.BR mlock2 (), +or +.BR mlockall () +will be unlocked by a single call to +.BR munlock () +for the corresponding range or by +.BR munlockall (). +Pages which are mapped to several locations or by several processes stay +locked into RAM as long as they are locked at least at one location or by +at least one process. +.P +If a call to +.BR mlockall () +which uses the +.B MCL_FUTURE +flag is followed by another call that does not specify this flag, the +changes made by the +.B MCL_FUTURE +call will be lost. +.P +The +.BR mlock2 () +.B MLOCK_ONFAULT +flag and the +.BR mlockall () +.B MCL_ONFAULT +flag allow efficient memory locking for applications that deal with +large mappings where only a (small) portion of pages in the mapping are touched. +In such cases, locking all of the pages in a mapping would incur +a significant penalty for memory locking. +.SS Limits and permissions +In Linux 2.6.8 and earlier, +a process must be privileged +.RB ( CAP_IPC_LOCK ) +in order to lock memory and the +.B RLIMIT_MEMLOCK +soft resource limit defines a limit on how much memory the process may lock. +.P +Since Linux 2.6.9, no limits are placed on the amount of memory +that a privileged process can lock and the +.B RLIMIT_MEMLOCK +soft resource limit instead defines a limit on how much memory an +unprivileged process may lock. +.SH BUGS +In Linux 4.8 and earlier, +a bug in the kernel's accounting of locked memory for unprivileged processes +(i.e., without +.BR CAP_IPC_LOCK ) +meant that if the region specified by +.I addr +and +.I len +overlapped an existing lock, +then the already locked bytes in the overlapping region were counted twice +when checking against the limit. +Such double accounting could incorrectly calculate a "total locked memory" +value for the process that exceeded the +.B RLIMIT_MEMLOCK +limit, with the result that +.BR mlock () +and +.BR mlock2 () +would fail on requests that should have succeeded. +This bug was fixed +.\" commit 0cf2f6f6dc605e587d2c1120f295934c77e810e8 +in Linux 4.9. +.P +In Linux 2.4 series of kernels up to and including Linux 2.4.17, +a bug caused the +.BR mlockall () +.B MCL_FUTURE +flag to be inherited across a +.BR fork (2). +This was rectified in Linux 2.4.18. +.P +Since Linux 2.6.9, if a privileged process calls +.I mlockall(MCL_FUTURE) +and later drops privileges (loses the +.B CAP_IPC_LOCK +capability by, for example, +setting its effective UID to a nonzero value), +then subsequent memory allocations (e.g., +.BR mmap (2), +.BR brk (2)) +will fail if the +.B RLIMIT_MEMLOCK +resource limit is encountered. +.\" See the following LKML thread: +.\" http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2 +.\" "Rationale for RLIMIT_MEMLOCK" +.\" 23 Jan 2006 +.SH SEE ALSO +.BR mincore (2), +.BR mmap (2), +.BR setrlimit (2), +.BR shmctl (2), +.BR sysconf (3), +.BR proc (5), +.BR capabilities (7) diff --git a/man/man2/mlock2.2 b/man/man2/mlock2.2 new file mode 100644 index 0000000..5e5b3c7 --- /dev/null +++ b/man/man2/mlock2.2 @@ -0,0 +1 @@ +.so man2/mlock.2 diff --git a/man/man2/mlockall.2 b/man/man2/mlockall.2 new file mode 100644 index 0000000..5e5b3c7 --- /dev/null +++ b/man/man2/mlockall.2 @@ -0,0 +1 @@ +.so man2/mlock.2 diff --git a/man/man2/mmap.2 b/man/man2/mmap.2 new file mode 100644 index 0000000..7af0de2 --- /dev/null +++ b/man/man2/mmap.2 @@ -0,0 +1,1038 @@ +'\" t +.\" Copyright (C) 1996 Andries Brouwer +.\" and Copyright (C) 2006, 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2000-03-25 by Jim Van Zandt +.\" Modified 2001-10-04 by John Levon +.\" Modified 2003-02-02 by Andi Kleen +.\" Modified 2003-05-21 by Michael Kerrisk +.\" MAP_LOCKED works from Linux 2.5.37 +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2004-09-11 by aeb +.\" Modified 2004-12-08, from Eric Estievenart +.\" Modified 2004-12-08, mtk, formatting tidy-ups +.\" Modified 2006-12-04, mtk, various parts rewritten +.\" 2007-07-10, mtk, Added an example program. +.\" 2008-11-18, mtk, document MAP_STACK +.\" +.TH mmap 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mmap, munmap \- map or unmap files or devices into memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *mmap(void " addr [. length "], size_t " length \ +", int " prot ", int " flags , +.BI " int " fd ", off_t " offset ); +.BI "int munmap(void " addr [. length "], size_t " length ); +.fi +.P +See NOTES for information on feature test macro requirements. +.SH DESCRIPTION +.BR mmap () +creates a new mapping in the virtual address space of +the calling process. +The starting address for the new mapping is specified in +.IR addr . +The +.I length +argument specifies the length of the mapping (which must be greater than 0). +.P +If +.I addr +is NULL, +then the kernel chooses the (page-aligned) address +at which to create the mapping; +this is the most portable method of creating a new mapping. +If +.I addr +is not NULL, +then the kernel takes it as a hint about where to place the mapping; +on Linux, the kernel will pick a nearby page boundary (but always above +or equal to the value specified by +.IR /proc/sys/vm/mmap_min_addr ) +and attempt to create the mapping there. +If another mapping already exists there, the kernel picks a new address that +may or may not depend on the hint. +.\" Before Linux 2.6.24, the address was rounded up to the next page +.\" boundary; since Linux 2.6.24, it is rounded down! +The address of the new mapping is returned as the result of the call. +.P +The contents of a file mapping (as opposed to an anonymous mapping; see +.B MAP_ANONYMOUS +below), are initialized using +.I length +bytes starting at offset +.I offset +in the file (or other object) referred to by the file descriptor +.IR fd . +.I offset +must be a multiple of the page size as returned by +.IR sysconf(_SC_PAGE_SIZE) . +.P +After the +.BR mmap () +call has returned, the file descriptor, +.IR fd , +can be closed immediately without invalidating the mapping. +.P +The +.I prot +argument describes the desired memory protection of the mapping +(and must not conflict with the open mode of the file). +It is either +.B PROT_NONE +or the bitwise OR of one or more of the following flags: +.TP 1.1i +.B PROT_EXEC +Pages may be executed. +.TP +.B PROT_READ +Pages may be read. +.TP +.B PROT_WRITE +Pages may be written. +.TP +.B PROT_NONE +Pages may not be accessed. +.\" +.SS The flags argument +The +.I flags +argument determines whether updates to the mapping +are visible to other processes mapping the same region, +and whether updates are carried through to the underlying file. +This behavior is determined by including exactly one +of the following values in +.IR flags : +.TP +.B MAP_SHARED +Share this mapping. +Updates to the mapping are visible to other processes mapping the same region, +and (in the case of file-backed mappings) +are carried through to the underlying file. +(To precisely control when updates are carried through +to the underlying file requires the use of +.BR msync (2).) +.TP +.BR MAP_SHARED_VALIDATE " (since Linux 4.15)" +This flag provides the same behavior as +.B MAP_SHARED +except that +.B MAP_SHARED +mappings ignore unknown flags in +.IR flags . +By contrast, when creating a mapping using +.BR MAP_SHARED_VALIDATE , +the kernel verifies all passed flags are known and fails the +mapping with the error +.B EOPNOTSUPP +for unknown flags. +This mapping type is also required to be able to use some mapping flags +(e.g., +.BR MAP_SYNC ). +.TP +.B MAP_PRIVATE +Create a private copy-on-write mapping. +Updates to the mapping are not visible to other processes +mapping the same file, and are not carried through to +the underlying file. +It is unspecified whether changes made to the file after the +.BR mmap () +call are visible in the mapped region. +.P +Both +.B MAP_SHARED +and +.B MAP_PRIVATE +are described in POSIX.1-2001 and POSIX.1-2008. +.B MAP_SHARED_VALIDATE +is a Linux extension. +.P +In addition, zero or more of the following values can be ORed in +.IR flags : +.TP +.BR MAP_32BIT " (since Linux 2.4.20, 2.6)" +Put the mapping into the first 2 Gigabytes of the process address space. +This flag is supported only on x86-64, for 64-bit programs. +It was added to allow thread stacks to be allocated somewhere +in the first 2\ GB of memory, +so as to improve context-switch performance on some early +64-bit processors. +.\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08 +Modern x86-64 processors no longer have this performance problem, +so use of this flag is not required on those systems. +The +.B MAP_32BIT +flag is ignored when +.B MAP_FIXED +is set. +.TP +.B MAP_ANON +Synonym for +.BR MAP_ANONYMOUS ; +provided for compatibility with other implementations. +.TP +.B MAP_ANONYMOUS +The mapping is not backed by any file; +its contents are initialized to zero. +The +.I fd +argument is ignored; +however, some implementations require +.I fd +to be \-1 if +.B MAP_ANONYMOUS +(or +.BR MAP_ANON ) +is specified, +and portable applications should ensure this. +The +.I offset +argument should be zero. +.\" See the pgoff overflow check in do_mmap(). +.\" See the offset check in sys_mmap in arch/x86/kernel/sys_x86_64.c. +Support for +.B MAP_ANONYMOUS +in conjunction with +.B MAP_SHARED +was added in Linux 2.4. +.TP +.B MAP_DENYWRITE +This flag is ignored. +.\" Introduced in 1.1.36, removed in 1.3.24. +(Long ago\[em]Linux 2.0 and earlier\[em]it signaled +that attempts to write to the underlying file should fail with +.BR ETXTBSY . +But this was a source of denial-of-service attacks.) +.TP +.B MAP_EXECUTABLE +This flag is ignored. +.\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link. +.\" (Long ago, it signaled that the underlying file is an executable. +.\" However, that information was not really used anywhere.) +.\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of +.\" MAP_DENYWRITE? +.TP +.B MAP_FILE +Compatibility flag. +Ignored. +.\" On some systems, this was required as the opposite of +.\" MAP_ANONYMOUS -- mtk, 1 May 2007 +.TP +.B MAP_FIXED +Don't interpret +.I addr +as a hint: place the mapping at exactly that address. +.I addr +must be suitably aligned: for most architectures a multiple of the page +size is sufficient; however, some architectures may impose additional +restrictions. +If the memory region specified by +.I addr +and +.I length +overlaps pages of any existing mapping(s), then the overlapped +part of the existing mapping(s) will be discarded. +If the specified address cannot be used, +.BR mmap () +will fail. +.IP +Software that aspires to be portable should use the +.B MAP_FIXED +flag with care, +keeping in mind that the exact layout of a process's memory mappings +is allowed to change significantly between Linux versions, +C library versions, and operating system releases. +.I Carefully read the discussion of this flag in NOTES! +.TP +.BR MAP_FIXED_NOREPLACE " (since Linux 4.17)" +.\" commit a4ff8e8620d3f4f50ac4b41e8067b7d395056843 +This flag provides behavior that is similar to +.B MAP_FIXED +with respect to the +.I addr +enforcement, but differs in that +.B MAP_FIXED_NOREPLACE +never clobbers a preexisting mapped range. +If the requested range would collide with an existing mapping, +then this call fails with the error +.B EEXIST. +This flag can therefore be used as a way to atomically +(with respect to other threads) attempt to map an address range: +one thread will succeed; all others will report failure. +.IP +Note that older kernels which do not recognize the +.B MAP_FIXED_NOREPLACE +flag will typically (upon detecting a collision with a preexisting mapping) +fall back to a +.RB \[lq]non- MAP_FIXED \[rq] +type of behavior: +they will return an address that is different from the requested address. +Therefore, backward-compatible software +should check the returned address against the requested address. +.TP +.B MAP_GROWSDOWN +This flag is used for stacks. +It indicates to the kernel virtual memory system that the mapping +should extend downward in memory. +The return address is one page lower than the memory area that is +actually created in the process's virtual address space. +Touching an address in the "guard" page below the mapping will cause +the mapping to grow by a page. +This growth can be repeated until the mapping grows to within a +page of the high end of the next lower mapping, +at which point touching the "guard" page will result in a +.B SIGSEGV +signal. +.TP +.BR MAP_HUGETLB " (since Linux 2.6.32)" +Allocate the mapping using "huge" pages. +See the Linux kernel source file +.I Documentation/admin\-guide/mm/hugetlbpage.rst +for further information, as well as NOTES, below. +.TP +.B MAP_HUGE_2MB +.TQ +.BR MAP_HUGE_1GB " (since Linux 3.8)" +.\" See https://lwn.net/Articles/533499/ +Used in conjunction with +.B MAP_HUGETLB +to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB) +on systems that support multiple hugetlb page sizes. +.IP +More generally, the desired huge page size can be configured by encoding +the base-2 logarithm of the desired page size in the six bits at the offset +.BR MAP_HUGE_SHIFT . +(A value of zero in this bit field provides the default huge page size; +the default huge page size can be discovered via the +.I Hugepagesize +field exposed by +.IR /proc/meminfo .) +Thus, the above two constants are defined as: +.IP +.in +4n +.EX +#define MAP_HUGE_2MB (21 << MAP_HUGE_SHIFT) +#define MAP_HUGE_1GB (30 << MAP_HUGE_SHIFT) +.EE +.in +.IP +The range of huge page sizes that are supported by the system +can be discovered by listing the subdirectories in +.IR /sys/kernel/mm/hugepages . +.TP +.BR MAP_LOCKED " (since Linux 2.5.37)" +Mark the mapped region to be locked in the same way as +.BR mlock (2). +This implementation will try to populate (prefault) the whole range but the +.BR mmap () +call doesn't fail with +.B ENOMEM +if this fails. +Therefore major faults might happen later on. +So the semantic is not as strong as +.BR mlock (2). +One should use +.BR mmap () +plus +.BR mlock (2) +when major faults are not acceptable after the initialization of the mapping. +The +.B MAP_LOCKED +flag is ignored in older kernels. +.\" If set, the mapped pages will not be swapped out. +.TP +.BR MAP_NONBLOCK " (since Linux 2.5.46)" +This flag is meaningful only in conjunction with +.BR MAP_POPULATE . +Don't perform read-ahead: +create page tables entries only for pages +that are already present in RAM. +Since Linux 2.6.23, +.\" commit 54cb8821de07f2ffcd28c380ce9b93d5784b40d7 +this flag causes +.B MAP_POPULATE +to do nothing. +One day, the combination of +.B MAP_POPULATE +and +.B MAP_NONBLOCK +may be reimplemented. +.TP +.B MAP_NORESERVE +Do not reserve swap space for this mapping. +When swap space is reserved, one has the guarantee +that it is possible to modify the mapping. +When swap space is not reserved one might get +.B SIGSEGV +upon a write +if no physical memory is available. +See also the discussion of the file +.I /proc/sys/vm/overcommit_memory +in +.BR proc (5). +Before Linux 2.6, this flag had effect only for +private writable mappings. +.TP +.BR MAP_POPULATE " (since Linux 2.5.46)" +Populate (prefault) page tables for a mapping. +For a file mapping, this causes read-ahead on the file. +This will help to reduce blocking on page faults later. +The +.BR mmap () +call doesn't fail if the mapping cannot be populated (for example, due +to limitations on the number of mapped huge pages when using +.BR MAP_HUGETLB ). +Support for +.B MAP_POPULATE +in conjunction with private mappings was added in Linux 2.6.23. +.TP +.BR MAP_STACK " (since Linux 2.6.27)" +Allocate the mapping at an address suitable for a process +or thread stack. +.IP +This flag is currently a no-op on Linux. +However, by employing this flag, applications can ensure that +they transparently obtain support if the flag +is implemented in the future. +Thus, it is used in the glibc threading implementation to allow for +the fact that some architectures may (later) require special treatment +for stack allocations. +.\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08 +.\" commit cd98a04a59e2f94fa64d5bf1e26498d27427d5e7 +.\" http://thread.gmane.org/gmane.linux.kernel/720412 +.\" "pthread_create() slow for many threads; also time to revisit 64b +.\" context switch optimization?" +A further reason to employ this flag is portability: +.B MAP_STACK +exists (and has an effect) on some other systems (e.g., some of the BSDs). +.TP +.BR MAP_SYNC " (since Linux 4.15)" +This flag is available only with the +.B MAP_SHARED_VALIDATE +mapping type; +mappings of type +.B MAP_SHARED +will silently ignore this flag. +This flag is supported only for files supporting DAX +(direct mapping of persistent memory). +For other files, creating a mapping with this flag results in an +.B EOPNOTSUPP +error. +.IP +Shared file mappings with this flag provide the guarantee that while +some memory is mapped writable in the address space of the process, +it will be visible in the same file at the same offset even after +the system crashes or is rebooted. +In conjunction with the use of appropriate CPU instructions, +this provides users of such mappings with a more efficient way +of making data modifications persistent. +.TP +.BR MAP_UNINITIALIZED " (since Linux 2.6.33)" +Don't clear anonymous pages. +This flag is intended to improve performance on embedded devices. +This flag is honored only if the kernel was configured with the +.B CONFIG_MMAP_ALLOW_UNINITIALIZED +option. +Because of the security implications, +that option is normally enabled only on embedded devices +(i.e., devices where one has complete control of the contents of user memory). +.P +Of the above flags, only +.B MAP_FIXED +is specified in POSIX.1-2001 and POSIX.1-2008. +However, most systems also support +.B MAP_ANONYMOUS +(or its synonym +.BR MAP_ANON ). +.\" FIXME . for later review when Issue 8 is one day released... +.\" POSIX may add MAP_ANON in the future +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=850 +.SS munmap() +The +.BR munmap () +system call deletes the mappings for the specified address range, and +causes further references to addresses within the range to generate +invalid memory references. +The region is also automatically unmapped +when the process is terminated. +On the other hand, closing the file +descriptor does not unmap the region. +.P +The address +.I addr +must be a multiple of the page size (but +.I length +need not be). +All pages containing a part +of the indicated range are unmapped, and subsequent references +to these pages will generate +.BR SIGSEGV . +It is not an error if the +indicated range does not contain any mapped pages. +.SH RETURN VALUE +On success, +.BR mmap () +returns a pointer to the mapped area. +On error, the value +.B MAP_FAILED +(that is, +.IR "(void\ *)\ \-1" ) +is returned, and +.I errno +is set to indicate the error. +.P +On success, +.BR munmap () +returns 0. +On failure, it returns \-1, and +.I errno +is set to indicate the error (probably to +.BR EINVAL ). +.SH ERRORS +.TP +.B EACCES +A file descriptor refers to a non-regular file. +Or a file mapping was requested, but +.I fd +is not open for reading. +Or +.B MAP_SHARED +was requested and +.B PROT_WRITE +is set, but +.I fd +is not open in read/write +.RB ( O_RDWR ) +mode. +Or +.B PROT_WRITE +is set, but the file is append-only. +.TP +.B EAGAIN +The file has been locked, or too much memory has been locked (see +.BR setrlimit (2)). +.TP +.B EBADF +.I fd +is not a valid file descriptor (and +.B MAP_ANONYMOUS +was not set). +.TP +.B EEXIST +.B MAP_FIXED_NOREPLACE +was specified in +.IR flags , +and the range covered by +.I addr +and +.I length +clashes with an existing mapping. +.TP +.B EINVAL +We don't like +.IR addr , +.IR length , +or +.I offset +(e.g., they are too large, or not aligned on a page boundary). +.TP +.B EINVAL +(since Linux 2.6.12) +.I length +was 0. +.TP +.B EINVAL +.I flags +contained none of +.BR MAP_PRIVATE , +.BR MAP_SHARED , +or +.BR MAP_SHARED_VALIDATE . +.TP +.B ENFILE +.\" This is for shared anonymous segments +.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() +The system-wide limit on the total number of open files has been reached. +.\" .TP +.\" .B ENOEXEC +.\" A file could not be mapped for reading. +.TP +.B ENODEV +The underlying filesystem of the specified file does not support +memory mapping. +.TP +.B ENOMEM +No memory is available. +.TP +.B ENOMEM +The process's maximum number of mappings would have been exceeded. +This error can also occur for +.BR munmap (), +when unmapping a region in the middle of an existing mapping, +since this results in two smaller mappings on either side of +the region being unmapped. +.TP +.B ENOMEM +(since Linux 4.7) +The process's +.B RLIMIT_DATA +limit, described in +.BR getrlimit (2), +would have been exceeded. +.TP +.B ENOMEM +We don't like +.IR addr , +because it exceeds the virtual address space of the CPU. +.TP +.B EOVERFLOW +On 32-bit architecture together with the large file extension +(i.e., using 64-bit +.IR off_t ): +the number of pages used for +.I length +plus number of pages used for +.I offset +would overflow +.I "unsigned long" +(32 bits). +.TP +.B EPERM +The +.I prot +argument asks for +.B PROT_EXEC +but the mapped area belongs to a file on a filesystem that +was mounted no-exec. +.\" (Since Linux 2.4.25 / Linux 2.6.0.) +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B EPERM +The +.B MAP_HUGETLB +flag was specified, but the caller was not privileged (did not have the +.B CAP_IPC_LOCK +capability) +and is not a member of the +.I sysctl_hugetlb_shm_group +group; see the description of +.I /proc/sys/vm/sysctl_hugetlb_shm_group +in +.BR proc_sys (5). +.TP +.B ETXTBSY +.B MAP_DENYWRITE +was set but the object specified by +.I fd +is open for writing. +.P +Use of a mapped region can result in these signals: +.TP +.B SIGSEGV +Attempted write into a region mapped as read-only. +.TP +.B SIGBUS +Attempted access to a page of the buffer that lies beyond the +end of the mapped file. +For an explanation of the treatment of the bytes in the page that +corresponds to the end of a mapped file that is not a multiple +of the page size, see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mmap (), +.BR munmap () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On some hardware architectures (e.g., i386), +.B PROT_WRITE +implies +.BR PROT_READ . +It is architecture dependent whether +.B PROT_READ +implies +.B PROT_EXEC +or not. +Portable programs should always set +.B PROT_EXEC +if they intend to execute code in the new mapping. +.P +The portable way to create a mapping is to specify +.I addr +as 0 (NULL), and omit +.B MAP_FIXED +from +.IR flags . +In this case, the system chooses the address for the mapping; +the address is chosen so as not to conflict with any existing mapping, +and will not be 0. +If the +.B MAP_FIXED +flag is specified, and +.I addr +is 0 (NULL), then the mapped address will be 0 (NULL). +.P +Certain +.I flags +constants are defined only if suitable feature test macros are defined +(possibly by default): +.B _DEFAULT_SOURCE +with glibc 2.19 or later; +or +.B _BSD_SOURCE +or +.B _SVID_SOURCE +in glibc 2.19 and earlier. +(Employing +.B _GNU_SOURCE +also suffices, +and requiring that macro specifically would have been more logical, +since these flags are all Linux-specific.) +The relevant flags are: +.BR MAP_32BIT , +.B MAP_ANONYMOUS +(and the synonym +.BR MAP_ANON ), +.BR MAP_DENYWRITE , +.BR MAP_EXECUTABLE , +.BR MAP_FILE , +.BR MAP_GROWSDOWN , +.BR MAP_HUGETLB , +.BR MAP_LOCKED , +.BR MAP_NONBLOCK , +.BR MAP_NORESERVE , +.BR MAP_POPULATE , +and +.BR MAP_STACK . +.SS C library/kernel differences +This page describes the interface provided by the glibc +.BR mmap () +wrapper function. +Originally, this function invoked a system call of the same name. +Since Linux 2.4, that system call has been superseded by +.BR mmap2 (2), +and nowadays +.\" Since around glibc 2.1/2.2, depending on the platform. +the glibc +.BR mmap () +wrapper function invokes +.BR mmap2 (2) +with a suitably adjusted value for +.IR offset . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD. +.\" SVr4 documents additional error codes ENXIO and ENODEV. +.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. +.P +On POSIX systems on which +.BR mmap (), +.BR msync (2), +and +.BR munmap () +are available, +.B _POSIX_MAPPED_FILES +is defined in \fI\fP to a value greater than 0. +(See also +.BR sysconf (3).) +.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines it to 1. +.SH NOTES +Memory mapped by +.BR mmap () +is preserved across +.BR fork (2), +with the same attributes. +.P +A file is mapped in multiples of the page size. +For a file that is not +a multiple of the page size, +the remaining bytes in the partial page at the end of the mapping +are zeroed when mapped, +and modifications to that region are not written out to the file. +The effect of +changing the size of the underlying file of a mapping on the pages that +correspond to added or removed regions of the file is unspecified. +.P +An application can determine which pages of a mapping are +currently resident in the buffer/page cache using +.BR mincore (2). +.\" +.SS Using MAP_FIXED safely +The only safe use for +.B MAP_FIXED +is where the address range specified by +.I addr +and +.I length +was previously reserved using another mapping; +otherwise, the use of +.B MAP_FIXED +is hazardous because it forcibly removes preexisting mappings, +making it easy for a multithreaded process to corrupt its own address space. +.P +For example, suppose that thread A looks through +.IR /proc/ pid /maps +in order to locate an unused address range that it can map using +.BR MAP_FIXED , +while thread B simultaneously acquires part or all of that same +address range. +When thread A subsequently employs +.BR mmap(MAP_FIXED) , +it will effectively clobber the mapping that thread B created. +In this scenario, +thread B need not create a mapping directly; simply making a library call +that, internally, uses +.BR dlopen (3) +to load some other shared library, will suffice. +The +.BR dlopen (3) +call will map the library into the process's address space. +Furthermore, almost any library call may be implemented in a way that +adds memory mappings to the address space, either with this technique, +or by simply allocating memory. +Examples include +.BR brk (2), +.BR malloc (3), +.BR pthread_create (3), +and the PAM libraries +.UR http://www.linux-pam.org +.UE . +.P +Since Linux 4.17, a multithreaded program can use the +.B MAP_FIXED_NOREPLACE +flag to avoid the hazard described above +when attempting to create a mapping at a fixed address +that has not been reserved by a preexisting mapping. +.\" +.SS Timestamps changes for file-backed mappings +For file-backed mappings, the +.I st_atime +field for the mapped file may be updated at any time between the +.BR mmap () +and the corresponding unmapping; the first reference to a mapped +page will update the field if it has not been already. +.P +The +.I st_ctime +and +.I st_mtime +field for a file mapped with +.B PROT_WRITE +and +.B MAP_SHARED +will be updated after +a write to the mapped region, and before a subsequent +.BR msync (2) +with the +.B MS_SYNC +or +.B MS_ASYNC +flag, if one occurs. +.\" +.SS Huge page (Huge TLB) mappings +For mappings that employ huge pages, the requirements for the arguments of +.BR mmap () +and +.BR munmap () +differ somewhat from the requirements for mappings +that use the native system page size. +.P +For +.BR mmap (), +.I offset +must be a multiple of the underlying huge page size. +The system automatically aligns +.I length +to be a multiple of the underlying huge page size. +.P +For +.BR munmap (), +.IR addr , +and +.I length +must both be a multiple of the underlying huge page size. +.\" +.SH BUGS +On Linux, there are no guarantees like those suggested above under +.BR MAP_NORESERVE . +By default, any process can be killed +at any moment when the system runs out of memory. +.P +Before Linux 2.6.7, the +.B MAP_POPULATE +flag has effect only if +.I prot +is specified as +.BR PROT_NONE . +.P +SUSv3 specifies that +.BR mmap () +should fail if +.I length +is 0. +However, before Linux 2.6.12, +.BR mmap () +succeeded in this case: no mapping was created and the call returned +.IR addr . +Since Linux 2.6.12, +.BR mmap () +fails with the error +.B EINVAL +for this case. +.P +POSIX specifies that the system shall always +zero fill any partial page at the end +of the object and that system will never write any modification of the +object beyond its end. +On Linux, when you write data to such partial page after the end +of the object, the data stays in the page cache even after the file +is closed and unmapped +and even though the data is never written to the file itself, +subsequent mappings may see the modified content. +In some cases, this could be fixed by calling +.BR msync (2) +before the unmap takes place; +however, this doesn't work on +.BR tmpfs (5) +(for example, when using the POSIX shared memory interface documented in +.BR shm_overview (7)). +.SH EXAMPLES +.\" FIXME . Add an example here that uses an anonymous shared region for +.\" IPC between parent and child. +The following program prints part of the file specified in +its first command-line argument to standard output. +The range of bytes to be printed is specified via offset and length +values in the second and third command-line arguments. +The program creates a memory mapping of the required +pages of the file and then uses +.BR write (2) +to output the desired bytes. +.SS Program source +.\" SRC BEGIN (mmap.c) +.EX +#include +#include +#include +#include +#include +#include +#include +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +int +main(int argc, char *argv[]) +{ + int fd; + char *addr; + off_t offset, pa_offset; + size_t length; + ssize_t s; + struct stat sb; +\& + if (argc < 3 || argc > 4) { + fprintf(stderr, "%s file offset [length]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + fd = open(argv[1], O_RDONLY); + if (fd == \-1) + handle_error("open"); +\& + if (fstat(fd, &sb) == \-1) /* To obtain file size */ + handle_error("fstat"); +\& + offset = atoi(argv[2]); + pa_offset = offset & \[ti](sysconf(_SC_PAGE_SIZE) \- 1); + /* offset for mmap() must be page aligned */ +\& + if (offset >= sb.st_size) { + fprintf(stderr, "offset is past end of file\en"); + exit(EXIT_FAILURE); + } +\& + if (argc == 4) { + length = atoi(argv[3]); + if (offset + length > sb.st_size) + length = sb.st_size \- offset; + /* Can\[aq]t display bytes past end of file */ +\& + } else { /* No length arg ==> display to end of file */ + length = sb.st_size \- offset; + } +\& + addr = mmap(NULL, length + offset \- pa_offset, PROT_READ, + MAP_PRIVATE, fd, pa_offset); + if (addr == MAP_FAILED) + handle_error("mmap"); +\& + s = write(STDOUT_FILENO, addr + offset \- pa_offset, length); + if (s != length) { + if (s == \-1) + handle_error("write"); +\& + fprintf(stderr, "partial write"); + exit(EXIT_FAILURE); + } +\& + munmap(addr, length + offset \- pa_offset); + close(fd); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ftruncate (2), +.BR getpagesize (2), +.BR memfd_create (2), +.BR mincore (2), +.BR mlock (2), +.BR mmap2 (2), +.BR mprotect (2), +.BR mremap (2), +.BR msync (2), +.BR remap_file_pages (2), +.BR setrlimit (2), +.BR shmat (2), +.BR userfaultfd (2), +.BR shm_open (3), +.BR shm_overview (7) +.P +The descriptions of the following files in +.BR proc (5): +.IR /proc/ pid /maps , +.IR /proc/ pid /map_files , +and +.IR /proc/ pid /smaps . +.P +B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391. +.\" +.\" Repeat after me: private read-only mappings are 100% equivalent to +.\" shared read-only mappings. No ifs, buts, or maybes. -- Linus diff --git a/man/man2/mmap2.2 b/man/man2/mmap2.2 new file mode 100644 index 0000000..c6a2ad6 --- /dev/null +++ b/man/man2/mmap2.2 @@ -0,0 +1,85 @@ +.\" Copyright (C) 2002, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 31 Jan 2002, Michael Kerrisk +.\" Added description of mmap2 +.\" Modified, 2004-11-25, mtk -- removed stray #endif in prototype +.\" +.TH mmap2 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mmap2 \- map files or devices into memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " MAP_* " and " PROT_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "void *syscall(SYS_mmap2, unsigned long " addr ", unsigned long " length , +.BI " unsigned long " prot ", unsigned long " flags , +.BI " unsigned long " fd ", unsigned long " pgoffset ); +.fi +.SH DESCRIPTION +This is probably not the system call that you are interested in; instead, see +.BR mmap (2), +which describes the glibc wrapper function that invokes this system call. +.P +The +.BR mmap2 () +system call provides the same interface as +.BR mmap (2), +except that the final argument specifies the offset into the +file in 4096-byte units (instead of bytes, as is done by +.BR mmap (2)). +This enables applications that use a 32-bit +.I off_t +to map large files (up to 2\[ha]44 bytes). +.SH RETURN VALUE +On success, +.BR mmap2 () +returns a pointer to the mapped area. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Problem with getting the data from user space. +.TP +.B EINVAL +(Various platforms where the page size is not 4096 bytes.) +.I "offset\ *\ 4096" +is not a multiple of the system page size. +.P +.BR mmap2 () +can also return any of the errors described in +.BR mmap (2). +.SH VERSIONS +On architectures where this system call is present, +the glibc +.BR mmap () +wrapper function invokes this system call rather than the +.BR mmap (2) +system call. +.P +This system call does not exist on x86-64. +.P +On ia64, the unit for +.I offset +is actually the system page size, rather than 4096 bytes. +.\" ia64 can have page sizes ranging from 4 kB to 64 kB. +.\" On cris, it looks like the unit might also be the page size, +.\" which is 8192 bytes. -- mtk, June 2007 +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.3.31. +.SH SEE ALSO +.BR getpagesize (2), +.BR mmap (2), +.BR mremap (2), +.BR msync (2), +.BR shm_open (3) diff --git a/man/man2/modify_ldt.2 b/man/man2/modify_ldt.2 new file mode 100644 index 0000000..faf87d9 --- /dev/null +++ b/man/man2/modify_ldt.2 @@ -0,0 +1,196 @@ +.\" Copyright (c) 1995 Michael Chastain (mec@duracef.shout.net), 22 July 1995. +.\" Copyright (c) 2015 Andrew Lutomirski +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH modify_ldt 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +modify_ldt \- get or set a per-process LDT entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " "struct user_desc" " */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_modify_ldt, int " func ", void " ptr [. bytecount ], +.BI " unsigned long " bytecount ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR modify_ldt (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR modify_ldt () +reads or writes the local descriptor table (LDT) for a process. +The LDT +is an array of segment descriptors that can be referenced by user code. +Linux allows processes to configure a per-process (actually per-mm) LDT. +For more information about the LDT, see the Intel Software Developer's +Manual or the AMD Architecture Programming Manual. +.P +When +.I func +is 0, +.BR modify_ldt () +reads the LDT into the memory pointed to by +.IR ptr . +The number of bytes read is the smaller of +.I bytecount +and the actual size of the LDT, although the kernel may act as though +the LDT is padded with additional trailing zero bytes. +On success, +.BR modify_ldt () +will return the number of bytes read. +.P +When +.I func +is 1 or 0x11, +.BR modify_ldt () +modifies the LDT entry indicated by +.IR ptr\->entry_number . +.I ptr +points to a +.I user_desc +structure +and +.I bytecount +must equal the size of this structure. +.P +The +.I user_desc +structure is defined in \fI\fP as: +.P +.in +4n +.EX +struct user_desc { + unsigned int entry_number; + unsigned int base_addr; + unsigned int limit; + unsigned int seg_32bit:1; + unsigned int contents:2; + unsigned int read_exec_only:1; + unsigned int limit_in_pages:1; + unsigned int seg_not_present:1; + unsigned int useable:1; +}; +.EE +.in +.P +In Linux 2.4 and earlier, this structure was named +.IR modify_ldt_ldt_s . +.P +The +.I contents +field is the segment type (data, expand-down data, non-conforming code, or +conforming code). +The other fields match their descriptions in the CPU manual, although +.BR modify_ldt () +cannot set the hardware-defined "accessed" bit described in the CPU manual. +.P +A +.I user_desc +is considered "empty" if +.I read_exec_only +and +.I seg_not_present +are set to 1 and all of the other fields are 0. +An LDT entry can be cleared by setting it to an "empty" +.I user_desc +or, if +.I func +is 1, by setting both +.I base +and +.I limit +to 0. +.P +A conforming code segment (i.e., one with +.IR contents==3 ) +will be rejected if +.I +func +is 1 or if +.I seg_not_present +is 0. +.P +When +.I func +is 2, +.BR modify_ldt () +will read zeros. +This appears to be a leftover from Linux 2.4. +.SH RETURN VALUE +On success, +.BR modify_ldt () +returns either the actual number of bytes read (for reading) +or 0 (for writing). +On failure, +.BR modify_ldt () +returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I ptr +points outside the address space. +.TP +.B EINVAL +.I ptr +is 0, +or +.I func +is 1 and +.I bytecount +is not equal to the size of the structure +.IR user_desc , +or +.I func +is 1 or 0x11 and the new LDT entry has invalid values. +.TP +.B ENOSYS +.I func +is neither 0, 1, 2, nor 0x11. +.SH STANDARDS +Linux. +.SH NOTES +.BR modify_ldt () +should not be used for thread-local storage, as it slows down context +switches and only supports a limited number of threads. +Threading libraries should use +.BR set_thread_area (2) +or +.BR arch_prctl (2) +instead, except on extremely old kernels that do not support those system +calls. +.P +The normal use for +.BR modify_ldt () +is to run legacy 16-bit or segmented 32-bit code. +Not all kernels allow 16-bit segments to be installed, however. +.P +Even on 64-bit kernels, +.BR modify_ldt () +cannot be used to create a long mode (i.e., 64-bit) code segment. +The undocumented field "lm" in +.I user_desc +is not useful, and, despite its name, +does not result in a long mode segment. +.SH BUGS +On 64-bit kernels before Linux 3.19, +.\" commit e30ab185c490e9a9381385529e0fd32f0a399495 +setting the "lm" bit in +.I user_desc +prevents the descriptor from being considered empty. +Keep in mind that the +"lm" bit does not exist in the 32-bit headers, but these buggy kernels +will still notice the bit even when set in a 32-bit process. +.SH SEE ALSO +.BR arch_prctl (2), +.BR set_thread_area (2), +.BR vm86 (2) diff --git a/man/man2/mount.2 b/man/man2/mount.2 new file mode 100644 index 0000000..95d3a5d --- /dev/null +++ b/man/man2/mount.2 @@ -0,0 +1,971 @@ +.\" Copyright (C) 1993 Rickard E. Faith +.\" and Copyright (C) 1994 Andries E. Brouwer +.\" and Copyright (C) 2002, 2005, 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1996-11-04 by Eric S. Raymond +.\" Modified 2001-10-13 by Michael Kerrisk +.\" Added note on historical behavior of MS_NOSUID +.\" Modified 2002-05-16 by Michael Kerrisk +.\" Extensive changes and additions +.\" Modified 2002-05-27 by aeb +.\" Modified 2002-06-11 by Michael Kerrisk +.\" Enhanced descriptions of MS_MOVE, MS_BIND, and MS_REMOUNT +.\" Modified 2004-06-17 by Michael Kerrisk +.\" 2005-05-18, mtk, Added MNT_EXPIRE, plus a few other tidy-ups. +.\" 2008-10-06, mtk: move umount*() material into separate umount.2 page. +.\" 2008-10-06, mtk: Add discussion of namespaces. +.\" +.TH mount 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mount \- mount filesystem +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int mount(const char *" source ", const char *" target , +.BI " const char *" filesystemtype ", unsigned long " mountflags , +.BI " const void *_Nullable " data ); +.fi +.SH DESCRIPTION +.BR mount () +attaches the filesystem specified by +.I source +(which is often a pathname referring to a device, +but can also be the pathname of a directory or file, +or a dummy string) to the location (a directory or file) +specified by the pathname in +.IR target . +.P +Appropriate privilege (Linux: the +.B CAP_SYS_ADMIN +capability) is required to mount filesystems. +.P +Values for the +.I filesystemtype +argument supported by the kernel are listed in +.I /proc/filesystems +(e.g., "btrfs", "ext4", "jfs", "xfs", "vfat", "fuse", +"tmpfs", "cgroup", "proc", "mqueue", "nfs", "cifs", "iso9660"). +Further types may become available when the appropriate modules +are loaded. +.P +The +.I data +argument is interpreted by the different filesystems. +Typically it is a string of comma-separated options +understood by this filesystem. +See +.BR mount (8) +for details of the options available for each filesystem type. +This argument may be specified as NULL, if there are no options. +.P +A call to +.BR mount () +performs one of a number of general types of operation, +depending on the bits specified in +.IR mountflags . +The choice of which operation to perform is determined by +testing the bits set in +.IR mountflags , +with the tests being conducted in the order listed here: +.IP \[bu] 3 +Remount an existing mount: +.I mountflags +includes +.BR MS_REMOUNT . +.IP \[bu] +Create a bind mount: +.I mountflags +includes +.BR MS_BIND . +.IP \[bu] +Change the propagation type of an existing mount: +.I mountflags +includes one of +.BR MS_SHARED , +.BR MS_PRIVATE , +.BR MS_SLAVE , +or +.BR MS_UNBINDABLE . +.IP \[bu] +Move an existing mount to a new location: +.I mountflags +includes +.BR MS_MOVE . +.IP \[bu] +Create a new mount: +.I mountflags +includes none of the above flags. +.P +Each of these operations is detailed later in this page. +Further flags may be specified in +.I mountflags +to modify the behavior of +.BR mount (), +as described below. +.\" +.SS Additional mount flags +The list below describes the additional flags that can be specified in +.IR mountflags . +Note that some operation types ignore some or all of these flags, +as described later in this page. +.\" +.\" FIXME 2.6.25 Added MS_I_VERSION, which needs to be documented. +.\" commit 7a224228ed79d587ece2304869000aad1b8e97dd +.\" (This is a per-superblock flag) +.\" +.TP +.BR MS_DIRSYNC " (since Linux 2.5.19)" +Make directory changes on this filesystem synchronous. +(This property can be obtained for individual directories +or subtrees using +.BR chattr (1).) +.TP +.BR MS_LAZYTIME " (since Linux 4.0)" +.\" commit 0ae45f63d4ef8d8eeec49c7d8b44a1775fff13e8 +.\" commit fe032c422c5ba562ba9c2d316f55e258e03259c6 +.\" commit a26f49926da938f47561f386be56a83dd37a496d +Reduce on-disk updates of inode timestamps (atime, mtime, ctime) +by maintaining these changes only in memory. +The on-disk timestamps are updated only when: +.RS +.IP \[bu] 3 +the inode needs to be updated for some change unrelated to file timestamps; +.IP \[bu] +the application employs +.BR fsync (2), +.BR syncfs (2), +or +.BR sync (2); +.IP \[bu] +an undeleted inode is evicted from memory; or +.IP \[bu] +more than 24 hours have passed since the inode was written to disk. +.RE +.IP +This mount option significantly reduces writes +needed to update the inode's timestamps, especially mtime and atime. +However, in the event of a system crash, the atime and mtime fields +on disk might be out of date by up to 24 hours. +.IP +Examples of workloads where this option could be of significant benefit +include frequent random writes to preallocated files, +as well as cases where the +.B MS_STRICTATIME +mount option is also enabled. +(The advantage of combining +.B MS_STRICTATIME +and +.B MS_LAZYTIME +is that +.BR stat (2) +will return the correctly updated atime, but the atime updates +will be flushed to disk only in the cases listed above.) +.TP +.B MS_MANDLOCK +Permit mandatory locking on files in this filesystem. +(Mandatory locking must still be enabled on a per-file basis, +as described in +.BR fcntl (2).) +Since Linux 4.5, +.\" commit 95ace75414f312f9a7b93d873f386987b92a5301 +this mount option requires the +.B CAP_SYS_ADMIN +capability and a kernel configured with the +.B CONFIG_MANDATORY_FILE_LOCKING +option. +Mandatory locking has been fully deprecated in Linux 5.15, so +this flag should be considered deprecated. +.TP +.B MS_NOATIME +Do not update access times for (all types of) files on this filesystem. +.TP +.B MS_NODEV +Do not allow access to devices (special files) on this filesystem. +.TP +.B MS_NODIRATIME +Do not update access times for directories on this filesystem. +This flag provides a subset of the functionality provided by +.BR MS_NOATIME ; +that is, +.B MS_NOATIME +implies +.BR MS_NODIRATIME . +.TP +.B MS_NOEXEC +Do not allow programs to be executed from this filesystem. +.\" (Possibly useful for a filesystem that contains non-Linux executables. +.\" Often used as a security feature, e.g., to make sure that restricted +.\" users cannot execute files uploaded using ftp or so.) +.TP +.B MS_NOSUID +Do not honor set-user-ID and set-group-ID bits or file capabilities +when executing programs from this filesystem. +In addition, SELinux domain +transitions require the permission +.IR nosuid_transition , +which in turn needs +also the policy capability +.IR nnp_nosuid_transition . +.\" (This is a security feature to prevent users executing set-user-ID and +.\" set-group-ID programs from removable disk devices.) +.TP +.B MS_RDONLY +Mount filesystem read-only. +.TP +.BR MS_REC " (since Linux 2.4.11)" +Used in conjunction with +.B MS_BIND +to create a recursive bind mount, +and in conjunction with the propagation type flags to recursively change +the propagation type of all of the mounts in a subtree. +See below for further details. +.TP +.BR MS_RELATIME " (since Linux 2.6.20)" +When a file on this filesystem is accessed, +update the file's last access time (atime) only if the current value +of atime is less than or equal to the file's last modification time (mtime) +or last status change time (ctime). +This option is useful for programs, such as +.BR mutt (1), +that need to know when a file has been read since it was last modified. +Since Linux 2.6.30, the kernel defaults to the behavior provided +by this flag (unless +.B MS_NOATIME +was specified), and the +.B MS_STRICTATIME +flag is required to obtain traditional semantics. +In addition, since Linux 2.6.30, +the file's last access time is always updated if it +is more than 1 day old. +.\" Matthew Garrett notes in the patch that added this behavior +.\" that this lets utilities such as tmpreaper (which deletes +.\" files based on last access time) work correctly. +.TP +.BR MS_SILENT " (since Linux 2.6.17)" +Suppress the display of certain +.RI ( printk ()) +warning messages in the kernel log. +This flag supersedes the misnamed and obsolete +.B MS_VERBOSE +flag (available since Linux 2.4.12), which has the same meaning. +.TP +.BR MS_STRICTATIME " (since Linux 2.6.30)" +Always update the last access time (atime) when files on this +filesystem are accessed. +(This was the default behavior before Linux 2.6.30.) +Specifying this flag overrides the effect of setting the +.B MS_NOATIME +and +.B MS_RELATIME +flags. +.TP +.B MS_SYNCHRONOUS +Make writes on this filesystem synchronous (as though +the +.B O_SYNC +flag to +.BR open (2) +was specified for all file opens to this filesystem). +.TP +.BR MS_NOSYMFOLLOW " (since Linux 5.10)" +.\" dab741e0e02bd3c4f5e2e97be74b39df2523fc6e +Do not follow symbolic links when resolving paths. +Symbolic links can still be created, +and +.BR readlink (1), +.BR readlink (2), +.BR realpath (1), +and +.BR realpath (3) +all still work properly. +.P +From Linux 2.4 onward, some of the above flags are +settable on a per-mount basis, +while others apply to the superblock of the mounted filesystem, +meaning that all mounts of the same filesystem share those flags. +(Previously, all of the flags were per-superblock.) +.P +The per-mount-point flags are as follows: +.IP \[bu] 3 +Since Linux 2.4: +.BR MS_NODEV ", " MS_NOEXEC ", and " MS_NOSUID +flags are settable on a per-mount-point basis. +.IP \[bu] +Additionally, since Linux 2.6.16: +.B MS_NOATIME +and +.BR MS_NODIRATIME . +.IP \[bu] +Additionally, since Linux 2.6.20: +.BR MS_RELATIME . +.P +The following flags are per-superblock: +.BR MS_DIRSYNC , +.BR MS_LAZYTIME , +.BR MS_MANDLOCK , +.BR MS_SILENT , +and +.BR MS_SYNCHRONOUS . +.\" And MS_I_VERSION? +The initial settings of these flags are determined on the first +mount of the filesystem, and will be shared by all subsequent mounts +of the same filesystem. +Subsequently, the settings of the flags can be changed +via a remount operation (see below). +Such changes will be visible via all mounts associated +with the filesystem. +.P +Since Linux 2.6.16, +.B MS_RDONLY +can be set or cleared on a per-mount-point basis as well as on +the underlying filesystem superblock. +The mounted filesystem will be writable only if neither the filesystem +nor the mountpoint are flagged as read-only. +.\" +.SS Remounting an existing mount +An existing mount may be remounted by specifying +.B MS_REMOUNT +in +.IR mountflags . +This allows you to change the +.I mountflags +and +.I data +of an existing mount without having to unmount and remount the filesystem. +.I target +should be the same value specified in the initial +.BR mount () +call. +.P +The +.I source +and +.I filesystemtype +arguments are ignored. +.P +The +.I mountflags +and +.I data +arguments should match the values used in the original +.BR mount () +call, except for those parameters that are being deliberately changed. +.P +The following +.I mountflags +can be changed: +.BR MS_LAZYTIME , +.\" FIXME +.\" MS_LAZYTIME seems to be available only on a few filesystems, +.\" and on ext4, it seems (from experiment that this flag +.\" can only be enabled (but not disabled) on a remount. +.\" The following code in ext4_remount() (kernel 4.17) seems to +.\" confirm this: +.\" +.\" if (*flags & SB_LAZYTIME) +.\" sb->s_flags |= SB_LAZYTIME; +.BR MS_MANDLOCK , +.BR MS_NOATIME , +.BR MS_NODEV , +.BR MS_NODIRATIME , +.BR MS_NOEXEC , +.BR MS_NOSUID , +.BR MS_RELATIME , +.BR MS_RDONLY , +.B MS_STRICTATIME +(whose effect is to clear the +.B MS_NOATIME +and +.B MS_RELATIME +flags), +and +.BR MS_SYNCHRONOUS . +Attempts to change the setting of the +.\" See the definition of MS_RMT_MASK in include/uapi/linux/fs.h, +.\" which excludes MS_DIRSYNC and MS_SILENT, although SB_DIRSYNC +.\" and SB_SILENT are split out as per-superblock flags in do_mount() +.\" (Linux 4.17 source code) +.B MS_DIRSYNC +and +.B MS_SILENT +flags during a remount are silently ignored. +Note that changes to per-superblock flags are visible via +all mounts of the associated filesystem +(because the per-superblock flags are shared by all mounts). +.P +Since Linux 3.17, +.\" commit ffbc6f0ead47fa5a1dc9642b0331cb75c20a640e +if none of +.BR MS_NOATIME , +.BR MS_NODIRATIME , +.BR MS_RELATIME , +or +.B MS_STRICTATIME +is specified in +.IR mountflags , +then the remount operation preserves the existing values of these flags +(rather than defaulting to +.BR MS_RELATIME ). +.P +Since Linux 2.6.26, the +.B MS_REMOUNT +flag can be used with +.B MS_BIND +to modify only the per-mount-point flags. +.\" See https://lwn.net/Articles/281157/ +This is particularly useful for setting or clearing the "read-only" +flag on a mount without changing the underlying filesystem. +Specifying +.I mountflags +as: +.P +.in +4n +.EX +MS_REMOUNT | MS_BIND | MS_RDONLY +.EE +.in +.P +will make access through this mountpoint read-only, without affecting +other mounts. +.\" +.SS Creating a bind mount +If +.I mountflags +includes +.B MS_BIND +(available since Linux 2.4), +.\" since Linux 2.4.0-test9 +then perform a bind mount. +A bind mount makes a file or a directory subtree visible at +another point within the single directory hierarchy. +Bind mounts may cross filesystem boundaries and span +.BR chroot (2) +jails. +.P +The +.I filesystemtype +and +.I data +arguments are ignored. +.P +The remaining bits (other than +.BR MS_REC , +described below) in the +.I mountflags +argument are also ignored. +(The bind mount has the same mount options as +the underlying mount.) +However, see the discussion of remounting above, +for a method of making an existing bind mount read-only. +.P +By default, when a directory is bind mounted, +only that directory is mounted; +if there are any submounts under the directory tree, +they are not bind mounted. +If the +.B MS_REC +flag is also specified, then a recursive bind mount operation is performed: +all submounts under the +.I source +subtree (other than unbindable mounts) +are also bind mounted at the corresponding location in the +.I target +subtree. +.\" +.SS Changing the propagation type of an existing mount +If +.I mountflags +includes one of +.BR MS_SHARED , +.BR MS_PRIVATE , +.BR MS_SLAVE , +or +.B MS_UNBINDABLE +(all available since Linux 2.6.15), +then the propagation type of an existing mount is changed. +If more than one of these flags is specified, an error results. +.P +The only other flags that can be specified while changing +the propagation type are +.B MS_REC +(described below) and +.B MS_SILENT +(which is ignored). +.P +The +.IR source , +.IR filesystemtype , +and +.I data +arguments are ignored. +.P +The meanings of the propagation type flags are as follows: +.TP +.B MS_SHARED +Make this mount shared. +Mount and unmount events immediately under this mount will propagate +to the other mounts that are members of this mount's peer group. +Propagation here means that the same mount or unmount will automatically +occur under all of the other mounts in the peer group. +Conversely, mount and unmount events that take place under +peer mounts will propagate to this mount. +.TP +.B MS_PRIVATE +Make this mount private. +Mount and unmount events do not propagate into or out of this mount. +.TP +.B MS_SLAVE +If this is a shared mount that is a member of a peer group +that contains other members, convert it to a slave mount. +If this is a shared mount that is a member of a peer group +that contains no other members, convert it to a private mount. +Otherwise, the propagation type of the mount is left unchanged. +.IP +When a mount is a slave, +mount and unmount events propagate into this mount from +the (master) shared peer group of which it was formerly a member. +Mount and unmount events under this mount do not propagate to any peer. +.IP +A mount can be the slave of another peer group +while at the same time sharing mount and unmount events +with a peer group of which it is a member. +.TP +.B MS_UNBINDABLE +Make this mount unbindable. +This is like a private mount, +and in addition this mount can't be bind mounted. +When a recursive bind mount +.RB ( mount () +with the +.B MS_BIND +and +.B MS_REC +flags) is performed on a directory subtree, +any unbindable mounts within the subtree are automatically pruned +(i.e., not replicated) +when replicating that subtree to produce the target subtree. +.P +By default, changing the propagation type affects only the +.I target +mount. +If the +.B MS_REC +flag is also specified in +.IR mountflags , +then the propagation type of all mounts under +.I target +is also changed. +.P +For further details regarding mount propagation types +(including the default propagation type assigned to new mounts), see +.BR mount_namespaces (7). +.\" +.SS Moving a mount +If +.I mountflags +contains the flag +.B MS_MOVE +(available since Linux 2.4.18), +then move a subtree: +.I source +specifies an existing mount and +.I target +specifies the new location to which that mount is to be relocated. +The move is atomic: at no point is the subtree unmounted. +.P +The remaining bits in the +.I mountflags +argument are ignored, as are the +.I filesystemtype +and +.I data +arguments. +.\" +.SS Creating a new mount +If none of +.BR MS_REMOUNT , +.BR MS_BIND , +.BR MS_MOVE , +.BR MS_SHARED , +.BR MS_PRIVATE , +.BR MS_SLAVE , +or +.B MS_UNBINDABLE +is specified in +.IR mountflags , +then +.BR mount () +performs its default action: creating a new mount. +.I source +specifies the source for the new mount, and +.I target +specifies the directory at which to create the mount point. +.P +The +.I filesystemtype +and +.I data +arguments are employed, and further bits may be specified in +.I mountflags +to modify the behavior of the call. +.\" +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +The error values given below result from filesystem type independent +errors. +Each filesystem type may have its own special errors and its +own special behavior. +See the Linux kernel source code for details. +.TP +.B EACCES +A component of a path was not searchable. +(See also +.BR path_resolution (7).) +.TP +.B EACCES +Mounting a read-only filesystem was attempted without giving the +.B MS_RDONLY +flag. +.IP +The filesystem may be read-only for various reasons, including: +it resides on a read-only optical disk; +it is resides on a device with a physical switch that has been set to +mark the device read-only; +the filesystem implementation was compiled with read-only support; +or errors were detected when initially mounting the filesystem, +so that it was marked read-only +and can't be remounted as read-write (until the errors are fixed). +.IP +Some filesystems instead return the error +.B EROFS +on an attempt to mount a read-only filesystem. +.TP +.B EACCES +The block device +.I source +is located on a filesystem mounted with the +.B MS_NODEV +option. +.\" mtk: Probably: write permission is required for MS_BIND, with +.\" the error EPERM if not present; CAP_DAC_OVERRIDE is required. +.TP +.B EBUSY +An attempt was made to stack a new mount directly on +top of an existing mount point that was created in this +mount namespace with the same +.I source +and +.IR target . +.TP +.B EBUSY +.I source +cannot be remounted read-only, +because it still holds files open for writing. +.TP +.B EFAULT +One of the pointer arguments points outside the user address space. +.TP +.B EINVAL +.I source +had an invalid superblock. +.TP +.B EINVAL +A remount operation +.RB ( MS_REMOUNT ) +was attempted, but +.I source +was not already mounted on +.IR target . +.TP +.B EINVAL +A move operation +.RB ( MS_MOVE ) +was attempted, but the mount tree under +.I source +includes unbindable mounts and +.I target +is a mount that has propagation type +.BR MS_SHARED . +.TP +.B EINVAL +A move operation +.RB ( MS_MOVE ) +was attempted, but the parent mount of +.I source +mount has propagation type +.BR MS_SHARED . +.TP +.B EINVAL +A move operation +.RB ( MS_MOVE ) +was attempted, but +.I source +was not a mount, or was \[aq]/\[aq]. +.TP +.B EINVAL +A bind operation +.RB ( MS_BIND ) +was requested where +.I source +referred a mount namespace magic link (i.e., a +.IR /proc/ pid /ns/mnt +magic link or a bind mount to such a link) +and the propagation type of the parent mount of +.I target +was +.BR MS_SHARED , +.\" See commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e +but propagation of the requested bind mount could lead to a circular +dependency that might prevent the mount namespace from ever being freed. +.TP +.B EINVAL +.I mountflags +includes more than one of +.BR MS_SHARED , +.BR MS_PRIVATE , +.BR MS_SLAVE , +or +.BR MS_UNBINDABLE . +.TP +.B EINVAL +.I mountflags +includes +.BR MS_SHARED , +.BR MS_PRIVATE , +.BR MS_SLAVE , +or +.B MS_UNBINDABLE +and also includes a flag other than +.B MS_REC +or +.BR MS_SILENT . +.TP +.B EINVAL +An attempt was made to bind mount an unbindable mount. +.TP +.B EINVAL +In an unprivileged mount namespace +(i.e., a mount namespace owned by a user namespace +that was created by an unprivileged user), +a bind mount operation +.RB ( MS_BIND ) +was attempted without specifying +.RB ( MS_REC ), +which would have revealed the filesystem tree underneath one of +the submounts of the directory being bound. +.TP +.B ELOOP +Too many links encountered during pathname resolution. +.TP +.B ELOOP +A move operation was attempted, and +.I target +is a descendant of +.IR source . +.TP +.B EMFILE +(In case no block device is required:) +Table of dummy devices is full. +.TP +.B ENAMETOOLONG +A pathname was longer than +.BR MAXPATHLEN . +.TP +.B ENODEV +.I filesystemtype +not configured in the kernel. +.TP +.B ENOENT +A pathname was empty or had a nonexistent component. +.TP +.B ENOMEM +The kernel could not allocate a free page to copy filenames or data into. +.TP +.B ENOTBLK +.I source +is not a block device (and a device was required). +.TP +.B ENOTDIR +.IR target , +or a prefix of +.IR source , +is not a directory. +.TP +.B ENXIO +The major number of the block device +.I source +is out of range. +.TP +.B EPERM +The caller does not have the required privileges. +.TP +.B EPERM +An attempt was made to modify +.RB ( MS_REMOUNT ) +the +.BR MS_RDONLY , +.BR MS_NOSUID , +or +.B MS_NOEXEC +flag, or one of the "atime" flags +.RB ( MS_NOATIME , +.BR MS_NODIRATIME , +.BR MS_RELATIME ) +of an existing mount, but the mount is locked; see +.BR mount_namespaces (7). +.TP +.B EROFS +Mounting a read-only filesystem was attempted without giving the +.B MS_RDONLY +flag. +See +.BR EACCES , +above. +.\" +.SH STANDARDS +Linux. +.SH HISTORY +The definitions of +.BR MS_DIRSYNC , +.BR MS_MOVE , +.BR MS_PRIVATE , +.BR MS_REC , +.BR MS_RELATIME , +.BR MS_SHARED , +.BR MS_SLAVE , +.BR MS_STRICTATIME , +and +.B MS_UNBINDABLE +were added to glibc headers in glibc 2.12. +.P +Since Linux 2.4 a single filesystem can be mounted at +multiple mount points, and multiple mounts can be stacked +on the same mount point. +.\" Multiple mounts on same mount point: since Linux 2.3.99pre7. +.P +The +.I mountflags +argument may have the magic number 0xC0ED (\fBMS_MGC_VAL\fP) +in the top 16 bits. +(All of the other flags discussed in DESCRIPTION +occupy the low order 16 bits of +.IR mountflags .) +Specifying +.B MS_MGC_VAL +was required before Linux 2.4, +but since Linux 2.4 is no longer required and is ignored if specified. +.P +The original +.B MS_SYNC +flag was renamed +.B MS_SYNCHRONOUS +in 1.1.69 +when a different +.B MS_SYNC +was added to \fI\fP. +.P +Before Linux 2.4 an attempt to execute a set-user-ID or set-group-ID program +on a filesystem mounted with +.B MS_NOSUID +would fail with +.BR EPERM . +Since Linux 2.4 the set-user-ID and set-group-ID bits are +just silently ignored in this case. +.\" The change is in patch-2.4.0-prerelease. +.\" +.SH NOTES +.SS Mount namespaces +Starting with Linux 2.4.19, Linux provides mount namespaces. +A mount namespace is the set of filesystem mounts that +are visible to a process. +Mount namespaces can be (and usually are) +shared between multiple processes, +and changes to the namespace (i.e., mounts and unmounts) by one process +are visible to all other processes sharing the same namespace. +(The pre-2.4.19 Linux situation can be considered as one in which +a single namespace was shared by every process on the system.) +.P +A child process created by +.BR fork (2) +shares its parent's mount namespace; +the mount namespace is preserved across an +.BR execve (2). +.P +A process can obtain a private mount namespace if: +it was created using the +.BR clone (2) +.B CLONE_NEWNS +flag, +in which case its new namespace is initialized to be a +.I copy +of the namespace of the process that called +.BR clone (2); +or it calls +.BR unshare (2) +with the +.B CLONE_NEWNS +flag, +which causes the caller's mount namespace to obtain a private copy +of the namespace that it was previously sharing with other processes, +so that future mounts and unmounts by the caller are invisible +to other processes (except child processes that the caller +subsequently creates) and vice versa. +.P +For further details on mount namespaces, see +.BR mount_namespaces (7). +.\" +.SS Parental relationship between mounts +Each mount has a parent mount. +The overall parental relationship of all mounts defines +the single directory hierarchy seen by the processes within a mount namespace. +.P +The parent of a new mount is defined when the mount is created. +In the usual case, +the parent of a new mount is the mount of the filesystem +containing the directory or file at which the new mount is attached. +In the case where a new mount is stacked on top of an existing mount, +the parent of the new mount is the previous mount that was stacked +at that location. +.P +The parental relationship between mounts can be discovered via the +.IR /proc/ pid /mountinfo +file (see below). +.\" +.SS \fI/proc/\fPpid\fI/mounts\fP and \fI/proc/\fPpid\fI/mountinfo\fP +The Linux-specific +.IR /proc/ pid /mounts +file exposes the list of mounts in the mount +namespace of the process with the specified ID. +The +.IR /proc/ pid /mountinfo +file exposes even more information about mounts, +including the propagation type and mount ID information that makes it +possible to discover the parental relationship between mounts. +See +.BR proc (5) +and +.BR mount_namespaces (7) +for details of this file. +.SH SEE ALSO +.BR mountpoint (1), +.BR chroot (2), +.BR ioctl_iflags (2), +.BR mount_setattr (2), +.BR pivot_root (2), +.BR umount (2), +.BR mount_namespaces (7), +.BR path_resolution (7), +.BR findmnt (8), +.BR lsblk (8), +.BR mount (8), +.BR umount (8) diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2 new file mode 100644 index 0000000..0ea655f --- /dev/null +++ b/man/man2/mount_setattr.2 @@ -0,0 +1,1067 @@ +.\" Copyright (c) 2021 by Christian Brauner +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mount_setattr 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mount_setattr \- change properties of a mount or mount tree +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " AT_* " constants */" +.BR "#include " " /* Definition of " MOUNT_ATTR_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" pathname , +.BI " unsigned int " flags ", struct mount_attr *" attr \ +", size_t " size ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR mount_setattr (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR mount_setattr () +system call changes the mount properties of a mount or an entire mount tree. +If +.I pathname +is a relative pathname, +then it is interpreted relative to +the directory referred to by the file descriptor +.IR dirfd . +If +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to +the current working directory of the calling process. +If +.I pathname +is the empty string and +.B AT_EMPTY_PATH +is specified in +.IR flags , +then the mount properties of the mount identified by +.I dirfd +are changed. +(See +.BR openat (2) +for an explanation of why the +.I dirfd +argument is useful.) +.P +The +.BR mount_setattr () +system call uses an extensible structure +.RI ( "struct mount_attr" ) +to allow for future extensions. +Any non-flag extensions to +.BR mount_setattr () +will be implemented as new fields appended to the this structure, +with a zero value in a new field resulting in the kernel behaving +as though that extension field was not present. +Therefore, +the caller +.I must +zero-fill this structure on initialization. +See the "Extensibility" subsection under +.B NOTES +for more details. +.P +The +.I size +argument should usually be specified as +.IR "sizeof(struct mount_attr)" . +However, if the caller is using a kernel that supports an extended +.IR "struct mount_attr" , +but the caller does not intend to make use of these features, +it is possible to pass the size of an earlier +version of the structure together with the extended structure. +This allows the kernel to not copy later parts of the structure +that aren't used anyway. +With each extension that changes the size of +.IR "struct mount_attr" , +the kernel will expose a definition of the form +.BI MOUNT_ATTR_SIZE_VER number\c +\&. +For example, the macro for the size of the initial version of +.I struct mount_attr +is +.BR MOUNT_ATTR_SIZE_VER0 . +.P +The +.I flags +argument can be used to alter the pathname resolution behavior. +The supported values are: +.TP +.B AT_EMPTY_PATH +If +.I pathname +is the empty string, +change the mount properties on +.I dirfd +itself. +.TP +.B AT_RECURSIVE +Change the mount properties of the entire mount tree. +.TP +.B AT_SYMLINK_NOFOLLOW +Don't follow trailing symbolic links. +.TP +.B AT_NO_AUTOMOUNT +Don't trigger automounts. +.P +The +.I attr +argument of +.BR mount_setattr () +is a structure of the following form: +.P +.in +4n +.EX +struct mount_attr { + __u64 attr_set; /* Mount properties to set */ + __u64 attr_clr; /* Mount properties to clear */ + __u64 propagation; /* Mount propagation type */ + __u64 userns_fd; /* User namespace file descriptor */ +}; +.EE +.in +.P +The +.I attr_set +and +.I attr_clr +members are used to specify the mount properties that +are supposed to be set or cleared for a mount or mount tree. +Flags set in +.I attr_set +enable a property on a mount or mount tree, +and flags set in +.I attr_clr +remove a property from a mount or mount tree. +.P +When changing mount properties, +the kernel will first clear the flags specified +in the +.I attr_clr +field, +and then set the flags specified in the +.I attr_set +field. +For example, these settings: +.P +.in +4n +.EX +struct mount_attr attr = { + .attr_clr = MOUNT_ATTR_NOEXEC | MOUNT_ATTR_NODEV, + .attr_set = MOUNT_ATTR_RDONLY | MOUNT_ATTR_NOSUID, +}; +.EE +.in +.P +are equivalent to the following steps: +.P +.in +4n +.EX +unsigned int current_mnt_flags = mnt\->mnt_flags; +\& +/* + * Clear all flags set in .attr_clr, + * clearing MOUNT_ATTR_NOEXEC and MOUNT_ATTR_NODEV. + */ +current_mnt_flags &= \(tiattr\->attr_clr; +\& +/* + * Now set all flags set in .attr_set, + * applying MOUNT_ATTR_RDONLY and MOUNT_ATTR_NOSUID. + */ +current_mnt_flags |= attr\->attr_set; +\& +mnt\->mnt_flags = current_mnt_flags; +.EE +.in +.P +As a result of this change, the mount or mount tree (a) is read-only; +(b) blocks the execution of set-user-ID and set-group-ID programs; +(c) allows execution of programs; and (d) allows access to devices. +.P +Multiple changes with the same set of flags requested +in +.I attr_clr +and +.I attr_set +are guaranteed to be idempotent after the changes have been applied. +.P +The following mount attributes can be specified in the +.I attr_set +or +.I attr_clr +fields: +.TP +.B MOUNT_ATTR_RDONLY +If set in +.IR attr_set , +makes the mount read-only. +If set in +.IR attr_clr , +removes the read-only setting if set on the mount. +.TP +.B MOUNT_ATTR_NOSUID +If set in +.IR attr_set , +causes the mount not to honor the set-user-ID and set-group-ID mode bits and +file capabilities when executing programs. +If set in +.IR attr_clr , +clears the set-user-ID, set-group-ID, +and file capability restriction if set on this mount. +.TP +.B MOUNT_ATTR_NODEV +If set in +.IR attr_set , +prevents access to devices on this mount. +If set in +.IR attr_clr , +removes the restriction that prevented accessing devices on this mount. +.TP +.B MOUNT_ATTR_NOEXEC +If set in +.IR attr_set , +prevents executing programs on this mount. +If set in +.IR attr_clr , +removes the restriction that prevented executing programs on this mount. +.TP +.B MOUNT_ATTR_NOSYMFOLLOW +If set in +.IR attr_set , +prevents following symbolic links on this mount. +If set in +.IR attr_clr , +removes the restriction that prevented following symbolic links on this mount. +.TP +.B MOUNT_ATTR_NODIRATIME +If set in +.IR attr_set , +prevents updating access time for directories on this mount. +If set in +.IR attr_clr , +removes the restriction that prevented updating access time for directories. +Note that +.B MOUNT_ATTR_NODIRATIME +can be combined with other access-time settings +and is implied by the noatime setting. +All other access-time settings are mutually exclusive. +.TP +.BR MOUNT_ATTR__ATIME " - changing access-time settings" +The access-time values listed below are an enumeration that +includes the value zero, expressed in the bits defined by the mask +.BR MOUNT_ATTR__ATIME . +Even though these bits are an enumeration +(in contrast to the other mount flags such as +.BR MOUNT_ATTR_NOEXEC ), +they are nonetheless passed in +.I attr_set +and +.I attr_clr +for consistency with +.BR fsmount (2), +which introduced this behavior. +.IP +Note that, +since the access-time values are an enumeration rather than bit values, +a caller wanting to transition to a different access-time setting +cannot simply specify the access-time setting in +.IR attr_set , +but must also include +.B MOUNT_ATTR__ATIME +in the +.I attr_clr +field. +The kernel will verify that +.B MOUNT_ATTR__ATIME +isn't partially set in +.I attr_clr +(i.e., either all bits in the +.B MOUNT_ATTR__ATIME +bit field are either set or clear), and that +.I attr_set +doesn't have any access-time bits set if +.B MOUNT_ATTR__ATIME +isn't set in +.IR attr_clr . +.RS +.TP +.B MOUNT_ATTR_RELATIME +When a file is accessed via this mount, +update the file's last access time (atime) +only if the current value of atime is less than or equal to +the file's last modification time (mtime) or last status change time (ctime). +.IP +To enable this access-time setting on a mount or mount tree, +.B MOUNT_ATTR_RELATIME +must be set in +.I attr_set +and +.B MOUNT_ATTR__ATIME +must be set in the +.I attr_clr +field. +.TP +.B MOUNT_ATTR_NOATIME +Do not update access times for (all types of) files on this mount. +.IP +To enable this access-time setting on a mount or mount tree, +.B MOUNT_ATTR_NOATIME +must be set in +.I attr_set +and +.B MOUNT_ATTR__ATIME +must be set in the +.I attr_clr +field. +.TP +.B MOUNT_ATTR_STRICTATIME +Always update the last access time (atime) +when files are accessed on this mount. +.IP +To enable this access-time setting on a mount or mount tree, +.B MOUNT_ATTR_STRICTATIME +must be set in +.I attr_set +and +.B MOUNT_ATTR__ATIME +must be set in the +.I attr_clr +field. +.RE +.TP +.B MOUNT_ATTR_IDMAP +If set in +.IR attr_set , +creates an ID-mapped mount. +The ID mapping is taken from the user namespace specified in +.I userns_fd +and attached to the mount. +.IP +Since it is not supported to +change the ID mapping of a mount after it has been ID mapped, +it is invalid to specify +.B MOUNT_ATTR_IDMAP +in +.IR attr_clr . +.IP +For further details, see the subsection "ID-mapped mounts" under NOTES. +.P +The +.I propagation +field is used to specify the propagation type of the mount or mount tree. +This field either has the value zero, +meaning leave the propagation type unchanged, or it has one of +the following values: +.TP +.B MS_PRIVATE +Turn all mounts into private mounts. +.TP +.B MS_SHARED +Turn all mounts into shared mounts. +.TP +.B MS_SLAVE +Turn all mounts into dependent mounts. +.TP +.B MS_UNBINDABLE +Turn all mounts into unbindable mounts. +.P +For further details on the above propagation types, see +.BR mount_namespaces (7). +.SH RETURN VALUE +On success, +.BR mount_setattr () +returns zero. +On error, +\-1 is returned and +.I errno +is set to indicate the cause of the error. +.SH ERRORS +.TP +.B EBADF +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EBADF +.I userns_fd +is not a valid file descriptor. +.TP +.B EBUSY +The caller tried to change the mount to +.BR MOUNT_ATTR_RDONLY , +but the mount still holds files open for writing. +.TP +.B EBUSY +The caller tried to create an ID-mapped mount raising +.B MOUNT_ATTR_IDMAP +and specifying +.I userns_fd +but the mount still holds files open for writing. +.TP +.B EINVAL +The pathname specified via the +.I dirfd +and +.I pathname +arguments to +.BR mount_setattr () +isn't a mount point. +.TP +.B EINVAL +An unsupported value was set in +.IR flags . +.TP +.B EINVAL +An unsupported value was specified in the +.I attr_set +field of +.IR mount_attr . +.TP +.B EINVAL +An unsupported value was specified in the +.I attr_clr +field of +.IR mount_attr . +.TP +.B EINVAL +An unsupported value was specified in the +.I propagation +field of +.IR mount_attr . +.TP +.B EINVAL +More than one of +.BR MS_SHARED , +.BR MS_SLAVE , +.BR MS_PRIVATE , +or +.B MS_UNBINDABLE +was set in the +.I propagation +field of +.IR mount_attr . +.TP +.B EINVAL +An access-time setting was specified in the +.I attr_set +field without +.B MOUNT_ATTR__ATIME +being set in the +.I attr_clr +field. +.TP +.B EINVAL +.B MOUNT_ATTR_IDMAP +was specified in +.IR attr_clr . +.TP +.B EINVAL +A file descriptor value was specified in +.I userns_fd +which exceeds +.BR INT_MAX . +.TP +.B EINVAL +A valid file descriptor value was specified in +.IR userns_fd , +but the file descriptor did not refer to a user namespace. +.TP +.B EINVAL +The underlying filesystem does not support ID-mapped mounts. +.TP +.B EINVAL +The mount that is to be ID mapped is not a detached mount; +that is, the mount has not previously been visible in a mount namespace. +.TP +.B EINVAL +A partial access-time setting was specified in +.I attr_clr +instead of +.B MOUNT_ATTR__ATIME +being set. +.TP +.B EINVAL +The mount is located outside the caller's mount namespace. +.TP +.B EINVAL +The underlying filesystem has been mounted in a mount namespace that is +owned by a noninitial user namespace +.TP +.B ENOENT +A pathname was empty or had a nonexistent component. +.TP +.B ENOMEM +When changing mount propagation to +.BR MS_SHARED , +a new peer group ID needs to be allocated for all mounts without a peer group +ID set. +This allocation failed because there was not +enough memory to allocate the relevant internal structures. +.TP +.B ENOSPC +When changing mount propagation to +.BR MS_SHARED , +a new peer group ID needs to be allocated for all mounts without a peer group +ID set. +This allocation failed because +the kernel has run out of IDs. +.\" Christian Brauner: i.e. someone has somehow managed to +.\" allocate so many peer groups and managed to keep the kernel running +.\" (???) that the ida has ran out of ids +.\" Note that technically further error codes are possible that are +.\" specific to the ID allocation implementation used. +.TP +.B EPERM +One of the mounts had at least one of +.BR MOUNT_ATTR_NOATIME , +.BR MOUNT_ATTR_NODEV , +.BR MOUNT_ATTR_NODIRATIME , +.BR MOUNT_ATTR_NOEXEC , +.BR MOUNT_ATTR_NOSUID , +or +.B MOUNT_ATTR_RDONLY +set and the flag is locked. +Mount attributes become locked on a mount if: +.RS +.IP \[bu] 3 +A new mount or mount tree is created causing mount propagation across user +namespaces +(i.e., propagation to a mount namespace owned by a different user namespace). +The kernel will lock the aforementioned flags to prevent these sensitive +properties from being altered. +.IP \[bu] +A new mount and user namespace pair is created. +This happens for example when specifying +.B CLONE_NEWUSER | CLONE_NEWNS +in +.BR unshare (2), +.BR clone (2), +or +.BR clone3 (2). +The aforementioned flags become locked in the new mount namespace +to prevent sensitive mount properties from being altered. +Since the newly created mount namespace will be owned by the +newly created user namespace, +a calling process that is privileged in the new +user namespace would\[em]in the absence of such locking\[em]be +able to alter sensitive mount properties (e.g., to remount a mount +that was marked read-only as read-write in the new mount namespace). +.RE +.TP +.B EPERM +A valid file descriptor value was specified in +.IR userns_fd , +but the file descriptor refers to the initial user namespace. +.TP +.B EPERM +An attempt was made to add an ID mapping to a mount that is already ID mapped. +.TP +.B EPERM +The caller does not have +.B CAP_SYS_ADMIN +in the initial user namespace. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.12. +.\" commit 7d6beb71da3cc033649d641e1e608713b8220290 +.\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd +.\" commit 9caccd41541a6f7d6279928d9f971f6642c361af +.SH NOTES +.SS ID-mapped mounts +Creating an ID-mapped mount makes it possible to +change the ownership of all files located under a mount. +Thus, ID-mapped mounts make it possible to +change ownership in a temporary and localized way. +It is a localized change because the ownership changes are +visible only via a specific mount. +All other users and locations where the filesystem is exposed are unaffected. +It is a temporary change because +the ownership changes are tied to the lifetime of the mount. +.P +Whenever callers interact with the filesystem through an ID-mapped mount, +the ID mapping of the mount will be applied to +user and group IDs associated with filesystem objects. +This encompasses the user and group IDs associated with inodes +and also the following +.BR xattr (7) +keys: +.IP \[bu] 3 +.IR security.capability , +whenever filesystem capabilities +are stored or returned in the +.B VFS_CAP_REVISION_3 +format, +which stores a root user ID alongside the capabilities +(see +.BR capabilities (7)). +.IP \[bu] +.I system.posix_acl_access +and +.IR system.posix_acl_default , +whenever user IDs or group IDs are stored in +.B ACL_USER +or +.B ACL_GROUP +entries. +.P +The following conditions must be met in order to create an ID-mapped mount: +.IP \[bu] 3 +The caller must have the +.B CAP_SYS_ADMIN +capability in the user namespace the filesystem was mounted in. +.\" commit bd303368b776eead1c29e6cdda82bde7128b82a7 +.\" Christian Brauner +.\" Note, currently no filesystems mountable in non-initial user namespaces +.\" support ID-mapped mounts. +.IP \[bu] +The underlying filesystem must support ID-mapped mounts. +Currently, the following filesystems support ID-mapped mounts: +.\" fs_flags = FS_ALLOW_IDMAP in kernel sources +.RS +.IP \[bu] 3 +.PD 0 +.BR xfs (5) +(since Linux 5.12) +.IP \[bu] +.BR ext4 (5) +(since Linux 5.12) +.IP \[bu] +.B FAT +(since Linux 5.12) +.IP \[bu] +.BR btrfs (5) +(since Linux 5.15) +.\" commit 5b9b26f5d0b88b74001dcfe4ab8a8f2f4e744112 +.IP \[bu] +.B ntfs3 +(since Linux 5.15) +.\" commit 82cae269cfa953032fbb8980a7d554d60fb00b17 +.IP \[bu] +.B f2fs +(since Linux 5.18) +.\" commit 984fc4e76d63345499f01c0c198a4b44860cf027 +.IP \[bu] +.B erofs +(since Linux 5.19) +.\" commit 6c459b78d4793afbba6d864c466cc5cd2932459d +.IP \[bu] +.B overlayfs +(ID-mapped lower and upper layers supported since Linux 5.19) +.IP \[bu] +.B squashfs +(since Linux 6.2) +.IP \[bu] +.B tmpfs +(since Linux 6.3) +.IP \[bu] +.B cephfs +(since Linux 6.7) +.IP \[bu] +.B hugetlbfs +(since Linux 6.9) +.PD +.RE +.IP \[bu] +The mount must not already be ID-mapped. +This also implies that the ID mapping of a mount cannot be altered. +.IP \[bu] +The mount must not have any writers. +.\" commit 1bbcd277a53e08d619ffeec56c5c9287f2bf42f +.IP \[bu] +The mount must be a detached mount; +that is, +it must have been created by calling +.BR open_tree (2) +with the +.B OPEN_TREE_CLONE +flag and it must not already have been visible in a mount namespace. +(To put things another way: +the mount must not have been attached to the filesystem hierarchy +with a system call such as +.BR move_mount (2).) +.P +ID mappings can be created for user IDs, group IDs, and project IDs. +An ID mapping is essentially a mapping of a range of user or group IDs into +another or the same range of user or group IDs. +ID mappings are written to map files as three numbers +separated by white space. +The first two numbers specify the starting user or group ID +in each of the two user namespaces. +The third number specifies the range of the ID mapping. +For example, +a mapping for user IDs such as "1000\ 1001\ 1" would indicate that +user ID 1000 in the caller's user namespace is mapped to +user ID 1001 in its ancestor user namespace. +Since the map range is 1, +only user ID 1000 is mapped. +.P +It is possible to specify up to 340 ID mappings for each ID mapping type. +If any user IDs or group IDs are not mapped, +all files owned by that unmapped user or group ID will appear as +being owned by the overflow user ID or overflow group ID respectively. +.P +Further details on setting up ID mappings can be found in +.BR user_namespaces (7). +.P +In the common case, the user namespace passed in +.I userns_fd +(together with +.B MOUNT_ATTR_IDMAP +in +.IR attr_set ) +to create an ID-mapped mount will be the user namespace of a container. +In other scenarios it will be a dedicated user namespace associated with +a user's login session as is the case for portable home directories in +.BR systemd-homed.service (8)). +It is also perfectly fine to create a dedicated user namespace +for the sake of ID mapping a mount. +.P +ID-mapped mounts can be useful in the following +and a variety of other scenarios: +.IP \[bu] 3 +Sharing files or filesystems +between multiple users or multiple machines, +especially in complex scenarios. +For example, +ID-mapped mounts are used to implement portable home directories in +.BR systemd-homed.service (8), +where they allow users to move their home directory +to an external storage device +and use it on multiple computers +where they are assigned different user IDs and group IDs. +This effectively makes it possible to +assign random user IDs and group IDs at login time. +.IP \[bu] +Sharing files or filesystems +from the host with unprivileged containers. +This allows a user to avoid having to change ownership permanently through +.BR chown (2). +.IP \[bu] +ID mapping a container's root filesystem. +Users don't need to change ownership permanently through +.BR chown (2). +Especially for large root filesystems, using +.BR chown (2) +can be prohibitively expensive. +.IP \[bu] +Sharing files or filesystems +between containers with non-overlapping ID mappings. +.IP \[bu] +Implementing discretionary access (DAC) permission checking +for filesystems lacking a concept of ownership. +.IP \[bu] +Efficiently changing ownership on a per-mount basis. +In contrast to +.BR chown (2), +changing ownership of large sets of files is instantaneous with +ID-mapped mounts. +This is especially useful when ownership of +an entire root filesystem of a virtual machine or container +is to be changed as mentioned above. +With ID-mapped mounts, +a single +.BR mount_setattr () +system call will be sufficient to change the ownership of all files. +.IP \[bu] +Taking the current ownership into account. +ID mappings specify precisely +what a user or group ID is supposed to be mapped to. +This contrasts with the +.BR chown (2) +system call which cannot by itself +take the current ownership of the files it changes into account. +It simply changes the ownership to the specified user ID and group ID. +.IP \[bu] +Locally and temporarily restricted ownership changes. +ID-mapped mounts make it possible to change ownership locally, +restricting the ownership changes to specific mounts, +and temporarily as the ownership changes only apply as long as the mount exists. +By contrast, +changing ownership via the +.BR chown (2) +system call changes the ownership globally and permanently. +.\" +.SS Extensibility +In order to allow for future extensibility, +.BR mount_setattr () +requires the user-space application to specify the size of the +.I mount_attr +structure that it is passing. +By providing this information, it is possible for +.BR mount_setattr () +to provide both forwards- and backwards-compatibility, with +.I size +acting as an implicit version number. +(Because new extension fields will always +be appended, the structure size will always increase.) +This extensibility design is very similar to other system calls such as +.BR perf_setattr (2), +.BR perf_event_open (2), +.BR clone3 (2) +and +.BR openat2 (2). +.P +Let +.I usize +be the size of the structure as specified by the user-space application, +and let +.I ksize +be the size of the structure which the kernel supports, +then there are three cases to consider: +.IP \[bu] 3 +If +.I ksize +equals +.IR usize , +then there is no version mismatch and +.I attr +can be used verbatim. +.IP \[bu] +If +.I ksize +is larger than +.IR usize , +then there are some extension fields that the kernel supports +which the user-space application is unaware of. +Because a zero value in any added extension field signifies a no-op, +the kernel treats all of the extension fields +not provided by the user-space application +as having zero values. +This provides backwards-compatibility. +.IP \[bu] +If +.I ksize +is smaller than +.IR usize , +then there are some extension fields which the user-space application is aware +of but which the kernel does not support. +Because any extension field must have its zero values signify a no-op, +the kernel can safely ignore the unsupported extension fields +if they are all zero. +If any unsupported extension fields are non-zero, +then \-1 is returned and +.I errno +is set to +.BR E2BIG . +This provides forwards-compatibility. +.P +Because the definition of +.I struct mount_attr +may change in the future +(with new fields being added when system headers are updated), +user-space applications should zero-fill +.I struct mount_attr +to ensure that recompiling the program with new headers will not result in +spurious errors at run time. +The simplest way is to use a designated initializer: +.P +.in +4n +.EX +struct mount_attr attr = { + .attr_set = MOUNT_ATTR_RDONLY, + .attr_clr = MOUNT_ATTR_NODEV +}; +.EE +.in +.P +Alternatively, the structure can be zero-filled using +.BR memset (3) +or similar functions: +.P +.in +4n +.EX +struct mount_attr attr; +memset(&attr, 0, sizeof(attr)); +attr.attr_set = MOUNT_ATTR_RDONLY; +attr.attr_clr = MOUNT_ATTR_NODEV; +.EE +.in +.P +A user-space application that wishes to determine which extensions the running +kernel supports can do so by conducting a binary search on +.I size +with a structure which has every byte nonzero +(to find the largest value which doesn't produce an error of +.BR E2BIG ). +.SH EXAMPLES +.\" SRC BEGIN (mount_setattr.c) +.EX +/* + * This program allows the caller to create a new detached mount + * and set various properties on it. + */ +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +static inline int +mount_setattr(int dirfd, const char *pathname, unsigned int flags, + struct mount_attr *attr, size_t size) +{ + return syscall(SYS_mount_setattr, dirfd, pathname, flags, + attr, size); +} +\& +static inline int +open_tree(int dirfd, const char *filename, unsigned int flags) +{ + return syscall(SYS_open_tree, dirfd, filename, flags); +} +\& +static inline int +move_mount(int from_dirfd, const char *from_pathname, + int to_dirfd, const char *to_pathname, unsigned int flags) +{ + return syscall(SYS_move_mount, from_dirfd, from_pathname, + to_dirfd, to_pathname, flags); +} +\& +static const struct option longopts[] = { + {"map\-mount", required_argument, NULL, \[aq]a\[aq]}, + {"recursive", no_argument, NULL, \[aq]b\[aq]}, + {"read\-only", no_argument, NULL, \[aq]c\[aq]}, + {"block\-setid", no_argument, NULL, \[aq]d\[aq]}, + {"block\-devices", no_argument, NULL, \[aq]e\[aq]}, + {"block\-exec", no_argument, NULL, \[aq]f\[aq]}, + {"no\-access\-time", no_argument, NULL, \[aq]g\[aq]}, + { NULL, 0, NULL, 0 }, +}; +\& +int +main(int argc, char *argv[]) +{ + int fd_userns = \-1; + int fd_tree; + int index = 0; + int ret; + bool recursive = false; + const char *source; + const char *target; + struct mount_attr *attr = &(struct mount_attr){}; +\& + while ((ret = getopt_long_only(argc, argv, "", + longopts, &index)) != \-1) { + switch (ret) { + case \[aq]a\[aq]: + fd_userns = open(optarg, O_RDONLY | O_CLOEXEC); + if (fd_userns == \-1) + err(EXIT_FAILURE, "open(%s)", optarg); + break; + case \[aq]b\[aq]: + recursive = true; + break; + case \[aq]c\[aq]: + attr\->attr_set |= MOUNT_ATTR_RDONLY; + break; + case \[aq]d\[aq]: + attr\->attr_set |= MOUNT_ATTR_NOSUID; + break; + case \[aq]e\[aq]: + attr\->attr_set |= MOUNT_ATTR_NODEV; + break; + case \[aq]f\[aq]: + attr\->attr_set |= MOUNT_ATTR_NOEXEC; + break; + case \[aq]g\[aq]: + attr\->attr_set |= MOUNT_ATTR_NOATIME; + attr\->attr_clr |= MOUNT_ATTR__ATIME; + break; + default: + errx(EXIT_FAILURE, "Invalid argument specified"); + } + } +\& + if ((argc \- optind) < 2) + errx(EXIT_FAILURE, "Missing source or target mount point"); +\& + source = argv[optind]; + target = argv[optind + 1]; +\& + /* In the following, \-1 as the \[aq]dirfd\[aq] argument ensures that + open_tree() fails if \[aq]source\[aq] is not an absolute pathname. */ +.\" Christian Brauner +.\" When writing programs I like to never use relative paths with AT_FDCWD +.\" because. Because making assumptions about the current working directory +.\" of the calling process is just too easy to get wrong; especially when +.\" pivot_root() or chroot() are in play. +.\" My absolut preference (joke intended) is to open a well-known starting +.\" point with an absolute path to get a dirfd and then scope all future +.\" operations beneath that dirfd. This already works with old-style +.\" openat() and _very_ cautious programming but openat2() and its +.\" resolve-flag space have made this **chef's kiss**. +.\" If I can't operate based on a well-known dirfd I use absolute paths +.\" with a -EBADF dirfd passed to *at() functions. +\& + fd_tree = open_tree(\-1, source, + OPEN_TREE_CLONE | OPEN_TREE_CLOEXEC | + AT_EMPTY_PATH | (recursive ? AT_RECURSIVE : 0)); + if (fd_tree == \-1) + err(EXIT_FAILURE, "open(%s)", source); +\& + if (fd_userns >= 0) { + attr\->attr_set |= MOUNT_ATTR_IDMAP; + attr\->userns_fd = fd_userns; + } +\& + ret = mount_setattr(fd_tree, "", + AT_EMPTY_PATH | (recursive ? AT_RECURSIVE : 0), + attr, sizeof(struct mount_attr)); + if (ret == \-1) + err(EXIT_FAILURE, "mount_setattr"); +\& + close(fd_userns); +\& + /* In the following, \-1 as the \[aq]to_dirfd\[aq] argument ensures that + open_tree() fails if \[aq]target\[aq] is not an absolute pathname. */ +\& + ret = move_mount(fd_tree, "", \-1, target, + MOVE_MOUNT_F_EMPTY_PATH); + if (ret == \-1) + err(EXIT_FAILURE, "move_mount() to %s", target); +\& + close(fd_tree); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR newgidmap (1), +.BR newuidmap (1), +.BR clone (2), +.BR mount (2), +.BR unshare (2), +.BR proc (5), +.BR capabilities (7), +.BR mount_namespaces (7), +.BR user_namespaces (7), +.BR xattr (7) diff --git a/man/man2/move_pages.2 b/man/man2/move_pages.2 new file mode 100644 index 0000000..c6b7349 --- /dev/null +++ b/man/man2/move_pages.2 @@ -0,0 +1,253 @@ +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc. +.\" Christoph Lameter +.\" +.\" FIXME Should programs normally be using move_pages() directly, or should +.\" they rather be using interfaces in the numactl package? +.\" (e.g., compare with recommendation in mbind(2)). +.\" Does this page need to give advice on this topic? +.\" +.TH move_pages 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +move_pages \- move individual pages of a process to another node +.SH LIBRARY +NUMA (Non-Uniform Memory Access) policy library +.RI ( libnuma ", " \-lnuma ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long move_pages(int " pid ", unsigned long " count ", \ +void *" pages [. count ], +.BI " const int " nodes [. count "], int " status [. count "], \ +int " flags ); +.fi +.SH DESCRIPTION +.BR move_pages () +moves the specified +.I pages +of the process +.I pid +to the memory nodes specified by +.IR nodes . +The result of the move is reflected in +.IR status . +The +.I flags +indicate constraints on the pages to be moved. +.P +.I pid +is the ID of the process in which pages are to be moved. +If +.I pid +is 0, then +.BR move_pages () +moves pages of the calling process. +.P +To move pages in another process requires the following privileges: +.IP \[bu] 3 +Up to and including Linux 4.12: +the caller must be privileged +.RB ( CAP_SYS_NICE ) +or the real or effective user ID of the calling process must match the +real or saved-set user ID of the target process. +.IP \[bu] +The older rules allowed the caller to discover various +virtual address choices made by the kernel that could lead +to the defeat of address-space-layout randomization +for a process owned by the same UID as the caller, +the rules were changed starting with Linux 4.13. +Since Linux 4.13, +.\" commit 197e7e521384a23b9e585178f3f11c9fa08274b9 +permission is governed by a ptrace access mode +.B PTRACE_MODE_READ_REALCREDS +check with respect to the target process; see +.BR ptrace (2). +.P +.I count +is the number of pages to move. +It defines the size of the three arrays +.IR pages , +.IR nodes , +and +.IR status . +.P +.I pages +is an array of pointers to the pages that should be moved. +These are pointers that should be aligned to page boundaries. +.\" FIXME Describe the result if pointers in the 'pages' array are +.\" not aligned to page boundaries +Addresses are specified as seen by the process specified by +.IR pid . +.P +.I nodes +is an array of integers that specify the desired location for each page. +Each element in the array is a node number. +.I nodes +can also be NULL, in which case +.BR move_pages () +does not move any pages but instead will return the node +where each page currently resides, in the +.I status +array. +Obtaining the status of each page may be necessary to determine +pages that need to be moved. +.P +.I status +is an array of integers that return the status of each page. +The array contains valid values only if +.BR move_pages () +did not return an error. +Preinitialization of the array to a value +which cannot represent a real numa node or valid error of status array +could help to identify pages that have been migrated. +.P +.I flags +specify what types of pages to move. +.B MPOL_MF_MOVE +means that only pages that are in exclusive use by the process +are to be moved. +.B MPOL_MF_MOVE_ALL +means that pages shared between multiple processes can also be moved. +The process must be privileged +.RB ( CAP_SYS_NICE ) +to use +.BR MPOL_MF_MOVE_ALL . +.SS Page states in the status array +The following values can be returned in each element of the +.I status +array. +.TP +.B 0..MAX_NUMNODES +Identifies the node on which the page resides. +.TP +.B \-EACCES +The page is mapped by multiple processes and can be moved only if +.B MPOL_MF_MOVE_ALL +is specified. +.TP +.B \-EBUSY +The page is currently busy and cannot be moved. +Try again later. +This occurs if a page is undergoing I/O or another kernel subsystem +is holding a reference to the page. +.TP +.B \-EFAULT +This is a zero page or the memory area is not mapped by the process. +.TP +.B \-EIO +Unable to write back a page. +The page has to be written back +in order to move it since the page is dirty and the filesystem +does not provide a migration function that would allow the move +of dirty pages. +.TP +.B \-EINVAL +A dirty page cannot be moved. +The filesystem does not +provide a migration function and has no ability to write back pages. +.TP +.B \-ENOENT +The page is not present. +.TP +.B \-ENOMEM +Unable to allocate memory on target node. +.SH RETURN VALUE +On success +.BR move_pages () +returns zero. +.\" FIXME . Is the following quite true: does the wrapper in numactl +.\" do the right thing? +On error, it returns \-1, and sets +.I errno +to indicate the error. +If positive value is returned, it is the number of +nonmigrated pages. +.SH ERRORS +.TP +.B Positive value +The number of nonmigrated pages if they were the result of nonfatal +reasons (since +.\" commit a49bd4d7163707de377aee062f17befef6da891b +Linux 4.17). +.TP +.B E2BIG +Too many pages to move. +Since Linux 2.6.29, +.\" commit 3140a2273009c01c27d316f35ab76a37e105fdd8 +the kernel no longer generates this error. +.TP +.B EACCES +.\" FIXME Clarify "current cpuset" in the description of the EACCES error. +.\" Is that the cpuset of the caller or the target? +One of the target nodes is not allowed by the current cpuset. +.TP +.B EFAULT +Parameter array could not be accessed. +.TP +.B EINVAL +Flags other than +.B MPOL_MF_MOVE +and +.B MPOL_MF_MOVE_ALL +was specified or an attempt was made to migrate pages of a kernel thread. +.TP +.B ENODEV +One of the target nodes is not online. +.TP +.B EPERM +The caller specified +.B MPOL_MF_MOVE_ALL +without sufficient privileges +.RB ( CAP_SYS_NICE ). +Or, the caller attempted to move pages of a process belonging +to another user but did not have privilege to do so +.RB ( CAP_SYS_NICE ). +.TP +.B ESRCH +Process does not exist. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.18. +.SH NOTES +For information on library support, see +.BR numa (7). +.P +Use +.BR get_mempolicy (2) +with the +.B MPOL_F_MEMS_ALLOWED +flag to obtain the set of nodes that are allowed by +.\" FIXME Clarify "current cpuset". Is that the cpuset of the caller +.\" or the target? +the current cpuset. +Note that this information is subject to change at any +time by manual or automatic reconfiguration of the cpuset. +.P +Use of this function may result in pages whose location +(node) violates the memory policy established for the +specified addresses (See +.BR mbind (2)) +and/or the specified process (See +.BR set_mempolicy (2)). +That is, memory policy does not constrain the destination +nodes used by +.BR move_pages (). +.P +The +.I +header is not included with glibc, but requires installing +.I libnuma\-devel +or a similar package. +.SH SEE ALSO +.BR get_mempolicy (2), +.BR mbind (2), +.BR set_mempolicy (2), +.BR numa (3), +.BR numa_maps (5), +.BR cpuset (7), +.BR numa (7), +.BR migratepages (8), +.BR numastat (8) diff --git a/man/man2/mprotect.2 b/man/man2/mprotect.2 new file mode 100644 index 0000000..b378166 --- /dev/null +++ b/man/man2/mprotect.2 @@ -0,0 +1,363 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" and Copyright (C) 1995 Michael Shields . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1997-05-31 by Andries Brouwer +.\" Modified 2003-08-24 by Andries Brouwer +.\" Modified 2004-08-16 by Andi Kleen +.\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and +.\" a much improved example program. +.\" +.TH mprotect 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mprotect, pkey_mprotect \- set protection on a region of memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mprotect(void " addr [. len "], size_t " len ", int " prot ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int pkey_mprotect(void " addr [. len "], size_t " len ", int " prot ", int " pkey ");" +.fi +.SH DESCRIPTION +.BR mprotect () +changes the access protections for the calling process's memory pages +containing any part of the address range in the +interval [\fIaddr\fP,\ \fIaddr\fP+\fIlen\fP\-1]. +.I addr +must be aligned to a page boundary. +.P +If the calling process tries to access memory in a manner +that violates the protections, then the kernel generates a +.B SIGSEGV +signal for the process. +.P +.I prot +is a combination of the following access flags: +.B PROT_NONE +or a bitwise OR of the other values in the following list: +.TP +.B PROT_NONE +The memory cannot be accessed at all. +.TP +.B PROT_READ +The memory can be read. +.TP +.B PROT_WRITE +The memory can be modified. +.TP +.B PROT_EXEC +The memory can be executed. +.TP +.BR PROT_SEM " (since Linux 2.5.7)" +The memory can be used for atomic operations. +This flag was introduced as part of the +.BR futex (2) +implementation (in order to guarantee the ability to perform atomic +operations required by commands such as +.BR FUTEX_WAIT ), +but is not currently used in on any architecture. +.TP +.BR PROT_SAO " (since Linux 2.6.26)" +.\" commit aba46c5027cb59d98052231b36efcbbde9c77a1d +.\" commit ef3d3246a0d06be622867d21af25f997aeeb105f +The memory should have strong access ordering. +This feature is specific to +the PowerPC architecture +(version 2.06 of the architecture specification adds the SAO CPU feature, +and it is available on POWER 7 or PowerPC A2, for example). +.P +Additionally (since Linux 2.6.0), +.I prot +can have one of the following flags set: +.TP +.\" mm/mmap.c: +.\" vm_flags |= calc_vm_prot_bits(prot, pkey) | calc_vm_flag_bits(flags) | +.\" mm->def_flags | VM_MAYREAD | VM_MAYWRITE | VM_MAYEXEC; +.\" And calc_vm_flag_bits converts only GROWSDOWN/DENYWRITE/LOCKED. +.B PROT_GROWSUP +Apply the protection mode up to the end of a mapping +that grows upwards. +(Such mappings are created for the stack area on +architectures\[em]for example, HP-PARISC\[em]that +have an upwardly growing stack.) +.\" The VMA is one that was marked with VM_GROWSUP by the kernel +.\" when the stack was created. Note that (unlike VM_GROWSDOWN), +.\" there is no mmap() flag (analogous to MAP_GROWSDOWN) for +.\" creating a VMA that is marked VM_GROWSUP. +.TP +.B PROT_GROWSDOWN +Apply the protection mode down to the beginning of a mapping +that grows downward +(which should be a stack segment or a segment mapped with the +.B MAP_GROWSDOWN +flag set). +.P +Like +.BR mprotect (), +.BR pkey_mprotect () +changes the protection on the pages specified by +.I addr +and +.IR len . +The +.I pkey +argument specifies the protection key (see +.BR pkeys (7)) +to assign to the memory. +The protection key must be allocated with +.BR pkey_alloc (2) +before it is passed to +.BR pkey_mprotect (). +For an example of the use of this system call, see +.BR pkeys (7). +.SH RETURN VALUE +On success, +.BR mprotect () +and +.BR pkey_mprotect () +return zero. +On error, these system calls return \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The memory cannot be given the specified access. +This can happen, for example, if you +.BR mmap (2) +a file to which you have read-only access, then ask +.BR mprotect () +to mark it +.BR PROT_WRITE . +.TP +.B EINVAL +\fIaddr\fP is not a valid pointer, +or not a multiple of the system page size. +.TP +.B EINVAL +.RB ( pkey_mprotect ()) +\fIpkey\fP has not been allocated with +.BR pkey_alloc (2) +.TP +.B EINVAL +Both +.B PROT_GROWSUP +and +.B PROT_GROWSDOWN +were specified in +.IR prot . +.TP +.B EINVAL +Invalid flags specified in +.IR prot . +.TP +.B EINVAL +(PowerPC architecture) +.B PROT_SAO +was specified in +.IR prot , +but SAO hardware feature is not available. +.TP +.B ENOMEM +Internal kernel structures could not be allocated. +.TP +.B ENOMEM +Addresses in the range +.RI [ addr , +.IR addr + len \-1] +are invalid for the address space of the process, +or specify one or more pages that are not mapped. +(Before Linux 2.4.19, the error +.B EFAULT +was incorrectly produced for these cases.) +.TP +.B ENOMEM +Changing the protection of a memory region would result in the total number of +mappings with distinct attributes (e.g., read versus read/write protection) +exceeding the allowed maximum. +.\" I.e., the number of VMAs would exceed the 64 kB maximum +(For example, making the protection of a range +.B PROT_READ +in the middle of a region currently protected as +.B PROT_READ|PROT_WRITE +would result in three mappings: +two read/write mappings at each end and a read-only mapping in the middle.) +.SH VERSIONS +.\" SVr4 defines an additional error +.\" code EAGAIN. The SVr4 error conditions don't map neatly onto Linux's. +POSIX says that the behavior of +.BR mprotect () +is unspecified if it is applied to a region of memory that +was not obtained via +.BR mmap (2). +.P +On Linux, it is always permissible to call +.BR mprotect () +on any address in a process's address space (except for the +kernel vsyscall area). +In particular, it can be used +to change existing code mappings to be writable. +.P +Whether +.B PROT_EXEC +has any effect different from +.B PROT_READ +depends on processor architecture, kernel version, and process state. +If +.B READ_IMPLIES_EXEC +is set in the process's personality flags (see +.BR personality (2)), +specifying +.B PROT_READ +will implicitly add +.BR PROT_EXEC . +.P +On some hardware architectures (e.g., i386), +.B PROT_WRITE +implies +.BR PROT_READ . +.P +POSIX.1 says that an implementation may permit access +other than that specified in +.IR prot , +but at a minimum can allow write access only if +.B PROT_WRITE +has been set, and must not allow any access if +.B PROT_NONE +has been set. +.P +Applications should be careful when mixing use of +.BR mprotect () +and +.BR pkey_mprotect (). +On x86, when +.BR mprotect () +is used with +.I prot +set to +.B PROT_EXEC +a pkey may be allocated and set on the memory implicitly +by the kernel, but only when the pkey was 0 previously. +.P +On systems that do not support protection keys in hardware, +.BR pkey_mprotect () +may still be used, but +.I pkey +must be set to \-1. +When called this way, the operation of +.BR pkey_mprotect () +is equivalent to +.BR mprotect (). +.SH STANDARDS +.TP +.BR mprotect () +POSIX.1-2008. +.TP +.BR pkey_mprotect () +Linux. +.SH HISTORY +.TP +.BR mprotect () +POSIX.1-2001, SVr4. +.TP +.BR pkey_mprotect () +Linux 4.9, +glibc 2.27. +.SH NOTES +.SH EXAMPLES +.\" sigaction.2 refers to this example +The program below demonstrates the use of +.BR mprotect (). +The program allocates four pages of memory, makes the third +of these pages read-only, and then executes a loop that walks upward +through the allocated region modifying bytes. +.P +An example of what we might see when running the program is the +following: +.P +.in +4n +.EX +.RB "$" " ./a.out" +Start of region: 0x804c000 +Got SIGSEGV at address: 0x804e000 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mprotect.c) +.EX +#include +#include +#include +#include +#include +#include +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static char *buffer; +\& +static void +handler(int sig, siginfo_t *si, void *unused) +{ + /* 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("Got SIGSEGV at address: %p\en", si\->si_addr); + exit(EXIT_FAILURE); +} +\& +int +main(void) +{ + int pagesize; + struct sigaction sa; +\& + sa.sa_flags = SA_SIGINFO; + sigemptyset(&sa.sa_mask); + sa.sa_sigaction = handler; + if (sigaction(SIGSEGV, &sa, NULL) == \-1) + handle_error("sigaction"); +\& + pagesize = sysconf(_SC_PAGE_SIZE); + if (pagesize == \-1) + handle_error("sysconf"); +\& + /* Allocate a buffer aligned on a page boundary; + initial protection is PROT_READ | PROT_WRITE. */ +\& + buffer = memalign(pagesize, 4 * pagesize); + if (buffer == NULL) + handle_error("memalign"); +\& + printf("Start of region: %p\en", buffer); +\& + if (mprotect(buffer + pagesize * 2, pagesize, + PROT_READ) == \-1) + handle_error("mprotect"); +\& + for (char *p = buffer ; ; ) + *(p++) = \[aq]a\[aq]; +\& + printf("Loop completed\en"); /* Should never happen */ + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR mmap (2), +.BR sysconf (3), +.BR pkeys (7) diff --git a/man/man2/mpx.2 b/man/man2/mpx.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/mpx.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/mq_getsetattr.2 b/man/man2/mq_getsetattr.2 new file mode 100644 index 0000000..8a9e5b7 --- /dev/null +++ b/man/man2/mq_getsetattr.2 @@ -0,0 +1,33 @@ +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_getsetattr 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_getsetattr \- get/set message queue attributes +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " "struct mq_attr" " */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_mq_getsetattr, mqd_t " mqdes , +.BI " const struct mq_attr *" newattr ", struct mq_attr *" oldattr ); +.fi +.SH DESCRIPTION +Do not use this system call. +.P +This is the low-level system call used to implement +.BR mq_getattr (3) +and +.BR mq_setattr (3). +For an explanation of how this system call operates, +see the description of +.BR mq_setattr (3). +.SH STANDARDS +None. +.SH NOTES +Never call it unless you are writing a C library! +.SH SEE ALSO +.BR mq_getattr (3), +.BR mq_overview (7) diff --git a/man/man2/mq_notify.2 b/man/man2/mq_notify.2 new file mode 100644 index 0000000..505a45e --- /dev/null +++ b/man/man2/mq_notify.2 @@ -0,0 +1,2 @@ +.so man3/mq_notify.3 +.\" Because mq_notify(3) is layered on a system call of the same name diff --git a/man/man2/mq_open.2 b/man/man2/mq_open.2 new file mode 100644 index 0000000..ce82835 --- /dev/null +++ b/man/man2/mq_open.2 @@ -0,0 +1,2 @@ +.so man3/mq_open.3 +.\" Because mq_open(3) is layered on a system call of the same name diff --git a/man/man2/mq_timedreceive.2 b/man/man2/mq_timedreceive.2 new file mode 100644 index 0000000..b4184f8 --- /dev/null +++ b/man/man2/mq_timedreceive.2 @@ -0,0 +1,2 @@ +.so man3/mq_timedreceive.3 +.\" Because mq_timedreceive(3) is layered on a system call of the same name diff --git a/man/man2/mq_timedsend.2 b/man/man2/mq_timedsend.2 new file mode 100644 index 0000000..db95863 --- /dev/null +++ b/man/man2/mq_timedsend.2 @@ -0,0 +1,2 @@ +.so man3/mq_timedsend.3 +.\" Because mq_timedsend(3) is layered on a system call of the same name diff --git a/man/man2/mq_unlink.2 b/man/man2/mq_unlink.2 new file mode 100644 index 0000000..c5f2768 --- /dev/null +++ b/man/man2/mq_unlink.2 @@ -0,0 +1,2 @@ +.so man3/mq_unlink.3 +.\" Because mq_unlink(3) is layered on a system call of the same name diff --git a/man/man2/mremap.2 b/man/man2/mremap.2 new file mode 100644 index 0000000..d25b234 --- /dev/null +++ b/man/man2/mremap.2 @@ -0,0 +1,357 @@ +.\" Copyright (c) 1996 Tom Bjorkholm +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1996-04-11 Tom Bjorkholm +.\" First version written (1.3.86) +.\" 1996-04-12 Tom Bjorkholm +.\" Update for Linux 1.3.87 and later +.\" 2005-10-11 mtk: Added NOTES for MREMAP_FIXED; revised EINVAL text. +.\" +.TH mremap 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mremap \- remap a virtual memory address +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "void *mremap(void " old_address [. old_size "], size_t " old_size , +.BI " size_t " new_size ", int " flags ", ... /* void *" new_address " */);" +.fi +.SH DESCRIPTION +.BR mremap () +expands (or shrinks) an existing memory mapping, potentially +moving it at the same time (controlled by the \fIflags\fP argument and +the available virtual address space). +.P +\fIold_address\fP is the old address of the virtual memory block that you +want to expand (or shrink). +Note that \fIold_address\fP has to be page +aligned. +\fIold_size\fP is the old size of the +virtual memory block. +\fInew_size\fP is the requested size of the +virtual memory block after the resize. +An optional fifth argument, +.IR new_address , +may be provided; see the description of +.B MREMAP_FIXED +below. +.P +If the value of \fIold_size\fP is zero, and \fIold_address\fP refers to +a shareable mapping +(see the description of +.B MAP_SHARED +in +.BR mmap (2)), +then +.BR mremap () +will create a new mapping of the same pages. +\fInew_size\fP +will be the size of the new mapping and the location of the new mapping +may be specified with \fInew_address\fP; see the description of +.B MREMAP_FIXED +below. +If a new mapping is requested via this method, then the +.B MREMAP_MAYMOVE +flag must also be specified. +.P +The \fIflags\fP bit-mask argument may be 0, or include the following flags: +.TP +.B MREMAP_MAYMOVE +By default, if there is not sufficient space to expand a mapping +at its current location, then +.BR mremap () +fails. +If this flag is specified, then the kernel is permitted to +relocate the mapping to a new virtual address, if necessary. +If the mapping is relocated, +then absolute pointers into the old mapping location +become invalid (offsets relative to the starting address of +the mapping should be employed). +.TP +.BR MREMAP_FIXED " (since Linux 2.3.31)" +This flag serves a similar purpose to the +.B MAP_FIXED +flag of +.BR mmap (2). +If this flag is specified, then +.BR mremap () +accepts a fifth argument, +.IR "void\ *new_address" , +which specifies a page-aligned address to which the mapping must +be moved. +Any previous mapping at the address range specified by +.I new_address +and +.I new_size +is unmapped. +.IP +If +.B MREMAP_FIXED +is specified, then +.B MREMAP_MAYMOVE +must also be specified. +.TP +.BR MREMAP_DONTUNMAP " (since Linux 5.7)" +.\" commit e346b3813067d4b17383f975f197a9aa28a3b077 +This flag, which must be used in conjunction with +.BR MREMAP_MAYMOVE , +remaps a mapping to a new address but does not unmap the mapping at +.IR old_address . +.IP +The +.B MREMAP_DONTUNMAP +flag can be used only with private anonymous mappings +(see the description of +.B MAP_PRIVATE +and +.B MAP_ANONYMOUS +in +.BR mmap (2)). +.IP +After completion, +any access to the range specified by +.I old_address +and +.I old_size +will result in a page fault. +The page fault will be handled by a +.BR userfaultfd (2) +handler +if the address is in a range previously registered with +.BR userfaultfd (2). +Otherwise, the kernel allocates a zero-filled page to handle the fault. +.IP +The +.B MREMAP_DONTUNMAP +flag may be used to atomically move a mapping while leaving the source +mapped. +See NOTES for some possible applications of +.BR MREMAP_DONTUNMAP . +.P +If the memory segment specified by +.I old_address +and +.I old_size +is locked (using +.BR mlock (2) +or similar), then this lock is maintained when the segment is +resized and/or relocated. +As a consequence, the amount of memory locked by the process may change. +.SH RETURN VALUE +On success +.BR mremap () +returns a pointer to the new virtual memory area. +On error, the value +.B MAP_FAILED +(that is, \fI(void\ *)\ \-1\fP) is returned, +and \fIerrno\fP is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The caller tried to expand a memory segment that is locked, +but this was not possible without exceeding the +.B RLIMIT_MEMLOCK +resource limit. +.TP +.B EFAULT +Some address in the range +\fIold_address\fP to \fIold_address\fP+\fIold_size\fP is an invalid +virtual memory address for this process. +You can also get +.B EFAULT +even if there exist mappings that cover the +whole address space requested, but those mappings are of different types. +.TP +.B EINVAL +An invalid argument was given. +Possible causes are: +.RS +.IP \[bu] 3 +\fIold_address\fP was not +page aligned; +.IP \[bu] +a value other than +.B MREMAP_MAYMOVE +or +.B MREMAP_FIXED +or +.B MREMAP_DONTUNMAP +was specified in +.IR flags ; +.IP \[bu] +.I new_size +was zero; +.IP \[bu] +.I new_size +or +.I new_address +was invalid; +.IP \[bu] +the new address range specified by +.I new_address +and +.I new_size +overlapped the old address range specified by +.I old_address +and +.IR old_size ; +.IP \[bu] +.B MREMAP_FIXED +or +.B MREMAP_DONTUNMAP +was specified without also specifying +.BR MREMAP_MAYMOVE ; +.IP \[bu] +.B MREMAP_DONTUNMAP +was specified, but one or more pages in the range specified by +.I old_address +and +.I old_size +were not private anonymous; +.IP \[bu] +.B MREMAP_DONTUNMAP +was specified and +.I old_size +was not equal to +.IR new_size ; +.IP \[bu] +\fIold_size\fP was zero and \fIold_address\fP does not refer to a +shareable mapping (but see BUGS); +.IP \[bu] +\fIold_size\fP was zero and the +.B MREMAP_MAYMOVE +flag was not specified. +.RE +.TP +.B ENOMEM +Not enough memory was available to complete the operation. +Possible causes are: +.RS +.IP \[bu] 3 +The memory area cannot be expanded at the current virtual address, and the +.B MREMAP_MAYMOVE +flag is not set in \fIflags\fP. +Or, there is not enough (virtual) memory available. +.IP \[bu] +.B MREMAP_DONTUNMAP +was used causing a new mapping to be created that would exceed the +(virtual) memory available. +Or, it would exceed the maximum number of allowed mappings. +.RE +.SH STANDARDS +Linux. +.SH HISTORY +.\" 4.2BSD had a (never actually implemented) +.\" .BR mremap (2) +.\" call with completely different semantics. +.\" .P +Prior to glibc 2.4, glibc did not expose the definition of +.BR MREMAP_FIXED , +and the prototype for +.BR mremap () +did not allow for the +.I new_address +argument. +.SH NOTES +.BR mremap () +changes the +mapping between virtual addresses and memory pages. +This can be used to implement a very efficient +.BR realloc (3). +.P +In Linux, memory is divided into pages. +A process has (one or) +several linear virtual memory segments. +Each virtual memory segment has one +or more mappings to real memory pages (in the page table). +Each virtual memory segment has its own +protection (access rights), which may cause +a segmentation violation +.RB ( SIGSEGV ) +if the memory is accessed incorrectly (e.g., +writing to a read-only segment). +Accessing virtual memory outside of the +segments will also cause a segmentation violation. +.P +If +.BR mremap () +is used to move or expand an area locked with +.BR mlock (2) +or equivalent, the +.BR mremap () +call will make a best effort to populate the new area but will not fail +with +.B ENOMEM +if the area cannot be populated. +.\" +.SS MREMAP_DONTUNMAP use cases +Possible applications for +.B MREMAP_DONTUNMAP +include: +.IP \[bu] 3 +Non-cooperative +.BR userfaultfd (2): +an application can yank out a virtual address range using +.B MREMAP_DONTUNMAP +and then employ a +.BR userfaultfd (2) +handler to handle the page faults that subsequently occur +as other threads in the process touch pages in the yanked range. +.IP \[bu] +Garbage collection: +.B MREMAP_DONTUNMAP +can be used in conjunction with +.BR userfaultfd (2) +to implement garbage collection algorithms (e.g., in a Java virtual machine). +Such an implementation can be cheaper (and simpler) +than conventional garbage collection techniques that involve +marking pages with protection +.B PROT_NONE +in conjunction with the use of a +.B SIGSEGV +handler to catch accesses to those pages. +.SH BUGS +Before Linux 4.14, +if +.I old_size +was zero and the mapping referred to by +.I old_address +was a private mapping +(see the description of +.B MAP_PRIVATE +in +.BR mmap (2)), +.BR mremap () +created a new private mapping unrelated to the original mapping. +This behavior was unintended +and probably unexpected in user-space applications +(since the intention of +.BR mremap () +is to create a new mapping based on the original mapping). +Since Linux 4.14, +.\" commit dba58d3b8c5045ad89c1c95d33d01451e3964db7 +.BR mremap () +fails with the error +.B EINVAL +in this scenario. +.SH SEE ALSO +.BR brk (2), +.BR getpagesize (2), +.BR getrlimit (2), +.BR mlock (2), +.BR mmap (2), +.BR sbrk (2), +.BR malloc (3), +.BR realloc (3) +.P +Your favorite text book on operating systems +for more information on paged memory +(e.g., \fIModern Operating Systems\fP by Andrew S.\& Tanenbaum, +\fIInside Linux\fP by Randolph Bentson, +\fIThe Design of the UNIX Operating System\fP by Maurice J.\& Bach) diff --git a/man/man2/msgctl.2 b/man/man2/msgctl.2 new file mode 100644 index 0000000..d965269 --- /dev/null +++ b/man/man2/msgctl.2 @@ -0,0 +1,424 @@ +'\" t +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" and Copyright 2004, 2005 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified Sun Feb 18 01:59:29 2001 by Andries E. Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on CAP_IPC_OWNER requirement +.\" Modified, 17 Jun 2004, Michael Kerrisk +.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added msqid_ds and ipc_perm structure definitions +.\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions +.\" 2018-03-20, dbueso: Added MSG_STAT_ANY description. +.\" +.TH msgctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +msgctl \- System V message control operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int msgctl(int " msqid ", int " op ", struct msqid_ds *" buf ); +.fi +.SH DESCRIPTION +.BR msgctl () +performs the control operation specified by +.I op +on the System\ V message queue with identifier +.IR msqid . +.P +The +.I msqid_ds +data structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct msqid_ds { + struct ipc_perm msg_perm; /* Ownership and permissions */ + time_t msg_stime; /* Time of last msgsnd(2) */ + time_t msg_rtime; /* Time of last msgrcv(2) */ + time_t msg_ctime; /* Time of creation or last + modification by msgctl() */ + unsigned long msg_cbytes; /* # of bytes in queue */ + msgqnum_t msg_qnum; /* # number of messages in queue */ + msglen_t msg_qbytes; /* Maximum # of bytes in queue */ + pid_t msg_lspid; /* PID of last msgsnd(2) */ + pid_t msg_lrpid; /* PID of last msgrcv(2) */ +}; +.EE +.in +.P +The fields of the +.I msqid_ds +structure are as follows: +.TP 11 +.I msg_perm +This is an +.I ipc_perm +structure (see below) that specifies the access permissions on the message +queue. +.TP +.I msg_stime +Time of the last +.BR msgsnd (2) +system call. +.TP +.I msg_rtime +Time of the last +.BR msgrcv (2) +system call. +.TP +.I msg_ctime +Time of creation of queue or time of last +.BR msgctl () +.B IPC_SET +operation. +.TP +.I msg_cbytes +Number of bytes in all messages currently on the message queue. +This is a nonstandard Linux extension that is not specified in POSIX. +.TP +.I msg_qnum +Number of messages currently on the message queue. +.TP +.I msg_qbytes +Maximum number of bytes of message text allowed on the message +queue. +.TP +.I msg_lspid +ID of the process that performed the last +.BR msgsnd (2) +system call. +.TP +.I msg_lrpid +ID of the process that performed the last +.BR msgrcv (2) +system call. +.P +The +.I ipc_perm +structure is defined as follows +(the highlighted fields are settable using +.BR IPC_SET ): +.P +.in +4n +.EX +struct ipc_perm { + key_t __key; /* Key supplied to msgget(2) */ + uid_t \fBuid\fP; /* Effective UID of owner */ + gid_t \fBgid\fP; /* Effective GID of owner */ + uid_t cuid; /* Effective UID of creator */ + gid_t cgid; /* Effective GID of creator */ + unsigned short \fBmode\fP; /* Permissions */ + unsigned short __seq; /* Sequence number */ +}; +.EE +.in +.P +The least significant 9 bits of the +.I mode +field of the +.I ipc_perm +structure define the access permissions for the message queue. +The permission bits are as follows: +.TS +l l. +0400 Read by user +0200 Write by user +0040 Read by group +0020 Write by group +0004 Read by others +0002 Write by others +.TE +.P +Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. +.P +Valid values for +.I op +are: +.TP +.B IPC_STAT +Copy information from the kernel data structure associated with +.I msqid +into the +.I msqid_ds +structure pointed to by +.IR buf . +The caller must have read permission on the message queue. +.TP +.B IPC_SET +Write the values of some members of the +.I msqid_ds +structure pointed to by +.I buf +to the kernel data structure associated with this message queue, +updating also its +.I msg_ctime +member. +.IP +The following members of the structure are updated: +.IR msg_qbytes , +.IR msg_perm.uid , +.IR msg_perm.gid , +and (the least significant 9 bits of) +.IR msg_perm.mode . +.IP +The effective UID of the calling process must match the owner +.RI ( msg_perm.uid ) +or creator +.RI ( msg_perm.cuid ) +of the message queue, or the caller must be privileged. +Appropriate privilege (Linux: the +.B CAP_SYS_RESOURCE +capability) is required to raise the +.I msg_qbytes +value beyond the system parameter +.BR MSGMNB . +.TP +.B IPC_RMID +Immediately remove the message queue, +awakening all waiting reader and writer processes (with an error +return and +.I errno +set to +.BR EIDRM ). +The calling process must have appropriate privileges +or its effective user ID must be either that of the creator or owner +of the message queue. +The third argument to +.BR msgctl () +is ignored in this case. +.TP +.BR IPC_INFO " (Linux-specific)" +Return information about system-wide message queue limits and +parameters in the structure pointed to by +.IR buf . +This structure is of type +.I msginfo +(thus, a cast is required), +defined in +.I +if the +.B _GNU_SOURCE +feature test macro is defined: +.IP +.in +4n +.EX +struct msginfo { + int msgpool; /* Size in kibibytes of buffer pool + used to hold message data; + unused within kernel */ + int msgmap; /* Maximum number of entries in message + map; unused within kernel */ + int msgmax; /* Maximum number of bytes that can be + written in a single message */ + int msgmnb; /* Maximum number of bytes that can be + written to queue; used to initialize + msg_qbytes during queue creation + (msgget(2)) */ + int msgmni; /* Maximum number of message queues */ + int msgssz; /* Message segment size; + unused within kernel */ + int msgtql; /* Maximum number of messages on all queues + in system; unused within kernel */ + unsigned short msgseg; + /* Maximum number of segments; + unused within kernel */ +}; +.EE +.in +.IP +The +.IR msgmni , +.IR msgmax , +and +.I msgmnb +settings can be changed via +.I /proc +files of the same name; see +.BR proc (5) +for details. +.TP +.BR MSG_INFO " (Linux-specific)" +Return a +.I msginfo +structure containing the same information as for +.BR IPC_INFO , +except that the following fields are returned with information +about system resources consumed by message queues: the +.I msgpool +field returns the number of message queues that currently exist +on the system; the +.I msgmap +field returns the total number of messages in all queues +on the system; and the +.I msgtql +field returns the total number of bytes in all messages +in all queues on the system. +.TP +.BR MSG_STAT " (Linux-specific)" +Return a +.I msqid_ds +structure as for +.BR IPC_STAT . +However, the +.I msqid +argument is not a queue identifier, but instead an index into +the kernel's internal array that maintains information about +all message queues on the system. +.TP +.BR MSG_STAT_ANY " (Linux-specific, since Linux 4.17)" +Return a +.I msqid_ds +structure as for +.BR MSG_STAT . +However, +.I msg_perm.mode +is not checked for read access for +.I msqid +meaning that any user can employ this operation (just as any user may read +.I /proc/sysvipc/msg +to obtain the same information). +.SH RETURN VALUE +On success, +.BR IPC_STAT , +.BR IPC_SET , +and +.B IPC_RMID +return 0. +A successful +.B IPC_INFO +or +.B MSG_INFO +operation returns the index of the highest used entry in the +kernel's internal array recording information about all +message queues. +(This information can be used with repeated +.B MSG_STAT +or +.B MSG_STAT_ANY +operations to obtain information about all queues on the system.) +A successful +.B MSG_STAT +or +.B MSG_STAT_ANY +operation returns the identifier of the queue whose index was given in +.IR msqid . +.P +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The argument +.I op +is equal to +.B IPC_STAT +or +.BR MSG_STAT , +but the calling process does not have read permission on the message queue +.IR msqid , +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EFAULT +The argument +.I op +has the value +.B IPC_SET +or +.BR IPC_STAT , +but the address pointed to by +.I buf +isn't accessible. +.TP +.B EIDRM +The message queue was removed. +.TP +.B EINVAL +Invalid value for +.I op +or +.IR msqid . +Or: for a +.B MSG_STAT +operation, the index value specified in +.I msqid +referred to an array slot that is currently unused. +.TP +.B EPERM +The argument +.I op +has the value +.B IPC_SET +or +.BR IPC_RMID , +but the effective user ID of the calling process is not the creator +(as found in +.IR msg_perm.cuid ) +or the owner +(as found in +.IR msg_perm.uid ) +of the message queue, +and the caller is not privileged (Linux: does not have the +.B CAP_SYS_ADMIN +capability). +.TP +.B EPERM +An attempt +.RB ( IPC_SET ) +was made to increase +.I msg_qbytes +beyond the system parameter +.BR MSGMNB , +but the caller is not privileged (Linux: does not have the +.B CAP_SYS_RESOURCE +capability). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVID does not document the EIDRM error condition. +.P +Various fields in the \fIstruct msqid_ds\fP were +typed as +.I short +under Linux 2.2 +and have become +.I long +under Linux 2.4. +To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by an +.B IPC_64 +flag in +.IR op .) +.SH NOTES +The +.BR IPC_INFO , +.BR MSG_STAT , +and +.B MSG_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future these may modified or moved to a +.I /proc +filesystem interface. +.SH SEE ALSO +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR capabilities (7), +.BR mq_overview (7), +.BR sysvipc (7) diff --git a/man/man2/msgget.2 b/man/man2/msgget.2 new file mode 100644 index 0000000..ab68dde --- /dev/null +++ b/man/man2/msgget.2 @@ -0,0 +1,217 @@ +.\" Copyright 1993 Giorgio Ciucci +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Added correction due to Nick Duffek , aeb, 960426 +.\" Modified Wed Nov 6 04:00:31 1996 by Eric S. Raymond +.\" Modified, 8 Jan 2003, Michael Kerrisk, +.\" Removed EIDRM from errors - that can't happen... +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" +.TH msgget 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +msgget \- get a System V message queue identifier +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int msgget(key_t " key ", int " msgflg ); +.fi +.SH DESCRIPTION +The +.BR msgget () +system call returns the System\ V message queue identifier associated +with the value of the +.I key +argument. +It may be used either to obtain the identifier of a previously created +message queue (when +.I msgflg +is zero and +.I key +does not have the value +.BR IPC_PRIVATE ), +or to create a new set. +.P +A new message queue is created if +.I key +has the value +.B IPC_PRIVATE +or +.I key +isn't +.BR IPC_PRIVATE , +no message queue with the given key +.I key +exists, and +.B IPC_CREAT +is specified in +.IR msgflg . +.P +If +.I msgflg +specifies both +.B IPC_CREAT +and +.B IPC_EXCL +and a message queue already exists for +.IR key , +then +.BR msgget () +fails with +.I errno +set to +.BR EEXIST . +(This is analogous to the effect of the combination +.B O_CREAT | O_EXCL +for +.BR open (2).) +.P +Upon creation, the least significant bits of the argument +.I msgflg +define the permissions of the message queue. +These permission bits have the same format and semantics +as the permissions specified for the +.I mode +argument of +.BR open (2). +(The execute permissions are not used.) +.P +If a new message queue is created, +then its associated data structure +.I msqid_ds +(see +.BR msgctl (2)) +is initialized as follows: +.IP \[bu] 3 +.I msg_perm.cuid +and +.I msg_perm.uid +are set to the effective user ID of the calling process. +.IP \[bu] +.I msg_perm.cgid +and +.I msg_perm.gid +are set to the effective group ID of the calling process. +.IP \[bu] +The least significant 9 bits of +.I msg_perm.mode +are set to the least significant 9 bits of +.IR msgflg . +.IP \[bu] +.IR msg_qnum , +.IR msg_lspid , +.IR msg_lrpid , +.IR msg_stime , +and +.I msg_rtime +are set to 0. +.IP \[bu] +.I msg_ctime +is set to the current time. +.IP \[bu] +.I msg_qbytes +is set to the system limit +.BR MSGMNB . +.P +If the message queue already exists the permissions are +verified, and a check is made to see if it is marked for +destruction. +.SH RETURN VALUE +On success, +.BR msgget () +returns the message queue identifier (a nonnegative integer). +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +A message queue exists for +.IR key , +but the calling process does not have permission to access the queue, +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EEXIST +.B IPC_CREAT +and +.B IPC_EXCL +were specified in +.IR msgflg , +but a message queue already exists for +.IR key . +.TP +.B ENOENT +No message queue exists for +.I key +and +.I msgflg +did not specify +.BR IPC_CREAT . +.TP +.B ENOMEM +A message queue has to be created but the system does not have enough +memory for the new data structure. +.TP +.B ENOSPC +A message queue has to be created but the system limit for the maximum +number of message queues +.RB ( MSGMNI ) +would be exceeded. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.SS Linux +Until Linux 2.3.20, Linux would return +.B EIDRM +for a +.BR msgget () +on a message queue scheduled for deletion. +.SH NOTES +.B IPC_PRIVATE +isn't a flag field but a +.I key_t +type. +If this special value is used for +.IR key , +the system call ignores everything but the least significant 9 bits of +.I msgflg +and creates a new message queue (on success). +.P +The following is a system limit on message queue resources affecting a +.BR msgget () +call: +.TP +.B MSGMNI +System-wide limit on the number of message queues. +Before Linux 3.19, +.\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973 +the default value for this limit was calculated using a formula +based on available system memory. +Since Linux 3.19, the default value is 32,000. +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/msgmni . +.SH BUGS +The name choice +.B IPC_PRIVATE +was perhaps unfortunate, +.B IPC_NEW +would more clearly show its function. +.SH SEE ALSO +.BR msgctl (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR ftok (3), +.BR capabilities (7), +.BR mq_overview (7), +.BR sysvipc (7) diff --git a/man/man2/msgop.2 b/man/man2/msgop.2 new file mode 100644 index 0000000..0e5addf --- /dev/null +++ b/man/man2/msgop.2 @@ -0,0 +1,684 @@ +.\" Copyright 1993 Giorgio Ciucci +.\" and Copyright 2015 Bill Pemberton +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Tue Oct 22 16:40:11 1996 by Eric S. Raymond +.\" Modified Mon Jul 10 21:09:59 2000 by aeb +.\" Modified 1 Jun 2002, Michael Kerrisk +.\" Language clean-ups. +.\" Enhanced and corrected information on msg_qbytes, MSGMNB and MSGMAX +.\" Added note on restart behavior of msgsnd() and msgrcv() +.\" Formatting clean-ups (argument and field names marked as .I +.\" instead of .B) +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" +.TH MSGOP 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +msgrcv, msgsnd \- System V message queue operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int msgsnd(int " msqid ", const void " msgp [. msgsz "], size_t " msgsz , +.BI " int " msgflg ); +.P +.BI "ssize_t msgrcv(int " msqid ", void " msgp [. msgsz "], size_t " msgsz \ +", long " msgtyp , +.BI " int " msgflg ); +.fi +.SH DESCRIPTION +The +.BR msgsnd () +and +.BR msgrcv () +system calls are used to send messages to, +and receive messages from, a System\ V message queue. +The calling process must have write permission on the message queue +in order to send a message, and read permission to receive a message. +.P +The +.I msgp +argument is a pointer to a caller-defined structure +of the following general form: +.P +.in +4n +.EX +struct msgbuf { + long mtype; /* message type, must be > 0 */ + char mtext[1]; /* message data */ +}; +.EE +.in +.P +The +.I mtext +field is an array (or other structure) whose size is specified by +.IR msgsz , +a nonnegative integer value. +Messages of zero length (i.e., no +.I mtext +field) are permitted. +The +.I mtype +field must have a strictly positive integer value. +This value can be +used by the receiving process for message selection +(see the description of +.BR msgrcv () +below). +.SS msgsnd() +The +.BR msgsnd () +system call appends a copy of the message pointed to by +.I msgp +to the message queue whose identifier is specified +by +.IR msqid . +.P +If sufficient space is available in the queue, +.BR msgsnd () +succeeds immediately. +The queue capacity is governed by the +.I msg_qbytes +field in the associated data structure for the message queue. +During queue creation this field is initialized to +.B MSGMNB +bytes, but this limit can be modified using +.BR msgctl (2). +A message queue is considered to be full if either of the following +conditions is true: +.IP \[bu] 3 +Adding a new message to the queue would cause the total number of bytes +in the queue to exceed the queue's maximum size (the +.I msg_qbytes +field). +.IP \[bu] +Adding another message to the queue would cause the total number of messages +in the queue to exceed the queue's maximum size (the +.I msg_qbytes +field). +This check is necessary to prevent an unlimited number of zero-length +messages being placed on the queue. +Although such messages contain no data, +they nevertheless consume (locked) kernel memory. +.P +If insufficient space is available in the queue, then the default +behavior of +.BR msgsnd () +is to block until space becomes available. +If +.B IPC_NOWAIT +is specified in +.IR msgflg , +then the call instead fails with the error +.BR EAGAIN . +.P +A blocked +.BR msgsnd () +call may also fail if: +.IP \[bu] 3 +the queue is removed, +in which case the system call fails with +.I errno +set to +.BR EIDRM ; +or +.IP \[bu] +a signal is caught, in which case the system call fails +with +.I errno +set to +.BR EINTR ; see +.BR signal (7). +.RB ( msgsnd () +is never automatically restarted after being interrupted by a +signal handler, regardless of the setting of the +.B SA_RESTART +flag when establishing a signal handler.) +.P +Upon successful completion the message queue data structure is updated +as follows: +.IP \[bu] 3 +.I msg_lspid +is set to the process ID of the calling process. +.IP \[bu] +.I msg_qnum +is incremented by 1. +.IP \[bu] +.I msg_stime +is set to the current time. +.SS msgrcv() +The +.BR msgrcv () +system call removes a message from the queue specified by +.I msqid +and places it in the buffer +pointed to by +.IR msgp . +.P +The argument +.I msgsz +specifies the maximum size in bytes for the member +.I mtext +of the structure pointed to by the +.I msgp +argument. +If the message text has length greater than +.IR msgsz , +then the behavior depends on whether +.B MSG_NOERROR +is specified in +.IR msgflg . +If +.B MSG_NOERROR +is specified, then +the message text will be truncated (and the truncated part will be +lost); if +.B MSG_NOERROR +is not specified, then +the message isn't removed from the queue and +the system call fails returning \-1 with +.I errno +set to +.BR E2BIG . +.P +Unless +.B MSG_COPY +is specified in +.I msgflg +(see below), +the +.I msgtyp +argument specifies the type of message requested, as follows: +.IP \[bu] 3 +If +.I msgtyp +is 0, +then the first message in the queue is read. +.IP \[bu] +If +.I msgtyp +is greater than 0, +then the first message in the queue of type +.I msgtyp +is read, unless +.B MSG_EXCEPT +was specified in +.IR msgflg , +in which case +the first message in the queue of type not equal to +.I msgtyp +will be read. +.IP \[bu] +If +.I msgtyp +is less than 0, +then the first message in the queue with the lowest type less than or +equal to the absolute value of +.I msgtyp +will be read. +.P +The +.I msgflg +argument is a bit mask constructed by ORing together zero or more +of the following flags: +.TP +.B IPC_NOWAIT +Return immediately if no message of the requested type is in the queue. +The system call fails with +.I errno +set to +.BR ENOMSG . +.TP +.BR MSG_COPY " (since Linux 3.8)" +.\" commit 4a674f34ba04a002244edaf891b5da7fc1473ae8 +Nondestructively fetch a copy of the message at the ordinal position +in the queue specified by +.I msgtyp +(messages are considered to be numbered starting at 0). +.IP +This flag must be specified in conjunction with +.BR IPC_NOWAIT , +with the result that, if there is no message available at the given position, +the call fails immediately with the error +.BR ENOMSG . +Because they alter the meaning of +.I msgtyp +in orthogonal ways, +.B MSG_COPY +and +.B MSG_EXCEPT +may not both be specified in +.IR msgflg . +.IP +The +.B MSG_COPY +flag was added for the implementation of +the kernel checkpoint-restore facility and +is available only if the kernel was built with the +.B CONFIG_CHECKPOINT_RESTORE +option. +.TP +.B MSG_EXCEPT +Used with +.I msgtyp +greater than 0 +to read the first message in the queue with message type that differs +from +.IR msgtyp . +.TP +.B MSG_NOERROR +To truncate the message text if longer than +.I msgsz +bytes. +.P +If no message of the requested type is available and +.B IPC_NOWAIT +isn't specified in +.IR msgflg , +the calling process is blocked until one of the following conditions occurs: +.IP \[bu] 3 +A message of the desired type is placed in the queue. +.IP \[bu] +The message queue is removed from the system. +In this case, the system call fails with +.I errno +set to +.BR EIDRM . +.IP \[bu] +The calling process catches a signal. +In this case, the system call fails with +.I errno +set to +.BR EINTR . +.RB ( msgrcv () +is never automatically restarted after being interrupted by a +signal handler, regardless of the setting of the +.B SA_RESTART +flag when establishing a signal handler.) +.P +Upon successful completion the message queue data structure is updated +as follows: +.IP +.I msg_lrpid +is set to the process ID of the calling process. +.IP +.I msg_qnum +is decremented by 1. +.IP +.I msg_rtime +is set to the current time. +.SH RETURN VALUE +On success, +.BR msgsnd () +returns 0 +and +.BR msgrcv () +returns the number of bytes actually copied into the +.I mtext +array. +On failure, both functions return \-1, and set +.I errno +to indicate the error. +.SH ERRORS +.BR msgsnd () +can fail with the following errors: +.TP +.B EACCES +The calling process does not have write permission on the message queue, +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EAGAIN +The message can't be sent due to the +.I msg_qbytes +limit for the queue and +.B IPC_NOWAIT +was specified in +.IR msgflg . +.TP +.B EFAULT +The address pointed to by +.I msgp +isn't accessible. +.TP +.B EIDRM +The message queue was removed. +.TP +.B EINTR +Sleeping on a full message queue condition, the process caught a signal. +.TP +.B EINVAL +Invalid +.I msqid +value, or nonpositive +.I mtype +value, or +invalid +.I msgsz +value (less than 0 or greater than the system value +.BR MSGMAX ). +.TP +.B ENOMEM +The system does not have enough memory to make a copy of the +message pointed to by +.IR msgp . +.P +.BR msgrcv () +can fail with the following errors: +.TP +.B E2BIG +The message text length is greater than +.I msgsz +and +.B MSG_NOERROR +isn't specified in +.IR msgflg . +.TP +.B EACCES +The calling process does not have read permission on the message queue, +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EFAULT +The address pointed to by +.I msgp +isn't accessible. +.TP +.B EIDRM +While the process was sleeping to receive a message, +the message queue was removed. +.TP +.B EINTR +While the process was sleeping to receive a message, +the process caught a signal; see +.BR signal (7). +.TP +.B EINVAL +.I msqid +was invalid, or +.I msgsz +was less than 0. +.TP +.BR EINVAL " (since Linux 3.14)" +.I msgflg +specified +.BR MSG_COPY , +but not +.BR IPC_NOWAIT . +.TP +.BR EINVAL " (since Linux 3.14)" +.I msgflg +specified both +.B MSG_COPY +and +.BR MSG_EXCEPT . +.TP +.B ENOMSG +.B IPC_NOWAIT +was specified in +.I msgflg +and no message of the requested type existed on the message queue. +.TP +.B ENOMSG +.B IPC_NOWAIT +and +.B MSG_COPY +were specified in +.I msgflg +and the queue contains less than +.I msgtyp +messages. +.TP +.BR ENOSYS " (since Linux 3.8)" +Both +.B MSG_COPY +and +.B IPC_NOWAIT +were specified in +.IR msgflg , +and this kernel was configured without +.BR CONFIG_CHECKPOINT_RESTORE . +.SH STANDARDS +POSIX.1-2008. +.P +The +.B MSG_EXCEPT +and +.B MSG_COPY +flags are Linux-specific; +their definitions can be obtained by defining the +.B _GNU_SOURCE +.\" MSG_COPY since glibc 2.18 +feature test macro. +.SH HISTORY +POSIX.1-2001, SVr4. +.P +The +.I msgp +argument is declared as \fIstruct msgbuf\ *\fP in +glibc 2.0 and 2.1. +It is declared as \fIvoid\ *\fP +in glibc 2.2 and later, as required by SUSv2 and SUSv3. +.SH NOTES +The following limits on message queue resources affect the +.BR msgsnd () +call: +.TP +.B MSGMAX +Maximum size of a message text, in bytes (default value: 8192 bytes). +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/msgmax . +.TP +.B MSGMNB +Maximum number of bytes that can be held in a message queue +(default value: 16384 bytes). +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/msgmnb . +A privileged process +(Linux: a process with the +.B CAP_SYS_RESOURCE +capability) +can increase the size of a message queue beyond +.B MSGMNB +using the +.BR msgctl (2) +.B IPC_SET +operation. +.P +The implementation has no intrinsic system-wide limits on the +number of message headers +.RB ( MSGTQL ) +and the number of bytes in the message pool +.RB ( MSGPOOL ). +.SH BUGS +In Linux 3.13 and earlier, +if +.BR msgrcv () +was called with the +.B MSG_COPY +flag, but without +.BR IPC_NOWAIT , +and the message queue contained less than +.I msgtyp +messages, then the call would block until the next message is written +to the queue. +.\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2 +At that point, the call would return a copy of the message, +.I regardless +of whether that message was at the ordinal position +.IR msgtyp . +This bug is fixed +.\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c +in Linux 3.14. +.P +Specifying both +.B MSG_COPY +and +.B MSC_EXCEPT +in +.I msgflg +is a logical error (since these flags impose different interpretations on +.IR msgtyp ). +In Linux 3.13 and earlier, +.\" http://marc.info/?l=linux-kernel&m=139048542803605&w=2 +this error was not diagnosed by +.BR msgrcv (). +This bug is fixed +.\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c +in Linux 3.14. +.SH EXAMPLES +The program below demonstrates the use of +.BR msgsnd () +and +.BR msgrcv (). +.P +The example program is first run with the \fB\-s\fP option to send a +message and then run again with the \fB\-r\fP option to receive a +message. +.P +The following shell session shows a sample run of the program: +.P +.in +4n +.EX +.RB "$" " ./a.out \-s" +sent: a message at Wed Mar 4 16:25:45 2015 +.P +.RB "$" " ./a.out \-r" +message received: a message at Wed Mar 4 16:25:45 2015 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (msgop.c) +.EX +#include +#include +#include +#include +#include +#include +#include +\& +struct msgbuf { + long mtype; + char mtext[80]; +}; +\& +static void +usage(char *prog_name, char *msg) +{ + if (msg != NULL) + fputs(msg, stderr); +\& + fprintf(stderr, "Usage: %s [options]\en", prog_name); + fprintf(stderr, "Options are:\en"); + fprintf(stderr, "\-s send message using msgsnd()\en"); + fprintf(stderr, "\-r read message using msgrcv()\en"); + fprintf(stderr, "\-t message type (default is 1)\en"); + fprintf(stderr, "\-k message queue key (default is 1234)\en"); + exit(EXIT_FAILURE); +} +\& +static void +send_msg(int qid, int msgtype) +{ + time_t t; + struct msgbuf msg; +\& + msg.mtype = msgtype; +\& + time(&t); + snprintf(msg.mtext, sizeof(msg.mtext), "a message at %s", + ctime(&t)); +\& + if (msgsnd(qid, &msg, sizeof(msg.mtext), + IPC_NOWAIT) == \-1) + { + perror("msgsnd error"); + exit(EXIT_FAILURE); + } + printf("sent: %s\en", msg.mtext); +} +\& +static void +get_msg(int qid, int msgtype) +{ + struct msgbuf msg; +\& + if (msgrcv(qid, &msg, sizeof(msg.mtext), msgtype, + MSG_NOERROR | IPC_NOWAIT) == \-1) { + if (errno != ENOMSG) { + perror("msgrcv"); + exit(EXIT_FAILURE); + } + printf("No message available for msgrcv()\en"); + } else { + printf("message received: %s\en", msg.mtext); + } +} +\& +int +main(int argc, char *argv[]) +{ + int qid, opt; + int mode = 0; /* 1 = send, 2 = receive */ + int msgtype = 1; + int msgkey = 1234; +\& + while ((opt = getopt(argc, argv, "srt:k:")) != \-1) { + switch (opt) { + case \[aq]s\[aq]: + mode = 1; + break; + case \[aq]r\[aq]: + mode = 2; + break; + case \[aq]t\[aq]: + msgtype = atoi(optarg); + if (msgtype <= 0) + usage(argv[0], "\-t option must be greater than 0\en"); + break; + case \[aq]k\[aq]: + msgkey = atoi(optarg); + break; + default: + usage(argv[0], "Unrecognized option\en"); + } + } +\& + if (mode == 0) + usage(argv[0], "must use either \-s or \-r option\en"); +\& + qid = msgget(msgkey, IPC_CREAT | 0666); +\& + if (qid == \-1) { + perror("msgget"); + exit(EXIT_FAILURE); + } +\& + if (mode == 2) + get_msg(qid, msgtype); + else + send_msg(qid, msgtype); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR msgctl (2), +.BR msgget (2), +.BR capabilities (7), +.BR mq_overview (7), +.BR sysvipc (7) diff --git a/man/man2/msgrcv.2 b/man/man2/msgrcv.2 new file mode 100644 index 0000000..b34869e --- /dev/null +++ b/man/man2/msgrcv.2 @@ -0,0 +1 @@ +.so man2/msgop.2 diff --git a/man/man2/msgsnd.2 b/man/man2/msgsnd.2 new file mode 100644 index 0000000..b34869e --- /dev/null +++ b/man/man2/msgsnd.2 @@ -0,0 +1 @@ +.so man2/msgop.2 diff --git a/man/man2/msync.2 b/man/man2/msync.2 new file mode 100644 index 0000000..a453ead --- /dev/null +++ b/man/man2/msync.2 @@ -0,0 +1,140 @@ +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH msync 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +msync \- synchronize a file with a memory map +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int msync(void " addr [. length "], size_t " length ", int " flags ); +.fi +.SH DESCRIPTION +.BR msync () +flushes changes made to the in-core copy of a file that was mapped +into memory using +.BR mmap (2) +back to the filesystem. +Without use of this call, +there is no guarantee that changes are written back before +.BR munmap (2) +is called. +To be more precise, the part of the file that +corresponds to the memory area starting at +.I addr +and having length +.I length +is updated. +.P +The +.I flags +argument should specify exactly one of +.B MS_ASYNC +and +.BR MS_SYNC , +and may additionally include the +.B MS_INVALIDATE +bit. +These bits have the following meanings: +.TP +.B MS_ASYNC +Specifies that an update be scheduled, but the call returns immediately. +.TP +.B MS_SYNC +Requests an update and waits for it to complete. +.TP +.B MS_INVALIDATE +.\" Since Linux 2.4, this seems to be a no-op (other than the +.\" EBUSY check for VM_LOCKED). +Asks to invalidate other mappings of the same file +(so that they can be updated with the fresh values just written). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBUSY +.B MS_INVALIDATE +was specified in +.IR flags , +and a memory lock exists for the specified address range. +.TP +.B EINVAL +.I addr +is not a multiple of PAGESIZE; or any bit other than +.BR MS_ASYNC " | " MS_INVALIDATE " | " MS_SYNC +is set in +.IR flags ; +or both +.B MS_SYNC +and +.B MS_ASYNC +are set in +.IR flags . +.TP +.B ENOMEM +The indicated memory (or part of it) was not mapped. +.SH VERSIONS +According to POSIX, either +.B MS_SYNC +or +.B MS_ASYNC +must be specified in +.IR flags , +and indeed failure to include one of these flags will cause +.BR msync () +to fail on some systems. +However, Linux permits a call to +.BR msync () +that specifies neither of these flags, +with semantics that are (currently) equivalent to specifying +.BR MS_ASYNC . +(Since Linux 2.6.19, +.\" commit 204ec841fbea3e5138168edbc3a76d46747cc987 +.B MS_ASYNC +is in fact a no-op, since the kernel properly tracks dirty +pages and flushes them to storage as necessary.) +Notwithstanding the Linux behavior, +portable, future-proof applications should ensure that they specify either +.B MS_SYNC +or +.B MS_ASYNC +in +.IR flags . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +This call was introduced in Linux 1.3.21, and then used +.B EFAULT +instead of +.BR ENOMEM . +In Linux 2.4.19, this was changed to the POSIX value +.BR ENOMEM . +.P +On POSIX systems on which +.BR msync () +is available, both +.B _POSIX_MAPPED_FILES +and +.B _POSIX_SYNCHRONIZED_IO +are defined in +.I +to a value greater than 0. +(See also +.BR sysconf (3).) +.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. +.\" -1: unavailable, 0: ask using sysconf(). +.\" glibc defines them to 1. +.SH SEE ALSO +.BR mmap (2) +.P +B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391. diff --git a/man/man2/munlock.2 b/man/man2/munlock.2 new file mode 100644 index 0000000..5e5b3c7 --- /dev/null +++ b/man/man2/munlock.2 @@ -0,0 +1 @@ +.so man2/mlock.2 diff --git a/man/man2/munlockall.2 b/man/man2/munlockall.2 new file mode 100644 index 0000000..5e5b3c7 --- /dev/null +++ b/man/man2/munlockall.2 @@ -0,0 +1 @@ +.so man2/mlock.2 diff --git a/man/man2/munmap.2 b/man/man2/munmap.2 new file mode 100644 index 0000000..8902d1b --- /dev/null +++ b/man/man2/munmap.2 @@ -0,0 +1 @@ +.so man2/mmap.2 diff --git a/man/man2/name_to_handle_at.2 b/man/man2/name_to_handle_at.2 new file mode 100644 index 0000000..090521c --- /dev/null +++ b/man/man2/name_to_handle_at.2 @@ -0,0 +1 @@ +.so man2/open_by_handle_at.2 diff --git a/man/man2/nanosleep.2 b/man/man2/nanosleep.2 new file mode 100644 index 0000000..0b4bde4 --- /dev/null +++ b/man/man2/nanosleep.2 @@ -0,0 +1,221 @@ +.\" Copyright (C) Markus Kuhn, 1996 +.\" and Copyright (C) Linux Foundation, 2008, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1996-04-10 Markus Kuhn +.\" First version written +.\" Modified, 2004-10-24, aeb +.\" 2008-06-24, mtk +.\" Minor rewrites of some parts. +.\" NOTES: describe case where clock_nanosleep() can be preferable. +.\" NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP +.\" Replace crufty discussion of HZ with a pointer to time(7). +.TH nanosleep 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nanosleep \- high-resolution sleep +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int nanosleep(const struct timespec *" duration , +.BI " struct timespec *_Nullable " rem ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nanosleep (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +.BR nanosleep () +suspends the execution of the calling thread +until either at least the time specified in +.I *duration +has elapsed, or the delivery of a signal +that triggers the invocation of a handler in the calling thread or +that terminates the process. +.P +If the call is interrupted by a signal handler, +.BR nanosleep () +returns \-1, sets +.I errno +to +.BR EINTR , +and writes the remaining time into the structure pointed to by +.I rem +unless +.I rem +is NULL. +The value of +.I *rem +can then be used to call +.BR nanosleep () +again and complete the specified pause (but see NOTES). +.P +The +.BR timespec (3) +structure +is used to specify intervals of time with nanosecond precision. +.P +The value of the nanoseconds field must be in the range [0, 999999999]. +.P +Compared to +.BR sleep (3) +and +.BR usleep (3), +.BR nanosleep () +has the following advantages: +it provides a higher resolution for specifying the sleep interval; +POSIX.1 explicitly specifies that it +does not interact with signals; +and it makes the task of resuming a sleep that has been +interrupted by a signal handler easier. +.SH RETURN VALUE +On successfully sleeping for the requested duration, +.BR nanosleep () +returns 0. +If the call is interrupted by a signal handler or encounters an error, +then it returns \-1, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Problem with copying information from user space. +.TP +.B EINTR +The pause has been interrupted by a signal that was +delivered to the thread (see +.BR signal (7)). +The remaining sleep time has been written +into +.I *rem +so that the thread can easily call +.BR nanosleep () +again and continue with the pause. +.TP +.B EINVAL +The value in the +.I tv_nsec +field was not in the range [0, 999999999] or +.I tv_sec +was negative. +.SH VERSIONS +POSIX.1 specifies that +.BR nanosleep () +should measure time against the +.B CLOCK_REALTIME +clock. +However, Linux measures the time using the +.B CLOCK_MONOTONIC +clock. +.\" See also http://thread.gmane.org/gmane.linux.kernel/696854/ +.\" Subject: nanosleep() uses CLOCK_MONOTONIC, should be CLOCK_REALTIME? +.\" Date: 2008-06-22 07:35:41 GMT +This probably does not matter, since the POSIX.1 specification for +.BR clock_settime (2) +says that discontinuous changes in +.B CLOCK_REALTIME +should not affect +.BR nanosleep (): +.RS +.P +Setting the value of the +.B CLOCK_REALTIME +clock via +.BR clock_settime (2) +shall +have no effect on threads that are blocked waiting for a relative time +service based upon this clock, including the +.BR nanosleep () +function; ... +Consequently, +these time services shall expire when the requested duration elapses, +independently of the new or old value of the clock. +.RE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +In order to support applications requiring much more precise pauses +(e.g., in order to control some time-critical hardware), +.BR nanosleep () +would handle pauses of up to 2 milliseconds by busy waiting with microsecond +precision when called from a thread scheduled under a real-time policy +like +.B SCHED_FIFO +or +.BR SCHED_RR . +This special extension was removed in Linux 2.5.39, +and is thus not available in Linux 2.6.0 and later kernels. +.SH NOTES +If the +.I duration +is not an exact multiple of the granularity underlying clock (see +.BR time (7)), +then the interval will be rounded up to the next multiple. +Furthermore, after the sleep completes, there may still be a delay before +the CPU becomes free to once again execute the calling thread. +.P +The fact that +.BR nanosleep () +sleeps for a relative interval can be problematic if the call +is repeatedly restarted after being interrupted by signals, +since the time between the interruptions and restarts of the call +will lead to drift in the time when the sleep finally completes. +This problem can be avoided by using +.BR clock_nanosleep (2) +with an absolute time value. +.SH BUGS +If a program that catches signals and uses +.BR nanosleep () +receives signals at a very high rate, +then scheduling delays and rounding errors in the kernel's +calculation of the sleep interval and the returned +.I remain +value mean that the +.I remain +value may steadily +.I increase +on successive restarts of the +.BR nanosleep () +call. +To avoid such problems, use +.BR clock_nanosleep (2) +with the +.B TIMER_ABSTIME +flag to sleep to an absolute deadline. +.P +In Linux 2.4, if +.BR nanosleep () +is stopped by a signal (e.g., +.BR SIGTSTP ), +then the call fails with the error +.B EINTR +after the thread is resumed by a +.B SIGCONT +signal. +If the system call is subsequently restarted, +then the time that the thread spent in the stopped state is +.I not +counted against the sleep interval. +This problem is fixed in Linux 2.6.0 and later kernels. +.SH SEE ALSO +.BR clock_nanosleep (2), +.BR restart_syscall (2), +.BR sched_setscheduler (2), +.BR timer_create (2), +.BR sleep (3), +.BR timespec (3), +.BR usleep (3), +.BR time (7) diff --git a/man/man2/newfstatat.2 b/man/man2/newfstatat.2 new file mode 100644 index 0000000..7791269 --- /dev/null +++ b/man/man2/newfstatat.2 @@ -0,0 +1 @@ +.so man2/fstatat.2 diff --git a/man/man2/nfsservctl.2 b/man/man2/nfsservctl.2 new file mode 100644 index 0000000..70675e2 --- /dev/null +++ b/man/man2/nfsservctl.2 @@ -0,0 +1,70 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This text is in the public domain. +.\" %%%LICENSE_END +.\" +.TH nfsservctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nfsservctl \- syscall interface to kernel nfs daemon +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long nfsservctl(int " cmd ", struct nfsctl_arg *" argp , +.BI " union nfsctl_res *" resp ); +.fi +.SH DESCRIPTION +.IR Note : +Since Linux 3.1, this system call no longer exists. +It has been replaced by a set of files in the +.I nfsd +filesystem; see +.BR nfsd (7). +.P +.in +4n +.EX +/* + * These are the commands understood by nfsctl(). + */ +#define NFSCTL_SVC 0 /* This is a server process. */ +#define NFSCTL_ADDCLIENT 1 /* Add an NFS client. */ +#define NFSCTL_DELCLIENT 2 /* Remove an NFS client. */ +#define NFSCTL_EXPORT 3 /* Export a filesystem. */ +#define NFSCTL_UNEXPORT 4 /* Unexport a filesystem. */ +#define NFSCTL_UGIDUPDATE 5 /* Update a client\[aq]s UID/GID map + (only in Linux 2.4.x and earlier). */ +#define NFSCTL_GETFH 6 /* Get a file handle (used by mountd(8)) + (only in Linux 2.4.x and earlier). */ +\& +struct nfsctl_arg { + int ca_version; /* safeguard */ + union { + struct nfsctl_svc u_svc; + struct nfsctl_client u_client; + struct nfsctl_export u_export; + struct nfsctl_uidmap u_umap; + struct nfsctl_fhparm u_getfh; + unsigned int u_debug; + } u; +} +\& +union nfsctl_res { + struct knfs_fh cr_getfh; + unsigned int cr_debug; +}; +.EE +.in +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH STANDARDS +Linux. +.SH HISTORY +Removed in Linux 3.1. +Removed in glibc 2.28. +.SH SEE ALSO +.BR nfsd (7) diff --git a/man/man2/nice.2 b/man/man2/nice.2 new file mode 100644 index 0000000..0d84c8d --- /dev/null +++ b/man/man2/nice.2 @@ -0,0 +1,118 @@ +.\" Copyright (c) 1992 Drew Eckhardt , March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-11-04 by Eric S. Raymond +.\" Modified 2001-06-04 by aeb +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH nice 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nice \- change process priority +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int nice(int " inc ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nice (): +.nf + _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +.BR nice () +adds +.I inc +to the nice value for the calling thread. +(A higher nice value means a lower priority.) +.P +The range of the nice value is +19 (low priority) to \-20 (high priority). +Attempts to set a nice value outside the range are clamped to the range. +.P +Traditionally, only a privileged process could lower the nice value +(i.e., set a higher priority). +However, since Linux 2.6.12, an unprivileged process can decrease +the nice value of a target process that has a suitable +.B RLIMIT_NICE +soft limit; see +.BR getrlimit (2) +for details. +.SH RETURN VALUE +On success, the new nice value is returned (but see NOTES below). +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +A successful call can legitimately return \-1. +To detect an error, set +.I errno +to 0 before the call, and check whether it is nonzero after +.BR nice () +returns \-1. +.SH ERRORS +.TP +.B EPERM +The calling process attempted to increase its priority by +supplying a negative +.I inc +but has insufficient privileges. +Under Linux, the +.B CAP_SYS_NICE +capability is required. +(But see the discussion of the +.B RLIMIT_NICE +resource limit in +.BR setrlimit (2).) +.SH VERSIONS +.SS C library/kernel differences +POSIX.1 specifies that +.BR nice () +should return the new nice value. +However, the raw Linux system call returns 0 on success. +Likewise, the +.BR nice () +wrapper function provided in glibc 2.2.3 and earlier returns 0 on success. +.P +Since glibc 2.2.4, the +.BR nice () +wrapper function provided by glibc provides conformance to POSIX.1 by calling +.BR getpriority (2) +to obtain the new nice value, which is then returned to the caller. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.\" SVr4 documents an additional +.\" .B EINVAL +.\" error code. +.SH NOTES +For further details on the nice value, see +.BR sched (7). +.P +.IR Note : +the addition of the "autogroup" feature in Linux 2.6.38 means that +the nice value no longer has its traditional effect in many circumstances. +For details, see +.BR sched (7). +.SH SEE ALSO +.BR nice (1), +.BR renice (1), +.BR fork (2), +.BR getpriority (2), +.BR getrlimit (2), +.BR setpriority (2), +.BR capabilities (7), +.BR sched (7) diff --git a/man/man2/oldfstat.2 b/man/man2/oldfstat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man/man2/oldfstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man/man2/oldlstat.2 b/man/man2/oldlstat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man/man2/oldlstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man/man2/oldolduname.2 b/man/man2/oldolduname.2 new file mode 100644 index 0000000..450f7b1 --- /dev/null +++ b/man/man2/oldolduname.2 @@ -0,0 +1 @@ +.so man2/uname.2 diff --git a/man/man2/oldstat.2 b/man/man2/oldstat.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man/man2/oldstat.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man/man2/olduname.2 b/man/man2/olduname.2 new file mode 100644 index 0000000..450f7b1 --- /dev/null +++ b/man/man2/olduname.2 @@ -0,0 +1 @@ +.so man2/uname.2 diff --git a/man/man2/open.2 b/man/man2/open.2 new file mode 100644 index 0000000..7c408a6 --- /dev/null +++ b/man/man2/open.2 @@ -0,0 +1,1941 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2008 Greg Banks +.\" and Copyright (C) 2006, 2008, 2013, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1993-07-21 by Rik Faith +.\" Modified 1994-08-21 by Michael Haardt +.\" Modified 1996-04-13 by Andries Brouwer +.\" Modified 1996-05-13 by Thomas Koenig +.\" Modified 1996-12-20 by Michael Haardt +.\" Modified 1999-02-19 by Andries Brouwer +.\" Modified 1998-11-28 by Joseph S. Myers +.\" Modified 1999-06-03 by Michael Haardt +.\" Modified 2002-05-07 by Michael Kerrisk +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2004-12-08, mtk, reordered flags list alphabetically +.\" 2004-12-08, Martin Pool (& mtk), added O_NOATIME +.\" 2007-09-18, mtk, Added description of O_CLOEXEC + other minor edits +.\" 2008-01-03, mtk, with input from Trond Myklebust +.\" and Timo Sirainen +.\" Rewrite description of O_EXCL. +.\" 2008-01-11, Greg Banks : add more detail +.\" on O_DIRECT. +.\" 2008-02-26, Michael Haardt: Reorganized text for O_CREAT and mode +.\" +.\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and +.\" O_TTYINIT. Eventually these may need to be documented. --mtk +.\" +.TH open 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +open, openat, creat \- open and possibly create a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int open(const char *" pathname ", int " flags ", ..." +.BI " \fR/*\fP mode_t " mode " \fR*/\fP );" +.P +.BI "int creat(const char *" pathname ", mode_t " mode ); +.P +.BI "int openat(int " dirfd ", const char *" pathname ", int " flags ", ..." +.BI " \fR/*\fP mode_t " mode " \fR*/\fP );" +.P +/* Documented separately, in \c +.BR openat2 (2):\c +\& */ +.BI "int openat2(int " dirfd ", const char *" pathname , +.BI " const struct open_how *" how ", size_t " size ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR openat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +The +.BR open () +system call opens the file specified by +.IR pathname . +If the specified file does not exist, +it may optionally (if +.B O_CREAT +is specified in +.IR flags ) +be created by +.BR open (). +.P +The return value of +.BR open () +is a file descriptor, a small, nonnegative integer that is an index +to an entry in the process's table of open file descriptors. +The file descriptor is used +in subsequent system calls +(\c +.BR read (2), +.BR write (2), +.BR lseek (2), +.BR fcntl (2), +etc.) +to refer to the open file. +The file descriptor returned by a successful call will be +the lowest-numbered file descriptor not currently open for the process. +.P +By default, the new file descriptor is set to remain open across an +.BR execve (2) +(i.e., the +.B FD_CLOEXEC +file descriptor flag described in +.BR fcntl (2) +is initially disabled); the +.B O_CLOEXEC +flag, described below, can be used to change this default. +The file offset is set to the beginning of the file (see +.BR lseek (2)). +.P +A call to +.BR open () +creates a new +.IR "open file description" , +an entry in the system-wide table of open files. +The open file description records the file offset and the file status flags +(see below). +A file descriptor is a reference to an open file description; +this reference is unaffected if +.I pathname +is subsequently removed or modified to refer to a different file. +For further details on open file descriptions, see NOTES. +.P +The argument +.I flags +must include one of the following +.IR "access modes" : +.BR O_RDONLY ", " O_WRONLY ", or " O_RDWR . +These request opening the file read-only, write-only, or read/write, +respectively. +.P +In addition, zero or more file creation flags and file status flags +can be +bitwise ORed +in +.IR flags . +The +.I file creation flags +are +.BR O_CLOEXEC , +.BR O_CREAT , +.BR O_DIRECTORY , +.BR O_EXCL , +.BR O_NOCTTY , +.BR O_NOFOLLOW , +.BR O_TMPFILE , +and +.BR O_TRUNC . +The +.I file status flags +are all of the remaining flags listed below. +.\" SUSv4 divides the flags into: +.\" * Access mode +.\" * File creation +.\" * File status +.\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW) +.\" though it's not clear what the difference between "other" and +.\" "File creation" flags is. I raised an Aardvark to see if this +.\" can be clarified in SUSv4; 10 Oct 2008. +.\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67 +.\" TC1 (balloted in 2013), resolved this, so that those three constants +.\" are also categorized" as file status flags. +.\" +The distinction between these two groups of flags is that +the file creation flags affect the semantics of the open operation itself, +while the file status flags affect the semantics of subsequent I/O operations. +The file status flags can be retrieved and (in some cases) +modified; see +.BR fcntl (2) +for details. +.P +The full list of file creation flags and file status flags is as follows: +.TP +.B O_APPEND +The file is opened in append mode. +Before each +.BR write (2), +the file offset is positioned at the end of the file, +as if with +.BR lseek (2). +The modification of the file offset and the write operation +are performed as a single atomic step. +.IP +.B O_APPEND +may lead to corrupted files on NFS filesystems if more than one process +appends data to a file at once. +.\" For more background, see +.\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946 +.\" http://nfs.sourceforge.net/ +This is because NFS does not support +appending to a file, so the client kernel has to simulate it, which +can't be done without a race condition. +.TP +.B O_ASYNC +Enable signal-driven I/O: +generate a signal +.RB ( SIGIO +by default, but this can be changed via +.BR fcntl (2)) +when input or output becomes possible on this file descriptor. +This feature is available only for terminals, pseudoterminals, +sockets, and (since Linux 2.6) pipes and FIFOs. +See +.BR fcntl (2) +for further details. +See also BUGS, below. +.TP +.BR O_CLOEXEC " (since Linux 2.6.23)" +.\" NOTE! several other man pages refer to this text +Enable the close-on-exec flag for the new file descriptor. +.\" FIXME . for later review when Issue 8 is one day released... +.\" POSIX proposes to fix many APIs that provide hidden FDs +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=368 +Specifying this flag permits a program to avoid additional +.BR fcntl (2) +.B F_SETFD +operations to set the +.B FD_CLOEXEC +flag. +.IP +Note that the use of this flag is essential in some multithreaded programs, +because using a separate +.BR fcntl (2) +.B F_SETFD +operation to set the +.B FD_CLOEXEC +flag does not suffice to avoid race conditions +where one thread opens a file descriptor and +attempts to set its close-on-exec flag using +.BR fcntl (2) +at the same time as another thread does a +.BR fork (2) +plus +.BR execve (2). +Depending on the order of execution, +the race may lead to the file descriptor returned by +.BR open () +being unintentionally leaked to the program executed by the child process +created by +.BR fork (2). +(This kind of race is in principle possible for any system call +that creates a file descriptor whose close-on-exec flag should be set, +and various other Linux system calls provide an equivalent of the +.B O_CLOEXEC +flag to deal with this problem.) +.\" This flag fixes only one form of the race condition; +.\" The race can also occur with, for example, file descriptors +.\" returned by accept(), pipe(), etc. +.TP +.B O_CREAT +If +.I pathname +does not exist, create it as a regular file. +.IP +The owner (user ID) of the new file is set to the effective user ID +of the process. +.IP +The group ownership (group ID) of the new file is set either to +the effective group ID of the process (System V semantics) +or to the group ID of the parent directory (BSD semantics). +On Linux, the behavior depends on whether the +set-group-ID mode bit is set on the parent directory: +if that bit is set, then BSD semantics apply; +otherwise, System V semantics apply. +For some filesystems, the behavior also depends on the +.I bsdgroups +and +.I sysvgroups +mount options described in +.BR mount (8). +.\" As at Linux 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and +.\" XFS (since Linux 2.6.14). +.IP +The +.I mode +argument specifies the file mode bits to be applied when a new file is created. +If neither +.B O_CREAT +nor +.B O_TMPFILE +is specified in +.IR flags , +then +.I mode +is ignored (and can thus be specified as 0, or simply omitted). +The +.I mode +argument +.B must +be supplied if +.B O_CREAT +or +.B O_TMPFILE +is specified in +.IR flags ; +if it is not supplied, +some arbitrary bytes from the stack will be applied as the file mode. +.IP +The effective mode is modified by the process's +.I umask +in the usual way: in the absence of a default ACL, the mode of the +created file is +.IR "(mode\ &\ \[ti]umask)" . +.IP +Note that +.I mode +applies only to future accesses of the +newly created file; the +.BR open () +call that creates a read-only file may well return a read/write +file descriptor. +.IP +The following symbolic constants are provided for +.IR mode : +.RS +.TP 9 +.B S_IRWXU +00700 user (file owner) has read, write, and execute permission +.TP +.B S_IRUSR +00400 user has read permission +.TP +.B S_IWUSR +00200 user has write permission +.TP +.B S_IXUSR +00100 user has execute permission +.TP +.B S_IRWXG +00070 group has read, write, and execute permission +.TP +.B S_IRGRP +00040 group has read permission +.TP +.B S_IWGRP +00020 group has write permission +.TP +.B S_IXGRP +00010 group has execute permission +.TP +.B S_IRWXO +00007 others have read, write, and execute permission +.TP +.B S_IROTH +00004 others have read permission +.TP +.B S_IWOTH +00002 others have write permission +.TP +.B S_IXOTH +00001 others have execute permission +.RE +.IP +According to POSIX, the effect when other bits are set in +.I mode +is unspecified. +On Linux, the following bits are also honored in +.IR mode : +.RS +.TP 9 +.B S_ISUID +0004000 set-user-ID bit +.TP +.B S_ISGID +0002000 set-group-ID bit (see +.BR inode (7)). +.TP +.B S_ISVTX +0001000 sticky bit (see +.BR inode (7)). +.RE +.TP +.BR O_DIRECT " (since Linux 2.4.10)" +Try to minimize cache effects of the I/O to and from this file. +In general this will degrade performance, but it is useful in +special situations, such as when applications do their own caching. +File I/O is done directly to/from user-space buffers. +The +.B O_DIRECT +flag on its own makes an effort to transfer data synchronously, +but does not give the guarantees of the +.B O_SYNC +flag that data and necessary metadata are transferred. +To guarantee synchronous I/O, +.B O_SYNC +must be used in addition to +.BR O_DIRECT . +See NOTES below for further discussion. +.IP +A semantically similar (but deprecated) interface for block devices +is described in +.BR raw (8). +.TP +.B O_DIRECTORY +If \fIpathname\fP is not a directory, cause the open to fail. +.\" But see the following and its replies: +.\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2 +.\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail +.\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored. +This flag was added in Linux 2.1.126, to +avoid denial-of-service problems if +.BR opendir (3) +is called on a +FIFO or tape device. +.TP +.B O_DSYNC +Write operations on the file will complete according to the requirements of +synchronized I/O +.I data +integrity completion. +.IP +By the time +.BR write (2) +(and similar) +return, the output data +has been transferred to the underlying hardware, +along with any file metadata that would be required to retrieve that data +(i.e., as though each +.BR write (2) +was followed by a call to +.BR fdatasync (2)). +.IR "See NOTES below" . +.TP +.B O_EXCL +Ensure that this call creates the file: +if this flag is specified in conjunction with +.BR O_CREAT , +and +.I pathname +already exists, then +.BR open () +fails with the error +.BR EEXIST . +.IP +When these two flags are specified, symbolic links are not followed: +.\" POSIX.1-2001 explicitly requires this behavior. +if +.I pathname +is a symbolic link, then +.BR open () +fails regardless of where the symbolic link points. +.IP +In general, the behavior of +.B O_EXCL +is undefined if it is used without +.BR O_CREAT . +There is one exception: on Linux 2.6 and later, +.B O_EXCL +can be used without +.B O_CREAT +if +.I pathname +refers to a block device. +If the block device is in use by the system (e.g., mounted), +.BR open () +fails with the error +.BR EBUSY . +.IP +On NFS, +.B O_EXCL +is supported only when using NFSv3 or later on kernel 2.6 or later. +In NFS environments where +.B O_EXCL +support is not provided, programs that rely on it +for performing locking tasks will contain a race condition. +Portable programs that want to perform atomic file locking using a lockfile, +and need to avoid reliance on NFS support for +.BR O_EXCL , +can create a unique file on +the same filesystem (e.g., incorporating hostname and PID), and use +.BR link (2) +to make a link to the lockfile. +If +.BR link (2) +returns 0, the lock is successful. +Otherwise, use +.BR stat (2) +on the unique file to check if its link count has increased to 2, +in which case the lock is also successful. +.TP +.B O_LARGEFILE +(LFS) +Allow files whose sizes cannot be represented in an +.I off_t +(but can be represented in an +.IR off64_t ) +to be opened. +The +.B _LARGEFILE64_SOURCE +macro must be defined +(before including +.I any +header files) +in order to obtain this definition. +Setting the +.B _FILE_OFFSET_BITS +feature test macro to 64 (rather than using +.BR O_LARGEFILE ) +is the preferred +method of accessing large files on 32-bit systems (see +.BR feature_test_macros (7)). +.TP +.BR O_NOATIME " (since Linux 2.6.8)" +Do not update the file last access time +.RI ( st_atime +in the inode) +when the file is +.BR read (2). +.IP +This flag can be employed only if one of the following conditions is true: +.RS +.IP \[bu] 3 +The effective UID of the process +.\" Strictly speaking: the filesystem UID +matches the owner UID of the file. +.IP \[bu] +The calling process has the +.B CAP_FOWNER +capability in its user namespace and +the owner UID of the file has a mapping in the namespace. +.RE +.IP +This flag is intended for use by indexing or backup programs, +where its use can significantly reduce the amount of disk activity. +This flag may not be effective on all filesystems. +One example is NFS, where the server maintains the access time. +.\" The O_NOATIME flag also affects the treatment of st_atime +.\" by mmap() and readdir(2), MTK, Dec 04. +.TP +.B O_NOCTTY +If +.I pathname +refers to a terminal device\[em]see +.BR tty (4)\[em]it +will not become the process's controlling terminal even if the +process does not have one. +.TP +.B O_NOFOLLOW +If the trailing component (i.e., basename) of +.I pathname +is a symbolic link, then the open fails, with the error +.BR ELOOP . +Symbolic links in earlier components of the pathname will still be +followed. +(Note that the +.B ELOOP +error that can occur in this case is indistinguishable from the case where +an open fails because there are too many symbolic links found +while resolving components in the prefix part of the pathname.) +.IP +This flag is a FreeBSD extension, which was added in Linux 2.1.126, +and has subsequently been standardized in POSIX.1-2008. +.IP +See also +.B O_PATH +below. +.\" The headers from glibc 2.0.100 and later include a +.\" definition of this flag; \fIkernels before Linux 2.1.126 will ignore it if +.\" used\fP. +.TP +.BR O_NONBLOCK " or " O_NDELAY +When possible, the file is opened in nonblocking mode. +Neither the +.BR open () +nor any subsequent I/O operations on the file descriptor which is +returned will cause the calling process to wait. +.IP +Note that the setting of this flag has no effect on the operation of +.BR poll (2), +.BR select (2), +.BR epoll (7), +and similar, +since those interfaces merely inform the caller about whether +a file descriptor is "ready", +meaning that an I/O operation performed on +the file descriptor with the +.B O_NONBLOCK +flag +.I clear +would not block. +.IP +Note that this flag has no effect for regular files and block devices; +that is, I/O operations will (briefly) block when device activity +is required, regardless of whether +.B O_NONBLOCK +is set. +Since +.B O_NONBLOCK +semantics might eventually be implemented, +applications should not depend upon blocking behavior +when specifying this flag for regular files and block devices. +.IP +For the handling of FIFOs (named pipes), see also +.BR fifo (7). +For a discussion of the effect of +.B O_NONBLOCK +in conjunction with mandatory file locks and with file leases, see +.BR fcntl (2). +.TP +.BR O_PATH " (since Linux 2.6.39)" +.\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd +.\" commit 326be7b484843988afe57566b627fb7a70beac56 +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +.\" +.\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496 +.\" Subject: Re: [PATCH] open(2): document O_PATH +.\" Newsgroups: gmane.linux.man, gmane.linux.kernel +.\" +Obtain a file descriptor that can be used for two purposes: +to indicate a location in the filesystem tree and +to perform operations that act purely at the file descriptor level. +The file itself is not opened, and other file operations (e.g., +.BR read (2), +.BR write (2), +.BR fchmod (2), +.BR fchown (2), +.BR fgetxattr (2), +.BR ioctl (2), +.BR mmap (2)) +fail with the error +.BR EBADF . +.IP +The following operations +.I can +be performed on the resulting file descriptor: +.RS +.IP \[bu] 3 +.BR close (2). +.IP \[bu] +.BR fchdir (2), +if the file descriptor refers to a directory +(since Linux 3.5). +.\" commit 332a2e1244bd08b9e3ecd378028513396a004a24 +.IP \[bu] +.BR fstat (2) +(since Linux 3.6). +.IP \[bu] +.\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2 +.BR fstatfs (2) +(since Linux 3.12). +.\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf +.IP \[bu] +Duplicating the file descriptor +.RB ( dup (2), +.BR fcntl (2) +.BR F_DUPFD , +etc.). +.IP \[bu] +Getting and setting file descriptor flags +.RB ( fcntl (2) +.B F_GETFD +and +.BR F_SETFD ). +.IP \[bu] +Retrieving open file status flags using the +.BR fcntl (2) +.B F_GETFL +operation: the returned flags will include the bit +.BR O_PATH . +.IP \[bu] +Passing the file descriptor as the +.I dirfd +argument of +.BR openat () +and the other "*at()" system calls. +This includes +.BR linkat (2) +with +.B AT_EMPTY_PATH +(or via procfs using +.BR AT_SYMLINK_FOLLOW ) +even if the file is not a directory. +.IP \[bu] +Passing the file descriptor to another process via a UNIX domain socket +(see +.B SCM_RIGHTS +in +.BR unix (7)). +.RE +.IP +When +.B O_PATH +is specified in +.IR flags , +flag bits other than +.BR O_CLOEXEC , +.BR O_DIRECTORY , +and +.B O_NOFOLLOW +are ignored. +.IP +Opening a file or directory with the +.B O_PATH +flag requires no permissions on the object itself +(but does require execute permission on the directories in the path prefix). +Depending on the subsequent operation, +a check for suitable file permissions may be performed (e.g., +.BR fchdir (2) +requires execute permission on the directory referred to +by its file descriptor argument). +By contrast, +obtaining a reference to a filesystem object by opening it with the +.B O_RDONLY +flag requires that the caller have read permission on the object, +even when the subsequent operation (e.g., +.BR fchdir (2), +.BR fstat (2)) +does not require read permission on the object. +.IP +If +.I pathname +is a symbolic link and the +.B O_NOFOLLOW +flag is also specified, +then the call returns a file descriptor referring to the symbolic link. +This file descriptor can be used as the +.I dirfd +argument in calls to +.BR fchownat (2), +.BR fstatat (2), +.BR linkat (2), +and +.BR readlinkat (2) +with an empty pathname to have the calls operate on the symbolic link. +.IP +If +.I pathname +refers to an automount point that has not yet been triggered, so no +other filesystem is mounted on it, then the call returns a file +descriptor referring to the automount directory without triggering a mount. +.BR fstatfs (2) +can then be used to determine if it is, in fact, an untriggered +automount point +.RB ( ".f_type == AUTOFS_SUPER_MAGIC" ). +.IP +One use of +.B O_PATH +for regular files is to provide the equivalent of POSIX.1's +.B O_EXEC +functionality. +This permits us to open a file for which we have execute +permission but not read permission, and then execute that file, +with steps something like the following: +.IP +.in +4n +.EX +char buf[PATH_MAX]; +fd = open("some_prog", O_PATH); +snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd); +execl(buf, "some_prog", (char *) NULL); +.EE +.in +.IP +An +.B O_PATH +file descriptor can also be passed as the argument of +.BR fexecve (3). +.TP +.B O_SYNC +Write operations on the file will complete according to the requirements of +synchronized I/O +.I file +integrity completion +(by contrast with the +synchronized I/O +.I data +integrity completion +provided by +.BR O_DSYNC .) +.IP +By the time +.BR write (2) +(or similar) +returns, the output data and associated file metadata +have been transferred to the underlying hardware +(i.e., as though each +.BR write (2) +was followed by a call to +.BR fsync (2)). +.IR "See NOTES below" . +.TP +.BR O_TMPFILE " (since Linux 3.11)" +.\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e +.\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e +.\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd +Create an unnamed temporary regular file. +The +.I pathname +argument specifies a directory; +an unnamed inode will be created in that directory's filesystem. +Anything written to the resulting file will be lost when +the last file descriptor is closed, unless the file is given a name. +.IP +.B O_TMPFILE +must be specified with one of +.B O_RDWR +or +.B O_WRONLY +and, optionally, +.BR O_EXCL . +If +.B O_EXCL +is not specified, then +.BR linkat (2) +can be used to link the temporary file into the filesystem, making it +permanent, using code like the following: +.IP +.in +4n +.EX +char path[PATH_MAX]; +fd = open("/path/to/dir", O_TMPFILE | O_RDWR, + S_IRUSR | S_IWUSR); +\& +/* File I/O on \[aq]fd\[aq]... */ +\& +linkat(fd, "", AT_FDCWD, "/path/for/file", AT_EMPTY_PATH); +\& +/* If the caller doesn\[aq]t have the CAP_DAC_READ_SEARCH + capability (needed to use AT_EMPTY_PATH with linkat(2)), + and there is a proc(5) filesystem mounted, then the + linkat(2) call above can be replaced with: +\& +snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd); +linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file", + AT_SYMLINK_FOLLOW); +*/ +.EE +.in +.IP +In this case, +the +.BR open () +.I mode +argument determines the file permission mode, as with +.BR O_CREAT . +.IP +Specifying +.B O_EXCL +in conjunction with +.B O_TMPFILE +prevents a temporary file from being linked into the filesystem +in the above manner. +(Note that the meaning of +.B O_EXCL +in this case is different from the meaning of +.B O_EXCL +otherwise.) +.IP +There are two main use cases for +.\" Inspired by http://lwn.net/Articles/559147/ +.BR O_TMPFILE : +.RS +.IP \[bu] 3 +Improved +.BR tmpfile (3) +functionality: race-free creation of temporary files that +(1) are automatically deleted when closed; +(2) can never be reached via any pathname; +(3) are not subject to symlink attacks; and +(4) do not require the caller to devise unique names. +.IP \[bu] +Creating a file that is initially invisible, which is then populated +with data and adjusted to have appropriate filesystem attributes +.RB ( fchown (2), +.BR fchmod (2), +.BR fsetxattr (2), +etc.) +before being atomically linked into the filesystem +in a fully formed state (using +.BR linkat (2) +as described above). +.RE +.IP +.B O_TMPFILE +requires support by the underlying filesystem; +only a subset of Linux filesystems provide that support. +In the initial implementation, support was provided in +the ext2, ext3, ext4, UDF, Minix, and tmpfs filesystems. +.\" To check for support, grep for "tmpfile" in kernel sources +Support for other filesystems has subsequently been added as follows: +XFS (Linux 3.15); +.\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788 +.\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe +Btrfs (Linux 3.16); +.\" commit ef3b9af50bfa6a1f02cd7b3f5124b712b1ba3e3c +F2FS (Linux 3.16); +.\" commit 50732df02eefb39ab414ef655979c2c9b64ad21c +and ubifs (Linux 4.9) +.TP +.B O_TRUNC +If the file already exists and is a regular file and the access mode allows +writing (i.e., is +.B O_RDWR +or +.BR O_WRONLY ) +it will be truncated to length 0. +If the file is a FIFO or terminal device file, the +.B O_TRUNC +flag is ignored. +Otherwise, the effect of +.B O_TRUNC +is unspecified. +.SS creat() +A call to +.BR creat () +is equivalent to calling +.BR open () +with +.I flags +equal to +.BR O_CREAT|O_WRONLY|O_TRUNC . +.SS openat() +The +.BR openat () +system call operates in exactly the same way as +.BR open (), +except for the differences described here. +.P +The +.I dirfd +argument is used in conjunction with the +.I pathname +argument as follows: +.IP \[bu] 3 +If the pathname given in +.I pathname +is absolute, then +.I dirfd +is ignored. +.IP \[bu] +If the pathname given in +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR open ()). +.IP \[bu] +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR open () +for a relative pathname). +In this case, +.I dirfd +must be a directory that was opened for reading +.RB ( O_RDONLY ) +or using the +.B O_PATH +flag. +.P +If the pathname given in +.I pathname +is relative, and +.I dirfd +is not a valid file descriptor, an error +.RB ( EBADF ) +results. +(Specifying an invalid file descriptor number in +.I dirfd +can be used as a means to ensure that +.I pathname +is absolute.) +.\" +.SS openat2(2) +The +.BR openat2 (2) +system call is an extension of +.BR openat (), +and provides a superset of the features of +.BR openat (). +It is documented separately, in +.BR openat2 (2). +.SH RETURN VALUE +On success, +.BR open (), +.BR openat (), +and +.BR creat () +return the new file descriptor (a nonnegative integer). +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.BR open (), +.BR openat (), +and +.BR creat () +can fail with the following errors: +.TP +.B EACCES +The requested access to the file is not allowed, or search permission +is denied for one of the directories in the path prefix of +.IR pathname , +or the file did not exist yet and write access to the parent directory +is not allowed. +(See also +.BR path_resolution (7).) +.TP +.B EACCES +.\" commit 30aba6656f61ed44cba445a3c0d38b296fa9e8f5 +Where +.B O_CREAT +is specified, the +.I protected_fifos +or +.I protected_regular +sysctl is enabled, the file already exists and is a FIFO or regular file, the +owner of the file is neither the current user nor the owner of the +containing directory, and the containing directory is both world- or +group-writable and sticky. +For details, see the descriptions of +.I /proc/sys/fs/protected_fifos +and +.I /proc/sys/fs/protected_regular +in +.BR proc_sys_fs (5). +.TP +.B EBADF +.RB ( openat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EBUSY +.B O_EXCL +was specified in +.I flags +and +.I pathname +refers to a block device that is in use by the system (e.g., it is mounted). +.TP +.B EDQUOT +Where +.B O_CREAT +is specified, the file does not exist, and the user's quota of disk +blocks or inodes on the filesystem has been exhausted. +.TP +.B EEXIST +.I pathname +already exists and +.BR O_CREAT " and " O_EXCL +were used. +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EFBIG +See +.BR EOVERFLOW . +.TP +.B EINTR +While blocked waiting to complete an open of a slow device +(e.g., a FIFO; see +.BR fifo (7)), +the call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The filesystem does not support the +.B O_DIRECT +flag. +See +.B NOTES +for more information. +.TP +.B EINVAL +Invalid value in +.\" In particular, __O_TMPFILE instead of O_TMPFILE +.IR flags . +.TP +.B EINVAL +.B O_TMPFILE +was specified in +.IR flags , +but neither +.B O_WRONLY +nor +.B O_RDWR +was specified. +.TP +.B EINVAL +.B O_CREAT +was specified in +.I flags +and the final component ("basename") of the new file's +.I pathname +is invalid +(e.g., it contains characters not permitted by the underlying filesystem). +.TP +.B EINVAL +The final component ("basename") of +.I pathname +is invalid +(e.g., it contains characters not permitted by the underlying filesystem). +.TP +.B EISDIR +.I pathname +refers to a directory and the access requested involved writing +(that is, +.B O_WRONLY +or +.B O_RDWR +is set). +.TP +.B EISDIR +.I pathname +refers to an existing directory, +.B O_TMPFILE +and one of +.B O_WRONLY +or +.B O_RDWR +were specified in +.IR flags , +but this kernel version does not provide the +.B O_TMPFILE +functionality. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ELOOP +.I pathname +was a symbolic link, and +.I flags +specified +.B O_NOFOLLOW +but not +.BR O_PATH . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached +(see the description of +.B RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B ENAMETOOLONG +.I pathname +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENODEV +.I pathname +refers to a device special file and no corresponding device exists. +(This is a Linux kernel bug; in this situation +.B ENXIO +must be returned.) +.TP +.B ENOENT +.B O_CREAT +is not set and the named file does not exist. +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOENT +.I pathname +refers to a nonexistent directory, +.B O_TMPFILE +and one of +.B O_WRONLY +or +.B O_RDWR +were specified in +.IR flags , +but this kernel version does not provide the +.B O_TMPFILE +functionality. +.TP +.B ENOMEM +The named file is a FIFO, +but memory for the FIFO buffer can't be allocated because +the per-user hard limit on memory allocation for pipes has been reached +and the caller is not privileged; see +.BR pipe (7). +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +.I pathname +was to be created but the device containing +.I pathname +has no room for the new file. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and +.I pathname +was not a directory. +.TP +.B ENOTDIR +.RB ( openat ()) +.I pathname +is a relative pathname and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B ENXIO +.BR O_NONBLOCK " | " O_WRONLY +is set, the named file is a FIFO, and +no process has the FIFO open for reading. +.TP +.B ENXIO +The file is a device special file and no corresponding device exists. +.TP +.B ENXIO +The file is a UNIX domain socket. +.TP +.B EOPNOTSUPP +The filesystem containing +.I pathname +does not support +.BR O_TMPFILE . +.TP +.B EOVERFLOW +.I pathname +refers to a regular file that is too large to be opened. +The usual scenario here is that an application compiled +on a 32-bit platform without +.I \-D_FILE_OFFSET_BITS=64 +tried to open a file whose size exceeds +.I (1<<31)\-1 +bytes; +see also +.B O_LARGEFILE +above. +This is the error specified by POSIX.1; +before Linux 2.6.24, Linux gave the error +.B EFBIG +for this case. +.\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253 +.\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW" +.\" Reported 2006-10-03 +.TP +.B EPERM +The +.B O_NOATIME +flag was specified, but the effective user ID of the caller +.\" Strictly speaking, it's the filesystem UID... (MTK) +did not match the owner of the file and the caller was not privileged. +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem and write access was +requested. +.TP +.B ETXTBSY +.I pathname +refers to an executable image which is currently being executed and +write access was requested. +.TP +.B ETXTBSY +.I pathname +refers to a file that is currently in use as a swap file, and the +.B O_TRUNC +flag was specified. +.TP +.B ETXTBSY +.I pathname +refers to a file that is currently being read by the kernel (e.g., for +module/firmware loading), and write access was requested. +.TP +.B EWOULDBLOCK +The +.B O_NONBLOCK +flag was specified, and an incompatible lease was held on the file +(see +.BR fcntl (2)). +.SH VERSIONS +The (undefined) effect of +.B O_RDONLY | O_TRUNC +varies among implementations. +On many systems the file is actually truncated. +.\" Linux 2.0, 2.5: truncate +.\" Solaris 5.7, 5.8: truncate +.\" Irix 6.5: truncate +.\" Tru64 5.1B: truncate +.\" HP-UX 11.22: truncate +.\" FreeBSD 4.7: truncate +.SS Synchronized I/O +The POSIX.1-2008 "synchronized I/O" option +specifies different variants of synchronized I/O, +and specifies the +.BR open () +flags +.BR O_SYNC , +.BR O_DSYNC , +and +.B O_RSYNC +for controlling the behavior. +Regardless of whether an implementation supports this option, +it must at least support the use of +.B O_SYNC +for regular files. +.P +Linux implements +.B O_SYNC +and +.BR O_DSYNC , +but not +.BR O_RSYNC . +Somewhat incorrectly, glibc defines +.B O_RSYNC +to have the same value as +.BR O_SYNC . +.RB ( O_RSYNC +is defined in the Linux header file +.I +on HP PA-RISC, but it is not used.) +.P +.B O_SYNC +provides synchronized I/O +.I file +integrity completion, +meaning write operations will flush data and all associated metadata +to the underlying hardware. +.B O_DSYNC +provides synchronized I/O +.I data +integrity completion, +meaning write operations will flush data +to the underlying hardware, +but will only flush metadata updates that are required +to allow a subsequent read operation to complete successfully. +Data integrity completion can reduce the number of disk operations +that are required for applications that don't need the guarantees +of file integrity completion. +.P +To understand the difference between the two types of completion, +consider two pieces of file metadata: +the file last modification timestamp +.RI ( st_mtime ) +and the file length. +All write operations will update the last file modification timestamp, +but only writes that add data to the end of the +file will change the file length. +The last modification timestamp is not needed to ensure that +a read completes successfully, but the file length is. +Thus, +.B O_DSYNC +would only guarantee to flush updates to the file length metadata +(whereas +.B O_SYNC +would also always flush the last modification timestamp metadata). +.P +Before Linux 2.6.33, Linux implemented only the +.B O_SYNC +flag for +.BR open (). +However, when that flag was specified, +most filesystems actually provided the equivalent of synchronized I/O +.I data +integrity completion (i.e., +.B O_SYNC +was actually implemented as the equivalent of +.BR O_DSYNC ). +.P +Since Linux 2.6.33, proper +.B O_SYNC +support is provided. +However, to ensure backward binary compatibility, +.B O_DSYNC +was defined with the same value as the historical +.BR O_SYNC , +and +.B O_SYNC +was defined as a new (two-bit) flag value that includes the +.B O_DSYNC +flag value. +This ensures that applications compiled against +new headers get at least +.B O_DSYNC +semantics before Linux 2.6.33. +.\" +.SS C library/kernel differences +Since glibc 2.26, +the glibc wrapper function for +.BR open () +employs the +.BR openat () +system call, rather than the kernel's +.BR open () +system call. +For certain architectures, this is also true before glibc 2.26. +.\" +.SH STANDARDS +.TP +.BR open () +.TQ +.BR creat () +.TQ +.BR openat () +POSIX.1-2008. +.P +.BR openat2 (2) +Linux. +.P +The +.BR O_DIRECT , +.BR O_NOATIME , +.BR O_PATH , +and +.B O_TMPFILE +flags are Linux-specific. +One must define +.B _GNU_SOURCE +to obtain their definitions. +.P +The +.BR O_CLOEXEC , +.BR O_DIRECTORY , +and +.B O_NOFOLLOW +flags are not specified in POSIX.1-2001, +but are specified in POSIX.1-2008. +Since glibc 2.12, one can obtain their definitions by defining either +.B _POSIX_C_SOURCE +with a value greater than or equal to 200809L or +.B _XOPEN_SOURCE +with a value greater than or equal to 700. +In glibc 2.11 and earlier, one obtains the definitions by defining +.BR _GNU_SOURCE . +.SH HISTORY +.TP +.BR open () +.TQ +.BR creat () +SVr4, 4.3BSD, POSIX.1-2001. +.TP +.BR openat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. +.SH NOTES +Under Linux, the +.B O_NONBLOCK +flag is sometimes used in cases where one wants to open +but does not necessarily have the intention to read or write. +For example, +this may be used to open a device in order to get a file descriptor +for use with +.BR ioctl (2). +.P +Note that +.BR open () +can open device special files, but +.BR creat () +cannot create them; use +.BR mknod (2) +instead. +.P +If the file is newly created, its +.IR st_atime , +.IR st_ctime , +.I st_mtime +fields +(respectively, time of last access, time of last status change, and +time of last modification; see +.BR stat (2)) +are set +to the current time, and so are the +.I st_ctime +and +.I st_mtime +fields of the +parent directory. +Otherwise, if the file is modified because of the +.B O_TRUNC +flag, its +.I st_ctime +and +.I st_mtime +fields are set to the current time. +.P +The files in the +.IR /proc/ pid /fd +directory show the open file descriptors of the process with the PID +.IR pid . +The files in the +.IR /proc/ pid /fdinfo +directory show even more information about these file descriptors. +See +.BR proc (5) +for further details of both of these directories. +.P +The Linux header file +.B +doesn't define +.BR O_ASYNC ; +the (BSD-derived) +.B FASYNC +synonym is defined instead. +.\" +.\" +.SS Open file descriptions +The term open file description is the one used by POSIX to refer to the +entries in the system-wide table of open files. +In other contexts, this object is +variously also called an "open file object", +a "file handle", an "open file table entry", +or\[em]in kernel-developer parlance\[em]a +.IR "struct file" . +.P +When a file descriptor is duplicated (using +.BR dup (2) +or similar), +the duplicate refers to the same open file description +as the original file descriptor, +and the two file descriptors consequently share +the file offset and file status flags. +Such sharing can also occur between processes: +a child process created via +.BR fork (2) +inherits duplicates of its parent's file descriptors, +and those duplicates refer to the same open file descriptions. +.P +Each +.BR open () +of a file creates a new open file description; +thus, there may be multiple open file descriptions +corresponding to a file inode. +.P +On Linux, one can use the +.BR kcmp (2) +.B KCMP_FILE +operation to test whether two file descriptors +(in the same process or in two different processes) +refer to the same open file description. +.\" +.SS NFS +There are many infelicities in the protocol underlying NFS, affecting +amongst others +.BR O_SYNC " and " O_NDELAY . +.P +On NFS filesystems with UID mapping enabled, +.BR open () +may +return a file descriptor but, for example, +.BR read (2) +requests are denied +with +.BR EACCES . +This is because the client performs +.BR open () +by checking the +permissions, but UID mapping is performed by the server upon +read and write requests. +.\" +.\" +.SS FIFOs +Opening the read or write end of a FIFO blocks until the other +end is also opened (by another process or thread). +See +.BR fifo (7) +for further details. +.\" +.\" +.SS File access mode +Unlike the other values that can be specified in +.IR flags , +the +.I "access mode" +values +.BR O_RDONLY ", " O_WRONLY ", and " O_RDWR +do not specify individual bits. +Rather, they define the low order two bits of +.IR flags , +and are defined respectively as 0, 1, and 2. +In other words, the combination +.B "O_RDONLY | O_WRONLY" +is a logical error, and certainly does not have the same meaning as +.BR O_RDWR . +.P +Linux reserves the special, nonstandard access mode 3 (binary 11) in +.I flags +to mean: +check for read and write permission on the file and return a file descriptor +that can't be used for reading or writing. +This nonstandard access mode is used by some Linux drivers to return a +file descriptor that is to be used only for device-specific +.BR ioctl (2) +operations. +.\" See for example util-linux's disk-utils/setfdprm.c +.\" For some background on access mode 3, see +.\" http://thread.gmane.org/gmane.linux.kernel/653123 +.\" "[RFC] correct flags to f_mode conversion in __dentry_open" +.\" LKML, 12 Mar 2008 +.\" +.\" +.SS Rationale for openat() and other "directory file descriptor" APIs +.BR openat () +and the other system calls and library functions that take +a directory file descriptor argument +(i.e., +.BR execveat (2), +.BR faccessat (2), +.BR fanotify_mark (2), +.BR fchmodat (2), +.BR fchownat (2), +.BR fspick (2), +.BR fstatat (2), +.BR futimesat (2), +.BR linkat (2), +.BR mkdirat (2), +.BR mknodat (2), +.BR mount_setattr (2), +.BR move_mount (2), +.BR name_to_handle_at (2), +.BR open_tree (2), +.BR openat2 (2), +.BR readlinkat (2), +.BR renameat (2), +.BR renameat2 (2), +.BR statx (2), +.BR symlinkat (2), +.BR unlinkat (2), +.BR utimensat (2), +.BR mkfifoat (3), +and +.BR scandirat (3)) +address two problems with the older interfaces that preceded them. +Here, the explanation is in terms of the +.BR openat () +call, but the rationale is analogous for the other interfaces. +.P +First, +.BR openat () +allows an application to avoid race conditions that could +occur when using +.BR open () +to open files in directories other than the current working directory. +These race conditions result from the fact that some component +of the directory prefix given to +.BR open () +could be changed in parallel with the call to +.BR open (). +Suppose, for example, that we wish to create the file +.I dir1/dir2/xxx.dep +if the file +.I dir1/dir2/xxx +exists. +The problem is that between the existence check and the file-creation step, +.I dir1 +or +.I dir2 +(which might be symbolic links) +could be modified to point to a different location. +Such races can be avoided by +opening a file descriptor for the target directory, +and then specifying that file descriptor as the +.I dirfd +argument of (say) +.BR fstatat (2) +and +.BR openat (). +The use of the +.I dirfd +file descriptor also has other benefits: +.IP \[bu] 3 +the file descriptor is a stable reference to the directory, +even if the directory is renamed; and +.IP \[bu] +the open file descriptor prevents the underlying filesystem from +being dismounted, +just as when a process has a current working directory on a filesystem. +.P +Second, +.BR openat () +allows the implementation of a per-thread "current working +directory", via file descriptor(s) maintained by the application. +(This functionality can also be obtained by tricks based +on the use of +.IR /proc/self/fd/ dirfd, +but less efficiently.) +.P +The +.I dirfd +argument for these APIs can be obtained by using +.BR open () +or +.BR openat () +to open a directory (with either the +.B O_RDONLY +or the +.B O_PATH +flag). +Alternatively, such a file descriptor can be obtained by applying +.BR dirfd (3) +to a directory stream created using +.BR opendir (3). +.P +When these APIs are given a +.I dirfd +argument of +.B AT_FDCWD +or the specified pathname is absolute, +then they handle their pathname argument in the same way as +the corresponding conventional APIs. +However, in this case, several of the APIs have a +.I flags +argument that provides access to functionality that is not available with +the corresponding conventional APIs. +.\" +.\" +.SS O_DIRECT +The +.B O_DIRECT +flag may impose alignment restrictions on the length and address +of user-space buffers and the file offset of I/Os. +In Linux alignment +restrictions vary by filesystem and kernel version and might be +absent entirely. +The handling of misaligned +.B O_DIRECT +I/Os also varies; +they can either fail with +.B EINVAL +or fall back to buffered I/O. +.P +Since Linux 6.1, +.B O_DIRECT +support and alignment restrictions for a file can be queried using +.BR statx (2), +using the +.B STATX_DIOALIGN +flag. +Support for +.B STATX_DIOALIGN +varies by filesystem; +see +.BR statx (2). +.P +Some filesystems provide their own interfaces for querying +.B O_DIRECT +alignment restrictions, +for example the +.B XFS_IOC_DIOINFO +operation in +.BR xfsctl (3). +.B STATX_DIOALIGN +should be used instead when it is available. +.P +If none of the above is available, +then direct I/O support and alignment restrictions +can only be assumed from known characteristics of the filesystem, +the individual file, +the underlying storage device(s), +and the kernel version. +In Linux 2.4, +most filesystems based on block devices require that +the file offset and the length and memory address of all I/O segments +be multiples of the filesystem block size +(typically 4096 bytes). +In Linux 2.6.0, +this was relaxed to the logical block size of the block device +(typically 512 bytes). +A block device's logical block size can be determined using the +.BR ioctl (2) +.B BLKSSZGET +operation or from the shell using the command: +.P +.in +4n +.EX +blockdev \-\-getss +.EE +.in +.P +.B O_DIRECT +I/Os should never be run concurrently with the +.BR fork (2) +system call, +if the memory buffer is a private mapping +(i.e., any mapping created with the +.BR mmap (2) +.B MAP_PRIVATE +flag; +this includes memory allocated on the heap and statically allocated buffers). +Any such I/Os, whether submitted via an asynchronous I/O interface or from +another thread in the process, +should be completed before +.BR fork (2) +is called. +Failure to do so can result in data corruption and undefined behavior in +parent and child processes. +This restriction does not apply when the memory buffer for the +.B O_DIRECT +I/Os was created using +.BR shmat (2) +or +.BR mmap (2) +with the +.B MAP_SHARED +flag. +Nor does this restriction apply when the memory buffer has been advised as +.B MADV_DONTFORK +with +.BR madvise (2), +ensuring that it will not be available +to the child after +.BR fork (2). +.P +The +.B O_DIRECT +flag was introduced in SGI IRIX, where it has alignment +restrictions similar to those of Linux 2.4. +IRIX has also a +.BR fcntl (2) +call to query appropriate alignments, and sizes. +FreeBSD 4.x introduced +a flag of the same name, but without alignment restrictions. +.P +.B O_DIRECT +support was added in Linux 2.4.10. +Older Linux kernels simply ignore this flag. +Some filesystems may not implement the flag, in which case +.BR open () +fails with the error +.B EINVAL +if it is used. +.P +Applications should avoid mixing +.B O_DIRECT +and normal I/O to the same file, +and especially to overlapping byte regions in the same file. +Even when the filesystem correctly handles the coherency issues in +this situation, overall I/O throughput is likely to be slower than +using either mode alone. +Likewise, applications should avoid mixing +.BR mmap (2) +of files with direct I/O to the same files. +.P +The behavior of +.B O_DIRECT +with NFS will differ from local filesystems. +Older kernels, or +kernels configured in certain ways, may not support this combination. +The NFS protocol does not support passing the flag to the server, so +.B O_DIRECT +I/O will bypass the page cache only on the client; the server may +still cache the I/O. +The client asks the server to make the I/O +synchronous to preserve the synchronous semantics of +.BR O_DIRECT . +Some servers will perform poorly under these circumstances, especially +if the I/O size is small. +Some servers may also be configured to +lie to clients about the I/O having reached stable storage; this +will avoid the performance penalty at some risk to data integrity +in the event of server power failure. +The Linux NFS client places no alignment restrictions on +.B O_DIRECT +I/O. +.P +In summary, +.B O_DIRECT +is a potentially powerful tool that should be used with caution. +It is recommended that applications treat use of +.B O_DIRECT +as a performance option which is disabled by default. +.SH BUGS +Currently, it is not possible to enable signal-driven +I/O by specifying +.B O_ASYNC +when calling +.BR open (); +use +.BR fcntl (2) +to enable this flag. +.\" FIXME . Check bugzilla report on open(O_ASYNC) +.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993 +.P +One must check for two different error codes, +.B EISDIR +and +.BR ENOENT , +when trying to determine whether the kernel supports +.B O_TMPFILE +functionality. +.P +When both +.B O_CREAT +and +.B O_DIRECTORY +are specified in +.I flags +and the file specified by +.I pathname +does not exist, +.BR open () +will create a regular file (i.e., +.B O_DIRECTORY +is ignored). +.SH SEE ALSO +.BR chmod (2), +.BR chown (2), +.BR close (2), +.BR dup (2), +.BR fcntl (2), +.BR link (2), +.BR lseek (2), +.BR mknod (2), +.BR mmap (2), +.BR mount (2), +.BR open_by_handle_at (2), +.BR openat2 (2), +.BR read (2), +.BR socket (2), +.BR stat (2), +.BR umask (2), +.BR unlink (2), +.BR write (2), +.BR fopen (3), +.BR acl (5), +.BR fifo (7), +.BR inode (7), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/open_by_handle_at.2 b/man/man2/open_by_handle_at.2 new file mode 100644 index 0000000..eb2ffcc --- /dev/null +++ b/man/man2/open_by_handle_at.2 @@ -0,0 +1,788 @@ +.\" Copyright (c) 2014 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH open_by_handle_at 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +name_to_handle_at, open_by_handle_at \- obtain handle +for a pathname and open file via a handle +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int name_to_handle_at(int " dirfd ", const char *" pathname , +.BI " struct file_handle *" handle , +.BI " int *" mount_id ", int " flags ); +.BI "int open_by_handle_at(int " mount_fd ", struct file_handle *" handle , +.BI " int " flags ); +.fi +.SH DESCRIPTION +The +.BR name_to_handle_at () +and +.BR open_by_handle_at () +system calls split the functionality of +.BR openat (2) +into two parts: +.BR name_to_handle_at () +returns an opaque handle that corresponds to a specified file; +.BR open_by_handle_at () +opens the file corresponding to a handle returned by a previous call to +.BR name_to_handle_at () +and returns an open file descriptor. +.\" +.\" +.SS name_to_handle_at() +The +.BR name_to_handle_at () +system call returns a file handle and a mount ID corresponding to +the file specified by the +.I dirfd +and +.I pathname +arguments. +The file handle is returned via the argument +.IR handle , +which is a pointer to a structure of the following form: +.P +.in +4n +.EX +struct file_handle { + unsigned int handle_bytes; /* Size of f_handle [in, out] */ + int handle_type; /* Handle type [out] */ + unsigned char f_handle[0]; /* File identifier (sized by + caller) [out] */ +}; +.EE +.in +.P +It is the caller's responsibility to allocate the structure +with a size large enough to hold the handle returned in +.IR f_handle . +Before the call, the +.I handle_bytes +field should be initialized to contain the allocated size for +.IR f_handle . +(The constant +.BR MAX_HANDLE_SZ , +defined in +.IR , +specifies the maximum expected size for a file handle. +It is not a +guaranteed upper limit as future filesystems may require more space.) +Upon successful return, the +.I handle_bytes +field is updated to contain the number of bytes actually written to +.IR f_handle . +.P +The caller can discover the required size for the +.I file_handle +structure by making a call in which +.I handle\->handle_bytes +is zero; +in this case, the call fails with the error +.B EOVERFLOW +and +.I handle\->handle_bytes +is set to indicate the required size; +the caller can then use this information to allocate a structure +of the correct size (see EXAMPLES below). +Some care is needed here as +.B EOVERFLOW +can also indicate that no file handle is available for this particular +name in a filesystem which does normally support file-handle lookup. +This case can be detected when the +.B EOVERFLOW +error is returned without +.I handle_bytes +being increased. +.P +Other than the use of the +.I handle_bytes +field, the caller should treat the +.I file_handle +structure as an opaque data type: the +.I handle_type +and +.I f_handle +fields can be used in a subsequent call to +.BR open_by_handle_at (). +The caller can also use the opaque +.I file_handle +to compare the identity of filesystem objects +that were queried at different times and possibly +at different paths. +The +.BR fanotify (7) +subsystem can report events +with an information record containing a +.I file_handle +to identify the filesystem object. +.P +The +.I flags +argument is a bit mask constructed by ORing together zero or more of +.BR AT_HANDLE_FID , +.BR AT_EMPTY_PATH , +and +.BR AT_SYMLINK_FOLLOW , +described below. +.P +When +.I flags +contain the +.BR AT_HANDLE_FID " (since Linux 6.5)" +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8 +flag, the caller indicates that the returned +.I file_handle +is needed to identify the filesystem object, +and not for opening the file later, +so it should be expected that a subsequent call to +.BR open_by_handle_at () +with the returned +.I file_handle +may fail. +.P +Together, the +.I pathname +and +.I dirfd +arguments identify the file for which a handle is to be obtained. +There are four distinct cases: +.IP \[bu] 3 +If +.I pathname +is a nonempty string containing an absolute pathname, +then a handle is returned for the file referred to by that pathname. +In this case, +.I dirfd +is ignored. +.IP \[bu] +If +.I pathname +is a nonempty string containing a relative pathname and +.I dirfd +has the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working directory of the caller, +and a handle is returned for the file to which it refers. +.IP \[bu] +If +.I pathname +is a nonempty string containing a relative pathname and +.I dirfd +is a file descriptor referring to a directory, then +.I pathname +is interpreted relative to the directory referred to by +.IR dirfd , +and a handle is returned for the file to which it refers. +(See +.BR openat (2) +for an explanation of why "directory file descriptors" are useful.) +.IP \[bu] +If +.I pathname +is an empty string and +.I flags +specifies the value +.BR AT_EMPTY_PATH , +then +.I dirfd +can be an open file descriptor referring to any type of file, +or +.BR AT_FDCWD , +meaning the current working directory, +and a handle is returned for the file to which it refers. +.P +The +.I mount_id +argument returns an identifier for the filesystem +mount that corresponds to +.IR pathname . +This corresponds to the first field in one of the records in +.IR /proc/self/mountinfo . +Opening the pathname in the fifth field of that record yields a file +descriptor for the mount point; +that file descriptor can be used in a subsequent call to +.BR open_by_handle_at (). +.I mount_id +is returned both for a successful call and for a call that results +in the error +.BR EOVERFLOW . +.P +By default, +.BR name_to_handle_at () +does not dereference +.I pathname +if it is a symbolic link, and thus returns a handle for the link itself. +If +.B AT_SYMLINK_FOLLOW +is specified in +.IR flags , +.I pathname +is dereferenced if it is a symbolic link +(so that the call returns a handle for the file referred to by the link). +.P +.BR name_to_handle_at () +does not trigger a mount when the final component of the pathname is an +automount point. +When a filesystem supports both file handles and +automount points, a +.BR name_to_handle_at () +call on an automount point will return with error +.B EOVERFLOW +without having increased +.IR handle_bytes . +This can happen since Linux 4.13 +.\" commit 20fa19027286983ab2734b5910c4a687436e0c31 +with NFS when accessing a directory +which is on a separate filesystem on the server. +In this case, the automount can be triggered by adding a "/" to the end +of the pathname. +.SS open_by_handle_at() +The +.BR open_by_handle_at () +system call opens the file referred to by +.IR handle , +a file handle returned by a previous call to +.BR name_to_handle_at (). +.P +The +.I mount_fd +argument is a file descriptor for any object (file, directory, etc.) +in the mounted filesystem with respect to which +.I handle +should be interpreted. +The special value +.B AT_FDCWD +can be specified, meaning the current working directory of the caller. +.P +The +.I flags +argument +is as for +.BR open (2). +If +.I handle +refers to a symbolic link, the caller must specify the +.B O_PATH +flag, and the symbolic link is not dereferenced; the +.B O_NOFOLLOW +flag, if specified, is ignored. +.P +The caller must have the +.B CAP_DAC_READ_SEARCH +capability to invoke +.BR open_by_handle_at (). +.SH RETURN VALUE +On success, +.BR name_to_handle_at () +returns 0, +and +.BR open_by_handle_at () +returns a file descriptor (a nonnegative integer). +.P +In the event of an error, both system calls return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +.BR name_to_handle_at () +and +.BR open_by_handle_at () +can fail for the same errors as +.BR openat (2). +In addition, they can fail with the errors noted below. +.P +.BR name_to_handle_at () +can fail with the following errors: +.TP +.B EFAULT +.IR pathname , +.IR mount_id , +or +.I handle +points outside your accessible address space. +.TP +.B EINVAL +.I flags +includes an invalid bit value. +.TP +.B EINVAL +.I handle\->handle_bytes +is greater than +.BR MAX_HANDLE_SZ . +.TP +.B ENOENT +.I pathname +is an empty string, but +.B AT_EMPTY_PATH +was not specified in +.IR flags . +.TP +.B ENOTDIR +The file descriptor supplied in +.I dirfd +does not refer to a directory, +and it is not the case that both +.I flags +includes +.B AT_EMPTY_PATH +and +.I pathname +is an empty string. +.TP +.B EOPNOTSUPP +The filesystem does not support decoding of a pathname to a file handle. +.TP +.B EOVERFLOW +The +.I handle\->handle_bytes +value passed into the call was too small. +When this error occurs, +.I handle\->handle_bytes +is updated to indicate the required size for the handle. +.\" +.\" +.P +.BR open_by_handle_at () +can fail with the following errors: +.TP +.B EBADF +.I mount_fd +is not an open file descriptor. +.TP +.B EBADF +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I handle +points outside your accessible address space. +.TP +.B EINVAL +.I handle\->handle_bytes +is greater than +.B MAX_HANDLE_SZ +or is equal to zero. +.TP +.B ELOOP +.I handle +refers to a symbolic link, but +.B O_PATH +was not specified in +.IR flags . +.TP +.B EPERM +The caller does not have the +.B CAP_DAC_READ_SEARCH +capability. +.TP +.B ESTALE +The specified +.I handle +is not valid for opening a file. +This error will occur if, for example, the file has been deleted. +This error can also occur if the +.I handle +was acquired using the +.B AT_HANDLE_FID +flag and the filesystem does not support +.BR open_by_handle_at (). +.SH VERSIONS +FreeBSD has a broadly similar pair of system calls in the form of +.BR getfh () +and +.BR openfh (). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.39, +glibc 2.14. +.SH NOTES +A file handle can be generated in one process using +.BR name_to_handle_at () +and later used in a different process that calls +.BR open_by_handle_at (). +.P +Some filesystem don't support the translation of pathnames to +file handles, for example, +.IR /proc , +.IR /sys , +and various network filesystems. +Some filesystems support the translation of pathnames to +file handles, but do not support using those file handles in +.BR open_by_handle_at (). +.P +A file handle may become invalid ("stale") if a file is deleted, +or for other filesystem-specific reasons. +Invalid handles are notified by an +.B ESTALE +error from +.BR open_by_handle_at (). +.P +These system calls are designed for use by user-space file servers. +For example, a user-space NFS server might generate a file handle +and pass it to an NFS client. +Later, when the client wants to open the file, +it could pass the handle back to the server. +.\" https://lwn.net/Articles/375888/ +.\" "Open by handle" - Jonathan Corbet, 2010-02-23 +This sort of functionality allows a user-space file server to operate in +a stateless fashion with respect to the files it serves. +.P +If +.I pathname +refers to a symbolic link and +.I flags +does not specify +.BR AT_SYMLINK_FOLLOW , +then +.BR name_to_handle_at () +returns a handle for the link (rather than the file to which it refers). +.\" commit bcda76524cd1fa32af748536f27f674a13e56700 +The process receiving the handle can later perform operations +on the symbolic link by converting the handle to a file descriptor using +.BR open_by_handle_at () +with the +.B O_PATH +flag, and then passing the file descriptor as the +.I dirfd +argument in system calls such as +.BR readlinkat (2) +and +.BR fchownat (2). +.SS Obtaining a persistent filesystem ID +The mount IDs in +.I /proc/self/mountinfo +can be reused as filesystems are unmounted and mounted. +Therefore, the mount ID returned by +.BR name_to_handle_at () +(in +.IR *mount_id ) +should not be treated as a persistent identifier +for the corresponding mounted filesystem. +However, an application can use the information in the +.I mountinfo +record that corresponds to the mount ID +to derive a persistent identifier. +.P +For example, one can use the device name in the fifth field of the +.I mountinfo +record to search for the corresponding device UUID via the symbolic links in +.IR /dev/disks/by\-uuid . +(A more comfortable way of obtaining the UUID is to use the +.\" e.g., http://stackoverflow.com/questions/6748429/using-libblkid-to-find-uuid-of-a-partition +.BR libblkid (3) +library.) +That process can then be reversed, +using the UUID to look up the device name, +and then obtaining the corresponding mount point, +in order to produce the +.I mount_fd +argument used by +.BR open_by_handle_at (). +.SH EXAMPLES +The two programs below demonstrate the use of +.BR name_to_handle_at () +and +.BR open_by_handle_at (). +The first program +.RI ( t_name_to_handle_at.c ) +uses +.BR name_to_handle_at () +to obtain the file handle and mount ID +for the file specified in its command-line argument; +the handle and mount ID are written to standard output. +.P +The second program +.RI ( t_open_by_handle_at.c ) +reads a mount ID and file handle from standard input. +The program then employs +.BR open_by_handle_at () +to open the file using that handle. +If an optional command-line argument is supplied, then the +.I mount_fd +argument for +.BR open_by_handle_at () +is obtained by opening the directory named in that argument. +Otherwise, +.I mount_fd +is obtained by scanning +.I /proc/self/mountinfo +to find a record whose mount ID matches the mount ID +read from standard input, +and the mount directory specified in that record is opened. +(These programs do not deal with the fact that mount IDs are not persistent.) +.P +The following shell session demonstrates the use of these two programs: +.P +.in +4n +.EX +$ \fBecho \[aq]Can you please think about it?\[aq] > cecilia.txt\fP +$ \fB./t_name_to_handle_at cecilia.txt > fh\fP +$ \fB./t_open_by_handle_at < fh\fP +open_by_handle_at: Operation not permitted +$ \fBsudo ./t_open_by_handle_at < fh\fP # Need CAP_SYS_ADMIN +Read 31 bytes +$ \fBrm cecilia.txt\fP +.EE +.in +.P +Now we delete and (quickly) re-create the file so that +it has the same content and (by chance) the same inode. +Nevertheless, +.BR open_by_handle_at () +.\" Christoph Hellwig: That's why the file handles contain a generation +.\" counter that gets incremented in this case. +recognizes that the original file referred to by the file handle +no longer exists. +.P +.in +4n +.EX +$ \fBstat \-\-printf="%i\en" cecilia.txt\fP # Display inode number +4072121 +$ \fBrm cecilia.txt\fP +$ \fBecho \[aq]Can you please think about it?\[aq] > cecilia.txt\fP +$ \fBstat \-\-printf="%i\en" cecilia.txt\fP # Check inode number +4072121 +$ \fBsudo ./t_open_by_handle_at < fh\fP +open_by_handle_at: Stale NFS file handle +.EE +.in +.SS Program source: t_name_to_handle_at.c +\& +.\" SRC BEGIN (t_name_to_handle_at.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int mount_id, fhsize, flags, dirfd; + char *pathname; + struct file_handle *fhp; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s pathname\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + pathname = argv[1]; +\& + /* Allocate file_handle structure. */ +\& + fhsize = sizeof(*fhp); + fhp = malloc(fhsize); + if (fhp == NULL) + err(EXIT_FAILURE, "malloc"); +\& + /* Make an initial call to name_to_handle_at() to discover + the size required for file handle. */ +\& + dirfd = AT_FDCWD; /* For name_to_handle_at() calls */ + flags = 0; /* For name_to_handle_at() calls */ + fhp\->handle_bytes = 0; + if (name_to_handle_at(dirfd, pathname, fhp, + &mount_id, flags) != \-1 + || errno != EOVERFLOW) + { + fprintf(stderr, "Unexpected result from name_to_handle_at()\en"); + exit(EXIT_FAILURE); + } +\& + /* Reallocate file_handle structure with correct size. */ +\& + fhsize = sizeof(*fhp) + fhp\->handle_bytes; + fhp = realloc(fhp, fhsize); /* Copies fhp\->handle_bytes */ + if (fhp == NULL) + err(EXIT_FAILURE, "realloc"); +\& + /* Get file handle from pathname supplied on command line. */ +\& + if (name_to_handle_at(dirfd, pathname, fhp, &mount_id, flags) == \-1) + err(EXIT_FAILURE, "name_to_handle_at"); +\& + /* Write mount ID, file handle size, and file handle to stdout, + for later reuse by t_open_by_handle_at.c. */ +\& + printf("%d\en", mount_id); + printf("%u %d ", fhp\->handle_bytes, fhp\->handle_type); + for (size_t j = 0; j < fhp\->handle_bytes; j++) + printf(" %02x", fhp\->f_handle[j]); + printf("\en"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS Program source: t_open_by_handle_at.c +\& +.\" SRC BEGIN (t_open_by_handle_at.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +\& +/* Scan /proc/self/mountinfo to find the line whose mount ID matches + \[aq]mount_id\[aq]. (An easier way to do this is to install and use the + \[aq]libmount\[aq] library provided by the \[aq]util\-linux\[aq] project.) + Open the corresponding mount path and return the resulting file + descriptor. */ +\& +static int +open_mount_path_by_id(int mount_id) +{ + int mi_mount_id, found; + char mount_path[PATH_MAX]; + char *linep; + FILE *fp; + size_t lsize; + ssize_t nread; +\& + fp = fopen("/proc/self/mountinfo", "r"); + if (fp == NULL) + err(EXIT_FAILURE, "fopen"); +\& + found = 0; + linep = NULL; + while (!found) { + nread = getline(&linep, &lsize, fp); + if (nread == \-1) + break; +\& + nread = sscanf(linep, "%d %*d %*s %*s %s", + &mi_mount_id, mount_path); + if (nread != 2) { + fprintf(stderr, "Bad sscanf()\en"); + exit(EXIT_FAILURE); + } +\& + if (mi_mount_id == mount_id) + found = 1; + } + free(linep); +\& + fclose(fp); +\& + if (!found) { + fprintf(stderr, "Could not find mount point\en"); + exit(EXIT_FAILURE); + } +\& + return open(mount_path, O_RDONLY); +} +\& +int +main(int argc, char *argv[]) +{ + int mount_id, fd, mount_fd, handle_bytes; + char buf[1000]; +#define LINE_SIZE 100 + char line1[LINE_SIZE], line2[LINE_SIZE]; + char *nextp; + ssize_t nread; + struct file_handle *fhp; +\& + if ((argc > 1 && strcmp(argv[1], "\-\-help") == 0) || argc > 2) { + fprintf(stderr, "Usage: %s [mount\-path]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Standard input contains mount ID and file handle information: +\& + Line 1: + Line 2: + */ +\& + if (fgets(line1, sizeof(line1), stdin) == NULL || + fgets(line2, sizeof(line2), stdin) == NULL) + { + fprintf(stderr, "Missing mount_id / file handle\en"); + exit(EXIT_FAILURE); + } +\& + mount_id = atoi(line1); +\& + handle_bytes = strtoul(line2, &nextp, 0); +\& + /* Given handle_bytes, we can now allocate file_handle structure. */ +\& + fhp = malloc(sizeof(*fhp) + handle_bytes); + if (fhp == NULL) + err(EXIT_FAILURE, "malloc"); +\& + fhp\->handle_bytes = handle_bytes; +\& + fhp\->handle_type = strtoul(nextp, &nextp, 0); +\& + for (size_t j = 0; j < fhp\->handle_bytes; j++) + fhp\->f_handle[j] = strtoul(nextp, &nextp, 16); +\& + /* Obtain file descriptor for mount point, either by opening + the pathname specified on the command line, or by scanning + /proc/self/mounts to find a mount that matches the \[aq]mount_id\[aq] + that we received from stdin. */ +\& + if (argc > 1) + mount_fd = open(argv[1], O_RDONLY); + else + mount_fd = open_mount_path_by_id(mount_id); +\& + if (mount_fd == \-1) + err(EXIT_FAILURE, "opening mount fd"); +\& + /* Open file using handle and mount point. */ +\& + fd = open_by_handle_at(mount_fd, fhp, O_RDONLY); + if (fd == \-1) + err(EXIT_FAILURE, "open_by_handle_at"); +\& + /* Try reading a few bytes from the file. */ +\& + nread = read(fd, buf, sizeof(buf)); + if (nread == \-1) + err(EXIT_FAILURE, "read"); +\& + printf("Read %zd bytes\en", nread); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR open (2), +.BR libblkid (3), +.BR blkid (8), +.BR findfs (8), +.BR mount (8) +.P +The +.I libblkid +and +.I libmount +documentation in the latest +.I util\-linux +release at +.UR https://www.kernel.org/pub/linux/utils/util\-linux/ +.UE diff --git a/man/man2/openat.2 b/man/man2/openat.2 new file mode 100644 index 0000000..604e121 --- /dev/null +++ b/man/man2/openat.2 @@ -0,0 +1 @@ +.so man2/open.2 diff --git a/man/man2/openat2.2 b/man/man2/openat2.2 new file mode 100644 index 0000000..e758bd4 --- /dev/null +++ b/man/man2/openat2.2 @@ -0,0 +1,582 @@ +.\" Copyright (C) 2019 Aleksa Sarai +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH openat2 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +openat2 \- open and possibly create a file (extended) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " \ +" /* Definition of " O_* " and " S_* " constants */" +.BR "#include " " /* Definition of " RESOLVE_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "long syscall(SYS_openat2, int " dirfd ", const char *" pathname , +.BI " struct open_how *" how ", size_t " size ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR openat2 (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR openat2 () +system call is an extension of +.BR openat (2) +and provides a superset of its functionality. +.P +The +.BR openat2 () +system call opens the file specified by +.IR pathname . +If the specified file does not exist, it may optionally (if +.B O_CREAT +is specified in +.IR how.flags ) +be created. +.P +As with +.BR openat (2), +if +.I pathname +is a relative pathname, then it is interpreted relative to the +directory referred to by the file descriptor +.I dirfd +(or the current working directory of the calling process, if +.I dirfd +is the special value +.BR AT_FDCWD ). +If +.I pathname +is an absolute pathname, then +.I dirfd +is ignored (unless +.I how.resolve +contains +.BR RESOLVE_IN_ROOT , +in which case +.I pathname +is resolved relative to +.IR dirfd ). +.P +Rather than taking a single +.I flags +argument, an extensible structure (\fIhow\fP) is passed to allow for +future extensions. +The +.I size +argument must be specified as +.IR "sizeof(struct open_how)" . +.\" +.SS The open_how structure +The +.I how +argument specifies how +.I pathname +should be opened, and acts as a superset of the +.I flags +and +.I mode +arguments to +.BR openat (2). +This argument is a pointer to an +.I open_how +structure, +described in +.BR open_how (2type). +.P +Any future extensions to +.BR openat2 () +will be implemented as new fields appended to the +.I open_how +structure, +with a zero value in a new field resulting in the kernel behaving +as though that extension field was not present. +Therefore, the caller +.I must +zero-fill this structure on +initialization. +(See the "Extensibility" section of the +.B NOTES +for more detail on why this is necessary.) +.P +The fields of the +.I open_how +structure are as follows: +.TP +.I flags +This field specifies +the file creation and file status flags to use when opening the file. +All of the +.B O_* +flags defined for +.BR openat (2) +are valid +.BR openat2 () +flag values. +.IP +Whereas +.BR openat (2) +ignores unknown bits in its +.I flags +argument, +.BR openat2 () +returns an error if unknown or conflicting flags are specified in +.IR how.flags . +.TP +.I mode +This field specifies the +mode for the new file, with identical semantics to the +.I mode +argument of +.BR openat (2). +.IP +Whereas +.BR openat (2) +ignores bits other than those in the range +.I 07777 +in its +.I mode +argument, +.BR openat2 () +returns an error if +.I how.mode +contains bits other than +.IR 07777 . +Similarly, an error is returned if +.BR openat2 () +is called with a nonzero +.I how.mode +and +.I how.flags +does not contain +.B O_CREAT +or +.BR O_TMPFILE . +.TP +.I resolve +This is a bit-mask of flags that modify the way in which +.B all +components of +.I pathname +will be resolved. +(See +.BR path_resolution (7) +for background information.) +.IP +The primary use case for these flags is to allow trusted programs to restrict +how untrusted paths (or paths inside untrusted directories) are resolved. +The full list of +.I resolve +flags is as follows: +.RS +.TP +.B RESOLVE_BENEATH +.\" commit adb21d2b526f7f196b2f3fdca97d80ba05dd14a0 +Do not permit the path resolution to succeed if any component of the resolution +is not a descendant of the directory indicated by +.IR dirfd . +This causes absolute symbolic links (and absolute values of +.IR pathname ) +to be rejected. +.IP +Currently, this flag also disables magic-link resolution (see below). +However, this may change in the future. +Therefore, to ensure that magic links are not resolved, +the caller should explicitly specify +.BR RESOLVE_NO_MAGICLINKS . +.TP +.B RESOLVE_IN_ROOT +.\" commit 8db52c7e7ee1bd861b6096fcafc0fe7d0f24a994 +Treat the directory referred to by +.I dirfd +as the root directory while resolving +.IR pathname . +Absolute symbolic links are interpreted relative to +.IR dirfd . +If a prefix component of +.I pathname +equates to +.IR dirfd , +then an immediately following +.I ..\& +component likewise equates to +.I dirfd +(just as +.I /..\& +is traditionally equivalent to +.IR / ). +If +.I pathname +is an absolute path, it is also interpreted relative to +.IR dirfd . +.IP +The effect of this flag is as though the calling process had used +.BR chroot (2) +to (temporarily) modify its root directory (to the directory +referred to by +.IR dirfd ). +However, unlike +.BR chroot (2) +(which changes the filesystem root permanently for a process), +.B RESOLVE_IN_ROOT +allows a program to efficiently restrict path resolution on a per-open basis. +.IP +Currently, this flag also disables magic-link resolution. +However, this may change in the future. +Therefore, to ensure that magic links are not resolved, +the caller should explicitly specify +.BR RESOLVE_NO_MAGICLINKS . +.TP +.B RESOLVE_NO_MAGICLINKS +.\" commit 278121417a72d87fb29dd8c48801f80821e8f75a +Disallow all magic-link resolution during path resolution. +.IP +Magic links are symbolic link-like objects that are most notably found in +.BR proc (5); +examples include +.IR /proc/ pid /exe +and +.IR /proc/ pid /fd/* . +(See +.BR symlink (7) +for more details.) +.IP +Unknowingly opening magic links can be risky for some applications. +Examples of such risks include the following: +.RS +.IP \[bu] 3 +If the process opening a pathname is a controlling process that +currently has no controlling terminal (see +.BR credentials (7)), +then opening a magic link inside +.IR /proc/ pid /fd +that happens to refer to a terminal +would cause the process to acquire a controlling terminal. +.IP \[bu] +.\" From https://lwn.net/Articles/796868/: +.\" The presence of this flag will prevent a path lookup operation +.\" from traversing through one of these magic links, thus blocking +.\" (for example) attempts to escape from a container via a /proc +.\" entry for an open file descriptor. +In a containerized environment, +a magic link inside +.I /proc +may refer to an object outside the container, +and thus may provide a means to escape from the container. +.RE +.IP +Because of such risks, +an application may prefer to disable magic link resolution using the +.B RESOLVE_NO_MAGICLINKS +flag. +.IP +If the trailing component (i.e., basename) of +.I pathname +is a magic link, +.I how.resolve +contains +.BR RESOLVE_NO_MAGICLINKS , +and +.I how.flags +contains both +.B O_PATH +and +.BR O_NOFOLLOW , +then an +.B O_PATH +file descriptor referencing the magic link will be returned. +.TP +.B RESOLVE_NO_SYMLINKS +.\" commit 278121417a72d87fb29dd8c48801f80821e8f75a +Disallow resolution of symbolic links during path resolution. +This option implies +.BR RESOLVE_NO_MAGICLINKS . +.IP +If the trailing component (i.e., basename) of +.I pathname +is a symbolic link, +.I how.resolve +contains +.BR RESOLVE_NO_SYMLINKS , +and +.I how.flags +contains both +.B O_PATH +and +.BR O_NOFOLLOW , +then an +.B O_PATH +file descriptor referencing the symbolic link will be returned. +.IP +Note that the effect of the +.B RESOLVE_NO_SYMLINKS +flag, +which affects the treatment of symbolic links in all of the components of +.IR pathname , +differs from the effect of the +.B O_NOFOLLOW +file creation flag (in +.IR how.flags ), +which affects the handling of symbolic links only in the final component of +.IR pathname . +.IP +Applications that employ the +.B RESOLVE_NO_SYMLINKS +flag are encouraged to make its use configurable +(unless it is used for a specific security purpose), +as symbolic links are very widely used by end-users. +Setting this flag indiscriminately\[em]i.e., +for purposes not specifically related to security\[em]for all uses of +.BR openat2 () +may result in spurious errors on previously functional systems. +This may occur if, for example, +a system pathname that is used by an application is modified +(e.g., in a new distribution release) +so that a pathname component (now) contains a symbolic link. +.TP +.B RESOLVE_NO_XDEV +.\" commit 72ba29297e1439efaa54d9125b866ae9d15df339 +Disallow traversal of mount points during path resolution (including all bind +mounts). +Consequently, +.I pathname +must either be on the same mount as the directory referred to by +.IR dirfd , +or on the same mount as the current working directory if +.I dirfd +is specified as +.BR AT_FDCWD . +.IP +Applications that employ the +.B RESOLVE_NO_XDEV +flag are encouraged to make its use configurable (unless it is +used for a specific security purpose), +as bind mounts are widely used by end-users. +Setting this flag indiscriminately\[em]i.e., +for purposes not specifically related to security\[em]for all uses of +.BR openat2 () +may result in spurious errors on previously functional systems. +This may occur if, for example, +a system pathname that is used by an application is modified +(e.g., in a new distribution release) +so that a pathname component (now) contains a bind mount. +.TP +.B RESOLVE_CACHED +Make the open operation fail unless all path components are already present +in the kernel's lookup cache. +If any kind of revalidation or I/O is needed to satisfy the lookup, +.BR openat2 () +fails with the error +.BR EAGAIN . +This is useful in providing a fast-path open that can be performed without +resorting to thread offload, or other mechanisms that an application might +use to offload slower operations. +.RE +.IP +If any bits other than those listed above are set in +.IR how.resolve , +an error is returned. +.SH RETURN VALUE +On success, a new file descriptor is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +The set of errors returned by +.BR openat2 () +includes all of the errors returned by +.BR openat (2), +as well as the following additional errors: +.TP +.B E2BIG +An extension that this kernel does not support was specified in +.IR how . +(See the "Extensibility" section of +.B NOTES +for more detail on how extensions are handled.) +.TP +.B EAGAIN +.I how.resolve +contains either +.B RESOLVE_IN_ROOT +or +.BR RESOLVE_BENEATH , +and the kernel could not ensure that a ".." component didn't escape (due to a +race condition or potential attack). +The caller may choose to retry the +.BR openat2 () +call. +.TP +.B EAGAIN +.B RESOLVE_CACHED +was set, and the open operation cannot be performed using only cached +information. +The caller should retry without +.B RESOLVE_CACHED +set in +.IR how.resolve . +.TP +.B EINVAL +An unknown flag or invalid value was specified in +.IR how . +.TP +.B EINVAL +.I mode +is nonzero, but +.I how.flags +does not contain +.B O_CREAT +or +.BR O_TMPFILE . +.TP +.B EINVAL +.I size +was smaller than any known version of +.IR "struct open_how" . +.TP +.B ELOOP +.I how.resolve +contains +.BR RESOLVE_NO_SYMLINKS , +and one of the path components was a symbolic link (or magic link). +.TP +.B ELOOP +.I how.resolve +contains +.BR RESOLVE_NO_MAGICLINKS , +and one of the path components was a magic link. +.TP +.B EXDEV +.I how.resolve +contains either +.B RESOLVE_IN_ROOT +or +.BR RESOLVE_BENEATH , +and an escape from the root during path resolution was detected. +.TP +.B EXDEV +.I how.resolve +contains +.BR RESOLVE_NO_XDEV , +and a path component crosses a mount point. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.6. +.\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179 +.P +The semantics of +.B RESOLVE_BENEATH +were modeled after FreeBSD's +.BR O_BENEATH . +.SH NOTES +.SS Extensibility +In order to allow for future extensibility, +.BR openat2 () +requires the user-space application to specify the size of the +.I open_how +structure that it is passing. +By providing this information, it is possible for +.BR openat2 () +to provide both forwards- and backwards-compatibility, with +.I size +acting as an implicit version number. +(Because new extension fields will always +be appended, the structure size will always increase.) +This extensibility design is very similar to other system calls such as +.BR sched_setattr (2), +.BR perf_event_open (2), +and +.BR clone3 (2). +.P +If we let +.I usize +be the size of the structure as specified by the user-space application, and +.I ksize +be the size of the structure which the kernel supports, then there are +three cases to consider: +.IP \[bu] 3 +If +.I ksize +equals +.IR usize , +then there is no version mismatch and +.I how +can be used verbatim. +.IP \[bu] +If +.I ksize +is larger than +.IR usize , +then there are some extension fields that the kernel supports +which the user-space application +is unaware of. +Because a zero value in any added extension field signifies a no-op, +the kernel +treats all of the extension fields not provided by the user-space application +as having zero values. +This provides backwards-compatibility. +.IP \[bu] +If +.I ksize +is smaller than +.IR usize , +then there are some extension fields which the user-space application +is aware of but which the kernel does not support. +Because any extension field must have its zero values signify a no-op, +the kernel can +safely ignore the unsupported extension fields if they are all-zero. +If any unsupported extension fields are nonzero, then \-1 is returned and +.I errno +is set to +.BR E2BIG . +This provides forwards-compatibility. +.P +Because the definition of +.I struct open_how +may change in the future (with new fields being added when system headers are +updated), user-space applications should zero-fill +.I struct open_how +to ensure that recompiling the program with new headers will not result in +spurious errors at run time. +The simplest way is to use a designated +initializer: +.P +.in +4n +.EX +struct open_how how = { .flags = O_RDWR, + .resolve = RESOLVE_IN_ROOT }; +.EE +.in +.P +or explicitly using +.BR memset (3) +or similar: +.P +.in +4n +.EX +struct open_how how; +memset(&how, 0, sizeof(how)); +how.flags = O_RDWR; +how.resolve = RESOLVE_IN_ROOT; +.EE +.in +.P +A user-space application that wishes to determine which extensions +the running kernel supports can do so by conducting a binary search on +.I size +with a structure which has every byte nonzero (to find the largest value +which doesn't produce an error of +.BR E2BIG ). +.SH SEE ALSO +.BR openat (2), +.BR open_how (2type), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/outb.2 b/man/man2/outb.2 new file mode 100644 index 0000000..1517de9 --- /dev/null +++ b/man/man2/outb.2 @@ -0,0 +1,84 @@ +.\" Copyright (c) 1995 Paul Gortmaker +.\" (gpg109@rsphy1.anu.edu.au) +.\" Wed Nov 29 10:58:54 EST 1995 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH outb 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +outb, outw, outl, outsb, outsw, outsl, +inb, inw, inl, insb, insw, insl, +outb_p, outw_p, outl_p, inb_p, inw_p, inl_p \- port I/O +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "unsigned char inb(unsigned short " port ); +.BI "unsigned char inb_p(unsigned short " port ); +.BI "unsigned short inw(unsigned short " port ); +.BI "unsigned short inw_p(unsigned short " port ); +.BI "unsigned int inl(unsigned short " port ); +.BI "unsigned int inl_p(unsigned short " port ); +.P +.BI "void outb(unsigned char " value ", unsigned short " port ); +.BI "void outb_p(unsigned char " value ", unsigned short " port ); +.BI "void outw(unsigned short " value ", unsigned short " port ); +.BI "void outw_p(unsigned short " value ", unsigned short " port ); +.BI "void outl(unsigned int " value ", unsigned short " port ); +.BI "void outl_p(unsigned int " value ", unsigned short " port ); +.P +.BI "void insb(unsigned short " port ", void " addr [. count ], +.BI " unsigned long " count ); +.BI "void insw(unsigned short " port ", void " addr [. count ], +.BI " unsigned long " count ); +.BI "void insl(unsigned short " port ", void " addr [. count ], +.BI " unsigned long " count ); +.BI "void outsb(unsigned short " port ", const void " addr [. count ], +.BI " unsigned long " count ); +.BI "void outsw(unsigned short " port ", const void " addr [. count ], +.BI " unsigned long " count ); +.BI "void outsl(unsigned short " port ", const void " addr [. count ], +.BI " unsigned long " count ); +.fi +.SH DESCRIPTION +This family of functions is used to do low-level port input and output. +The out* functions do port output, the in* functions do port input; +the b-suffix functions are byte-width and the w-suffix functions +word-width; the _p-suffix functions pause until the I/O completes. +.P +They are primarily designed for internal kernel use, +but can be used from user space. +.\" , given the following information +.\" in addition to that given in +.\" .BR outb (9). +.P +You must compile with \fB\-O\fP or \fB\-O2\fP or similar. +The functions +are defined as inline macros, and will not be substituted in without +optimization enabled, causing unresolved references at link time. +.P +You use +.BR ioperm (2) +or alternatively +.BR iopl (2) +to tell the kernel to allow the user space application to access the +I/O ports in question. +Failure to do this will cause the application +to receive a segmentation fault. +.SH VERSIONS +.BR outb () +and friends are hardware-specific. +The +.I value +argument is passed first and the +.I port +argument is passed second, +which is the opposite order from most DOS implementations. +.SH STANDARDS +None. +.SH SEE ALSO +.BR ioperm (2), +.BR iopl (2) diff --git a/man/man2/outb_p.2 b/man/man2/outb_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/outb_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/outl.2 b/man/man2/outl.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/outl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/outl_p.2 b/man/man2/outl_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/outl_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/outsb.2 b/man/man2/outsb.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/outsb.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/outsl.2 b/man/man2/outsl.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/outsl.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/outsw.2 b/man/man2/outsw.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/outsw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/outw.2 b/man/man2/outw.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/outw.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/outw_p.2 b/man/man2/outw_p.2 new file mode 100644 index 0000000..2c63c75 --- /dev/null +++ b/man/man2/outw_p.2 @@ -0,0 +1 @@ +.so man2/outb.2 diff --git a/man/man2/pause.2 b/man/man2/pause.2 new file mode 100644 index 0000000..79df431 --- /dev/null +++ b/man/man2/pause.2 @@ -0,0 +1,50 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified Sat Jul 24 14:48:00 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995 by Mike Battersby (mib@deakin.edu.au) +.\" Modified 2000 by aeb, following Michael Kerrisk +.\" +.TH pause 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pause \- wait for signal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B int pause(void); +.fi +.SH DESCRIPTION +.BR pause () +causes the calling process (or thread) to sleep +until a signal is delivered that either terminates the process or causes +the invocation of a signal-catching function. +.SH RETURN VALUE +.BR pause () +returns only when a signal was caught and the +signal-catching function returned. +In this case, +.BR pause () +returns \-1, and +.I errno +is set to +.\" .BR ERESTARTNOHAND . +.BR EINTR . +.SH ERRORS +.TP +.B EINTR +a signal was caught and the signal-catching function returned. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR kill (2), +.BR select (2), +.BR signal (2), +.BR sigsuspend (2) diff --git a/man/man2/pciconfig_iobase.2 b/man/man2/pciconfig_iobase.2 new file mode 100644 index 0000000..5ab2995 --- /dev/null +++ b/man/man2/pciconfig_iobase.2 @@ -0,0 +1 @@ +.so man2/pciconfig_read.2 diff --git a/man/man2/pciconfig_read.2 b/man/man2/pciconfig_read.2 new file mode 100644 index 0000000..a23e30f --- /dev/null +++ b/man/man2/pciconfig_read.2 @@ -0,0 +1,122 @@ +.\" Contributed by Niki A. Rahimi, LTC Security Development +.\" narahimi@us.ibm.com +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" May be freely distributed and modified. +.\" %%%LICENSE_END +.\" +.TH pciconfig_read 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pciconfig_read, pciconfig_write, pciconfig_iobase \- +pci device information handling +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pciconfig_read(unsigned long " bus ", unsigned long " dfn , +.BI " unsigned long " off ", unsigned long " len , +.BI " unsigned char *" buf ); +.BI "int pciconfig_write(unsigned long " bus ", unsigned long " dfn , +.BI " unsigned long " off ", unsigned long " len , +.BI " unsigned char *" buf ); +.BI "int pciconfig_iobase(int " which ", unsigned long " bus , +.BI " unsigned long " devfn ); +.fi +.SH DESCRIPTION +Most of the interaction with PCI devices is already handled by the +kernel PCI layer, +and thus these calls should not normally need to be accessed from user space. +.TP +.BR pciconfig_read () +Reads to +.I buf +from device +.I dev +at offset +.I off +value. +.TP +.BR pciconfig_write () +Writes from +.I buf +to device +.I dev +at offset +.I off +value. +.TP +.BR pciconfig_iobase () +You pass it a bus/devfn pair and get a physical address for either the +memory offset (for things like prep, this is 0xc0000000), +the IO base for PIO cycles, or the ISA holes if any. +.SH RETURN VALUE +.TP +.BR pciconfig_read () +On success, zero is returned. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.TP +.BR pciconfig_write () +On success, zero is returned. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.TP +.BR pciconfig_iobase () +Returns information on locations of various I/O +regions in physical memory according to the +.I which +value. +Values for +.I which +are: +.BR IOBASE_BRIDGE_NUMBER , +.BR IOBASE_MEMORY , +.BR IOBASE_IO , +.BR IOBASE_ISA_IO , +.BR IOBASE_ISA_MEM . +.SH ERRORS +.TP +.B EINVAL +.I len +value is invalid. +This does not apply to +.BR pciconfig_iobase (). +.TP +.B EIO +I/O error. +.TP +.B ENODEV +For +.BR pciconfig_iobase (), +"hose" value is NULL. +For the other calls, could not find a slot. +.TP +.B ENOSYS +The system has not implemented these calls +.RB ( CONFIG_PCI +not defined). +.TP +.B EOPNOTSUPP +This return value is valid only for +.BR pciconfig_iobase (). +It is returned if the value for +.I which +is invalid. +.TP +.B EPERM +User does not have the +.B CAP_SYS_ADMIN +capability. +This does not apply to +.BR pciconfig_iobase (). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.0.26/2.1.11. +.SH SEE ALSO +.BR capabilities (7) diff --git a/man/man2/pciconfig_write.2 b/man/man2/pciconfig_write.2 new file mode 100644 index 0000000..5ab2995 --- /dev/null +++ b/man/man2/pciconfig_write.2 @@ -0,0 +1 @@ +.so man2/pciconfig_read.2 diff --git a/man/man2/perf_event_open.2 b/man/man2/perf_event_open.2 new file mode 100644 index 0000000..882797d --- /dev/null +++ b/man/man2/perf_event_open.2 @@ -0,0 +1,4037 @@ +.\" Copyright (c) 2012, Vincent Weaver +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" This document is based on the perf_event.h header file, the +.\" tools/perf/design.txt file, and a lot of bitter experience. +.\" +.TH perf_event_open 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +perf_event_open \- set up performance monitoring +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " PERF_* " constants */" +.BR "#include " " /* Definition of " HW_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_perf_event_open, struct perf_event_attr *" attr , +.BI " pid_t " pid ", int " cpu ", int " group_fd \ +", unsigned long " flags ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR perf_event_open (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +Given a list of parameters, +.BR perf_event_open () +returns a file descriptor, for use in subsequent system calls +(\c +.BR read (2), +.BR mmap (2), +.BR prctl (2), +.BR fcntl (2), +etc.). +.PP +A call to +.BR perf_event_open () +creates a file descriptor that allows measuring performance +information. +Each file descriptor corresponds to one +event that is measured; these can be grouped together +to measure multiple events simultaneously. +.P +Events can be enabled and disabled in two ways: via +.BR ioctl (2) +and via +.BR prctl (2). +When an event is disabled it does not count or generate overflows but does +continue to exist and maintain its count value. +.P +Events come in two flavors: counting and sampled. +A +.I counting +event is one that is used for counting the aggregate number of events +that occur. +In general, counting event results are gathered with a +.BR read (2) +call. +A +.I sampling +event periodically writes measurements to a buffer that can then +be accessed via +.BR mmap (2). +.SS Arguments +The +.I pid +and +.I cpu +arguments allow specifying which process and CPU to monitor: +.TP +.BR "pid == 0" " and " "cpu == \-1" +This measures the calling process/thread on any CPU. +.TP +.BR "pid == 0" " and " "cpu >= 0" +This measures the calling process/thread only +when running on the specified CPU. +.TP +.BR "pid > 0" " and " "cpu == \-1" +This measures the specified process/thread on any CPU. +.TP +.BR "pid > 0" " and " "cpu >= 0" +This measures the specified process/thread only +when running on the specified CPU. +.TP +.BR "pid == \-1" " and " "cpu >= 0" +This measures all processes/threads on the specified CPU. +This requires +.B CAP_PERFMON +(since Linux 5.8) or +.B CAP_SYS_ADMIN +capability or a +.I /proc/sys/kernel/perf_event_paranoid +value of less than 1. +.TP +.BR "pid == \-1" " and " "cpu == \-1" +This setting is invalid and will return an error. +.P +When +.I pid +is greater than zero, permission to perform this system call +is governed by +.B CAP_PERFMON +(since Linux 5.9) and a ptrace access mode +.B PTRACE_MODE_READ_REALCREDS +check on older Linux versions; see +.BR ptrace (2). +.P +The +.I group_fd +argument allows event groups to be created. +An event group has one event which is the group leader. +The leader is created first, with +.IR group_fd " = \-1." +The rest of the group members are created with subsequent +.BR perf_event_open () +calls with +.I group_fd +being set to the file descriptor of the group leader. +(A single event on its own is created with +.IR group_fd " = \-1" +and is considered to be a group with only 1 member.) +An event group is scheduled onto the CPU as a unit: +it will be put onto the CPU +only if all of the events in the group can be put onto the CPU. +This means that the values of the member events can be meaningfully compared +\[em]added, divided (to get ratios), and so on\[em] +with each other, +since they have counted events for the same set of executed instructions. +.P +The +.I flags +argument is formed by ORing together zero or more of the following values: +.TP +.BR PERF_FLAG_FD_CLOEXEC " (since Linux 3.14)" +.\" commit a21b0b354d4ac39be691f51c53562e2c24443d9e +This flag enables the close-on-exec flag for the created +event file descriptor, +so that the file descriptor is automatically closed on +.BR execve (2). +Setting the close-on-exec flags at creation time, rather than later with +.BR fcntl (2), +avoids potential race conditions where the calling thread invokes +.BR perf_event_open () +and +.BR fcntl (2) +at the same time as another thread calls +.BR fork (2) +then +.BR execve (2). +.TP +.B PERF_FLAG_FD_NO_GROUP +This flag tells the event to ignore the +.I group_fd +parameter except for the purpose of setting up output redirection +using the +.B PERF_FLAG_FD_OUTPUT +flag. +.TP +.BR PERF_FLAG_FD_OUTPUT " (broken since Linux 2.6.35)" +.\" commit ac9721f3f54b27a16c7e1afb2481e7ee95a70318 +This flag re-routes the event's sampled output to instead +be included in the mmap buffer of the event specified by +.IR group_fd . +.TP +.BR PERF_FLAG_PID_CGROUP " (since Linux 2.6.39)" +.\" commit e5d1367f17ba6a6fed5fd8b74e4d5720923e0c25 +This flag activates per-container system-wide monitoring. +A container +is an abstraction that isolates a set of resources for finer-grained +control (CPUs, memory, etc.). +In this mode, the event is measured +only if the thread running on the monitored CPU belongs to the designated +container (cgroup). +The cgroup is identified by passing a file descriptor +opened on its directory in the cgroupfs filesystem. +For instance, if the +cgroup to monitor is called +.IR test , +then a file descriptor opened on +.I /dev/cgroup/test +(assuming cgroupfs is mounted on +.IR /dev/cgroup ) +must be passed as the +.I pid +parameter. +cgroup monitoring is available only +for system-wide events and may therefore require extra permissions. +.P +The +.I perf_event_attr +structure provides detailed configuration information +for the event being created. +.P +.in +4n +.EX +struct perf_event_attr { + __u32 type; /* Type of event */ + __u32 size; /* Size of attribute structure */ + __u64 config; /* Type\-specific configuration */ +\& + union { + __u64 sample_period; /* Period of sampling */ + __u64 sample_freq; /* Frequency of sampling */ + }; +\& + __u64 sample_type; /* Specifies values included in sample */ + __u64 read_format; /* Specifies values returned in read */ +\& + __u64 disabled : 1, /* off by default */ + inherit : 1, /* children inherit it */ + pinned : 1, /* must always be on PMU */ + exclusive : 1, /* only group on PMU */ + exclude_user : 1, /* don\[aq]t count user */ + exclude_kernel : 1, /* don\[aq]t count kernel */ + exclude_hv : 1, /* don\[aq]t count hypervisor */ + exclude_idle : 1, /* don\[aq]t count when idle */ + mmap : 1, /* include mmap data */ + comm : 1, /* include comm data */ + freq : 1, /* use freq, not period */ + inherit_stat : 1, /* per task counts */ + enable_on_exec : 1, /* next exec enables */ + task : 1, /* trace fork/exit */ + watermark : 1, /* wakeup_watermark */ + precise_ip : 2, /* skid constraint */ + mmap_data : 1, /* non\-exec mmap data */ + sample_id_all : 1, /* sample_type all events */ + exclude_host : 1, /* don\[aq]t count in host */ + exclude_guest : 1, /* don\[aq]t count in guest */ + exclude_callchain_kernel : 1, + /* exclude kernel callchains */ + exclude_callchain_user : 1, + /* exclude user callchains */ + mmap2 : 1, /* include mmap with inode data */ + comm_exec : 1, /* flag comm events that are + due to exec */ + use_clockid : 1, /* use clockid for time fields */ + context_switch : 1, /* context switch data */ + write_backward : 1, /* Write ring buffer from end + to beginning */ + namespaces : 1, /* include namespaces data */ + ksymbol : 1, /* include ksymbol events */ + bpf_event : 1, /* include bpf events */ + aux_output : 1, /* generate AUX records + instead of events */ + cgroup : 1, /* include cgroup events */ + text_poke : 1, /* include text poke events */ + build_id : 1, /* use build id in mmap2 events */ + inherit_thread : 1, /* children only inherit */ + /* if cloned with CLONE_THREAD */ + remove_on_exec : 1, /* event is removed from task + on exec */ + sigtrap : 1, /* send synchronous SIGTRAP + on event */ +\& + __reserved_1 : 26; +\& + union { + __u32 wakeup_events; /* wakeup every n events */ + __u32 wakeup_watermark; /* bytes before wakeup */ + }; +\& + __u32 bp_type; /* breakpoint type */ +\& + union { + __u64 bp_addr; /* breakpoint address */ + __u64 kprobe_func; /* for perf_kprobe */ + __u64 uprobe_path; /* for perf_uprobe */ + __u64 config1; /* extension of config */ + }; +\& + union { + __u64 bp_len; /* breakpoint length */ + __u64 kprobe_addr; /* with kprobe_func == NULL */ + __u64 probe_offset; /* for perf_[k,u]probe */ + __u64 config2; /* extension of config1 */ + }; + __u64 branch_sample_type; /* enum perf_branch_sample_type */ + __u64 sample_regs_user; /* user regs to dump on samples */ + __u32 sample_stack_user; /* size of stack to dump on + samples */ + __s32 clockid; /* clock to use for time fields */ + __u64 sample_regs_intr; /* regs to dump on samples */ + __u32 aux_watermark; /* aux bytes before wakeup */ + __u16 sample_max_stack; /* max frames in callchain */ + __u16 __reserved_2; /* align to u64 */ + __u32 aux_sample_size; /* max aux sample size */ + __u32 __reserved_3; /* align to u64 */ + __u64 sig_data; /* user data for sigtrap */ +\& +}; +.EE +.in +.P +The fields of the +.I perf_event_attr +structure are described in more detail below: +.TP +.I type +This field specifies the overall event type. +It has one of the following values: +.RS +.TP +.B PERF_TYPE_HARDWARE +This indicates one of the "generalized" hardware events provided +by the kernel. +See the +.I config +field definition for more details. +.TP +.B PERF_TYPE_SOFTWARE +This indicates one of the software-defined events provided by the kernel +(even if no hardware support is available). +.TP +.B PERF_TYPE_TRACEPOINT +This indicates a tracepoint +provided by the kernel tracepoint infrastructure. +.TP +.B PERF_TYPE_HW_CACHE +This indicates a hardware cache event. +This has a special encoding, described in the +.I config +field definition. +.TP +.B PERF_TYPE_RAW +This indicates a "raw" implementation-specific event in the +.IR config " field." +.TP +.BR PERF_TYPE_BREAKPOINT " (since Linux 2.6.33)" +.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e +This indicates a hardware breakpoint as provided by the CPU. +Breakpoints can be read/write accesses to an address as well as +execution of an instruction address. +.TP +dynamic PMU +Since Linux 2.6.38, +.\" commit 2e80a82a49c4c7eca4e35734380f28298ba5db19 +.BR perf_event_open () +can support multiple PMUs. +To enable this, a value exported by the kernel can be used in the +.I type +field to indicate which PMU to use. +The value to use can be found in the sysfs filesystem: +there is a subdirectory per PMU instance under +.IR /sys/bus/event_source/devices . +In each subdirectory there is a +.I type +file whose content is an integer that can be used in the +.I type +field. +For instance, +.I /sys/bus/event_source/devices/cpu/type +contains the value for the core CPU PMU, which is usually 4. +.TP +.BR kprobe " and " uprobe " (since Linux 4.17)" +.\" commit 65074d43fc77bcae32776724b7fa2696923c78e4 +.\" commit e12f03d7031a977356e3d7b75a68c2185ff8d155 +.\" commit 33ea4b24277b06dbc55d7f5772a46f029600255e +These two dynamic PMUs create a kprobe/uprobe and attach it to the +file descriptor generated by perf_event_open. +The kprobe/uprobe will be destroyed on the destruction of the file descriptor. +See fields +.IR kprobe_func , +.IR uprobe_path , +.IR kprobe_addr , +and +.I probe_offset +for more details. +.RE +.TP +.I "size" +The size of the +.I perf_event_attr +structure for forward/backward compatibility. +Set this using +.I sizeof(struct perf_event_attr) +to allow the kernel to see +the struct size at the time of compilation. +.IP +The related define +.B PERF_ATTR_SIZE_VER0 +is set to 64; this was the size of the first published struct. +.B PERF_ATTR_SIZE_VER1 +is 72, corresponding to the addition of breakpoints in Linux 2.6.33. +.\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2 +.\" this was added much later when PERF_ATTR_SIZE_VER2 happened +.\" but the actual attr_size had increased in Linux 2.6.33 +.B PERF_ATTR_SIZE_VER2 +is 80 corresponding to the addition of branch sampling in Linux 3.4. +.\" commit cb5d76999029ae7a517cb07dfa732c1b5a934fc2 +.B PERF_ATTR_SIZE_VER3 +is 96 corresponding to the addition +of +.I sample_regs_user +and +.I sample_stack_user +in Linux 3.7. +.\" commit 1659d129ed014b715b0b2120e6fd929bdd33ed03 +.B PERF_ATTR_SIZE_VER4 +is 104 corresponding to the addition of +.I sample_regs_intr +in Linux 3.19. +.\" commit 60e2364e60e86e81bc6377f49779779e6120977f +.B PERF_ATTR_SIZE_VER5 +is 112 corresponding to the addition of +.I aux_watermark +in Linux 4.1. +.\" commit 1a5941312414c71dece6717da9a0fa1303127afa +.TP +.I "config" +This specifies which event you want, in conjunction with +the +.I type +field. +The +.I config1 +and +.I config2 +fields are also taken into account in cases where 64 bits is not +enough to fully specify the event. +The encoding of these fields are event dependent. +.IP +There are various ways to set the +.I config +field that are dependent on the value of the previously +described +.I type +field. +What follows are various possible settings for +.I config +separated out by +.IR type . +.IP +If +.I type +is +.BR PERF_TYPE_HARDWARE , +we are measuring one of the generalized hardware CPU events. +Not all of these are available on all platforms. +Set +.I config +to one of the following: +.RS 12 +.TP +.B PERF_COUNT_HW_CPU_CYCLES +Total cycles. +Be wary of what happens during CPU frequency scaling. +.TP +.B PERF_COUNT_HW_INSTRUCTIONS +Retired instructions. +Be careful, these can be affected by various +issues, most notably hardware interrupt counts. +.TP +.B PERF_COUNT_HW_CACHE_REFERENCES +Cache accesses. +Usually this indicates Last Level Cache accesses but this may +vary depending on your CPU. +This may include prefetches and coherency messages; again this +depends on the design of your CPU. +.TP +.B PERF_COUNT_HW_CACHE_MISSES +Cache misses. +Usually this indicates Last Level Cache misses; this is intended to be +used in conjunction with the +.B PERF_COUNT_HW_CACHE_REFERENCES +event to calculate cache miss rates. +.TP +.B PERF_COUNT_HW_BRANCH_INSTRUCTIONS +Retired branch instructions. +Prior to Linux 2.6.35, this used +the wrong event on AMD processors. +.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2 +.TP +.B PERF_COUNT_HW_BRANCH_MISSES +Mispredicted branch instructions. +.TP +.B PERF_COUNT_HW_BUS_CYCLES +Bus cycles, which can be different from total cycles. +.TP +.BR PERF_COUNT_HW_STALLED_CYCLES_FRONTEND " (since Linux 3.0)" +.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a +Stalled cycles during issue. +.TP +.BR PERF_COUNT_HW_STALLED_CYCLES_BACKEND " (since Linux 3.0)" +.\" commit 8f62242246351b5a4bc0c1f00c0c7003edea128a +Stalled cycles during retirement. +.TP +.BR PERF_COUNT_HW_REF_CPU_CYCLES " (since Linux 3.3)" +.\" commit c37e17497e01fc0f5d2d6feb5723b210b3ab8890 +Total cycles; not affected by CPU frequency scaling. +.RE +.IP +If +.I type +is +.BR PERF_TYPE_SOFTWARE , +we are measuring software events provided by the kernel. +Set +.I config +to one of the following: +.RS 12 +.TP +.B PERF_COUNT_SW_CPU_CLOCK +This reports the CPU clock, a high-resolution per-CPU timer. +.TP +.B PERF_COUNT_SW_TASK_CLOCK +This reports a clock count specific to the task that is running. +.TP +.B PERF_COUNT_SW_PAGE_FAULTS +This reports the number of page faults. +.TP +.B PERF_COUNT_SW_CONTEXT_SWITCHES +This counts context switches. +Until Linux 2.6.34, these were all reported as user-space +events, after that they are reported as happening in the kernel. +.\" commit e49a5bd38159dfb1928fd25b173bc9de4bbadb21 +.TP +.B PERF_COUNT_SW_CPU_MIGRATIONS +This reports the number of times the process +has migrated to a new CPU. +.TP +.B PERF_COUNT_SW_PAGE_FAULTS_MIN +This counts the number of minor page faults. +These did not require disk I/O to handle. +.TP +.B PERF_COUNT_SW_PAGE_FAULTS_MAJ +This counts the number of major page faults. +These required disk I/O to handle. +.TP +.BR PERF_COUNT_SW_ALIGNMENT_FAULTS " (since Linux 2.6.33)" +.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497 +This counts the number of alignment faults. +These happen when unaligned memory accesses happen; the kernel +can handle these but it reduces performance. +This happens only on some architectures (never on x86). +.TP +.BR PERF_COUNT_SW_EMULATION_FAULTS " (since Linux 2.6.33)" +.\" commit f7d7986060b2890fc26db6ab5203efbd33aa2497 +This counts the number of emulation faults. +The kernel sometimes traps on unimplemented instructions +and emulates them for user space. +This can negatively impact performance. +.TP +.BR PERF_COUNT_SW_DUMMY " (since Linux 3.12)" +.\" commit fa0097ee690693006ab1aea6c01ad3c851b65c77 +This is a placeholder event that counts nothing. +Informational sample record types such as mmap or comm +must be associated with an active event. +This dummy event allows gathering such records without requiring +a counting event. +.TP +.BR PERF_COUNT_SW_BPF_OUTPUT " (since Linux 4.4)" +.\" commit a43eec304259a6c637f4014a6d4767159b6a3aa3 +This is used to generate raw sample data from BPF. +BPF programs can write to this event using +.B bpf_perf_event_output +helper. +.TP +.BR PERF_COUNT_SW_CGROUP_SWITCHES " (since Linux 5.13)" +.\" commit d0d1dd628527c77db2391ce0293c1ed344b2365f +This counts context switches to a task in a different cgroup. +In other words, if the next task is in the same cgroup, +it won't count the switch. +.RE +.P +.RS +If +.I type +is +.BR PERF_TYPE_TRACEPOINT , +then we are measuring kernel tracepoints. +The value to use in +.I config +can be obtained from under debugfs +.I tracing/events/*/*/id +if ftrace is enabled in the kernel. +.RE +.P +.RS +If +.I type +is +.BR PERF_TYPE_HW_CACHE , +then we are measuring a hardware CPU cache event. +To calculate the appropriate +.I config +value, use the following equation: +.RS 4 +.P +.in +4n +.EX +config = (perf_hw_cache_id) | + (perf_hw_cache_op_id << 8) | + (perf_hw_cache_op_result_id << 16); +.EE +.in +.P +where +.I perf_hw_cache_id +is one of: +.RS 4 +.TP +.B PERF_COUNT_HW_CACHE_L1D +for measuring Level 1 Data Cache +.TP +.B PERF_COUNT_HW_CACHE_L1I +for measuring Level 1 Instruction Cache +.TP +.B PERF_COUNT_HW_CACHE_LL +for measuring Last-Level Cache +.TP +.B PERF_COUNT_HW_CACHE_DTLB +for measuring the Data TLB +.TP +.B PERF_COUNT_HW_CACHE_ITLB +for measuring the Instruction TLB +.TP +.B PERF_COUNT_HW_CACHE_BPU +for measuring the branch prediction unit +.TP +.BR PERF_COUNT_HW_CACHE_NODE " (since Linux 3.1)" +.\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477 +for measuring local memory accesses +.RE +.P +and +.I perf_hw_cache_op_id +is one of: +.RS 4 +.TP +.B PERF_COUNT_HW_CACHE_OP_READ +for read accesses +.TP +.B PERF_COUNT_HW_CACHE_OP_WRITE +for write accesses +.TP +.B PERF_COUNT_HW_CACHE_OP_PREFETCH +for prefetch accesses +.RE +.P +and +.I perf_hw_cache_op_result_id +is one of: +.RS 4 +.TP +.B PERF_COUNT_HW_CACHE_RESULT_ACCESS +to measure accesses +.TP +.B PERF_COUNT_HW_CACHE_RESULT_MISS +to measure misses +.RE +.RE +.P +If +.I type +is +.BR PERF_TYPE_RAW , +then a custom "raw" +.I config +value is needed. +Most CPUs support events that are not covered by the "generalized" events. +These are implementation defined; see your CPU manual (for example +the Intel Volume 3B documentation or the AMD BIOS and Kernel Developer +Guide). +The libpfm4 library can be used to translate from the name in the +architectural manuals to the raw hex value +.BR perf_event_open () +expects in this field. +.P +If +.I type +is +.BR PERF_TYPE_BREAKPOINT , +then leave +.I config +set to zero. +Its parameters are set in other places. +.P +If +.I type +is +.B kprobe +or +.BR uprobe , +set +.I retprobe +(bit 0 of +.IR config , +see +.IR /sys/bus/event_source/devices/[k,u]probe/format/retprobe ) +for kretprobe/uretprobe. +See fields +.IR kprobe_func , +.IR uprobe_path , +.IR kprobe_addr , +and +.I probe_offset +for more details. +.RE +.TP +.I kprobe_func +.TQ +.I uprobe_path +.TQ +.I kprobe_addr +.TQ +.I probe_offset +These fields describe the kprobe/uprobe for dynamic PMUs +.B kprobe +and +.BR uprobe . +For +.BR kprobe : +use +.I kprobe_func +and +.IR probe_offset , +or use +.I kprobe_addr +and leave +.I kprobe_func +as NULL. +For +.BR uprobe : +use +.I uprobe_path +and +.IR probe_offset . +.TP +.I sample_period +.TQ +.I sample_freq +A "sampling" event is one that generates an overflow notification +every N events, where N is given by +.IR sample_period . +A sampling event has +.IR sample_period " > 0." +When an overflow occurs, requested data is recorded +in the mmap buffer. +The +.I sample_type +field controls what data is recorded on each overflow. +.IP +.I sample_freq +can be used if you wish to use frequency rather than period. +In this case, you set the +.I freq +flag. +The kernel will adjust the sampling period +to try and achieve the desired rate. +The rate of adjustment is a +timer tick. +.TP +.I sample_type +The various bits in this field specify which values to include +in the sample. +They will be recorded in a ring-buffer, +which is available to user space using +.BR mmap (2). +The order in which the values are saved in the +sample are documented in the MMAP Layout subsection below; +it is not the +.I "enum perf_event_sample_format" +order. +.RS +.TP +.B PERF_SAMPLE_IP +Records instruction pointer. +.TP +.B PERF_SAMPLE_TID +Records the process and thread IDs. +.TP +.B PERF_SAMPLE_TIME +Records a timestamp. +.TP +.B PERF_SAMPLE_ADDR +Records an address, if applicable. +.TP +.B PERF_SAMPLE_READ +Record counter values for all events in a group, not just the group leader. +.TP +.B PERF_SAMPLE_CALLCHAIN +Records the callchain (stack backtrace). +.TP +.B PERF_SAMPLE_ID +Records a unique ID for the opened event's group leader. +.TP +.B PERF_SAMPLE_CPU +Records CPU number. +.TP +.B PERF_SAMPLE_PERIOD +Records the current sampling period. +.TP +.B PERF_SAMPLE_STREAM_ID +Records a unique ID for the opened event. +Unlike +.B PERF_SAMPLE_ID +the actual ID is returned, not the group leader. +This ID is the same as the one returned by +.BR PERF_FORMAT_ID . +.TP +.B PERF_SAMPLE_RAW +Records additional data, if applicable. +Usually returned by tracepoint events. +.TP +.BR PERF_SAMPLE_BRANCH_STACK " (since Linux 3.4)" +.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e +This provides a record of recent branches, as provided +by CPU branch sampling hardware (such as Intel Last Branch Record). +Not all hardware supports this feature. +.IP +See the +.I branch_sample_type +field for how to filter which branches are reported. +.TP +.BR PERF_SAMPLE_REGS_USER " (since Linux 3.7)" +.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56 +Records the current user-level CPU register state +(the values in the process before the kernel was called). +.TP +.BR PERF_SAMPLE_STACK_USER " (since Linux 3.7)" +.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7 +Records the user level stack, allowing stack unwinding. +.TP +.BR PERF_SAMPLE_WEIGHT " (since Linux 3.10)" +.\" commit c3feedf2aaf9ac8bad6f19f5d21e4ee0b4b87e9c +Records a hardware provided weight value that expresses how +costly the sampled event was. +This allows the hardware to highlight expensive events in +a profile. +.TP +.BR PERF_SAMPLE_DATA_SRC " (since Linux 3.10)" +.\" commit d6be9ad6c960f43800a6f118932bc8a5a4eadcd1 +Records the data source: where in the memory hierarchy +the data associated with the sampled instruction came from. +This is available only if the underlying hardware +supports this feature. +.TP +.BR PERF_SAMPLE_IDENTIFIER " (since Linux 3.12)" +.\" commit ff3d527cebc1fa3707c617bfe9e74f53fcfb0955 +Places the +.B SAMPLE_ID +value in a fixed position in the record, +either at the beginning (for sample events) or at the end +(if a non-sample event). +.IP +This was necessary because a sample stream may have +records from various different event sources with different +.I sample_type +settings. +Parsing the event stream properly was not possible because the +format of the record was needed to find +.BR SAMPLE_ID , +but +the format could not be found without knowing what +event the sample belonged to (causing a circular +dependency). +.IP +The +.B PERF_SAMPLE_IDENTIFIER +setting makes the event stream always parsable +by putting +.B SAMPLE_ID +in a fixed location, even though +it means having duplicate +.B SAMPLE_ID +values in records. +.TP +.BR PERF_SAMPLE_TRANSACTION " (since Linux 3.13)" +.\" commit fdfbbd07e91f8fe387140776f3fd94605f0c89e5 +Records reasons for transactional memory abort events +(for example, from Intel TSX transactional memory support). +.IP +The +.I precise_ip +setting must be greater than 0 and a transactional memory abort +event must be measured or no values will be recorded. +Also note that some perf_event measurements, such as sampled +cycle counting, may cause extraneous aborts (by causing an +interrupt during a transaction). +.TP +.BR PERF_SAMPLE_REGS_INTR " (since Linux 3.19)" +.\" commit 60e2364e60e86e81bc6377f49779779e6120977f +Records a subset of the current CPU register state +as specified by +.IR sample_regs_intr . +Unlike +.B PERF_SAMPLE_REGS_USER +the register values will return kernel register +state if the overflow happened while kernel +code is running. +If the CPU supports hardware sampling of +register state (i.e., PEBS on Intel x86) and +.I precise_ip +is set higher than zero then the register +values returned are those captured by +hardware at the time of the sampled +instruction's retirement. +.TP +.BR PERF_SAMPLE_PHYS_ADDR " (since Linux 4.13)" +.\" commit fc7ce9c74c3ad232b084d80148654f926d01ece7 +Records physical address of data like in +.BR PERF_SAMPLE_ADDR . +.TP +.BR PERF_SAMPLE_CGROUP " (since Linux 5.7)" +.\" commit 96aaab686505c449e24d76e76507290dcc30e008 +Records (perf_event) cgroup ID of the process. +This corresponds to the +.I id +field in the +.B PERF_RECORD_CGROUP +event. +.TP +.BR PERF_SAMPLE_DATA_PAGE_SIZE " (since Linux 5.11)" +.\" commit 8d97e71811aaafe4abf611dc24822fd6e73df1a1 +Records page size of data like in +.BR PERF_SAMPLE_ADDR . +.TP +.BR PERF_SAMPLE_CODE_PAGE_SIZE " (since Linux 5.11)" +.\" commit 995f088efebe1eba0282a6ffa12411b37f8990c2 +Records page size of ip like in +.BR PERF_SAMPLE_IP . +.TP +.BR PERF_SAMPLE_WEIGHT_STRUCT " (since Linux 5.12)" +.\" commit 2a6c6b7d7ad346f0679d0963cb19b3f0ea7ef32c +Records hardware provided weight values like in +.BR PERF_SAMPLE_WEIGHT , +but it can represent multiple values in a struct. +This shares the same space as +.BR PERF_SAMPLE_WEIGHT , +so users can apply either of those, +not both. +It has the following format and +the meaning of each field is +dependent on the hardware implementation. +.P +.in +4n +.EX +union perf_sample_weight { + u64 full; /* PERF_SAMPLE_WEIGHT */ + struct { /* PERF_SAMPLE_WEIGHT_STRUCT */ + u32 var1_dw; + u16 var2_w; + u16 var3_w; + }; +}; +.EE +.in +.RE +.TP +.I read_format +This field specifies the format of the data returned by +.BR read (2) +on a +.BR perf_event_open () +file descriptor. +.RS +.TP +.B PERF_FORMAT_TOTAL_TIME_ENABLED +Adds the 64-bit +.I time_enabled +field. +This can be used to calculate estimated totals if +the PMU is overcommitted and multiplexing is happening. +.TP +.B PERF_FORMAT_TOTAL_TIME_RUNNING +Adds the 64-bit +.I time_running +field. +This can be used to calculate estimated totals if +the PMU is overcommitted and multiplexing is happening. +.TP +.B PERF_FORMAT_ID +Adds a 64-bit unique value that corresponds to the event group. +.TP +.B PERF_FORMAT_GROUP +Allows all counter values in an event group to be read with one read. +.TP +.B PERF_FORMAT_LOST " (since Linux 6.0)" +.\" commit 119a784c81270eb88e573174ed2209225d646656 +Adds a 64-bit value that is the number of lost samples for this event. +This would be only meaningful when +.I sample_period +or +.I sample_freq +is set. +.RE +.TP +.I disabled +The +.I disabled +bit specifies whether the counter starts out disabled or enabled. +If disabled, the event can later be enabled by +.BR ioctl (2), +.BR prctl (2), +or +.IR enable_on_exec . +.IP +When creating an event group, typically the group leader is initialized +with +.I disabled +set to 1 and any child events are initialized with +.I disabled +set to 0. +Despite +.I disabled +being 0, the child events will not start until the group leader +is enabled. +.TP +.I inherit +The +.I inherit +bit specifies that this counter should count events of child +tasks as well as the task specified. +This applies only to new children, not to any existing children at +the time the counter is created (nor to any new children of +existing children). +.IP +Inherit does not work for some combinations of +.I read_format +values, such as +.BR PERF_FORMAT_GROUP . +.TP +.I pinned +The +.I pinned +bit specifies that the counter should always be on the CPU if at all +possible. +It applies only to hardware counters and only to group leaders. +If a pinned counter cannot be put onto the CPU (e.g., because there are +not enough hardware counters or because of a conflict with some other +event), then the counter goes into an 'error' state, where reads +return end-of-file (i.e., +.BR read (2) +returns 0) until the counter is subsequently enabled or disabled. +.TP +.I exclusive +The +.I exclusive +bit specifies that when this counter's group is on the CPU, +it should be the only group using the CPU's counters. +In the future this may allow monitoring programs to +support PMU features that need to run alone so that they do not +disrupt other hardware counters. +.IP +Note that many unexpected situations may prevent events with the +.I exclusive +bit set from ever running. +This includes any users running a system-wide +measurement as well as any kernel use of the performance counters +(including the commonly enabled NMI Watchdog Timer interface). +.TP +.I exclude_user +If this bit is set, the count excludes events that happen in user space. +.TP +.I exclude_kernel +If this bit is set, the count excludes events that happen in kernel space. +.TP +.I exclude_hv +If this bit is set, the count excludes events that happen in the +hypervisor. +This is mainly for PMUs that have built-in support for handling this +(such as POWER). +Extra support is needed for handling hypervisor measurements on most +machines. +.TP +.I exclude_idle +If set, don't count when the CPU is running the idle task. +While you can currently enable this for any event type, it is ignored +for all but software events. +.TP +.I mmap +The +.I mmap +bit enables generation of +.B PERF_RECORD_MMAP +samples for every +.BR mmap (2) +call that has +.B PROT_EXEC +set. +This allows tools to notice new executable code being mapped into +a program (dynamic shared libraries for example) +so that addresses can be mapped back to the original code. +.TP +.I comm +The +.I comm +bit enables tracking of process command name as modified by the +.BR execve (2) +and +.BR prctl (PR_SET_NAME) +system calls as well as writing to +.IR /proc/self/comm . +If the +.I comm_exec +flag is also successfully set (possible since Linux 3.16), +.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871 +then the misc flag +.B PERF_RECORD_MISC_COMM_EXEC +can be used to differentiate the +.BR execve (2) +case from the others. +.TP +.I freq +If this bit is set, then +.I sample_frequency +not +.I sample_period +is used when setting up the sampling interval. +.TP +.I inherit_stat +This bit enables saving of event counts on context switch for +inherited tasks. +This is meaningful only if the +.I inherit +field is set. +.TP +.I enable_on_exec +If this bit is set, a counter is automatically +enabled after a call to +.BR execve (2). +.TP +.I task +If this bit is set, then +fork/exit notifications are included in the ring buffer. +.TP +.I watermark +If set, have an overflow notification happen when we cross the +.I wakeup_watermark +boundary. +Otherwise, overflow notifications happen after +.I wakeup_events +samples. +.TP +.IR precise_ip " (since Linux 2.6.35)" +.\" commit ab608344bcbde4f55ec4cd911b686b0ce3eae076 +This controls the amount of skid. +Skid is how many instructions +execute between an event of interest happening and the kernel +being able to stop and record the event. +Smaller skid is +better and allows more accurate reporting of which events +correspond to which instructions, but hardware is often limited +with how small this can be. +.IP +The possible values of this field are the following: +.RS +.TP +.B 0 +.B SAMPLE_IP +can have arbitrary skid. +.TP +.B 1 +.B SAMPLE_IP +must have constant skid. +.TP +.B 2 +.B SAMPLE_IP +requested to have 0 skid. +.TP +.B 3 +.B SAMPLE_IP +must have 0 skid. +See also the description of +.BR PERF_RECORD_MISC_EXACT_IP . +.RE +.TP +.IR mmap_data " (since Linux 2.6.36)" +.\" commit 3af9e859281bda7eb7c20b51879cf43aa788ac2e +This is the counterpart of the +.I mmap +field. +This enables generation of +.B PERF_RECORD_MMAP +samples for +.BR mmap (2) +calls that do not have +.B PROT_EXEC +set (for example data and SysV shared memory). +.TP +.IR sample_id_all " (since Linux 2.6.38)" +.\" commit c980d1091810df13f21aabbce545fd98f545bbf7 +If set, then TID, TIME, ID, STREAM_ID, and CPU can +additionally be included in +.RB non- PERF_RECORD_SAMPLE s +if the corresponding +.I sample_type +is selected. +.IP +If +.B PERF_SAMPLE_IDENTIFIER +is specified, then an additional ID value is included +as the last value to ease parsing the record stream. +This may lead to the +.I id +value appearing twice. +.IP +The layout is described by this pseudo-structure: +.IP +.in +4n +.EX +struct sample_id { + { u32 pid, tid; } /* if PERF_SAMPLE_TID set */ + { u64 time; } /* if PERF_SAMPLE_TIME set */ + { u64 id; } /* if PERF_SAMPLE_ID set */ + { u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set */ + { u32 cpu, res; } /* if PERF_SAMPLE_CPU set */ + { u64 id; } /* if PERF_SAMPLE_IDENTIFIER set */ +}; +.EE +.in +.TP +.IR exclude_host " (since Linux 3.2)" +.\" commit a240f76165e6255384d4bdb8139895fac7988799 +When conducting measurements that include processes running +VM instances (i.e., have executed a +.B KVM_RUN +.BR ioctl (2)), +only measure events happening inside a guest instance. +This is only meaningful outside the guests; this setting does +not change counts gathered inside of a guest. +Currently, this functionality is x86 only. +.TP +.IR exclude_guest " (since Linux 3.2)" +.\" commit a240f76165e6255384d4bdb8139895fac7988799 +When conducting measurements that include processes running +VM instances (i.e., have executed a +.B KVM_RUN +.BR ioctl (2)), +do not measure events happening inside guest instances. +This is only meaningful outside the guests; this setting does +not change counts gathered inside of a guest. +Currently, this functionality is x86 only. +.TP +.IR exclude_callchain_kernel " (since Linux 3.7)" +.\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91 +Do not include kernel callchains. +.TP +.IR exclude_callchain_user " (since Linux 3.7)" +.\" commit d077526485d5c9b12fe85d0b2b3b7041e6bc5f91 +Do not include user callchains. +.TP +.IR mmap2 " (since Linux 3.16)" +.\" commit 13d7a2410fa637f450a29ecb515ac318ee40c741 +.\" This is tricky; was committed during 3.12 development +.\" but right before release was disabled. +.\" So while you could select mmap2 starting with Linux 3.12 +.\" it did not work until Linux 3.16 +.\" commit a5a5ba72843dd05f991184d6cb9a4471acce1005 +Generate an extended executable mmap record that contains enough +additional information to uniquely identify shared mappings. +The +.I mmap +flag must also be set for this to work. +.TP +.IR comm_exec " (since Linux 3.16)" +.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871 +This is purely a feature-detection flag, it does not change +kernel behavior. +If this flag can successfully be set, then, when +.I comm +is enabled, the +.B PERF_RECORD_MISC_COMM_EXEC +flag will be set in the +.I misc +field of a comm record header if the rename event being +reported was caused by a call to +.BR execve (2). +This allows tools to distinguish between the various +types of process renaming. +.TP +.IR use_clockid " (since Linux 4.1)" +.\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b +This allows selecting which internal Linux clock to use +when generating timestamps via the +.I clockid +field. +This can make it easier to correlate perf sample times with +timestamps generated by other tools. +.TP +.IR context_switch " (since Linux 4.3)" +.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4 +This enables the generation of +.B PERF_RECORD_SWITCH +records when a context switch occurs. +It also enables the generation of +.B PERF_RECORD_SWITCH_CPU_WIDE +records when sampling in CPU-wide mode. +This functionality is in addition to existing tracepoint and +software events for measuring context switches. +The advantage of this method is that it will give full +information even with strict +.I perf_event_paranoid +settings. +.TP +.IR write_backward " (since Linux 4.6)" +.\" commit 9ecda41acb971ebd07c8fb35faf24005c0baea12 +This causes the ring buffer to be written from the end to the beginning. +This is to support reading from overwritable ring buffer. +.TP +.IR namespaces " (since Linux 4.11)" +.\" commit e422267322cd319e2695a535e47c5b1feeac45eb +This enables the generation of +.B PERF_RECORD_NAMESPACES +records when a task enters a new namespace. +Each namespace has a combination of device and inode numbers. +.TP +.IR ksymbol " (since Linux 5.0)" +.\" commit 76193a94522f1d4edf2447a536f3f796ce56343b +This enables the generation of +.B PERF_RECORD_KSYMBOL +records when new kernel symbols are registered or unregistered. +This is analyzing dynamic kernel functions like eBPF. +.TP +.IR bpf_event " (since Linux 5.0)" +.\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106 +This enables the generation of +.B PERF_RECORD_BPF_EVENT +records when an eBPF program is loaded or unloaded. +.TP +.IR aux_output " (since Linux 5.4)" +.\" commit ab43762ef010967e4ccd53627f70a2eecbeafefb +This allows normal (non-AUX) events to generate data for AUX events +if the hardware supports it. +.TP +.IR cgroup " (since Linux 5.7)" +.\" commit 96aaab686505c449e24d76e76507290dcc30e008 +This enables the generation of +.B PERF_RECORD_CGROUP +records when a new cgroup is created (and activated). +.TP +.IR text_poke " (since Linux 5.8)" +.\" commit e17d43b93e544f5016c0251d2074c15568d5d963 +This enables the generation of +.B PERF_RECORD_TEXT_POKE +records when there's a change to the kernel text +(i.e., self-modifying code). +.TP +.IR build_id " (since Linux 5.12)" +.\" commit 88a16a1309333e43d328621ece3e9fa37027e8eb +This changes the contents in the +.B PERF_RECORD_MMAP2 +to have a build-id instead of device and inode numbers. +.TP +.IR inherit_thread " (since Linux 5.13)" +.\" commit 2b26f0aa004995f49f7b6f4100dd0e4c39a9ed5f +This disables the inheritance of the event to a child process. +Only new threads in the same process +(which is cloned with +.BR CLONE_THREAD ) +will inherit the event. +.TP +.IR remove_on_exec " (since Linux 5.13)" +.\" commit 2e498d0a74e5b88a6689ae1b811f247f91ff188e +This closes the event when it starts a new process image by +.BR execve (2). +.TP +.IR sigtrap " (since Linux 5.13)" +.\" commit 97ba62b278674293762c3d91f724f1bb922f04e0 +This enables synchronous signal delivery of +.B SIGTRAP +on event overflow. +.TP +.I wakeup_events +.TQ +.I wakeup_watermark +This union sets how many samples +.RI ( wakeup_events ) +or bytes +.RI ( wakeup_watermark ) +happen before an overflow notification happens. +Which one is used is selected by the +.I watermark +bit flag. +.IP +.I wakeup_events +counts only +.B PERF_RECORD_SAMPLE +record types. +To receive overflow notification for all +.B PERF_RECORD +types choose watermark and set +.I wakeup_watermark +to 1. +.IP +Prior to Linux 3.0, setting +.\" commit f506b3dc0ec454a16d40cab9ee5d75435b39dc50 +.I wakeup_events +to 0 resulted in no overflow notifications; +more recent kernels treat 0 the same as 1. +.TP +.IR bp_type " (since Linux 2.6.33)" +.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e +This chooses the breakpoint type. +It is one of: +.RS +.TP +.B HW_BREAKPOINT_EMPTY +No breakpoint. +.TP +.B HW_BREAKPOINT_R +Count when we read the memory location. +.TP +.B HW_BREAKPOINT_W +Count when we write the memory location. +.TP +.B HW_BREAKPOINT_RW +Count when we read or write the memory location. +.TP +.B HW_BREAKPOINT_X +Count when we execute code at the memory location. +.P +The values can be combined via a bitwise or, but the +combination of +.B HW_BREAKPOINT_R +or +.B HW_BREAKPOINT_W +with +.B HW_BREAKPOINT_X +is not allowed. +.RE +.TP +.IR bp_addr " (since Linux 2.6.33)" +.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e +This is the address of the breakpoint. +For execution breakpoints, this is the memory address of the instruction +of interest; for read and write breakpoints, it is the memory address +of the memory location of interest. +.TP +.IR config1 " (since Linux 2.6.39)" +.\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6 +.I config1 +is used for setting events that need an extra register or otherwise +do not fit in the regular config field. +Raw OFFCORE_EVENTS on Nehalem/Westmere/SandyBridge use this field +on Linux 3.3 and later kernels. +.TP +.IR bp_len " (since Linux 2.6.33)" +.\" commit 24f1e32c60c45c89a997c73395b69c8af6f0a84e +.I bp_len +is the length of the breakpoint being measured if +.I type +is +.BR PERF_TYPE_BREAKPOINT . +Options are +.BR HW_BREAKPOINT_LEN_1 , +.BR HW_BREAKPOINT_LEN_2 , +.BR HW_BREAKPOINT_LEN_4 , +and +.BR HW_BREAKPOINT_LEN_8 . +For an execution breakpoint, set this to +.IR sizeof(long) . +.TP +.IR config2 " (since Linux 2.6.39)" +.\" commit a7e3ed1e470116c9d12c2f778431a481a6be8ab6 +.I config2 +is a further extension of the +.I config1 +field. +.TP +.IR branch_sample_type " (since Linux 3.4)" +.\" commit bce38cd53e5ddba9cb6d708c4ef3d04a4016ec7e +If +.B PERF_SAMPLE_BRANCH_STACK +is enabled, then this specifies what branches to include +in the branch record. +.IP +The first part of the value is the privilege level, which +is a combination of one of the values listed below. +If the user does not set privilege level explicitly, the kernel +will use the event's privilege level. +Event and branch privilege levels do not have to match. +.RS +.TP +.B PERF_SAMPLE_BRANCH_USER +Branch target is in user space. +.TP +.B PERF_SAMPLE_BRANCH_KERNEL +Branch target is in kernel space. +.TP +.B PERF_SAMPLE_BRANCH_HV +Branch target is in hypervisor. +.TP +.B PERF_SAMPLE_BRANCH_PLM_ALL +A convenience value that is the three preceding values ORed together. +.P +In addition to the privilege value, at least one or more of the +following bits must be set. +.TP +.B PERF_SAMPLE_BRANCH_ANY +Any branch type. +.TP +.B PERF_SAMPLE_BRANCH_ANY_CALL +Any call branch (includes direct calls, indirect calls, and far jumps). +.TP +.B PERF_SAMPLE_BRANCH_IND_CALL +Indirect calls. +.TP +.BR PERF_SAMPLE_BRANCH_CALL " (since Linux 4.4)" +.\" commit c229bf9dc179d2023e185c0f705bdf68484c1e73 +Direct calls. +.TP +.B PERF_SAMPLE_BRANCH_ANY_RETURN +Any return branch. +.TP +.BR PERF_SAMPLE_BRANCH_IND_JUMP " (since Linux 4.2)" +.\" commit c9fdfa14c3792c0160849c484e83aa57afd80ccc +Indirect jumps. +.TP +.BR PERF_SAMPLE_BRANCH_COND " (since Linux 3.16)" +.\" commit bac52139f0b7ab31330e98fd87fc5a2664951050 +Conditional branches. +.TP +.BR PERF_SAMPLE_BRANCH_ABORT_TX " (since Linux 3.11)" +.\" commit 135c5612c460f89657c4698fe2ea753f6f667963 +Transactional memory aborts. +.TP +.BR PERF_SAMPLE_BRANCH_IN_TX " (since Linux 3.11)" +.\" commit 135c5612c460f89657c4698fe2ea753f6f667963 +Branch in transactional memory transaction. +.TP +.BR PERF_SAMPLE_BRANCH_NO_TX " (since Linux 3.11)" +.\" commit 135c5612c460f89657c4698fe2ea753f6f667963 +Branch not in transactional memory transaction. +.BR PERF_SAMPLE_BRANCH_CALL_STACK " (since Linux 4.1)" +.\" commit 2c44b1936bb3b135a3fac8b3493394d42e51cf70 +Branch is part of a hardware-generated call stack. +This requires hardware support, currently only found +on Intel x86 Haswell or newer. +.RE +.TP +.IR sample_regs_user " (since Linux 3.7)" +.\" commit 4018994f3d8785275ef0e7391b75c3462c029e56 +This bit mask defines the set of user CPU registers to dump on samples. +The layout of the register mask is architecture-specific and +is described in the kernel header file +.IR arch/ARCH/include/uapi/asm/perf_regs.h . +.TP +.IR sample_stack_user " (since Linux 3.7)" +.\" commit c5ebcedb566ef17bda7b02686e0d658a7bb42ee7 +This defines the size of the user stack to dump if +.B PERF_SAMPLE_STACK_USER +is specified. +.TP +.IR clockid " (since Linux 4.1)" +.\" commit 34f439278cef7b1177f8ce24f9fc81dfc6221d3b +If +.I use_clockid +is set, then this field selects which internal Linux timer to +use for timestamps. +The available timers are defined in +.IR linux/time.h , +with +.BR CLOCK_MONOTONIC , +.BR CLOCK_MONOTONIC_RAW , +.BR CLOCK_REALTIME , +.BR CLOCK_BOOTTIME , +and +.B CLOCK_TAI +currently supported. +.TP +.IR aux_watermark " (since Linux 4.1)" +.\" commit 1a5941312414c71dece6717da9a0fa1303127afa +This specifies how much data is required to trigger a +.B PERF_RECORD_AUX +sample. +.TP +.IR sample_max_stack " (since Linux 4.8)" +.\" commit 97c79a38cd454602645f0470ffb444b3b75ce574 +When +.I sample_type +includes +.BR PERF_SAMPLE_CALLCHAIN , +this field specifies how many stack frames to report when +generating the callchain. +.TP +.IR aux_sample_size " (since Linux 5.5)" +.\" commit a4faf00d994c40e64f656805ac375c65e324eefb +When +.B PERF_SAMPLE_AUX +flag is set, +specify the desired size of AUX data. +Note that it can get smaller data than the specified size. +.TP +.IR sig_data " (since Linux 5.13)" +.\" commit 97ba62b278674293762c3d91f724f1bb922f04e0 +This data will be copied to user's signal handler +(through +.I si_perf +in the +.IR siginfo_t ) +to disambiguate which event triggered the signal. +.SS Reading results +Once a +.BR perf_event_open () +file descriptor has been opened, the values +of the events can be read from the file descriptor. +The values that are there are specified by the +.I read_format +field in the +.I attr +structure at open time. +.P +If you attempt to read into a buffer that is not big enough to hold the +data, the error +.B ENOSPC +results. +.P +Here is the layout of the data returned by a read: +.IP \[bu] 3 +If +.B PERF_FORMAT_GROUP +was specified to allow reading all events in a group at once: +.IP +.in +4n +.EX +struct read_format { + u64 nr; /* The number of events */ + u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */ + u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */ + struct { + u64 value; /* The value of the event */ + u64 id; /* if PERF_FORMAT_ID */ + u64 lost; /* if PERF_FORMAT_LOST */ + } values[nr]; +}; +.EE +.in +.IP \[bu] +If +.B PERF_FORMAT_GROUP +was +.I not +specified: +.IP +.in +4n +.EX +struct read_format { + u64 value; /* The value of the event */ + u64 time_enabled; /* if PERF_FORMAT_TOTAL_TIME_ENABLED */ + u64 time_running; /* if PERF_FORMAT_TOTAL_TIME_RUNNING */ + u64 id; /* if PERF_FORMAT_ID */ + u64 lost; /* if PERF_FORMAT_LOST */ +}; +.EE +.in +.P +The values read are as follows: +.TP +.I nr +The number of events in this file descriptor. +Available only if +.B PERF_FORMAT_GROUP +was specified. +.TP +.I time_enabled +.TQ +.I time_running +Total time the event was enabled and running. +Normally these values are the same. +Multiplexing happens if the number of events is more than the +number of available PMU counter slots. +In that case the events run only part of the time and the +.I time_enabled +and +.I time running +values can be used to scale an estimated value for the count. +.TP +.I value +An unsigned 64-bit value containing the counter result. +.TP +.I id +A globally unique value for this particular event; only present if +.B PERF_FORMAT_ID +was specified in +.IR read_format . +.TP +.I lost +The number of lost samples of this event; +only present if +.B PERF_FORMAT_LOST +was specified in +.IR read_format . +.SS MMAP layout +When using +.BR perf_event_open () +in sampled mode, asynchronous events +(like counter overflow or +.B PROT_EXEC +mmap tracking) +are logged into a ring-buffer. +This ring-buffer is created and accessed through +.BR mmap (2). +.P +The mmap size should be 1+2\[ha]n pages, where the first page is a +metadata page +.RI ( "struct perf_event_mmap_page" ) +that contains various +bits of information such as where the ring-buffer head is. +.P +Before Linux 2.6.39, there is a bug that means you must allocate an mmap +ring buffer when sampling even if you do not plan to access it. +.P +The structure of the first metadata mmap page is as follows: +.P +.in +4n +.EX +struct perf_event_mmap_page { + __u32 version; /* version number of this structure */ + __u32 compat_version; /* lowest version this is compat with */ + __u32 lock; /* seqlock for synchronization */ + __u32 index; /* hardware counter identifier */ + __s64 offset; /* add to hardware counter value */ + __u64 time_enabled; /* time event active */ + __u64 time_running; /* time event on CPU */ + union { + __u64 capabilities; + struct { + __u64 cap_usr_time / cap_usr_rdpmc / cap_bit0 : 1, + cap_bit0_is_deprecated : 1, + cap_user_rdpmc : 1, + cap_user_time : 1, + cap_user_time_zero : 1, + }; + }; + __u16 pmc_width; + __u16 time_shift; + __u32 time_mult; + __u64 time_offset; + __u64 __reserved[120]; /* Pad to 1 k */ + __u64 data_head; /* head in the data section */ + __u64 data_tail; /* user\-space written tail */ + __u64 data_offset; /* where the buffer starts */ + __u64 data_size; /* data buffer size */ + __u64 aux_head; + __u64 aux_tail; + __u64 aux_offset; + __u64 aux_size; +\& +} +.EE +.in +.P +The following list describes the fields in the +.I perf_event_mmap_page +structure in more detail: +.TP +.I version +Version number of this structure. +.TP +.I compat_version +The lowest version this is compatible with. +.TP +.I lock +A seqlock for synchronization. +.TP +.I index +A unique hardware counter identifier. +.TP +.I offset +When using rdpmc for reads this offset value +must be added to the one returned by rdpmc to get +the current total event count. +.TP +.I time_enabled +Time the event was active. +.TP +.I time_running +Time the event was running. +.TP +.IR cap_usr_time " / " cap_usr_rdpmc " / " cap_bit0 " (since Linux 3.4)" +.\" commit c7206205d00ab375839bd6c7ddb247d600693c09 +There was a bug in the definition of +.I cap_usr_time +and +.I cap_usr_rdpmc +from Linux 3.4 until Linux 3.11. +Both bits were defined to point to the same location, so it was +impossible to know if +.I cap_usr_time +or +.I cap_usr_rdpmc +were actually set. +.IP +Starting with Linux 3.12, these are renamed to +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +.I cap_bit0 +and you should use the +.I cap_user_time +and +.I cap_user_rdpmc +fields instead. +.TP +.IR cap_bit0_is_deprecated " (since Linux 3.12)" +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +If set, this bit indicates that the kernel supports +the properly separated +.I cap_user_time +and +.I cap_user_rdpmc +bits. +.IP +If not-set, it indicates an older kernel where +.I cap_usr_time +and +.I cap_usr_rdpmc +map to the same bit and thus both features should +be used with caution. +.TP +.IR cap_user_rdpmc " (since Linux 3.12)" +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +If the hardware supports user-space read of performance counters +without syscall (this is the "rdpmc" instruction on x86), then +the following code can be used to do a read: +.IP +.in +4n +.EX +u32 seq, time_mult, time_shift, idx, width; +u64 count, enabled, running; +u64 cyc, time_offset; +\& +do { + seq = pc\->lock; + barrier(); + enabled = pc\->time_enabled; + running = pc\->time_running; +\& + if (pc\->cap_usr_time && enabled != running) { + cyc = rdtsc(); + time_offset = pc\->time_offset; + time_mult = pc\->time_mult; + time_shift = pc\->time_shift; + } +\& + idx = pc\->index; + count = pc\->offset; +\& + if (pc\->cap_usr_rdpmc && idx) { + width = pc\->pmc_width; + count += rdpmc(idx \- 1); + } +\& + barrier(); +} while (pc\->lock != seq); +.EE +.in +.TP +.IR cap_user_time " (since Linux 3.12)" +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +This bit indicates the hardware has a constant, nonstop +timestamp counter (TSC on x86). +.TP +.IR cap_user_time_zero " (since Linux 3.12)" +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +Indicates the presence of +.I time_zero +which allows mapping timestamp values to +the hardware clock. +.TP +.I pmc_width +If +.IR cap_usr_rdpmc , +this field provides the bit-width of the value +read using the rdpmc or equivalent instruction. +This can be used to sign extend the result like: +.IP +.in +4n +.EX +pmc <<= 64 \- pmc_width; +pmc >>= 64 \- pmc_width; // signed shift right +count += pmc; +.EE +.in +.TP +.I time_shift +.TQ +.I time_mult +.TQ +.I time_offset +.IP +If +.IR cap_usr_time , +these fields can be used to compute the time +delta since +.I time_enabled +(in nanoseconds) using rdtsc or similar. +.IP +.in +4n +.EX +u64 quot, rem; +u64 delta; +\& +quot = cyc >> time_shift; +rem = cyc & (((u64)1 << time_shift) \- 1); +delta = time_offset + quot * time_mult + + ((rem * time_mult) >> time_shift); +.EE +.in +.IP +Where +.IR time_offset , +.IR time_mult , +.IR time_shift , +and +.I cyc +are read in the +seqcount loop described above. +This delta can then be added to +enabled and possible running (if idx), improving the scaling: +.IP +.in +4n +.EX +enabled += delta; +if (idx) + running += delta; +quot = count / running; +rem = count % running; +count = quot * enabled + (rem * enabled) / running; +.EE +.in +.TP +.IR time_zero " (since Linux 3.12)" +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +.IP +If +.I cap_usr_time_zero +is set, then the hardware clock (the TSC timestamp counter on x86) +can be calculated from the +.IR time_zero , +.IR time_mult , +and +.I time_shift +values: +.IP +.in +4n +.EX +time = timestamp \- time_zero; +quot = time / time_mult; +rem = time % time_mult; +cyc = (quot << time_shift) + (rem << time_shift) / time_mult; +.EE +.in +.IP +And vice versa: +.IP +.in +4n +.EX +quot = cyc >> time_shift; +rem = cyc & (((u64)1 << time_shift) \- 1); +timestamp = time_zero + quot * time_mult + + ((rem * time_mult) >> time_shift); +.EE +.in +.TP +.I data_head +This points to the head of the data section. +The value continuously increases, it does not wrap. +The value needs to be manually wrapped by the size of the mmap buffer +before accessing the samples. +.IP +On SMP-capable platforms, after reading the +.I data_head +value, +user space should issue an rmb(). +.TP +.I data_tail +When the mapping is +.BR PROT_WRITE , +the +.I data_tail +value should be written by user space to reflect the last read data. +In this case, the kernel will not overwrite unread data. +.TP +.IR data_offset " (since Linux 4.1)" +.\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f +Contains the offset of the location in the mmap buffer +where perf sample data begins. +.TP +.IR data_size " (since Linux 4.1)" +.\" commit e8c6deac69629c0cb97c3d3272f8631ef17f8f0f +Contains the size of the perf sample region within +the mmap buffer. +.TP +.I aux_head +.TQ +.I aux_tail +.TQ +.I aux_offset +.TQ +.I aux_size " (since Linux 4.1)" +.\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff +The AUX region allows +.BR mmap (2)-ing +a separate sample buffer for +high-bandwidth data streams (separate from the main perf sample buffer). +An example of a high-bandwidth stream is instruction tracing support, +as is found in newer Intel processors. +.IP +To set up an AUX area, first +.I aux_offset +needs to be set with an offset greater than +.IR data_offset + data_size +and +.I aux_size +needs to be set to the desired buffer size. +The desired offset and size must be page aligned, and the size +must be a power of two. +These values are then passed to mmap in order to map the AUX buffer. +Pages in the AUX buffer are included as part of the +.B RLIMIT_MEMLOCK +resource limit (see +.BR setrlimit (2)), +and also as part of the +.I perf_event_mlock_kb +allowance. +.IP +By default, the AUX buffer will be truncated if it will not fit +in the available space in the ring buffer. +If the AUX buffer is mapped as a read only buffer, then it will +operate in ring buffer mode where old data will be overwritten +by new. +In overwrite mode, it might not be possible to infer where the +new data began, and it is the consumer's job to disable +measurement while reading to avoid possible data races. +.IP +The +.I aux_head +and +.I aux_tail +ring buffer pointers have the same behavior and ordering +rules as the previous described +.I data_head +and +.IR data_tail . +.P +The following 2^n ring-buffer pages have the layout described below. +.P +If +.I perf_event_attr.sample_id_all +is set, then all event types will +have the sample_type selected fields related to where/when (identity) +an event took place (TID, TIME, ID, CPU, STREAM_ID) described in +.B PERF_RECORD_SAMPLE +below, it will be stashed just after the +.I perf_event_header +and the fields already present for the existing +fields, that is, at the end of the payload. +This allows a newer perf.data +file to be supported by older perf tools, with the new optional +fields being ignored. +.P +The mmap values start with a header: +.P +.in +4n +.EX +struct perf_event_header { + __u32 type; + __u16 misc; + __u16 size; +}; +.EE +.in +.P +Below, we describe the +.I perf_event_header +fields in more detail. +For ease of reading, +the fields with shorter descriptions are presented first. +.TP +.I size +This indicates the size of the record. +.TP +.I misc +The +.I misc +field contains additional information about the sample. +.IP +The CPU mode can be determined from this value by masking with +.B PERF_RECORD_MISC_CPUMODE_MASK +and looking for one of the following (note these are not +bit masks, only one can be set at a time): +.RS +.TP +.B PERF_RECORD_MISC_CPUMODE_UNKNOWN +Unknown CPU mode. +.TP +.B PERF_RECORD_MISC_KERNEL +Sample happened in the kernel. +.TP +.B PERF_RECORD_MISC_USER +Sample happened in user code. +.TP +.B PERF_RECORD_MISC_HYPERVISOR +Sample happened in the hypervisor. +.TP +.BR PERF_RECORD_MISC_GUEST_KERNEL " (since Linux 2.6.35)" +.\" commit 39447b386c846bbf1c56f6403c5282837486200f +Sample happened in the guest kernel. +.TP +.B PERF_RECORD_MISC_GUEST_USER " (since Linux 2.6.35)" +.\" commit 39447b386c846bbf1c56f6403c5282837486200f +Sample happened in guest user code. +.RE +.P +.RS +Since the following three statuses are generated by +different record types, they alias to the same bit: +.TP +.BR PERF_RECORD_MISC_MMAP_DATA " (since Linux 3.10)" +.\" commit 2fe85427e3bf65d791700d065132772fc26e4d75 +This is set when the mapping is not executable; +otherwise the mapping is executable. +.TP +.BR PERF_RECORD_MISC_COMM_EXEC " (since Linux 3.16)" +.\" commit 82b897782d10fcc4930c9d4a15b175348fdd2871 +This is set for a +.B PERF_RECORD_COMM +record on kernels more recent than Linux 3.16 +if a process name change was caused by an +.BR execve (2) +system call. +.TP +.BR PERF_RECORD_MISC_SWITCH_OUT " (since Linux 4.3)" +.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4 +When a +.B PERF_RECORD_SWITCH +or +.B PERF_RECORD_SWITCH_CPU_WIDE +record is generated, this bit indicates that the +context switch is away from the current process +(instead of into the current process). +.RE +.P +.RS +In addition, the following bits can be set: +.TP +.B PERF_RECORD_MISC_EXACT_IP +This indicates that the content of +.B PERF_SAMPLE_IP +points +to the actual instruction that triggered the event. +See also +.IR perf_event_attr.precise_ip . +.TP +.BR PERF_RECORD_MISC_SWITCH_OUT_PREEMPT " (since Linux 4.17)" +.\" commit 101592b4904ecf6b8ed2a4784d41d180319d95a1 +When a +.B PERF_RECORD_SWITCH +or +.B PERF_RECORD_SWITCH_CPU_WIDE +record is generated, +this indicates the context switch was a preemption. +.TP +.BR PERF_RECORD_MISC_MMAP_BUILD_ID " (since Linux 5.12)" +.\" commit 88a16a1309333e43d328621ece3e9fa37027e8eb +This indicates that the content of +.B PERF_SAMPLE_MMAP2 +contains build-ID data instead of device major and minor numbers +as well as the inode number. +.TP +.BR PERF_RECORD_MISC_EXT_RESERVED " (since Linux 2.6.35)" +.\" commit 1676b8a077c352085d52578fb4f29350b58b6e74 +This indicates there is extended data available (currently not used). +.TP +.B PERF_RECORD_MISC_PROC_MAP_PARSE_TIMEOUT +.\" commit 930e6fcd2bcce9bcd9d4aa7e755678d33f3fe6f4 +This bit is not set by the kernel. +It is reserved for the user-space perf utility to indicate that +.IR /proc/ pid /maps +parsing was taking too long and was stopped, and thus the mmap +records may be truncated. +.RE +.TP +.I type +The +.I type +value is one of the below. +The values in the corresponding record (that follows the header) +depend on the +.I type +selected as shown. +.RS +.TP 4 +.B PERF_RECORD_MMAP +The MMAP events record the +.B PROT_EXEC +mappings so that we can correlate +user-space IPs to code. +They have the following structure: +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid, tid; + u64 addr; + u64 len; + u64 pgoff; + char filename[]; +}; +.EE +.in +.RS +.TP +.I pid +is the process ID. +.TP +.I tid +is the thread ID. +.TP +.I addr +is the address of the allocated memory. +.I len +is the length of the allocated memory. +.I pgoff +is the page offset of the allocated memory. +.I filename +is a string describing the backing of the allocated memory. +.RE +.TP +.B PERF_RECORD_LOST +This record indicates when events are lost. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 id; + u64 lost; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I id +is the unique event ID for the samples that were lost. +.TP +.I lost +is the number of events that were lost. +.RE +.TP +.B PERF_RECORD_COMM +This record indicates a change in the process name. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid; + u32 tid; + char comm[]; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I pid +is the process ID. +.TP +.I tid +is the thread ID. +.TP +.I comm +is a string containing the new name of the process. +.RE +.TP +.B PERF_RECORD_EXIT +This record indicates a process exit event. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid, ppid; + u32 tid, ptid; + u64 time; + struct sample_id sample_id; +}; +.EE +.in +.TP +.B PERF_RECORD_THROTTLE +.TQ +.B PERF_RECORD_UNTHROTTLE +This record indicates a throttle/unthrottle event. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 time; + u64 id; + u64 stream_id; + struct sample_id sample_id; +}; +.EE +.in +.TP +.B PERF_RECORD_FORK +This record indicates a fork event. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid, ppid; + u32 tid, ptid; + u64 time; + struct sample_id sample_id; +}; +.EE +.in +.TP +.B PERF_RECORD_READ +This record indicates a read event. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid, tid; + struct read_format values; + struct sample_id sample_id; +}; +.EE +.in +.TP +.B PERF_RECORD_SAMPLE +This record indicates a sample. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 sample_id; /* if PERF_SAMPLE_IDENTIFIER */ + u64 ip; /* if PERF_SAMPLE_IP */ + u32 pid, tid; /* if PERF_SAMPLE_TID */ + u64 time; /* if PERF_SAMPLE_TIME */ + u64 addr; /* if PERF_SAMPLE_ADDR */ + u64 id; /* if PERF_SAMPLE_ID */ + u64 stream_id; /* if PERF_SAMPLE_STREAM_ID */ + u32 cpu, res; /* if PERF_SAMPLE_CPU */ + u64 period; /* if PERF_SAMPLE_PERIOD */ + struct read_format v; + /* if PERF_SAMPLE_READ */ + u64 nr; /* if PERF_SAMPLE_CALLCHAIN */ + u64 ips[nr]; /* if PERF_SAMPLE_CALLCHAIN */ + u32 size; /* if PERF_SAMPLE_RAW */ + char data[size]; /* if PERF_SAMPLE_RAW */ + u64 bnr; /* if PERF_SAMPLE_BRANCH_STACK */ + struct perf_branch_entry lbr[bnr]; + /* if PERF_SAMPLE_BRANCH_STACK */ + u64 abi; /* if PERF_SAMPLE_REGS_USER */ + u64 regs[weight(mask)]; + /* if PERF_SAMPLE_REGS_USER */ + u64 size; /* if PERF_SAMPLE_STACK_USER */ + char data[size]; /* if PERF_SAMPLE_STACK_USER */ + u64 dyn_size; /* if PERF_SAMPLE_STACK_USER && + size != 0 */ + union perf_sample_weight weight; + /* if PERF_SAMPLE_WEIGHT */ + /* || PERF_SAMPLE_WEIGHT_STRUCT */ + u64 data_src; /* if PERF_SAMPLE_DATA_SRC */ + u64 transaction; /* if PERF_SAMPLE_TRANSACTION */ + u64 abi; /* if PERF_SAMPLE_REGS_INTR */ + u64 regs[weight(mask)]; + /* if PERF_SAMPLE_REGS_INTR */ + u64 phys_addr; /* if PERF_SAMPLE_PHYS_ADDR */ + u64 cgroup; /* if PERF_SAMPLE_CGROUP */ + u64 data_page_size; + /* if PERF_SAMPLE_DATA_PAGE_SIZE */ + u64 code_page_size; + /* if PERF_SAMPLE_CODE_PAGE_SIZE */ + u64 size; /* if PERF_SAMPLE_AUX */ + char data[size]; /* if PERF_SAMPLE_AUX */ +}; +.EE +.in +.RS 4 +.TP 4 +.I sample_id +If +.B PERF_SAMPLE_IDENTIFIER +is enabled, a 64-bit unique ID is included. +This is a duplication of the +.B PERF_SAMPLE_ID +.I id +value, but included at the beginning of the sample +so parsers can easily obtain the value. +.TP +.I ip +If +.B PERF_SAMPLE_IP +is enabled, then a 64-bit instruction +pointer value is included. +.TP +.I pid +.TQ +.I tid +If +.B PERF_SAMPLE_TID +is enabled, then a 32-bit process ID +and 32-bit thread ID are included. +.TP +.I time +If +.B PERF_SAMPLE_TIME +is enabled, then a 64-bit timestamp +is included. +This is obtained via local_clock() which is a hardware timestamp +if available and the jiffies value if not. +.TP +.I addr +If +.B PERF_SAMPLE_ADDR +is enabled, then a 64-bit address is included. +This is usually the address of a tracepoint, +breakpoint, or software event; otherwise the value is 0. +.TP +.I id +If +.B PERF_SAMPLE_ID +is enabled, a 64-bit unique ID is included. +If the event is a member of an event group, the group leader ID is returned. +This ID is the same as the one returned by +.BR PERF_FORMAT_ID . +.TP +.I stream_id +If +.B PERF_SAMPLE_STREAM_ID +is enabled, a 64-bit unique ID is included. +Unlike +.B PERF_SAMPLE_ID +the actual ID is returned, not the group leader. +This ID is the same as the one returned by +.BR PERF_FORMAT_ID . +.TP +.I cpu +.TQ +.I res +If +.B PERF_SAMPLE_CPU +is enabled, this is a 32-bit value indicating +which CPU was being used, in addition to a reserved (unused) +32-bit value. +.TP +.I period +If +.B PERF_SAMPLE_PERIOD +is enabled, a 64-bit value indicating +the current sampling period is written. +.TP +.I v +If +.B PERF_SAMPLE_READ +is enabled, a structure of type read_format +is included which has values for all events in the event group. +The values included depend on the +.I read_format +value used at +.BR perf_event_open () +time. +.TP +.I nr +.TQ +.I ips[nr] +If +.B PERF_SAMPLE_CALLCHAIN +is enabled, then a 64-bit number is included +which indicates how many following 64-bit instruction pointers will +follow. +This is the current callchain. +.TP +.I size +.TQ +.I data[size] +If +.B PERF_SAMPLE_RAW +is enabled, then a 32-bit value indicating size +is included followed by an array of 8-bit values of length size. +The values are padded with 0 to have 64-bit alignment. +.IP +This RAW record data is opaque with respect to the ABI. +The ABI doesn't make any promises with respect to the stability +of its content, it may vary depending +on event, hardware, and kernel version. +.TP +.I bnr +.TQ +.I lbr[bnr] +If +.B PERF_SAMPLE_BRANCH_STACK +is enabled, then a 64-bit value indicating +the number of records is included, followed by +.I bnr +.I perf_branch_entry +structures which each include the fields: +.RS +.TP +.I from +This indicates the source instruction (may not be a branch). +.TP +.I to +The branch target. +.TP +.I mispred +The branch target was mispredicted. +.TP +.I predicted +The branch target was predicted. +.TP +.IR in_tx " (since Linux 3.11)" +.\" commit 135c5612c460f89657c4698fe2ea753f6f667963 +The branch was in a transactional memory transaction. +.TP +.IR abort " (since Linux 3.11)" +.\" commit 135c5612c460f89657c4698fe2ea753f6f667963 +The branch was in an aborted transactional memory transaction. +.TP +.IR cycles " (since Linux 4.3)" +.\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f +This reports the number of cycles elapsed since the +previous branch stack update. +.P +The entries are from most to least recent, so the first entry +has the most recent branch. +.P +Support for +.IR mispred , +.IR predicted , +and +.I cycles +is optional; if not supported, those +values will be 0. +.P +The type of branches recorded is specified by the +.I branch_sample_type +field. +.RE +.TP +.I abi +.TQ +.I regs[weight(mask)] +If +.B PERF_SAMPLE_REGS_USER +is enabled, then the user CPU registers are recorded. +.IP +The +.I abi +field is one of +.BR PERF_SAMPLE_REGS_ABI_NONE , +.BR PERF_SAMPLE_REGS_ABI_32 , +or +.BR PERF_SAMPLE_REGS_ABI_64 . +.IP +The +.I regs +field is an array of the CPU registers that were specified by +the +.I sample_regs_user +attr field. +The number of values is the number of bits set in the +.I sample_regs_user +bit mask. +.TP +.I size +.TQ +.I data[size] +.TQ +.I dyn_size +If +.B PERF_SAMPLE_STACK_USER +is enabled, then the user stack is recorded. +This can be used to generate stack backtraces. +.I size +is the size requested by the user in +.I sample_stack_user +or else the maximum record size. +.I data +is the stack data (a raw dump of the memory pointed to by the +stack pointer at the time of sampling). +.I dyn_size +is the amount of data actually dumped (can be less than +.IR size ). +Note that +.I dyn_size +is omitted if +.I size +is 0. +.TP +.I weight +If +.B PERF_SAMPLE_WEIGHT +or +.B PERF_SAMPLE_WEIGHT_STRUCT +is enabled, then a 64-bit value provided by the hardware +is recorded that indicates how costly the event was. +This allows expensive events to stand out more clearly +in profiles. +.TP +.I data_src +If +.B PERF_SAMPLE_DATA_SRC +is enabled, then a 64-bit value is recorded that is made up of +the following fields: +.RS +.TP 4 +.I mem_op +Type of opcode, a bitwise combination of: +.IP +.PD 0 +.RS +.TP 24 +.B PERF_MEM_OP_NA +Not available +.TP +.B PERF_MEM_OP_LOAD +Load instruction +.TP +.B PERF_MEM_OP_STORE +Store instruction +.TP +.B PERF_MEM_OP_PFETCH +Prefetch +.TP +.B PERF_MEM_OP_EXEC +Executable code +.RE +.PD +.TP +.I mem_lvl +Memory hierarchy level hit or miss, a bitwise combination of +the following, shifted left by +.BR PERF_MEM_LVL_SHIFT : +.IP +.PD 0 +.RS +.TP 24 +.B PERF_MEM_LVL_NA +Not available +.TP +.B PERF_MEM_LVL_HIT +Hit +.TP +.B PERF_MEM_LVL_MISS +Miss +.TP +.B PERF_MEM_LVL_L1 +Level 1 cache +.TP +.B PERF_MEM_LVL_LFB +Line fill buffer +.TP +.B PERF_MEM_LVL_L2 +Level 2 cache +.TP +.B PERF_MEM_LVL_L3 +Level 3 cache +.TP +.B PERF_MEM_LVL_LOC_RAM +Local DRAM +.TP +.B PERF_MEM_LVL_REM_RAM1 +Remote DRAM 1 hop +.TP +.B PERF_MEM_LVL_REM_RAM2 +Remote DRAM 2 hops +.TP +.B PERF_MEM_LVL_REM_CCE1 +Remote cache 1 hop +.TP +.B PERF_MEM_LVL_REM_CCE2 +Remote cache 2 hops +.TP +.B PERF_MEM_LVL_IO +I/O memory +.TP +.B PERF_MEM_LVL_UNC +Uncached memory +.RE +.PD +.TP +.I mem_snoop +Snoop mode, a bitwise combination of the following, shifted left by +.BR PERF_MEM_SNOOP_SHIFT : +.IP +.PD 0 +.RS +.TP 24 +.B PERF_MEM_SNOOP_NA +Not available +.TP +.B PERF_MEM_SNOOP_NONE +No snoop +.TP +.B PERF_MEM_SNOOP_HIT +Snoop hit +.TP +.B PERF_MEM_SNOOP_MISS +Snoop miss +.TP +.B PERF_MEM_SNOOP_HITM +Snoop hit modified +.RE +.PD +.TP +.I mem_lock +Lock instruction, a bitwise combination of the following, shifted left by +.BR PERF_MEM_LOCK_SHIFT : +.IP +.PD 0 +.RS +.TP 24 +.B PERF_MEM_LOCK_NA +Not available +.TP +.B PERF_MEM_LOCK_LOCKED +Locked transaction +.RE +.PD +.TP +.I mem_dtlb +TLB access hit or miss, a bitwise combination of the following, shifted +left by +.BR PERF_MEM_TLB_SHIFT : +.IP +.PD 0 +.RS +.TP 24 +.B PERF_MEM_TLB_NA +Not available +.TP +.B PERF_MEM_TLB_HIT +Hit +.TP +.B PERF_MEM_TLB_MISS +Miss +.TP +.B PERF_MEM_TLB_L1 +Level 1 TLB +.TP +.B PERF_MEM_TLB_L2 +Level 2 TLB +.TP +.B PERF_MEM_TLB_WK +Hardware walker +.TP +.B PERF_MEM_TLB_OS +OS fault handler +.RE +.PD +.RE +.TP +.I transaction +If the +.B PERF_SAMPLE_TRANSACTION +flag is set, then a 64-bit field is recorded describing +the sources of any transactional memory aborts. +.IP +The field is a bitwise combination of the following values: +.RS +.TP +.B PERF_TXN_ELISION +Abort from an elision type transaction (Intel-CPU-specific). +.TP +.B PERF_TXN_TRANSACTION +Abort from a generic transaction. +.TP +.B PERF_TXN_SYNC +Synchronous abort (related to the reported instruction). +.TP +.B PERF_TXN_ASYNC +Asynchronous abort (not related to the reported instruction). +.TP +.B PERF_TXN_RETRY +Retryable abort (retrying the transaction may have succeeded). +.TP +.B PERF_TXN_CONFLICT +Abort due to memory conflicts with other threads. +.TP +.B PERF_TXN_CAPACITY_WRITE +Abort due to write capacity overflow. +.TP +.B PERF_TXN_CAPACITY_READ +Abort due to read capacity overflow. +.RE +.IP +In addition, a user-specified abort code can be obtained from +the high 32 bits of the field by shifting right by +.B PERF_TXN_ABORT_SHIFT +and masking with the value +.BR PERF_TXN_ABORT_MASK . +.TP +.I abi +.TQ +.I regs[weight(mask)] +If +.B PERF_SAMPLE_REGS_INTR +is enabled, then the user CPU registers are recorded. +.IP +The +.I abi +field is one of +.BR PERF_SAMPLE_REGS_ABI_NONE , +.BR PERF_SAMPLE_REGS_ABI_32 , +or +.BR PERF_SAMPLE_REGS_ABI_64 . +.IP +The +.I regs +field is an array of the CPU registers that were specified by +the +.I sample_regs_intr +attr field. +The number of values is the number of bits set in the +.I sample_regs_intr +bit mask. +.TP +.I phys_addr +If the +.B PERF_SAMPLE_PHYS_ADDR +flag is set, then the 64-bit physical address is recorded. +.TP +.I cgroup +If the +.B PERF_SAMPLE_CGROUP +flag is set, +then the 64-bit cgroup ID (for the perf_event subsystem) is recorded. +To get the pathname of the cgroup, the ID should match to one in a +.BR PERF_RECORD_CGROUP . +.TP +.I data_page_size +If the +.B PERF_SAMPLE_DATA_PAGE_SIZE +flag is set, +then the 64-bit page size value of the +.B data +address is recorded. +.TP +.I code_page_size +If the +.B PERF_SAMPLE_CODE_PAGE_SIZE +flag is set, +then the 64-bit page size value of the +.B ip +address is recorded. +.TP +.I size +.TQ +.IR data [ size ] +If +.B PERF_SAMPLE_AUX +is enabled, +a snapshot of the aux buffer is recorded. +.RE +.TP +.B PERF_RECORD_MMAP2 +This record includes extended information on +.BR mmap (2) +calls returning executable mappings. +The format is similar to that of the +.B PERF_RECORD_MMAP +record, but includes extra values that allow uniquely identifying +shared mappings. +Depending on the +.B PERF_RECORD_MISC_MMAP_BUILD_ID +bit in the header, +the extra values have different layout and meanings. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid; + u32 tid; + u64 addr; + u64 len; + u64 pgoff; + union { + struct { + u32 maj; + u32 min; + u64 ino; + u64 ino_generation; + }; + struct { /* if PERF_RECORD_MISC_MMAP_BUILD_ID */ + u8 build_id_size; + u8 __reserved_1; + u16 __reserved_2; + u8 build_id[20]; + }; + }; + u32 prot; + u32 flags; + char filename[]; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I pid +is the process ID. +.TP +.I tid +is the thread ID. +.TP +.I addr +is the address of the allocated memory. +.TP +.I len +is the length of the allocated memory. +.TP +.I pgoff +is the page offset of the allocated memory. +.TP +.I maj +is the major ID of the underlying device. +.TP +.I min +is the minor ID of the underlying device. +.TP +.I ino +is the inode number. +.TP +.I ino_generation +is the inode generation. +.TP +.I build_id_size +is the actual size of +.I build_id +field (up to 20). +.TP +.I build_id +is a raw data to identify a binary. +.TP +.I prot +is the protection information. +.TP +.I flags +is the flags information. +.TP +.I filename +is a string describing the backing of the allocated memory. +.RE +.TP +.BR PERF_RECORD_AUX " (since Linux 4.1)" +.\" commit 68db7e98c3a6ebe7284b6cf14906ed7c55f3f7f0 +This record reports that new data is available in the separate +AUX buffer region. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 aux_offset; + u64 aux_size; + u64 flags; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I aux_offset +offset in the AUX mmap region where the new data begins. +.TP +.I aux_size +size of the data made available. +.TP +.I flags +describes the AUX update. +.RS +.TP +.B PERF_AUX_FLAG_TRUNCATED +if set, then the data returned was truncated to fit the available +buffer size. +.TP +.B PERF_AUX_FLAG_OVERWRITE +.\" commit 2023a0d2829e521fe6ad6b9907f3f90bfbf57142 +if set, then the data returned has overwritten previous data. +.RE +.RE +.TP +.BR PERF_RECORD_ITRACE_START " (since Linux 4.1)" +.\" ec0d7729bbaed4b9d2d3fada693278e13a3d1368 +This record indicates which process has initiated an instruction +trace event, allowing tools to properly correlate the instruction +addresses in the AUX buffer with the proper executable. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid; + u32 tid; +}; +.EE +.in +.RS +.TP +.I pid +process ID of the thread starting an instruction trace. +.TP +.I tid +thread ID of the thread starting an instruction trace. +.RE +.TP +.BR PERF_RECORD_LOST_SAMPLES " (since Linux 4.2)" +.\" f38b0dbb491a6987e198aa6b428db8692a6480f8 +When using hardware sampling (such as Intel PEBS) this record +indicates some number of samples that may have been lost. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 lost; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I lost +the number of potentially lost samples. +.RE +.TP +.BR PERF_RECORD_SWITCH " (since Linux 4.3)" +.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4 +This record indicates a context switch has happened. +The +.B PERF_RECORD_MISC_SWITCH_OUT +bit in the +.I misc +field indicates whether it was a context switch into +or away from the current process. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + struct sample_id sample_id; +}; +.EE +.in +.TP +.BR PERF_RECORD_SWITCH_CPU_WIDE " (since Linux 4.3)" +.\" commit 45ac1403f564f411c6a383a2448688ba8dd705a4 +As with +.B PERF_RECORD_SWITCH +this record indicates a context switch has happened, +but it only occurs when sampling in CPU-wide mode +and provides additional information on the process +being switched to/from. +The +.B PERF_RECORD_MISC_SWITCH_OUT +bit in the +.I misc +field indicates whether it was a context switch into +or away from the current process. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 next_prev_pid; + u32 next_prev_tid; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I next_prev_pid +The process ID of the previous (if switching in) +or next (if switching out) process on the CPU. +.TP +.I next_prev_tid +The thread ID of the previous (if switching in) +or next (if switching out) thread on the CPU. +.RE +.TP +.BR PERF_RECORD_NAMESPACES " (since Linux 4.11)" +.\" commit e422267322cd319e2695a535e47c5b1feeac45eb +This record includes various namespace information of a process. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u32 pid; + u32 tid; + u64 nr_namespaces; + struct { u64 dev, inode } [nr_namespaces]; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I pid +is the process ID +.TP +.I tid +is the thread ID +.TP +.I nr_namespace +is the number of namespaces in this record +.RE +.IP +Each namespace has +.I dev +and +.I inode +fields and is recorded in the +fixed position like below: +.RS +.TP +.BR NET_NS_INDEX = 0 +Network namespace +.TP +.BR UTS_NS_INDEX = 1 +UTS namespace +.TP +.BR IPC_NS_INDEX = 2 +IPC namespace +.TP +.BR PID_NS_INDEX = 3 +PID namespace +.TP +.BR USER_NS_INDEX = 4 +User namespace +.TP +.BR MNT_NS_INDEX = 5 +Mount namespace +.TP +.BR CGROUP_NS_INDEX = 6 +Cgroup namespace +.RE +.TP +.BR PERF_RECORD_KSYMBOL " (since Linux 5.0)" +.\" commit 76193a94522f1d4edf2447a536f3f796ce56343b +This record indicates kernel symbol register/unregister events. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 addr; + u32 len; + u16 ksym_type; + u16 flags; + char name[]; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I addr +is the address of the kernel symbol. +.TP +.I len +is the length of the kernel symbol. +.TP +.I ksym_type +is the type of the kernel symbol. +Currently the following types are available: +.RS +.TP +.B PERF_RECORD_KSYMBOL_TYPE_BPF +The kernel symbol is a BPF function. +.RE +.TP +.I flags +If the +.B PERF_RECORD_KSYMBOL_FLAGS_UNREGISTER +is set, then this event is for unregistering the kernel symbol. +.RE +.TP +.BR PERF_RECORD_BPF_EVENT " (since Linux 5.0)" +.\" commit 6ee52e2a3fe4ea35520720736e6791df1fb67106 +This record indicates BPF program is loaded or unloaded. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u16 type; + u16 flags; + u32 id; + u8 tag[BPF_TAG_SIZE]; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I type +is one of the following values: +.RS +.TP +.B PERF_BPF_EVENT_PROG_LOAD +A BPF program is loaded +.TP +.B PERF_BPF_EVENT_PROG_UNLOAD +A BPF program is unloaded +.RE +.TP +.I id +is the ID of the BPF program. +.TP +.I tag +is the tag of the BPF program. +Currently, +.B BPF_TAG_SIZE +is defined as 8. +.RE +.TP +.BR PERF_RECORD_CGROUP " (since Linux 5.7)" +.\" commit 96aaab686505c449e24d76e76507290dcc30e008 +This record indicates a new cgroup is created and activated. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 id; + char path[]; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I id +is the cgroup identifier. +This can be also retrieved by +.BR name_to_handle_at (2) +on the cgroup path (as a file handle). +.TP +.I path +is the path of the cgroup from the root. +.RE +.TP +.BR PERF_RECORD_TEXT_POKE " (since Linux 5.8)" +.\" commit e17d43b93e544f5016c0251d2074c15568d5d963 +This record indicates a change in the kernel text. +This includes addition and removal of the text +and the corresponding length is zero in this case. +.IP +.in +4n +.EX +struct { + struct perf_event_header header; + u64 addr; + u16 old_len; + u16 new_len; + u8 bytes[]; + struct sample_id sample_id; +}; +.EE +.in +.RS +.TP +.I addr +is the address of the change +.TP +.I old_len +is the old length +.TP +.I new_len +is the new length +.TP +.I bytes +contains old bytes immediately followed by new bytes. +.RE +.RE +.SS Overflow handling +Events can be set to notify when a threshold is crossed, +indicating an overflow. +Overflow conditions can be captured by monitoring the +event file descriptor with +.BR poll (2), +.BR select (2), +or +.BR epoll (7). +Alternatively, the overflow events can be captured via sa signal handler, +by enabling I/O signaling on the file descriptor; see the discussion of the +.B F_SETOWN +and +.B F_SETSIG +operations in +.BR fcntl (2). +.P +Overflows are generated only by sampling events +.RI ( sample_period +must have a nonzero value). +.P +There are two ways to generate overflow notifications. +.P +The first is to set a +.I wakeup_events +or +.I wakeup_watermark +value that will trigger if a certain number of samples +or bytes have been written to the mmap ring buffer. +In this case, +.B POLL_IN +is indicated. +.P +The other way is by use of the +.B PERF_EVENT_IOC_REFRESH +ioctl. +This ioctl adds to a counter that decrements each time the event overflows. +When nonzero, +.B POLL_IN +is indicated, but +once the counter reaches 0 +.B POLL_HUP +is indicated and +the underlying event is disabled. +.P +Refreshing an event group leader refreshes all siblings and +refreshing with a parameter of 0 currently enables infinite +refreshes; +these behaviors are unsupported and should not be relied on. +.\" See https://lkml.org/lkml/2011/5/24/337 +.P +Starting with Linux 3.18, +.\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883 +.B POLL_HUP +is indicated if the event being monitored is attached to a different +process and that process exits. +.SS rdpmc instruction +Starting with Linux 3.4 on x86, you can use the +.\" commit c7206205d00ab375839bd6c7ddb247d600693c09 +.I rdpmc +instruction to get low-latency reads without having to enter the kernel. +Note that using +.I rdpmc +is not necessarily faster than other methods for reading event values. +.P +Support for this can be detected with the +.I cap_usr_rdpmc +field in the mmap page; documentation on how +to calculate event values can be found in that section. +.P +Originally, when rdpmc support was enabled, any process (not just ones +with an active perf event) could use the rdpmc instruction to access +the counters. +Starting with Linux 4.0, +.\" 7911d3f7af14a614617e38245fedf98a724e46a9 +rdpmc support is only allowed if an event is currently enabled +in a process's context. +To restore the old behavior, write the value 2 to +.IR /sys/devices/cpu/rdpmc . +.SS perf_event ioctl calls +Various ioctls act on +.BR perf_event_open () +file descriptors: +.TP +.B PERF_EVENT_IOC_ENABLE +This enables the individual event or event group specified by the +file descriptor argument. +.IP +If the +.B PERF_IOC_FLAG_GROUP +bit is set in the ioctl argument, then all events in a group are +enabled, even if the event specified is not the group leader +(but see BUGS). +.TP +.B PERF_EVENT_IOC_DISABLE +This disables the individual counter or event group specified by the +file descriptor argument. +.IP +Enabling or disabling the leader of a group enables or disables the +entire group; that is, while the group leader is disabled, none of the +counters in the group will count. +Enabling or disabling a member of a group other than the leader +affects only that counter; disabling a non-leader +stops that counter from counting but doesn't affect any other counter. +.IP +If the +.B PERF_IOC_FLAG_GROUP +bit is set in the ioctl argument, then all events in a group are +disabled, even if the event specified is not the group leader +(but see BUGS). +.TP +.B PERF_EVENT_IOC_REFRESH +Non-inherited overflow counters can use this +to enable a counter for a number of overflows specified by the argument, +after which it is disabled. +Subsequent calls of this ioctl add the argument value to the current +count. +An overflow notification with +.B POLL_IN +set will happen on each overflow until the +count reaches 0; when that happens a notification with +.B POLL_HUP +set is sent and the event is disabled. +Using an argument of 0 is considered undefined behavior. +.TP +.B PERF_EVENT_IOC_RESET +Reset the event count specified by the +file descriptor argument to zero. +This resets only the counts; there is no way to reset the +multiplexing +.I time_enabled +or +.I time_running +values. +.IP +If the +.B PERF_IOC_FLAG_GROUP +bit is set in the ioctl argument, then all events in a group are +reset, even if the event specified is not the group leader +(but see BUGS). +.TP +.B PERF_EVENT_IOC_PERIOD +This updates the overflow period for the event. +.IP +Since Linux 3.7 (on ARM) +.\" commit 3581fe0ef37ce12ac7a4f74831168352ae848edc +and Linux 3.14 (all other architectures), +.\" commit bad7192b842c83e580747ca57104dd51fe08c223 +the new period takes effect immediately. +On older kernels, the new period did not take effect until +after the next overflow. +.IP +The argument is a pointer to a 64-bit value containing the +desired new period. +.IP +Prior to Linux 2.6.36, +.\" commit ad0cf3478de8677f720ee06393b3147819568d6a +this ioctl always failed due to a bug +in the kernel. +.TP +.B PERF_EVENT_IOC_SET_OUTPUT +This tells the kernel to report event notifications to the specified +file descriptor rather than the default one. +The file descriptors must all be on the same CPU. +.IP +The argument specifies the desired file descriptor, or \-1 if +output should be ignored. +.TP +.BR PERF_EVENT_IOC_SET_FILTER " (since Linux 2.6.33)" +.\" commit 6fb2915df7f0747d9044da9dbff5b46dc2e20830 +This adds an ftrace filter to this event. +.IP +The argument is a pointer to the desired ftrace filter. +.TP +.BR PERF_EVENT_IOC_ID " (since Linux 3.12)" +.\" commit cf4957f17f2a89984915ea808876d9c82225b862 +This returns the event ID value for the given event file descriptor. +.IP +The argument is a pointer to a 64-bit unsigned integer +to hold the result. +.TP +.BR PERF_EVENT_IOC_SET_BPF " (since Linux 4.1)" +.\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 +This allows attaching a Berkeley Packet Filter (BPF) +program to an existing kprobe tracepoint event. +You need +.B CAP_PERFMON +(since Linux 5.8) or +.B CAP_SYS_ADMIN +privileges to use this ioctl. +.IP +The argument is a BPF program file descriptor that was created by +a previous +.BR bpf (2) +system call. +.TP +.BR PERF_EVENT_IOC_PAUSE_OUTPUT " (since Linux 4.7)" +.\" commit 86e7972f690c1017fd086cdfe53d8524e68c661c +This allows pausing and resuming the event's ring-buffer. +A paused ring-buffer does not prevent generation of samples, +but simply discards them. +The discarded samples are considered lost, and cause a +.B PERF_RECORD_LOST +sample to be generated when possible. +An overflow signal may still be triggered by the discarded sample +even though the ring-buffer remains empty. +.IP +The argument is an unsigned 32-bit integer. +A nonzero value pauses the ring-buffer, while a +zero value resumes the ring-buffer. +.TP +.BR PERF_EVENT_MODIFY_ATTRIBUTES " (since Linux 4.17)" +.\" commit 32ff77e8cc9e66cc4fb38098f64fd54cc8f54573 +This allows modifying an existing event without the overhead +of closing and reopening a new event. +Currently this is supported only for breakpoint events. +.IP +The argument is a pointer to a +.I perf_event_attr +structure containing the updated event settings. +.TP +.BR PERF_EVENT_IOC_QUERY_BPF " (since Linux 4.16)" +.\" commit f371b304f12e31fe30207c41ca7754564e0ea4dc +This allows querying which Berkeley Packet Filter (BPF) +programs are attached to an existing kprobe tracepoint. +You can only attach one BPF program per event, but you can +have multiple events attached to a tracepoint. +Querying this value on one tracepoint event returns the ID +of all BPF programs in all events attached to the tracepoint. +You need +.B CAP_PERFMON +(since Linux 5.8) or +.B CAP_SYS_ADMIN +privileges to use this ioctl. +.IP +The argument is a pointer to a structure +.in +4n +.EX +struct perf_event_query_bpf { + __u32 ids_len; + __u32 prog_cnt; + __u32 ids[0]; +}; +.EE +.in +.IP +The +.I ids_len +field indicates the number of ids that can fit in the provided +.I ids +array. +The +.I prog_cnt +value is filled in by the kernel with the number of attached +BPF programs. +The +.I ids +array is filled with the ID of each attached BPF program. +If there are more programs than will fit in the array, then the +kernel will return +.B ENOSPC +and +.I ids_len +will indicate the number of program IDs that were successfully copied. +.\" +.SS Using prctl(2) +A process can enable or disable all currently open event groups +using the +.BR prctl (2) +.B PR_TASK_PERF_EVENTS_ENABLE +and +.B PR_TASK_PERF_EVENTS_DISABLE +operations. +This applies only to events created locally by the calling process. +This does not apply to events created by other processes attached +to the calling process or inherited events from a parent process. +Only group leaders are enabled and disabled, +not any other members of the groups. +.SS perf_event related configuration files +Files in +.I /proc/sys/kernel/ +.RS 4 +.TP +.I /proc/sys/kernel/perf_event_paranoid +The +.I perf_event_paranoid +file can be set to restrict access to the performance counters. +.IP +.PD 0 +.RS +.TP +.B 2 +allow only user-space measurements (default since Linux 4.6). +.\" default changed in commit 0161028b7c8aebef64194d3d73e43bc3b53b5c66 +.TP +.B 1 +allow both kernel and user measurements (default before Linux 4.6). +.TP +.B 0 +allow access to CPU-specific data but not raw tracepoint samples. +.TP +.B \-1 +no restrictions. +.RE +.PD +.IP +The existence of the +.I perf_event_paranoid +file is the official method for determining if a kernel supports +.BR perf_event_open (). +.TP +.I /proc/sys/kernel/perf_event_max_sample_rate +This sets the maximum sample rate. +Setting this too high can allow +users to sample at a rate that impacts overall machine performance +and potentially lock up the machine. +The default value is +100000 (samples per second). +.TP +.I /proc/sys/kernel/perf_event_max_stack +.\" Introduced in c5dfd78eb79851e278b7973031b9ca363da87a7e +This file sets the maximum depth of stack frame entries reported +when generating a call trace. +.TP +.I /proc/sys/kernel/perf_event_mlock_kb +Maximum number of pages an unprivileged user can +.BR mlock (2). +The default is 516 (kB). +.RE +.P +Files in +.I /sys/bus/event_source/devices/ +.P +.RS 4 +Since Linux 2.6.34, the kernel supports having multiple PMUs +available for monitoring. +Information on how to program these PMUs can be found under +.IR /sys/bus/event_source/devices/ . +Each subdirectory corresponds to a different PMU. +.TP +.IR /sys/bus/event_source/devices/*/type " (since Linux 2.6.38)" +.\" commit abe43400579d5de0078c2d3a760e6598e183f871 +This contains an integer that can be used in the +.I type +field of +.I perf_event_attr +to indicate that you wish to use this PMU. +.TP +.IR /sys/bus/event_source/devices/cpu/rdpmc " (since Linux 3.4)" +.\" commit 0c9d42ed4cee2aa1dfc3a260b741baae8615744f +If this file is 1, then direct user-space access to the +performance counter registers is allowed via the rdpmc instruction. +This can be disabled by echoing 0 to the file. +.IP +As of Linux 4.0 +.\" a66734297f78707ce39d756b656bfae861d53f62 +.\" 7911d3f7af14a614617e38245fedf98a724e46a9 +the behavior has changed, so that 1 now means only allow access +to processes with active perf events, with 2 indicating the old +allow-anyone-access behavior. +.TP +.IR /sys/bus/event_source/devices/*/format/ " (since Linux 3.4)" +.\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33 +This subdirectory contains information on the architecture-specific +subfields available for programming the various +.I config +fields in the +.I perf_event_attr +struct. +.IP +The content of each file is the name of the config field, followed +by a colon, followed by a series of integer bit ranges separated by +commas. +For example, the file +.I event +may contain the value +.I config1:1,6\-10,44 +which indicates that event is an attribute that occupies bits 1,6\[en]10, and 44 +of +.IR perf_event_attr::config1 . +.TP +.IR /sys/bus/event_source/devices/*/events/ " (since Linux 3.4)" +.\" commit 641cc938815dfd09f8fa1ec72deb814f0938ac33 +This subdirectory contains files with predefined events. +The contents are strings describing the event settings +expressed in terms of the fields found in the previously mentioned +.I ./format/ +directory. +These are not necessarily complete lists of all events supported by +a PMU, but usually a subset of events deemed useful or interesting. +.IP +The content of each file is a list of attribute names +separated by commas. +Each entry has an optional value (either hex or decimal). +If no value is specified, then it is assumed to be a single-bit +field with a value of 1. +An example entry may look like this: +.IR event=0x2,inv,ldlat=3 . +.TP +.I /sys/bus/event_source/devices/*/uevent +This file is the standard kernel device interface +for injecting hotplug events. +.TP +.IR /sys/bus/event_source/devices/*/cpumask " (since Linux 3.7)" +.\" commit 314d9f63f385096580e9e2a06eaa0745d92fe4ac +The +.I cpumask +file contains a comma-separated list of integers that +indicate a representative CPU number for each socket (package) +on the motherboard. +This is needed when setting up uncore or northbridge events, as +those PMUs present socket-wide events. +.RE +.SH RETURN VALUE +On success, +.BR perf_event_open () +returns the new file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +The errors returned by +.BR perf_event_open () +can be inconsistent, and may +vary across processor architectures and performance monitoring units. +.TP +.B E2BIG +Returned if the +.I perf_event_attr +.I size +value is too small +(smaller than +.BR PERF_ATTR_SIZE_VER0 ), +too big (larger than the page size), +or larger than the kernel supports and the extra bytes are not zero. +When +.B E2BIG +is returned, the +.I perf_event_attr +.I size +field is overwritten by the kernel to be the size of the structure +it was expecting. +.TP +.B EACCES +Returned when the requested event requires +.B CAP_PERFMON +(since Linux 5.8) or +.B CAP_SYS_ADMIN +permissions (or a more permissive perf_event paranoid setting). +Some common cases where an unprivileged process +may encounter this error: +attaching to a process owned by a different user; +monitoring all processes on a given CPU (i.e., specifying the +.I pid +argument as \-1); +and not setting +.I exclude_kernel +when the paranoid setting requires it. +.TP +.B EBADF +Returned if the +.I group_fd +file descriptor is not valid, or, if +.B PERF_FLAG_PID_CGROUP +is set, +the cgroup file descriptor in +.I pid +is not valid. +.TP +.BR EBUSY " (since Linux 4.1)" +.\" bed5b25ad9c8a2f5d735ef0bc746ec870c01c1b0 +Returned if another event already has exclusive +access to the PMU. +.TP +.B EFAULT +Returned if the +.I attr +pointer points at an invalid memory address. +.TP +.B EINTR +Returned when trying to mix perf and ftrace handling +for a uprobe. +.TP +.B EINVAL +Returned if the specified event is invalid. +There are many possible reasons for this. +A not-exhaustive list: +.I sample_freq +is higher than the maximum setting; +the +.I cpu +to monitor does not exist; +.I read_format +is out of range; +.I sample_type +is out of range; +the +.I flags +value is out of range; +.I exclusive +or +.I pinned +set and the event is not a group leader; +the event +.I config +values are out of range or set reserved bits; +the generic event selected is not supported; or +there is not enough room to add the selected event. +.TP +.B EMFILE +Each opened event uses one file descriptor. +If a large number of events are opened, +the per-process limit on the number of open file descriptors will be reached, +and no more events can be created. +.TP +.B ENODEV +Returned when the event involves a feature not supported +by the current CPU. +.TP +.B ENOENT +Returned if the +.I type +setting is not valid. +This error is also returned for +some unsupported generic events. +.TP +.B ENOSPC +Prior to Linux 3.3, if there was not enough room for the event, +.\" commit aa2bc1ade59003a379ffc485d6da2d92ea3370a6 +.B ENOSPC +was returned. +In Linux 3.3, this was changed to +.BR EINVAL . +.B ENOSPC +is still returned if you try to add more breakpoint events +than supported by the hardware. +.TP +.B ENOSYS +Returned if +.B PERF_SAMPLE_STACK_USER +is set in +.I sample_type +and it is not supported by hardware. +.TP +.B EOPNOTSUPP +Returned if an event requiring a specific hardware feature is +requested but there is no hardware support. +This includes requesting low-skid events if not supported, +branch tracing if it is not available, sampling if no PMU +interrupt is available, and branch stacks for software events. +.TP +.BR EOVERFLOW " (since Linux 4.8)" +.\" 97c79a38cd454602645f0470ffb444b3b75ce574 +Returned if +.B PERF_SAMPLE_CALLCHAIN +is requested and +.I sample_max_stack +is larger than the maximum specified in +.IR /proc/sys/kernel/perf_event_max_stack . +.TP +.B EPERM +Returned on many (but not all) architectures when an unsupported +.IR exclude_hv ", " exclude_idle ", " exclude_user ", or " exclude_kernel +setting is specified. +.IP +It can also happen, as with +.BR EACCES , +when the requested event requires +.B CAP_PERFMON +(since Linux 5.8) or +.B CAP_SYS_ADMIN +permissions (or a more permissive perf_event paranoid setting). +This includes setting a breakpoint on a kernel address, +and (since Linux 3.13) setting a kernel function-trace tracepoint. +.\" commit a4e95fc2cbb31d70a65beffeaf8773f881328c34 +.TP +.B ESRCH +Returned if attempting to attach to a process that does not exist. +.SH STANDARDS +Linux. +.SH HISTORY +.BR perf_event_open () +was introduced in Linux 2.6.31 but was called +.\" commit 0793a61d4df8daeac6492dbf8d2f3e5713caae5e +.BR perf_counter_open (). +It was renamed in Linux 2.6.32. +.\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6 +.SH NOTES +The official way of knowing if +.BR perf_event_open () +support is enabled is checking +for the existence of the file +.IR /proc/sys/kernel/perf_event_paranoid . +.P +.B CAP_PERFMON +capability (since Linux 5.8) provides secure approach to +performance monitoring and observability operations in a system +according to the principal of least privilege (POSIX IEEE 1003.1e). +Accessing system performance monitoring and observability operations +using +.B CAP_PERFMON +rather than the much more powerful +.B CAP_SYS_ADMIN +excludes chances to misuse credentials and makes operations more secure. +.B CAP_SYS_ADMIN +usage for secure system performance monitoring and observability +is discouraged in favor of the +.B CAP_PERFMON +capability. +.SH BUGS +The +.B F_SETOWN_EX +option to +.BR fcntl (2) +is needed to properly get overflow signals in threads. +This was introduced in Linux 2.6.32. +.\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5 +.P +Prior to Linux 2.6.33 (at least for x86), +.\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1 +the kernel did not check +if events could be scheduled together until read time. +The same happens on all known kernels if the NMI watchdog is enabled. +This means to see if a given set of events works you have to +.BR perf_event_open (), +start, then read before you know for sure you +can get valid measurements. +.P +Prior to Linux 2.6.34, +.\" FIXME . cannot find a kernel commit for this one +event constraints were not enforced by the kernel. +In that case, some events would silently return "0" if the kernel +scheduled them in an improper counter slot. +.P +Prior to Linux 2.6.34, there was a bug when multiplexing where the +wrong results could be returned. +.\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8 +.P +Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if +"inherit" is enabled and many threads are started. +.\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd +.P +Prior to Linux 2.6.35, +.\" commit 050735b08ca8a016bbace4445fa025b88fee770b +.B PERF_FORMAT_GROUP +did not work with attached processes. +.P +There is a bug in the kernel code between +Linux 2.6.36 and Linux 3.0 that ignores the +"watermark" field and acts as if a wakeup_event +was chosen if the union has a +nonzero value in it. +.\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02 +.P +From Linux 2.6.31 to Linux 3.4, the +.B PERF_IOC_FLAG_GROUP +ioctl argument was broken and would repeatedly operate +on the event specified rather than iterating across +all sibling events in a group. +.\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e +.P +From Linux 3.4 to Linux 3.11, the mmap +.\" commit fa7315871046b9a4c48627905691dbde57e51033 +.I cap_usr_rdpmc +and +.I cap_usr_time +bits mapped to the same location. +Code should migrate to the new +.I cap_user_rdpmc +and +.I cap_user_time +fields instead. +.P +Always double-check your results! +Various generalized events have had wrong values. +For example, retired branches measured +the wrong thing on AMD machines until Linux 2.6.35. +.\" commit f287d332ce835f77a4f5077d2c0ef1e3f9ea42d2 +.SH EXAMPLES +The following is a short example that measures the total +instruction count of a call to +.BR printf (3). +.P +.\" SRC BEGIN (perf_event_open.c) +.EX +#include +#include +#include +#include +#include +#include +#include +#include +\& +static long +perf_event_open(struct perf_event_attr *hw_event, pid_t pid, + int cpu, int group_fd, unsigned long flags) +{ + int ret; +\& + ret = syscall(SYS_perf_event_open, hw_event, pid, cpu, + group_fd, flags); + return ret; +} +\& +int +main(void) +{ + int fd; + long long count; + struct perf_event_attr pe; +\& + memset(&pe, 0, sizeof(pe)); + pe.type = PERF_TYPE_HARDWARE; + pe.size = sizeof(pe); + pe.config = PERF_COUNT_HW_INSTRUCTIONS; + pe.disabled = 1; + pe.exclude_kernel = 1; + pe.exclude_hv = 1; +\& + fd = perf_event_open(&pe, 0, \-1, \-1, 0); + if (fd == \-1) { + fprintf(stderr, "Error opening leader %llx\en", pe.config); + exit(EXIT_FAILURE); + } +\& + ioctl(fd, PERF_EVENT_IOC_RESET, 0); + ioctl(fd, PERF_EVENT_IOC_ENABLE, 0); +\& + printf("Measuring instruction count for this printf\en"); +\& + ioctl(fd, PERF_EVENT_IOC_DISABLE, 0); + read(fd, &count, sizeof(count)); +\& + printf("Used %lld instructions\en", count); +\& + close(fd); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR perf (1), +.BR fcntl (2), +.BR mmap (2), +.BR open (2), +.BR prctl (2), +.BR read (2) +.P +.I Documentation/admin\-guide/perf\-security.rst +in the kernel source tree diff --git a/man/man2/perfmonctl.2 b/man/man2/perfmonctl.2 new file mode 100644 index 0000000..7ba64cb --- /dev/null +++ b/man/man2/perfmonctl.2 @@ -0,0 +1,193 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" and Copyright (C) 2013 Michael Kerrisk +.\" Written by Ivana Varekova +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH perfmonctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +perfmonctl \- interface to IA-64 performance monitoring unit +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "long perfmonctl(int " fd ", int " cmd ", void " arg [. narg "], int " narg ");" +.fi +.P +.IR Note : +There is no glibc wrapper for this system call; see HISTORY. +.SH DESCRIPTION +The IA-64-specific +.BR perfmonctl () +system call provides an interface to the +PMU (performance monitoring unit). +The PMU consists of PMD (performance monitoring data) registers and +PMC (performance monitoring control) registers, +which gather hardware statistics. +.P +.BR perfmonctl () +applies the operation +.I cmd +to the input arguments specified by +.IR arg . +The number of arguments is defined by \fInarg\fR. +The +.I fd +argument specifies the perfmon context to operate on. +.P +Supported values for +.I cmd +are: +.TP +.B PFM_CREATE_CONTEXT +.nf +.BI "perfmonctl(int " fd ", PFM_CREATE_CONTEXT, pfarg_context_t *" ctxt ", 1);" +.fi +Set up a context. +.IP +The +.I fd +parameter is ignored. +A new perfmon context is created as specified in +.I ctxt +and its file descriptor is returned in \fIctxt\->ctx_fd\fR. +.IP +The file descriptor can be used in subsequent calls to +.BR perfmonctl () +and can be used to read event notifications (type +.IR pfm_msg_t ) +using +.BR read (2). +The file descriptor is pollable using +.BR select (2), +.BR poll (2), +and +.BR epoll (7). +.IP +The context can be destroyed by calling +.BR close (2) +on the file descriptor. +.TP +.B PFM_WRITE_PMCS +.\" pfm_write_pmcs() +.nf +.BI "perfmonctl(int " fd ", PFM_WRITE_PMCS, pfarg_reg_t *" pmcs ", n);" +.fi +Set PMC registers. +.TP +.B PFM_WRITE_PMDS +.nf +.BI "perfmonctl(int " fd ", PFM_WRITE_PMDS, pfarg_reg_t *" pmds ", n);" +.fi +.\" pfm_write_pmds() +Set PMD registers. +.TP +.B PFM_READ_PMDS +.\" pfm_read_pmds() +.nf +.BI "perfmonctl(int " fd ", PFM_READ_PMDS, pfarg_reg_t *" pmds ", n);" +.fi +Read PMD registers. +.TP +.B PFM_START +.\" pfm_start() +.nf +.\" .BI "perfmonctl(int " fd ", PFM_START, arg, 1); +.BI "perfmonctl(int " fd ", PFM_START, NULL, 0);" +.fi +Start monitoring. +.TP +.B PFM_STOP +.\" pfm_stop() +.nf +.BI "perfmonctl(int " fd ", PFM_STOP, NULL, 0);" +.fi +Stop monitoring. +.TP +.B PFM_LOAD_CONTEXT +.\" pfm_context_load() +.nf +.BI "perfmonctl(int " fd ", PFM_LOAD_CONTEXT, pfarg_load_t *" largs ", 1);" +.fi +Attach the context to a thread. +.TP +.B PFM_UNLOAD_CONTEXT +.\" pfm_context_unload() +.nf +.BI "perfmonctl(int " fd ", PFM_UNLOAD_CONTEXT, NULL, 0);" +.fi +Detach the context from a thread. +.TP +.B PFM_RESTART +.\" pfm_restart() +.nf +.BI "perfmonctl(int " fd ", PFM_RESTART, NULL, 0);" +.fi +Restart monitoring after receiving an overflow notification. +.TP +.B PFM_GET_FEATURES +.\" pfm_get_features() +.nf +.BI "perfmonctl(int " fd ", PFM_GET_FEATURES, pfarg_features_t *" arg ", 1);" +.fi +.TP +.B PFM_DEBUG +.\" pfm_debug() +.nf +.BI "perfmonctl(int " fd ", PFM_DEBUG, " val ", 0);" +.fi +If +.I val +is nonzero, enable debugging mode, otherwise disable. +.TP +.B PFM_GET_PMC_RESET_VAL +.\" pfm_get_pmc_reset() +.nf +.BI "perfmonctl(int " fd ", PFM_GET_PMC_RESET_VAL, pfarg_reg_t *" req ", n);" +.fi +Reset PMC registers to default values. +.\" +.\" +.\" .TP +.\" .B PFM_CREATE_EVTSETS +.\" +.\" create or modify event sets +.\" .nf +.\" .BI "perfmonctl(int " fd ", PFM_CREATE_EVTSETS, pfarg_setdesc_t *desc , n); +.\" .fi +.\" .TP +.\" .B PFM_DELETE_EVTSETS +.\" delete event sets +.\" .nf +.\" .BI "perfmonctl(int " fd ", PFM_DELETE_EVTSET, pfarg_setdesc_t *desc , n); +.\" .fi +.\" .TP +.\" .B PFM_GETINFO_EVTSETS +.\" get information about event sets +.\" .nf +.\" .BI "perfmonctl(int " fd ", PFM_GETINFO_EVTSETS, pfarg_setinfo_t *info, n); +.\" .fi +.SH RETURN VALUE +.BR perfmonctl () +returns zero when the operation is successful. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH STANDARDS +Linux on IA-64. +.SH HISTORY +Added in Linux 2.4; +.\" commit ecf5b72d5f66af843f189dfe9ce31598c3e48ad7 +removed in Linux 5.10. +.P +This system call was broken for many years, +and ultimately removed in Linux 5.10. +.P +glibc does not provide a wrapper for this system call; +on kernels where it exists, call it using +.BR syscall (2). +.SH SEE ALSO +.BR gprof (1) +.P +The perfmon2 interface specification diff --git a/man/man2/personality.2 b/man/man2/personality.2 new file mode 100644 index 0000000..bebd3b4 --- /dev/null +++ b/man/man2/personality.2 @@ -0,0 +1,296 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" and Copyright (C) 2016, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created Sat Aug 21 1995 Thomas K. Dyas +.\" +.\" typo corrected, aeb, 950825 +.\" added layout change from joey, 960722 +.\" changed prototype, documented 0xffffffff, aeb, 030101 +.\" Modified 2004-11-03 patch from Martin Schulze +.\" +.TH personality 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +personality \- set the process execution domain +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int personality(unsigned long " persona ); +.fi +.SH DESCRIPTION +Linux supports different execution domains, or personalities, for each +process. +Among other things, execution domains tell Linux how to map +signal numbers into signal actions. +The execution domain system allows +Linux to provide limited support for binaries compiled under other +UNIX-like operating systems. +.P +If +.I persona +is not +0xffffffff, then +.BR personality () +sets the caller's execution domain to the value specified by +.IR persona . +Specifying +.I persona +as 0xffffffff provides a way of retrieving +the current persona without changing it. +.P +A list of the available execution domains can be found in +.IR . +The execution domain is a 32-bit value in which the top three +bytes are set aside for flags that cause the kernel to modify the +behavior of certain system calls so as to emulate historical or +architectural quirks. +The least significant byte is a value defining the personality +the kernel should assume. +The flag values are as follows: +.TP +.BR ADDR_COMPAT_LAYOUT " (since Linux 2.6.9)" +With this flag set, provide legacy virtual address space layout. +.TP +.BR ADDR_NO_RANDOMIZE " (since Linux 2.6.12)" +With this flag set, disable address-space-layout randomization. +.TP +.BR ADDR_LIMIT_32BIT " (since Linux 2.2)" +Limit the address space to 32 bits. +.TP +.BR ADDR_LIMIT_3GB " (since Linux 2.4.0)" +With this flag set, use 0xc0000000 as the offset at which to search +a virtual memory chunk on +.BR mmap (2); +otherwise use 0xffffe000. +Applies to 32-bit x86 processes only. +.TP +.BR FDPIC_FUNCPTRS " (since Linux 2.6.11)" +User-space function pointers to signal handlers point +to descriptors. +Applies only to ARM if BINFMT_ELF_FDPIC and SuperH. +.TP +.BR MMAP_PAGE_ZERO " (since Linux 2.4.0)" +Map page 0 as read-only +(to support binaries that depend on this SVr4 behavior). +.TP +.BR READ_IMPLIES_EXEC " (since Linux 2.6.8)" +With this flag set, +.B PROT_READ +implies +.B PROT_EXEC +for +.BR mmap (2). +.TP +.BR SHORT_INODE " (since Linux 2.4.0)" +No effect. +.TP +.BR STICKY_TIMEOUTS " (since Linux 1.2.0)" +With this flag set, +.BR select (2), +.BR pselect (2), +and +.BR ppoll (2) +do not modify the returned timeout argument when +interrupted by a signal handler. +.TP +.BR UNAME26 " (since Linux 3.1)" +Have +.BR uname (2) +report a 2.6.(40+x) version number rather than a MAJOR.x version number. +Added as a stopgap measure to support broken applications that +could not handle the +kernel version-numbering switch from Linux 2.6.x to Linux 3.x. +.TP +.BR WHOLE_SECONDS " (since Linux 1.2.0)" +No effect. +.P +The available execution domains are: +.TP +.BR PER_BSD " (since Linux 1.2.0)" +BSD. (No effects.) +.TP +.BR PER_HPUX " (since Linux 2.4)" +Support for 32-bit HP/UX. +This support was never complete, and was dropped so that since Linux 4.0, +this value has no effect. +.TP +.BR PER_IRIX32 " (since Linux 2.2)" +IRIX 5 32-bit. +Never fully functional; support dropped in Linux 2.6.27. +Implies +.BR STICKY_TIMEOUTS . +.TP +.BR PER_IRIX64 " (since Linux 2.2)" +IRIX 6 64-bit. +Implies +.BR STICKY_TIMEOUTS ; +otherwise no effect. +.TP +.BR PER_IRIXN32 " (since Linux 2.2)" +IRIX 6 new 32-bit. +Implies +.BR STICKY_TIMEOUTS ; +otherwise no effect. +.TP +.BR PER_ISCR4 " (since Linux 1.2.0)" +Implies +.BR STICKY_TIMEOUTS ; +otherwise no effect. +.TP +.BR PER_LINUX " (since Linux 1.2.0)" +Linux. +.TP +.BR PER_LINUX32 " (since Linux 2.2)" +.BR uname (2) +returns the name of the 32-bit architecture in the +.I machine +field ("i686" instead of "x86_64", &c.). +.IP +Under ia64 (Itanium), processes with this personality don't have the +O_LARGEFILE +.BR open (2) +flag forced. +.IP +Under 64-bit ARM, setting this personality is forbidden if +.BR execve (2)ing +a 32-bit process would also be forbidden +(cf. the allow_mismatched_32bit_el0 kernel parameter and +.IR Documentation/arm64/asymmetric-32bit.rst ). +.TP +.BR PER_LINUX32_3GB " (since Linux 2.4)" +Same as +.BR PER_LINUX32 , +but implies +.BR ADDR_LIMIT_3GB . +.TP +.BR PER_LINUX_32BIT " (since Linux 2.0)" +Same as +.BR PER_LINUX , +but implies +.BR ADDR_LIMIT_32BIT . +.TP +.BR PER_LINUX_FDPIC " (since Linux 2.6.11)" +Same as +.BR PER_LINUX , +but implies +.BR FDPIC_FUNCPTRS . +.TP +.BR PER_OSF4 " (since Linux 2.4)" +OSF/1 v4. +.\" commit 987f20a9dcce3989e48d87cff3952c095c994445 +No effect since Linux 6.1, which removed a.out binary support. +Before, on alpha, +.\" Following is from a comment in arch/alpha/kernel/osf_sys.c +would clear top 32 bits of iov_len in the user's buffer for +compatibility with old versions of OSF/1 where iov_len +was defined as. +.IR int . +.TP +.BR PER_OSR5 " (since Linux 2.4)" +SCO OpenServer 5. +Implies +.B STICKY_TIMEOUTS +and +.BR WHOLE_SECONDS ; +otherwise no effect. +.TP +.BR PER_RISCOS " (since Linux 2.3.7; macro since Linux 2.3.13)" +Acorn RISC OS/Arthur (MIPS). +No effect. +.\" commit 125ec7b4e90cbae4eed5a7ff1ee479cc331dcf3c +Up to Linux v4.0, would set the emulation altroot to +.I /usr/gnemul/riscos +(cf.\& +.BR PER_SUNOS , +below). +Before then, up to Linux 2.6.3, just Arthur emulation. +.TP +.BR PER_SCOSVR3 " (since Linux 1.2.0)" +SCO UNIX System V Release 3. +Same as +.BR PER_OSR5 , +but also implies +.BR SHORT_INODE . +.TP +.BR PER_SOLARIS " (since Linux 2.4)" +Solaris. +Implies +.BR STICKY_TIMEOUTS ; +otherwise no effect. +.TP +.BR PER_SUNOS " (since Linux 2.4.0)" +Sun OS. +Same as +.BR PER_BSD , +but implies +.BR STICKY_TIMEOUTS . +Prior to Linux 2.6.26, +diverted library and dynamic linker searches to +.IR /usr/gnemul . +Buggy, largely unmaintained, and almost entirely unused. +.TP +.BR PER_SVR3 " (since Linux 1.2.0)" +AT&T UNIX System V Release 3. +Implies +.B STICKY_TIMEOUTS +and +.BR SHORT_INODE ; +otherwise no effect. +.TP +.BR PER_SVR4 " (since Linux 1.2.0)" +AT&T UNIX System V Release 4. +Implies +.B STICKY_TIMEOUTS +and +.BR MMAP_PAGE_ZERO ; +otherwise no effect. +.TP +.BR PER_UW7 " (since Linux 2.4)" +UnixWare 7. +Implies +.B STICKY_TIMEOUTS +and +.BR MMAP_PAGE_ZERO ; +otherwise no effect. +.TP +.BR PER_WYSEV386 " (since Linux 1.2.0)" +WYSE UNIX System V/386. +Implies +.B STICKY_TIMEOUTS +and +.BR SHORT_INODE ; +otherwise no effect. +.TP +.BR PER_XENIX " (since Linux 1.2.0)" +XENIX. +Implies +.B STICKY_TIMEOUTS +and +.BR SHORT_INODE ; +otherwise no effect. +.SH RETURN VALUE +On success, the previous +.I persona +is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The kernel was unable to change the personality. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 1.1.20, +.\" (and thus first in a stable kernel release with Linux 1.2.0) +glibc 2.3. +.\" personality wrapper first appeared in glibc 1.90, +.\" was added later in glibc 2.2.91. +.SH SEE ALSO +.BR setarch (8) diff --git a/man/man2/phys.2 b/man/man2/phys.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/phys.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/pidfd_getfd.2 b/man/man2/pidfd_getfd.2 new file mode 100644 index 0000000..2db690b --- /dev/null +++ b/man/man2/pidfd_getfd.2 @@ -0,0 +1,144 @@ +.\" Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pidfd_getfd 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pidfd_getfd \- obtain a duplicate of another process's file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_pidfd_getfd, int " pidfd ", int " targetfd , +.BI " unsigned int " flags ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR pidfd_getfd (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR pidfd_getfd () +system call allocates a new file descriptor in the calling process. +This new file descriptor is a duplicate of an existing file descriptor, +.IR targetfd , +in the process referred to by the PID file descriptor +.IR pidfd . +.P +The duplicate file descriptor refers to the same open file description (see +.BR open (2)) +as the original file descriptor in the process referred to by +.IR pidfd . +The two file descriptors thus share file status flags and file offset. +Furthermore, operations on the underlying file object +(for example, assigning an address to a socket object using +.BR bind (2)) +can equally be performed via the duplicate file descriptor. +.P +The close-on-exec flag +.RB ( FD_CLOEXEC ; +see +.BR fcntl (2)) +is set on the file descriptor returned by +.BR pidfd_getfd (). +.P +The +.I flags +argument is reserved for future use. +Currently, it must be specified as 0. +.P +Permission to duplicate another process's file descriptor +is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_REALCREDS +check (see +.BR ptrace (2)). +.SH RETURN VALUE +On success, +.BR pidfd_getfd () +returns a file descriptor (a nonnegative integer). +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I pidfd +is not a valid PID file descriptor. +.TP +.B EBADF +.I targetfd +is not an open file descriptor in the process referred to by +.IR pidfd . +.TP +.B EINVAL +.I flags +is not 0. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached +(see the description of +.B RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B EPERM +The calling process did not have +.B PTRACE_MODE_ATTACH_REALCREDS +permissions (see +.BR ptrace (2)) +over the process referred to by +.IR pidfd . +.TP +.B ESRCH +The process referred to by +.I pidfd +does not exist +(i.e., it has terminated and been waited on). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.6. +.\" commit 8649c322f75c96e7ced2fec201e123b2b073bf09 +.SH NOTES +For a description of PID file descriptors, see +.BR pidfd_open (2). +.P +The effect of +.BR pidfd_getfd () +is similar to the use of +.B SCM_RIGHTS +messages described in +.BR unix (7), +but differs in the following respects: +.IP \[bu] 3 +In order to pass a file descriptor using an +.B SCM_RIGHTS +message, +the two processes must first establish a UNIX domain socket connection. +.IP \[bu] +The use of +.B SCM_RIGHTS +requires cooperation on the part of the process whose +file descriptor is being copied. +By contrast, no such cooperation is necessary when using +.BR pidfd_getfd (). +.IP \[bu] +The ability to use +.BR pidfd_getfd () +is restricted by a +.B PTRACE_MODE_ATTACH_REALCREDS +ptrace access mode check. +.SH SEE ALSO +.BR clone3 (2), +.BR dup (2), +.BR kcmp (2), +.BR pidfd_open (2) diff --git a/man/man2/pidfd_open.2 b/man/man2/pidfd_open.2 new file mode 100644 index 0000000..9c4c840 --- /dev/null +++ b/man/man2/pidfd_open.2 @@ -0,0 +1,270 @@ +.\" Copyright (c) 2019 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pidfd_open 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pidfd_open \- obtain a file descriptor that refers to a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_pidfd_open, pid_t " pid ", unsigned int " flags ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR pidfd_open (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR pidfd_open () +system call creates a file descriptor that refers to +the process whose PID is specified in +.IR pid . +The file descriptor is returned as the function result; +the close-on-exec flag is set on the file descriptor. +.P +The +.I flags +argument either has the value 0, or contains the following flag: +.TP +.BR PIDFD_NONBLOCK " (since Linux 5.10)" +.\" commit 4da9af0014b51c8b015ed8c622440ef28912efe6 +Return a nonblocking file descriptor. +If the process referred to by the file descriptor has not yet terminated, +then an attempt to wait on the file descriptor using +.BR waitid (2) +will immediately return the error +.B EAGAIN +rather than blocking. +.SH RETURN VALUE +On success, +.BR pidfd_open () +returns a file descriptor (a nonnegative integer). +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I flags +is not valid. +.TP +.B EINVAL +.I pid +is not valid. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached +(see the description of +.B RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENODEV +The anonymous inode filesystem is not available in this kernel. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ESRCH +The process specified by +.I pid +does not exist. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.3. +.SH NOTES +The following code sequence can be used to obtain a file descriptor +for the child of +.BR fork (2): +.P +.in +4n +.EX +pid = fork(); +if (pid > 0) { /* If parent */ + pidfd = pidfd_open(pid, 0); + ... +} +.EE +.in +.P +Even if the child has already terminated by the time of the +.BR pidfd_open () +call, its PID will not have been recycled and the returned +file descriptor will refer to the resulting zombie process. +Note, however, that this is guaranteed only if the following +conditions hold true: +.IP \[bu] 3 +the disposition of +.B SIGCHLD +has not been explicitly set to +.B SIG_IGN +(see +.BR sigaction (2)); +.IP \[bu] +the +.B SA_NOCLDWAIT +flag was not specified while establishing a handler for +.B SIGCHLD +or while setting the disposition of that signal to +.B SIG_DFL +(see +.BR sigaction (2)); +and +.IP \[bu] +the zombie process was not reaped elsewhere in the program +(e.g., either by an asynchronously executed signal handler or by +.BR wait (2) +or similar in another thread). +.P +If any of these conditions does not hold, +then the child process (along with a PID file descriptor that refers to it) +should instead be created using +.BR clone (2) +with the +.B CLONE_PIDFD +flag. +.\" +.SS Use cases for PID file descriptors +A PID file descriptor returned by +.BR pidfd_open () +(or by +.BR clone (2) +with the +.B CLONE_PID +flag) can be used for the following purposes: +.IP \[bu] 3 +The +.BR pidfd_send_signal (2) +system call can be used to send a signal to the process referred to by +a PID file descriptor. +.IP \[bu] +A PID file descriptor can be monitored using +.BR poll (2), +.BR select (2), +and +.BR epoll (7). +When the process that it refers to terminates, +these interfaces indicate the file descriptor as readable. +Note, however, that in the current implementation, +nothing can be read from the file descriptor +.RB ( read (2) +on the file descriptor fails with the error +.BR EINVAL ). +.IP \[bu] +If the PID file descriptor refers to a child of the calling process, +then it can be waited on using +.BR waitid (2). +.IP \[bu] +The +.BR pidfd_getfd (2) +system call can be used to obtain a duplicate of a file descriptor +of another process referred to by a PID file descriptor. +.IP \[bu] +A PID file descriptor can be used as the argument of +.BR setns (2) +in order to move into one or more of the same namespaces as the process +referred to by the file descriptor. +.IP \[bu] +A PID file descriptor can be used as the argument of +.BR process_madvise (2) +in order to provide advice on the memory usage patterns of the process +referred to by the file descriptor. +.P +The +.BR pidfd_open () +system call is the preferred way of obtaining a PID file descriptor +for an already existing process. +The alternative is to obtain a file descriptor by opening a +.IR /proc/ pid +directory. +However, the latter technique is possible only if the +.BR proc (5) +filesystem is mounted; +furthermore, the file descriptor obtained in this way is +.I not +pollable and can't be waited on with +.BR waitid (2). +.SH EXAMPLES +The program below opens a PID file descriptor for the +process whose PID is specified as its command-line argument. +It then uses +.BR poll (2) +to monitor the file descriptor for process exit, as indicated by an +.B EPOLLIN +event. +.\" +.SS Program source +\& +.\" SRC BEGIN (pidfd_open.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +\& +static int +pidfd_open(pid_t pid, unsigned int flags) +{ + return syscall(SYS_pidfd_open, pid, flags); +} +\& +int +main(int argc, char *argv[]) +{ + int pidfd, ready; + struct pollfd pollfd; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_SUCCESS); + } +\& + pidfd = pidfd_open(atoi(argv[1]), 0); + if (pidfd == \-1) { + perror("pidfd_open"); + exit(EXIT_FAILURE); + } +\& + pollfd.fd = pidfd; + pollfd.events = POLLIN; +\& + ready = poll(&pollfd, 1, \-1); + if (ready == \-1) { + perror("poll"); + exit(EXIT_FAILURE); + } +\& + printf("Events (%#x): POLLIN is %sset\en", pollfd.revents, + (pollfd.revents & POLLIN) ? "" : "not "); +\& + close(pidfd); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clone (2), +.BR kill (2), +.BR pidfd_getfd (2), +.BR pidfd_send_signal (2), +.BR poll (2), +.BR process_madvise (2), +.BR select (2), +.BR setns (2), +.BR waitid (2), +.BR epoll (7) diff --git a/man/man2/pidfd_send_signal.2 b/man/man2/pidfd_send_signal.2 new file mode 100644 index 0000000..4be9ffe --- /dev/null +++ b/man/man2/pidfd_send_signal.2 @@ -0,0 +1,240 @@ +.\" Copyright (c) 2019 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pidfd_send_signal 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pidfd_send_signal \- send a signal to a process specified by a file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SIG* " constants */" +.BR "#include " " /* Definition of " SI_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_pidfd_send_signal, int " pidfd ", int " sig , +.BI " siginfo_t *_Nullable " info ", unsigned int " flags ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR pidfd_send_signal (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR pidfd_send_signal () +system call sends the signal +.I sig +to the target process referred to by +.IR pidfd , +a PID file descriptor that refers to a process. +.\" See the very detailed commit message for kernel commit +.\" 3eb39f47934f9d5a3027fe00d906a45fe3a15fad +.P +If the +.I info +argument points to a +.I siginfo_t +buffer, that buffer should be populated as described in +.BR rt_sigqueueinfo (2). +.P +If the +.I info +argument is a null pointer, +this is equivalent to specifying a pointer to a +.I siginfo_t +buffer whose fields match the values that are +implicitly supplied when a signal is sent using +.BR kill (2): +.P +.PD 0 +.IP \[bu] 3 +.I si_signo +is set to the signal number; +.IP \[bu] +.I si_errno +is set to 0; +.IP \[bu] +.I si_code +is set to +.BR SI_USER ; +.IP \[bu] +.I si_pid +is set to the caller's PID; and +.IP \[bu] +.I si_uid +is set to the caller's real user ID. +.PD +.P +The calling process must either be in the same PID namespace as the +process referred to by +.IR pidfd , +or be in an ancestor of that namespace. +.P +The +.I flags +argument is reserved for future use; +currently, this argument must be specified as 0. +.SH RETURN VALUE +On success, +.BR pidfd_send_signal () +returns 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I pidfd +is not a valid PID file descriptor. +.TP +.B EINVAL +.I sig +is not a valid signal. +.TP +.B EINVAL +The calling process is not in a PID namespace from which it can +send a signal to the target process. +.TP +.B EINVAL +.I flags +is not 0. +.TP +.B EPERM +The calling process does not have permission to send the signal +to the target process. +.TP +.B EPERM +.I pidfd +doesn't refer to the calling process, and +.I info.si_code +is invalid (see +.BR rt_sigqueueinfo (2)). +.TP +.B ESRCH +The target process does not exist +(i.e., it has terminated and been waited on). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.1. +.SH NOTES +.SS PID file descriptors +The +.I pidfd +argument is a PID file descriptor, +a file descriptor that refers to process. +Such a file descriptor can be obtained in any of the following ways: +.IP \[bu] 3 +by opening a +.IR /proc/ pid +directory; +.IP \[bu] +using +.BR pidfd_open (2); +or +.IP \[bu] +via the PID file descriptor that is returned by a call to +.BR clone (2) +or +.BR clone3 (2) +that specifies the +.B CLONE_PIDFD +flag. +.P +The +.BR pidfd_send_signal () +system call allows the avoidance of race conditions that occur +when using traditional interfaces (such as +.BR kill (2)) +to signal a process. +The problem is that the traditional interfaces specify the target process +via a process ID (PID), +with the result that the sender may accidentally send a signal to +the wrong process if the originally intended target process +has terminated and its PID has been recycled for another process. +By contrast, +a PID file descriptor is a stable reference to a specific process; +if that process terminates, +.BR pidfd_send_signal () +fails with the error +.BR ESRCH . +.SH EXAMPLES +.\" SRC BEGIN (pidfd_send_signal.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +\& +static int +pidfd_send_signal(int pidfd, int sig, siginfo_t *info, + unsigned int flags) +{ + return syscall(SYS_pidfd_send_signal, pidfd, sig, info, flags); +} +\& +int +main(int argc, char *argv[]) +{ + int pidfd, sig; + char path[PATH_MAX]; + siginfo_t info; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + sig = atoi(argv[2]); +\& + /* Obtain a PID file descriptor by opening the /proc/PID directory + of the target process. */ +\& + snprintf(path, sizeof(path), "/proc/%s", argv[1]); +\& + pidfd = open(path, O_RDONLY); + if (pidfd == \-1) { + perror("open"); + exit(EXIT_FAILURE); + } +\& + /* Populate a \[aq]siginfo_t\[aq] structure for use with + pidfd_send_signal(). */ +\& + memset(&info, 0, sizeof(info)); + info.si_code = SI_QUEUE; + info.si_signo = sig; + info.si_errno = 0; + info.si_uid = getuid(); + info.si_pid = getpid(); + info.si_value.sival_int = 1234; +\& + /* Send the signal. */ +\& + if (pidfd_send_signal(pidfd, sig, &info, 0) == \-1) { + perror("pidfd_send_signal"); + exit(EXIT_FAILURE); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clone (2), +.BR kill (2), +.BR pidfd_open (2), +.BR rt_sigqueueinfo (2), +.BR sigaction (2), +.BR pid_namespaces (7), +.BR signal (7) diff --git a/man/man2/pipe.2 b/man/man2/pipe.2 new file mode 100644 index 0000000..ee2189a --- /dev/null +++ b/man/man2/pipe.2 @@ -0,0 +1,305 @@ +.\" Copyright (C) 2005, 2008, Michael Kerrisk +.\" (A few fragments remain from an earlier (1992) version by +.\" Drew Eckhardt .) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-23 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2005, mtk: added an example program +.\" Modified 2008-01-09, mtk: rewrote DESCRIPTION; minor additions +.\" to EXAMPLE text. +.\" 2008-10-10, mtk: add description of pipe2() +.\" +.TH pipe 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pipe, pipe2 \- create pipe +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pipe(int " pipefd [2]); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.BR "#include " " /* Definition of " O_* " constants */" +.B #include +.P +.BI "int pipe2(int " pipefd "[2], int " flags ); +.P +/* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64, pipe() has the + following prototype; see VERSIONS */ +.P +.B #include +.P +.B struct fd_pair { +.B " long fd[2];" +.B "};" +.B struct fd_pair pipe(void); +.fi +.SH DESCRIPTION +.BR pipe () +creates a pipe, a unidirectional data channel that +can be used for interprocess communication. +The array +.I pipefd +is used to return two file descriptors referring to the ends of the pipe. +.I pipefd[0] +refers to the read end of the pipe. +.I pipefd[1] +refers to the write end of the pipe. +Data written to the write end of the pipe is buffered by the kernel +until it is read from the read end of the pipe. +For further details, see +.BR pipe (7). +.P +If +.I flags +is 0, then +.BR pipe2 () +is the same as +.BR pipe (). +The following values can be bitwise ORed in +.I flags +to obtain different behavior: +.TP +.B O_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the two new file descriptors. +See the description of the same flag in +.BR open (2) +for reasons why this may be useful. +.TP +.BR O_DIRECT " (since Linux 3.4)" +.\" commit 9883035ae7edef3ec62ad215611cb8e17d6a1a5d +Create a pipe that performs I/O in "packet" mode. +Each +.BR write (2) +to the pipe is dealt with as a separate packet, and +.BR read (2)s +from the pipe will read one packet at a time. +Note the following points: +.RS +.IP \[bu] 3 +Writes of greater than +.B PIPE_BUF +bytes (see +.BR pipe (7)) +will be split into multiple packets. +The constant +.B PIPE_BUF +is defined in +.IR . +.IP \[bu] +If a +.BR read (2) +specifies a buffer size that is smaller than the next packet, +then the requested number of bytes are read, +and the excess bytes in the packet are discarded. +Specifying a buffer size of +.B PIPE_BUF +will be sufficient to read the largest possible packets +(see the previous point). +.IP \[bu] +Zero-length packets are not supported. +(A +.BR read (2) +that specifies a buffer size of zero is a no-op, and returns 0.) +.RE +.IP +Older kernels that do not support this flag will indicate this via an +.B EINVAL +error. +.IP +Since Linux 4.5, +.\" commit 0dbf5f20652108106cb822ad7662c786baaa03ff +.\" FIXME . But, it is not possible to specify O_DIRECT when opening a FIFO +it is possible to change the +.B O_DIRECT +setting of a pipe file descriptor using +.BR fcntl (2). +.TP +.B O_NONBLOCK +Set the +.B O_NONBLOCK +file status flag on the open file descriptions +referred to by the new file descriptors. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B O_NOTIFICATION_PIPE +Since Linux 5.8, +.\" commit c73be61cede5882f9605a852414db559c0ebedfd +general notification mechanism is built on the top of the pipe where +kernel splices notification messages into pipes opened by user space. +The owner of the pipe has to tell the kernel which sources of events to watch +and filters can also be applied to select +which subevents should be placed into the pipe. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, +.I errno +is set to indicate the error, and +.I pipefd +is left unchanged. +.P +On Linux (and other systems), +.BR pipe () +does not modify +.I pipefd +on failure. +A requirement standardizing this behavior was added in POSIX.1-2008 TC2. +.\" http://austingroupbugs.net/view.php?id=467 +The Linux-specific +.BR pipe2 () +system call +likewise does not modify +.I pipefd +on failure. +.SH ERRORS +.TP +.B EFAULT +.I pipefd +is not valid. +.TP +.B EINVAL +.RB ( pipe2 ()) +Invalid value in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENFILE +The user hard limit on memory that can be allocated for pipes +has been reached and the caller is not privileged; see +.BR pipe (7). +.TP +.B ENOPKG +.RB ( pipe2 ()) +.B O_NOTIFICATION_PIPE +was passed in +.I flags +and support for notifications +.RB ( CONFIG_WATCH_QUEUE ) +is not compiled into the kernel. +.SH VERSIONS +.\" See http://math-atlas.sourceforge.net/devel/assembly/64.psabi.1.33.ps.Z +.\" for example, section 3.2.1 "Registers and the Stack Frame". +The System V ABI on some architectures allows the use of more than one register +for returning multiple values; several architectures +(namely, Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64) +(ab)use this feature in order to implement the +.BR pipe () +system call in a functional manner: +the call doesn't take any arguments and returns +a pair of file descriptors as the return value on success. +The glibc +.BR pipe () +wrapper function transparently deals with this. +See +.BR syscall (2) +for information regarding registers used for storing second file descriptor. +.SH STANDARDS +.TP +.BR pipe () +POSIX.1-2008. +.TP +.BR pipe2 () +Linux. +.SH HISTORY +.TP +.BR pipe () +POSIX.1-2001. +.TP +.BR pipe2 () +Linux 2.6.27, +glibc 2.9. +.SH EXAMPLES +.\" fork.2 refers to this example program. +The following program creates a pipe, and then +.BR fork (2)s +to create a child process; +the child inherits a duplicate set of file +descriptors that refer to the same pipe. +After the +.BR fork (2), +each process closes the file descriptors that it doesn't need for the pipe +(see +.BR pipe (7)). +The parent then writes the string contained in the program's +command-line argument to the pipe, +and the child reads this string a byte at a time from the pipe +and echoes it on standard output. +.SS Program source +.\" SRC BEGIN (pipe.c) +.EX +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int pipefd[2]; + char buf; + pid_t cpid; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (pipe(pipefd) == \-1) { + perror("pipe"); + exit(EXIT_FAILURE); + } +\& + cpid = fork(); + if (cpid == \-1) { + perror("fork"); + exit(EXIT_FAILURE); + } +\& + if (cpid == 0) { /* Child reads from pipe */ + close(pipefd[1]); /* Close unused write end */ +\& + while (read(pipefd[0], &buf, 1) > 0) + write(STDOUT_FILENO, &buf, 1); +\& + write(STDOUT_FILENO, "\en", 1); + close(pipefd[0]); + _exit(EXIT_SUCCESS); +\& + } else { /* Parent writes argv[1] to pipe */ + close(pipefd[0]); /* Close unused read end */ + write(pipefd[1], argv[1], strlen(argv[1])); + close(pipefd[1]); /* Reader will see EOF */ + wait(NULL); /* Wait for child */ + exit(EXIT_SUCCESS); + } +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fork (2), +.BR read (2), +.BR socketpair (2), +.BR splice (2), +.BR tee (2), +.BR vmsplice (2), +.BR write (2), +.BR popen (3), +.BR pipe (7) diff --git a/man/man2/pipe2.2 b/man/man2/pipe2.2 new file mode 100644 index 0000000..980e240 --- /dev/null +++ b/man/man2/pipe2.2 @@ -0,0 +1 @@ +.so man2/pipe.2 diff --git a/man/man2/pivot_root.2 b/man/man2/pivot_root.2 new file mode 100644 index 0000000..ede732a --- /dev/null +++ b/man/man2/pivot_root.2 @@ -0,0 +1,409 @@ +.\" Copyright (C) 2019 Michael Kerrisk +.\" A very few fragments remain from an earlier page written by +.\" Werner Almesberger in 2000 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pivot_root 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pivot_root \- change the root mount +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_pivot_root, const char *" new_root \ +", const char *" put_old ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR pivot_root (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR pivot_root () +changes the root mount in the mount namespace of the calling process. +More precisely, it moves the root mount to the +directory \fIput_old\fP and makes \fInew_root\fP the new root mount. +The calling process must have the +.B CAP_SYS_ADMIN +capability in the user namespace that owns the caller's mount namespace. +.P +.BR pivot_root () +changes the root directory and the current working directory +of each process or thread in the same mount namespace to +.I new_root +if they point to the old root directory. +(See also NOTES.) +On the other hand, +.BR pivot_root () +does not change the caller's current working directory +(unless it is on the old root directory), +and thus it should be followed by a +\fBchdir("/")\fP call. +.P +The following restrictions apply: +.IP \[bu] 3 +.I new_root +and +.I put_old +must be directories. +.IP \[bu] +.I new_root +and +.I put_old +must not be on the same mount as the current root. +.IP \[bu] +\fIput_old\fP must be at or underneath \fInew_root\fP; +that is, adding some nonnegative +number of "\fI/..\fP" suffixes to the pathname pointed to by +.I put_old +must yield the same directory as \fInew_root\fP. +.IP \[bu] +.I new_root +must be a path to a mount point, but can't be +.IR \[dq]/\[dq] . +A path that is not already a mount point can be converted into one by +bind mounting the path onto itself. +.IP \[bu] +The propagation type of the parent mount of +.I new_root +and the parent mount of the current root directory must not be +.BR MS_SHARED ; +similarly, if +.I put_old +is an existing mount point, its propagation type must not be +.BR MS_SHARED . +These restrictions ensure that +.BR pivot_root () +never propagates any changes to another mount namespace. +.IP \[bu] +The current root directory must be a mount point. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +\fIerrno\fP is set to indicate the error. +.SH ERRORS +.BR pivot_root () +may fail with any of the same errors as +.BR stat (2). +Additionally, it may fail with the following errors: +.TP +.B EBUSY +.\" Reconfirmed that the following error occurs on Linux 5.0 by +.\" specifying 'new_root' as "/rootfs" and 'put_old' as +.\" "/rootfs/oldrootfs", and *not* bind mounting "/rootfs" on top of +.\" itself. Of course, this is an odd situation, since a later check +.\" in the kernel code will in any case yield EINVAL if 'new_root' is +.\" not a mount point. However, when the system call was first added, +.\" 'new_root' was not required to be a mount point. So, this +.\" error is nowadays probably just the result of crufty accumulation. +.\" This error can also occur if we bind mount "/" on top of itself +.\" and try to specify "/" as the 'new' (again, an odd situation). So, +.\" the EBUSY check in the kernel does still seem necessary to prevent +.\" that case. Furthermore, the "or put_old" piece is probably +.\" redundant text (although the check is in the kernel), since, +.\" in another check, 'put_old' is required to be under 'new_root'. +.I new_root +or +.I put_old +is on the current root mount. +(This error covers the pathological case where +.I new_root +is +.IR \[dq]/\[dq] .) +.TP +.B EINVAL +.I new_root +is not a mount point. +.TP +.B EINVAL +\fIput_old\fP is not at or underneath \fInew_root\fP. +.TP +.B EINVAL +The current root directory is not a mount point +(because of an earlier +.BR chroot (2)). +.TP +.B EINVAL +The current root is on the rootfs (initial ramfs) mount; see NOTES. +.TP +.B EINVAL +Either the mount point at +.IR new_root , +or the parent mount of that mount point, +has propagation type +.BR MS_SHARED . +.TP +.B EINVAL +.I put_old +is a mount point and has the propagation type +.BR MS_SHARED . +.TP +.B ENOTDIR +\fInew_root\fP or \fIput_old\fP is not a directory. +.TP +.B EPERM +The calling process does not have the +.B CAP_SYS_ADMIN +capability. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.3.41. +.SH NOTES +A command-line interface for this system call is provided by +.BR pivot_root (8). +.P +.BR pivot_root () +allows the caller to switch to a new root filesystem while at the same time +placing the old root mount at a location under +.I new_root +from where it can subsequently be unmounted. +(The fact that it moves all processes that have a root directory +or current working directory on the old root directory to the +new root frees the old root directory of users, +allowing the old root mount to be unmounted more easily.) +.P +One use of +.BR pivot_root () +is during system startup, when the +system mounts a temporary root filesystem (e.g., an +.BR initrd (4)), +then mounts the real root filesystem, and eventually turns the latter into +the root directory of all relevant processes and threads. +A modern use is to set up a root filesystem during +the creation of a container. +.P +The fact that +.BR pivot_root () +modifies process root and current working directories in the +manner noted in DESCRIPTION +is necessary in order to prevent kernel threads from keeping the old +root mount busy with their root and current working directories, +even if they never access +the filesystem in any way. +.P +The rootfs (initial ramfs) cannot be +.BR pivot_root ()ed. +The recommended method of changing the root filesystem in this case is +to delete everything in rootfs, overmount rootfs with the new root, attach +.IR stdin / stdout / stderr +to the new +.IR /dev/console , +and exec the new +.BR init (1). +Helper programs for this process exist; see +.BR switch_root (8). +.\" +.SS pivot_root(\[dq].\[dq], \[dq].\[dq]) +.I new_root +and +.I put_old +may be the same directory. +In particular, the following sequence allows a pivot-root operation +without needing to create and remove a temporary directory: +.P +.in +4n +.EX +chdir(new_root); +pivot_root(".", "."); +umount2(".", MNT_DETACH); +.EE +.in +.P +This sequence succeeds because the +.BR pivot_root () +call stacks the old root mount point +on top of the new root mount point at +.IR / . +At that point, the calling process's root directory and current +working directory refer to the new root mount point +.RI ( new_root ). +During the subsequent +.BR umount () +call, resolution of +.I \[dq].\[dq] +starts with +.I new_root +and then moves up the list of mounts stacked at +.IR / , +with the result that old root mount point is unmounted. +.\" +.SS Historical notes +For many years, this manual page carried the following text: +.RS +.P +.BR pivot_root () +may or may not change the current root and the current +working directory of any processes or threads which use the old +root directory. +The caller of +.BR pivot_root () +must ensure that processes with root or current working directory +at the old root operate correctly in either case. +An easy way to ensure this is to change their +root and current working directory to \fInew_root\fP before invoking +.BR pivot_root (). +.RE +.P +This text, written before the system call implementation was +even finalized in the kernel, was probably intended to warn users +at that time that the implementation might change before final release. +However, the behavior stated in DESCRIPTION +has remained consistent since this system call +was first implemented and will not change now. +.SH EXAMPLES +.\" FIXME +.\" Would it be better, because simpler, to use unshare(2) +.\" rather than clone(2) in the example below? +The program below demonstrates the use of +.BR pivot_root () +inside a mount namespace that is created using +.BR clone (2). +After pivoting to the root directory named in the program's +first command-line argument, the child created by +.BR clone (2) +then executes the program named in the remaining command-line arguments. +.P +We demonstrate the program by creating a directory that will serve as +the new root filesystem and placing a copy of the (statically linked) +.BR busybox (1) +executable in that directory. +.P +.in +4n +.EX +$ \fBmkdir /tmp/rootfs\fP +$ \fBls \-id /tmp/rootfs\fP # Show inode number of new root directory +319459 /tmp/rootfs +$ \fBcp $(which busybox) /tmp/rootfs\fP +$ \fBPS1=\[aq]bbsh$ \[aq] sudo ./pivot_root_demo /tmp/rootfs /busybox sh\fP +bbsh$ \fBPATH=/\fP +bbsh$ \fBbusybox ln busybox ln\fP +bbsh$ \fBln busybox echo\fP +bbsh$ \fBln busybox ls\fP +bbsh$ \fBls\fP +busybox echo ln ls +bbsh$ \fBls \-id /\fP # Compare with inode number above +319459 / +bbsh$ \fBecho \[aq]hello world\[aq]\fP +hello world +.EE +.in +.SS Program source +\& +.P +.\" SRC BEGIN (pivot_root.c) +.EX +/* pivot_root_demo.c */ +\& +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +static int +pivot_root(const char *new_root, const char *put_old) +{ + return syscall(SYS_pivot_root, new_root, put_old); +} +\& +#define STACK_SIZE (1024 * 1024) +\& +static int /* Startup function for cloned child */ +child(void *arg) +{ + char path[PATH_MAX]; + char **args = arg; + char *new_root = args[0]; + const char *put_old = "/oldrootfs"; +\& + /* Ensure that \[aq]new_root\[aq] and its parent mount don\[aq]t have + shared propagation (which would cause pivot_root() to + return an error), and prevent propagation of mount + events to the initial mount namespace. */ +\& + if (mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, NULL) == \-1) + err(EXIT_FAILURE, "mount\-MS_PRIVATE"); +\& + /* Ensure that \[aq]new_root\[aq] is a mount point. */ +\& + if (mount(new_root, new_root, NULL, MS_BIND, NULL) == \-1) + err(EXIT_FAILURE, "mount\-MS_BIND"); +\& + /* Create directory to which old root will be pivoted. */ +\& + snprintf(path, sizeof(path), "%s/%s", new_root, put_old); + if (mkdir(path, 0777) == \-1) + err(EXIT_FAILURE, "mkdir"); +\& + /* And pivot the root filesystem. */ +\& + if (pivot_root(new_root, path) == \-1) + err(EXIT_FAILURE, "pivot_root"); +\& + /* Switch the current working directory to "/". */ +\& + if (chdir("/") == \-1) + err(EXIT_FAILURE, "chdir"); +\& + /* Unmount old root and remove mount point. */ +\& + if (umount2(put_old, MNT_DETACH) == \-1) + perror("umount2"); + if (rmdir(put_old) == \-1) + perror("rmdir"); +\& + /* Execute the command specified in argv[1]... */ +\& + execv(args[1], &args[1]); + err(EXIT_FAILURE, "execv"); +} +\& +int +main(int argc, char *argv[]) +{ + char *stack; +\& + /* Create a child process in a new mount namespace. */ +\& + stack = mmap(NULL, STACK_SIZE, PROT_READ | PROT_WRITE, + MAP_PRIVATE | MAP_ANONYMOUS | MAP_STACK, \-1, 0); + if (stack == MAP_FAILED) + err(EXIT_FAILURE, "mmap"); +\& + if (clone(child, stack + STACK_SIZE, + CLONE_NEWNS | SIGCHLD, &argv[1]) == \-1) + err(EXIT_FAILURE, "clone"); +\& + /* Parent falls through to here; wait for child. */ +\& + if (wait(NULL) == \-1) + err(EXIT_FAILURE, "wait"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR chdir (2), +.BR chroot (2), +.BR mount (2), +.BR stat (2), +.BR initrd (4), +.BR mount_namespaces (7), +.BR pivot_root (8), +.BR switch_root (8) diff --git a/man/man2/pkey_alloc.2 b/man/man2/pkey_alloc.2 new file mode 100644 index 0000000..2fd662b --- /dev/null +++ b/man/man2/pkey_alloc.2 @@ -0,0 +1,115 @@ +.\" Copyright (C) 2016 Intel Corporation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pkey_alloc 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pkey_alloc, pkey_free \- allocate or free a protection key +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int pkey_alloc(unsigned int " flags ", unsigned int " access_rights ");" +.BI "int pkey_free(int " pkey ");" +.fi +.SH DESCRIPTION +.BR pkey_alloc () +allocates a protection key (pkey) and allows it to be passed to +.BR pkey_mprotect (2). +.P +The +.BR pkey_alloc () +.I flags +is reserved for future use and currently must always be specified as 0. +.P +The +.BR pkey_alloc () +.I access_rights +argument may contain zero or more disable operations: +.TP +.B PKEY_DISABLE_ACCESS +Disable all data access to memory covered by the returned protection key. +.TP +.B PKEY_DISABLE_WRITE +Disable write access to memory covered by the returned protection key. +.P +.BR pkey_free () +frees a protection key and makes it available for later +allocations. +After a protection key has been freed, it may no longer be used +in any protection-key-related operations. +.P +An application should not call +.BR pkey_free () +on any protection key which has been assigned to an address +range by +.BR pkey_mprotect (2) +and which is still in use. +The behavior in this case is undefined and may result in an error. +.SH RETURN VALUE +On success, +.BR pkey_alloc () +returns a positive protection key value. +On success, +.BR pkey_free () +returns zero. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.IR pkey , +.IR flags , +or +.I access_rights +is invalid. +.TP +.B ENOSPC +.RB ( pkey_alloc ()) +All protection keys available for the current process have +been allocated. +The number of keys available is architecture-specific and +implementation-specific and may be reduced by kernel-internal use +of certain keys. +There are currently 15 keys available to user programs on x86. +.IP +This error will also be returned if the processor or operating system +does not support protection keys. +Applications should always be prepared to handle this error, since +factors outside of the application's control can reduce the number +of available pkeys. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.9, +glibc 2.27. +.SH NOTES +.BR pkey_alloc () +is always safe to call regardless of whether or not the operating system +supports protection keys. +It can be used in lieu of any other mechanism for detecting pkey support +and will simply fail with the error +.B ENOSPC +if the operating system has no pkey support. +.P +The kernel guarantees that the contents of the hardware rights +register (PKRU) will be preserved only for allocated protection +keys. +Any time a key is unallocated (either before the first call +returning that key from +.BR pkey_alloc () +or after it is freed via +.BR pkey_free ()), +the kernel may make arbitrary changes to the parts of the +rights register affecting access to that key. +.SH EXAMPLES +See +.BR pkeys (7). +.SH SEE ALSO +.BR pkey_mprotect (2), +.BR pkeys (7) diff --git a/man/man2/pkey_free.2 b/man/man2/pkey_free.2 new file mode 100644 index 0000000..5b524cb --- /dev/null +++ b/man/man2/pkey_free.2 @@ -0,0 +1 @@ +.so man2/pkey_alloc.2 diff --git a/man/man2/pkey_mprotect.2 b/man/man2/pkey_mprotect.2 new file mode 100644 index 0000000..b4f9309 --- /dev/null +++ b/man/man2/pkey_mprotect.2 @@ -0,0 +1 @@ +.so man2/mprotect.2 diff --git a/man/man2/poll.2 b/man/man2/poll.2 new file mode 100644 index 0000000..c0a4525 --- /dev/null +++ b/man/man2/poll.2 @@ -0,0 +1,650 @@ +.\" Copyright (C) 2006, 2019 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Additions from Richard Gooch and aeb, 971207 +.\" 2006-03-13, mtk, Added ppoll() + various other rewordings +.\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and +.\" formatting changes. +.\" +.TH poll 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +poll, ppoll \- wait for some event on a file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds , +.BI " const struct timespec *_Nullable " tmo_p , +.BI " const sigset_t *_Nullable " sigmask ); +.fi +.SH DESCRIPTION +.BR poll () +performs a similar task to +.BR select (2): +it waits for one of a set of file descriptors to become ready +to perform I/O. +The Linux-specific +.BR epoll (7) +API performs a similar task, but offers features beyond those found in +.BR poll (). +.P +The set of file descriptors to be monitored is specified in the +.I fds +argument, which is an array of structures of the following form: +.P +.in +4n +.EX +struct pollfd { + int fd; /* file descriptor */ + short events; /* requested events */ + short revents; /* returned events */ +}; +.EE +.in +.P +The caller should specify the number of items in the +.I fds +array in +.IR nfds . +.P +The field +.I fd +contains a file descriptor for an open file. +If this field is negative, then the corresponding +.I events +field is ignored and the +.I revents +field returns zero. +(This provides an easy way of ignoring a +file descriptor for a single +.BR poll () +call: simply set the +.I fd +field to its bitwise complement.) +.P +The field +.I events +is an input parameter, a bit mask specifying the events the application +is interested in for the file descriptor +.IR fd . +This field may be specified as zero, +in which case the only events that can be returned in +.I revents +are +.BR POLLHUP , +.BR POLLERR , +and +.B POLLNVAL +(see below). +.P +The field +.I revents +is an output parameter, filled by the kernel with the events that +actually occurred. +The bits returned in +.I revents +can include any of those specified in +.IR events , +or one of the values +.BR POLLERR , +.BR POLLHUP , +or +.BR POLLNVAL . +(These three bits are meaningless in the +.I events +field, and will be set in the +.I revents +field whenever the corresponding condition is true.) +.P +If none of the events requested (and no error) has occurred for any +of the file descriptors, then +.BR poll () +blocks until one of the events occurs. +.P +The +.I timeout +argument specifies the number of milliseconds that +.BR poll () +should block waiting for a file descriptor to become ready. +The call will block until either: +.IP \[bu] 3 +a file descriptor becomes ready; +.IP \[bu] +the call is interrupted by a signal handler; or +.IP \[bu] +the timeout expires. +.P +Being "ready" means that the requested operation will not block; thus, +.BR poll ()ing +regular files, +block devices, +and other files with no reasonable polling semantic +.I always +returns instantly as ready to read and write. +.P +Note that the +.I timeout +interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the blocking interval +may overrun by a small amount. +Specifying a negative value in +.I timeout +means an infinite timeout. +Specifying a +.I timeout +of zero causes +.BR poll () +to return immediately, even if no file descriptors are ready. +.P +The bits that may be set/returned in +.I events +and +.I revents +are defined in \fI\fP: +.TP +.B POLLIN +There is data to read. +.TP +.B POLLPRI +There is some exceptional condition on the file descriptor. +Possibilities include: +.RS +.IP \[bu] 3 +There is out-of-band data on a TCP socket (see +.BR tcp (7)). +.IP \[bu] +A pseudoterminal master in packet mode has seen a state change on the slave +(see +.BR ioctl_tty (2)). +.IP \[bu] +A +.I cgroup.events +file has been modified (see +.BR cgroups (7)). +.RE +.TP +.B POLLOUT +Writing is now possible, though a write larger than the available space +in a socket or pipe will still block (unless +.B O_NONBLOCK +is set). +.TP +.BR POLLRDHUP " (since Linux 2.6.17)" +Stream socket peer closed connection, +or shut down writing half of connection. +The +.B _GNU_SOURCE +feature test macro must be defined +(before including +.I any +header files) +in order to obtain this definition. +.TP +.B POLLERR +Error condition (only returned in +.IR revents ; +ignored in +.IR events ). +This bit is also set for a file descriptor referring +to the write end of a pipe when the read end has been closed. +.TP +.B POLLHUP +Hang up (only returned in +.IR revents ; +ignored in +.IR events ). +Note that when reading from a channel such as a pipe or a stream socket, +this event merely indicates that the peer closed its end of the channel. +Subsequent reads from the channel will return 0 (end of file) +only after all outstanding data in the channel has been consumed. +.TP +.B POLLNVAL +Invalid request: +.I fd +not open (only returned in +.IR revents ; +ignored in +.IR events ). +.P +When compiling with +.B _XOPEN_SOURCE +defined, one also has the following, +which convey no further information beyond the bits listed above: +.TP +.B POLLRDNORM +Equivalent to +.BR POLLIN . +.TP +.B POLLRDBAND +Priority band data can be read (generally unused on Linux). +.\" POLLRDBAND is used in the DECnet protocol. +.TP +.B POLLWRNORM +Equivalent to +.BR POLLOUT . +.TP +.B POLLWRBAND +Priority data may be written. +.P +Linux also knows about, but does not use +.BR POLLMSG . +.SS ppoll() +The relationship between +.BR poll () +and +.BR ppoll () +is analogous to the relationship between +.BR select (2) +and +.BR pselect (2): +like +.BR pselect (2), +.BR ppoll () +allows an application to safely wait until either a file descriptor +becomes ready or until a signal is caught. +.P +Other than the difference in the precision of the +.I timeout +argument, the following +.BR ppoll () +call: +.P +.in +4n +.EX +ready = ppoll(&fds, nfds, tmo_p, &sigmask); +.EE +.in +.P +is nearly equivalent to +.I atomically +executing the following calls: +.P +.in +4n +.EX +sigset_t origmask; +int timeout; +\& +timeout = (tmo_p == NULL) ? \-1 : + (tmo_p\->tv_sec * 1000 + tmo_p\->tv_nsec / 1000000); +pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); +ready = poll(&fds, nfds, timeout); +pthread_sigmask(SIG_SETMASK, &origmask, NULL); +.EE +.in +.P +The above code segment is described as +.I nearly +equivalent because whereas a negative +.I timeout +value for +.BR poll () +is interpreted as an infinite timeout, a negative value expressed in +.I *tmo_p +results in an error from +.BR ppoll (). +.P +See the description of +.BR pselect (2) +for an explanation of why +.BR ppoll () +is necessary. +.P +If the +.I sigmask +argument is specified as NULL, then +no signal mask manipulation is performed +(and thus +.BR ppoll () +differs from +.BR poll () +only in the precision of the +.I timeout +argument). +.P +The +.I tmo_p +argument specifies an upper limit on the amount of time that +.BR ppoll () +will block. +This argument is a pointer to a +.BR timespec (3) +structure. +.P +If +.I tmo_p +is specified as NULL, then +.BR ppoll () +can block indefinitely. +.SH RETURN VALUE +On success, +.BR poll () +returns a nonnegative value which is the number of elements in the +.I pollfds +whose +.I revents +fields have been set to a nonzero value (indicating an event or an error). +A return value of zero indicates that the system call timed out +before any file descriptors became ready. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I fds +points outside the process's accessible address space. +The array given as argument was not contained in the calling program's +address space. +.TP +.B EINTR +A signal occurred before any requested event; see +.BR signal (7). +.TP +.B EINVAL +The +.I nfds +value exceeds the +.B RLIMIT_NOFILE +value. +.TP +.B EINVAL +.RB ( ppoll ()) +The timeout value expressed in +.I *tmo_p +is invalid (negative). +.TP +.B ENOMEM +Unable to allocate memory for kernel data structures. +.SH VERSIONS +On some other UNIX systems, +.\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett +.BR poll () +can fail with the error +.B EAGAIN +if the system fails to allocate kernel-internal resources, rather than +.B ENOMEM +as Linux does. +POSIX permits this behavior. +Portable programs may wish to check for +.B EAGAIN +and loop, just as with +.BR EINTR . +.P +Some implementations define the nonstandard constant +.B INFTIM +with the value \-1 for use as a +.I timeout +for +.BR poll (). +This constant is not provided in glibc. +.SS C library/kernel differences +The Linux +.BR ppoll () +system call modifies its +.I tmo_p +argument. +However, the glibc wrapper function hides this behavior +by using a local variable for the timeout argument that +is passed to the system call. +Thus, the glibc +.BR ppoll () +function does not modify its +.I tmo_p +argument. +.P +The raw +.BR ppoll () +system call has a fifth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the +.I sigmask +argument. +The glibc +.BR ppoll () +wrapper function specifies this argument as a fixed value +(equal to +.IR sizeof(kernel_sigset_t) ). +See +.BR sigprocmask (2) +for a discussion on the differences between the kernel and the libc +notion of the sigset. +.SH STANDARDS +.TP +.BR poll () +POSIX.1-2008. +.TP +.BR ppoll () +Linux. +.\" FIXME . +.\" ppoll() is proposed for inclusion in POSIX: +.\" https://www.austingroupbugs.net/view.php?id=1263 +.\" NetBSD 3.0 has a pollts() which is like Linux ppoll(). +.SH HISTORY +.TP +.BR poll () +POSIX.1-2001. +Linux 2.1.23. +.IP +On older kernels that lack this system call, +the glibc +.BR poll () +wrapper function provides emulation using +.BR select (2). +.TP +.BR ppoll () +Linux 2.6.16, +glibc 2.4. +.SH NOTES +The operation of +.BR poll () +and +.BR ppoll () +is not affected by the +.B O_NONBLOCK +flag. +.P +For a discussion of what may happen if a file descriptor being monitored by +.BR poll () +is closed in another thread, see +.BR select (2). +.SH BUGS +See the discussion of spurious readiness notifications under the +BUGS section of +.BR select (2). +.SH EXAMPLES +The program below opens each of the files named in its command-line +arguments and monitors the resulting file descriptors for readiness to read +.RB ( POLLIN ). +The program loops, repeatedly using +.BR poll () +to monitor the file descriptors, +printing the number of ready file descriptors on return. +For each ready file descriptor, the program: +.IP \[bu] 3 +displays the returned +.I revents +field in a human-readable form; +.IP \[bu] +if the file descriptor is readable, reads some data from it, +and displays that data on standard output; and +.IP \[bu] +if the file descriptor was not readable, +but some other event occurred (presumably +.BR POLLHUP ), +closes the file descriptor. +.P +Suppose we run the program in one terminal, asking it to open a FIFO: +.P +.in +4n +.EX +$ \fBmkfifo myfifo\fP +$ \fB./poll_input myfifo\fP +.EE +.in +.P +In a second terminal window, we then open the FIFO for writing, +write some data to it, and close the FIFO: +.P +.in +4n +.EX +$ \fBecho aaaaabbbbbccccc > myfifo\fP +.EE +.in +.P +In the terminal where we are running the program, we would then see: +.P +.in +4n +.EX +Opened "myfifo" on fd 3 +About to poll() +Ready: 1 + fd=3; events: POLLIN POLLHUP + read 10 bytes: aaaaabbbbb +About to poll() +Ready: 1 + fd=3; events: POLLIN POLLHUP + read 6 bytes: ccccc +\& +About to poll() +Ready: 1 + fd=3; events: POLLHUP + closing fd 3 +All file descriptors closed; bye +.EE +.in +.P +In the above output, we see that +.BR poll () +returned three times: +.IP \[bu] 3 +On the first return, the bits returned in the +.I revents +field were +.BR POLLIN , +indicating that the file descriptor is readable, and +.BR POLLHUP , +indicating that the other end of the FIFO has been closed. +The program then consumed some of the available input. +.IP \[bu] +The second return from +.BR poll () +also indicated +.B POLLIN +and +.BR POLLHUP ; +the program then consumed the last of the available input. +.IP \[bu] +On the final return, +.BR poll () +indicated only +.B POLLHUP +on the FIFO, +at which point the file descriptor was closed and the program terminated. +.\" +.SS Program source +\& +.\" SRC BEGIN (poll_input.c) +.EX +/* poll_input.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include +#include +#include +#include +#include +#include +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + int ready; + char buf[10]; + nfds_t num_open_fds, nfds; + ssize_t s; + struct pollfd *pfds; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s file...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + num_open_fds = nfds = argc \- 1; + pfds = calloc(nfds, sizeof(struct pollfd)); + if (pfds == NULL) + errExit("malloc"); +\& + /* Open each file on command line, and add it to \[aq]pfds\[aq] array. */ +\& + for (nfds_t j = 0; j < nfds; j++) { + pfds[j].fd = open(argv[j + 1], O_RDONLY); + if (pfds[j].fd == \-1) + errExit("open"); +\& + printf("Opened \e"%s\e" on fd %d\en", argv[j + 1], pfds[j].fd); +\& + pfds[j].events = POLLIN; + } +\& + /* Keep calling poll() as long as at least one file descriptor is + open. */ +\& + while (num_open_fds > 0) { + printf("About to poll()\en"); + ready = poll(pfds, nfds, \-1); + if (ready == \-1) + errExit("poll"); +\& + printf("Ready: %d\en", ready); +\& + /* Deal with array returned by poll(). */ +\& + for (nfds_t j = 0; j < nfds; j++) { + if (pfds[j].revents != 0) { + printf(" fd=%d; events: %s%s%s\en", pfds[j].fd, + (pfds[j].revents & POLLIN) ? "POLLIN " : "", + (pfds[j].revents & POLLHUP) ? "POLLHUP " : "", + (pfds[j].revents & POLLERR) ? "POLLERR " : ""); +\& + if (pfds[j].revents & POLLIN) { + s = read(pfds[j].fd, buf, sizeof(buf)); + if (s == \-1) + errExit("read"); + printf(" read %zd bytes: %.*s\en", + s, (int) s, buf); + } else { /* POLLERR | POLLHUP */ + printf(" closing fd %d\en", pfds[j].fd); + if (close(pfds[j].fd) == \-1) + errExit("close"); + num_open_fds\-\-; + } + } + } + } +\& + printf("All file descriptors closed; bye\en"); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR restart_syscall (2), +.BR select (2), +.BR select_tut (2), +.BR timespec (3), +.BR epoll (7), +.BR time (7) diff --git a/man/man2/posix_fadvise.2 b/man/man2/posix_fadvise.2 new file mode 100644 index 0000000..a21da3b --- /dev/null +++ b/man/man2/posix_fadvise.2 @@ -0,0 +1,227 @@ +.\" Copyright 2003 Abhijit Menon-Sen +.\" and Copyright (C) 2010, 2015, 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2005-04-08 mtk, noted kernel version and added BUGS +.\" 2010-10-09, mtk, document arm_fadvise64_64() +.\" +.TH posix_fadvise 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_fadvise \- predeclare an access pattern for file data +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \ +", int " advice ");" +.fi +.P +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR posix_fadvise (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +Programs can use +.BR posix_fadvise () +to announce an intention to access +file data in a specific pattern in the future, thus allowing the kernel +to perform appropriate optimizations. +.P +The \fIadvice\fP applies to a (not necessarily existent) region starting +at \fIoffset\fP and extending for \fIlen\fP bytes (or until the end of +the file if \fIlen\fP is 0) within the file referred to by \fIfd\fP. +The \fIadvice\fP is not binding; +it merely constitutes an expectation on behalf of +the application. +.P +Permissible values for \fIadvice\fP include: +.TP +.B POSIX_FADV_NORMAL +Indicates that the application has no advice to give about its access +pattern for the specified data. +If no advice is given for an open file, +this is the default assumption. +.TP +.B POSIX_FADV_SEQUENTIAL +The application expects to access the specified data sequentially (with +lower offsets read before higher ones). +.TP +.B POSIX_FADV_RANDOM +The specified data will be accessed in random order. +.TP +.B POSIX_FADV_NOREUSE +The specified data will be accessed only once. +.IP +Before Linux 2.6.18, \fBPOSIX_FADV_NOREUSE\fP had the +same semantics as \fBPOSIX_FADV_WILLNEED\fP. +This was probably a bug; since Linux 2.6.18, this flag is a no-op. +.TP +.B POSIX_FADV_WILLNEED +The specified data will be accessed in the near future. +.IP +\fBPOSIX_FADV_WILLNEED\fP initiates a +nonblocking read of the specified region into the page cache. +The amount of data read may be decreased by the kernel depending +on virtual memory load. +(A few megabytes will usually be fully satisfied, +and more is rarely useful.) +.TP +.B POSIX_FADV_DONTNEED +The specified data will not be accessed in the near future. +.IP +\fBPOSIX_FADV_DONTNEED\fP attempts to free cached pages associated with +the specified region. +This is useful, for example, while streaming large +files. +A program may periodically request the kernel to free cached data +that has already been used, so that more useful cached pages are not +discarded instead. +.IP +Requests to discard partial pages are ignored. +It is preferable to preserve needed data than discard unneeded data. +If the application requires that data be considered for discarding, then +.I offset +and +.I len +must be page-aligned. +.IP +The implementation +.I may +attempt to write back dirty pages in the specified region, +but this is not guaranteed. +Any unwritten dirty pages will not be freed. +If the application wishes to ensure that dirty pages will be released, +it should call +.BR fsync (2) +or +.BR fdatasync (2) +first. +.SH RETURN VALUE +On success, zero is returned. +On error, an error number is returned. +.SH ERRORS +.TP +.B EBADF +The \fIfd\fP argument was not a valid file descriptor. +.TP +.B EINVAL +An invalid value was specified for \fIadvice\fP. +.TP +.B ESPIPE +The specified file descriptor refers to a pipe or FIFO. +.RB ( ESPIPE +is the error specified by POSIX, +but before Linux 2.6.16, +.\" commit 87ba81dba431232548ce29d5d224115d0c2355ac +Linux returned +.B EINVAL +in this case.) +.SH VERSIONS +Under Linux, \fBPOSIX_FADV_NORMAL\fP sets the readahead window to the +default size for the backing device; \fBPOSIX_FADV_SEQUENTIAL\fP doubles +this size, and \fBPOSIX_FADV_RANDOM\fP disables file readahead entirely. +These changes affect the entire file, not just the specified region +(but other open file handles to the same file are unaffected). +.SS C library/kernel differences +The name of the wrapper function in the C library is +.BR posix_fadvise (). +The underlying system call is called +.BR fadvise64 () +(or, on some architectures, +.BR fadvise64_64 ()); +the difference between the two is that the former system call +assumes that the type of the \fIlen\fP argument is \fIsize_t\fP, +while the latter expects \fIloff_t\fP there. +.SS Architecture-specific variants +Some architectures require +64-bit arguments to be aligned in a suitable pair of registers (see +.BR syscall (2) +for further detail). +On such architectures, the call signature of +.BR posix_fadvise () +shown in the SYNOPSIS would force +a register to be wasted as padding between the +.I fd +and +.I offset +arguments. +Therefore, these architectures define a version of the +system call that orders the arguments suitably, +but is otherwise exactly the same as +.BR posix_fadvise (). +.P +For example, since Linux 2.6.14, ARM has the following system call: +.P +.in +4n +.EX +.BI "long arm_fadvise64_64(int " fd ", int " advice , +.BI " loff_t " offset ", loff_t " len ); +.EE +.in +.P +These architecture-specific details are generally +hidden from applications by the glibc +.BR posix_fadvise () +wrapper function, +which invokes the appropriate architecture-specific system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Kernel support first appeared in Linux 2.5.60; +the underlying system call is called +.BR fadvise64 (). +.\" of fadvise64_64() +Library support has been provided since glibc 2.2, +via the wrapper function +.BR posix_fadvise (). +.P +Since Linux 3.18, +.\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb +support for the underlying system call is optional, +depending on the setting of the +.B CONFIG_ADVISE_SYSCALLS +configuration option. +.P +The type of the +.I len +argument was changed from +.I size_t +to +.I off_t +in POSIX.1-2001 TC1. +.SH NOTES +The contents of the kernel buffer cache can be cleared via the +.I /proc/sys/vm/drop_caches +interface described in +.BR proc (5). +.P +One can obtain a snapshot of which pages of a file are resident +in the buffer cache by opening a file, mapping it with +.BR mmap (2), +and then applying +.BR mincore (2) +to the mapping. +.SH BUGS +Before Linux 2.6.6, if +.I len +was specified as 0, then this was interpreted literally as "zero bytes", +rather than as meaning "all bytes through to the end of the file". +.SH SEE ALSO +.BR fincore (1), +.BR mincore (2), +.BR readahead (2), +.BR sync_file_range (2), +.BR posix_fallocate (3), +.BR posix_madvise (3) diff --git a/man/man2/ppoll.2 b/man/man2/ppoll.2 new file mode 100644 index 0000000..227cd0e --- /dev/null +++ b/man/man2/ppoll.2 @@ -0,0 +1 @@ +.so man2/poll.2 diff --git a/man/man2/prctl.2 b/man/man2/prctl.2 new file mode 100644 index 0000000..56a8e43 --- /dev/null +++ b/man/man2/prctl.2 @@ -0,0 +1,2577 @@ +.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2002, 2006, 2008, 2012, 2013, 2015 Michael Kerrisk +.\" and Copyright Guillem Jover +.\" and Copyright (C) 2010 Andi Kleen +.\" and Copyright (C) 2012 Cyrill Gorcunov +.\" and Copyright (C) 2014 Dave Hansen / Intel +.\" and Copyright (c) 2016 Eugene Syromyatnikov +.\" and Copyright (c) 2018 Konrad Rzeszutek Wilk +.\" and Copyright (c) 2020 Dave Martin +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Thu Nov 11 04:19:42 MET 1999, aeb: added PR_GET_PDEATHSIG +.\" Modified 27 Jun 02, Michael Kerrisk +.\" Added PR_SET_DUMPABLE, PR_GET_DUMPABLE, +.\" PR_SET_KEEPCAPS, PR_GET_KEEPCAPS +.\" Modified 2006-08-30 Guillem Jover +.\" Updated Linux versions where the options where introduced. +.\" Added PR_SET_TIMING, PR_GET_TIMING, PR_SET_NAME, PR_GET_NAME, +.\" PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU, +.\" PR_SET_FPEXC, PR_GET_FPEXC +.\" 2008-04-29 Serge Hallyn, Document PR_CAPBSET_READ and PR_CAPBSET_DROP +.\" 2008-06-13 Erik Bosman, +.\" Document PR_GET_TSC and PR_SET_TSC. +.\" 2008-06-15 mtk, Document PR_SET_SECCOMP, PR_GET_SECCOMP +.\" 2009-10-03 Andi Kleen, document PR_MCE_KILL +.\" 2012-04 Cyrill Gorcunov, Document PR_SET_MM +.\" 2012-04-25 Michael Kerrisk, Document PR_TASK_PERF_EVENTS_DISABLE and +.\" PR_TASK_PERF_EVENTS_ENABLE +.\" 2012-09-20 Kees Cook, update PR_SET_SECCOMP for mode 2 +.\" 2012-09-20 Kees Cook, document PR_SET_NO_NEW_PRIVS, PR_GET_NO_NEW_PRIVS +.\" 2012-10-25 Michael Kerrisk, Document PR_SET_TIMERSLACK and +.\" PR_GET_TIMERSLACK +.\" 2013-01-10 Kees Cook, document PR_SET_PTRACER +.\" 2012-02-04 Michael Kerrisk, document PR_{SET,GET}_CHILD_SUBREAPER +.\" 2014-11-10 Dave Hansen, document PR_MPX_{EN,DIS}ABLE_MANAGEMENT +.\" +.\" +.TH prctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +prctl \- operations on a process or thread +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int prctl(int " op ", ..." +.BI " \fR/*\fP unsigned long " arg2 ", unsigned long " arg3 , +.BI " unsigned long " arg4 ", unsigned long " arg5 " \fR*/\fP );" +.fi +.SH DESCRIPTION +.BR prctl () +manipulates various aspects of the behavior +of the calling thread or process. +.P +Note that careless use of some +.BR prctl () +operations can confuse the user-space run-time environment, +so these operations should be used with care. +.P +.BR prctl () +is called with a first argument describing what to do +(with values defined in \fI\fP), and further +arguments with a significance depending on the first one. +The first argument can be: +.\" +.\" prctl PR_CAP_AMBIENT +.TP +.BR PR_CAP_AMBIENT " (since Linux 4.3)" +.\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08 +Reads or changes the ambient capability set of the calling thread, +according to the value of +.IR arg2 , +which must be one of the following: +.RS +.\" +.TP +.B PR_CAP_AMBIENT_RAISE +The capability specified in +.I arg3 +is added to the ambient set. +The specified capability must already be present in +both the permitted and the inheritable sets of the process. +This operation is not permitted if the +.B SECBIT_NO_CAP_AMBIENT_RAISE +securebit is set. +.TP +.B PR_CAP_AMBIENT_LOWER +The capability specified in +.I arg3 +is removed from the ambient set. +.TP +.B PR_CAP_AMBIENT_IS_SET +The +.BR prctl () +call returns 1 if the capability in +.I arg3 +is in the ambient set and 0 if it is not. +.TP +.B PR_CAP_AMBIENT_CLEAR_ALL +All capabilities will be removed from the ambient set. +This operation requires setting +.I arg3 +to zero. +.RE +.IP +In all of the above operations, +.I arg4 +and +.I arg5 +must be specified as 0. +.IP +Higher-level interfaces layered on top of the above operations are +provided in the +.BR libcap (3) +library in the form of +.BR cap_get_ambient (3), +.BR cap_set_ambient (3), +and +.BR cap_reset_ambient (3). +.\" prctl PR_CAPBSET_READ +.TP +.BR PR_CAPBSET_READ " (since Linux 2.6.25)" +Return (as the function result) 1 if the capability specified in +.I arg2 +is in the calling thread's capability bounding set, +or 0 if it is not. +(The capability constants are defined in +.IR .) +The capability bounding set dictates +whether the process can receive the capability through a +file's permitted capability set on a subsequent call to +.BR execve (2). +.IP +If the capability specified in +.I arg2 +is not valid, then the call fails with the error +.BR EINVAL . +.IP +A higher-level interface layered on top of this operation is provided in the +.BR libcap (3) +library in the form of +.BR cap_get_bound (3). +.\" prctl PR_CAPBSET_DROP +.TP +.BR PR_CAPBSET_DROP " (since Linux 2.6.25)" +If the calling thread has the +.B CAP_SETPCAP +capability within its user namespace, then drop the capability specified by +.I arg2 +from the calling thread's capability bounding set. +Any children of the calling thread will inherit the newly +reduced bounding set. +.IP +The call fails with the error: +.B EPERM +if the calling thread does not have the +.BR CAP_SETPCAP ; +.B EINVAL +if +.I arg2 +does not represent a valid capability; or +.B EINVAL +if file capabilities are not enabled in the kernel, +in which case bounding sets are not supported. +.IP +A higher-level interface layered on top of this operation is provided in the +.BR libcap (3) +library in the form of +.BR cap_drop_bound (3). +.\" prctl PR_SET_CHILD_SUBREAPER +.TP +.BR PR_SET_CHILD_SUBREAPER " (since Linux 3.4)" +.\" commit ebec18a6d3aa1e7d84aab16225e87fd25170ec2b +If +.I arg2 +is nonzero, +set the "child subreaper" attribute of the calling process; +if +.I arg2 +is zero, unset the attribute. +.IP +A subreaper fulfills the role of +.BR init (1) +for its descendant processes. +When a process becomes orphaned +(i.e., its immediate parent terminates), +then that process will be reparented to +the nearest still living ancestor subreaper. +Subsequently, calls to +.BR getppid (2) +in the orphaned process will now return the PID of the subreaper process, +and when the orphan terminates, it is the subreaper process that +will receive a +.B SIGCHLD +signal and will be able to +.BR wait (2) +on the process to discover its termination status. +.IP +The setting of the "child subreaper" attribute +is not inherited by children created by +.BR fork (2) +and +.BR clone (2). +The setting is preserved across +.BR execve (2). +.IP +Establishing a subreaper process is useful in session management frameworks +where a hierarchical group of processes is managed by a subreaper process +that needs to be informed when one of the processes\[em]for example, +a double-forked daemon\[em]terminates +(perhaps so that it can restart that process). +Some +.BR init (1) +frameworks (e.g., +.BR systemd (1)) +employ a subreaper process for similar reasons. +.\" prctl PR_GET_CHILD_SUBREAPER +.TP +.BR PR_GET_CHILD_SUBREAPER " (since Linux 3.4)" +Return the "child subreaper" setting of the caller, +in the location pointed to by +.IR "(int\~*) arg2" . +.\" prctl PR_SET_DUMPABLE +.TP +.BR PR_SET_DUMPABLE " (since Linux 2.3.20)" +Set the state of the "dumpable" attribute, +which determines whether core dumps are produced for the calling process +upon delivery of a signal whose default behavior is to produce a core dump. +.IP +Up to and including Linux 2.6.12, +.I arg2 +must be either 0 +.RB ( SUID_DUMP_DISABLE , +process is not dumpable) or 1 +.RB ( SUID_DUMP_USER , +process is dumpable). +Between Linux 2.6.13 and Linux 2.6.17, +.\" commit abf75a5033d4da7b8a7e92321d74021d1fcfb502 +the value 2 was also permitted, +which caused any binary which normally would not be dumped +to be dumped readable by root only; +for security reasons, this feature has been removed. +.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2 +.\" Subject: Fix prctl privilege escalation (CVE-2006-2451) +.\" From: Marcel Holtmann +.\" Date: 2006-07-12 11:12:00 +(See also the description of +.I /proc/sys/fs/\:suid_dumpable +in +.BR proc (5).) +.IP +Normally, the "dumpable" attribute is set to 1. +However, it is reset to the current value contained in the file +.I /proc/sys/fs/\:suid_dumpable +(which by default has the value 0), +in the following circumstances: +.\" See kernel/cred.c::commit_creds() (Linux 3.18 sources) +.RS +.IP \[bu] 3 +The process's effective user or group ID is changed. +.IP \[bu] +The process's filesystem user or group ID is changed (see +.BR credentials (7)). +.IP \[bu] +The process executes +.RB ( execve (2)) +a set-user-ID or set-group-ID program, resulting in a change +of either the effective user ID or the effective group ID. +.IP \[bu] +The process executes +.RB ( execve (2)) +a program that has file capabilities (see +.BR capabilities (7)), +.\" See kernel/cred.c::commit_creds() +but only if the permitted capabilities +gained exceed those already permitted for the process. +.\" Also certain namespace operations; +.RE +.IP +Processes that are not dumpable can not be attached via +.BR ptrace (2) +.BR PTRACE_ATTACH ; +see +.BR ptrace (2) +for further details. +.IP +If a process is not dumpable, +the ownership of files in the process's +.IR /proc/ pid +directory is affected as described in +.BR proc (5). +.\" prctl PR_GET_DUMPABLE +.TP +.BR PR_GET_DUMPABLE " (since Linux 2.3.20)" +Return (as the function result) the current state of the calling +process's dumpable attribute. +.\" Since Linux 2.6.13, the dumpable flag can have the value 2, +.\" but in Linux 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable +.\" flags has a nonzero value. This was fixed in Linux 2.6.14. +.\" prctl PR_SET_ENDIAN +.TP +.BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)" +Set the endian-ness of the calling process to the value given +in \fIarg2\fP, which should be one of the following: +.\" Respectively 0, 1, 2 +.BR PR_ENDIAN_BIG , +.BR PR_ENDIAN_LITTLE , +or +.B PR_ENDIAN_PPC_LITTLE +(PowerPC pseudo little endian). +.\" prctl PR_GET_ENDIAN +.TP +.BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)" +Return the endian-ness of the calling process, +in the location pointed to by +.IR "(int\~*) arg2" . +.\" prctl PR_SET_FP_MODE +.TP +.BR PR_SET_FP_MODE " (since Linux 4.0, only on MIPS)" +.\" commit 9791554b45a2acc28247f66a5fd5bbc212a6b8c8 +On the MIPS architecture, +user-space code can be built using an ABI which permits linking +with code that has more restrictive floating-point (FP) requirements. +For example, user-space code may be built to target the O32 FPXX ABI +and linked with code built for either one of the more restrictive +FP32 or FP64 ABIs. +When more restrictive code is linked in, +the overall requirement for the process is to use the more +restrictive floating-point mode. +.IP +Because the kernel has no means of knowing in advance +which mode the process should be executed in, +and because these restrictions can +change over the lifetime of the process, the +.B PR_SET_FP_MODE +operation is provided to allow control of the floating-point mode +from user space. +.IP +.\" https://dmz-portal.mips.com/wiki/MIPS_O32_ABI_-_FR0_and_FR1_Interlinking +The +.I (unsigned int) arg2 +argument is a bit mask describing the floating-point mode used: +.RS +.TP +.B PR_FP_MODE_FR +When this bit is +.I unset +(so called +.BR FR=0 " or " FR0 +mode), the 32 floating-point registers are 32 bits wide, +and 64-bit registers are represented as a pair of registers +(even- and odd- numbered, +with the even-numbered register containing the lower 32 bits, +and the odd-numbered register containing the higher 32 bits). +.IP +When this bit is +.I set +(on supported hardware), +the 32 floating-point registers are 64 bits wide (so called +.BR FR=1 " or " FR1 +mode). +Note that modern MIPS implementations (MIPS R6 and newer) support +.B FR=1 +mode only. +.IP +Applications that use the O32 FP32 ABI can operate only when this bit is +.I unset +.RB ( FR=0 ; +or they can be used with FRE enabled, see below). +Applications that use the O32 FP64 ABI +(and the O32 FP64A ABI, which exists to +provide the ability to operate with existing FP32 code; see below) +can operate only when this bit is +.I set +.RB ( FR=1 ). +Applications that use the O32 FPXX ABI can operate with either +.B FR=0 +or +.BR FR=1 . +.TP +.B PR_FP_MODE_FRE +Enable emulation of 32-bit floating-point mode. +When this mode is enabled, +it emulates 32-bit floating-point operations +by raising a reserved-instruction exception +on every instruction that uses 32-bit formats and +the kernel then handles the instruction in software. +(The problem lies in the discrepancy of handling odd-numbered registers +which are the high 32 bits of 64-bit registers with even numbers in +.B FR=0 +mode and the lower 32-bit parts of odd-numbered 64-bit registers in +.B FR=1 +mode.) +Enabling this bit is necessary when code with the O32 FP32 ABI should operate +with code with compatible the O32 FPXX or O32 FP64A ABIs (which require +.B FR=1 +FPU mode) or when it is executed on newer hardware (MIPS R6 onwards) +which lacks +.B FR=0 +mode support when a binary with the FP32 ABI is used. +.IP +Note that this mode makes sense only when the FPU is in 64-bit mode +.RB ( FR=1 ). +.IP +Note that the use of emulation inherently has a significant performance hit +and should be avoided if possible. +.RE +.IP +In the N32/N64 ABI, 64-bit floating-point mode is always used, +so FPU emulation is not required and the FPU always operates in +.B FR=1 +mode. +.IP +This operation is mainly intended for use by the dynamic linker +.RB ( ld.so (8)). +.IP +The arguments +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.\" prctl PR_GET_FP_MODE +.TP +.BR PR_GET_FP_MODE " (since Linux 4.0, only on MIPS)" +Return (as the function result) +the current floating-point mode (see the description of +.B PR_SET_FP_MODE +for details). +.IP +On success, +the call returns a bit mask which represents the current floating-point mode. +.IP +The arguments +.IR arg2 , +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.\" prctl PR_SET_FPEMU +.TP +.BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)" +Set floating-point emulation control bits to \fIarg2\fP. +Pass +.B PR_FPEMU_NOPRINT +to silently emulate floating-point operation accesses, or +.B PR_FPEMU_SIGFPE +to not emulate floating-point operations and send +.B SIGFPE +instead. +.\" prctl PR_GET_FPEMU +.TP +.BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)" +Return floating-point emulation control bits, +in the location pointed to by +.IR "(int\~*) arg2" . +.\" prctl PR_SET_FPEXC +.TP +.BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)" +Set floating-point exception mode to \fIarg2\fP. +Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables, +\fBPR_FP_EXC_DIV\fP for floating-point divide by zero, +\fBPR_FP_EXC_OVF\fP for floating-point overflow, +\fBPR_FP_EXC_UND\fP for floating-point underflow, +\fBPR_FP_EXC_RES\fP for floating-point inexact result, +\fBPR_FP_EXC_INV\fP for floating-point invalid operation, +\fBPR_FP_EXC_DISABLED\fP for FP exceptions disabled, +\fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode, +\fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode, +\fBPR_FP_EXC_PRECISE\fP for precise exception mode. +.\" prctl PR_GET_FPEXC +.TP +.BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)" +Return floating-point exception mode, +in the location pointed to by +.IR "(int\~*) arg2" . +.\" prctl PR_SET_IO_FLUSHER +.TP +.BR PR_SET_IO_FLUSHER " (since Linux 5.6)" +If a user process is involved in the block layer or filesystem I/O path, +and can allocate memory while processing I/O requests it must set +\fIarg2\fP to 1. +This will put the process in the IO_FLUSHER state, +which allows it special treatment to make progress when allocating memory. +If \fIarg2\fP is 0, the process will clear the IO_FLUSHER state, and +the default behavior will be used. +.IP +The calling process must have the +.B CAP_SYS_RESOURCE +capability. +.IP +.IR arg3 , +.IR arg4 , +and +.I arg5 +must be zero. +.IP +The IO_FLUSHER state is inherited by a child process created via +.BR fork (2) +and is preserved across +.BR execve (2). +.IP +Examples of IO_FLUSHER applications are FUSE daemons, SCSI device +emulation daemons, and daemons that perform error handling like multipath +path recovery applications. +.\" prctl PR_GET_IO_FLUSHER +.TP +.B PR_GET_IO_FLUSHER (Since Linux 5.6) +Return (as the function result) the IO_FLUSHER state of the caller. +A value of 1 indicates that the caller is in the IO_FLUSHER state; +0 indicates that the caller is not in the IO_FLUSHER state. +.IP +The calling process must have the +.B CAP_SYS_RESOURCE +capability. +.IP +.IR arg2 , +.IR arg3 , +.IR arg4 , +and +.I arg5 +must be zero. +.\" prctl PR_SET_KEEPCAPS +.TP +.BR PR_SET_KEEPCAPS " (since Linux 2.2.18)" +Set the state of the calling thread's "keep capabilities" flag. +The effect of this flag is described in +.BR capabilities (7). +.I arg2 +must be either 0 (clear the flag) +or 1 (set the flag). +The "keep capabilities" value will be reset to 0 on subsequent calls to +.BR execve (2). +.\" prctl PR_GET_KEEPCAPS +.TP +.BR PR_GET_KEEPCAPS " (since Linux 2.2.18)" +Return (as the function result) the current state of the calling thread's +"keep capabilities" flag. +See +.BR capabilities (7) +for a description of this flag. +.\" prctl PR_MCE_KILL +.TP +.BR PR_MCE_KILL " (since Linux 2.6.32)" +Set the machine check memory corruption kill policy for the calling thread. +If +.I arg2 +is +.BR PR_MCE_KILL_CLEAR , +clear the thread memory corruption kill policy and use the system-wide default. +(The system-wide default is defined by +.IR /proc/sys/vm/memory_failure_early_kill ; +see +.BR proc (5).) +If +.I arg2 +is +.BR PR_MCE_KILL_SET , +use a thread-specific memory corruption kill policy. +In this case, +.I arg3 +defines whether the policy is +.I early kill +.RB ( PR_MCE_KILL_EARLY ), +.I late kill +.RB ( PR_MCE_KILL_LATE ), +or the system-wide default +.RB ( PR_MCE_KILL_DEFAULT ). +Early kill means that the thread receives a +.B SIGBUS +signal as soon as hardware memory corruption is detected inside +its address space. +In late kill mode, the process is killed only when it accesses a corrupted page. +See +.BR sigaction (2) +for more information on the +.B SIGBUS +signal. +The policy is inherited by children. +The remaining unused +.BR prctl () +arguments must be zero for future compatibility. +.\" prctl PR_MCE_KILL_GET +.TP +.BR PR_MCE_KILL_GET " (since Linux 2.6.32)" +Return (as the function result) +the current per-process machine check kill policy. +All unused +.BR prctl () +arguments must be zero. +.\" prctl PR_SET_MM +.TP +.BR PR_SET_MM " (since Linux 3.3)" +.\" commit 028ee4be34a09a6d48bdf30ab991ae933a7bc036 +Modify certain kernel memory map descriptor fields +of the calling process. +Usually these fields are set by the kernel and dynamic loader (see +.BR ld.so (8) +for more information) and a regular application should not use this feature. +However, there are cases, such as self-modifying programs, +where a program might find it useful to change its own memory map. +.IP +The calling process must have the +.B CAP_SYS_RESOURCE +capability. +The value in +.I arg2 +is one of the options below, while +.I arg3 +provides a new value for the option. +The +.I arg4 +and +.I arg5 +arguments must be zero if unused. +.IP +Before Linux 3.10, +.\" commit 52b3694157e3aa6df871e283115652ec6f2d31e0 +this feature is available only if the kernel is built with the +.B CONFIG_CHECKPOINT_RESTORE +option enabled. +.RS +.TP +.B PR_SET_MM_START_CODE +Set the address above which the program text can run. +The corresponding memory area must be readable and executable, +but not writable or shareable (see +.BR mprotect (2) +and +.BR mmap (2) +for more information). +.TP +.B PR_SET_MM_END_CODE +Set the address below which the program text can run. +The corresponding memory area must be readable and executable, +but not writable or shareable. +.TP +.B PR_SET_MM_START_DATA +Set the address above which initialized and +uninitialized (bss) data are placed. +The corresponding memory area must be readable and writable, +but not executable or shareable. +.TP +.B PR_SET_MM_END_DATA +Set the address below which initialized and +uninitialized (bss) data are placed. +The corresponding memory area must be readable and writable, +but not executable or shareable. +.TP +.B PR_SET_MM_START_STACK +Set the start address of the stack. +The corresponding memory area must be readable and writable. +.TP +.B PR_SET_MM_START_BRK +Set the address above which the program heap can be expanded with +.BR brk (2) +call. +The address must be greater than the ending address of +the current program data segment. +In addition, the combined size of the resulting heap and +the size of the data segment can't exceed the +.B RLIMIT_DATA +resource limit (see +.BR setrlimit (2)). +.TP +.B PR_SET_MM_BRK +Set the current +.BR brk (2) +value. +The requirements for the address are the same as for the +.B PR_SET_MM_START_BRK +option. +.P +The following options are available since Linux 3.5. +.\" commit fe8c7f5cbf91124987106faa3bdf0c8b955c4cf7 +.TP +.B PR_SET_MM_ARG_START +Set the address above which the program command line is placed. +.TP +.B PR_SET_MM_ARG_END +Set the address below which the program command line is placed. +.TP +.B PR_SET_MM_ENV_START +Set the address above which the program environment is placed. +.TP +.B PR_SET_MM_ENV_END +Set the address below which the program environment is placed. +.IP +The address passed with +.BR PR_SET_MM_ARG_START , +.BR PR_SET_MM_ARG_END , +.BR PR_SET_MM_ENV_START , +and +.B PR_SET_MM_ENV_END +should belong to a process stack area. +Thus, the corresponding memory area must be readable, writable, and +(depending on the kernel configuration) have the +.B MAP_GROWSDOWN +attribute set (see +.BR mmap (2)). +.TP +.B PR_SET_MM_AUXV +Set a new auxiliary vector. +The +.I arg3 +argument should provide the address of the vector. +The +.I arg4 +is the size of the vector. +.TP +.B PR_SET_MM_EXE_FILE +.\" commit b32dfe377102ce668775f8b6b1461f7ad428f8b6 +Supersede the +.IR /proc/ pid /exe +symbolic link with a new one pointing to a new executable file +identified by the file descriptor provided in +.I arg3 +argument. +The file descriptor should be obtained with a regular +.BR open (2) +call. +.IP +To change the symbolic link, one needs to unmap all existing +executable memory areas, including those created by the kernel itself +(for example the kernel usually creates at least one executable +memory area for the ELF +.I .text +section). +.IP +In Linux 4.9 and earlier, the +.\" commit 3fb4afd9a504c2386b8435028d43283216bf588e +.B PR_SET_MM_EXE_FILE +operation can be performed only once in a process's lifetime; +attempting to perform the operation a second time results in the error +.BR EPERM . +This restriction was enforced for security reasons that were subsequently +deemed specious, +and the restriction was removed in Linux 4.10 because some +user-space applications needed to perform this operation more than once. +.P +The following options are available since Linux 3.18. +.\" commit f606b77f1a9e362451aca8f81d8f36a3a112139e +.TP +.B PR_SET_MM_MAP +Provides one-shot access to all the addresses by passing in a +.I struct prctl_mm_map +(as defined in \fI\fP). +The +.I arg4 +argument should provide the size of the struct. +.IP +This feature is available only if the kernel is built with the +.B CONFIG_CHECKPOINT_RESTORE +option enabled. +.TP +.B PR_SET_MM_MAP_SIZE +Returns the size of the +.I struct prctl_mm_map +the kernel expects. +This allows user space to find a compatible struct. +The +.I arg4 +argument should be a pointer to an unsigned int. +.IP +This feature is available only if the kernel is built with the +.B CONFIG_CHECKPOINT_RESTORE +option enabled. +.RE +.\" prctl PR_SET_VMA +.TP +.BR PR_SET_VMA " (since Linux 5.17)" +.\" Commit 9a10064f5625d5572c3626c1516e0bebc6c9fe9b +Sets an attribute specified in +.I arg2 +for virtual memory areas starting from the address specified in +.I arg3 +and spanning the size specified in +.IR arg4 . +.I arg5 +specifies the value of the attribute to be set. +.IP +Note that assigning an attribute to a virtual memory area +might prevent it from being merged with adjacent virtual memory areas +due to the difference in that attribute's value. +.IP +Currently, +.I arg2 +must be one of: +.RS +.TP +.B PR_SET_VMA_ANON_NAME +Set a name for anonymous virtual memory areas. +.I arg5 +should be a pointer to a null-terminated string containing the name. +The name length including null byte cannot exceed 80 bytes. +If +.I arg5 +is NULL, the name of the appropriate anonymous virtual memory areas +will be reset. +The name can contain only printable ascii characters (including space), +except \[aq][\[aq], \[aq]]\[aq], \[aq]\e\[aq], \[aq]$\[aq], and \[aq]\[ga]\[aq]. +.RE +.\" prctl PR_MPX_ENABLE_MANAGEMENT +.TP +.B PR_MPX_ENABLE_MANAGEMENT +.TQ +.BR PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19, removed in Linux 5.4; only on x86)" +.\" commit fe3d197f84319d3bce379a9c0dc17b1f48ad358c +.\" See also http://lwn.net/Articles/582712/ +.\" See also https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler +Enable or disable kernel management of Memory Protection eXtensions (MPX) +bounds tables. +The +.IR arg2 , +.IR arg3 , +.IR arg4 , +and +.I arg5 +.\" commit e9d1b4f3c60997fe197bf0243cb4a41a44387a88 +arguments must be zero. +.IP +MPX is a hardware-assisted mechanism for performing bounds checking on +pointers. +It consists of a set of registers storing bounds information +and a set of special instruction prefixes that tell the CPU on which +instructions it should do bounds enforcement. +There is a limited number of these registers and +when there are more pointers than registers, +their contents must be "spilled" into a set of tables. +These tables are called "bounds tables" and the MPX +.BR prctl () +operations control +whether the kernel manages their allocation and freeing. +.IP +When management is enabled, the kernel will take over allocation +and freeing of the bounds tables. +It does this by trapping the #BR exceptions that result +at first use of missing bounds tables and +instead of delivering the exception to user space, +it allocates the table and populates the bounds directory +with the location of the new table. +For freeing, the kernel checks to see if bounds tables are +present for memory which is not allocated, and frees them if so. +.IP +Before enabling MPX management using +.BR PR_MPX_ENABLE_MANAGEMENT , +the application must first have allocated a user-space buffer for +the bounds directory and placed the location of that directory in the +.I bndcfgu +register. +.IP +These calls fail if the CPU or kernel does not support MPX. +Kernel support for MPX is enabled via the +.B CONFIG_X86_INTEL_MPX +configuration option. +You can check whether the CPU supports MPX by looking for the +.I mpx +CPUID bit, like with the following command: +.IP +.in +4n +.EX +cat /proc/cpuinfo | grep \[aq] mpx \[aq] +.EE +.in +.IP +A thread may not switch in or out of long (64-bit) mode while MPX is +enabled. +.IP +All threads in a process are affected by these calls. +.IP +The child of a +.BR fork (2) +inherits the state of MPX management. +During +.BR execve (2), +MPX management is reset to a state as if +.B PR_MPX_DISABLE_MANAGEMENT +had been called. +.IP +For further information on Intel MPX, see the kernel source file +.IR Documentation/x86/intel_mpx.txt . +.IP +.\" commit f240652b6032b48ad7fa35c5e701cc4c8d697c0b +.\" See also https://lkml.kernel.org/r/20190705175321.DB42F0AD@viggo.jf.intel.com +Due to a lack of toolchain support, +.BR PR_MPX_ENABLE_MANAGEMENT " and " PR_MPX_DISABLE_MANAGEMENT +are not supported in Linux 5.4 and later. +.\" prctl PR_SET_NAME +.TP +.BR PR_SET_NAME " (since Linux 2.6.9)" +Set the name of the calling thread, +using the value in the location pointed to by +.IR "(char\~*) arg2" . +The name can be up to 16 bytes long, +.\" TASK_COMM_LEN in include/linux/sched.h +including the terminating null byte. +(If the length of the string, including the terminating null byte, +exceeds 16 bytes, the string is silently truncated.) +This is the same attribute that can be set via +.BR pthread_setname_np (3) +and retrieved using +.BR pthread_getname_np (3). +The attribute is likewise accessible via +.IR /proc/self/task/ tid /comm +(see +.BR proc (5)), +where +.I tid +is the thread ID of the calling thread, as returned by +.BR gettid (2). +.\" prctl PR_GET_NAME +.TP +.BR PR_GET_NAME " (since Linux 2.6.11)" +Return the name of the calling thread, +in the buffer pointed to by +.IR "(char\~*) arg2" . +The buffer should allow space for up to 16 bytes; +the returned string will be null-terminated. +.\" prctl PR_SET_NO_NEW_PRIVS +.TP +.BR PR_SET_NO_NEW_PRIVS " (since Linux 3.5)" +Set the calling thread's +.I no_new_privs +attribute to the value in +.IR arg2 . +With +.I no_new_privs +set to 1, +.BR execve (2) +promises not to grant privileges to do anything +that could not have been done without the +.BR execve (2) +call (for example, +rendering the set-user-ID and set-group-ID mode bits, +and file capabilities non-functional). +Once set, the +.I no_new_privs +attribute cannot be unset. +The setting of this attribute is inherited by children created by +.BR fork (2) +and +.BR clone (2), +and preserved across +.BR execve (2). +.IP +Since Linux 4.10, +the value of a thread's +.I no_new_privs +attribute can be viewed via the +.I NoNewPrivs +field in the +.IR /proc/ pid /status +file. +.IP +For more information, see the kernel source file +.I Documentation/userspace\-api/no_new_privs.rst +.\" commit 40fde647ccb0ae8c11d256d271e24d385eed595b +(or +.I Documentation/prctl/no_new_privs.txt +before Linux 4.13). +See also +.BR seccomp (2). +.\" prctl PR_GET_NO_NEW_PRIVS +.TP +.BR PR_GET_NO_NEW_PRIVS " (since Linux 3.5)" +Return (as the function result) the value of the +.I no_new_privs +attribute for the calling thread. +A value of 0 indicates the regular +.BR execve (2) +behavior. +A value of 1 indicates +.BR execve (2) +will operate in the privilege-restricting mode described above. +.\" prctl PR_PAC_RESET_KEYS +.\" commit ba830885656414101b2f8ca88786524d4bb5e8c1 +.TP +.BR PR_PAC_RESET_KEYS " (since Linux 5.0, only on arm64)" +Securely reset the thread's pointer authentication keys +to fresh random values generated by the kernel. +.IP +The set of keys to be reset is specified by +.IR arg2 , +which must be a logical OR of zero or more of the following: +.RS +.TP +.B PR_PAC_APIAKEY +instruction authentication key A +.TP +.B PR_PAC_APIBKEY +instruction authentication key B +.TP +.B PR_PAC_APDAKEY +data authentication key A +.TP +.B PR_PAC_APDBKEY +data authentication key B +.TP +.B PR_PAC_APGAKEY +generic authentication \[lq]A\[rq] key. +.IP +(Yes folks, there really is no generic B key.) +.RE +.IP +As a special case, if +.I arg2 +is zero, then all the keys are reset. +Since new keys could be added in future, +this is the recommended way to completely wipe the existing keys +when establishing a clean execution context. +Note that there is no need to use +.B PR_PAC_RESET_KEYS +in preparation for calling +.BR execve (2), +since +.BR execve (2) +resets all the pointer authentication keys. +.IP +The remaining arguments +.IR arg3 ", " arg4 ", and " arg5 +must all be zero. +.IP +If the arguments are invalid, +and in particular if +.I arg2 +contains set bits that are unrecognized +or that correspond to a key not available on this platform, +then the call fails with error +.BR EINVAL . +.IP +.B Warning: +Because the compiler or run-time environment +may be using some or all of the keys, +a successful +.B PR_PAC_RESET_KEYS +may crash the calling process. +The conditions for using it safely are complex and system-dependent. +Don't use it unless you know what you are doing. +.IP +For more information, see the kernel source file +.I Documentation/arm64/pointer\-authentication.rst +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed +(or +.I Documentation/arm64/pointer\-authentication.txt +before Linux 5.3). +.\" prctl PR_SET_PDEATHSIG +.TP +.BR PR_SET_PDEATHSIG " (since Linux 2.1.57)" +Set the parent-death signal +of the calling process to \fIarg2\fP (either a signal value +in the range +.RB [ 1 , +.IR NSIG\~\-\~1 ], +or +.B 0 +to clear). +This is the signal that the calling process will get when its +parent dies. +.IP +.IR Warning : +.\" https://bugzilla.kernel.org/show_bug.cgi?id=43300 +the "parent" in this case is considered to be the +.I thread +that created this process. +In other words, the signal will be sent when that thread terminates +(via, for example, +.BR pthread_exit (3)), +rather than after all of the threads in the parent process terminate. +.IP +The parent-death signal is sent upon subsequent termination of the parent +thread and also upon termination of each subreaper process +(see the description of +.B PR_SET_CHILD_SUBREAPER +above) to which the caller is subsequently reparented. +If the parent thread and all ancestor subreapers have already terminated +by the time of the +.B PR_SET_PDEATHSIG +operation, then no parent-death signal is sent to the caller. +.IP +The parent-death signal is process-directed (see +.BR signal (7)) +and, if the child installs a handler using the +.BR sigaction (2) +.B SA_SIGINFO +flag, the +.I si_pid +field of the +.I siginfo_t +argument of the handler contains the PID of the terminating parent process. +.IP +The parent-death signal setting is cleared for the child of a +.BR fork (2). +It is also +(since Linux 2.4.36 / 2.6.23) +.\" commit d2d56c5f51028cb9f3d800882eb6f4cbd3f9099f +cleared when executing a set-user-ID or set-group-ID binary, +or a binary that has associated capabilities (see +.BR capabilities (7)); +otherwise, this value is preserved across +.BR execve (2). +The parent-death signal setting is also cleared upon changes to +any of the following thread credentials: +.\" FIXME capability changes can also trigger this; see +.\" kernel/cred.c::commit_creds in the Linux 5.6 source. +effective user ID, effective group ID, filesystem user ID, +or filesystem group ID. +.\" prctl PR_GET_PDEATHSIG +.TP +.BR PR_GET_PDEATHSIG " (since Linux 2.3.15)" +Return the current value of the parent process death signal, +in the location pointed to by +.IR "(int\~*) arg2" . +.\" prctl PR_SET_PTRACER +.TP +.BR PR_SET_PTRACER " (since Linux 3.4)" +.\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb +.\" commit bf06189e4d14641c0148bea16e9dd24943862215 +This is meaningful only when the Yama LSM is enabled and in mode 1 +("restricted ptrace", visible via +.IR /proc/sys/kernel/yama/ptrace_scope ). +When a "ptracer process ID" is passed in \fIarg2\fP, +the caller is declaring that the ptracer process can +.BR ptrace (2) +the calling process as if it were a direct process ancestor. +Each +.B PR_SET_PTRACER +operation replaces the previous "ptracer process ID". +Employing +.B PR_SET_PTRACER +with +.I arg2 +set to 0 clears the caller's "ptracer process ID". +If +.I arg2 +is +.BR PR_SET_PTRACER_ANY , +the ptrace restrictions introduced by Yama are effectively disabled for the +calling process. +.IP +For further information, see the kernel source file +.I Documentation/admin\-guide/LSM/Yama.rst +.\" commit 90bb766440f2147486a2acc3e793d7b8348b0c22 +(or +.I Documentation/security/Yama.txt +before Linux 4.13). +.\" prctl PR_SET_SECCOMP +.TP +.BR PR_SET_SECCOMP " (since Linux 2.6.23)" +.\" See http://thread.gmane.org/gmane.linux.kernel/542632 +.\" [PATCH 0 of 2] seccomp updates +.\" andrea@cpushare.com +Set the secure computing (seccomp) mode for the calling thread, to limit +the available system calls. +The more recent +.BR seccomp (2) +system call provides a superset of the functionality of +.BR PR_SET_SECCOMP , +and is the preferred interface for new applications. +.IP +The seccomp mode is selected via +.IR arg2 . +(The seccomp constants are defined in +.IR .) +The following values can be specified: +.RS +.TP +.BR SECCOMP_MODE_STRICT " (since Linux 2.6.23)" +See the description of +.B SECCOMP_SET_MODE_STRICT +in +.BR seccomp (2). +.IP +This operation is available only +if the kernel is configured with +.B CONFIG_SECCOMP +enabled. +.TP +.BR SECCOMP_MODE_FILTER " (since Linux 3.5)" +The allowed system calls are defined by a pointer +to a Berkeley Packet Filter passed in +.IR arg3 . +This argument is a pointer to +.IR "struct sock_fprog" ; +it can be designed to filter +arbitrary system calls and system call arguments. +See the description of +.B SECCOMP_SET_MODE_FILTER +in +.BR seccomp (2). +.IP +This operation is available only +if the kernel is configured with +.B CONFIG_SECCOMP_FILTER +enabled. +.RE +.IP +For further details on seccomp filtering, see +.BR seccomp (2). +.\" prctl PR_GET_SECCOMP +.TP +.BR PR_GET_SECCOMP " (since Linux 2.6.23)" +Return (as the function result) +the secure computing mode of the calling thread. +If the caller is not in secure computing mode, this operation returns 0; +if the caller is in strict secure computing mode, then the +.BR prctl () +call will cause a +.B SIGKILL +signal to be sent to the process. +If the caller is in filter mode, and this system call is allowed by the +seccomp filters, it returns 2; otherwise, the process is killed with a +.B SIGKILL +signal. +.IP +This operation is available only +if the kernel is configured with +.B CONFIG_SECCOMP +enabled. +.IP +Since Linux 3.8, the +.I Seccomp +field of the +.IR /proc/ pid /status +file provides a method of obtaining the same information, +without the risk that the process is killed; see +.BR proc (5). +.\" prctl PR_SET_SECUREBITS +.TP +.BR PR_SET_SECUREBITS " (since Linux 2.6.26)" +Set the "securebits" flags of the calling thread to the value supplied in +.IR arg2 . +See +.BR capabilities (7). +.\" prctl PR_GET_SECUREBITS +.TP +.BR PR_GET_SECUREBITS " (since Linux 2.6.26)" +Return (as the function result) +the "securebits" flags of the calling thread. +See +.BR capabilities (7). +.\" prctl PR_GET_SPECULATION_CTRL +.TP +.BR PR_GET_SPECULATION_CTRL " (since Linux 4.17)" +Return (as the function result) +the state of the speculation misfeature specified in +.IR arg2 . +Currently, the only permitted value for this argument is +.B PR_SPEC_STORE_BYPASS +(otherwise the call fails with the error +.BR ENODEV ). +.IP +The return value uses bits 0-3 with the following meaning: +.RS +.TP +.B PR_SPEC_PRCTL +Mitigation can be controlled per thread by +.BR PR_SET_SPECULATION_CTRL . +.TP +.B PR_SPEC_ENABLE +The speculation feature is enabled, mitigation is disabled. +.TP +.B PR_SPEC_DISABLE +The speculation feature is disabled, mitigation is enabled. +.TP +.B PR_SPEC_FORCE_DISABLE +Same as +.B PR_SPEC_DISABLE +but cannot be undone. +.TP +.BR PR_SPEC_DISABLE_NOEXEC " (since Linux 5.1)" +Same as +.BR PR_SPEC_DISABLE , +but the state will be cleared on +.BR execve (2). +.RE +.IP +If all bits are 0, +then the CPU is not affected by the speculation misfeature. +.IP +If +.B PR_SPEC_PRCTL +is set, then per-thread control of the mitigation is available. +If not set, +.BR prctl () +for the speculation misfeature will fail. +.IP +The +.IR arg3 , +.IR arg4 , +and +.I arg5 +arguments must be specified as 0; otherwise the call fails with the error +.BR EINVAL . +.\" prctl PR_SET_SPECULATION_CTRL +.TP +.BR PR_SET_SPECULATION_CTRL " (since Linux 4.17)" +.\" commit b617cfc858161140d69cc0b5cc211996b557a1c7 +.\" commit 356e4bfff2c5489e016fdb925adbf12a1e3950ee +Sets the state of the speculation misfeature specified in +.IR arg2 . +The speculation-misfeature settings are per-thread attributes. +.IP +Currently, +.I arg2 +must be one of: +.RS +.TP +.B PR_SPEC_STORE_BYPASS +Set the state of the speculative store bypass misfeature. +.\" commit 9137bb27e60e554dab694eafa4cca241fa3a694f +.TP +.BR PR_SPEC_INDIRECT_BRANCH " (since Linux 4.20)" +Set the state of the indirect branch speculation misfeature. +.RE +.IP +If +.I arg2 +does not have one of the above values, +then the call fails with the error +.BR ENODEV . +.IP +The +.I arg3 +argument is used to hand in the control value, +which is one of the following: +.RS +.TP +.B PR_SPEC_ENABLE +The speculation feature is enabled, mitigation is disabled. +.TP +.B PR_SPEC_DISABLE +The speculation feature is disabled, mitigation is enabled. +.TP +.B PR_SPEC_FORCE_DISABLE +Same as +.BR PR_SPEC_DISABLE , +but cannot be undone. +A subsequent +.BR prctl (\c +.IR arg2 , +.BR PR_SPEC_ENABLE ) +with the same value for +.I arg2 +will fail with the error +.BR EPERM . +.\" commit 71368af9027f18fe5d1c6f372cfdff7e4bde8b48 +.TP +.BR PR_SPEC_DISABLE_NOEXEC " (since Linux 5.1)" +Same as +.BR PR_SPEC_DISABLE , +but the state will be cleared on +.BR execve (2). +Currently only supported for +.I arg2 +equal to +.B PR_SPEC_STORE_BYPASS. +.RE +.IP +Any unsupported value in +.I arg3 +will result in the call failing with the error +.BR ERANGE . +.IP +The +.I arg4 +and +.I arg5 +arguments must be specified as 0; otherwise the call fails with the error +.BR EINVAL . +.IP +The speculation feature can also be controlled by the +.B spec_store_bypass_disable +boot parameter. +This parameter may enforce a read-only policy which will result in the +.BR prctl () +call failing with the error +.BR ENXIO . +For further details, see the kernel source file +.IR Documentation/admin\-guide/kernel\-parameters.txt . +.\" prctl PR_SVE_SET_VL +.\" commit 2d2123bc7c7f843aa9db87720de159a049839862 +.\" linux-5.6/Documentation/arm64/sve.rst +.TP +.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)" +Configure the thread's SVE vector length, +as specified by +.IR "(int) arg2" . +Arguments +.IR arg3 , +.IR arg4 , +and +.I arg5 +are ignored. +.IP +The bits of +.I arg2 +corresponding to +.B PR_SVE_VL_LEN_MASK +must be set to the desired vector length in bytes. +This is interpreted as an upper bound: +the kernel will select the greatest available vector length +that does not exceed the value specified. +In particular, specifying +.B SVE_VL_MAX +(defined in +.I ) +for the +.B PR_SVE_VL_LEN_MASK +bits requests the maximum supported vector length. +.IP +In addition, the other bits of +.I arg2 +must be set to one of the following combinations of flags: +.RS +.TP +.B 0 +Perform the change immediately. +At the next +.BR execve (2) +in the thread, +the vector length will be reset to the value configured in +.IR /proc/sys/abi/sve_default_vector_length . +.TP +.B PR_SVE_VL_INHERIT +Perform the change immediately. +Subsequent +.BR execve (2) +calls will preserve the new vector length. +.TP +.B PR_SVE_SET_VL_ONEXEC +Defer the change, so that it is performed at the next +.BR execve (2) +in the thread. +Further +.BR execve (2) +calls will reset the vector length to the value configured in +.IR /proc/sys/abi/sve_default_vector_length . +.TP +.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT" +Defer the change, so that it is performed at the next +.BR execve (2) +in the thread. +Further +.BR execve (2) +calls will preserve the new vector length. +.RE +.IP +In all cases, +any previously pending deferred change is canceled. +.IP +The call fails with error +.B EINVAL +if SVE is not supported on the platform, if +.I arg2 +is unrecognized or invalid, or the value in the bits of +.I arg2 +corresponding to +.B PR_SVE_VL_LEN_MASK +is outside the range +.BR SVE_VL_MIN .. SVE_VL_MAX +or is not a multiple of 16. +.IP +On success, +a nonnegative value is returned that describes the +.I selected +configuration. +If +.B PR_SVE_SET_VL_ONEXEC +was included in +.IR arg2 , +then the configuration described by the return value +will take effect at the next +.BR execve (2). +Otherwise, the configuration is already in effect when the +.B PR_SVE_SET_VL +call returns. +In either case, the value is encoded in the same way as the return value of +.BR PR_SVE_GET_VL . +Note that there is no explicit flag in the return value +corresponding to +.BR PR_SVE_SET_VL_ONEXEC . +.IP +The configuration (including any pending deferred change) +is inherited across +.BR fork (2) +and +.BR clone (2). +.IP +For more information, see the kernel source file +.I Documentation/arm64/sve.rst +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed +(or +.I Documentation/arm64/sve.txt +before Linux 5.3). +.IP +.B Warning: +Because the compiler or run-time environment +may be using SVE, using this call without the +.B PR_SVE_SET_VL_ONEXEC +flag may crash the calling process. +The conditions for using it safely are complex and system-dependent. +Don't use it unless you really know what you are doing. +.\" prctl PR_SVE_GET_VL +.TP +.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)" +Get the thread's current SVE vector length configuration. +.IP +Arguments +.IR arg2 ", " arg3 ", " arg4 ", and " arg5 +are ignored. +.IP +Provided that the kernel and platform support SVE, +this operation always succeeds, +returning a nonnegative value that describes the +.I current +configuration. +The bits corresponding to +.B PR_SVE_VL_LEN_MASK +contain the currently configured vector length in bytes. +The bit corresponding to +.B PR_SVE_VL_INHERIT +indicates whether the vector length will be inherited +across +.BR execve (2). +.IP +Note that there is no way to determine whether there is +a pending vector length change that has not yet taken effect. +.IP +For more information, see the kernel source file +.I Documentation/arm64/sve.rst +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed +(or +.I Documentation/arm64/sve.txt +before Linux 5.3). +.TP +.\" prctl PR_SET_SYSCALL_USER_DISPATCH +.\" commit 1446e1df9eb183fdf81c3f0715402f1d7595d4 +.BR PR_SET_SYSCALL_USER_DISPATCH " (since Linux 5.11, x86 only)" +Configure the Syscall User Dispatch mechanism +for the calling thread. +This mechanism allows an application +to selectively intercept system calls +so that they can be handled within the application itself. +Interception takes the form of a thread-directed +.B SIGSYS +signal that is delivered to the thread +when it makes a system call. +If intercepted, +the system call is not executed by the kernel. +.IP +To enable this mechanism, +.I arg2 +should be set to +.BR PR_SYS_DISPATCH_ON . +Once enabled, further system calls will be selectively intercepted, +depending on a control variable provided by user space. +In this case, +.I arg3 +and +.I arg4 +respectively identify the +.I offset +and +.I length +of a single contiguous memory region in the process address space +from where system calls are always allowed to be executed, +regardless of the control variable. +(Typically, this area would include the area of memory +containing the C library.) +.IP +.I arg5 +points to a char-sized variable +that is a fast switch to allow/block system call execution +without the overhead of doing another system call +to re-configure Syscall User Dispatch. +This control variable can either be set to +.B SYSCALL_DISPATCH_FILTER_BLOCK +to block system calls from executing +or to +.B SYSCALL_DISPATCH_FILTER_ALLOW +to temporarily allow them to be executed. +This value is checked by the kernel +on every system call entry, +and any unexpected value will raise +an uncatchable +.B SIGSYS +at that time, +killing the application. +.IP +When a system call is intercepted, +the kernel sends a thread-directed +.B SIGSYS +signal to the triggering thread. +Various fields will be set in the +.I siginfo_t +structure (see +.BR sigaction (2)) +associated with the signal: +.RS +.IP \[bu] 3 +.I si_signo +will contain +.BR SIGSYS . +.IP \[bu] +.I si_call_addr +will show the address of the system call instruction. +.IP \[bu] +.I si_syscall +and +.I si_arch +will indicate which system call was attempted. +.IP \[bu] +.I si_code +will contain +.BR SYS_USER_DISPATCH . +.IP \[bu] +.I si_errno +will be set to 0. +.RE +.IP +The program counter will be as though the system call happened +(i.e., the program counter will not point to the system call instruction). +.IP +When the signal handler returns to the kernel, +the system call completes immediately +and returns to the calling thread, +without actually being executed. +If necessary +(i.e., when emulating the system call on user space.), +the signal handler should set the system call return value +to a sane value, +by modifying the register context stored in the +.I ucontext +argument of the signal handler. +See +.BR sigaction (2), +.BR sigreturn (2), +and +.BR getcontext (3) +for more information. +.IP +If +.I arg2 +is set to +.BR PR_SYS_DISPATCH_OFF , +Syscall User Dispatch is disabled for that thread. +the remaining arguments must be set to 0. +.IP +The setting is not preserved across +.BR fork (2), +.BR clone (2), +or +.BR execve (2). +.IP +For more information, +see the kernel source file +.I Documentation/admin\-guide/syscall\-user\-dispatch.rst +.\" prctl PR_SET_TAGGED_ADDR_CTRL +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d +.TP +.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)" +Controls support for passing tagged user-space addresses to the kernel +(i.e., addresses where bits 56\[em]63 are not all zero). +.IP +The level of support is selected by +.IR "arg2" , +which can be one of the following: +.RS +.TP +.B 0 +Addresses that are passed +for the purpose of being dereferenced by the kernel +must be untagged. +.TP +.B PR_TAGGED_ADDR_ENABLE +Addresses that are passed +for the purpose of being dereferenced by the kernel +may be tagged, with the exceptions summarized below. +.RE +.IP +The remaining arguments +.IR arg3 ", " arg4 ", and " arg5 +must all be zero. +.\" Enforcement added in +.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95 +.IP +On success, the mode specified in +.I arg2 +is set for the calling thread and the return value is 0. +If the arguments are invalid, +the mode specified in +.I arg2 +is unrecognized, +or if this feature is unsupported by the kernel +or disabled via +.IR /proc/sys/abi/tagged_addr_disabled , +the call fails with the error +.BR EINVAL . +.IP +In particular, if +.BR prctl ( PR_SET_TAGGED_ADDR_CTRL , +0, 0, 0, 0) +fails with +.BR EINVAL , +then all addresses passed to the kernel must be untagged. +.IP +Irrespective of which mode is set, +addresses passed to certain interfaces +must always be untagged: +.RS +.IP \[bu] 3 +.BR brk (2), +.BR mmap (2), +.BR shmat (2), +.BR shmdt (2), +and the +.I new_address +argument of +.BR mremap (2). +.IP +(Prior to Linux 5.6 these accepted tagged addresses, +but the behaviour may not be what you expect. +Don't rely on it.) +.IP \[bu] +\[oq]polymorphic\[cq] interfaces +that accept pointers to arbitrary types cast to a +.I void * +or other generic type, specifically +.BR prctl (), +.BR ioctl (2), +and in general +.BR setsockopt (2) +(only certain specific +.BR setsockopt (2) +options allow tagged addresses). +.RE +.IP +This list of exclusions may shrink +when moving from one kernel version to a later kernel version. +While the kernel may make some guarantees +for backwards compatibility reasons, +for the purposes of new software +the effect of passing tagged addresses to these interfaces +is unspecified. +.IP +The mode set by this call is inherited across +.BR fork (2) +and +.BR clone (2). +The mode is reset by +.BR execve (2) +to 0 +(i.e., tagged addresses not permitted in the user/kernel ABI). +.IP +For more information, see the kernel source file +.IR Documentation/arm64/tagged\-address\-abi.rst . +.IP +.B Warning: +This call is primarily intended for use by the run-time environment. +A successful +.B PR_SET_TAGGED_ADDR_CTRL +call elsewhere may crash the calling process. +The conditions for using it safely are complex and system-dependent. +Don't use it unless you know what you are doing. +.\" prctl PR_GET_TAGGED_ADDR_CTRL +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d +.TP +.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)" +Returns the current tagged address mode +for the calling thread. +.IP +Arguments +.IR arg2 ", " arg3 ", " arg4 ", and " arg5 +must all be zero. +.IP +If the arguments are invalid +or this feature is disabled or unsupported by the kernel, +the call fails with +.BR EINVAL . +In particular, if +.BR prctl ( PR_GET_TAGGED_ADDR_CTRL , +0, 0, 0, 0) +fails with +.BR EINVAL , +then this feature is definitely either unsupported, +or disabled via +.IR /proc/sys/abi/tagged_addr_disabled . +In this case, +all addresses passed to the kernel must be untagged. +.IP +Otherwise, the call returns a nonnegative value +describing the current tagged address mode, +encoded in the same way as the +.I arg2 +argument of +.BR PR_SET_TAGGED_ADDR_CTRL . +.IP +For more information, see the kernel source file +.IR Documentation/arm64/tagged\-address\-abi.rst . +.\" +.\" prctl PR_TASK_PERF_EVENTS_DISABLE +.TP +.BR PR_TASK_PERF_EVENTS_DISABLE " (since Linux 2.6.31)" +Disable all performance counters attached to the calling process, +regardless of whether the counters were created by +this process or another process. +Performance counters created by the calling process for other +processes are unaffected. +For more information on performance counters, see the Linux kernel source file +.IR tools/perf/design.txt . +.IP +Originally called +.BR PR_TASK_PERF_COUNTERS_DISABLE ; +.\" commit 1d1c7ddbfab358445a542715551301b7fc363e28 +renamed (retaining the same numerical value) +in Linux 2.6.32. +.\" +.\" prctl PR_TASK_PERF_EVENTS_ENABLE +.TP +.BR PR_TASK_PERF_EVENTS_ENABLE " (since Linux 2.6.31)" +The converse of +.BR PR_TASK_PERF_EVENTS_DISABLE ; +enable performance counters attached to the calling process. +.IP +Originally called +.BR PR_TASK_PERF_COUNTERS_ENABLE ; +.\" commit 1d1c7ddbfab358445a542715551301b7fc363e28 +renamed +.\" commit cdd6c482c9ff9c55475ee7392ec8f672eddb7be6 +in Linux 2.6.32. +.\" +.\" prctl PR_SET_THP_DISABLE +.TP +.BR PR_SET_THP_DISABLE " (since Linux 3.15)" +.\" commit a0715cc22601e8830ace98366c0c2bd8da52af52 +Set the state of the "THP disable" flag for the calling thread. +If +.I arg2 +has a nonzero value, the flag is set, otherwise it is cleared. +Setting this flag provides a method +for disabling transparent huge pages +for jobs where the code cannot be modified, and using a malloc hook with +.BR madvise (2) +is not an option (i.e., statically allocated data). +The setting of the "THP disable" flag is inherited by a child created via +.BR fork (2) +and is preserved across +.BR execve (2). +.\" prctl PR_GET_THP_DISABLE +.TP +.BR PR_GET_THP_DISABLE " (since Linux 3.15)" +Return (as the function result) the current setting of the "THP disable" +flag for the calling thread: +either 1, if the flag is set, or 0, if it is not. +.\" prctl PR_GET_TID_ADDRESS +.TP +.BR PR_GET_TID_ADDRESS " (since Linux 3.5)" +.\" commit 300f786b2683f8bb1ec0afb6e1851183a479c86d +Return the +.I clear_child_tid +address set by +.BR set_tid_address (2) +and the +.BR clone (2) +.B CLONE_CHILD_CLEARTID +flag, in the location pointed to by +.IR "(int\~**)\~arg2" . +This feature is available only if the kernel is built with the +.B CONFIG_CHECKPOINT_RESTORE +option enabled. +Note that since the +.BR prctl () +system call does not have a compat implementation for +the AMD64 x32 and MIPS n32 ABIs, +and the kernel writes out a pointer using the kernel's pointer size, +this operation expects a user-space buffer of 8 (not 4) bytes on these ABIs. +.\" prctl PR_SET_TIMERSLACK +.TP +.BR PR_SET_TIMERSLACK " (since Linux 2.6.28)" +.\" See https://lwn.net/Articles/369549/ +.\" commit 6976675d94042fbd446231d1bd8b7de71a980ada +Each thread has two associated timer slack values: +a "default" value, and a "current" value. +This operation sets the "current" timer slack value for the calling thread. +.I arg2 +is an unsigned long value, then maximum "current" value is ULONG_MAX and +the minimum "current" value is 1. +If the nanosecond value supplied in +.I arg2 +is greater than zero, then the "current" value is set to this value. +If +.I arg2 +is equal to zero, +the "current" timer slack is reset to the +thread's "default" timer slack value. +.IP +The "current" timer slack is used by the kernel to group timer expirations +for the calling thread that are close to one another; +as a consequence, timer expirations for the thread may be +up to the specified number of nanoseconds late (but will never expire early). +Grouping timer expirations can help reduce system power consumption +by minimizing CPU wake-ups. +.IP +The timer expirations affected by timer slack are those set by +.BR select (2), +.BR pselect (2), +.BR poll (2), +.BR ppoll (2), +.BR epoll_wait (2), +.BR epoll_pwait (2), +.BR clock_nanosleep (2), +.BR nanosleep (2), +and +.BR futex (2) +(and thus the library functions implemented via futexes, including +.\" List obtained by grepping for futex usage in glibc source +.BR pthread_cond_timedwait (3), +.BR pthread_mutex_timedlock (3), +.BR pthread_rwlock_timedrdlock (3), +.BR pthread_rwlock_timedwrlock (3), +and +.BR sem_timedwait (3)). +.IP +Timer slack is not applied to threads that are scheduled under +a real-time scheduling policy (see +.BR sched_setscheduler (2)). +.IP +When a new thread is created, +the two timer slack values are made the same as the "current" value +of the creating thread. +Thereafter, a thread can adjust its "current" timer slack value via +.BR PR_SET_TIMERSLACK . +The "default" value can't be changed. +The timer slack values of +.I init +(PID 1), the ancestor of all processes, +are 50,000 nanoseconds (50 microseconds). +The timer slack value is inherited by a child created via +.BR fork (2), +and is preserved across +.BR execve (2). +.IP +Since Linux 4.6, the "current" timer slack value of any process +can be examined and changed via the file +.IR /proc/ pid /timerslack_ns . +See +.BR proc (5). +.\" prctl PR_GET_TIMERSLACK +.TP +.BR PR_GET_TIMERSLACK " (since Linux 2.6.28)" +Return (as the function result) +the "current" timer slack value of the calling thread. +.\" prctl PR_SET_TIMING +.TP +.BR PR_SET_TIMING " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test4 +Set whether to use (normal, traditional) statistical process timing or +accurate timestamp-based process timing, by passing +.B PR_TIMING_STATISTICAL +.\" 0 +or +.B PR_TIMING_TIMESTAMP +.\" 1 +to \fIarg2\fP. +.B PR_TIMING_TIMESTAMP +is not currently implemented +(attempting to set this mode will yield the error +.BR EINVAL ). +.\" PR_TIMING_TIMESTAMP doesn't do anything in Linux 2.6.26-rc8, +.\" and looking at the patch history, it appears +.\" that it never did anything. +.\" prctl PR_GET_TIMING +.TP +.BR PR_GET_TIMING " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test4 +Return (as the function result) which process timing method is currently +in use. +.\" prctl PR_SET_TSC +.TP +.BR PR_SET_TSC " (since Linux 2.6.26, x86 only)" +Set the state of the flag determining whether the timestamp counter +can be read by the process. +Pass +.B PR_TSC_ENABLE +to +.I arg2 +to allow it to be read, or +.B PR_TSC_SIGSEGV +to generate a +.B SIGSEGV +when the process tries to read the timestamp counter. +.\" prctl PR_GET_TSC +.TP +.BR PR_GET_TSC " (since Linux 2.6.26, x86 only)" +Return the state of the flag determining whether the timestamp counter +can be read, +in the location pointed to by +.IR "(int\~*) arg2" . +.\" prctl PR_SET_UNALIGN +.TP +.B PR_SET_UNALIGN +(Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15; +PowerPC, since Linux 2.6.18; Alpha, since Linux 2.6.22; +.\" sh: 94ea5e449ae834af058ef005d16a8ad44fcf13d6 +.\" tile: 2f9ac29eec71a696cb0dcc5fb82c0f8d4dac28c9 +sh, since Linux 2.6.34; tile, since Linux 3.12) +Set unaligned access control bits to \fIarg2\fP. +Pass +\fBPR_UNALIGN_NOPRINT\fP to silently fix up unaligned user accesses, +or \fBPR_UNALIGN_SIGBUS\fP to generate +.B SIGBUS +on unaligned user access. +Alpha also supports an additional flag with the value +of 4 and no corresponding named constant, +which instructs kernel to not fix up +unaligned accesses (it is analogous to providing the +.B UAC_NOFIX +flag in +.B SSI_NVPAIRS +operation of the +.BR setsysinfo () +system call on Tru64). +.\" prctl PR_GET_UNALIGN +.TP +.B PR_GET_UNALIGN +(See +.B PR_SET_UNALIGN +for information on versions and architectures.) +Return unaligned access control bits, in the location pointed to by +.IR "(unsigned int\~*) arg2" . +.\" prctl PR_GET_AUXV +.TP +.BR PR_GET_AUXV " (since Linux 6.4)" +Get the auxiliary vector (auxv) into the buffer pointed to by +.IR "(void\~*) arg2" , +whose length is given by \fIarg3\fP. +If the buffer is not long enough for the full auxiliary vector, +the copy will be truncated. +Return (as the function result) +the full length of the auxiliary vector. +\fIarg4\fP and \fIarg5\fP must be 0. +.TP +.BR PR_SET_MDWE " (since Linux 6.3)" +.\" commit b507808ebce23561d4ff8c2aa1fb949fe402bc61 +Set the calling process' Memory-Deny-Write-Execute protection mask. +Once protection bits are set, +they can not be changed. +.I arg2 +must be a bit mask of: +.RS +.TP +.B PR_MDWE_REFUSE_EXEC_GAIN +New memory mapping protections can't be writable and executable. +Non-executable mappings can't become executable. +.TP +.B PR_MDWE_NO_INHERIT " (since Linux 6.6)" +.\" commit 2a87e5520554034e8c423479740f95bea4a086a0 +Do not propagate MDWE protection to child processes on +.BR fork (2). +Setting this bit requires setting +.B PR_MDWE_REFUSE_EXEC_GAIN +too. +.RE +.TP +.BR PR_GET_MDWE " (since Linux 6.3)" +.\" commit b507808ebce23561d4ff8c2aa1fb949fe402bc61 +Return (as the function result) the Memory-Deny-Write-Execute protection mask +of the calling process. +(See +.B PR_SET_MDWE +for information on the protection mask bits.) +.SH RETURN VALUE +On success, +.BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET , +.BR PR_CAPBSET_READ , +.BR PR_GET_DUMPABLE , +.BR PR_GET_FP_MODE , +.BR PR_GET_IO_FLUSHER , +.BR PR_GET_KEEPCAPS , +.BR PR_MCE_KILL_GET , +.BR PR_GET_NO_NEW_PRIVS , +.BR PR_GET_SECUREBITS , +.BR PR_GET_SPECULATION_CTRL , +.BR PR_SVE_GET_VL , +.BR PR_SVE_SET_VL , +.BR PR_GET_TAGGED_ADDR_CTRL , +.BR PR_GET_THP_DISABLE , +.BR PR_GET_TIMING , +.BR PR_GET_TIMERSLACK , +.BR PR_GET_AUXV , +and (if it returns) +.B PR_GET_SECCOMP +return the nonnegative values described above. +All other +.I op +values return 0 on success. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.I op +is +.B PR_SET_SECCOMP +and +.I arg2 +is +.BR SECCOMP_MODE_FILTER , +but the process does not have the +.B CAP_SYS_ADMIN +capability or has not set the +.I no_new_privs +attribute (see the discussion of +.B PR_SET_NO_NEW_PRIVS +above). +.TP +.B EACCES +.I op +is +.BR PR_SET_MM , +and +.I arg3 +is +.BR PR_SET_MM_EXE_FILE , +the file is not executable. +.TP +.B EBADF +.I op +is +.BR PR_SET_MM , +.I arg3 +is +.BR PR_SET_MM_EXE_FILE , +and the file descriptor passed in +.I arg4 +is not valid. +.TP +.B EBUSY +.I op +is +.BR PR_SET_MM , +.I arg3 +is +.BR PR_SET_MM_EXE_FILE , +and this the second attempt to change the +.IR /proc/ pid /exe +symbolic link, which is prohibited. +.TP +.B EFAULT +.I arg2 +is an invalid address. +.TP +.B EFAULT +.I op +is +.BR PR_SET_SECCOMP , +.I arg2 +is +.BR SECCOMP_MODE_FILTER , +the system was built with +.BR CONFIG_SECCOMP_FILTER , +and +.I arg3 +is an invalid address. +.TP +.B EFAULT +.I op +is +.B PR_SET_SYSCALL_USER_DISPATCH +and +.I arg5 +has an invalid address. +.TP +.B EINVAL +The value of +.I op +is not recognized, +or not supported on this system. +.TP +.B EINVAL +.I op +is +.B PR_MCE_KILL +or +.B PR_MCE_KILL_GET +or +.BR PR_SET_MM , +and unused +.BR prctl () +arguments were not specified as zero. +.TP +.B EINVAL +.I arg2 +is not valid value for this +.IR op . +.TP +.B EINVAL +.I op +is +.B PR_SET_SECCOMP +or +.BR PR_GET_SECCOMP , +and the kernel was not configured with +.BR CONFIG_SECCOMP . +.TP +.B EINVAL +.I op +is +.BR PR_SET_SECCOMP , +.I arg2 +is +.BR SECCOMP_MODE_FILTER , +and the kernel was not configured with +.BR CONFIG_SECCOMP_FILTER . +.TP +.B EINVAL +.I op +is +.BR PR_SET_MM , +and one of the following is true +.RS +.IP \[bu] 3 +.I arg4 +or +.I arg5 +is nonzero; +.IP \[bu] +.I arg3 +is greater than +.B TASK_SIZE +(the limit on the size of the user address space for this architecture); +.IP \[bu] +.I arg2 +is +.BR PR_SET_MM_START_CODE , +.BR PR_SET_MM_END_CODE , +.BR PR_SET_MM_START_DATA , +.BR PR_SET_MM_END_DATA , +or +.BR PR_SET_MM_START_STACK , +and the permissions of the corresponding memory area are not as required; +.IP \[bu] +.I arg2 +is +.B PR_SET_MM_START_BRK +or +.BR PR_SET_MM_BRK , +and +.I arg3 +is less than or equal to the end of the data segment +or specifies a value that would cause the +.B RLIMIT_DATA +resource limit to be exceeded. +.RE +.TP +.B EINVAL +.I op +is +.B PR_SET_PTRACER +and +.I arg2 +is not 0, +.BR PR_SET_PTRACER_ANY , +or the PID of an existing process. +.TP +.B EINVAL +.I op +is +.B PR_SET_PDEATHSIG +and +.I arg2 +is not a valid signal number. +.TP +.B EINVAL +.I op +is +.B PR_SET_DUMPABLE +and +.I arg2 +is neither +.B SUID_DUMP_DISABLE +nor +.BR SUID_DUMP_USER . +.TP +.B EINVAL +.I op +is +.B PR_SET_TIMING +and +.I arg2 +is not +.BR PR_TIMING_STATISTICAL . +.TP +.B EINVAL +.I op +is +.B PR_SET_NO_NEW_PRIVS +and +.I arg2 +is not equal to 1 +or +.IR arg3 , +.IR arg4 , +or +.I arg5 +is nonzero. +.TP +.B EINVAL +.I op +is +.B PR_GET_NO_NEW_PRIVS +and +.IR arg2 , +.IR arg3 , +.IR arg4 , +or +.I arg5 +is nonzero. +.TP +.B EINVAL +.I op +is +.B PR_SET_THP_DISABLE +and +.IR arg3 , +.IR arg4 , +or +.I arg5 +is nonzero. +.TP +.B EINVAL +.I op +is +.B PR_GET_THP_DISABLE +and +.IR arg2 , +.IR arg3 , +.IR arg4 , +or +.I arg5 +is nonzero. +.TP +.B EINVAL +.I op +is +.B PR_CAP_AMBIENT +and an unused argument +.RI ( arg4 , +.IR arg5 , +or, +in the case of +.BR PR_CAP_AMBIENT_CLEAR_ALL , +.IR arg3 ) +is nonzero; or +.I arg2 +has an invalid value; +or +.I arg2 +is +.BR PR_CAP_AMBIENT_LOWER , +.BR PR_CAP_AMBIENT_RAISE , +or +.B PR_CAP_AMBIENT_IS_SET +and +.I arg3 +does not specify a valid capability. +.TP +.B EINVAL +.I op +was +.B PR_GET_SPECULATION_CTRL +or +.B PR_SET_SPECULATION_CTRL +and unused arguments to +.BR prctl () +are not 0. +.TP +.B EINVAL +.I op +is +.B PR_PAC_RESET_KEYS +and the arguments are invalid or unsupported. +See the description of +.B PR_PAC_RESET_KEYS +above for details. +.TP +.B EINVAL +.I op +is +.B PR_SVE_SET_VL +and the arguments are invalid or unsupported, +or SVE is not available on this platform. +See the description of +.B PR_SVE_SET_VL +above for details. +.TP +.B EINVAL +.I op +is +.B PR_SVE_GET_VL +and SVE is not available on this platform. +.TP +.B EINVAL +.I op +is +.B PR_SET_SYSCALL_USER_DISPATCH +and one of the following is true: +.RS +.IP \[bu] 3 +.I arg2 +is +.B PR_SYS_DISPATCH_OFF +and the remaining arguments are not 0; +.IP \[bu] +.I arg2 +is +.B PR_SYS_DISPATCH_ON +and the memory range specified is outside the +address space of the process. +.IP \[bu] +.I arg2 +is invalid. +.RE +.TP +.B EINVAL +.I op +is +.B PR_SET_TAGGED_ADDR_CTRL +and the arguments are invalid or unsupported. +See the description of +.B PR_SET_TAGGED_ADDR_CTRL +above for details. +.TP +.B EINVAL +.I op +is +.B PR_GET_TAGGED_ADDR_CTRL +and the arguments are invalid or unsupported. +See the description of +.B PR_GET_TAGGED_ADDR_CTRL +above for details. +.TP +.B ENODEV +.I op +was +.B PR_SET_SPECULATION_CTRL +the kernel or CPU does not support the requested speculation misfeature. +.TP +.B ENXIO +.I op +was +.B PR_MPX_ENABLE_MANAGEMENT +or +.B PR_MPX_DISABLE_MANAGEMENT +and the kernel or the CPU does not support MPX management. +Check that the kernel and processor have MPX support. +.TP +.B ENXIO +.I op +was +.B PR_SET_SPECULATION_CTRL +implies that the control of the selected speculation misfeature is not possible. +See +.B PR_GET_SPECULATION_CTRL +for the bit fields to determine which option is available. +.TP +.B EOPNOTSUPP +.I op +is +.B PR_SET_FP_MODE +and +.I arg2 +has an invalid or unsupported value. +.TP +.B EPERM +.I op +is +.BR PR_SET_SECUREBITS , +and the caller does not have the +.B CAP_SETPCAP +capability, +or tried to unset a "locked" flag, +or tried to set a flag whose corresponding locked flag was set +(see +.BR capabilities (7)). +.TP +.B EPERM +.I op +is +.B PR_SET_SPECULATION_CTRL +wherein the speculation was disabled with +.B PR_SPEC_FORCE_DISABLE +and caller tried to enable it again. +.TP +.B EPERM +.I op +is +.BR PR_SET_KEEPCAPS , +and the caller's +.B SECBIT_KEEP_CAPS_LOCKED +flag is set +(see +.BR capabilities (7)). +.TP +.B EPERM +.I op +is +.BR PR_CAPBSET_DROP , +and the caller does not have the +.B CAP_SETPCAP +capability. +.TP +.B EPERM +.I op +is +.BR PR_SET_MM , +and the caller does not have the +.B CAP_SYS_RESOURCE +capability. +.TP +.B EPERM +.I op +is +.B PR_CAP_AMBIENT +and +.I arg2 +is +.BR PR_CAP_AMBIENT_RAISE , +but either the capability specified in +.I arg3 +is not present in the process's permitted and inheritable capability sets, +or the +.B PR_CAP_AMBIENT_LOWER +securebit has been set. +.TP +.B ERANGE +.I op +was +.B PR_SET_SPECULATION_CTRL +and +.I arg3 +is not +.BR PR_SPEC_ENABLE , +.BR PR_SPEC_DISABLE , +.BR PR_SPEC_FORCE_DISABLE , +nor +.BR PR_SPEC_DISABLE_NOEXEC . +.SH VERSIONS +IRIX has a +.BR prctl () +system call (also introduced in Linux 2.1.44 +as irix_prctl on the MIPS architecture), +with prototype +.P +.in +4n +.EX +.BI "ptrdiff_t prctl(int " op ", int " arg2 ", int " arg3 ); +.EE +.in +.P +and operations to get the maximum number of processes per user, +get the maximum number of processors the calling process can use, +find out whether a specified process is currently blocked, +get or set the maximum stack size, and so on. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.1.57, +glibc 2.0.6 +.SH SEE ALSO +.BR signal (2), +.BR core (5) diff --git a/man/man2/pread.2 b/man/man2/pread.2 new file mode 100644 index 0000000..e79b89c --- /dev/null +++ b/man/man2/pread.2 @@ -0,0 +1,146 @@ +.\" Copyright (C) 1999 Joseph Samuel Myers. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pread 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pread, pwrite \- read from or write to a file descriptor at a given offset +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t pread(int " fd ", void " buf [. count "], size_t " count , +.BI " off_t " offset ); +.BI "ssize_t pwrite(int " fd ", const void " buf [. count "], size_t " count , +.BI " off_t " offset ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pread (), +.BR pwrite (): +.nf + _XOPEN_SOURCE >= 500 + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +.BR pread () +reads up to +.I count +bytes from file descriptor +.I fd +at offset +.I offset +(from the start of the file) into the buffer starting at +.IR buf . +The file offset is not changed. +.P +.BR pwrite () +writes up to +.I count +bytes from the buffer starting at +.I buf +to the file descriptor +.I fd +at offset +.IR offset . +The file offset is not changed. +.P +The file referenced by +.I fd +must be capable of seeking. +.SH RETURN VALUE +On success, +.BR pread () +returns the number of bytes read +(a return of zero indicates end of file) +and +.BR pwrite () +returns the number of bytes written. +.P +Note that it is not an error for a successful call to transfer fewer bytes +than requested (see +.BR read (2) +and +.BR write (2)). +.P +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.BR pread () +can fail and set +.I errno +to any error specified for +.BR read (2) +or +.BR lseek (2). +.BR pwrite () +can fail and set +.I errno +to any error specified for +.BR write (2) +or +.BR lseek (2). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Added in Linux 2.1.60; +the entries in the i386 system call table were added in Linux 2.1.69. +C library support (including emulation using +.BR lseek (2) +on older kernels without the system calls) was added in glibc 2.1. +.SS C library/kernel differences +On Linux, the underlying system calls were renamed +in Linux 2.6: +.BR pread () +became +.BR pread64 (), +and +.BR pwrite () +became +.BR pwrite64 (). +The system call numbers remained the same. +The glibc +.BR pread () +and +.BR pwrite () +wrapper functions transparently deal with the change. +.P +On some 32-bit architectures, +the calling signature for these system calls differ, +for the reasons described in +.BR syscall (2). +.SH NOTES +The +.BR pread () +and +.BR pwrite () +system calls are especially useful in multithreaded applications. +They allow multiple threads to perform I/O on the same file descriptor +without being affected by changes to the file offset by other threads. +.SH BUGS +POSIX requires that opening a file with the +.B O_APPEND +flag should have no effect on the location at which +.BR pwrite () +writes data. +However, on Linux, if a file is opened with +.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=43178 +.BR O_APPEND , +.BR pwrite () +appends data to the end of the file, regardless of the value of +.IR offset . +.SH SEE ALSO +.BR lseek (2), +.BR read (2), +.BR readv (2), +.BR write (2) diff --git a/man/man2/pread64.2 b/man/man2/pread64.2 new file mode 100644 index 0000000..87eacb2 --- /dev/null +++ b/man/man2/pread64.2 @@ -0,0 +1 @@ +.so man2/pread.2 diff --git a/man/man2/preadv.2 b/man/man2/preadv.2 new file mode 100644 index 0000000..54e3384 --- /dev/null +++ b/man/man2/preadv.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man/man2/preadv2.2 b/man/man2/preadv2.2 new file mode 100644 index 0000000..54e3384 --- /dev/null +++ b/man/man2/preadv2.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man/man2/prlimit.2 b/man/man2/prlimit.2 new file mode 100644 index 0000000..df6d736 --- /dev/null +++ b/man/man2/prlimit.2 @@ -0,0 +1 @@ +.so man2/getrlimit.2 diff --git a/man/man2/prlimit64.2 b/man/man2/prlimit64.2 new file mode 100644 index 0000000..df6d736 --- /dev/null +++ b/man/man2/prlimit64.2 @@ -0,0 +1 @@ +.so man2/getrlimit.2 diff --git a/man/man2/process_madvise.2 b/man/man2/process_madvise.2 new file mode 100644 index 0000000..924397f --- /dev/null +++ b/man/man2/process_madvise.2 @@ -0,0 +1,200 @@ +.\" Copyright (C) 2021 Suren Baghdasaryan +.\" and Copyright (C) 2021 Minchan Kim +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Commit ecb8ac8b1f146915aa6b96449b66dd48984caacc +.\" +.TH process_madvise 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +process_madvise \- give advice about use of memory to a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t process_madvise(int " pidfd ", const struct iovec " iovec [. n ], +.BI " size_t " n ", int " advice \ +", unsigned int " flags ); +.fi +.SH DESCRIPTION +The +.BR process_madvise () +system call is used to give advice or directions to the kernel about the +address ranges of another process or of the calling process. +It provides the advice for the address ranges described by +.I iovec +and +.IR n . +The goal of such advice is to improve system or application performance. +.P +The +.I pidfd +argument is a PID file descriptor (see +.BR pidfd_open (2)) +that specifies the process to which the advice is to be applied. +.P +The pointer +.I iovec +points to an array of +.I iovec +structures, described in +.BR iovec (3type). +.P +.I n +specifies the number of elements in the array of +.I iovec +structures. +This value must be less than or equal to +.B IOV_MAX +(defined in +.I +or accessible via the call +.IR sysconf(_SC_IOV_MAX) ). +.P +The +.I advice +argument is one of the following values: +.TP +.B MADV_COLD +See +.BR madvise (2). +.TP +.B MADV_COLLAPSE +See +.BR madvise (2). +.TP +.B MADV_PAGEOUT +See +.BR madvise (2). +.TP +.B MADV_WILLNEED +See +.BR madvise (2). +.P +The +.I flags +argument is reserved for future use; currently, this argument must be +specified as 0. +.P +The +.I n +and +.I iovec +arguments are checked before applying any advice. +If +.I n +is too big, or +.I iovec +is invalid, +then an error will be returned immediately and no advice will be applied. +.P +The advice might be applied to only a part of +.I iovec +if one of its elements points to an invalid memory region in the +remote process. +No further elements will be processed beyond that point. +(See the discussion regarding partial advice in RETURN VALUE.) +.P +.\" commit 96cfe2c0fd23ea7c2368d14f769d287e7ae1082e +Starting in Linux 5.12, +permission to apply advice to another process is governed by +ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check (see +.BR ptrace (2)); +in addition, +because of the performance implications of applying the advice, +the caller must have the +.B CAP_SYS_NICE +capability +(see +.BR capabilities (7)). +.SH RETURN VALUE +On success, +.BR process_madvise () +returns the number of bytes advised. +This return value may be less than the total number of requested bytes, +if an error occurred after some +.I iovec +elements were already processed. +The caller should check the return value to determine whether a partial +advice occurred. +.P +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I pidfd +is not a valid PID file descriptor. +.TP +.B EFAULT +The memory described by +.I iovec +is outside the accessible address space of the process referred to by +.IR pidfd . +.TP +.B EINVAL +.I flags +is not 0. +.TP +.B EINVAL +The sum of the +.I iov_len +values of +.I iovec +overflows a +.I ssize_t +value. +.TP +.B EINVAL +.I n +is too large. +.TP +.B ENOMEM +Could not allocate memory for internal copies of the +.I iovec +structures. +.TP +.B EPERM +The caller does not have permission to access the address space of the process +.IR pidfd . +.TP +.B ESRCH +The target process does not exist (i.e., it has terminated and been waited on). +.P +See +.BR madvise (2) +for +.IR advice -specific +errors. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 5.10. +.\" Linux commit ecb8ac8b1f146915aa6b96449b66dd48984caacc +glibc 2.36. +.\" glibc commit d19ee3473d68ca0e794f3a8b7677a0983ae1342e +.P +Support for this system call is optional, +depending on the setting of the +.B CONFIG_ADVISE_SYSCALLS +configuration option. +.P +When this system call first appeared in Linux 5.10, +permission to apply advice to another process was entirely governed by +ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check (see +.BR ptrace (2)). +This requirement was relaxed in Linux 5.12 so that the caller didn't require +full control over the target process. +.SH SEE ALSO +.BR madvise (2), +.BR pidfd_open (2), +.BR process_vm_readv (2), +.BR process_vm_write (2) diff --git a/man/man2/process_vm_readv.2 b/man/man2/process_vm_readv.2 new file mode 100644 index 0000000..089a276 --- /dev/null +++ b/man/man2/process_vm_readv.2 @@ -0,0 +1,314 @@ +.\" Copyright (C) 2011 Christopher Yeoh +.\" and Copyright (C) 2012 Mike Frysinger +.\" and Copyright (C) 2012 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Commit fcf634098c00dd9cd247447368495f0b79be12d1 +.\" +.TH process_vm_readv 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +process_vm_readv, process_vm_writev \- +transfer data between process address spaces +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t process_vm_readv(pid_t " pid , +.BI " const struct iovec *" local_iov , +.BI " unsigned long " liovcnt , +.BI " const struct iovec *" remote_iov , +.BI " unsigned long " riovcnt , +.BI " unsigned long " flags ");" +.BI "ssize_t process_vm_writev(pid_t " pid , +.BI " const struct iovec *" local_iov , +.BI " unsigned long " liovcnt , +.BI " const struct iovec *" remote_iov , +.BI " unsigned long " riovcnt , +.BI " unsigned long " flags ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR process_vm_readv (), +.BR process_vm_writev (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +These system calls transfer data between the address space +of the calling process ("the local process") and the process identified by +.I pid +("the remote process"). +The data moves directly between the address spaces of the two processes, +without passing through kernel space. +.P +The +.BR process_vm_readv () +system call transfers data from the remote process to the local process. +The data to be transferred is identified by +.I remote_iov +and +.IR riovcnt : +.I remote_iov +is a pointer to an array describing address ranges in the process +.IR pid , +and +.I riovcnt +specifies the number of elements in +.IR remote_iov . +The data is transferred to the locations specified by +.I local_iov +and +.IR liovcnt : +.I local_iov +is a pointer to an array describing address ranges in the calling process, +and +.I liovcnt +specifies the number of elements in +.IR local_iov . +.P +The +.BR process_vm_writev () +system call is the converse of +.BR process_vm_readv ()\[em]it +transfers data from the local process to the remote process. +Other than the direction of the transfer, the arguments +.IR liovcnt , +.IR local_iov , +.IR riovcnt , +and +.I remote_iov +have the same meaning as for +.BR process_vm_readv (). +.P +The +.I local_iov +and +.I remote_iov +arguments point to an array of +.I iovec +structures, described in +.BR iovec (3type). +.P +Buffers are processed in array order. +This means that +.BR process_vm_readv () +completely fills +.I local_iov[0] +before proceeding to +.IR local_iov[1] , +and so on. +Likewise, +.I remote_iov[0] +is completely read before proceeding to +.IR remote_iov[1] , +and so on. +.P +Similarly, +.BR process_vm_writev () +writes out the entire contents of +.I local_iov[0] +before proceeding to +.IR local_iov[1] , +and it completely fills +.I remote_iov[0] +before proceeding to +.IR remote_iov[1] . +.P +The lengths of +.I remote_iov[i].iov_len +and +.I local_iov[i].iov_len +do not have to be the same. +Thus, it is possible to split a single local buffer +into multiple remote buffers, or vice versa. +.P +The +.I flags +argument is currently unused and must be set to 0. +.P +The values specified in the +.I liovcnt +and +.I riovcnt +arguments must be less than or equal to +.B IOV_MAX +(defined in +.I +or accessible via the call +.IR sysconf(_SC_IOV_MAX) ). +.\" In time, glibc might provide a wrapper that works around this limit, +.\" as is done for readv()/writev() +.P +The count arguments and +.I local_iov +are checked before doing any transfers. +If the counts are too big, or +.I local_iov +is invalid, +or the addresses refer to regions that are inaccessible to the local process, +none of the vectors will be processed +and an error will be returned immediately. +.P +Note, however, that these system calls do not check the memory regions +in the remote process until just before doing the read/write. +Consequently, a partial read/write (see RETURN VALUE) +may result if one of the +.I remote_iov +elements points to an invalid memory region in the remote process. +No further reads/writes will be attempted beyond that point. +Keep this in mind when attempting to read data of unknown length +(such as C strings that are null-terminated) from a remote process, +by avoiding spanning memory pages (typically 4\ KiB) in a single remote +.I iovec +element. +(Instead, split the remote read into two +.I remote_iov +elements and have them merge back into a single write +.I local_iov +entry. +The first read entry goes up to the page boundary, +while the second starts on the next page boundary.) +.P +Permission to read from or write to another process +is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_REALCREDS +check; see +.BR ptrace (2). +.SH RETURN VALUE +On success, +.BR process_vm_readv () +returns the number of bytes read and +.BR process_vm_writev () +returns the number of bytes written. +This return value may be less than the total number of requested bytes, +if a partial read/write occurred. +(Partial transfers apply at the granularity of +.I iovec +elements. +These system calls won't perform a partial transfer that splits a single +.I iovec +element.) +The caller should check the return value to determine whether +a partial read/write occurred. +.P +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +The memory described by +.I local_iov +is outside the caller's accessible address space. +.TP +.B EFAULT +The memory described by +.I remote_iov +is outside the accessible address space of the process +.IR pid . +.TP +.B EINVAL +The sum of the +.I iov_len +values of either +.I local_iov +or +.I remote_iov +overflows a +.I ssize_t +value. +.TP +.B EINVAL +.I flags +is not 0. +.TP +.B EINVAL +.I liovcnt +or +.I riovcnt +is too large. +.TP +.B ENOMEM +Could not allocate memory for internal copies of the +.I iovec +structures. +.TP +.B EPERM +The caller does not have permission to access the address space of the process +.IR pid . +.TP +.B ESRCH +No process with ID +.I pid +exists. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.2, +glibc 2.15. +.SH NOTES +The data transfers performed by +.BR process_vm_readv () +and +.BR process_vm_writev () +are not guaranteed to be atomic in any way. +.P +These system calls were designed to permit fast message passing +by allowing messages to be exchanged with a single copy operation +(rather than the double copy that would be required +when using, for example, shared memory or pipes). +.\" Original user is MPI, http://www.mcs.anl.gov/research/projects/mpi/ +.\" See also some benchmarks at http://lwn.net/Articles/405284/ +.\" and http://marc.info/?l=linux-mm&m=130105930902915&w=2 +.SH EXAMPLES +The following code sample demonstrates the use of +.BR process_vm_readv (). +It reads 20 bytes at the address 0x10000 from the process with PID 10 +and writes the first 10 bytes into +.I buf1 +and the second 10 bytes into +.IR buf2 . +.P +.\" SRC BEGIN (process_vm_readv.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +\& +int +main(void) +{ + char buf1[10]; + char buf2[10]; + pid_t pid = 10; /* PID of remote process */ + ssize_t nread; + struct iovec local[2]; + struct iovec remote[1]; +\& + local[0].iov_base = buf1; + local[0].iov_len = 10; + local[1].iov_base = buf2; + local[1].iov_len = 10; + remote[0].iov_base = (void *) 0x10000; + remote[0].iov_len = 20; +\& + nread = process_vm_readv(pid, local, 2, remote, 1, 0); + if (nread != 20) + exit(EXIT_FAILURE); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR readv (2), +.BR writev (2) diff --git a/man/man2/process_vm_writev.2 b/man/man2/process_vm_writev.2 new file mode 100644 index 0000000..7b198a9 --- /dev/null +++ b/man/man2/process_vm_writev.2 @@ -0,0 +1 @@ +.so man2/process_vm_readv.2 diff --git a/man/man2/prof.2 b/man/man2/prof.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/prof.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/pselect.2 b/man/man2/pselect.2 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man2/pselect.2 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man2/pselect6.2 b/man/man2/pselect6.2 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man2/pselect6.2 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man2/ptrace.2 b/man/man2/ptrace.2 new file mode 100644 index 0000000..7ae2ad5 --- /dev/null +++ b/man/man2/ptrace.2 @@ -0,0 +1,2986 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" and changes Copyright (C) 1999 Mike Coleman (mkc@acm.org) +.\" -- major revision to fully document ptrace semantics per recent Linux +.\" kernel (2.2.10) and glibc (2.1.2) +.\" Sun Nov 7 03:18:35 CST 1999 +.\" +.\" and Copyright (c) 2011, Denys Vlasenko +.\" and Copyright (c) 2015, 2016, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Fri Jul 23 23:47:18 1993 by Rik Faith +.\" Modified Fri Jan 31 16:46:30 1997 by Eric S. Raymond +.\" Modified Thu Oct 7 17:28:49 1999 by Andries Brouwer +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.\" 2006-03-24, Chuck Ebbert <76306.1226@compuserve.com> +.\" Added PTRACE_SETOPTIONS, PTRACE_GETEVENTMSG, PTRACE_GETSIGINFO, +.\" PTRACE_SETSIGINFO, PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP +.\" (Thanks to Blaisorblade, Daniel Jacobowitz and others who helped.) +.\" 2011-09, major update by Denys Vlasenko +.\" 2015-01, Kees Cook +.\" Added PTRACE_O_TRACESECCOMP, PTRACE_EVENT_SECCOMP +.\" +.\" FIXME The following are undocumented: +.\" +.\" PTRACE_GETWMMXREGS +.\" PTRACE_SETWMMXREGS +.\" ARM +.\" Linux 2.6.12 +.\" +.\" PTRACE_SET_SYSCALL +.\" ARM and ARM64 +.\" Linux 2.6.16 +.\" commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f +.\" Author: Nicolas Pitre +.\" Date: Sat Jan 14 19:30:04 2006 +0000 +.\" +.\" PTRACE_GETCRUNCHREGS +.\" PTRACE_SETCRUNCHREGS +.\" ARM +.\" Linux 2.6.18 +.\" commit 3bec6ded282b331552587267d67a06ed7fd95ddd +.\" Author: Lennert Buytenhek +.\" Date: Tue Jun 27 22:56:18 2006 +0100 +.\" +.\" PTRACE_GETVFPREGS +.\" PTRACE_SETVFPREGS +.\" ARM and ARM64 +.\" Linux 2.6.30 +.\" commit 3d1228ead618b88e8606015cbabc49019981805d +.\" Author: Catalin Marinas +.\" Date: Wed Feb 11 13:12:56 2009 +0100 +.\" +.\" PTRACE_GETHBPREGS +.\" PTRACE_SETHBPREGS +.\" ARM and ARM64 +.\" Linux 2.6.37 +.\" commit 864232fa1a2f8dfe003438ef0851a56722740f3e +.\" Author: Will Deacon +.\" Date: Fri Sep 3 10:42:55 2010 +0100 +.\" +.\" PTRACE_SINGLEBLOCK +.\" Since at least Linux 2.4.0 on various architectures +.\" Since Linux 2.6.25 on x86 (and others?) +.\" commit 5b88abbf770a0e1975c668743100f42934f385e8 +.\" Author: Roland McGrath +.\" Date: Wed Jan 30 13:30:53 2008 +0100 +.\" ptrace: generic PTRACE_SINGLEBLOCK +.\" +.\" PTRACE_GETFPXREGS +.\" PTRACE_SETFPXREGS +.\" Since at least Linux 2.4.0 on various architectures +.\" +.\" PTRACE_GETFDPIC +.\" PTRACE_GETFDPIC_EXEC +.\" PTRACE_GETFDPIC_INTERP +.\" blackfin, c6x, frv, sh +.\" First appearance in Linux 2.6.11 on frv +.\" +.\" and others that can be found in the arch/*/include/uapi/asm/ptrace files +.\" +.TH ptrace 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ptrace \- process trace +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long ptrace(enum __ptrace_request " op ", pid_t " pid , +.BI " void *" addr ", void *" data ); +.fi +.SH DESCRIPTION +The +.BR ptrace () +system call provides a means by which one process (the "tracer") +may observe and control the execution of another process (the "tracee"), +and examine and change the tracee's memory and registers. +It is primarily used to implement breakpoint debugging and system +call tracing. +.P +A tracee first needs to be attached to the tracer. +Attachment and subsequent commands are per thread: +in a multithreaded process, +every thread can be individually attached to a +(potentially different) tracer, +or left not attached and thus not debugged. +Therefore, "tracee" always means "(one) thread", +never "a (possibly multithreaded) process". +Ptrace commands are always sent to +a specific tracee using a call of the form +.P +.in +4n +.EX +ptrace(PTRACE_foo, pid, ...) +.EE +.in +.P +where +.I pid +is the thread ID of the corresponding Linux thread. +.P +(Note that in this page, a "multithreaded process" +means a thread group consisting of threads created using the +.BR clone (2) +.B CLONE_THREAD +flag.) +.P +A process can initiate a trace by calling +.BR fork (2) +and having the resulting child do a +.BR PTRACE_TRACEME , +followed (typically) by an +.BR execve (2). +Alternatively, one process may commence tracing another process using +.B PTRACE_ATTACH +or +.BR PTRACE_SEIZE . +.P +While being traced, the tracee will stop each time a signal is delivered, +even if the signal is being ignored. +(An exception is +.BR SIGKILL , +which has its usual effect.) +The tracer will be notified at its next call to +.BR waitpid (2) +(or one of the related "wait" system calls); that call will return a +.I status +value containing information that indicates +the cause of the stop in the tracee. +While the tracee is stopped, +the tracer can use various ptrace operations to inspect and modify the tracee. +The tracer then causes the tracee to continue, +optionally ignoring the delivered signal +(or even delivering a different signal instead). +.P +If the +.B PTRACE_O_TRACEEXEC +option is not in effect, all successful calls to +.BR execve (2) +by the traced process will cause it to be sent a +.B SIGTRAP +signal, +giving the parent a chance to gain control before the new program +begins execution. +.P +When the tracer is finished tracing, it can cause the tracee to continue +executing in a normal, untraced mode via +.BR PTRACE_DETACH . +.P +The value of +.I op +determines the operation to be performed: +.TP +.B PTRACE_TRACEME +Indicate that this process is to be traced by its parent. +A process probably shouldn't make this operation if its parent +isn't expecting to trace it. +.RI ( pid , +.IR addr , +and +.I data +are ignored.) +.IP +The +.B PTRACE_TRACEME +operation is used only by the tracee; +the remaining operations are used only by the tracer. +In the following operations, +.I pid +specifies the thread ID of the tracee to be acted on. +For operations other than +.BR PTRACE_ATTACH , +.BR PTRACE_SEIZE , +.BR PTRACE_INTERRUPT , +and +.BR PTRACE_KILL , +the tracee must be stopped. +.TP +.B PTRACE_PEEKTEXT +.TQ +.B PTRACE_PEEKDATA +Read a word at the address +.I addr +in the tracee's memory, returning the word as the result of the +.BR ptrace () +call. +Linux does not have separate text and data address spaces, +so these two operations are currently equivalent. +.RI ( data +is ignored; but see NOTES.) +.TP +.B PTRACE_PEEKUSER +.\" PTRACE_PEEKUSR in kernel source, but glibc uses PTRACE_PEEKUSER, +.\" and that is the name that seems common on other systems. +Read a word at offset +.I addr +in the tracee's USER area, +which holds the registers and other information about the process +(see +.IR ). +The word is returned as the result of the +.BR ptrace () +call. +Typically, the offset must be word-aligned, though this might vary by +architecture. +See NOTES. +.RI ( data +is ignored; but see NOTES.) +.TP +.B PTRACE_POKETEXT +.TQ +.B PTRACE_POKEDATA +Copy the word +.I data +to the address +.I addr +in the tracee's memory. +As for +.B PTRACE_PEEKTEXT +and +.BR PTRACE_PEEKDATA , +these two operations are currently equivalent. +.TP +.B PTRACE_POKEUSER +.\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER, +.\" and that is the name that seems common on other systems. +Copy the word +.I data +to offset +.I addr +in the tracee's USER area. +As for +.BR PTRACE_PEEKUSER , +the offset must typically be word-aligned. +In order to maintain the integrity of the kernel, +some modifications to the USER area are disallowed. +.\" FIXME In the preceding sentence, which modifications are disallowed, +.\" and when they are disallowed, how does user space discover that fact? +.TP +.B PTRACE_GETREGS +.TQ +.B PTRACE_GETFPREGS +Copy the tracee's general-purpose or floating-point registers, +respectively, to the address +.I data +in the tracer. +See +.I +for information on the format of this data. +.RI ( addr +is ignored.) +Note that SPARC systems have the meaning of +.I data +and +.I addr +reversed; that is, +.I data +is ignored and the registers are copied to the address +.IR addr . +.B PTRACE_GETREGS +and +.B PTRACE_GETFPREGS +are not present on all architectures. +.TP +.BR PTRACE_GETREGSET " (since Linux 2.6.34)" +Read the tracee's registers. +.I addr +specifies, in an architecture-dependent way, the type of registers to be read. +.B NT_PRSTATUS +(with numerical value 1) +usually results in reading of general-purpose registers. +If the CPU has, for example, +floating-point and/or vector registers, they can be retrieved by setting +.I addr +to the corresponding +.B NT_foo +constant. +.I data +points to a +.BR "struct iovec" , +which describes the destination buffer's location and length. +On return, the kernel modifies +.B iov.len +to indicate the actual number of bytes returned. +.TP +.B PTRACE_SETREGS +.TQ +.B PTRACE_SETFPREGS +Modify the tracee's general-purpose or floating-point registers, +respectively, from the address +.I data +in the tracer. +As for +.BR PTRACE_POKEUSER , +some general-purpose register modifications may be disallowed. +.\" FIXME . In the preceding sentence, which modifications are disallowed, +.\" and when they are disallowed, how does user space discover that fact? +.RI ( addr +is ignored.) +Note that SPARC systems have the meaning of +.I data +and +.I addr +reversed; that is, +.I data +is ignored and the registers are copied from the address +.IR addr . +.B PTRACE_SETREGS +and +.B PTRACE_SETFPREGS +are not present on all architectures. +.TP +.BR PTRACE_SETREGSET " (since Linux 2.6.34)" +Modify the tracee's registers. +The meaning of +.I addr +and +.I data +is analogous to +.BR PTRACE_GETREGSET . +.TP +.BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)" +Retrieve information about the signal that caused the stop. +Copy a +.I siginfo_t +structure (see +.BR sigaction (2)) +from the tracee to the address +.I data +in the tracer. +.RI ( addr +is ignored.) +.TP +.BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)" +Set signal information: +copy a +.I siginfo_t +structure from the address +.I data +in the tracer to the tracee. +This will affect only signals that would normally be delivered to +the tracee and were caught by the tracer. +It may be difficult to tell +these normal signals from synthetic signals generated by +.BR ptrace () +itself. +.RI ( addr +is ignored.) +.TP +.BR PTRACE_PEEKSIGINFO " (since Linux 3.10)" +.\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4 +Retrieve +.I siginfo_t +structures without removing signals from a queue. +.I addr +points to a +.I ptrace_peeksiginfo_args +structure that specifies the ordinal position from which +copying of signals should start, +and the number of signals to copy. +.I siginfo_t +structures are copied into the buffer pointed to by +.IR data . +The return value contains the number of copied signals (zero indicates +that there is no signal corresponding to the specified ordinal position). +Within the returned +.I siginfo +structures, +the +.I si_code +field includes information +.RB ( __SI_CHLD , +.BR __SI_FAULT , +etc.) that are not otherwise exposed to user space. +.P +.in +4n +.EX +struct ptrace_peeksiginfo_args { + u64 off; /* Ordinal position in queue at which + to start copying signals */ + u32 flags; /* PTRACE_PEEKSIGINFO_SHARED or 0 */ + s32 nr; /* Number of signals to copy */ +}; +.EE +.in +.IP +Currently, there is only one flag, +.BR PTRACE_PEEKSIGINFO_SHARED , +for dumping signals from the process-wide signal queue. +If this flag is not set, +signals are read from the per-thread queue of the specified thread. +.in +.TP +.BR PTRACE_GETSIGMASK " (since Linux 3.11)" +.\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1 +Place a copy of the mask of blocked signals (see +.BR sigprocmask (2)) +in the buffer pointed to by +.IR data , +which should be a pointer to a buffer of type +.IR sigset_t . +The +.I addr +argument contains the size of the buffer pointed to by +.I data +(i.e., +.IR sizeof(sigset_t) ). +.TP +.BR PTRACE_SETSIGMASK " (since Linux 3.11)" +Change the mask of blocked signals (see +.BR sigprocmask (2)) +to the value specified in the buffer pointed to by +.IR data , +which should be a pointer to a buffer of type +.IR sigset_t . +The +.I addr +argument contains the size of the buffer pointed to by +.I data +(i.e., +.IR sizeof(sigset_t) ). +.TP +.BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)" +Set ptrace options from +.IR data . +.RI ( addr +is ignored.) +.I data +is interpreted as a bit mask of options, +which are specified by the following flags: +.RS +.TP +.BR PTRACE_O_EXITKILL " (since Linux 3.8)" +.\" commit 992fb6e170639b0849bace8e49bf31bd37c4123 +Send a +.B SIGKILL +signal to the tracee if the tracer exits. +This option is useful for ptrace jailers that +want to ensure that tracees can never escape the tracer's control. +.TP +.BR PTRACE_O_TRACECLONE " (since Linux 2.5.46)" +Stop the tracee at the next +.BR clone (2) +and automatically start tracing the newly cloned process, +which will start with a +.BR SIGSTOP , +or +.B PTRACE_EVENT_STOP +if +.B PTRACE_SEIZE +was used. +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_CLONE<<8)) +.fi +.IP +The PID of the new process can be retrieved with +.BR PTRACE_GETEVENTMSG . +.IP +This option may not catch +.BR clone (2) +calls in all cases. +If the tracee calls +.BR clone (2) +with the +.B CLONE_VFORK +flag, +.B PTRACE_EVENT_VFORK +will be delivered instead +if +.B PTRACE_O_TRACEVFORK +is set; otherwise if the tracee calls +.BR clone (2) +with the exit signal set to +.BR SIGCHLD , +.B PTRACE_EVENT_FORK +will be delivered if +.B PTRACE_O_TRACEFORK +is set. +.TP +.BR PTRACE_O_TRACEEXEC " (since Linux 2.5.46)" +Stop the tracee at the next +.BR execve (2). +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_EXEC<<8)) +.fi +.IP +If the execing thread is not a thread group leader, +the thread ID is reset to thread group leader's ID before this stop. +Since Linux 3.0, the former thread ID can be retrieved with +.BR PTRACE_GETEVENTMSG . +.TP +.BR PTRACE_O_TRACEEXIT " (since Linux 2.5.60)" +Stop the tracee at exit. +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_EXIT<<8)) +.fi +.IP +The tracee's exit status can be retrieved with +.BR PTRACE_GETEVENTMSG . +.IP +The tracee is stopped early during process exit, +when registers are still available, +allowing the tracer to see where the exit occurred, +whereas the normal exit notification is done after the process +is finished exiting. +Even though context is available, +the tracer cannot prevent the exit from happening at this point. +.TP +.BR PTRACE_O_TRACEFORK " (since Linux 2.5.46)" +Stop the tracee at the next +.BR fork (2) +and automatically start tracing the newly forked process, +which will start with a +.BR SIGSTOP , +or +.B PTRACE_EVENT_STOP +if +.B PTRACE_SEIZE +was used. +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_FORK<<8)) +.fi +.IP +The PID of the new process can be retrieved with +.BR PTRACE_GETEVENTMSG . +.TP +.BR PTRACE_O_TRACESYSGOOD " (since Linux 2.4.6)" +When delivering system call traps, set bit 7 in the signal number +(i.e., deliver +.IR "SIGTRAP|0x80" ). +This makes it easy for the tracer to distinguish +normal traps from those caused by a system call. +.TP +.BR PTRACE_O_TRACEVFORK " (since Linux 2.5.46)" +Stop the tracee at the next +.BR vfork (2) +and automatically start tracing the newly vforked process, +which will start with a +.BR SIGSTOP , +or +.B PTRACE_EVENT_STOP +if +.B PTRACE_SEIZE +was used. +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK<<8)) +.fi +.IP +The PID of the new process can be retrieved with +.BR PTRACE_GETEVENTMSG . +.TP +.BR PTRACE_O_TRACEVFORKDONE " (since Linux 2.5.60)" +Stop the tracee at the completion of the next +.BR vfork (2). +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_VFORK_DONE<<8)) +.fi +.IP +The PID of the new process can (since Linux 2.6.18) be retrieved with +.BR PTRACE_GETEVENTMSG . +.TP +.BR PTRACE_O_TRACESECCOMP " (since Linux 3.5)" +Stop the tracee when a +.BR seccomp (2) +.B SECCOMP_RET_TRACE +rule is triggered. +A +.BR waitpid (2) +by the tracer will return a +.I status +value such that +.IP +.nf + status>>8 == (SIGTRAP | (PTRACE_EVENT_SECCOMP<<8)) +.fi +.IP +While this triggers a +.B PTRACE_EVENT +stop, it is similar to a syscall-enter-stop. +For details, see the note on +.B PTRACE_EVENT_SECCOMP +below. +The seccomp event message data (from the +.B SECCOMP_RET_DATA +portion of the seccomp filter rule) can be retrieved with +.BR PTRACE_GETEVENTMSG . +.TP +.BR PTRACE_O_SUSPEND_SECCOMP " (since Linux 4.3)" +.\" commit 13c4a90119d28cfcb6b5bdd820c233b86c2b0237 +Suspend the tracee's seccomp protections. +This applies regardless of mode, and +can be used when the tracee has not yet installed seccomp filters. +That is, a valid use case is to suspend a tracee's seccomp protections +before they are installed by the tracee, +let the tracee install the filters, +and then clear this flag when the filters should be resumed. +Setting this option requires that the tracer have the +.B CAP_SYS_ADMIN +capability, +not have any seccomp protections installed, and not have +.B PTRACE_O_SUSPEND_SECCOMP +set on itself. +.RE +.TP +.BR PTRACE_GETEVENTMSG " (since Linux 2.5.46)" +Retrieve a message (as an +.IR "unsigned long" ) +about the ptrace event +that just happened, placing it at the address +.I data +in the tracer. +For +.BR PTRACE_EVENT_EXIT , +this is the tracee's exit status. +For +.BR PTRACE_EVENT_FORK , +.BR PTRACE_EVENT_VFORK , +.BR PTRACE_EVENT_VFORK_DONE , +and +.BR PTRACE_EVENT_CLONE , +this is the PID of the new process. +For +.BR PTRACE_EVENT_SECCOMP , +this is the +.BR seccomp (2) +filter's +.B SECCOMP_RET_DATA +associated with the triggered rule. +.RI ( addr +is ignored.) +.TP +.B PTRACE_CONT +Restart the stopped tracee process. +If +.I data +is nonzero, +it is interpreted as the number of a signal to be delivered to the tracee; +otherwise, no signal is delivered. +Thus, for example, the tracer can control +whether a signal sent to the tracee is delivered or not. +.RI ( addr +is ignored.) +.TP +.B PTRACE_SYSCALL +.TQ +.B PTRACE_SINGLESTEP +Restart the stopped tracee as for +.BR PTRACE_CONT , +but arrange for the tracee to be stopped at +the next entry to or exit from a system call, +or after execution of a single instruction, respectively. +(The tracee will also, as usual, be stopped upon receipt of a signal.) +From the tracer's perspective, the tracee will appear to have been +stopped by receipt of a +.BR SIGTRAP . +So, for +.BR PTRACE_SYSCALL , +for example, the idea is to inspect +the arguments to the system call at the first stop, +then do another +.B PTRACE_SYSCALL +and inspect the return value of the system call at the second stop. +The +.I data +argument is treated as for +.BR PTRACE_CONT . +.RI ( addr +is ignored.) +.TP +.BR PTRACE_SET_SYSCALL " (since Linux 2.6.16)" +.\" commit 3f471126ee53feb5e9b210ea2f525ed3bb9b7a7f +When in syscall-enter-stop, +change the number of the system call that is about to +be executed to the number specified in the +.I data +argument. +The +.I addr +argument is ignored. +This operation is currently +.\" As of 4.19-rc2 +supported only on arm (and arm64, though only for backwards compatibility), +.\" commit 27aa55c5e5123fa8b8ad0156559d34d7edff58ca +but most other architectures have other means of accomplishing this +(usually by changing the register that the userland code passed the +system call number in). +.\" see change_syscall in tools/testing/selftests/seccomp/seccomp_bpf.c +.\" and also strace's linux/*/set_scno.c files. +.TP +.B PTRACE_SYSEMU +.TQ +.BR PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)" +For +.BR PTRACE_SYSEMU , +continue and stop on entry to the next system call, +which will not be executed. +See the documentation on syscall-stops below. +For +.BR PTRACE_SYSEMU_SINGLESTEP , +do the same but also singlestep if not a system call. +This call is used by programs like +User Mode Linux that want to emulate all the tracee's system calls. +The +.I data +argument is treated as for +.BR PTRACE_CONT . +The +.I addr +argument is ignored. +These operations are currently +.\" As at 3.7 +supported only on x86. +.TP +.BR PTRACE_LISTEN " (since Linux 3.4)" +Restart the stopped tracee, but prevent it from executing. +The resulting state of the tracee is similar to a process which +has been stopped by a +.B SIGSTOP +(or other stopping signal). +See the "group-stop" subsection for additional information. +.B PTRACE_LISTEN +works only on tracees attached by +.BR PTRACE_SEIZE . +.TP +.B PTRACE_KILL +Send the tracee a +.B SIGKILL +to terminate it. +.RI ( addr +and +.I data +are ignored.) +.IP +.I This operation is deprecated; do not use it! +Instead, send a +.B SIGKILL +directly using +.BR kill (2) +or +.BR tgkill (2). +The problem with +.B PTRACE_KILL +is that it requires the tracee to be in signal-delivery-stop, +otherwise it may not work +(i.e., may complete successfully but won't kill the tracee). +By contrast, sending a +.B SIGKILL +directly has no such limitation. +.\" [Note from Denys Vlasenko: +.\" deprecation suggested by Oleg Nesterov. He prefers to deprecate it +.\" instead of describing (and needing to support) PTRACE_KILL's quirks.] +.TP +.BR PTRACE_INTERRUPT " (since Linux 3.4)" +Stop a tracee. +If the tracee is running or sleeping in kernel space and +.B PTRACE_SYSCALL +is in effect, +the system call is interrupted and syscall-exit-stop is reported. +(The interrupted system call is restarted when the tracee is restarted.) +If the tracee was already stopped by a signal and +.B PTRACE_LISTEN +was sent to it, +the tracee stops with +.B PTRACE_EVENT_STOP +and +.I WSTOPSIG(status) +returns the stop signal. +If any other ptrace-stop is generated at the same time (for example, +if a signal is sent to the tracee), this ptrace-stop happens. +If none of the above applies (for example, if the tracee is running in user +space), it stops with +.B PTRACE_EVENT_STOP +with +.I WSTOPSIG(status) +== +.BR SIGTRAP . +.B PTRACE_INTERRUPT +only works on tracees attached by +.BR PTRACE_SEIZE . +.TP +.B PTRACE_ATTACH +Attach to the process specified in +.IR pid , +making it a tracee of the calling process. +.\" No longer true (removed by Denys Vlasenko, 2011, who remarks: +.\" "I think it isn't true in non-ancient 2.4 and in Linux 2.6/3.x. +.\" Basically, it's not true for any Linux in practical use. +.\" ; the behavior of the tracee is as if it had done a +.\" .BR PTRACE_TRACEME . +.\" The calling process actually becomes the parent of the tracee +.\" process for most purposes (e.g., it will receive +.\" notification of tracee events and appears in +.\" .BR ps (1) +.\" output as the tracee's parent), but a +.\" .BR getppid (2) +.\" by the tracee will still return the PID of the original parent. +The tracee is sent a +.BR SIGSTOP , +but will not necessarily have stopped +by the completion of this call; use +.BR waitpid (2) +to wait for the tracee to stop. +See the "Attaching and detaching" subsection for additional information. +.RI ( addr +and +.I data +are ignored.) +.IP +Permission to perform a +.B PTRACE_ATTACH +is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_REALCREDS +check; see below. +.TP +.BR PTRACE_SEIZE " (since Linux 3.4)" +.\" +.\" Noted by Dmitry Levin: +.\" +.\" PTRACE_SEIZE was introduced by commit v3.1-rc1~308^2~28, but +.\" it had to be used along with a temporary flag PTRACE_SEIZE_DEVEL, +.\" which was removed later by commit v3.4-rc1~109^2~20. +.\" +.\" That is, [before] v3.4 we had a test mode of PTRACE_SEIZE API, +.\" which was not compatible with the current PTRACE_SEIZE API introduced +.\" in Linux 3.4. +.\" +Attach to the process specified in +.IR pid , +making it a tracee of the calling process. +Unlike +.BR PTRACE_ATTACH , +.B PTRACE_SEIZE +does not stop the process. +Group-stops are reported as +.B PTRACE_EVENT_STOP +and +.I WSTOPSIG(status) +returns the stop signal. +Automatically attached children stop with +.B PTRACE_EVENT_STOP +and +.I WSTOPSIG(status) +returns +.B SIGTRAP +instead of having +.B SIGSTOP +signal delivered to them. +.BR execve (2) +does not deliver an extra +.BR SIGTRAP . +Only a +.BR PTRACE_SEIZE d +process can accept +.B PTRACE_INTERRUPT +and +.B PTRACE_LISTEN +commands. +The "seized" behavior just described is inherited by +children that are automatically attached using +.BR PTRACE_O_TRACEFORK , +.BR PTRACE_O_TRACEVFORK , +and +.BR PTRACE_O_TRACECLONE . +.I addr +must be zero. +.I data +contains a bit mask of ptrace options to activate immediately. +.IP +Permission to perform a +.B PTRACE_SEIZE +is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_REALCREDS +check; see below. +.\" +.TP +.BR PTRACE_SECCOMP_GET_FILTER " (since Linux 4.4)" +.\" commit f8e529ed941ba2bbcbf310b575d968159ce7e895 +This operation allows the tracer to dump the tracee's +classic BPF filters. +.IP +.I addr +is an integer specifying the index of the filter to be dumped. +The most recently installed filter has the index 0. +If +.I addr +is greater than the number of installed filters, +the operation fails with the error +.BR ENOENT . +.IP +.I data +is either a pointer to a +.I struct sock_filter +array that is large enough to store the BPF program, +or NULL if the program is not to be stored. +.IP +Upon success, +the return value is the number of instructions in the BPF program. +If +.I data +was NULL, then this return value can be used to correctly size the +.I struct sock_filter +array passed in a subsequent call. +.IP +This operation fails with the error +.B EACCES +if the caller does not have the +.B CAP_SYS_ADMIN +capability or if the caller is in strict or filter seccomp mode. +If the filter referred to by +.I addr +is not a classic BPF filter, the operation fails with the error +.BR EMEDIUMTYPE . +.IP +This operation is available if the kernel was configured with both the +.B CONFIG_SECCOMP_FILTER +and the +.B CONFIG_CHECKPOINT_RESTORE +options. +.TP +.B PTRACE_DETACH +Restart the stopped tracee as for +.BR PTRACE_CONT , +but first detach from it. +Under Linux, a tracee can be detached in this way regardless +of which method was used to initiate tracing. +.RI ( addr +is ignored.) +.\" +.TP +.BR PTRACE_GET_THREAD_AREA " (since Linux 2.6.0)" +This operation performs a similar task to +.BR get_thread_area (2). +It reads the TLS entry in the GDT whose index is given in +.IR addr , +placing a copy of the entry into the +.I struct user_desc +pointed to by +.IR data . +(By contrast with +.BR get_thread_area (2), +the +.I entry_number +of the +.I struct user_desc +is ignored.) +.TP +.BR PTRACE_SET_THREAD_AREA " (since Linux 2.6.0)" +This operation performs a similar task to +.BR set_thread_area (2). +It sets the TLS entry in the GDT whose index is given in +.IR addr , +assigning it the data supplied in the +.I struct user_desc +pointed to by +.IR data . +(By contrast with +.BR set_thread_area (2), +the +.I entry_number +of the +.I struct user_desc +is ignored; in other words, +this ptrace operation can't be used to allocate a free TLS entry.) +.TP +.BR PTRACE_GET_SYSCALL_INFO " (since Linux 5.3)" +.\" commit 201766a20e30f982ccfe36bebfad9602c3ff574a +Retrieve information about the system call that caused the stop. +The information is placed into the buffer pointed by the +.I data +argument, which should be a pointer to a buffer of type +.IR "struct ptrace_syscall_info" . +The +.I addr +argument contains the size of the buffer pointed to +by the +.I data +argument (i.e., +.IR "sizeof(struct ptrace_syscall_info)" ). +The return value contains the number of bytes available +to be written by the kernel. +If the size of the data to be written by the kernel exceeds the size +specified by the +.I addr +argument, the output data is truncated. +.IP +The +.I ptrace_syscall_info +structure contains the following fields: +.IP +.in +4n +.EX +struct ptrace_syscall_info { + __u8 op; /* Type of system call stop */ + __u32 arch; /* AUDIT_ARCH_* value; see seccomp(2) */ + __u64 instruction_pointer; /* CPU instruction pointer */ + __u64 stack_pointer; /* CPU stack pointer */ + union { + struct { /* op == PTRACE_SYSCALL_INFO_ENTRY */ + __u64 nr; /* System call number */ + __u64 args[6]; /* System call arguments */ + } entry; + struct { /* op == PTRACE_SYSCALL_INFO_EXIT */ + __s64 rval; /* System call return value */ + __u8 is_error; /* System call error flag; + Boolean: does rval contain + an error value (\-ERRCODE) or + a nonerror return value? */ + } exit; + struct { /* op == PTRACE_SYSCALL_INFO_SECCOMP */ + __u64 nr; /* System call number */ + __u64 args[6]; /* System call arguments */ + __u32 ret_data; /* SECCOMP_RET_DATA portion + of SECCOMP_RET_TRACE + return value */ + } seccomp; + }; +}; +.EE +.in +.IP +The +.IR op , +.IR arch , +.IR instruction_pointer , +and +.I stack_pointer +fields are defined for all kinds of ptrace system call stops. +The rest of the structure is a union; one should read only those fields +that are meaningful for the kind of system call stop specified by the +.I op +field. +.IP +The +.I op +field has one of the following values (defined in +.IR ) +indicating what type of stop occurred and +which part of the union is filled: +.RS +.TP +.B PTRACE_SYSCALL_INFO_ENTRY +The +.I entry +component of the union contains information relating to a +system call entry stop. +.TP +.B PTRACE_SYSCALL_INFO_EXIT +The +.I exit +component of the union contains information relating to a +system call exit stop. +.TP +.B PTRACE_SYSCALL_INFO_SECCOMP +The +.I seccomp +component of the union contains information relating to a +.B PTRACE_EVENT_SECCOMP +stop. +.TP +.B PTRACE_SYSCALL_INFO_NONE +No component of the union contains relevant information. +.RE +.IP +In case of system call entry or exit stops, +the data returned by +.B PTRACE_GET_SYSCALL_INFO +is limited to type +.B PTRACE_SYSCALL_INFO_NONE +unless +.B PTRACE_O_TRACESYSGOOD +option is set before the corresponding system call stop has occurred. +.\" +.SS Death under ptrace +When a (possibly multithreaded) process receives a killing signal +(one whose disposition is set to +.B SIG_DFL +and whose default action is to kill the process), +all threads exit. +Tracees report their death to their tracer(s). +Notification of this event is delivered via +.BR waitpid (2). +.P +Note that the killing signal will first cause signal-delivery-stop +(on one tracee only), +and only after it is injected by the tracer +(or after it was dispatched to a thread which isn't traced), +will death from the signal happen on +.I all +tracees within a multithreaded process. +(The term "signal-delivery-stop" is explained below.) +.P +.B SIGKILL +does not generate signal-delivery-stop and +therefore the tracer can't suppress it. +.B SIGKILL +kills even within system calls +(syscall-exit-stop is not generated prior to death by +.BR SIGKILL ). +The net effect is that +.B SIGKILL +always kills the process (all its threads), +even if some threads of the process are ptraced. +.P +When the tracee calls +.BR _exit (2), +it reports its death to its tracer. +Other threads are not affected. +.P +When any thread executes +.BR exit_group (2), +every tracee in its thread group reports its death to its tracer. +.P +If the +.B PTRACE_O_TRACEEXIT +option is on, +.B PTRACE_EVENT_EXIT +will happen before actual death. +This applies to exits via +.BR exit (2), +.BR exit_group (2), +and signal deaths (except +.BR SIGKILL , +depending on the kernel version; see BUGS below), +and when threads are torn down on +.BR execve (2) +in a multithreaded process. +.P +The tracer cannot assume that the ptrace-stopped tracee exists. +There are many scenarios when the tracee may die while stopped (such as +.BR SIGKILL ). +Therefore, the tracer must be prepared to handle an +.B ESRCH +error on any ptrace operation. +Unfortunately, the same error is returned if the tracee +exists but is not ptrace-stopped +(for commands which require a stopped tracee), +or if it is not traced by the process which issued the ptrace call. +The tracer needs to keep track of the stopped/running state of the tracee, +and interpret +.B ESRCH +as "tracee died unexpectedly" only if it knows that the tracee has +been observed to enter ptrace-stop. +Note that there is no guarantee that +.I waitpid(WNOHANG) +will reliably report the tracee's death status if a +ptrace operation returned +.BR ESRCH . +.I waitpid(WNOHANG) +may return 0 instead. +In other words, the tracee may be "not yet fully dead", +but already refusing ptrace operations. +.P +The tracer can't assume that the tracee +.I always +ends its life by reporting +.I WIFEXITED(status) +or +.IR WIFSIGNALED(status) ; +there are cases where this does not occur. +For example, if a thread other than thread group leader does an +.BR execve (2), +it disappears; +its PID will never be seen again, +and any subsequent ptrace stops will be reported under +the thread group leader's PID. +.SS Stopped states +A tracee can be in two states: running or stopped. +For the purposes of ptrace, a tracee which is blocked in a system call +(such as +.BR read (2), +.BR pause (2), +etc.) +is nevertheless considered to be running, even if the tracee is blocked +for a long time. +The state of the tracee after +.B PTRACE_LISTEN +is somewhat of a gray area: it is not in any ptrace-stop (ptrace commands +won't work on it, and it will deliver +.BR waitpid (2) +notifications), +but it also may be considered "stopped" because +it is not executing instructions (is not scheduled), and if it was +in group-stop before +.BR PTRACE_LISTEN , +it will not respond to signals until +.B SIGCONT +is received. +.P +There are many kinds of states when the tracee is stopped, and in ptrace +discussions they are often conflated. +Therefore, it is important to use precise terms. +.P +In this manual page, any stopped state in which the tracee is ready +to accept ptrace commands from the tracer is called +.IR ptrace-stop . +Ptrace-stops can +be further subdivided into +.IR signal-delivery-stop , +.IR group-stop , +.IR syscall-stop , +.IR "PTRACE_EVENT stops" , +and so on. +These stopped states are described in detail below. +.P +When the running tracee enters ptrace-stop, it notifies its tracer using +.BR waitpid (2) +(or one of the other "wait" system calls). +Most of this manual page assumes that the tracer waits with: +.P +.in +4n +.EX +pid = waitpid(pid_or_minus_1, &status, __WALL); +.EE +.in +.P +Ptrace-stopped tracees are reported as returns with +.I pid +greater than 0 and +.I WIFSTOPPED(status) +true. +.\" Denys Vlasenko: +.\" Do we require __WALL usage, or will just using 0 be ok? (With 0, +.\" I am not 100% sure there aren't ugly corner cases.) Are the +.\" rules different if user wants to use waitid? Will waitid require +.\" WEXITED? +.\" +.P +The +.B __WALL +flag does not include the +.B WSTOPPED +and +.B WEXITED +flags, but implies their functionality. +.P +Setting the +.B WCONTINUED +flag when calling +.BR waitpid (2) +is not recommended: the "continued" state is per-process and +consuming it can confuse the real parent of the tracee. +.P +Use of the +.B WNOHANG +flag may cause +.BR waitpid (2) +to return 0 ("no wait results available yet") +even if the tracer knows there should be a notification. +Example: +.P +.in +4n +.EX +errno = 0; +ptrace(PTRACE_CONT, pid, 0L, 0L); +if (errno == ESRCH) { + /* tracee is dead */ + r = waitpid(tracee, &status, __WALL | WNOHANG); + /* r can still be 0 here! */ +} +.EE +.in +.\" FIXME . +.\" waitid usage? WNOWAIT? +.\" describe how wait notifications queue (or not queue) +.P +The following kinds of ptrace-stops exist: signal-delivery-stops, +group-stops, +.B PTRACE_EVENT +stops, syscall-stops. +They all are reported by +.BR waitpid (2) +with +.I WIFSTOPPED(status) +true. +They may be differentiated by examining the value +.IR status>>8 , +and if there is ambiguity in that value, by querying +.BR PTRACE_GETSIGINFO . +(Note: the +.I WSTOPSIG(status) +macro can't be used to perform this examination, +because it returns the value +.IR "(status>>8)\ &\ 0xff" .) +.SS Signal-delivery-stop +When a (possibly multithreaded) process receives any signal except +.BR SIGKILL , +the kernel selects an arbitrary thread which handles the signal. +(If the signal is generated with +.BR tgkill (2), +the target thread can be explicitly selected by the caller.) +If the selected thread is traced, it enters signal-delivery-stop. +At this point, the signal is not yet delivered to the process, +and can be suppressed by the tracer. +If the tracer doesn't suppress the signal, +it passes the signal to the tracee in the next ptrace restart operation. +This second step of signal delivery is called +.I "signal injection" +in this manual page. +Note that if the signal is blocked, +signal-delivery-stop doesn't happen until the signal is unblocked, +with the usual exception that +.B SIGSTOP +can't be blocked. +.P +Signal-delivery-stop is observed by the tracer as +.BR waitpid (2) +returning with +.I WIFSTOPPED(status) +true, with the signal returned by +.IR WSTOPSIG(status) . +If the signal is +.BR SIGTRAP , +this may be a different kind of ptrace-stop; +see the "Syscall-stops" and "execve" sections below for details. +If +.I WSTOPSIG(status) +returns a stopping signal, this may be a group-stop; see below. +.SS Signal injection and suppression +After signal-delivery-stop is observed by the tracer, +the tracer should restart the tracee with the call +.P +.in +4n +.EX +ptrace(PTRACE_restart, pid, 0, sig) +.EE +.in +.P +where +.B PTRACE_restart +is one of the restarting ptrace operations. +If +.I sig +is 0, then a signal is not delivered. +Otherwise, the signal +.I sig +is delivered. +This operation is called +.I "signal injection" +in this manual page, to distinguish it from signal-delivery-stop. +.P +The +.I sig +value may be different from the +.I WSTOPSIG(status) +value: the tracer can cause a different signal to be injected. +.P +Note that a suppressed signal still causes system calls to return +prematurely. +In this case, system calls will be restarted: the tracer will +observe the tracee to reexecute the interrupted system call (or +.BR restart_syscall (2) +system call for a few system calls which use a different mechanism +for restarting) if the tracer uses +.BR PTRACE_SYSCALL . +Even system calls (such as +.BR poll (2)) +which are not restartable after signal are restarted after +signal is suppressed; +however, kernel bugs exist which cause some system calls to fail with +.B EINTR +even though no observable signal is injected to the tracee. +.P +Restarting ptrace commands issued in ptrace-stops other than +signal-delivery-stop are not guaranteed to inject a signal, even if +.I sig +is nonzero. +No error is reported; a nonzero +.I sig +may simply be ignored. +Ptrace users should not try to "create a new signal" this way: use +.BR tgkill (2) +instead. +.P +The fact that signal injection operations may be ignored +when restarting the tracee after +ptrace stops that are not signal-delivery-stops +is a cause of confusion among ptrace users. +One typical scenario is that the tracer observes group-stop, +mistakes it for signal-delivery-stop, restarts the tracee with +.P +.in +4n +.EX +ptrace(PTRACE_restart, pid, 0, stopsig) +.EE +.in +.P +with the intention of injecting +.IR stopsig , +but +.I stopsig +gets ignored and the tracee continues to run. +.P +The +.B SIGCONT +signal has a side effect of waking up (all threads of) +a group-stopped process. +This side effect happens before signal-delivery-stop. +The tracer can't suppress this side effect (it can +only suppress signal injection, which only causes the +.B SIGCONT +handler to not be executed in the tracee, if such a handler is installed). +In fact, waking up from group-stop may be followed by +signal-delivery-stop for signal(s) +.I other than +.BR SIGCONT , +if they were pending when +.B SIGCONT +was delivered. +In other words, +.B SIGCONT +may be not the first signal observed by the tracee after it was sent. +.P +Stopping signals cause (all threads of) a process to enter group-stop. +This side effect happens after signal injection, and therefore can be +suppressed by the tracer. +.P +In Linux 2.4 and earlier, the +.B SIGSTOP +signal can't be injected. +.\" In the Linux 2.4 sources, in arch/i386/kernel/signal.c::do_signal(), +.\" there is: +.\" +.\" /* The debugger continued. Ignore SIGSTOP. */ +.\" if (signr == SIGSTOP) +.\" continue; +.P +.B PTRACE_GETSIGINFO +can be used to retrieve a +.I siginfo_t +structure which corresponds to the delivered signal. +.B PTRACE_SETSIGINFO +may be used to modify it. +If +.B PTRACE_SETSIGINFO +has been used to alter +.IR siginfo_t , +the +.I si_signo +field and the +.I sig +parameter in the restarting command must match, +otherwise the result is undefined. +.SS Group-stop +When a (possibly multithreaded) process receives a stopping signal, +all threads stop. +If some threads are traced, they enter a group-stop. +Note that the stopping signal will first cause signal-delivery-stop +(on one tracee only), and only after it is injected by the tracer +(or after it was dispatched to a thread which isn't traced), +will group-stop be initiated on +.I all +tracees within the multithreaded process. +As usual, every tracee reports its group-stop separately +to the corresponding tracer. +.P +Group-stop is observed by the tracer as +.BR waitpid (2) +returning with +.I WIFSTOPPED(status) +true, with the stopping signal available via +.IR WSTOPSIG(status) . +The same result is returned by some other classes of ptrace-stops, +therefore the recommended practice is to perform the call +.P +.in +4n +.EX +ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo) +.EE +.in +.P +The call can be avoided if the signal is not +.BR SIGSTOP , +.BR SIGTSTP , +.BR SIGTTIN , +or +.BR SIGTTOU ; +only these four signals are stopping signals. +If the tracer sees something else, it can't be a group-stop. +Otherwise, the tracer needs to call +.BR PTRACE_GETSIGINFO . +If +.B PTRACE_GETSIGINFO +fails with +.BR EINVAL , +then it is definitely a group-stop. +(Other failure codes are possible, such as +.B ESRCH +("no such process") if a +.B SIGKILL +killed the tracee.) +.P +If tracee was attached using +.BR PTRACE_SEIZE , +group-stop is indicated by +.BR PTRACE_EVENT_STOP : +.IR "status>>16 == PTRACE_EVENT_STOP" . +This allows detection of group-stops +without requiring an extra +.B PTRACE_GETSIGINFO +call. +.P +As of Linux 2.6.38, +after the tracer sees the tracee ptrace-stop and until it +restarts or kills it, the tracee will not run, +and will not send notifications (except +.B SIGKILL +death) to the tracer, even if the tracer enters into another +.BR waitpid (2) +call. +.P +The kernel behavior described in the previous paragraph +causes a problem with transparent handling of stopping signals. +If the tracer restarts the tracee after group-stop, +the stopping signal +is effectively ignored\[em]the tracee doesn't remain stopped, it runs. +If the tracer doesn't restart the tracee before entering into the next +.BR waitpid (2), +future +.B SIGCONT +signals will not be reported to the tracer; +this would cause the +.B SIGCONT +signals to have no effect on the tracee. +.P +Since Linux 3.4, there is a method to overcome this problem: instead of +.BR PTRACE_CONT , +a +.B PTRACE_LISTEN +command can be used to restart a tracee in a way where it does not execute, +but waits for a new event which it can report via +.BR waitpid (2) +(such as when +it is restarted by a +.BR SIGCONT ). +.SS PTRACE_EVENT stops +If the tracer sets +.B PTRACE_O_TRACE_* +options, the tracee will enter ptrace-stops called +.B PTRACE_EVENT +stops. +.P +.B PTRACE_EVENT +stops are observed by the tracer as +.BR waitpid (2) +returning with +.IR WIFSTOPPED(status) , +and +.I WSTOPSIG(status) +returns +.B SIGTRAP +(or for +.BR PTRACE_EVENT_STOP , +returns the stopping signal if tracee is in a group-stop). +An additional bit is set in the higher byte of the status word: +the value +.I status>>8 +will be +.P +.in +4n +.EX +((PTRACE_EVENT_foo<<8) | SIGTRAP). +.EE +.in +.P +The following events exist: +.TP +.B PTRACE_EVENT_VFORK +Stop before return from +.BR vfork (2) +or +.BR clone (2) +with the +.B CLONE_VFORK +flag. +When the tracee is continued after this stop, it will wait for child to +exit/exec before continuing its execution +(in other words, the usual behavior on +.BR vfork (2)). +.TP +.B PTRACE_EVENT_FORK +Stop before return from +.BR fork (2) +or +.BR clone (2) +with the exit signal set to +.BR SIGCHLD . +.TP +.B PTRACE_EVENT_CLONE +Stop before return from +.BR clone (2). +.TP +.B PTRACE_EVENT_VFORK_DONE +Stop before return from +.BR vfork (2) +or +.BR clone (2) +with the +.B CLONE_VFORK +flag, +but after the child unblocked this tracee by exiting or execing. +.P +For all four stops described above, +the stop occurs in the parent (i.e., the tracee), +not in the newly created thread. +.B PTRACE_GETEVENTMSG +can be used to retrieve the new thread's ID. +.TP +.B PTRACE_EVENT_EXEC +Stop before return from +.BR execve (2). +Since Linux 3.0, +.B PTRACE_GETEVENTMSG +returns the former thread ID. +.TP +.B PTRACE_EVENT_EXIT +Stop before exit (including death from +.BR exit_group (2)), +signal death, or exit caused by +.BR execve (2) +in a multithreaded process. +.B PTRACE_GETEVENTMSG +returns the exit status. +Registers can be examined +(unlike when "real" exit happens). +The tracee is still alive; it needs to be +.BR PTRACE_CONT ed +or +.BR PTRACE_DETACH ed +to finish exiting. +.TP +.B PTRACE_EVENT_STOP +Stop induced by +.B PTRACE_INTERRUPT +command, or group-stop, or initial ptrace-stop when a new child is attached +(only if attached using +.BR PTRACE_SEIZE ). +.TP +.B PTRACE_EVENT_SECCOMP +Stop triggered by a +.BR seccomp (2) +rule on tracee syscall entry when +.B PTRACE_O_TRACESECCOMP +has been set by the tracer. +The seccomp event message data (from the +.B SECCOMP_RET_DATA +portion of the seccomp filter rule) can be retrieved with +.BR PTRACE_GETEVENTMSG . +The semantics of this stop are described in +detail in a separate section below. +.P +.B PTRACE_GETSIGINFO +on +.B PTRACE_EVENT +stops returns +.B SIGTRAP +in +.IR si_signo , +with +.I si_code +set to +.IR "(event<<8)\ |\ SIGTRAP" . +.SS Syscall-stops +If the tracee was restarted by +.B PTRACE_SYSCALL +or +.BR PTRACE_SYSEMU , +the tracee enters +syscall-enter-stop just prior to entering any system call (which +will not be executed if the restart was using +.BR PTRACE_SYSEMU , +regardless of any change made to registers at this point or how the +tracee is restarted after this stop). +No matter which method caused the syscall-entry-stop, +if the tracer restarts the tracee with +.BR PTRACE_SYSCALL , +the tracee enters syscall-exit-stop when the system call is finished, +or if it is interrupted by a signal. +(That is, signal-delivery-stop never happens between syscall-enter-stop +and syscall-exit-stop; it happens +.I after +syscall-exit-stop.). +If the tracee is continued using any other method (including +.BR PTRACE_SYSEMU ), +no syscall-exit-stop occurs. +Note that all mentions +.B PTRACE_SYSEMU +apply equally to +.BR PTRACE_SYSEMU_SINGLESTEP . +.P +However, even if the tracee was continued using +.BR PTRACE_SYSCALL , +it is not guaranteed that the next stop will be a syscall-exit-stop. +Other possibilities are that the tracee may stop in a +.B PTRACE_EVENT +stop (including seccomp stops), exit (if it entered +.BR _exit (2) +or +.BR exit_group (2)), +be killed by +.BR SIGKILL , +or die silently (if it is a thread group leader, the +.BR execve (2) +happened in another thread, +and that thread is not traced by the same tracer; +this situation is discussed later). +.P +Syscall-enter-stop and syscall-exit-stop are observed by the tracer as +.BR waitpid (2) +returning with +.I WIFSTOPPED(status) +true, and +.I WSTOPSIG(status) +giving +.BR SIGTRAP . +If the +.B PTRACE_O_TRACESYSGOOD +option was set by the tracer, then +.I WSTOPSIG(status) +will give the value +.IR "(SIGTRAP\ |\ 0x80)" . +.P +Syscall-stops can be distinguished from signal-delivery-stop with +.B SIGTRAP +by querying +.B PTRACE_GETSIGINFO +for the following cases: +.TP +.IR si_code " <= 0" +.B SIGTRAP +was delivered as a result of a user-space action, +for example, a system call +.RB ( tgkill (2), +.BR kill (2), +.BR sigqueue (3), +etc.), +expiration of a POSIX timer, +change of state on a POSIX message queue, +or completion of an asynchronous I/O operation. +.TP +.IR si_code " == SI_KERNEL (0x80)" +.B SIGTRAP +was sent by the kernel. +.TP +.IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)" +This is a syscall-stop. +.P +However, syscall-stops happen very often (twice per system call), +and performing +.B PTRACE_GETSIGINFO +for every syscall-stop may be somewhat expensive. +.P +Some architectures allow the cases to be distinguished +by examining registers. +For example, on x86, +.I rax +== +.RB \- ENOSYS +in syscall-enter-stop. +Since +.B SIGTRAP +(like any other signal) always happens +.I after +syscall-exit-stop, +and at this point +.I rax +almost never contains +.RB \- ENOSYS , +the +.B SIGTRAP +looks like "syscall-stop which is not syscall-enter-stop"; +in other words, it looks like a +"stray syscall-exit-stop" and can be detected this way. +But such detection is fragile and is best avoided. +.P +Using the +.B PTRACE_O_TRACESYSGOOD +option is the recommended method to distinguish syscall-stops +from other kinds of ptrace-stops, +since it is reliable and does not incur a performance penalty. +.P +Syscall-enter-stop and syscall-exit-stop are +indistinguishable from each other by the tracer. +The tracer needs to keep track of the sequence of +ptrace-stops in order to not misinterpret syscall-enter-stop as +syscall-exit-stop or vice versa. +In general, a syscall-enter-stop is +always followed by syscall-exit-stop, +.B PTRACE_EVENT +stop, or the tracee's death; +no other kinds of ptrace-stop can occur in between. +However, note that seccomp stops (see below) can cause syscall-exit-stops, +without preceding syscall-entry-stops. +If seccomp is in use, care needs +to be taken not to misinterpret such stops as syscall-entry-stops. +.P +If after syscall-enter-stop, +the tracer uses a restarting command other than +.BR PTRACE_SYSCALL , +syscall-exit-stop is not generated. +.P +.B PTRACE_GETSIGINFO +on syscall-stops returns +.B SIGTRAP +in +.IR si_signo , +with +.I si_code +set to +.B SIGTRAP +or +.IR (SIGTRAP|0x80) . +.\" +.SS PTRACE_EVENT_SECCOMP stops (Linux 3.5 to Linux 4.7) +The behavior of +.B PTRACE_EVENT_SECCOMP +stops and their interaction with other kinds +of ptrace stops has changed between kernel versions. +This documents the behavior +from their introduction until Linux 4.7 (inclusive). +The behavior in later kernel versions is documented in the next section. +.P +A +.B PTRACE_EVENT_SECCOMP +stop occurs whenever a +.B SECCOMP_RET_TRACE +rule is triggered. +This is independent of which methods was used to restart the system call. +Notably, seccomp still runs even if the tracee was restarted using +.B PTRACE_SYSEMU +and this system call is unconditionally skipped. +.P +Restarts from this stop will behave as if the stop had occurred right +before the system call in question. +In particular, both +.B PTRACE_SYSCALL +and +.B PTRACE_SYSEMU +will normally cause a subsequent syscall-entry-stop. +However, if after the +.B PTRACE_EVENT_SECCOMP +the system call number is negative, +both the syscall-entry-stop and the system call itself will be skipped. +This means that if the system call number is negative after a +.B PTRACE_EVENT_SECCOMP +and the tracee is restarted using +.BR PTRACE_SYSCALL , +the next observed stop will be a syscall-exit-stop, +rather than the syscall-entry-stop that might have been expected. +.\" +.SS PTRACE_EVENT_SECCOMP stops (since Linux 4.8) +Starting with Linux 4.8, +.\" commit 93e35efb8de45393cf61ed07f7b407629bf698ea +the +.B PTRACE_EVENT_SECCOMP +stop was reordered to occur between syscall-entry-stop and +syscall-exit-stop. +Note that seccomp no longer runs (and no +.B PTRACE_EVENT_SECCOMP +will be reported) if the system call is skipped due to +.BR PTRACE_SYSEMU . +.P +Functionally, a +.B PTRACE_EVENT_SECCOMP +stop functions comparably +to a syscall-entry-stop (i.e., continuations using +.B PTRACE_SYSCALL +will cause syscall-exit-stops, +the system call number may be changed and any other modified registers +are visible to the to-be-executed system call as well). +Note that there may be, +but need not have been a preceding syscall-entry-stop. +.P +After a +.B PTRACE_EVENT_SECCOMP +stop, seccomp will be rerun, with a +.B SECCOMP_RET_TRACE +rule now functioning the same as a +.BR SECCOMP_RET_ALLOW . +Specifically, this means that if registers are not modified during the +.B PTRACE_EVENT_SECCOMP +stop, the system call will then be allowed. +.\" +.SS PTRACE_SINGLESTEP stops +[Details of these kinds of stops are yet to be documented.] +.\" +.\" FIXME . +.\" document stops occurring with PTRACE_SINGLESTEP +.\" +.SS Informational and restarting ptrace commands +Most ptrace commands (all except +.BR PTRACE_ATTACH , +.BR PTRACE_SEIZE , +.BR PTRACE_TRACEME , +.BR PTRACE_INTERRUPT , +and +.BR PTRACE_KILL ) +require the tracee to be in a ptrace-stop, otherwise they fail with +.BR ESRCH . +.P +When the tracee is in ptrace-stop, +the tracer can read and write data to +the tracee using informational commands. +These commands leave the tracee in ptrace-stopped state: +.P +.in +4n +.EX +ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0); +ptrace(PTRACE_POKETEXT/POKEDATA/POKEUSER, pid, addr, long_val); +ptrace(PTRACE_GETREGS/GETFPREGS, pid, 0, &struct); +ptrace(PTRACE_SETREGS/SETFPREGS, pid, 0, &struct); +ptrace(PTRACE_GETREGSET, pid, NT_foo, &iov); +ptrace(PTRACE_SETREGSET, pid, NT_foo, &iov); +ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo); +ptrace(PTRACE_SETSIGINFO, pid, 0, &siginfo); +ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var); +ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); +.EE +.in +.P +Note that some errors are not reported. +For example, setting signal information +.RI ( siginfo ) +may have no effect in some ptrace-stops, yet the call may succeed +(return 0 and not set +.IR errno ); +querying +.B PTRACE_GETEVENTMSG +may succeed and return some random value if current ptrace-stop +is not documented as returning a meaningful event message. +.P +The call +.P +.in +4n +.EX +ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); +.EE +.in +.P +affects one tracee. +The tracee's current flags are replaced. +Flags are inherited by new tracees created and "auto-attached" via active +.BR PTRACE_O_TRACEFORK , +.BR PTRACE_O_TRACEVFORK , +or +.B PTRACE_O_TRACECLONE +options. +.P +Another group of commands makes the ptrace-stopped tracee run. +They have the form: +.P +.in +4n +.EX +ptrace(cmd, pid, 0, sig); +.EE +.in +.P +where +.I cmd +is +.BR PTRACE_CONT , +.BR PTRACE_LISTEN , +.BR PTRACE_DETACH , +.BR PTRACE_SYSCALL , +.BR PTRACE_SINGLESTEP , +.BR PTRACE_SYSEMU , +or +.BR PTRACE_SYSEMU_SINGLESTEP . +If the tracee is in signal-delivery-stop, +.I sig +is the signal to be injected (if it is nonzero). +Otherwise, +.I sig +may be ignored. +(When restarting a tracee from a ptrace-stop other than signal-delivery-stop, +recommended practice is to always pass 0 in +.IR sig .) +.SS Attaching and detaching +A thread can be attached to the tracer using the call +.P +.in +4n +.EX +ptrace(PTRACE_ATTACH, pid, 0, 0); +.EE +.in +.P +or +.P +.in +4n +.EX +ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags); +.EE +.in +.P +.B PTRACE_ATTACH +sends +.B SIGSTOP +to this thread. +If the tracer wants this +.B SIGSTOP +to have no effect, it needs to suppress it. +Note that if other signals are concurrently sent to +this thread during attach, +the tracer may see the tracee enter signal-delivery-stop +with other signal(s) first! +The usual practice is to reinject these signals until +.B SIGSTOP +is seen, then suppress +.B SIGSTOP +injection. +The design bug here is that a ptrace attach and a concurrently delivered +.B SIGSTOP +may race and the concurrent +.B SIGSTOP +may be lost. +.\" +.\" FIXME Describe how to attach to a thread which is already group-stopped. +.P +Since attaching sends +.B SIGSTOP +and the tracer usually suppresses it, this may cause a stray +.B EINTR +return from the currently executing system call in the tracee, +as described in the "Signal injection and suppression" section. +.P +Since Linux 3.4, +.B PTRACE_SEIZE +can be used instead of +.BR PTRACE_ATTACH . +.B PTRACE_SEIZE +does not stop the attached process. +If you need to stop +it after attach (or at any other time) without sending it any signals, +use +.B PTRACE_INTERRUPT +command. +.P +The operation +.P +.in +4n +.EX +ptrace(PTRACE_TRACEME, 0, 0, 0); +.EE +.in +.P +turns the calling thread into a tracee. +The thread continues to run (doesn't enter ptrace-stop). +A common practice is to follow the +.B PTRACE_TRACEME +with +.P +.in +4n +.EX +raise(SIGSTOP); +.EE +.in +.P +and allow the parent (which is our tracer now) to observe our +signal-delivery-stop. +.P +If the +.BR PTRACE_O_TRACEFORK , +.BR PTRACE_O_TRACEVFORK , +or +.B PTRACE_O_TRACECLONE +options are in effect, then children created by, respectively, +.BR vfork (2) +or +.BR clone (2) +with the +.B CLONE_VFORK +flag, +.BR fork (2) +or +.BR clone (2) +with the exit signal set to +.BR SIGCHLD , +and other kinds of +.BR clone (2), +are automatically attached to the same tracer which traced their parent. +.B SIGSTOP +is delivered to the children, causing them to enter +signal-delivery-stop after they exit the system call which created them. +.P +Detaching of the tracee is performed by: +.P +.in +4n +.EX +ptrace(PTRACE_DETACH, pid, 0, sig); +.EE +.in +.P +.B PTRACE_DETACH +is a restarting operation; +therefore it requires the tracee to be in ptrace-stop. +If the tracee is in signal-delivery-stop, a signal can be injected. +Otherwise, the +.I sig +parameter may be silently ignored. +.P +If the tracee is running when the tracer wants to detach it, +the usual solution is to send +.B SIGSTOP +(using +.BR tgkill (2), +to make sure it goes to the correct thread), +wait for the tracee to stop in signal-delivery-stop for +.B SIGSTOP +and then detach it (suppressing +.B SIGSTOP +injection). +A design bug is that this can race with concurrent +.BR SIGSTOP s. +Another complication is that the tracee may enter other ptrace-stops +and needs to be restarted and waited for again, until +.B SIGSTOP +is seen. +Yet another complication is to be sure that +the tracee is not already ptrace-stopped, +because no signal delivery happens while it is\[em]not even +.BR SIGSTOP . +.\" FIXME Describe how to detach from a group-stopped tracee so that it +.\" doesn't run, but continues to wait for SIGCONT. +.P +If the tracer dies, all tracees are automatically detached and restarted, +unless they were in group-stop. +Handling of restart from group-stop is currently buggy, +but the "as planned" behavior is to leave tracee stopped and waiting for +.BR SIGCONT . +If the tracee is restarted from signal-delivery-stop, +the pending signal is injected. +.SS execve(2) under ptrace +.\" clone(2) CLONE_THREAD says: +.\" If any of the threads in a thread group performs an execve(2), +.\" then all threads other than the thread group leader are terminated, +.\" and the new program is executed in the thread group leader. +.\" +When one thread in a multithreaded process calls +.BR execve (2), +the kernel destroys all other threads in the process, +.\" In Linux 3.1 sources, see fs/exec.c::de_thread() +and resets the thread ID of the execing thread to the +thread group ID (process ID). +(Or, to put things another way, when a multithreaded process does an +.BR execve (2), +at completion of the call, it appears as though the +.BR execve (2) +occurred in the thread group leader, regardless of which thread did the +.BR execve (2).) +This resetting of the thread ID looks very confusing to tracers: +.IP \[bu] 3 +All other threads stop in +.B PTRACE_EVENT_EXIT +stop, if the +.B PTRACE_O_TRACEEXIT +option was turned on. +Then all other threads except the thread group leader report +death as if they exited via +.BR _exit (2) +with exit code 0. +.IP \[bu] +The execing tracee changes its thread ID while it is in the +.BR execve (2). +(Remember, under ptrace, the "pid" returned from +.BR waitpid (2), +or fed into ptrace calls, is the tracee's thread ID.) +That is, the tracee's thread ID is reset to be the same as its process ID, +which is the same as the thread group leader's thread ID. +.IP \[bu] +Then a +.B PTRACE_EVENT_EXEC +stop happens, if the +.B PTRACE_O_TRACEEXEC +option was turned on. +.IP \[bu] +If the thread group leader has reported its +.B PTRACE_EVENT_EXIT +stop by this time, +it appears to the tracer that +the dead thread leader "reappears from nowhere". +(Note: the thread group leader does not report death via +.I WIFEXITED(status) +until there is at least one other live thread. +This eliminates the possibility that the tracer will see +it dying and then reappearing.) +If the thread group leader was still alive, +for the tracer this may look as if thread group leader +returns from a different system call than it entered, +or even "returned from a system call even though +it was not in any system call". +If the thread group leader was not traced +(or was traced by a different tracer), then during +.BR execve (2) +it will appear as if it has become a tracee of +the tracer of the execing tracee. +.P +All of the above effects are the artifacts of +the thread ID change in the tracee. +.P +The +.B PTRACE_O_TRACEEXEC +option is the recommended tool for dealing with this situation. +First, it enables +.B PTRACE_EVENT_EXEC +stop, +which occurs before +.BR execve (2) +returns. +In this stop, the tracer can use +.B PTRACE_GETEVENTMSG +to retrieve the tracee's former thread ID. +(This feature was introduced in Linux 3.0.) +Second, the +.B PTRACE_O_TRACEEXEC +option disables legacy +.B SIGTRAP +generation on +.BR execve (2). +.P +When the tracer receives +.B PTRACE_EVENT_EXEC +stop notification, +it is guaranteed that except this tracee and the thread group leader, +no other threads from the process are alive. +.P +On receiving the +.B PTRACE_EVENT_EXEC +stop notification, +the tracer should clean up all its internal +data structures describing the threads of this process, +and retain only one data structure\[em]one which +describes the single still running tracee, with +.P +.in +4n +.EX +thread ID == thread group ID == process ID. +.EE +.in +.P +Example: two threads call +.BR execve (2) +at the same time: +.P +.nf +*** we get syscall-enter-stop in thread 1: ** +PID1 execve("/bin/foo", "foo" +*** we issue PTRACE_SYSCALL for thread 1 ** +*** we get syscall-enter-stop in thread 2: ** +PID2 execve("/bin/bar", "bar" +*** we issue PTRACE_SYSCALL for thread 2 ** +*** we get PTRACE_EVENT_EXEC for PID0, we issue PTRACE_SYSCALL ** +*** we get syscall-exit-stop for PID0: ** +PID0 <... execve resumed> ) = 0 +.fi +.P +If the +.B PTRACE_O_TRACEEXEC +option is +.I not +in effect for the execing tracee, +and if the tracee was +.BR PTRACE_ATTACH ed +rather that +.BR PTRACE_SEIZE d, +the kernel delivers an extra +.B SIGTRAP +to the tracee after +.BR execve (2) +returns. +This is an ordinary signal (similar to one which can be +generated by +.IR "kill \-TRAP" ), +not a special kind of ptrace-stop. +Employing +.B PTRACE_GETSIGINFO +for this signal returns +.I si_code +set to 0 +.RI ( SI_USER ). +This signal may be blocked by signal mask, +and thus may be delivered (much) later. +.P +Usually, the tracer (for example, +.BR strace (1)) +would not want to show this extra post-execve +.B SIGTRAP +signal to the user, and would suppress its delivery to the tracee (if +.B SIGTRAP +is set to +.BR SIG_DFL , +it is a killing signal). +However, determining +.I which +.B SIGTRAP +to suppress is not easy. +Setting the +.B PTRACE_O_TRACEEXEC +option or using +.B PTRACE_SEIZE +and thus suppressing this extra +.B SIGTRAP +is the recommended approach. +.SS Real parent +The ptrace API (ab)uses the standard UNIX parent/child signaling over +.BR waitpid (2). +This used to cause the real parent of the process to stop receiving +several kinds of +.BR waitpid (2) +notifications when the child process is traced by some other process. +.P +Many of these bugs have been fixed, but as of Linux 2.6.38 several still +exist; see BUGS below. +.P +As of Linux 2.6.38, the following is believed to work correctly: +.IP \[bu] 3 +exit/death by signal is reported first to the tracer, then, +when the tracer consumes the +.BR waitpid (2) +result, to the real parent (to the real parent only when the +whole multithreaded process exits). +If the tracer and the real parent are the same process, +the report is sent only once. +.SH RETURN VALUE +On success, the +.B PTRACE_PEEK* +operations return the requested data (but see NOTES), +the +.B PTRACE_SECCOMP_GET_FILTER +operation returns the number of instructions in the BPF program, +the +.B PTRACE_GET_SYSCALL_INFO +operation returns the number of bytes available to be written by the kernel, +and other operations return zero. +.P +On error, all operations return \-1, and +.I errno +is set to indicate the error. +Since the value returned by a successful +.B PTRACE_PEEK* +operation may be \-1, the caller must clear +.I errno +before the call, and then check it afterward +to determine whether or not an error occurred. +.SH ERRORS +.TP +.B EBUSY +(i386 only) There was an error with allocating or freeing a debug register. +.TP +.B EFAULT +There was an attempt to read from or write to an invalid area in +the tracer's or the tracee's memory, +probably because the area wasn't mapped or accessible. +Unfortunately, under Linux, different variations of this fault +will return +.B EIO +or +.B EFAULT +more or less arbitrarily. +.TP +.B EINVAL +An attempt was made to set an invalid option. +.TP +.B EIO +.I op +is invalid, or an attempt was made to read from or +write to an invalid area in the tracer's or the tracee's memory, +or there was a word-alignment violation, +or an invalid signal was specified during a restart operation. +.TP +.B EPERM +The specified process cannot be traced. +This could be because the +tracer has insufficient privileges (the required capability is +.BR CAP_SYS_PTRACE ); +unprivileged processes cannot trace processes that they +cannot send signals to or those running +set-user-ID/set-group-ID programs, for obvious reasons. +Alternatively, the process may already be being traced, +or (before Linux 2.6.26) be +.BR init (1) +(PID 1). +.TP +.B ESRCH +The specified process does not exist, or is not currently being traced +by the caller, or is not stopped +(for operations that require a stopped tracee). +.SH STANDARDS +None. +.SH HISTORY +SVr4, 4.3BSD. +.P +Before Linux 2.6.26, +.\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb +.BR init (1), +the process with PID 1, may not be traced. +.SH NOTES +Although arguments to +.BR ptrace () +are interpreted according to the prototype given, +glibc currently declares +.BR ptrace () +as a variadic function with only the +.I op +argument fixed. +It is recommended to always supply four arguments, +even if the requested operation does not use them, +setting unused/ignored arguments to +.I 0L +or +.IR "(void\ *)\ 0". +.P +A tracees parent continues to be the tracer even if that tracer calls +.BR execve (2). +.P +The layout of the contents of memory and the USER area are +quite operating-system- and architecture-specific. +The offset supplied, and the data returned, +might not entirely match with the definition of +.IR "struct user" . +.\" See http://lkml.org/lkml/2008/5/8/375 +.P +The size of a "word" is determined by the operating-system variant +(e.g., for 32-bit Linux it is 32 bits). +.P +This page documents the way the +.BR ptrace () +call works currently in Linux. +Its behavior differs significantly on other flavors of UNIX. +In any case, use of +.BR ptrace () +is highly specific to the operating system and architecture. +.\" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SS Ptrace access mode checking +Various parts of the kernel-user-space API (not just +.BR ptrace () +operations), require so-called "ptrace access mode" checks, +whose outcome determines whether an operation is permitted +(or, in a few cases, causes a "read" operation to return sanitized data). +These checks are performed in cases where one process can +inspect sensitive information about, +or in some cases modify the state of, another process. +The checks are based on factors such as the credentials and capabilities +of the two processes, +whether or not the "target" process is dumpable, +and the results of checks performed by any enabled Linux Security Module +(LSM)\[em]for example, SELinux, Yama, or Smack\[em]and by the commoncap LSM +(which is always invoked). +.P +Prior to Linux 2.6.27, all access checks were of a single type. +Since Linux 2.6.27, +.\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd +two access mode levels are distinguished: +.TP +.B PTRACE_MODE_READ +For "read" operations or other operations that are less dangerous, +such as: +.BR get_robust_list (2); +.BR kcmp (2); +reading +.IR /proc/ pid /auxv , +.IR /proc/ pid /environ , +or +.IR /proc/ pid /stat ; +or +.BR readlink (2) +of a +.IR /proc/ pid /ns/* +file. +.TP +.B PTRACE_MODE_ATTACH +For "write" operations, or other operations that are more dangerous, +such as: ptrace attaching +.RB ( PTRACE_ATTACH ) +to another process +or calling +.BR process_vm_writev (2). +.RB ( PTRACE_MODE_ATTACH +was effectively the default before Linux 2.6.27.) +.\" +.\" Regarding the above description of the distinction between +.\" PTRACE_MODE_READ and PTRACE_MODE_ATTACH, Stephen Smalley notes: +.\" +.\" That was the intent when the distinction was introduced, but it doesn't +.\" appear to have been properly maintained, e.g. there is now a common +.\" helper lock_trace() that is used for +.\" /proc/pid/{stack,syscall,personality} but checks PTRACE_MODE_ATTACH, and +.\" PTRACE_MODE_ATTACH is also used in timerslack_ns_write/show(). Likely +.\" should review and make them consistent. There was also some debate +.\" about proper handling of /proc/pid/fd. Arguably that one might belong +.\" back in the _ATTACH camp. +.\" +.P +Since Linux 4.5, +.\" commit caaee6234d05a58c5b4d05e7bf766131b810a657 +the above access mode checks are combined (ORed) with +one of the following modifiers: +.TP +.B PTRACE_MODE_FSCREDS +Use the caller's filesystem UID and GID (see +.BR credentials (7)) +or effective capabilities for LSM checks. +.TP +.B PTRACE_MODE_REALCREDS +Use the caller's real UID and GID or permitted capabilities for LSM checks. +This was effectively the default before Linux 4.5. +.P +Because combining one of the credential modifiers with one of +the aforementioned access modes is typical, +some macros are defined in the kernel sources for the combinations: +.TP +.B PTRACE_MODE_READ_FSCREDS +Defined as +.BR "PTRACE_MODE_READ | PTRACE_MODE_FSCREDS" . +.TP +.B PTRACE_MODE_READ_REALCREDS +Defined as +.BR "PTRACE_MODE_READ | PTRACE_MODE_REALCREDS" . +.TP +.B PTRACE_MODE_ATTACH_FSCREDS +Defined as +.BR "PTRACE_MODE_ATTACH | PTRACE_MODE_FSCREDS" . +.TP +.B PTRACE_MODE_ATTACH_REALCREDS +Defined as +.BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" . +.P +One further modifier can be ORed with the access mode: +.TP +.BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)" +.\" commit 69f594a38967f4540ce7a29b3fd214e68a8330bd +.\" Just for /proc/pid/stat +Don't audit this access mode check. +This modifier is employed for ptrace access mode checks +(such as checks when reading +.IR /proc/ pid /stat ) +that merely cause the output to be filtered or sanitized, +rather than causing an error to be returned to the caller. +In these cases, accessing the file is not a security violation and +there is no reason to generate a security audit record. +This modifier suppresses the generation of +such an audit record for the particular access check. +.P +Note that all of the +.B PTRACE_MODE_* +constants described in this subsection are kernel-internal, +and not visible to user space. +The constant names are mentioned here in order to label the various kinds of +ptrace access mode checks that are performed for various system calls +and accesses to various pseudofiles (e.g., under +.IR /proc ). +These names are used in other manual pages to provide a simple +shorthand for labeling the different kernel checks. +.P +The algorithm employed for ptrace access mode checking determines whether +the calling process is allowed to perform the corresponding action +on the target process. +(In the case of opening +.IR /proc/ pid +files, the "calling process" is the one opening the file, +and the process with the corresponding PID is the "target process".) +The algorithm is as follows: +.IP (1) 5 +If the calling thread and the target thread are in the same +thread group, access is always allowed. +.IP (2) +If the access mode specifies +.BR PTRACE_MODE_FSCREDS , +then, for the check in the next step, +employ the caller's filesystem UID and GID. +(As noted in +.BR credentials (7), +the filesystem UID and GID almost always have the same values +as the corresponding effective IDs.) +.IP +Otherwise, the access mode specifies +.BR PTRACE_MODE_REALCREDS , +so use the caller's real UID and GID for the checks in the next step. +(Most APIs that check the caller's UID and GID use the effective IDs. +For historical reasons, the +.B PTRACE_MODE_REALCREDS +check uses the real IDs instead.) +.IP (3) +Deny access if +.I neither +of the following is true: +.RS +.IP \[bu] 3 +The real, effective, and saved-set user IDs of the target +match the caller's user ID, +.I and +the real, effective, and saved-set group IDs of the target +match the caller's group ID. +.IP \[bu] +The caller has the +.B CAP_SYS_PTRACE +capability in the user namespace of the target. +.RE +.IP (4) +Deny access if the target process "dumpable" attribute has a value other than 1 +.RB ( SUID_DUMP_USER ; +see the discussion of +.B PR_SET_DUMPABLE +in +.BR prctl (2)), +and the caller does not have the +.B CAP_SYS_PTRACE +capability in the user namespace of the target process. +.IP (5) +The kernel LSM +.IR security_ptrace_access_check () +interface is invoked to see if ptrace access is permitted. +The results depend on the LSM(s). +The implementation of this interface in the commoncap LSM performs +the following steps: +.\" (in cap_ptrace_access_check()): +.RS +.IP (5.1) 7 +If the access mode includes +.BR PTRACE_MODE_FSCREDS , +then use the caller's +.I effective +capability set +in the following check; +otherwise (the access mode specifies +.BR PTRACE_MODE_REALCREDS , +so) use the caller's +.I permitted +capability set. +.IP (5.2) +Deny access if +.I neither +of the following is true: +.RS +.IP \[bu] 3 +The caller and the target process are in the same user namespace, +and the caller's capabilities are a superset of the target process's +.I permitted +capabilities. +.IP \[bu] +The caller has the +.B CAP_SYS_PTRACE +capability in the target process's user namespace. +.RE +.IP +Note that the commoncap LSM does not distinguish between +.B PTRACE_MODE_READ +and +.BR PTRACE_MODE_ATTACH . +.RE +.IP (6) +If access has not been denied by any of the preceding steps, +then access is allowed. +.\" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SS /proc/sys/kernel/yama/ptrace_scope +On systems with the Yama Linux Security Module (LSM) installed +(i.e., the kernel was configured with +.BR CONFIG_SECURITY_YAMA ), +the +.I /proc/sys/kernel/yama/ptrace_scope +file (available since Linux 3.4) +.\" commit 2d514487faf188938a4ee4fb3464eeecfbdcf8eb +can be used to restrict the ability to trace a process with +.BR ptrace () +(and thus also the ability to use tools such as +.BR strace (1) +and +.BR gdb (1)). +The goal of such restrictions is to prevent attack escalation whereby +a compromised process can ptrace-attach to other sensitive processes +(e.g., a GPG agent or an SSH session) owned by the user in order +to gain additional credentials that may exist in memory +and thus expand the scope of the attack. +.P +More precisely, the Yama LSM limits two types of operations: +.IP \[bu] 3 +Any operation that performs a ptrace access mode +.B PTRACE_MODE_ATTACH +check\[em]for example, +.BR ptrace () +.BR PTRACE_ATTACH . +(See the "Ptrace access mode checking" discussion above.) +.IP \[bu] +.BR ptrace () +.BR PTRACE_TRACEME . +.P +A process that has the +.B CAP_SYS_PTRACE +capability can update the +.I /proc/sys/kernel/yama/ptrace_scope +file with one of the following values: +.TP +0 ("classic ptrace permissions") +No additional restrictions on operations that perform +.B PTRACE_MODE_ATTACH +checks (beyond those imposed by the commoncap and other LSMs). +.IP +The use of +.B PTRACE_TRACEME +is unchanged. +.TP +1 ("restricted ptrace") [default value] +When performing an operation that requires a +.B PTRACE_MODE_ATTACH +check, the calling process must either have the +.B CAP_SYS_PTRACE +capability in the user namespace of the target process or +it must have a predefined relationship with the target process. +By default, +the predefined relationship is that the target process +must be a descendant of the caller. +.IP +A target process can employ the +.BR prctl (2) +.B PR_SET_PTRACER +operation to declare an additional PID that is allowed to perform +.B PTRACE_MODE_ATTACH +operations on the target. +See the kernel source file +.I Documentation/admin\-guide/LSM/Yama.rst +.\" commit 90bb766440f2147486a2acc3e793d7b8348b0c22 +(or +.I Documentation/security/Yama.txt +before Linux 4.13) +for further details. +.IP +The use of +.B PTRACE_TRACEME +is unchanged. +.TP +2 ("admin-only attach") +Only processes with the +.B CAP_SYS_PTRACE +capability in the user namespace of the target process may perform +.B PTRACE_MODE_ATTACH +operations or trace children that employ +.BR PTRACE_TRACEME . +.TP +3 ("no attach") +No process may perform +.B PTRACE_MODE_ATTACH +operations or trace children that employ +.BR PTRACE_TRACEME . +.IP +Once this value has been written to the file, it cannot be changed. +.P +With respect to values 1 and 2, +note that creating a new user namespace effectively removes the +protection offered by Yama. +This is because a process in the parent user namespace whose effective +UID matches the UID of the creator of a child namespace +has all capabilities (including +.BR CAP_SYS_PTRACE ) +when performing operations within the child user namespace +(and further-removed descendants of that namespace). +Consequently, when a process tries to use user namespaces to sandbox itself, +it inadvertently weakens the protections offered by the Yama LSM. +.\" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.\" +.SS C library/kernel differences +At the system call level, the +.BR PTRACE_PEEKTEXT , +.BR PTRACE_PEEKDATA , +and +.B PTRACE_PEEKUSER +operations have a different API: they store the result +at the address specified by the +.I data +parameter, and the return value is the error flag. +The glibc wrapper function provides the API given in DESCRIPTION above, +with the result being returned via the function return value. +.SH BUGS +On hosts with Linux 2.6 kernel headers, +.B PTRACE_SETOPTIONS +is declared with a different value than the one for Linux 2.4. +This leads to applications compiled with Linux 2.6 kernel +headers failing when run on Linux 2.4. +This can be worked around by redefining +.B PTRACE_SETOPTIONS +to +.BR PTRACE_OLDSETOPTIONS , +if that is defined. +.P +Group-stop notifications are sent to the tracer, but not to real parent. +Last confirmed on 2.6.38.6. +.P +If a thread group leader is traced and exits by calling +.BR _exit (2), +.\" Note from Denys Vlasenko: +.\" Here "exits" means any kind of death - _exit, exit_group, +.\" signal death. Signal death and exit_group cases are trivial, +.\" though: since signal death and exit_group kill all other threads +.\" too, "until all other threads exit" thing happens rather soon +.\" in these cases. Therefore, only _exit presents observably +.\" puzzling behavior to ptrace users: thread leader _exit's, +.\" but WIFEXITED isn't reported! We are trying to explain here +.\" why it is so. +a +.B PTRACE_EVENT_EXIT +stop will happen for it (if requested), but the subsequent +.B WIFEXITED +notification will not be delivered until all other threads exit. +As explained above, if one of other threads calls +.BR execve (2), +the death of the thread group leader will +.I never +be reported. +If the execed thread is not traced by this tracer, +the tracer will never know that +.BR execve (2) +happened. +One possible workaround is to +.B PTRACE_DETACH +the thread group leader instead of restarting it in this case. +Last confirmed on 2.6.38.6. +.\" FIXME . need to test/verify this scenario +.P +A +.B SIGKILL +signal may still cause a +.B PTRACE_EVENT_EXIT +stop before actual signal death. +This may be changed in the future; +.B SIGKILL +is meant to always immediately kill tasks even under ptrace. +Last confirmed on Linux 3.13. +.P +Some system calls return with +.B EINTR +if a signal was sent to a tracee, but delivery was suppressed by the tracer. +(This is very typical operation: it is usually +done by debuggers on every attach, in order to not introduce +a bogus +.BR SIGSTOP ). +As of Linux 3.2.9, the following system calls are affected +(this list is likely incomplete): +.BR epoll_wait (2), +and +.BR read (2) +from an +.BR inotify (7) +file descriptor. +The usual symptom of this bug is that when you attach to +a quiescent process with the command +.P +.in +4n +.EX +strace \-p +.EE +.in +.P +then, instead of the usual +and expected one-line output such as +.P +.in +4n +.EX +restart_syscall(<... resuming interrupted call ...>_ +.EE +.in +.P +or +.P +.in +4n +.EX +select(6, [5], NULL, [5], NULL_ +.EE +.in +.P +('_' denotes the cursor position), you observe more than one line. +For example: +.P +.in +4n +.EX + clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0 + epoll_wait(4,_ +.EE +.in +.P +What is not visible here is that the process was blocked in +.BR epoll_wait (2) +before +.BR strace (1) +has attached to it. +Attaching caused +.BR epoll_wait (2) +to return to user space with the error +.BR EINTR . +In this particular case, the program reacted to +.B EINTR +by checking the current time, and then executing +.BR epoll_wait (2) +again. +(Programs which do not expect such "stray" +.B EINTR +errors may behave in an unintended way upon an +.BR strace (1) +attach.) +.P +Contrary to the normal rules, the glibc wrapper for +.BR ptrace () +can set +.I errno +to zero. +.SH SEE ALSO +.BR gdb (1), +.BR ltrace (1), +.BR strace (1), +.BR clone (2), +.BR execve (2), +.BR fork (2), +.BR gettid (2), +.BR prctl (2), +.BR seccomp (2), +.BR sigaction (2), +.BR tgkill (2), +.BR vfork (2), +.BR waitpid (2), +.BR exec (3), +.BR capabilities (7), +.BR signal (7) diff --git a/man/man2/putmsg.2 b/man/man2/putmsg.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/putmsg.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/putpmsg.2 b/man/man2/putpmsg.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/putpmsg.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/pwrite.2 b/man/man2/pwrite.2 new file mode 100644 index 0000000..87eacb2 --- /dev/null +++ b/man/man2/pwrite.2 @@ -0,0 +1 @@ +.so man2/pread.2 diff --git a/man/man2/pwrite64.2 b/man/man2/pwrite64.2 new file mode 100644 index 0000000..9290e0a --- /dev/null +++ b/man/man2/pwrite64.2 @@ -0,0 +1 @@ +.so man2/pwrite.2 diff --git a/man/man2/pwritev.2 b/man/man2/pwritev.2 new file mode 100644 index 0000000..54e3384 --- /dev/null +++ b/man/man2/pwritev.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man/man2/pwritev2.2 b/man/man2/pwritev2.2 new file mode 100644 index 0000000..54e3384 --- /dev/null +++ b/man/man2/pwritev2.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man/man2/query_module.2 b/man/man2/query_module.2 new file mode 100644 index 0000000..450e13f --- /dev/null +++ b/man/man2/query_module.2 @@ -0,0 +1,194 @@ +.\" Copyright (C) 1996 Free Software Foundation, Inc. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" 2006-02-09, some reformatting by Luc Van Oostenryck; some +.\" reformatting and rewordings by mtk +.\" +.TH query_module 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +query_module \- query the kernel for various bits pertaining to modules +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int query_module(const char *" name ", int " which , +.BI " void " buf [. bufsize "], \ +size_t " bufsize , +.BI " size_t *" ret ); +.fi +.SH DESCRIPTION +.IR Note : +This system call is present only before Linux 2.6. +.P +.BR query_module () +requests information from the kernel about loadable modules. +The returned information is placed in the buffer pointed to by +.IR buf . +The caller must specify the size of +.I buf +in +.IR bufsize . +The precise nature and format of the returned information +depend on the operation specified by +.IR which . +Some operations require +.I name +to identify a currently loaded module, some allow +.I name +to be NULL, indicating the kernel proper. +.P +The following values can be specified for +.IR which : +.TP +.B 0 +Returns success, if the kernel supports +.BR query_module (). +Used to probe for availability of the system call. +.TP +.B QM_MODULES +Returns the names of all loaded modules. +The returned buffer consists of a sequence of null-terminated strings; +.I ret +is set to the number of +modules. +.\" ret is set on ENOSPC +.TP +.B QM_DEPS +Returns the names of all modules used by the indicated module. +The returned buffer consists of a sequence of null-terminated strings; +.I ret +is set to the number of modules. +.\" ret is set on ENOSPC +.TP +.B QM_REFS +Returns the names of all modules using the indicated module. +This is the inverse of +.BR QM_DEPS . +The returned buffer consists of a sequence of null-terminated strings; +.I ret +is set to the number of modules. +.\" ret is set on ENOSPC +.TP +.B QM_SYMBOLS +Returns the symbols and values exported by the kernel or the indicated +module. +The returned buffer is an array of structures of the following form +.\" ret is set on ENOSPC +.IP +.in +4n +.EX +struct module_symbol { + unsigned long value; + unsigned long name; +}; +.EE +.in +.IP +followed by null-terminated strings. +The value of +.I name +is the character offset of the string relative to the start of +.IR buf ; +.I ret +is set to the number of symbols. +.TP +.B QM_INFO +Returns miscellaneous information about the indicated module. +The output buffer format is: +.IP +.in +4n +.EX +struct module_info { + unsigned long address; + unsigned long size; + unsigned long flags; +}; +.EE +.in +.IP +where +.I address +is the kernel address at which the module resides, +.I size +is the size of the module in bytes, and +.I flags +is a mask of +.BR MOD_RUNNING , +.BR MOD_AUTOCLEAN , +and so on, that indicates the current status of the module +(see the Linux kernel source file +.IR include/linux/module.h ). +.I ret +is set to the size of the +.I module_info +structure. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +At least one of +.IR name , +.IR buf , +or +.I ret +was outside the program's accessible address space. +.TP +.B EINVAL +Invalid +.IR which ; +or +.I name +is NULL (indicating "the kernel"), +but this is not permitted with the specified value of +.IR which . +.\" Not permitted with QM_DEPS, QM_REFS, or QM_INFO. +.TP +.B ENOENT +No module by that +.I name +exists. +.TP +.B ENOSPC +The buffer size provided was too small. +.I ret +is set to the minimum size needed. +.TP +.B ENOSYS +.BR query_module () +is not supported in this version of the kernel +(e.g., Linux 2.6 or later). +.SH STANDARDS +Linux. +.SH VERSIONS +Removed in Linux 2.6. +.\" Removed in Linux 2.5.48 +.P +Some of the information that was formerly available via +.BR query_module () +can be obtained from +.IR /proc/modules , +.IR /proc/kallsyms , +and the files under the directory +.IR /sys/module . +.P +The +.BR query_module () +system call is not supported by glibc. +No declaration is provided in glibc headers, but, +through a quirk of history, glibc does export an ABI for this system call. +Therefore, in order to employ this system call, +it is sufficient to manually declare the interface in your code; +alternatively, you can invoke the system call using +.BR syscall (2). +.SH SEE ALSO +.BR create_module (2), +.BR delete_module (2), +.BR get_kernel_syms (2), +.BR init_module (2), +.BR lsmod (8), +.BR modinfo (8) diff --git a/man/man2/quotactl.2 b/man/man2/quotactl.2 new file mode 100644 index 0000000..26b0580 --- /dev/null +++ b/man/man2/quotactl.2 @@ -0,0 +1,806 @@ +.\" Copyright (c) 2010, Jan Kara +.\" A few pieces copyright (c) 1996 Andries Brouwer (aeb@cwi.nl) +.\" and copyright 2010 (c) Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH quotactl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +quotactl \- manipulate disk quotas +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.BR "#include " " /* Definition of " Q_X* " and " XFS_QUOTA_* \ +" constants" +.RB " (or " "; see NOTES) */" +.P +.BI "int quotactl(int " op ", const char *_Nullable " special ", int " id , +.BI " caddr_t " addr ); +.fi +.SH DESCRIPTION +The quota system can be used to set per-user, per-group, and per-project limits +on the amount of disk space used on a filesystem. +For each user and/or group, +a soft limit and a hard limit can be set for each filesystem. +The hard limit can't be exceeded. +The soft limit can be exceeded, but warnings will ensue. +Moreover, the user can't exceed the soft limit for more than grace period +duration (one week by default) at a time; +after this, the soft limit counts as a hard limit. +.P +The +.BR quotactl () +call manipulates disk quotas. +The +.I op +argument indicates an operation to be applied to the user or +group ID specified in +.IR id . +To initialize the +.I op +argument, use the +.I QCMD(subop, type) +macro. +The +.I type +value is either +.BR USRQUOTA , +for user quotas, +.BR GRPQUOTA , +for group quotas, or (since Linux 4.1) +.\" 847aac644e92e5624f2c153bab409bf713d5ff9a +.BR PRJQUOTA , +for project quotas. +The +.I subop +value is described below. +.P +The +.I special +argument is a pointer to a null-terminated string containing the pathname +of the (mounted) block special device for the filesystem being manipulated. +.P +The +.I addr +argument is the address of an optional, operation-specific, data structure +that is copied in or out of the system. +The interpretation of +.I addr +is given with each operation below. +.P +The +.I subop +value is one of the following operations: +.TP +.B Q_QUOTAON +Turn on quotas for a filesystem. +The +.I id +argument is the identification number of the quota format to be used. +Currently, there are three supported quota formats: +.RS +.TP 13 +.B QFMT_VFS_OLD +The original quota format. +.TP +.B QFMT_VFS_V0 +The standard VFS v0 quota format, which can handle 32-bit UIDs and GIDs +and quota limits up to 2\[ha]42 bytes and 2\[ha]32 inodes. +.TP +.B QFMT_VFS_V1 +A quota format that can handle 32-bit UIDs and GIDs +and quota limits of 2\[ha]63 \- 1 bytes and 2\[ha]63 \- 1 inodes. +.RE +.IP +The +.I addr +argument points to the pathname of a file containing the quotas for +the filesystem. +The quota file must exist; it is normally created with the +.BR quotacheck (8) +program +.IP +Quota information can be also stored in hidden system inodes +for ext4, XFS, and other filesystems if the filesystem is configured so. +In this case, there are no visible quota files and there is no need to +use +.BR quotacheck (8). +Quota information is always kept consistent by the filesystem and the +.B Q_QUOTAON +operation serves only to enable enforcement of quota limits. +The presence of hidden +system inodes with quota information is indicated by the +.B DQF_SYS_FILE +flag in the +.I dqi_flags +field returned by the +.B Q_GETINFO +operation. +.IP +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.TP +.B Q_QUOTAOFF +Turn off quotas for a filesystem. +The +.I addr +and +.I id +arguments are ignored. +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.TP +.B Q_GETQUOTA +Get disk quota limits and current usage for user or group +.IR id . +The +.I addr +argument is a pointer to a +.I dqblk +structure defined in +.I +as follows: +.IP +.in +4n +.EX +/* uint64_t is an unsigned 64\-bit integer; + uint32_t is an unsigned 32\-bit integer */ +\& +struct dqblk { /* Definition since Linux 2.4.22 */ + uint64_t dqb_bhardlimit; /* Absolute limit on disk + quota blocks alloc */ + uint64_t dqb_bsoftlimit; /* Preferred limit on + disk quota blocks */ + uint64_t dqb_curspace; /* Current occupied space + (in bytes) */ + uint64_t dqb_ihardlimit; /* Maximum number of + allocated inodes */ + uint64_t dqb_isoftlimit; /* Preferred inode limit */ + uint64_t dqb_curinodes; /* Current number of + allocated inodes */ + uint64_t dqb_btime; /* Time limit for excessive + disk use */ + uint64_t dqb_itime; /* Time limit for excessive + files */ + uint32_t dqb_valid; /* Bit mask of QIF_* + constants */ +}; +\& +/* Flags in dqb_valid that indicate which fields in + dqblk structure are valid. */ +\& +#define QIF_BLIMITS 1 +#define QIF_SPACE 2 +#define QIF_ILIMITS 4 +#define QIF_INODES 8 +#define QIF_BTIME 16 +#define QIF_ITIME 32 +#define QIF_LIMITS (QIF_BLIMITS | QIF_ILIMITS) +#define QIF_USAGE (QIF_SPACE | QIF_INODES) +#define QIF_TIMES (QIF_BTIME | QIF_ITIME) +#define QIF_ALL (QIF_LIMITS | QIF_USAGE | QIF_TIMES) +.EE +.in +.IP +The +.I dqb_valid +field is a bit mask that is set to indicate the entries in the +.I dqblk +structure that are valid. +Currently, the kernel fills in all entries of the +.I dqblk +structure and marks them as valid in the +.I dqb_valid +field. +Unprivileged users may retrieve only their own quotas; +a privileged user +.RB ( CAP_SYS_ADMIN ) +can retrieve the quotas of any user. +.TP +.BR Q_GETNEXTQUOTA " (since Linux 4.6)" +.\" commit 926132c0257a5a8d149a6a395cc3405e55420566 +This operation is the same as +.BR Q_GETQUOTA , +but it returns quota information for the next ID greater than or equal to +.I id +that has a quota set. +.IP +The +.I addr +argument is a pointer to a +.I nextdqblk +structure whose fields are as for the +.IR dqblk , +except for the addition of a +.I dqb_id +field that is used to return the ID for which +quota information is being returned: +.IP +.in +4n +.EX +struct nextdqblk { + uint64_t dqb_bhardlimit; + uint64_t dqb_bsoftlimit; + uint64_t dqb_curspace; + uint64_t dqb_ihardlimit; + uint64_t dqb_isoftlimit; + uint64_t dqb_curinodes; + uint64_t dqb_btime; + uint64_t dqb_itime; + uint32_t dqb_valid; + uint32_t dqb_id; +}; +.EE +.in +.TP +.B Q_SETQUOTA +Set quota information for user or group +.IR id , +using the information supplied in the +.I dqblk +structure pointed to by +.IR addr . +The +.I dqb_valid +field of the +.I dqblk +structure indicates which entries in the structure have been set by the caller. +This operation supersedes the +.B Q_SETQLIM +and +.B Q_SETUSE +operations in the previous quota interfaces. +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.TP +.BR Q_GETINFO " (since Linux 2.4.22)" +Get information (like grace times) about quotafile. +The +.I addr +argument should be a pointer to a +.I dqinfo +structure. +This structure is defined in +.I +as follows: +.IP +.in +4n +.EX +/* uint64_t is an unsigned 64\-bit integer; + uint32_t is an unsigned 32\-bit integer */ +\& +struct dqinfo { /* Defined since Linux 2.4.22 */ + uint64_t dqi_bgrace; /* Time before block soft limit + becomes hard limit */ + uint64_t dqi_igrace; /* Time before inode soft limit + becomes hard limit */ + uint32_t dqi_flags; /* Flags for quotafile + (DQF_*) */ + uint32_t dqi_valid; +}; +\& +/* Bits for dqi_flags */ +\& +/* Quota format QFMT_VFS_OLD */ +\& +#define DQF_ROOT_SQUASH (1 << 0) /* Root squash enabled */ + /* Before Linux v4.0, this had been defined + privately as V1_DQF_RSQUASH */ +\& +/* Quota format QFMT_VFS_V0 / QFMT_VFS_V1 */ +\& +#define DQF_SYS_FILE (1 << 16) /* Quota stored in + a system file */ +\& +/* Flags in dqi_valid that indicate which fields in + dqinfo structure are valid. */ +\& +#define IIF_BGRACE 1 +#define IIF_IGRACE 2 +#define IIF_FLAGS 4 +#define IIF_ALL (IIF_BGRACE | IIF_IGRACE | IIF_FLAGS) +.EE +.in +.IP +The +.I dqi_valid +field in the +.I dqinfo +structure indicates the entries in the structure that are valid. +Currently, the kernel fills in all entries of the +.I dqinfo +structure and marks them all as valid in the +.I dqi_valid +field. +The +.I id +argument is ignored. +.TP +.BR Q_SETINFO " (since Linux 2.4.22)" +Set information about quotafile. +The +.I addr +argument should be a pointer to a +.I dqinfo +structure. +The +.I dqi_valid +field of the +.I dqinfo +structure indicates the entries in the structure +that have been set by the caller. +This operation supersedes the +.B Q_SETGRACE +and +.B Q_SETFLAGS +operations in the previous quota interfaces. +The +.I id +argument is ignored. +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.TP +.BR Q_GETFMT " (since Linux 2.4.22)" +Get quota format used on the specified filesystem. +The +.I addr +argument should be a pointer to a 4-byte buffer +where the format number will be stored. +.TP +.B Q_SYNC +Update the on-disk copy of quota usages for a filesystem. +If +.I special +is NULL, then all filesystems with active quotas are sync'ed. +The +.I addr +and +.I id +arguments are ignored. +.TP +.BR Q_GETSTATS " (supported up to Linux 2.4.21)" +Get statistics and other generic information about the quota subsystem. +The +.I addr +argument should be a pointer to a +.I dqstats +structure in which data should be stored. +This structure is defined in +.IR . +The +.I special +and +.I id +arguments are ignored. +.IP +This operation is obsolete and was removed in Linux 2.4.22. +Files in +.I /proc/sys/fs/quota/ +carry the information instead. +.P +For XFS filesystems making use of the XFS Quota Manager (XQM), +the above operations are bypassed and the following operations are used: +.TP +.B Q_XQUOTAON +Turn on quotas for an XFS filesystem. +XFS provides the ability to turn on/off quota limit enforcement +with quota accounting. +Therefore, XFS expects +.I addr +to be a pointer to an +.I "unsigned int" +that contains a bitwise combination of the following flags (defined in +.IR ): +.IP +.in +4n +.EX +XFS_QUOTA_UDQ_ACCT /* User quota accounting */ +XFS_QUOTA_UDQ_ENFD /* User quota limits enforcement */ +XFS_QUOTA_GDQ_ACCT /* Group quota accounting */ +XFS_QUOTA_GDQ_ENFD /* Group quota limits enforcement */ +XFS_QUOTA_PDQ_ACCT /* Project quota accounting */ +XFS_QUOTA_PDQ_ENFD /* Project quota limits enforcement */ +.EE +.in +.IP +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +The +.I id +argument is ignored. +.TP +.B Q_XQUOTAOFF +Turn off quotas for an XFS filesystem. +As with +.BR Q_QUOTAON , +XFS filesystems expect a pointer to an +.I "unsigned int" +that specifies whether quota accounting and/or limit enforcement need +to be turned off (using the same flags as for +.B Q_XQUOTAON +operation). +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +The +.I id +argument is ignored. +.TP +.B Q_XGETQUOTA +Get disk quota limits and current usage for user +.IR id . +The +.I addr +argument is a pointer to an +.I fs_disk_quota +structure, which is defined in +.I +as follows: +.IP +.in +4n +.EX +/* All the blk units are in BBs (Basic Blocks) of + 512 bytes. */ +\& +#define FS_DQUOT_VERSION 1 /* fs_disk_quota.d_version */ +\& +#define XFS_USER_QUOTA (1<<0) /* User quota type */ +#define XFS_PROJ_QUOTA (1<<1) /* Project quota type */ +#define XFS_GROUP_QUOTA (1<<2) /* Group quota type */ +\& +struct fs_disk_quota { + int8_t d_version; /* Version of this structure */ + int8_t d_flags; /* XFS_{USER,PROJ,GROUP}_QUOTA */ + uint16_t d_fieldmask; /* Field specifier */ + uint32_t d_id; /* User, project, or group ID */ + uint64_t d_blk_hardlimit; /* Absolute limit on + disk blocks */ + uint64_t d_blk_softlimit; /* Preferred limit on + disk blocks */ + uint64_t d_ino_hardlimit; /* Maximum # allocated + inodes */ + uint64_t d_ino_softlimit; /* Preferred inode limit */ + uint64_t d_bcount; /* # disk blocks owned by + the user */ + uint64_t d_icount; /* # inodes owned by the user */ + int32_t d_itimer; /* Zero if within inode limits */ + /* If not, we refuse service */ + int32_t d_btimer; /* Similar to above; for + disk blocks */ + uint16_t d_iwarns; /* # warnings issued with + respect to # of inodes */ + uint16_t d_bwarns; /* # warnings issued with + respect to disk blocks */ + int32_t d_padding2; /* Padding \- for future use */ + uint64_t d_rtb_hardlimit; /* Absolute limit on realtime + (RT) disk blocks */ + uint64_t d_rtb_softlimit; /* Preferred limit on RT + disk blocks */ + uint64_t d_rtbcount; /* # realtime blocks owned */ + int32_t d_rtbtimer; /* Similar to above; for RT + disk blocks */ + uint16_t d_rtbwarns; /* # warnings issued with + respect to RT disk blocks */ + int16_t d_padding3; /* Padding \- for future use */ + char d_padding4[8]; /* Yet more padding */ +}; +.EE +.in +.IP +Unprivileged users may retrieve only their own quotas; +a privileged user +.RB ( CAP_SYS_ADMIN ) +may retrieve the quotas of any user. +.TP +.BR Q_XGETNEXTQUOTA " (since Linux 4.6)" +.\" commit 8b37524962b9c54423374717786198f5c0820a28 +This operation is the same as +.BR Q_XGETQUOTA , +but it returns (in the +.I fs_disk_quota +structure pointed by +.IR addr ) +quota information for the next ID greater than or equal to +.I id +that has a quota set. +Note that since +.I fs_disk_quota +already has +.I q_id +field, no separate structure type is needed (in contrast with +.B Q_GETQUOTA +and +.B Q_GETNEXTQUOTA +operations) +.TP +.B Q_XSETQLIM +Set disk quota limits for user +.IR id . +The +.I addr +argument is a pointer to an +.I fs_disk_quota +structure. +This operation requires privilege +.RB ( CAP_SYS_ADMIN ). +.TP +.B Q_XGETQSTAT +Returns XFS filesystem-specific quota information in the +.I fs_quota_stat +structure pointed by +.IR addr . +This is useful for finding out how much space is used to store quota +information, and also to get the quota on/off status of a given local XFS +filesystem. +The +.I fs_quota_stat +structure itself is defined as follows: +.IP +.in +4n +.EX +#define FS_QSTAT_VERSION 1 /* fs_quota_stat.qs_version */ +\& +struct fs_qfilestat { + uint64_t qfs_ino; /* Inode number */ + uint64_t qfs_nblks; /* Number of BBs + 512\-byte\-blocks */ + uint32_t qfs_nextents; /* Number of extents */ +}; +\& +struct fs_quota_stat { + int8_t qs_version; /* Version number for + future changes */ + uint16_t qs_flags; /* XFS_QUOTA_{U,P,G}DQ_{ACCT,ENFD} */ + int8_t qs_pad; /* Unused */ + struct fs_qfilestat qs_uquota; /* User quota storage + information */ + struct fs_qfilestat qs_gquota; /* Group quota storage + information */ + uint32_t qs_incoredqs; /* Number of dquots in core */ + int32_t qs_btimelimit; /* Limit for blocks timer */ + int32_t qs_itimelimit; /* Limit for inodes timer */ + int32_t qs_rtbtimelimit;/* Limit for RT + blocks timer */ + uint16_t qs_bwarnlimit; /* Limit for # of warnings */ + uint16_t qs_iwarnlimit; /* Limit for # of warnings */ +}; +.EE +.in +.IP +The +.I id +argument is ignored. +.TP +.B Q_XGETQSTATV +Returns XFS filesystem-specific quota information in the +.I fs_quota_statv +pointed to by +.IR addr . +This version of the operation uses a structure with proper versioning support, +along with appropriate layout (all fields are naturally aligned) and +padding to avoiding special compat handling; +it also provides the ability to get statistics regarding +the project quota file. +The +.I fs_quota_statv +structure itself is defined as follows: +.IP +.in +4n +.EX +#define FS_QSTATV_VERSION1 1 /* fs_quota_statv.qs_version */ +\& +struct fs_qfilestatv { + uint64_t qfs_ino; /* Inode number */ + uint64_t qfs_nblks; /* Number of BBs + 512\-byte\-blocks */ + uint32_t qfs_nextents; /* Number of extents */ + uint32_t qfs_pad; /* Pad for 8\-byte alignment */ +}; +\& +struct fs_quota_statv { + int8_t qs_version; /* Version for future + changes */ + uint8_t qs_pad1; /* Pad for 16\-bit alignment */ + uint16_t qs_flags; /* XFS_QUOTA_.* flags */ + uint32_t qs_incoredqs; /* Number of dquots incore */ + struct fs_qfilestatv qs_uquota; /* User quota + information */ + struct fs_qfilestatv qs_gquota; /* Group quota + information */ + struct fs_qfilestatv qs_pquota; /* Project quota + information */ + int32_t qs_btimelimit; /* Limit for blocks timer */ + int32_t qs_itimelimit; /* Limit for inodes timer */ + int32_t qs_rtbtimelimit; /* Limit for RT blocks + timer */ + uint16_t qs_bwarnlimit; /* Limit for # of warnings */ + uint16_t qs_iwarnlimit; /* Limit for # of warnings */ + uint64_t qs_pad2[8]; /* For future proofing */ +}; +.EE +.in +.IP +The +.I qs_version +field of the structure should be filled with the version of the structure +supported by the callee (for now, only +.I FS_QSTAT_VERSION1 +is supported). +The kernel will fill the structure in accordance with +version provided. +The +.I id +argument is ignored. +.TP +.BR Q_XQUOTARM " (buggy until Linux 3.16)" +.\" 9da93f9b7cdf8ab28da6b364cdc1fafc8670b4dc +Free the disk space taken by disk quotas. +The +.I addr +argument should be a pointer to an +.I "unsigned int" +value containing flags (the same as in +.I d_flags +field of +.I fs_disk_quota +structure) +which identify what types of quota +should be removed. +(Note that the quota type passed in the +.I op +argument is ignored, but should remain valid in order to pass preliminary +quotactl syscall handler checks.) +.IP +Quotas must have already been turned off. +The +.I id +argument is ignored. +.TP +.BR Q_XQUOTASYNC " (since Linux 2.6.15; no-op since Linux 3.4)" +.\" Added in commit ee34807a65aa0c5911dc27682863afca780a003e +This operation was an XFS quota equivalent to +.BR Q_SYNC , +but it is no-op since Linux 3.4, +.\" 4b217ed9e30f94b6e8e5e262020ef0ceab6113af +as +.BR sync (1) +writes quota information to disk now +(in addition to the other filesystem metadata that it writes out). +The +.IR special ", " id " and " addr +arguments are ignored. +.SH RETURN VALUE +On success, +.BR quotactl () +returns 0; on error \-1 +is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.I op +is +.BR Q_QUOTAON , +and the quota file pointed to by +.I addr +exists, but is not a regular file or +is not on the filesystem pointed to by +.IR special . +.TP +.B EBUSY +.I op +is +.BR Q_QUOTAON , +but another +.B Q_QUOTAON +had already been performed. +.TP +.B EFAULT +.I addr +or +.I special +is invalid. +.TP +.B EINVAL +.I op +or +.I type +is invalid. +.TP +.B EINVAL +.I op +is +.BR Q_QUOTAON , +but the specified quota file is corrupted. +.TP +.BR EINVAL " (since Linux 5.5)" +.\" 3dd4d40b420846dd35869ccc8f8627feef2cff32 +.I op +is +.BR Q_XQUOTARM , +but +.I addr +does not point to valid quota types. +.TP +.B ENOENT +The file specified by +.I special +or +.I addr +does not exist. +.TP +.B ENOSYS +The kernel has not been compiled with the +.B CONFIG_QUOTA +option. +.TP +.B ENOTBLK +.I special +is not a block device. +.TP +.B EPERM +The caller lacked the required privilege +.RB ( CAP_SYS_ADMIN ) +for the specified operation. +.TP +.B ERANGE +.I op +is +.BR Q_SETQUOTA , +but the specified limits are out of the range allowed by the quota format. +.TP +.B ESRCH +No disk quota is found for the indicated user. +Quotas have not been turned on for this filesystem. +.TP +.B ESRCH +.I op +is +.BR Q_QUOTAON , +but the specified quota format was not found. +.TP +.B ESRCH +.I op +is +.B Q_GETNEXTQUOTA +or +.BR Q_XGETNEXTQUOTA , +but there is no ID greater than or equal to +.I id +that has an active quota. +.SH NOTES +Instead of +.I +one can use +.IR , +taking into account that there are several naming discrepancies: +.IP \[bu] 3 +Quota enabling flags (of format +.BR XFS_QUOTA_[UGP]DQ_{ACCT,ENFD} ) +are defined without a leading "X", as +.BR FS_QUOTA_[UGP]DQ_{ACCT,ENFD} . +.IP \[bu] +The same is true for +.B XFS_{USER,GROUP,PROJ}_QUOTA +quota type flags, which are defined as +.BR FS_{USER,GROUP,PROJ}_QUOTA . +.IP \[bu] +The +.I dqblk_xfs.h +header file defines its own +.BR XQM_USRQUOTA , +.BR XQM_GRPQUOTA , +and +.B XQM_PRJQUOTA +constants for the available quota types, but their values are the same as for +constants without the +.B XQM_ +prefix. +.SH SEE ALSO +.BR quota (1), +.BR getrlimit (2), +.BR quotacheck (8), +.BR quotaon (8) diff --git a/man/man2/read.2 b/man/man2/read.2 new file mode 100644 index 0000000..dae8942 --- /dev/null +++ b/man/man2/read.2 @@ -0,0 +1,245 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2009-2015 Michael Kerrisk, +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 00:06:00 1993 by Rik Faith +.\" Modified Wed Jan 17 16:02:32 1996 by Michael Haardt +.\" +.\" Modified Thu Apr 11 19:26:35 1996 by Andries Brouwer +.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer +.\" Modified Fri Jan 31 16:47:33 1997 by Eric S. Raymond +.\" Modified Sat Jul 12 20:45:39 1997 by Michael Haardt +.\" +.\" +.TH read 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +read \- read from a file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t read(int " fd ", void " buf [. count "], size_t " count ); +.fi +.SH DESCRIPTION +.BR read () +attempts to read up to +.I count +bytes from file descriptor +.I fd +into the buffer starting at +.IR buf . +.P +On files that support seeking, +the read operation commences at the file offset, +and the file offset is incremented by the number of bytes read. +If the file offset is at or past the end of file, +no bytes are read, and +.BR read () +returns zero. +.P +If +.I count +is zero, +.BR read () +.I may +detect the errors described below. +In the absence of any errors, +or if +.BR read () +does not check for errors, a +.BR read () +with a +.I count +of 0 returns zero and has no other effects. +.P +According to POSIX.1, if +.I count +is greater than +.BR SSIZE_MAX , +the result is implementation-defined; +see NOTES for the upper limit on Linux. +.SH RETURN VALUE +On success, the number of bytes read is returned (zero indicates end of +file), and the file position is advanced by this number. +It is not an error if this number is smaller than the number of bytes +requested; this may happen for example because fewer bytes are actually +available right now (maybe because we were close to end-of-file, or +because we are reading from a pipe, or from a terminal), or because +.BR read () +was interrupted by a signal. +See also NOTES. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +In this case, it is left unspecified whether +the file position (if any) changes. +.SH ERRORS +.TP +.B EAGAIN +The file descriptor +.I fd +refers to a file other than a socket and has been marked nonblocking +.RB ( O_NONBLOCK ), +and the read would block. +See +.BR open (2) +for further details on the +.B O_NONBLOCK +flag. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.\" Actually EAGAIN on Linux +The file descriptor +.I fd +refers to a socket and has been marked nonblocking +.RB ( O_NONBLOCK ), +and the read would block. +POSIX.1-2001 allows either error to be returned for this case, +and does not require these constants to have the same value, +so a portable application should check for both possibilities. +.TP +.B EBADF +.I fd +is not a valid file descriptor or is not open for reading. +.TP +.B EFAULT +.I buf +is outside your accessible address space. +.TP +.B EINTR +The call was interrupted by a signal before any data was read; see +.BR signal (7). +.TP +.B EINVAL +.I fd +is attached to an object which is unsuitable for reading; +or the file was opened with the +.B O_DIRECT +flag, and either the address specified in +.IR buf , +the value specified in +.IR count , +or the file offset is not suitably aligned. +.TP +.B EINVAL +.I fd +was created via a call to +.BR timerfd_create (2) +and the wrong size buffer was given to +.BR read (); +see +.BR timerfd_create (2) +for further information. +.TP +.B EIO +I/O error. +This will happen for example when the process is in a +background process group, tries to read from its controlling terminal, +and either it is ignoring or blocking +.B SIGTTIN +or its process group +is orphaned. +It may also occur when there is a low-level I/O error +while reading from a disk or tape. +A further possible cause of +.B EIO +on networked filesystems is when an advisory lock had been taken +out on the file descriptor and this lock has been lost. +See the +.I "Lost locks" +section of +.BR fcntl (2) +for further details. +.TP +.B EISDIR +.I fd +refers to a directory. +.P +Other errors may occur, depending on the object connected to +.IR fd . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, 4.3BSD, POSIX.1-2001. +.SH NOTES +On Linux, +.BR read () +(and similar system calls) will transfer at most +0x7ffff000 (2,147,479,552) bytes, +returning the number of bytes actually transferred. +.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 +(This is true on both 32-bit and 64-bit systems.) +.P +On NFS filesystems, reading small amounts of data will update the +timestamp only the first time, subsequent calls may not do so. +This is caused +by client side attribute caching, because most if not all NFS clients +leave +.I st_atime +(last file access time) +updates to the server, and client side reads satisfied from the +client's cache will not cause +.I st_atime +updates on the server as there are no +server-side reads. +UNIX semantics can be obtained by disabling client-side attribute caching, +but in most situations this will substantially +increase server load and decrease performance. +.SH BUGS +According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 +("Thread Interactions with Regular File Operations"): +.P +.RS 4 +All of the following functions shall be atomic with respect to +each other in the effects specified in POSIX.1-2008 when they +operate on regular files or symbolic links: ... +.RE +.P +Among the APIs subsequently listed are +.BR read () +and +.BR readv (2). +And among the effects that should be atomic across threads (and processes) +are updates of the file offset. +However, before Linux 3.14, +this was not the case: if two processes that share +an open file description (see +.BR open (2)) +perform a +.BR read () +(or +.BR readv (2)) +at the same time, then the I/O operations were not atomic +with respect to updating the file offset, +with the result that the reads in the two processes +might (incorrectly) overlap in the blocks of data that they obtained. +This problem was fixed in Linux 3.14. +.\" http://thread.gmane.org/gmane.linux.kernel/1649458 +.\" From: Michael Kerrisk (man-pages gmail.com> +.\" Subject: Update of file offset on write() etc. is non-atomic with I/O +.\" Date: 2014-02-17 15:41:37 GMT +.\" Newsgroups: gmane.linux.kernel, gmane.linux.file-systems +.\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4 +.\" Author: Linus Torvalds +.\" Date: Mon Mar 3 09:36:58 2014 -0800 +.\" +.\" vfs: atomic f_pos accesses as per POSIX +.SH SEE ALSO +.BR close (2), +.BR fcntl (2), +.BR ioctl (2), +.BR lseek (2), +.BR open (2), +.BR pread (2), +.BR readdir (2), +.BR readlink (2), +.BR readv (2), +.BR select (2), +.BR write (2), +.BR fread (3) diff --git a/man/man2/readahead.2 b/man/man2/readahead.2 new file mode 100644 index 0000000..bf2241c --- /dev/null +++ b/man/man2/readahead.2 @@ -0,0 +1,99 @@ +.\" This manpage is Copyright (C) 2004, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2004-05-40 Created by Michael Kerrisk +.\" 2004-10-05 aeb, minor correction +.\" +.TH readahead 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +readahead \- initiate file readahead into page cache +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #define _FILE_OFFSET_BITS 64 +.B #include +.P +.BI "ssize_t readahead(int " fd ", off_t " offset ", size_t " count ); +.fi +.SH DESCRIPTION +.BR readahead () +initiates readahead on a file so that subsequent reads from that file will +be satisfied from the cache, and not block on disk I/O +(assuming the readahead was initiated early enough and that other activity +on the system did not in the meantime flush pages from the cache). +.P +The +.I fd +argument is a file descriptor identifying the file which is +to be read. +The +.I offset +argument specifies the starting point from which data is to be read +and +.I count +specifies the number of bytes to be read. +I/O is performed in whole pages, so that +.I offset +is effectively rounded down to a page boundary +and bytes are read up to the next page boundary greater than or +equal to +.IR "(offset+count)" . +.BR readahead () +does not read beyond the end of the file. +The file offset of the open file description referred to by the file descriptor +.I fd +is left unchanged. +.SH RETURN VALUE +On success, +.BR readahead () +returns 0; on failure, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor or is not open for reading. +.TP +.B EINVAL +.I fd +does not refer to a file type to which +.BR readahead () +can be applied. +.SH VERSIONS +On some 32-bit architectures, +the calling signature for this system call differs, +for the reasons described in +.BR syscall (2). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.4.13, +glibc 2.3. +.SH NOTES +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that uses a pointer to +.BR readahead , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. +.SH BUGS +.BR readahead () +attempts to schedule the reads in the background and return immediately. +However, it may block while it reads the filesystem metadata needed +to locate the requested blocks. +This occurs frequently with ext[234] on large files +using indirect blocks instead of extents, +giving the appearance that the call blocks until the requested data has +been read. +.SH SEE ALSO +.BR lseek (2), +.BR madvise (2), +.BR mmap (2), +.BR posix_fadvise (2), +.BR read (2) diff --git a/man/man2/readdir.2 b/man/man2/readdir.2 new file mode 100644 index 0000000..c858813 --- /dev/null +++ b/man/man2/readdir.2 @@ -0,0 +1,116 @@ +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Written 11 June 1995 by Andries Brouwer +.\" Modified 22 July 1995 by Michael Chastain : +.\" In 1.3.X, returns only one entry each time; return value is different. +.\" Modified 2004-12-01, mtk, fixed headers listed in SYNOPSIS +.\" +.TH readdir 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +readdir \- read directory entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_readdir, unsigned int " fd , +.BI " struct old_linux_dirent *" dirp ", unsigned int " count ); +.fi +.P +.IR Note : +There is no definition of +.BR "struct old_linux_dirent" ; +see NOTES. +.SH DESCRIPTION +This is not the function you are interested in. +Look at +.BR readdir (3) +for the POSIX conforming C library interface. +This page documents the bare kernel system call interface, +which is superseded by +.BR getdents (2). +.P +.BR readdir () +reads one +.I old_linux_dirent +structure from the directory +referred to by the file descriptor +.I fd +into the buffer pointed to by +.IR dirp . +The argument +.I count +is ignored; at most one +.I old_linux_dirent +structure is read. +.P +The +.I old_linux_dirent +structure is declared (privately in Linux kernel file +.BR fs/readdir.c ) +as follows: +.P +.in +4n +.EX +struct old_linux_dirent { + unsigned long d_ino; /* inode number */ + unsigned long d_offset; /* offset to this \fIold_linux_dirent\fP */ + unsigned short d_namlen; /* length of this \fId_name\fP */ + char d_name[1]; /* filename (null\-terminated) */ +} +.EE +.in +.P +.I d_ino +is an inode number. +.I d_offset +is the distance from the start of the directory to this +.IR old_linux_dirent . +.I d_reclen +is the size of +.IR d_name , +not counting the terminating null byte (\[aq]\e0\[aq]). +.I d_name +is a null-terminated filename. +.SH RETURN VALUE +On success, 1 is returned. +On end of directory, 0 is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +Invalid file descriptor +.IR fd . +.TP +.B EFAULT +Argument points outside the calling process's address space. +.TP +.B EINVAL +Result buffer is too small. +.TP +.B ENOENT +No such directory. +.TP +.B ENOTDIR +File descriptor does not refer to a directory. +.SH VERSIONS +You will need to define the +.I old_linux_dirent +structure yourself. +However, probably you should use +.BR readdir (3) +instead. +.P +This system call does not exist on x86-64. +.SH STANDARDS +Linux. +.SH SEE ALSO +.BR getdents (2), +.BR readdir (3) diff --git a/man/man2/readlink.2 b/man/man2/readlink.2 new file mode 100644 index 0000000..12bf43b --- /dev/null +++ b/man/man2/readlink.2 @@ -0,0 +1,332 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" And Copyright (C) 2011 Guillem Jover +.\" And Copyright (C) 2006, 2014 Michael Kerrisk +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)readlink.2 6.8 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 00:10:21 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Jul 9 23:55:17 1996 by aeb +.\" Modified Fri Jan 24 00:26:00 1997 by aeb +.\" 2011-09-20, Guillem Jover : +.\" Added text on dynamically allocating buffer + example program +.\" +.TH readlink 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +readlink, readlinkat \- read value of a symbolic link +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t readlink(const char *restrict " pathname ", char *restrict " buf , +.BI " size_t " bufsiz ); +.P +.BR "#include " "/* Definition of " AT_* " constants */" +.B #include +.P +.BI "ssize_t readlinkat(int " dirfd ", const char *restrict " pathname , +.BI " char *restrict " buf ", size_t " bufsiz ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR readlink (): +.nf + _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.P +.BR readlinkat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +.BR readlink () +places the contents of the symbolic link +.I pathname +in the buffer +.IR buf , +which has size +.IR bufsiz . +.BR readlink () +does not append a terminating null byte to +.IR buf . +It will (silently) truncate the contents (to a length of +.I bufsiz +characters), in case the buffer is too small to hold all of the contents. +.SS readlinkat() +The +.BR readlinkat () +system call operates in exactly the same way as +.BR readlink (), +except for the differences described here. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR readlink () +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR readlink ()). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +Since Linux 2.6.39, +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +.I pathname +can be an empty string, +in which case the call operates on the symbolic link referred to by +.I dirfd +(which should have been obtained using +.BR open (2) +with the +.B O_PATH +and +.B O_NOFOLLOW +flags). +.P +See +.BR openat (2) +for an explanation of the need for +.BR readlinkat (). +.SH RETURN VALUE +On success, these calls return the number of bytes placed in +.IR buf . +(If the returned value equals +.IR bufsiz , +then truncation may have occurred.) +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for a component of the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( readlinkat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I buf +extends outside the process's allocated address space. +.TP +.B EINVAL +.I bufsiz +is not positive. +.\" At the glibc level, bufsiz is unsigned, so this error can only occur +.\" if bufsiz==0. However, the in the kernel syscall, bufsiz is signed, +.\" and this error can also occur if bufsiz < 0. +.\" See: http://thread.gmane.org/gmane.linux.man/380 +.\" Subject: [patch 0/3] [RFC] kernel/glibc mismatch of "readlink" syscall? +.TP +.B EINVAL +The named file (i.e., the final filename component of +.IR pathname ) +is not a symbolic link. +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A pathname, or a component of a pathname, was too long. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B ENOTDIR +.RB ( readlinkat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR readlink () +4.4BSD +(first appeared in 4.2BSD), +POSIX.1-2001, POSIX.1-2008. +.TP +.BR readlinkat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. +.P +Up to and including glibc 2.4, the return type of +.BR readlink () +was declared as +.IR int . +Nowadays, the return type is declared as +.IR ssize_t , +as (newly) required in POSIX.1-2001. +.SS glibc +On older kernels where +.BR readlinkat () +is unavailable, the glibc wrapper function falls back to the use of +.BR readlink (). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.I /proc/self/fd +that corresponds to the +.I dirfd +argument. +.SH NOTES +Using a statically sized buffer might not provide enough room for the +symbolic link contents. +The required size for the buffer can be obtained from the +.I stat.st_size +value returned by a call to +.BR lstat (2) +on the link. +However, the number of bytes written by +.BR readlink () +and +.BR readlinkat () +should be checked to make sure that the size of the +symbolic link did not increase between the calls. +Dynamically allocating the buffer for +.BR readlink () +and +.BR readlinkat () +also addresses a common portability problem when using +.B PATH_MAX +for the buffer size, +as this constant is not guaranteed to be defined per POSIX +if the system does not have such limit. +.SH EXAMPLES +The following program allocates the buffer needed by +.BR readlink () +dynamically from the information provided by +.BR lstat (2), +falling back to a buffer of size +.B PATH_MAX +in cases where +.BR lstat (2) +reports a size of zero. +.P +.\" SRC BEGIN (readlink.c) +.EX +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + char *buf; + ssize_t nbytes, bufsiz; + struct stat sb; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (lstat(argv[1], &sb) == \-1) { + perror("lstat"); + exit(EXIT_FAILURE); + } +\& + /* Add one to the link size, so that we can determine whether + the buffer returned by readlink() was truncated. */ +\& + bufsiz = sb.st_size + 1; +\& + /* Some magic symlinks under (for example) /proc and /sys + report \[aq]st_size\[aq] as zero. In that case, take PATH_MAX as + a "good enough" estimate. */ +\& + if (sb.st_size == 0) + bufsiz = PATH_MAX; +\& + buf = malloc(bufsiz); + if (buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + nbytes = readlink(argv[1], buf, bufsiz); + if (nbytes == \-1) { + perror("readlink"); + exit(EXIT_FAILURE); + } +\& + /* Print only \[aq]nbytes\[aq] of \[aq]buf\[aq], as it doesn't contain a terminating + null byte (\[aq]\e0\[aq]). */ + printf("\[aq]%s\[aq] points to \[aq]%.*s\[aq]\en", argv[1], (int) nbytes, buf); +\& + /* If the return value was equal to the buffer size, then + the link target was larger than expected (perhaps because the + target was changed between the call to lstat() and the call to + readlink()). Warn the user that the returned target may have + been truncated. */ +\& + if (nbytes == bufsiz) + printf("(Returned buffer may have been truncated)\en"); +\& + free(buf); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR readlink (1), +.BR lstat (2), +.BR stat (2), +.BR symlink (2), +.BR realpath (3), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/readlinkat.2 b/man/man2/readlinkat.2 new file mode 100644 index 0000000..b29d1b5 --- /dev/null +++ b/man/man2/readlinkat.2 @@ -0,0 +1 @@ +.so man2/readlink.2 diff --git a/man/man2/readv.2 b/man/man2/readv.2 new file mode 100644 index 0000000..330294d --- /dev/null +++ b/man/man2/readv.2 @@ -0,0 +1,427 @@ +.\" Copyright (C) 2007, 2010 Michael Kerrisk +.\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 18:34:44 1993 by Rik Faith (faith@cs.unc.edu) +.\" Merged readv.[23], 2002-10-17, aeb +.\" 2007-04-30 mtk, A fairly major rewrite to fix errors and +.\" add more details. +.\" 2010-11-16, mtk, Added documentation of preadv() and pwritev() +.\" +.TH readv 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +readv, writev, preadv, pwritev, preadv2, pwritev2 \- +read or write data into multiple buffers +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); +.BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); +.P +.BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt , +.BI " off_t " offset ); +.BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt , +.BI " off_t " offset ); +.P +.BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt , +.BI " off_t " offset ", int " flags ); +.BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt , +.BI " off_t " offset ", int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR preadv (), +.BR pwritev (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR readv () +system call reads +.I iovcnt +buffers from the file associated with the file descriptor +.I fd +into the buffers described by +.I iov +("scatter input"). +.P +The +.BR writev () +system call writes +.I iovcnt +buffers of data described by +.I iov +to the file associated with the file descriptor +.I fd +("gather output"). +.P +The pointer +.I iov +points to an array of +.I iovec +structures, +described in +.BR iovec (3type). +.P +The +.BR readv () +system call works just like +.BR read (2) +except that multiple buffers are filled. +.P +The +.BR writev () +system call works just like +.BR write (2) +except that multiple buffers are written out. +.P +Buffers are processed in array order. +This means that +.BR readv () +completely fills +.I iov[0] +before proceeding to +.IR iov[1] , +and so on. +(If there is insufficient data, then not all buffers pointed to by +.I iov +may be filled.) +Similarly, +.BR writev () +writes out the entire contents of +.I iov[0] +before proceeding to +.IR iov[1] , +and so on. +.P +The data transfers performed by +.BR readv () +and +.BR writev () +are atomic: the data written by +.\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596 +.BR writev () +is written as a single block that is not intermingled with output +from writes in other processes; +analogously, +.BR readv () +is guaranteed to read a contiguous block of data from the file, +regardless of read operations performed in other threads or processes +that have file descriptors referring to the same open file description +(see +.BR open (2)). +.SS preadv() and pwritev() +The +.BR preadv () +system call combines the functionality of +.BR readv () +and +.BR pread (2). +It performs the same task as +.BR readv (), +but adds a fourth argument, +.IR offset , +which specifies the file offset at which the input operation +is to be performed. +.P +The +.BR pwritev () +system call combines the functionality of +.BR writev () +and +.BR pwrite (2). +It performs the same task as +.BR writev (), +but adds a fourth argument, +.IR offset , +which specifies the file offset at which the output operation +is to be performed. +.P +The file offset is not changed by these system calls. +The file referred to by +.I fd +must be capable of seeking. +.SS preadv2() and pwritev2() +These system calls are similar to +.BR preadv () +and +.BR pwritev () +calls, but add a fifth argument, +.IR flags , +which modifies the behavior on a per-call basis. +.P +Unlike +.BR preadv () +and +.BR pwritev (), +if the +.I offset +argument is \-1, then the current file offset is used and updated. +.P +The +.I flags +argument contains a bitwise OR of zero or more of the following flags: +.TP +.BR RWF_DSYNC " (since Linux 4.7)" +.\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 +Provide a per-write equivalent of the +.B O_DSYNC +.BR open (2) +flag. +This flag is meaningful only for +.BR pwritev2 (), +and its effect applies only to the data range written by the system call. +.TP +.BR RWF_HIPRI " (since Linux 4.6)" +High priority read/write. +Allows block-based filesystems to use polling of the device, +which provides lower latency, but may use additional resources. +(Currently, this feature is usable only on a file descriptor opened using the +.B O_DIRECT +flag.) +.TP +.BR RWF_SYNC " (since Linux 4.7)" +.\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 +Provide a per-write equivalent of the +.B O_SYNC +.BR open (2) +flag. +This flag is meaningful only for +.BR pwritev2 (), +and its effect applies only to the data range written by the system call. +.TP +.BR RWF_NOWAIT " (since Linux 4.14)" +.\" commit 3239d834847627b6634a4139cf1dc58f6f137a46 +.\" commit 91f9943e1c7b6638f27312d03fe71fcc67b23571 +Do not wait for data which is not immediately available. +If this flag is specified, the +.BR preadv2 () +system call will return instantly if it would have to read data from +the backing storage or wait for a lock. +If some data was successfully read, it will return the number of bytes read. +If no bytes were read, it will return \-1 and set +.I errno +to +.B EAGAIN +(but see +.BR BUGS ). +Currently, this flag is meaningful only for +.BR preadv2 (). +.TP +.BR RWF_APPEND " (since Linux 4.16)" +.\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb +Provide a per-write equivalent of the +.B O_APPEND +.BR open (2) +flag. +This flag is meaningful only for +.BR pwritev2 (), +and its effect applies only to the data range written by the system call. +The +.I offset +argument does not affect the write operation; +the data is always appended to the end of the file. +However, if the +.I offset +argument is \-1, the current file offset is updated. +.SH RETURN VALUE +On success, +.BR readv (), +.BR preadv (), +and +.BR preadv2 () +return the number of bytes read; +.BR writev (), +.BR pwritev (), +and +.BR pwritev2 () +return the number of bytes written. +.P +Note that it is not an error for a successful call to transfer fewer bytes +than requested (see +.BR read (2) +and +.BR write (2)). +.P +On error, \-1 is returned, and \fIerrno\fP is set to indicate the error. +.SH ERRORS +The errors are as given for +.BR read (2) +and +.BR write (2). +Furthermore, +.BR preadv (), +.BR preadv2 (), +.BR pwritev (), +and +.BR pwritev2 () +can also fail for the same reasons as +.BR lseek (2). +Additionally, the following errors are defined: +.TP +.B EINVAL +The sum of the +.I iov_len +values overflows an +.I ssize_t +value. +.TP +.B EINVAL +The vector count, +.IR iovcnt , +is less than zero or greater than the permitted maximum. +.TP +.B EOPNOTSUPP +An unknown flag is specified in \fIflags\fP. +.SH VERSIONS +.SS C library/kernel differences +The raw +.BR preadv () +and +.BR pwritev () +system calls have call signatures that differ slightly from that of the +corresponding GNU C library wrapper functions shown in the SYNOPSIS. +The final argument, +.IR offset , +is unpacked by the wrapper functions into two arguments in the system calls: +.P +.BI " unsigned long " pos_l ", unsigned long " pos +.P +These arguments contain, respectively, the low order and high order 32 bits of +.IR offset . +.SH STANDARDS +.TP +.BR readv () +.TQ +.BR writev () +POSIX.1-2008. +.TP +.BR preadv () +.TQ +.BR pwritev () +BSD. +.TP +.BR preadv2 () +.TQ +.BR pwritev2 () +Linux. +.SH HISTORY +.TP +.BR readv () +.TQ +.BR writev () +POSIX.1-2001, +4.4BSD (first appeared in 4.2BSD). +.\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument, +.\" and \fIint\fP as the return type. +.\" The readv/writev system calls were buggy before Linux 1.3.40. +.\" (Says release.libc.) +.P +.BR preadv (), +.BR pwritev (): +Linux 2.6.30, +glibc 2.10. +.P +.BR preadv2 (), +.BR pwritev2 (): +Linux 4.6, +glibc 2.26. +.SS Historical C library/kernel differences +To deal with the fact that +.B IOV_MAX +was so low on early versions of Linux, +the glibc wrapper functions for +.BR readv () +and +.BR writev () +did some extra work if they detected that the underlying kernel +system call failed because this limit was exceeded. +In the case of +.BR readv (), +the wrapper function allocated a temporary buffer large enough +for all of the items specified by +.IR iov , +passed that buffer in a call to +.BR read (2), +copied data from the buffer to the locations specified by the +.I iov_base +fields of the elements of +.IR iov , +and then freed the buffer. +The wrapper function for +.BR writev () +performed the analogous task using a temporary buffer and a call to +.BR write (2). +.P +The need for this extra effort in the glibc wrapper functions +went away with Linux 2.2 and later. +However, glibc continued to provide this behavior until glibc 2.10. +Starting with glibc 2.9, +the wrapper functions provide this behavior only if the library detects +that the system is running a Linux kernel older than Linux 2.6.18 +(an arbitrarily selected kernel version). +And since glibc 2.20 +(which requires a minimum of Linux 2.6.32), +the glibc wrapper functions always just directly invoke the system calls. +.SH NOTES +POSIX.1 allows an implementation to place a limit on +the number of items that can be passed in +.IR iov . +An implementation can advertise its limit by defining +.B IOV_MAX +in +.I +or at run time via the return value from +.IR sysconf(_SC_IOV_MAX) . +On modern Linux systems, the limit is 1024. +Back in Linux 2.0 days, this limit was 16. +.\" +.\" +.SH BUGS +Linux 5.9 and Linux 5.10 have a bug where +.BR preadv2 () +with the +.B RWF_NOWAIT +flag may return 0 even when not at end of file. +.\" See +.\" +.\" The bug was introduced in +.\" efa8480a831 fs: RWF_NOWAIT should imply IOCB_NOIO +.\"and fixed in +.\" 06c0444290 mm/filemap.c: generic_file_buffered_read() now uses find_get_pages_contig +.SH EXAMPLES +The following code sample demonstrates the use of +.BR writev (): +.P +.in +4n +.EX +char *str0 = "hello "; +char *str1 = "world\en"; +ssize_t nwritten; +struct iovec iov[2]; +\& +iov[0].iov_base = str0; +iov[0].iov_len = strlen(str0); +iov[1].iov_base = str1; +iov[1].iov_len = strlen(str1); +\& +nwritten = writev(STDOUT_FILENO, iov, 2); +.EE +.in +.SH SEE ALSO +.BR pread (2), +.BR read (2), +.BR write (2) diff --git a/man/man2/reboot.2 b/man/man2/reboot.2 new file mode 100644 index 0000000..6d8a241 --- /dev/null +++ b/man/man2/reboot.2 @@ -0,0 +1,241 @@ +.\" Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl), 24 September 1998 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH reboot 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +reboot \- reboot or enable/disable Ctrl-Alt-Del +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.RB "/* Since Linux 2.1.30 there are symbolic names " LINUX_REBOOT_* + for the constants and a fourth argument to the call: */ +.P +.BR "#include " \ +"/* Definition of " LINUX_REBOOT_* " constants */" +.BR "#include " "/* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_reboot, int " magic ", int " magic2 ", int " op ", void *" arg ); +.P +/* Under glibc and most alternative libc's (including uclibc, dietlibc, + musl and a few others), some of the constants involved have gotten +.RB " symbolic names " RB_* ", and the library call is a 1-argument" + wrapper around the system call: */ +.P +.BR "#include " "/* Definition of " RB_* " constants */" +.B #include +.P +.BI "int reboot(int " op ); +.fi +.SH DESCRIPTION +The +.BR reboot () +call reboots the system, or enables/disables the reboot keystroke +(abbreviated CAD, since the default is Ctrl-Alt-Delete; +it can be changed using +.BR loadkeys (1)). +.P +This system call fails (with the error +.BR EINVAL ) +unless +.I magic +equals +.B LINUX_REBOOT_MAGIC1 +(that is, 0xfee1dead) and +.I magic2 +equals +.B LINUX_REBOOT_MAGIC2 +(that is, 0x28121969). +However, since Linux 2.1.17 also +.B LINUX_REBOOT_MAGIC2A +(that is, 0x05121996) +and since Linux 2.1.97 also +.B LINUX_REBOOT_MAGIC2B +(that is, 0x16041998) +and since Linux 2.5.71 also +.B LINUX_REBOOT_MAGIC2C +(that is, 0x20112000) +are permitted as values for +.IR magic2 . +(The hexadecimal values of these constants are meaningful.) +.P +The +.I op +argument can have the following values: +.TP +.B LINUX_REBOOT_CMD_CAD_OFF +.RB ( RB_DISABLE_CAD , +0). +CAD is disabled. +This means that the CAD keystroke will cause a +.B SIGINT +signal to be +sent to init (process 1), whereupon this process may decide upon a +proper action (maybe: kill all processes, sync, reboot). +.TP +.B LINUX_REBOOT_CMD_CAD_ON +.RB ( RB_ENABLE_CAD , +0x89abcdef). +CAD is enabled. +This means that the CAD keystroke will immediately cause +the action associated with +.BR LINUX_REBOOT_CMD_RESTART . +.TP +.B LINUX_REBOOT_CMD_HALT +.RB ( RB_HALT_SYSTEM , +0xcdef0123; since Linux 1.1.76). +The message "System halted." is printed, and the system is halted. +Control is given to the ROM monitor, if there is one. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.B LINUX_REBOOT_CMD_KEXEC +.RB ( RB_KEXEC , +0x45584543, since Linux 2.6.13). +Execute a kernel that has been loaded earlier with +.BR kexec_load (2). +This option is available only if the kernel was configured with +.BR CONFIG_KEXEC . +.TP +.B LINUX_REBOOT_CMD_POWER_OFF +.RB ( RB_POWER_OFF , +0x4321fedc; since Linux 2.1.30). +The message "Power down." is printed, the system is stopped, +and all power is removed from the system, if possible. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.B LINUX_REBOOT_CMD_RESTART +.RB ( RB_AUTOBOOT , +0x1234567). +The message "Restarting system." is printed, and a default +restart is performed immediately. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.B LINUX_REBOOT_CMD_RESTART2 +(0xa1b2c3d4; since Linux 2.1.30). +The message "Restarting system with command \[aq]%s\[aq]" is printed, +and a restart (using the command string given in +.IR arg ) +is performed immediately. +If not preceded by a +.BR sync (2), +data will be lost. +.TP +.B LINUX_REBOOT_CMD_SW_SUSPEND +.RB ( RB_SW_SUSPEND , +0xd000fce1; since Linux 2.5.18). +The system is suspended (hibernated) to disk. +This option is available only if the kernel was configured with +.BR CONFIG_HIBERNATION . +.P +Only the superuser may call +.BR reboot (). +.P +The precise effect of the above actions depends on the architecture. +For the i386 architecture, the additional argument does not do +anything at present (2.1.122), but the type of reboot can be +determined by kernel command-line arguments ("reboot=...") to be +either warm or cold, and either hard or through the BIOS. +.\" +.SS Behavior inside PID namespaces +.\" commit cf3f89214ef6a33fad60856bc5ffd7bb2fc4709b +.\" see also commit 923c7538236564c46ee80c253a416705321f13e3 +Since Linux 3.4, +if +.BR reboot () +is called +from a PID namespace other than the initial PID namespace +with one of the +.I op +values listed below, +it performs a "reboot" of that namespace: +the "init" process of the PID namespace is immediately terminated, +with the effects described in +.BR pid_namespaces (7). +.P +The values that can be supplied in +.I op +when calling +.BR reboot () +in this case are as follows: +.TP +.B LINUX_REBOOT_CMD_RESTART +.TQ +.B LINUX_REBOOT_CMD_RESTART2 +The "init" process is terminated, +and +.BR wait (2) +in the parent process reports that the child was killed with a +.B SIGHUP +signal. +.TP +.B LINUX_REBOOT_CMD_POWER_OFF +.TQ +.B LINUX_REBOOT_CMD_HALT +The "init" process is terminated, +and +.BR wait (2) +in the parent process reports that the child was killed with a +.B SIGINT +signal. +.P +For the other +.I op +values, +.BR reboot () +returns \-1 and +.I errno +is set to +.BR EINVAL . +.SH RETURN VALUE +For the values of +.I op +that stop or restart the system, +a successful call to +.BR reboot () +does not return. +For the other +.I op +values, zero is returned on success. +In all cases, \-1 is returned on failure, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Problem with getting user-space data under +.BR LINUX_REBOOT_CMD_RESTART2 . +.TP +.B EINVAL +Bad magic numbers or +.IR op . +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR reboot (); +the caller must have the +.B CAP_SYS_BOOT +inside its user namespace. +.SH STANDARDS +Linux. +.SH SEE ALSO +.BR systemctl (1), +.BR systemd (1), +.BR kexec_load (2), +.BR sync (2), +.BR bootparam (7), +.BR capabilities (7), +.BR ctrlaltdel (8), +.BR halt (8), +.BR shutdown (8) diff --git a/man/man2/recv.2 b/man/man2/recv.2 new file mode 100644 index 0000000..dac38eb --- /dev/null +++ b/man/man2/recv.2 @@ -0,0 +1,563 @@ +.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" $Id: recv.2,v 1.3 1999/05/13 11:33:38 freitag Exp $ +.\" +.\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith +.\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond +.\" Modified 1998,1999 by Andi Kleen +.\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin +.\" +.TH recv 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +recv, recvfrom, recvmsg \- receive a message from a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t recv(int " sockfd ", void " buf [. len "], size_t " len , +.BI " int " flags ); +.BI "ssize_t recvfrom(int " sockfd ", void " buf "[restrict ." len "], size_t " len , +.BI " int " flags , +.BI " struct sockaddr *_Nullable restrict " src_addr , +.BI " socklen_t *_Nullable restrict " addrlen ); +.BI "ssize_t recvmsg(int " sockfd ", struct msghdr *" msg ", int " flags ); +.fi +.SH DESCRIPTION +The +.BR recv (), +.BR recvfrom (), +and +.BR recvmsg () +calls are used to receive messages from a socket. +They may be used +to receive data on both connectionless and connection-oriented sockets. +This page first describes common features of all three system calls, +and then describes the differences between the calls. +.P +The only difference between +.BR recv () +and +.BR read (2) +is the presence of +.IR flags . +With a zero +.I flags +argument, +.BR recv () +is generally equivalent to +.BR read (2) +(but see NOTES). +Also, the following call +.P +.in +4n +.EX +recv(sockfd, buf, len, flags); +.EE +.in +.P +is equivalent to +.P +.in +4n +.EX +recvfrom(sockfd, buf, len, flags, NULL, NULL); +.EE +.in +.P +All three calls return the length of the message on successful +completion. +If a message is too long to fit in the supplied buffer, excess +bytes may be discarded depending on the type of socket the message is +received from. +.P +If no messages are available at the socket, the receive calls wait for a +message to arrive, unless the socket is nonblocking (see +.BR fcntl (2)), +in which case the value \-1 is returned and +.I errno +is set to +.BR EAGAIN " or " EWOULDBLOCK . +The receive calls normally return any data available, up to the requested +amount, rather than waiting for receipt of the full amount requested. +.P +An application can use +.BR select (2), +.BR poll (2), +or +.BR epoll (7) +to determine when more data arrives on a socket. +.SS The flags argument +The +.I flags +argument is formed by ORing one or more of the following values: +.TP +.BR MSG_CMSG_CLOEXEC " (" recvmsg "() only; since Linux 2.6.23)" +Set the close-on-exec flag for the file descriptor received +via a UNIX domain file descriptor using the +.B SCM_RIGHTS +operation (described in +.BR unix (7)). +This flag is useful for the same reasons as the +.B O_CLOEXEC +flag of +.BR open (2). +.TP +.BR MSG_DONTWAIT " (since Linux 2.2)" +Enables nonblocking operation; if the operation would block, +the call fails with the error +.BR EAGAIN " or " EWOULDBLOCK . +This provides similar behavior to setting the +.B O_NONBLOCK +flag (via the +.BR fcntl (2) +.B F_SETFL +operation), but differs in that +.B MSG_DONTWAIT +is a per-call option, whereas +.B O_NONBLOCK +is a setting on the open file description (see +.BR open (2)), +which will affect all threads in the calling process +as well as other processes that hold file descriptors +referring to the same open file description. +.TP +.BR MSG_ERRQUEUE " (since Linux 2.2)" +This flag +specifies that queued errors should be received from the socket error queue. +The error is passed in +an ancillary message with a type dependent on the protocol (for IPv4 +.BR IP_RECVERR ). +The user should supply a buffer of sufficient size. +See +.BR cmsg (3) +and +.BR ip (7) +for more information. +The payload of the original packet that caused the error +is passed as normal data via +.IR msg_iovec . +The original destination address of the datagram that caused the error +is supplied via +.IR msg_name . +.IP +The error is supplied in a +.I sock_extended_err +structure: +.IP +.in +4n +.EX +#define SO_EE_ORIGIN_NONE 0 +#define SO_EE_ORIGIN_LOCAL 1 +#define SO_EE_ORIGIN_ICMP 2 +#define SO_EE_ORIGIN_ICMP6 3 +\& +struct sock_extended_err +{ + uint32_t ee_errno; /* Error number */ + uint8_t ee_origin; /* Where the error originated */ + uint8_t ee_type; /* Type */ + uint8_t ee_code; /* Code */ + uint8_t ee_pad; /* Padding */ + uint32_t ee_info; /* Additional information */ + uint32_t ee_data; /* Other data */ + /* More data may follow */ +}; +\& +struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); +.EE +.in +.IP +.I ee_errno +contains the +.I errno +number of the queued error. +.I ee_origin +is the origin code of where the error originated. +The other fields are protocol-specific. +The macro +.B SO_EE_OFFENDER +returns a pointer to the address of the network object +where the error originated from given a pointer to the ancillary message. +If this address is not known, the +.I sa_family +member of the +.I sockaddr +contains +.B AF_UNSPEC +and the other fields of the +.I sockaddr +are undefined. +The payload of the packet that caused the error is passed as normal data. +.IP +For local errors, no address is passed (this +can be checked with the +.I cmsg_len +member of the +.IR cmsghdr ). +For error receives, +the +.B MSG_ERRQUEUE +flag is set in the +.IR msghdr . +After an error has been passed, the pending socket error +is regenerated based on the next queued error and will be passed +on the next socket operation. +.TP +.B MSG_OOB +This flag requests receipt of out-of-band data that would not be received +in the normal data stream. +Some protocols place expedited data +at the head of the normal data queue, and thus this flag cannot +be used with such protocols. +.TP +.B MSG_PEEK +This flag causes the receive operation to +return data from the beginning of the +receive queue without removing that data from the queue. +Thus, a +subsequent receive call will return the same data. +.TP +.BR MSG_TRUNC " (since Linux 2.2)" +For raw +.RB ( AF_PACKET ), +Internet datagram (since Linux 2.4.27/2.6.8), +netlink (since Linux 2.6.22), +and UNIX datagram as well as sequenced-packet +.\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f +(since Linux 3.4) sockets: +return the real length of the packet or datagram, +even when it was longer than the passed buffer. +.IP +For use with Internet stream sockets, see +.BR tcp (7). +.TP +.BR MSG_WAITALL " (since Linux 2.2)" +This flag requests that the operation block until the full request is +satisfied. +However, the call may still return less data than requested if +a signal is caught, an error or disconnect occurs, or the next data to be +received is of a different type than that returned. +This flag has no effect for datagram sockets. +.\" +.SS recvfrom() +.BR recvfrom () +places the received message into the buffer +.IR buf . +The caller must specify the size of the buffer in +.IR len . +.P +If +.I src_addr +is not NULL, +and the underlying protocol provides the source address of the message, +that source address is placed in the buffer pointed to by +.IR src_addr . +.\" (Note: for datagram sockets in both the UNIX and Internet domains, +.\" .I src_addr +.\" is filled in. +.\" .I src_addr +.\" is also filled in for stream sockets in the UNIX domain, but is not +.\" filled in for stream sockets in the Internet domain.) +.\" [The above notes on AF_UNIX and AF_INET sockets apply as at +.\" Kernel 2.4.18. (MTK, 22 Jul 02)] +In this case, +.I addrlen +is a value-result argument. +Before the call, +it should be initialized to the size of the buffer associated with +.IR src_addr . +Upon return, +.I addrlen +is updated to contain the actual size of the source address. +The returned address is truncated if the buffer provided is too small; +in this case, +.I addrlen +will return a value greater than was supplied to the call. +.P +If the caller is not interested in the source address, +.I src_addr +and +.I addrlen +should be specified as NULL. +.\" +.SS recv() +The +.BR recv () +call is normally used only on a +.I connected +socket (see +.BR connect (2)). +It is equivalent to the call: +.P +.in +4n +.EX +recvfrom(fd, buf, len, flags, NULL, 0); +.EE +.in +.\" +.SS recvmsg() +The +.BR recvmsg () +call uses a +.I msghdr +structure to minimize the number of directly supplied arguments. +This structure is defined as follows in +.IR : +.P +.in +4n +.EX +struct msghdr { + void *msg_name; /* Optional address */ + socklen_t msg_namelen; /* Size of address */ + struct iovec *msg_iov; /* Scatter/gather array */ + size_t msg_iovlen; /* # elements in msg_iov */ + void *msg_control; /* Ancillary data, see below */ + size_t msg_controllen; /* Ancillary data buffer len */ + int msg_flags; /* Flags on received message */ +}; +.EE +.in +.P +The +.I msg_name +field points to a caller-allocated buffer that is used to +return the source address if the socket is unconnected. +The caller should set +.I msg_namelen +to the size of this buffer before this call; +upon return from a successful call, +.I msg_namelen +will contain the length of the returned address. +If the application does not need to know the source address, +.I msg_name +can be specified as NULL. +.P +The fields +.I msg_iov +and +.I msg_iovlen +describe scatter-gather locations, as discussed in +.BR readv (2). +.P +The field +.IR msg_control , +which has length +.IR msg_controllen , +points to a buffer for other protocol control-related messages or +miscellaneous ancillary data. +When +.BR recvmsg () +is called, +.I msg_controllen +should contain the length of the available buffer in +.IR msg_control ; +upon return from a successful call it will contain the length +of the control message sequence. +.P +The messages are of the form: +.P +.in +4n +.EX +struct cmsghdr { + size_t cmsg_len; /* Data byte count, including header + (type is socklen_t in POSIX) */ + int cmsg_level; /* Originating protocol */ + int cmsg_type; /* Protocol\-specific type */ +/* followed by + unsigned char cmsg_data[]; */ +}; +.EE +.in +.P +Ancillary data should be accessed only by the macros defined in +.BR cmsg (3). +.P +As an example, Linux uses this ancillary data mechanism to pass extended +errors, IP options, or file descriptors over UNIX domain sockets. +For further information on the use of ancillary data in various +socket domains, see +.BR unix (7) +and +.BR ip (7). +.P +The +.I msg_flags +field in the +.I msghdr +is set on return of +.BR recvmsg (). +It can contain several flags: +.TP +.B MSG_EOR +indicates end-of-record; the data returned completed a record (generally +used with sockets of type +.BR SOCK_SEQPACKET ). +.TP +.B MSG_TRUNC +indicates that the trailing portion of a datagram was discarded because the +datagram was larger than the buffer supplied. +.TP +.B MSG_CTRUNC +indicates that some control data was discarded due to lack of space in the +buffer for ancillary data. +.TP +.B MSG_OOB +is returned to indicate that expedited or out-of-band data was received. +.TP +.B MSG_ERRQUEUE +indicates that no data was received but an extended error from the socket +error queue. +.TP +.BR MSG_CMSG_CLOEXEC " (since Linux 2.6.23)" +.\" commit 4a19542e5f694cd408a32c3d9dc593ba9366e2d7 +indicates that +.B MSG_CMSG_CLOEXEC +was specified in the +.I flags +argument of +.BR recvmsg (). +.SH RETURN VALUE +These calls return the number of bytes received, or \-1 +if an error occurred. +In the event of an error, +.I errno +is set to indicate the error. +.P +When a stream socket peer has performed an orderly shutdown, +the return value will be 0 (the traditional "end-of-file" return). +.P +Datagram sockets in various domains (e.g., the UNIX and Internet domains) +permit zero-length datagrams. +When such a datagram is received, the return value is 0. +.P +The value 0 may also be returned if the requested number of bytes +to receive from a stream socket was 0. +.SH ERRORS +These are some standard errors generated by the socket layer. +Additional errors +may be generated and returned from the underlying protocol modules; +see their manual pages. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.\" Actually EAGAIN on Linux +The socket is marked nonblocking and the receive operation +would block, or a receive timeout had been set and the timeout expired +before data was received. +POSIX.1 allows either error to be returned for this case, +and does not require these constants to have the same value, +so a portable application should check for both possibilities. +.TP +.B EBADF +The argument +.I sockfd +is an invalid file descriptor. +.TP +.B ECONNREFUSED +A remote host refused to allow the network connection (typically +because it is not running the requested service). +.TP +.B EFAULT +The receive buffer pointer(s) point outside the process's +address space. +.TP +.B EINTR +The receive was interrupted by delivery of a signal before +any data was available; see +.BR signal (7). +.TP +.B EINVAL +Invalid argument passed. +.\" e.g., msg_namelen < 0 for recvmsg() or addrlen < 0 for recvfrom() +.TP +.B ENOMEM +Could not allocate memory for +.BR recvmsg (). +.TP +.B ENOTCONN +The socket is associated with a connection-oriented protocol +and has not been connected (see +.BR connect (2) +and +.BR accept (2)). +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.SH VERSIONS +According to POSIX.1, +.\" POSIX.1-2001, POSIX.1-2008 +the +.I msg_controllen +field of the +.I msghdr +structure should be typed as +.IR socklen_t , +and the +.I msg_iovlen +field should be typed as +.IR int , +but glibc currently types both as +.IR size_t . +.\" glibc bug for msg_controllen raised 12 Mar 2006 +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 +.\" The problem is an underlying kernel issue: the size of the +.\" __kernel_size_t type used to type these fields varies +.\" across architectures, but socklen_t is always 32 bits, +.\" as (at least with GCC) is int. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, +4.4BSD (first appeared in 4.2BSD). +.P +POSIX.1 describes only the +.BR MSG_OOB , +.BR MSG_PEEK , +and +.B MSG_WAITALL +flags. +.SH NOTES +If a zero-length datagram is pending, +.BR read (2) +and +.BR recv () +with a +.I flags +argument of zero provide different behavior. +In this circumstance, +.BR read (2) +has no effect (the datagram remains pending), while +.BR recv () +consumes the pending datagram. +.P +See +.BR recvmmsg (2) +for information about a Linux-specific system call +that can be used to receive multiple datagrams in a single call. +.SH EXAMPLES +An example of the use of +.BR recvfrom () +is shown in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR fcntl (2), +.BR getsockopt (2), +.BR read (2), +.BR recvmmsg (2), +.BR select (2), +.BR shutdown (2), +.BR socket (2), +.BR cmsg (3), +.BR sockatmark (3), +.BR ip (7), +.BR ipv6 (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) diff --git a/man/man2/recvfrom.2 b/man/man2/recvfrom.2 new file mode 100644 index 0000000..13228c3 --- /dev/null +++ b/man/man2/recvfrom.2 @@ -0,0 +1 @@ +.so man2/recv.2 diff --git a/man/man2/recvmmsg.2 b/man/man2/recvmmsg.2 new file mode 100644 index 0000000..f621a56 --- /dev/null +++ b/man/man2/recvmmsg.2 @@ -0,0 +1,276 @@ +.\" Copyright (C) 2011 by Andi Kleen +.\" and Copyright (c) 2011 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Syscall added in following commit +.\" commit a2e2725541fad72416326798c2d7fa4dafb7d337 +.\" Author: Arnaldo Carvalho de Melo +.\" Date: Mon Oct 12 23:40:10 2009 -0700 +.\" +.TH recvmmsg 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +recvmmsg \- receive multiple messages on a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int recvmmsg(int " sockfd ", struct mmsghdr *" msgvec \ +", unsigned int " vlen "," +.BI " int " flags ", struct timespec *" timeout ");" +.fi +.SH DESCRIPTION +The +.BR recvmmsg () +system call is an extension of +.BR recvmsg (2) +that allows the caller to receive multiple messages from a socket +using a single system call. +(This has performance benefits for some applications.) +A further extension over +.BR recvmsg (2) +is support for a timeout on the receive operation. +.P +The +.I sockfd +argument is the file descriptor of the socket to receive data from. +.P +The +.I msgvec +argument is a pointer to an array of +.I mmsghdr +structures. +The size of this array is specified in +.IR vlen . +.P +The +.I mmsghdr +structure is defined in +.I +as: +.P +.in +4n +.EX +struct mmsghdr { + struct msghdr msg_hdr; /* Message header */ + unsigned int msg_len; /* Number of received bytes for header */ +}; +.EE +.in +.P +The +.I msg_hdr +field is a +.I msghdr +structure, as described in +.BR recvmsg (2). +The +.I msg_len +field is the number of bytes returned for the message in the entry. +This field has the same value as the return value of a single +.BR recvmsg (2) +on the header. +.P +The +.I flags +argument contains flags ORed together. +The flags are the same as documented for +.BR recvmsg (2), +with the following addition: +.TP +.BR MSG_WAITFORONE " (since Linux 2.6.34)" +Turns on +.B MSG_DONTWAIT +after the first message has been received. +.P +The +.I timeout +argument points to a +.I struct timespec +(see +.BR clock_gettime (2)) +defining a timeout (seconds plus nanoseconds) for the receive operation +.RI ( "but see BUGS!" ). +(This interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the blocking interval +may overrun by a small amount.) +If +.I timeout +is NULL, then the operation blocks indefinitely. +.P +A blocking +.BR recvmmsg () +call blocks until +.I vlen +messages have been received +or until the timeout expires. +A nonblocking call reads as many messages as are available +(up to the limit specified by +.IR vlen ) +and returns immediately. +.P +On return from +.BR recvmmsg (), +successive elements of +.I msgvec +are updated to contain information about each received message: +.I msg_len +contains the size of the received message; +the subfields of +.I msg_hdr +are updated as described in +.BR recvmsg (2). +The return value of the call indicates the number of elements of +.I msgvec +that have been updated. +.SH RETURN VALUE +On success, +.BR recvmmsg () +returns the number of messages received in +.IR msgvec ; +on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Errors are as for +.BR recvmsg (2). +In addition, the following error can occur: +.TP +.B EINVAL +.I timeout +is invalid. +.P +See also BUGS. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.33, +glibc 2.12. +.SH BUGS +The +.I timeout +argument does not work as intended. +.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=75371 +.\" http://thread.gmane.org/gmane.linux.man/5677 +The timeout is checked only after the receipt of each datagram, +so that if up to +.I vlen\-1 +datagrams are received before the timeout expires, +but then no further datagrams are received, the call will block forever. +.P +If an error occurs after at least one message has been received, +the call succeeds, and returns the number of messages received. +The error code is expected to be returned on a subsequent call to +.BR recvmmsg (). +In the current implementation, however, the error code can be overwritten +in the meantime by an unrelated network event on a socket, +for example an incoming ICMP packet. +.SH EXAMPLES +The following program uses +.BR recvmmsg () +to receive multiple messages on a socket and stores +them in multiple buffers. +The call returns if all buffers are filled or if the +timeout specified has expired. +.P +The following snippet periodically generates UDP datagrams +containing a random number: +.P +.in +4n +.EX +.RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234;" +.B " sleep 0.25; done" +.EE +.in +.P +These datagrams are read by the example application, which +can give the following output: +.P +.in +4n +.EX +.RB "$" " ./a.out" +5 messages received +1 11782 +2 11345 +3 304 +4 13514 +5 28421 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (recvmmsg.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +\& +int +main(void) +{ +#define VLEN 10 +#define BUFSIZE 200 +#define TIMEOUT 1 + int sockfd, retval; + char bufs[VLEN][BUFSIZE+1]; + struct iovec iovecs[VLEN]; + struct mmsghdr msgs[VLEN]; + struct timespec timeout; + struct sockaddr_in addr; +\& + sockfd = socket(AF_INET, SOCK_DGRAM, 0); + if (sockfd == \-1) { + perror("socket()"); + exit(EXIT_FAILURE); + } +\& + addr.sin_family = AF_INET; + addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK); + addr.sin_port = htons(1234); + if (bind(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) { + perror("bind()"); + exit(EXIT_FAILURE); + } +\& + memset(msgs, 0, sizeof(msgs)); + for (size_t i = 0; i < VLEN; i++) { + iovecs[i].iov_base = bufs[i]; + iovecs[i].iov_len = BUFSIZE; + msgs[i].msg_hdr.msg_iov = &iovecs[i]; + msgs[i].msg_hdr.msg_iovlen = 1; + } +\& + timeout.tv_sec = TIMEOUT; + timeout.tv_nsec = 0; +\& + retval = recvmmsg(sockfd, msgs, VLEN, 0, &timeout); + if (retval == \-1) { + perror("recvmmsg()"); + exit(EXIT_FAILURE); + } +\& + printf("%d messages received\en", retval); + for (size_t i = 0; i < retval; i++) { + bufs[i][msgs[i].msg_len] = 0; + printf("%zu %s", i+1, bufs[i]); + } + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clock_gettime (2), +.BR recvmsg (2), +.BR sendmmsg (2), +.BR sendmsg (2), +.BR socket (2), +.BR socket (7) diff --git a/man/man2/recvmsg.2 b/man/man2/recvmsg.2 new file mode 100644 index 0000000..13228c3 --- /dev/null +++ b/man/man2/recvmsg.2 @@ -0,0 +1 @@ +.so man2/recv.2 diff --git a/man/man2/remap_file_pages.2 b/man/man2/remap_file_pages.2 new file mode 100644 index 0000000..3caf9af --- /dev/null +++ b/man/man2/remap_file_pages.2 @@ -0,0 +1,170 @@ +.\" Copyright (C) 2003, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2003-12-10 Initial creation, Michael Kerrisk +.\" 2004-10-28 aeb, corrected prototype, prot must be 0 +.\" +.TH remap_file_pages 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +remap_file_pages \- create a nonlinear file mapping +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "[[deprecated]] int remap_file_pages(void " addr [. size "], size_t " size , +.BI " int " prot ", size_t " pgoff ", \ +int " flags ); +.fi +.SH DESCRIPTION +.BR Note : +.\" commit 33041a0d76d3c3e0aff28ac95a2ffdedf1282dbc +.\" http://lwn.net/Articles/597632/ +this system call was marked as deprecated starting with Linux 3.16. +In Linux 4.0, the implementation was replaced +.\" commit c8d78c1823f46519473949d33f0d1d33fe21ea16 +by a slower in-kernel emulation. +Those few applications that use this system call should +consider migrating to alternatives. +This change was made because the kernel code for this system call was complex, +and it is believed to be little used or perhaps even completely unused. +While it had some use cases in database applications on 32-bit systems, +those use cases don't exist on 64-bit systems. +.P +The +.BR remap_file_pages () +system call is used to create a nonlinear mapping, that is, a mapping +in which the pages of the file are mapped into a nonsequential order +in memory. +The advantage of using +.BR remap_file_pages () +over using repeated calls to +.BR mmap (2) +is that the former approach does not require the kernel to create +additional VMA (Virtual Memory Area) data structures. +.P +To create a nonlinear mapping we perform the following steps: +.TP 3 +1. +Use +.BR mmap (2) +to create a mapping (which is initially linear). +This mapping must be created with the +.B MAP_SHARED +flag. +.TP +2. +Use one or more calls to +.BR remap_file_pages () +to rearrange the correspondence between the pages of the mapping +and the pages of the file. +It is possible to map the same page of a file +into multiple locations within the mapped region. +.P +The +.I pgoff +and +.I size +arguments specify the region of the file that is to be relocated +within the mapping: +.I pgoff +is a file offset in units of the system page size; +.I size +is the length of the region in bytes. +.P +The +.I addr +argument serves two purposes. +First, it identifies the mapping whose pages we want to rearrange. +Thus, +.I addr +must be an address that falls within +a region previously mapped by a call to +.BR mmap (2). +Second, +.I addr +specifies the address at which the file pages +identified by +.I pgoff +and +.I size +will be placed. +.P +The values specified in +.I addr +and +.I size +should be multiples of the system page size. +If they are not, then the kernel rounds +.I both +values +.I down +to the nearest multiple of the page size. +.\" This rounding is weird, and not consistent with the treatment of +.\" the analogous arguments for munmap()/mprotect() and for mlock(). +.\" MTK, 14 Sep 2005 +.P +The +.I prot +argument must be specified as 0. +.P +The +.I flags +argument has the same meaning as for +.BR mmap (2), +but all flags other than +.B MAP_NONBLOCK +are ignored. +.SH RETURN VALUE +On success, +.BR remap_file_pages () +returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I addr +does not refer to a valid mapping +created with the +.B MAP_SHARED +flag. +.TP +.B EINVAL +.IR addr , +.IR size , +.IR prot , +or +.I pgoff +is invalid. +.\" And possibly others from vma->vm_ops->populate() +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5.46, +glibc 2.3.3. +.SH NOTES +Since Linux 2.6.23, +.\" commit 3ee6dafc677a68e461a7ddafc94a580ebab80735 +.BR remap_file_pages () +creates non-linear mappings only +on in-memory filesystems such as +.BR tmpfs (5), +hugetlbfs or ramfs. +On filesystems with a backing store, +.BR remap_file_pages () +is not much more efficient than using +.BR mmap (2) +to adjust which parts of the file are mapped to which addresses. +.SH SEE ALSO +.BR getpagesize (2), +.BR mmap (2), +.BR mmap2 (2), +.BR mprotect (2), +.BR mremap (2), +.BR msync (2) diff --git a/man/man2/removexattr.2 b/man/man2/removexattr.2 new file mode 100644 index 0000000..dc32898 --- /dev/null +++ b/man/man2/removexattr.2 @@ -0,0 +1,100 @@ +.\" Copyright (C) Andreas Gruenbacher, February 2001 +.\" Copyright (C) Silicon Graphics Inc, September 2001 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH removexattr 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +removexattr, lremovexattr, fremovexattr \- remove an extended attribute +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int removexattr(const char *" path ", const char *" name ); +.BI "int lremovexattr(const char *" path ", const char *" name ); +.BI "int fremovexattr(int " fd ", const char *" name ); +.fi +.SH DESCRIPTION +Extended attributes are +.IR name : value +pairs associated with inodes (files, directories, symbolic links, etc.). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e., the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR xattr (7). +.P +.BR removexattr () +removes the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +.P +.BR lremovexattr () +is identical to +.BR removexattr (), +except in the case of a symbolic link, where the extended attribute is +removed from the link itself, not the file that it refers to. +.P +.BR fremovexattr () +is identical to +.BR removexattr (), +only the extended attribute is removed from the open file referred to by +.I fd +(as returned by +.BR open (2)) +in place of +.IR path . +.P +An extended attribute name is a null-terminated string. +The +.I name +includes a namespace prefix; there may be several, disjoint +namespaces associated with an individual inode. +.SH RETURN VALUE +On success, zero is returned. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENODATA +The named attribute does not exist. +.\" .RB ( ENOATTR +.\" is defined to be a synonym for +.\" .BR ENODATA +.\" in +.\" .IR .) +.TP +.B ENOTSUP +Extended attributes are not supported by the filesystem, or are disabled. +.P +In addition, the errors documented in +.BR stat (2) +can also occur. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.4, +glibc 2.3. +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@computer.org > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.\" Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR listxattr (2), +.BR open (2), +.BR setxattr (2), +.BR stat (2), +.BR symlink (7), +.BR xattr (7) diff --git a/man/man2/rename.2 b/man/man2/rename.2 new file mode 100644 index 0000000..1ab88ba --- /dev/null +++ b/man/man2/rename.2 @@ -0,0 +1,549 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt; +.\" and Copyright (C) 1993,1995 Ian Jackson +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 00:35:52 1993 by Rik Faith +.\" Modified Thu Jun 4 12:21:13 1998 by Andries Brouwer +.\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt +.\" 2007-03-25, mtk, added various text to DESCRIPTION. +.\" +.TH rename 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rename, renameat, renameat2 \- change the name or location of a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int rename(const char *" oldpath ", const char *" newpath ); +.P +.BR "#include " "/* Definition of " AT_* " constants */" +.B #include +.P +.BI "int renameat(int " olddirfd ", const char *" oldpath , +.BI " int " newdirfd ", const char *" newpath ); +.BI "int renameat2(int " olddirfd ", const char *" oldpath , +.BI " int " newdirfd ", const char *" newpath \ +", unsigned int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.nf +.BR renameat (): + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.P +.BR renameat2 (): + _GNU_SOURCE +.fi +.SH DESCRIPTION +.BR rename () +renames a file, moving it between directories if required. +Any other hard links to the file (as created using +.BR link (2)) +are unaffected. +Open file descriptors for +.I oldpath +are also unaffected. +.P +Various restrictions determine whether or not the rename operation succeeds: +see ERRORS below. +.P +If +.I newpath +already exists, it will be atomically replaced, so that there is +no point at which another process attempting to access +.I newpath +will find it missing. +However, there will probably be a window in which both +.I oldpath +and +.I newpath +refer to the file being renamed. +.P +If +.I oldpath +and +.I newpath +are existing hard links referring to the same file, then +.BR rename () +does nothing, and returns a success status. +.P +If +.I newpath +exists but the operation fails for some reason, +.BR rename () +guarantees to leave an instance of +.I newpath +in place. +.P +.I oldpath +can specify a directory. +In this case, +.I newpath +must either not exist, or it must specify an empty directory. +.P +If +.I oldpath +refers to a symbolic link, the link is renamed; if +.I newpath +refers to a symbolic link, the link will be overwritten. +.SS renameat() +The +.BR renameat () +system call operates in exactly the same way as +.BR rename (), +except for the differences described here. +.P +If the pathname given in +.I oldpath +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I olddirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR rename () +for a relative pathname). +.P +If +.I oldpath +is relative and +.I olddirfd +is the special value +.BR AT_FDCWD , +then +.I oldpath +is interpreted relative to the current working +directory of the calling process (like +.BR rename ()). +.P +If +.I oldpath +is absolute, then +.I olddirfd +is ignored. +.P +The interpretation of +.I newpath +is as for +.IR oldpath , +except that a relative pathname is interpreted relative +to the directory referred to by the file descriptor +.IR newdirfd . +.P +See +.BR openat (2) +for an explanation of the need for +.BR renameat (). +.SS renameat2() +.BR renameat2 () +has an additional +.I flags +argument. +A +.BR renameat2 () +call with a zero +.I flags +argument is equivalent to +.BR renameat (). +.P +The +.I flags +argument is a bit mask consisting of zero or more of the following flags: +.TP +.B RENAME_EXCHANGE +Atomically exchange +.I oldpath +and +.IR newpath . +Both pathnames must exist +but may be of different types (e.g., one could be a non-empty directory +and the other a symbolic link). +.TP +.B RENAME_NOREPLACE +Don't overwrite +.I newpath +of the rename. +Return an error if +.I newpath +already exists. +.IP +.B RENAME_NOREPLACE +can't be employed together with +.BR RENAME_EXCHANGE . +.IP +.B RENAME_NOREPLACE +requires support from the underlying filesystem. +Support for various filesystems was added as follows: +.RS +.IP \[bu] 3 +ext4 (Linux 3.15); +.\" ext4: commit 0a7c3937a1f23f8cb5fc77ae01661e9968a51d0c +.IP \[bu] +btrfs, tmpfs, and cifs (Linux 3.17); +.IP \[bu] +xfs (Linux 4.0); +.\" btrfs: commit 80ace85c915d0f41016f82917218997b72431258 +.\" tmpfs: commit 3b69ff51d087d265aa4af3a532fc4f20bf33e718 +.\" cifs: commit 7c33d5972ce382bcc506d16235f1e9b7d22cbef8 +.\" +.\" gfs2 in Linux 4.2? +.IP \[bu] +Support for many other filesystems was added in Linux 4.9, including +ext2, minix, reiserfs, jfs, vfat, and bpf. +.\" Also affs, bfs, exofs, hfs, hfsplus, jffs2, logfs, msdos, +.\" nilfs2, omfs, sysvfs, ubifs, udf, ufs +.\" hugetlbfs, ramfs +.\" local filesystems: commit f03b8ad8d38634d13e802165cc15917481b47835 +.\" libfs: commit e0e0be8a835520e2f7c89f214dfda570922a1b90 +.RE +.TP +.BR RENAME_WHITEOUT " (since Linux 3.18)" +.\" commit 0d7a855526dd672e114aff2ac22b60fc6f155b08 +.\" commit 787fb6bc9682ec7c05fb5d9561b57100fbc1cc41 +This operation makes sense only for overlay/union +filesystem implementations. +.IP +Specifying +.B RENAME_WHITEOUT +creates a "whiteout" object at the source of +the rename at the same time as performing the rename. +The whole operation is atomic, +so that if the rename succeeds then the whiteout will also have been created. +.IP +A "whiteout" is an object that has special meaning in union/overlay +filesystem constructs. +In these constructs, +multiple layers exist and only the top one is ever modified. +A whiteout on an upper layer will effectively hide a +matching file in the lower layer, +making it appear as if the file didn't exist. +.IP +When a file that exists on the lower layer is renamed, +the file is first copied up (if not already on the upper layer) +and then renamed on the upper, read-write layer. +At the same time, the source file needs to be "whiteouted" +(so that the version of the source file in the lower layer +is rendered invisible). +The whole operation needs to be done atomically. +.IP +When not part of a union/overlay, +the whiteout appears as a character device with a {0,0} device number. +.\" https://www.freebsd.org/cgi/man.cgi?query=mount_unionfs&manpath=FreeBSD+11.0-RELEASE +(Note that other union/overlay implementations may employ different methods +for storing whiteout entries; specifically, BSD union mount employs +a separate inode type, +.BR DT_WHT , +which, while supported by some filesystems available in Linux, +such as CODA and XFS, is ignored by the kernel's whiteout support code, +as of Linux 4.19, at least.) +.IP +.B RENAME_WHITEOUT +requires the same privileges as creating a device node (i.e., the +.B CAP_MKNOD +capability). +.IP +.B RENAME_WHITEOUT +can't be employed together with +.BR RENAME_EXCHANGE . +.IP +.B RENAME_WHITEOUT +requires support from the underlying filesystem. +Among the filesystems that support it are +tmpfs (since Linux 3.18), +.\" tmpfs: commit 46fdb794e3f52ef18b859ebc92f0a9d7db21c5df +ext4 (since Linux 3.18), +.\" ext4: commit cd808deced431b66b5fa4e5c193cb7ec0059eaff +XFS (since Linux 4.1), +.\" XFS: commit 7dcf5c3e4527cfa2807567b00387cf2ed5e07f00 +f2fs (since Linux 4.2), +.\" f2fs: commit 7e01e7ad746bc8198a8b46163ddc73a1c7d22339 +btrfs (since Linux 4.7), +.\" btrfs: commit cdd1fedf8261cd7a73c0596298902ff4f0f04492 +and ubifs (since Linux 4.9). +.\" ubifs: commit 9e0a1fff8db56eaaebb74b4a3ef65f86811c4798 +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Write permission is denied for the directory containing +.I oldpath +or +.IR newpath , +or, search permission is denied for one of the directories +in the path prefix of +.I oldpath +or +.IR newpath , +or +.I oldpath +is a directory and does not allow write permission (needed to update +the +.I .. +entry). +(See also +.BR path_resolution (7).) +.TP +.B EBUSY +The rename fails because +.IR oldpath " or " newpath +is a directory that is in use by some process (perhaps as +current working directory, or as root directory, or because +it was open for reading) or is in use by the system +(for example as a mount point), while the system considers +this an error. +(Note that there is no requirement to return +.B EBUSY +in such +cases\[em]there is nothing wrong with doing the rename anyway\[em]but +it is allowed to return +.B EBUSY +if the system cannot otherwise +handle such situations.) +.TP +.B EDQUOT +The user's quota of disk blocks on the filesystem has been exhausted. +.TP +.B EFAULT +.IR oldpath " or " newpath " points outside your accessible address space." +.TP +.B EINVAL +The new pathname contained a path prefix of the old, or, more generally, +an attempt was made to make a directory a subdirectory of itself. +.TP +.B EISDIR +.I newpath +is an existing directory, but +.I oldpath +is not a directory. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR oldpath " or " newpath . +.TP +.B EMLINK +.I oldpath +already has the maximum number of links to it, or +it was a directory and the directory containing +.I newpath +has the maximum number of links. +.TP +.B ENAMETOOLONG +.IR oldpath " or " newpath " was too long." +.TP +.B ENOENT +The link named by +.I oldpath +does not exist; +or, a directory component in +.I newpath +does not exist; +or, +.I oldpath +or +.I newpath +is an empty string. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing the file has no room for the new directory +entry. +.TP +.B ENOTDIR +A component used as a directory in +.IR oldpath " or " newpath +is not, in fact, a directory. +Or, +.I oldpath +is a directory, and +.I newpath +exists but is not a directory. +.TP +.BR ENOTEMPTY " or " EEXIST +.I newpath +is a nonempty directory, that is, contains entries other than "." and "..". +.TP +.BR EPERM " or " EACCES +The directory containing +.I oldpath +has the sticky bit +.RB ( S_ISVTX ) +set and the process's effective user ID is neither +the user ID of the file to be deleted nor that of the directory +containing it, and the process is not privileged +(Linux: does not have the +.B CAP_FOWNER +capability); +or +.I newpath +is an existing file and the directory containing it has the sticky bit set +and the process's effective user ID is neither the user ID of the file +to be replaced nor that of the directory containing it, +and the process is not privileged +(Linux: does not have the +.B CAP_FOWNER +capability); +or the filesystem containing +.I oldpath +does not support renaming of the type requested. +.TP +.B EROFS +The file is on a read-only filesystem. +.TP +.B EXDEV +.IR oldpath " and " newpath +are not on the same mounted filesystem. +(Linux permits a filesystem to be mounted at multiple points, but +.BR rename () +does not work across different mount points, +even if the same filesystem is mounted on both.) +.P +The following additional errors can occur for +.BR renameat () +and +.BR renameat2 (): +.TP +.B EBADF +.I oldpath +.RI ( newpath ) +is relative but +.I olddirfd +.RI ( newdirfd ) +is not a valid file descriptor. +.TP +.B ENOTDIR +.I oldpath +is relative and +.I olddirfd +is a file descriptor referring to a file other than a directory; +or similar for +.I newpath +and +.I newdirfd +.P +The following additional errors can occur for +.BR renameat2 (): +.TP +.B EEXIST +.I flags +contains +.B RENAME_NOREPLACE +and +.I newpath +already exists. +.TP +.B EINVAL +An invalid flag was specified in +.IR flags . +.TP +.B EINVAL +Both +.B RENAME_NOREPLACE +and +.B RENAME_EXCHANGE +were specified in +.IR flags . +.TP +.B EINVAL +Both +.B RENAME_WHITEOUT +and +.B RENAME_EXCHANGE +were specified in +.IR flags . +.TP +.B EINVAL +The filesystem does not support one of the flags in +.IR flags . +.TP +.B ENOENT +.I flags +contains +.B RENAME_EXCHANGE +and +.I newpath +does not exist. +.TP +.B EPERM +.B RENAME_WHITEOUT +was specified in +.IR flags , +but the caller does not have the +.B CAP_MKNOD +capability. +.SH STANDARDS +.TP +.BR rename () +C11, POSIX.1-2008. +.TP +.BR renameat () +POSIX.1-2008. +.TP +.BR renameat2 () +Linux. +.SH HISTORY +.TP +.BR rename () +4.3BSD, C89, POSIX.1-2001. +.TP +.BR renameat () +Linux 2.6.16, +glibc 2.4. +.TP +.BR renameat2 () +Linux 3.15, +glibc 2.28. +.SS glibc notes +On older kernels where +.BR renameat () +is unavailable, the glibc wrapper function falls back to the use of +.BR rename (). +When +.I oldpath +and +.I newpath +are relative pathnames, +glibc constructs pathnames based on the symbolic links in +.I /proc/self/fd +that correspond to the +.I olddirfd +and +.I newdirfd +arguments. +.SH BUGS +On NFS filesystems, you can not assume that if the operation +failed, the file was not renamed. +If the server does the rename operation +and then crashes, the retransmitted RPC which will be processed when the +server is up again causes a failure. +The application is expected to +deal with this. +See +.BR link (2) +for a similar problem. +.SH SEE ALSO +.BR mv (1), +.BR rename (1), +.BR chmod (2), +.BR link (2), +.BR symlink (2), +.BR unlink (2), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/renameat.2 b/man/man2/renameat.2 new file mode 100644 index 0000000..9b74442 --- /dev/null +++ b/man/man2/renameat.2 @@ -0,0 +1 @@ +.so man2/rename.2 diff --git a/man/man2/renameat2.2 b/man/man2/renameat2.2 new file mode 100644 index 0000000..9b74442 --- /dev/null +++ b/man/man2/renameat2.2 @@ -0,0 +1 @@ +.so man2/rename.2 diff --git a/man/man2/request_key.2 b/man/man2/request_key.2 new file mode 100644 index 0000000..9ad563b --- /dev/null +++ b/man/man2/request_key.2 @@ -0,0 +1,562 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH request_key 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +request_key \- request a key from the kernel's key management facility +.SH LIBRARY +Linux Key Management Utilities +.RI ( libkeyutils ", " \-lkeyutils ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "key_serial_t request_key(const char *" type ", const char *" description , +.BI " const char *_Nullable " callout_info , +.BI " key_serial_t " dest_keyring ); +.fi +.SH DESCRIPTION +.BR request_key () +attempts to find a key of the given +.I type +with a description (name) that matches the specified +.IR description . +If such a key could not be found, then the key is optionally created. +If the key is found or created, +.BR request_key () +attaches it to the keyring whose ID is specified in +.I dest_keyring +and returns the key's serial number. +.P +.BR request_key () +first recursively searches for a matching key in all of the keyrings +attached to the calling process. +The keyrings are searched in the order: thread-specific keyring, +process-specific keyring, and then session keyring. +.P +If +.BR request_key () +is called from a program invoked by +.BR request_key () +on behalf of some other process to generate a key, then the keyrings of that +other process will be searched next, +using that other process's user ID, group ID, +supplementary group IDs, and security context to determine access. +.\" David Howells: we can then have an arbitrarily long sequence +.\" of "recursive" request-key upcalls. There is no limit, other +.\" than number of PIDs, etc. +.P +The search of the keyring tree is breadth-first: +the keys in each keyring searched are checked for a match before any child +keyrings are recursed into. +Only keys for which the caller has +.I search +permission be found, and only keyrings for which the caller has +.I search +permission may be searched. +.P +If the key is not found and +.I callout +is NULL, then the call fails with the error +.BR ENOKEY . +.P +If the key is not found and +.I callout +is not NULL, then the kernel attempts to invoke a user-space +program to instantiate the key. +The details are given below. +.P +The +.I dest_keyring +serial number may be that of a valid keyring for which the caller has +.I write +permission, or it may be one of the following special keyring IDs: +.TP +.B KEY_SPEC_THREAD_KEYRING +This specifies the caller's thread-specific keyring (see +.BR thread\-keyring (7)). +.TP +.B KEY_SPEC_PROCESS_KEYRING +This specifies the caller's process-specific keyring (see +.BR process\-keyring (7)). +.TP +.B KEY_SPEC_SESSION_KEYRING +This specifies the caller's session-specific keyring (see +.BR session\-keyring (7)). +.TP +.B KEY_SPEC_USER_KEYRING +This specifies the caller's UID-specific keyring (see +.BR user\-keyring (7)). +.TP +.B KEY_SPEC_USER_SESSION_KEYRING +This specifies the caller's UID-session keyring (see +.BR user\-session\-keyring (7)). +.P +When the +.I dest_keyring +is specified as 0 +and no key construction has been performed, +then no additional linking is done. +.P +Otherwise, if +.I dest_keyring +is 0 and a new key is constructed, the new key will be linked +to the "default" keyring. +More precisely, when the kernel tries to determine to which keyring the +newly constructed key should be linked, +it tries the following keyrings, +beginning with the keyring set via the +.BR keyctl (2) +.B KEYCTL_SET_REQKEY_KEYRING +operation and continuing in the order shown below +until it finds the first keyring that exists: +.IP \[bu] 3 +.\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 +The requestor keyring +.RB ( KEY_REQKEY_DEFL_REQUESTOR_KEYRING , +since Linux 2.6.29). +.\" FIXME +.\" Actually, is the preceding point correct? +.\" If I understand correctly, we'll only get here if +.\" 'dest_keyring' is zero, in which case KEY_REQKEY_DEFL_REQUESTOR_KEYRING +.\" won't refer to a keyring. Have I misunderstood? +.IP \[bu] +The thread-specific keyring +.RB ( KEY_REQKEY_DEFL_THREAD_KEYRING ; +see +.BR thread\-keyring (7)). +.IP \[bu] +The process-specific keyring +.RB ( KEY_REQKEY_DEFL_PROCESS_KEYRING ; +see +.BR process\-keyring (7)). +.IP \[bu] +The session-specific keyring +.RB ( KEY_REQKEY_DEFL_SESSION_KEYRING ; +see +.BR session\-keyring (7)). +.IP \[bu] +The session keyring for the process's user ID +.RB ( KEY_REQKEY_DEFL_USER_SESSION_KEYRING ; +see +.BR user\-session\-keyring (7)). +This keyring is expected to always exist. +.IP \[bu] +The UID-specific keyring +.RB ( KEY_REQKEY_DEFL_USER_KEYRING ; +see +.BR user\-keyring (7)). +This keyring is also expected to always exist. +.\" mtk: Are there circumstances where the user sessions and UID-specific +.\" keyrings do not exist? +.\" +.\" David Howells: +.\" The uid keyrings don't exist until someone tries to access them - +.\" at which point they're both created. When you log in, pam_keyinit +.\" creates a link to your user keyring in the session keyring it just +.\" created, thereby creating the user and user-session keyrings. +.\" +.\" and David elaborated that "access" means: +.\" +.\" It means lookup_user_key() was passed KEY_LOOKUP_CREATE. So: +.\" +.\" add_key() - destination keyring +.\" request_key() - destination keyring +.\" KEYCTL_GET_KEYRING_ID - if create arg is true +.\" KEYCTL_CLEAR +.\" KEYCTL_LINK - both args +.\" KEYCTL_SEARCH - destination keyring +.\" KEYCTL_CHOWN +.\" KEYCTL_SETPERM +.\" KEYCTL_SET_TIMEOUT +.\" KEYCTL_INSTANTIATE - destination keyring +.\" KEYCTL_INSTANTIATE_IOV - destination keyring +.\" KEYCTL_NEGATE - destination keyring +.\" KEYCTL_REJECT - destination keyring +.\" KEYCTL_GET_PERSISTENT - destination keyring +.\" +.\" will all create a keyring under some circumstances. Whereas the rest, +.\" such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't. +.P +If the +.BR keyctl (2) +.B KEYCTL_SET_REQKEY_KEYRING +operation specifies +.B KEY_REQKEY_DEFL_DEFAULT +(or no +.B KEYCTL_SET_REQKEY_KEYRING +operation is performed), +then the kernel looks for a keyring +starting from the beginning of the list. +.\" +.SS Requesting user-space instantiation of a key +If the kernel cannot find a key matching +.I type +and +.IR description , +and +.I callout +is not NULL, then the kernel attempts to invoke a user-space +program to instantiate a key with the given +.I type +and +.IR description . +In this case, the following steps are performed: +.IP (1) 5 +The kernel creates an uninstantiated key, U, with the requested +.I type +and +.IR description . +.IP (2) +The kernel creates an authorization key, V, +.\" struct request_key_auth, defined in security/keys/internal.h +that refers to the key U and records the facts that the caller of +.BR request_key () +is: +.RS +.IP (2.1) 7 +the context in which the key U should be instantiated and secured, and +.IP (2.2) +the context from which associated key requests may be satisfied. +.RE +.IP +The authorization key is constructed as follows: +.RS +.IP \[bu] 3 +The key type is +.IR \[dq].request_key_auth\[dq] . +.IP \[bu] +The key's UID and GID are the same as the corresponding filesystem IDs +of the requesting process. +.IP \[bu] +The key grants +.IR view , +.IR read , +and +.I search +permissions to the key possessor as well as +.I view +permission for the key user. +.IP \[bu] +The description (name) of the key is the hexadecimal +string representing the ID of the key that is to be instantiated +in the requesting program. +.IP \[bu] +The payload of the key is taken from the data specified in +.IR callout_info . +.IP \[bu] +Internally, the kernel also records the PID of the process that called +.BR request_key (). +.RE +.IP (3) +The kernel creates a process that executes a user-space service such as +.BR request\-key (8) +with a new session keyring that contains a link to the authorization key, V. +.\" The request\-key(8) program can be invoked in circumstances *other* than +.\" when triggered by request_key(2). For example, upcalls from places such +.\" as the DNS resolver. +.IP +This program is supplied with the following command-line arguments: +.RS +.IP [0] 5 +The string +.IR \[dq]/sbin/request\-key\[dq] . +.IP [1] +The string +.I \[dq]create\[dq] +(indicating that a key is to be created). +.IP [2] +The ID of the key that is to be instantiated. +.IP [3] +The filesystem UID of the caller of +.BR request_key (). +.IP [4] +The filesystem GID of the caller of +.BR request_key (). +.IP [5] +The ID of the thread keyring of the caller of +.BR request_key (). +This may be zero if that keyring hasn't been created. +.IP [6] +The ID of the process keyring of the caller of +.BR request_key (). +This may be zero if that keyring hasn't been created. +.IP [7] +The ID of the session keyring of the caller of +.BR request_key (). +.RE +.IP +.IR Note : +each of the command-line arguments that is a key ID is encoded in +.I decimal +(unlike the key IDs shown in +.IR /proc/keys , +which are shown as hexadecimal values). +.IP (4) +The program spawned in the previous step: +.RS +.IP \[bu] 3 +Assumes the authority to instantiate the key U using the +.BR keyctl (2) +.B KEYCTL_ASSUME_AUTHORITY +operation (typically via the +.BR keyctl_assume_authority (3) +function). +.IP \[bu] +Obtains the callout data from the payload of the authorization key V +(using the +.BR keyctl (2) +.B KEYCTL_READ +operation (or, more commonly, the +.BR keyctl_read (3) +function) with a key ID value of +.BR KEY_SPEC_REQKEY_AUTH_KEY ). +.IP \[bu] +Instantiates the key +(or execs another program that performs that task), +specifying the payload and destination keyring. +(The destination keyring that the requestor specified when calling +.BR request_key () +can be accessed using the special key ID +.BR KEY_SPEC_REQUESTOR_KEYRING .) +.\" Should an instantiating program be using KEY_SPEC_REQUESTOR_KEYRING? +.\" I couldn't find a use in the keyutils git repo. +.\" According to David Howells: +.\" * This feature is provided, but not used at the moment. +.\" * A key added to that ring is then owned by the requester +Instantiation is performed using the +.BR keyctl (2) +.B KEYCTL_INSTANTIATE +operation (or, more commonly, the +.BR keyctl_instantiate (3) +function). +At this point, the +.BR request_key () +call completes, and the requesting program can continue execution. +.RE +.P +If these steps are unsuccessful, then an +.B ENOKEY +error will be returned to the caller of +.BR request_key () +and a temporary, negatively instantiated key will be installed +in the keyring specified by +.IR dest_keyring . +This will expire after a few seconds, but will cause subsequent calls to +.BR request_key () +to fail until it does. +The purpose of this negatively instantiated key is to prevent +(possibly different) processes making repeated requests +(that require expensive +.BR request\-key (8) +upcalls) for a key that can't (at the moment) be positively instantiated. +.P +Once the key has been instantiated, the authorization key +.RB ( KEY_SPEC_REQKEY_AUTH_KEY ) +is revoked, and the destination keyring +.RB ( KEY_SPEC_REQUESTOR_KEYRING ) +is no longer accessible from the +.BR request\-key (8) +program. +.P +If a key is created, then\[em]regardless of whether it is a valid key or +a negatively instantiated key\[em]it will displace any other key with +the same type and description from the keyring specified in +.IR dest_keyring . +.SH RETURN VALUE +On success, +.BR request_key () +returns the serial number of the key it found or caused to be created. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The keyring wasn't available for modification by the user. +.TP +.B EDQUOT +The key quota for this user would be exceeded by creating this key or linking +it to the keyring. +.TP +.B EFAULT +One of +.IR type , +.IR description , +or +.I callout_info +points outside the process's accessible address space. +.TP +.B EINTR +The request was interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +The size of the string (including the terminating null byte) specified in +.I type +or +.I description +exceeded the limit (32 bytes and 4096 bytes respectively). +.TP +.B EINVAL +The size of the string (including the terminating null byte) specified in +.I callout_info +exceeded the system page size. +.TP +.B EKEYEXPIRED +An expired key was found, but no replacement could be obtained. +.TP +.B EKEYREJECTED +The attempt to generate a new key was rejected. +.TP +.B EKEYREVOKED +A revoked key was found, but no replacement could be obtained. +.TP +.B ENOKEY +No matching key was found. +.TP +.B ENOMEM +Insufficient memory to create a key. +.TP +.B EPERM +The +.I type +argument started with a period (\[aq].\[aq]). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.10. +.P +The ability to instantiate keys upon request was added +.\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a +in Linux 2.6.13. +.SH EXAMPLES +The program below demonstrates the use of +.BR request_key (). +The +.IR type , +.IR description , +and +.I callout_info +arguments for the system call are taken from the values +supplied in the command-line arguments. +The call specifies the session keyring as the target keyring. +.P +In order to demonstrate this program, +we first create a suitable entry in the file +.IR /etc/request\-key.conf . +.P +.in +4n +.EX +$ sudo sh +# \fBecho \[aq]create user mtk:* * /bin/keyctl instantiate %k %c %S\[aq] \e\fP + \fB> /etc/request\-key.conf\fP +# \fBexit\fP +.EE +.in +.P +This entry specifies that when a new "user" key with the prefix +"mtk:" must be instantiated, that task should be performed via the +.BR keyctl (1) +command's +.B instantiate +operation. +The arguments supplied to the +.B instantiate +operation are: +the ID of the uninstantiated key +.RI ( %k ); +the callout data supplied to the +.BR request_key () +call +.RI ( %c ); +and the session keyring +.RI ( %S ) +of the requestor (i.e., the caller of +.BR request_key ()). +See +.BR request\-key.conf (5) +for details of these +.I % +specifiers. +.P +Then we run the program and check the contents of +.I /proc/keys +to verify that the requested key has been instantiated: +.P +.in +4n +.EX +$ \fB./t_request_key user mtk:key1 "Payload data"\fP +$ \fBgrep \[aq]2dddaf50\[aq] /proc/keys\fP +2dddaf50 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mtk:key1: 12 +.EE +.in +.P +For another example of the use of this program, see +.BR keyctl (2). +.SS Program source +\& +.\" SRC BEGIN (t_request_key.c) +.EX +/* t_request_key.c */ +\& +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + key_serial_t key; +\& + if (argc != 4) { + fprintf(stderr, "Usage: %s type description callout\-data\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + key = request_key(argv[1], argv[2], argv[3], + KEY_SPEC_SESSION_KEYRING); + if (key == \-1) { + perror("request_key"); + exit(EXIT_FAILURE); + } +\& + printf("Key ID is %jx\en", (uintmax_t) key); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR keyctl (3), +.BR capabilities (7), +.BR keyrings (7), +.BR keyutils (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7), +.BR request\-key (8) +.P +The kernel source files +.I Documentation/security/keys/core.rst +and +.I Documentation/keys/request\-key.rst +(or, before Linux 4.13, in the files +.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 +.I Documentation/security/keys.txt +and +.\" commit 3db38ed76890565772fcca3279cc8d454ea6176b +.IR Documentation/security/keys\-request\-key.txt ). diff --git a/man/man2/restart_syscall.2 b/man/man2/restart_syscall.2 new file mode 100644 index 0000000..8c752d4 --- /dev/null +++ b/man/man2/restart_syscall.2 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2013 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" http://thread.gmane.org/gmane.linux.kernel/76552/focus=76803 +.\" From: Linus Torvalds transmeta.com> +.\" Subject: Re: [PATCH] compatibility syscall layer (lets try again) +.\" Newsgroups: gmane.linux.kernel +.\" Date: 2002-12-05 02:51:12 GMT +.\" +.\" See also Section 11.3.3 of Understanding the Linux Kernel, 3rd edition +.\" +.TH restart_syscall 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +restart_syscall \- restart a system call after interruption by a stop signal +.SH SYNOPSIS +.nf +.B long restart_syscall(void); +.fi +.P +.IR Note : +There is no glibc wrapper for this system call; see NOTES. +.SH DESCRIPTION +The +.BR restart_syscall () +system call is used to restart certain system calls +after a process that was stopped by a signal (e.g., +.B SIGSTOP +or +.BR SIGTSTP ) +is later resumed after receiving a +.B SIGCONT +signal. +This system call is designed only for internal use by the kernel. +.P +.BR restart_syscall () +is used for restarting only those system calls that, +when restarted, should adjust their time-related parameters\[em]namely +.BR poll (2) +(since Linux 2.6.24), +.BR nanosleep (2) +(since Linux 2.6), +.BR clock_nanosleep (2) +(since Linux 2.6), +and +.BR futex (2), +when employed with the +.B FUTEX_WAIT +(since Linux 2.6.22) +and +.B FUTEX_WAIT_BITSET +(since Linux 2.6.31) +operations. +.\" These system calls correspond to the special internal errno value +.\" ERESTART_RESTARTBLOCK. Each of the system calls has a "restart" +.\" helper function that is invoked by restart_syscall(). +.\" Notable (as at Linux 3.17) is that poll() has such a "restart" +.\" function, but ppoll(), select(), and pselect() do not. +.\" This means that the latter system calls do not take account of the +.\" time spent in the stopped state when restarting. +.BR restart_syscall () +restarts the interrupted system call with a +time argument that is suitably adjusted to account for the +time that has already elapsed (including the time where the process +was stopped by a signal). +Without the +.BR restart_syscall () +mechanism, restarting these system calls would not correctly deduct the +already elapsed time when the process continued execution. +.SH RETURN VALUE +The return value of +.BR restart_syscall () +is the return value of whatever system call is being restarted. +.SH ERRORS +.I errno +is set as per the errors for whatever system call is being restarted by +.BR restart_syscall (). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6. +.SH NOTES +There is no glibc wrapper for this system call, +because it is intended for use only by the kernel and +should never be called by applications. +.P +The kernel uses +.BR restart_syscall () +to ensure that when a system call is restarted +after a process has been stopped by a signal and then resumed by +.BR SIGCONT , +then the time that the process spent in the stopped state is counted +against the timeout interval specified in the original system call. +In the case of system calls that take a timeout argument and +automatically restart after a stop signal plus +.BR SIGCONT , +but which do not have the +.BR restart_syscall () +mechanism built in, then, after the process resumes execution, +the time that the process spent in the stop state is +.I not +counted against the timeout value. +Notable examples of system calls that suffer this problem are +.BR ppoll (2), +.BR select (2), +and +.BR pselect (2). +.P +From user space, the operation of +.BR restart_syscall () +is largely invisible: +to the process that made the system call that is restarted, +it appears as though that system call executed and +returned in the usual fashion. +.SH SEE ALSO +.BR sigaction (2), +.BR sigreturn (2), +.BR signal (7) +.\" FIXME . ppoll(2), select(2), and pselect(2) +.\" should probably get the restart_syscall() treatment: +.\" If a select() call is suspended by stop-sig+SIGCONT, the time +.\" spent suspended is *not* deducted when the select() is restarted. +.\" FIXME . check whether recvmmsg() handles stop-sig+SIGCONT properly. diff --git a/man/man2/rmdir.2 b/man/man2/rmdir.2 new file mode 100644 index 0000000..8f50c50 --- /dev/null +++ b/man/man2/rmdir.2 @@ -0,0 +1,128 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH rmdir 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rmdir \- delete a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int rmdir(const char *" pathname ); +.fi +.SH DESCRIPTION +.BR rmdir () +deletes a directory, which must be empty. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I pathname +was not allowed, or one of the directories in the path prefix of +.I pathname +did not allow search permission. +(See also +.BR path_resolution (7).) +.TP +.B EBUSY +.I pathname +is currently in use by the system or some process that prevents its +removal. +On Linux, this means +.I pathname +is currently used as a mount point +or is the root directory of the calling process. +.TP +.B EFAULT +.IR pathname " points outside your accessible address space." +.TP +.B EINVAL +.I pathname +has +.I . +as last component. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A directory component in +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +.IR pathname , +or a component used as a directory in +.IR pathname , +is not, in fact, a directory. +.TP +.B ENOTEMPTY +.I pathname +contains entries other than +.IR . " and " .. " ;" +or, +.I pathname +has +.I .. +as its final component. +POSIX.1 also allows +.\" POSIX.1-2001, POSIX.1-2008 +.B EEXIST +for this condition. +.TP +.B EPERM +The directory containing +.I pathname +has the sticky bit +.RB ( S_ISVTX ) +set and the process's effective user ID is neither the user ID +of the file to be deleted nor that of the directory containing it, +and the process is not privileged (Linux: does not have the +.B CAP_FOWNER +capability). +.TP +.B EPERM +The filesystem containing +.I pathname +does not support the removal of directories. +.TP +.B EROFS +.I pathname +refers to a directory on a read-only filesystem. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of directories which are still being used. +.SH SEE ALSO +.BR rm (1), +.BR rmdir (1), +.BR chdir (2), +.BR chmod (2), +.BR mkdir (2), +.BR rename (2), +.BR unlink (2), +.BR unlinkat (2) diff --git a/man/man2/rt_sigaction.2 b/man/man2/rt_sigaction.2 new file mode 100644 index 0000000..d642d26 --- /dev/null +++ b/man/man2/rt_sigaction.2 @@ -0,0 +1 @@ +.so man2/sigaction.2 diff --git a/man/man2/rt_sigpending.2 b/man/man2/rt_sigpending.2 new file mode 100644 index 0000000..304adff --- /dev/null +++ b/man/man2/rt_sigpending.2 @@ -0,0 +1 @@ +.so man2/sigpending.2 diff --git a/man/man2/rt_sigprocmask.2 b/man/man2/rt_sigprocmask.2 new file mode 100644 index 0000000..5eab7ac --- /dev/null +++ b/man/man2/rt_sigprocmask.2 @@ -0,0 +1 @@ +.so man2/sigprocmask.2 diff --git a/man/man2/rt_sigqueueinfo.2 b/man/man2/rt_sigqueueinfo.2 new file mode 100644 index 0000000..d097bb3 --- /dev/null +++ b/man/man2/rt_sigqueueinfo.2 @@ -0,0 +1,195 @@ +.\" Copyright (c) 2002, 2011 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH rt_sigqueueinfo 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rt_sigqueueinfo, rt_tgsigqueueinfo \- queue a signal and data +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SI_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_rt_sigqueueinfo, pid_t " tgid , +.BI " int " sig ", siginfo_t *" info ); +.BI "int syscall(SYS_rt_tgsigqueueinfo, pid_t " tgid ", pid_t " tid , +.BI " int " sig ", siginfo_t *" info ); +.fi +.P +.IR Note : +There are no glibc wrappers for these system calls; see NOTES. +.SH DESCRIPTION +The +.BR rt_sigqueueinfo () +and +.BR rt_tgsigqueueinfo () +system calls are the low-level interfaces used to send a signal plus data +to a process or thread. +The receiver of the signal can obtain the accompanying data +by establishing a signal handler with the +.BR sigaction (2) +.B SA_SIGINFO +flag. +.P +These system calls are not intended for direct application use; +they are provided to allow the implementation of +.BR sigqueue (3) +and +.BR pthread_sigqueue (3). +.P +The +.BR rt_sigqueueinfo () +system call sends the signal +.I sig +to the thread group with the ID +.IR tgid . +(The term "thread group" is synonymous with "process", and +.I tid +corresponds to the traditional UNIX process ID.) +The signal will be delivered to an arbitrary member of the thread group +(i.e., one of the threads that is not currently blocking the signal). +.P +The +.I info +argument specifies the data to accompany the signal. +This argument is a pointer to a structure of type +.IR siginfo_t , +described in +.BR sigaction (2) +(and defined by including +.IR ). +The caller should set the following fields in this structure: +.TP +.I si_code +This should be one of the +.B SI_* +codes in the Linux kernel source file +.IR include/asm\-generic/siginfo.h . +If the signal is being sent to any process other than the caller itself, +the following restrictions apply: +.RS +.IP \[bu] 3 +The code can't be a value greater than or equal to zero. +In particular, it can't be +.BR SI_USER , +which is used by the kernel to indicate a signal sent by +.BR kill (2), +and nor can it be +.BR SI_KERNEL , +which is used to indicate a signal generated by the kernel. +.IP \[bu] +The code can't (since Linux 2.6.39) be +.BR SI_TKILL , +which is used by the kernel to indicate a signal sent using +.\" tkill(2) or +.BR tgkill (2). +.RE +.TP +.I si_pid +This should be set to a process ID, +typically the process ID of the sender. +.TP +.I si_uid +This should be set to a user ID, +typically the real user ID of the sender. +.TP +.I si_value +This field contains the user data to accompany the signal. +For more information, see the description of the last +.RI ( "union sigval" ) +argument of +.BR sigqueue (3). +.P +Internally, the kernel sets the +.I si_signo +field to the value specified in +.IR sig , +so that the receiver of the signal can also obtain +the signal number via that field. +.P +The +.BR rt_tgsigqueueinfo () +system call is like +.BR rt_sigqueueinfo (), +but sends the signal and data to the single thread +specified by the combination of +.IR tgid , +a thread group ID, +and +.IR tid , +a thread in that thread group. +.SH RETURN VALUE +On success, these system calls return 0. +On error, they return \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The limit of signals which may be queued has been reached. +(See +.BR signal (7) +for further information.) +.TP +.B EINVAL +.IR sig , +.IR tgid , +or +.I tid +was invalid. +.TP +.B EPERM +The caller does not have permission to send the signal to the target. +For the required permissions, see +.BR kill (2). +.TP +.B EPERM +.I tgid +specifies a process other than the caller and +.I info\->si_code +is invalid. +.TP +.B ESRCH +.BR rt_sigqueueinfo (): +No thread group matching +.I tgid +was found. +.P +.BR rt_tgsigqueinfo (): +No thread matching +.I tgid +and +.I tid +was found. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR rt_sigqueueinfo () +Linux 2.2. +.TP +.BR rt_tgsigqueueinfo () +Linux 2.6.31. +.SH NOTES +Since these system calls are not intended for application use, +there are no glibc wrapper functions; use +.BR syscall (2) +in the unlikely case that you want to call them directly. +.P +As with +.BR kill (2), +the null signal (0) can be used to check if the specified process +or thread exists. +.SH SEE ALSO +.BR kill (2), +.BR pidfd_send_signal (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR tgkill (2), +.BR pthread_sigqueue (3), +.BR sigqueue (3), +.BR signal (7) diff --git a/man/man2/rt_sigreturn.2 b/man/man2/rt_sigreturn.2 new file mode 100644 index 0000000..830b7b9 --- /dev/null +++ b/man/man2/rt_sigreturn.2 @@ -0,0 +1 @@ +.so man2/sigreturn.2 diff --git a/man/man2/rt_sigsuspend.2 b/man/man2/rt_sigsuspend.2 new file mode 100644 index 0000000..96d99c4 --- /dev/null +++ b/man/man2/rt_sigsuspend.2 @@ -0,0 +1 @@ +.so man2/sigsuspend.2 diff --git a/man/man2/rt_sigtimedwait.2 b/man/man2/rt_sigtimedwait.2 new file mode 100644 index 0000000..ca098e5 --- /dev/null +++ b/man/man2/rt_sigtimedwait.2 @@ -0,0 +1 @@ +.so man2/sigtimedwait.2 diff --git a/man/man2/rt_tgsigqueueinfo.2 b/man/man2/rt_tgsigqueueinfo.2 new file mode 100644 index 0000000..7b6cf68 --- /dev/null +++ b/man/man2/rt_tgsigqueueinfo.2 @@ -0,0 +1 @@ +.so man2/rt_sigqueueinfo.2 diff --git a/man/man2/s390_guarded_storage.2 b/man/man2/s390_guarded_storage.2 new file mode 100644 index 0000000..9155161 --- /dev/null +++ b/man/man2/s390_guarded_storage.2 @@ -0,0 +1,162 @@ +.\" Copyright (C) 2018 Eugene Syromyatnikov +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH s390_guarded_storage 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +s390_guarded_storage \- operations with z/Architecture guarded storage facility +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " "/* Definition of " GS_* " constants */" +.BR "#include " \ +"/* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_s390_guarded_storage, int " command , +.BI " struct gs_cb *" gs_cb ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR s390_guarded_storage (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR s390_guarded_storage () +system call enables the use of the Guarded Storage Facility +(a z/Architecture-specific feature) for user-space processes. +.P +.\" The description is based on +.\" http://www-05.ibm.com/de/linux-on-z-ws-us/agenda/pdfs/8_-_Linux_Whats_New_-_Stefan_Raspl.pdf +.\" and "z/Architecture Principles of Operation" obtained from +.\" http://publibfi.boulder.ibm.com/epubs/pdf/dz9zr011.pdf +The guarded storage facility is a hardware feature that allows marking up to +64 memory regions (as of z14) as guarded; +reading a pointer with a newly introduced "Load Guarded" (LGG) +or "Load Logical and Shift Guarded" (LLGFSG) instructions will cause +a range check on the loaded value and invoke a (previously set up) +user-space handler if one of the guarded regions is affected. +.P +The +.\" The command description is copied from v4.12-rc1~139^2~56^2 commit message +.I command +argument indicates which function to perform. +The following commands are supported: +.TP +.B GS_ENABLE +Enable the guarded storage facility for the calling task. +The initial content of the guarded storage control block will be all zeros. +After enablement, user-space code can use the "Load Guarded Storage +Controls" (LGSC) instruction (or the +.BR load_gs_cb () +function wrapper provided in the +.I asm/guarded_storage.h +header) to load an arbitrary control block. +While a task is enabled, the kernel will save and restore the calling content +of the guarded storage registers on context switch. +.TP +.B GS_DISABLE +Disables the use of the guarded storage facility for the calling task. +The kernel will cease to save and restore the content of the guarded storage +registers, the task-specific content of these registers is lost. +.TP +.B GS_SET_BC_CB +Set a broadcast guarded storage control block to the one provided in the +.I gs_cb +argument. +This is called per thread and associates a specific guarded storage control +block with the calling task. +This control block will be used in the broadcast command +.BR GS_BROADCAST . +.TP +.B GS_CLEAR_BC_CB +Clears the broadcast guarded storage control block. +The guarded storage control block will no longer have the association +established by the +.B GS_SET_BC_CB +command. +.TP +.B GS_BROADCAST +Sends a broadcast to all thread siblings of the calling task. +Every sibling that has established a broadcast guarded storage control block +will load this control block and will be enabled for guarded storage. +The broadcast guarded storage control block is consumed; a second broadcast +without a refresh of the stored control block with +.B GS_SET_BC_CB +will not have any effect. +.P +The +.I gs_cb +argument specifies the address of a guarded storage control block structure +and is currently used only by the +.B GS_SET_BC_CB +command; all other aforementioned commands ignore this argument. +.SH RETURN VALUE +On success, the return value of +.BR s390_guarded_storage () +is 0. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I command +was +.B GS_SET_BC_CB +and the copying of the guarded storage control block structure pointed by the +.I gs_cb +argument has failed. +.TP +.B EINVAL +The value provided in the +.I command +argument was not valid. +.TP +.B ENOMEM +.I command +was one of +.BR GS_ENABLE " or " GS_SET_BC_CB , +and the allocation of a new guarded storage control block has failed. +.TP +.B EOPNOTSUPP +The guarded storage facility is not supported by the hardware. +.SH STANDARDS +Linux on s390. +.SH HISTORY +.\" 916cda1aa1b412d7cf2991c3af7479544942d121, v4.12-rc1~139^2~56^2 +Linux 4.12. +System z14. +.SH NOTES +The description of the guarded storage facility along with related +instructions and Guarded Storage Control Block and +Guarded Storage Event Parameter List structure layouts +is available in "z/Architecture Principles of Operations" +beginning from the twelfth edition. +.P +The +.I gs_cb +structure has a field +.I gsepla +(Guarded Storage Event Parameter List Address), which is a user-space pointer +to a Guarded Storage Event Parameter List structure +(that contains the address +of the aforementioned event handler in the +.I gseha +field), and its layout is available as a +.B gs_epl +structure type definition in the +.I asm/guarded_storage.h +header. +.\" .P +.\" For the example of using the guarded storage facility, see +.\" .UR https://developer.ibm.com/javasdk/2017/09/25/concurrent-scavenge-using-guarded-storage-facility-works/ +.\" the article with the description of its usage in the Java Garbage Collection +.\" .UE +.SH SEE ALSO +.BR syscall (2) diff --git a/man/man2/s390_pci_mmio_read.2 b/man/man2/s390_pci_mmio_read.2 new file mode 100644 index 0000000..dedc390 --- /dev/null +++ b/man/man2/s390_pci_mmio_read.2 @@ -0,0 +1 @@ +.so man2/s390_pci_mmio_write.2 diff --git a/man/man2/s390_pci_mmio_write.2 b/man/man2/s390_pci_mmio_write.2 new file mode 100644 index 0000000..5fca868 --- /dev/null +++ b/man/man2/s390_pci_mmio_write.2 @@ -0,0 +1,94 @@ +.\" Copyright (c) IBM Corp. 2015 +.\" Author: Alexey Ishchuk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH s390_pci_mmio_write 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +s390_pci_mmio_write, s390_pci_mmio_read \- transfer data to/from PCI +MMIO memory page +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_s390_pci_mmio_write, unsigned long " mmio_addr , +.BI " const void " user_buffer [. length "], \ +size_t " length ); +.BI "int syscall(SYS_s390_pci_mmio_read, unsigned long " mmio_addr , +.BI " void " user_buffer [. length "], size_t " length ); +.fi +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR s390_pci_mmio_write () +system call writes +.I length +bytes of data from the user-space buffer +.I user_buffer +to the PCI MMIO memory location specified by +.IR mmio_addr . +The +.BR s390_pci_mmio_read () +system call reads +.I length +bytes of +data from the PCI MMIO memory location specified by +.I mmio_addr +to the user-space buffer +.IR user_buffer . +.P +These system calls must be used instead of the simple assignment +or data-transfer operations that are used to access the PCI MMIO +memory areas mapped to user space on the Linux System z platform. +The address specified by +.I mmio_addr +must belong to a PCI MMIO memory page mapping in the caller's address space, +and the data being written or read must not cross a page boundary. +The +.I length +value cannot be greater than the system page size. +.SH RETURN VALUE +On success, +.BR s390_pci_mmio_write () +and +.BR s390_pci_mmio_read () +return 0. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +The address in +.I mmio_addr +is invalid. +.TP +.B EFAULT +.I user_buffer +does not point to a valid location in the caller's address space. +.TP +.B EINVAL +Invalid +.I length +argument. +.TP +.B ENODEV +PCI support is not enabled. +.TP +.B ENOMEM +Insufficient memory. +.SH STANDARDS +Linux on s390. +.SH HISTORY +Linux 3.19. +System z EC12. +.SH SEE ALSO +.BR syscall (2) diff --git a/man/man2/s390_runtime_instr.2 b/man/man2/s390_runtime_instr.2 new file mode 100644 index 0000000..1d52848 --- /dev/null +++ b/man/man2/s390_runtime_instr.2 @@ -0,0 +1,104 @@ +.\" Copyright (c) IBM Corp. 2012 +.\" Author: Jan Glauber +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH s390_runtime_instr 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " S390_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_s390_runtime_instr, int " command ", int " signum ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR s390_runtime_instr (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR s390_runtime_instr () +system call starts or stops CPU run-time instrumentation for the +calling thread. +.P +The +.I command +argument controls whether run-time instrumentation is started +.RB ( S390_RUNTIME_INSTR_START , +1) or stopped +.RB ( S390_RUNTIME_INSTR_STOP , +2) for the calling thread. +.P +The +.I signum +argument specifies the number of a real-time signal. +This argument was used to specify a signal number that should be delivered +to the thread if the run-time instrumentation buffer was full or if +the run-time-instrumentation-halted interrupt had occurred. +This feature was never used, +and in Linux 4.4 support for this feature was removed; +.\" commit b38feccd663b55ab07116208b68e1ffc7c3c7e78 +thus, in current kernels, this argument is ignored. +.SH RETURN VALUE +On success, +.BR s390_runtime_instr () +returns 0 and enables the thread for +run-time instrumentation by assigning the thread a default run-time +instrumentation control block. +The caller can then read and modify the control block and start the run-time +instrumentation. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The value specified in +.I command +is not a valid command. +.TP +.B EINVAL +The value specified in +.I signum +is not a real-time signal number. +From Linux 4.4 onwards, the +.I signum +argument has no effect, +so that an invalid signal number will not result in an error. +.TP +.B ENOMEM +Allocating memory for the run-time instrumentation control block failed. +.TP +.B EOPNOTSUPP +The run-time instrumentation facility is not available. +.SH STANDARDS +Linux on s390. +.SH HISTORY +Linux 3.7. +System z EC12. +.SH NOTES +The +.I asm/runtime_instr.h +header file is available +.\" commit df2f815a7df7edb5335a3bdeee6a8f9f6f9c35c4 +since Linux 4.16. +.P +Starting with Linux 4.4, +support for signalling was removed, as was the check whether +.I signum +is a valid real-time signal. +For backwards compatibility with older kernels, it is recommended to pass +a valid real-time signal number in +.I signum +and install a handler for that signal. +.SH SEE ALSO +.BR syscall (2), +.BR signal (7) diff --git a/man/man2/s390_sthyi.2 b/man/man2/s390_sthyi.2 new file mode 100644 index 0000000..36cbbc4 --- /dev/null +++ b/man/man2/s390_sthyi.2 @@ -0,0 +1,133 @@ +.\" Copyright IBM Corp. 2017 +.\" Author: QingFeng Hao +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH s390_sthyi 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +s390_sthyi \- emulate STHYI instruction +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " STHYI_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_s390_sthyi, unsigned long " function_code , +.BI " void *" resp_buffer ", uint64_t *" return_code , +.BI " unsigned long " flags ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR s390_sthyi (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR s390_sthyi () +system call emulates the STHYI (Store Hypervisor Information) instruction. +It provides hardware resource information for the machine and its +virtualization levels. +This includes CPU type and capacity, as well as the machine model and +other metrics. +.P +The +.I function_code +argument indicates which function to perform. +The following code(s) are supported: +.TP +.B STHYI_FC_CP_IFL_CAP +Return CP (Central Processor) and IFL (Integrated Facility for Linux) +capacity information. +.P +The +.I resp_buffer +argument specifies the address of a response buffer. +When the +.I function_code +is +.BR STHYI_FC_CP_IFL_CAP , +the buffer must be one page (4K) in size. +If the system call returns 0, +the response buffer will be filled with CPU capacity information. +Otherwise, the response buffer's content is unchanged. +.P +The +.I return_code +argument stores the return code of the STHYI instruction, +using one of the following values: +.TP +0 +Success. +.TP +4 +Unsupported function code. +.P +For further details about +.IR return_code , +.IR function_code , +and +.IR resp_buffer , +see the reference given in NOTES. +.P +The +.I flags +argument is provided to allow for future extensions and currently +must be set to 0. +.SH RETURN VALUE +On success (that is: emulation succeeded), the return value of +.BR s390_sthyi () +matches the condition code of the STHYI instructions, which is a value +in the range [0..3]. +A return value of 0 indicates that CPU capacity information is stored in +.IR *resp_buffer . +A return value of 3 indicates "unsupported function code" and the content of +.I *resp_buffer +is unchanged. +The return values 1 and 2 are reserved. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +The value specified in +.I resp_buffer +or +.I return_code +is not a valid address. +.TP +.B EINVAL +The value specified in +.I flags +is nonzero. +.TP +.B ENOMEM +Allocating memory for handling the CPU capacity information failed. +.TP +.B EOPNOTSUPP +The value specified in +.I function_code +is not valid. +.SH STANDARDS +Linux on s390. +.SH HISTORY +Linux 4.15. +.SH NOTES +For details of the STHYI instruction, see +.UR https://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm +the documentation page +.UE . +.P +When the system call interface is used, the response buffer doesn't +have to fulfill alignment requirements described in the STHYI +instruction definition. +.P +The kernel caches the response (for up to one second, as of Linux 4.16). +Subsequent system call invocations may return the cached response. +.SH SEE ALSO +.BR syscall (2) diff --git a/man/man2/sbrk.2 b/man/man2/sbrk.2 new file mode 100644 index 0000000..a3711a5 --- /dev/null +++ b/man/man2/sbrk.2 @@ -0,0 +1 @@ +.so man2/brk.2 diff --git a/man/man2/sched_get_priority_max.2 b/man/man2/sched_get_priority_max.2 new file mode 100644 index 0000000..b60a873 --- /dev/null +++ b/man/man2/sched_get_priority_max.2 @@ -0,0 +1,112 @@ +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" +.TH sched_get_priority_max 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sched_get_priority_max, sched_get_priority_min \- get static priority range +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sched_get_priority_max(int " policy ); +.BI "int sched_get_priority_min(int " policy ); +.fi +.SH DESCRIPTION +.BR sched_get_priority_max () +returns the maximum priority value that can be used with the +scheduling algorithm identified by +.IR policy . +.BR sched_get_priority_min () +returns the minimum priority value that can be used with the +scheduling algorithm identified by +.IR policy . +Supported +.I policy +values are +.BR SCHED_FIFO , +.BR SCHED_RR , +.BR SCHED_OTHER , +.BR SCHED_BATCH , +.BR SCHED_IDLE , +and +.BR SCHED_DEADLINE . +Further details about these policies can be found in +.BR sched (7). +.P +Processes with numerically higher priority values are scheduled before +processes with numerically lower priority values. +Thus, the value +returned by +.BR sched_get_priority_max () +will be greater than the +value returned by +.BR sched_get_priority_min (). +.P +Linux allows the static priority range 1 to 99 for the +.B SCHED_FIFO +and +.B SCHED_RR +policies, and the priority 0 for the remaining policies. +Scheduling priority ranges for the various policies +are not alterable. +.P +The range of scheduling priorities may vary on other POSIX systems, +thus it is a good idea for portable applications to use a virtual +priority range and map it to the interval given by +.BR sched_get_priority_max () +and +.BR sched_get_priority_min () +POSIX.1 requires +.\" POSIX.1-2001, POSIX.1-2008 (XBD 2.8.4) +a spread of at least 32 between the maximum and the minimum values for +.B SCHED_FIFO +and +.BR SCHED_RR . +.P +POSIX systems on which +.BR sched_get_priority_max () +and +.BR sched_get_priority_min () +are available define +.B _POSIX_PRIORITY_SCHEDULING +in +.IR . +.SH RETURN VALUE +On success, +.BR sched_get_priority_max () +and +.BR sched_get_priority_min () +return the maximum/minimum priority value for the named scheduling +policy. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The argument +.I policy +does not identify a defined scheduling policy. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.ad l +.nh +.BR sched_getaffinity (2), +.BR sched_getparam (2), +.BR sched_getscheduler (2), +.BR sched_setaffinity (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR sched (7) diff --git a/man/man2/sched_get_priority_min.2 b/man/man2/sched_get_priority_min.2 new file mode 100644 index 0000000..17b99f0 --- /dev/null +++ b/man/man2/sched_get_priority_min.2 @@ -0,0 +1 @@ +.so man2/sched_get_priority_max.2 diff --git a/man/man2/sched_getaffinity.2 b/man/man2/sched_getaffinity.2 new file mode 100644 index 0000000..f376c11 --- /dev/null +++ b/man/man2/sched_getaffinity.2 @@ -0,0 +1 @@ +.so man2/sched_setaffinity.2 diff --git a/man/man2/sched_getattr.2 b/man/man2/sched_getattr.2 new file mode 100644 index 0000000..cb2c346 --- /dev/null +++ b/man/man2/sched_getattr.2 @@ -0,0 +1 @@ +.so man2/sched_setattr.2 diff --git a/man/man2/sched_getparam.2 b/man/man2/sched_getparam.2 new file mode 100644 index 0000000..d39facd --- /dev/null +++ b/man/man2/sched_getparam.2 @@ -0,0 +1 @@ +.so man2/sched_setparam.2 diff --git a/man/man2/sched_getscheduler.2 b/man/man2/sched_getscheduler.2 new file mode 100644 index 0000000..13aa827 --- /dev/null +++ b/man/man2/sched_getscheduler.2 @@ -0,0 +1 @@ +.so man2/sched_setscheduler.2 diff --git a/man/man2/sched_rr_get_interval.2 b/man/man2/sched_rr_get_interval.2 new file mode 100644 index 0000000..7ce3e60 --- /dev/null +++ b/man/man2/sched_rr_get_interval.2 @@ -0,0 +1,110 @@ +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" +.TH sched_rr_get_interval 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sched_rr_get_interval \- get the SCHED_RR interval for the named process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sched_rr_get_interval(pid_t " pid ", struct timespec *" tp ); +.fi +.SH DESCRIPTION +.BR sched_rr_get_interval () +writes into the +.BR timespec (3) +structure pointed to by +.I tp +the round-robin time quantum for the process identified by +.IR pid . +The specified process should be running under the +.B SCHED_RR +scheduling policy. +.P +If +.I pid +is zero, the time quantum for the calling process is written into +.IR *tp . +.\" FIXME . On Linux, sched_rr_get_interval() +.\" returns the timeslice for SCHED_OTHER processes -- this timeslice +.\" is influenced by the nice value. +.\" For SCHED_FIFO processes, this always returns 0. +.\" +.\" The round-robin time quantum value is not alterable under Linux +.\" 1.3.81. +.\" +.SH RETURN VALUE +On success, +.BR sched_rr_get_interval () +returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Problem with copying information to user space. +.TP +.B EINVAL +Invalid pid. +.TP +.B ENOSYS +The system call is not yet implemented (only on rather old kernels). +.TP +.B ESRCH +Could not find a process with the ID +.IR pid . +.SH VERSIONS +.SS Linux +Linux 3.9 added +.\" commit ce0dbbbb30aee6a835511d5be446462388ba9eee +a new mechanism for adjusting (and viewing) the +.B SCHED_RR +quantum: the +.I /proc/sys/kernel/sched_rr_timeslice_ms +file exposes the quantum as a millisecond value, whose default is 100. +Writing 0 to this file resets the quantum to the default value. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SS Linux +POSIX does not specify any mechanism for controlling the size of the +round-robin time quantum. +Older Linux kernels provide a (nonportable) method of doing this. +The quantum can be controlled by adjusting the process's nice value (see +.BR setpriority (2)). +Assigning a negative (i.e., high) nice value results in a longer quantum; +assigning a positive (i.e., low) nice value results in a shorter quantum. +The default quantum is 0.1 seconds; +the degree to which changing the nice value affects the +quantum has varied somewhat across kernel versions. +This method of adjusting the quantum was removed +.\" commit a4ec24b48ddef1e93f7578be53270f0b95ad666c +starting with Linux 2.6.24. +.SH NOTES +POSIX systems on which +.BR sched_rr_get_interval () +is available define +.B _POSIX_PRIORITY_SCHEDULING +in +.IR . +.\" .SH BUGS +.\" As of Linux 1.3.81 +.\" .BR sched_rr_get_interval () +.\" returns with error +.\" ENOSYS, because SCHED_RR has not yet been fully implemented and tested +.\" properly. +.SH SEE ALSO +.BR timespec (3), +.BR sched (7) diff --git a/man/man2/sched_setaffinity.2 b/man/man2/sched_setaffinity.2 new file mode 100644 index 0000000..d7b1988 --- /dev/null +++ b/man/man2/sched_setaffinity.2 @@ -0,0 +1,427 @@ +.\" Copyright (C) 2002 Robert Love +.\" and Copyright (C) 2006, 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2002-11-19 Robert Love - initial version +.\" 2004-04-20 mtk - fixed description of return value +.\" 2004-04-22 aeb - added glibc prototype history +.\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread +.\" migration and that CPU affinity is a per-thread attribute. +.\" 2006-02-03 mtk -- Major rewrite +.\" 2008-11-12, mtk, removed CPU_*() macro descriptions to a +.\" separate CPU_SET(3) page. +.\" +.TH sched_setaffinity 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sched_setaffinity, sched_getaffinity \- \ +set and get a thread's CPU affinity mask +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize , +.BI " const cpu_set_t *" mask ); +.BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize , +.BI " cpu_set_t *" mask ); +.fi +.SH DESCRIPTION +A thread's CPU affinity mask determines the set of CPUs on which +it is eligible to run. +On a multiprocessor system, setting the CPU affinity mask +can be used to obtain performance benefits. +For example, +by dedicating one CPU to a particular thread +(i.e., setting the affinity mask of that thread to specify a single CPU, +and setting the affinity mask of all other threads to exclude that CPU), +it is possible to ensure maximum execution speed for that thread. +Restricting a thread to run on a single CPU also avoids +the performance cost caused by the cache invalidation that occurs +when a thread ceases to execute on one CPU and then +recommences execution on a different CPU. +.P +A CPU affinity mask is represented by the +.I cpu_set_t +structure, a "CPU set", pointed to by +.IR mask . +A set of macros for manipulating CPU sets is described in +.BR CPU_SET (3). +.P +.BR sched_setaffinity () +sets the CPU affinity mask of the thread whose ID is +.I pid +to the value specified by +.IR mask . +If +.I pid +is zero, then the calling thread is used. +The argument +.I cpusetsize +is the length (in bytes) of the data pointed to by +.IR mask . +Normally this argument would be specified as +.IR "sizeof(cpu_set_t)" . +.P +If the thread specified by +.I pid +is not currently running on one of the CPUs specified in +.IR mask , +then that thread is migrated to one of the CPUs specified in +.IR mask . +.P +.BR sched_getaffinity () +writes the affinity mask of the thread whose ID is +.I pid +into the +.I cpu_set_t +structure pointed to by +.IR mask . +The +.I cpusetsize +argument specifies the size (in bytes) of +.IR mask . +If +.I pid +is zero, then the mask of the calling thread is returned. +.SH RETURN VALUE +On success, +.BR sched_setaffinity () +and +.BR sched_getaffinity () +return 0 (but see "C library/kernel differences" below, +which notes that the underlying +.BR sched_getaffinity () +differs in its return value). +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +A supplied memory address was invalid. +.TP +.B EINVAL +The affinity bit mask +.I mask +contains no processors that are currently physically on the system +and permitted to the thread according to any restrictions that +may be imposed by +.I cpuset +cgroups or the "cpuset" mechanism described in +.BR cpuset (7). +.TP +.B EINVAL +.RB ( sched_getaffinity () +and, before Linux 2.6.9, +.BR sched_setaffinity ()) +.I cpusetsize +is smaller than the size of the affinity mask used by the kernel. +.TP +.B EPERM +.RB ( sched_setaffinity ()) +The calling thread does not have appropriate privileges. +The caller needs an effective user ID equal to the real user ID +or effective user ID of the thread identified by +.IR pid , +or it must possess the +.B CAP_SYS_NICE +capability in the user namespace of the thread +.IR pid . +.TP +.B ESRCH +The thread whose ID is \fIpid\fP could not be found. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5.8, +glibc 2.3. +.P +Initially, the glibc interfaces included a +.I cpusetsize +argument, typed as +.IR "unsigned int" . +In glibc 2.3.3, the +.I cpusetsize +argument was removed, but was then restored in glibc 2.3.4, with type +.IR size_t . +.SH NOTES +After a call to +.BR sched_setaffinity (), +the set of CPUs on which the thread will actually run is +the intersection of the set specified in the +.I mask +argument and the set of CPUs actually present on the system. +The system may further restrict the set of CPUs on which the thread +runs if the "cpuset" mechanism described in +.BR cpuset (7) +is being used. +These restrictions on the actual set of CPUs on which the thread +will run are silently imposed by the kernel. +.P +There are various ways of determining the number of CPUs +available on the system, including: inspecting the contents of +.IR /proc/cpuinfo ; +using +.BR sysconf (3) +to obtain the values of the +.B _SC_NPROCESSORS_CONF +and +.B _SC_NPROCESSORS_ONLN +parameters; and inspecting the list of CPU directories under +.IR /sys/devices/system/cpu/ . +.P +.BR sched (7) +has a description of the Linux scheduling scheme. +.P +The affinity mask is a per-thread attribute that can be +adjusted independently for each of the threads in a thread group. +The value returned from a call to +.BR gettid (2) +can be passed in the argument +.IR pid . +Specifying +.I pid +as 0 will set the attribute for the calling thread, +and passing the value returned from a call to +.BR getpid (2) +will set the attribute for the main thread of the thread group. +(If you are using the POSIX threads API, then use +.BR pthread_setaffinity_np (3) +instead of +.BR sched_setaffinity ().) +.P +The +.I isolcpus +boot option can be used to isolate one or more CPUs at boot time, +so that no processes are scheduled onto those CPUs. +Following the use of this boot option, +the only way to schedule processes onto the isolated CPUs is via +.BR sched_setaffinity () +or the +.BR cpuset (7) +mechanism. +For further information, see the kernel source file +.IR Documentation/admin\-guide/kernel\-parameters.txt . +As noted in that file, +.I isolcpus +is the preferred mechanism of isolating CPUs +(versus the alternative of manually setting the CPU affinity +of all processes on the system). +.P +A child created via +.BR fork (2) +inherits its parent's CPU affinity mask. +The affinity mask is preserved across an +.BR execve (2). +.SS C library/kernel differences +This manual page describes the glibc interface for the CPU affinity calls. +The actual system call interface is slightly different, with the +.I mask +being typed as +.IR "unsigned long\ *" , +reflecting the fact that the underlying implementation of CPU +sets is a simple bit mask. +.P +On success, the raw +.BR sched_getaffinity () +system call returns the number of bytes placed copied into the +.I mask +buffer; +this will be the minimum of +.I cpusetsize +and the size (in bytes) of the +.I cpumask_t +data type that is used internally by the kernel to +represent the CPU set bit mask. +.SS Handling systems with large CPU affinity masks +The underlying system calls (which represent CPU masks as bit masks of type +.IR "unsigned long\ *" ) +impose no restriction on the size of the CPU mask. +However, the +.I cpu_set_t +data type used by glibc has a fixed size of 128 bytes, +meaning that the maximum CPU number that can be represented is 1023. +.\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630 +.\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html +If the kernel CPU affinity mask is larger than 1024, +then calls of the form: +.P +.in +4n +.EX +sched_getaffinity(pid, sizeof(cpu_set_t), &mask); +.EE +.in +.P +fail with the error +.BR EINVAL , +the error produced by the underlying system call for the case where the +.I mask +size specified in +.I cpusetsize +is smaller than the size of the affinity mask used by the kernel. +(Depending on the system CPU topology, the kernel affinity mask can +be substantially larger than the number of active CPUs in the system.) +.P +When working on systems with large kernel CPU affinity masks, +one must dynamically allocate the +.I mask +argument (see +.BR CPU_ALLOC (3)). +Currently, the only way to do this is by probing for the size +of the required mask using +.BR sched_getaffinity () +calls with increasing mask sizes (until the call does not fail with the error +.BR EINVAL ). +.P +Be aware that +.BR CPU_ALLOC (3) +may allocate a slightly larger CPU set than requested +(because CPU sets are implemented as bit masks allocated in units of +.IR sizeof(long) ). +Consequently, +.BR sched_getaffinity () +can set bits beyond the requested allocation size, because the kernel +sees a few additional bits. +Therefore, the caller should iterate over the bits in the returned set, +counting those which are set, and stop upon reaching the value returned by +.BR CPU_COUNT (3) +(rather than iterating over the number of bits +requested to be allocated). +.SH EXAMPLES +The program below creates a child process. +The parent and child then each assign themselves to a specified CPU +and execute identical loops that consume some CPU time. +Before terminating, the parent waits for the child to complete. +The program takes three command-line arguments: +the CPU number for the parent, +the CPU number for the child, +and the number of loop iterations that both processes should perform. +.P +As the sample runs below demonstrate, the amount of real and CPU time +consumed when running the program will depend on intra-core caching effects +and whether the processes are using the same CPU. +.P +We first employ +.BR lscpu (1) +to determine that this (x86) +system has two cores, each with two CPUs: +.P +.in +4n +.EX +$ \fBlscpu | egrep \-i \[aq]core.*:|socket\[aq]\fP +Thread(s) per core: 2 +Core(s) per socket: 2 +Socket(s): 1 +.EE +.in +.P +We then time the operation of the example program for three cases: +both processes running on the same CPU; +both processes running on different CPUs on the same core; +and both processes running on different CPUs on different cores. +.P +.in +4n +.EX +$ \fBtime \-p ./a.out 0 0 100000000\fP +real 14.75 +user 3.02 +sys 11.73 +$ \fBtime \-p ./a.out 0 1 100000000\fP +real 11.52 +user 3.98 +sys 19.06 +$ \fBtime \-p ./a.out 0 3 100000000\fP +real 7.89 +user 3.29 +sys 12.07 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (sched_setaffinity.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int parentCPU, childCPU; + cpu_set_t set; + unsigned int nloops; +\& + if (argc != 4) { + fprintf(stderr, "Usage: %s parent\-cpu child\-cpu num\-loops\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + parentCPU = atoi(argv[1]); + childCPU = atoi(argv[2]); + nloops = atoi(argv[3]); +\& + CPU_ZERO(&set); +\& + switch (fork()) { + case \-1: /* Error */ + err(EXIT_FAILURE, "fork"); +\& + case 0: /* Child */ + CPU_SET(childCPU, &set); +\& + if (sched_setaffinity(getpid(), sizeof(set), &set) == \-1) + err(EXIT_FAILURE, "sched_setaffinity"); +\& + for (unsigned int j = 0; j < nloops; j++) + getppid(); +\& + exit(EXIT_SUCCESS); +\& + default: /* Parent */ + CPU_SET(parentCPU, &set); +\& + if (sched_setaffinity(getpid(), sizeof(set), &set) == \-1) + err(EXIT_FAILURE, "sched_setaffinity"); +\& + for (unsigned int j = 0; j < nloops; j++) + getppid(); +\& + wait(NULL); /* Wait for child to terminate */ + exit(EXIT_SUCCESS); + } +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR lscpu (1), +.BR nproc (1), +.BR taskset (1), +.BR clone (2), +.BR getcpu (2), +.BR getpriority (2), +.BR gettid (2), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getscheduler (2), +.BR sched_setscheduler (2), +.BR setpriority (2), +.BR CPU_SET (3), +.BR get_nprocs (3), +.BR pthread_setaffinity_np (3), +.BR sched_getcpu (3), +.BR capabilities (7), +.BR cpuset (7), +.BR sched (7), +.BR numactl (8) diff --git a/man/man2/sched_setattr.2 b/man/man2/sched_setattr.2 new file mode 100644 index 0000000..ac830a5 --- /dev/null +++ b/man/man2/sched_setattr.2 @@ -0,0 +1,447 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" and Copyright (C) 2014 Peter Zijlstra +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sched_setattr 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sched_setattr, sched_getattr \- +set and get scheduling policy and attributes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SCHED_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_sched_setattr, pid_t " pid ", struct sched_attr *" attr , +.BI " unsigned int " flags ); +.BI "int syscall(SYS_sched_getattr, pid_t " pid ", struct sched_attr *" attr , +.BI " unsigned int " size ", unsigned int " flags ); +.fi +.\" FIXME . Add feature test macro requirements +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.SS sched_setattr() +The +.BR sched_setattr () +system call sets the scheduling policy and +associated attributes for the thread whose ID is specified in +.IR pid . +If +.I pid +equals zero, +the scheduling policy and attributes of the calling thread will be set. +.P +Currently, Linux supports the following "normal" +(i.e., non-real-time) scheduling policies as values that may be specified in +.IR policy : +.TP 14 +.B SCHED_OTHER +the standard round-robin time-sharing policy; +.\" In the 2.6 kernel sources, SCHED_OTHER is actually called +.\" SCHED_NORMAL. +.TP +.B SCHED_BATCH +for "batch" style execution of processes; and +.TP +.B SCHED_IDLE +for running +.I very +low priority background jobs. +.P +Various "real-time" policies are also supported, +for special time-critical applications that need precise control over +the way in which runnable threads are selected for execution. +For the rules governing when a process may use these policies, see +.BR sched (7). +The real-time policies that may be specified in +.I policy +are: +.TP 14 +.B SCHED_FIFO +a first-in, first-out policy; and +.TP +.B SCHED_RR +a round-robin policy. +.P +Linux also provides the following policy: +.TP 14 +.B SCHED_DEADLINE +a deadline scheduling policy; see +.BR sched (7) +for details. +.P +The +.I attr +argument is a pointer to a structure that defines +the new scheduling policy and attributes for the specified thread. +This structure has the following form: +.P +.in +4n +.EX +struct sched_attr { + u32 size; /* Size of this structure */ + u32 sched_policy; /* Policy (SCHED_*) */ + u64 sched_flags; /* Flags */ + s32 sched_nice; /* Nice value (SCHED_OTHER, + SCHED_BATCH) */ + u32 sched_priority; /* Static priority (SCHED_FIFO, + SCHED_RR) */ + /* Remaining fields are for SCHED_DEADLINE */ + u64 sched_runtime; + u64 sched_deadline; + u64 sched_period; +}; +.EE +.in +.P +The fields of the +.I sched_attr +structure are as follows: +.TP +.B size +This field should be set to the size of the structure in bytes, as in +.IR "sizeof(struct sched_attr)" . +If the provided structure is smaller than the kernel structure, +any additional fields are assumed to be '0'. +If the provided structure is larger than the kernel structure, +the kernel verifies that all additional fields are 0; +if they are not, +.BR sched_setattr () +fails with the error +.B E2BIG +and updates +.I size +to contain the size of the kernel structure. +.IP +The above behavior when the size of the user-space +.I sched_attr +structure does not match the size of the kernel structure +allows for future extensibility of the interface. +Malformed applications that pass oversize structures +won't break in the future if the size of the kernel +.I sched_attr +structure is increased. +In the future, +it could also allow applications that know about a larger user-space +.I sched_attr +structure to determine whether they are running on an older kernel +that does not support the larger structure. +.TP +.I sched_policy +This field specifies the scheduling policy, as one of the +.B SCHED_* +values listed above. +.TP +.I sched_flags +This field contains zero or more of the following flags +that are ORed together to control scheduling behavior: +.RS +.TP +.B SCHED_FLAG_RESET_ON_FORK +Children created by +.BR fork (2) +do not inherit privileged scheduling policies. +See +.BR sched (7) +for details. +.TP +.BR SCHED_FLAG_RECLAIM " (since Linux 4.13)" +.\" 2d4283e9d583a3ee8cfb1cbb9c1270614df4c29d +This flag allows a +.B SCHED_DEADLINE +thread to reclaim bandwidth unused by other real-time threads. +.\" Bandwidth reclaim is done via the GRUB algorithm; see +.\" Documentation/scheduler/sched-deadline.txt +.TP +.BR SCHED_FLAG_DL_OVERRUN " (since Linux 4.16)" +.\" commit 34be39305a77b8b1ec9f279163c7cdb6cc719b91 +This flag allows an application to get informed about run-time overruns in +.B SCHED_DEADLINE +threads. +Such overruns may be caused by (for example) coarse execution time accounting +or incorrect parameter assignment. +Notification takes the form of a +.B SIGXCPU +signal which is generated on each overrun. +.IP +This +.B SIGXCPU +signal is +.I process-directed +(see +.BR signal (7)) +rather than thread-directed. +This is probably a bug. +On the one hand, +.BR sched_setattr () +is being used to set a per-thread attribute. +On the other hand, if the process-directed signal is delivered to +a thread inside the process other than the one that had a run-time overrun, +the application has no way of knowing which thread overran. +.RE +.TP +.I sched_nice +This field specifies the nice value to be set when specifying +.I sched_policy +as +.B SCHED_OTHER +or +.BR SCHED_BATCH . +The nice value is a number in the range \-20 (high priority) +to +19 (low priority); see +.BR sched (7). +.TP +.I sched_priority +This field specifies the static priority to be set when specifying +.I sched_policy +as +.B SCHED_FIFO +or +.BR SCHED_RR . +The allowed range of priorities for these policies can be determined using +.BR sched_get_priority_min (2) +and +.BR sched_get_priority_max (2). +For other policies, this field must be specified as 0. +.TP +.I sched_runtime +This field specifies the "Runtime" parameter for deadline scheduling. +The value is expressed in nanoseconds. +This field, and the next two fields, +are used only for +.B SCHED_DEADLINE +scheduling; for further details, see +.BR sched (7). +.TP +.I sched_deadline +This field specifies the "Deadline" parameter for deadline scheduling. +The value is expressed in nanoseconds. +.TP +.I sched_period +This field specifies the "Period" parameter for deadline scheduling. +The value is expressed in nanoseconds. +.P +The +.I flags +argument is provided to allow for future extensions to the interface; +in the current implementation it must be specified as 0. +.\" +.\" +.SS sched_getattr() +The +.BR sched_getattr () +system call fetches the scheduling policy and the +associated attributes for the thread whose ID is specified in +.IR pid . +If +.I pid +equals zero, +the scheduling policy and attributes of the calling thread +will be retrieved. +.P +The +.I size +argument should be set to the size of the +.I sched_attr +structure as known to user space. +The value must be at least as large as the size of the initially published +.I sched_attr +structure, or the call fails with the error +.BR EINVAL . +.P +The retrieved scheduling attributes are placed in the fields of the +.I sched_attr +structure pointed to by +.IR attr . +The kernel sets +.I attr.size +to the size of its +.I sched_attr +structure. +.P +If the caller-provided +.I attr +buffer is larger than the kernel's +.I sched_attr +structure, +the additional bytes in the user-space structure are not touched. +If the caller-provided structure is smaller than the kernel +.I sched_attr +structure, the kernel will silently not return any values which would be stored +outside the provided space. +As with +.BR sched_setattr (), +these semantics allow for future extensibility of the interface. +.P +The +.I flags +argument is provided to allow for future extensions to the interface; +in the current implementation it must be specified as 0. +.SH RETURN VALUE +On success, +.BR sched_setattr () +and +.BR sched_getattr () +return 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR sched_getattr () +and +.BR sched_setattr () +can both fail for the following reasons: +.TP +.B EINVAL +.I attr +is NULL; or +.I pid +is negative; or +.I flags +is not zero. +.TP +.B ESRCH +The thread whose ID is +.I pid +could not be found. +.P +In addition, +.BR sched_getattr () +can fail for the following reasons: +.TP +.B E2BIG +The buffer specified by +.I size +and +.I attr +is too small. +.TP +.B EINVAL +.I size +is invalid; that is, it is smaller than the initial version of the +.I sched_attr +structure (48 bytes) or larger than the system page size. +.P +In addition, +.BR sched_setattr () +can fail for the following reasons: +.TP +.B E2BIG +The buffer specified by +.I size +and +.I attr +is larger than the kernel structure, +and one or more of the excess bytes is nonzero. +.TP +.B EBUSY +.B SCHED_DEADLINE +admission control failure, see +.BR sched (7). +.TP +.B EINVAL +.I attr.sched_policy +is not one of the recognized policies; +.I attr.sched_flags +contains a flag other than +.BR SCHED_FLAG_RESET_ON_FORK ; +or +.I attr.sched_priority +is invalid; or +.I attr.sched_policy +is +.B SCHED_DEADLINE +and the deadline scheduling parameters in +.I attr +are invalid. +.TP +.B EPERM +The caller does not have appropriate privileges. +.TP +.B EPERM +The CPU affinity mask of the thread specified by +.I pid +does not include all CPUs in the system +(see +.BR sched_setaffinity (2)). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.14. +.\" FIXME . Add glibc version +.SH NOTES +glibc does not provide wrappers for these system calls; call them using +.BR syscall (2). +.P +.BR sched_setattr () +provides a superset of the functionality of +.BR sched_setscheduler (2), +.BR sched_setparam (2), +.BR nice (2), +and (other than the ability to set the priority of all processes +belonging to a specified user or all processes in a specified group) +.BR setpriority (2). +Analogously, +.BR sched_getattr () +provides a superset of the functionality of +.BR sched_getscheduler (2), +.BR sched_getparam (2), +and (partially) +.BR getpriority (2). +.SH BUGS +In Linux versions up to +.\" FIXME . patch sent to Peter Zijlstra +3.15, +.BR sched_setattr () +failed with the error +.B EFAULT +instead of +.B E2BIG +for the case described in ERRORS. +.P +Up to Linux 5.3, +.BR sched_getattr () +failed with the error +.B EFBIG +if the in-kernel +.I sched_attr +structure was larger than the +.I size +passed by user space. +.\" In Linux versions up to up 3.15, +.\" FIXME . patch from Peter Zijlstra pending +.\" .BR sched_setattr () +.\" allowed a negative +.\" .I attr.sched_policy +.\" value. +.SH SEE ALSO +.ad l +.nh +.BR chrt (1), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getaffinity (2), +.BR sched_getparam (2), +.BR sched_getscheduler (2), +.BR sched_rr_get_interval (2), +.BR sched_setaffinity (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR sched_yield (2), +.BR setpriority (2), +.BR pthread_getschedparam (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR capabilities (7), +.BR cpuset (7), +.BR sched (7) +.ad diff --git a/man/man2/sched_setparam.2 b/man/man2/sched_setparam.2 new file mode 100644 index 0000000..378782d --- /dev/null +++ b/man/man2/sched_setparam.2 @@ -0,0 +1,121 @@ +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH sched_setparam 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sched_setparam, sched_getparam \- set and get scheduling parameters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sched_setparam(pid_t " pid ", const struct sched_param *" param ); +.BI "int sched_getparam(pid_t " pid ", struct sched_param *" param ); +.P +\fBstruct sched_param { + ... + int \fIsched_priority\fB; + ... +}; +.fi +.SH DESCRIPTION +.BR sched_setparam () +sets the scheduling parameters associated with the scheduling policy +for the thread whose thread ID is specified in \fIpid\fP. +If \fIpid\fP is zero, then +the parameters of the calling thread are set. +The interpretation of +the argument \fIparam\fP depends on the scheduling +policy of the thread identified by +.IR pid . +See +.BR sched (7) +for a description of the scheduling policies supported under Linux. +.P +.BR sched_getparam () +retrieves the scheduling parameters for the +thread identified by \fIpid\fP. +If \fIpid\fP is zero, then the parameters +of the calling thread are retrieved. +.P +.BR sched_setparam () +checks the validity of \fIparam\fP for the scheduling policy of the +thread. +The value \fIparam\->sched_priority\fP must lie within the +range given by +.BR sched_get_priority_min (2) +and +.BR sched_get_priority_max (2). +.P +For a discussion of the privileges and resource limits related to +scheduling priority and policy, see +.BR sched (7). +.P +POSIX systems on which +.BR sched_setparam () +and +.BR sched_getparam () +are available define +.B _POSIX_PRIORITY_SCHEDULING +in \fI\fP. +.SH RETURN VALUE +On success, +.BR sched_setparam () +and +.BR sched_getparam () +return 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Invalid arguments: +.I param +is NULL or +.I pid +is negative +.TP +.B EINVAL +.RB ( sched_setparam ()) +The argument \fIparam\fP does not make sense for the current +scheduling policy. +.TP +.B EPERM +.RB ( sched_setparam ()) +The caller does not have appropriate privileges +(Linux: does not have the +.B CAP_SYS_NICE +capability). +.TP +.B ESRCH +The thread whose ID is \fIpid\fP could not be found. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.ad l +.nh +.BR getpriority (2), +.BR gettid (2), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getaffinity (2), +.BR sched_getscheduler (2), +.BR sched_setaffinity (2), +.BR sched_setattr (2), +.BR sched_setscheduler (2), +.BR setpriority (2), +.BR capabilities (7), +.BR sched (7) diff --git a/man/man2/sched_setscheduler.2 b/man/man2/sched_setscheduler.2 new file mode 100644 index 0000000..76f4395 --- /dev/null +++ b/man/man2/sched_setscheduler.2 @@ -0,0 +1,232 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH sched_setscheduler 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sched_setscheduler, sched_getscheduler \- +set and get scheduling policy/parameters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sched_setscheduler(pid_t " pid ", int " policy , +.BI " const struct sched_param *" param ); +.BI "int sched_getscheduler(pid_t " pid ); +.fi +.SH DESCRIPTION +The +.BR sched_setscheduler () +system call +sets both the scheduling policy and parameters for the +thread whose ID is specified in \fIpid\fP. +If \fIpid\fP equals zero, the +scheduling policy and parameters of the calling thread will be set. +.P +The scheduling parameters are specified in the +.I param +argument, which is a pointer to a structure of the following form: +.P +.in +4n +.EX +struct sched_param { + ... + int sched_priority; + ... +}; +.EE +.in +.P +In the current implementation, the structure contains only one field, +.IR sched_priority . +The interpretation of +.I param +depends on the selected policy. +.P +Currently, Linux supports the following "normal" +(i.e., non-real-time) scheduling policies as values that may be specified in +.IR policy : +.TP 14 +.B SCHED_OTHER +the standard round-robin time-sharing policy; +.\" In the 2.6 kernel sources, SCHED_OTHER is actually called +.\" SCHED_NORMAL. +.TP +.B SCHED_BATCH +for "batch" style execution of processes; and +.TP +.B SCHED_IDLE +for running +.I very +low priority background jobs. +.P +For each of the above policies, +.I param\->sched_priority +must be 0. +.P +Various "real-time" policies are also supported, +for special time-critical applications that need precise control over +the way in which runnable threads are selected for execution. +For the rules governing when a process may use these policies, see +.BR sched (7). +The real-time policies that may be specified in +.I policy +are: +.TP 14 +.B SCHED_FIFO +a first-in, first-out policy; and +.TP +.B SCHED_RR +a round-robin policy. +.P +For each of the above policies, +.I param\->sched_priority +specifies a scheduling priority for the thread. +This is a number in the range returned by calling +.BR sched_get_priority_min (2) +and +.BR sched_get_priority_max (2) +with the specified +.IR policy . +On Linux, these system calls return, respectively, 1 and 99. +.P +Since Linux 2.6.32, the +.B SCHED_RESET_ON_FORK +flag can be ORed in +.I policy +when calling +.BR sched_setscheduler (). +As a result of including this flag, children created by +.BR fork (2) +do not inherit privileged scheduling policies. +See +.BR sched (7) +for details. +.P +.BR sched_getscheduler () +returns the current scheduling policy of the thread +identified by \fIpid\fP. +If \fIpid\fP equals zero, the policy of the +calling thread will be retrieved. +.SH RETURN VALUE +On success, +.BR sched_setscheduler () +returns zero. +On success, +.BR sched_getscheduler () +returns the policy for the thread (a nonnegative integer). +On error, both calls return \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Invalid arguments: +.I pid +is negative or +.I param +is NULL. +.TP +.B EINVAL +.RB ( sched_setscheduler ()) +.I policy +is not one of the recognized policies. +.TP +.B EINVAL +.RB ( sched_setscheduler ()) +.I param +does not make sense for the specified +.IR policy . +.TP +.B EPERM +The calling thread does not have appropriate privileges. +.TP +.B ESRCH +The thread whose ID is \fIpid\fP could not be found. +.SH VERSIONS +POSIX.1 does not detail the permissions that an unprivileged +thread requires in order to call +.BR sched_setscheduler (), +and details vary across systems. +For example, the Solaris 7 manual page says that +the real or effective user ID of the caller must +match the real user ID or the save set-user-ID of the target. +.P +The scheduling policy and parameters are in fact per-thread +attributes on Linux. +The value returned from a call to +.BR gettid (2) +can be passed in the argument +.IR pid . +Specifying +.I pid +as 0 will operate on the attributes of the calling thread, +and passing the value returned from a call to +.BR getpid (2) +will operate on the attributes of the main thread of the thread group. +(If you are using the POSIX threads API, then use +.BR pthread_setschedparam (3), +.BR pthread_getschedparam (3), +and +.BR pthread_setschedprio (3), +instead of the +.BR sched_* (2) +system calls.) +.SH STANDARDS +POSIX.1-2008 (but see BUGS below). +.P +.B SCHED_BATCH +and +.B SCHED_IDLE +are Linux-specific. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Further details of the semantics of all of the above "normal" +and "real-time" scheduling policies can be found in the +.BR sched (7) +manual page. +That page also describes an additional policy, +.BR SCHED_DEADLINE , +which is settable only via +.BR sched_setattr (2). +.P +POSIX systems on which +.BR sched_setscheduler () +and +.BR sched_getscheduler () +are available define +.B _POSIX_PRIORITY_SCHEDULING +in \fI\fP. +.SH BUGS +POSIX.1 says that on success, +.BR sched_setscheduler () +should return the previous scheduling policy. +Linux +.BR sched_setscheduler () +does not conform to this requirement, +since it always returns 0 on success. +.SH SEE ALSO +.ad l +.nh +.BR chrt (1), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getaffinity (2), +.BR sched_getattr (2), +.BR sched_getparam (2), +.BR sched_rr_get_interval (2), +.BR sched_setaffinity (2), +.BR sched_setattr (2), +.BR sched_setparam (2), +.BR sched_yield (2), +.BR setpriority (2), +.BR capabilities (7), +.BR cpuset (7), +.BR sched (7) +.ad diff --git a/man/man2/sched_yield.2 b/man/man2/sched_yield.2 new file mode 100644 index 0000000..e661927 --- /dev/null +++ b/man/man2/sched_yield.2 @@ -0,0 +1,76 @@ +.\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1996-04-01 Tom Bjorkholm +.\" First version written +.\" 1996-04-10 Markus Kuhn +.\" revision +.\" +.TH sched_yield 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sched_yield \- yield the processor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B int sched_yield(void); +.fi +.SH DESCRIPTION +.BR sched_yield () +causes the calling thread to relinquish the CPU. +The thread is moved to the end of the queue for its static +priority and a new thread gets to run. +.SH RETURN VALUE +On success, +.BR sched_yield () +returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +In the Linux implementation, +.BR sched_yield () +always succeeds. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001 (but optional). +POSIX.1-2008. +.P +Before POSIX.1-2008, +systems on which +.BR sched_yield () +is available defined +.B _POSIX_PRIORITY_SCHEDULING +in +.IR . +.SH CAVEATS +.BR sched_yield () +is intended for use with real-time scheduling policies (i.e., +.B SCHED_FIFO +or +.BR SCHED_RR ). +Use of +.BR sched_yield () +with nondeterministic scheduling policies such as +.B SCHED_OTHER +is unspecified and very likely means your application design is broken. +.P +If the calling thread is the only thread in the highest +priority list at that time, +it will continue to run after a call to +.BR sched_yield (). +.P +Avoid calling +.BR sched_yield () +unnecessarily or inappropriately +(e.g., when resources needed by other +schedulable threads are still held by the caller), +since doing so will result in unnecessary context switches, +which will degrade system performance. +.SH SEE ALSO +.BR sched (7) diff --git a/man/man2/seccomp.2 b/man/man2/seccomp.2 new file mode 100644 index 0000000..83f5406 --- /dev/null +++ b/man/man2/seccomp.2 @@ -0,0 +1,1245 @@ +.\" Copyright (C) 2014 Kees Cook +.\" and Copyright (C) 2012 Will Drewry +.\" and Copyright (C) 2008, 2014,2017 Michael Kerrisk +.\" and Copyright (C) 2017 Tyler Hicks +.\" and Copyright (C) 2020 Tycho Andersen +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH seccomp 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +seccomp \- operate on Secure Computing state of the process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SECCOMP_* " constants */" +.BR "#include " " /* Definition of " "struct sock_fprog" " */" +.BR "#include " " /* Definition of " AUDIT_* " constants */" +.BR "#include " " /* Definition of " SIG* " constants */" +.BR "#include " " /* Definition of " PTRACE_* " constants */" +.\" Kees Cook noted: Anything that uses SECCOMP_RET_TRACE returns will +.\" need +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_seccomp, unsigned int " operation ", unsigned int " flags , +.BI " void *" args ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR seccomp (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR seccomp () +system call operates on the Secure Computing (seccomp) state of the +calling process. +.P +Currently, Linux supports the following +.I operation +values: +.TP +.B SECCOMP_SET_MODE_STRICT +The only system calls that the calling thread is permitted to make are +.BR read (2), +.BR write (2), +.BR _exit (2) +(but not +.BR exit_group (2)), +and +.BR sigreturn (2). +Other system calls result in the termination of the calling thread, +or termination of the entire process with the +.B SIGKILL +signal when there is only one thread. +Strict secure computing mode is useful for number-crunching +applications that may need to execute untrusted byte code, perhaps +obtained by reading from a pipe or socket. +.IP +Note that although the calling thread can no longer call +.BR sigprocmask (2), +it can use +.BR sigreturn (2) +to block all signals apart from +.B SIGKILL +and +.BR SIGSTOP . +This means that +.BR alarm (2) +(for example) is not sufficient for restricting the process's execution time. +Instead, to reliably terminate the process, +.B SIGKILL +must be used. +This can be done by using +.BR timer_create (2) +with +.B SIGEV_SIGNAL +and +.I sigev_signo +set to +.BR SIGKILL , +or by using +.BR setrlimit (2) +to set the hard limit for +.BR RLIMIT_CPU . +.IP +This operation is available only if the kernel is configured with +.B CONFIG_SECCOMP +enabled. +.IP +The value of +.I flags +must be 0, and +.I args +must be NULL. +.IP +This operation is functionally identical to the call: +.IP +.in +4n +.EX +prctl(PR_SET_SECCOMP, SECCOMP_MODE_STRICT); +.EE +.in +.TP +.B SECCOMP_SET_MODE_FILTER +The system calls allowed are defined by a pointer to a Berkeley Packet +Filter (BPF) passed via +.IR args . +This argument is a pointer to a +.IR "struct\~sock_fprog" ; +it can be designed to filter arbitrary system calls and system call +arguments. +If the filter is invalid, +.BR seccomp () +fails, returning +.B EINVAL +in +.IR errno . +.IP +If +.BR fork (2) +or +.BR clone (2) +is allowed by the filter, any child processes will be constrained to +the same system call filters as the parent. +If +.BR execve (2) +is allowed, +the existing filters will be preserved across a call to +.BR execve (2). +.IP +In order to use the +.B SECCOMP_SET_MODE_FILTER +operation, either the calling thread must have the +.B CAP_SYS_ADMIN +capability in its user namespace, or the thread must already have the +.I no_new_privs +bit set. +If that bit was not already set by an ancestor of this thread, +the thread must make the following call: +.IP +.in +4n +.EX +prctl(PR_SET_NO_NEW_PRIVS, 1); +.EE +.in +.IP +Otherwise, the +.B SECCOMP_SET_MODE_FILTER +operation fails and returns +.B EACCES +in +.IR errno . +This requirement ensures that an unprivileged process cannot apply +a malicious filter and then invoke a set-user-ID or +other privileged program using +.BR execve (2), +thus potentially compromising that program. +(Such a malicious filter might, for example, cause an attempt to use +.BR setuid (2) +to set the caller's user IDs to nonzero values to instead +return 0 without actually making the system call. +Thus, the program might be tricked into retaining superuser privileges +in circumstances where it is possible to influence it to do +dangerous things because it did not actually drop privileges.) +.IP +If +.BR prctl (2) +or +.BR seccomp () +is allowed by the attached filter, further filters may be added. +This will increase evaluation time, but allows for further reduction of +the attack surface during execution of a thread. +.IP +The +.B SECCOMP_SET_MODE_FILTER +operation is available only if the kernel is configured with +.B CONFIG_SECCOMP_FILTER +enabled. +.IP +When +.I flags +is 0, this operation is functionally identical to the call: +.IP +.in +4n +.EX +prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, args); +.EE +.in +.IP +The recognized +.I flags +are: +.RS +.TP +.BR SECCOMP_FILTER_FLAG_LOG " (since Linux 4.14)" +.\" commit e66a39977985b1e69e17c4042cb290768eca9b02 +All filter return actions except +.B SECCOMP_RET_ALLOW +should be logged. +An administrator may override this filter flag by preventing specific +actions from being logged via the +.I /proc/sys/kernel/seccomp/actions_logged +file. +.TP +.BR SECCOMP_FILTER_FLAG_NEW_LISTENER " (since Linux 5.0)" +.\" commit 6a21cc50f0c7f87dae5259f6cfefe024412313f6 +After successfully installing the filter program, +return a new user-space notification file descriptor. +(The close-on-exec flag is set for the file descriptor.) +When the filter returns +.B SECCOMP_RET_USER_NOTIF +a notification will be sent to this file descriptor. +.IP +At most one seccomp filter using the +.B SECCOMP_FILTER_FLAG_NEW_LISTENER +flag can be installed for a thread. +.IP +See +.BR seccomp_unotify (2) +for further details. +.TP +.BR SECCOMP_FILTER_FLAG_SPEC_ALLOW " (since Linux 4.17)" +.\" commit 00a02d0c502a06d15e07b857f8ff921e3e402675 +Disable Speculative Store Bypass mitigation. +.TP +.B SECCOMP_FILTER_FLAG_TSYNC +When adding a new filter, synchronize all other threads of the calling +process to the same seccomp filter tree. +A "filter tree" is the ordered list of filters attached to a thread. +(Attaching identical filters in separate +.BR seccomp () +calls results in different filters from this perspective.) +.IP +If any thread cannot synchronize to the same filter tree, +the call will not attach the new seccomp filter, +and will fail, returning the first thread ID found that cannot synchronize. +Synchronization will fail if another thread in the same process is in +.B SECCOMP_MODE_STRICT +or if it has attached new seccomp filters to itself, +diverging from the calling thread's filter tree. +.RE +.TP +.BR SECCOMP_GET_ACTION_AVAIL " (since Linux 4.14)" +.\" commit d612b1fd8010d0d67b5287fe146b8b55bcbb8655 +Test to see if an action is supported by the kernel. +This operation is helpful to confirm that the kernel knows +of a more recently added filter return action +since the kernel treats all unknown actions as +.BR SECCOMP_RET_KILL_PROCESS . +.IP +The value of +.I flags +must be 0, and +.I args +must be a pointer to an unsigned 32-bit filter return action. +.TP +.BR SECCOMP_GET_NOTIF_SIZES " (since Linux 5.0)" +.\" commit 6a21cc50f0c7f87dae5259f6cfefe024412313f6 +Get the sizes of the seccomp user-space notification structures. +Since these structures may evolve and grow over time, +this command can be used to determine how +much memory to allocate for sending and receiving notifications. +.IP +The value of +.I flags +must be 0, and +.I args +must be a pointer to a +.IR "struct seccomp_notif_sizes" , +which has the following form: +.IP +.EX +struct seccomp_notif_sizes + __u16 seccomp_notif; /* Size of notification structure */ + __u16 seccomp_notif_resp; /* Size of response structure */ + __u16 seccomp_data; /* Size of \[aq]struct seccomp_data\[aq] */ +}; +.EE +.IP +See +.BR seccomp_unotify (2) +for further details. +.\" +.SS Filters +When adding filters via +.BR SECCOMP_SET_MODE_FILTER , +.I args +points to a filter program: +.P +.in +4n +.EX +struct sock_fprog { + unsigned short len; /* Number of BPF instructions */ + struct sock_filter *filter; /* Pointer to array of + BPF instructions */ +}; +.EE +.in +.P +Each program must contain one or more BPF instructions: +.P +.in +4n +.EX +struct sock_filter { /* Filter block */ + __u16 code; /* Actual filter code */ + __u8 jt; /* Jump true */ + __u8 jf; /* Jump false */ + __u32 k; /* Generic multiuse field */ +}; +.EE +.in +.P +When executing the instructions, the BPF program operates on the +system call information made available (i.e., use the +.B BPF_ABS +addressing mode) as a (read-only) +.\" Quoting Kees Cook: +.\" If BPF even allows changing the data, it's not copied back to +.\" the syscall when it runs. Anything wanting to do things like +.\" that would need to use ptrace to catch the call and directly +.\" modify the registers before continuing with the call. +buffer of the following form: +.P +.in +4n +.EX +struct seccomp_data { + int nr; /* System call number */ + __u32 arch; /* AUDIT_ARCH_* value + (see ) */ + __u64 instruction_pointer; /* CPU instruction pointer */ + __u64 args[6]; /* Up to 6 system call arguments */ +}; +.EE +.in +.P +Because numbering of system calls varies between architectures and +some architectures (e.g., x86-64) allow user-space code to use +the calling conventions of multiple architectures +(and the convention being used may vary over the life of a process that uses +.BR execve (2) +to execute binaries that employ the different conventions), +it is usually necessary to verify the value of the +.I arch +field. +.P +It is strongly recommended to use an allow-list approach whenever +possible because such an approach is more robust and simple. +A deny-list will have to be updated whenever a potentially +dangerous system call is added (or a dangerous flag or option if those +are deny-listed), and it is often possible to alter the +representation of a value without altering its meaning, leading to +a deny-list bypass. +See also +.I Caveats +below. +.P +The +.I arch +field is not unique for all calling conventions. +The x86-64 ABI and the x32 ABI both use +.B AUDIT_ARCH_X86_64 +as +.IR arch , +and they run on the same processors. +Instead, the mask +.B __X32_SYSCALL_BIT +is used on the system call number to tell the two ABIs apart. +.\" As noted by Dave Drysdale in a note at the end of +.\" https://lwn.net/Articles/604515/ +.\" One additional detail to point out for the x32 ABI case: +.\" the syscall number gets a high bit set (__X32_SYSCALL_BIT), +.\" to mark it as an x32 call. +.\" +.\" If x32 support is included in the kernel, then __SYSCALL_MASK +.\" will have a value that is not all-ones, and this will trigger +.\" an extra instruction in system_call to mask off the extra bit, +.\" so that the syscall table indexing still works. +.P +This means that a policy must either deny all syscalls with +.B __X32_SYSCALL_BIT +or it must recognize syscalls with and without +.B __X32_SYSCALL_BIT +set. +A list of system calls to be denied based on +.I nr +that does not also contain +.I nr +values with +.B __X32_SYSCALL_BIT +set can be bypassed by a malicious program that sets +.BR __X32_SYSCALL_BIT . +.P +Additionally, kernels prior to Linux 5.4 incorrectly permitted +.I nr +in the ranges 512-547 as well as the corresponding non-x32 syscalls ORed +with +.BR __X32_SYSCALL_BIT . +For example, +.I nr +== 521 and +.I nr +== (101 | +.BR __X32_SYSCALL_BIT ) +would result in invocations of +.BR ptrace (2) +with potentially confused x32-vs-x86_64 semantics in the kernel. +Policies intended to work on kernels before Linux 5.4 must ensure that they +deny or otherwise correctly handle these system calls. +On Linux 5.4 and newer, +.\" commit 6365b842aae4490ebfafadfc6bb27a6d3cc54757 +such system calls will fail with the error +.BR ENOSYS , +without doing anything. +.P +The +.I instruction_pointer +field provides the address of the machine-language instruction that +performed the system call. +This might be useful in conjunction with the use of +.IR /proc/ pid /maps +to perform checks based on which region (mapping) of the program +made the system call. +(Probably, it is wise to lock down the +.BR mmap (2) +and +.BR mprotect (2) +system calls to prevent the program from subverting such checks.) +.P +When checking values from +.IR args , +keep in mind that arguments are often +silently truncated before being processed, but after the seccomp check. +For example, this happens if the i386 ABI is used on an +x86-64 kernel: although the kernel will normally not look beyond +the 32 lowest bits of the arguments, the values of the full +64-bit registers will be present in the seccomp data. +A less surprising example is that if the x86-64 ABI is used to perform +a system call that takes an argument of type +.IR int , +the more-significant half of the argument register is ignored by +the system call, but visible in the seccomp data. +.P +A seccomp filter returns a 32-bit value consisting of two parts: +the most significant 16 bits +(corresponding to the mask defined by the constant +.BR SECCOMP_RET_ACTION_FULL ) +contain one of the "action" values listed below; +the least significant 16-bits (defined by the constant +.BR SECCOMP_RET_DATA ) +are "data" to be associated with this return value. +.P +If multiple filters exist, they are \fIall\fP executed, +in reverse order of their addition to the filter tree\[em]that is, +the most recently installed filter is executed first. +(Note that all filters will be called +even if one of the earlier filters returns +.BR SECCOMP_RET_KILL . +This is done to simplify the kernel code and to provide a +tiny speed-up in the execution of sets of filters by +avoiding a check for this uncommon case.) +.\" From an Aug 2015 conversation with Kees Cook where I asked why *all* +.\" filters are applied even if one of the early filters returns +.\" SECCOMP_RET_KILL: +.\" +.\" It's just because it would be an optimization that would only speed up +.\" the RET_KILL case, but it's the uncommon one and the one that doesn't +.\" benefit meaningfully from such a change (you need to kill the process +.\" really quickly?). We would speed up killing a program at the (albeit +.\" tiny) expense to all other filtered programs. Best to keep the filter +.\" execution logic clear, simple, and as fast as possible for all +.\" filters. +The return value for the evaluation of a given system call is the first-seen +action value of highest precedence (along with its accompanying data) +returned by execution of all of the filters. +.P +In decreasing order of precedence, +the action values that may be returned by a seccomp filter are: +.TP +.BR SECCOMP_RET_KILL_PROCESS " (since Linux 4.14)" +.\" commit 4d3b0b05aae9ee9ce0970dc4cc0fb3fad5e85945 +.\" commit 0466bdb99e8744bc9befa8d62a317f0fd7fd7421 +This value results in immediate termination of the process, +with a core dump. +The system call is not executed. +By contrast with +.B SECCOMP_RET_KILL_THREAD +below, all threads in the thread group are terminated. +(For a discussion of thread groups, see the description of the +.B CLONE_THREAD +flag in +.BR clone (2).) +.IP +The process terminates +.I "as though" +killed by a +.B SIGSYS +signal. +Even if a signal handler has been registered for +.BR SIGSYS , +the handler will be ignored in this case and the process always terminates. +To a parent process that is waiting on this process (using +.BR waitpid (2) +or similar), the returned +.I wstatus +will indicate that its child was terminated as though by a +.B SIGSYS +signal. +.TP +.BR SECCOMP_RET_KILL_THREAD " (or " SECCOMP_RET_KILL ) +This value results in immediate termination of the thread +that made the system call. +The system call is not executed. +Other threads in the same thread group will continue to execute. +.IP +The thread terminates +.I "as though" +killed by a +.B SIGSYS +signal. +See +.B SECCOMP_RET_KILL_PROCESS +above. +.IP +.\" See these commits: +.\" seccomp: dump core when using SECCOMP_RET_KILL +.\" (b25e67161c295c98acda92123b2dd1e7d8642901) +.\" seccomp: Only dump core when single-threaded +.\" (d7276e321ff8a53106a59c85ca46d03e34288893) +Before Linux 4.11, +any process terminated in this way would not trigger a coredump +(even though +.B SIGSYS +is documented in +.BR signal (7) +as having a default action of termination with a core dump). +Since Linux 4.11, +a single-threaded process will dump core if terminated in this way. +.IP +With the addition of +.B SECCOMP_RET_KILL_PROCESS +in Linux 4.14, +.B SECCOMP_RET_KILL_THREAD +was added as a synonym for +.BR SECCOMP_RET_KILL , +in order to more clearly distinguish the two actions. +.IP +.BR Note : +the use of +.B SECCOMP_RET_KILL_THREAD +to kill a single thread in a multithreaded process is likely to leave the +process in a permanently inconsistent and possibly corrupt state. +.TP +.B SECCOMP_RET_TRAP +This value results in the kernel sending a thread-directed +.B SIGSYS +signal to the triggering thread. +(The system call is not executed.) +Various fields will be set in the +.I siginfo_t +structure (see +.BR sigaction (2)) +associated with signal: +.RS +.IP \[bu] 3 +.I si_signo +will contain +.BR SIGSYS . +.IP \[bu] +.I si_call_addr +will show the address of the system call instruction. +.IP \[bu] +.I si_syscall +and +.I si_arch +will indicate which system call was attempted. +.IP \[bu] +.I si_code +will contain +.BR SYS_SECCOMP . +.IP \[bu] +.I si_errno +will contain the +.B SECCOMP_RET_DATA +portion of the filter return value. +.RE +.IP +The program counter will be as though the system call happened +(i.e., the program counter will not point to the system call instruction). +The return value register will contain an architecture\-dependent value; +if resuming execution, set it to something appropriate for the system call. +(The architecture dependency is because replacing it with +.B ENOSYS +could overwrite some useful information.) +.TP +.B SECCOMP_RET_ERRNO +This value results in the +.B SECCOMP_RET_DATA +portion of the filter's return value being passed to user space as the +.I errno +value without executing the system call. +.TP +.BR SECCOMP_RET_USER_NOTIF " (since Linux 5.0)" +.\" commit 6a21cc50f0c7f87dae5259f6cfefe024412313f6 +Forward the system call to an attached user-space supervisor +process to allow that process to decide what to do with the system call. +If there is no attached supervisor (either +because the filter was not installed with the +.B SECCOMP_FILTER_FLAG_NEW_LISTENER +flag or because the file descriptor was closed), the filter returns +.B ENOSYS +(similar to what happens when a filter returns +.B SECCOMP_RET_TRACE +and there is no tracer). +See +.BR seccomp_unotify (2) +for further details. +.IP +Note that the supervisor process will not be notified +if another filter returns an action value with a precedence greater than +.BR SECCOMP_RET_USER_NOTIF . +.TP +.B SECCOMP_RET_TRACE +When returned, this value will cause the kernel to attempt to notify a +.BR ptrace (2)-based +tracer prior to executing the system call. +If there is no tracer present, +the system call is not executed and returns a failure status with +.I errno +set to +.BR ENOSYS . +.IP +A tracer will be notified if it requests +.B PTRACE_O_TRACESECCOMP +using +.IR ptrace(PTRACE_SETOPTIONS) . +The tracer will be notified of a +.B PTRACE_EVENT_SECCOMP +and the +.B SECCOMP_RET_DATA +portion of the filter's return value will be available to the tracer via +.BR PTRACE_GETEVENTMSG . +.IP +The tracer can skip the system call by changing the system call number +to \-1. +Alternatively, the tracer can change the system call +requested by changing the system call to a valid system call number. +If the tracer asks to skip the system call, then the system call will +appear to return the value that the tracer puts in the return value register. +.IP +.\" This was changed in ce6526e8afa4. +.\" A related hole, using PTRACE_SYSCALL instead of SECCOMP_RET_TRACE, was +.\" changed in arch-specific commits, e.g. 93e35efb8de4 for X86 and +.\" 0f3912fd934c for ARM. +Before Linux 4.8, the seccomp check will not be run again after the tracer is +notified. +(This means that, on older kernels, seccomp-based sandboxes +.B "must not" +allow use of +.BR ptrace (2)\[em]even +of other +sandboxed processes\[em]without extreme care; +ptracers can use this mechanism to escape from the seccomp sandbox.) +.IP +Note that a tracer process will not be notified +if another filter returns an action value with a precedence greater than +.BR SECCOMP_RET_TRACE . +.TP +.BR SECCOMP_RET_LOG " (since Linux 4.14)" +.\" commit 59f5cf44a38284eb9e76270c786fb6cc62ef8ac4 +This value results in the system call being executed after +the filter return action is logged. +An administrator may override the logging of this action via +the +.I /proc/sys/kernel/seccomp/actions_logged +file. +.TP +.B SECCOMP_RET_ALLOW +This value results in the system call being executed. +.P +If an action value other than one of the above is specified, +then the filter action is treated as either +.B SECCOMP_RET_KILL_PROCESS +(since Linux 4.14) +.\" commit 4d3b0b05aae9ee9ce0970dc4cc0fb3fad5e85945 +or +.B SECCOMP_RET_KILL_THREAD +(in Linux 4.13 and earlier). +.\" +.SS /proc interfaces +The files in the directory +.I /proc/sys/kernel/seccomp +provide additional seccomp information and configuration: +.TP +.IR actions_avail " (since Linux 4.14)" +.\" commit 8e5f1ad116df6b0de65eac458d5e7c318d1c05af +A read-only ordered list of seccomp filter return actions in string form. +The ordering, from left-to-right, is in decreasing order of precedence. +The list represents the set of seccomp filter return actions +supported by the kernel. +.TP +.IR actions_logged " (since Linux 4.14)" +.\" commit 0ddec0fc8900201c0897b87b762b7c420436662f +A read-write ordered list of seccomp filter return actions that +are allowed to be logged. +Writes to the file do not need to be in ordered form but reads from +the file will be ordered in the same way as the +.I actions_avail +file. +.IP +It is important to note that the value of +.I actions_logged +does not prevent certain filter return actions from being logged when +the audit subsystem is configured to audit a task. +If the action is not found in the +.I actions_logged +file, the final decision on whether to audit the action for that task is +ultimately left up to the audit subsystem to decide for all filter return +actions other than +.BR SECCOMP_RET_ALLOW . +.IP +The "allow" string is not accepted in the +.I actions_logged +file as it is not possible to log +.B SECCOMP_RET_ALLOW +actions. +Attempting to write "allow" to the file will fail with the error +.BR EINVAL . +.\" +.SS Audit logging of seccomp actions +.\" commit 59f5cf44a38284eb9e76270c786fb6cc62ef8ac4 +Since Linux 4.14, the kernel provides the facility to log the +actions returned by seccomp filters in the audit log. +The kernel makes the decision to log an action based on +the action type, whether or not the action is present in the +.I actions_logged +file, and whether kernel auditing is enabled +(e.g., via the kernel boot option +.IR audit=1 ). +.\" or auditing could be enabled via the netlink API (AUDIT_SET) +The rules are as follows: +.IP \[bu] 3 +If the action is +.BR SECCOMP_RET_ALLOW , +the action is not logged. +.IP \[bu] +Otherwise, if the action is either +.B SECCOMP_RET_KILL_PROCESS +or +.BR SECCOMP_RET_KILL_THREAD , +and that action appears in the +.I actions_logged +file, the action is logged. +.IP \[bu] +Otherwise, if the filter has requested logging (the +.B SECCOMP_FILTER_FLAG_LOG +flag) +and the action appears in the +.I actions_logged +file, the action is logged. +.IP \[bu] +Otherwise, if kernel auditing is enabled and the process is being audited +.RB ( autrace (8)), +the action is logged. +.IP \[bu] +Otherwise, the action is not logged. +.SH RETURN VALUE +On success, +.BR seccomp () +returns 0. +On error, if +.B SECCOMP_FILTER_FLAG_TSYNC +was used, +the return value is the ID of the thread +that caused the synchronization failure. +(This ID is a kernel thread ID of the type returned by +.BR clone (2) +and +.BR gettid (2).) +On other errors, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR seccomp () +can fail for the following reasons: +.TP +.B EACCES +The caller did not have the +.B CAP_SYS_ADMIN +capability in its user namespace, or had not set +.I no_new_privs +before using +.BR SECCOMP_SET_MODE_FILTER . +.TP +.B EBUSY +While installing a new filter, the +.B SECCOMP_FILTER_FLAG_NEW_LISTENER +flag was specified, +but a previous filter had already been installed with that flag. +.TP +.B EFAULT +.I args +was not a valid address. +.TP +.B EINVAL +.I operation +is unknown or is not supported by this kernel version or configuration. +.TP +.B EINVAL +The specified +.I flags +are invalid for the given +.IR operation . +.TP +.B EINVAL +.I operation +included +.BR BPF_ABS , +but the specified offset was not aligned to a 32-bit boundary or exceeded +.IR "sizeof(struct\~seccomp_data)" . +.TP +.B EINVAL +.\" See kernel/seccomp.c::seccomp_may_assign_mode() in Linux 3.18 sources +A secure computing mode has already been set, and +.I operation +differs from the existing setting. +.TP +.B EINVAL +.I operation +specified +.BR SECCOMP_SET_MODE_FILTER , +but the filter program pointed to by +.I args +was not valid or the length of the filter program was zero or exceeded +.B BPF_MAXINSNS +(4096) instructions. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOMEM +.\" ENOMEM in kernel/seccomp.c::seccomp_attach_filter() in Linux 3.18 sources +The total length of all filter programs attached +to the calling thread would exceed +.B MAX_INSNS_PER_PATH +(32768) instructions. +Note that for the purposes of calculating this limit, +each already existing filter program incurs an +overhead penalty of 4 instructions. +.TP +.B EOPNOTSUPP +.I operation +specified +.BR SECCOMP_GET_ACTION_AVAIL , +but the kernel does not support the filter return action specified by +.IR args . +.TP +.B ESRCH +Another thread caused a failure during thread sync, but its ID could not +be determined. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.17. +.\" FIXME . Add glibc version +.SH NOTES +Rather than hand-coding seccomp filters as shown in the example below, +you may prefer to employ the +.I libseccomp +library, which provides a front-end for generating seccomp filters. +.P +The +.I Seccomp +field of the +.IR /proc/ pid /status +file provides a method of viewing the seccomp mode of a process; see +.BR proc (5). +.P +.BR seccomp () +provides a superset of the functionality provided by the +.BR prctl (2) +.B PR_SET_SECCOMP +operation (which does not support +.IR flags ). +.P +Since Linux 4.4, the +.BR ptrace (2) +.B PTRACE_SECCOMP_GET_FILTER +operation can be used to dump a process's seccomp filters. +.\" +.SS Architecture support for seccomp BPF +Architecture support for seccomp BPF filtering +.\" Check by grepping for HAVE_ARCH_SECCOMP_FILTER in Kconfig files in +.\" kernel source. Last checked in Linux 4.16-rc source. +is available on the following architectures: +.IP \[bu] 3 +x86-64, i386, x32 (since Linux 3.5) +.PD 0 +.IP \[bu] +ARM (since Linux 3.8) +.IP \[bu] +s390 (since Linux 3.8) +.IP \[bu] +MIPS (since Linux 3.16) +.IP \[bu] +ARM-64 (since Linux 3.19) +.IP \[bu] +PowerPC (since Linux 4.3) +.IP \[bu] +Tile (since Linux 4.3) +.IP \[bu] +PA-RISC (since Linux 4.6) +.\" User mode Linux since Linux 4.6 +.PD +.\" +.SS Caveats +There are various subtleties to consider when applying seccomp filters +to a program, including the following: +.IP \[bu] 3 +Some traditional system calls have user-space implementations in the +.BR vdso (7) +on many architectures. +Notable examples include +.BR clock_gettime (2), +.BR gettimeofday (2), +and +.BR time (2). +On such architectures, +seccomp filtering for these system calls will have no effect. +(However, there are cases where the +.BR vdso (7) +implementations may fall back to invoking the true system call, +in which case seccomp filters would see the system call.) +.IP \[bu] +Seccomp filtering is based on system call numbers. +However, applications typically do not directly invoke system calls, +but instead call wrapper functions in the C library which +in turn invoke the system calls. +Consequently, one must be aware of the following: +.RS +.IP \[bu] 3 +The glibc wrappers for some traditional system calls may actually +employ system calls with different names in the kernel. +For example, the +.BR exit (2) +wrapper function actually employs the +.BR exit_group (2) +system call, and the +.BR fork (2) +wrapper function actually calls +.BR clone (2). +.IP \[bu] +The behavior of wrapper functions may vary across architectures, +according to the range of system calls provided on those architectures. +In other words, the same wrapper function may invoke +different system calls on different architectures. +.IP \[bu] +Finally, the behavior of wrapper functions can change across glibc versions. +For example, in older versions, the glibc wrapper function for +.BR open (2) +invoked the system call of the same name, +but starting in glibc 2.26, the implementation switched to calling +.BR openat (2) +on all architectures. +.RE +.P +The consequence of the above points is that it may be necessary +to filter for a system call other than might be expected. +Various manual pages in Section 2 provide helpful details +about the differences between wrapper functions and +the underlying system calls in subsections entitled +.IR "C library/kernel differences" . +.P +Furthermore, note that the application of seccomp filters +even risks causing bugs in an application, +when the filters cause unexpected failures for legitimate operations +that the application might need to perform. +Such bugs may not easily be discovered when testing the seccomp +filters if the bugs occur in rarely used application code paths. +.\" +.SS Seccomp-specific BPF details +Note the following BPF details specific to seccomp filters: +.IP \[bu] 3 +The +.B BPF_H +and +.B BPF_B +size modifiers are not supported: all operations must load and store +(4-byte) words +.RB ( BPF_W ). +.IP \[bu] +To access the contents of the +.I seccomp_data +buffer, use the +.B BPF_ABS +addressing mode modifier. +.IP \[bu] +The +.B BPF_LEN +addressing mode modifier yields an immediate mode operand +whose value is the size of the +.I seccomp_data +buffer. +.SH EXAMPLES +The program below accepts four or more arguments. +The first three arguments are a system call number, +a numeric architecture identifier, and an error number. +The program uses these values to construct a BPF filter +that is used at run time to perform the following checks: +.IP \[bu] 3 +If the program is not running on the specified architecture, +the BPF filter causes system calls to fail with the error +.BR ENOSYS . +.IP \[bu] +If the program attempts to execute the system call with the specified number, +the BPF filter causes the system call to fail, with +.I errno +being set to the specified error number. +.P +The remaining command-line arguments specify +the pathname and additional arguments of a program +that the example program should attempt to execute using +.BR execv (3) +(a library function that employs the +.BR execve (2) +system call). +Some example runs of the program are shown below. +.P +First, we display the architecture that we are running on (x86-64) +and then construct a shell function that looks up system call +numbers on this architecture: +.P +.in +4n +.EX +$ \fBuname \-m\fP +x86_64 +$ \fBsyscall_nr() { + cat /usr/src/linux/arch/x86/syscalls/syscall_64.tbl | \e + awk \[aq]$2 != "x32" && $3 == "\[aq]$1\[aq]" { print $1 }\[aq] +}\fP +.EE +.in +.P +When the BPF filter rejects a system call (case [2] above), +it causes the system call to fail with the error number +specified on the command line. +In the experiments shown here, we'll use error number 99: +.P +.in +4n +.EX +$ \fBerrno 99\fP +EADDRNOTAVAIL 99 Cannot assign requested address +.EE +.in +.P +In the following example, we attempt to run the command +.BR whoami (1), +but the BPF filter rejects the +.BR execve (2) +system call, so that the command is not even executed: +.P +.in +4n +.EX +$ \fBsyscall_nr execve\fP +59 +$ \fB./a.out\fP +Usage: ./a.out [] +Hint for : AUDIT_ARCH_I386: 0x40000003 + AUDIT_ARCH_X86_64: 0xC000003E +$ \fB./a.out 59 0xC000003E 99 /bin/whoami\fP +execv: Cannot assign requested address +.EE +.in +.P +In the next example, the BPF filter rejects the +.BR write (2) +system call, so that, although it is successfully started, the +.BR whoami (1) +command is not able to write output: +.P +.in +4n +.EX +$ \fBsyscall_nr write\fP +1 +$ \fB./a.out 1 0xC000003E 99 /bin/whoami\fP +.EE +.in +.P +In the final example, +the BPF filter rejects a system call that is not used by the +.BR whoami (1) +command, so it is able to successfully execute and produce output: +.P +.in +4n +.EX +$ \fBsyscall_nr preadv\fP +295 +$ \fB./a.out 295 0xC000003E 99 /bin/whoami\fP +cecilia +.EE +.in +.SS Program source +.\" SRC BEGIN (seccomp.c) +.EX +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +#define X32_SYSCALL_BIT 0x40000000 +#define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0])) +\& +static int +install_filter(int syscall_nr, unsigned int t_arch, int f_errno) +{ + unsigned int upper_nr_limit = 0xffffffff; +\& + /* Assume that AUDIT_ARCH_X86_64 means the normal x86\-64 ABI + (in the x32 ABI, all system calls have bit 30 set in the + \[aq]nr\[aq] field, meaning the numbers are >= X32_SYSCALL_BIT). */ + if (t_arch == AUDIT_ARCH_X86_64) + upper_nr_limit = X32_SYSCALL_BIT \- 1; +\& + struct sock_filter filter[] = { + /* [0] Load architecture from \[aq]seccomp_data\[aq] buffer into + accumulator. */ + BPF_STMT(BPF_LD | BPF_W | BPF_ABS, + (offsetof(struct seccomp_data, arch))), +\& + /* [1] Jump forward 5 instructions if architecture does not + match \[aq]t_arch\[aq]. */ + BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, t_arch, 0, 5), +\& + /* [2] Load system call number from \[aq]seccomp_data\[aq] buffer into + accumulator. */ + BPF_STMT(BPF_LD | BPF_W | BPF_ABS, + (offsetof(struct seccomp_data, nr))), +\& + /* [3] Check ABI \- only needed for x86\-64 in deny\-list use + cases. Use BPF_JGT instead of checking against the bit + mask to avoid having to reload the syscall number. */ + BPF_JUMP(BPF_JMP | BPF_JGT | BPF_K, upper_nr_limit, 3, 0), +\& + /* [4] Jump forward 1 instruction if system call number + does not match \[aq]syscall_nr\[aq]. */ + BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, syscall_nr, 0, 1), +\& + /* [5] Matching architecture and system call: don\[aq]t execute + the system call, and return \[aq]f_errno\[aq] in \[aq]errno\[aq]. */ + BPF_STMT(BPF_RET | BPF_K, + SECCOMP_RET_ERRNO | (f_errno & SECCOMP_RET_DATA)), +\& + /* [6] Destination of system call number mismatch: allow other + system calls. */ + BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW), +\& + /* [7] Destination of architecture mismatch: kill process. */ + BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_KILL_PROCESS), + }; +\& + struct sock_fprog prog = { + .len = ARRAY_SIZE(filter), + .filter = filter, + }; +\& + if (syscall(SYS_seccomp, SECCOMP_SET_MODE_FILTER, 0, &prog)) { + perror("seccomp"); + return 1; + } +\& + return 0; +} +\& +int +main(int argc, char *argv[]) +{ + if (argc < 5) { + fprintf(stderr, "Usage: " + "%s []\en" + "Hint for : AUDIT_ARCH_I386: 0x%X\en" + " AUDIT_ARCH_X86_64: 0x%X\en" + "\en", argv[0], AUDIT_ARCH_I386, AUDIT_ARCH_X86_64); + exit(EXIT_FAILURE); + } +\& + if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { + perror("prctl"); + exit(EXIT_FAILURE); + } +\& + if (install_filter(strtol(argv[1], NULL, 0), + strtoul(argv[2], NULL, 0), + strtol(argv[3], NULL, 0))) + exit(EXIT_FAILURE); +\& + execv(argv[4], &argv[4]); + perror("execv"); + exit(EXIT_FAILURE); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR bpfc (1), +.BR strace (1), +.BR bpf (2), +.BR prctl (2), +.BR ptrace (2), +.BR seccomp_unotify (2), +.BR sigaction (2), +.BR proc (5), +.BR signal (7), +.BR socket (7) +.P +Various pages from the +.I libseccomp +library, including: +.BR scmp_sys_resolver (1), +.BR seccomp_export_bpf (3), +.BR seccomp_init (3), +.BR seccomp_load (3), +and +.BR seccomp_rule_add (3). +.P +The kernel source files +.I Documentation/networking/filter.txt +and +.I Documentation/userspace\-api/seccomp_filter.rst +.\" commit c061f33f35be0ccc80f4b8e0aea5dfd2ed7e01a3 +(or +.I Documentation/prctl/seccomp_filter.txt +before Linux 4.13). +.P +McCanne, S.\& and Jacobson, V.\& (1992) +.IR "The BSD Packet Filter: A New Architecture for User-level Packet Capture" , +Proceedings of the USENIX Winter 1993 Conference +.UR http://www.tcpdump.org/papers/bpf\-usenix93.pdf +.UE diff --git a/man/man2/seccomp_unotify.2 b/man/man2/seccomp_unotify.2 new file mode 100644 index 0000000..d8080e0 --- /dev/null +++ b/man/man2/seccomp_unotify.2 @@ -0,0 +1,2011 @@ +.\" Copyright (C) 2020 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH seccomp_unotify 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +seccomp_unotify \- Seccomp user-space notification mechanism +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.BI "int seccomp(unsigned int " operation ", unsigned int " flags \ +", void *" args ); +.P +.B #include +.P +.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_RECV," +.BI " struct seccomp_notif *" req ); +.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_SEND," +.BI " struct seccomp_notif_resp *" resp ); +.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_ID_VALID, __u64 *" id ); +.BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_ADDFD," +.BI " struct seccomp_notif_addfd *" addfd ); +.fi +.SH DESCRIPTION +This page describes the user-space notification mechanism provided by the +Secure Computing (seccomp) facility. +As well as the use of the +.B SECCOMP_FILTER_FLAG_NEW_LISTENER +flag, the +.B SECCOMP_RET_USER_NOTIF +action value, and the +.B SECCOMP_GET_NOTIF_SIZES +operation described in +.BR seccomp (2), +this mechanism involves the use of a number of related +.BR ioctl (2) +operations (described below). +.\" +.SS Overview +In conventional usage of a seccomp filter, +the decision about how to treat a system call is made by the filter itself. +By contrast, the user-space notification mechanism allows +the seccomp filter to delegate +the handling of the system call to another user-space process. +Note that this mechanism is explicitly +.B not +intended as a method implementing security policy; see NOTES. +.P +In the discussion that follows, +the thread(s) on which the seccomp filter is installed is (are) +referred to as the +.IR target , +and the process that is notified by the user-space notification +mechanism is referred to as the +.IR supervisor . +.P +A suitably privileged supervisor can use the user-space notification +mechanism to perform actions on behalf of the target. +The advantage of the user-space notification mechanism is that +the supervisor will +usually be able to retrieve information about the target and the +performed system call that the seccomp filter itself cannot. +(A seccomp filter is limited in the information it can obtain and +the actions that it can perform because it +is running on a virtual machine inside the kernel.) +.P +An overview of the steps performed by the target and the supervisor +is as follows: +.\"------------------------------------- +.IP (1) 5 +The target establishes a seccomp filter in the usual manner, +but with two differences: +.RS +.IP \[bu] 3 +The +.BR seccomp (2) +.I flags +argument includes the flag +.BR SECCOMP_FILTER_FLAG_NEW_LISTENER . +Consequently, the return value of the (successful) +.BR seccomp (2) +call is a new "listening" +file descriptor that can be used to receive notifications. +Only one "listening" seccomp filter can be installed for a thread. +.\" FIXME +.\" Is the last sentence above correct? +.\" +.\" Kees Cook (25 Oct 2020) notes: +.\" +.\" I like this limitation, but I expect that it'll need to change in the +.\" future. Even with LSMs, we see the need for arbitrary stacking, and the +.\" idea of there being only 1 supervisor will eventually break down. Right +.\" now there is only 1 because only container managers are using this +.\" feature. But if some daemon starts using it to isolate some thread, +.\" suddenly it might break if a container manager is trying to listen to it +.\" too, etc. I expect it won't be needed soon, but I do think it'll change. +.\" +.IP \[bu] +In cases where it is appropriate, the seccomp filter returns the action value +.BR SECCOMP_RET_USER_NOTIF . +This return value will trigger a notification event. +.RE +.\"------------------------------------- +.IP (2) +In order that the supervisor can obtain notifications +using the listening file descriptor, +(a duplicate of) that file descriptor must be passed from +the target to the supervisor. +One way in which this could be done is by passing the file descriptor +over a UNIX domain socket connection between the target and the supervisor +(using the +.B SCM_RIGHTS +ancillary message type described in +.BR unix (7)). +Another way to do this is through the use of +.BR pidfd_getfd (2). +.\" Jann Horn: +.\" Instead of using unix domain sockets to send the fd to the +.\" parent, I think you could also use clone3() with +.\" flags==CLONE_FILES|SIGCHLD, dup2() the seccomp fd to an fd +.\" that was reserved in the parent, call unshare(CLONE_FILES) +.\" in the child after setting up the seccomp fd, and wake +.\" up the parent with something like pthread_cond_signal()? +.\" I'm not sure whether that'd look better or worse in the +.\" end though, so maybe just ignore this comment. +.\"------------------------------------- +.IP (3) +The supervisor will receive notification events +on the listening file descriptor. +These events are returned as structures of type +.IR seccomp_notif . +Because this structure and its size may evolve over kernel versions, +the supervisor must first determine the size of this structure +using the +.BR seccomp (2) +.B SECCOMP_GET_NOTIF_SIZES +operation, which returns a structure of type +.IR seccomp_notif_sizes . +The supervisor allocates a buffer of size +.I seccomp_notif_sizes.seccomp_notif +bytes to receive notification events. +In addition,the supervisor allocates another buffer of size +.I seccomp_notif_sizes.seccomp_notif_resp +bytes for the response (a +.I struct seccomp_notif_resp +structure) +that it will provide to the kernel (and thus the target). +.\"------------------------------------- +.IP (4) +The target then performs its workload, +which includes system calls that will be controlled by the seccomp filter. +Whenever one of these system calls causes the filter to return the +.B SECCOMP_RET_USER_NOTIF +action value, the kernel does +.I not +(yet) execute the system call; +instead, execution of the target is temporarily blocked inside +the kernel (in a sleep state that is interruptible by signals) +and a notification event is generated on the listening file descriptor. +.\"------------------------------------- +.IP (5) +The supervisor can now repeatedly monitor the +listening file descriptor for +.BR SECCOMP_RET_USER_NOTIF -triggered +events. +To do this, the supervisor uses the +.B SECCOMP_IOCTL_NOTIF_RECV +.BR ioctl (2) +operation to read information about a notification event; +this operation blocks until an event is available. +The operation returns a +.I seccomp_notif +structure containing information about the system call +that is being attempted by the target. +(As described in NOTES, +the file descriptor can also be monitored with +.BR select (2), +.BR poll (2), +or +.BR epoll (7).) +.\" FIXME +.\" Christian Brauner: +.\" +.\" Do we support O_NONBLOCK with SECCOMP_IOCTL_NOTIF_RECV and if +.\" not should we? +.\" +.\" Michael Kerrisk: +.\" +.\" A quick test suggests that O_NONBLOCK has no effect on the blocking +.\" behavior of SECCOMP_IOCTL_NOTIF_RECV. +. +.\"------------------------------------- +.IP (6) +The +.I seccomp_notif +structure returned by the +.B SECCOMP_IOCTL_NOTIF_RECV +operation includes the same information (a +.I seccomp_data +structure) that was passed to the seccomp filter. +This information allows the supervisor to discover the system call number and +the arguments for the target's system call. +In addition, the notification event contains the ID of the thread +that triggered the notification and a unique cookie value that +is used in subsequent +.B SECCOMP_IOCTL_NOTIF_ID_VALID +and +.B SECCOMP_IOCTL_NOTIF_SEND +operations. +.IP +The information in the notification can be used to discover the +values of pointer arguments for the target's system call. +(This is something that can't be done from within a seccomp filter.) +One way in which the supervisor can do this is to open the corresponding +.IR /proc/ tid /mem +file (see +.BR proc (5)) +and read bytes from the location that corresponds to one of +the pointer arguments whose value is supplied in the notification event. +.\" Tycho Andersen mentioned that there are alternatives to /proc/PID/mem, +.\" such as ptrace() and /proc/PID/map_files +(The supervisor must be careful to avoid +a race condition that can occur when doing this; +see the description of the +.B SECCOMP_IOCTL_NOTIF_ID_VALID +.BR ioctl (2) +operation below.) +In addition, +the supervisor can access other system information that is visible +in user space but which is not accessible from a seccomp filter. +.\"------------------------------------- +.IP (7) +Having obtained information as per the previous step, +the supervisor may then choose to perform an action in response +to the target's system call +(which, as noted above, is not executed when the seccomp filter returns the +.B SECCOMP_RET_USER_NOTIF +action value). +.IP +One example use case here relates to containers. +The target may be located inside a container where +it does not have sufficient capabilities to mount a filesystem +in the container's mount namespace. +However, the supervisor may be a more privileged process that +does have sufficient capabilities to perform the mount operation. +.\"------------------------------------- +.IP (8) +The supervisor then sends a response to the notification. +The information in this response is used by the kernel to construct +a return value for the target's system call and provide +a value that will be assigned to the +.I errno +variable of the target. +.IP +The response is sent using the +.B SECCOMP_IOCTL_NOTIF_SEND +.BR ioctl (2) +operation, which is used to transmit a +.I seccomp_notif_resp +structure to the kernel. +This structure includes a cookie value that the supervisor obtained in the +.I seccomp_notif +structure returned by the +.B SECCOMP_IOCTL_NOTIF_RECV +operation. +This cookie value allows the kernel to associate the response with the +target. +This structure must include the cookie value that the supervisor +obtained in the +.I seccomp_notif +structure returned by the +.B SECCOMP_IOCTL_NOTIF_RECV +operation; +the cookie allows the kernel to associate the response with the target. +.\"------------------------------------- +.IP (9) +Once the notification has been sent, +the system call in the target thread unblocks, +returning the information that was provided by the supervisor +in the notification response. +.\"------------------------------------- +.P +As a variation on the last two steps, +the supervisor can send a response that tells the kernel that it +should execute the target thread's system call; see the discussion of +.BR SECCOMP_USER_NOTIF_FLAG_CONTINUE , +below. +.\" +.SH IOCTL OPERATIONS +The following +.BR ioctl (2) +operations are supported by the seccomp user-space +notification file descriptor. +For each of these operations, the first (file descriptor) argument of +.BR ioctl (2) +is the listening file descriptor returned by a call to +.BR seccomp (2) +with the +.B SECCOMP_FILTER_FLAG_NEW_LISTENER +flag. +.\" +.SS SECCOMP_IOCTL_NOTIF_RECV +The +.B SECCOMP_IOCTL_NOTIF_RECV +operation (available since Linux 5.0) is used to obtain a user-space +notification event. +If no such event is currently pending, +the operation blocks until an event occurs. +The third +.BR ioctl (2) +argument is a pointer to a structure of the following form +which contains information about the event. +This structure must be zeroed out before the call. +.P +.in +4n +.EX +struct seccomp_notif { + __u64 id; /* Cookie */ + __u32 pid; /* TID of target thread */ + __u32 flags; /* Currently unused (0) */ + struct seccomp_data data; /* See seccomp(2) */ +}; +.EE +.in +.P +The fields in this structure are as follows: +.TP +.I id +This is a cookie for the notification. +Each such cookie is guaranteed to be unique for the corresponding +seccomp filter. +.RS +.IP \[bu] 3 +The cookie can be used with the +.B SECCOMP_IOCTL_NOTIF_ID_VALID +.BR ioctl (2) +operation described below. +.IP \[bu] +When returning a notification response to the kernel, +the supervisor must include the cookie value in the +.I seccomp_notif_resp +structure that is specified as the argument of the +.B SECCOMP_IOCTL_NOTIF_SEND +operation. +.RE +.TP +.I pid +This is the thread ID of the target thread that triggered +the notification event. +.TP +.I flags +This is a bit mask of flags providing further information on the event. +In the current implementation, this field is always zero. +.TP +.I data +This is a +.I seccomp_data +structure containing information about the system call that +triggered the notification. +This is the same structure that is passed to the seccomp filter. +See +.BR seccomp (2) +for details of this structure. +.P +On success, this operation returns 0; on failure, \-1 is returned, and +.I errno +is set to indicate the cause of the error. +This operation can fail with the following errors: +.TP +.BR EINVAL " (since Linux 5.5)" +.\" commit 2882d53c9c6f3b8311d225062522f03772cf0179 +The +.I seccomp_notif +structure that was passed to the call contained nonzero fields. +.TP +.B ENOENT +The target thread was killed by a signal as the notification information +was being generated, +or the target's (blocked) system call was interrupted by a signal handler. +.\" FIXME +.\" From my experiments, +.\" it appears that if a SECCOMP_IOCTL_NOTIF_RECV is done after +.\" the target thread terminates, then the ioctl() simply +.\" blocks (rather than returning an error to indicate that the +.\" target no longer exists). +.\" +.\" I found that surprising, and it required some contortions in +.\" the example program. It was not possible to code my SIGCHLD +.\" handler (which reaps the zombie when the worker/target +.\" terminates) to simply set a flag checked in the main +.\" handleNotifications() loop, since this created an +.\" unavoidable race where the child might terminate just after +.\" I had checked the flag, but before I blocked (forever!) in the +.\" SECCOMP_IOCTL_NOTIF_RECV operation. Instead, I had to code +.\" the signal handler to simply call _exit(2) in order to +.\" terminate the parent process (the supervisor). +.\" +.\" Is this expected behavior? It seems to me rather +.\" desirable that SECCOMP_IOCTL_NOTIF_RECV should give an error +.\" if the target has terminated. +.\" +.\" Jann posted a patch to rectify this, but there was no response +.\" (Lore link: https://bit.ly/3jvUBxk) to his question about fixing +.\" this issue. (I've tried building with the patch, but encountered +.\" an issue with the target process entering D state after a signal.) +.\" +.\" For now, this behavior is documented in BUGS. +.\" +.\" Kees Cook commented: Let's change [this] ASAP! +.\" +.SS SECCOMP_IOCTL_NOTIF_ID_VALID +The +.B SECCOMP_IOCTL_NOTIF_ID_VALID +operation (available since Linux 5.0) is used to check that a notification ID +returned by an earlier +.B SECCOMP_IOCTL_NOTIF_RECV +operation is still valid +(i.e., that the target still exists and its system call +is still blocked waiting for a response). +.P +The third +.BR ioctl (2) +argument is a pointer to the cookie +.RI ( id ) +returned by the +.B SECCOMP_IOCTL_NOTIF_RECV +operation. +.P +This operation is necessary to avoid race conditions that can occur when the +.I pid +returned by the +.B SECCOMP_IOCTL_NOTIF_RECV +operation terminates, and that process ID is reused by another process. +An example of this kind of race is the following +.IP (1) 5 +A notification is generated on the listening file descriptor. +The returned +.I seccomp_notif +contains the TID of the target thread (in the +.I pid +field of the structure). +.IP (2) +The target terminates. +.IP (3) +Another thread or process is created on the system that by chance reuses the +TID that was freed when the target terminated. +.IP (4) +The supervisor +.BR open (2)s +the +.IR /proc/ tid /mem +file for the TID obtained in step 1, with the intention of (say) +inspecting the memory location(s) that containing the argument(s) of +the system call that triggered the notification in step 1. +.P +In the above scenario, the risk is that the supervisor may try +to access the memory of a process other than the target. +This race can be avoided by following the call to +.BR open (2) +with a +.B SECCOMP_IOCTL_NOTIF_ID_VALID +operation to verify that the process that generated the notification +is still alive. +(Note that if the target terminates after the latter step, +a subsequent +.BR read (2) +from the file descriptor may return 0, indicating end of file.) +.\" Jann Horn: +.\" the PID can be reused, but the /proc/$pid directory is +.\" internally not associated with the numeric PID, but, +.\" conceptually speaking, with a specific incarnation of the +.\" PID, or something like that. (Actually, it is associated +.\" with the "struct pid", which is not reused, instead of the +.\" numeric PID. +.P +See NOTES for a discussion of other cases where +.B SECCOMP_IOCTL_NOTIF_ID_VALID +checks must be performed. +.P +On success (i.e., the notification ID is still valid), +this operation returns 0. +On failure (i.e., the notification ID is no longer valid), +\-1 is returned, and +.I errno +is set to +.BR ENOENT . +.\" +.SS SECCOMP_IOCTL_NOTIF_SEND +The +.B SECCOMP_IOCTL_NOTIF_SEND +operation (available since Linux 5.0) +is used to send a notification response back to the kernel. +The third +.BR ioctl (2) +argument of this structure is a pointer to a structure of the following form: +.P +.in +4n +.EX +struct seccomp_notif_resp { + __u64 id; /* Cookie value */ + __s64 val; /* Success return value */ + __s32 error; /* 0 (success) or negative error number */ + __u32 flags; /* See below */ +}; +.EE +.in +.P +The fields of this structure are as follows: +.TP +.I id +This is the cookie value that was obtained using the +.B SECCOMP_IOCTL_NOTIF_RECV +operation. +This cookie value allows the kernel to correctly associate this response +with the system call that triggered the user-space notification. +.TP +.I val +This is the value that will be used for a spoofed +success return for the target's system call; see below. +.TP +.I error +This is the value that will be used as the error number +.RI ( errno ) +for a spoofed error return for the target's system call; see below. +.TP +.I flags +This is a bit mask that includes zero or more of the following flags: +.RS +.TP +.BR SECCOMP_USER_NOTIF_FLAG_CONTINUE " (since Linux 5.5)" +Tell the kernel to execute the target's system call. +.\" commit fb3c5386b382d4097476ce9647260fc89b34afdb +.RE +.P +Two kinds of response are possible: +.IP \[bu] 3 +A response to the kernel telling it to execute the +target's system call. +In this case, the +.I flags +field includes +.B SECCOMP_USER_NOTIF_FLAG_CONTINUE +and the +.I error +and +.I val +fields must be zero. +.IP +This kind of response can be useful in cases where the supervisor needs +to do deeper analysis of the target's system call than is possible +from a seccomp filter (e.g., examining the values of pointer arguments), +and, having decided that the system call does not require emulation +by the supervisor, the supervisor wants the system call to +be executed normally in the target. +.IP +The +.B SECCOMP_USER_NOTIF_FLAG_CONTINUE +flag should be used with caution; see NOTES. +.IP \[bu] +A spoofed return value for the target's system call. +In this case, the kernel does not execute the target's system call, +instead causing the system call to return a spoofed value as specified by +fields of the +.I seccomp_notif_resp +structure. +The supervisor should set the fields of this structure as follows: +.RS +.IP \[bu] 3 +.I flags +does not contain +.BR SECCOMP_USER_NOTIF_FLAG_CONTINUE . +.IP \[bu] +.I error +is set either to 0 for a spoofed "success" return or to a negative +error number for a spoofed "failure" return. +In the former case, the kernel causes the target's system call +to return the value specified in the +.I val +field. +In the latter case, the kernel causes the target's system call +to return \-1, and +.I errno +is assigned the negated +.I error +value. +.IP \[bu] +.I val +is set to a value that will be used as the return value for a spoofed +"success" return for the target's system call. +The value in this field is ignored if the +.I error +field contains a nonzero value. +.\" FIXME +.\" Kees Cook suggested: +.\" +.\" Strictly speaking, this is architecture specific, but +.\" all architectures do it this way. Should seccomp enforce +.\" val == 0 when err != 0 ? +.\" +.\" Christian Brauner +.\" +.\" Feels like it should, at least for the SEND ioctl where we already +.\" verify that val and err are both 0 when CONTINUE is specified (as you +.\" pointed out correctly above). +.RE +.P +On success, this operation returns 0; on failure, \-1 is returned, and +.I errno +is set to indicate the cause of the error. +This operation can fail with the following errors: +.TP +.B EINPROGRESS +A response to this notification has already been sent. +.TP +.B EINVAL +An invalid value was specified in the +.I flags field. +.TP +.B +.B EINVAL +The +.I flags +field contained +.BR SECCOMP_USER_NOTIF_FLAG_CONTINUE , +and the +.I error +or +.I val +field was not zero. +.TP +.B ENOENT +The blocked system call in the target +has been interrupted by a signal handler +or the target has terminated. +.\" Jann Horn notes: +.\" you could also get this [ENOENT] if a response has already +.\" been sent, instead of EINPROGRESS - the only difference is +.\" whether the target thread has picked up the response yet +.\" +.SS SECCOMP_IOCTL_NOTIF_ADDFD +The +.B SECCOMP_IOCTL_NOTIF_ADDFD +operation (available since Linux 5.9) +allows the supervisor to install a file descriptor +into the target's file descriptor table. +Much like the use of +.B SCM_RIGHTS +messages described in +.BR unix (7), +this operation is semantically equivalent to duplicating +a file descriptor from the supervisor's file descriptor table +into the target's file descriptor table. +.P +The +.B SECCOMP_IOCTL_NOTIF_ADDFD +operation permits the supervisor to emulate a target system call (such as +.BR socket (2) +or +.BR openat (2)) +that generates a file descriptor. +The supervisor can perform the system call that generates +the file descriptor (and associated open file description) +and then use this operation to allocate +a file descriptor that refers to the same open file description in the target. +(For an explanation of open file descriptions, see +.BR open (2).) +.P +Once this operation has been performed, +the supervisor can close its copy of the file descriptor. +.P +In the target, +the received file descriptor is subject to the same +Linux Security Module (LSM) checks as are applied to a file descriptor +that is received in an +.B SCM_RIGHTS +ancillary message. +If the file descriptor refers to a socket, +it inherits the cgroup version 1 network controller settings +.RI ( classid +and +.IR netprioidx ) +of the target. +.P +The third +.BR ioctl (2) +argument is a pointer to a structure of the following form: +.P +.in +4n +.EX +struct seccomp_notif_addfd { + __u64 id; /* Cookie value */ + __u32 flags; /* Flags */ + __u32 srcfd; /* Local file descriptor number */ + __u32 newfd; /* 0 or desired file descriptor + number in target */ + __u32 newfd_flags; /* Flags to set on target file + descriptor */ +}; +.EE +.in +.P +The fields in this structure are as follows: +.TP +.I id +This field should be set to the notification ID +(cookie value) that was obtained via +.BR SECCOMP_IOCTL_NOTIF_RECV . +.TP +.I flags +This field is a bit mask of flags that modify the behavior of the operation. +Currently, only one flag is supported: +.RS +.TP +.B SECCOMP_ADDFD_FLAG_SETFD +When allocating the file descriptor in the target, +use the file descriptor number specified in the +.I newfd +field. +.TP +.BR SECCOMP_ADDFD_FLAG_SEND " (since Linux 5.14)" +.\" commit 0ae71c7720e3ae3aabd2e8a072d27f7bd173d25c +Perform the equivalent of +.B SECCOMP_IOCTL_NOTIF_ADDFD +plus +.B SECCOMP_IOCTL_NOTIF_SEND +as an atomic operation. +On successful invocation, the target process's +.I errno +will be 0 +and the return value will be the file descriptor number +that was allocated in the target. +If allocating the file descriptor in the target fails, +the target's system call continues to be blocked +until a successful response is sent. +.RE +.TP +.I srcfd +This field should be set to the number of the file descriptor +in the supervisor that is to be duplicated. +.TP +.I newfd +This field determines which file descriptor number is allocated in the target. +If the +.B SECCOMP_ADDFD_FLAG_SETFD +flag is set, +then this field specifies which file descriptor number should be allocated. +If this file descriptor number is already open in the target, +it is atomically closed and reused. +If the descriptor duplication fails due to an LSM check, or if +.I srcfd +is not a valid file descriptor, +the file descriptor +.I newfd +will not be closed in the target process. +.IP +If the +.B SECCOMP_ADDFD_FLAG_SETFD +flag it not set, then this field must be 0, +and the kernel allocates the lowest unused file descriptor number +in the target. +.TP +.I newfd_flags +This field is a bit mask specifying flags that should be set on +the file descriptor that is received in the target process. +Currently, only the following flag is implemented: +.RS +.TP +.B O_CLOEXEC +Set the close-on-exec flag on the received file descriptor. +.RE +.P +On success, this +.BR ioctl (2) +call returns the number of the file descriptor that was allocated +in the target. +Assuming that the emulated system call is one that returns +a file descriptor as its function result (e.g., +.BR socket (2)), +this value can be used as the return value +.RI ( resp.val ) +that is supplied in the response that is subsequently sent with the +.B SECCOMP_IOCTL_NOTIF_SEND +operation. +.P +On error, \-1 is returned and +.I errno +is set to indicate the cause of the error. +.P +This operation can fail with the following errors: +.TP +.B EBADF +Allocating the file descriptor in the target would cause the target's +.B RLIMIT_NOFILE +limit to be exceeded (see +.BR getrlimit (2)). +.TP +.B EBUSY +If the flag +.B SECCOMP_IOCTL_NOTIF_SEND +is used, this means the operation can't proceed until other +.B SECCOMP_IOCTL_NOTIF_ADDFD +requests are processed. +.TP +.B EINPROGRESS +The user-space notification specified in the +.I id +field exists but has not yet been fetched (by a +.BR SECCOMP_IOCTL_NOTIF_RECV ) +or has already been responded to (by a +.BR SECCOMP_IOCTL_NOTIF_SEND ). +.TP +.B EINVAL +An invalid flag was specified in the +.I flags +or +.I newfd_flags +field, or the +.I newfd +field is nonzero and the +.B SECCOMP_ADDFD_FLAG_SETFD +flag was not specified in the +.I flags +field. +.TP +.B EMFILE +The file descriptor number specified in +.I newfd +exceeds the limit specified in +.IR /proc/sys/fs/nr_open . +.TP +.B ENOENT +The blocked system call in the target +has been interrupted by a signal handler +or the target has terminated. +.P +Here is some sample code (with error handling omitted) that uses the +.B SECCOMP_ADDFD_FLAG_SETFD +operation (here, to emulate a call to +.BR openat (2)): +.P +.EX +.in +4n +int fd, removeFd; +\& +fd = openat(req\->data.args[0], path, req\->data.args[2], + req\->data.args[3]); +\& +struct seccomp_notif_addfd addfd; +addfd.id = req\->id; /* Cookie from SECCOMP_IOCTL_NOTIF_RECV */ +addfd.srcfd = fd; +addfd.newfd = 0; +addfd.flags = 0; +addfd.newfd_flags = O_CLOEXEC; +\& +targetFd = ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_ADDFD, &addfd); +\& +close(fd); /* No longer needed in supervisor */ +\& +struct seccomp_notif_resp *resp; + /* Code to allocate 'resp' omitted */ +resp\->id = req\->id; +resp\->error = 0; /* "Success" */ +resp\->val = targetFd; +resp\->flags = 0; +ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_SEND, resp); +.in +.EE +.SH NOTES +One example use case for the user-space notification +mechanism is to allow a container manager +(a process which is typically running with more privilege than +the processes inside the container) +to mount block devices or create device nodes for the container. +The mount use case provides an example of where the +.B SECCOMP_USER_NOTIF_FLAG_CONTINUE +.BR ioctl (2) +operation is useful. +Upon receiving a notification for the +.BR mount (2) +system call, the container manager (the "supervisor") can distinguish +a request to mount a block filesystem +(which would not be possible for a "target" process inside the container) +and mount that file system. +If, on the other hand, the container manager detects that the operation +could be performed by the process inside the container +(e.g., a mount of a +.BR tmpfs (5) +filesystem), it can notify the kernel that the target process's +.BR mount (2) +system call can continue. +.\" +.SS select()/poll()/epoll semantics +The file descriptor returned when +.BR seccomp (2) +is employed with the +.B SECCOMP_FILTER_FLAG_NEW_LISTENER +flag can be monitored using +.BR poll (2), +.BR epoll (7), +and +.BR select (2). +These interfaces indicate that the file descriptor is ready as follows: +.IP \[bu] 3 +When a notification is pending, +these interfaces indicate that the file descriptor is readable. +Following such an indication, a subsequent +.B SECCOMP_IOCTL_NOTIF_RECV +.BR ioctl (2) +will not block, returning either information about a notification +or else failing with the error +.B EINTR +if the target has been killed by a signal or its system call +has been interrupted by a signal handler. +.IP \[bu] +After the notification has been received (i.e., by the +.B SECCOMP_IOCTL_NOTIF_RECV +.BR ioctl (2) +operation), these interfaces indicate that the file descriptor is writable, +meaning that a notification response can be sent using the +.B SECCOMP_IOCTL_NOTIF_SEND +.BR ioctl (2) +operation. +.IP \[bu] +After the last thread using the filter has terminated and been reaped using +.BR waitpid (2) +(or similar), +the file descriptor indicates an end-of-file condition (readable in +.BR select (2); +.BR POLLHUP / EPOLLHUP +in +.BR poll (2)/ +.BR epoll_wait (2)). +.SS Design goals; use of SECCOMP_USER_NOTIF_FLAG_CONTINUE +The intent of the user-space notification feature is +to allow system calls to be performed on behalf of the target. +The target's system call should either be handled by the supervisor or +allowed to continue normally in the kernel (where standard security +policies will be applied). +.P +.BR "Note well" : +this mechanism must not be used to make security policy decisions +about the system call, +which would be inherently race-prone for reasons described next. +.P +The +.B SECCOMP_USER_NOTIF_FLAG_CONTINUE +flag must be used with caution. +If set by the supervisor, the target's system call will continue. +However, there is a time-of-check, time-of-use race here, +since an attacker could exploit the interval of time where the target is +blocked waiting on the "continue" response to do things such as +rewriting the system call arguments. +.P +Note furthermore that a user-space notifier can be bypassed if +the existing filters allow the use of +.BR seccomp (2) +or +.BR prctl (2) +to install a filter that returns an action value with a higher precedence than +.B SECCOMP_RET_USER_NOTIF +(see +.BR seccomp (2)). +.P +It should thus be absolutely clear that the +seccomp user-space notification mechanism +.B can not +be used to implement a security policy! +It should only ever be used in scenarios where a more privileged process +supervises the system calls of a lesser privileged target to +get around kernel-enforced security restrictions when +the supervisor deems this safe. +In other words, +in order to continue a system call, the supervisor should be sure that +another security mechanism or the kernel itself will sufficiently block +the system call if its arguments are rewritten to something unsafe. +.\" +.SS Caveats regarding the use of \fI/proc/\fPtid\fI/mem\fP +The discussion above noted the need to use the +.B SECCOMP_IOCTL_NOTIF_ID_VALID +.BR ioctl (2) +when opening the +.IR /proc/ tid /mem +file of the target +to avoid the possibility of accessing the memory of the wrong process +in the event that the target terminates and its ID +is recycled by another (unrelated) thread. +However, the use of this +.BR ioctl (2) +operation is also necessary in other situations, +as explained in the following paragraphs. +.P +Consider the following scenario, where the supervisor +tries to read the pathname argument of a target's blocked +.BR mount (2) +system call: +.IP (1) 5 +From one of its functions +.RI ( func() ), +the target calls +.BR mount (2), +which triggers a user-space notification and causes the target to block. +.IP (2) +The supervisor receives the notification, opens +.IR /proc/ tid /mem , +and (successfully) performs the +.B SECCOMP_IOCTL_NOTIF_ID_VALID +check. +.IP (3) +The target receives a signal, which causes the +.BR mount (2) +to abort. +.IP (4) +The signal handler executes in the target, and returns. +.IP (5) +Upon return from the handler, the execution of +.I func() +resumes, and it returns (and perhaps other functions are called, +overwriting the memory that had been used for the stack frame of +.IR func() ). +.IP (6) +Using the address provided in the notification information, +the supervisor reads from the target's memory location that used to +contain the pathname. +.IP (7) +The supervisor now calls +.BR mount (2) +with some arbitrary bytes obtained in the previous step. +.P +The conclusion from the above scenario is this: +since the target's blocked system call may be interrupted by a signal handler, +the supervisor must be written to expect that the +target may abandon its system call at +.B any +time; +in such an event, any information that the supervisor obtained from +the target's memory must be considered invalid. +.P +To prevent such scenarios, +every read from the target's memory must be separated from use of +the bytes so obtained by a +.B SECCOMP_IOCTL_NOTIF_ID_VALID +check. +In the above example, the check would be placed between the two final steps. +An example of such a check is shown in EXAMPLES. +.P +Following on from the above, it should be clear that +a write by the supervisor into the target's memory can +.B never +be considered safe. +.\" +.SS Caveats regarding blocking system calls +Suppose that the target performs a blocking system call (e.g., +.BR accept (2)) +that the supervisor should handle. +The supervisor might then in turn execute the same blocking system call. +.P +In this scenario, +it is important to note that if the target's system call is now +interrupted by a signal, the supervisor is +.I not +informed of this. +If the supervisor does not take suitable steps to +actively discover that the target's system call has been canceled, +various difficulties can occur. +Taking the example of +.BR accept (2), +the supervisor might remain blocked in its +.BR accept (2) +holding a port number that the target +(which, after the interruption by the signal handler, +perhaps closed its listening socket) might expect to be able to reuse in a +.BR bind (2) +call. +.P +Therefore, when the supervisor wishes to emulate a blocking system call, +it must do so in such a way that it gets informed if the target's +system call is interrupted by a signal handler. +For example, if the supervisor itself executes the same +blocking system call, then it could employ a separate thread +that uses the +.B SECCOMP_IOCTL_NOTIF_ID_VALID +operation to check if the target is still blocked in its system call. +Alternatively, in the +.BR accept (2) +example, the supervisor might use +.BR poll (2) +to monitor both the notification file descriptor +(so as to discover when the target's +.BR accept (2) +call has been interrupted) and the listening file descriptor +(so as to know when a connection is available). +.P +If the target's system call is interrupted, +the supervisor must take care to release resources (e.g., file descriptors) +that it acquired on behalf of the target. +.\" +.SS Interaction with SA_RESTART signal handlers +Consider the following scenario: +.IP (1) 5 +The target process has used +.BR sigaction (2) +to install a signal handler with the +.B SA_RESTART +flag. +.IP (2) +The target has made a system call that triggered a seccomp +user-space notification and the target is currently blocked +until the supervisor sends a notification response. +.IP (3) +A signal is delivered to the target and the signal handler is executed. +.IP (4) +When (if) the supervisor attempts to send a notification response, the +.B SECCOMP_IOCTL_NOTIF_SEND +.BR ioctl (2)) +operation will fail with the +.B ENOENT +error. +.P +In this scenario, the kernel will restart the target's system call. +Consequently, the supervisor will receive another user-space notification. +Thus, depending on how many times the blocked system call +is interrupted by a signal handler, +the supervisor may receive multiple notifications for +the same instance of a system call in the target. +.P +One oddity is that system call restarting as described in this scenario +will occur even for the blocking system calls listed in +.BR signal (7) +that would +.B never +normally be restarted by the +.B SA_RESTART +flag. +.\" FIXME +.\" About the above, Kees Cook commented: +.\" +.\" Does this need fixing? I imagine the correct behavior for this case +.\" would be a response to _SEND of EINPROGRESS and the target would see +.\" EINTR normally? +.\" +.\" I mean, it's not like seccomp doesn't already expose weirdness with +.\" syscall restarts. Not even arm64 compat agrees[3] with arm32 in this +.\" regard. :( +. +.\" FIXME +.\" Michael Kerrisk: +.\" I wonder about the effect of this oddity for system calls that +.\" are normally nonrestartable because they have timeouts. My +.\" understanding is that the kernel doesn't restart those system +.\" calls because it's impossible for the kernel to restart the call +.\" with the right timeout value. I wonder what happens when those +.\" system calls are restarted in the scenario we're discussing.) +.P +Furthermore, if the supervisor response is a file descriptor +added with +.BR SECCOMP_IOCTL_NOTIF_ADDFD , +then the flag +.B SECCOMP_ADDFD_FLAG_SEND +can be used to atomically add the file descriptor and return that value, +making sure no file descriptors are inadvertently leaked into the target. +.SH BUGS +If a +.B SECCOMP_IOCTL_NOTIF_RECV +.BR ioctl (2) +operation +.\" or a poll/epoll/select +is performed after the target terminates, then the +.BR ioctl (2) +call simply blocks (rather than returning an error to indicate that the +target no longer exists). +.\" FIXME +.\" Comment from Kees Cook: +.\" +.\" I want this fixed. It caused me no end of pain when building the +.\" selftests, and ended up spawning my implementing a global test timeout +.\" in kselftest. :P Before the usage counter refactor, there was no sane +.\" way to deal with this, but now I think we're close. +.\" +.SH EXAMPLES +The (somewhat contrived) program shown below demonstrates the use of +the interfaces described in this page. +The program creates a child process that serves as the "target" process. +The child process installs a seccomp filter that returns the +.B SECCOMP_RET_USER_NOTIF +action value if a call is made to +.BR mkdir (2). +The child process then calls +.BR mkdir (2) +once for each of the supplied command-line arguments, +and reports the result returned by the call. +After processing all arguments, the child process terminates. +.P +The parent process acts as the supervisor, listening for the notifications +that are generated when the target process calls +.BR mkdir (2). +When such a notification occurs, +the supervisor examines the memory of the target process (using +.IR /proc/ pid /mem ) +to discover the pathname argument that was supplied to the +.BR mkdir (2) +call, and performs one of the following actions: +.IP \[bu] 3 +If the pathname begins with the prefix "/tmp/", +then the supervisor attempts to create the specified directory, +and then spoofs a return for the target process based on the return +value of the supervisor's +.BR mkdir (2) +call. +In the event that that call succeeds, +the spoofed success return value is the length of the pathname. +.IP \[bu] +If the pathname begins with "./" (i.e., it is a relative pathname), +the supervisor sends a +.B SECCOMP_USER_NOTIF_FLAG_CONTINUE +response to the kernel to say that the kernel should execute +the target process's +.BR mkdir (2) +call. +.IP \[bu] +If the pathname begins with some other prefix, +the supervisor spoofs an error return for the target process, +so that the target process's +.BR mkdir (2) +call appears to fail with the error +.B EOPNOTSUPP +("Operation not supported"). +Additionally, if the specified pathname is exactly "/bye", +then the supervisor terminates. +.P +This program can be used to demonstrate various aspects of the +behavior of the seccomp user-space notification mechanism. +To help aid such demonstrations, +the program logs various messages to show the operation +of the target process (lines prefixed "T:") and the supervisor +(indented lines prefixed "S:"). +.P +In the following example, the target attempts to create the directory +.IR /tmp/x . +Upon receiving the notification, the supervisor creates the directory on the +target's behalf, +and spoofs a success return to be received by the target process's +.BR mkdir (2) +call. +.P +.in +4n +.EX +$ \fB./seccomp_unotify /tmp/x\fP +T: PID = 23168 +\& +T: about to mkdir("/tmp/x") + S: got notification (ID 0x17445c4a0f4e0e3c) for PID 23168 + S: executing: mkdir("/tmp/x", 0700) + S: success! spoofed return = 6 + S: sending response (flags = 0; val = 6; error = 0) +T: SUCCESS: mkdir(2) returned 6 +\& +T: terminating + S: target has terminated; bye +.EE +.in +.P +In the above output, note that the spoofed return value seen by the target +process is 6 (the length of the pathname +.IR /tmp/x ), +whereas a normal +.BR mkdir (2) +call returns 0 on success. +.P +In the next example, the target attempts to create a directory using the +relative pathname +.IR ./sub . +Since this pathname starts with "./", +the supervisor sends a +.B SECCOMP_USER_NOTIF_FLAG_CONTINUE +response to the kernel, +and the kernel then (successfully) executes the target process's +.BR mkdir (2) +call. +.P +.in +4n +.EX +$ \fB./seccomp_unotify ./sub\fP +T: PID = 23204 +\& +T: about to mkdir("./sub") + S: got notification (ID 0xddb16abe25b4c12) for PID 23204 + S: target can execute system call + S: sending response (flags = 0x1; val = 0; error = 0) +T: SUCCESS: mkdir(2) returned 0 +\& +T: terminating + S: target has terminated; bye +.EE +.in +.P +If the target process attempts to create a directory with +a pathname that doesn't start with "." and doesn't begin with the prefix +"/tmp/", then the supervisor spoofs an error return +.RB ( EOPNOTSUPP , +"Operation not supported") +for the target's +.BR mkdir (2) +call (which is not executed): +.P +.in +4n +.EX +$ \fB./seccomp_unotify /xxx\fP +T: PID = 23178 +\& +T: about to mkdir("/xxx") + S: got notification (ID 0xe7dc095d1c524e80) for PID 23178 + S: spoofing error response (Operation not supported) + S: sending response (flags = 0; val = 0; error = \-95) +T: ERROR: mkdir(2): Operation not supported +\& +T: terminating + S: target has terminated; bye +.EE +.in +.P +In the next example, +the target process attempts to create a directory with the pathname +.BR /tmp/nosuchdir/b . +Upon receiving the notification, +the supervisor attempts to create that directory, but the +.BR mkdir (2) +call fails because the directory +.B /tmp/nosuchdir +does not exist. +Consequently, the supervisor spoofs an error return that passes the error +that it received back to the target process's +.BR mkdir (2) +call. +.P +.in +4n +.EX +$ \fB./seccomp_unotify /tmp/nosuchdir/b\fP +T: PID = 23199 +\& +T: about to mkdir("/tmp/nosuchdir/b") + S: got notification (ID 0x8744454293506046) for PID 23199 + S: executing: mkdir("/tmp/nosuchdir/b", 0700) + S: failure! (errno = 2; No such file or directory) + S: sending response (flags = 0; val = 0; error = \-2) +T: ERROR: mkdir(2): No such file or directory +\& +T: terminating + S: target has terminated; bye +.EE +.in +.P +If the supervisor receives a notification and sees that the +argument of the target's +.BR mkdir (2) +is the string "/bye", then (as well as spoofing an +.B EOPNOTSUPP +error), the supervisor terminates. +If the target process subsequently executes another +.BR mkdir (2) +that triggers its seccomp filter to return the +.B SECCOMP_RET_USER_NOTIF +action value, then the kernel causes the target process's system call to +fail with the error +.B ENOSYS +("Function not implemented"). +This is demonstrated by the following example: +.P +.in +4n +.EX +$ \fB./seccomp_unotify /bye /tmp/y\fP +T: PID = 23185 +\& +T: about to mkdir("/bye") + S: got notification (ID 0xa81236b1d2f7b0f4) for PID 23185 + S: spoofing error response (Operation not supported) + S: sending response (flags = 0; val = 0; error = \-95) + S: terminating ********** +T: ERROR: mkdir(2): Operation not supported +\& +T: about to mkdir("/tmp/y") +T: ERROR: mkdir(2): Function not implemented +\& +T: terminating +.EE +.in +.\" +.SS Program source +.\" SRC BEGIN (seccomp_unotify.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +#define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0])) +\& +/* Send the file descriptor \[aq]fd\[aq] over the connected UNIX domain socket + \[aq]sockfd\[aq]. Returns 0 on success, or \-1 on error. */ +\& +static int +sendfd(int sockfd, int fd) +{ + int data; + struct iovec iov; + struct msghdr msgh; + struct cmsghdr *cmsgp; +\& + /* Allocate a char array of suitable size to hold the ancillary data. + However, since this buffer is in reality a \[aq]struct cmsghdr\[aq], use a + union to ensure that it is suitably aligned. */ + union { + char buf[CMSG_SPACE(sizeof(int))]; + /* Space large enough to hold an \[aq]int\[aq] */ + struct cmsghdr align; + } controlMsg; +\& + /* The \[aq]msg_name\[aq] field can be used to specify the address of the + destination socket when sending a datagram. However, we do not + need to use this field because \[aq]sockfd\[aq] is a connected socket. */ +\& + msgh.msg_name = NULL; + msgh.msg_namelen = 0; +\& + /* On Linux, we must transmit at least one byte of real data in + order to send ancillary data. We transmit an arbitrary integer + whose value is ignored by recvfd(). */ +\& + msgh.msg_iov = &iov; + msgh.msg_iovlen = 1; + iov.iov_base = &data; + iov.iov_len = sizeof(int); + data = 12345; +\& + /* Set \[aq]msghdr\[aq] fields that describe ancillary data */ +\& + msgh.msg_control = controlMsg.buf; + msgh.msg_controllen = sizeof(controlMsg.buf); +\& + /* Set up ancillary data describing file descriptor to send */ +\& + cmsgp = CMSG_FIRSTHDR(&msgh); + cmsgp\->cmsg_level = SOL_SOCKET; + cmsgp\->cmsg_type = SCM_RIGHTS; + cmsgp\->cmsg_len = CMSG_LEN(sizeof(int)); + memcpy(CMSG_DATA(cmsgp), &fd, sizeof(int)); +\& + /* Send real plus ancillary data */ +\& + if (sendmsg(sockfd, &msgh, 0) == \-1) + return \-1; +\& + return 0; +} +\& +/* Receive a file descriptor on a connected UNIX domain socket. Returns + the received file descriptor on success, or \-1 on error. */ +\& +static int +recvfd(int sockfd) +{ + int data, fd; + ssize_t nr; + struct iovec iov; + struct msghdr msgh; +\& + /* Allocate a char buffer for the ancillary data. See the comments + in sendfd() */ + union { + char buf[CMSG_SPACE(sizeof(int))]; + struct cmsghdr align; + } controlMsg; + struct cmsghdr *cmsgp; +\& + /* The \[aq]msg_name\[aq] field can be used to obtain the address of the + sending socket. However, we do not need this information. */ +\& + msgh.msg_name = NULL; + msgh.msg_namelen = 0; +\& + /* Specify buffer for receiving real data */ +\& + msgh.msg_iov = &iov; + msgh.msg_iovlen = 1; + iov.iov_base = &data; /* Real data is an \[aq]int\[aq] */ + iov.iov_len = sizeof(int); +\& + /* Set \[aq]msghdr\[aq] fields that describe ancillary data */ +\& + msgh.msg_control = controlMsg.buf; + msgh.msg_controllen = sizeof(controlMsg.buf); +\& + /* Receive real plus ancillary data; real data is ignored */ +\& + nr = recvmsg(sockfd, &msgh, 0); + if (nr == \-1) + return \-1; +\& + cmsgp = CMSG_FIRSTHDR(&msgh); +\& + /* Check the validity of the \[aq]cmsghdr\[aq] */ +\& + if (cmsgp == NULL + || cmsgp\->cmsg_len != CMSG_LEN(sizeof(int)) + || cmsgp\->cmsg_level != SOL_SOCKET + || cmsgp\->cmsg_type != SCM_RIGHTS) + { + errno = EINVAL; + return \-1; + } +\& + /* Return the received file descriptor to our caller */ +\& + memcpy(&fd, CMSG_DATA(cmsgp), sizeof(int)); + return fd; +} +\& +static void +sigchldHandler(int sig) +{ + char msg[] = "\etS: target has terminated; bye\en"; +\& + write(STDOUT_FILENO, msg, sizeof(msg) \- 1); + _exit(EXIT_SUCCESS); +} +\& +static int +seccomp(unsigned int operation, unsigned int flags, void *args) +{ + return syscall(SYS_seccomp, operation, flags, args); +} +\& +/* The following is the x86\-64\-specific BPF boilerplate code for checking + that the BPF program is running on the right architecture + ABI. At + completion of these instructions, the accumulator contains the system + call number. */ +\& +/* For the x32 ABI, all system call numbers have bit 30 set */ +\& +#define X32_SYSCALL_BIT 0x40000000 +\& +#define X86_64_CHECK_ARCH_AND_LOAD_SYSCALL_NR \e + BPF_STMT(BPF_LD | BPF_W | BPF_ABS, \e + (offsetof(struct seccomp_data, arch))), \e + BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, AUDIT_ARCH_X86_64, 0, 2), \e + BPF_STMT(BPF_LD | BPF_W | BPF_ABS, \e + (offsetof(struct seccomp_data, nr))), \e + BPF_JUMP(BPF_JMP | BPF_JGE | BPF_K, X32_SYSCALL_BIT, 0, 1), \e + BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_KILL_PROCESS) +\& +/* installNotifyFilter() installs a seccomp filter that generates + user\-space notifications (SECCOMP_RET_USER_NOTIF) when the process + calls mkdir(2); the filter allows all other system calls. +\& + The function return value is a file descriptor from which the + user\-space notifications can be fetched. */ +\& +static int +installNotifyFilter(void) +{ + int notifyFd; +\& + struct sock_filter filter[] = { + X86_64_CHECK_ARCH_AND_LOAD_SYSCALL_NR, +\& + /* mkdir() triggers notification to user\-space supervisor */ +\& + BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, SYS_mkdir, 0, 1), + BPF_STMT(BPF_RET + BPF_K, SECCOMP_RET_USER_NOTIF), +\& + /* Every other system call is allowed */ +\& + BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW), + }; +\& + struct sock_fprog prog = { + .len = ARRAY_SIZE(filter), + .filter = filter, + }; +\& + /* Install the filter with the SECCOMP_FILTER_FLAG_NEW_LISTENER flag; + as a result, seccomp() returns a notification file descriptor. */ +\& + notifyFd = seccomp(SECCOMP_SET_MODE_FILTER, + SECCOMP_FILTER_FLAG_NEW_LISTENER, &prog); + if (notifyFd == \-1) + err(EXIT_FAILURE, "seccomp\-install\-notify\-filter"); +\& + return notifyFd; +} +\& +/* Close a pair of sockets created by socketpair() */ +\& +static void +closeSocketPair(int sockPair[2]) +{ + if (close(sockPair[0]) == \-1) + err(EXIT_FAILURE, "closeSocketPair\-close\-0"); + if (close(sockPair[1]) == \-1) + err(EXIT_FAILURE, "closeSocketPair\-close\-1"); +} +\& +/* Implementation of the target process; create a child process that: +\& + (1) installs a seccomp filter with the + SECCOMP_FILTER_FLAG_NEW_LISTENER flag; + (2) writes the seccomp notification file descriptor returned from + the previous step onto the UNIX domain socket, \[aq]sockPair[0]\[aq]; + (3) calls mkdir(2) for each element of \[aq]argv\[aq]. +\& + The function return value in the parent is the PID of the child + process; the child does not return from this function. */ +\& +static pid_t +targetProcess(int sockPair[2], char *argv[]) +{ + int notifyFd, s; + pid_t targetPid; +\& + targetPid = fork(); +\& + if (targetPid == \-1) + err(EXIT_FAILURE, "fork"); +\& + if (targetPid > 0) /* In parent, return PID of child */ + return targetPid; +\& + /* Child falls through to here */ +\& + printf("T: PID = %ld\en", (long) getpid()); +\& + /* Install seccomp filter(s) */ +\& + if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) + err(EXIT_FAILURE, "prctl"); +\& + notifyFd = installNotifyFilter(); +\& + /* Pass the notification file descriptor to the tracing process over + a UNIX domain socket */ +\& + if (sendfd(sockPair[0], notifyFd) == \-1) + err(EXIT_FAILURE, "sendfd"); +\& + /* Notification and socket FDs are no longer needed in target */ +\& + if (close(notifyFd) == \-1) + err(EXIT_FAILURE, "close\-target\-notify\-fd"); +\& + closeSocketPair(sockPair); +\& + /* Perform a mkdir() call for each of the command\-line arguments */ +\& + for (char **ap = argv; *ap != NULL; ap++) { + printf("\enT: about to mkdir(\e"%s\e")\en", *ap); +\& + s = mkdir(*ap, 0700); + if (s == \-1) + perror("T: ERROR: mkdir(2)"); + else + printf("T: SUCCESS: mkdir(2) returned %d\en", s); + } +\& + printf("\enT: terminating\en"); + exit(EXIT_SUCCESS); +} +\& +/* Check that the notification ID provided by a SECCOMP_IOCTL_NOTIF_RECV + operation is still valid. It will no longer be valid if the target + process has terminated or is no longer blocked in the system call that + generated the notification (because it was interrupted by a signal). +\& + This operation can be used when doing such things as accessing + /proc/PID files in the target process in order to avoid TOCTOU race + conditions where the PID that is returned by SECCOMP_IOCTL_NOTIF_RECV + terminates and is reused by another process. */ +\& +static bool +cookieIsValid(int notifyFd, uint64_t id) +{ + return ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_ID_VALID, &id) == 0; +} +\& +/* Access the memory of the target process in order to fetch the + pathname referred to by the system call argument \[aq]argNum\[aq] in + \[aq]req\->data.args[]\[aq]. The pathname is returned in \[aq]path\[aq], + a buffer of \[aq]len\[aq] bytes allocated by the caller. +\& + Returns true if the pathname is successfully fetched, and false + otherwise. For possible causes of failure, see the comments below. */ +\& +static bool +getTargetPathname(struct seccomp_notif *req, int notifyFd, + int argNum, char *path, size_t len) +{ + int procMemFd; + char procMemPath[PATH_MAX]; + ssize_t nread; +\& + snprintf(procMemPath, sizeof(procMemPath), "/proc/%d/mem", req\->pid); +\& + procMemFd = open(procMemPath, O_RDONLY | O_CLOEXEC); + if (procMemFd == \-1) + return false; +\& + /* Check that the process whose info we are accessing is still alive + and blocked in the system call that caused the notification. + If the SECCOMP_IOCTL_NOTIF_ID_VALID operation (performed in + cookieIsValid()) succeeded, we know that the /proc/PID/mem file + descriptor that we opened corresponded to the process for which we + received a notification. If that process subsequently terminates, + then read() on that file descriptor will return 0 (EOF). */ +\& + if (!cookieIsValid(notifyFd, req\->id)) { + close(procMemFd); + return false; + } +\& + /* Read bytes at the location containing the pathname argument */ +\& + nread = pread(procMemFd, path, len, req\->data.args[argNum]); +\& + close(procMemFd); +\& + if (nread <= 0) + return false; +\& + /* Once again check that the notification ID is still valid. The + case we are particularly concerned about here is that just + before we fetched the pathname, the target\[aq]s blocked system + call was interrupted by a signal handler, and after the handler + returned, the target carried on execution (past the interrupted + system call). In that case, we have no guarantees about what we + are reading, since the target\[aq]s memory may have been arbitrarily + changed by subsequent operations. */ +\& + if (!cookieIsValid(notifyFd, req\->id)) { + perror("\etS: notification ID check failed!!!"); + return false; + } +\& + /* Even if the target\[aq]s system call was not interrupted by a signal, + we have no guarantees about what was in the memory of the target + process. (The memory may have been modified by another thread, or + even by an external attacking process.) We therefore treat the + buffer returned by pread() as untrusted input. The buffer should + contain a terminating null byte; if not, then we will trigger an + error for the target process. */ +\& + if (strnlen(path, nread) < nread) + return true; +\& + return false; +} +\& +/* Allocate buffers for the seccomp user\-space notification request and + response structures. It is the caller\[aq]s responsibility to free the + buffers returned via \[aq]req\[aq] and \[aq]resp\[aq]. */ +\& +static void +allocSeccompNotifBuffers(struct seccomp_notif **req, + struct seccomp_notif_resp **resp, + struct seccomp_notif_sizes *sizes) +{ + size_t resp_size; +\& + /* Discover the sizes of the structures that are used to receive + notifications and send notification responses, and allocate + buffers of those sizes. */ +\& + if (seccomp(SECCOMP_GET_NOTIF_SIZES, 0, sizes) == \-1) + err(EXIT_FAILURE, "seccomp\-SECCOMP_GET_NOTIF_SIZES"); +\& + *req = malloc(sizes\->seccomp_notif); + if (*req == NULL) + err(EXIT_FAILURE, "malloc\-seccomp_notif"); +\& + /* When allocating the response buffer, we must allow for the fact + that the user\-space binary may have been built with user\-space + headers where \[aq]struct seccomp_notif_resp\[aq] is bigger than the + response buffer expected by the (older) kernel. Therefore, we + allocate a buffer that is the maximum of the two sizes. This + ensures that if the supervisor places bytes into the response + structure that are past the response size that the kernel expects, + then the supervisor is not touching an invalid memory location. */ +\& + resp_size = sizes\->seccomp_notif_resp; + if (sizeof(struct seccomp_notif_resp) > resp_size) + resp_size = sizeof(struct seccomp_notif_resp); +\& + *resp = malloc(resp_size); + if (*resp == NULL) + err(EXIT_FAILURE, "malloc\-seccomp_notif_resp"); +\& +} +\& +/* Handle notifications that arrive via the SECCOMP_RET_USER_NOTIF file + descriptor, \[aq]notifyFd\[aq]. */ +\& +static void +handleNotifications(int notifyFd) +{ + bool pathOK; + char path[PATH_MAX]; + struct seccomp_notif *req; + struct seccomp_notif_resp *resp; + struct seccomp_notif_sizes sizes; +\& + allocSeccompNotifBuffers(&req, &resp, &sizes); +\& + /* Loop handling notifications */ +\& + for (;;) { +\& + /* Wait for next notification, returning info in \[aq]*req\[aq] */ +\& + memset(req, 0, sizes.seccomp_notif); + if (ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_RECV, req) == \-1) { + if (errno == EINTR) + continue; + err(EXIT_FAILURE, "\etS: ioctl\-SECCOMP_IOCTL_NOTIF_RECV"); + } +\& + printf("\etS: got notification (ID %#llx) for PID %d\en", + req\->id, req\->pid); +\& + /* The only system call that can generate a notification event + is mkdir(2). Nevertheless, we check that the notified system + call is indeed mkdir() as kind of future\-proofing of this + code in case the seccomp filter is later modified to + generate notifications for other system calls. */ +\& + if (req\->data.nr != SYS_mkdir) { + printf("\etS: notification contained unexpected " + "system call number; bye!!!\en"); + exit(EXIT_FAILURE); + } +\& + pathOK = getTargetPathname(req, notifyFd, 0, path, sizeof(path)); +\& + /* Prepopulate some fields of the response */ +\& + resp\->id = req\->id; /* Response includes notification ID */ + resp\->flags = 0; + resp\->val = 0; +\& + /* If getTargetPathname() failed, trigger an EINVAL error + response (sending this response may yield an error if the + failure occurred because the notification ID was no longer + valid); if the directory is in /tmp, then create it on behalf + of the supervisor; if the pathname starts with \[aq].\[aq], tell the + kernel to let the target process execute the mkdir(); + otherwise, give an error for a directory pathname in any other + location. */ +\& + if (!pathOK) { + resp\->error = \-EINVAL; + printf("\etS: spoofing error for invalid pathname (%s)\en", + strerror(\-resp\->error)); + } else if (strncmp(path, "/tmp/", strlen("/tmp/")) == 0) { + printf("\etS: executing: mkdir(\e"%s\e", %#llo)\en", + path, req\->data.args[1]); +\& + if (mkdir(path, req\->data.args[1]) == 0) { + resp\->error = 0; /* "Success" */ + resp\->val = strlen(path); /* Used as return value of + mkdir() in target */ + printf("\etS: success! spoofed return = %lld\en", + resp\->val); + } else { +\& + /* If mkdir() failed in the supervisor, pass the error + back to the target */ +\& + resp\->error = \-errno; + printf("\etS: failure! (errno = %d; %s)\en", errno, + strerror(errno)); + } + } else if (strncmp(path, "./", strlen("./")) == 0) { + resp\->error = resp\->val = 0; + resp\->flags = SECCOMP_USER_NOTIF_FLAG_CONTINUE; + printf("\etS: target can execute system call\en"); + } else { + resp\->error = \-EOPNOTSUPP; + printf("\etS: spoofing error response (%s)\en", + strerror(\-resp\->error)); + } +\& + /* Send a response to the notification */ +\& + printf("\etS: sending response " + "(flags = %#x; val = %lld; error = %d)\en", + resp\->flags, resp\->val, resp\->error); +\& + if (ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_SEND, resp) == \-1) { + if (errno == ENOENT) + printf("\etS: response failed with ENOENT; " + "perhaps target process\[aq]s syscall was " + "interrupted by a signal?\en"); + else + perror("ioctl\-SECCOMP_IOCTL_NOTIF_SEND"); + } +\& + /* If the pathname is just "/bye", then the supervisor breaks out + of the loop and terminates. This allows us to see what happens + if the target process makes further calls to mkdir(2). */ +\& + if (strcmp(path, "/bye") == 0) + break; + } +\& + free(req); + free(resp); + printf("\etS: terminating **********\en"); + exit(EXIT_FAILURE); +} +\& +/* Implementation of the supervisor process: +\& + (1) obtains the notification file descriptor from \[aq]sockPair[1]\[aq] + (2) handles notifications that arrive on that file descriptor. */ +\& +static void +supervisor(int sockPair[2]) +{ + int notifyFd; +\& + notifyFd = recvfd(sockPair[1]); +\& + if (notifyFd == \-1) + err(EXIT_FAILURE, "recvfd"); +\& + closeSocketPair(sockPair); /* We no longer need the socket pair */ +\& + handleNotifications(notifyFd); +} +\& +int +main(int argc, char *argv[]) +{ + int sockPair[2]; + struct sigaction sa; +\& + setbuf(stdout, NULL); +\& + if (argc < 2) { + fprintf(stderr, "At least one pathname argument is required\en"); + exit(EXIT_FAILURE); + } +\& + /* Create a UNIX domain socket that is used to pass the seccomp + notification file descriptor from the target process to the + supervisor process. */ +\& + if (socketpair(AF_UNIX, SOCK_STREAM, 0, sockPair) == \-1) + err(EXIT_FAILURE, "socketpair"); +\& + /* Create a child process\-\-the "target"\-\-that installs seccomp + filtering. The target process writes the seccomp notification + file descriptor onto \[aq]sockPair[0]\[aq] and then calls mkdir(2) for + each directory in the command\-line arguments. */ +\& + (void) targetProcess(sockPair, &argv[optind]); +\& + /* Catch SIGCHLD when the target terminates, so that the + supervisor can also terminate. */ +\& + sa.sa_handler = sigchldHandler; + sa.sa_flags = 0; + sigemptyset(&sa.sa_mask); + if (sigaction(SIGCHLD, &sa, NULL) == \-1) + err(EXIT_FAILURE, "sigaction"); +\& + supervisor(sockPair); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ioctl (2), +.BR pidfd_getfd (2), +.BR pidfd_open (2), +.BR seccomp (2) +.P +A further example program can be found in the kernel source file +.IR samples/seccomp/user-trap.c . diff --git a/man/man2/security.2 b/man/man2/security.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/security.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/select.2 b/man/man2/select.2 new file mode 100644 index 0000000..df076b6 --- /dev/null +++ b/man/man2/select.2 @@ -0,0 +1,765 @@ +.\" This manpage is copyright (C) 1992 Drew Eckhardt, +.\" copyright (C) 1995 Michael Shields, +.\" copyright (C) 2001 Paul Sheer, +.\" copyright (C) 2006, 2019 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-05-18 by Jim Van Zandt +.\" Sun Feb 11 14:07:00 MET 1996 Martin Schulze +.\" * layout slightly modified +.\" +.\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond +.\" Modified Thu Feb 24 01:41:09 CET 2000 by aeb +.\" Modified Thu Feb 9 22:32:09 CET 2001 by bert hubert , aeb +.\" Modified Mon Nov 11 14:35:00 PST 2002 by Ben Woodard +.\" 2005-03-11, mtk, modified pselect() text (it is now a system +.\" call in Linux 2.6.16. +.\" +.TH select 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO, fd_set \- +synchronous I/O multiplexing +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " fd_set; +.P +.BI "int select(int " nfds ", fd_set *_Nullable restrict " readfds , +.BI " fd_set *_Nullable restrict " writefds , +.BI " fd_set *_Nullable restrict " exceptfds , +.BI " struct timeval *_Nullable restrict " timeout ); +.P +.BI "void FD_CLR(int " fd ", fd_set *" set ); +.BI "int FD_ISSET(int " fd ", fd_set *" set ); +.BI "void FD_SET(int " fd ", fd_set *" set ); +.BI "void FD_ZERO(fd_set *" set ); +.P +.BI "int pselect(int " nfds ", fd_set *_Nullable restrict " readfds , +.BI " fd_set *_Nullable restrict " writefds , +.BI " fd_set *_Nullable restrict " exceptfds , +.BI " const struct timespec *_Nullable restrict " timeout , +.BI " const sigset_t *_Nullable restrict " sigmask ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pselect (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR "WARNING" : +.BR select () +can monitor only file descriptors numbers that are less than +.B FD_SETSIZE +(1024)\[em]an unreasonably low limit for many modern applications\[em]and +this limitation will not change. +All modern applications should instead use +.BR poll (2) +or +.BR epoll (7), +which do not suffer this limitation. +.P +.BR select () +allows a program to monitor multiple file descriptors, +waiting until one or more of the file descriptors become "ready" +for some class of I/O operation (e.g., input possible). +A file descriptor is considered ready if it is possible to +perform a corresponding I/O operation (e.g., +.BR read (2), +or a sufficiently small +.BR write (2)) +without blocking. +.\" +.SS fd_set +A structure type that can represent a set of file descriptors. +According to POSIX, +the maximum number of file descriptors in an +.I fd_set +structure is the value of the macro +.BR FD_SETSIZE . +.\" +.SS File descriptor sets +The principal arguments of +.BR select () +are three "sets" of file descriptors (declared with the type +.IR fd_set ), +which allow the caller to wait for three classes of events +on the specified set of file descriptors. +Each of the +.I fd_set +arguments may be specified as NULL if no file descriptors are +to be watched for the corresponding class of events. +.P +.BR "Note well" : +Upon return, each of the file descriptor sets is modified in place +to indicate which file descriptors are currently "ready". +Thus, if using +.BR select () +within a loop, the sets \fImust be reinitialized\fP before each call. +.P +The contents of a file descriptor set can be manipulated +using the following macros: +.TP +.BR FD_ZERO () +This macro clears (removes all file descriptors from) +.IR set . +It should be employed as the first step in initializing a file descriptor set. +.TP +.BR FD_SET () +This macro adds the file descriptor +.I fd +to +.IR set . +Adding a file descriptor that is already present in the set is a no-op, +and does not produce an error. +.TP +.BR FD_CLR () +This macro removes the file descriptor +.I fd +from +.IR set . +Removing a file descriptor that is not present in the set is a no-op, +and does not produce an error. +.TP +.BR FD_ISSET () +.BR select () +modifies the contents of the sets according to the rules +described below. +After calling +.BR select (), +the +.BR FD_ISSET () +macro +can be used to test if a file descriptor is still present in a set. +.BR FD_ISSET () +returns nonzero if the file descriptor +.I fd +is present in +.IR set , +and zero if it is not. +.\" +.SS Arguments +The arguments of +.BR select () +are as follows: +.TP +.I readfds +The file descriptors in this set are watched to see if they are +ready for reading. +A file descriptor is ready for reading if a read operation will not +block; in particular, a file descriptor is also ready on end-of-file. +.IP +After +.BR select () +has returned, \fIreadfds\fP will be +cleared of all file descriptors except for those that are ready for reading. +.TP +.I writefds +The file descriptors in this set are watched to see if they are +ready for writing. +A file descriptor is ready for writing if a write operation will not block. +However, even if a file descriptor indicates as writable, +a large write may still block. +.IP +After +.BR select () +has returned, \fIwritefds\fP will be +cleared of all file descriptors except for those that are ready for writing. +.TP +.I exceptfds +The file descriptors in this set are watched for "exceptional conditions". +For examples of some exceptional conditions, see the discussion of +.B POLLPRI +in +.BR poll (2). +.IP +After +.BR select () +has returned, +\fIexceptfds\fP will be cleared of all file descriptors except for those +for which an exceptional condition has occurred. +.TP +.I nfds +This argument should be set to the highest-numbered file descriptor in any +of the three sets, plus 1. +The indicated file descriptors in each set are checked, up to this limit +(but see BUGS). +.TP +.I timeout +The +.I timeout +argument is a +.I timeval +structure (shown below) that specifies the interval that +.BR select () +should block waiting for a file descriptor to become ready. +The call will block until either: +.RS +.IP \[bu] 3 +a file descriptor becomes ready; +.IP \[bu] +the call is interrupted by a signal handler; or +.IP \[bu] +the timeout expires. +.RE +.IP +Note that the +.I timeout +interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the blocking interval +may overrun by a small amount. +.IP +If both fields of the +.I timeval +structure are zero, then +.BR select () +returns immediately. +(This is useful for polling.) +.IP +If +.I timeout +is specified as NULL, +.BR select () +blocks indefinitely waiting for a file descriptor to become ready. +.\" +.SS pselect() +The +.BR pselect () +system call allows an application to safely wait until either +a file descriptor becomes ready or until a signal is caught. +.P +The operation of +.BR select () +and +.BR pselect () +is identical, other than these three differences: +.IP \[bu] 3 +.BR select () +uses a timeout that is a +.I struct timeval +(with seconds and microseconds), while +.BR pselect () +uses a +.I struct timespec +(with seconds and nanoseconds). +.IP \[bu] +.BR select () +may update the +.I timeout +argument to indicate how much time was left. +.BR pselect () +does not change this argument. +.IP \[bu] +.BR select () +has no +.I sigmask +argument, and behaves as +.BR pselect () +called with NULL +.IR sigmask . +.P +.I sigmask +is a pointer to a signal mask (see +.BR sigprocmask (2)); +if it is not NULL, then +.BR pselect () +first replaces the current signal mask by the one pointed to by +.IR sigmask , +then does the "select" function, and then restores the original +signal mask. +(If +.I sigmask +is NULL, +the signal mask is not modified during the +.BR pselect () +call.) +.P +Other than the difference in the precision of the +.I timeout +argument, the following +.BR pselect () +call: +.P +.in +4n +.EX +ready = pselect(nfds, &readfds, &writefds, &exceptfds, + timeout, &sigmask); +.EE +.in +.P +is equivalent to +.I atomically +executing the following calls: +.P +.in +4n +.EX +sigset_t origmask; +\& +pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); +ready = select(nfds, &readfds, &writefds, &exceptfds, timeout); +pthread_sigmask(SIG_SETMASK, &origmask, NULL); +.EE +.in +.P +The reason that +.BR pselect () +is needed is that if one wants to wait for either a signal +or for a file descriptor to become ready, then +an atomic test is needed to prevent race conditions. +(Suppose the signal handler sets a global flag and +returns. +Then a test of this global flag followed by a call of +.BR select () +could hang indefinitely if the signal arrived just after the test +but just before the call. +By contrast, +.BR pselect () +allows one to first block signals, handle the signals that have come in, +then call +.BR pselect () +with the desired +.IR sigmask , +avoiding the race.) +.SS The timeout +The +.I timeout +argument for +.BR select () +is a structure of the following type: +.P +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.P +The corresponding argument for +.BR pselect () +is a +.BR timespec (3) +structure. +.P +On Linux, +.BR select () +modifies +.I timeout +to reflect the amount of time not slept; most other implementations +do not do this. +(POSIX.1 permits either behavior.) +This causes problems both when Linux code which reads +.I timeout +is ported to other operating systems, and when code is ported to Linux +that reuses a \fIstruct timeval\fP for multiple +.BR select ()s +in a loop without reinitializing it. +Consider +.I timeout +to be undefined after +.BR select () +returns. +.\" .P - it is rumored that: +.\" On BSD, when a timeout occurs, the file descriptor bits are not changed. +.\" - it is certainly true that: +.\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout. +.SH RETURN VALUE +On success, +.BR select () +and +.BR pselect () +return the number of file descriptors contained in the three returned +descriptor sets (that is, the total number of bits that are set in +.IR readfds , +.IR writefds , +.IR exceptfds ). +The return value may be zero if the timeout expired before any +file descriptors became ready. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error; +the file descriptor sets are unmodified, +and +.I timeout +becomes undefined. +.SH ERRORS +.TP +.B EBADF +An invalid file descriptor was given in one of the sets. +(Perhaps a file descriptor that was already closed, +or one on which an error has occurred.) +However, see BUGS. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EINVAL +.I nfds +is negative or exceeds the +.B RLIMIT_NOFILE +resource limit (see +.BR getrlimit (2)). +.TP +.B EINVAL +The value contained within +.I timeout +is invalid. +.TP +.B ENOMEM +Unable to allocate memory for internal tables. +.SH VERSIONS +On some other UNIX systems, +.\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett +.BR select () +can fail with the error +.B EAGAIN +if the system fails to allocate kernel-internal resources, rather than +.B ENOMEM +as Linux does. +POSIX specifies this error for +.BR poll (2), +but not for +.BR select (). +Portable programs may wish to check for +.B EAGAIN +and loop, just as with +.BR EINTR . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR select () +POSIX.1-2001, 4.4BSD (first appeared in 4.2BSD). +.IP +Generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System\ V variants). +However, note that the System\ V variant typically +sets the timeout variable before returning, but the BSD variant does not. +.TP +.BR pselect () +Linux 2.6.16. +POSIX.1g, POSIX.1-2001. +.IP +Prior to this, +it was emulated in glibc (but see BUGS). +.TP +.B fd_set +POSIX.1-2001. +.SH NOTES +The following header also provides the +.I fd_set +type: +.IR . +.P +An +.I fd_set +is a fixed size buffer. +Executing +.BR FD_CLR () +or +.BR FD_SET () +with a value of +.I fd +that is negative or is equal to or larger than +.B FD_SETSIZE +will result +in undefined behavior. +Moreover, POSIX requires +.I fd +to be a valid file descriptor. +.P +The operation of +.BR select () +and +.BR pselect () +is not affected by the +.B O_NONBLOCK +flag. +.\" +.SS The self-pipe trick +On systems that lack +.BR pselect (), +reliable (and more portable) signal trapping can be achieved +using the self-pipe trick. +In this technique, +a signal handler writes a byte to a pipe whose other end +is monitored by +.BR select () +in the main program. +(To avoid possibly blocking when writing to a pipe that may be full +or reading from a pipe that may be empty, +nonblocking I/O is used when reading from and writing to the pipe.) +.\" +.SS Emulating usleep(3) +Before the advent of +.BR usleep (3), +some code employed a call to +.BR select () +with all three sets empty, +.I nfds +zero, and a non-NULL +.I timeout +as a fairly portable way to sleep with subsecond precision. +.\" +.SS Correspondence between select() and poll() notifications +Within the Linux kernel source, +.\" fs/select.c +we find the following definitions which show the correspondence +between the readable, writable, and exceptional condition notifications of +.BR select () +and the event notifications provided by +.BR poll (2) +and +.BR epoll (7): +.P +.in +4n +.EX +#define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN | + EPOLLHUP | EPOLLERR) + /* Ready for reading */ +#define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT | + EPOLLERR) + /* Ready for writing */ +#define POLLEX_SET (EPOLLPRI) + /* Exceptional condition */ +.EE +.in +.\" +.SS Multithreaded applications +If a file descriptor being monitored by +.BR select () +is closed in another thread, the result is unspecified. +On some UNIX systems, +.BR select () +unblocks and returns, with an indication that the file descriptor is ready +(a subsequent I/O operation will likely fail with an error, +unless another process reopens the file descriptor between the time +.BR select () +returned and the I/O operation is performed). +On Linux (and some other systems), +closing the file descriptor in another thread has no effect on +.BR select (). +In summary, any application that relies on a particular behavior +in this scenario must be considered buggy. +.\" +.SS C library/kernel differences +The Linux kernel allows file descriptor sets of arbitrary size, +determining the length of the sets to be checked from the value of +.IR nfds . +However, in the glibc implementation, the +.I fd_set +type is fixed in size. +See also BUGS. +.P +The +.BR pselect () +interface described in this page is implemented by glibc. +The underlying Linux system call is named +.BR pselect6 (). +This system call has somewhat different behavior from the glibc +wrapper function. +.P +The Linux +.BR pselect6 () +system call modifies its +.I timeout +argument. +However, the glibc wrapper function hides this behavior +by using a local variable for the timeout argument that +is passed to the system call. +Thus, the glibc +.BR pselect () +function does not modify its +.I timeout +argument; +this is the behavior required by POSIX.1-2001. +.P +The final argument of the +.BR pselect6 () +system call is not a +.I "sigset_t\ *" +pointer, but is instead a structure of the form: +.P +.in +4n +.EX +struct { + const kernel_sigset_t *ss; /* Pointer to signal set */ + size_t ss_len; /* Size (in bytes) of object + pointed to by \[aq]ss\[aq] */ +}; +.EE +.in +.P +This allows the system call to obtain both +a pointer to the signal set and its size, +while allowing for the fact that most architectures +support a maximum of 6 arguments to a system call. +See +.BR sigprocmask (2) +for a discussion of the difference between the kernel and libc +notion of the signal set. +.\" +.SS Historical glibc details +glibc 2.0 provided an incorrect version of +.BR pselect () +that did not take a +.I sigmask +argument. +.P +From glibc 2.1 to glibc 2.2.1, +one must define +.B _GNU_SOURCE +in order to obtain the declaration of +.BR pselect () +from +.IR . +.SH BUGS +POSIX allows an implementation to define an upper limit, +advertised via the constant +.BR FD_SETSIZE , +on the range of file descriptors that can be specified +in a file descriptor set. +The Linux kernel imposes no fixed limit, but the glibc implementation makes +.I fd_set +a fixed-size type, with +.B FD_SETSIZE +defined as 1024, and the +.BR FD_* () +macros operating according to that limit. +To monitor file descriptors greater than 1023, use +.BR poll (2) +or +.BR epoll (7) +instead. +.P +The implementation of the +.I fd_set +arguments as value-result arguments is a design error that is avoided in +.BR poll (2) +and +.BR epoll (7). +.P +According to POSIX, +.BR select () +should check all specified file descriptors in the three file descriptor sets, +up to the limit +.IR nfds\-1 . +However, the current implementation ignores any file descriptor in +these sets that is greater than the maximum file descriptor number +that the process currently has open. +According to POSIX, any such file descriptor that is specified in one +of the sets should result in the error +.BR EBADF . +.P +Starting with glibc 2.1, glibc provided an emulation of +.BR pselect () +that was implemented using +.BR sigprocmask (2) +and +.BR select (). +This implementation remained vulnerable to the very race condition that +.BR pselect () +was designed to prevent. +Modern versions of glibc use the (race-free) +.BR pselect () +system call on kernels where it is provided. +.P +On Linux, +.BR select () +may report a socket file descriptor as "ready for reading", while +nevertheless a subsequent read blocks. +This could for example +happen when data has arrived but upon examination has the wrong +checksum and is discarded. +There may be other circumstances +in which a file descriptor is spuriously reported as ready. +.\" Stevens discusses a case where accept can block after select +.\" returns successfully because of an intervening RST from the client. +Thus it may be safer to use +.B O_NONBLOCK +on sockets that should not block. +.\" Maybe the kernel should have returned EIO in such a situation? +.P +On Linux, +.BR select () +also modifies +.I timeout +if the call is interrupted by a signal handler (i.e., the +.B EINTR +error return). +This is not permitted by POSIX.1. +The Linux +.BR pselect () +system call has the same behavior, +but the glibc wrapper hides this behavior by internally copying the +.I timeout +to a local variable and passing that variable to the system call. +.SH EXAMPLES +.\" SRC BEGIN (select.c) +.EX +#include +#include +#include +\& +int +main(void) +{ + int retval; + fd_set rfds; + struct timeval tv; +\& + /* Watch stdin (fd 0) to see when it has input. */ +\& + FD_ZERO(&rfds); + FD_SET(0, &rfds); +\& + /* Wait up to five seconds. */ +\& + tv.tv_sec = 5; + tv.tv_usec = 0; +\& + retval = select(1, &rfds, NULL, NULL, &tv); + /* Don\[aq]t rely on the value of tv now! */ +\& + if (retval == \-1) + perror("select()"); + else if (retval) + printf("Data is available now.\en"); + /* FD_ISSET(0, &rfds) will be true. */ + else + printf("No data within five seconds.\en"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR accept (2), +.BR connect (2), +.BR poll (2), +.BR read (2), +.BR recv (2), +.BR restart_syscall (2), +.BR send (2), +.BR sigprocmask (2), +.BR write (2), +.BR timespec (3), +.BR epoll (7), +.BR time (7) +.P +For a tutorial with discussion and examples, see +.BR select_tut (2). diff --git a/man/man2/select_tut.2 b/man/man2/select_tut.2 new file mode 100644 index 0000000..e99ea05 --- /dev/null +++ b/man/man2/select_tut.2 @@ -0,0 +1,639 @@ +.\" This manpage is copyright (C) 2001 Paul Sheer. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" very minor changes, aeb +.\" +.\" Modified 5 June 2002, Michael Kerrisk +.\" 2006-05-13, mtk, removed much material that is redundant with select.2 +.\" various other changes +.\" 2008-01-26, mtk, substantial changes and rewrites +.\" +.TH SELECT_TUT 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +select, pselect \- synchronous I/O multiplexing +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +See +.BR select (2) +.SH DESCRIPTION +The +.BR select () +and +.BR pselect () +system calls are used to efficiently monitor multiple file descriptors, +to see if any of them is, or becomes, "ready"; +that is, to see whether I/O becomes possible, +or an "exceptional condition" has occurred on any of the file descriptors. +.P +This page provides background and tutorial information +on the use of these system calls. +For details of the arguments and semantics of +.BR select () +and +.BR pselect (), +see +.BR select (2). +.\" +.SS Combining signal and data events +.BR pselect () +is useful if you are waiting for a signal as well as +for file descriptor(s) to become ready for I/O. +Programs that receive signals +normally use the signal handler only to raise a global flag. +The global flag will indicate that the event must be processed +in the main loop of the program. +A signal will cause the +.BR select () +(or +.BR pselect ()) +call to return with \fIerrno\fP set to \fBEINTR\fP. +This behavior is essential so that signals can be processed +in the main loop of the program, otherwise +.BR select () +would block indefinitely. +.P +Now, somewhere +in the main loop will be a conditional to check the global flag. +So we must ask: +what if a signal arrives after the conditional, but before the +.BR select () +call? +The answer is that +.BR select () +would block indefinitely, even though an event is actually pending. +This race condition is solved by the +.BR pselect () +call. +This call can be used to set the signal mask to a set of signals +that are to be received only within the +.BR pselect () +call. +For instance, let us say that the event in question +was the exit of a child process. +Before the start of the main loop, we +would block \fBSIGCHLD\fP using +.BR sigprocmask (2). +Our +.BR pselect () +call would enable +.B SIGCHLD +by using an empty signal mask. +Our program would look like: +.P +.EX +static volatile sig_atomic_t got_SIGCHLD = 0; +\& +static void +child_sig_handler(int sig) +{ + got_SIGCHLD = 1; +} +\& +int +main(int argc, char *argv[]) +{ + sigset_t sigmask, empty_mask; + struct sigaction sa; + fd_set readfds, writefds, exceptfds; + int r; +\& + sigemptyset(&sigmask); + sigaddset(&sigmask, SIGCHLD); + if (sigprocmask(SIG_BLOCK, &sigmask, NULL) == \-1) { + perror("sigprocmask"); + exit(EXIT_FAILURE); + } +\& + sa.sa_flags = 0; + sa.sa_handler = child_sig_handler; + sigemptyset(&sa.sa_mask); + if (sigaction(SIGCHLD, &sa, NULL) == \-1) { + perror("sigaction"); + exit(EXIT_FAILURE); + } +\& + sigemptyset(&empty_mask); +\& + for (;;) { /* main loop */ + /* Initialize readfds, writefds, and exceptfds + before the pselect() call. (Code omitted.) */ +\& + r = pselect(nfds, &readfds, &writefds, &exceptfds, + NULL, &empty_mask); + if (r == \-1 && errno != EINTR) { + /* Handle error */ + } +\& + if (got_SIGCHLD) { + got_SIGCHLD = 0; +\& + /* Handle signalled event here; e.g., wait() for all + terminated children. (Code omitted.) */ + } +\& + /* main body of program */ + } +} +.EE +.SS Practical +So what is the point of +.BR select ()? +Can't I just read and write to my file descriptors whenever I want? +The point of +.BR select () +is that it watches +multiple descriptors at the same time and properly puts the process to +sleep if there is no activity. +UNIX programmers often find +themselves in a position where they have to handle I/O from more than one +file descriptor where the data flow may be intermittent. +If you were to merely create a sequence of +.BR read (2) +and +.BR write (2) +calls, you would +find that one of your calls may block waiting for data from/to a file +descriptor, while another file descriptor is unused though ready for I/O. +.BR select () +efficiently copes with this situation. +.SS Select law +Many people who try to use +.BR select () +come across behavior that is +difficult to understand and produces nonportable or borderline results. +For instance, the above program is carefully written not to +block at any point, even though it does not set its file descriptors to +nonblocking mode. +It is easy to introduce +subtle errors that will remove the advantage of using +.BR select (), +so here is a list of essentials to watch for when using +.BR select (). +.TP 4 +1. +You should always try to use +.BR select () +without a timeout. +Your program +should have nothing to do if there is no data available. +Code that +depends on timeouts is not usually portable and is difficult to debug. +.TP +2. +The value \fInfds\fP must be properly calculated for efficiency as +explained above. +.TP +3. +No file descriptor must be added to any set if you do not intend +to check its result after the +.BR select () +call, and respond appropriately. +See next rule. +.TP +4. +After +.BR select () +returns, all file descriptors in all sets +should be checked to see if they are ready. +.TP +5. +The functions +.BR read (2), +.BR recv (2), +.BR write (2), +and +.BR send (2) +do \fInot\fP necessarily read/write the full amount of data +that you have requested. +If they do read/write the full amount, it's +because you have a low traffic load and a fast stream. +This is not always going to be the case. +You should cope with the case of your +functions managing to send or receive only a single byte. +.TP +6. +Never read/write only in single bytes at a time unless you are really +sure that you have a small amount of data to process. +It is extremely +inefficient not to read/write as much data as you can buffer each time. +The buffers in the example below are 1024 bytes although they could +easily be made larger. +.TP +7. +Calls to +.BR read (2), +.BR recv (2), +.BR write (2), +.BR send (2), +and +.BR select () +can fail with the error +\fBEINTR\fP, +and calls to +.BR read (2), +.BR recv (2), +.BR write (2), +and +.BR send (2) +can fail with +.I errno +set to \fBEAGAIN\fP (\fBEWOULDBLOCK\fP). +These results must be properly managed (not done properly above). +If your program is not going to receive any signals, then +it is unlikely you will get \fBEINTR\fP. +If your program does not set nonblocking I/O, +you will not get \fBEAGAIN\fP. +.\" Nonetheless, you should still cope with these errors for completeness. +.TP +8. +Never call +.BR read (2), +.BR recv (2), +.BR write (2), +or +.BR send (2) +with a buffer length of zero. +.TP +9. +If the functions +.BR read (2), +.BR recv (2), +.BR write (2), +and +.BR send (2) +fail with errors other than those listed in \fB7.\fP, +or one of the input functions returns 0, indicating end of file, +then you should \fInot\fP pass that file descriptor to +.BR select () +again. +In the example below, +I close the file descriptor immediately, and then set it to \-1 +to prevent it being included in a set. +.TP +10. +The timeout value must be initialized with each new call to +.BR select (), +since some operating systems modify the structure. +.BR pselect () +however does not modify its timeout structure. +.TP +11. +Since +.BR select () +modifies its file descriptor sets, +if the call is being used in a loop, +then the sets must be reinitialized before each call. +.\" "I have heard" does not fill me with confidence, and doesn't +.\" belong in a man page, so I've commented this point out. +.\" .TP +.\" 11. +.\" I have heard that the Windows socket layer does not cope with OOB data +.\" properly. +.\" It also does not cope with +.\" .BR select () +.\" calls when no file descriptors are set at all. +.\" Having no file descriptors set is a useful +.\" way to sleep the process with subsecond precision by using the timeout. +.\" (See further on.) +.SH RETURN VALUE +See +.BR select (2). +.SH NOTES +Generally speaking, +all operating systems that support sockets also support +.BR select (). +.BR select () +can be used to solve +many problems in a portable and efficient way that naive programmers try +to solve in a more complicated manner using +threads, forking, IPCs, signals, memory sharing, and so on. +.P +The +.BR poll (2) +system call has the same functionality as +.BR select (), +and is somewhat more efficient when monitoring sparse +file descriptor sets. +It is nowadays widely available, but historically was less portable than +.BR select (). +.P +The Linux-specific +.BR epoll (7) +API provides an interface that is more efficient than +.BR select (2) +and +.BR poll (2) +when monitoring large numbers of file descriptors. +.SH EXAMPLES +Here is an example that better demonstrates the true utility of +.BR select (). +The listing below is a TCP forwarding program that forwards +from one TCP port to another. +.P +.\" SRC BEGIN (select.c) +.EX +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +static int forward_port; +\& +#undef max +#define max(x, y) ((x) > (y) ? (x) : (y)) +\& +static int +listen_socket(int listen_port) +{ + int lfd; + int yes; + struct sockaddr_in addr; +\& + lfd = socket(AF_INET, SOCK_STREAM, 0); + if (lfd == \-1) { + perror("socket"); + return \-1; + } +\& + yes = 1; + if (setsockopt(lfd, SOL_SOCKET, SO_REUSEADDR, + &yes, sizeof(yes)) == \-1) + { + perror("setsockopt"); + close(lfd); + return \-1; + } +\& + memset(&addr, 0, sizeof(addr)); + addr.sin_port = htons(listen_port); + addr.sin_family = AF_INET; + if (bind(lfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) { + perror("bind"); + close(lfd); + return \-1; + } +\& + printf("accepting connections on port %d\en", listen_port); + listen(lfd, 10); + return lfd; +} +\& +static int +connect_socket(int connect_port, char *address) +{ + int cfd; + struct sockaddr_in addr; +\& + cfd = socket(AF_INET, SOCK_STREAM, 0); + if (cfd == \-1) { + perror("socket"); + return \-1; + } +\& + memset(&addr, 0, sizeof(addr)); + addr.sin_port = htons(connect_port); + addr.sin_family = AF_INET; +\& + if (!inet_aton(address, (struct in_addr *) &addr.sin_addr.s_addr)) { + fprintf(stderr, "inet_aton(): bad IP address format\en"); + close(cfd); + return \-1; + } +\& + if (connect(cfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) { + perror("connect()"); + shutdown(cfd, SHUT_RDWR); + close(cfd); + return \-1; + } + return cfd; +} +\& +#define SHUT_FD1 do { \e + if (fd1 >= 0) { \e + shutdown(fd1, SHUT_RDWR); \e + close(fd1); \e + fd1 = \-1; \e + } \e + } while (0) +\& +#define SHUT_FD2 do { \e + if (fd2 >= 0) { \e + shutdown(fd2, SHUT_RDWR); \e + close(fd2); \e + fd2 = \-1; \e + } \e + } while (0) +\& +#define BUF_SIZE 1024 +\& +int +main(int argc, char *argv[]) +{ + int h; + int ready, nfds; + int fd1 = \-1, fd2 = \-1; + int buf1_avail = 0, buf1_written = 0; + int buf2_avail = 0, buf2_written = 0; + char buf1[BUF_SIZE], buf2[BUF_SIZE]; + fd_set readfds, writefds, exceptfds; + ssize_t nbytes; +\& + if (argc != 4) { + fprintf(stderr, "Usage\en\etfwd " + " \en"); + exit(EXIT_FAILURE); + } +\& + signal(SIGPIPE, SIG_IGN); +\& + forward_port = atoi(argv[2]); +\& + h = listen_socket(atoi(argv[1])); + if (h == \-1) + exit(EXIT_FAILURE); +\& + for (;;) { + nfds = 0; +\& + FD_ZERO(&readfds); + FD_ZERO(&writefds); + FD_ZERO(&exceptfds); + FD_SET(h, &readfds); + nfds = max(nfds, h); +\& + if (fd1 > 0 && buf1_avail < BUF_SIZE) + FD_SET(fd1, &readfds); + /* Note: nfds is updated below, when fd1 is added to + exceptfds. */ + if (fd2 > 0 && buf2_avail < BUF_SIZE) + FD_SET(fd2, &readfds); +\& + if (fd1 > 0 && buf2_avail \- buf2_written > 0) + FD_SET(fd1, &writefds); + if (fd2 > 0 && buf1_avail \- buf1_written > 0) + FD_SET(fd2, &writefds); +\& + if (fd1 > 0) { + FD_SET(fd1, &exceptfds); + nfds = max(nfds, fd1); + } + if (fd2 > 0) { + FD_SET(fd2, &exceptfds); + nfds = max(nfds, fd2); + } +\& + ready = select(nfds + 1, &readfds, &writefds, &exceptfds, NULL); +\& + if (ready == \-1 && errno == EINTR) + continue; +\& + if (ready == \-1) { + perror("select()"); + exit(EXIT_FAILURE); + } +\& + if (FD_ISSET(h, &readfds)) { + socklen_t addrlen; + struct sockaddr_in client_addr; + int fd; +\& + addrlen = sizeof(client_addr); + memset(&client_addr, 0, addrlen); + fd = accept(h, (struct sockaddr *) &client_addr, &addrlen); + if (fd == \-1) { + perror("accept()"); + } else { + SHUT_FD1; + SHUT_FD2; + buf1_avail = buf1_written = 0; + buf2_avail = buf2_written = 0; + fd1 = fd; + fd2 = connect_socket(forward_port, argv[3]); + if (fd2 == \-1) + SHUT_FD1; + else + printf("connect from %s\en", + inet_ntoa(client_addr.sin_addr)); +\& + /* Skip any events on the old, closed file + descriptors. */ +\& + continue; + } + } +\& + /* NB: read OOB data before normal reads. */ +\& + if (fd1 > 0 && FD_ISSET(fd1, &exceptfds)) { + char c; +\& + nbytes = recv(fd1, &c, 1, MSG_OOB); + if (nbytes < 1) + SHUT_FD1; + else + send(fd2, &c, 1, MSG_OOB); + } + if (fd2 > 0 && FD_ISSET(fd2, &exceptfds)) { + char c; +\& + nbytes = recv(fd2, &c, 1, MSG_OOB); + if (nbytes < 1) + SHUT_FD2; + else + send(fd1, &c, 1, MSG_OOB); + } + if (fd1 > 0 && FD_ISSET(fd1, &readfds)) { + nbytes = read(fd1, buf1 + buf1_avail, + BUF_SIZE \- buf1_avail); + if (nbytes < 1) + SHUT_FD1; + else + buf1_avail += nbytes; + } + if (fd2 > 0 && FD_ISSET(fd2, &readfds)) { + nbytes = read(fd2, buf2 + buf2_avail, + BUF_SIZE \- buf2_avail); + if (nbytes < 1) + SHUT_FD2; + else + buf2_avail += nbytes; + } + if (fd1 > 0 && FD_ISSET(fd1, &writefds) && buf2_avail > 0) { + nbytes = write(fd1, buf2 + buf2_written, + buf2_avail \- buf2_written); + if (nbytes < 1) + SHUT_FD1; + else + buf2_written += nbytes; + } + if (fd2 > 0 && FD_ISSET(fd2, &writefds) && buf1_avail > 0) { + nbytes = write(fd2, buf1 + buf1_written, + buf1_avail \- buf1_written); + if (nbytes < 1) + SHUT_FD2; + else + buf1_written += nbytes; + } +\& + /* Check if write data has caught read data. */ +\& + if (buf1_written == buf1_avail) + buf1_written = buf1_avail = 0; + if (buf2_written == buf2_avail) + buf2_written = buf2_avail = 0; +\& + /* One side has closed the connection, keep + writing to the other side until empty. */ +\& + if (fd1 < 0 && buf1_avail \- buf1_written == 0) + SHUT_FD2; + if (fd2 < 0 && buf2_avail \- buf2_written == 0) + SHUT_FD1; + } + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.P +The above program properly forwards most kinds of TCP connections +including OOB signal data transmitted by \fBtelnet\fP servers. +It handles the tricky problem of having data flow in both directions +simultaneously. +You might think it more efficient to use a +.BR fork (2) +call and devote a thread to each stream. +This becomes more tricky than you might suspect. +Another idea is to set nonblocking I/O using +.BR fcntl (2). +This also has its problems because you end up using +inefficient timeouts. +.P +The program does not handle more than one simultaneous connection at a +time, although it could easily be extended to do this with a linked list +of buffers\[em]one for each connection. +At the moment, new +connections cause the current connection to be dropped. +.SH SEE ALSO +.BR accept (2), +.BR connect (2), +.BR poll (2), +.BR read (2), +.BR recv (2), +.BR select (2), +.BR send (2), +.BR sigprocmask (2), +.BR write (2), +.BR epoll (7) +.\" .SH AUTHORS +.\" This man page was written by Paul Sheer. diff --git a/man/man2/semctl.2 b/man/man2/semctl.2 new file mode 100644 index 0000000..a5c7fae --- /dev/null +++ b/man/man2/semctl.2 @@ -0,0 +1,623 @@ +'\" t +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" and Copyright 2004, 2005 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond +.\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer +.\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer +.\" Modified 20 Dec 2001, Michael Kerrisk +.\" Modified 21 Dec 2001, aeb +.\" Modified 27 May 2004, Michael Kerrisk +.\" Added notes on CAP_IPC_OWNER requirement +.\" Modified 17 Jun 2004, Michael Kerrisk +.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Rewrote semun text +.\" Added semid_ds and ipc_perm structure definitions +.\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. +.\" 2018-03-20, dbueso: Added SEM_STAT_ANY description. +.\" +.TH semctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +semctl \- System V semaphore control operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int semctl(int " semid ", int " semnum ", int " op ", ...);" +.fi +.SH DESCRIPTION +.BR semctl () +performs the control operation specified by +.I op +on the System\ V semaphore set identified by +.IR semid , +or on the +.IR semnum -th +semaphore of that set. +(The semaphores in a set are numbered starting at 0.) +.P +This function has three or four arguments, depending on +.IR op . +When there are four, the fourth has the type +.IR "union semun" . +The \fIcalling program\fP must define this union as follows: +.P +.in +4n +.EX +union semun { + int val; /* Value for SETVAL */ + struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */ + unsigned short *array; /* Array for GETALL, SETALL */ + struct seminfo *__buf; /* Buffer for IPC_INFO + (Linux\-specific) */ +}; +.EE +.in +.P +The +.I semid_ds +data structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct semid_ds { + struct ipc_perm sem_perm; /* Ownership and permissions */ + time_t sem_otime; /* Last semop time */ + time_t sem_ctime; /* Creation time/time of last + modification via semctl() */ + unsigned long sem_nsems; /* No. of semaphores in set */ +}; +.EE +.in +.P +The fields of the +.I semid_ds +structure are as follows: +.TP 11 +.I sem_perm +This is an +.I ipc_perm +structure (see below) that specifies the access permissions on the semaphore +set. +.TP +.I sem_otime +Time of last +.BR semop (2) +system call. +.TP +.I sem_ctime +Time of creation of semaphore set or time of last +.BR semctl () +.BR IPCSET , +.BR SETVAL , +or +.B SETALL +operation. +.TP +.I sem_nsems +Number of semaphores in the set. +Each semaphore of the set is referenced by a nonnegative integer +ranging from +.B 0 +to +.IR sem_nsems\-1 . +.P +The +.I ipc_perm +structure is defined as follows +(the highlighted fields are settable using +.BR IPC_SET ): +.P +.in +4n +.EX +struct ipc_perm { + key_t __key; /* Key supplied to semget(2) */ + uid_t \fBuid\fP; /* Effective UID of owner */ + gid_t \fBgid\fP; /* Effective GID of owner */ + uid_t cuid; /* Effective UID of creator */ + gid_t cgid; /* Effective GID of creator */ + unsigned short \fBmode\fP; /* Permissions */ + unsigned short __seq; /* Sequence number */ +}; +.EE +.in +.P +The least significant 9 bits of the +.I mode +field of the +.I ipc_perm +structure define the access permissions for the shared memory segment. +The permission bits are as follows: +.TS +l l. +0400 Read by user +0200 Write by user +0040 Read by group +0020 Write by group +0004 Read by others +0002 Write by others +.TE +.P +In effect, "write" means "alter" for a semaphore set. +Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. +.P +Valid values for +.I op +are: +.TP +.B IPC_STAT +Copy information from the kernel data structure associated with +.I semid +into the +.I semid_ds +structure pointed to by +.IR arg.buf . +The argument +.I semnum +is ignored. +The calling process must have read permission on the semaphore set. +.TP +.B IPC_SET +Write the values of some members of the +.I semid_ds +structure pointed to by +.I arg.buf +to the kernel data structure associated with this semaphore set, +updating also its +.I sem_ctime +member. +.IP +The following members of the structure are updated: +.IR sem_perm.uid , +.IR sem_perm.gid , +and (the least significant 9 bits of) +.IR sem_perm.mode . +.IP +The effective UID of the calling process must match the owner +.RI ( sem_perm.uid ) +or creator +.RI ( sem_perm.cuid ) +of the semaphore set, or the caller must be privileged. +The argument +.I semnum +is ignored. +.TP +.B IPC_RMID +Immediately remove the semaphore set, +awakening all processes blocked in +.BR semop (2) +calls on the set (with an error return and +.I errno +set to +.BR EIDRM ). +The effective user ID of the calling process must +match the creator or owner of the semaphore set, +or the caller must be privileged. +The argument +.I semnum +is ignored. +.TP +.BR IPC_INFO " (Linux\-specific)" +Return information about system-wide semaphore limits and +parameters in the structure pointed to by +.IR arg.__buf . +This structure is of type +.IR seminfo , +defined in +.I +if the +.B _GNU_SOURCE +feature test macro is defined: +.IP +.in +4n +.EX +struct seminfo { + int semmap; /* Number of entries in semaphore + map; unused within kernel */ + int semmni; /* Maximum number of semaphore sets */ + int semmns; /* Maximum number of semaphores in all + semaphore sets */ + int semmnu; /* System\-wide maximum number of undo + structures; unused within kernel */ + int semmsl; /* Maximum number of semaphores in a + set */ + int semopm; /* Maximum number of operations for + semop(2) */ + int semume; /* Maximum number of undo entries per + process; unused within kernel */ + int semusz; /* Size of struct sem_undo */ + int semvmx; /* Maximum semaphore value */ + int semaem; /* Max. value that can be recorded for + semaphore adjustment (SEM_UNDO) */ +}; +.EE +.in +.IP +The +.IR semmsl , +.IR semmns , +.IR semopm , +and +.I semmni +settings can be changed via +.IR /proc/sys/kernel/sem ; +see +.BR proc (5) +for details. +.TP +.BR SEM_INFO " (Linux-specific)" +Return a +.I seminfo +structure containing the same information as for +.BR IPC_INFO , +except that the following fields are returned with information +about system resources consumed by semaphores: the +.I semusz +field returns the number of semaphore sets that currently exist +on the system; and the +.I semaem +field returns the total number of semaphores in all semaphore sets +on the system. +.TP +.BR SEM_STAT " (Linux-specific)" +Return a +.I semid_ds +structure as for +.BR IPC_STAT . +However, the +.I semid +argument is not a semaphore identifier, but instead an index into +the kernel's internal array that maintains information about +all semaphore sets on the system. +.TP +.BR SEM_STAT_ANY " (Linux-specific, since Linux 4.17)" +Return a +.I semid_ds +structure as for +.BR SEM_STAT . +However, +.I sem_perm.mode +is not checked for read access for +.I semid +meaning that any user can employ this operation (just as any user may read +.I /proc/sysvipc/sem +to obtain the same information). +.TP +.B GETALL +Return +.B semval +(i.e., the current value) +for all semaphores of the set into +.IR arg.array . +The argument +.I semnum +is ignored. +The calling process must have read permission on the semaphore set. +.TP +.B GETNCNT +Return the +.B semncnt +value for the +.IR semnum \-th +semaphore of the set +(i.e., the number of processes waiting for the semaphore's value to increase). +The calling process must have read permission on the semaphore set. +.TP +.B GETPID +Return the +.B sempid +value for the +.IR semnum \-th +semaphore of the set. +This is the PID of the process that last performed an operation on +that semaphore (but see NOTES). +The calling process must have read permission on the semaphore set. +.TP +.B GETVAL +Return +.B semval +(i.e., the semaphore value) for the +.IR semnum \-th +semaphore of the set. +The calling process must have read permission on the semaphore set. +.TP +.B GETZCNT +Return the +.B semzcnt +value for the +.IR semnum \-th +semaphore of the set +(i.e., the number of processes waiting for the semaphore value to become 0). +The calling process must have read permission on the semaphore set. +.TP +.B SETALL +Set the +.B semval +values for all semaphores of the set using +.IR arg.array , +updating also the +.I sem_ctime +member of the +.I semid_ds +structure associated with the set. +Undo entries (see +.BR semop (2)) +are cleared for altered semaphores in all processes. +If the changes to semaphore values would permit blocked +.BR semop (2) +calls in other processes to proceed, then those processes are woken up. +The argument +.I semnum +is ignored. +The calling process must have alter (write) permission on +the semaphore set. +.TP +.B SETVAL +Set the semaphore value +.RB ( semval ) +to +.I arg.val +for the +.IR semnum \-th +semaphore of the set, updating also the +.I sem_ctime +member of the +.I semid_ds +structure associated with the set. +Undo entries are cleared for altered semaphores in all processes. +If the changes to semaphore values would permit blocked +.BR semop (2) +calls in other processes to proceed, then those processes are woken up. +The calling process must have alter permission on the semaphore set. +.SH RETURN VALUE +On success, +.BR semctl () +returns a nonnegative value depending on +.I op +as follows: +.TP +.B GETNCNT +the value of +.BR semncnt . +.TP +.B GETPID +the value of +.BR sempid . +.TP +.B GETVAL +the value of +.BR semval . +.TP +.B GETZCNT +the value of +.BR semzcnt . +.TP +.B IPC_INFO +the index of the highest used entry in the +kernel's internal array recording information about all +semaphore sets. +(This information can be used with repeated +.B SEM_STAT +or +.B SEM_STAT_ANY +operations to obtain information about all semaphore sets on the system.) +.TP +.B SEM_INFO +as for +.BR IPC_INFO . +.TP +.B SEM_STAT +the identifier of the semaphore set whose index was given in +.IR semid . +.TP +.B SEM_STAT_ANY +as for +.BR SEM_STAT . +.P +All other +.I op +values return 0 on success. +.P +On failure, +.BR semctl () +returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EACCES +The argument +.I op +has one of the values +.BR GETALL , +.BR GETPID , +.BR GETVAL , +.BR GETNCNT , +.BR GETZCNT , +.BR IPC_STAT , +.BR SEM_STAT , +.BR SEM_STAT_ANY , +.BR SETALL , +or +.B SETVAL +and the calling process does not have the required +permissions on the semaphore set and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EFAULT +The address pointed to by +.I arg.buf +or +.I arg.array +isn't accessible. +.TP +.B EIDRM +The semaphore set was removed. +.TP +.B EINVAL +Invalid value for +.I op +or +.IR semid . +Or: for a +.B SEM_STAT +operation, the index value specified in +.I semid +referred to an array slot that is currently unused. +.TP +.B EPERM +The argument +.I op +has the value +.B IPC_SET +or +.B IPC_RMID +but the effective user ID of the calling process is not the creator +(as found in +.IR sem_perm.cuid ) +or the owner +(as found in +.IR sem_perm.uid ) +of the semaphore set, +and the process does not have the +.B CAP_SYS_ADMIN +capability. +.TP +.B ERANGE +The argument +.I op +has the value +.B SETALL +or +.B SETVAL +and the value to which +.B semval +is to be set (for some semaphore of the set) is less than 0 +or greater than the implementation limit +.BR SEMVMX . +.SH VERSIONS +POSIX.1 specifies the +.\" POSIX.1-2001, POSIX.1-2008 +.I sem_nsems +field of the +.I semid_ds +structure as having the type +.IR "unsigned\ short" , +and the field is so defined on most other systems. +It was also so defined on Linux 2.2 and earlier, +but, since Linux 2.4, the field has the type +.IR "unsigned\ long" . +.\" +.SS The sempid value +POSIX.1 defines +.I sempid +as the "process ID of [the] last operation" on a semaphore, +and explicitly notes that this value is set by a successful +.BR semop (2) +call, with the implication that no other interface affects the +.I sempid +value. +.P +While some implementations conform to the behavior specified in POSIX.1, +others do not. +(The fault here probably lies with POSIX.1 inasmuch as it likely failed +to capture the full range of existing implementation behaviors.) +Various other implementations +.\" At least OpenSolaris (and, one supposes, older Solaris) and Darwin +also update +.I sempid +for the other operations that update the value of a semaphore: the +.B SETVAL +and +.B SETALL +operations, as well as the semaphore adjustments performed +on process termination as a consequence of the use of the +.B SEM_UNDO +flag (see +.BR semop (2)). +.P +Linux also updates +.I sempid +for +.B SETVAL +operations and semaphore adjustments. +However, somewhat inconsistently, up to and including Linux 4.5, +the kernel did not update +.I sempid +for +.B SETALL +operations. +This was rectified +.\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f +in Linux 4.6. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVr4 documents more error conditions EINVAL and EOVERFLOW. +.P +Various fields in a \fIstruct semid_ds\fP were typed as +.I short +under Linux 2.2 +and have become +.I long +under Linux 2.4. +To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by an +.B IPC_64 +flag in +.IR op .) +.P +In some earlier versions of glibc, the +.I semun +union was defined in \fI\fP, but POSIX.1 requires +.\" POSIX.1-2001, POSIX.1-2008 +that the caller define this union. +On versions of glibc where this union is \fInot\fP defined, +the macro +.B _SEM_SEMUN_UNDEFINED +is defined in \fI\fP. +.SH NOTES +The +.BR IPC_INFO , +.BR SEM_STAT , +and +.B SEM_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future these may modified or moved to a +.I /proc +filesystem interface. +.P +The following system limit on semaphore sets affects a +.BR semctl () +call: +.TP +.B SEMVMX +Maximum value for +.BR semval : +implementation dependent (32767). +.P +For greater portability, it is best to always call +.BR semctl () +with four arguments. +.SH EXAMPLES +See +.BR shmop (2). +.SH SEE ALSO +.BR ipc (2), +.BR semget (2), +.BR semop (2), +.BR capabilities (7), +.BR sem_overview (7), +.BR sysvipc (7) diff --git a/man/man2/semget.2 b/man/man2/semget.2 new file mode 100644 index 0000000..9c53462 --- /dev/null +++ b/man/man2/semget.2 @@ -0,0 +1,434 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" and Copyright (C) 2020 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Tue Oct 22 17:54:56 1996 by Eric S. Raymond +.\" Modified 1 Jan 2002, Martin Schulze +.\" Modified 4 Jan 2002, Michael Kerrisk +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" Rewrote BUGS note about semget()'s failure to initialize +.\" semaphore values +.\" +.TH semget 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +semget \- get a System V semaphore set identifier +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.fi +.P +.BI "int semget(key_t " key , +.BI "int " nsems , +.BI "int " semflg ); +.SH DESCRIPTION +The +.BR semget () +system call returns the System\ V semaphore set identifier +associated with the argument +.IR key . +It may be used either to obtain the identifier of a previously created +semaphore set (when +.I semflg +is zero and +.I key +does not have the value +.BR IPC_PRIVATE ), +or to create a new set. +.P +A new set of +.I nsems +semaphores is created if +.I key +has the value +.B IPC_PRIVATE +or if no existing semaphore set is associated with +.I key +and +.B IPC_CREAT +is specified in +.IR semflg . +.P +If +.I semflg +specifies both +.B IPC_CREAT +and +.B IPC_EXCL +and a semaphore set already exists for +.IR key , +then +.BR semget () +fails with +.I errno +set to +.BR EEXIST . +(This is analogous to the effect of the combination +.B O_CREAT | O_EXCL +for +.BR open (2).) +.P +Upon creation, the least significant 9 bits of the argument +.I semflg +define the permissions (for owner, group, and others) +for the semaphore set. +These bits have the same format, and the same +meaning, as the +.I mode +argument of +.BR open (2) +(though the execute permissions are +not meaningful for semaphores, and write permissions mean permission +to alter semaphore values). +.P +When creating a new semaphore set, +.BR semget () +initializes the set's associated data structure, +.I semid_ds +(see +.BR semctl (2)), +as follows: +.IP \[bu] 3 +.I sem_perm.cuid +and +.I sem_perm.uid +are set to the effective user ID of the calling process. +.IP \[bu] +.I sem_perm.cgid +and +.I sem_perm.gid +are set to the effective group ID of the calling process. +.IP \[bu] +The least significant 9 bits of +.I sem_perm.mode +are set to the least significant 9 bits of +.IR semflg . +.IP \[bu] +.I sem_nsems +is set to the value of +.IR nsems . +.IP \[bu] +.I sem_otime +is set to 0. +.IP \[bu] +.I sem_ctime +is set to the current time. +.P +The argument +.I nsems +can be 0 +(a don't care) +when a semaphore set is not being created. +Otherwise, +.I nsems +must be greater than 0 +and less than or equal to the maximum number of semaphores per semaphore set +.RB ( SEMMSL ). +.P +If the semaphore set already exists, the permissions are +verified. +.\" and a check is made to see if it is marked for destruction. +.SH RETURN VALUE +On success, +.BR semget () +returns the semaphore set identifier (a nonnegative integer). +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +A semaphore set exists for +.IR key , +but the calling process does not have permission to access the set, +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EEXIST +.B IPC_CREAT +and +.B IPC_EXCL +were specified in +.IR semflg , +but a semaphore set already exists for +.IR key . +.\" .TP +.\" .B EIDRM +.\" The semaphore set is marked to be deleted. +.TP +.B EINVAL +.I nsems +is less than 0 or greater than the limit on the number +of semaphores per semaphore set +.RB ( SEMMSL ). +.TP +.B EINVAL +A semaphore set corresponding to +.I key +already exists, but +.I nsems +is larger than the number of semaphores in that set. +.TP +.B ENOENT +No semaphore set exists for +.I key +and +.I semflg +did not specify +.BR IPC_CREAT . +.TP +.B ENOMEM +A semaphore set has to be created but the system does not have +enough memory for the new data structure. +.TP +.B ENOSPC +A semaphore set has to be created but the system limit for the maximum +number of semaphore sets +.RB ( SEMMNI ), +or the system wide maximum number of semaphores +.RB ( SEMMNS ), +would be exceeded. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, POSIX.1-2001. +.\" SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN, +.\" ERANGE, EFAULT. +.SH NOTES +.B IPC_PRIVATE +isn't a flag field but a +.I key_t +type. +If this special value is used for +.IR key , +the system call ignores all but the least significant 9 bits of +.I semflg +and creates a new semaphore set (on success). +.\" +.SS Semaphore initialization +The values of the semaphores in a newly created set are indeterminate. +(POSIX.1-2001 and POSIX.1-2008 are explicit on this point, +although POSIX.1-2008 notes that a future version of the standard +may require an implementation to initialize the semaphores to 0.) +Although Linux, like many other implementations, +initializes the semaphore values to 0, +a portable application cannot rely on this: +it should explicitly initialize the semaphores to the desired values. +.\" In truth, every one of the many implementations that I've tested sets +.\" the values to zero, but I suppose there is/was some obscure +.\" implementation out there that does not. +.P +Initialization can be done using +.BR semctl (2) +.B SETVAL +or +.B SETALL +operation. +Where multiple peers do not know who will be the first to +initialize the set, checking for a nonzero +.I sem_otime +in the associated data structure retrieved by a +.BR semctl (2) +.B IPC_STAT +operation can be used to avoid races. +.\" +.SS Semaphore limits +The following limits on semaphore set resources affect the +.BR semget () +call: +.TP +.B SEMMNI +System-wide limit on the number of semaphore sets. +Before Linux 3.19, +the default value for this limit was 128. +Since Linux 3.19, +.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4 +the default value is 32,000. +On Linux, this limit can be read and modified via the fourth field of +.IR /proc/sys/kernel/sem . +.\" This /proc file is not available in Linux 2.2 and earlier -- MTK +.TP +.B SEMMSL +Maximum number of semaphores per semaphore ID. +Before Linux 3.19, +the default value for this limit was 250. +Since Linux 3.19, +.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4 +the default value is 32,000. +On Linux, this limit can be read and modified via the first field of +.IR /proc/sys/kernel/sem . +.TP +.B SEMMNS +System-wide limit on the number of semaphores: policy dependent +(on Linux, this limit can be read and modified via the second field of +.IR /proc/sys/kernel/sem ). +Note that the number of semaphores system-wide +is also limited by the product of +.B SEMMSL +and +.BR SEMMNI . +.SH BUGS +The name choice +.B IPC_PRIVATE +was perhaps unfortunate, +.B IPC_NEW +would more clearly show its function. +.SH EXAMPLES +The program shown below uses +.BR semget () +to create a new semaphore set or retrieve the ID of an existing set. +It generates the +.I key +for +.BR semget () +using +.BR ftok (3). +The first two command-line arguments are used as the +.I pathname +and +.I proj_id +arguments for +.BR ftok (3). +The third command-line argument is an integer that specifies the +.I nsems +argument for +.BR semget (). +Command-line options can be used to specify the +.B IPC_CREAT +.RI ( \-c ) +and +.B IPC_EXCL +.RI ( \-x ) +flags for the call to +.BR semget (). +The usage of this program is demonstrated below. +.P +We first create two files that will be used to generate keys using +.BR ftok (3), +create two semaphore sets using those files, and then list the sets using +.BR ipcs (1): +.P +.in +4n +.EX +$ \fBtouch mykey mykey2\fP +$ \fB./t_semget \-c mykey p 1\fP +ID = 9 +$ \fB./t_semget \-c mykey2 p 2\fP +ID = 10 +$ \fBipcs \-s\fP +\& +\-\-\-\-\-\- Semaphore Arrays \-\-\-\-\-\-\-\- +key semid owner perms nsems +0x7004136d 9 mtk 600 1 +0x70041368 10 mtk 600 2 +.EE +.in +.P +Next, we demonstrate that when +.BR semctl (2) +is given the same +.I key +(as generated by the same arguments to +.BR ftok (3)), +it returns the ID of the already existing semaphore set: +.P +.in +4n +.EX +$ \fB./t_semget \-c mykey p 1\fP +ID = 9 +.EE +.in +.P +Finally, we demonstrate the kind of collision that can occur when +.BR ftok (3) +is given different +.I pathname +arguments that have the same inode number: +.P +.in +4n +.EX +$ \fBln mykey link\fP +$ \fBls \-i1 link mykey\fP +2233197 link +2233197 mykey +$ \fB./t_semget link p 1\fP # Generates same key as \[aq]mykey\[aq] +ID = 9 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (t_semget.c) +.EX +/* t_semget.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include +#include +#include +#include +#include +\& +static void +usage(const char *pname) +{ + fprintf(stderr, "Usage: %s [\-cx] pathname proj\-id num\-sems\en", + pname); + fprintf(stderr, " \-c Use IPC_CREAT flag\en"); + fprintf(stderr, " \-x Use IPC_EXCL flag\en"); + exit(EXIT_FAILURE); +} +\& +int +main(int argc, char *argv[]) +{ + int semid, nsems, flags, opt; + key_t key; +\& + flags = 0; + while ((opt = getopt(argc, argv, "cx")) != \-1) { + switch (opt) { + case \[aq]c\[aq]: flags |= IPC_CREAT; break; + case \[aq]x\[aq]: flags |= IPC_EXCL; break; + default: usage(argv[0]); + } + } +\& + if (argc != optind + 3) + usage(argv[0]); +\& + key = ftok(argv[optind], argv[optind + 1][0]); + if (key == \-1) { + perror("ftok"); + exit(EXIT_FAILURE); + } +\& + nsems = atoi(argv[optind + 2]); +\& + semid = semget(key, nsems, flags | 0600); + if (semid == \-1) { + perror("semget"); + exit(EXIT_FAILURE); + } +\& + printf("ID = %d\en", semid); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR semctl (2), +.BR semop (2), +.BR ftok (3), +.BR capabilities (7), +.BR sem_overview (7), +.BR sysvipc (7) diff --git a/man/man2/semop.2 b/man/man2/semop.2 new file mode 100644 index 0000000..6c03ffe --- /dev/null +++ b/man/man2/semop.2 @@ -0,0 +1,523 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1996-10-22, Eric S. Raymond +.\" Modified 2002-01-08, Michael Kerrisk +.\" Modified 2003-04-28, Ernie Petrides +.\" Modified 2004-05-27, Michael Kerrisk +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop() +.\" 2007-07-09, mtk, Added an EXAMPLE code segment. +.\" +.TH semop 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +semop, semtimedop \- System V semaphore operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int semop(int " semid ", struct sembuf *" sops ", size_t " nsops ); +.BI "int semtimedop(int " semid ", struct sembuf *" sops ", size_t " nsops , +.BI " const struct timespec *_Nullable " timeout ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR semtimedop (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +Each semaphore in a System\ V semaphore set +has the following associated values: +.P +.in +4n +.EX +unsigned short semval; /* semaphore value */ +unsigned short semzcnt; /* # waiting for zero */ +unsigned short semncnt; /* # waiting for increase */ +pid_t sempid; /* PID of process that last + modified the semaphore value */ +.EE +.in +.P +.BR semop () +performs operations on selected semaphores in the set indicated by +.IR semid . +Each of the +.I nsops +elements in the array pointed to by +.I sops +is a structure that +specifies an operation to be performed on a single semaphore. +The elements of this structure are of type +.IR "struct sembuf" , +containing the following members: +.P +.in +4n +.EX +unsigned short sem_num; /* semaphore number */ +short sem_op; /* semaphore operation */ +short sem_flg; /* operation flags */ +.EE +.in +.P +Flags recognized in +.I sem_flg +are +.B IPC_NOWAIT +and +.BR SEM_UNDO . +If an operation specifies +.BR SEM_UNDO , +it will be automatically undone when the process terminates. +.P +The set of operations contained in +.I sops +is performed in +.IR "array order" , +and +.IR atomically , +that is, the operations are performed either as a complete unit, +or not at all. +The behavior of the system call if not all operations can be +performed immediately depends on the presence of the +.B IPC_NOWAIT +flag in the individual +.I sem_flg +fields, as noted below. +.P +Each operation is performed on the +.IR sem_num \-th +semaphore of the semaphore set, where the first semaphore of the set +is numbered 0. +There are three types of operation, distinguished by the value of +.IR sem_op . +.P +If +.I sem_op +is a positive integer, the operation adds this value to +the semaphore value +.RI ( semval ). +Furthermore, if +.B SEM_UNDO +is specified for this operation, the system subtracts the value +.I sem_op +from the semaphore adjustment +.RI ( semadj ) +value for this semaphore. +This operation can always proceed\[em]it never forces a thread to wait. +The calling process must have alter permission on the semaphore set. +.P +If +.I sem_op +is zero, the process must have read permission on the semaphore +set. +This is a "wait-for-zero" operation: if +.I semval +is zero, the operation can immediately proceed. +Otherwise, if +.B IPC_NOWAIT +is specified in +.IR sem_flg , +.BR semop () +fails with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +Otherwise, +.I semzcnt +(the count of threads waiting until this semaphore's value becomes zero) +is incremented by one and the thread sleeps until +one of the following occurs: +.IP \[bu] 3 +.I semval +becomes 0, at which time the value of +.I semzcnt +is decremented. +.IP \[bu] +The semaphore set +is removed: +.BR semop () +fails, with +.I errno +set to +.BR EIDRM . +.IP \[bu] +The calling thread catches a signal: +the value of +.I semzcnt +is decremented and +.BR semop () +fails, with +.I errno +set to +.BR EINTR . +.P +If +.I sem_op +is less than zero, the process must have alter permission on the +semaphore set. +If +.I semval +is greater than or equal to the absolute value of +.IR sem_op , +the operation can proceed immediately: +the absolute value of +.I sem_op +is subtracted from +.IR semval , +and, if +.B SEM_UNDO +is specified for this operation, the system adds the absolute value of +.I sem_op +to the semaphore adjustment +.RI ( semadj ) +value for this semaphore. +If the absolute value of +.I sem_op +is greater than +.IR semval , +and +.B IPC_NOWAIT +is specified in +.IR sem_flg , +.BR semop () +fails, with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +Otherwise, +.I semncnt +(the counter of threads waiting for this semaphore's value to increase) +is incremented by one and the thread sleeps until +one of the following occurs: +.IP \[bu] 3 +.I semval +becomes greater than or equal to the absolute value of +.IR sem_op : +the operation now proceeds, as described above. +.IP \[bu] +The semaphore set is removed from the system: +.BR semop () +fails, with +.I errno +set to +.BR EIDRM . +.IP \[bu] +The calling thread catches a signal: +the value of +.I semncnt +is decremented and +.BR semop () +fails, with +.I errno +set to +.BR EINTR . +.P +On successful completion, the +.I sempid +value for each semaphore specified in the array pointed to by +.I sops +is set to the caller's process ID. +In addition, the +.I sem_otime +.\" and +.\" .I sem_ctime +is set to the current time. +.SS semtimedop() +.BR semtimedop () +behaves identically to +.BR semop () +except that in those cases where the calling thread would sleep, +the duration of that sleep is limited by the amount of elapsed +time specified by the +.I timespec +structure whose address is passed in the +.I timeout +argument. +(This sleep interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the interval +may overrun by a small amount.) +If the specified time limit has been reached, +.BR semtimedop () +fails with +.I errno +set to +.B EAGAIN +(and none of the operations in +.I sops +is performed). +If the +.I timeout +argument is NULL, +then +.BR semtimedop () +behaves exactly like +.BR semop (). +.P +Note that if +.BR semtimedop () +is interrupted by a signal, causing the call to fail with the error +.BR EINTR , +the contents of +.I timeout +are left unchanged. +.SH RETURN VALUE +On success, +.BR semop () +and +.BR semtimedop () +return 0. +On failure, they return \-1, and set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B E2BIG +The argument +.I nsops +is greater than +.BR SEMOPM , +the maximum number of operations allowed per system +call. +.TP +.B EACCES +The calling process does not have the permissions required +to perform the specified semaphore operations, +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EAGAIN +An operation could not proceed immediately and either +.B IPC_NOWAIT +was specified in +.I sem_flg +or the time limit specified in +.I timeout +expired. +.TP +.B EFAULT +An address specified in either the +.I sops +or the +.I timeout +argument isn't accessible. +.TP +.B EFBIG +For some operation the value of +.I sem_num +is less than 0 or greater than or equal to the number +of semaphores in the set. +.TP +.B EIDRM +The semaphore set was removed. +.TP +.B EINTR +While blocked in this system call, the thread caught a signal; see +.BR signal (7). +.TP +.B EINVAL +The semaphore set doesn't exist, or +.I semid +is less than zero, or +.I nsops +has a nonpositive value. +.TP +.B ENOMEM +The +.I sem_flg +of some operation specified +.B SEM_UNDO +and the system does not have enough memory to allocate the undo +structure. +.TP +.B ERANGE +For some operation +.I sem_op+semval +is greater than +.BR SEMVMX , +the implementation dependent maximum value for +.IR semval . +.SH STANDARDS +POSIX.1-2008. +.SH VERSIONS +Linux 2.5.52 (backported into Linux 2.4.22), +glibc 2.3.3. +POSIX.1-2001, SVr4. +.\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC. +.SH NOTES +The +.I sem_undo +structures of a process aren't inherited by the child produced by +.BR fork (2), +but they are inherited across an +.BR execve (2) +system call. +.P +.BR semop () +is never automatically restarted after being interrupted by a signal handler, +regardless of the setting of the +.B SA_RESTART +flag when establishing a signal handler. +.P +A semaphore adjustment +.RI ( semadj ) +value is a per-process, per-semaphore integer that is the negated sum +of all operations performed on a semaphore specifying the +.B SEM_UNDO +flag. +Each process has a list of +.I semadj +values\[em]one value for each semaphore on which it has operated using +.BR SEM_UNDO . +When a process terminates, each of its per-semaphore +.I semadj +values is added to the corresponding semaphore, +thus undoing the effect of that process's operations on the semaphore +(but see BUGS below). +When a semaphore's value is directly set using the +.B SETVAL +or +.B SETALL +request to +.BR semctl (2), +the corresponding +.I semadj +values in all processes are cleared. +The +.BR clone (2) +.B CLONE_SYSVSEM +flag allows more than one process to share a +.I semadj +list; see +.BR clone (2) +for details. +.P +The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values +for a semaphore can all be retrieved using appropriate +.BR semctl (2) +calls. +.SS Semaphore limits +The following limits on semaphore set resources affect the +.BR semop () +call: +.TP +.B SEMOPM +Maximum number of operations allowed for one +.BR semop () +call. +Before Linux 3.19, +.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4 +the default value for this limit was 32. +Since Linux 3.19, the default value is 500. +On Linux, this limit can be read and modified via the third field of +.IR /proc/sys/kernel/sem . +.\" This /proc file is not available in Linux 2.2 and earlier -- MTK +.IR Note : +this limit should not be raised above 1000, +.\" See comment in Linux 3.19 source file include/uapi/linux/sem.h +because of the risk of that +.BR semop () +fails due to kernel memory fragmentation when allocating memory to copy the +.I sops +array. +.TP +.B SEMVMX +Maximum allowable value for +.IR semval : +implementation dependent (32767). +.P +The implementation has no intrinsic limits for +the adjust on exit maximum value +.RB ( SEMAEM ), +the system wide maximum number of undo structures +.RB ( SEMMNU ) +and the per-process maximum number of undo entries system parameters. +.SH BUGS +When a process terminates, its set of associated +.I semadj +structures is used to undo the effect of all of the +semaphore operations it performed with the +.B SEM_UNDO +flag. +This raises a difficulty: if one (or more) of these semaphore adjustments +would result in an attempt to decrease a semaphore's value below zero, +what should an implementation do? +One possible approach would be to block until all the semaphore +adjustments could be performed. +This is however undesirable since it could force process termination to +block for arbitrarily long periods. +Another possibility is that such semaphore adjustments could be ignored +altogether (somewhat analogously to failing when +.B IPC_NOWAIT +is specified for a semaphore operation). +Linux adopts a third approach: decreasing the semaphore value +as far as possible (i.e., to zero) and allowing process +termination to proceed immediately. +.P +In Linux 2.6.x, x <= 10, there is a bug that in some circumstances +prevents a thread that is waiting for a semaphore value to become +zero from being woken up when the value does actually become zero. +This bug is fixed in Linux 2.6.11. +.\" The bug report: +.\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2 +.\" the fix: +.\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2 +.SH EXAMPLES +The following code segment uses +.BR semop () +to atomically wait for the value of semaphore 0 to become zero, +and then increment the semaphore value by one. +.P +.in +4n +.EX +struct sembuf sops[2]; +int semid; +\& +/* Code to set \fIsemid\fP omitted */ +\& +sops[0].sem_num = 0; /* Operate on semaphore 0 */ +sops[0].sem_op = 0; /* Wait for value to equal 0 */ +sops[0].sem_flg = 0; +\& +sops[1].sem_num = 0; /* Operate on semaphore 0 */ +sops[1].sem_op = 1; /* Increment value by one */ +sops[1].sem_flg = 0; +\& +if (semop(semid, sops, 2) == \-1) { + perror("semop"); + exit(EXIT_FAILURE); +} +.EE +.in +.P +A further example of the use of +.BR semop () +can be found in +.BR shmop (2). +.SH SEE ALSO +.BR clone (2), +.BR semctl (2), +.BR semget (2), +.BR sigaction (2), +.BR capabilities (7), +.BR sem_overview (7), +.BR sysvipc (7), +.BR time (7) diff --git a/man/man2/semtimedop.2 b/man/man2/semtimedop.2 new file mode 100644 index 0000000..8a40618 --- /dev/null +++ b/man/man2/semtimedop.2 @@ -0,0 +1 @@ +.so man2/semop.2 diff --git a/man/man2/send.2 b/man/man2/send.2 new file mode 100644 index 0000000..99c4a2d --- /dev/null +++ b/man/man2/send.2 @@ -0,0 +1,506 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified Oct 1998 by Andi Kleen +.\" Modified Oct 2003 by aeb +.\" Modified 2004-07-01 by mtk +.\" +.TH send 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +send, sendto, sendmsg \- send a message on a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t send(int " sockfd ", const void " buf [. len "], size_t " len \ +", int " flags ); +.BI "ssize_t sendto(int " sockfd ", const void " buf [. len "], size_t " len \ +", int " flags , +.BI " const struct sockaddr *" dest_addr ", socklen_t " addrlen ); +.BI "ssize_t sendmsg(int " sockfd ", const struct msghdr *" msg \ +", int " flags ); +.fi +.SH DESCRIPTION +The system calls +.BR send (), +.BR sendto (), +and +.BR sendmsg () +are used to transmit a message to another socket. +.P +The +.BR send () +call may be used only when the socket is in a +.I connected +state (so that the intended recipient is known). +The only difference between +.BR send () +and +.BR write (2) +is the presence of +.IR flags . +With a zero +.I flags +argument, +.BR send () +is equivalent to +.BR write (2). +Also, the following call +.P +.in +4n +.EX +send(sockfd, buf, len, flags); +.EE +.in +.P +is equivalent to +.P +.in +4n +.EX +sendto(sockfd, buf, len, flags, NULL, 0); +.EE +.in +.P +The argument +.I sockfd +is the file descriptor of the sending socket. +.P +If +.BR sendto () +is used on a connection-mode +.RB ( SOCK_STREAM , +.BR SOCK_SEQPACKET ) +socket, the arguments +.I dest_addr +and +.I addrlen +are ignored (and the error +.B EISCONN +may be returned when they are +not NULL and 0), and the error +.B ENOTCONN +is returned when the socket was not actually connected. +Otherwise, the address of the target is given by +.I dest_addr +with +.I addrlen +specifying its size. +For +.BR sendmsg (), +the address of the target is given by +.IR msg.msg_name , +with +.I msg.msg_namelen +specifying its size. +.P +For +.BR send () +and +.BR sendto (), +the message is found in +.I buf +and has length +.IR len . +For +.BR sendmsg (), +the message is pointed to by the elements of the array +.IR msg.msg_iov . +The +.BR sendmsg () +call also allows sending ancillary data (also known as control information). +.P +If the message is too long to pass atomically through the +underlying protocol, the error +.B EMSGSIZE +is returned, and the message is not transmitted. +.P +No indication of failure to deliver is implicit in a +.BR send (). +Locally detected errors are indicated by a return value of \-1. +.P +When the message does not fit into the send buffer of the socket, +.BR send () +normally blocks, unless the socket has been placed in nonblocking I/O +mode. +In nonblocking mode it would fail with the error +.B EAGAIN +or +.B EWOULDBLOCK +in this case. +The +.BR select (2) +call may be used to determine when it is possible to send more data. +.SS The flags argument +The +.I flags +argument is the bitwise OR +of zero or more of the following flags. +.\" FIXME . ? document MSG_PROXY (which went away in Linux 2.3.15) +.TP +.BR MSG_CONFIRM " (since Linux 2.3.15)" +Tell the link layer that forward progress happened: you got a successful +reply from the other side. +If the link layer doesn't get this +it will regularly reprobe the neighbor (e.g., via a unicast ARP). +Valid only on +.B SOCK_DGRAM +and +.B SOCK_RAW +sockets and currently implemented only for IPv4 and IPv6. +See +.BR arp (7) +for details. +.TP +.B MSG_DONTROUTE +Don't use a gateway to send out the packet, send to hosts only on +directly connected networks. +This is usually used only +by diagnostic or routing programs. +This is defined only for protocol +families that route; packet sockets don't. +.TP +.BR MSG_DONTWAIT " (since Linux 2.2)" +Enables nonblocking operation; if the operation would block, +.B EAGAIN +or +.B EWOULDBLOCK +is returned. +This provides similar behavior to setting the +.B O_NONBLOCK +flag (via the +.BR fcntl (2) +.B F_SETFL +operation), but differs in that +.B MSG_DONTWAIT +is a per-call option, whereas +.B O_NONBLOCK +is a setting on the open file description (see +.BR open (2)), +which will affect all threads in the calling process +as well as other processes that hold file descriptors +referring to the same open file description. +.TP +.BR MSG_EOR " (since Linux 2.2)" +Terminates a record (when this notion is supported, as for sockets of type +.BR SOCK_SEQPACKET ). +.TP +.BR MSG_MORE " (since Linux 2.4.4)" +The caller has more data to send. +This flag is used with TCP sockets to obtain the same effect +as the +.B TCP_CORK +socket option (see +.BR tcp (7)), +with the difference that this flag can be set on a per-call basis. +.IP +Since Linux 2.6, this flag is also supported for UDP sockets, and informs +the kernel to package all of the data sent in calls with this flag set +into a single datagram which is transmitted only when a call is performed +that does not specify this flag. +(See also the +.B UDP_CORK +socket option described in +.BR udp (7).) +.TP +.BR MSG_NOSIGNAL " (since Linux 2.2)" +Don't generate a +.B SIGPIPE +signal if the peer on a stream-oriented socket has closed the connection. +The +.B EPIPE +error is still returned. +This provides similar behavior to using +.BR sigaction (2) +to ignore +.BR SIGPIPE , +but, whereas +.B MSG_NOSIGNAL +is a per-call feature, +ignoring +.B SIGPIPE +sets a process attribute that affects all threads in the process. +.TP +.B MSG_OOB +Sends +.I out-of-band +data on sockets that support this notion (e.g., of type +.BR SOCK_STREAM ); +the underlying protocol must also support +.I out-of-band +data. +.TP +.BR MSG_FASTOPEN " (since Linux 3.7)" +Attempts TCP Fast Open (RFC7413) and sends data in the SYN like a +combination of +.BR connect (2) +and +.BR write (2), +by performing an implicit +.BR connect (2) +operation. +It blocks until the data is buffered and the handshake has completed. +For a non-blocking socket, +it returns the number of bytes buffered and sent in the SYN packet. +If the cookie is not available locally, +it returns +.BR EINPROGRESS , +and sends a SYN with a Fast Open cookie request automatically. +The caller needs to write the data again when the socket is connected. +On errors, +it sets the same +.I errno +as +.BR connect (2) +if the handshake fails. +This flag requires enabling TCP Fast Open client support on sysctl +.IR net.ipv4.tcp_fastopen . +.IP +Refer to +.B TCP_FASTOPEN_CONNECT +socket option in +.BR tcp (7) +for an alternative approach. +.SS sendmsg() +The definition of the +.I msghdr +structure employed by +.BR sendmsg () +is as follows: +.P +.in +4n +.EX +struct msghdr { + void *msg_name; /* Optional address */ + socklen_t msg_namelen; /* Size of address */ + struct iovec *msg_iov; /* Scatter/gather array */ + size_t msg_iovlen; /* # elements in msg_iov */ + void *msg_control; /* Ancillary data, see below */ + size_t msg_controllen; /* Ancillary data buffer len */ + int msg_flags; /* Flags (unused) */ +}; +.EE +.in +.P +The +.I msg_name +field is used on an unconnected socket to specify the target +address for a datagram. +It points to a buffer containing the address; the +.I msg_namelen +field should be set to the size of the address. +For a connected socket, these fields should be specified as NULL and 0, +respectively. +.P +The +.I msg_iov +and +.I msg_iovlen +fields specify scatter-gather locations, as for +.BR writev (2). +.P +You may send control information (ancillary data) using the +.I msg_control +and +.I msg_controllen +members. +The maximum control buffer length the kernel can process is limited +per socket by the value in +.IR /proc/sys/net/core/optmem_max ; +see +.BR socket (7). +For further information on the use of ancillary data in various +socket domains, see +.BR unix (7) +and +.BR ip (7). +.P +The +.I msg_flags +field is ignored. +.\" Still to be documented: +.\" Send file descriptors and user credentials using the +.\" msg_control* fields. +.SH RETURN VALUE +On success, these calls return the number of bytes sent. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +These are some standard errors generated by the socket layer. +Additional errors +may be generated and returned from the underlying protocol modules; +see their respective manual pages. +.TP +.B EACCES +(For UNIX domain sockets, which are identified by pathname) +Write permission is denied on the destination socket file, +or search permission is denied for one of the directories +the path prefix. +(See +.BR path_resolution (7).) +.IP +(For UDP sockets) An attempt was made to send to a +network/broadcast address as though it was a unicast address. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.\" Actually EAGAIN on Linux +The socket is marked nonblocking and the requested operation +would block. +POSIX.1-2001 allows either error to be returned for this case, +and does not require these constants to have the same value, +so a portable application should check for both possibilities. +.TP +.B EAGAIN +(Internet domain datagram sockets) +The socket referred to by +.I sockfd +had not previously been bound to an address and, +upon attempting to bind it to an ephemeral port, +it was determined that all port numbers in the ephemeral port range +are currently in use. +See the discussion of +.I /proc/sys/net/ipv4/ip_local_port_range +in +.BR ip (7). +.TP +.B EALREADY +Another Fast Open is in progress. +.TP +.B EBADF +.I sockfd +is not a valid open file descriptor. +.TP +.B ECONNRESET +Connection reset by peer. +.TP +.B EDESTADDRREQ +The socket is not connection-mode, and no peer address is set. +.TP +.B EFAULT +An invalid user space address was specified for an argument. +.TP +.B EINTR +A signal occurred before any data was transmitted; see +.BR signal (7). +.TP +.B EINVAL +Invalid argument passed. +.TP +.B EISCONN +The connection-mode socket was connected already but a +recipient was specified. +(Now either this error is returned, or the recipient specification +is ignored.) +.TP +.B EMSGSIZE +The socket type +.\" (e.g., SOCK_DGRAM ) +requires that message be sent atomically, and the size +of the message to be sent made this impossible. +.TP +.B ENOBUFS +The output queue for a network interface was full. +This generally indicates that the interface has stopped sending, +but may be caused by transient congestion. +(Normally, this does not occur in Linux. +Packets are just silently dropped +when a device queue overflows.) +.TP +.B ENOMEM +No memory available. +.TP +.B ENOTCONN +The socket is not connected, and no target has been given. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.TP +.B EOPNOTSUPP +Some bit in the +.I flags +argument is inappropriate for the socket type. +.TP +.B EPIPE +The local end has been shut down on a connection oriented socket. +In this case, the process +will also receive a +.B SIGPIPE +unless +.B MSG_NOSIGNAL +is set. +.SH VERSIONS +According to POSIX.1-2001, the +.I msg_controllen +field of the +.I msghdr +structure should be typed as +.IR socklen_t , +and the +.I msg_iovlen +field should be typed as +.IR int , +but glibc currently types both as +.IR size_t . +.\" glibc bug for msg_controllen raised 12 Mar 2006 +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=2448 +.\" The problem is an underlying kernel issue: the size of the +.\" __kernel_size_t type used to type these fields varies +.\" across architectures, but socklen_t is always 32 bits, +.\" as (at least with GCC) is int. +.SH STANDARDS +POSIX.1-2008. +.P +.B MSG_CONFIRM +is a Linux extension. +.SH HISTORY +4.4BSD, SVr4, POSIX.1-2001. +(first appeared in 4.2BSD). +.P +POSIX.1-2001 describes only the +.B MSG_OOB +and +.B MSG_EOR +flags. +POSIX.1-2008 adds a specification of +.BR MSG_NOSIGNAL . +.SH NOTES +See +.BR sendmmsg (2) +for information about a Linux-specific system call +that can be used to transmit multiple datagrams in a single call. +.SH BUGS +Linux may return +.B EPIPE +instead of +.BR ENOTCONN . +.SH EXAMPLES +An example of the use of +.BR sendto () +is shown in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR fcntl (2), +.BR getsockopt (2), +.BR recv (2), +.BR select (2), +.BR sendfile (2), +.BR sendmmsg (2), +.BR shutdown (2), +.BR socket (2), +.BR write (2), +.BR cmsg (3), +.BR ip (7), +.BR ipv6 (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) diff --git a/man/man2/sendfile.2 b/man/man2/sendfile.2 new file mode 100644 index 0000000..cc691fc --- /dev/null +++ b/man/man2/sendfile.2 @@ -0,0 +1,245 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1998 Pawel Krawczyk. +.\" +.\" $Id: sendfile.2,v 1.5 1999/05/18 11:54:11 freitag Exp $ +.\" 2000-11-19 bert hubert : in_fd cannot be socket +.\" +.\" 2004-12-17, mtk +.\" updated description of in_fd and out_fd for 2.6 +.\" Various wording and formatting changes +.\" +.\" 2005-03-31 Martin Pool mmap() improvements +.\" +.TH sendfile 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sendfile \- transfer data between file descriptors +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", \ +off_t *_Nullable " offset , +.BI " size_t" " count" ); +.\" The below is too ugly. Comments about glibc versions belong +.\" in the notes, not in the header. +.\" +.\" .B #include +.\" .B #if (__GLIBC__==2 && __GLIBC_MINOR__>=1) || __GLIBC__>2 +.\" .B #include +.\" #else +.\" .B #include +.\" .B /* No system prototype before glibc 2.1. */ +.\" .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", off_t *" \ +.\" offset ", size_t" " count" ) +.\" .B #endif +.\" +.fi +.SH DESCRIPTION +.BR sendfile () +copies data between one file descriptor and another. +Because this copying is done within the kernel, +.BR sendfile () +is more efficient than the combination of +.BR read (2) +and +.BR write (2), +which would require transferring data to and from user space. +.P +.I in_fd +should be a file descriptor opened for reading and +.I out_fd +should be a descriptor opened for writing. +.P +If +.I offset +is not NULL, then it points +to a variable holding the file offset from which +.BR sendfile () +will start reading data from +.IR in_fd . +When +.BR sendfile () +returns, this variable +will be set to the offset of the byte following the last byte that was read. +If +.I offset +is not NULL, then +.BR sendfile () +does not modify the file offset of +.IR in_fd ; +otherwise the file offset is adjusted to reflect +the number of bytes read from +.IR in_fd . +.P +If +.I offset +is NULL, then data will be read from +.I in_fd +starting at the file offset, +and the file offset will be updated by the call. +.P +.I count +is the number of bytes to copy between the file descriptors. +.P +The +.I in_fd +argument must correspond to a file which supports +.BR mmap (2)-like +operations +(i.e., it cannot be a socket). +Except since Linux 5.12 +.\" commit b964bf53e540262f2d12672b3cca10842c0172e7 +and if +.I out_fd +is a pipe, in which case +.BR sendfile () +desugars to a +.BR splice (2) +and its restrictions apply. +.P +Before Linux 2.6.33, +.I out_fd +must refer to a socket. +Since Linux 2.6.33 it can be any file. +If it's seekable, then +.BR sendfile () +changes the file offset appropriately. +.SH RETURN VALUE +If the transfer was successful, the number of bytes written to +.I out_fd +is returned. +Note that a successful call to +.BR sendfile () +may write fewer bytes than requested; +the caller should be prepared to retry the call if there were unsent bytes. +See also NOTES. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +Nonblocking I/O has been selected using +.B O_NONBLOCK +and the write would block. +.TP +.B EBADF +The input file was not opened for reading or the output file +was not opened for writing. +.TP +.B EFAULT +Bad address. +.TP +.B EINVAL +Descriptor is not valid or locked, or an +.BR mmap (2)-like +operation is not available for +.IR in_fd , +or +.I count +is negative. +.TP +.B EINVAL +.I out_fd +has the +.B O_APPEND +flag set. +This is not currently supported by +.BR sendfile (). +.TP +.B EIO +Unspecified error while reading from +.IR in_fd . +.TP +.B ENOMEM +Insufficient memory to read from +.IR in_fd . +.TP +.B EOVERFLOW +.I count +is too large, the operation would result in exceeding the maximum size of either +the input file or the output file. +.TP +.B ESPIPE +.I offset +is not NULL but the input file is not seekable. +.SH VERSIONS +Other UNIX systems implement +.BR sendfile () +with different semantics and prototypes. +It should not be used in portable programs. +.SH STANDARDS +None. +.SH HISTORY +Linux 2.2, +glibc 2.1. +.P +In Linux 2.4 and earlier, +.I out_fd +could also refer to a regular file; +this possibility went away in the Linux 2.6.x kernel series, +but was restored in Linux 2.6.33. +.P +The original Linux +.BR sendfile () +system call was not designed to handle large file offsets. +Consequently, Linux 2.4 added +.BR sendfile64 (), +with a wider type for the +.I offset +argument. +The glibc +.BR sendfile () +wrapper function transparently deals with the kernel differences. +.SH NOTES +.BR sendfile () +will transfer at most 0x7ffff000 (2,147,479,552) bytes, +returning the number of bytes actually transferred. +.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 +(This is true on both 32-bit and 64-bit systems.) +.P +If you plan to use +.BR sendfile () +for sending files to a TCP socket, but need +to send some header data in front of the file contents, you will find +it useful to employ the +.B TCP_CORK +option, described in +.BR tcp (7), +to minimize the number of packets and to tune performance. +.P +Applications may wish to fall back to +.BR read (2) +and +.BR write (2) +in the case where +.BR sendfile () +fails with +.B EINVAL +or +.BR ENOSYS . +.P +If +.I out_fd +refers to a socket or pipe with zero-copy support, callers must ensure the +transferred portions of the file referred to by +.I in_fd +remain unmodified until the reader on the other end of +.I out_fd +has consumed the transferred data. +.P +The Linux-specific +.BR splice (2) +call supports transferring data between arbitrary file descriptors +provided one (or both) of them is a pipe. +.SH SEE ALSO +.BR copy_file_range (2), +.BR mmap (2), +.BR open (2), +.BR socket (2), +.BR splice (2) diff --git a/man/man2/sendfile64.2 b/man/man2/sendfile64.2 new file mode 100644 index 0000000..888077b --- /dev/null +++ b/man/man2/sendfile64.2 @@ -0,0 +1 @@ +.so man2/sendfile.2 diff --git a/man/man2/sendmmsg.2 b/man/man2/sendmmsg.2 new file mode 100644 index 0000000..5e06151 --- /dev/null +++ b/man/man2/sendmmsg.2 @@ -0,0 +1,232 @@ +.\" Copyright (c) 2012 by Michael Kerrisk +.\" with some material from a draft by +.\" Stephan Mueller +.\" in turn based on Andi Kleen's recvmmsg.2 page. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sendmmsg 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sendmmsg \- send multiple messages on a socket +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int sendmmsg(int " sockfd ", struct mmsghdr *" msgvec \ +", unsigned int " vlen "," +.BI " int " flags ");" +.fi +.SH DESCRIPTION +The +.BR sendmmsg () +system call is an extension of +.BR sendmsg (2) +that allows the caller to transmit multiple messages on a socket +using a single system call. +(This has performance benefits for some applications.) +.\" See commit 228e548e602061b08ee8e8966f567c12aa079682 +.P +The +.I sockfd +argument is the file descriptor of the socket +on which data is to be transmitted. +.P +The +.I msgvec +argument is a pointer to an array of +.I mmsghdr +structures. +The size of this array is specified in +.IR vlen . +.P +The +.I mmsghdr +structure is defined in +.I +as: +.P +.in +4n +.EX +struct mmsghdr { + struct msghdr msg_hdr; /* Message header */ + unsigned int msg_len; /* Number of bytes transmitted */ +}; +.EE +.in +.P +The +.I msg_hdr +field is a +.I msghdr +structure, as described in +.BR sendmsg (2). +The +.I msg_len +field is used to return the number of bytes sent from the message in +.I msg_hdr +(i.e., the same as the return value from a single +.BR sendmsg (2) +call). +.P +The +.I flags +argument contains flags ORed together. +The flags are the same as for +.BR sendmsg (2). +.P +A blocking +.BR sendmmsg () +call blocks until +.I vlen +messages have been sent. +A nonblocking call sends as many messages as possible +(up to the limit specified by +.IR vlen ) +and returns immediately. +.P +On return from +.BR sendmmsg (), +the +.I msg_len +fields of successive elements of +.I msgvec +are updated to contain the number of bytes transmitted from the corresponding +.IR msg_hdr . +The return value of the call indicates the number of elements of +.I msgvec +that have been updated. +.SH RETURN VALUE +On success, +.BR sendmmsg () +returns the number of messages sent from +.IR msgvec ; +if this is less than +.IR vlen , +the caller can retry with a further +.BR sendmmsg () +call to send the remaining messages. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Errors are as for +.BR sendmsg (2). +An error is returned only if no datagrams could be sent. +See also BUGS. +.\" commit 728ffb86f10873aaf4abd26dde691ee40ae731fe +.\" ... only return an error if no datagrams could be sent. +.\" If less than the requested number of messages were sent, the application +.\" must retry starting at the first failed one and if the problem is +.\" persistent the error will be returned. +.\" +.\" This matches the behavior of other syscalls like read/write - it +.\" is not an error if less than the requested number of elements are sent. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 3.0, +glibc 2.14. +.SH NOTES +The value specified in +.I vlen +is capped to +.B UIO_MAXIOV +(1024). +.\" commit 98382f419f32d2c12d021943b87dea555677144b +.\" net: Cap number of elements for sendmmsg +.\" +.\" To limit the amount of time we can spend in sendmmsg, cap the +.\" number of elements to UIO_MAXIOV (currently 1024). +.\" +.\" For error handling an application using sendmmsg needs to retry at +.\" the first unsent message, so capping is simpler and requires less +.\" application logic than returning EINVAL. +.SH BUGS +If an error occurs after at least one message has been sent, +the call succeeds, and returns the number of messages sent. +The error code is lost. +The caller can retry the transmission, +starting at the first failed message, but there is no guarantee that, +if an error is returned, it will be the same as the one that was lost +on the previous call. +.SH EXAMPLES +The example below uses +.BR sendmmsg () +to send +.I onetwo +and +.I three +in two distinct UDP datagrams using one system call. +The contents of the first datagram originates from a pair of buffers. +.P +.\" SRC BEGIN (sendmmsg.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +\& +int +main(void) +{ + int retval; + int sockfd; + struct iovec msg1[2], msg2; + struct mmsghdr msg[2]; + struct sockaddr_in addr; +\& + sockfd = socket(AF_INET, SOCK_DGRAM, 0); + if (sockfd == \-1) { + perror("socket()"); + exit(EXIT_FAILURE); + } +\& + addr.sin_family = AF_INET; + addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK); + addr.sin_port = htons(1234); + if (connect(sockfd, (struct sockaddr *) &addr, sizeof(addr)) == \-1) { + perror("connect()"); + exit(EXIT_FAILURE); + } +\& + memset(msg1, 0, sizeof(msg1)); + msg1[0].iov_base = "one"; + msg1[0].iov_len = 3; + msg1[1].iov_base = "two"; + msg1[1].iov_len = 3; +\& + memset(&msg2, 0, sizeof(msg2)); + msg2.iov_base = "three"; + msg2.iov_len = 5; +\& + memset(msg, 0, sizeof(msg)); + msg[0].msg_hdr.msg_iov = msg1; + msg[0].msg_hdr.msg_iovlen = 2; +\& + msg[1].msg_hdr.msg_iov = &msg2; + msg[1].msg_hdr.msg_iovlen = 1; +\& + retval = sendmmsg(sockfd, msg, 2, 0); + if (retval == \-1) + perror("sendmmsg()"); + else + printf("%d messages sent\en", retval); +\& + exit(0); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR recvmmsg (2), +.BR sendmsg (2), +.BR socket (2), +.BR socket (7) diff --git a/man/man2/sendmsg.2 b/man/man2/sendmsg.2 new file mode 100644 index 0000000..9a61b33 --- /dev/null +++ b/man/man2/sendmsg.2 @@ -0,0 +1 @@ +.so man2/send.2 diff --git a/man/man2/sendto.2 b/man/man2/sendto.2 new file mode 100644 index 0000000..9a61b33 --- /dev/null +++ b/man/man2/sendto.2 @@ -0,0 +1 @@ +.so man2/send.2 diff --git a/man/man2/set_mempolicy.2 b/man/man2/set_mempolicy.2 new file mode 100644 index 0000000..5223d1b --- /dev/null +++ b/man/man2/set_mempolicy.2 @@ -0,0 +1,343 @@ +.\" SPDX-License-Identifier: Linux-man-pages-copyleft-var +.\" +.\" Copyright 2003,2004 Andi Kleen, SuSE Labs. +.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard +.\" +.\" 2006-02-03, mtk, substantial wording changes and other improvements +.\" 2007-08-27, Lee Schermerhorn +.\" more precise specification of behavior. +.\" +.TH set_mempolicy 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +set_mempolicy \- set default NUMA memory policy for a thread and its children +.SH LIBRARY +NUMA (Non-Uniform Memory Access) policy library +.RI ( libnuma ", " \-lnuma ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "long set_mempolicy(int " mode ", const unsigned long *" nodemask , +.BI " unsigned long " maxnode ); +.fi +.SH DESCRIPTION +.BR set_mempolicy () +sets the NUMA memory policy of the calling thread, +which consists of a policy mode and zero or more nodes, +to the values specified by the +.IR mode , +.IR nodemask , +and +.I maxnode +arguments. +.P +A NUMA machine has different +memory controllers with different distances to specific CPUs. +The memory policy defines from which node memory is allocated for +the thread. +.P +This system call defines the default policy for the thread. +The thread policy governs allocation of pages in the process's +address space outside of memory ranges +controlled by a more specific policy set by +.BR mbind (2). +The thread default policy also controls allocation of any pages for +memory-mapped files mapped using the +.BR mmap (2) +call with the +.B MAP_PRIVATE +flag and that are only read (loaded) from by the thread +and of memory-mapped files mapped using the +.BR mmap (2) +call with the +.B MAP_SHARED +flag, regardless of the access type. +The policy is applied only when a new page is allocated +for the thread. +For anonymous memory this is when the page is first +touched by the thread. +.P +The +.I mode +argument must specify one of +.BR MPOL_DEFAULT , +.BR MPOL_BIND , +.BR MPOL_INTERLEAVE , +.BR MPOL_WEIGHTED_INTERLEAVE , +.BR MPOL_PREFERRED , +or +.B MPOL_LOCAL +(which are described in detail below). +All modes except +.B MPOL_DEFAULT +require the caller to specify the node or nodes to which the mode applies, +via the +.I nodemask +argument. +.P +The +.I mode +argument may also include an optional +.IR "mode flag" . +The supported +.I "mode flags" +are: +.TP +.BR MPOL_F_NUMA_BALANCING " (since Linux 5.12)" +.\" commit bda420b985054a3badafef23807c4b4fa38a3dff +When +.I mode +is +.BR MPOL_BIND , +enable the kernel NUMA balancing for the task if it is supported by the kernel. +If the flag isn't supported by the kernel, or is used with +.I mode +other than +.BR MPOL_BIND , +\-1 is returned and +.I errno +is set to +.BR EINVAL . +.TP +.BR MPOL_F_RELATIVE_NODES " (since Linux 2.6.26)" +A nonempty +.I nodemask +specifies node IDs that are relative to the +set of node IDs allowed by the process's current cpuset. +.TP +.BR MPOL_F_STATIC_NODES " (since Linux 2.6.26)" +A nonempty +.I nodemask +specifies physical node IDs. +Linux will not remap the +.I nodemask +when the process moves to a different cpuset context, +nor when the set of nodes allowed by the process's +current cpuset context changes. +.P +.I nodemask +points to a bit mask of node IDs that contains up to +.I maxnode +bits. +The bit mask size is rounded to the next multiple of +.IR "sizeof(unsigned long)" , +but the kernel will use bits only up to +.IR maxnode . +A NULL value of +.I nodemask +or a +.I maxnode +value of zero specifies the empty set of nodes. +If the value of +.I maxnode +is zero, +the +.I nodemask +argument is ignored. +.P +Where a +.I nodemask +is required, it must contain at least one node that is on-line, +allowed by the process's current cpuset context, +(unless the +.B MPOL_F_STATIC_NODES +mode flag is specified), +and contains memory. +If the +.B MPOL_F_STATIC_NODES +is set in +.I mode +and a required +.I nodemask +contains no nodes that are allowed by the process's current cpuset context, +the memory policy reverts to +.IR "local allocation" . +This effectively overrides the specified policy until the process's +cpuset context includes one or more of the nodes specified by +.IR nodemask . +.P +The +.I mode +argument must include one of the following values: +.TP +.B MPOL_DEFAULT +This mode specifies that any nondefault thread memory policy be removed, +so that the memory policy "falls back" to the system default policy. +The system default policy is "local allocation"\[em]that is, +allocate memory on the node of the CPU that triggered the allocation. +.I nodemask +must be specified as NULL. +If the "local node" contains no free memory, the system will +attempt to allocate memory from a "near by" node. +.TP +.B MPOL_BIND +This mode defines a strict policy that restricts memory allocation to the +nodes specified in +.IR nodemask . +If +.I nodemask +specifies more than one node, page allocations will come from +the node with the lowest numeric node ID first, until that node +contains no free memory. +Allocations will then come from the node with the next highest +node ID specified in +.I nodemask +and so forth, until none of the specified nodes contain free memory. +Pages will not be allocated from any node not specified in the +.IR nodemask . +.TP +.B MPOL_INTERLEAVE +This mode interleaves page allocations across the nodes specified in +.I nodemask +in numeric node ID order. +This optimizes for bandwidth instead of latency +by spreading out pages and memory accesses to those pages across +multiple nodes. +However, accesses to a single page will still be limited to +the memory bandwidth of a single node. +.\" NOTE: the following sentence doesn't make sense in the context +.\" of set_mempolicy() -- no memory area specified. +.\" To be effective the memory area should be fairly large, +.\" at least 1 MB or bigger. +.TP +.BR MPOL_WEIGHTED_INTERLEAVE " (since Linux 6.9)" +.\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758 +This mode interleaves page allocations across the nodes specified in +.I nodemask +according to the weights in +.IR /sys/kernel/mm/mempolicy/weighted_interleave . +For example, if bits 0, 2, and 5 are set in +.IR nodemask , +and the contents of +.IR /sys/kernel/mm/mempolicy/weighted_interleave/node0 , +.IR /sys/ .\|.\|. /node2 , +and +.IR /sys/ .\|.\|. /node5 +are 4, 7, and 9, respectively, +then pages in this region will be allocated on nodes 0, 2, and 5 +in a 4:7:9 ratio. +.TP +.B MPOL_PREFERRED +This mode sets the preferred node for allocation. +The kernel will try to allocate pages from this node first +and fall back to "near by" nodes if the preferred node is low on free +memory. +If +.I nodemask +specifies more than one node ID, the first node in the +mask will be selected as the preferred node. +If the +.I nodemask +and +.I maxnode +arguments specify the empty set, then the policy +specifies "local allocation" +(like the system default policy discussed above). +.TP +.BR MPOL_LOCAL " (since Linux 3.8)" +.\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8 +.\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f +This mode specifies "local allocation"; the memory is allocated on +the node of the CPU that triggered the allocation (the "local node"). +The +.I nodemask +and +.I maxnode +arguments must specify the empty set. +If the "local node" is low on free memory, +the kernel will try to allocate memory from other nodes. +The kernel will allocate memory from the "local node" +whenever memory for this node is available. +If the "local node" is not allowed by the process's current cpuset context, +the kernel will try to allocate memory from other nodes. +The kernel will allocate memory from the "local node" whenever +it becomes allowed by the process's current cpuset context. +.P +The thread memory policy is preserved across an +.BR execve (2), +and is inherited by child threads created using +.BR fork (2) +or +.BR clone (2). +.SH RETURN VALUE +On success, +.BR set_mempolicy () +returns 0; +on error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Part of all of the memory range specified by +.I nodemask +and +.I maxnode +points outside your accessible address space. +.TP +.B EINVAL +.I mode +is invalid. +Or, +.I mode +is +.B MPOL_DEFAULT +and +.I nodemask +is nonempty, +or +.I mode +is +.B MPOL_BIND +or +.B MPOL_INTERLEAVE +and +.I nodemask +is empty. +Or, +.I maxnode +specifies more than a page worth of bits. +Or, +.I nodemask +specifies one or more node IDs that are +greater than the maximum supported node ID. +Or, none of the node IDs specified by +.I nodemask +are on-line and allowed by the process's current cpuset context, +or none of the specified nodes contain memory. +Or, the +.I mode +argument specified both +.B MPOL_F_STATIC_NODES +and +.BR MPOL_F_RELATIVE_NODES . +Or, the +.B MPOL_F_NUMA_BALANCING +isn't supported by the kernel, or is used with +.I mode +other than +.BR MPOL_BIND . +.TP +.B ENOMEM +Insufficient kernel memory was available. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.7. +.SH NOTES +Memory policy is not remembered if the page is swapped out. +When such a page is paged back in, it will use the policy of +the thread or memory range that is in effect at the time the +page is allocated. +.P +For information on library support, see +.BR numa (7). +.SH SEE ALSO +.BR get_mempolicy (2), +.BR getcpu (2), +.BR mbind (2), +.BR mmap (2), +.BR numa (3), +.BR cpuset (7), +.BR numa (7), +.BR numactl (8) diff --git a/man/man2/set_robust_list.2 b/man/man2/set_robust_list.2 new file mode 100644 index 0000000..a38aa23 --- /dev/null +++ b/man/man2/set_robust_list.2 @@ -0,0 +1 @@ +.so man2/get_robust_list.2 diff --git a/man/man2/set_thread_area.2 b/man/man2/set_thread_area.2 new file mode 100644 index 0000000..64adf19 --- /dev/null +++ b/man/man2/set_thread_area.2 @@ -0,0 +1,229 @@ +.\" Copyright (C) 2003 Free Software Foundation, Inc. +.\" Copyright (C) 2015 Andrew Lutomirski +.\" Author: Kent Yoder +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH set_thread_area 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +get_thread_area, set_thread_area \- manipulate thread-local storage information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.B #if defined __i386__ || defined __x86_64__ +.BR "# include " " /* Definition of " "struct user_desc" " */" +.P +.BI "int syscall(SYS_get_thread_area, struct user_desc *" u_info ); +.BI "int syscall(SYS_set_thread_area, struct user_desc *" u_info ); +.P +.B #elif defined __m68k__ +.P +.B "int syscall(SYS_get_thread_area);" +.BI "int syscall(SYS_set_thread_area, unsigned long " tp ); +.P +.B #elif defined __mips__ || defined __csky__ +.P +.BI "int syscall(SYS_set_thread_area, unsigned long " addr ); +.P +.B #endif +.fi +.P +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +These calls provide architecture-specific support for a thread-local storage +implementation. +At the moment, +.BR set_thread_area () +is available on m68k, MIPS, C-SKY, and x86 (both 32-bit and 64-bit variants); +.BR get_thread_area () +is available on m68k and x86. +.P +On m68k, MIPS and C-SKY, +.BR set_thread_area () +allows storing an arbitrary pointer (provided in the +.B tp +argument on m68k and in the +.B addr +argument on MIPS and C-SKY) +in the kernel data structure associated with the calling thread; +this pointer can later be retrieved using +.BR get_thread_area () +(see also NOTES +for information regarding obtaining the thread pointer on MIPS). +.P +On x86, Linux dedicates three global descriptor table (GDT) entries for +thread-local storage. +For more information about the GDT, see the +Intel Software Developer's Manual or the AMD Architecture Programming Manual. +.P +Both of these system calls take an argument that is a pointer +to a structure of the following type: +.P +.in +4n +.EX +struct user_desc { + unsigned int entry_number; + unsigned int base_addr; + unsigned int limit; + unsigned int seg_32bit:1; + unsigned int contents:2; + unsigned int read_exec_only:1; + unsigned int limit_in_pages:1; + unsigned int seg_not_present:1; + unsigned int useable:1; +#ifdef __x86_64__ + unsigned int lm:1; +#endif +}; +.EE +.in +.P +.BR get_thread_area () +reads the GDT entry indicated by +.I u_info\->entry_number +and fills in the rest of the fields in +.IR u_info . +.P +.BR set_thread_area () +sets a TLS entry in the GDT. +.P +The TLS array entry set by +.BR set_thread_area () +corresponds to the value of +.I u_info\->entry_number +passed in by the user. +If this value is in bounds, +.BR set_thread_area () +writes the TLS descriptor pointed to by +.I u_info +into the thread's TLS array. +.P +When +.BR set_thread_area () +is passed an +.I entry_number +of \-1, it searches for a free TLS entry. +If +.BR set_thread_area () +finds a free TLS entry, the value of +.I u_info\->entry_number +is set upon return to show which entry was changed. +.P +A +.I user_desc +is considered "empty" if +.I read_exec_only +and +.I seg_not_present +are set to 1 and all of the other fields are 0. +If an "empty" descriptor is passed to +.BR set_thread_area (), +the corresponding TLS entry will be cleared. +See BUGS for additional details. +.P +Since Linux 3.19, +.BR set_thread_area () +cannot be used to write non-present segments, 16-bit segments, or code +segments, although clearing a segment is still acceptable. +.SH RETURN VALUE +On x86, these system calls +return 0 on success, and \-1 on failure, with +.I errno +set to indicate the error. +.P +On C-SKY, MIPS and m68k, +.BR set_thread_area () +always returns 0. +On m68k, +.BR get_thread_area () +returns the thread area pointer value +(previously set via +.BR set_thread_area ()). +.SH ERRORS +.TP +.B EFAULT +\fIu_info\fP is an invalid pointer. +.TP +.B EINVAL +\fIu_info\->entry_number\fP is out of bounds. +.TP +.B ENOSYS +.BR get_thread_area () +or +.BR set_thread_area () +was invoked as a 64-bit system call. +.TP +.B ESRCH +.RB ( set_thread_area ()) +A free TLS entry could not be located. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR set_thread_area () +Linux 2.5.29. +.TP +.BR get_thread_area () +Linux 2.5.32. +.SH NOTES +These system calls are generally intended for use only by threading libraries. +.P +.BR arch_prctl (2) +can interfere with +.BR set_thread_area () +on x86. +See +.BR arch_prctl (2) +for more details. +This is not normally a problem, as +.BR arch_prctl (2) +is normally used only by 64-bit programs. +.P +On MIPS, the current value of the thread area pointer can be obtained +using the instruction: +.P +.in +4n +.EX +rdhwr dest, $29 +.EE +.in +.P +This instruction traps and is handled by kernel. +.SH BUGS +On 64-bit kernels before Linux 3.19, +.\" commit e30ab185c490e9a9381385529e0fd32f0a399495 +one of the padding bits in +.IR user_desc , +if set, would prevent the descriptor from being considered empty (see +.BR modify_ldt (2)). +As a result, the only reliable way to clear a TLS entry is to use +.BR memset (3) +to zero the entire +.I user_desc +structure, including padding bits, and then to set the +.I read_exec_only +and +.I seg_not_present +bits. +On Linux 3.19, a +.I user_desc +consisting entirely of zeros except for +.I entry_number +will also be interpreted as a request to clear a TLS entry, but this +behaved differently on older kernels. +.P +Prior to Linux 3.19, the DS and ES segment registers must not reference +TLS entries. +.SH SEE ALSO +.BR arch_prctl (2), +.BR modify_ldt (2), +.BR ptrace (2) +.RB ( PTRACE_GET_THREAD_AREA " and " PTRACE_SET_THREAD_AREA ) diff --git a/man/man2/set_tid_address.2 b/man/man2/set_tid_address.2 new file mode 100644 index 0000000..dd9d9bc --- /dev/null +++ b/man/man2/set_tid_address.2 @@ -0,0 +1,97 @@ +.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH set_tid_address 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +set_tid_address \- set pointer to thread ID +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "pid_t syscall(SYS_set_tid_address, int *" tidptr ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR set_tid_address (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +For each thread, the kernel maintains two attributes (addresses) called +.I set_child_tid +and +.IR clear_child_tid . +These two attributes contain the value NULL by default. +.TP +.I set_child_tid +If a thread is started using +.BR clone (2) +with the +.B CLONE_CHILD_SETTID +flag, +.I set_child_tid +is set to the value passed in the +.I ctid +argument of that system call. +.IP +When +.I set_child_tid +is set, the very first thing the new thread does +is to write its thread ID at this address. +.TP +.I clear_child_tid +If a thread is started using +.BR clone (2) +with the +.B CLONE_CHILD_CLEARTID +flag, +.I clear_child_tid +is set to the value passed in the +.I ctid +argument of that system call. +.P +The system call +.BR set_tid_address () +sets the +.I clear_child_tid +value for the calling thread to +.IR tidptr . +.P +When a thread whose +.I clear_child_tid +is not NULL terminates, then, +if the thread is sharing memory with other threads, +then 0 is written at the address specified in +.I clear_child_tid +and the kernel performs the following operation: +.P +.in +4n +.EX +futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0); +.EE +.in +.P +The effect of this operation is to wake a single thread that +is performing a futex wait on the memory location. +Errors from the futex wake operation are ignored. +.SH RETURN VALUE +.BR set_tid_address () +always returns the caller's thread ID. +.SH ERRORS +.BR set_tid_address () +always succeeds. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5.48. +.P +Details as given here are valid since Linux 2.5.49. +.SH SEE ALSO +.BR clone (2), +.BR futex (2), +.BR gettid (2) diff --git a/man/man2/setdomainname.2 b/man/man2/setdomainname.2 new file mode 100644 index 0000000..1c1594c --- /dev/null +++ b/man/man2/setdomainname.2 @@ -0,0 +1 @@ +.so man2/getdomainname.2 diff --git a/man/man2/setegid.2 b/man/man2/setegid.2 new file mode 100644 index 0000000..85032b5 --- /dev/null +++ b/man/man2/setegid.2 @@ -0,0 +1 @@ +.so man2/seteuid.2 diff --git a/man/man2/seteuid.2 b/man/man2/seteuid.2 new file mode 100644 index 0000000..968b158 --- /dev/null +++ b/man/man2/seteuid.2 @@ -0,0 +1,134 @@ +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" [should really be seteuid.3] +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH seteuid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +seteuid, setegid \- set effective user or group ID +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int seteuid(uid_t " euid ); +.BI "int setegid(gid_t " egid ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR seteuid (), +.BR setegid (): +.nf + _POSIX_C_SOURCE >= 200112L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR seteuid () +sets the effective user ID of the calling process. +Unprivileged processes may only set the effective user ID to the +real user ID, the effective user ID or the saved set-user-ID. +.P +Precisely the same holds for +.BR setegid () +with "group" instead of "user". +.\" When +.\" .I euid +.\" equals \-1, nothing is changed. +.\" (This is an artifact of the implementation in glibc of seteuid() +.\" using setresuid(2).) +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +.IR Note : +there are cases where +.BR seteuid () +can fail even when the caller is UID 0; +it is a grave security error to omit checking for a failure return from +.BR seteuid (). +.SH ERRORS +.TP +.B EINVAL +The target user or group ID is not valid in this user namespace. +.TP +.B EPERM +In the case of +.BR seteuid (): +the calling process is not privileged (does not have the +.B CAP_SETUID +capability in its user namespace) and +.I euid +does not match the current real user ID, current effective user ID, +or current saved set-user-ID. +.IP +In the case of +.BR setegid (): +the calling process is not privileged (does not have the +.B CAP_SETGID +capability in its user namespace) and +.I egid +does not match the current real group ID, current effective group ID, +or current saved set-group-ID. +.SH VERSIONS +Setting the effective user (group) ID to the +saved set-user-ID (saved set-group-ID) is +possible since Linux 1.1.37 (1.1.38). +On an arbitrary system one should check +.BR _POSIX_SAVED_IDS . +.P +Under glibc 2.0, +.BI seteuid( euid ) +is equivalent to +.BI setreuid(\-1, " euid" ) +and hence may change the saved set-user-ID. +Under glibc 2.1 and later, it is equivalent to +.BI setresuid(\-1, " euid" ", \-1)" +and hence does not change the saved set-user-ID. +Analogous remarks hold for +.BR setegid (), +with the difference that the change in implementation from +.BI setregid(\-1, " egid" ) +to +.BI setresgid(\-1, " egid" ", \-1)" +occurred in glibc 2.2 or 2.3 (depending on the hardware architecture). +.P +According to POSIX.1, +.BR seteuid () +.RB ( setegid ()) +need not permit +.I euid +.RI ( egid ) +to be the same value as the current effective user (group) ID, +and some implementations do not permit this. +.SS C library/kernel differences +On Linux, +.BR seteuid () +and +.BR setegid () +are implemented as library functions that call, respectively, +.BR setresuid (2) +and +.BR setresgid (2). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.SH SEE ALSO +.BR geteuid (2), +.BR setresuid (2), +.BR setreuid (2), +.BR setuid (2), +.BR capabilities (7), +.BR credentials (7), +.BR user_namespaces (7) diff --git a/man/man2/setfsgid.2 b/man/man2/setfsgid.2 new file mode 100644 index 0000000..008f095 --- /dev/null +++ b/man/man2/setfsgid.2 @@ -0,0 +1,109 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" and Copyright (C) 2019, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created 1995-08-06 Thomas K. Dyas +.\" Modified 2000-07-01 aeb +.\" Modified 2002-07-23 aeb +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH setfsgid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setfsgid \- set group identity used for filesystem checks +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int setfsgid(gid_t " fsgid ); +.fi +.SH DESCRIPTION +On Linux, a process has both a filesystem group ID and an effective group ID. +The (Linux-specific) filesystem group ID is used +for permissions checking when accessing filesystem objects, +while the effective group ID is used for some other kinds +of permissions checks (see +.BR credentials (7)). +.P +Normally, the value of the process's filesystem group ID +is the same as the value of its effective group ID. +This is so, because whenever a process's effective group ID is changed, +the kernel also changes the filesystem group ID to be the same as +the new value of the effective group ID. +A process can cause the value of its filesystem group ID to diverge +from its effective group ID by using +.BR setfsgid () +to change its filesystem group ID to the value given in +.IR fsgid . +.P +.BR setfsgid () +will succeed only if the caller is the superuser or if +.I fsgid +matches either the caller's real group ID, effective group ID, +saved set-group-ID, or current the filesystem user ID. +.SH RETURN VALUE +On both success and failure, +this call returns the previous filesystem group ID of the caller. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 1.2. +.\" Linux 1.1.44 +.\" and in libc since libc 4.7.6. +.SS C library/kernel differences +In glibc 2.15 and earlier, +when the wrapper for this system call determines that the argument can't be +passed to the kernel without integer truncation (because the kernel +is old and does not support 32-bit group IDs), +it will return \-1 and set \fIerrno\fP to +.B EINVAL +without attempting +the system call. +.SH NOTES +The filesystem group ID concept and the +.BR setfsgid () +system call were invented for historical reasons that are +no longer applicable on modern Linux kernels. +See +.BR setfsuid (2) +for a discussion of why the use of both +.BR setfsuid (2) +and +.BR setfsgid () +is nowadays unneeded. +.P +The original Linux +.BR setfsgid () +system call supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR setfsgid32 () +supporting 32-bit IDs. +The glibc +.BR setfsgid () +wrapper function transparently deals with the variation across kernel versions. +.SH BUGS +No error indications of any kind are returned to the caller, +and the fact that both successful and unsuccessful calls return +the same value makes it impossible to directly determine +whether the call succeeded or failed. +Instead, the caller must resort to looking at the return value +from a further call such as +.I setfsgid(\-1) +(which will always fail), in order to determine if a preceding call to +.BR setfsgid () +changed the filesystem group ID. +At the very +least, +.B EPERM +should be returned when the call fails (because the caller lacks the +.B CAP_SETGID +capability). +.SH SEE ALSO +.BR kill (2), +.BR setfsuid (2), +.BR capabilities (7), +.BR credentials (7) diff --git a/man/man2/setfsgid32.2 b/man/man2/setfsgid32.2 new file mode 100644 index 0000000..fdb8bdc --- /dev/null +++ b/man/man2/setfsgid32.2 @@ -0,0 +1 @@ +.so man2/setfsgid.2 diff --git a/man/man2/setfsuid.2 b/man/man2/setfsuid.2 new file mode 100644 index 0000000..84d6891 --- /dev/null +++ b/man/man2/setfsuid.2 @@ -0,0 +1,127 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" and Copyright (C) 2013, 2019, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created 1995-08-06 Thomas K. Dyas +.\" Modified 2000-07-01 aeb +.\" Modified 2002-07-23 aeb +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH setfsuid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setfsuid \- set user identity used for filesystem checks +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int setfsuid(uid_t " fsuid ); +.fi +.SH DESCRIPTION +On Linux, a process has both a filesystem user ID and an effective user ID. +The (Linux-specific) filesystem user ID is used +for permissions checking when accessing filesystem objects, +while the effective user ID is used for various other kinds +of permissions checks (see +.BR credentials (7)). +.P +Normally, the value of the process's filesystem user ID +is the same as the value of its effective user ID. +This is so, because whenever a process's effective user ID is changed, +the kernel also changes the filesystem user ID to be the same as +the new value of the effective user ID. +A process can cause the value of its filesystem user ID to diverge +from its effective user ID by using +.BR setfsuid () +to change its filesystem user ID to the value given in +.IR fsuid . +.P +Explicit calls to +.BR setfsuid () +and +.BR setfsgid (2) +are (were) usually used only by programs such as the Linux NFS server that +need to change what user and group ID is used for file access without a +corresponding change in the real and effective user and group IDs. +A change in the normal user IDs for a program such as the NFS server +is (was) a security hole that can expose it to unwanted signals. +(However, this issue is historical; see below.) +.P +.BR setfsuid () +will succeed only if the caller is the superuser or if +.I fsuid +matches either the caller's real user ID, effective user ID, +saved set-user-ID, or current filesystem user ID. +.SH RETURN VALUE +On both success and failure, +this call returns the previous filesystem user ID of the caller. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 1.2. +.\" Linux 1.1.44 +.\" and in libc since libc 4.7.6. +.P +At the time when this system call was introduced, one process +could send a signal to another process with the same effective user ID. +This meant that if a privileged process changed its effective user ID +for the purpose of file permission checking, +then it could become vulnerable to receiving signals +sent by another (unprivileged) process with the same user ID. +The filesystem user ID attribute was thus added to allow a process to +change its user ID for the purposes of file permission checking without +at the same time becoming vulnerable to receiving unwanted signals. +Since Linux 2.0, signal permission handling is different (see +.BR kill (2)), +with the result that a process can change its effective user ID +without being vulnerable to receiving signals from unwanted processes. +Thus, +.BR setfsuid () +is nowadays unneeded and should be avoided in new applications +(likewise for +.BR setfsgid (2)). +.P +The original Linux +.BR setfsuid () +system call supported only 16-bit user IDs. +Subsequently, Linux 2.4 added +.BR setfsuid32 () +supporting 32-bit IDs. +The glibc +.BR setfsuid () +wrapper function transparently deals with the variation across kernel versions. +.SS C library/kernel differences +In glibc 2.15 and earlier, +when the wrapper for this system call determines that the argument can't be +passed to the kernel without integer truncation (because the kernel +is old and does not support 32-bit user IDs), +it will return \-1 and set \fIerrno\fP to +.B EINVAL +without attempting +the system call. +.SH BUGS +No error indications of any kind are returned to the caller, +and the fact that both successful and unsuccessful calls return +the same value makes it impossible to directly determine +whether the call succeeded or failed. +Instead, the caller must resort to looking at the return value +from a further call such as +.I setfsuid(\-1) +(which will always fail), in order to determine if a preceding call to +.BR setfsuid () +changed the filesystem user ID. +At the very +least, +.B EPERM +should be returned when the call fails (because the caller lacks the +.B CAP_SETUID +capability). +.SH SEE ALSO +.BR kill (2), +.BR setfsgid (2), +.BR capabilities (7), +.BR credentials (7) diff --git a/man/man2/setfsuid32.2 b/man/man2/setfsuid32.2 new file mode 100644 index 0000000..1ea58fd --- /dev/null +++ b/man/man2/setfsuid32.2 @@ -0,0 +1 @@ +.so man2/setfsuid.2 diff --git a/man/man2/setgid.2 b/man/man2/setgid.2 new file mode 100644 index 0000000..0b00b85 --- /dev/null +++ b/man/man2/setgid.2 @@ -0,0 +1,92 @@ +.\" Copyright (C), 1994, Graeme W. Wilford. (Wilf.) +.\" and Copyright (C) 2010, 2015, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Fri Jul 29th 12:56:44 BST 1994 Wilf. +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2002-03-09 by aeb +.\" +.TH setgid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setgid \- set group identity +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int setgid(gid_t " gid ); +.fi +.SH DESCRIPTION +.BR setgid () +sets the effective group ID of the calling process. +If the calling process is privileged (more precisely: has the +.B CAP_SETGID +capability in its user namespace), +the real GID and saved set-group-ID are also set. +.P +Under Linux, +.BR setgid () +is implemented like the POSIX version with the +.B _POSIX_SAVED_IDS +feature. +This allows a set-group-ID program that is not set-user-ID-root +to drop all of its group +privileges, do some un-privileged work, and then reengage the original +effective group ID in a secure manner. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The group ID specified in +.I gid +is not valid in this user namespace. +.TP +.B EPERM +The calling process is not privileged (does not have the +\fBCAP_SETGID\fP capability in its user namespace), and +.I gid +does not match the real group ID or saved set-group-ID of +the calling process. +.SH VERSIONS +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including the one for +.BR setgid ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.P +The original Linux +.BR setgid () +system call supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR setgid32 () +supporting 32-bit IDs. +The glibc +.BR setgid () +wrapper function transparently deals with the variation across kernel versions. +.SH SEE ALSO +.BR getgid (2), +.BR setegid (2), +.BR setregid (2), +.BR capabilities (7), +.BR credentials (7), +.BR user_namespaces (7) diff --git a/man/man2/setgid32.2 b/man/man2/setgid32.2 new file mode 100644 index 0000000..bc8ef19 --- /dev/null +++ b/man/man2/setgid32.2 @@ -0,0 +1 @@ +.so man2/setgid.2 diff --git a/man/man2/setgroups.2 b/man/man2/setgroups.2 new file mode 100644 index 0000000..0ae4cc0 --- /dev/null +++ b/man/man2/setgroups.2 @@ -0,0 +1 @@ +.so man2/getgroups.2 diff --git a/man/man2/setgroups32.2 b/man/man2/setgroups32.2 new file mode 100644 index 0000000..478fb63 --- /dev/null +++ b/man/man2/setgroups32.2 @@ -0,0 +1 @@ +.so man2/setgroups.2 diff --git a/man/man2/sethostname.2 b/man/man2/sethostname.2 new file mode 100644 index 0000000..e1fa2a6 --- /dev/null +++ b/man/man2/sethostname.2 @@ -0,0 +1 @@ +.so man2/gethostname.2 diff --git a/man/man2/setitimer.2 b/man/man2/setitimer.2 new file mode 100644 index 0000000..9518567 --- /dev/null +++ b/man/man2/setitimer.2 @@ -0,0 +1 @@ +.so man2/getitimer.2 diff --git a/man/man2/setns.2 b/man/man2/setns.2 new file mode 100644 index 0000000..1a01c10 --- /dev/null +++ b/man/man2/setns.2 @@ -0,0 +1,419 @@ +.\" Copyright (C) 2011, Eric Biederman +.\" and Copyright (C) 2011, 2012, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.TH setns 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setns \- reassociate thread with a namespace +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int setns(int " fd ", int " nstype ); +.fi +.SH DESCRIPTION +The +.BR setns () +system call allows the calling thread to move into different namespaces. +The +.I fd +argument is one of the following: +.IP \[bu] 3 +a file descriptor referring to one of the magic links in a +.IR /proc/ pid /ns/ +directory (or a bind mount to such a link); +.IP \[bu] +a PID file descriptor (see +.BR pidfd_open (2)). +.P +The +.I nstype +argument is interpreted differently in each case. +.\" +.SS fd refers to a \fI/proc/\fPpid\fI/ns/\fP link +If +.I fd +refers to a +.IR /proc/ pid /ns/ +link, then +.BR setns () +reassociates the calling thread with the namespace associated with that link, +subject to any constraints imposed by the +.I nstype +argument. +In this usage, each call to +.BR setns () +changes just one of the caller's namespace memberships. +.P +The +.I nstype +argument specifies which type of namespace +the calling thread may be reassociated with. +This argument can have +.I one +of the following values: +.TP +.B 0 +Allow any type of namespace to be joined. +.TP +.BR CLONE_NEWCGROUP " (since Linux 4.6)" +.I fd +must refer to a cgroup namespace. +.TP +.BR CLONE_NEWIPC " (since Linux 3.0)" +.I fd +must refer to an IPC namespace. +.TP +.BR CLONE_NEWNET " (since Linux 3.0)" +.I fd +must refer to a network namespace. +.TP +.BR CLONE_NEWNS " (since Linux 3.8)" +.I fd +must refer to a mount namespace. +.TP +.BR CLONE_NEWPID " (since Linux 3.8)" +.I fd +must refer to a descendant PID namespace. +.TP +.BR CLONE_NEWTIME " (since Linux 5.8)" +.\" commit 76c12881a38aaa83e1eb4ce2fada36c3a732bad4 +.I fd +must refer to a time namespace. +.TP +.BR CLONE_NEWUSER " (since Linux 3.8)" +.I fd +must refer to a user namespace. +.TP +.BR CLONE_NEWUTS " (since Linux 3.0)" +.I fd +must refer to a UTS namespace. +.P +Specifying +.I nstype +as 0 suffices if the caller knows (or does not care) +what type of namespace is referred to by +.IR fd . +Specifying a nonzero value for +.I nstype +is useful if the caller does not know what type of namespace is referred to by +.I fd +and wants to ensure that the namespace is of a particular type. +(The caller might not know the type of the namespace referred to by +.I fd +if the file descriptor was opened by another process and, for example, +passed to the caller via a UNIX domain socket.) +.\" +.SS fd is a PID file descriptor +Since Linux 5.8, +.I fd +may refer to a PID file descriptor obtained from +.BR pidfd_open (2) +or +.BR clone (2). +In this usage, +.BR setns () +atomically moves the calling thread into one or more of the same namespaces +as the thread referred to by +.IR fd . +.P +The +.I nstype +argument is a bit mask specified by ORing together +.I "one or more" +of the +.B CLONE_NEW* +namespace constants listed above. +The caller is moved into each of the target thread's namespaces +that is specified in +.IR nstype ; +the caller's memberships in the remaining namespaces are left unchanged. +.P +For example, the following code would move the caller into the +same user, network, and UTS namespaces as PID 1234, +but would leave the caller's other namespace memberships unchanged: +.P +.in +4n +.EX +int fd = pidfd_open(1234, 0); +setns(fd, CLONE_NEWUSER | CLONE_NEWNET | CLONE_NEWUTS); +.EE +.in +.\" +.SS Details for specific namespace types +Note the following details and restrictions when reassociating with +specific namespace types: +.TP +User namespaces +A process reassociating itself with a user namespace must have the +.B CAP_SYS_ADMIN +.\" See kernel/user_namespace.c:userns_install() [3.8 source] +capability in the target user namespace. +(This necessarily implies that it is only possible to join +a descendant user namespace.) +Upon successfully joining a user namespace, +a process is granted all capabilities in that namespace, +regardless of its user and group IDs. +.IP +A multithreaded process may not change user namespace with +.BR setns (). +.IP +It is not permitted to use +.BR setns () +to reenter the caller's current user namespace. +This prevents a caller that has dropped capabilities from regaining +those capabilities via a call to +.BR setns (). +.IP +For security reasons, +.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 +.\" https://lwn.net/Articles/543273/ +a process can't join a new user namespace if it is sharing +filesystem-related attributes +(the attributes whose sharing is controlled by the +.BR clone (2) +.B CLONE_FS +flag) with another process. +.IP +For further details on user namespaces, see +.BR user_namespaces (7). +.TP +Mount namespaces +Changing the mount namespace requires that the caller possess both +.B CAP_SYS_CHROOT +and +.B CAP_SYS_ADMIN +capabilities in its own user namespace and +.B CAP_SYS_ADMIN +in the user namespace that owns the target mount namespace. +.IP +A process can't join a new mount namespace if it is sharing +filesystem-related attributes +(the attributes whose sharing is controlled by the +.BR clone (2) +.B CLONE_FS +flag) with another process. +.\" Above check is in fs/namespace.c:mntns_install() [3.8 source] +.IP +See +.BR user_namespaces (7) +for details on the interaction of user namespaces and mount namespaces. +.TP +PID namespaces +In order to reassociate itself with a new PID namespace, +the caller must have the +.B CAP_SYS_ADMIN +capability both in its own user namespace and in the user namespace +that owns the target PID namespace. +.IP +Reassociating the PID namespace has somewhat different +from other namespace types. +Reassociating the calling thread with a PID namespace changes only +the PID namespace that subsequently created child processes of +the caller will be placed in; +it does not change the PID namespace of the caller itself. +.IP +Reassociating with a PID namespace is allowed only if the target +PID namespace is a descendant (child, grandchild, etc.) +of, or is the same as, the current PID namespace of the caller. +.IP +For further details on PID namespaces, see +.BR pid_namespaces (7). +.TP +Cgroup namespaces +In order to reassociate itself with a new cgroup namespace, +the caller must have the +.B CAP_SYS_ADMIN +capability both in its own user namespace and in the user namespace +that owns the target cgroup namespace. +.IP +Using +.BR setns () +to change the caller's cgroup namespace does not change +the caller's cgroup memberships. +.TP +Network, IPC, time, and UTS namespaces +In order to reassociate itself with a new network, IPC, time, or UTS namespace, +the caller must have the +.B CAP_SYS_ADMIN +capability both in its own user namespace and in the user namespace +that owns the target namespace. +.SH RETURN VALUE +On success, +.BR setns () +returns 0. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I fd +refers to a namespace whose type does not match that specified in +.IR nstype . +.TP +.B EINVAL +There is problem with reassociating +the thread with the specified namespace. +.TP +.\" See kernel/pid_namespace.c::pidns_install() [kernel 3.18 sources] +.B EINVAL +The caller tried to join an ancestor (parent, grandparent, and so on) +PID namespace. +.TP +.B EINVAL +The caller attempted to join the user namespace +in which it is already a member. +.TP +.B EINVAL +.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 +The caller shares filesystem +.RB ( CLONE_FS ) +state (in particular, the root directory) +with other processes and tried to join a new user namespace. +.TP +.B EINVAL +.\" See kernel/user_namespace.c::userns_install() [kernel 3.15 sources] +The caller is multithreaded and tried to join a new user namespace. +.TP +.B EINVAL +.I fd +is a PID file descriptor and +.I nstype +is invalid (e.g., it is 0). +.TP +.B ENOMEM +Cannot allocate sufficient memory to change the specified namespace. +.TP +.B EPERM +The calling thread did not have the required capability +for this operation. +.TP +.B ESRCH +.I fd +is a PID file descriptor but the process it refers to no longer exists +(i.e., it has terminated and been waited on). +.SH STANDARDS +Linux. +.SH VERSIONS +Linux 3.0, +glibc 2.14. +.SH NOTES +For further information on the +.IR /proc/ pid /ns/ +magic links, see +.BR namespaces (7). +.P +Not all of the attributes that can be shared when +a new thread is created using +.BR clone (2) +can be changed using +.BR setns (). +.SH EXAMPLES +The program below takes two or more arguments. +The first argument specifies the pathname of a namespace file in an existing +.IR /proc/ pid /ns/ +directory. +The remaining arguments specify a command and its arguments. +The program opens the namespace file, joins that namespace using +.BR setns (), +and executes the specified command inside that namespace. +.P +The following shell session demonstrates the use of this program +(compiled as a binary named +.IR ns_exec ) +in conjunction with the +.B CLONE_NEWUTS +example program in the +.BR clone (2) +man page (complied as a binary named +.IR newuts ). +.P +We begin by executing the example program in +.BR clone (2) +in the background. +That program creates a child in a separate UTS namespace. +The child changes the hostname in its namespace, +and then both processes display the hostnames in their UTS namespaces, +so that we can see that they are different. +.P +.in +4n +.EX +$ \fBsu\fP # Need privilege for namespace operations +Password: +# \fB./newuts bizarro &\fP +[1] 3549 +clone() returned 3550 +uts.nodename in child: bizarro +uts.nodename in parent: antero +# \fBuname \-n\fP # Verify hostname in the shell +antero +.EE +.in +.P +We then run the program shown below, +using it to execute a shell. +Inside that shell, we verify that the hostname is the one +set by the child created by the first program: +.P +.in +4n +.EX +# \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP +# \fBuname \-n\fP # Executed in shell started by ns_exec +bizarro +.EE +.in +.SS Program source +.\" SRC BEGIN (setns.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int fd; +\& + if (argc < 3) { + fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Get file descriptor for namespace; the file descriptor is opened + with O_CLOEXEC so as to ensure that it is not inherited by the + program that is later executed. */ +\& + fd = open(argv[1], O_RDONLY | O_CLOEXEC); + if (fd == \-1) + err(EXIT_FAILURE, "open"); +\& + if (setns(fd, 0) == \-1) /* Join that namespace */ + err(EXIT_FAILURE, "setns"); +\& + execvp(argv[2], &argv[2]); /* Execute a command in namespace */ + err(EXIT_FAILURE, "execvp"); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR nsenter (1), +.BR clone (2), +.BR fork (2), +.BR unshare (2), +.BR vfork (2), +.BR namespaces (7), +.BR unix (7) diff --git a/man/man2/setpgid.2 b/man/man2/setpgid.2 new file mode 100644 index 0000000..2a24eed --- /dev/null +++ b/man/man2/setpgid.2 @@ -0,0 +1,329 @@ +.\" Copyright (c) 1983, 1991 Regents of the University of California. +.\" and Copyright (C) 2007, Michael Kerrisk +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)getpgrp.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-04-15 by Michael Chastain : +.\" Added 'getpgid'. +.\" Modified 1996-07-21 by Andries Brouwer +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1999-09-02 by Michael Haardt +.\" Modified 2002-01-18 by Michael Kerrisk +.\" Modified 2003-01-20 by Andries Brouwer +.\" 2007-07-25, mtk, fairly substantial rewrites and rearrangements +.\" of text. +.\" +.TH setpgid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setpgid, getpgid, setpgrp, getpgrp \- set/get process group +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int setpgid(pid_t " pid ", pid_t " pgid ); +.BI "pid_t getpgid(pid_t " pid ); +.P +.BR "pid_t getpgrp(void);" " /* POSIX.1 version */" +.BI "[[deprecated]] pid_t getpgrp(pid_t " pid ");\fR /* BSD version */" +.P +.BR "int setpgrp(void);" " /* System V version */" +.BI "[[deprecated]] int setpgrp(pid_t " pid ", pid_t " pgid ");\fR /* BSD version */" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getpgid (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L +.fi +.P +.BR setpgrp "() (POSIX.1):" +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.P +.BR setpgrp "() (BSD)," +.BR getpgrp "() (BSD):" +.nf + [These are available only before glibc 2.19] + _BSD_SOURCE && + ! (_POSIX_SOURCE || _POSIX_C_SOURCE || _XOPEN_SOURCE + || _GNU_SOURCE || _SVID_SOURCE) +.fi +.SH DESCRIPTION +All of these interfaces are available on Linux, +and are used for getting and setting the +process group ID (PGID) of a process. +The preferred, POSIX.1-specified ways of doing this are: +.BR getpgrp (void), +for retrieving the calling process's PGID; and +.BR setpgid (), +for setting a process's PGID. +.P +.BR setpgid () +sets the PGID of the process specified by +.I pid +to +.IR pgid . +If +.I pid +is zero, then the process ID of the calling process is used. +If +.I pgid +is zero, then the PGID of the process specified by +.I pid +is made the same as its process ID. +If +.BR setpgid () +is used to move a process from one process +group to another (as is done by some shells when creating pipelines), +both process groups must be part of the same session (see +.BR setsid (2) +and +.BR credentials (7)). +In this case, +the \fIpgid\fP specifies an existing process group to be joined and the +session ID of that group must match the session ID of the joining process. +.P +The POSIX.1 version of +.BR getpgrp (), +which takes no arguments, +returns the PGID of the calling process. +.P +.BR getpgid () +returns the PGID of the process specified by +.IR pid . +If +.I pid +is zero, the process ID of the calling process is used. +(Retrieving the PGID of a process other than the caller is rarely +necessary, and the POSIX.1 +.BR getpgrp () +is preferred for that task.) +.P +The System\ V-style +.BR setpgrp (), +which takes no arguments, is equivalent to +.IR "setpgid(0,\ 0)" . +.P +The BSD-specific +.BR setpgrp () +call, which takes arguments +.I pid +and +.IR pgid , +is a wrapper function that calls +.P +.in +4n +.EX +setpgid(pid, pgid) +.EE +.in +.P +.\" The true BSD setpgrp() system call differs in allowing the PGID +.\" to be set to arbitrary values, rather than being restricted to +.\" PGIDs in the same session. +Since glibc 2.19, the BSD-specific +.BR setpgrp () +function is no longer exposed by +.IR ; +calls should be replaced with the +.BR setpgid () +call shown above. +.P +The BSD-specific +.BR getpgrp () +call, which takes a single +.I pid +argument, is a wrapper function that calls +.P +.in +4n +.EX +getpgid(pid) +.EE +.in +.P +Since glibc 2.19, the BSD-specific +.BR getpgrp () +function is no longer exposed by +.IR ; +calls should be replaced with calls to the POSIX.1 +.BR getpgrp () +which takes no arguments (if the intent is to obtain the caller's PGID), +or with the +.BR getpgid () +call shown above. +.SH RETURN VALUE +On success, +.BR setpgid () +and +.BR setpgrp () +return zero. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +The POSIX.1 +.BR getpgrp () +always returns the PGID of the caller. +.P +.BR getpgid (), +and the BSD-specific +.BR getpgrp () +return a process group on success. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +An attempt was made to change the process group ID +of one of the children of the calling process and the child had +already performed an +.BR execve (2) +.RB ( setpgid (), +.BR setpgrp ()). +.TP +.B EINVAL +.I pgid +is less than 0 +.RB ( setpgid (), +.BR setpgrp ()). +.TP +.B EPERM +An attempt was made to move a process into a process group in a +different session, or to change the process +group ID of one of the children of the calling process and the +child was in a different session, or to change the process group ID of +a session leader +.RB ( setpgid (), +.BR setpgrp ()). +.TP +.B EPERM +The target process group does not exist. +.RB ( setpgid (), +.BR setpgrp ()). +.TP +.B ESRCH +For +.BR getpgid (): +.I pid +does not match any process. +For +.BR setpgid (): +.I pid +is not the calling process and not a child of the calling process. +.SH STANDARDS +.TP +.BR getpgid () +.TQ +.BR setpgid () +.TQ +.BR getpgrp "() (no args)" +.TQ +.BR setpgrp "() (no args)" +POSIX.1-2008 (but see HISTORY). +.TP +.BR setpgrp "() (2 args)" +.TQ +.BR getpgrp "() (1 arg)" +None. +.SH HISTORY +.TP +.BR getpgid () +.TQ +.BR setpgid () +.TQ +.BR getpgrp "() (no args)" +POSIX.1-2001. +.TP +.BR setpgrp "() (no args)" +POSIX.1-2001. +POSIX.1-2008 marks it as obsolete. +.TP +.BR setpgrp "() (2 args)" +.TQ +.BR getpgrp "() (1 arg)" +4.2BSD. +.SH NOTES +A child created via +.BR fork (2) +inherits its parent's process group ID. +The PGID is preserved across an +.BR execve (2). +.P +Each process group is a member of a session and each process is a +member of the session of which its process group is a member. +(See +.BR credentials (7).) +.P +A session can have a controlling terminal. +At any time, one (and only one) of the process groups +in the session can be the foreground process group +for the terminal; +the remaining process groups are in the background. +If a signal is generated from the terminal (e.g., typing the +interrupt key to generate +.BR SIGINT ), +that signal is sent to the foreground process group. +(See +.BR termios (3) +for a description of the characters that generate signals.) +Only the foreground process group may +.BR read (2) +from the terminal; +if a background process group tries to +.BR read (2) +from the terminal, then the group is sent a +.B SIGTTIN +signal, which suspends it. +The +.BR tcgetpgrp (3) +and +.BR tcsetpgrp (3) +functions are used to get/set the foreground +process group of the controlling terminal. +.P +The +.BR setpgid () +and +.BR getpgrp () +calls are used by programs such as +.BR bash (1) +to create process groups in order to implement shell job control. +.P +If the termination of a process causes a process group to become orphaned, +and if any member of the newly orphaned process group is stopped, then a +.B SIGHUP +signal followed by a +.B SIGCONT +signal will be sent to each process +in the newly orphaned process group. +.\" exit.3 refers to the following text: +An orphaned process group is one in which the parent of +every member of process group is either itself also a member +of the process group or is a member of a process group +in a different session (see also +.BR credentials (7)). +.SH SEE ALSO +.BR getuid (2), +.BR setsid (2), +.BR tcgetpgrp (3), +.BR tcsetpgrp (3), +.BR termios (3), +.BR credentials (7) diff --git a/man/man2/setpgrp.2 b/man/man2/setpgrp.2 new file mode 100644 index 0000000..d6b107a --- /dev/null +++ b/man/man2/setpgrp.2 @@ -0,0 +1 @@ +.so man2/setpgid.2 diff --git a/man/man2/setpriority.2 b/man/man2/setpriority.2 new file mode 100644 index 0000000..b1dcfd9 --- /dev/null +++ b/man/man2/setpriority.2 @@ -0,0 +1 @@ +.so man2/getpriority.2 diff --git a/man/man2/setregid.2 b/man/man2/setregid.2 new file mode 100644 index 0000000..ec3ff64 --- /dev/null +++ b/man/man2/setregid.2 @@ -0,0 +1 @@ +.so man2/setreuid.2 diff --git a/man/man2/setregid32.2 b/man/man2/setregid32.2 new file mode 100644 index 0000000..035df17 --- /dev/null +++ b/man/man2/setregid32.2 @@ -0,0 +1 @@ +.so man2/setregid.2 diff --git a/man/man2/setresgid.2 b/man/man2/setresgid.2 new file mode 100644 index 0000000..d6866a1 --- /dev/null +++ b/man/man2/setresgid.2 @@ -0,0 +1 @@ +.so man2/setresuid.2 diff --git a/man/man2/setresgid32.2 b/man/man2/setresgid32.2 new file mode 100644 index 0000000..dec1b95 --- /dev/null +++ b/man/man2/setresgid32.2 @@ -0,0 +1 @@ +.so man2/setresgid.2 diff --git a/man/man2/setresuid.2 b/man/man2/setresuid.2 new file mode 100644 index 0000000..203b770 --- /dev/null +++ b/man/man2/setresuid.2 @@ -0,0 +1,147 @@ +.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2005, 2010, 2014, 2015, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified, 2003-05-26, Michael Kerrisk, +.TH setresuid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setresuid, setresgid \- set real, effective, and saved user or group ID +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int setresuid(uid_t " ruid ", uid_t " euid ", uid_t " suid ); +.BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid ); +.fi +.SH DESCRIPTION +.BR setresuid () +sets the real user ID, the effective user ID, and the +saved set-user-ID of the calling process. +.P +An unprivileged process may change its real UID, +effective UID, and saved set-user-ID, each to one of: +the current real UID, the current effective UID, or the +current saved set-user-ID. +.P +A privileged process (on Linux, one having the \fBCAP_SETUID\fP capability) +may set its real UID, effective UID, and +saved set-user-ID to arbitrary values. +.P +If one of the arguments equals \-1, the corresponding value is not changed. +.P +Regardless of what changes are made to the real UID, effective UID, +and saved set-user-ID, the filesystem UID is always set to the same +value as the (possibly new) effective UID. +.P +Completely analogously, +.BR setresgid () +sets the real GID, effective GID, and saved set-group-ID +of the calling process (and always modifies the filesystem GID +to be the same as the effective GID), +with the same restrictions for unprivileged processes. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +.IR Note : +there are cases where +.BR setresuid () +can fail even when the caller is UID 0; +it is a grave security error to omit checking for a failure return from +.BR setresuid (). +.SH ERRORS +.TP +.B EAGAIN +The call would change the caller's real UID (i.e., +.I ruid +does not match the caller's real UID), +but there was a temporary failure allocating the +necessary kernel data structures. +.TP +.B EAGAIN +.I ruid +does not match the caller's real UID and this call would +bring the number of processes belonging to the real user ID +.I ruid +over the caller's +.B RLIMIT_NPROC +resource limit. +Since Linux 3.1, this error case no longer occurs +(but robust applications should check for this error); +see the description of +.B EAGAIN +in +.BR execve (2). +.TP +.B EINVAL +One or more of the target user or group IDs +is not valid in this user namespace. +.TP +.B EPERM +The calling process is not privileged (did not have the necessary +capability in its user namespace) +and tried to change the IDs to values that are not permitted. +For +.BR setresuid (), +the necessary capability is +.BR CAP_SETUID ; +for +.BR setresgid (), +it is +.BR CAP_SETGID . +.SH VERSIONS +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including those for +.BR setresuid () +and +.BR setresgid ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). +.SH STANDARDS +None. +.SH HISTORY +Linux 2.1.44, +glibc 2.3.2. +HP-UX, FreeBSD. +.P +The original Linux +.BR setresuid () +and +.BR setresgid () +system calls supported only 16-bit user and group IDs. +Subsequently, Linux 2.4 added +.BR setresuid32 () +and +.BR setresgid32 (), +supporting 32-bit IDs. +The glibc +.BR setresuid () +and +.BR setresgid () +wrapper functions transparently deal with the variations across kernel versions. +.SH SEE ALSO +.BR getresuid (2), +.BR getuid (2), +.BR setfsgid (2), +.BR setfsuid (2), +.BR setreuid (2), +.BR setuid (2), +.BR capabilities (7), +.BR credentials (7), +.BR user_namespaces (7) diff --git a/man/man2/setresuid32.2 b/man/man2/setresuid32.2 new file mode 100644 index 0000000..d6866a1 --- /dev/null +++ b/man/man2/setresuid32.2 @@ -0,0 +1 @@ +.so man2/setresuid.2 diff --git a/man/man2/setreuid.2 b/man/man2/setreuid.2 new file mode 100644 index 0000000..c66ea22 --- /dev/null +++ b/man/man2/setreuid.2 @@ -0,0 +1,193 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" and Copyright (C) 2009, 2010, 2014, 2015, Michael Kerrisk +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)setregid.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified Sat Jul 24 09:08:49 1993 by Rik Faith +.\" Portions extracted from linux/kernel/sys.c: +.\" Copyright (C) 1991, 1992 Linus Torvalds +.\" May be distributed under the GNU General Public License +.\" Changes: 1994-07-29 by Wilf +.\" 1994-08-02 by Wilf due to change in kernel. +.\" 2004-07-04 by aeb +.\" 2004-05-27 by Michael Kerrisk +.\" +.TH setreuid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setreuid, setregid \- set real and/or effective user or group ID +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int setreuid(uid_t " ruid ", uid_t " euid ); +.BI "int setregid(gid_t " rgid ", gid_t " egid ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setreuid (), +.BR setregid (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR setreuid () +sets real and effective user IDs of the calling process. +.P +Supplying a value of \-1 for either the real or effective user ID forces +the system to leave that ID unchanged. +.P +Unprivileged processes may only set the effective user ID to the real user ID, +the effective user ID, or the saved set-user-ID. +.P +Unprivileged users may only set the real user ID to +the real user ID or the effective user ID. +.P +If the real user ID is set (i.e., +.I ruid +is not \-1) or the effective user ID is set to a value +not equal to the previous real user ID, +the saved set-user-ID will be set to the new effective user ID. +.P +Completely analogously, +.BR setregid () +sets real and effective group ID's of the calling process, +and all of the above holds with "group" instead of "user". +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +.IR Note : +there are cases where +.BR setreuid () +can fail even when the caller is UID 0; +it is a grave security error to omit checking for a failure return from +.BR setreuid (). +.SH ERRORS +.TP +.B EAGAIN +The call would change the caller's real UID (i.e., +.I ruid +does not match the caller's real UID), +but there was a temporary failure allocating the +necessary kernel data structures. +.TP +.B EAGAIN +.I ruid +does not match the caller's real UID and this call would +bring the number of processes belonging to the real user ID +.I ruid +over the caller's +.B RLIMIT_NPROC +resource limit. +Since Linux 3.1, this error case no longer occurs +(but robust applications should check for this error); +see the description of +.B EAGAIN +in +.BR execve (2). +.TP +.B EINVAL +One or more of the target user or group IDs +is not valid in this user namespace. +.TP +.B EPERM +The calling process is not privileged +(on Linux, does not have the necessary capability in its user namespace: +.B CAP_SETUID +in the case of +.BR setreuid (), +or +.B CAP_SETGID +in the case of +.BR setregid ()) +and a change other than (i) +swapping the effective user (group) ID with the real user (group) ID, +or (ii) setting one to the value of the other or (iii) setting the +effective user (group) ID to the value of the +saved set-user-ID (saved set-group-ID) was specified. +.SH VERSIONS +POSIX.1 does not specify all of the UID changes that Linux permits +for an unprivileged process. +For +.BR setreuid (), +the effective user ID can be made the same as the +real user ID or the saved set-user-ID, +and it is unspecified whether unprivileged processes may set the +real user ID to the real user ID, the effective user ID, or the +saved set-user-ID. +For +.BR setregid (), +the real group ID can be changed to the value of the saved set-group-ID, +and the effective group ID can be changed to the value of +the real group ID or the saved set-group-ID. +The precise details of what ID changes are permitted vary +across implementations. +.P +POSIX.1 makes no specification about the effect of these calls +on the saved set-user-ID and saved set-group-ID. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD (first appeared in 4.2BSD). +.P +Setting the effective user (group) ID to the +saved set-user-ID (saved set-group-ID) is +possible since Linux 1.1.37 (1.1.38). +.P +The original Linux +.BR setreuid () +and +.BR setregid () +system calls supported only 16-bit user and group IDs. +Subsequently, Linux 2.4 added +.BR setreuid32 () +and +.BR setregid32 (), +supporting 32-bit IDs. +The glibc +.BR setreuid () +and +.BR setregid () +wrapper functions transparently deal with the variations across kernel versions. +.\" +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including those for +.BR setreuid () +and +.BR setregid ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). +.SH SEE ALSO +.BR getgid (2), +.BR getuid (2), +.BR seteuid (2), +.BR setgid (2), +.BR setresuid (2), +.BR setuid (2), +.BR capabilities (7), +.BR credentials (7), +.BR user_namespaces (7) diff --git a/man/man2/setreuid32.2 b/man/man2/setreuid32.2 new file mode 100644 index 0000000..ec3ff64 --- /dev/null +++ b/man/man2/setreuid32.2 @@ -0,0 +1 @@ +.so man2/setreuid.2 diff --git a/man/man2/setrlimit.2 b/man/man2/setrlimit.2 new file mode 100644 index 0000000..df6d736 --- /dev/null +++ b/man/man2/setrlimit.2 @@ -0,0 +1 @@ +.so man2/getrlimit.2 diff --git a/man/man2/setsid.2 b/man/man2/setsid.2 new file mode 100644 index 0000000..71be3b5 --- /dev/null +++ b/man/man2/setsid.2 @@ -0,0 +1,100 @@ +.\" Copyright Michael Haardt (michael@cantor.informatik.rwth-aachen.de) +.\" Sat Aug 27 20:43:50 MET DST 1994 +.\" and Copyright (C) 2014, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Sep 11 19:19:05 1994 +.\" Modified Mon Mar 25 10:19:00 1996 (merged a few +.\" tiny changes from a man page by Charles Livingston). +.\" Modified Sun Jul 21 14:45:46 1996 +.\" +.TH setsid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setsid \- creates a session and sets the process group ID +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B pid_t setsid(void); +.fi +.SH DESCRIPTION +.BR setsid () +creates a new session if the calling process is not a +process group leader. +The calling process is the leader of the new session +(i.e., its session ID is made the same as its process ID). +The calling process also becomes +the process group leader of a new process group in the session +(i.e., its process group ID is made the same as its process ID). +.P +The calling process will be the only process in +the new process group and in the new session. +.P +Initially, the new session has no controlling terminal. +For details of how a session acquires a controlling terminal, see +.BR credentials (7). +.SH RETURN VALUE +On success, the (new) session ID of the calling process is returned. +On error, +.I "(pid_t)\ \-1" +is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EPERM +The process group ID of any process equals the PID of the calling process. +Thus, in particular, +.BR setsid () +fails if the calling process is already a process group leader. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.SH NOTES +A child created via +.BR fork (2) +inherits its parent's session ID. +The session ID is preserved across an +.BR execve (2). +.P +A process group leader is a process whose process group ID equals its PID. +Disallowing a process group leader from calling +.BR setsid () +prevents the possibility that a process group leader places itself +in a new session while other processes in the process group remain +in the original session; +such a scenario would break the strict +two-level hierarchy of sessions and process groups. +In order to be sure that +.BR setsid () +will succeed, call +.BR fork (2) +and have the parent +.BR _exit (2), +while the child (which by definition can't be a process group leader) calls +.BR setsid (). +.P +If a session has a controlling terminal, and the +.B CLOCAL +flag for that terminal is not set, +and a terminal hangup occurs, then the session leader is sent a +.B SIGHUP +signal. +.P +If a process that is a session leader terminates, then a +.B SIGHUP +signal is sent to each process in the foreground +process group of the controlling terminal. +.SH SEE ALSO +.BR setsid (1), +.BR getsid (2), +.BR setpgid (2), +.BR setpgrp (2), +.BR tcgetsid (3), +.BR credentials (7), +.BR sched (7) diff --git a/man/man2/setsockopt.2 b/man/man2/setsockopt.2 new file mode 100644 index 0000000..d98c776 --- /dev/null +++ b/man/man2/setsockopt.2 @@ -0,0 +1 @@ +.so man2/getsockopt.2 diff --git a/man/man2/settimeofday.2 b/man/man2/settimeofday.2 new file mode 100644 index 0000000..2b6eff4 --- /dev/null +++ b/man/man2/settimeofday.2 @@ -0,0 +1 @@ +.so man2/gettimeofday.2 diff --git a/man/man2/setuid.2 b/man/man2/setuid.2 new file mode 100644 index 0000000..9d0e4ac --- /dev/null +++ b/man/man2/setuid.2 @@ -0,0 +1,156 @@ +.\" Copyright (C), 1994, Graeme W. Wilford (Wilf). +.\" and Copyright (C) 2010, 2014, 2015, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Fri Jul 29th 12:56:44 BST 1994 Wilf. +.\" Changes inspired by patch from Richard Kettlewell +.\" , aeb 970616. +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.TH setuid 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setuid \- set user identity +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int setuid(uid_t " uid ); +.fi +.SH DESCRIPTION +.BR setuid () +sets the effective user ID of the calling process. +If the calling process is privileged +(more precisely: if the process has the +.B CAP_SETUID +capability in its user namespace), +the real UID and saved set-user-ID are also set. +.P +Under Linux, +.BR setuid () +is implemented like the POSIX version with the +.B _POSIX_SAVED_IDS +feature. +This allows a set-user-ID (other than root) program to drop all of its user +privileges, do some un-privileged work, and then reengage the original +effective user ID in a secure manner. +.P +If the user is root or the program is set-user-ID-root, special care must be +taken: +.BR setuid () +checks the effective user ID of the caller and if it is +the superuser, all process-related user ID's are set to +.IR uid . +After this has occurred, it is impossible for the program to regain root +privileges. +.P +Thus, a set-user-ID-root program wishing to temporarily drop root +privileges, assume the identity of an unprivileged user, and then regain +root privileges afterward cannot use +.BR setuid (). +You can accomplish this with +.BR seteuid (2). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.P +.IR Note : +there are cases where +.BR setuid () +can fail even when the caller is UID 0; +it is a grave security error to omit checking for a failure return from +.BR setuid (). +.SH ERRORS +.TP +.B EAGAIN +The call would change the caller's real UID (i.e., +.I uid +does not match the caller's real UID), +but there was a temporary failure allocating the +necessary kernel data structures. +.TP +.B EAGAIN +.I uid +does not match the real user ID of the caller and this call would +bring the number of processes belonging to the real user ID +.I uid +over the caller's +.B RLIMIT_NPROC +resource limit. +Since Linux 3.1, this error case no longer occurs +(but robust applications should check for this error); +see the description of +.B EAGAIN +in +.BR execve (2). +.TP +.B EINVAL +The user ID specified in +.I uid +is not valid in this user namespace. +.TP +.B EPERM +The user is not privileged (Linux: does not have the +.B CAP_SETUID +capability in its user namespace) and +.I uid +does not match the real UID or saved set-user-ID of the calling process. +.SH VERSIONS +.SS C library/kernel differences +At the kernel level, user IDs and group IDs are a per-thread attribute. +However, POSIX requires that all threads in a process +share the same credentials. +The NPTL threading implementation handles the POSIX requirements by +providing wrapper functions for +the various system calls that change process UIDs and GIDs. +These wrapper functions (including the one for +.BR setuid ()) +employ a signal-based technique to ensure +that when one thread changes credentials, +all of the other threads in the process also change their credentials. +For details, see +.BR nptl (7). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.P +Not quite compatible with the 4.4BSD call, which +sets all of the real, saved, and effective user IDs. +.\" SVr4 documents an additional EINVAL error condition. +.P +The original Linux +.BR setuid () +system call supported only 16-bit user IDs. +Subsequently, Linux 2.4 added +.BR setuid32 () +supporting 32-bit IDs. +The glibc +.BR setuid () +wrapper function transparently deals with the variation across kernel versions. +.SH NOTES +Linux has the concept of the filesystem user ID, normally equal to the +effective user ID. +The +.BR setuid () +call also sets the filesystem user ID of the calling process. +See +.BR setfsuid (2). +.P +If +.I uid +is different from the old effective UID, the process will +be forbidden from leaving core dumps. +.SH SEE ALSO +.BR getuid (2), +.BR seteuid (2), +.BR setfsuid (2), +.BR setreuid (2), +.BR capabilities (7), +.BR credentials (7), +.BR user_namespaces (7) diff --git a/man/man2/setuid32.2 b/man/man2/setuid32.2 new file mode 100644 index 0000000..24656c2 --- /dev/null +++ b/man/man2/setuid32.2 @@ -0,0 +1 @@ +.so man2/setuid.2 diff --git a/man/man2/setup.2 b/man/man2/setup.2 new file mode 100644 index 0000000..f9757d3 --- /dev/null +++ b/man/man2/setup.2 @@ -0,0 +1,55 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified Sun Jul 25 10:14:13 1993 by Rik Faith +.\" Modified 15 April 1995 by Michael Chastain +.\" Update calling parameters to Linux 1.2.4 values. +.\" Modified 10 June 1995 by Andries Brouwer +.\" Modified 3 May 1996 by Martin Schulze +.\" Modified Wed Nov 6 04:05:28 1996 by Eric S. Raymond +.\" Modified Sat Jan 29 01:08:23 2000 by aeb +.\" +.TH setup 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setup \- setup devices and filesystems, mount root filesystem +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B [[deprecated]] int setup(void); +.fi +.SH DESCRIPTION +.BR setup () +is called once from within +.IR linux/init/main.c . +It calls initialization functions for devices and filesystems +configured into the kernel and then mounts the root filesystem. +.P +No user process may call +.BR setup (). +Any user process, even a process with superuser permission, +will receive +.BR EPERM . +.SH RETURN VALUE +.BR setup () +always returns \-1 for a user process. +.SH ERRORS +.TP +.B EPERM +Always, for a user process. +.SH STANDARDS +Linux. +.SH VERSIONS +Removed in Linux 2.1.121. +.P +The calling sequence varied: at some times +.BR setup () +has had a single argument +.I "void\ *BIOS" +and at other times a single argument +.IR "int magic" . diff --git a/man/man2/setxattr.2 b/man/man2/setxattr.2 new file mode 100644 index 0000000..efcc3bb --- /dev/null +++ b/man/man2/setxattr.2 @@ -0,0 +1,159 @@ +.\" Copyright (C) Andreas Gruenbacher, February 2001 +.\" Copyright (C) Silicon Graphics Inc, September 2001 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH setxattr 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setxattr, lsetxattr, fsetxattr \- set an extended attribute value +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int setxattr(const char *" path ", const char *" name , +.BI " const void " value [. size "], size_t " size ", int " flags ); +.BI "int lsetxattr(const char *" path ", const char *" name , +.BI " const void " value [. size "], size_t " size ", int " flags ); +.BI "int fsetxattr(int " fd ", const char *" name , +.BI " const void " value [. size "], size_t " size ", int " flags ); +.fi +.SH DESCRIPTION +Extended attributes are +.IR name : value +pairs associated with inodes (files, directories, symbolic links, etc.). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e., the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR xattr (7). +.P +.BR setxattr () +sets the +.I value +of the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +The +.I size +argument specifies the size (in bytes) of +.IR value ; +a zero-length value is permitted. +.P +.BR lsetxattr () +is identical to +.BR setxattr (), +except in the case of a symbolic link, where the extended attribute is +set on the link itself, not the file that it refers to. +.P +.BR fsetxattr () +is identical to +.BR setxattr (), +only the extended attribute is set on the open file referred to by +.I fd +(as returned by +.BR open (2)) +in place of +.IR path . +.P +An extended attribute name is a null-terminated string. +The +.I name +includes a namespace prefix; there may be several, disjoint +namespaces associated with an individual inode. +The +.I value +of an extended attribute is a chunk of arbitrary textual or +binary data of specified length. +.P +By default +(i.e., +.I flags +is zero), +the extended attribute will be created if it does not exist, +or the value will be replaced if the attribute already exists. +To modify these semantics, one of the following values can be specified in +.IR flags : +.TP +.B XATTR_CREATE +Perform a pure create, which fails if the named attribute exists already. +.TP +.B XATTR_REPLACE +Perform a pure replace operation, +which fails if the named attribute does not already exist. +.SH RETURN VALUE +On success, zero is returned. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EDQUOT +Disk quota limits meant that +there is insufficient space remaining to store the extended attribute. +.TP +.B EEXIST +.B XATTR_CREATE +was specified, and the attribute exists already. +.TP +.B ENODATA +.B XATTR_REPLACE +was specified, and the attribute does not exist. +.\" .RB ( ENOATTR +.\" is defined to be a synonym for +.\" .BR ENODATA +.\" in +.\" .IR .) +.TP +.B ENOSPC +There is insufficient space remaining to store the extended attribute. +.TP +.B ENOTSUP +The namespace prefix of +.I name +is not valid. +.TP +.B ENOTSUP +Extended attributes are not supported by the filesystem, or are disabled, +.TP +.B EPERM +The file is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.P +In addition, the errors documented in +.BR stat (2) +can also occur. +.TP +.B ERANGE +The size of +.I name +or +.I value +exceeds a filesystem-specific limit. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.4, +glibc 2.3. +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@computer.org > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.\" Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR listxattr (2), +.BR open (2), +.BR removexattr (2), +.BR stat (2), +.BR symlink (7), +.BR xattr (7) diff --git a/man/man2/sgetmask.2 b/man/man2/sgetmask.2 new file mode 100644 index 0000000..1bfa553 --- /dev/null +++ b/man/man2/sgetmask.2 @@ -0,0 +1,70 @@ +.\" Copyright (c) 2007 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sgetmask 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sgetmask, ssetmask \- manipulation of signal mask (obsolete) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.B [[deprecated]] long syscall(SYS_sgetmask, void); +.BI "[[deprecated]] long syscall(SYS_ssetmask, long " newmask ); +.fi +.SH DESCRIPTION +These system calls are obsolete. +.IR "Do not use them" ; +use +.BR sigprocmask (2) +instead. +.P +.BR sgetmask () +returns the signal mask of the calling process. +.P +.BR ssetmask () +sets the signal mask of the calling process to the value given in +.IR newmask . +The previous signal mask is returned. +.P +The signal masks dealt with by these two system calls +are plain bit masks (unlike the +.I sigset_t +used by +.BR sigprocmask (2)); +use +.BR sigmask (3) +to create and inspect these masks. +.SH RETURN VALUE +.BR sgetmask () +always successfully returns the signal mask. +.BR ssetmask () +always succeeds, and returns the previous signal mask. +.SH ERRORS +These system calls always succeed. +.SH STANDARDS +Linux. +.SH HISTORY +Since Linux 3.16, +.\" f6187769dae48234f3877df3c4d99294cc2254fa +support for these system calls is optional, +depending on whether the kernel was built with the +.B CONFIG_SGETMASK_SYSCALL +option. +.SH NOTES +These system calls are unaware of signal numbers greater than 31 +(i.e., real-time signals). +.P +These system calls do not exist on x86-64. +.P +It is not possible to block +.B SIGSTOP +or +.BR SIGKILL . +.SH SEE ALSO +.BR sigprocmask (2), +.BR signal (7) diff --git a/man/man2/shmat.2 b/man/man2/shmat.2 new file mode 100644 index 0000000..3f3e5a4 --- /dev/null +++ b/man/man2/shmat.2 @@ -0,0 +1 @@ +.so man2/shmop.2 diff --git a/man/man2/shmctl.2 b/man/man2/shmctl.2 new file mode 100644 index 0000000..45f8cf1 --- /dev/null +++ b/man/man2/shmctl.2 @@ -0,0 +1,494 @@ +'\" t +.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993 +.\" and Copyright 1993 Giorgio Ciucci +.\" and Copyright 2004, 2005 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1993-07-28, Rik Faith +.\" Modified 1993-11-28, Giorgio Ciucci +.\" Modified 1997-01-31, Eric S. Raymond +.\" Modified 2001-02-18, Andries Brouwer +.\" Modified 2002-01-05, 2004-05-27, 2004-06-17, +.\" Michael Kerrisk +.\" Modified 2004-10-11, aeb +.\" Modified, Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Updated shmid_ds structure definitions +.\" Added information on SHM_DEST and SHM_LOCKED flags +.\" Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK +.\" since Linux 2.6.9 +.\" Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes +.\" 2005-04-25, mtk -- noted aberrant Linux behavior w.r.t. new +.\" attaches to a segment that has already been marked for deletion. +.\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions. +.\" 2018-03-20, dbueso: Added SHM_STAT_ANY description. +.\" +.TH shmctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +shmctl \- System V shared memory control +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int shmctl(int " shmid ", int " op ", struct shmid_ds *" buf ); +.fi +.SH DESCRIPTION +.BR shmctl () +performs the control operation specified by +.I op +on the System\ V shared memory segment whose identifier is given in +.IR shmid . +.P +The +.I buf +argument is a pointer to a \fIshmid_ds\fP structure, +defined in \fI\fP as follows: +.P +.in +4n +.EX +struct shmid_ds { + struct ipc_perm shm_perm; /* Ownership and permissions */ + size_t shm_segsz; /* Size of segment (bytes) */ + time_t shm_atime; /* Last attach time */ + time_t shm_dtime; /* Last detach time */ + time_t shm_ctime; /* Creation time/time of last + modification via shmctl() */ + pid_t shm_cpid; /* PID of creator */ + pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */ + shmatt_t shm_nattch; /* No. of current attaches */ + ... +}; +.EE +.in +.P +The fields of the +.I shmid_ds +structure are as follows: +.TP 12 +.I shm_perm +This is an +.I ipc_perm +structure (see below) that specifies the access permissions +on the shared memory segment. +.TP +.I shm_segsz +Size in bytes of the shared memory segment. +.TP +.I shm_atime +Time of the last +.BR shmat (2) +system call that attached this segment. +.TP +.I shm_dtime +Time of the last +.BR shmdt (2) +system call that detached tgis segment. +.TP +.I shm_ctime +Time of creation of segment or time of the last +.BR shmctl () +.B IPC_SET +operation. +.TP +.I shm_cpid +ID of the process that created the shared memory segment. +.TP +.I shm_lpid +ID of the last process that executed a +.BR shmat (2) +or +.BR shmdt (2) +system call on this segment. +.TP +.I shm_nattch +Number of processes that have this segment attached. +.P +The +.I ipc_perm +structure is defined as follows +(the highlighted fields are settable using +.BR IPC_SET ): +.P +.in +4n +.EX +struct ipc_perm { + key_t __key; /* Key supplied to shmget(2) */ + uid_t \fBuid\fP; /* Effective UID of owner */ + gid_t \fBgid\fP; /* Effective GID of owner */ + uid_t cuid; /* Effective UID of creator */ + gid_t cgid; /* Effective GID of creator */ + unsigned short \fBmode\fP; /* \fBPermissions\fP + SHM_DEST and + SHM_LOCKED flags */ + unsigned short __seq; /* Sequence number */ +}; +.EE +.in +.P +The least significant 9 bits of the +.I mode +field of the +.I ipc_perm +structure define the access permissions for the shared memory segment. +The permission bits are as follows: +.TS +l l. +0400 Read by user +0200 Write by user +0040 Read by group +0020 Write by group +0004 Read by others +0002 Write by others +.TE +.P +Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. +(It is not necessary to have execute permission on a segment +in order to perform a +.BR shmat (2) +call with the +.B SHM_EXEC +flag.) +.P +Valid values for +.I op +are: +.TP +.B IPC_STAT +Copy information from the kernel data structure associated with +.I shmid +into the +.I shmid_ds +structure pointed to by \fIbuf\fP. +The caller must have read permission on the +shared memory segment. +.TP +.B IPC_SET +Write the values of some members of the +.I shmid_ds +structure pointed to by +.I buf +to the kernel data structure associated with this shared memory segment, +updating also its +.I shm_ctime +member. +.IP +The following fields are updated: +\fIshm_perm.uid\fP, \fIshm_perm.gid\fP, +and (the least significant 9 bits of) \fIshm_perm.mode\fP. +.IP +The effective UID of the calling process must match the owner +.RI ( shm_perm.uid ) +or creator +.RI ( shm_perm.cuid ) +of the shared memory segment, or the caller must be privileged. +.TP +.B IPC_RMID +Mark the segment to be destroyed. +The segment will actually be destroyed +only after the last process detaches it (i.e., when the +.I shm_nattch +member of the associated structure +.I shmid_ds +is zero). +The caller must be the owner or creator of the segment, or be privileged. +The +.I buf +argument is ignored. +.IP +If a segment has been marked for destruction, then the (nonstandard) +.B SHM_DEST +flag of the +.I shm_perm.mode +field in the associated data structure retrieved by +.B IPC_STAT +will be set. +.IP +The caller \fImust\fP ensure that a segment is eventually destroyed; +otherwise its pages that were faulted in will remain in memory or swap. +.IP +See also the description of +.I /proc/sys/kernel/shm_rmid_forced +in +.BR proc (5). +.TP +.BR IPC_INFO " (Linux-specific)" +Return information about system-wide shared memory limits and +parameters in the structure pointed to by +.IR buf . +This structure is of type +.I shminfo +(thus, a cast is required), +defined in +.I +if the +.B _GNU_SOURCE +feature test macro is defined: +.IP +.in +4n +.EX +struct shminfo { + unsigned long shmmax; /* Maximum segment size */ + unsigned long shmmin; /* Minimum segment size; + always 1 */ + unsigned long shmmni; /* Maximum number of segments */ + unsigned long shmseg; /* Maximum number of segments + that a process can attach; + unused within kernel */ + unsigned long shmall; /* Maximum number of pages of + shared memory, system\-wide */ +}; +.EE +.in +.IP +The +.IR shmmni , +.IR shmmax , +and +.I shmall +settings can be changed via +.I /proc +files of the same name; see +.BR proc (5) +for details. +.TP +.BR SHM_INFO " (Linux-specific)" +Return a +.I shm_info +structure whose fields contain information +about system resources consumed by shared memory. +This structure is defined in +.I +if the +.B _GNU_SOURCE +feature test macro is defined: +.IP +.in +4n +.EX +struct shm_info { + int used_ids; /* # of currently existing + segments */ + unsigned long shm_tot; /* Total number of shared + memory pages */ + unsigned long shm_rss; /* # of resident shared + memory pages */ + unsigned long shm_swp; /* # of swapped shared + memory pages */ + unsigned long swap_attempts; + /* Unused since Linux 2.4 */ + unsigned long swap_successes; + /* Unused since Linux 2.4 */ +}; +.EE +.in +.TP +.BR SHM_STAT " (Linux-specific)" +Return a +.I shmid_ds +structure as for +.BR IPC_STAT . +However, the +.I shmid +argument is not a segment identifier, but instead an index into +the kernel's internal array that maintains information about +all shared memory segments on the system. +.TP +.BR SHM_STAT_ANY " (Linux-specific, since Linux 4.17)" +Return a +.I shmid_ds +structure as for +.BR SHM_STAT . +However, +.I shm_perm.mode +is not checked for read access for +.IR shmid , +meaning that any user can employ this operation (just as any user may read +.I /proc/sysvipc/shm +to obtain the same information). +.P +The caller can prevent or allow swapping of a shared +memory segment with the following +.I op +values: +.TP +.BR SHM_LOCK " (Linux-specific)" +Prevent swapping of the shared memory segment. +The caller must fault in +any pages that are required to be present after locking is enabled. +If a segment has been locked, then the (nonstandard) +.B SHM_LOCKED +flag of the +.I shm_perm.mode +field in the associated data structure retrieved by +.B IPC_STAT +will be set. +.TP +.BR SHM_UNLOCK " (Linux-specific)" +Unlock the segment, allowing it to be swapped out. +.P +Before Linux 2.6.10, only a privileged process +could employ +.B SHM_LOCK +and +.BR SHM_UNLOCK . +Since Linux 2.6.10, an unprivileged process can employ these operations +if its effective UID matches the owner or creator UID of the segment, and +(for +.BR SHM_LOCK ) +the amount of memory to be locked falls within the +.B RLIMIT_MEMLOCK +resource limit (see +.BR setrlimit (2)). +.\" There was some weirdness in Linux 2.6.9: SHM_LOCK and SHM_UNLOCK could +.\" be applied to a segment, regardless of ownership of the segment. +.\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed +.\" in Linux 2.6.10. MTK, May 2005 +.SH RETURN VALUE +A successful +.B IPC_INFO +or +.B SHM_INFO +operation returns the index of the highest used entry in the +kernel's internal array recording information about all +shared memory segments. +(This information can be used with repeated +.B SHM_STAT +or +.B SHM_STAT_ANY +operations to obtain information about all shared memory segments +on the system.) +A successful +.B SHM_STAT +operation returns the identifier of the shared memory segment +whose index was given in +.IR shmid . +Other operations return 0 on success. +.P +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +\fBIPC_STAT\fP or \fBSHM_STAT\fP is requested and +\fIshm_perm.mode\fP does not allow read access for +.IR shmid , +and the calling process does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EFAULT +The argument +.I op +has value +.B IPC_SET +or +.B IPC_STAT +but the address pointed to by +.I buf +isn't accessible. +.TP +.B EIDRM +\fIshmid\fP points to a removed identifier. +.TP +.B EINVAL +.I shmid +is not a valid identifier, or +.I op +is not a valid operation. +Or: for a +.B SHM_STAT +or +.B SHM_STAT_ANY +operation, the index value specified in +.I shmid +referred to an array slot that is currently unused. +.TP +.B ENOMEM +(Since Linux 2.6.9), +.B SHM_LOCK +was specified and the size of the to-be-locked segment would mean +that the total bytes in locked shared memory segments would exceed +the limit for the real user ID of the calling process. +This limit is defined by the +.B RLIMIT_MEMLOCK +soft resource limit (see +.BR setrlimit (2)). +.TP +.B EOVERFLOW +\fBIPC_STAT\fP is attempted, and the GID or UID value +is too large to be stored in the structure pointed to by +.IR buf . +.TP +.B EPERM +\fBIPC_SET\fP or \fBIPC_RMID\fP is attempted, and the +effective user ID of the calling process is not that of the creator +(found in +.IR shm_perm.cuid ), +or the owner +(found in +.IR shm_perm.uid ), +and the process was not privileged (Linux: did not have the +.B CAP_SYS_ADMIN +capability). +.IP +Or (before Linux 2.6.9), +.B SHM_LOCK +or +.B SHM_UNLOCK +was specified, but the process was not privileged +(Linux: did not have the +.B CAP_IPC_LOCK +capability). +(Since Linux 2.6.9, this error can also occur if the +.B RLIMIT_MEMLOCK +is 0 and the caller is not privileged.) +.SH VERSIONS +Linux permits a process to attach +.RB ( shmat (2)) +a shared memory segment that has already been marked for deletion +using +.IR shmctl(IPC_RMID) . +This feature is not available on other UNIX implementations; +portable applications should avoid relying on it. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVr4 documents additional error conditions EINVAL, +.\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents +.\" an EIDRM error condition. +.P +Various fields in a \fIstruct shmid_ds\fP were typed as +.I short +under Linux 2.2 +and have become +.I long +under Linux 2.4. +To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by an +.B IPC_64 +flag in +.IR op .) +.SH NOTES +The +.BR IPC_INFO , +.BR SHM_STAT , +and +.B SHM_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future, these may modified or moved to a +.I /proc +filesystem interface. +.SH SEE ALSO +.BR mlock (2), +.BR setrlimit (2), +.BR shmget (2), +.BR shmop (2), +.BR capabilities (7), +.BR sysvipc (7) diff --git a/man/man2/shmdt.2 b/man/man2/shmdt.2 new file mode 100644 index 0000000..3f3e5a4 --- /dev/null +++ b/man/man2/shmdt.2 @@ -0,0 +1 @@ +.so man2/shmop.2 diff --git a/man/man2/shmget.2 b/man/man2/shmget.2 new file mode 100644 index 0000000..45ba5ab --- /dev/null +++ b/man/man2/shmget.2 @@ -0,0 +1,412 @@ +.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 28 10:57:35 1993, Rik Faith +.\" Modified Sun Nov 28 16:43:30 1993, Rik Faith +.\" with material from Giorgio Ciucci +.\" Portions Copyright 1993 Giorgio Ciucci +.\" Modified Tue Oct 22 22:03:17 1996 by Eric S. Raymond +.\" Modified, 8 Jan 2003, Michael Kerrisk, +.\" Removed EIDRM from errors - that can't happen... +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" +.TH shmget 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +shmget \- allocates a System V shared memory segment +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int shmget(key_t " key ", size_t " size ", int " shmflg ); +.fi +.SH DESCRIPTION +.BR shmget () +returns the identifier of the System\ V shared memory segment +associated with the value of the argument +.IR key . +It may be used either to obtain the identifier of a previously created +shared memory segment (when +.I shmflg +is zero and +.I key +does not have the value +.BR IPC_PRIVATE ), +or to create a new set. +.P +A new shared memory segment, with size equal to the value of +.I size +rounded up to a multiple of +.BR PAGE_SIZE , +is created if +.I key +has the value +.B IPC_PRIVATE +or +.I key +isn't +.BR IPC_PRIVATE , +no shared memory segment corresponding to +.I key +exists, and +.B IPC_CREAT +is specified in +.IR shmflg . +.P +If +.I shmflg +specifies both +.B IPC_CREAT +and +.B IPC_EXCL +and a shared memory segment already exists for +.IR key , +then +.BR shmget () +fails with +.I errno +set to +.BR EEXIST . +(This is analogous to the effect of the combination +.B O_CREAT | O_EXCL +for +.BR open (2).) +.P +The value +.I shmflg +is composed of: +.TP +.B IPC_CREAT +Create a new segment. +If this flag is not used, then +.BR shmget () +will find the segment associated with \fIkey\fP and check to see if +the user has permission to access the segment. +.TP +.B IPC_EXCL +This flag is used with +.B IPC_CREAT +to ensure that this call creates the segment. +If the segment already exists, the call fails. +.TP +.BR SHM_HUGETLB " (since Linux 2.6)" +Allocate the segment using "huge" pages. +See the Linux kernel source file +.I Documentation/admin\-guide/mm/hugetlbpage.rst +for further information. +.TP +.B SHM_HUGE_2MB +.TQ +.BR SHM_HUGE_1GB " (since Linux 3.8)" +.\" See https://lwn.net/Articles/533499/ +Used in conjunction with +.B SHM_HUGETLB +to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB) +on systems that support multiple hugetlb page sizes. +.IP +More generally, the desired huge page size can be configured by encoding +the base-2 logarithm of the desired page size in the six bits at the offset +.BR SHM_HUGE_SHIFT . +Thus, the above two constants are defined as: +.IP +.in +4n +.EX +#define SHM_HUGE_2MB (21 << SHM_HUGE_SHIFT) +#define SHM_HUGE_1GB (30 << SHM_HUGE_SHIFT) +.EE +.in +.IP +For some additional details, +see the discussion of the similarly named constants in +.BR mmap (2). +.TP +.BR SHM_NORESERVE " (since Linux 2.6.15)" +This flag serves the same purpose as the +.BR mmap (2) +.B MAP_NORESERVE +flag. +Do not reserve swap space for this segment. +When swap space is reserved, one has the guarantee +that it is possible to modify the segment. +When swap space is not reserved one might get +.B SIGSEGV +upon a write +if no physical memory is available. +See also the discussion of the file +.I /proc/sys/vm/overcommit_memory +in +.BR proc (5). +.\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also +.\" specified. +.P +In addition to the above flags, the least significant 9 bits of +.I shmflg +specify the permissions granted to the owner, group, and others. +These bits have the same format, and the same +meaning, as the +.I mode +argument of +.BR open (2). +Presently, execute permissions are not used by the system. +.P +When a new shared memory segment is created, +its contents are initialized to zero values, and +its associated data structure, +.I shmid_ds +(see +.BR shmctl (2)), +is initialized as follows: +.IP \[bu] 3 +.I shm_perm.cuid +and +.I shm_perm.uid +are set to the effective user ID of the calling process. +.IP \[bu] +.I shm_perm.cgid +and +.I shm_perm.gid +are set to the effective group ID of the calling process. +.IP \[bu] +The least significant 9 bits of +.I shm_perm.mode +are set to the least significant 9 bit of +.IR shmflg . +.IP \[bu] +.I shm_segsz +is set to the value of +.IR size . +.IP \[bu] +.IR shm_lpid , +.IR shm_nattch , +.IR shm_atime , +and +.I shm_dtime +are set to 0. +.IP \[bu] +.I shm_ctime +is set to the current time. +.P +If the shared memory segment already exists, the permissions are +verified, and a check is made to see if it is marked for destruction. +.SH RETURN VALUE +On success, a valid shared memory identifier is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The user does not have permission to access the +shared memory segment, and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EEXIST +.B IPC_CREAT +and +.B IPC_EXCL +were specified in +.IR shmflg , +but a shared memory segment already exists for +.IR key . +.TP +.B EINVAL +A new segment was to be created and +.I size +is less than +.B SHMMIN +or greater than +.BR SHMMAX . +.TP +.B EINVAL +A segment for the given +.I key +exists, but \fIsize\fP is greater than the size +of that segment. +.TP +.B ENFILE +.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +No segment exists for the given \fIkey\fP, and +.B IPC_CREAT +was not specified. +.TP +.B ENOMEM +No memory could be allocated for segment overhead. +.TP +.B ENOSPC +All possible shared memory IDs have been taken +.RB ( SHMMNI ), +or allocating a segment of the requested +.I size +would cause the system to exceed the system-wide limit on shared memory +.RB ( SHMALL ). +.TP +.B EPERM +The +.B SHM_HUGETLB +flag was specified, but the caller was not privileged (did not have the +.B CAP_IPC_LOCK +capability) +and is not a member of the +.I sysctl_hugetlb_shm_group +group; see the description of +.I /proc/sys/vm/sysctl_hugetlb_shm_group +in +.BR proc (5). +.SH STANDARDS +POSIX.1-2008. +.P +.B SHM_HUGETLB +and +.B SHM_NORESERVE +are Linux extensions. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVr4 documents an additional error condition EEXIST. +.SH NOTES +.B IPC_PRIVATE +isn't a flag field but a +.I key_t +type. +If this special value is used for +.IR key , +the system call ignores all but the least significant 9 bits of +.I shmflg +and creates a new shared memory segment. +.\" +.SS Shared memory limits +The following limits on shared memory segment resources affect the +.BR shmget () +call: +.TP +.B SHMALL +System-wide limit on the total amount of shared memory, +measured in units of the system page size. +.IP +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/shmall . +Since Linux 3.16, +.\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31 +the default value for this limit is: +.IP +.in +4n +.EX +ULONG_MAX - 2\[ha]24 +.EE +.in +.IP +The effect of this value +(which is suitable for both 32-bit and 64-bit systems) +is to impose no limitation on allocations. +This value, rather than +.BR ULONG_MAX , +was chosen as the default to prevent some cases where historical +applications simply raised the existing limit without first checking +its current value. +Such applications would cause the value to overflow if the limit was set at +.BR ULONG_MAX . +.IP +From Linux 2.4 up to Linux 3.15, +the default value for this limit was: +.IP +.in +4n +.EX +SHMMAX / PAGE_SIZE * (SHMMNI / 16) +.EE +.in +.IP +If +.B SHMMAX +and +.B SHMMNI +were not modified, then multiplying the result of this formula +by the page size (to get a value in bytes) yielded a value of 8\ GB +as the limit on the total memory used by all shared memory segments. +.TP +.B SHMMAX +Maximum size in bytes for a shared memory segment. +.IP +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/shmmax . +Since Linux 3.16, +.\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31 +the default value for this limit is: +.IP +.in +4n +.EX +ULONG_MAX - 2\[ha]24 +.EE +.in +.IP +The effect of this value +(which is suitable for both 32-bit and 64-bit systems) +is to impose no limitation on allocations. +See the description of +.B SHMALL +for a discussion of why this default value (rather than +.BR ULONG_MAX ) +is used. +.IP +From Linux 2.2 up to Linux 3.15, the default value of +this limit was 0x2000000 (32\ MiB). +.IP +Because it is not possible to map just part of a shared memory segment, +the amount of virtual memory places another limit on the maximum size of a +usable segment: +for example, on i386 the largest segments that can be mapped have a +size of around 2.8\ GB, and on x86-64 the limit is around 127 TB. +.TP +.B SHMMIN +Minimum size in bytes for a shared memory segment: implementation +dependent (currently 1 byte, though +.B PAGE_SIZE +is the effective minimum size). +.TP +.B SHMMNI +System-wide limit on the number of shared memory segments. +In Linux 2.2, the default value for this limit was 128; +since Linux 2.4, the default value is 4096. +.IP +On Linux, this limit can be read and modified via +.IR /proc/sys/kernel/shmmni . +.\" Kernels between Linux 2.4.x and Linux 2.6.8 had an off-by-one error +.\" that meant that we could create one more segment than SHMMNI -- MTK +.\" This /proc file is not available in Linux 2.2 and earlier -- MTK +.P +The implementation has no specific limits for the per-process maximum +number of shared memory segments +.RB ( SHMSEG ). +.SS Linux notes +Until Linux 2.3.30, Linux would return +.B EIDRM +for a +.BR shmget () +on a shared memory segment scheduled for deletion. +.SH BUGS +The name choice +.B IPC_PRIVATE +was perhaps unfortunate, +.B IPC_NEW +would more clearly show its function. +.SH EXAMPLES +See +.BR shmop (2). +.SH SEE ALSO +.BR memfd_create (2), +.BR shmat (2), +.BR shmctl (2), +.BR shmdt (2), +.BR ftok (3), +.BR capabilities (7), +.BR shm_overview (7), +.BR sysvipc (7) diff --git a/man/man2/shmop.2 b/man/man2/shmop.2 new file mode 100644 index 0000000..1cb835e --- /dev/null +++ b/man/man2/shmop.2 @@ -0,0 +1,508 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" and Copyright 2020 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sun Nov 28 17:06:19 1993, Rik Faith (faith@cs.unc.edu) +.\" with material from Luigi P. Bai (lpb@softint.com) +.\" Portions Copyright 1993 Luigi P. Bai +.\" Modified Tue Oct 22 22:04:23 1996 by Eric S. Raymond +.\" Modified, 5 Jan 2002, Michael Kerrisk +.\" Modified, 19 Sep 2002, Michael Kerrisk +.\" Added SHM_REMAP flag description +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Changed wording and placement of sentence regarding attachment +.\" of segments marked for destruction +.\" +.TH SHMOP 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +shmat, shmdt \- System V shared memory operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *shmat(int " shmid ", const void *_Nullable " shmaddr ", \ +int " shmflg ); +.BI "int shmdt(const void *" shmaddr ); +.fi +.SH DESCRIPTION +.SS shmat() +.BR shmat () +attaches the System\ V shared memory segment identified by +.I shmid +to the address space of the calling process. +The attaching address is specified by +.I shmaddr +with one of the following criteria: +.IP \[bu] 3 +If +.I shmaddr +is NULL, +the system chooses a suitable (unused) page-aligned address to attach +the segment. +.IP \[bu] +If +.I shmaddr +isn't NULL +and +.B SHM_RND +is specified in +.IR shmflg , +the attach occurs at the address equal to +.I shmaddr +rounded down to the nearest multiple of +.BR SHMLBA . +.IP \[bu] +Otherwise, +.I shmaddr +must be a page-aligned address at which the attach occurs. +.P +In addition to +.BR SHM_RND , +the following flags may be specified in the +.I shmflg +bit-mask argument: +.TP +.BR SHM_EXEC " (Linux-specific; since Linux 2.6.9)" +Allow the contents of the segment to be executed. +The caller must have execute permission on the segment. +.TP +.B SHM_RDONLY +Attach the segment for read-only access. +The process must have read permission for the segment. +If this flag is not specified, +the segment is attached for read and write access, +and the process must have read and write permission for the segment. +There is no notion of a write-only shared memory segment. +.TP +.BR SHM_REMAP " (Linux-specific)" +This flag specifies +that the mapping of the segment should replace +any existing mapping in the range starting at +.I shmaddr +and continuing for the size of the segment. +(Normally, an +.B EINVAL +error would result if a mapping already exists in this address range.) +In this case, +.I shmaddr +must not be NULL. +.P +The +.BR brk (2) +value of the calling process is not altered by the attach. +The segment will automatically be detached at process exit. +The same segment may be attached as a read and as a read-write +one, and more than once, in the process's address space. +.P +A successful +.BR shmat () +call updates the members of the +.I shmid_ds +structure (see +.BR shmctl (2)) +associated with the shared memory segment as follows: +.IP \[bu] 3 +.I shm_atime +is set to the current time. +.IP \[bu] +.I shm_lpid +is set to the process-ID of the calling process. +.IP \[bu] +.I shm_nattch +is incremented by one. +.\" +.SS shmdt() +.BR shmdt () +detaches the shared memory segment located at the address specified by +.I shmaddr +from the address space of the calling process. +The to-be-detached segment must be currently +attached with +.I shmaddr +equal to the value returned by the attaching +.BR shmat () +call. +.P +On a successful +.BR shmdt () +call, the system updates the members of the +.I shmid_ds +structure associated with the shared memory segment as follows: +.IP \[bu] 3 +.I shm_dtime +is set to the current time. +.IP \[bu] +.I shm_lpid +is set to the process-ID of the calling process. +.IP \[bu] +.I shm_nattch +is decremented by one. +If it becomes 0 and the segment is marked for deletion, +the segment is deleted. +.SH RETURN VALUE +On success, +.BR shmat () +returns the address of the attached shared memory segment; on error, +.I (void\ *)\ \-1 +is returned, and +.I errno +is set to indicate the error. +.P +On success, +.BR shmdt () +returns 0; on error \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR shmat () +can fail with one of the following errors: +.TP +.B EACCES +The calling process does not have the required permissions for +the requested attach type, and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EIDRM +\fIshmid\fP points to a removed identifier. +.TP +.B EINVAL +Invalid +.I shmid +value, unaligned (i.e., not page-aligned and \fBSHM_RND\fP was not +specified) or invalid +.I shmaddr +value, or can't attach segment at +.IR shmaddr , +or +.B SHM_REMAP +was specified and +.I shmaddr +was NULL. +.TP +.B ENOMEM +Could not allocate memory for the descriptor or for the page tables. +.P +.BR shmdt () +can fail with one of the following errors: +.TP +.B EINVAL +There is no shared memory segment attached at +.IR shmaddr ; +or, +.\" The following since Linux 2.6.17-rc1: +.I shmaddr +is not aligned on a page boundary. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVr4 documents an additional error condition EMFILE. +.P +In SVID 3 (or perhaps earlier), +the type of the \fIshmaddr\fP argument was changed from +.I "char\ *" +into +.IR "const void\ *" , +and the returned type of +.BR shmat () +from +.I "char\ *" +into +.IR "void\ *" . +.SH NOTES +After a +.BR fork (2), +the child inherits the attached shared memory segments. +.P +After an +.BR execve (2), +all attached shared memory segments are detached from the process. +.P +Upon +.BR _exit (2), +all attached shared memory segments are detached from the process. +.P +Using +.BR shmat () +with +.I shmaddr +equal to NULL +is the preferred, portable way of attaching a shared memory segment. +Be aware that the shared memory segment attached in this way +may be attached at different addresses in different processes. +Therefore, any pointers maintained within the shared memory must be +made relative (typically to the starting address of the segment), +rather than absolute. +.P +On Linux, it is possible to attach a shared memory segment even if it +is already marked to be deleted. +However, POSIX.1 does not specify this behavior and +many other implementations do not support it. +.P +The following system parameter affects +.BR shmat (): +.TP +.B SHMLBA +Segment low boundary address multiple. +When explicitly specifying an attach address in a call to +.BR shmat (), +the caller should ensure that the address is a multiple of this value. +This is necessary on some architectures, +in order either to ensure good CPU cache performance or to ensure that +different attaches of the same segment have consistent views +within the CPU cache. +.B SHMLBA +is normally some multiple of the system page size. +(On many Linux architectures, +.B SHMLBA +is the same as the system page size.) +.P +The implementation places no intrinsic per-process limit on the +number of shared memory segments +.RB ( SHMSEG ). +.SH EXAMPLES +The two programs shown below exchange a string using a shared memory segment. +Further details about the programs are given below. +First, we show a shell session demonstrating their use. +.P +In one terminal window, we run the "reader" program, +which creates a System V shared memory segment and a System V semaphore set. +The program prints out the IDs of the created objects, +and then waits for the semaphore to change value. +.P +.in +4n +.EX +$ \fB./svshm_string_read\fP +shmid = 1114194; semid = 15 +.EE +.in +.P +In another terminal window, we run the "writer" program. +The "writer" program takes three command-line arguments: +the IDs of the shared memory segment and semaphore set created +by the "reader", and a string. +It attaches the existing shared memory segment, +copies the string to the shared memory, and modifies the semaphore value. +.P +.in +4n +.EX +$ \fB./svshm_string_write 1114194 15 \[aq]Hello, world\[aq]\fP +.EE +.in +.P +Returning to the terminal where the "reader" is running, +we see that the program has ceased waiting on the semaphore +and has printed the string that was copied into the +shared memory segment by the writer: +.P +.in +4n +.EX +Hello, world +.EE +.in +.\" +.SS Program source: svshm_string.h +The following header file is included by the "reader" and "writer" programs: +.P +.in +4n +.\" SRC BEGIN (svshm_string.h) +.EX +/* svshm_string.h +\& + Licensed under GNU General Public License v2 or later. +*/ +#ifndef SVSHM_STRING_H +#define SVSHM_STRING_H +\& +#include +#include +#include +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +union semun { /* Used in calls to semctl() */ + int val; + struct semid_ds *buf; + unsigned short *array; +#if defined(__linux__) + struct seminfo *__buf; +#endif +}; +\& +#define MEM_SIZE 4096 +\& +#endif // include guard +.EE +.\" SRC END +.in +.\" +.SS Program source: svshm_string_read.c +The "reader" program creates a shared memory segment and a semaphore set +containing one semaphore. +It then attaches the shared memory object into its address space +and initializes the semaphore value to 1. +Finally, the program waits for the semaphore value to become 0, +and afterwards prints the string that has been copied into the +shared memory segment by the "writer". +.P +.in +4n +.\" SRC BEGIN (svshm_string_read.c) +.EX +/* svshm_string_read.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include +#include +#include +#include +#include +\& +#include "svshm_string.h" +\& +int +main(void) +{ + int semid, shmid; + char *addr; + union semun arg, dummy; + struct sembuf sop; +\& + /* Create shared memory and semaphore set containing one + semaphore. */ +\& + shmid = shmget(IPC_PRIVATE, MEM_SIZE, IPC_CREAT | 0600); + if (shmid == \-1) + errExit("shmget"); +\& + semid = semget(IPC_PRIVATE, 1, IPC_CREAT | 0600); + if (semid == \-1) + errExit("semget"); +\& + /* Attach shared memory into our address space. */ +\& + addr = shmat(shmid, NULL, SHM_RDONLY); + if (addr == (void *) \-1) + errExit("shmat"); +\& + /* Initialize semaphore 0 in set with value 1. */ +\& + arg.val = 1; + if (semctl(semid, 0, SETVAL, arg) == \-1) + errExit("semctl"); +\& + printf("shmid = %d; semid = %d\en", shmid, semid); +\& + /* Wait for semaphore value to become 0. */ +\& + sop.sem_num = 0; + sop.sem_op = 0; + sop.sem_flg = 0; +\& + if (semop(semid, &sop, 1) == \-1) + errExit("semop"); +\& + /* Print the string from shared memory. */ +\& + printf("%s\en", addr); +\& + /* Remove shared memory and semaphore set. */ +\& + if (shmctl(shmid, IPC_RMID, NULL) == \-1) + errExit("shmctl"); + if (semctl(semid, 0, IPC_RMID, dummy) == \-1) + errExit("semctl"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.\" +.SS Program source: svshm_string_write.c +The writer program takes three command-line arguments: +the IDs of the shared memory segment and semaphore set +that have already been created by the "reader", and a string. +It attaches the shared memory segment into its address space, +and then decrements the semaphore value to 0 in order to inform the +"reader" that it can now examine the contents of the shared memory. +.P +.in +4n +.\" SRC BEGIN (svshm_string_write.c) +.EX +/* svshm_string_write.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include +#include +#include +#include +#include +\& +#include "svshm_string.h" +\& +int +main(int argc, char *argv[]) +{ + int semid, shmid; + char *addr; + size_t len; + struct sembuf sop; +\& + if (argc != 4) { + fprintf(stderr, "Usage: %s shmid semid string\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + len = strlen(argv[3]) + 1; /* +1 to include trailing \[aq]\e0\[aq] */ + if (len > MEM_SIZE) { + fprintf(stderr, "String is too big!\en"); + exit(EXIT_FAILURE); + } +\& + /* Get object IDs from command\-line. */ +\& + shmid = atoi(argv[1]); + semid = atoi(argv[2]); +\& + /* Attach shared memory into our address space and copy string + (including trailing null byte) into memory. */ +\& + addr = shmat(shmid, NULL, 0); + if (addr == (void *) \-1) + errExit("shmat"); +\& + memcpy(addr, argv[3], len); +\& + /* Decrement semaphore to 0. */ +\& + sop.sem_num = 0; + sop.sem_op = \-1; + sop.sem_flg = 0; +\& + if (semop(semid, &sop, 1) == \-1) + errExit("semop"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR brk (2), +.BR mmap (2), +.BR shmctl (2), +.BR shmget (2), +.BR capabilities (7), +.BR shm_overview (7), +.BR sysvipc (7) diff --git a/man/man2/shutdown.2 b/man/man2/shutdown.2 new file mode 100644 index 0000000..9a33b32 --- /dev/null +++ b/man/man2/shutdown.2 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" $Id: shutdown.2,v 1.1.1.1 1999/03/21 22:52:23 freitag Exp $ +.\" +.\" Modified Sat Jul 24 09:57:55 1993 by Rik Faith +.\" Modified Tue Oct 22 22:04:51 1996 by Eric S. Raymond +.\" Modified 1998 by Andi Kleen +.\" +.TH shutdown 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +shutdown \- shut down part of a full-duplex connection +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int shutdown(int " sockfd ", int " how ); +.fi +.SH DESCRIPTION +The +.BR shutdown () +call causes all or part of a full-duplex connection on the socket +associated with +.I sockfd +to be shut down. +If +.I how +is +.BR SHUT_RD , +further receptions will be disallowed. +If +.I how +is +.BR SHUT_WR , +further transmissions will be disallowed. +If +.I how +is +.BR SHUT_RDWR , +further receptions and transmissions will be disallowed. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I sockfd +is not a valid file descriptor. +.TP +.B EINVAL +An invalid value was specified in +.I how +(but see BUGS). +.TP +.B ENOTCONN +The specified socket is not connected. +.TP +.B ENOTSOCK +The file descriptor +.I sockfd +does not refer to a socket. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.4BSD +(first appeared in 4.2BSD). +.SH NOTES +The constants +.BR SHUT_RD , +.BR SHUT_WR , +.B SHUT_RDWR +have the value 0, 1, 2, +respectively, and are defined in +.I +since glibc-2.1.91. +.SH BUGS +Checks for the validity of +.I how +are done in domain-specific code, +and before Linux 3.7 not all domains performed these checks. +.\" https://bugzilla.kernel.org/show_bug.cgi?id=47111 +Most notably, UNIX domain sockets simply ignored invalid values. +This problem was fixed for UNIX domain sockets +.\" commit fc61b928dc4d72176cf4bd4d30bf1d22e599aefc +.\" and for DECnet sockets in commit 46b66d7077b89fb4917ceef19b3f7dd86055c94a +in Linux 3.7. +.SH SEE ALSO +.BR close (2), +.BR connect (2), +.BR socket (2), +.BR socket (7) diff --git a/man/man2/sigaction.2 b/man/man2/sigaction.2 new file mode 100644 index 0000000..af4c3fb --- /dev/null +++ b/man/man2/sigaction.2 @@ -0,0 +1,1210 @@ +.\" Copyright (c) 1994,1995 Mike Battersby +.\" and Copyright 2004, 2005 Michael Kerrisk +.\" based on work by faith@cs.unc.edu +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified, aeb, 960424 +.\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond +.\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. +.\" Modified Sat May 8 17:40:19 1999 by Matthew Wilcox +.\" add POSIX.1b signals +.\" Modified Sat Dec 29 01:44:52 2001 by Evan Jones +.\" SA_ONSTACK +.\" Modified 2004-11-11 by Michael Kerrisk +.\" Added mention of SIGCONT under SA_NOCLDSTOP +.\" Added SA_NOCLDWAIT +.\" Modified 2004-11-17 by Michael Kerrisk +.\" Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags. +.\" Formatting fixes +.\" 2004-12-09, mtk, added SI_TKILL + other minor changes +.\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend() +.\" out of this page into separate pages. +.\" 2010-06-11 Andi Kleen, add hwpoison signal extensions +.\" 2010-06-11 mtk, improvements to discussion of various siginfo_t fields. +.\" 2015-01-17, Kees Cook +.\" Added notes on ptrace SIGTRAP and SYS_SECCOMP. +.\" +.TH sigaction 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigaction, rt_sigaction \- examine and change a signal action +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sigaction(int " signum , +.BI " const struct sigaction *_Nullable restrict " act , +.BI " struct sigaction *_Nullable restrict " oldact ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigaction (): +.nf + _POSIX_C_SOURCE +.fi +.P +.IR siginfo_t : +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +The +.BR sigaction () +system call is used to change the action taken by a process on +receipt of a specific signal. +(See +.BR signal (7) +for an overview of signals.) +.P +.I signum +specifies the signal and can be any valid signal except +.B SIGKILL +and +.BR SIGSTOP . +.P +If +.I act +is non-NULL, the new action for signal +.I signum +is installed from +.IR act . +If +.I oldact +is non-NULL, the previous action is saved in +.IR oldact . +.P +The +.I sigaction +structure is defined as something like: +.P +.in +4n +.EX +struct sigaction { + void (*sa_handler)(int); + void (*sa_sigaction)(int, siginfo_t *, void *); + sigset_t sa_mask; + int sa_flags; + void (*sa_restorer)(void); +}; +.EE +.in +.P +On some architectures a union is involved: do not assign to both +.I sa_handler +and +.IR sa_sigaction . +.P +The +.I sa_restorer +field is not intended for application use. +(POSIX does not specify a +.I sa_restorer +field.) +Some further details of the purpose of this field can be found in +.BR sigreturn (2). +.P +.I sa_handler +specifies the action to be associated with +.I signum +and can be one of the following: +.IP \[bu] 3 +.B SIG_DFL +for the default action. +.IP \[bu] +.B SIG_IGN +to ignore this signal. +.IP \[bu] +A pointer to a signal handling function. +This function receives the signal number as its only argument. +.P +If +.B SA_SIGINFO +is specified in +.IR sa_flags , +then +.I sa_sigaction +(instead of +.IR sa_handler ) +specifies the signal-handling function for +.IR signum . +This function receives three arguments, as described below. +.P +.I sa_mask +specifies a mask of signals which should be blocked +(i.e., added to the signal mask of the thread in which +the signal handler is invoked) +during execution of the signal handler. +In addition, the signal which triggered the handler +will be blocked, unless the +.B SA_NODEFER +flag is used. +.P +.I sa_flags +specifies a set of flags which modify the behavior of the signal. +It is formed by the bitwise OR of zero or more of the following: +.TP +.B SA_NOCLDSTOP +If +.I signum +is +.BR SIGCHLD , +do not receive notification when child processes stop (i.e., when they +receive one of +.BR SIGSTOP ", " SIGTSTP ", " SIGTTIN , +or +.BR SIGTTOU ) +or resume (i.e., they receive +.BR SIGCONT ) +(see +.BR wait (2)). +This flag is meaningful only when establishing a handler for +.BR SIGCHLD . +.TP +.BR SA_NOCLDWAIT " (since Linux 2.6)" +.\" To be precise: Linux 2.5.60 -- MTK +If +.I signum +is +.BR SIGCHLD , +do not transform children into zombies when they terminate. +See also +.BR waitpid (2). +This flag is meaningful only when establishing a handler for +.BR SIGCHLD , +or when setting that signal's disposition to +.BR SIG_DFL . +.IP +If the +.B SA_NOCLDWAIT +flag is set when establishing a handler for +.BR SIGCHLD , +POSIX.1 leaves it unspecified whether a +.B SIGCHLD +signal is generated when a child process terminates. +On Linux, a +.B SIGCHLD +signal is generated in this case; +on some other implementations, it is not. +.TP +.B SA_NODEFER +Do not add the signal to the thread's signal mask while the +handler is executing, unless the signal is specified in +.IR act.sa_mask . +Consequently, a further instance of the signal may be delivered +to the thread while it is executing the handler. +This flag is meaningful only when establishing a signal handler. +.IP +.B SA_NOMASK +is an obsolete, nonstandard synonym for this flag. +.TP +.B SA_ONSTACK +Call the signal handler on an alternate signal stack provided by +.BR sigaltstack (2). +If an alternate stack is not available, the default stack will be used. +This flag is meaningful only when establishing a signal handler. +.TP +.B SA_RESETHAND +Restore the signal action to the default upon entry to the signal handler. +This flag is meaningful only when establishing a signal handler. +.IP +.B SA_ONESHOT +is an obsolete, nonstandard synonym for this flag. +.TP +.B SA_RESTART +Provide behavior compatible with BSD signal semantics by making certain +system calls restartable across signals. +This flag is meaningful only when establishing a signal handler. +See +.BR signal (7) +for a discussion of system call restarting. +.TP +.B SA_RESTORER +.IR "Not intended for application use" . +This flag is used by C libraries to indicate that the +.I sa_restorer +field contains the address of a "signal trampoline". +See +.BR sigreturn (2) +for more details. +.TP +.BR SA_SIGINFO " (since Linux 2.2)" +The signal handler takes three arguments, not one. +In this case, +.I sa_sigaction +should be set instead of +.IR sa_handler . +This flag is meaningful only when establishing a signal handler. +.\" (The +.\" .I sa_sigaction +.\" field was added in Linux 2.1.86.) +.\" +.TP +.BR SA_UNSUPPORTED " (since Linux 5.11)" +Used to dynamically probe for flag bit support. +.IP +If an attempt to register a handler succeeds with this flag set in +.I act\->sa_flags +alongside other flags that are potentially unsupported by the kernel, +and an immediately subsequent +.BR sigaction () +call specifying the same signal number and with a non-NULL +.I oldact +argument yields +.B SA_UNSUPPORTED +.I clear +in +.IR oldact\->sa_flags , +then +.I oldact\->sa_flags +may be used as a bitmask +describing which of the potentially unsupported flags are, +in fact, supported. +See the section "Dynamically probing for flag bit support" +below for more details. +.TP +.BR SA_EXPOSE_TAGBITS " (since Linux 5.11)" +Normally, when delivering a signal, +an architecture-specific set of tag bits are cleared from the +.I si_addr +field of +.IR siginfo_t . +If this flag is set, +an architecture-specific subset of the tag bits will be preserved in +.IR si_addr . +.IP +Programs that need to be compatible with Linux versions older than 5.11 +must use +.B SA_UNSUPPORTED +to probe for support. +.SS The siginfo_t argument to a SA_SIGINFO handler +When the +.B SA_SIGINFO +flag is specified in +.IR act.sa_flags , +the signal handler address is passed via the +.I act.sa_sigaction +field. +This handler takes three arguments, as follows: +.P +.in +4n +.EX +void +handler(int sig, siginfo_t *info, void *ucontext) +{ + ... +} +.EE +.in +.P +These three arguments are as follows +.TP +.I sig +The number of the signal that caused invocation of the handler. +.TP +.I info +A pointer to a +.IR siginfo_t , +which is a structure containing further information about the signal, +as described below. +.TP +.I ucontext +This is a pointer to a +.I ucontext_t +structure, cast to \fIvoid\ *\fP. +The structure pointed to by this field contains +signal context information that was saved +on the user-space stack by the kernel; for details, see +.BR sigreturn (2). +Further information about the +.I ucontext_t +structure can be found in +.BR getcontext (3) +and +.BR signal (7). +Commonly, the handler function doesn't make any use of the third argument. +.P +The +.I siginfo_t +data type is a structure with the following fields: +.P +.in +4n +.EX +siginfo_t { + int si_signo; /* Signal number */ + int si_errno; /* An errno value */ + int si_code; /* Signal code */ + int si_trapno; /* Trap number that caused + hardware\-generated signal + (unused on most architectures) */ +.\" FIXME +.\" The siginfo_t 'si_trapno' field seems to be used +.\" only on SPARC and Alpha; this page could use +.\" a little more detail on its purpose there. + pid_t si_pid; /* Sending process ID */ + uid_t si_uid; /* Real user ID of sending process */ + int si_status; /* Exit value or signal */ + clock_t si_utime; /* User time consumed */ + clock_t si_stime; /* System time consumed */ + union sigval si_value; /* Signal value */ + int si_int; /* POSIX.1b signal */ + void *si_ptr; /* POSIX.1b signal */ + int si_overrun; /* Timer overrun count; + POSIX.1b timers */ + int si_timerid; /* Timer ID; POSIX.1b timers */ +.\" In the kernel: si_tid + void *si_addr; /* Memory location which caused fault */ + long si_band; /* Band event (was \fIint\fP in + glibc 2.3.2 and earlier) */ + int si_fd; /* File descriptor */ + short si_addr_lsb; /* Least significant bit of address + (since Linux 2.6.32) */ + void *si_lower; /* Lower bound when address violation + occurred (since Linux 3.19) */ + void *si_upper; /* Upper bound when address violation + occurred (since Linux 3.19) */ + int si_pkey; /* Protection key on PTE that caused + fault (since Linux 4.6) */ + void *si_call_addr; /* Address of system call instruction + (since Linux 3.5) */ + int si_syscall; /* Number of attempted system call + (since Linux 3.5) */ + unsigned int si_arch; /* Architecture of attempted system call + (since Linux 3.5) */ +} +.EE +.in +.P +.IR si_signo ", " si_errno " and " si_code +are defined for all signals. +.RI ( si_errno +is generally unused on Linux.) +The rest of the struct may be a union, so that one should +read only the fields that are meaningful for the given signal: +.IP \[bu] 3 +Signals sent with +.BR kill (2) +and +.BR sigqueue (3) +fill in +.IR si_pid " and " si_uid . +In addition, signals sent with +.BR sigqueue (3) +fill in +.IR si_int " and " si_ptr +with the values specified by the sender of the signal; +see +.BR sigqueue (3) +for more details. +.IP \[bu] +Signals sent by POSIX.1b timers (since Linux 2.6) fill in +.I si_overrun +and +.IR si_timerid . +The +.I si_timerid +field is an internal ID used by the kernel to identify +the timer; it is not the same as the timer ID returned by +.BR timer_create (2). +The +.I si_overrun +field is the timer overrun count; +this is the same information as is obtained by a call to +.BR timer_getoverrun (2). +These fields are nonstandard Linux extensions. +.IP \[bu] +Signals sent for message queue notification (see the description of +.B SIGEV_SIGNAL +in +.BR mq_notify (3)) +fill in +.IR si_int / si_ptr , +with the +.I sigev_value +supplied to +.BR mq_notify (3); +.IR si_pid , +with the process ID of the message sender; and +.IR si_uid , +with the real user ID of the message sender. +.IP \[bu] +.B SIGCHLD +fills in +.IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime , +providing information about the child. +The +.I si_pid +field is the process ID of the child; +.I si_uid +is the child's real user ID. +The +.I si_status +field contains the exit status of the child (if +.I si_code +is +.BR CLD_EXITED ), +or the signal number that caused the process to change state. +The +.I si_utime +and +.I si_stime +contain the user and system CPU time used by the child process; +these fields do not include the times used by waited-for children (unlike +.BR getrusage (2) +and +.BR times (2)). +Up to Linux 2.6, and since Linux 2.6.27, these fields report +CPU time in units of +.IR sysconf(_SC_CLK_TCK) . +In Linux 2.6 kernels before Linux 2.6.27, +a bug meant that these fields reported time in units +of the (configurable) system jiffy (see +.BR time (7)). +.\" FIXME . +.\" When si_utime and si_stime where originally implemented, the +.\" measurement unit was HZ, which was the same as clock ticks +.\" (sysconf(_SC_CLK_TCK)). In Linux 2.6, HZ became configurable, and +.\" was *still* used as the unit to return the info these fields, +.\" with the result that the field values depended on the +.\" configured HZ. Of course, the should have been measured in +.\" USER_HZ instead, so that sysconf(_SC_CLK_TCK) could be used to +.\" convert to seconds. I have a queued patch to fix this: +.\" http://thread.gmane.org/gmane.linux.kernel/698061/ . +.\" This patch made it into Linux 2.6.27. +.\" But note that these fields still don't return the times of +.\" waited-for children (as is done by getrusage() and times() +.\" and wait4()). Solaris 8 does include child times. +.IP \[bu] +.BR SIGILL , +.BR SIGFPE , +.BR SIGSEGV , +.BR SIGBUS , +and +.B SIGTRAP +fill in +.I si_addr +with the address of the fault. +On some architectures, +these signals also fill in the +.I si_trapno +field. +.IP +Some suberrors of +.BR SIGBUS , +in particular +.B BUS_MCEERR_AO +and +.BR BUS_MCEERR_AR , +also fill in +.IR si_addr_lsb . +This field indicates the least significant bit of the reported address +and therefore the extent of the corruption. +For example, if a full page was corrupted, +.I si_addr_lsb +contains +.IR log2(sysconf(_SC_PAGESIZE)) . +When +.B SIGTRAP +is delivered in response to a +.BR ptrace (2) +event (PTRACE_EVENT_foo), +.I si_addr +is not populated, but +.I si_pid +and +.I si_uid +are populated with the respective process ID and user ID responsible for +delivering the trap. +In the case of +.BR seccomp (2), +the tracee will be shown as delivering the event. +.B BUS_MCEERR_* +and +.I si_addr_lsb +are Linux-specific extensions. +.IP +The +.B SEGV_BNDERR +suberror of +.B SIGSEGV +populates +.I si_lower +and +.IR si_upper . +.IP +The +.B SEGV_PKUERR +suberror of +.B SIGSEGV +populates +.IR si_pkey . +.IP \[bu] +.BR SIGIO / SIGPOLL +(the two names are synonyms on Linux) +fills in +.I si_band +and +.IR si_fd . +The +.I si_band +event is a bit mask containing the same values as are filled in the +.I revents +field by +.BR poll (2). +The +.I si_fd +field indicates the file descriptor for which the I/O event occurred; +for further details, see the description of +.B F_SETSIG +in +.BR fcntl (2). +.IP \[bu] +.BR SIGSYS , +generated (since Linux 3.5) +.\" commit a0727e8ce513fe6890416da960181ceb10fbfae6 +when a seccomp filter returns +.BR SECCOMP_RET_TRAP , +fills in +.IR si_call_addr , +.IR si_syscall , +.IR si_arch , +.IR si_errno , +and other fields as described in +.BR seccomp (2). +.\" +.SS +The si_code field +The +.I si_code +field inside the +.I siginfo_t +argument that is passed to a +.B SA_SIGINFO +signal handler is a value (not a bit mask) +indicating why this signal was sent. +For a +.BR ptrace (2) +event, +.I si_code +will contain +.B SIGTRAP +and have the ptrace event in the high byte: +.P +.in +4n +.EX +(SIGTRAP | PTRACE_EVENT_foo << 8). +.EE +.in +.P +For a +.RB non- ptrace (2) +event, the values that can appear in +.I si_code +are described in the remainder of this section. +Since glibc 2.20, +the definitions of most of these symbols are obtained from +.I +by defining feature test macros (before including +.I any +header file) as follows: +.IP \[bu] 3 +.B _XOPEN_SOURCE +with the value 500 or greater; +.IP \[bu] +.B _XOPEN_SOURCE +and +.BR _XOPEN_SOURCE_EXTENDED ; +or +.IP \[bu] +.B _POSIX_C_SOURCE +with the value 200809L or greater. +.P +For the +.B TRAP_* +constants, the symbol definitions are provided only in the first two cases. +Before glibc 2.20, no feature test macros were required to obtain these symbols. +.P +For a regular signal, the following list shows the values which can be +placed in +.I si_code +for any signal, along with the reason that the signal was generated. +.RS 4 +.TP +.B SI_USER +.BR kill (2). +.TP +.B SI_KERNEL +Sent by the kernel. +.TP +.B SI_QUEUE +.BR sigqueue (3). +.TP +.B SI_TIMER +POSIX timer expired. +.TP +.BR SI_MESGQ " (since Linux 2.6.6)" +POSIX message queue state changed; see +.BR mq_notify (3). +.TP +.B SI_ASYNCIO +AIO completed. +.TP +.B SI_SIGIO +Queued +.B SIGIO +(only up to Linux 2.2; from Linux 2.4 onward +.BR SIGIO / SIGPOLL +fills in +.I si_code +as described below). +.TP +.BR SI_TKILL " (since Linux 2.4.19)" +.BR tkill (2) +or +.BR tgkill (2). +.\" SI_DETHREAD is defined in Linux 2.6.9 sources, but isn't implemented +.\" It appears to have been an idea that was tried during 2.5.6 +.\" through to Linux 2.5.24 and then was backed out. +.RE +.P +The following values can be placed in +.I si_code +for a +.B SIGILL +signal: +.RS 4 +.TP +.B ILL_ILLOPC +Illegal opcode. +.TP +.B ILL_ILLOPN +Illegal operand. +.TP +.B ILL_ILLADR +Illegal addressing mode. +.TP +.B ILL_ILLTRP +Illegal trap. +.TP +.B ILL_PRVOPC +Privileged opcode. +.TP +.B ILL_PRVREG +Privileged register. +.TP +.B ILL_COPROC +Coprocessor error. +.TP +.B ILL_BADSTK +Internal stack error. +.RE +.P +The following values can be placed in +.I si_code +for a +.B SIGFPE +signal: +.RS 4 +.TP +.B FPE_INTDIV +Integer divide by zero. +.TP +.B FPE_INTOVF +Integer overflow. +.TP +.B FPE_FLTDIV +Floating-point divide by zero. +.TP +.B FPE_FLTOVF +Floating-point overflow. +.TP +.B FPE_FLTUND +Floating-point underflow. +.TP +.B FPE_FLTRES +Floating-point inexact result. +.TP +.B FPE_FLTINV +Floating-point invalid operation. +.TP +.B FPE_FLTSUB +Subscript out of range. +.RE +.P +The following values can be placed in +.I si_code +for a +.B SIGSEGV +signal: +.RS 4 +.TP +.B SEGV_MAPERR +Address not mapped to object. +.TP +.B SEGV_ACCERR +Invalid permissions for mapped object. +.TP +.BR SEGV_BNDERR " (since Linux 3.19)" +.\" commit ee1b58d36aa1b5a79eaba11f5c3633c88231da83 +Failed address bound checks. +.TP +.BR SEGV_PKUERR " (since Linux 4.6)" +.\" commit cd0ea35ff5511cde299a61c21a95889b4a71464e +Access was denied by memory protection keys. +See +.BR pkeys (7). +The protection key which applied to this access is available via +.IR si_pkey . +.RE +.P +The following values can be placed in +.I si_code +for a +.B SIGBUS +signal: +.RS 4 +.TP +.B BUS_ADRALN +Invalid address alignment. +.TP +.B BUS_ADRERR +Nonexistent physical address. +.TP +.B BUS_OBJERR +Object-specific hardware error. +.TP +.BR BUS_MCEERR_AR " (since Linux 2.6.32)" +Hardware memory error consumed on a machine check; action required. +.TP +.BR BUS_MCEERR_AO " (since Linux 2.6.32)" +Hardware memory error detected in process but not consumed; action optional. +.RE +.P +The following values can be placed in +.I si_code +for a +.B SIGTRAP +signal: +.RS 4 +.TP +.B TRAP_BRKPT +Process breakpoint. +.TP +.B TRAP_TRACE +Process trace trap. +.TP +.BR TRAP_BRANCH " (since Linux 2.4, IA64 only)" +Process taken branch trap. +.TP +.BR TRAP_HWBKPT " (since Linux 2.4, IA64 only)" +Hardware breakpoint/watchpoint. +.RE +.P +The following values can be placed in +.I si_code +for a +.B SIGCHLD +signal: +.RS 4 +.TP +.B CLD_EXITED +Child has exited. +.TP +.B CLD_KILLED +Child was killed. +.TP +.B CLD_DUMPED +Child terminated abnormally. +.TP +.B CLD_TRAPPED +Traced child has trapped. +.TP +.B CLD_STOPPED +Child has stopped. +.TP +.BR CLD_CONTINUED " (since Linux 2.6.9)" +Stopped child has continued. +.RE +.P +The following values can be placed in +.I si_code +for a +.BR SIGIO / SIGPOLL +signal: +.RS 4 +.TP +.B POLL_IN +Data input available. +.TP +.B POLL_OUT +Output buffers available. +.TP +.B POLL_MSG +Input message available. +.TP +.B POLL_ERR +I/O error. +.TP +.B POLL_PRI +High priority input available. +.TP +.B POLL_HUP +Device disconnected. +.RE +.P +The following value can be placed in +.I si_code +for a +.B SIGSYS +signal: +.RS 4 +.TP +.BR SYS_SECCOMP " (since Linux 3.5)" +Triggered by a +.BR seccomp (2) +filter rule. +.RE +.SS Dynamically probing for flag bit support +The +.BR sigaction () +call on Linux accepts unknown bits set in +.I act\->sa_flags +without error. +The behavior of the kernel starting with Linux 5.11 is that a second +.BR sigaction () +will clear unknown bits from +.IR oldact\->sa_flags . +However, historically, a second +.BR sigaction () +call would typically leave those bits set in +.IR oldact\->sa_flags . +.P +This means that support for new flags cannot be detected +simply by testing for a flag in +.IR sa_flags , +and a program must test that +.B SA_UNSUPPORTED +has been cleared before relying on the contents of +.IR sa_flags . +.P +Since the behavior of the signal handler cannot be guaranteed +unless the check passes, +it is wise to either block the affected signal +while registering the handler and performing the check in this case, +or where this is not possible, +for example if the signal is synchronous, to issue the second +.BR sigaction () +in the signal handler itself. +.P +In kernels that do not support a specific flag, +the kernel's behavior is as if the flag was not set, +even if the flag was set in +.IR act\->sa_flags . +.P +The flags +.BR SA_NOCLDSTOP , +.BR SA_NOCLDWAIT , +.BR SA_SIGINFO , +.BR SA_ONSTACK , +.BR SA_RESTART , +.BR SA_NODEFER , +.BR SA_RESETHAND , +and, if defined by the architecture, +.B SA_RESTORER +may not be reliably probed for using this mechanism, +because they were introduced before Linux 5.11. +However, in general, programs may assume that these flags are supported, +since they have all been supported since Linux 2.6, +which was released in the year 2003. +.P +See EXAMPLES below for a demonstration of the use of +.BR SA_UNSUPPORTED . +.SH RETURN VALUE +.BR sigaction () +returns 0 on success; on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.IR act " or " oldact +points to memory which is not a valid part of the process address space. +.TP +.B EINVAL +An invalid signal was specified. +This will also be generated if an attempt +is made to change the action for +.BR SIGKILL " or " SIGSTOP , +which cannot be caught or ignored. +.SH VERSIONS +.SS C library/kernel differences +The glibc wrapper function for +.BR sigaction () +gives an error +.RB ( EINVAL ) +on attempts to change the disposition of the two real-time signals +used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.P +On architectures where the signal trampoline resides in the C library, +the glibc wrapper function for +.BR sigaction () +places the address of the trampoline code in the +.I act.sa_restorer +field and sets the +.B SA_RESTORER +flag in the +.I act.sa_flags +field. +See +.BR sigreturn (2). +.P +The original Linux system call was named +.BR sigaction (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.I sigset_t +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigaction (), +was added to support an enlarged +.I sigset_t +type. +The new system call takes a fourth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal sets in +.I act.sa_mask +and +.IR oldact.sa_mask . +This argument is currently required to have the value +.I sizeof(sigset_t) +(or the error +.B EINVAL +results). +The glibc +.BR sigaction () +wrapper function hides these details from us, transparently calling +.BR rt_sigaction () +when the kernel provides it. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVr4 does not document the EINTR condition. +.P +POSIX.1-1990 disallowed setting the action for +.B SIGCHLD +to +.BR SIG_IGN . +POSIX.1-2001 and later allow this possibility, so that ignoring +.B SIGCHLD +can be used to prevent the creation of zombies (see +.BR wait (2)). +Nevertheless, the historical BSD and System\ V behaviors for ignoring +.B SIGCHLD +differ, so that the only completely portable method of ensuring that +terminated children do not become zombies is to catch the +.B SIGCHLD +signal and perform a +.BR wait (2) +or similar. +.P +POSIX.1-1990 specified only +.BR SA_NOCLDSTOP . +POSIX.1-2001 added +.BR SA_NOCLDWAIT , +.BR SA_NODEFER , +.BR SA_ONSTACK , +.BR SA_RESETHAND , +.BR SA_RESTART , +and +.B SA_SIGINFO +as XSI extensions. +POSIX.1-2008 moved +.BR SA_NODEFER , +.BR SA_RESETHAND , +.BR SA_RESTART , +and +.B SA_SIGINFO +to the base specifications. +Use of these latter values in +.I sa_flags +may be less portable in applications intended for older +UNIX implementations. +.P +The +.B SA_RESETHAND +flag is compatible with the SVr4 flag of the same name. +.P +The +.B SA_NODEFER +flag is compatible with the SVr4 flag of the same name under kernels +1.3.9 and later. +On older kernels the Linux implementation +allowed the receipt of any signal, not just the one we are installing +(effectively overriding any +.I sa_mask +settings). +.SH NOTES +A child created via +.BR fork (2) +inherits a copy of its parent's signal dispositions. +During an +.BR execve (2), +the dispositions of handled signals are reset to the default; +the dispositions of ignored signals are left unchanged. +.P +According to POSIX, the behavior of a process is undefined after it +ignores a +.BR SIGFPE , +.BR SIGILL , +or +.B SIGSEGV +signal that was not generated by +.BR kill (2) +or +.BR raise (3). +Integer division by zero has undefined result. +On some architectures it will generate a +.B SIGFPE +signal. +(Also dividing the most negative integer by \-1 may generate +.BR SIGFPE .) +Ignoring this signal might lead to an endless loop. +.P +.BR sigaction () +can be called with a NULL second argument to query the current signal +handler. +It can also be used to check whether a given signal is valid for +the current machine by calling it with NULL second and third arguments. +.P +It is not possible to block +.BR SIGKILL " or " SIGSTOP +(by specifying them in +.IR sa_mask ). +Attempts to do so are silently ignored. +.P +See +.BR sigsetops (3) +for details on manipulating signal sets. +.P +See +.BR signal\-safety (7) +for a list of the async-signal-safe functions that can be +safely called inside from inside a signal handler. +.\" +.SS Undocumented +Before the introduction of +.BR SA_SIGINFO , +it was also possible to get some additional information about the signal. +This was done by providing an +.I sa_handler +signal handler with a second argument of type +.IR "struct sigcontext" , +which is the same structure as the one that is passed in the +.I uc_mcontext +field of the +.I ucontext +structure that is passed (via a pointer) in the third argument of the +.I sa_sigaction +handler. +See the relevant Linux kernel sources for details. +This use is obsolete now. +.SH BUGS +When delivering a signal with a +.B SA_SIGINFO +handler, +the kernel does not always provide meaningful values +for all of the fields of the +.I siginfo_t +that are relevant for that signal. +.P +Up to and including Linux 2.6.13, specifying +.B SA_NODEFER +in +.I sa_flags +prevents not only the delivered signal from being masked during +execution of the handler, but also the signals specified in +.IR sa_mask . +This bug was fixed in Linux 2.6.14. +.\" commit 69be8f189653cd81aae5a74e26615b12871bb72e +.SH EXAMPLES +See +.BR mprotect (2). +.SS Probing for flag support +The following example program exits with status +.B EXIT_SUCCESS +if +.B SA_EXPOSE_TAGBITS +is determined to be supported, and +.B EXIT_FAILURE +otherwise. +.P +.\" SRC BEGIN (sigaction.c) +.EX +#include +#include +#include +#include +\& +void +handler(int signo, siginfo_t *info, void *context) +{ + struct sigaction oldact; +\& + if (sigaction(SIGSEGV, NULL, &oldact) == \-1 + || (oldact.sa_flags & SA_UNSUPPORTED) + || !(oldact.sa_flags & SA_EXPOSE_TAGBITS)) + { + _exit(EXIT_FAILURE); + } + _exit(EXIT_SUCCESS); +} +\& +int +main(void) +{ + struct sigaction act = { 0 }; +\& + act.sa_flags = SA_SIGINFO | SA_UNSUPPORTED | SA_EXPOSE_TAGBITS; + act.sa_sigaction = &handler; + if (sigaction(SIGSEGV, &act, NULL) == \-1) { + perror("sigaction"); + exit(EXIT_FAILURE); + } +\& + raise(SIGSEGV); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR kill (1), +.BR kill (2), +.BR pause (2), +.BR pidfd_send_signal (2), +.BR restart_syscall (2), +.BR seccomp (2), +.BR sigaltstack (2), +.BR signal (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigreturn (2), +.BR sigsuspend (2), +.BR wait (2), +.BR killpg (3), +.BR raise (3), +.BR siginterrupt (3), +.BR sigqueue (3), +.BR sigsetops (3), +.BR sigvec (3), +.BR core (5), +.BR signal (7) diff --git a/man/man2/sigaltstack.2 b/man/man2/sigaltstack.2 new file mode 100644 index 0000000..166999f --- /dev/null +++ b/man/man2/sigaltstack.2 @@ -0,0 +1,362 @@ +'\" t +.\" Copyright (c) 2001, 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" aeb, various minor fixes +.TH sigaltstack 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigaltstack \- set and/or get signal stack context +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sigaltstack(const stack_t *_Nullable restrict " ss , +.BI " stack_t *_Nullable restrict " old_ss ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigaltstack (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR sigaltstack () +allows a thread to define a new alternate +signal stack and/or retrieve the state of an existing +alternate signal stack. +An alternate signal stack is used during the +execution of a signal handler if the establishment of that handler (see +.BR sigaction (2)) +requested it. +.P +The normal sequence of events for using an alternate signal stack +is the following: +.TP 3 +1. +Allocate an area of memory to be used for the alternate +signal stack. +.TP +2. +Use +.BR sigaltstack () +to inform the system of the existence and +location of the alternate signal stack. +.TP +3. +When establishing a signal handler using +.BR sigaction (2), +inform the system that the signal handler should be executed +on the alternate signal stack by +specifying the \fBSA_ONSTACK\fP flag. +.P +The \fIss\fP argument is used to specify a new +alternate signal stack, while the \fIold_ss\fP argument +is used to retrieve information about the currently +established signal stack. +If we are interested in performing just one +of these tasks, then the other argument can be specified as NULL. +.P +The +.I stack_t +type used to type the arguments of this function is defined as follows: +.P +.in +4n +.EX +typedef struct { + void *ss_sp; /* Base address of stack */ + int ss_flags; /* Flags */ + size_t ss_size; /* Number of bytes in stack */ +} stack_t; +.EE +.in +.P +To establish a new alternate signal stack, +the fields of this structure are set as follows: +.TP +.I ss.ss_flags +This field contains either 0, or the following flag: +.RS +.TP +.BR SS_AUTODISARM " (since Linux 4.7)" +.\" commit 2a74213838104a41588d86fd5e8d344972891ace +.\" See tools/testing/selftests/sigaltstack/sas.c in kernel sources +Clear the alternate signal stack settings on entry to the signal handler. +When the signal handler returns, +the previous alternate signal stack settings are restored. +.IP +This flag was added in order to make it safe +to switch away from the signal handler with +.BR swapcontext (3). +Without this flag, a subsequently handled signal will corrupt +the state of the switched-away signal handler. +On kernels where this flag is not supported, +.BR sigaltstack () +fails with the error +.B EINVAL +when this flag is supplied. +.RE +.TP +.I ss.ss_sp +This field specifies the starting address of the stack. +When a signal handler is invoked on the alternate stack, +the kernel automatically aligns the address given in \fIss.ss_sp\fP +to a suitable address boundary for the underlying hardware architecture. +.TP +.I ss.ss_size +This field specifies the size of the stack. +The constant \fBSIGSTKSZ\fP is defined to be large enough +to cover the usual size requirements for an alternate signal stack, +and the constant \fBMINSIGSTKSZ\fP defines the minimum +size required to execute a signal handler. +.P +To disable an existing stack, specify \fIss.ss_flags\fP +as \fBSS_DISABLE\fP. +In this case, the kernel ignores any other flags in +.I ss.ss_flags +and the remaining fields +in \fIss\fP. +.P +If \fIold_ss\fP is not NULL, then it is used to return information about +the alternate signal stack which was in effect prior to the +call to +.BR sigaltstack (). +The \fIold_ss.ss_sp\fP and \fIold_ss.ss_size\fP fields return the starting +address and size of that stack. +The \fIold_ss.ss_flags\fP may return either of the following values: +.TP +.B SS_ONSTACK +The thread is currently executing on the alternate signal stack. +(Note that it is not possible +to change the alternate signal stack if the thread is +currently executing on it.) +.TP +.B SS_DISABLE +The alternate signal stack is currently disabled. +.IP +Alternatively, this value is returned if the thread is currently +executing on an alternate signal stack that was established using the +.B SS_AUTODISARM +flag. +In this case, it is safe to switch away from the signal handler with +.BR swapcontext (3). +It is also possible to set up a different alternative signal stack +using a further call to +.BR sigaltstack (). +.\" FIXME Was it intended that one can set up a different alternative +.\" signal stack in this scenario? (In passing, if one does this, the +.\" sigaltstack(NULL, &old_ss) now returns old_ss.ss_flags==SS_AUTODISARM +.\" rather than old_ss.ss_flags==SS_DISABLE. The API design here seems +.\" confusing... +.TP +.B SS_AUTODISARM +The alternate signal stack has been marked to be autodisarmed +as described above. +.P +By specifying +.I ss +as NULL, and +.I old_ss +as a non-NULL value, one can obtain the current settings for +the alternate signal stack without changing them. +.SH RETURN VALUE +.BR sigaltstack () +returns 0 on success, or \-1 on failure with +\fIerrno\fP set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Either \fIss\fP or \fIold_ss\fP is not NULL and points to an area +outside of the process's address space. +.TP +.B EINVAL +\fIss\fP is not NULL and the \fIss_flags\fP field contains +an invalid flag. +.TP +.B ENOMEM +The specified size of the new alternate signal stack +.I ss.ss_size +was less than +.BR MINSIGSTKSZ . +.TP +.B EPERM +An attempt was made to change the alternate signal stack while +it was active (i.e., the thread was already executing +on the current alternate signal stack). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigaltstack () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.P +.B SS_AUTODISARM +is a Linux extension. +.SH HISTORY +POSIX.1-2001, SUSv2, SVr4. +.SH NOTES +The most common usage of an alternate signal stack is to handle the +.B SIGSEGV +signal that is generated if the space available for the +standard stack is exhausted: in this case, a signal handler for +.B SIGSEGV +cannot be invoked on the standard stack; if we wish to handle it, +we must use an alternate signal stack. +.P +Establishing an alternate signal stack is useful if a thread +expects that it may exhaust its standard stack. +This may occur, for example, because the stack grows so large +that it encounters the upwardly growing heap, or it reaches a +limit established by a call to \fB\%setrlimit(RLIMIT_STACK, &rlim)\fP. +If the standard stack is exhausted, the kernel sends +the thread a \fBSIGSEGV\fP signal. +In these circumstances the only way to catch this signal is +on an alternate signal stack. +.P +On most hardware architectures supported by Linux, stacks grow +downward. +.BR sigaltstack () +automatically takes account +of the direction of stack growth. +.P +Functions called from a signal handler executing on an alternate +signal stack will also use the alternate signal stack. +(This also applies to any handlers invoked for other signals while +the thread is executing on the alternate signal stack.) +Unlike the standard stack, the system does not +automatically extend the alternate signal stack. +Exceeding the allocated size of the alternate signal stack will +lead to unpredictable results. +.P +A successful call to +.BR execve (2) +removes any existing alternate +signal stack. +A child process created via +.BR fork (2) +inherits a copy of its parent's alternate signal stack settings. +The same is also true for a child process created using +.BR clone (2), +unless the clone flags include +.B CLONE_VM +and do not include +.BR CLONE_VFORK , +in which case any alternate signal stack that was established in the parent +is disabled in the child process. +.P +.BR sigaltstack () +supersedes the older +.BR sigstack () +call. +For backward compatibility, glibc also provides +.BR sigstack (). +All new applications should be written using +.BR sigaltstack (). +.SS History +4.2BSD had a +.BR sigstack () +system call. +It used a slightly +different struct, and had the major disadvantage that the caller +had to know the direction of stack growth. +.SH BUGS +In Linux 2.2 and earlier, the only flag that could be specified +in +.I ss.sa_flags +was +.BR SS_DISABLE . +In the lead up to the release of the Linux 2.4 kernel, +.\" Linux 2.3.40 +.\" After quite a bit of web and mail archive searching, +.\" I could not find the patch on any mailing list, and I +.\" could find no place where the rationale for this change +.\" explained -- mtk +a change was made to allow +.BR sigaltstack () +to allow +.I ss.ss_flags==SS_ONSTACK +with the same meaning as +.I ss.ss_flags==0 +(i.e., the inclusion of +.B SS_ONSTACK +in +.I ss.ss_flags +is a no-op). +On other implementations, and according to POSIX.1, +.B SS_ONSTACK +appears only as a reported flag in +.IR old_ss.ss_flags . +On Linux, there is no need ever to specify +.B SS_ONSTACK +in +.IR ss.ss_flags , +and indeed doing so should be avoided on portability grounds: +various other systems +.\" See the source code of Illumos and FreeBSD, for example. +give an error if +.B SS_ONSTACK +is specified in +.IR ss.ss_flags . +.SH EXAMPLES +The following code segment demonstrates the use of +.BR sigaltstack () +(and +.BR sigaction (2)) +to install an alternate signal stack that is employed by a handler +for the +.B SIGSEGV +signal: +.P +.in +4n +.EX +stack_t ss; +\& +ss.ss_sp = malloc(SIGSTKSZ); +if (ss.ss_sp == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); +} +\& +ss.ss_size = SIGSTKSZ; +ss.ss_flags = 0; +if (sigaltstack(&ss, NULL) == \-1) { + perror("sigaltstack"); + exit(EXIT_FAILURE); +} +\& +sa.sa_flags = SA_ONSTACK; +sa.sa_handler = handler(); /* Address of a signal handler */ +sigemptyset(&sa.sa_mask); +if (sigaction(SIGSEGV, &sa, NULL) == \-1) { + perror("sigaction"); + exit(EXIT_FAILURE); +} +.EE +.in +.SH SEE ALSO +.BR execve (2), +.BR setrlimit (2), +.BR sigaction (2), +.BR siglongjmp (3), +.BR sigsetjmp (3), +.BR signal (7) diff --git a/man/man2/signal.2 b/man/man2/signal.2 new file mode 100644 index 0000000..102caaa --- /dev/null +++ b/man/man2/signal.2 @@ -0,0 +1,280 @@ +.\" Copyright (c) 2000 Andries Brouwer +.\" and Copyright (c) 2007 Michael Kerrisk +.\" and Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" based on work by Rik Faith +.\" and Mike Battersby . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2004-11-19, mtk: +.\" added pointer to sigaction.2 for details of ignoring SIGCHLD +.\" 2007-06-03, mtk: strengthened portability warning, and rewrote +.\" various sections. +.\" 2008-07-11, mtk: rewrote and expanded portability discussion. +.\" +.TH signal 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +signal \- ANSI C signal handling +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B typedef void (*sighandler_t)(int); +.P +.BI "sighandler_t signal(int " signum ", sighandler_t " handler ); +.fi +.SH DESCRIPTION +.BR WARNING : +the behavior of +.BR signal () +varies across UNIX versions, +and has also varied historically across different versions of Linux. +\fBAvoid its use\fP: use +.BR sigaction (2) +instead. +See \fIPortability\fP below. +.P +.BR signal () +sets the disposition of the signal +.I signum +to +.IR handler , +which is either +.BR SIG_IGN , +.BR SIG_DFL , +or the address of a programmer-defined function (a "signal handler"). +.P +If the signal +.I signum +is delivered to the process, then one of the following happens: +.TP 3 +* +If the disposition is set to +.BR SIG_IGN , +then the signal is ignored. +.TP +* +If the disposition is set to +.BR SIG_DFL , +then the default action associated with the signal (see +.BR signal (7)) +occurs. +.TP +* +If the disposition is set to a function, +then first either the disposition is reset to +.BR SIG_DFL , +or the signal is blocked (see \fIPortability\fP below), and then +.I handler +is called with argument +.IR signum . +If invocation of the handler caused the signal to be blocked, +then the signal is unblocked upon return from the handler. +.P +The signals +.B SIGKILL +and +.B SIGSTOP +cannot be caught or ignored. +.SH RETURN VALUE +.BR signal () +returns the previous value of the signal handler. +On failure, it returns +.BR SIG_ERR , +and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I signum +is invalid. +.SH VERSIONS +The use of +.I sighandler_t +is a GNU extension, exposed if +.B _GNU_SOURCE +is defined; +.\" libc4 and libc5 define +.\" .IR SignalHandler ; +glibc also defines (the BSD-derived) +.I sig_t +if +.B _BSD_SOURCE +(glibc 2.19 and earlier) +or +.B _DEFAULT_SOURCE +(glibc 2.19 and later) +is defined. +Without use of such a type, the declaration of +.BR signal () +is the somewhat harder to read: +.P +.in +4n +.EX +.BI "void ( *" signal "(int " signum ", void (*" handler ")(int)) ) (int);" +.EE +.in +.SS Portability +The only portable use of +.BR signal () +is to set a signal's disposition to +.B SIG_DFL +or +.BR SIG_IGN . +The semantics when using +.BR signal () +to establish a signal handler vary across systems +(and POSIX.1 explicitly permits this variation); +.B do not use it for this purpose. +.P +POSIX.1 solved the portability mess by specifying +.BR sigaction (2), +which provides explicit control of the semantics when a +signal handler is invoked; use that interface instead of +.BR signal (). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.P +In the original UNIX systems, when a handler that was established using +.BR signal () +was invoked by the delivery of a signal, +the disposition of the signal would be reset to +.BR SIG_DFL , +and the system did not block delivery of further instances of the signal. +This is equivalent to calling +.BR sigaction (2) +with the following flags: +.P +.in +4n +.EX +sa.sa_flags = SA_RESETHAND | SA_NODEFER; +.EE +.in +.P +System\ V also provides these semantics for +.BR signal (). +This was bad because the signal might be delivered again +before the handler had a chance to reestablish itself. +Furthermore, rapid deliveries of the same signal could +result in recursive invocations of the handler. +.P +BSD improved on this situation, but unfortunately also +changed the semantics of the existing +.BR signal () +interface while doing so. +On BSD, when a signal handler is invoked, +the signal disposition is not reset, +and further instances of the signal are blocked from +being delivered while the handler is executing. +Furthermore, certain blocking system calls are automatically +restarted if interrupted by a signal handler (see +.BR signal (7)). +The BSD semantics are equivalent to calling +.BR sigaction (2) +with the following flags: +.P +.in +4n +.EX +sa.sa_flags = SA_RESTART; +.EE +.in +.P +The situation on Linux is as follows: +.IP \[bu] 3 +The kernel's +.BR signal () +system call provides System\ V semantics. +.IP \[bu] +By default, in glibc 2 and later, the +.BR signal () +wrapper function does not invoke the kernel system call. +Instead, it calls +.BR sigaction (2) +using flags that supply BSD semantics. +This default behavior is provided as long as a suitable +feature test macro is defined: +.B _BSD_SOURCE +on glibc 2.19 and earlier or +.B _DEFAULT_SOURCE +in glibc 2.19 and later. +(By default, these macros are defined; see +.BR feature_test_macros (7) +for details.) +If such a feature test macro is not defined, then +.BR signal () +provides System\ V semantics. +.\" +.\" System V semantics are also provided if one uses the separate +.\" .BR sysv_signal (3) +.\" function. +.\" .IP \[bu] +.\" The +.\" .BR signal () +.\" function in Linux libc4 and libc5 provide System\ V semantics. +.\" If one on a libc5 system includes +.\" .I +.\" instead of +.\" .IR , +.\" then +.\" .BR signal () +.\" provides BSD semantics. +.SH NOTES +The effects of +.BR signal () +in a multithreaded process are unspecified. +.P +According to POSIX, the behavior of a process is undefined after it +ignores a +.BR SIGFPE , +.BR SIGILL , +or +.B SIGSEGV +signal that was not generated by +.BR kill (2) +or +.BR raise (3). +Integer division by zero has undefined result. +On some architectures it will generate a +.B SIGFPE +signal. +(Also dividing the most negative integer by \-1 may generate +.BR SIGFPE .) +Ignoring this signal might lead to an endless loop. +.P +See +.BR sigaction (2) +for details on what happens when the disposition +.B SIGCHLD +is set to +.BR SIG_IGN . +.P +See +.BR signal\-safety (7) +for a list of the async-signal-safe functions that can be +safely called from inside a signal handler. +.SH SEE ALSO +.BR kill (1), +.BR alarm (2), +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR bsd_signal (3), +.BR killpg (3), +.BR raise (3), +.BR siginterrupt (3), +.BR sigqueue (3), +.BR sigsetops (3), +.BR sigvec (3), +.BR sysv_signal (3), +.BR signal (7) diff --git a/man/man2/signalfd.2 b/man/man2/signalfd.2 new file mode 100644 index 0000000..fe33a68 --- /dev/null +++ b/man/man2/signalfd.2 @@ -0,0 +1,526 @@ +.\" Copyright (C) 2008 Michael Kerrisk +.\" starting from a version by Davide Libenzi +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH signalfd 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +signalfd \- create a file descriptor for accepting signals +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int signalfd(int " fd ", const sigset_t *" mask ", int " flags ); +.fi +.SH DESCRIPTION +.BR signalfd () +creates a file descriptor that can be used to accept signals +targeted at the caller. +This provides an alternative to the use of a signal handler or +.BR sigwaitinfo (2), +and has the advantage that the file descriptor may be monitored by +.BR select (2), +.BR poll (2), +and +.BR epoll (7). +.P +The +.I mask +argument specifies the set of signals that the caller +wishes to accept via the file descriptor. +This argument is a signal set whose contents can be initialized +using the macros described in +.BR sigsetops (3). +Normally, the set of signals to be received via the +file descriptor should be blocked using +.BR sigprocmask (2), +to prevent the signals being handled according to their default +dispositions. +It is not possible to receive +.B SIGKILL +or +.B SIGSTOP +signals via a signalfd file descriptor; +these signals are silently ignored if specified in +.IR mask . +.P +If the +.I fd +argument is \-1, +then the call creates a new file descriptor and associates the +signal set specified in +.I mask +with that file descriptor. +If +.I fd +is not \-1, +then it must specify a valid existing signalfd file descriptor, and +.I mask +is used to replace the signal set associated with that file descriptor. +.P +Starting with Linux 2.6.27, the following values may be bitwise ORed in +.I flags +to change the behavior of +.BR signalfd (): +.TP 14 +.B SFD_NONBLOCK +Set the +.B O_NONBLOCK +file status flag on the open file description (see +.BR open (2)) +referred to by the new file descriptor. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B SFD_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.P +Up to Linux 2.6.26, the +.I flags +argument is unused, and must be specified as zero. +.P +.BR signalfd () +returns a file descriptor that supports the following operations: +.TP +.BR read (2) +If one or more of the signals specified in +.I mask +is pending for the process, then the buffer supplied to +.BR read (2) +is used to return one or more +.I signalfd_siginfo +structures (see below) that describe the signals. +The +.BR read (2) +returns information for as many signals as are pending and will +fit in the supplied buffer. +The buffer must be at least +.I "sizeof(struct signalfd_siginfo)" +bytes. +The return value of the +.BR read (2) +is the total number of bytes read. +.IP +As a consequence of the +.BR read (2), +the signals are consumed, +so that they are no longer pending for the process +(i.e., will not be caught by signal handlers, +and cannot be accepted using +.BR sigwaitinfo (2)). +.IP +If none of the signals in +.I mask +is pending for the process, then the +.BR read (2) +either blocks until one of the signals in +.I mask +is generated for the process, +or fails with the error +.B EAGAIN +if the file descriptor has been made nonblocking. +.TP +.BR poll (2) +.TQ +.BR select (2) +.TQ +(and similar) +The file descriptor is readable +(the +.BR select (2) +.I readfds +argument; the +.BR poll (2) +.B POLLIN +flag) +if one or more of the signals in +.I mask +is pending for the process. +.IP +The signalfd file descriptor also supports the other file-descriptor +multiplexing APIs: +.BR pselect (2), +.BR ppoll (2), +and +.BR epoll (7). +.TP +.BR close (2) +When the file descriptor is no longer required it should be closed. +When all file descriptors associated with the same signalfd object +have been closed, the resources for object are freed by the kernel. +.SS The signalfd_siginfo structure +The format of the +.I signalfd_siginfo +structure(s) returned by +.BR read (2)s +from a signalfd file descriptor is as follows: +.P +.in +4n +.EX +struct signalfd_siginfo { + uint32_t ssi_signo; /* Signal number */ + int32_t ssi_errno; /* Error number (unused) */ + int32_t ssi_code; /* Signal code */ + uint32_t ssi_pid; /* PID of sender */ + uint32_t ssi_uid; /* Real UID of sender */ + int32_t ssi_fd; /* File descriptor (SIGIO) */ + uint32_t ssi_tid; /* Kernel timer ID (POSIX timers) + uint32_t ssi_band; /* Band event (SIGIO) */ + uint32_t ssi_overrun; /* POSIX timer overrun count */ + uint32_t ssi_trapno; /* Trap number that caused signal */ +.\" ssi_trapno is unused on most arches + int32_t ssi_status; /* Exit status or signal (SIGCHLD) */ + int32_t ssi_int; /* Integer sent by sigqueue(3) */ + uint64_t ssi_ptr; /* Pointer sent by sigqueue(3) */ + uint64_t ssi_utime; /* User CPU time consumed (SIGCHLD) */ + uint64_t ssi_stime; /* System CPU time consumed + (SIGCHLD) */ + uint64_t ssi_addr; /* Address that generated signal + (for hardware\-generated signals) */ + uint16_t ssi_addr_lsb; /* Least significant bit of address + (SIGBUS; since Linux 2.6.37) */ +.\" ssi_addr_lsb: commit b8aeec34175fc8fe8b0d40efea4846dfc1ba663e + uint8_t pad[\fIX\fP]; /* Pad size to 128 bytes (allow for + additional fields in the future) */ +}; +.EE +.in +.P +Each of the fields in this structure +is analogous to the similarly named field in the +.I siginfo_t +structure. +The +.I siginfo_t +structure is described in +.BR sigaction (2). +Not all fields in the returned +.I signalfd_siginfo +structure will be valid for a specific signal; +the set of valid fields can be determined from the value returned in the +.I ssi_code +field. +This field is the analog of the +.I siginfo_t +.I si_code +field; see +.BR sigaction (2) +for details. +.SS fork(2) semantics +After a +.BR fork (2), +the child inherits a copy of the signalfd file descriptor. +A +.BR read (2) +from the file descriptor in the child will return information +about signals queued to the child. +.SS Semantics of file descriptor passing +As with other file descriptors, +signalfd file descriptors can be passed to another process +via a UNIX domain socket (see +.BR unix (7)). +In the receiving process, a +.BR read (2) +from the received file descriptor will return information +about signals queued to that process. +.SS execve(2) semantics +Just like any other file descriptor, +a signalfd file descriptor remains open across an +.BR execve (2), +unless it has been marked for close-on-exec (see +.BR fcntl (2)). +Any signals that were available for reading before the +.BR execve (2) +remain available to the newly loaded program. +(This is analogous to traditional signal semantics, +where a blocked signal that is pending remains pending across an +.BR execve (2).) +.SS Thread semantics +The semantics of signalfd file descriptors in a multithreaded program +mirror the standard semantics for signals. +In other words, +when a thread reads from a signalfd file descriptor, +it will read the signals that are directed to the thread +itself and the signals that are directed to the process +(i.e., the entire thread group). +(A thread will not be able to read signals that are directed +to other threads in the process.) +.\" +.SS epoll(7) semantics +If a process adds (via +.BR epoll_ctl (2)) +a signalfd file descriptor to an +.BR epoll (7) +instance, then +.BR epoll_wait (2) +returns events only for signals sent to that process. +In particular, if the process then uses +.BR fork (2) +to create a child process, then the child will be able to +.BR read (2) +signals that are sent to it using the signalfd file descriptor, but +.BR epoll_wait (2) +will +.B not +indicate that the signalfd file descriptor is ready. +In this scenario, a possible workaround is that after the +.BR fork (2), +the child process can close the signalfd file descriptor that it inherited +from the parent process and then create another signalfd file descriptor +and add it to the epoll instance. +Alternatively, the parent and the child could delay creating their +(separate) signalfd file descriptors and adding them to the +epoll instance until after the call to +.BR fork (2). +.SH RETURN VALUE +On success, +.BR signalfd () +returns a signalfd file descriptor; +this is either a new file descriptor (if +.I fd +was \-1), or +.I fd +if +.I fd +was a valid signalfd file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The +.I fd +file descriptor is not a valid file descriptor. +.TP +.B EINVAL +.I fd +is not a valid signalfd file descriptor. +.\" or, the +.\" .I sizemask +.\" argument is not equal to +.\" .IR sizeof(sigset_t) ; +.TP +.B EINVAL +.I flags +is invalid; +or, in Linux 2.6.26 or earlier, +.I flags +is nonzero. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been +reached. +.TP +.B ENODEV +Could not mount (internal) anonymous inode device. +.TP +.B ENOMEM +There was insufficient memory to create a new signalfd file descriptor. +.SH VERSIONS +.SS C library/kernel differences +The underlying Linux system call requires an additional argument, +.IR "size_t sizemask" , +which specifies the size of the +.I mask +argument. +The glibc +.BR signalfd () +wrapper function does not include this argument, +since it provides the required value for the underlying system call. +.P +There are two underlying Linux system calls: +.BR signalfd () +and the more recent +.BR signalfd4 (). +The former system call does not implement a +.I flags +argument. +The latter system call implements the +.I flags +values described above. +Starting with glibc 2.9, the +.BR signalfd () +wrapper function will use +.BR signalfd4 () +where it is available. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR signalfd () +Linux 2.6.22, +glibc 2.8. +.\" signalfd() is in glibc 2.7, but reportedly does not build +.TP +.BR signalfd4 () +Linux 2.6.27. +.SH NOTES +A process can create multiple signalfd file descriptors. +This makes it possible to accept different signals +on different file descriptors. +(This may be useful if monitoring the file descriptors using +.BR select (2), +.BR poll (2), +or +.BR epoll (7): +the arrival of different signals will make different file descriptors ready.) +If a signal appears in the +.I mask +of more than one of the file descriptors, then occurrences +of that signal can be read (once) from any one of the file descriptors. +.P +Attempts to include +.B SIGKILL +and +.B SIGSTOP +in +.I mask +are silently ignored. +.P +The signal mask employed by a signalfd file descriptor can be viewed +via the entry for the corresponding file descriptor in the process's +.IR /proc/ pid /fdinfo +directory. +See +.BR proc (5) +for further details. +.\" +.SS Limitations +The signalfd mechanism can't be used to receive signals that +are synchronously generated, such as the +.B SIGSEGV +signal that results from accessing an invalid memory address +or the +.B SIGFPE +signal that results from an arithmetic error. +Such signals can be caught only via signal handler. +.P +As described above, +in normal usage one blocks the signals that will be accepted via +.BR signalfd (). +If spawning a child process to execute a helper program +(that does not need the signalfd file descriptor), +then, after the call to +.BR fork (2), +you will normally want to unblock those signals before calling +.BR execve (2), +so that the helper program can see any signals that it expects to see. +Be aware, however, +that this won't be possible in the case of a helper program spawned +behind the scenes by any library function that the program may call. +In such cases, one must fall back to using a traditional signal +handler that writes to a file descriptor monitored by +.BR select (2), +.BR poll (2), +or +.BR epoll (7). +.SH BUGS +Before Linux 2.6.25, the +.I ssi_ptr +and +.I ssi_int +fields are not filled in with the data accompanying a signal sent by +.BR sigqueue (3). +.\" The fix also was put into Linux 2.6.24.5 +.SH EXAMPLES +The program below accepts the signals +.B SIGINT +and +.B SIGQUIT +via a signalfd file descriptor. +The program terminates after accepting a +.B SIGQUIT +signal. +The following shell session demonstrates the use of the program: +.P +.in +4n +.EX +.RB "$" " ./signalfd_demo" +.BR "\[ha]C" " # Control\-C generates SIGINT" +Got SIGINT +.B \[ha]C +Got SIGINT +\fB\[ha]\e\fP # Control\-\e generates SIGQUIT +Got SIGQUIT +$ +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (signalfd.c) +.EX +#include +#include +#include +#include +#include +#include +#include +\& +int +main(void) +{ + int sfd; + ssize_t s; + sigset_t mask; + struct signalfd_siginfo fdsi; +\& + sigemptyset(&mask); + sigaddset(&mask, SIGINT); + sigaddset(&mask, SIGQUIT); +\& + /* Block signals so that they aren\[aq]t handled + according to their default dispositions. */ +\& + if (sigprocmask(SIG_BLOCK, &mask, NULL) == \-1) + err(EXIT_FAILURE, "sigprocmask"); +\& + sfd = signalfd(\-1, &mask, 0); + if (sfd == \-1) + err(EXIT_FAILURE, "signalfd"); +\& + for (;;) { + s = read(sfd, &fdsi, sizeof(fdsi)); + if (s != sizeof(fdsi)) + err(EXIT_FAILURE, "read"); +\& + if (fdsi.ssi_signo == SIGINT) { + printf("Got SIGINT\en"); + } else if (fdsi.ssi_signo == SIGQUIT) { + printf("Got SIGQUIT\en"); + exit(EXIT_SUCCESS); + } else { + printf("Read unexpected signal\en"); + } + } +} +.EE +.\" SRC END +.SH SEE ALSO +.BR eventfd (2), +.BR poll (2), +.BR read (2), +.BR select (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR sigwaitinfo (2), +.BR timerfd_create (2), +.BR sigsetops (3), +.BR sigwait (3), +.BR epoll (7), +.BR signal (7) diff --git a/man/man2/signalfd4.2 b/man/man2/signalfd4.2 new file mode 100644 index 0000000..8dbea5c --- /dev/null +++ b/man/man2/signalfd4.2 @@ -0,0 +1 @@ +.so man2/signalfd.2 diff --git a/man/man2/sigpending.2 b/man/man2/sigpending.2 new file mode 100644 index 0000000..c85133f --- /dev/null +++ b/man/man2/sigpending.2 @@ -0,0 +1,110 @@ +.\" Copyright (c) 2005 Michael Kerrisk +.\" based on earlier work by faith@cs.unc.edu and +.\" Mike Battersby +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 +.\" +.TH sigpending 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigpending, rt_sigpending \- examine pending signals +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sigpending(sigset_t *" set ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigpending (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +.BR sigpending () +returns the set of signals that are pending for delivery to the calling +thread (i.e., the signals which have been raised while blocked). +The mask of pending signals is returned in +.IR set . +.SH RETURN VALUE +.BR sigpending () +returns 0 on success. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I set +points to memory which is not a valid part of the process address space. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SS C library/kernel differences +The original Linux system call was named +.BR sigpending (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.I sigset_t +argument supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigpending (), +was added to support an enlarged +.I sigset_t +type. +The new system call takes a second argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal set in +.IR set . +.\" This argument is currently required to be less than or equal to +.\" .IR sizeof(sigset_t) +.\" (or the error +.\" .B EINVAL +.\" results). +The glibc +.BR sigpending () +wrapper function hides these details from us, transparently calling +.BR rt_sigpending () +when the kernel provides it. +.SH NOTES +See +.BR sigsetops (3) +for details on manipulating signal sets. +.P +If a signal is both blocked and has a disposition of "ignored", it is +.I not +added to the mask of pending signals when generated. +.P +The set of signals that is pending for a thread +is the union of the set of signals that is pending for that thread +and the set of signals that is pending for the process as a whole; see +.BR signal (7). +.P +A child created via +.BR fork (2) +initially has an empty pending signal set; +the pending signal set is preserved across an +.BR execve (2). +.SH BUGS +Up to and including glibc 2.2.1, +there is a bug in the wrapper function for +.BR sigpending () +which means that information about pending real-time signals +is not correctly returned. +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR sigsetops (3), +.BR signal (7) diff --git a/man/man2/sigprocmask.2 b/man/man2/sigprocmask.2 new file mode 100644 index 0000000..47bbc69 --- /dev/null +++ b/man/man2/sigprocmask.2 @@ -0,0 +1,224 @@ +.\" Copyright (c) 2005 Michael Kerrisk +.\" based on earlier work by faith@cs.unc.edu and +.\" Mike Battersby +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 +.\" +.TH sigprocmask 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigprocmask, rt_sigprocmask \- examine and change blocked signals +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.B #include +.P +.nf +/* Prototype for the glibc wrapper function */ +.BI "int sigprocmask(int " how ", const sigset_t *_Nullable restrict " set , +.BI " sigset_t *_Nullable restrict " oldset ); +.P +.BR "#include " " /* Definition of " SIG_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +/* Prototype for the underlying system call */ +.BI "int syscall(SYS_rt_sigprocmask, int " how , +.BI " const kernel_sigset_t *_Nullable " set , +.BI " kernel_sigset_t *_Nullable " oldset , +.BI " size_t " sigsetsize ); +.P +/* Prototype for the legacy system call */ +.BI "[[deprecated]] int syscall(SYS_sigprocmask, int " how , +.BI " const old_kernel_sigset_t *_Nullable " set , +.BI " old_kernel_sigset_t *_Nullable " oldset ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigprocmask (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +.BR sigprocmask () +is used to fetch and/or change the signal mask of the calling thread. +The signal mask is the set of signals whose delivery is currently +blocked for the caller +(see also +.BR signal (7) +for more details). +.P +The behavior of the call is dependent on the value of +.IR how , +as follows. +.TP +.B SIG_BLOCK +The set of blocked signals is the union of the current set and the +.I set +argument. +.TP +.B SIG_UNBLOCK +The signals in +.I set +are removed from the current set of blocked signals. +It is permissible to attempt to unblock a signal which is not blocked. +.TP +.B SIG_SETMASK +The set of blocked signals is set to the argument +.IR set . +.P +If +.I oldset +is non-NULL, the previous value of the signal mask is stored in +.IR oldset . +.P +If +.I set +is NULL, then the signal mask is unchanged (i.e., +.I how +is ignored), +but the current value of the signal mask is nevertheless returned in +.I oldset +(if it is not NULL). +.P +A set of functions for modifying and inspecting variables of type +.I sigset_t +("signal sets") is described in +.BR sigsetops (3). +.P +The use of +.BR sigprocmask () +is unspecified in a multithreaded process; see +.BR pthread_sigmask (3). +.SH RETURN VALUE +.BR sigprocmask () +returns 0 on success. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +The +.I set +or +.I oldset +argument points outside the process's allocated address space. +.TP +.B EINVAL +Either the value specified in +.I how +was invalid or the kernel does not support the size passed in +.I sigsetsize. +.SH VERSIONS +.SS C library/kernel differences +The kernel's definition of +.I sigset_t +differs in size from that used +by the C library. +In this manual page, the former is referred to as +.I kernel_sigset_t +(it is nevertheless named +.I sigset_t +in the kernel sources). +.P +The glibc wrapper function for +.BR sigprocmask () +silently ignores attempts to block the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.P +The original Linux system call was named +.BR sigprocmask (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.I sigset_t +(referred to as +.I old_kernel_sigset_t +in this manual page) +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigprocmask (), +was added to support an enlarged +.I sigset_t +type +(referred to as +.I kernel_sigset_t +in this manual page). +The new system call takes a fourth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal sets in +.I set +and +.IR oldset . +This argument is currently required to have a fixed architecture specific value +(equal to +.IR sizeof(kernel_sigset_t) ). +.\" sizeof(kernel_sigset_t) == _NSIG / 8, +.\" which equals to 8 on most architectures, but e.g. on MIPS it's 16. +.P +The glibc +.BR sigprocmask () +wrapper function hides these details from us, transparently calling +.BR rt_sigprocmask () +when the kernel provides it. +.\" +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +It is not possible to block +.BR SIGKILL " or " SIGSTOP . +Attempts to do so are silently ignored. +.P +Each of the threads in a process has its own signal mask. +.P +A child created via +.BR fork (2) +inherits a copy of its parent's signal mask; +the signal mask is preserved across +.BR execve (2). +.P +If +.BR SIGBUS , +.BR SIGFPE , +.BR SIGILL , +or +.B SIGSEGV +are generated +while they are blocked, the result is undefined, +unless the signal was generated by +.BR kill (2), +.BR sigqueue (3), +or +.BR raise (3). +.P +See +.BR sigsetops (3) +for details on manipulating signal sets. +.P +Note that it is permissible (although not very useful) to specify both +.I set +and +.I oldset +as NULL. +.SH SEE ALSO +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signal (2), +.BR sigpending (2), +.BR sigsuspend (2), +.BR pthread_sigmask (3), +.BR sigqueue (3), +.BR sigsetops (3), +.BR signal (7) diff --git a/man/man2/sigreturn.2 b/man/man2/sigreturn.2 new file mode 100644 index 0000000..1d8d927 --- /dev/null +++ b/man/man2/sigreturn.2 @@ -0,0 +1,151 @@ +.\" Copyright (C) 2008, 2014, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created Sat Aug 21 1995 Thomas K. Dyas +.\" Modified Tue Oct 22 22:09:03 1996 by Eric S. Raymond +.\" 2008-06-26, mtk, added some more detail on the work done by sigreturn() +.\" 2014-12-05, mtk, rewrote all of the rest of the original page +.\" +.TH sigreturn 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigreturn, rt_sigreturn \- return from signal handler and cleanup stack frame +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B int sigreturn(...); +.fi +.SH DESCRIPTION +If the Linux kernel determines that an unblocked +signal is pending for a process, then, +at the next transition back to user mode in that process +(e.g., upon return from a system call or +when the process is rescheduled onto the CPU), +it creates a new frame on the user-space stack where it +saves various pieces of process context +(processor status word, registers, signal mask, and signal stack settings). +.\" See arch/x86/kernel/signal.c::__setup_frame() [in Linux 3.17 source code] +.P +The kernel also arranges that, during the transition back to user mode, +the signal handler is called, and that, upon return from the handler, +control passes to a piece of user-space code commonly called +the "signal trampoline". +The signal trampoline code in turn calls +.BR sigreturn (). +.P +This +.BR sigreturn () +call undoes everything that was +done\[em]changing the process's signal mask, switching signal stacks (see +.BR sigaltstack "(2))\[em]in" +order to invoke the signal handler. +Using the information that was earlier saved on the user-space stack +.BR sigreturn () +restores the process's signal mask, switches stacks, +and restores the process's context +(processor flags and registers, +including the stack pointer and instruction pointer), +so that the process resumes execution +at the point where it was interrupted by the signal. +.SH RETURN VALUE +.BR sigreturn () +never returns. +.SH VERSIONS +Many UNIX-type systems have a +.BR sigreturn () +system call or near equivalent. +However, this call is not specified in POSIX, +and details of its behavior vary across systems. +.SH STANDARDS +None. +.SH NOTES +.BR sigreturn () +exists only to allow the implementation of signal handlers. +It should +.B never +be called directly. +(Indeed, a simple +.BR sigreturn () +.\" See sysdeps/unix/sysv/linux/sigreturn.c and +.\" signal/sigreturn.c in the glibc source +wrapper in the GNU C library simply returns \-1, with +.I errno +set to +.BR ENOSYS .) +Details of the arguments (if any) passed to +.BR sigreturn () +vary depending on the architecture. +(On some architectures, such as x86-64, +.BR sigreturn () +takes no arguments, since all of the information that it requires +is available in the stack frame that was previously created by the +kernel on the user-space stack.) +.P +Once upon a time, UNIX systems placed the signal trampoline code +onto the user stack. +Nowadays, pages of the user stack are protected so as to +disallow code execution. +Thus, on contemporary Linux systems, depending on the architecture, +the signal trampoline code lives either in the +.BR vdso (7) +or in the C library. +In the latter case, +.\" See, for example, sysdeps/unix/sysv/linux/i386/sigaction.c and +.\" sysdeps/unix/sysv/linux/x86_64/sigaction.c in the glibc (2.20) source. +the C library's +.BR sigaction (2) +wrapper function informs the kernel of the location of the trampoline code +by placing its address in the +.I sa_restorer +field of the +.I sigaction +structure, +and sets the +.B SA_RESTORER +flag in the +.I sa_flags +field. +.P +The saved process context information is placed in a +.I ucontext_t +structure (see +.IR ). +That structure is visible within the signal handler +as the third argument of a handler established via +.BR sigaction (2) +with the +.B SA_SIGINFO +flag. +.P +On some other UNIX systems, +the operation of the signal trampoline differs a little. +In particular, on some systems, upon transitioning back to user mode, +the kernel passes control to the trampoline (rather than the signal handler), +and the trampoline code calls the signal handler (and then calls +.BR sigreturn () +once the handler returns). +.\" +.SS C library/kernel differences +The original Linux system call was named +.BR sigreturn (). +However, with the addition of real-time signals in Linux 2.2, +a new system call, +.BR rt_sigreturn () +was added to support an enlarged +.I sigset_t +type. +The GNU C library +hides these details from us, transparently employing +.BR rt_sigreturn () +when the kernel provides it. +.\" +.SH SEE ALSO +.BR kill (2), +.BR restart_syscall (2), +.BR sigaltstack (2), +.BR signal (2), +.BR getcontext (3), +.BR signal (7), +.BR vdso (7) diff --git a/man/man2/sigsuspend.2 b/man/man2/sigsuspend.2 new file mode 100644 index 0000000..c7e225f --- /dev/null +++ b/man/man2/sigsuspend.2 @@ -0,0 +1,131 @@ +.\" Copyright (c) 2005 Michael Kerrisk +.\" based on earlier work by faith@cs.unc.edu and +.\" Mike Battersby +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 +.\" +.TH sigsuspend 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigsuspend, rt_sigsuspend \- wait for a signal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sigsuspend(const sigset_t *" mask ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigsuspend (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +.BR sigsuspend () +temporarily replaces the signal mask of the calling thread with the +mask given by +.I mask +and then suspends the thread until delivery of a signal whose +action is to invoke a signal handler or to terminate a process. +.P +If the signal terminates the process, then +.BR sigsuspend () +does not return. +If the signal is caught, then +.BR sigsuspend () +returns after the signal handler returns, +and the signal mask is restored to the state before the call to +.BR sigsuspend (). +.P +It is not possible to block +.B SIGKILL +or +.BR SIGSTOP ; +specifying these signals in +.IR mask , +has no effect on the thread's signal mask. +.SH RETURN VALUE +.BR sigsuspend () +always returns \-1, with +.I errno +set to indicate the error (normally, +.BR EINTR ). +.SH ERRORS +.TP +.B EFAULT +.I mask +points to memory which is not a valid part of the process address space. +.TP +.B EINTR +The call was interrupted by a signal; +.BR signal (7). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SS C library/kernel differences +The original Linux system call was named +.BR sigsuspend (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.I sigset_t +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigsuspend (), +was added to support an enlarged +.I sigset_t +type. +The new system call takes a second argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal set in +.IR mask . +This argument is currently required to have the value +.I sizeof(sigset_t) +(or the error +.B EINVAL +results). +The glibc +.BR sigsuspend () +wrapper function hides these details from us, transparently calling +.BR rt_sigsuspend () +when the kernel provides it. +.\" +.SH NOTES +Normally, +.BR sigsuspend () +is used in conjunction with +.BR sigprocmask (2) +in order to prevent delivery of a signal during the execution of a +critical code section. +The caller first blocks the signals with +.BR sigprocmask (2). +When the critical code has completed, the caller then waits for the +signals by calling +.BR sigsuspend () +with the signal mask that was returned by +.BR sigprocmask (2) +(in the +.I oldset +argument). +.P +See +.BR sigsetops (3) +for details on manipulating signal sets. +.SH SEE ALSO +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR sigwaitinfo (2), +.BR sigsetops (3), +.BR sigwait (3), +.BR signal (7) diff --git a/man/man2/sigtimedwait.2 b/man/man2/sigtimedwait.2 new file mode 100644 index 0000000..1b13df1 --- /dev/null +++ b/man/man2/sigtimedwait.2 @@ -0,0 +1 @@ +.so man2/sigwaitinfo.2 diff --git a/man/man2/sigwaitinfo.2 b/man/man2/sigwaitinfo.2 new file mode 100644 index 0000000..d0127c8 --- /dev/null +++ b/man/man2/sigwaitinfo.2 @@ -0,0 +1,231 @@ +.\" Copyright (c) 2002 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigwaitinfo 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigwaitinfo, sigtimedwait, rt_sigtimedwait \- synchronously wait +for queued signals +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sigwaitinfo(const sigset_t *restrict " set , +.BI " siginfo_t *_Nullable restrict " info ); +.BI "int sigtimedwait(const sigset_t *restrict " set , +.BI " siginfo_t *_Nullable restrict " info , +.BI " const struct timespec *restrict " timeout ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigwaitinfo (), +.BR sigtimedwait (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +.BR sigwaitinfo () +suspends execution of the calling thread until one of the signals in +.I set +is pending +(If one of the signals in +.I set +is already pending for the calling thread, +.BR sigwaitinfo () +will return immediately.) +.P +.BR sigwaitinfo () +removes the signal from the set of pending +signals and returns the signal number as its function result. +If the +.I info +argument is not NULL, +then the buffer that it points to is used to return a structure of type +.I siginfo_t +(see +.BR sigaction (2)) +containing information about the signal. +.P +If multiple signals in +.I set +are pending for the caller, the signal that is retrieved by +.BR sigwaitinfo () +is determined according to the usual ordering rules; see +.BR signal (7) +for further details. +.P +.BR sigtimedwait () +operates in exactly the same way as +.BR sigwaitinfo () +except that it has an additional argument, +.IR timeout , +which specifies the interval for which +the thread is suspended waiting for a signal. +(This interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the interval +may overrun by a small amount.) +This argument is a +.BR timespec (3) +structure. +.P +If both fields of this structure are specified as 0, a poll is performed: +.BR sigtimedwait () +returns immediately, either with information about a signal that +was pending for the caller, or with an error +if none of the signals in +.I set +was pending. +.SH RETURN VALUE +On success, both +.BR sigwaitinfo () +and +.BR sigtimedwait () +return a signal number (i.e., a value greater than zero). +On failure both calls return \-1, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +No signal in +.I set +became pending within the +.I timeout +period specified to +.BR sigtimedwait (). +.TP +.B EINTR +The wait was interrupted by a signal handler; see +.BR signal (7). +(This handler was for a signal other than one of those in +.IR set .) +.TP +.B EINVAL +.I timeout +was invalid. +.SH VERSIONS +.SS C library/kernel differences +On Linux, +.BR sigwaitinfo () +is a library function implemented on top of +.BR sigtimedwait (). +.P +The glibc wrapper functions for +.BR sigwaitinfo () +and +.BR sigtimedwait () +silently ignore attempts to wait for the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.P +The original Linux system call was named +.BR sigtimedwait (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.I sigset_t +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigtimedwait (), +was added to support an enlarged +.I sigset_t +type. +The new system call takes a fourth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal set in +.IR set . +This argument is currently required to have the value +.I sizeof(sigset_t) +(or the error +.B EINVAL +results). +The glibc +.BR sigtimedwait () +wrapper function hides these details from us, transparently calling +.BR rt_sigtimedwait () +when the kernel provides it. +.\" +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +In normal usage, the calling program blocks the signals in +.I set +via a prior call to +.BR sigprocmask (2) +(so that the default disposition for these signals does not occur if they +become pending between successive calls to +.BR sigwaitinfo () +or +.BR sigtimedwait ()) +and does not establish handlers for these signals. +In a multithreaded program, +the signal should be blocked in all threads, in order to prevent +the signal being treated according to its default disposition in +a thread other than the one calling +.BR sigwaitinfo () +or +.BR sigtimedwait ()). +.P +The set of signals that is pending for a given thread is the +union of the set of signals that is pending specifically for that thread +and the set of signals that is pending for the process as a whole (see +.BR signal (7)). +.P +Attempts to wait for +.B SIGKILL +and +.B SIGSTOP +are silently ignored. +.P +If multiple threads of a process are blocked +waiting for the same signal(s) in +.BR sigwaitinfo () +or +.BR sigtimedwait (), +then exactly one of the threads will actually receive the +signal if it becomes pending for the process as a whole; +which of the threads receives the signal is indeterminate. +.P +.BR sigwaitinfo () +or +.BR sigtimedwait (), +can't be used to receive signals that +are synchronously generated, such as the +.B SIGSEGV +signal that results from accessing an invalid memory address +or the +.B SIGFPE +signal that results from an arithmetic error. +Such signals can be caught only via signal handler. +.P +POSIX leaves the meaning of a NULL value for the +.I timeout +argument of +.BR sigtimedwait () +unspecified, permitting the possibility that this has the same meaning +as a call to +.BR sigwaitinfo (), +and indeed this is what is done on Linux. +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR signal (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigqueue (3), +.BR sigsetops (3), +.BR sigwait (3), +.BR timespec (3), +.BR signal (7), +.BR time (7) diff --git a/man/man2/socket.2 b/man/man2/socket.2 new file mode 100644 index 0000000..cf41c2f --- /dev/null +++ b/man/man2/socket.2 @@ -0,0 +1,493 @@ +'\" t +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" $Id: socket.2,v 1.4 1999/05/13 11:33:42 freitag Exp $ +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1998, 1999 by Andi Kleen +.\" Modified 2002-07-17 by Michael Kerrisk +.\" Modified 2004-06-17 by Michael Kerrisk +.\" +.TH socket 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +socket \- create an endpoint for communication +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int socket(int " domain ", int " type ", int " protocol ); +.fi +.SH DESCRIPTION +.BR socket () +creates an endpoint for communication and returns a file descriptor +that refers to that endpoint. +The file descriptor returned by a successful call will be +the lowest-numbered file descriptor not currently open for the process. +.P +The +.I domain +argument specifies a communication domain; this selects the protocol +family which will be used for communication. +These families are defined in +.IR . +The formats currently understood by the Linux kernel include: +.TS +tab(:); +l1 lw40 l. +Name:Purpose:Man page +T{ +.B AF_UNIX +T}:T{ +Local communication +T}:T{ +.BR unix (7) +T} +T{ +.B AF_LOCAL +T}:T{ +Synonym for +.B AF_UNIX +T}:T{ +T} +T{ +.B AF_INET +T}:IPv4 Internet protocols:T{ +.BR ip (7) +T} +T{ +.B AF_AX25 +T}:T{ +Amateur radio AX.25 protocol +T}:T{ +.\" Part of ax25-tools +.BR ax25 (4) +T} +T{ +.B AF_IPX +T}:IPX \- Novell protocols: +T{ +.B AF_APPLETALK +T}:AppleTalk:T{ +.BR ddp (7) +T} +T{ +.B AF_X25 +T}:ITU-T X.25 / ISO/IEC\~8208 protocol:T{ +.BR x25 (7) +T} +T{ +.B AF_INET6 +T}:IPv6 Internet protocols:T{ +.BR ipv6 (7) +T} +T{ +.B AF_DECnet +T}:T{ +DECet protocol sockets +T} +T{ +.B AF_KEY +T}:T{ +Key management protocol, originally developed for usage with IPsec +T} +T{ +.B AF_NETLINK +T}:T{ +Kernel user interface device +T}:T{ +.BR netlink (7) +T} +T{ +.B AF_PACKET +T}:T{ +Low-level packet interface +T}:T{ +.BR packet (7) +T} +T{ +.B AF_RDS +T}:T{ +.\" commit: 639b321b4d8f4e412bfbb2a4a19bfebc1e68ace4 +Reliable Datagram Sockets (RDS) protocol +T}:T{ +.\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds.7 +.\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds-rdma.7 +.BR rds (7) +.br +.BR rds\-rdma (7) +T} +T{ +.B AF_PPPOX +T}:T{ +Generic PPP transport layer, for setting up L2 tunnels +(L2TP and PPPoE) +T} +T{ +.B AF_LLC +T}:T{ +.\" linux-history commit: 34beb106cde7da233d4df35dd3d6cf4fee937caa +Logical link control (IEEE 802.2 LLC) protocol +T} +T{ +.B AF_IB +T}:T{ +.\" commits: 8d36eb01da5d371f..ce117ffac2e93334 +InfiniBand native addressing +T} +T{ +.B AF_MPLS +T}:T{ +.\" commits: 0189197f441602acdca3f97750d392a895b778fd +Multiprotocol Label Switching +T} +T{ +.B AF_CAN +T}:T{ +.\" commits: 8dbde28d9711475a..5423dd67bd0108a1 +Controller Area Network automotive bus protocol +T} +T{ +.B AF_TIPC +T}:T{ +.\" commits: b97bf3fd8f6a16966d4f18983b2c40993ff937d4 +TIPC, "cluster domain sockets" protocol +T} +T{ +.B AF_BLUETOOTH +T}:T{ +.\" commits: 8d36eb01da5d371f..ce117ffac2e93334 +Bluetooth low-level socket protocol +T} +T{ +.B AF_ALG +T}:T{ +.\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314 +Interface to kernel crypto API +T} +T{ +.B AF_VSOCK +T}:T{ +.\" commit: d021c344051af91f42c5ba9fdedc176740cbd238 +VSOCK (originally "VMWare VSockets") protocol +for hypervisor-guest communication +T}:T{ +.BR vsock (7) +T} +T{ +.B AF_KCM +T}:T{ +.\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314 +KCM (kernel connection multiplexer) interface +T} +T{ +.B AF_XDP +T}:T{ +.\" commit: c0c77d8fb787cfe0c3fca689c2a30d1dad4eaba7 +XDP (express data path) interface +T} +.TE +.P +Further details of the above address families, +as well as information on several other address families, can be found in +.BR address_families (7). +.P +The socket has the indicated +.IR type , +which specifies the communication semantics. +Currently defined types +are: +.TP 16 +.B SOCK_STREAM +Provides sequenced, reliable, two-way, connection-based byte streams. +An out-of-band data transmission mechanism may be supported. +.TP +.B SOCK_DGRAM +Supports datagrams (connectionless, unreliable messages of a fixed +maximum length). +.TP +.B SOCK_SEQPACKET +Provides a sequenced, reliable, two-way connection-based data +transmission path for datagrams of fixed maximum length; a consumer is +required to read an entire packet with each input system call. +.TP +.B SOCK_RAW +Provides raw network protocol access. +.TP +.B SOCK_RDM +Provides a reliable datagram layer that does not guarantee ordering. +.TP +.B SOCK_PACKET +Obsolete and should not be used in new programs; +see +.BR packet (7). +.P +Some socket types may not be implemented by all protocol families. +.P +Since Linux 2.6.27, the +.I type +argument serves a second purpose: +in addition to specifying a socket type, +it may include the bitwise OR of any of the following values, +to modify the behavior of +.BR socket (): +.TP 16 +.B SOCK_NONBLOCK +Set the +.B O_NONBLOCK +file status flag on the open file description (see +.BR open (2)) +referred to by the new file descriptor. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B SOCK_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.P +The +.I protocol +specifies a particular protocol to be used with the socket. +Normally only a single protocol exists to support a particular +socket type within a given protocol family, in which case +.I protocol +can be specified as 0. +However, it is possible that many protocols may exist, in +which case a particular protocol must be specified in this manner. +The protocol number to use is specific to the \*(lqcommunication domain\*(rq +in which communication is to take place; see +.BR protocols (5). +See +.BR getprotoent (3) +on how to map protocol name strings to protocol numbers. +.P +Sockets of type +.B SOCK_STREAM +are full-duplex byte streams. +They do not preserve +record boundaries. +A stream socket must be in +a +.I connected +state before any data may be sent or received on it. +A connection to +another socket is created with a +.BR connect (2) +call. +Once connected, data may be transferred using +.BR read (2) +and +.BR write (2) +calls or some variant of the +.BR send (2) +and +.BR recv (2) +calls. +When a session has been completed a +.BR close (2) +may be performed. +Out-of-band data may also be transmitted as described in +.BR send (2) +and received as described in +.BR recv (2). +.P +The communications protocols which implement a +.B SOCK_STREAM +ensure that data is not lost or duplicated. +If a piece of data for which +the peer protocol has buffer space cannot be successfully transmitted +within a reasonable length of time, then the connection is considered +to be dead. +When +.B SO_KEEPALIVE +is enabled on the socket the protocol checks in a protocol-specific +manner if the other end is still alive. +A +.B SIGPIPE +signal is raised if a process sends or receives +on a broken stream; this causes naive processes, +which do not handle the signal, to exit. +.B SOCK_SEQPACKET +sockets employ the same system calls as +.B SOCK_STREAM +sockets. +The only difference is that +.BR read (2) +calls will return only the amount of data requested, +and any data remaining in the arriving packet will be discarded. +Also all message boundaries in incoming datagrams are preserved. +.P +.B SOCK_DGRAM +and +.B SOCK_RAW +sockets allow sending of datagrams to correspondents named in +.BR sendto (2) +calls. +Datagrams are generally received with +.BR recvfrom (2), +which returns the next datagram along with the address of its sender. +.P +.B SOCK_PACKET +is an obsolete socket type to receive raw packets directly from the +device driver. +Use +.BR packet (7) +instead. +.P +An +.BR fcntl (2) +.B F_SETOWN +operation can be used to specify a process or process group to receive a +.B SIGURG +signal when the out-of-band data arrives or +.B SIGPIPE +signal when a +.B SOCK_STREAM +connection breaks unexpectedly. +This operation may also be used to set the process or process group +that receives the I/O and asynchronous notification of I/O events via +.BR SIGIO . +Using +.B F_SETOWN +is equivalent to an +.BR ioctl (2) +call with the +.B FIOSETOWN +or +.B SIOCSPGRP +argument. +.P +When the network signals an error condition to the protocol module (e.g., +using an ICMP message for IP) the pending error flag is set for the socket. +The next operation on this socket will return the error code of the pending +error. +For some protocols it is possible to enable a per-socket error queue +to retrieve detailed information about the error; see +.B IP_RECVERR +in +.BR ip (7). +.P +The operation of sockets is controlled by socket level +.IR options . +These options are defined in +.IR . +The functions +.BR setsockopt (2) +and +.BR getsockopt (2) +are used to set and get options. +.SH RETURN VALUE +On success, a file descriptor for the new socket is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Permission to create a socket of the specified type and/or protocol +is denied. +.TP +.B EAFNOSUPPORT +The implementation does not support the specified address family. +.TP +.B EINVAL +Unknown protocol, or protocol family not available. +.TP +.B EINVAL +.\" Since Linux 2.6.27 +Invalid flags in +.IR type . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.BR ENOBUFS " or " ENOMEM +Insufficient memory is available. +The socket cannot be +created until sufficient resources are freed. +.TP +.B EPROTONOSUPPORT +The protocol type or the specified protocol is not +supported within this domain. +.P +Other errors may be generated by the underlying protocol modules. +.SH STANDARDS +POSIX.1-2008. +.P +.B SOCK_NONBLOCK +and +.B SOCK_CLOEXEC +are Linux-specific. +.SH HISTORY +POSIX.1-2001, 4.4BSD. +.P +.BR socket () +appeared in 4.2BSD. +It is generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System\ V variants). +.P +The manifest constants used under 4.x BSD for protocol families +are +.BR PF_UNIX , +.BR PF_INET , +and so on, while +.BR AF_UNIX , +.BR AF_INET , +and so on are used for address +families. +However, already the BSD man page promises: "The protocol +family generally is the same as the address family", and subsequent +standards use AF_* everywhere. +.SH EXAMPLES +An example of the use of +.BR socket () +is shown in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR close (2), +.BR connect (2), +.BR fcntl (2), +.BR getpeername (2), +.BR getsockname (2), +.BR getsockopt (2), +.BR ioctl (2), +.BR listen (2), +.BR read (2), +.BR recv (2), +.BR select (2), +.BR send (2), +.BR shutdown (2), +.BR socketpair (2), +.BR write (2), +.BR getprotoent (3), +.BR address_families (7), +.BR ip (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) +.P +\[lq]An Introductory 4.3BSD Interprocess Communication Tutorial\[rq] +and +\[lq]BSD Interprocess Communication Tutorial\[rq], +reprinted in +.I UNIX Programmer's Supplementary Documents Volume 1. diff --git a/man/man2/socketcall.2 b/man/man2/socketcall.2 new file mode 100644 index 0000000..aa52f90 --- /dev/null +++ b/man/man2/socketcall.2 @@ -0,0 +1,185 @@ +'\" t +.\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Tue Oct 22 22:11:53 1996 by Eric S. Raymond +.TH socketcall 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +socketcall \- socket system calls +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.BR "#include " " /* Definition of " SYS_socketcall " */" +.B #include +.P +.BI "int syscall(SYS_socketcall, int " call ", unsigned long *" args ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR socketcall (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR socketcall () +is a common kernel entry point for the socket system calls. +.I call +determines which socket function to invoke. +.I args +points to a block containing the actual arguments, +which are passed through to the appropriate call. +.P +User programs should call the appropriate functions by their usual names. +Only standard library implementors and kernel hackers need to know about +.BR socketcall (). +.P +.TS +tab(:); +l l. +\fIcall\fR:Man page +T{ +.B SYS_SOCKET +T}:T{ +.BR socket (2) +T} +T{ +.B SYS_BIND +T}:T{ +.BR bind (2) +T} +T{ +.B SYS_CONNECT +T}:T{ +.BR connect (2) +T} +T{ +.B SYS_LISTEN +T}:T{ +.BR listen (2) +T} +T{ +.B SYS_ACCEPT +T}:T{ +.BR accept (2) +T} +T{ +.B SYS_GETSOCKNAME +T}:T{ +.BR getsockname (2) +T} +T{ +.B SYS_GETPEERNAME +T}:T{ +.BR getpeername (2) +T} +T{ +.B SYS_SOCKETPAIR +T}:T{ +.BR socketpair (2) +T} +T{ +.B SYS_SEND +T}:T{ +.BR send (2) +T} +T{ +.B SYS_RECV +T}:T{ +.BR recv (2) +T} +T{ +.B SYS_SENDTO +T}:T{ +.BR sendto (2) +T} +T{ +.B SYS_RECVFROM +T}:T{ +.BR recvfrom (2) +T} +T{ +.B SYS_SHUTDOWN +T}:T{ +.BR shutdown (2) +T} +T{ +.B SYS_SETSOCKOPT +T}:T{ +.BR setsockopt (2) +T} +T{ +.B SYS_GETSOCKOPT +T}:T{ +.BR getsockopt (2) +T} +T{ +.B SYS_SENDMSG +T}:T{ +.BR sendmsg (2) +T} +T{ +.B SYS_RECVMSG +T}:T{ +.BR recvmsg (2) +T} +T{ +.B SYS_ACCEPT4 +T}:T{ +.BR accept4 (2) +T} +T{ +.B SYS_RECVMMSG +T}:T{ +.BR recvmmsg (2) +T} +T{ +.B SYS_SENDMMSG +T}:T{ +.BR sendmmsg (2) +T} +.TE +.SH VERSIONS +On some architectures\[em]for example, x86-64 and ARM\[em]there is no +.BR socketcall () +system call; instead +.BR socket (2), +.BR accept (2), +.BR bind (2), +and so on really are implemented as separate system calls. +.SH STANDARDS +Linux. +.P +On x86-32, +.BR socketcall () +was historically the only entry point for the sockets API. +However, starting in Linux 4.3, +.\" commit 9dea5dc921b5f4045a18c63eb92e84dc274d17eb +direct system calls are provided on x86-32 for the sockets API. +This facilitates the creation of +.BR seccomp (2) +filters that filter sockets system calls +(for new user-space binaries that are compiled +to use the new entry points) +and also provides a (very) small performance improvement. +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR connect (2), +.BR getpeername (2), +.BR getsockname (2), +.BR getsockopt (2), +.BR listen (2), +.BR recv (2), +.BR recvfrom (2), +.BR recvmsg (2), +.BR send (2), +.BR sendmsg (2), +.BR sendto (2), +.BR setsockopt (2), +.BR shutdown (2), +.BR socket (2), +.BR socketpair (2) diff --git a/man/man2/socketpair.2 b/man/man2/socketpair.2 new file mode 100644 index 0000000..a55c03d --- /dev/null +++ b/man/man2/socketpair.2 @@ -0,0 +1,116 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)socketpair.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2002-07-22 by Michael Kerrisk +.\" Modified 2004-06-17 by Michael Kerrisk +.\" 2008-10-11, mtk: Add description of SOCK_NONBLOCK and SOCK_CLOEXEC +.\" +.TH socketpair 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +socketpair \- create a pair of connected sockets +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int socketpair(int " domain ", int " type ", int " protocol \ +", int " sv [2]); +.fi +.SH DESCRIPTION +The +.BR socketpair () +call creates an unnamed pair of connected sockets in the specified +.IR domain , +of the specified +.IR type , +and using the optionally specified +.IR protocol . +For further details of these arguments, see +.BR socket (2). +.P +The file descriptors used in referencing the new sockets are returned in +.I sv[0] +and +.IR sv[1] . +The two sockets are indistinguishable. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, +.I errno +is set to indicate the error, and +.I sv +is left unchanged +.P +On Linux (and other systems), +.BR socketpair () +does not modify +.I sv +on failure. +A requirement standardizing this behavior was added in POSIX.1-2008 TC2. +.\" http://austingroupbugs.net/view.php?id=483 +.SH ERRORS +.TP +.B EAFNOSUPPORT +The specified address family is not supported on this machine. +.TP +.B EFAULT +The address +.I sv +does not specify a valid part of the process address space. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B EOPNOTSUPP +The specified protocol does not support creation of socket pairs. +.TP +.B EPROTONOSUPPORT +The specified protocol is not supported on this machine. +.SH VERSIONS +On Linux, the only supported domains for this call are +.B AF_UNIX +(or synonymously, +.BR AF_LOCAL ) +and +.B AF_TIPC +.\" commit: 70b03759e9ecfae400605fa34f3d7154cccbbba3 +(since Linux 4.12). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.4BSD. +.P +.BR socketpair () +first appeared in 4.2BSD. +It is generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System\ V variants). +.P +Since Linux 2.6.27, +.BR socketpair () +supports the +.B SOCK_NONBLOCK +and +.B SOCK_CLOEXEC +flags in the +.I type +argument, as described in +.BR socket (2). +.SH SEE ALSO +.BR pipe (2), +.BR read (2), +.BR socket (2), +.BR write (2), +.BR socket (7), +.BR unix (7) diff --git a/man/man2/splice.2 b/man/man2/splice.2 new file mode 100644 index 0000000..9bc52ea --- /dev/null +++ b/man/man2/splice.2 @@ -0,0 +1,266 @@ +.\" This manpage is Copyright (C) 2006 Jens Axboe +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH splice 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +splice \- splice data to/from a pipe +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #define _FILE_OFFSET_BITS 64 +.B #include +.P +.BI "ssize_t splice(int " fd_in ", off_t *_Nullable " off_in , +.BI " int " fd_out ", off_t *_Nullable " off_out , +.BI " size_t " len ", unsigned int " flags ); +.\" Return type was long before glibc 2.7 +.fi +.SH DESCRIPTION +.BR splice () +moves data between two file descriptors +without copying between kernel address space and user address space. +It transfers up to +.I len +bytes of data from the file descriptor +.I fd_in +to the file descriptor +.IR fd_out , +where one of the file descriptors must refer to a pipe. +.P +The following semantics apply for +.I fd_in +and +.IR off_in : +.IP \[bu] 3 +If +.I fd_in +refers to a pipe, then +.I off_in +must be NULL. +.IP \[bu] +If +.I fd_in +does not refer to a pipe and +.I off_in +is NULL, then bytes are read from +.I fd_in +starting from the file offset, +and the file offset is adjusted appropriately. +.IP \[bu] +If +.I fd_in +does not refer to a pipe and +.I off_in +is not NULL, then +.I off_in +must point to a buffer which specifies the starting +offset from which bytes will be read from +.IR fd_in ; +in this case, the file offset of +.I fd_in +is not changed. +.P +Analogous statements apply for +.I fd_out +and +.IR off_out . +.P +The +.I flags +argument is a bit mask that is composed by ORing together +zero or more of the following values: +.TP +.B SPLICE_F_MOVE +Attempt to move pages instead of copying. +This is only a hint to the kernel: +pages may still be copied if the kernel cannot move the +pages from the pipe, or if +the pipe buffers don't refer to full pages. +The initial implementation of this flag was buggy: +therefore starting in Linux 2.6.21 it is a no-op +(but is still permitted in a +.BR splice () +call); +in the future, a correct implementation may be restored. +.TP +.B SPLICE_F_NONBLOCK +Do not block on I/O. +This makes the splice pipe operations nonblocking, but +.BR splice () +may nevertheless block because the file descriptors that +are spliced to/from may block (unless they have the +.B O_NONBLOCK +flag set). +.TP +.B SPLICE_F_MORE +More data will be coming in a subsequent splice. +This is a helpful hint when +the +.I fd_out +refers to a socket (see also the description of +.B MSG_MORE +in +.BR send (2), +and the description of +.B TCP_CORK +in +.BR tcp (7)). +.TP +.B SPLICE_F_GIFT +Unused for +.BR splice (); +see +.BR vmsplice (2). +.SH RETURN VALUE +Upon successful completion, +.BR splice () +returns the number of bytes +spliced to or from the pipe. +.P +A return value of 0 means end of input. +If +.I fd_in +refers to a pipe, then this 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. +.P +On error, +.BR splice () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +.B SPLICE_F_NONBLOCK +was specified in +.I flags +or one of the file descriptors had been marked as nonblocking +.RB ( O_NONBLOCK ) , +and the operation would block. +.TP +.B EBADF +One or both file descriptors are not valid, +or do not have proper read-write mode. +.TP +.B EINVAL +The target filesystem doesn't support splicing. +.TP +.B EINVAL +The target file is opened in append mode. +.\" The append-mode error is given since Linux 2.6.27; in earlier kernels, +.\" splice() in append mode was broken +.TP +.B EINVAL +Neither of the file descriptors refers to a pipe. +.TP +.B EINVAL +An offset was given for nonseekable device (e.g., a pipe). +.TP +.B EINVAL +.I fd_in +and +.I fd_out +refer to the same pipe. +.TP +.B ENOMEM +Out of memory. +.TP +.B ESPIPE +Either +.I off_in +or +.I off_out +was not NULL, but the corresponding file descriptor refers to a pipe. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.17, +glibc 2.5. +.P +In Linux 2.6.30 and earlier, +exactly one of +.I fd_in +and +.I fd_out +was required to be a pipe. +Since Linux 2.6.31, +.\" commit 7c77f0b3f9208c339a4b40737bb2cb0f0319bb8d +both arguments may refer to pipes. +.SH NOTES +The three system calls +.BR splice (), +.BR vmsplice (2), +and +.BR tee (2), +provide user-space programs with full control over an arbitrary +kernel buffer, implemented within the kernel using the same type +of buffer that is used for a pipe. +In overview, these system calls perform the following tasks: +.TP +.BR splice () +moves data from the buffer to an arbitrary file descriptor, or vice versa, +or from one buffer to another. +.TP +.BR tee (2) +"copies" the data from one buffer to another. +.TP +.BR vmsplice (2) +"copies" data from user space into the buffer. +.P +Though we talk of copying, actual copies are generally avoided. +The kernel does this by implementing a pipe buffer as a set +of reference-counted pointers to pages of kernel memory. +The kernel creates "copies" of pages in a buffer by creating new +pointers (for the output buffer) referring to the pages, +and increasing the reference counts for the pages: +only pointers are copied, not the pages of the buffer. +.\" +.\" Linus: Now, imagine using the above in a media server, for example. +.\" Let's say that a year or two has passed, so that the video drivers +.\" have been updated to be able to do the splice thing, and what can +.\" you do? You can: +.\" +.\" - splice from the (mpeg or whatever - let's just assume that the video +.\" input is either digital or does the encoding on its own - like they +.\" pretty much all do) video input into a pipe (remember: no copies - the +.\" video input will just DMA directly into memory, and splice will just +.\" set up the pages in the pipe buffer) +.\" - tee that pipe to split it up +.\" - splice one end to a file (ie "save the compressed stream to disk") +.\" - splice the other end to a real-time video decoder window for your +.\" real-time viewing pleasure. +.\" +.\" Linus: Now, the advantage of splice()/tee() is that you can +.\" do zero-copy movement of data, and unlike sendfile() you can +.\" do it on _arbitrary_ data (and, as shown by "tee()", it's more +.\" than just sending the data to somebody else: you can duplicate +.\" the data and choose to forward it to two or more different +.\" users - for things like logging etc.). +.\" +.P +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that uses non-null +.I off_in +or +.I off_out +or that takes the address of +.BR splice , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. +.SH EXAMPLES +See +.BR tee (2). +.SH SEE ALSO +.BR copy_file_range (2), +.BR sendfile (2), +.BR tee (2), +.BR vmsplice (2), +.BR pipe (7) diff --git a/man/man2/spu_create.2 b/man/man2/spu_create.2 new file mode 100644 index 0000000..d9b6118 --- /dev/null +++ b/man/man2/spu_create.2 @@ -0,0 +1,276 @@ +.\" Copyright (c) International Business Machines Corp., 2006 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" HISTORY: +.\" 2005-09-28, created by Arnd Bergmann +.\" 2006-06-16, revised by Eduardo M. Fleury +.\" 2007-07-10, some polishing by mtk +.\" 2007-09-28, updates for newer kernels by Jeremy Kerr +.\" +.TH spu_create 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +spu_create \- create a new spu context +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SPU_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_spu_create, const char *" pathname \ +", unsigned int " flags , +.BI " mode_t " mode ", int " neighbor_fd ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR spu_create (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR spu_create () +system call is used on PowerPC machines that implement the +Cell Broadband Engine Architecture in order to access Synergistic +Processor Units (SPUs). +It creates a new logical context for an SPU in +.I pathname +and returns a file descriptor associated with it. +.I pathname +must refer to a nonexistent directory in the mount point of +the SPU filesystem +.RB ( spufs ). +If +.BR spu_create () +is successful, a directory is created at +.I pathname +and it is populated with the files described in +.BR spufs (7). +.P +When a context is created, +the returned file descriptor can only be passed to +.BR spu_run (2), +used as the +.I dirfd +argument to the +.B *at +family of system calls (e.g., +.BR openat (2)), +or closed; +other operations are not defined. +A logical SPU +context is destroyed (along with all files created within the context's +.I pathname +directory) once the last reference to the context has gone; +this usually occurs when the file descriptor returned by +.BR spu_create () +is closed. +.P +The +.I mode +argument (minus any bits set in the process's +.BR umask (2)) +specifies the permissions used for creating the new directory in +.BR spufs . +See +.BR stat (2) +for a full list of the possible +.I mode +values. +.P +The +.I neighbor_fd +is used only when the +.B SPU_CREATE_AFFINITY_SPU +flag is specified; see below. +.P +The +.I flags +argument can be zero or any bitwise OR-ed +combination of the following constants: +.TP +.B SPU_CREATE_EVENTS_ENABLED +Rather than using signals for reporting DMA errors, use the +.I event +argument to +.BR spu_run (2). +.TP +.B SPU_CREATE_GANG +Create an SPU gang instead of a context. +(A gang is a group of SPU contexts that are +functionally related to each other and which share common scheduling +parameters\[em]priority and policy. +In the future, gang scheduling may be implemented causing +the group to be switched in and out as a single unit.) +.IP +A new directory will be created at the location specified by the +.I pathname +argument. +This gang may be used to hold other SPU contexts, by providing +a pathname that is within the gang directory to further calls to +.BR spu_create (). +.TP +.B SPU_CREATE_NOSCHED +Create a context that is not affected by the SPU scheduler. +Once the context is run, +it will not be scheduled out until it is destroyed by +the creating process. +.IP +Because the context cannot be removed from the SPU, some functionality +is disabled for +.B SPU_CREATE_NOSCHED +contexts. +Only a subset of the files will be +available in this context directory in +.BR spufs . +Additionally, +.B SPU_CREATE_NOSCHED +contexts cannot dump a core file when crashing. +.IP +Creating +.B SPU_CREATE_NOSCHED +contexts requires the +.B CAP_SYS_NICE +capability. +.TP +.B SPU_CREATE_ISOLATE +Create an isolated SPU context. +Isolated contexts are protected from some +PPE (PowerPC Processing Element) +operations, +such as access to the SPU local store and the NPC register. +.IP +Creating +.B SPU_CREATE_ISOLATE +contexts also requires the +.B SPU_CREATE_NOSCHED +flag. +.TP +.BR SPU_CREATE_AFFINITY_SPU " (since Linux 2.6.23)" +.\" commit 8e68e2f248332a9c3fd4f08258f488c209bd3e0c +Create a context with affinity to another SPU context. +This affinity information is used within the SPU scheduling algorithm. +Using this flag requires that a file descriptor referring to +the other SPU context be passed in the +.I neighbor_fd +argument. +.TP +.BR SPU_CREATE_AFFINITY_MEM " (since Linux 2.6.23)" +.\" commit 8e68e2f248332a9c3fd4f08258f488c209bd3e0c +Create a context with affinity to system memory. +This affinity information +is used within the SPU scheduling algorithm. +.SH RETURN VALUE +On success, +.BR spu_create () +returns a new file descriptor. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The current user does not have write access to the +.BR spufs (7) +mount point. +.TP +.B EEXIST +An SPU context already exists at the given pathname. +.TP +.B EFAULT +.I pathname +is not a valid string pointer in the +calling process's address space. +.TP +.B EINVAL +.I pathname +is not a directory in the +.BR spufs (7) +mount point, or invalid flags have been provided. +.TP +.B ELOOP +Too many symbolic links were found while resolving +.IR pathname . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENODEV +An isolated context was requested, but the hardware does not support +SPU isolation. +.TP +.B ENOENT +Part of +.I pathname +could not be resolved. +.TP +.B ENOMEM +The kernel could not allocate all resources required. +.TP +.B ENOSPC +There are not enough SPU resources available to create +a new context or the user-specific limit for the number +of SPU contexts has been reached. +.TP +.B ENOSYS +The functionality is not provided by the current system, because +either the hardware does not provide SPUs or the spufs module is not +loaded. +.TP +.B ENOTDIR +A part of +.I pathname +is not a directory. +.TP +.B EPERM +The +.B SPU_CREATE_NOSCHED +flag has been given, but the user does not have the +.B CAP_SYS_NICE +capability. +.SH FILES +.I pathname +must point to a location beneath the mount point of +.BR spufs . +By convention, it gets mounted in +.IR /spu . +.SH STANDARDS +Linux on PowerPC. +.SH HISTORY +Linux 2.6.16. +.P +Prior to the addition of the +.B SPU_CREATE_AFFINITY_SPU +flag in Linux 2.6.23, the +.BR spu_create () +system call took only three arguments (i.e., there was no +.I neighbor_fd +argument). +.SH NOTES +.BR spu_create () +is meant to be used from libraries that implement a more abstract +interface to SPUs, not to be used from regular applications. +See +.UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ +.UE +for the recommended libraries. +.SH EXAMPLES +See +.BR spu_run (2) +for an example of the use of +.BR spu_create () +.SH SEE ALSO +.BR close (2), +.BR spu_run (2), +.BR capabilities (7), +.BR spufs (7) diff --git a/man/man2/spu_run.2 b/man/man2/spu_run.2 new file mode 100644 index 0000000..54f4e69 --- /dev/null +++ b/man/man2/spu_run.2 @@ -0,0 +1,260 @@ +.\" Copyright (c) International Business Machines Corp., 2006 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" HISTORY: +.\" 2005-09-28, created by Arnd Bergmann +.\" 2006-06-16, revised by Eduardo M. Fleury +.\" 2007-07-10, some polishing by mtk +.\" 2007-09-28, updates for newer kernels, added example +.\" by Jeremy Kerr +.\" +.TH spu_run 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +spu_run \- execute an SPU context +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SPU_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_spu_run, int " fd ", uint32_t *" npc \ +", uint32_t *" event ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR spu_run (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The +.BR spu_run () +system call is used on PowerPC machines that implement the +Cell Broadband Engine Architecture in order to access Synergistic +Processor Units (SPUs). +The +.I fd +argument is a file descriptor returned by +.BR spu_create (2) +that refers to a specific SPU context. +When the context gets scheduled to a physical SPU, +it starts execution at the instruction pointer passed in +.IR npc . +.P +Execution of SPU code happens synchronously, meaning that +.BR spu_run () +blocks while the SPU is still running. +If there is a need +to execute SPU code in parallel with other code on either the +main CPU or other SPUs, a new thread of execution must be created +first (e.g., using +.BR pthread_create (3)). +.P +When +.BR spu_run () +returns, the current value of the SPU program counter is written to +.IR npc , +so successive calls to +.BR spu_run () +can use the same +.I npc +pointer. +.P +The +.I event +argument provides a buffer for an extended status code. +If the SPU +context was created with the +.B SPU_CREATE_EVENTS_ENABLED +flag, then this buffer is populated by the Linux kernel before +.BR spu_run () +returns. +.P +The status code may be one (or more) of the following constants: +.TP +.B SPE_EVENT_DMA_ALIGNMENT +A DMA alignment error occurred. +.TP +.B SPE_EVENT_INVALID_DMA +An invalid MFC DMA command was attempted. +.\" SPE_EVENT_SPE_DATA_SEGMENT is defined, but does not seem to be generated +.\" at any point (in Linux 5.9 sources). +.TP +.B SPE_EVENT_SPE_DATA_STORAGE +A DMA storage error occurred. +.TP +.B SPE_EVENT_SPE_ERROR +An illegal instruction was executed. +.P +NULL +is a valid value for the +.I event +argument. +In this case, the events will not be reported to the calling process. +.SH RETURN VALUE +On success, +.BR spu_run () +returns the value of the +.I spu_status +register. +On failure, it returns \-1 and sets +.I errno +is set to indicate the error. +.P +The +.I spu_status +register value is a bit mask of status codes and +optionally a 14-bit code returned from the +.B stop-and-signal +instruction on the SPU. +The bit masks for the status codes +are: +.TP +.B 0x02 +SPU was stopped by a +.B stop-and-signal +instruction. +.TP +.B 0x04 +SPU was stopped by a +.B halt +instruction. +.TP +.B 0x08 +SPU is waiting for a channel. +.TP +.B 0x10 +SPU is in single-step mode. +.TP +.B 0x20 +SPU has tried to execute an invalid instruction. +.TP +.B 0x40 +SPU has tried to access an invalid channel. +.TP +.B 0x3fff0000 +The bits masked with this value contain the code returned from a +.B stop-and-signal +instruction. +These bits are valid only if the 0x02 bit is set. +.P +If +.BR spu_run () +has not returned an error, one or more bits among the lower eight +ones are always set. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EFAULT +.I npc +is not a valid pointer, or +.I event +is non-NULL and an invalid pointer. +.TP +.B EINTR +A signal occurred while +.BR spu_run () +was in progress; see +.BR signal (7). +The +.I npc +value has been updated to the new program counter value if +necessary. +.TP +.B EINVAL +.I fd +is not a valid file descriptor returned from +.BR spu_create (2). +.TP +.B ENOMEM +There was not enough memory available to handle a page fault +resulting from a Memory Flow Controller (MFC) direct memory access. +.TP +.B ENOSYS +The functionality is not provided by the current system, because +either the hardware does not provide SPUs or the spufs module is not +loaded. +.SH STANDARDS +Linux on PowerPC. +.SH HISTORY +Linux 2.6.16. +.SH NOTES +.BR spu_run () +is meant to be used from libraries that implement a more abstract +interface to SPUs, not to be used from regular applications. +See +.UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ +.UE +for the recommended libraries. +.SH EXAMPLES +The following is an example of running a simple, one-instruction SPU +program with the +.BR spu_run () +system call. +.P +.\" SRC BEGIN (spu_run.c) +.EX +#include +#include +#include +#include +#include +#include +#include +\& +int main(void) +{ + int context, fd, spu_status; + uint32_t instruction, npc; +\& + context = syscall(SYS_spu_create, "/spu/example\-context", 0, 0755); + if (context == \-1) + err(EXIT_FAILURE, "spu_create"); +\& + /* + * Write a \[aq]stop 0x1234\[aq] instruction to the SPU\[aq]s + * local store memory. + */ + instruction = 0x00001234; +\& + fd = open("/spu/example\-context/mem", O_RDWR); + if (fd == \-1) + err(EXIT_FAILURE, "open"); + write(fd, &instruction, sizeof(instruction)); +\& + /* + * set npc to the starting instruction address of the + * SPU program. Since we wrote the instruction at the + * start of the mem file, the entry point will be 0x0. + */ + npc = 0; +\& + spu_status = syscall(SYS_spu_run, context, &npc, NULL); + if (spu_status == \-1) + err(EXIT_FAILURE, "open"); +\& + /* + * We should see a status code of 0x12340002: + * 0x00000002 (spu was stopped due to stop\-and\-signal) + * | 0x12340000 (the stop\-and\-signal code) + */ + printf("SPU Status: %#08x\en", spu_status); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.\" .SH AUTHORS +.\" Arnd Bergmann , Jeremy Kerr +.SH SEE ALSO +.BR close (2), +.BR spu_create (2), +.BR capabilities (7), +.BR spufs (7) diff --git a/man/man2/ssetmask.2 b/man/man2/ssetmask.2 new file mode 100644 index 0000000..a7f99d2 --- /dev/null +++ b/man/man2/ssetmask.2 @@ -0,0 +1 @@ +.so man2/sgetmask.2 diff --git a/man/man2/stat.2 b/man/man2/stat.2 new file mode 100644 index 0000000..198aca0 --- /dev/null +++ b/man/man2/stat.2 @@ -0,0 +1,539 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95 +.\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-05-18 by Todd Larason +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 1995-01-09 by Richard Kettlewell +.\" Modified 1998-05-13 by Michael Haardt +.\" Modified 1999-07-06 by aeb & Albert Cahalan +.\" Modified 2000-01-07 by aeb +.\" Modified 2004-06-23 by Michael Kerrisk +.\" 2007-06-08 mtk: Added example program +.\" 2007-07-05 mtk: Added details on underlying system call interfaces +.\" +.TH stat 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stat, fstat, lstat, fstatat \- get file status +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int stat(const char *restrict " pathname , +.BI " struct stat *restrict " statbuf ); +.BI "int fstat(int " fd ", struct stat *" statbuf ); +.BI "int lstat(const char *restrict " pathname , +.BI " struct stat *restrict " statbuf ); +.P +.BR "#include " "/* Definition of " AT_* " constants */" +.B #include +.P +.BI "int fstatat(int " dirfd ", const char *restrict " pathname , +.BI " struct stat *restrict " statbuf ", int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR lstat (): +.nf + /* Since glibc 2.20 */ _DEFAULT_SOURCE + || _XOPEN_SOURCE >= 500 +.\" _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L + || /* glibc 2.19 and earlier */ _BSD_SOURCE +.fi +.P +.BR fstatat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +These functions return information about a file, in the buffer pointed to by +.IR statbuf . +No permissions are required on the file itself, but\[em]in the case of +.BR stat (), +.BR fstatat (), +and +.BR lstat ()\[em]execute +(search) permission is required on all of the directories in +.I pathname +that lead to the file. +.P +.BR stat () +and +.BR fstatat () +retrieve information about the file pointed to by +.IR pathname ; +the differences for +.BR fstatat () +are described below. +.P +.BR lstat () +is identical to +.BR stat (), +except that if +.I pathname +is a symbolic link, then it returns information about the link itself, +not the file that the link refers to. +.P +.BR fstat () +is identical to +.BR stat (), +except that the file about which information is to be retrieved +is specified by the file descriptor +.IR fd . +.\" +.SS The stat structure +All of these system calls return a +.I stat +structure (see +.BR stat (3type)). +.P +.\" Background: inode attributes are modified with i_mutex held, but +.\" read by stat() without taking the mutex. +.IR Note : +for performance and simplicity reasons, different fields in the +.I stat +structure may contain state information from different moments +during the execution of the system call. +For example, if +.I st_mode +or +.I st_uid +is changed by another process by calling +.BR chmod (2) +or +.BR chown (2), +.BR stat () +might return the old +.I st_mode +together with the new +.IR st_uid , +or the old +.I st_uid +together with the new +.IR st_mode . +.SS fstatat() +The +.BR fstatat () +system call is a more general interface for accessing file information +which can still provide exactly the behavior of each of +.BR stat (), +.BR lstat (), +and +.BR fstat (). +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR stat () +and +.BR lstat () +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR stat () +and +.BR lstat ()). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +.I flags +can either be 0, or include one or more of the following flags ORed: +.TP +.BR AT_EMPTY_PATH " (since Linux 2.6.39)" +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory, and +the behavior of +.BR fstatat () +is similar to that of +.BR fstat (). +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed +to obtain its definition. +.TP +.BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)" +Don't automount the terminal ("basename") component of +.I pathname. +Since Linux 3.1 this flag is ignored. +Since Linux 4.11 this flag is implied. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead return information about the link itself, like +.BR lstat (). +(By default, +.BR fstatat () +dereferences symbolic links, like +.BR stat ().) +.P +See +.BR openat (2) +for an explanation of the need for +.BR fstatat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories +in the path prefix of +.IR pathname . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.I fd +is not a valid open file descriptor. +.TP +.B EBADF +.RB ( fstatat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +Bad address. +.TP +.B EINVAL +.RB ( fstatat ()) +Invalid flag specified in +.IR flags . +.TP +.B ELOOP +Too many symbolic links encountered while traversing the path. +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A component of +.I pathname +does not exist or is a dangling symbolic link. +.TP +.B ENOENT +.I pathname +is an empty string and +.B AT_EMPTY_PATH +was not specified in +.IR flags . +.TP +.B ENOMEM +Out of memory (i.e., kernel memory). +.TP +.B ENOTDIR +A component of the path prefix of +.I pathname +is not a directory. +.TP +.B ENOTDIR +.RB ( fstatat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B EOVERFLOW +.I pathname +or +.I fd +refers to a file whose size, inode number, +or number of blocks cannot be represented in, respectively, the types +.IR off_t , +.IR ino_t , +or +.IR blkcnt_t . +This error can occur when, for example, +an application compiled on a 32-bit platform without +.I \-D_FILE_OFFSET_BITS=64 +calls +.BR stat () +on a file whose size exceeds +.I (1<<31)\-1 +bytes. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR stat () +.TQ +.BR fstat () +.TQ +.BR lstat () +SVr4, 4.3BSD, POSIX.1-2001. +.\" SVr4 documents additional +.\" .BR fstat () +.\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4 +.\" documents additional +.\" .BR stat () +.\" and +.\" .BR lstat () +.\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW. +.TP +.BR fstatat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. +.P +According to POSIX.1-2001, +.BR lstat () +on a symbolic link need return valid information only in the +.I st_size +field and the file type of the +.I st_mode +field of the +.I stat +structure. +POSIX.1-2008 tightens the specification, requiring +.BR lstat () +to return valid information in all fields except the mode bits in +.IR st_mode . +.P +Use of the +.I st_blocks +and +.I st_blksize +fields may be less portable. +(They were introduced in BSD. +The interpretation differs between systems, +and possibly on a single system when NFS mounts are involved.) +.SS C library/kernel differences +Over time, increases in the size of the +.I stat +structure have led to three successive versions of +.BR stat (): +.IR sys_stat () +(slot +.IR __NR_oldstat ), +.IR sys_newstat () +(slot +.IR __NR_stat ), +and +.I sys_stat64() +(slot +.IR __NR_stat64 ) +on 32-bit platforms such as i386. +The first two versions were already present in Linux 1.0 +(albeit with different names); +.\" See include/asm-i386/stat.h in the Linux 2.4 source code for the +.\" various versions of the structure definitions +the last was added in Linux 2.4. +Similar remarks apply for +.BR fstat () +and +.BR lstat (). +.P +The kernel-internal versions of the +.I stat +structure dealt with by the different versions are, respectively: +.TP +.I __old_kernel_stat +The original structure, with rather narrow fields, and no padding. +.TP +.I stat +Larger +.I st_ino +field and padding added to various parts of the structure to +allow for future expansion. +.TP +.I stat64 +Even larger +.I st_ino +field, +larger +.I st_uid +and +.I st_gid +fields to accommodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits, +and various other enlarged fields and further padding in the structure. +(Various padding bytes were eventually consumed in Linux 2.6, +with the advent of 32-bit device IDs and nanosecond components +for the timestamp fields.) +.P +The glibc +.BR stat () +wrapper function hides these details from applications, +invoking the most recent version of the system call provided by the kernel, +and repacking the returned information if required for old binaries. +.\" +.\" A note from Andries Brouwer, July 2007 +.\" +.\" > Is the story not rather more complicated for some calls like +.\" > stat(2)? +.\" +.\" Yes and no, mostly no. See /usr/include/sys/stat.h . +.\" +.\" The idea is here not so much that syscalls change, but that +.\" the definitions of struct stat and of the types dev_t and mode_t change. +.\" This means that libc (even if it does not call the kernel +.\" but only calls some internal function) must know what the +.\" format of dev_t or of struct stat is. +.\" The communication between the application and libc goes via +.\" the include file that defines a _STAT_VER and +.\" _MKNOD_VER describing the layout of the data that user space +.\" uses. Each (almost each) occurrence of stat() is replaced by +.\" an occurrence of xstat() where the first parameter of xstat() +.\" is this version number _STAT_VER. +.\" +.\" Now, also the definitions used by the kernel change. +.\" But glibc copes with this in the standard way, and the +.\" struct stat as returned by the kernel is repacked into +.\" the struct stat as expected by the application. +.\" Thus, _STAT_VER and this setup cater for the application-libc +.\" interface, rather than the libc-kernel interface. +.\" +.\" (Note that the details depend on gcc being used as c compiler.) +.P +On modern 64-bit systems, life is simpler: there is a single +.BR stat () +system call and the kernel deals with a +.I stat +structure that contains fields of a sufficient size. +.P +The underlying system call employed by the glibc +.BR fstatat () +wrapper function is actually called +.BR fstatat64 () +or, on some architectures, +.\" strace(1) shows the name "newfstatat" on x86-64 +.BR newfstatat (). +.SH EXAMPLES +The following program calls +.BR lstat () +and displays selected fields in the returned +.I stat +structure. +.P +.\" SRC BEGIN (stat.c) +.EX +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + struct stat sb; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (lstat(argv[1], &sb) == \-1) { + perror("lstat"); + exit(EXIT_FAILURE); + } +\& + printf("ID of containing device: [%x,%x]\en", + major(sb.st_dev), + minor(sb.st_dev)); +\& + printf("File type: "); +\& + switch (sb.st_mode & S_IFMT) { + case S_IFBLK: printf("block device\en"); break; + case S_IFCHR: printf("character device\en"); break; + case S_IFDIR: printf("directory\en"); break; + case S_IFIFO: printf("FIFO/pipe\en"); break; + case S_IFLNK: printf("symlink\en"); break; + case S_IFREG: printf("regular file\en"); break; + case S_IFSOCK: printf("socket\en"); break; + default: printf("unknown?\en"); break; + } +\& + printf("I\-node number: %ju\en", (uintmax_t) sb.st_ino); +\& + printf("Mode: %jo (octal)\en", + (uintmax_t) sb.st_mode); +\& + printf("Link count: %ju\en", (uintmax_t) sb.st_nlink); + printf("Ownership: UID=%ju GID=%ju\en", + (uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid); +\& + printf("Preferred I/O block size: %jd bytes\en", + (intmax_t) sb.st_blksize); + printf("File size: %jd bytes\en", + (intmax_t) sb.st_size); + printf("Blocks allocated: %jd\en", + (intmax_t) sb.st_blocks); +\& + printf("Last status change: %s", ctime(&sb.st_ctime)); + printf("Last file access: %s", ctime(&sb.st_atime)); + printf("Last file modification: %s", ctime(&sb.st_mtime)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ls (1), +.BR stat (1), +.BR access (2), +.BR chmod (2), +.BR chown (2), +.BR readlink (2), +.BR statx (2), +.BR utime (2), +.BR stat (3type), +.BR capabilities (7), +.BR inode (7), +.BR symlink (7) diff --git a/man/man2/stat64.2 b/man/man2/stat64.2 new file mode 100644 index 0000000..b1a86c1 --- /dev/null +++ b/man/man2/stat64.2 @@ -0,0 +1 @@ +.so man2/stat.2 diff --git a/man/man2/statfs.2 b/man/man2/statfs.2 new file mode 100644 index 0000000..99a1807 --- /dev/null +++ b/man/man2/statfs.2 @@ -0,0 +1,389 @@ +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2003-08-17 by Walter Harms +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH statfs 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +statfs, fstatfs \- get filesystem statistics +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " "/* or */" +.P +.BI "int statfs(const char *" path ", struct statfs *" buf ); +.BI "int fstatfs(int " fd ", struct statfs *" buf ); +.fi +.P +Unless you need the +.I f_type +field, you should use the standard +.BR statvfs (3) +interface instead. +.SH DESCRIPTION +The +.BR statfs () +system call returns information about a mounted filesystem. +.I path +is the pathname of any file within the mounted filesystem. +.I buf +is a pointer to a +.I statfs +structure defined approximately as follows: +.P +.in +4n +.EX +struct statfs { + __fsword_t f_type; /* Type of filesystem (see below) */ + __fsword_t f_bsize; /* Optimal transfer block size */ + fsblkcnt_t f_blocks; /* Total data blocks in filesystem */ + fsblkcnt_t f_bfree; /* Free blocks in filesystem */ + fsblkcnt_t f_bavail; /* Free blocks available to + unprivileged user */ + fsfilcnt_t f_files; /* Total inodes in filesystem */ + fsfilcnt_t f_ffree; /* Free inodes in filesystem */ + fsid_t f_fsid; /* Filesystem ID */ + __fsword_t f_namelen; /* Maximum length of filenames */ + __fsword_t f_frsize; /* Fragment size (since Linux 2.6) */ + __fsword_t f_flags; /* Mount flags of filesystem + (since Linux 2.6.36) */ + __fsword_t f_spare[xxx]; + /* Padding bytes reserved for future use */ +}; +.EE +.in +.P +The following filesystem types may appear in +.IR f_type : +.P +.in +4n +.EX +ADFS_SUPER_MAGIC 0xadf5 +AFFS_SUPER_MAGIC 0xadff +AFS_SUPER_MAGIC 0x5346414f +ANON_INODE_FS_MAGIC 0x09041934 /* Anonymous inode FS (for + pseudofiles that have no name; + e.g., epoll, signalfd, bpf) */ +AUTOFS_SUPER_MAGIC 0x0187 +BDEVFS_MAGIC 0x62646576 +BEFS_SUPER_MAGIC 0x42465331 +BFS_MAGIC 0x1badface +BINFMTFS_MAGIC 0x42494e4d +BPF_FS_MAGIC 0xcafe4a11 +BTRFS_SUPER_MAGIC 0x9123683e +BTRFS_TEST_MAGIC 0x73727279 +CGROUP_SUPER_MAGIC 0x27e0eb /* Cgroup pseudo FS */ +CGROUP2_SUPER_MAGIC 0x63677270 /* Cgroup v2 pseudo FS */ +CIFS_MAGIC_NUMBER 0xff534d42 +CODA_SUPER_MAGIC 0x73757245 +COH_SUPER_MAGIC 0x012ff7b7 +CRAMFS_MAGIC 0x28cd3d45 +DEBUGFS_MAGIC 0x64626720 +DEVFS_SUPER_MAGIC 0x1373 /* Linux 2.6.17 and earlier */ +DEVPTS_SUPER_MAGIC 0x1cd1 +ECRYPTFS_SUPER_MAGIC 0xf15f +EFIVARFS_MAGIC 0xde5e81e4 +EFS_SUPER_MAGIC 0x00414a53 +EXT_SUPER_MAGIC 0x137d /* Linux 2.0 and earlier */ +EXT2_OLD_SUPER_MAGIC 0xef51 +EXT2_SUPER_MAGIC 0xef53 +EXT3_SUPER_MAGIC 0xef53 +EXT4_SUPER_MAGIC 0xef53 +F2FS_SUPER_MAGIC 0xf2f52010 +FUSE_SUPER_MAGIC 0x65735546 +FUTEXFS_SUPER_MAGIC 0xbad1dea /* Unused */ +HFS_SUPER_MAGIC 0x4244 +HOSTFS_SUPER_MAGIC 0x00c0ffee +HPFS_SUPER_MAGIC 0xf995e849 +HUGETLBFS_MAGIC 0x958458f6 +ISOFS_SUPER_MAGIC 0x9660 +JFFS2_SUPER_MAGIC 0x72b6 +JFS_SUPER_MAGIC 0x3153464a +MINIX_SUPER_MAGIC 0x137f /* original minix FS */ +MINIX_SUPER_MAGIC2 0x138f /* 30 char minix FS */ +MINIX2_SUPER_MAGIC 0x2468 /* minix V2 FS */ +MINIX2_SUPER_MAGIC2 0x2478 /* minix V2 FS, 30 char names */ +MINIX3_SUPER_MAGIC 0x4d5a /* minix V3 FS, 60 char names */ +MQUEUE_MAGIC 0x19800202 /* POSIX message queue FS */ +MSDOS_SUPER_MAGIC 0x4d44 +MTD_INODE_FS_MAGIC 0x11307854 +NCP_SUPER_MAGIC 0x564c +NFS_SUPER_MAGIC 0x6969 +NILFS_SUPER_MAGIC 0x3434 +NSFS_MAGIC 0x6e736673 +NTFS_SB_MAGIC 0x5346544e +OCFS2_SUPER_MAGIC 0x7461636f +OPENPROM_SUPER_MAGIC 0x9fa1 +OVERLAYFS_SUPER_MAGIC 0x794c7630 +PIPEFS_MAGIC 0x50495045 +PROC_SUPER_MAGIC 0x9fa0 /* /proc FS */ +PSTOREFS_MAGIC 0x6165676c +QNX4_SUPER_MAGIC 0x002f +QNX6_SUPER_MAGIC 0x68191122 +RAMFS_MAGIC 0x858458f6 +REISERFS_SUPER_MAGIC 0x52654973 +ROMFS_MAGIC 0x7275 +SECURITYFS_MAGIC 0x73636673 +SELINUX_MAGIC 0xf97cff8c +SMACK_MAGIC 0x43415d53 +SMB_SUPER_MAGIC 0x517b +SMB2_MAGIC_NUMBER 0xfe534d42 +SOCKFS_MAGIC 0x534f434b +SQUASHFS_MAGIC 0x73717368 +SYSFS_MAGIC 0x62656572 +SYSV2_SUPER_MAGIC 0x012ff7b6 +SYSV4_SUPER_MAGIC 0x012ff7b5 +TMPFS_MAGIC 0x01021994 +TRACEFS_MAGIC 0x74726163 +UDF_SUPER_MAGIC 0x15013346 +UFS_MAGIC 0x00011954 +USBDEVICE_SUPER_MAGIC 0x9fa2 +V9FS_MAGIC 0x01021997 +VXFS_SUPER_MAGIC 0xa501fcf5 +XENFS_SUPER_MAGIC 0xabba1974 +XENIX_SUPER_MAGIC 0x012ff7b4 +XFS_SUPER_MAGIC 0x58465342 +_XIAFS_SUPER_MAGIC 0x012fd16d /* Linux 2.0 and earlier */ +.EE +.in +.P +Most of these MAGIC constants are defined in +.IR /usr/include/linux/magic.h , +and some are hardcoded in kernel sources. +.P +The +.I f_flags +field is a bit mask indicating mount options for the filesystem. +It contains zero or more of the following bits: +.\" XXX Keep this list in sync with statvfs(3) +.TP +.B ST_MANDLOCK +Mandatory locking is permitted on the filesystem (see +.BR fcntl (2)). +.TP +.B ST_NOATIME +Do not update access times; see +.BR mount (2). +.TP +.B ST_NODEV +Disallow access to device special files on this filesystem. +.TP +.B ST_NODIRATIME +Do not update directory access times; see +.BR mount (2). +.TP +.B ST_NOEXEC +Execution of programs is disallowed on this filesystem. +.TP +.B ST_NOSUID +The set-user-ID and set-group-ID bits are ignored by +.BR exec (3) +for executable files on this filesystem +.TP +.B ST_RDONLY +This filesystem is mounted read-only. +.TP +.B ST_RELATIME +Update atime relative to mtime/ctime; see +.BR mount (2). +.TP +.B ST_SYNCHRONOUS +Writes are synched to the filesystem immediately (see the description of +.B O_SYNC +in +.BR open (2)). +.TP +.BR ST_NOSYMFOLLOW " (since Linux 5.10)" +.\" dab741e0e02bd3c4f5e2e97be74b39df2523fc6e +Symbolic links are not followed when resolving paths; see +.BR mount (2). +.P +Nobody knows what +.I f_fsid +is supposed to contain (but see below). +.P +Fields that are undefined for a particular filesystem are set to 0. +.P +.BR fstatfs () +returns the same information about an open file referenced by descriptor +.IR fd . +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.RB ( statfs ()) +Search permission is denied for a component of the path prefix of +.IR path . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( fstatfs ()) +.I fd +is not a valid open file descriptor. +.TP +.B EFAULT +.I buf +or +.I path +points to an invalid address. +.TP +.B EINTR +The call was interrupted by a signal; see +.BR signal (7). +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +.RB ( statfs ()) +Too many symbolic links were encountered in translating +.IR path . +.TP +.B ENAMETOOLONG +.RB ( statfs ()) +.I path +is too long. +.TP +.B ENOENT +.RB ( statfs ()) +The file referred to by +.I path +does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSYS +The filesystem does not support this call. +.TP +.B ENOTDIR +.RB ( statfs ()) +A component of the path prefix of +.I path +is not a directory. +.TP +.B EOVERFLOW +Some values were too large to be represented in the returned struct. +.SH VERSIONS +.SS The f_fsid field +Solaris, Irix, and POSIX have a system call +.BR statvfs (2) +that returns a +.I "struct statvfs" +(defined in +.IR ) +containing an +.I "unsigned long" +.IR f_fsid . +Linux, SunOS, HP-UX, 4.4BSD have a system call +.BR statfs () +that returns a +.I "struct statfs" +(defined in +.IR ) +containing a +.I fsid_t +.IR f_fsid , +where +.I fsid_t +is defined as +.IR "struct { int val[2]; }" . +The same holds for FreeBSD, except that it uses the include file +.IR . +.P +The general idea is that +.I f_fsid +contains some random stuff such that the pair +.RI ( f_fsid , ino ) +uniquely determines a file. +Some operating systems use (a variation on) the device number, +or the device number combined with the filesystem type. +Several operating systems restrict giving out the +.I f_fsid +field to the superuser only (and zero it for unprivileged users), +because this field is used in the filehandle of the filesystem +when NFS-exported, and giving it out is a security concern. +.P +Under some operating systems, the +.I fsid +can be used as the second argument to the +.BR sysfs (2) +system call. +.SH STANDARDS +Linux. +.SH HISTORY +The Linux +.BR statfs () +was inspired by the 4.4BSD one +(but they do not use the same structure). +.P +The original Linux +.BR statfs () +and +.BR fstatfs () +system calls were not designed with extremely large file sizes in mind. +Subsequently, Linux 2.6 +added new +.BR statfs64 () +and +.BR fstatfs64 () +system calls that employ a new structure, +.IR statfs64 . +The new structure contains the same fields as the original +.I statfs +structure, but the sizes of various fields are increased, +to accommodate large file sizes. +The glibc +.BR statfs () +and +.BR fstatfs () +wrapper functions transparently deal with the kernel differences. +.P +LSB has deprecated the library calls +.BR statfs () +and +.BR fstatfs () +and tells us to use +.BR statvfs (3) +and +.BR fstatvfs (3) +instead. +.SH NOTES +The +.I __fsword_t +type used for various fields in the +.I statfs +structure definition is a glibc internal type, +not intended for public use. +This leaves the programmer in a bit of a conundrum when trying to copy +or compare these fields to local variables in a program. +Using +.I "unsigned\ int" +for such variables suffices on most systems. +.P +Some systems have only \fI\fP, other systems also have +\fI\fP, where the former includes the latter. +So it seems +including the former is the best choice. +.SH BUGS +From Linux 2.6.38 up to and including Linux 3.1, +.\" broken in commit ff0c7d15f9787b7e8c601533c015295cc68329f8 +.\" fixed in commit d70ef97baf048412c395bb5d65791d8fe133a52b +.BR fstatfs () +failed with the error +.B ENOSYS +for file descriptors created by +.BR pipe (2). +.SH SEE ALSO +.BR stat (2), +.BR statvfs (3), +.BR path_resolution (7) diff --git a/man/man2/statfs64.2 b/man/man2/statfs64.2 new file mode 100644 index 0000000..923d3c0 --- /dev/null +++ b/man/man2/statfs64.2 @@ -0,0 +1 @@ +.so man2/statfs.2 diff --git a/man/man2/statx.2 b/man/man2/statx.2 new file mode 100644 index 0000000..855fb6e --- /dev/null +++ b/man/man2/statx.2 @@ -0,0 +1,614 @@ +'\" t +.\" Copyright (c) 2017 David Howells +.\" +.\" Derived from the stat.2 manual page: +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95 +.\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH statx 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +statx \- get file status (extended) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */" +.BR "#include " "/* Definition of " AT_* " constants */" +.B #include +.P +.BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags , +.BI " unsigned int " mask ", struct statx *restrict " statxbuf ); +.fi +.SH DESCRIPTION +This function returns information about a file, storing it in the buffer +pointed to by +.IR statxbuf . +The returned buffer is a structure of the following type: +.P +.in +4n +.EX +struct statx { + __u32 stx_mask; /* Mask of bits indicating + filled fields */ + __u32 stx_blksize; /* Block size for filesystem I/O */ + __u64 stx_attributes; /* Extra file attribute indicators */ + __u32 stx_nlink; /* Number of hard links */ + __u32 stx_uid; /* User ID of owner */ + __u32 stx_gid; /* Group ID of owner */ + __u16 stx_mode; /* File type and mode */ + __u64 stx_ino; /* Inode number */ + __u64 stx_size; /* Total size in bytes */ + __u64 stx_blocks; /* Number of 512B blocks allocated */ + __u64 stx_attributes_mask; + /* Mask to show what\[aq]s supported + in stx_attributes */ +\& + /* The following fields are file timestamps */ + struct statx_timestamp stx_atime; /* Last access */ + struct statx_timestamp stx_btime; /* Creation */ + struct statx_timestamp stx_ctime; /* Last status change */ + struct statx_timestamp stx_mtime; /* Last modification */ +\& + /* If this file represents a device, then the next two + fields contain the ID of the device */ + __u32 stx_rdev_major; /* Major ID */ + __u32 stx_rdev_minor; /* Minor ID */ +\& + /* The next two fields contain the ID of the device + containing the filesystem where the file resides */ + __u32 stx_dev_major; /* Major ID */ + __u32 stx_dev_minor; /* Minor ID */ +\& + __u64 stx_mnt_id; /* Mount ID */ +\& + /* Direct I/O alignment restrictions */ + __u32 stx_dio_mem_align; + __u32 stx_dio_offset_align; +}; +.EE +.in +.P +The file timestamps are structures of the following type: +.P +.in +4n +.EX +struct statx_timestamp { + __s64 tv_sec; /* Seconds since the Epoch (UNIX time) */ + __u32 tv_nsec; /* Nanoseconds since tv_sec */ +}; +.EE +.in +.P +(Note that reserved space and padding is omitted.) +.SS +Invoking \fBstatx\fR(): +To access a file's status, no permissions are required on the file itself, +but in the case of +.BR statx () +with a pathname, +execute (search) permission is required on all of the directories in +.I pathname +that lead to the file. +.P +.BR statx () +uses +.IR pathname , +.IR dirfd , +and +.I flags +to identify the target file in one of the following ways: +.TP +An absolute pathname +If +.I pathname +begins with a slash, +then it is an absolute pathname that identifies the target file. +In this case, +.I dirfd +is ignored. +.TP +A relative pathname +If +.I pathname +is a string that begins with a character other than a slash and +.I dirfd +is +.BR AT_FDCWD , +then +.I pathname +is a relative pathname that is interpreted relative to the process's +current working directory. +.TP +A directory-relative pathname +If +.I pathname +is a string that begins with a character other than a slash and +.I dirfd +is a file descriptor that refers to a directory, then +.I pathname +is a relative pathname that is interpreted relative to the directory +referred to by +.IR dirfd . +(See +.BR openat (2) +for an explanation of why this is useful.) +.TP +By file descriptor +If +.I pathname +is an empty string and the +.B AT_EMPTY_PATH +flag is specified in +.I flags +(see below), +then the target file is the one referred to by the file descriptor +.IR dirfd . +.P +.I flags +can be used to influence a pathname-based lookup. +A value for +.I flags +is constructed by ORing together zero or more of the following constants: +.TP +.B AT_EMPTY_PATH +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +.IP +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +.TP +.B AT_NO_AUTOMOUNT +Don't automount the terminal ("basename") component of +.I pathname +if it is a directory that is an automount point. +This allows the caller to gather attributes of an automount point +(rather than the location it would mount). +This flag has no effect if the mount point has already been mounted over. +.IP +The +.B AT_NO_AUTOMOUNT +flag can be used in tools that scan directories +to prevent mass-automounting of a directory of automount points. +.IP +All of +.BR stat (2), +.BR lstat (2), +and +.BR fstatat (2) +act as though +.B AT_NO_AUTOMOUNT +was set. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +is a symbolic link, do not dereference it: +instead return information about the link itself, like +.BR lstat (2). +.P +.I flags +can also be used to control what sort of synchronization the kernel will do +when querying a file on a remote filesystem. +This is done by ORing in one of the following values: +.TP +.B AT_STATX_SYNC_AS_STAT +Do whatever +.BR stat (2) +does. +This is the default and is very much filesystem-specific. +.TP +.B AT_STATX_FORCE_SYNC +Force the attributes to be synchronized with the server. +This may require that +a network filesystem perform a data writeback to get the timestamps correct. +.TP +.B AT_STATX_DONT_SYNC +Don't synchronize anything, but rather just take whatever +the system has cached if possible. +This may mean that the information returned is approximate, but, +on a network filesystem, it may not involve a round trip to the server - even +if no lease is held. +.P +The +.I mask +argument to +.BR statx () +is used to tell the kernel which fields the caller is interested in. +.I mask +is an ORed combination of the following constants: +.P +.in +4n +.TS +lB l. +STATX_TYPE Want stx_mode & S_IFMT +STATX_MODE Want stx_mode & \[ti]S_IFMT +STATX_NLINK Want stx_nlink +STATX_UID Want stx_uid +STATX_GID Want stx_gid +STATX_ATIME Want stx_atime +STATX_MTIME Want stx_mtime +STATX_CTIME Want stx_ctime +STATX_INO Want stx_ino +STATX_SIZE Want stx_size +STATX_BLOCKS Want stx_blocks +STATX_BASIC_STATS [All of the above] +STATX_BTIME Want stx_btime +STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME. + It is deprecated and should not be used. +STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) +STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align + (since Linux 6.1; support varies by filesystem) +.TE +.in +.P +Note that, in general, the kernel does +.I not +reject values in +.I mask +other than the above. +(For an exception, see +.B EINVAL +in errors.) +Instead, it simply informs the caller which values are supported +by this kernel and filesystem via the +.I statx.stx_mask +field. +Therefore, +.I "do not" +simply set +.I mask +to +.B UINT_MAX +(all bits set), +as one or more bits may, in the future, be used to specify an +extension to the buffer. +.SS +The returned information +The status information for the target file is returned in the +.I statx +structure pointed to by +.IR statxbuf . +Included in this is +.I stx_mask +which indicates what other information has been returned. +.I stx_mask +has the same format as the +.I mask +argument and bits are set in it to indicate +which fields have been filled in. +.P +It should be noted that the kernel may return fields that weren't +requested and may fail to return fields that were requested, +depending on what the backing filesystem supports. +(Fields that are given values despite being unrequested can just be ignored.) +In either case, +.I stx_mask +will not be equal +.IR mask . +.P +If a filesystem does not support a field or if it has +an unrepresentable value (for instance, a file with an exotic type), +then the mask bit corresponding to that field will be cleared in +.I stx_mask +even if the user asked for it and a dummy value will be filled in for +compatibility purposes if one is available (e.g., a dummy UID and GID may be +specified to mount under some circumstances). +.P +A filesystem may also fill in fields that the caller didn't ask for if it has +values for them available and the information is available at no extra cost. +If this happens, the corresponding bits will be set in +.IR stx_mask . +.P +.\" Background: inode attributes are modified with i_mutex held, but +.\" read by stat() without taking the mutex. +.IR Note : +for performance and simplicity reasons, different fields in the +.I statx +structure may contain state information from different moments +during the execution of the system call. +For example, if +.I stx_mode +or +.I stx_uid +is changed by another process by calling +.BR chmod (2) +or +.BR chown (2), +.BR stat () +might return the old +.I stx_mode +together with the new +.IR stx_uid , +or the old +.I stx_uid +together with the new +.IR stx_mode . +.P +Apart from +.I stx_mask +(which is described above), the fields in the +.I statx +structure are: +.TP +.I stx_blksize +The "preferred" block size for efficient filesystem I/O. +(Writing to a file in +smaller chunks may cause an inefficient read-modify-rewrite.) +.TP +.I stx_attributes +Further status information about the file (see below for more information). +.TP +.I stx_nlink +The number of hard links on a file. +.TP +.I stx_uid +This field contains the user ID of the owner of the file. +.TP +.I stx_gid +This field contains the ID of the group owner of the file. +.TP +.I stx_mode +The file type and mode. +See +.BR inode (7) +for details. +.TP +.I stx_ino +The inode number of the file. +.TP +.I stx_size +The size of the file (if it is a regular file or a symbolic link) in bytes. +The size of a symbolic link is the length of the pathname it contains, +without a terminating null byte. +.TP +.I stx_blocks +The number of blocks allocated to the file on the medium, in 512-byte units. +(This may be smaller than +.IR stx_size /512 +when the file has holes.) +.TP +.I stx_attributes_mask +A mask indicating which bits in +.I stx_attributes +are supported by the VFS and the filesystem. +.TP +.I stx_atime +The file's last access timestamp. +.TP +.I stx_btime +The file's creation timestamp. +.TP +.I stx_ctime +The file's last status change timestamp. +.TP +.I stx_mtime +The file's last modification timestamp. +.TP +.IR stx_dev_major " and " stx_dev_minor +The device on which this file (inode) resides. +.TP +.IR stx_rdev_major " and " stx_rdev_minor +The device that this file (inode) represents if the file is of block or +character device type. +.TP +.I stx_mnt_id +.\" commit fa2fcf4f1df1559a0a4ee0f46915b496cc2ebf60 +The mount ID of the mount containing the file. +This is the same number reported by +.BR name_to_handle_at (2) +and corresponds to the number in the first field in one of the records in +.IR /proc/self/mountinfo . +.TP +.I stx_dio_mem_align +The alignment (in bytes) required for user memory buffers for direct I/O +.RB ( O_DIRECT ) +on this file, +or 0 if direct I/O is not supported on this file. +.IP +.B STATX_DIOALIGN +.RI ( stx_dio_mem_align +and +.IR stx_dio_offset_align ) +is supported on block devices since Linux 6.1. +The support on regular files varies by filesystem; +it is supported by ext4, f2fs, and xfs since Linux 6.1. +.TP +.I stx_dio_offset_align +The alignment (in bytes) required for file offsets and I/O segment lengths +for direct I/O +.RB ( O_DIRECT ) +on this file, +or 0 if direct I/O is not supported on this file. +This will only be nonzero if +.I stx_dio_mem_align +is nonzero, and vice versa. +.P +For further information on the above fields, see +.BR inode (7). +.\" +.SS File attributes +The +.I stx_attributes +field contains a set of ORed flags that indicate additional attributes +of the file. +Note that any attribute that is not indicated as supported by +.I stx_attributes_mask +has no usable value here. +The bits in +.I stx_attributes_mask +correspond bit-by-bit to +.IR stx_attributes . +.P +The flags are as follows: +.TP +.B STATX_ATTR_COMPRESSED +The file is compressed by the filesystem and may take extra resources +to access. +.TP +.B STATX_ATTR_IMMUTABLE +The file cannot be modified: it cannot be deleted or renamed, +no hard links can be created to this file and no data can be written to it. +See +.BR chattr (1). +.TP +.B STATX_ATTR_APPEND +The file can only be opened in append mode for writing. +Random access writing +is not permitted. +See +.BR chattr (1). +.TP +.B STATX_ATTR_NODUMP +File is not a candidate for backup when a backup program such as +.BR dump (8) +is run. +See +.BR chattr (1). +.TP +.B STATX_ATTR_ENCRYPTED +A key is required for the file to be encrypted by the filesystem. +.TP +.BR STATX_ATTR_VERITY " (since Linux 5.5)" +.\" commit 3ad2522c64cff1f5aebb987b00683268f0cc7c29 +The file has fs-verity enabled. +It cannot be written to, and all reads from it will be verified +against a cryptographic hash that covers the +entire file (e.g., via a Merkle tree). +.TP +.BR STATX_ATTR_DAX " (since Linux 5.8)" +The file is in the DAX (cpu direct access) state. +DAX state attempts to +minimize software cache effects for both I/O and memory mappings of this file. +It requires a file system which has been configured to support DAX. +.IP +DAX generally assumes all accesses are via CPU load / store instructions +which can minimize overhead for small accesses, +but may adversely affect CPU utilization for large transfers. +.IP +File I/O is done directly to/from user-space buffers and memory mapped I/O may +be performed with direct memory mappings that bypass the kernel page cache. +.IP +While the DAX property tends to result in data being transferred synchronously, +it does not give the same guarantees as the +.B O_SYNC +flag (see +.BR open (2)), +where data and the necessary metadata are transferred together. +.IP +A DAX file may support being mapped with the +.B MAP_SYNC +flag, which enables a +program to use CPU cache flush instructions to persist CPU store operations +without an explicit +.BR fsync (2). +See +.BR mmap (2) +for more information. +.TP +.BR STATX_ATTR_MOUNT_ROOT " (since Linux 5.8)" +.\" commit 80340fe3605c0e78cfe496c3b3878be828cfdbfe +The file is the root of a mount. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories +in the path prefix of +.IR pathname . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I pathname +or +.I statxbuf +is NULL or points to a location outside the process's +accessible address space. +.TP +.B EINVAL +Invalid flag specified in +.IR flags . +.TP +.B EINVAL +Reserved flag specified in +.IR mask . +(Currently, there is one such flag, designated by the constant +.BR STATX__RESERVED , +with the value 0x80000000U.) +.TP +.B ELOOP +Too many symbolic links encountered while traversing the pathname. +.TP +.B ENAMETOOLONG +.I pathname +is too long. +.TP +.B ENOENT +A component of +.I pathname +does not exist, or +.I pathname +is an empty string and +.B AT_EMPTY_PATH +was not specified in +.IR flags . +.TP +.B ENOMEM +Out of memory (i.e., kernel memory). +.TP +.B ENOTDIR +A component of the path prefix of +.I pathname +is not a directory or +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.11, +glibc 2.28. +.SH SEE ALSO +.BR ls (1), +.BR stat (1), +.BR access (2), +.BR chmod (2), +.BR chown (2), +.BR name_to_handle_at (2), +.BR readlink (2), +.BR stat (2), +.BR utime (2), +.BR proc (5), +.BR capabilities (7), +.BR inode (7), +.BR symlink (7) diff --git a/man/man2/stime.2 b/man/man2/stime.2 new file mode 100644 index 0000000..04195ea --- /dev/null +++ b/man/man2/stime.2 @@ -0,0 +1,73 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 2001-03-16 by Andries Brouwer +.\" Modified 2004-05-27 by Michael Kerrisk +.\" +.TH stime 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stime \- set time +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int stime(const time_t *" t ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR stime (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +.BR NOTE : +This function is deprecated; +use +.BR clock_settime (2) +instead. +.P +.BR stime () +sets the system's idea of the time and date. +The time, pointed +to by \fIt\fP, is measured in seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.BR stime () +may be executed only by the superuser. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Error in getting information from user space. +.TP +.B EPERM +The calling process has insufficient privilege. +Under Linux, the +.B CAP_SYS_TIME +privilege is required. +.SH STANDARDS +None. +.SH HISTORY +SVr4. +.P +Starting with glibc 2.31, +this function is no longer available to newly linked applications +and is no longer declared in +.IR . +.SH SEE ALSO +.BR date (1), +.BR settimeofday (2), +.BR capabilities (7) diff --git a/man/man2/stty.2 b/man/man2/stty.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/stty.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/subpage_prot.2 b/man/man2/subpage_prot.2 new file mode 100644 index 0000000..da0643f --- /dev/null +++ b/man/man2/subpage_prot.2 @@ -0,0 +1,118 @@ +.\" Copyright (c) 2010 Michael Kerrisk +.\" based on a proposal from Stephan Mueller +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Various pieces of text taken from the kernel source and the commentary +.\" in Linux commit fa28237cfcc5827553044cbd6ee52e33692b0faa +.\" both written by Paul Mackerras +.\" +.TH subpage_prot 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +subpage_prot \- define a subpage protection for an address range +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_subpage_prot, unsigned long " addr ", unsigned long " len , +.BI " uint32_t *" map ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR subpage_prot (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +The PowerPC-specific +.BR subpage_prot () +system call provides the facility to control the access +permissions on individual 4\ kB subpages on systems configured with +a page size of 64\ kB. +.P +The protection map is applied to the memory pages in the region starting at +.I addr +and continuing for +.I len +bytes. +Both of these arguments must be aligned to a 64-kB boundary. +.P +The protection map is specified in the buffer pointed to by +.IR map . +The map has 2 bits per 4\ kB subpage; +thus each 32-bit word specifies the protections of 16 4\ kB subpages +inside a 64\ kB page +(so, the number of 32-bit words pointed to by +.I map +should equate to the number of 64-kB pages specified by +.IR len ). +Each 2-bit field in the protection map is either 0 to allow any access, +1 to prevent writes, or 2 or 3 to prevent all accesses. +.SH RETURN VALUE +On success, +.BR subpage_prot () +returns 0. +Otherwise, one of the error codes specified below is returned. +.SH ERRORS +.TP +.B EFAULT +The buffer referred to by +.I map +is not accessible. +.TP +.B EINVAL +The +.I addr +or +.I len +arguments are incorrect. +Both of these arguments must be aligned to a multiple of the system page size, +and they must not refer to a region outside of the +address space of the process or to a region that consists of huge pages. +.TP +.B ENOMEM +Out of memory. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.25 (PowerPC). +.P +The system call is provided only if the kernel is configured with +.BR CONFIG_PPC_64K_PAGES . +.SH NOTES +Normal page protections (at the 64-kB page level) also apply; +the subpage protection mechanism is an additional constraint, +so putting 0 in a 2-bit field won't allow writes to a page that is otherwise +write-protected. +.SS Rationale +This system call is provided to assist writing emulators that +operate using 64-kB pages on PowerPC systems. +When emulating systems such as x86, which uses a smaller page size, +the emulator can no longer use the memory-management unit (MMU) +and normal system calls for controlling page protections. +(The emulator could emulate the MMU by checking and possibly remapping +the address for each memory access in software, but that is slow.) +The idea is that the emulator supplies an array of protection masks +to apply to a specified range of virtual addresses. +These masks are applied at the level where hardware page-table entries (PTEs) +are inserted into the hardware page table based on the Linux PTEs, +so the Linux PTEs are not affected. +Implicit in this is that the regions of the address space that are +protected are switched to use 4-kB hardware pages rather than 64-kB +hardware pages (on machines with hardware 64-kB page support). +.\" In the initial implementation, it was the case that: +.\" In fact the whole process is switched to use 4 kB hardware pages when the +.\" subpage_prot system call is used, but this could be improved in future +.\" to switch only the affected segments. +.\" But Paul Mackerass says (Oct 2010): I'm pretty sure we now only switch +.\" the affected segment, not the whole process. +.SH SEE ALSO +.BR mprotect (2), +.BR syscall (2) +.P +.I Documentation/admin\-guide/mm/hugetlbpage.rst +in the Linux kernel source tree diff --git a/man/man2/swapoff.2 b/man/man2/swapoff.2 new file mode 100644 index 0000000..2bd424c --- /dev/null +++ b/man/man2/swapoff.2 @@ -0,0 +1 @@ +.so man2/swapon.2 diff --git a/man/man2/swapon.2 b/man/man2/swapon.2 new file mode 100644 index 0000000..8100654 --- /dev/null +++ b/man/man2/swapon.2 @@ -0,0 +1,202 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-07-22 by Michael Chastain +.\" Modified 1995-07-23 by aeb +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1998-09-08 by aeb +.\" Modified 2004-06-17 by Michael Kerrisk +.\" Modified 2004-10-10 by aeb +.\" 2004-12-14 mtk, Anand Kumria: added new errors +.\" 2007-06-22 Ivana Varekova , mtk +.\" Update text describing limit on number of swap files. +.\" 2021-01-17 Alex Baranowski +.\" Update information about available swap files decreased by +.\" CONFIG_DEVICE_PRIVATE option. +.\" +.\" FIXME Linux 3.11 added SWAP_FLAG_DISCARD_ONCE and SWAP_FLAG_DISCARD_PAGES +.\" commit dcf6b7ddd7df8965727746f89c59229b23180e5a +.\" Author: Rafael Aquini +.\" Date: Wed Jul 3 15:02:46 2013 -0700 +.\" +.TH swapon 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +swapon, swapoff \- start/stop swapping to file/device +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int swapon(const char *" path ", int " swapflags ); +.BI "int swapoff(const char *" path ); +.fi +.SH DESCRIPTION +.BR swapon () +sets the swap area to the file or block device specified by +.IR path . +.BR swapoff () +stops swapping to the file or block device specified by +.IR path . +.P +If the +.B SWAP_FLAG_PREFER +flag is specified in the +.BR swapon () +.I swapflags +argument, the new swap area will have a higher priority than default. +The priority is encoded within +.I swapflags +as: +.P +.in +4n +.EX +.I "(prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK" +.EE +.in +.P +If the +.B SWAP_FLAG_DISCARD +flag is specified in the +.BR swapon () +.I swapflags +argument, freed swap pages will be discarded before they are reused, +if the swap device supports the discard or trim operation. +(This may improve performance on some Solid State Devices, +but often it does not.) +See also NOTES. +.P +These functions may be used only by a privileged process (one having the +.B CAP_SYS_ADMIN +capability). +.SS Priority +Each swap area has a priority, either high or low. +The default priority is low. +Within the low-priority areas, +newer areas are even lower priority than older areas. +.P +All priorities set with +.I swapflags +are high-priority, higher than default. +They may have any nonnegative value chosen by the caller. +Higher numbers mean higher priority. +.P +Swap pages are allocated from areas in priority order, +highest priority first. +For areas with different priorities, +a higher-priority area is exhausted before using a lower-priority area. +If two or more areas have the same priority, +and it is the highest priority available, +pages are allocated on a round-robin basis between them. +.P +As of Linux 1.3.6, the kernel usually follows these rules, +but there are exceptions. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBUSY +(for +.BR swapon ()) +The specified +.I path +is already being used as a swap area. +.TP +.B EINVAL +The file +.I path +exists, but refers neither to a regular file nor to a block device; +.TP +.B EINVAL +.RB ( swapon ()) +The indicated path does not contain a valid swap signature or +resides on an in-memory filesystem such as +.BR tmpfs (5). +.TP +.BR EINVAL " (since Linux 3.4)" +.RB ( swapon ()) +An invalid flag value was specified in +.IR swapflags . +.TP +.B EINVAL +.RB ( swapoff ()) +.I path +is not currently a swap area. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +The file +.I path +does not exist. +.TP +.B ENOMEM +The system has insufficient memory to start swapping. +.TP +.B EPERM +The caller does not have the +.B CAP_SYS_ADMIN +capability. +Alternatively, the maximum number of swap files are already in use; +see NOTES below. +.SH STANDARDS +Linux. +.SH HISTORY +The +.I swapflags +argument was introduced in Linux 1.3.2. +.SH NOTES +The partition or path must be prepared with +.BR mkswap (8). +.P +There is an upper limit on the number of swap files that may be used, +defined by the kernel constant +.BR MAX_SWAPFILES . +Before Linux 2.4.10, +.B MAX_SWAPFILES +has the value 8; +since Linux 2.4.10, it has the value 32. +Since Linux 2.6.18, the limit is decreased by 2 (thus 30), +since Linux 5.19, the limit is decreased by 3 (thus: 29) +if the kernel is built with the +.B CONFIG_MIGRATION +option +(which reserves two swap table entries for the page migration features of +.BR mbind (2) +and +.BR migrate_pages (2)). +Since Linux 2.6.32, the limit is further decreased by 1 +if the kernel is built with the +.B CONFIG_MEMORY_FAILURE +option. +Since Linux 5.14, the limit is further decreased by 4 +if the kernel is built with the +.B CONFIG_DEVICE_PRIVATE +option. +Since Linux 5.19, the limit is further decreased by 1 +if the kernel is built with the +.B CONFIG_PTE_MARKER +option. +.P +Discard of swap pages was introduced in Linux 2.6.29, +then made conditional +on the +.B SWAP_FLAG_DISCARD +flag in Linux 2.6.36, +.\" To be precise: 2.6.35.5 +which still discards the +entire swap area when +.BR swapon () +is called, even if that flag bit is not set. +.SH SEE ALSO +.BR mkswap (8), +.BR swapoff (8), +.BR swapon (8) diff --git a/man/man2/symlink.2 b/man/man2/symlink.2 new file mode 100644 index 0000000..ae6e969 --- /dev/null +++ b/man/man2/symlink.2 @@ -0,0 +1,265 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-04-26 by Nick Duffek +.\" Modified 1996-11-06 by Eric S. Raymond +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH symlink 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +symlink, symlinkat \- make a new name for a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int symlink(const char *" target ", const char *" linkpath ); +.P +.BR "#include " "/* Definition of " AT_* " constants */" +.B #include +.P +.BI "int symlinkat(const char *" target ", int " newdirfd \ +", const char *" linkpath ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR symlink (): +.nf + _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.P +.BR symlinkat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +.BR symlink () +creates a symbolic link named +.I linkpath +which contains the string +.IR target . +.P +Symbolic links are interpreted at run time as if the contents of the +link had been substituted into the path being followed to find a file or +directory. +.P +Symbolic links may contain +.I .. +path components, which (if used at the start of the link) refer to the +parent directories of that in which the link resides. +.P +A symbolic link (also known as a soft link) may point to an existing +file or to a nonexistent one; the latter case is known as a dangling +link. +.P +The permissions of a symbolic link are irrelevant; the ownership is +ignored when following the link +(except when the +.I protected_symlinks +feature is enabled, as explained in +.BR proc (5)), +but is checked when removal or +renaming of the link is requested and the link is in a directory with +the sticky bit +.RB ( S_ISVTX ) +set. +.P +If +.I linkpath +exists, it will +.I not +be overwritten. +.SS symlinkat() +The +.BR symlinkat () +system call operates in exactly the same way as +.BR symlink (), +except for the differences described here. +.P +If the pathname given in +.I linkpath +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I newdirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR symlink () +for a relative pathname). +.P +If +.I linkpath +is relative and +.I newdirfd +is the special value +.BR AT_FDCWD , +then +.I linkpath +is interpreted relative to the current working +directory of the calling process (like +.BR symlink ()). +.P +If +.I linkpath +is absolute, then +.I newdirfd +is ignored. +.P +See +.BR openat (2) +for an explanation of the need for +.BR symlinkat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I linkpath +is denied, or one of the directories in the path prefix of +.I linkpath +did not allow search permission. +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( symlinkat ()) +.I linkpath +is relative but +.I newdirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EDQUOT +The user's quota of resources on the filesystem has been exhausted. +The resources could be inodes or disk blocks, depending on the filesystem +implementation. +.TP +.B EEXIST +.I linkpath +already exists. +.TP +.B EFAULT +.IR target " or " linkpath " points outside your accessible address space." +.TP +.B EIO +An I/O error occurred. +.TP +.B ELOOP +Too many symbolic links were encountered in resolving +.IR linkpath . +.TP +.B ENAMETOOLONG +.IR target " or " linkpath " was too long." +.TP +.B ENOENT +A directory component in +.I linkpath +does not exist or is a dangling symbolic link, or +.I target +or +.I linkpath +is an empty string. +.TP +.B ENOENT +.RB ( symlinkat ()) +.I linkpath +is a relative pathname and +.I newdirfd +refers to a directory that has been deleted. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSPC +The device containing the file has no room for the new directory +entry. +.TP +.B ENOTDIR +A component used as a directory in +.I linkpath +is not, in fact, a directory. +.TP +.B ENOTDIR +.RB ( symlinkat ()) +.I linkpath +is relative and +.I newdirfd +is a file descriptor referring to a file other than a directory. +.TP +.B EPERM +The filesystem containing +.I linkpath +does not support the creation of symbolic links. +.TP +.B EROFS +.I linkpath +is on a read-only filesystem. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR symlink () +SVr4, 4.3BSD, POSIX.1-2001. +.\" SVr4 documents additional error codes EDQUOT and ENOSYS. +.\" See +.\" .BR open (2) +.\" re multiple files with the same name, and NFS. +.TP +.BR symlinkat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. +.SS glibc notes +On older kernels where +.BR symlinkat () +is unavailable, the glibc wrapper function falls back to the use of +.BR symlink (). +When +.I linkpath +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.I /proc/self/fd +that corresponds to the +.I newdirfd +argument. +.SH NOTES +No checking of +.I target +is done. +.P +Deleting the name referred to by a symbolic link will actually delete the +file (unless it also has other hard links). +If this behavior is not desired, use +.BR link (2). +.SH SEE ALSO +.BR ln (1), +.BR namei (1), +.BR lchown (2), +.BR link (2), +.BR lstat (2), +.BR open (2), +.BR readlink (2), +.BR rename (2), +.BR unlink (2), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/symlinkat.2 b/man/man2/symlinkat.2 new file mode 100644 index 0000000..78568cd --- /dev/null +++ b/man/man2/symlinkat.2 @@ -0,0 +1 @@ +.so man2/symlink.2 diff --git a/man/man2/sync.2 b/man/man2/sync.2 new file mode 100644 index 0000000..6a45a29 --- /dev/null +++ b/man/man2/sync.2 @@ -0,0 +1,148 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" and Copyright (c) 2011 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified Sat Jul 24 12:02:47 1993 by Rik Faith +.\" Modified 15 Apr 1995 by Michael Chastain : +.\" Added reference to `bdflush(2)'. +.\" Modified 960414 by Andries Brouwer : +.\" Added the fact that since 1.3.20 sync actually waits. +.\" Modified Tue Oct 22 22:27:07 1996 by Eric S. Raymond +.\" Modified 2001-10-10 by aeb, following Michael Kerrisk. +.\" 2011-09-07, mtk, Added syncfs() documentation, +.\" +.TH sync 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sync, syncfs \- commit filesystem caches to disk +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B void sync(void); +.P +.BI "int syncfs(int " fd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sync (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.P +.BR syncfs (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +.BR sync () +causes all pending modifications to filesystem metadata and cached file +data to be written to the underlying filesystems. +.P +.BR syncfs () +is like +.BR sync (), +but synchronizes just the filesystem containing file +referred to by the open file descriptor +.IR fd . +.SH RETURN VALUE +.BR syncfs () +returns 0 on success; +on error, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.BR sync () +is always successful. +.P +.BR syncfs () +can fail for at least the following reasons: +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EIO +An error occurred during synchronization. +This error may relate to data written to any file on the filesystem, or on +metadata related to the filesystem itself. +.TP +.B ENOSPC +Disk space was exhausted while synchronizing. +.TP +.B ENOSPC +.TQ +.B EDQUOT +Data was written to a file on NFS or another filesystem which does not +allocate space at the time of a +.BR write (2) +system call, and some previous write failed due to insufficient +storage space. +.SH VERSIONS +According to the standard specification (e.g., POSIX.1-2001), +.BR sync () +schedules the writes, but may return before the actual +writing is done. +However Linux waits for I/O completions, +and thus +.BR sync () +or +.BR syncfs () +provide the same guarantees as +.BR fsync () +called on every file in +the system or filesystem respectively. +.SH STANDARDS +.TP +.BR sync () +POSIX.1-2008. +.TP +.BR syncfs () +Linux. +.SH HISTORY +.TP +.BR sync () +POSIX.1-2001, SVr4, 4.3BSD. +.TP +.BR syncfs () +Linux 2.6.39, +glibc 2.14. +.P +Since glibc 2.2.2, the Linux prototype for +.BR sync () +is as listed above, +following the various standards. +In glibc 2.2.1 and earlier, +it was "int sync(void)", and +.BR sync () +always returned 0. +.P +In mainline kernel versions prior to Linux 5.8, +.BR syncfs () +will fail only when passed a bad file descriptor +.RB ( EBADF ). +Since Linux 5.8, +.\" commit 735e4ae5ba28c886d249ad04d3c8cc097dad6336 +.BR syncfs () +will also report an error if one or more inodes failed +to be written back since the last +.BR syncfs () +call. +.SH BUGS +Before Linux 1.3.20, Linux did not wait for I/O to complete +before returning. +.SH SEE ALSO +.BR sync (1), +.BR fdatasync (2), +.BR fsync (2) diff --git a/man/man2/sync_file_range.2 b/man/man2/sync_file_range.2 new file mode 100644 index 0000000..278daf2 --- /dev/null +++ b/man/man2/sync_file_range.2 @@ -0,0 +1,213 @@ +.\" Copyright (c) 2006 Andrew Morton +.\" and Copyright 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2006-07-05 Initial creation, Michael Kerrisk based on +.\" Andrew Morton's comments in fs/sync.c +.\" 2010-10-09, mtk, Document sync_file_range2() +.\" +.TH sync_file_range 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sync_file_range \- sync a file segment with disk +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #define _FILE_OFFSET_BITS 64 +.B #include +.P +.BI "int sync_file_range(int " fd ", off_t " offset ", off_t " nbytes , +.BI " unsigned int " flags ); +.fi +.SH DESCRIPTION +.BR sync_file_range () +permits fine control when synchronizing the open file referred to by the +file descriptor +.I fd +with disk. +.P +.I offset +is the starting byte of the file range to be synchronized. +.I nbytes +specifies the length of the range to be synchronized, in bytes; if +.I nbytes +is zero, then all bytes from +.I offset +through to the end of file are synchronized. +Synchronization is in units of the system page size: +.I offset +is rounded down to a page boundary; +.I (offset+nbytes\-1) +is rounded up to a page boundary. +.P +The +.I flags +bit-mask argument can include any of the following values: +.TP +.B 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. +.TP +.B 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. +.TP +.B SYNC_FILE_RANGE_WAIT_AFTER +Wait upon write-out of all pages in the range +after performing any write. +.P +Specifying +.I flags +as 0 is permitted, as a no-op. +.SS 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., +.IR 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. +.SS Some details +.B SYNC_FILE_RANGE_WAIT_BEFORE +and +.B SYNC_FILE_RANGE_WAIT_AFTER +will detect any +I/O errors or +.B ENOSPC +conditions and will return these to the caller. +.P +Useful combinations of the +.I flags +bits are: +.TP +.B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE +Ensures that all pages +in the specified range which were dirty when +.BR sync_file_range () +was called are placed +under write-out. +This is a start-write-for-data-integrity operation. +.TP +.B 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. +.TP +.BR 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 +.B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE +operation to wait for completion of that operation, and obtain its result. +.TP +.B 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 +.BR sync_file_range () +was called are committed to disk. +.SH RETURN VALUE +On success, +.BR sync_file_range () +returns 0; on failure \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I flags +specifies an invalid bit; or +.I offset +or +.I nbytes +is invalid. +.TP +.B EIO +I/O error. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOSPC +Out of disk space. +.TP +.B ESPIPE +.I fd +refers to something other than a regular file, a block device, or +a directory. +.SH VERSIONS +.SS sync_file_range2() +Some architectures (e.g., PowerPC, ARM) +need 64-bit arguments to be aligned in a suitable pair of registers. +.\" See kernel commit edd5cd4a9424f22b0fa08bef5e299d41befd5622 +On such architectures, the call signature of +.BR sync_file_range () +shown in the SYNOPSIS would force +a register to be wasted as padding between the +.I fd +and +.I offset +arguments. +(See +.BR syscall (2) +for details.) +Therefore, these architectures define a different +system call that orders the arguments suitably: +.P +.in +4n +.EX +.BI "int sync_file_range2(int " fd ", unsigned int " flags , +.BI " off_t " offset ", off_t " nbytes ); +.EE +.in +.P +The behavior of this system call is otherwise exactly the same as +.BR sync_file_range (). +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.17. +.SS sync_file_range2() +A system call with this signature first appeared on the ARM architecture +in Linux 2.6.20, with the name +.BR 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 +.BR sync_file_range2 () +under the name +.BR sync_file_range (). +.SH NOTES +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that takes the address of +.BR sync_file_range , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. +.SH SEE ALSO +.BR fdatasync (2), +.BR fsync (2), +.BR msync (2), +.BR sync (2) diff --git a/man/man2/sync_file_range2.2 b/man/man2/sync_file_range2.2 new file mode 100644 index 0000000..ad7a1e6 --- /dev/null +++ b/man/man2/sync_file_range2.2 @@ -0,0 +1 @@ +.so man2/sync_file_range.2 diff --git a/man/man2/syncfs.2 b/man/man2/syncfs.2 new file mode 100644 index 0000000..5555798 --- /dev/null +++ b/man/man2/syncfs.2 @@ -0,0 +1 @@ +.so man2/sync.2 diff --git a/man/man2/syscall.2 b/man/man2/syscall.2 new file mode 100644 index 0000000..db6544a --- /dev/null +++ b/man/man2/syscall.2 @@ -0,0 +1,368 @@ +'\" t +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)syscall.2 8.1 (Berkeley) 6/16/93 +.\" +.\" +.\" 2002-03-20 Christoph Hellwig +.\" - adopted for Linux +.\" 2015-01-17, Kees Cook +.\" Added mips and arm64. +.\" +.TH syscall 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +syscall \- indirect system call +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "long syscall(long " number ", ...);" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR syscall (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + Before glibc 2.19: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +.BR syscall () +is a small library function that invokes +the system call whose assembly language +interface has the specified +.I number +with the specified arguments. +Employing +.BR syscall () +is useful, for example, +when invoking a system call that has no wrapper function in the C library. +.P +.BR 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 +.BR errno (3). +.P +Symbolic constants for system call numbers can be found in the header file +.IR . +.SH 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 +.IR errno . +.SH ERRORS +.TP +.B ENOSYS +The requested system call number is not implemented. +.P +Other errors are specific to the invoked system call. +.SH NOTES +.BR syscall () +first appeared in +4BSD. +.SS 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 +.BR 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. +.P +For example, on the ARM architecture Embedded ABI (EABI), a +64-bit value (e.g., +.IR "long long" ) +must be aligned to an even register pair. +Thus, using +.BR syscall () +instead of the wrapper provided by glibc, +the +.BR readahead (2) +system call would be invoked as follows on the ARM architecture with the EABI +in little endian mode: +.P +.in +4n +.EX +syscall(SYS_readahead, fd, 0, + (unsigned int) (offset & 0xFFFFFFFF), + (unsigned int) (offset >> 32), + count); +.EE +.in +.P +Since the offset argument is 64 bits, and the first argument +.RI ( fd ) +is passed in +.IR r0 , +the caller must manually split and align the 64-bit value +so that it is passed in the +.IR r2 / r3 +register pair. +That means inserting a dummy value into +.I 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). +.P +Similar issues can occur on MIPS with the O32 ABI, +on PowerPC and parisc with the 32-bit ABI, and on Xtensa. +.\" Mike Frysinger: this issue ends up forcing MIPS +.\" O32 to take 7 arguments to syscall() +.P +.\" See arch/parisc/kernel/sys_parisc.c. +Note that while the parisc C ABI also uses aligned register pairs, +it uses a shim layer to hide the issue from user space. +.P +The affected system calls are +.BR fadvise64_64 (2), +.BR ftruncate64 (2), +.BR posix_fadvise (2), +.BR pread64 (2), +.BR pwrite64 (2), +.BR readahead (2), +.BR sync_file_range (2), +and +.BR truncate64 (2). +.P +.\" You need to look up the syscalls directly in the kernel source to see if +.\" they should be in this list. For example, look at fs/read_write.c and +.\" the function signatures that do: +.\" ..., unsigned long, pos_l, unsigned long, pos_h, ... +.\" If they use off_t, then they most likely do not belong in this list. +This does not affect syscalls that manually split and assemble 64-bit values +such as +.BR _llseek (2), +.BR preadv (2), +.BR preadv2 (2), +.BR pwritev (2), +and +.BR pwritev2 (2). +Welcome to the wonderful world of historical baggage. +.SS 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. +.P +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 +.BR 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. +.if t \{\ +.ft CW +\} +.TS +l2 l2 l2 l2 l1 l2 l. +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 - - +.TE +.P +Notes: +.IP \[bu] 3 +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 +.RI ( csr ) +in the processor status register +.RI ( psr ) +is used instead of a full register. +On powerpc64, the summary overflow bit +.RI ( SO ) +in field 0 of the condition register +.RI ( cr0 ) +is used. +.IP \[bu] +.I NR +is the system call number. +.IP \[bu] +For s390 and s390x, +.I NR +(the system call number) may be passed directly with +.I "svc\ NR" +if it is less than 256. +.IP \[bu] +On SuperH additional trap numbers are supported for historic reasons, but +.BR trapa #31 +is the recommended "unified" ABI. +.IP \[bu] +The x32 ABI shares syscall table with x86-64 ABI, but there are some +nuances: +.RS +.IP \[bu] 3 +In order to indicate that a system call is called under the x32 ABI, +an additional bit, +.BR __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. +.IP \[bu] +Since x32 has different sizes for +.I long +and pointer types, layouts of some (but not all; +.I struct timeval +or +.I 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 +.BR __X32_SYSCALL_BIT ). +For example, +.B __NR_readv +is defined as 19 for the x86-64 ABI and as +.IR __X32_SYSCALL_BIT " | " \fB515\fP +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 +.BR preadv2 (2), +which uses +.I struct iovec +entities with 4-byte pointers and sizes ("compat_iovec" in kernel terms), +but passes an 8-byte +.I pos +argument in a single register and not two, as is done in every other ABI. +.RE +.IP \[bu] +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 +.BR pipe (2) +system call; +Alpha uses this technique in the architecture-specific +.BR getxpid (2), +.BR getxuid (2), +and +.BR 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. +.if t \{\ +.in +.ft P +\} +.P +The second table shows the registers used to pass the system call arguments. +.if t \{\ +.ft CW +\} +.TS +l l2 l2 l2 l2 l2 l2 l2 l. +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 - +.TE +.P +Notes: +.IP \[bu] 3 +The mips/o32 system call convention passes +arguments 5 through 8 on the user stack. +.if t \{\ +.in +.ft P +\} +.P +Note that these tables don't cover the entire calling convention\[em]some +architectures may indiscriminately clobber other registers not listed here. +.SH EXAMPLES +.\" SRC BEGIN (syscall.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +\& +int +main(void) +{ + pid_t tid; +\& + tid = syscall(SYS_gettid); + syscall(SYS_tgkill, getpid(), tid, SIGHUP); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR _syscall (2), +.BR intro (2), +.BR syscalls (2), +.BR errno (3), +.BR vdso (7) diff --git a/man/man2/syscalls.2 b/man/man2/syscalls.2 new file mode 100644 index 0000000..6e9135c --- /dev/null +++ b/man/man2/syscalls.2 @@ -0,0 +1,1172 @@ +'\" t +.\" Copyright (C) 2007 Michael Kerrisk +.\" with some input from Stepan Kasal +.\" +.\" Some content retained from an earlier version of this page: +.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl) +.\" Modifications for 2.2 and 2.4 Copyright (C) 2002 Ian Redfern +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH syscalls 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +syscalls \- Linux system calls +.SH SYNOPSIS +.nf +Linux system calls. +.fi +.SH DESCRIPTION +The system call is the fundamental interface between an application +and the Linux kernel. +.SS 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 +.BR 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 +.BR chdir () +which invokes the underlying "chdir" system call. +.P +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 +.I errno +appropriately after the system call has returned. +(These are the same steps that are performed by +.BR 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 +.BR syscall (2); +when this happens, +the wrapper function negates the returned error number +(to make it positive), copies it to +.IR errno , +and returns \-1 to the caller of the wrapper. +.P +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, +.BR truncate (2) +and +.BR truncate64 (2), +and the glibc +.BR truncate () +wrapper function checks which of those system calls +are provided by the kernel and determines which should be employed. +.SS System call list +Below is a list of the Linux system calls. +In the list, the +.I 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: +.IP \[bu] 3 +Where no kernel version is indicated, +the system call appeared in Linux 1.0 or earlier. +.IP \[bu] +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 Linux 1.2 kernel was initiated from a branch of +Linux 1.0.6 via the Linux 1.1.x unstable kernel series.) +.IP \[bu] +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.) +.\" Was Linux 2.0 started from a branch of Linux 1.2.10? +.\" At least from the timestamps of the tarballs of +.\" of Linux 1.2.10 and Linux 1.3.0, that's how it looks, but in +.\" fact the diff doesn't seem very clear, the +.\" Linux 1.3.0 .tar.bz is much bigger (2.0 MB) than the +.\" Linux 1.2.10 .tar.bz2 (1.8 MB), and AEB points out the +.\" timestamps of some files in Linux 1.3.0 seem to be older +.\" than those in Linux 1.2.10. All of this suggests +.\" that there might not have been a clean branch point. +.IP \[bu] +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 +Linux 2.0.21 via the Linux 2.1.x unstable kernel series.) +.IP \[bu] +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.) +.IP \[bu] +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.) +.IP \[bu] +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; and the Linux 6.x kernel series, +which followed on from Linux 5.19. +.IP \[bu] +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. +.P +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: +.P +.\" +.\" Looking at scripts/checksyscalls.sh in the kernel source is +.\" instructive about x86 specifics. +.\" +.TS +Lb Lb Lb +L2 L L. +System call Kernel Notes +_ +\fB_llseek\fP(2) 1.2 +\fB_newselect\fP(2) 2.0 +\fB_sysctl\fP(2) 2.0 Removed in 5.5 +\fBaccept\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBaccept4\fP(2) 2.6.28 +\fBaccess\fP(2) 1.0 +\fBacct\fP(2) 1.0 +\fBadd_key\fP(2) 2.6.10 +\fBadjtimex\fP(2) 1.0 +\fBalarm\fP(2) 1.0 +\fBalloc_hugepages\fP(2) 2.5.36 Removed in 2.5.44 +.\" 4adeefe161a74369e44cc8e663f240ece0470dc3 +\fBarc_gettls\fP(2) 3.9 ARC only +\fBarc_settls\fP(2) 3.9 ARC only +.\" 91e040a79df73d371f70792f30380d4e44805250 +\fBarc_usr_cmpxchg\fP(2) 4.9 ARC only +.\" x86: 79170fda313ed5be2394f87aa2a00d597f8ed4a1 +\fBarch_prctl\fP(2) 2.6 T{ +x86_64, x86 since 4.12 +T} +.\" 9674cdc74d63f346870943ef966a034f8c71ee57 +\fBatomic_barrier\fP(2) 2.6.34 m68k only +\fBatomic_cmpxchg_32\fP(2) 2.6.34 m68k only +\fBbdflush\fP(2) 1.2 T{ +Deprecated (does nothing) +since 2.6 +T} +\fBbind\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBbpf\fP(2) 3.18 +\fBbrk\fP(2) 1.0 +\fBbreakpoint\fP(2) 2.2 T{ +ARM OABI only, defined with +\fB__ARM_NR\fP prefix +T} +\fBcacheflush\fP(2) 1.2 Not on x86 +\fBcapget\fP(2) 2.2 +\fBcapset\fP(2) 2.2 +\fBchdir\fP(2) 1.0 +\fBchmod\fP(2) 1.0 +\fBchown\fP(2) 2.2 T{ +See \fBchown\fP(2) for +version details +T} +\fBchown32\fP(2) 2.4 +\fBchroot\fP(2) 1.0 +\fBclock_adjtime\fP(2) 2.6.39 +\fBclock_getres\fP(2) 2.6 +\fBclock_gettime\fP(2) 2.6 +\fBclock_nanosleep\fP(2) 2.6 +\fBclock_settime\fP(2) 2.6 +\fBclone2\fP(2) 2.4 IA-64 only +\fBclone\fP(2) 1.0 +\fBclone3\fP(2) 5.3 +\fBclose\fP(2) 1.0 +\fBclose_range\fP(2) 5.9 +.\" .\" dcef1f634657dabe7905af3ccda12cf7f0b6fcc1 +.\" .\" cc20d42986d5807cbe4f5c7c8e3dab2e59ea0db3 +.\" .\" db695c0509d6ec9046ee5e4c520a19fa17d9fce2 +.\" \fBcmpxchg\fP(2) 2.6.12 T{ +.\" ARM, syscall constant never was +.\" exposed to user space, in-kernel +.\" definition had \fB__ARM_NR\fP prefix, +.\" removed in 4.4 +.\" T} +.\" 867e359b97c970a60626d5d76bbe2a8fadbf38fb +.\" bb9d812643d8a121df7d614a2b9c60193a92deb0 +\fBconnect\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBcopy_file_range\fP(2) 4.5 +\fBcreat\fP(2) 1.0 +\fBcreate_module\fP(2) 1.0 Removed in 2.6 +\fBdelete_module\fP(2) 1.0 +.\" 1394f03221790a988afc3e4b3cb79f2e477246a9 +.\" 4ba66a9760722ccbb691b8f7116cad2f791cca7b +\fBdup\fP(2) 1.0 +\fBdup2\fP(2) 1.0 +\fBdup3\fP(2) 2.6.27 +\fBepoll_create\fP(2) 2.6 +\fBepoll_create1\fP(2) 2.6.27 +\fBepoll_ctl\fP(2) 2.6 +\fBepoll_pwait\fP(2) 2.6.19 +\fBepoll_pwait2\fP(2) 5.11 +\fBepoll_wait\fP(2) 2.6 +\fBeventfd\fP(2) 2.6.22 +\fBeventfd2\fP(2) 2.6.27 +\fBexecv\fP(2) 2.0 T{ +SPARC/SPARC64 only, for +compatibility with SunOS +T} +\fBexecve\fP(2) 1.0 +\fBexecveat\fP(2) 3.19 +\fBexit\fP(2) 1.0 +\fBexit_group\fP(2) 2.6 +\fBfaccessat\fP(2) 2.6.16 +\fBfaccessat2\fP(2) 5.8 +\fBfadvise64\fP(2) 2.6 +.\" Implements \fBposix_fadvise\fP(2) +\fBfadvise64_64\fP(2) 2.6 +\fBfallocate\fP(2) 2.6.23 +\fBfanotify_init\fP(2) 2.6.37 +\fBfanotify_mark\fP(2) 2.6.37 +.\" The fanotify calls were added in Linux 2.6.36, +.\" but disabled while the API was finalized. +\fBfchdir\fP(2) 1.0 +\fBfchmod\fP(2) 1.0 +\fBfchmodat\fP(2) 2.6.16 +\fBfchown\fP(2) 1.0 +\fBfchown32\fP(2) 2.4 +\fBfchownat\fP(2) 2.6.16 +\fBfcntl\fP(2) 1.0 +\fBfcntl64\fP(2) 2.4 +\fBfdatasync\fP(2) 2.0 +\fBfgetxattr\fP(2) 2.6; 2.4.18 +\fBfinit_module\fP(2) 3.8 +\fBflistxattr\fP(2) 2.6; 2.4.18 +\fBflock\fP(2) 2.0 +\fBfork\fP(2) 1.0 +\fBfree_hugepages\fP(2) 2.5.36 Removed in 2.5.44 +\fBfremovexattr\fP(2) 2.6; 2.4.18 +\fBfsconfig\fP(2) 5.2 +\fBfsetxattr\fP(2) 2.6; 2.4.18 +\fBfsmount\fP(2) 5.2 +\fBfsopen\fP(2) 5.2 +\fBfspick\fP(2) 5.2 +\fBfstat\fP(2) 1.0 +\fBfstat64\fP(2) 2.4 +\fBfstatat64\fP(2) 2.6.16 +\fBfstatfs\fP(2) 1.0 +\fBfstatfs64\fP(2) 2.6 +\fBfsync\fP(2) 1.0 +\fBftruncate\fP(2) 1.0 +\fBftruncate64\fP(2) 2.4 +\fBfutex\fP(2) 2.6 +\fBfutimesat\fP(2) 2.6.16 +\fBget_kernel_syms\fP(2) 1.0 Removed in 2.6 +\fBget_mempolicy\fP(2) 2.6.6 +\fBget_robust_list\fP(2) 2.6.17 +\fBget_thread_area\fP(2) 2.6 +.\" 8fcd6c45f5a65621ec809b7866a3623e9a01d4ed +\fBget_tls\fP(2) 4.15 T{ +ARM OABI only, has +\fB__ARM_NR\fP prefix +T} +\fBgetcpu\fP(2) 2.6.19 +\fBgetcwd\fP(2) 2.2 +\fBgetdents\fP(2) 2.0 +\fBgetdents64\fP(2) 2.4 +.\" parisc: 863722e856e64dae0e252b6bb546737c6c5626ce +\fBgetdomainname\fP(2) 2.2 T{ +SPARC, SPARC64; available +as \fBosf_getdomainname\fP(2) +on Alpha since Linux 2.0 +T} +.\" ec98c6b9b47df6df1c1fa6cf3d427414f8c2cf16 +\fBgetdtablesize\fP(2) 2.0 T{ +SPARC (removed in 2.6.26), +available on Alpha as +\fBosf_getdtablesize\fP(2) +T} +\fBgetegid\fP(2) 1.0 +\fBgetegid32\fP(2) 2.4 +\fBgeteuid\fP(2) 1.0 +\fBgeteuid32\fP(2) 2.4 +\fBgetgid\fP(2) 1.0 +\fBgetgid32\fP(2) 2.4 +\fBgetgroups\fP(2) 1.0 +\fBgetgroups32\fP(2) 2.4 +.\" SPARC removal: ec98c6b9b47df6df1c1fa6cf3d427414f8c2cf16 +\fBgethostname\fP(2) 2.0 T{ +Alpha, was available on +SPARC up to Linux 2.6.26 +T} +\fBgetitimer\fP(2) 1.0 +\fBgetpeername\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBgetpagesize\fP(2) 2.0 T{ +Alpha, SPARC/SPARC64 only +T} +\fBgetpgid\fP(2) 1.0 +\fBgetpgrp\fP(2) 1.0 +\fBgetpid\fP(2) 1.0 +\fBgetppid\fP(2) 1.0 +\fBgetpriority\fP(2) 1.0 +\fBgetrandom\fP(2) 3.17 +\fBgetresgid\fP(2) 2.2 +\fBgetresgid32\fP(2) 2.4 +\fBgetresuid\fP(2) 2.2 +\fBgetresuid32\fP(2) 2.4 +\fBgetrlimit\fP(2) 1.0 +\fBgetrusage\fP(2) 1.0 +\fBgetsid\fP(2) 2.0 +\fBgetsockname\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBgetsockopt\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBgettid\fP(2) 2.4.11 +\fBgettimeofday\fP(2) 1.0 +\fBgetuid\fP(2) 1.0 +\fBgetuid32\fP(2) 2.4 +\fBgetunwind\fP(2) 2.4.8 T{ +IA-64 only; deprecated +T} +\fBgetxattr\fP(2) 2.6; 2.4.18 +\fBgetxgid\fP(2) 2.0 T{ +Alpha only; see NOTES +T} +\fBgetxpid\fP(2) 2.0 T{ +Alpha only; see NOTES +T} +\fBgetxuid\fP(2) 2.0 T{ +Alpha only; see NOTES +T} +\fBinit_module\fP(2) 1.0 +\fBinotify_add_watch\fP(2) 2.6.13 +\fBinotify_init\fP(2) 2.6.13 +\fBinotify_init1\fP(2) 2.6.27 +\fBinotify_rm_watch\fP(2) 2.6.13 +\fBio_cancel\fP(2) 2.6 +\fBio_destroy\fP(2) 2.6 +\fBio_getevents\fP(2) 2.6 +\fBio_pgetevents\fP(2) 4.18 +\fBio_setup\fP(2) 2.6 +\fBio_submit\fP(2) 2.6 +\fBio_uring_enter\fP(2) 5.1 +\fBio_uring_register\fP(2) 5.1 +\fBio_uring_setup\fP(2) 5.1 +\fBioctl\fP(2) 1.0 +\fBioperm\fP(2) 1.0 +\fBiopl\fP(2) 1.0 +\fBioprio_get\fP(2) 2.6.13 +\fBioprio_set\fP(2) 2.6.13 +\fBipc\fP(2) 1.0 +.\" Implements System V IPC calls +\fBkcmp\fP(2) 3.5 +\fBkern_features\fP(2) 3.7 SPARC64 only +.\" FIXME . document kern_features(): +.\" commit 517ffce4e1a03aea979fe3a18a3dd1761a24fafb +\fBkexec_file_load\fP(2) 3.17 +\fBkexec_load\fP(2) 2.6.13 +.\" The entry in the syscall table was reserved starting in 2.6.7 +.\" Was named sys_kexec_load() from 2.6.7 to 2.6.16 +\fBkeyctl\fP(2) 2.6.10 +\fBkill\fP(2) 1.0 +\fBlandlock_add_rule\fP(2) 5.13 +\fBlandlock_create_ruleset\fP(2) 5.13 +\fBlandlock_restrict_self\fP(2) 5.13 +\fBlchown\fP(2) 1.0 T{ +See \fBchown\fP(2) for +version details +T} +\fBlchown32\fP(2) 2.4 +\fBlgetxattr\fP(2) 2.6; 2.4.18 +\fBlink\fP(2) 1.0 +\fBlinkat\fP(2) 2.6.16 +\fBlisten\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBlistxattr\fP(2) 2.6; 2.4.18 +\fBllistxattr\fP(2) 2.6; 2.4.18 +\fBlookup_dcookie\fP(2) 2.6 +\fBlremovexattr\fP(2) 2.6; 2.4.18 +\fBlseek\fP(2) 1.0 +\fBlsetxattr\fP(2) 2.6; 2.4.18 +\fBlstat\fP(2) 1.0 +\fBlstat64\fP(2) 2.4 +\fBmadvise\fP(2) 2.4 +\fBmbind\fP(2) 2.6.6 +\fBmemory_ordering\fP(2) 2.2 SPARC64 only +.\" 26025bbfbba33a9425be1b89eccb4664ea4c17b6 +.\" bb6fb6dfcc17cddac11ac295861f7608194447a7 +\fBmembarrier\fP(2) 3.17 +\fBmemfd_create\fP(2) 3.17 +\fBmemfd_secret\fP(2) 5.14 +\fBmigrate_pages\fP(2) 2.6.16 +\fBmincore\fP(2) 2.4 +\fBmkdir\fP(2) 1.0 +\fBmkdirat\fP(2) 2.6.16 +\fBmknod\fP(2) 1.0 +\fBmknodat\fP(2) 2.6.16 +\fBmlock\fP(2) 2.0 +\fBmlock2\fP(2) 4.4 +\fBmlockall\fP(2) 2.0 +\fBmmap\fP(2) 1.0 +\fBmmap2\fP(2) 2.4 +\fBmodify_ldt\fP(2) 1.0 +\fBmount\fP(2) 1.0 +\fBmove_mount\fP(2) 5.2 +\fBmove_pages\fP(2) 2.6.18 +\fBmprotect\fP(2) 1.0 +\fBmq_getsetattr\fP(2) 2.6.6 +.\" Implements \fBmq_getattr\fP(3) and \fBmq_setattr\fP(3) +\fBmq_notify\fP(2) 2.6.6 +\fBmq_open\fP(2) 2.6.6 +\fBmq_timedreceive\fP(2) 2.6.6 +\fBmq_timedsend\fP(2) 2.6.6 +\fBmq_unlink\fP(2) 2.6.6 +\fBmremap\fP(2) 2.0 +\fBmsgctl\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBmsgget\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBmsgrcv\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBmsgsnd\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBmsync\fP(2) 2.0 +.\" \fBmultiplexer\fP(2) ?? __NR_multiplexer reserved on +.\" PowerPC, but unimplemented? +\fBmunlock\fP(2) 2.0 +\fBmunlockall\fP(2) 2.0 +\fBmunmap\fP(2) 1.0 +\fBname_to_handle_at\fP(2) 2.6.39 +\fBnanosleep\fP(2) 2.0 +.\" 5590ff0d5528b60153c0b4e7b771472b5a95e297 +\fBnewfstatat\fP(2) 2.6.16 T{ +See \fBstat\fP(2) +T} +\fBnfsservctl\fP(2) 2.2 Removed in 3.1 +\fBnice\fP(2) 1.0 +\fBold_adjtimex\fP(2) 2.0 T{ +Alpha only; see NOTES +T} +\fBold_getrlimit\fP(2) 2.4 T{ +Old variant of \fBgetrlimit\fP(2) +that used a different value +for \fBRLIM_INFINITY\fP +T} +\fBoldfstat\fP(2) 1.0 +\fBoldlstat\fP(2) 1.0 +\fBoldolduname\fP(2) 1.0 +\fBoldstat\fP(2) 1.0 +\fBoldumount\fP(2) 2.4.116 T{ +Name of the old \fBumount\fP(2) +syscall on Alpha +T} +\fBolduname\fP(2) 1.0 +\fBopen\fP(2) 1.0 +\fBopen_by_handle_at\fP(2) 2.6.39 +\fBopen_tree\fP(2) 5.2 +\fBopenat\fP(2) 2.6.16 +\fBopenat2\fP(2) 5.6 +.\" 9d02a4283e9ce4e9ca11ff00615bdacdb0515a1a +\fBor1k_atomic\fP(2) 3.1 T{ +OpenRISC 1000 only +T} +\fBpause\fP(2) 1.0 +\fBpciconfig_iobase\fP(2) 2.2.15; 2.4 Not on x86 +.\" Alpha, PowerPC, ARM; not x86 +\fBpciconfig_read\fP(2) 2.0.26; 2.2 Not on x86 +.\" , PowerPC, ARM; not x86 +\fBpciconfig_write\fP(2) 2.0.26; 2.2 Not on x86 +.\" , PowerPC, ARM; not x86 +\fBperf_event_open\fP(2) 2.6.31 T{ +Was perf_counter_open() in +2.6.31; renamed in 2.6.32 +T} +\fBpersonality\fP(2) 1.2 +\fBperfctr\fP(2) 2.2 T{ +SPARC only; removed in 2.6.34 +T} +.\" commit c7d5a0050773e98d1094eaa9f2a1a793fafac300 removed perfctr() +\fBperfmonctl\fP(2) 2.4 IA-64 only; removed in 5.10 +\fBpidfd_getfd\fP(2) 5.6 +\fBpidfd_send_signal\fP(2) 5.1 +\fBpidfd_open\fP(2) 5.3 +\fBpipe\fP(2) 1.0 +\fBpipe2\fP(2) 2.6.27 +\fBpivot_root\fP(2) 2.4 +\fBpkey_alloc\fP(2) 4.8 +\fBpkey_free\fP(2) 4.8 +\fBpkey_mprotect\fP(2) 4.8 +\fBpoll\fP(2) 2.0.36; 2.2 +\fBppoll\fP(2) 2.6.16 +\fBprctl\fP(2) 2.2 +\fBpread64\fP(2) T{ +Added as "pread" in 2.2; +renamed "pread64" in 2.6 +T} +\fBpreadv\fP(2) 2.6.30 +\fBpreadv2\fP(2) 4.6 +\fBprlimit64\fP(2) 2.6.36 +\fBprocess_madvise\fP(2) 5.10 +\fBprocess_vm_readv\fP(2) 3.2 +\fBprocess_vm_writev\fP(2) 3.2 +\fBpselect6\fP(2) 2.6.16 +.\" Implements \fBpselect\fP(2) +\fBptrace\fP(2) 1.0 +\fBpwrite64\fP(2) T{ +Added as "pwrite" in 2.2; +renamed "pwrite64" in 2.6 +T} +\fBpwritev\fP(2) 2.6.30 +\fBpwritev2\fP(2) 4.6 +\fBquery_module\fP(2) 2.2 Removed in 2.6 +\fBquotactl\fP(2) 1.0 +\fBquotactl_fd\fP(2) 5.14 +\fBread\fP(2) 1.0 +\fBreadahead\fP(2) 2.4.13 +\fBreaddir\fP(2) 1.0 +.\" Supersedes \fBgetdents\fP(2) +\fBreadlink\fP(2) 1.0 +\fBreadlinkat\fP(2) 2.6.16 +\fBreadv\fP(2) 2.0 +\fBreboot\fP(2) 1.0 +\fBrecv\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBrecvfrom\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBrecvmsg\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBrecvmmsg\fP(2) 2.6.33 +\fBremap_file_pages\fP(2) 2.6 T{ +Deprecated since 3.16 +T} +\fBremovexattr\fP(2) 2.6; 2.4.18 +\fBrename\fP(2) 1.0 +\fBrenameat\fP(2) 2.6.16 +\fBrenameat2\fP(2) 3.15 +\fBrequest_key\fP(2) 2.6.10 +\fBrestart_syscall\fP(2) 2.6 +.\" 921ebd8f2c081b3cf6c3b29ef4103eef3ff26054 +\fBriscv_flush_icache\fP(2) 4.15 RISC-V only +\fBrmdir\fP(2) 1.0 +\fBrseq\fP(2) 4.18 +\fBrt_sigaction\fP(2) 2.2 +\fBrt_sigpending\fP(2) 2.2 +\fBrt_sigprocmask\fP(2) 2.2 +\fBrt_sigqueueinfo\fP(2) 2.2 +\fBrt_sigreturn\fP(2) 2.2 +\fBrt_sigsuspend\fP(2) 2.2 +\fBrt_sigtimedwait\fP(2) 2.2 +\fBrt_tgsigqueueinfo\fP(2) 2.6.31 +\fBrtas\fP(2) 2.6.2 T{ +PowerPC/PowerPC64 only +T} +\fBs390_runtime_instr\fP(2) 3.7 s390 only +\fBs390_pci_mmio_read\fP(2) 3.19 s390 only +\fBs390_pci_mmio_write\fP(2) 3.19 s390 only +\fBs390_sthyi\fP(2) 4.15 s390 only +\fBs390_guarded_storage\fP(2) 4.12 s390 only +\fBsched_get_affinity\fP(2) 2.6 T{ +Name of +.BR \%sched_getaffinity (2) +on SPARC and SPARC64 +T} +\fBsched_get_priority_max\fP(2) 2.0 +\fBsched_get_priority_min\fP(2) 2.0 +\fBsched_getaffinity\fP(2) 2.6 +\fBsched_getattr\fP(2) 3.14 +\fBsched_getparam\fP(2) 2.0 +\fBsched_getscheduler\fP(2) 2.0 +\fBsched_rr_get_interval\fP(2) 2.0 +\fBsched_set_affinity\fP(2) 2.6 T{ +Name of +.BR \%sched_setaffinity (2) +on SPARC and SPARC64 +T} +\fBsched_setaffinity\fP(2) 2.6 +\fBsched_setattr\fP(2) 3.14 +\fBsched_setparam\fP(2) 2.0 +\fBsched_setscheduler\fP(2) 2.0 +\fBsched_yield\fP(2) 2.0 +\fBseccomp\fP(2) 3.17 +\fBselect\fP(2) 1.0 +\fBsemctl\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBsemget\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBsemop\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBsemtimedop\fP(2) 2.6; 2.4.22 +\fBsend\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBsendfile\fP(2) 2.2 +\fBsendfile64\fP(2) 2.6; 2.4.19 +\fBsendmmsg\fP(2) 3.0 +\fBsendmsg\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBsendto\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBset_mempolicy\fP(2) 2.6.6 +\fBset_robust_list\fP(2) 2.6.17 +\fBset_thread_area\fP(2) 2.6 +\fBset_tid_address\fP(2) 2.6 +\fBset_tls\fP(2) 2.6.11 T{ +ARM OABI/EABI only (constant +has \fB__ARM_NR\fP prefix) +T} +.\" \fBsetaltroot\fP(2) 2.6.10 T{ +.\" Removed in 2.6.11, exposed one +.\" of implementation details of +.\" \fBpersonality\fP(2) (creating an +.\" alternative root, precursor of +.\" mount namespaces) to user space. +.\" T} +.\" See http://lkml.org/lkml/2005/8/1/83 +.\" "[PATCH] remove sys_set_zone_reclaim()" +\fBsetdomainname\fP(2) 1.0 +\fBsetfsgid\fP(2) 1.2 +\fBsetfsgid32\fP(2) 2.4 +\fBsetfsuid\fP(2) 1.2 +\fBsetfsuid32\fP(2) 2.4 +\fBsetgid\fP(2) 1.0 +\fBsetgid32\fP(2) 2.4 +\fBsetgroups\fP(2) 1.0 +\fBsetgroups32\fP(2) 2.4 +.\" arch/alpha/include/asm/core_lca.h +\fBsethae\fP(2) 2.0 T{ +Alpha only; see NOTES +T} +\fBsethostname\fP(2) 1.0 +\fBsetitimer\fP(2) 1.0 +\fBsetns\fP(2) 3.0 +\fBsetpgid\fP(2) 1.0 +\fBsetpgrp\fP(2) 2.0 T{ +Alternative name for \fBsetpgid\fP(2) on Alpha +T} +\fBsetpriority\fP(2) 1.0 +\fBsetregid\fP(2) 1.0 +\fBsetregid32\fP(2) 2.4 +\fBsetresgid\fP(2) 2.2 +\fBsetresgid32\fP(2) 2.4 +\fBsetresuid\fP(2) 2.2 +\fBsetresuid32\fP(2) 2.4 +\fBsetreuid\fP(2) 1.0 +\fBsetreuid32\fP(2) 2.4 +\fBsetrlimit\fP(2) 1.0 +\fBsetsid\fP(2) 1.0 +\fBsetsockopt\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBsettimeofday\fP(2) 1.0 +\fBsetuid\fP(2) 1.0 +\fBsetuid32\fP(2) 2.4 +\fBsetup\fP(2) 1.0 Removed in 2.2 +\fBsetxattr\fP(2) 2.6; 2.4.18 +\fBsgetmask\fP(2) 1.0 +\fBshmat\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBshmctl\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBshmdt\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBshmget\fP(2) 2.0 T{ +See notes on \fBipc\fP(2) +T} +\fBshutdown\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBsigaction\fP(2) 1.0 +\fBsigaltstack\fP(2) 2.2 +\fBsignal\fP(2) 1.0 +\fBsignalfd\fP(2) 2.6.22 +\fBsignalfd4\fP(2) 2.6.27 +\fBsigpending\fP(2) 1.0 +\fBsigprocmask\fP(2) 1.0 +\fBsigreturn\fP(2) 1.0 +\fBsigsuspend\fP(2) 1.0 +\fBsocket\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +\fBsocketcall\fP(2) 1.0 +.\" Implements BSD socket calls +\fBsocketpair\fP(2) 2.0 T{ +See notes on \fBsocketcall\fP(2) +T} +.\" 5a0015d62668e64c8b6e02e360fbbea121bfd5e6 +\fBspill\fP(2) 2.6.13 Xtensa only +\fBsplice\fP(2) 2.6.17 +\fBspu_create\fP(2) 2.6.16 T{ +PowerPC/PowerPC64 only +T} +\fBspu_run\fP(2) 2.6.16 T{ +PowerPC/PowerPC64 only +T} +\fBssetmask\fP(2) 1.0 +\fBstat\fP(2) 1.0 +\fBstat64\fP(2) 2.4 +\fBstatfs\fP(2) 1.0 +\fBstatfs64\fP(2) 2.6 +\fBstatx\fP(2) 4.11 +\fBstime\fP(2) 1.0 +\fBsubpage_prot\fP(2) 2.6.25 T{ +PowerPC/PowerPC64 only +T} +\fBswapcontext\fP(2) 2.6.3 T{ +PowerPC/PowerPC64 only +T} +.\" 529d235a0e190ded1d21ccc80a73e625ebcad09b +\fBswitch_endian\fP(2) 4.1 PowerPC64 only +\fBswapoff\fP(2) 1.0 +\fBswapon\fP(2) 1.0 +\fBsymlink\fP(2) 1.0 +\fBsymlinkat\fP(2) 2.6.16 +\fBsync\fP(2) 1.0 +\fBsync_file_range\fP(2) 2.6.17 +\fBsync_file_range2\fP(2) 2.6.22 +.\" PowerPC, ARM, tile +.\" First appeared on ARM, as arm_sync_file_range(), but later renamed +.\" \fBsys_debug_setcontext\fP(2) ??? PowerPC if CONFIG_PPC32 +\fBsyncfs\fP(2) 2.6.39 +\fBsys_debug_setcontext\fP(2) 2.6.11 PowerPC only +\fBsyscall\fP(2) 1.0 T{ +Still available on ARM OABI +and MIPS O32 ABI +T} +\fBsysfs\fP(2) 1.2 +\fBsysinfo\fP(2) 1.0 +\fBsyslog\fP(2) 1.0 +.\" glibc interface is \fBklogctl\fP(3) +\fBsysmips\fP(2) 2.6.0 MIPS only +\fBtee\fP(2) 2.6.17 +\fBtgkill\fP(2) 2.6 +\fBtime\fP(2) 1.0 +\fBtimer_create\fP(2) 2.6 +\fBtimer_delete\fP(2) 2.6 +\fBtimer_getoverrun\fP(2) 2.6 +\fBtimer_gettime\fP(2) 2.6 +\fBtimer_settime\fP(2) 2.6 +.\" .\" b215e283992899650c4271e7385c79e26fb9a88e +.\" .\" 4d672e7ac79b5ec5cdc90e450823441e20464691 +.\" \fBtimerfd\fP(2) 2.6.22 T{ +.\" Old timerfd interface, +.\" removed in 2.6.25 +.\" T} +\fBtimerfd_create\fP(2) 2.6.25 +\fBtimerfd_gettime\fP(2) 2.6.25 +\fBtimerfd_settime\fP(2) 2.6.25 +\fBtimes\fP(2) 1.0 +\fBtkill\fP(2) 2.6; 2.4.22 +\fBtruncate\fP(2) 1.0 +\fBtruncate64\fP(2) 2.4 +\fBugetrlimit\fP(2) 2.4 +\fBumask\fP(2) 1.0 +\fBumount\fP(2) 1.0 +.\" sys_oldumount() -- __NR_umount +\fBumount2\fP(2) 2.2 +.\" sys_umount() -- __NR_umount2 +\fBuname\fP(2) 1.0 +\fBunlink\fP(2) 1.0 +\fBunlinkat\fP(2) 2.6.16 +\fBunshare\fP(2) 2.6.16 +\fBuselib\fP(2) 1.0 +\fBustat\fP(2) 1.0 +\fBuserfaultfd\fP(2) 4.3 +\fBusr26\fP(2) 2.4.8.1 ARM OABI only +\fBusr32\fP(2) 2.4.8.1 ARM OABI only +\fButime\fP(2) 1.0 +\fButimensat\fP(2) 2.6.22 +\fButimes\fP(2) 2.2 +\fButrap_install\fP(2) 2.2 SPARC64 only +.\" FIXME . document utrap_install() +.\" There's a man page for Solaris 5.11 +\fBvfork\fP(2) 2.2 +\fBvhangup\fP(2) 1.0 +\fBvm86old\fP(2) 1.0 T{ +Was "vm86"; renamed in +2.0.28/2.2 +T} +\fBvm86\fP(2) 2.0.28; 2.2 +\fBvmsplice\fP(2) 2.6.17 +\fBwait4\fP(2) 1.0 +\fBwaitid\fP(2) 2.6.10 +\fBwaitpid\fP(2) 1.0 +\fBwrite\fP(2) 1.0 +\fBwritev\fP(2) 2.0 +.\" 5a0015d62668e64c8b6e02e360fbbea121bfd5e6 +\fBxtensa\fP(2) 2.6.13 Xtensa only +.TE +.P +On many platforms, including x86-32, socket calls are all multiplexed +(via glibc wrapper functions) through +.BR socketcall (2) +and similarly System\ V IPC calls are multiplexed through +.BR ipc (2). +.P +Although slots are reserved for them in the system call table, +the following system calls are not implemented in the standard kernel: +.BR afs_syscall (2), \" __NR_afs_syscall is 53 on Linux 2.6.22/i386 +.BR break (2), \" __NR_break is 17 on Linux 2.6.22/i386 +.BR ftime (2), \" __NR_ftime is 35 on Linux 2.6.22/i386 +.BR getpmsg (2), \" __NR_getpmsg is 188 on Linux 2.6.22/i386 +.BR gtty (2), \" __NR_gtty is 32 on Linux 2.6.22/i386 +.BR idle (2), \" __NR_idle is 112 on Linux 2.6.22/i386 +.BR lock (2), \" __NR_lock is 53 on Linux 2.6.22/i386 +.BR madvise1 (2), \" __NR_madvise1 is 219 on Linux 2.6.22/i386 +.BR mpx (2), \" __NR_mpx is 66 on Linux 2.6.22/i386 +.BR phys (2), \" Slot has been reused +.BR prof (2), \" __NR_prof is 44 on Linux 2.6.22/i386 +.BR profil (2), \" __NR_profil is 98 on Linux 2.6.22/i386 +.BR putpmsg (2), \" __NR_putpmsg is 189 on Linux 2.6.22/i386 +.\" __NR_security is 223 on Linux 2.4/i386; absent on 2.6/i386, present +.\" on a couple of 2.6 architectures +.BR security (2), \" __NR_security is 223 on Linux 2.4/i386 +.\" The security call is for future use. +.BR stty (2), \" __NR_stty is 31 on Linux 2.6.22/i386 +.BR tuxcall (2), \" __NR_tuxcall is 184 on x86_64, also on PPC and alpha +.BR ulimit (2), \" __NR_ulimit is 58 on Linux 2.6.22/i386 +and +.BR vserver (2) \" __NR_vserver is 273 on Linux 2.6.22/i386 +(see also +.BR unimplemented (2)). +However, +.BR ftime (3), +.BR profil (3), +and +.BR ulimit (3) +exist as library routines. +The slot for +.BR phys (2) +is in use since Linux 2.1.116 for +.BR umount (2); +.BR phys (2) +will never be implemented. +The +.BR getpmsg (2) +and +.BR putpmsg (2) +calls are for kernels patched to support STREAMS, +and may never be in the standard kernel. +.P +There was briefly +.BR 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. +.\" +.SS System calls on removed ports +Some system calls only ever existed on Linux architectures that have +since been removed from the kernel: +.TP +AVR32 (port removed in Linux 4.12) +.RS +.PD 0 +.IP \[bu] 3 +.BR pread (2) +.IP \[bu] +.BR pwrite (2) +.PD +.RE +.TP +Blackfin (port removed in Linux 4.17) +.RS +.PD 0 +.IP \[bu] 3 +.BR bfin_spinlock (2) +(added in Linux 2.6.22) +.IP \[bu] +.BR dma_memcpy (2) +(added in Linux 2.6.22) +.IP \[bu] +.BR pread (2) +(added in Linux 2.6.22) +.IP \[bu] +.BR pwrite (2) +(added in Linux 2.6.22) +.IP \[bu] +.BR sram_alloc (2) +(added in Linux 2.6.22) +.IP \[bu] +.BR sram_free (2) +(added in Linux 2.6.22) +.PD +.RE +.TP +Metag (port removed in Linux 4.17) +.RS +.PD 0 +.IP \[bu] 3 +.BR metag_get_tls (2) +(add in Linux 3.9) +.IP \[bu] +.BR metag_set_fpu_flags (2) +(add in Linux 3.9) +.IP \[bu] +.BR metag_set_tls (2) +(add in Linux 3.9) +.IP \[bu] +.BR metag_setglobalbit (2) +(add in Linux 3.9) +.PD +.RE +.TP +Tile (port removed in Linux 4.17) +.RS +.PD 0 +.IP \[bu] 3 +.BR cmpxchg_badaddr (2) +(added in Linux 2.6.36) +.PD +.RE +.SH NOTES +Roughly speaking, the code belonging to the system call +with number __NR_xxx defined in +.I /usr/include/asm/unistd.h +can be found in the Linux kernel source in the routine +.IR 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. +.P +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., +.BR truncate (2) +and +.BR 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 system calls that exist in multiple versions are +the following: +.IP \[bu] 3 +By now there are three different versions of +.BR stat (2): +.IR sys_stat () +(slot +.IR __NR_oldstat ), +.IR sys_newstat () +(slot +.IR __NR_stat ), +and +.IR sys_stat64 () +(slot +.IR __NR_stat64 ), +with the last being the most current. +.\" e.g., on 2.6.22/i386: __NR_oldstat 18, __NR_stat 106, __NR_stat64 195 +.\" The stat system calls deal with three different data structures, +.\" defined in include/asm-i386/stat.h: __old_kernel_stat, stat, stat64 +A similar story applies for +.BR lstat (2) +and +.BR fstat (2). +.IP \[bu] +Similarly, the defines +.IR __NR_oldolduname , +.IR __NR_olduname , +and +.I __NR_uname +refer to the routines +.IR sys_olduname (), +.IR sys_uname (), +and +.IR sys_newuname (). +.IP \[bu] +In Linux 2.0, a new version of +.BR vm86 (2) +appeared, with the old and the new kernel routines being named +.IR sys_vm86old () +and +.IR sys_vm86 (). +.IP \[bu] +In Linux 2.4, a new version of +.BR getrlimit (2) +appeared, with the old and the new kernel routines being named +.IR sys_old_getrlimit () +(slot +.IR __NR_getrlimit ) +and +.IR sys_getrlimit () +(slot +.IR __NR_ugetrlimit ). +.IP \[bu] +Linux 2.4 increased the size of user and group IDs from 16 to 32 bits. +.\" 64-bit off_t changes: ftruncate64, *stat64, +.\" fcntl64 (because of the flock structure), getdents64, *statfs64 +To support this change, a range of system calls were added +(e.g., +.BR chown32 (2), +.BR getuid32 (2), +.BR getgroups32 (2), +.BR setresuid32 (2)), +superseding earlier calls of the same name without the +"32" suffix. +.IP \[bu] +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: +.BR fcntl64 (2), +.BR getdents64 (2), +.BR stat64 (2), +.BR statfs64 (2), +.BR 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. +.IP +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. +.IP \[bu] +The +.I rt_sig* +calls were added in Linux 2.2 to support the addition +of real-time signals (see +.BR signal (7)). +These system calls supersede the older system calls of the same +name without the "rt_" prefix. +.IP \[bu] +The +.BR select (2) +and +.BR 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 +.IR sys_select () +and +.IR sys_mmap () +corresponding to +.I __NR_select +and +.IR __NR_mmap , +on i386 one finds +.IR old_select () +and +.IR 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 +.I __NR__newselect +.\" (used by libc 6) +that corresponds directly to +.IR sys_select () +and similarly +.IR __NR_mmap2 . +s390x is the only 64-bit architecture that has +.IR old_mmap (). +.\" .P +.\" Two system call numbers, +.\" .IR __NR__llseek +.\" and +.\" .IR __NR__sysctl +.\" have an additional underscore absent in +.\" .IR sys_llseek () +.\" and +.\" .IR sys_sysctl (). +.\" +.\" In Linux 2.1.81, +.\" .BR lchown (2) +.\" and +.\" .BR chown (2) +.\" were swapped; that is, +.\" .BR lchown (2) +.\" was added with the semantics that were then current for +.\" .BR chown (2), +.\" and the semantics of the latter call were changed to what +.\" they are today. +.\" +.\" +.SS "Architecture-specific details: Alpha" +.TP +.BR getxgid (2) +returns a pair of GID and effective GID via registers +\fBr0\fP and \fBr20\fP; it is provided +instead of +\fBgetgid\fP(2) and \fBgetegid\fP(2). +.TP +.BR getxpid (2) +returns a pair of PID and parent PID via registers +\fBr0\fP and \fBr20\fP; it is provided instead of +\fBgetpid\fP(2) and \fBgetppid\fP(2). +.TP +.BR old_adjtimex (2) +is a variant of \fBadjtimex\fP(2) that uses \fIstruct timeval32\fP, +for compatibility with OSF/1. +.TP +.BR getxuid (2) +returns a pair of GID and effective GID via registers +\fBr0\fP and \fBr20\fP; it is provided instead of +\fBgetuid\fP(2) and \fBgeteuid\fP(2). +.TP +.BR 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. +.SH SEE ALSO +.BR ausyscall (1), +.BR intro (2), +.BR syscall (2), +.BR unimplemented (2), +.BR errno (3), +.BR libc (7), +.BR vdso (7) diff --git a/man/man2/sysctl.2 b/man/man2/sysctl.2 new file mode 100644 index 0000000..1dc148e --- /dev/null +++ b/man/man2/sysctl.2 @@ -0,0 +1,160 @@ +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Written 11 April 1996 by Andries Brouwer +.\" 960412: Added comments from Stephen Tweedie +.\" Modified Tue Oct 22 22:28:41 1996 by Eric S. Raymond +.\" Modified Mon Jan 5 20:31:04 1998 by aeb. +.\" +.TH sysctl 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sysctl \- read/write system parameters +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "[[deprecated]] int _sysctl(struct __sysctl_args *" args ); +.fi +.SH DESCRIPTION +.B This system call no longer exists on current kernels! +See NOTES. +.P +The +.BR _sysctl () +call reads and/or writes kernel parameters. +For example, the hostname, +or the maximum number of open files. +The argument has the form +.P +.in +4n +.EX +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 */ +}; +.EE +.in +.P +This call does a search in a tree structure, possibly resembling +a directory tree under +.IR /proc/sys , +and if the requested item is found calls some appropriate routine +to read or modify the value. +.SH RETURN VALUE +Upon successful completion, +.BR _sysctl () +returns 0. +Otherwise, a value of \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.TQ +.B EPERM +No search permission for one of the encountered "directories", +or no read permission where +.I oldval +was nonzero, or no write permission where +.I newval +was nonzero. +.TP +.B EFAULT +The invocation asked for the previous value by setting +.I oldval +non-NULL, but allowed zero room in +.IR oldlenp . +.TP +.B ENOTDIR +.I name +was not found. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 1.3.57. +Removed in Linux 5.5, glibc 2.32. +.P +It originated in +4.4BSD. +Only Linux has the +.I /proc/sys +mirror, and the object naming schemes differ between Linux and 4.4BSD, +but the declaration of the +.BR sysctl () +function is the same in both. +.SH 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 +.I /proc/sys +interface instead. +.P +Note that on older kernels where this system call still exists, +it is available only if the kernel was configured with the +.B CONFIG_SYSCTL_SYSCALL +option. +Furthermore, glibc does not provide a wrapper for this system call, +necessitating the use of +.BR syscall (2). +.SH BUGS +The object names vary between kernel versions, +making this system call worthless for applications. +.P +Not all available objects are properly documented. +.P +It is not yet possible to change operating system by writing to +.IR /proc/sys/kernel/ostype . +.SH EXAMPLES +.\" SRC BEGIN (sysctl.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +\& +#include +\& +#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\en", (int) osnamelth, osname); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR proc (5) diff --git a/man/man2/sysfs.2 b/man/man2/sysfs.2 new file mode 100644 index 0000000..6452725 --- /dev/null +++ b/man/man2/sysfs.2 @@ -0,0 +1,97 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created Wed Aug 9 1995 Thomas K. Dyas +.\" +.TH sysfs 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sysfs \- get filesystem type information +.SH SYNOPSIS +.nf +.BI "[[deprecated]] int sysfs(int " option ", const char *" fsname ); +.BI "[[deprecated]] int sysfs(int " option ", unsigned int " fs_index ", char *" buf ); +.BI "[[deprecated]] int sysfs(int " option ); +.fi +.SH DESCRIPTION +.BR "Note" : +if you are looking for information about the +.B sysfs +filesystem that is normally mounted at +.IR /sys , +see +.BR sysfs (5). +.P +The (obsolete) +.BR sysfs () +system call returns information about the filesystem types +currently present in the kernel. +The specific form of the +.BR sysfs () +call and the information returned depends on the +.I option +in effect: +.TP 3 +.B 1 +Translate the filesystem identifier string +.I fsname +into a filesystem type index. +.TP +.B 2 +Translate the filesystem type index +.I fs_index +into a null-terminated filesystem identifier string. +This string will +be written to the buffer pointed to by +.IR buf . +Make sure that +.I buf +has enough space to accept the string. +.TP +.B 3 +Return the total number of filesystem types currently present in the +kernel. +.P +The numbering of the filesystem type indexes begins with zero. +.SH RETURN VALUE +On success, +.BR sysfs () +returns the filesystem index for option +.BR 1 , +zero for option +.BR 2 , +and the number of currently configured filesystems for option +.BR 3 . +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.RI "Either " fsname " or " buf +is outside your accessible address space. +.TP +.B EINVAL +.I fsname +is not a valid filesystem type identifier; +.I fs_index +is out-of-bounds; +.I option +is invalid. +.SH STANDARDS +None. +.SH HISTORY +SVr4. +.P +This System-V derived system call is obsolete; don't use it. +On systems with +.IR /proc , +the same information can be obtained via +.IR /proc ; +use that interface instead. +.SH BUGS +There is no libc or glibc support. +There is no way to guess how large \fIbuf\fP should be. +.SH SEE ALSO +.BR proc (5), +.BR sysfs (5) diff --git a/man/man2/sysinfo.2 b/man/man2/sysinfo.2 new file mode 100644 index 0000000..b13459a --- /dev/null +++ b/man/man2/sysinfo.2 @@ -0,0 +1,106 @@ +.\" Copyright (C) 2016, Michael Kerrisk +.\" Based on an earlier version of the page where a few pieces were +.\" copyright (C) 1993 by Dan Miner (dminer@nyx.cs.du.edu) and subsequently +.\" others (see old changelog below). +.\" The structure definitions are taken more or less straight from the kernel +.\" source files. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.\" Modified Sat Jul 24 12:35:12 1993 by Rik Faith +.\" Modified Tue Oct 22 22:29:51 1996 by Eric S. Raymond +.\" Modified Mon Aug 25 16:06:11 1997 by Nicolás Lichtmaier +.\" +.TH sysinfo 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sysinfo \- return system information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sysinfo(struct sysinfo *" info ); +.fi +.SH DESCRIPTION +.BR sysinfo () +returns certain statistics on memory and swap usage, +as well as the load average. +.P +Until Linux 2.3.16, +.BR sysinfo () +returned information in the following structure: +.P +.in +4n +.EX +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 */ +}; +.EE +.in +.P +In the above structure, the sizes of the memory and swap fields +are given in bytes. +.P +Since Linux 2.3.23 (i386) and Linux 2.3.48 +(all architectures) the structure is: +.P +.in +4n +.EX +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 */ +}; +.EE +.in +.P +In the above structure, +sizes of the memory and swap fields are given as multiples of +.I mem_unit +bytes. +.SH RETURN VALUE +On success, +.BR sysinfo () +returns zero. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I info +is not a valid address. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 0.98.pl6. +.SH NOTES +All of the information provided by this system call is also available via +.I /proc/meminfo +and +.IR /proc/loadavg . +.SH SEE ALSO +.BR proc (5) diff --git a/man/man2/syslog.2 b/man/man2/syslog.2 new file mode 100644 index 0000000..fe09564 --- /dev/null +++ b/man/man2/syslog.2 @@ -0,0 +1,378 @@ +'\" t +.\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2012, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Written 11 June 1995 by Andries Brouwer +.\" 2008-02-15, Jeremy Kerr +.\" Add info on command type 10; add details on types 6, 7, 8, & 9. +.\" 2008-02-15, Michael Kerrisk +.\" Update LOG_BUF_LEN details; update RETURN VALUE section. +.\" +.TH syslog 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +syslog, klogctl \- read and/or clear kernel message ring buffer; +set console_loglevel +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SYSLOG_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "int syscall(SYS_syslog, int " type ", char *" bufp ", int " len ); +.P +/* The glibc interface */ +.B #include +.P +.BI "int klogctl(int " type ", char *" bufp ", int " len ); +.fi +.SH DESCRIPTION +.IR Note : +Probably, you are looking for the C library function +.BR syslog (), +which talks to +.BR syslogd (8); +see +.BR syslog (3) +for details. +.P +This page describes the kernel +.BR syslog () +system call, which is used to control the kernel +.IR printk () +buffer; the glibc wrapper function for the system call is called +.BR klogctl (). +.SS The kernel log buffer +The kernel has a cyclic buffer of length +.B LOG_BUF_LEN +in which messages given as arguments to the kernel function +.BR printk () +are stored (regardless of their log level). +In early kernels, +.B 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 +.RB ( CONFIG_LOG_BUF_SHIFT , +default value dependent on the architecture). +.\" Under "General setup" ==> "Kernel log buffer size" +.\" For Linux 2.6, precisely the option seems to have appeared in Linux 2.5.55. +Since Linux 2.6.6, the size can be queried with command type 10 (see below). +.SS Commands +The \fItype\fP argument determines the action taken by this function. +The list below specifies the values for +.IR 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. +.TP +.BR SYSLOG_ACTION_CLOSE " (0)" +Close the log. +Currently a NOP. +.TP +.BR SYSLOG_ACTION_OPEN " (1)" +Open the log. +Currently a NOP. +.TP +.BR SYSLOG_ACTION_READ " (2)" +Read from the log. +The call +waits until the kernel log buffer is nonempty, and then reads +at most \fIlen\fP bytes into the buffer pointed to by +.IR 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 +.IR /proc/kmsg . +.TP +.BR SYSLOG_ACTION_READ_ALL " (3)" +Read all messages remaining in the ring buffer, +placing them in the buffer pointed to by +.IR bufp . +The call reads the last \fIlen\fP +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. +.TP +.BR SYSLOG_ACTION_READ_CLEAR " (4)" +Read and clear all messages remaining in the ring buffer. +The call does precisely the same as for a +.I type +of 3, but also executes the "clear ring buffer" command. +.TP +.BR SYSLOG_ACTION_CLEAR " (5)" +The call executes just the "clear ring buffer" command. +The +.I bufp +and +.I len +arguments are ignored. +.IP +This command does not really clear the ring buffer. +Rather, it sets a kernel bookkeeping variable that +determines the results returned by commands 3 +.RB ( SYSLOG_ACTION_READ_ALL ) +and 4 +.RB ( SYSLOG_ACTION_READ_CLEAR ). +This command has no effect on commands 2 +.RB ( SYSLOG_ACTION_READ ) +and 9 +.RB ( SYSLOG_ACTION_SIZE_UNREAD ). +.TP +.BR SYSLOG_ACTION_CONSOLE_OFF " (6)" +The command saves the current value of +.I console_loglevel +and then sets +.I console_loglevel +to +.IR minimum_console_loglevel , +so that no messages are printed to the console. +Before Linux 2.6.32, +.\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245 +the command simply sets +.I console_loglevel +to +.IR minimum_console_loglevel . +See the discussion of +.IR /proc/sys/kernel/printk , +below. +.IP +The +.I bufp +and +.I len +arguments are ignored. +.TP +.BR SYSLOG_ACTION_CONSOLE_ON " (7)" +If a previous +.B SYSLOG_ACTION_CONSOLE_OFF +command has been performed, +this command restores +.I console_loglevel +to the value that was saved by that command. +Before Linux 2.6.32, +.\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245 +this command simply sets +.I console_loglevel +to +.IR default_console_loglevel . +See the discussion of +.IR /proc/sys/kernel/printk , +below. +.IP +The +.I bufp +and +.I len +arguments are ignored. +.TP +.BR SYSLOG_ACTION_CONSOLE_LEVEL " (8)" +The call sets +.I console_loglevel +to the value given in +.IR len , +which must be an integer between 1 and 8 (inclusive). +The kernel silently enforces a minimum value of +.I minimum_console_loglevel +for +.IR len . +See the +.I log level +section for details. +The +.I bufp +argument is ignored. +.TP +.BR 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 +.RB ( SYSLOG_ACTION_READ ). +The +.I bufp +and +.I len +arguments are ignored. +.TP +.BR SYSLOG_ACTION_SIZE_BUFFER " (10) (since Linux 2.6.6)" +This command returns the total size of the kernel log buffer. +The +.I bufp +and +.I len +arguments are ignored. +.P +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 +.I /proc/sys/kernel/dmesg_restrict +has the value 0. +Before Linux 2.6.37, "privileged" means that the caller has the +.B CAP_SYS_ADMIN +capability. +Since Linux 2.6.37, +"privileged" means that the caller has either the +.B CAP_SYS_ADMIN +capability (now deprecated for this purpose) or the (new) +.B CAP_SYSLOG +capability. +.\" +.\" +.SS /proc/sys/kernel/printk +.I /proc/sys/kernel/printk +is a writable file containing four integer values that influence kernel +.I printk() +behavior when printing or logging error messages. +The four values are: +.TP +.I 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 +.B DEFAULT_CONSOLE_LOGLEVEL +(7), but it is set to +4 if the kernel command line contains the word "quiet",\" since Linux 2.4 +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 +.I console_loglevel +can be set (to a value in the range 1\[en]8) by a +.BR syslog () +call with a +.I type +of 8. +.TP +.I default_message_loglevel +This value will be used as the log level for +.I 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 +.RB ( KERN_WARNING ); +since Linux 2.6.39, +.\" commit 5af5bcb8d37f99ba415a1adc6da71051b84f93a5 +the default value is defined by the kernel configuration option +.BR CONFIG_DEFAULT_MESSAGE_LOGLEVEL , +which defaults to 4. +.TP +.I minimum_console_loglevel +The value in this field is the minimum value to which +.I console_loglevel +can be set. +.TP +.I default_console_loglevel +This is the default value for +.IR console_loglevel . +.\" +.\" +.SS The log level +Every +.IR printk () +message has its own log level. +If the log level is not explicitly specified as part of the message, +it defaults to +.IR default_message_loglevel . +The conventional meaning of the log level is as follows: +.TS +lB lB lB +lB c l. +Kernel constant Level value Meaning +KERN_EMERG 0 System is unusable +KERN_ALERT 1 T{ +Action must be taken immediately +T} +KERN_CRIT 2 Critical conditions +KERN_ERR 3 Error conditions +KERN_WARNING 4 Warning conditions +KERN_NOTICE 5 T{ +Normal but significant condition +T} +KERN_INFO 6 Informational +KERN_DEBUG 7 Debug-level messages +.TE +.P +The kernel +.I printk() +routine will print a message on the +console only if it has a log level less than the value of +.IR console_loglevel . +.SH RETURN VALUE +For \fItype\fP equal to 2, 3, or 4, a successful call to +.BR syslog () +returns the number +of bytes read. +For \fItype\fP 9, +.BR syslog () +returns the number of bytes currently +available to be read on the kernel log buffer. +For \fItype\fP 10, +.BR syslog () +returns the total size of the kernel log buffer. +For other values of \fItype\fP, 0 is returned on success. +.P +In case of error, \-1 is returned, +and \fIerrno\fP is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Bad arguments (e.g., +bad +.IR type ; +or for +.I type +2, 3, or 4, +.I buf +is NULL, +or +.I len +is less than zero; or for +.I type +8, the +.I level +is outside the range 1 to 8). +.TP +.B ENOSYS +This +.BR syslog () +system call is not available, because the kernel was compiled with the +.B CONFIG_PRINTK +kernel-configuration option disabled. +.TP +.B EPERM +An attempt was made to change +.I console_loglevel +or clear the kernel +message ring buffer by a process without sufficient privilege +(more precisely: without the +.B CAP_SYS_ADMIN +or +.B CAP_SYSLOG +capability). +.TP +.B ERESTARTSYS +System call was interrupted by a signal; nothing was read. +(This can be seen only during a trace.) +.SH STANDARDS +Linux. +.SH 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. +.\" In libc4 and libc5 the number of this call was defined by +.\" .BR SYS_klog . +.\" In glibc 2.0 the syscall is baptized +.\" .BR klogctl (). +.SH SEE ALSO +.BR dmesg (1), +.BR syslog (3), +.BR capabilities (7) diff --git a/man/man2/tee.2 b/man/man2/tee.2 new file mode 100644 index 0000000..4e677b4 --- /dev/null +++ b/man/man2/tee.2 @@ -0,0 +1,200 @@ +.\" This manpage is Copyright (C) 2006 Jens Axboe +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tee 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tee \- duplicating pipe content +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "ssize_t tee(int " fd_in ", int " fd_out ", size_t " len \ +", unsigned int " flags ); +.fi +.\" Return type was long before glibc 2.7 +.SH DESCRIPTION +.\" Example programs http://brick.kernel.dk/snaps +.\" +.\" +.\" add a "tee(in, out1, out2)" system call that duplicates the pages +.\" (again, incrementing their reference count, not copying the data) from +.\" one pipe to two other pipes. +.BR tee () +duplicates up to +.I len +bytes of data from the pipe referred to by the file descriptor +.I fd_in +to the pipe referred to by the file descriptor +.IR fd_out . +It does not consume the data that is duplicated from +.IR fd_in ; +therefore, that data can be copied by a subsequent +.BR splice (2). +.P +.I flags +is a bit mask that is composed by ORing together +zero or more of the following values: +.TP 1.9i +.B SPLICE_F_MOVE +Currently has no effect for +.BR tee (); +see +.BR splice (2). +.TP +.B SPLICE_F_NONBLOCK +Do not block on I/O; see +.BR splice (2) +for further details. +.TP +.B SPLICE_F_MORE +Currently has no effect for +.BR tee (), +but may be implemented in the future; see +.BR splice (2). +.TP +.B SPLICE_F_GIFT +Unused for +.BR tee (); +see +.BR vmsplice (2). +.SH RETURN VALUE +Upon successful completion, +.BR 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 +.IR fd_in . +.P +On error, +.BR tee () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +.B SPLICE_F_NONBLOCK +was specified in +.I flags +or one of the file descriptors had been marked as nonblocking +.RB ( O_NONBLOCK ) , +and the operation would block. +.TP +.B EINVAL +.I fd_in +or +.I fd_out +does not refer to a pipe; or +.I fd_in +and +.I fd_out +refer to the same pipe. +.TP +.B ENOMEM +Out of memory. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.17, +glibc 2.5. +.SH NOTES +Conceptually, +.BR tee () +copies the data between the two pipes. +In reality no real data copying takes place though: +under the covers, +.BR tee () +assigns data to the output by merely grabbing +a reference to the input. +.SH EXAMPLES +The example below implements a basic +.BR tee (1) +program using the +.BR tee () +system call. +Here is an example of its use: +.P +.in +4n +.EX +$ \fBdate | ./a.out out.log | cat\fP +Tue Oct 28 10:06:00 CET 2014 +$ \fBcat out.log\fP +Tue Oct 28 10:06:00 CET 2014 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (tee.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int fd; + ssize_t len, slen; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", 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); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR splice (2), +.BR vmsplice (2), +.BR pipe (7) diff --git a/man/man2/tgkill.2 b/man/man2/tgkill.2 new file mode 100644 index 0000000..82fc2d6 --- /dev/null +++ b/man/man2/tgkill.2 @@ -0,0 +1 @@ +.so man2/tkill.2 diff --git a/man/man2/time.2 b/man/man2/time.2 new file mode 100644 index 0000000..46b845d --- /dev/null +++ b/man/man2/time.2 @@ -0,0 +1,114 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified Sat Jul 24 14:13:40 1993 by Rik Faith +.\" Additions by Joseph S. Myers , 970909 +.\" +.TH time 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +time \- get time in seconds +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "time_t time(time_t *_Nullable " tloc ); +.fi +.SH DESCRIPTION +.BR time () +returns the time as the number of seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.P +If +.I tloc +is non-NULL, +the return value is also stored in the memory pointed to by +.IR tloc . +.SH RETURN VALUE +On success, the value of time in seconds since the Epoch is returned. +On error, \fI((time_t)\ \-1)\fP is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EOVERFLOW +The time cannot be represented as a +.I time_t +value. +This can happen if an executable with 32-bit +.I time_t +is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later. +However, when the system time is out of +.I time_t +range in other situations, the behavior is undefined. +.TP +.B EFAULT +.I tloc +points outside your accessible address space (but see BUGS). +.IP +On systems where the C library +.BR time () +wrapper function invokes an implementation provided by the +.BR vdso (7) +(so that there is no trap into the kernel), +an invalid address may instead trigger a +.B SIGSEGV +signal. +.SH VERSIONS +POSIX.1 defines +.I 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. +Linux systems normally follow the POSIX requirement +that this value ignore leap seconds, +so that conforming systems interpret it consistently; +see POSIX.1-2018 Rationale A.4.16. +.P +Applications intended to run after 2038 should use ABIs with +.I time_t +wider than 32 bits; see +.BR time_t (3type). +.SS C library/kernel differences +On some architectures, an implementation of +.BR time () +is provided in the +.BR vdso (7). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +SVr4, 4.3BSD, C89, POSIX.1-2001. +.\" Under 4.3BSD, this call is obsoleted by +.\" .BR gettimeofday (2). +.SH BUGS +Error returns from this system call are indistinguishable from +successful reports that the time is a few seconds +.I before +the Epoch, so the C library wrapper function never sets +.I errno +as a result of this call. +.P +The +.I tloc +argument is obsolescent and should always be NULL in new code. +When +.I tloc +is NULL, the call cannot fail. +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR ctime (3), +.BR ftime (3), +.BR time (7), +.BR vdso (7) diff --git a/man/man2/timer_create.2 b/man/man2/timer_create.2 new file mode 100644 index 0000000..0c1157b --- /dev/null +++ b/man/man2/timer_create.2 @@ -0,0 +1,487 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH timer_create 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timer_create \- create a POSIX per-process timer +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SIGEV_* " constants */" +.B #include +.P +.BI "int timer_create(clockid_t " clockid , +.BI " struct sigevent *_Nullable restrict " sevp , +.BI " timer_t *restrict " timerid ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR timer_create (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +.BR timer_create () +creates a new per-process interval timer. +The ID of the new timer is returned in the buffer pointed to by +.IR 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. +.P +The +.I clockid +argument specifies the clock that the new timer uses to measure time. +It can be specified as one of the following values: +.TP +.B CLOCK_REALTIME +A settable system-wide real-time clock. +.TP +.B CLOCK_MONOTONIC +A nonsettable monotonically increasing clock that measures time +from some unspecified point in the past that does not change +after system startup. +.\" Note: the CLOCK_MONOTONIC_RAW clock added for clock_gettime() +.\" in Linux 2.6.28 is not supported for POSIX timers -- mtk, Feb 2009 +.TP +.BR 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. +.TP +.BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" +A clock that measures (user and system) CPU time consumed by +the calling thread. +.\" The CLOCK_MONOTONIC_RAW that was added in Linux 2.6.28 can't be used +.\" to create a timer -- mtk, Feb 2009 +.TP +.BR CLOCK_BOOTTIME " (Since Linux 2.6.39)" +.\" commit 70a08cca1227dc31c784ec930099a4417a06e7d0 +Like +.BR CLOCK_MONOTONIC , +this is a monotonically increasing clock. +However, whereas the +.B CLOCK_MONOTONIC +clock does not measure the time while a system is suspended, the +.B CLOCK_BOOTTIME +clock does include the time during which the system is suspended. +This is useful for applications that need to be suspend-aware. +.B CLOCK_REALTIME +is not suitable for such applications, since that clock is affected +by discontinuous changes to the system clock. +.TP +.BR CLOCK_REALTIME_ALARM " (since Linux 3.0)" +.\" commit 9a7adcf5c6dea63d2e47e6f6d2f7a6c9f48b9337 +This clock is like +.BR CLOCK_REALTIME , +but will wake the system if it is suspended. +The caller must have the +.B CAP_WAKE_ALARM +capability in order to set a timer against this clock. +.TP +.BR CLOCK_BOOTTIME_ALARM " (since Linux 3.0)" +.\" commit 9a7adcf5c6dea63d2e47e6f6d2f7a6c9f48b9337 +This clock is like +.BR CLOCK_BOOTTIME , +but will wake the system if it is suspended. +The caller must have the +.B CAP_WAKE_ALARM +capability in order to set a timer against this clock. +.TP +.BR CLOCK_TAI " (since Linux 3.10)" +A system-wide clock derived from wall-clock time but counting leap seconds. +.P +See +.BR clock_getres (2) +for some further details on the above clocks. +.P +As well as the above values, +.I clockid +can be specified as the +.I clockid +returned by a call to +.BR clock_getcpuclockid (3) +or +.BR pthread_getcpuclockid (3). +.P +The +.I sevp +argument points to a +.I sigevent +structure that specifies how the caller +should be notified when the timer expires. +For the definition and general details of this structure, see +.BR sigevent (3type). +.P +The +.I sevp.sigev_notify +field can have the following values: +.TP +.B SIGEV_NONE +Don't asynchronously notify when the timer expires. +Progress of the timer can be monitored using +.BR timer_gettime (2). +.TP +.B SIGEV_SIGNAL +Upon timer expiration, generate the signal +.I sigev_signo +for the process. +See +.BR sigevent (3type) +for general details. +The +.I si_code +field of the +.I siginfo_t +structure will be set to +.BR SI_TIMER . +At any point in time, +at most one signal is queued to the process for a given timer; see +.BR timer_getoverrun (2) +for more details. +.TP +.B SIGEV_THREAD +Upon timer expiration, invoke +.I sigev_notify_function +as if it were the start function of a new thread. +See +.BR sigevent (3type) +for details. +.TP +.BR SIGEV_THREAD_ID " (Linux-specific)" +As for +.BR SIGEV_SIGNAL , +but the signal is targeted at the thread whose ID is given in +.IR sigev_notify_thread_id , +which must be a thread in the same process as the caller. +The +.I sigev_notify_thread_id +field specifies a kernel thread ID, that is, the value returned by +.BR clone (2) +or +.BR gettid (2). +This flag is intended only for use by threading libraries. +.P +Specifying +.I sevp +as NULL is equivalent to specifying a pointer to a +.I sigevent +structure in which +.I sigev_notify +is +.BR SIGEV_SIGNAL , +.I sigev_signo +is +.BR SIGALRM , +and +.I sigev_value.sival_int +is the timer ID. +.SH RETURN VALUE +On success, +.BR timer_create () +returns 0, and the ID of the new timer is placed in +.IR *timerid . +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +Temporary error during kernel allocation of timer structures. +.TP +.B EINVAL +Clock ID, +.IR sigev_notify , +.IR sigev_signo , +or +.I sigev_notify_thread_id +is invalid. +.TP +.B ENOMEM +.\" glibc layer: malloc() +Could not allocate memory. +.TP +.B ENOTSUP +The kernel does not support creating a timer against this +.IR clockid . +.TP +.B EPERM +.I clockid +was +.B CLOCK_REALTIME_ALARM +or +.B CLOCK_BOOTTIME_ALARM +but the caller did not have the +.B CAP_WAKE_ALARM +capability. +.SH VERSIONS +.SS C library/kernel differences +Part of the implementation of the POSIX timers API is provided by glibc. +.\" See nptl/sysdeps/unix/sysv/linux/timer_create.c +In particular: +.IP \[bu] 3 +Much of the functionality for +.B 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 +.I sigev_notify +value of +.B SIGEV_THREAD_ID +along with a real-time signal that is reserved by the implementation (see +.BR nptl (7)). +.IP \[bu] +The implementation of the default case where +.I evp +is NULL is handled inside glibc, +which invokes the underlying system call with a suitably populated +.I sigevent +structure. +.IP \[bu] +The timer IDs presented at user level are maintained by glibc, +which maps these IDs to the timer IDs employed by the kernel. +.\" See the glibc source file kernel-posix-timers.h for the structure +.\" that glibc uses to map user-space timer IDs to kernel timer IDs +.\" The kernel-level timer ID is exposed via siginfo.si_tid. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +Linux 2.6. +POSIX.1-2001. +.P +Prior to Linux 2.6, +glibc provided an incomplete user-space implementation +.RB ( CLOCK_REALTIME +timers only) using POSIX threads, +and before glibc 2.17, +.\" glibc commit 93a78ac437ba44f493333d7e2a4b0249839ce460 +the implementation falls back to this technique on systems +running kernels older than Linux 2.6. +.SH NOTES +A program may create multiple interval timers using +.BR timer_create (). +.P +Timers are not inherited by the child of a +.BR fork (2), +and are disarmed and deleted during an +.BR execve (2). +.P +The kernel preallocates a "queued real-time signal" +for each timer created using +.BR timer_create (). +Consequently, the number of timers is limited by the +.B RLIMIT_SIGPENDING +resource limit (see +.BR setrlimit (2)). +.P +The timers created by +.BR timer_create () +are commonly known as "POSIX (interval) timers". +The POSIX timers API consists of the following interfaces: +.TP +.BR timer_create () +Create a timer. +.TP +.BR timer_settime (2) +Arm (start) or disarm (stop) a timer. +.TP +.BR timer_gettime (2) +Fetch the time remaining until the next expiration of a timer, +along with the interval setting of the timer. +.TP +.BR timer_getoverrun (2) +Return the overrun count for the last timer expiration. +.TP +.BR timer_delete (2) +Disarm and delete a timer. +.P +Since Linux 3.10, the +.IR /proc/ pid /timers +file can be used to list the POSIX timers for the process with PID +.IR pid . +See +.BR proc (5) +for further information. +.P +Since Linux 4.10, +.\" baa73d9e478ff32d62f3f9422822b59dd9a95a21 +support for POSIX timers is a configurable option that is enabled by default. +Kernel support can be disabled via the +.B CONFIG_POSIX_TIMERS +option. +.SH 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. +.P +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. +.P +.in +4n +.EX +$ \fB./a.out 1 100\fP +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 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (timer_create.c) +.EX +#include +#include +#include +#include +#include +#include +\& +#define CLOCKID CLOCK_REALTIME +#define SIG SIGRTMIN +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } 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\en", (uintmax_t) *tidp); +\& + or = timer_getoverrun(*tidp); + if (or == \-1) + errExit("timer_getoverrun"); + else + printf(" overrun count = %d\en", 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\en", 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 \en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Establish handler for timer signal. */ +\& + printf("Establishing handler for signal %d\en", 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\en", 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\en", (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\en", atoi(argv[1])); + sleep(atoi(argv[1])); +\& + /* Unlock the timer signal, so that timer notification + can be delivered. */ +\& + printf("Unblocking signal %d\en", SIG); + if (sigprocmask(SIG_UNBLOCK, &mask, NULL) == \-1) + errExit("sigprocmask"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR clock_gettime (2), +.BR setitimer (2), +.BR timer_delete (2), +.BR timer_getoverrun (2), +.BR timer_settime (2), +.BR timerfd_create (2), +.BR clock_getcpuclockid (3), +.BR pthread_getcpuclockid (3), +.BR pthreads (7), +.BR sigevent (3type), +.BR signal (7), +.BR time (7) diff --git a/man/man2/timer_delete.2 b/man/man2/timer_delete.2 new file mode 100644 index 0000000..56d0cdf --- /dev/null +++ b/man/man2/timer_delete.2 @@ -0,0 +1,58 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH timer_delete 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timer_delete \- delete a POSIX per-process timer +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int timer_delete(timer_t " timerid ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR timer_delete (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +.BR timer_delete () +deletes the timer whose ID is given in +.IR 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. +.SH RETURN VALUE +On success, +.BR timer_delete () +returns 0. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I timerid +is not a valid timer ID. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +Linux 2.6. +POSIX.1-2001. +.SH SEE ALSO +.BR clock_gettime (2), +.BR timer_create (2), +.BR timer_getoverrun (2), +.BR timer_settime (2), +.BR time (7) diff --git a/man/man2/timer_getoverrun.2 b/man/man2/timer_getoverrun.2 new file mode 100644 index 0000000..a2bd9b5 --- /dev/null +++ b/man/man2/timer_getoverrun.2 @@ -0,0 +1,134 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH timer_getoverrun 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timer_getoverrun \- get overrun count for a POSIX per-process timer +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int timer_getoverrun(timer_t " timerid ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR timer_getoverrun (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +.BR timer_getoverrun () +returns the "overrun count" for the timer referred to by +.IR 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 +.RB ( SIGEV_SIGNAL ), +and via threads +.RB ( SIGEV_THREAD ). +.P +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 +.BR 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. +.P +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. +.SH RETURN VALUE +On success, +.BR 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 +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I timerid +is not a valid timer ID. +.SH VERSIONS +When timer notifications are delivered via signals +.RB ( SIGEV_SIGNAL ), +on Linux it is also possible to obtain the overrun count via the +.I si_overrun +field of the +.I siginfo_t +structure (see +.BR 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. +.P +POSIX.1 discusses timer overruns only in the context of +timer notifications using signals. +.\" FIXME . Austin bug filed, 11 Feb 09 +.\" https://www.austingroupbugs.net/view.php?id=95 +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +Linux 2.6. +POSIX.1-2001. +.SH BUGS +POSIX.1 specifies that if the timer overrun count +is equal to or greater than an implementation-defined maximum, +.BR DELAYTIMER_MAX , +then +.BR timer_getoverrun () +should return +.BR DELAYTIMER_MAX . +However, before Linux 4.19, +.\" http://bugzilla.kernel.org/show_bug.cgi?id=12665 +if the timer overrun value exceeds the maximum representable integer, +the counter cycles, starting once more from low values. +Since Linux 4.19, +.\" commit 78c9c4dfbf8c04883941445a195276bb4bb92c76 +.BR timer_getoverrun () +returns +.B DELAYTIMER_MAX +(defined as +.B INT_MAX +in +.IR ) +in this case (and the overrun value is reset to 0). +.SH EXAMPLES +See +.BR timer_create (2). +.SH SEE ALSO +.BR clock_gettime (2), +.BR sigaction (2), +.BR signalfd (2), +.BR sigwaitinfo (2), +.BR timer_create (2), +.BR timer_delete (2), +.BR timer_settime (2), +.BR signal (7), +.BR time (7) diff --git a/man/man2/timer_gettime.2 b/man/man2/timer_gettime.2 new file mode 100644 index 0000000..42015ca --- /dev/null +++ b/man/man2/timer_gettime.2 @@ -0,0 +1 @@ +.so man2/timer_settime.2 diff --git a/man/man2/timer_settime.2 b/man/man2/timer_settime.2 new file mode 100644 index 0000000..ce043ff --- /dev/null +++ b/man/man2/timer_settime.2 @@ -0,0 +1,187 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH timer_settime 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timer_settime, timer_gettime \- arm/disarm and fetch +state of POSIX per-process timer +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int timer_gettime(timer_t " timerid ", struct itimerspec *" curr_value ); +.BI "int timer_settime(timer_t " timerid ", int " flags , +.BI " const struct itimerspec *restrict " new_value , +.BI " struct itimerspec *_Nullable restrict " old_value ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR timer_settime (), +.BR timer_gettime (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +.BR timer_settime () +arms or disarms the timer identified by +.IR timerid . +The +.I new_value +argument is pointer to an +.I itimerspec +structure that specifies the new initial value and +the new interval for the timer. +The +.I itimerspec +structure is described in +.BR itimerspec (3type). +.P +Each of the substructures of the +.I itimerspec +structure is a +.BR 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 +.BR timer_create (2). +.P +If +.I new_value\->it_value +specifies a nonzero value (i.e., either subfield is nonzero), then +.BR 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 +.I new_value\->it_value +specifies a zero value +(i.e., both subfields are zero), +then the timer is disarmed. +.P +The +.I 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 +.IR new_value\->it_interval . +If +.I new_value\->it_interval +specifies a zero value, +then the timer expires just once, at the time specified by +.IR it_value . +.P +By default, the initial expiration time specified in +.I 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 +.B TIMER_ABSTIME +in +.IR flags , +in which case +.I 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 +.IR new_value\->it_value . +If the specified absolute time has already passed, +then the timer expires immediately, +and the overrun count (see +.BR timer_getoverrun (2)) +will be set correctly. +.\" By experiment: the overrun count is set correctly, for CLOCK_REALTIME. +.P +If the value of the +.B 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 +.B CLOCK_REALTIME +clock have no effect on relative timers based on that clock. +.\" Similar remarks might apply with respect to process and thread CPU time +.\" clocks, but these clocks are not currently (2.6.28) settable on Linux. +.P +If +.I old_value +is not NULL, then it points to a buffer +that is used to return the previous interval of the timer (in +.IR old_value\->it_interval ) +and the amount of time until the timer +would previously have next expired (in +.IR old_value\->it_value ). +.P +.BR timer_gettime () +returns the time until next expiration, and the interval, +for the timer specified by +.IR timerid , +in the buffer pointed to by +.IR curr_value . +The time remaining until the next timer expiration is returned in +.IR curr_value\->it_value ; +this is always a relative value, regardless of whether the +.B TIMER_ABSTIME +flag was used when arming the timer. +If the value returned in +.I curr_value\->it_value +is zero, then the timer is currently disarmed. +The timer interval is returned in +.IR curr_value\->it_interval . +If the value returned in +.I curr_value\->it_interval +is zero, then this is a "one-shot" timer. +.SH RETURN VALUE +On success, +.BR timer_settime () +and +.BR timer_gettime () +return 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +These functions may fail with the following errors: +.TP +.B EFAULT +.IR new_value , +.IR old_value , +or +.I curr_value +is not a valid pointer. +.TP +.B EINVAL +.I timerid +is invalid. +.\" FIXME . eventually: invalid value in flags +.P +.BR timer_settime () +may fail with the following errors: +.TP +.B EINVAL +.I new_value.it_value +is negative; or +.I new_value.it_value.tv_nsec +is negative or greater than 999,999,999. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +Linux 2.6. +POSIX.1-2001. +.SH EXAMPLES +See +.BR timer_create (2). +.SH SEE ALSO +.BR timer_create (2), +.BR timer_getoverrun (2), +.BR timespec (3), +.BR time (7) diff --git a/man/man2/timerfd_create.2 b/man/man2/timerfd_create.2 new file mode 100644 index 0000000..b9972c9 --- /dev/null +++ b/man/man2/timerfd_create.2 @@ -0,0 +1,705 @@ +.\" Copyright (C) 2008 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH timerfd_create 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timerfd_create, timerfd_settime, timerfd_gettime \- +timers that notify via file descriptors +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int timerfd_create(int " clockid ", int " flags ); +.P +.BI "int timerfd_settime(int " fd ", int " flags , +.BI " const struct itimerspec *" new_value , +.BI " struct itimerspec *_Nullable " old_value ); +.BI "int timerfd_gettime(int " fd ", struct itimerspec *" curr_value ); +.fi +.SH 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 +.BR setitimer (2) +or +.BR timer_create (2), +with the advantage that the file descriptor may be monitored by +.BR select (2), +.BR poll (2), +and +.BR epoll (7). +.P +The use of these three system calls is analogous to the use of +.BR timer_create (2), +.BR timer_settime (2), +and +.BR timer_gettime (2). +(There is no analog of +.BR timer_getoverrun (2), +since that functionality is provided by +.BR read (2), +as described below.) +.\" +.SS timerfd_create() +.BR timerfd_create () +creates a new timer object, +and returns a file descriptor that refers to that timer. +The +.I clockid +argument specifies the clock that is used to mark the progress +of the timer, and must be one of the following: +.TP +.B CLOCK_REALTIME +A settable system-wide real-time clock. +.TP +.B CLOCK_MONOTONIC +A nonsettable monotonically increasing clock that measures time +from some unspecified point in the past that does not change +after system startup. +.TP +.BR CLOCK_BOOTTIME " (Since Linux 3.15)" +.\" commit 4a2378a943f09907fb1ae35c15de917f60289c14 +Like +.BR CLOCK_MONOTONIC , +this is a monotonically increasing clock. +However, whereas the +.B CLOCK_MONOTONIC +clock does not measure the time while a system is suspended, the +.B CLOCK_BOOTTIME +clock does include the time during which the system is suspended. +This is useful for applications that need to be suspend-aware. +.B CLOCK_REALTIME +is not suitable for such applications, since that clock is affected +by discontinuous changes to the system clock. +.TP +.BR CLOCK_REALTIME_ALARM " (since Linux 3.11)" +.\" commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8 +This clock is like +.BR CLOCK_REALTIME , +but will wake the system if it is suspended. +The caller must have the +.B CAP_WAKE_ALARM +capability in order to set a timer against this clock. +.TP +.BR CLOCK_BOOTTIME_ALARM " (since Linux 3.11)" +.\" commit 11ffa9d6065f344a9bd769a2452f26f2f671e5f8 +This clock is like +.BR CLOCK_BOOTTIME , +but will wake the system if it is suspended. +The caller must have the +.B CAP_WAKE_ALARM +capability in order to set a timer against this clock. +.P +See +.BR clock_getres (2) +for some further details on the above clocks. +.P +The current value of each of these clocks can be retrieved using +.BR clock_gettime (2). +.P +Starting with Linux 2.6.27, the following values may be bitwise ORed in +.I flags +to change the behavior of +.BR timerfd_create (): +.TP 14 +.B TFD_NONBLOCK +Set the +.B O_NONBLOCK +file status flag on the open file description (see +.BR open (2)) +referred to by the new file descriptor. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B TFD_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.P +In Linux versions up to and including 2.6.26, +.I flags +must be specified as zero. +.SS timerfd_settime() +.BR timerfd_settime () +arms (starts) or disarms (stops) +the timer referred to by the file descriptor +.IR fd . +.P +The +.I new_value +argument specifies the initial expiration and interval for the timer. +The +.I itimerspec +structure used for this argument is described in +.BR itimerspec (3type). +.P +.I new_value.it_value +specifies the initial expiration of the timer, +in seconds and nanoseconds. +Setting either field of +.I new_value.it_value +to a nonzero value arms the timer. +Setting both fields of +.I new_value.it_value +to zero disarms the timer. +.P +Setting one or both fields of +.I 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 +.I new_value.it_interval +are zero, the timer expires just once, at the time specified by +.IR new_value.it_value . +.P +By default, +the initial expiration time specified in +.I new_value +is interpreted relative to the current time +on the timer's clock at the time of the call (i.e., +.I new_value.it_value +specifies a time relative to the current value of the clock specified by +.IR clockid ). +An absolute timeout can be selected via the +.I flags +argument. +.P +The +.I flags +argument is a bit mask that can include the following values: +.TP +.B TFD_TIMER_ABSTIME +Interpret +.I 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 +.IR new_value.it_value . +.TP +.B TFD_TIMER_CANCEL_ON_SET +If this flag is specified along with +.B TFD_TIMER_ABSTIME +and the clock for this timer is +.B CLOCK_REALTIME +or +.BR CLOCK_REALTIME_ALARM , +then mark this timer as cancelable if the real-time clock +undergoes a discontinuous change +.RB ( settimeofday (2), +.BR clock_settime (2), +or similar). +When such changes occur, a current or future +.BR read (2) +from the file descriptor will fail with the error +.BR ECANCELED . +.P +If the +.I old_value +argument is not NULL, then the +.I 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 +.BR timerfd_gettime () +following. +.\" +.SS timerfd_gettime() +.BR timerfd_gettime () +returns, in +.IR curr_value , +an +.I itimerspec +structure that contains the current setting of the timer +referred to by the file descriptor +.IR fd . +.P +The +.I 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 +.B TFD_TIMER_ABSTIME +flag was specified when setting the timer. +.P +The +.I 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 +.IR curr_value.it_value . +.SS Operating on a timer file descriptor +The file descriptor returned by +.BR timerfd_create () +supports the following additional operations: +.TP +.BR read (2) +If the timer has already expired one or more times since +its settings were last modified using +.BR timerfd_settime (), +or since the last successful +.BR read (2), +then the buffer given to +.BR read (2) +returns an unsigned 8-byte integer +.RI ( uint64_t ) +containing the number of expirations that have occurred. +(The returned value is in host byte order\[em]that is, +the native byte order for integers on the host machine.) +.IP +If no timer expirations have occurred at the time of the +.BR read (2), +then the call either blocks until the next timer expiration, +or fails with the error +.B EAGAIN +if the file descriptor has been made nonblocking +(via the use of the +.BR fcntl (2) +.B F_SETFL +operation to set the +.B O_NONBLOCK +flag). +.IP +A +.BR read (2) +fails with the error +.B EINVAL +if the size of the supplied buffer is less than 8 bytes. +.IP +If the associated clock is either +.B CLOCK_REALTIME +or +.BR CLOCK_REALTIME_ALARM , +the timer is absolute +.RB ( TFD_TIMER_ABSTIME ), +and the flag +.B TFD_TIMER_CANCEL_ON_SET +was specified when calling +.BR timerfd_settime (), +then +.BR read (2) +fails with the error +.B ECANCELED +if the real-time clock undergoes a discontinuous change. +(This allows the reading application to discover +such discontinuous changes to the clock.) +.IP +If the associated clock is either +.B CLOCK_REALTIME +or +.BR CLOCK_REALTIME_ALARM , +the timer is absolute +.RB ( TFD_TIMER_ABSTIME ), +and the flag +.B TFD_TIMER_CANCEL_ON_SET +was +.I not +specified when calling +.BR timerfd_settime (), +then a discontinuous negative change to the clock (e.g., +.BR clock_settime (2)) +may cause +.BR 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 +.BR read (2) +on the file descriptor. +.TP +.BR poll (2) +.TQ +.BR select (2) +.TQ +(and similar) +The file descriptor is readable +(the +.BR select (2) +.I readfds +argument; the +.BR poll (2) +.B POLLIN +flag) +if one or more timer expirations have occurred. +.IP +The file descriptor also supports the other file-descriptor +multiplexing APIs: +.BR pselect (2), +.BR ppoll (2), +and +.BR epoll (7). +.TP +.BR ioctl (2) +The following timerfd-specific command is supported: +.RS +.TP +.BR TFD_IOC_SET_TICKS " (since Linux 3.17)" +.\" commit 5442e9fbd7c23172a1c9bc736629cd123a9923f0 +Adjust the number of timer expirations that have occurred. +The argument is a pointer to a nonzero 8-byte integer +.RI ( 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 +.B CONFIG_CHECKPOINT_RESTORE +option. +.RE +.TP +.BR 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. +.\" +.SS fork(2) semantics +After a +.BR fork (2), +the child inherits a copy of the file descriptor created by +.BR timerfd_create (). +The file descriptor refers to the same underlying +timer object as the corresponding file descriptor in the parent, +and +.BR read (2)s +in the child will return information about +expirations of the timer. +.\" +.SS execve(2) semantics +A file descriptor created by +.BR timerfd_create () +is preserved across +.BR execve (2), +and continues to generate timer expirations if the timer was armed. +.SH RETURN VALUE +On success, +.BR timerfd_create () +returns a new file descriptor. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.P +.BR timerfd_settime () +and +.BR timerfd_gettime () +return 0 on success; +on error they return \-1, and set +.I errno +to indicate the error. +.SH ERRORS +.BR timerfd_create () +can fail with the following errors: +.TP +.B EINVAL +The +.I clockid +is not valid. +.TP +.B EINVAL +.I flags +is invalid; +or, in Linux 2.6.26 or earlier, +.I flags +is nonzero. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been +reached. +.TP +.B ENODEV +Could not mount (internal) anonymous inode device. +.TP +.B ENOMEM +There was insufficient kernel memory to create the timer. +.TP +.B EPERM +.I clockid +was +.B CLOCK_REALTIME_ALARM +or +.B CLOCK_BOOTTIME_ALARM +but the caller did not have the +.B CAP_WAKE_ALARM +capability. +.P +.BR timerfd_settime () +and +.BR timerfd_gettime () +can fail with the following errors: +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EFAULT +.IR new_value , +.IR old_value , +or +.I curr_value +is not a valid pointer. +.TP +.B EINVAL +.I fd +is not a valid timerfd file descriptor. +.P +.BR timerfd_settime () +can also fail with the following errors: +.TP +.B ECANCELED +See NOTES. +.TP +.B EINVAL +.I new_value +is not properly initialized (one of the +.I tv_nsec +falls outside the range zero to 999,999,999). +.TP +.B EINVAL +.\" This case only checked since Linux 2.6.29, and Linux 2.2.2[78].some-stable-version. +.\" In older kernel versions, no check was made for invalid flags. +.I flags +is invalid. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.25, +glibc 2.8. +.SH NOTES +Suppose the following scenario for +.B CLOCK_REALTIME +or +.B CLOCK_REALTIME_ALARM +timer that was created with +.BR timerfd_create (): +.IP (1) 5 +The timer has been started +.RB ( timerfd_settime ()) +with the +.B TFD_TIMER_ABSTIME +and +.B TFD_TIMER_CANCEL_ON_SET +flags; +.IP (2) +A discontinuous change (e.g., +.BR settimeofday (2)) +is subsequently made to the +.B CLOCK_REALTIME +clock; and +.IP (3) +the caller once more calls +.BR timerfd_settime () +to rearm the timer (without first doing a +.BR read (2) +on the file descriptor). +.P +In this case the following occurs: +.IP \[bu] 3 +The +.BR timerfd_settime () +returns \-1 with +.I errno +set to +.BR ECANCELED . +(This enables the caller to know that the previous timer was affected +by a discontinuous change to the clock.) +.IP \[bu] +The timer +.I "is successfully rearmed" +with the settings provided in the second +.BR 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.) +.SH BUGS +Currently, +.\" 2.6.29 +.BR timerfd_create () +supports fewer types of clock IDs than +.BR timer_create (2). +.SH 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. +.P +The following shell session demonstrates the use of the program: +.P +.in +4n +.EX +.RB "$" " a.out 3 1 100" +0.000: timer started +3.000: read: 1; total=1 +4.000: read: 1; total=2 +.BR "\[ha]Z " " # type control\-Z to suspend the program" +[1]+ Stopped ./timerfd3_demo 3 1 100 +.RB "$ " "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 +.BR "\[ha]C " " # type control\-C to suspend the program" +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (timerfd_create.c) +.EX +.\" The commented out code here is what we currently need until +.\" the required stuff is in glibc +.\" +.\" +.\"/* Link with \-lrt */ +.\"#define _GNU_SOURCE +.\"#include +.\"#include +.\"#include +.\"#if defined(__i386__) +.\"#define __NR_timerfd_create 322 +.\"#define __NR_timerfd_settime 325 +.\"#define __NR_timerfd_gettime 326 +.\"#endif +.\" +.\"static int +.\"timerfd_create(int clockid, int flags) +.\"{ +.\" return syscall(__NR_timerfd_create, clockid, flags); +.\"} +.\" +.\"static int +.\"timerfd_settime(int fd, int flags, struct itimerspec *new_value, +.\" struct itimerspec *curr_value) +.\"{ +.\" return syscall(__NR_timerfd_settime, fd, flags, new_value, +.\" curr_value); +.\"} +.\" +.\"static int +.\"timerfd_gettime(int fd, struct itimerspec *curr_value) +.\"{ +.\" return syscall(__NR_timerfd_gettime, fd, curr_value); +.\"} +.\" +.\"#define TFD_TIMER_ABSTIME (1 << 0) +.\" +.\"//////////////////////////////////////////////////////////// +#include +#include +#include +#include +#include +#include +#include +#include +\& +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]\en", + 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\en"); +\& + 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 "\en", exp, tot_exp); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR eventfd (2), +.BR poll (2), +.BR read (2), +.BR select (2), +.BR setitimer (2), +.BR signalfd (2), +.BR timer_create (2), +.BR timer_gettime (2), +.BR timer_settime (2), +.BR timespec (3), +.BR epoll (7), +.BR time (7) diff --git a/man/man2/timerfd_gettime.2 b/man/man2/timerfd_gettime.2 new file mode 100644 index 0000000..6d12940 --- /dev/null +++ b/man/man2/timerfd_gettime.2 @@ -0,0 +1 @@ +.so man2/timerfd_create.2 diff --git a/man/man2/timerfd_settime.2 b/man/man2/timerfd_settime.2 new file mode 100644 index 0000000..6d12940 --- /dev/null +++ b/man/man2/timerfd_settime.2 @@ -0,0 +1 @@ +.so man2/timerfd_create.2 diff --git a/man/man2/times.2 b/man/man2/times.2 new file mode 100644 index 0000000..c2b8b09 --- /dev/null +++ b/man/man2/times.2 @@ -0,0 +1,222 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt (michael@moria.de) +.\" Modified Sat Jul 24 14:29:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 961203 and 001211 and 010326 by aeb@cwi.nl +.\" Modified 001213 by Michael Haardt (michael@moria.de) +.\" Modified 13 Jun 02, Michael Kerrisk +.\" Added note on nonstandard behavior when SIGCHLD is ignored. +.\" Modified 2004-11-16, mtk, Noted that the nonconformance when +.\" SIGCHLD is being ignored is fixed in Linux 2.6.9; other minor changes +.\" Modified 2004-12-08, mtk, in Linux 2.6 times() return value changed +.\" 2005-04-13, mtk +.\" Added notes on nonstandard behavior: Linux allows 'buf' to +.\" be NULL, but POSIX.1 doesn't specify this and it's nonportable. +.\" +.TH times 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +times \- get process times +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "clock_t times(struct tms *" buf ); +.fi +.SH DESCRIPTION +.BR times () +stores the current process times in the +.I "struct tms" +that +.I buf +points to. +The +.I struct tms +is as defined in +.IR : +.P +.in +4n +.EX +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 */ +}; +.EE +.in +.P +The +.I tms_utime +field contains the CPU time spent executing instructions +of the calling process. +The +.I tms_stime +field contains the CPU time spent executing inside the kernel +while performing tasks on behalf of the calling process. +.P +The +.I tms_cutime +field contains the sum of the +.I tms_utime +and +.I tms_cutime +values for all waited-for terminated children. +The +.I tms_cstime +field contains the sum of the +.I tms_stime +and +.I tms_cstime +values for all waited-for terminated children. +.P +Times for terminated children (and their descendants) +are added in at the moment +.BR wait (2) +or +.BR waitpid (2) +returns their process ID. +In particular, +times of grandchildren +that the children did not wait for are never seen. +.P +All times reported are in clock ticks. +.SH RETURN VALUE +.BR 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 +.IR clock_t . +On error, +\fI(clock_t)\ \-1\fP is returned, +and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I tms +points outside the process's address space. +.SH VERSIONS +On Linux, +the +.I buf +argument can be specified as NULL, +with the result that +.BR times () +just returns a function result. +However, +POSIX does not specify this behavior, +and most +other UNIX implementations require a non-NULL value for +.IR buf . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, +SVr4, +4.3BSD. +.P +In POSIX.1-1996 the symbol \fBCLK_TCK\fP (defined in +.IR ) +is mentioned as obsolescent. +It is obsolete now. +.P +Before Linux 2.6.9, +if the disposition of +.B SIGCHLD +is set to +.BR SIG_IGN , +then the times of terminated children +are automatically included in the +.I tms_cstime +and +.I tms_cutime +fields, +although POSIX.1-2001 says that this should happen +only if the calling process +.BR wait (2)s +on its children. +This nonconformance is rectified in Linux 2.6.9 and later. +.\" See the description of times() in XSH, which says: +.\" The times of a terminated child process are included... when wait() +.\" or waitpid() returns the process ID of this terminated child. +.P +On Linux, +the \[lq]arbitrary point in the past\[rq] +from which the return value of +.BR 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 \fI(2\[ha]32/HZ) \- 300\fP +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 +.IR clock_t , +means that a portable application would be wise to avoid using this value. +To measure changes in elapsed time, +use +.BR clock_gettime (2) +instead. +.\" .P +.\" On older systems the number of clock ticks per second is given +.\" by the variable HZ. +.P +SVr1-3 returns +.I long +and the struct members are of type +.I time_t +although they store clock ticks, +not seconds since the Epoch. +V7 used +.I long +for the struct members, +because it had no type +.I time_t +yet. +.SH NOTES +The number of clock ticks per second can be obtained using: +.P +.in +4n +.EX +sysconf(_SC_CLK_TCK); +.EE +.in +.P +Note that +.BR clock (3) +also returns a value of type +.IR clock_t , +but this value is measured in units of +.BR CLOCKS_PER_SEC , +not the clock ticks used by +.BR times (). +.SH 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 +.BR 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 +.BR clock_t . +.\" The problem is that a syscall return of -4095 to -1 +.\" is interpreted by glibc as an error, and the wrapper converts +.\" the return value to -1. +.\" http://marc.info/?l=linux-kernel&m=119447727031225&w=2 +.\" "compat_sys_times() bogus until jiffies >= 0" +.\" November 2007 +.SH SEE ALSO +.BR time (1), +.BR getrusage (2), +.BR wait (2), +.BR clock (3), +.BR sysconf (3), +.BR time (7) diff --git a/man/man2/tkill.2 b/man/man2/tkill.2 new file mode 100644 index 0000000..21462a7 --- /dev/null +++ b/man/man2/tkill.2 @@ -0,0 +1,130 @@ +.\" Copyright (C) 2008 Michael Kerrisk +.\" and Copyright 2003 Abhijit Menon-Sen +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2004-05-31, added tgkill, ahu, aeb +.\" 2008-01-15 mtk -- rewrote DESCRIPTION +.\" +.TH tkill 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tkill, tgkill \- send a signal to a thread +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " SIG* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include +.P +.BI "[[deprecated]] int syscall(SYS_tkill, pid_t " tid ", int " sig ); +.P +.B #include +.P +.BI "int tgkill(pid_t " tgid ", pid_t " tid ", int " sig ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR tkill (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR tgkill () +sends the signal +.I sig +to the thread with the thread ID +.I tid +in the thread group +.IR tgid . +(By contrast, +.BR kill (2) +can be used to send a signal only to a process (i.e., thread group) +as a whole, and the signal will be delivered to an arbitrary +thread within that process.) +.P +.BR tkill () +is an obsolete predecessor to +.BR tgkill (). +It allows only the target thread ID to be specified, +which may result in the wrong thread being signaled if a thread +terminates and its thread ID is recycled. +Avoid using this system call. +.\" FIXME Maybe say something about the following: +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12889 +.\" +.\" Quoting Rich Felker : +.\" +.\" There is a race condition in pthread_kill: it is possible that, +.\" between the time pthread_kill reads the pid/tid from the target +.\" thread descriptor and the time it makes the tgkill syscall, +.\" the target thread terminates and the same tid gets assigned +.\" to a new thread in the same process. +.\" +.\" (The tgkill syscall was designed to eliminate a similar race +.\" condition in tkill, but it only succeeded in eliminating races +.\" where the tid gets reused in a different process, and does not +.\" help if the same tid gets assigned to a new thread in the +.\" same process.) +.\" +.\" The only solution I can see is to introduce a mutex that ensures +.\" that a thread cannot exit while pthread_kill is being called on it. +.\" +.\" Note that in most real-world situations, like almost all race +.\" conditions, this one will be extremely rare. To make it +.\" measurable, one could exhaust all but 1-2 available pid values, +.\" possibly by lowering the max pid parameter in /proc, forcing +.\" the same tid to be reused rapidly. +.P +These are the raw system call interfaces, meant for internal +thread library use. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and \fIerrno\fP +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The +.B RLIMIT_SIGPENDING +resource limit was reached and +.I sig +is a real-time signal. +.TP +.B EAGAIN +Insufficient kernel memory was available and +.I sig +is a real-time signal. +.TP +.B EINVAL +An invalid thread ID, thread group ID, or signal was specified. +.TP +.B EPERM +Permission denied. +For the required permissions, see +.BR kill (2). +.TP +.B ESRCH +No process with the specified thread ID (and thread group ID) exists. +.SH STANDARDS +Linux. +.SH HISTORY +.TP +.BR tkill () +Linux 2.4.19 / 2.5.4. +.TP +.BR tgkill () +Linux 2.5.75, +glibc 2.30. +.SH NOTES +See the description of +.B CLONE_THREAD +in +.BR clone (2) +for an explanation of thread groups. +.SH SEE ALSO +.BR clone (2), +.BR gettid (2), +.BR kill (2), +.BR rt_sigqueueinfo (2) diff --git a/man/man2/truncate.2 b/man/man2/truncate.2 new file mode 100644 index 0000000..2b62140 --- /dev/null +++ b/man/man2/truncate.2 @@ -0,0 +1,251 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)truncate.2 6.9 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 1998-12-21 by Andries Brouwer +.\" Modified 2002-01-07 by Michael Kerrisk +.\" Modified 2002-04-06 by Andries Brouwer +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH truncate 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +truncate, ftruncate \- truncate a file to a specified length +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int truncate(const char *" path ", off_t " length ); +.BI "int ftruncate(int " fd ", off_t " length ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR truncate (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.P +.BR ftruncate (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 200112L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR truncate () +and +.BR ftruncate () +functions cause the regular file named by +.I path +or referenced by +.I fd +to be truncated to a size of precisely +.I length +bytes. +.P +If the file previously was larger than this size, the extra data is lost. +If the file previously was shorter, it is extended, and +the extended part reads as null bytes (\[aq]\e0\[aq]). +.P +The file offset is not changed. +.P +If the size changed, then the st_ctime and st_mtime fields +(respectively, time of last status change and +time of last modification; see +.BR inode (7)) +for the file are updated, +and the set-user-ID and set-group-ID mode bits may be cleared. +.P +With +.BR ftruncate (), +the file must be open for writing; with +.BR truncate (), +the file must be writable. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +For +.BR truncate (): +.TP +.B EACCES +Search permission is denied for a component of the path prefix, +or the named file is not writable by the user. +(See also +.BR path_resolution (7).) +.TP +.B EFAULT +The argument +.I path +points outside the process's allocated address space. +.TP +.B EFBIG +The argument +.I length +is larger than the maximum file size. (XSI) +.TP +.B EINTR +While blocked waiting to complete, +the call was interrupted by a signal handler; see +.BR fcntl (2) +and +.BR signal (7). +.TP +.B EINVAL +The argument +.I length +is negative or larger than the maximum file size. +.TP +.B EIO +An I/O error occurred updating the inode. +.TP +.B EISDIR +The named file is a directory. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire pathname exceeded 1023 characters. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EPERM +.\" This happens for at least MSDOS and VFAT filesystems +.\" on kernel 2.6.13 +The underlying filesystem does not support extending +a file beyond its current size. +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B EROFS +The named file resides on a read-only filesystem. +.TP +.B ETXTBSY +The file is an executable file that is being executed. +.P +For +.BR ftruncate () +the same errors apply, but instead of things that can be wrong with +.IR path , +we now have things that can be wrong with the file descriptor, +.IR fd : +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.BR EBADF " or " EINVAL +.I fd +is not open for writing. +.TP +.B EINVAL +.I fd +does not reference a regular file or a POSIX shared memory object. +.TP +.BR EINVAL " or " EBADF +The file descriptor +.I fd +is not open for writing. +POSIX permits, and portable applications should handle, +either error for this case. +(Linux produces +.BR EINVAL .) +.SH VERSIONS +The details in DESCRIPTION are for XSI-compliant systems. +For non-XSI-compliant systems, the POSIX standard allows +two behaviors for +.BR ftruncate () +when +.I length +exceeds the file length +(note that +.BR truncate () +is not specified at all in such an environment): +either returning an error, or extending the file. +Like most UNIX implementations, Linux follows the XSI requirement +when dealing with native filesystems. +However, some nonnative filesystems do not permit +.BR truncate () +and +.BR ftruncate () +to be used to extend a file beyond its current length: +a notable example on Linux is VFAT. +.\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002 +.P +On some 32-bit architectures, +the calling signature for these system calls differ, +for the reasons described in +.BR syscall (2). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, +4.4BSD, SVr4 (first appeared in 4.2BSD). +.\" POSIX.1-1996 has +.\" .BR ftruncate (). +.\" POSIX.1-2001 also has +.\" .BR truncate (), +.\" as an XSI extension. +.\" .P +.\" SVr4 documents additional +.\" .BR truncate () +.\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for +.\" .BR ftruncate () +.\" an additional EAGAIN error condition. +.P +The original Linux +.BR truncate () +and +.BR ftruncate () +system calls were not designed to handle large file offsets. +Consequently, Linux 2.4 added +.BR truncate64 () +and +.BR ftruncate64 () +system calls that handle large files. +However, these details can be ignored by applications using glibc, whose +wrapper functions transparently employ the more recent system calls +where they are available. +.SH NOTES +.BR ftruncate () +can also be used to set the size of a POSIX shared memory object; see +.BR shm_open (3). +.SH BUGS +A header file bug in glibc 2.12 meant that the minimum value of +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037 +.B _POSIX_C_SOURCE +required to expose the declaration of +.BR ftruncate () +was 200809L instead of 200112L. +This has been fixed in later glibc versions. +.SH SEE ALSO +.BR truncate (1), +.BR open (2), +.BR stat (2), +.BR path_resolution (7) diff --git a/man/man2/truncate64.2 b/man/man2/truncate64.2 new file mode 100644 index 0000000..2ed34f1 --- /dev/null +++ b/man/man2/truncate64.2 @@ -0,0 +1 @@ +.so man2/truncate.2 diff --git a/man/man2/tuxcall.2 b/man/man2/tuxcall.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/tuxcall.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/ugetrlimit.2 b/man/man2/ugetrlimit.2 new file mode 100644 index 0000000..df6d736 --- /dev/null +++ b/man/man2/ugetrlimit.2 @@ -0,0 +1 @@ +.so man2/getrlimit.2 diff --git a/man/man2/umask.2 b/man/man2/umask.2 new file mode 100644 index 0000000..77bf013 --- /dev/null +++ b/man/man2/umask.2 @@ -0,0 +1,149 @@ +.\" Copyright (c) 2006, 2008, Michael Kerrisk +.\" (A few fragments remain from an earlier (1992) version written in +.\" 1992 by Drew Eckhardt .) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified Sat Jul 24 12:51:53 1993 by Rik Faith +.\" Modified Tue Oct 22 22:39:04 1996 by Eric S. Raymond +.\" Modified Thu May 1 06:05:54 UTC 1997 by Nicolás Lichtmaier +.\" with Lars Wirzenius suggestion +.\" 2006-05-13, mtk, substantial rewrite of description of 'mask' +.\" 2008-01-09, mtk, a few rewrites and additions. +.TH umask 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +umask \- set file mode creation mask +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "mode_t umask(mode_t " mask ); +.fi +.SH DESCRIPTION +.BR umask () +sets the calling process's file mode creation mask (umask) to +.I mask +& 0777 (i.e., only the file permission bits of +.I mask +are used), and returns the previous value of the mask. +.P +The umask is used by +.BR open (2), +.BR mkdir (2), +and other system calls that create files +.\" e.g., mkfifo(), creat(), mknod(), sem_open(), mq_open(), shm_open() +.\" but NOT the System V IPC *get() calls +to modify the permissions placed on newly created files or directories. +Specifically, permissions in the umask are turned off from +the +.I mode +argument to +.BR open (2) +and +.BR mkdir (2). +.P +Alternatively, if the parent directory has a default ACL (see +.BR acl (5)), +the umask is ignored, the default ACL is inherited, +the permission bits are set based on the inherited ACL, +and permission bits absent in the +.I mode +argument are turned off. +For example, the following default ACL is equivalent to a umask of 022: +.P +.in +4n +.EX +u::rwx,g::r-x,o::r-x +.EE +.in +.P +Combining the effect of this default ACL with a +.I mode +argument of 0666 (rw-rw-rw-), the resulting file permissions would be 0644 +(rw-r--r--). +.P +The constants that should be used to specify +.I mask +are described in +.BR inode (7). +.P +The typical default value for the process umask is +.BR S_IWGRP " | " S_IWOTH +(octal 022). +In the usual case where the +.I mode +argument to +.BR open (2) +is specified as: +.P +.in +4n +.EX +.BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH +.EE +.in +.P +(octal 0666) when creating a new file, the permissions on the +resulting file will be: +.P +.in +4n +.EX +.BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IROTH +.EE +.in +.P +(because 0666 & \[ti]022 = 0644; i.e. rw\-r\-\-r\-\-). +.SH RETURN VALUE +This system call always succeeds and the previous value of the mask +is returned. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +A child process created via +.BR fork (2) +inherits its parent's umask. +The umask is left unchanged by +.BR execve (2). +.P +It is impossible to use +.BR umask () +to fetch a process's umask without at the same time changing it. +A second call to +.BR umask () +would then be needed to restore the umask. +The nonatomicity of these two steps provides the potential +for races in multithreaded programs. +.P +Since Linux 4.7, the umask of any process can be viewed via the +.I Umask +field of +.IR /proc/ pid /status . +Inspecting this field in +.I /proc/self/status +allows a process to retrieve its umask without at the same time changing it. +.P +The umask setting also affects the permissions assigned to POSIX IPC objects +.RB ( mq_open (3), +.BR sem_open (3), +.BR shm_open (3)), +FIFOs +.RB ( mkfifo (3)), +and UNIX domain sockets +.RB ( unix (7)) +created by the process. +The umask does not affect the permissions assigned +to System\ V IPC objects created by the process (using +.BR msgget (2), +.BR semget (2), +.BR shmget (2)). +.SH SEE ALSO +.BR chmod (2), +.BR mkdir (2), +.BR open (2), +.BR stat (2), +.BR acl (5) diff --git a/man/man2/umount.2 b/man/man2/umount.2 new file mode 100644 index 0000000..e7678eb --- /dev/null +++ b/man/man2/umount.2 @@ -0,0 +1,214 @@ +.\" Copyright (C) 1993 Rickard E. Faith +.\" and Copyright (C) 1994 Andries E. Brouwer +.\" and Copyright (C) 2002, 2005 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2008-10-06, mtk: Created this as a new page by splitting +.\" umount/umount2 material out of mount.2 +.\" +.TH umount 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +umount, umount2 \- unmount filesystem +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int umount(const char *" target ); +.BI "int umount2(const char *" target ", int " flags ); +.fi +.SH DESCRIPTION +.BR umount () +and +.BR umount2 () +remove the attachment of the (topmost) filesystem mounted on +.IR target . +.\" Note: the kernel naming differs from the glibc naming +.\" umount2 is the glibc name for what the kernel now calls umount +.\" and umount is the glibc name for oldumount +.P +Appropriate privilege (Linux: the +.B CAP_SYS_ADMIN +capability) is required to unmount filesystems. +.P +Linux 2.1.116 added the +.BR umount2 () +system call, which, like +.BR umount (), +unmounts a target, but allows additional +.I flags +controlling the behavior of the operation: +.TP +.BR MNT_FORCE " (since Linux 2.1.116)" +Ask the filesystem to abort pending requests before attempting the +unmount. +This may allow the unmount to complete without waiting +for an inaccessible server, but could cause data loss. +If, after aborting requests, +some processes still have active references to the filesystem, +the unmount will still fail. +As at Linux 4.12, +.B MNT_FORCE +is supported only on the following filesystems: +9p (since Linux 2.6.16), +ceph (since Linux 2.6.34), +cifs (since Linux 2.6.12), +fuse (since Linux 2.6.16), +lustre (since Linux 3.11), +and NFS (since Linux 2.1.116). +.TP +.BR MNT_DETACH " (since Linux 2.4.11)" +Perform a lazy unmount: make the mount unavailable for new +accesses, immediately disconnect the filesystem and all filesystems +mounted below it from each other and from the mount table, and +actually perform the unmount when the mount ceases to be busy. +.TP +.BR MNT_EXPIRE " (since Linux 2.6.8)" +Mark the mount as expired. +If a mount is not currently in use, then an initial call to +.BR umount2 () +with this flag fails with the error +.BR EAGAIN , +but marks the mount as expired. +The mount remains expired as long as it isn't accessed +by any process. +A second +.BR umount2 () +call specifying +.B MNT_EXPIRE +unmounts an expired mount. +This flag cannot be specified with either +.B MNT_FORCE +or +.BR MNT_DETACH . +.TP +.BR UMOUNT_NOFOLLOW " (since Linux 2.6.34)" +.\" Later added to Linux 2.6.33-stable +Don't dereference +.I target +if it is a symbolic link. +This flag allows security problems to be avoided in set-user-ID-\fIroot\fP +programs that allow unprivileged users to unmount filesystems. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +The error values given below result from filesystem type independent +errors. +Each filesystem type may have its own special errors and its +own special behavior. +See the Linux kernel source code for details. +.TP +.B EAGAIN +A call to +.BR umount2 () +specifying +.B MNT_EXPIRE +successfully marked an unbusy filesystem as expired. +.TP +.B EBUSY +.I target +could not be unmounted because it is busy. +.TP +.B EFAULT +.I target +points outside the user address space. +.TP +.B EINVAL +.I target +is not a mount point. +.TP +.B EINVAL +.I target +is locked; see +.BR mount_namespaces (7). +.TP +.B EINVAL +.BR umount2 () +was called with +.B MNT_EXPIRE +and either +.B MNT_DETACH +or +.BR MNT_FORCE . +.TP +.BR EINVAL " (since Linux 2.6.34)" +.BR umount2 () +was called with an invalid flag value in +.IR flags . +.TP +.B ENAMETOOLONG +A pathname was longer than +.BR MAXPATHLEN . +.TP +.B ENOENT +A pathname was empty or had a nonexistent component. +.TP +.B ENOMEM +The kernel could not allocate a free page to copy filenames or data into. +.TP +.B EPERM +The caller does not have the required privileges. +.SH STANDARDS +Linux. +.SH HISTORY +.B MNT_DETACH +and +.B MNT_EXPIRE +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=10092 +are available since glibc 2.11. +.P +The original +.BR umount () +function was called as \fIumount(device)\fP and would return +.B ENOTBLK +when called with something other than a block device. +In Linux 0.98p4, a call \fIumount(dir)\fP was added, in order to +support anonymous devices. +In Linux 2.3.99-pre7, the call \fIumount(device)\fP was removed, +leaving only \fIumount(dir)\fP (since now devices can be mounted +in more than one place, so specifying the device does not suffice). +.SH NOTES +.SS umount() and shared mounts +Shared mounts cause any mount activity on a mount, including +.BR umount () +operations, to be forwarded to every shared mount in the +peer group and every slave mount of that peer group. +This means that +.BR umount () +of any peer in a set of shared mounts will cause all of its +peers to be unmounted and all of their slaves to be unmounted as well. +.P +This propagation of unmount activity can be particularly surprising +on systems where every mount is shared by default. +On such systems, +recursively bind mounting the root directory of the filesystem +onto a subdirectory and then later unmounting that subdirectory with +.B MNT_DETACH +will cause every mount in the mount namespace to be lazily unmounted. +.P +To ensure +.BR umount () +does not propagate in this fashion, +the mount may be remounted using a +.BR mount (2) +call with a +.I mount_flags +argument that includes both +.B MS_REC +and +.B MS_PRIVATE +prior to +.BR umount () +being called. +.SH SEE ALSO +.BR mount (2), +.BR mount_namespaces (7), +.BR path_resolution (7), +.BR mount (8), +.BR umount (8) diff --git a/man/man2/umount2.2 b/man/man2/umount2.2 new file mode 100644 index 0000000..84ea419 --- /dev/null +++ b/man/man2/umount2.2 @@ -0,0 +1 @@ +.so man2/umount.2 diff --git a/man/man2/uname.2 b/man/man2/uname.2 new file mode 100644 index 0000000..3f7ada9 --- /dev/null +++ b/man/man2/uname.2 @@ -0,0 +1,134 @@ +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-07-05 mtk: Added details on underlying system call interfaces +.\" +.TH uname 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +uname \- get name and information about current kernel +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int uname(struct utsname *" buf ); +.fi +.SH DESCRIPTION +.BR uname () +returns system information in the structure pointed to by +.IR buf . +The +.I utsname +struct is defined in +.IR : +.P +.in +4n +.EX +struct utsname { + char sysname[]; /* Operating system name (e.g., "Linux") */ + char nodename[]; /* Name within communications network + to which the node is attached, if any */ + char release[]; /* Operating system release + (e.g., "2.6.28") */ + char version[]; /* Operating system version */ + char machine[]; /* Hardware type identifier */ +#ifdef _GNU_SOURCE + char domainname[]; /* NIS or YP domain name */ +#endif +}; +.EE +.in +.P +The length of the arrays in a +.I struct utsname +is unspecified (see NOTES); +the fields are terminated by a null byte (\[aq]\e0\[aq]). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I buf +is not valid. +.SH VERSIONS +The +.I domainname +member (the NIS or YP domain name) is a GNU extension. +.P +The length of the fields in the struct varies. +Some operating systems +or libraries use a hardcoded 9 or 33 or 65 or 257. +Other systems use +.B SYS_NMLN +or +.B _SYS_NMLN +or +.B UTSLEN +or +.BR _UTSNAME_LENGTH . +Clearly, it is a bad +idea to use any of these constants; just use sizeof(...). +SVr4 uses 257, "to support Internet hostnames" +\[em] this is the largest value likely to be encountered in the wild. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD. +.SS C library/kernel differences +Over time, increases in the size of the +.I utsname +structure have led to three successive versions of +.BR uname (): +.IR sys_olduname () +(slot +.IR __NR_oldolduname ), +.IR sys_uname () +(slot +.IR __NR_olduname ), +and +.IR sys_newuname () +(slot +.IR __NR_uname) . +The first one +.\" That was back before Linux 1.0 +used length 9 for all fields; +the second +.\" That was also back before Linux 1.0 +used 65; +the third also uses 65 but adds the +.I domainname +field. +The glibc +.BR uname () +wrapper function hides these details from applications, +invoking the most recent version of the system call provided by the kernel. +.SH NOTES +The kernel has the name, release, version, and supported machine type built in. +Conversely, the +.I nodename +field is configured by the administrator to match the network +(this is what the BSD historically calls the "hostname", +and is set via +.BR sethostname (2)). +Similarly, the +.I domainname +field is set via +.BR setdomainname (2). +.P +Part of the utsname information is also accessible via +.IR /proc/sys/kernel/ { ostype , +.IR hostname , +.IR osrelease , +.IR version , +.IR domainname }. +.SH SEE ALSO +.BR uname (1), +.BR getdomainname (2), +.BR gethostname (2), +.BR uts_namespaces (7) diff --git a/man/man2/unimplemented.2 b/man/man2/unimplemented.2 new file mode 100644 index 0000000..71645a9 --- /dev/null +++ b/man/man2/unimplemented.2 @@ -0,0 +1,48 @@ +.\" Copyright 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Updated, aeb, 980612 +.\" +.TH UNIMPLEMENTED 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +afs_syscall, break, fattach, fdetach, ftime, getmsg, getpmsg, gtty, isastream, +lock, madvise1, mpx, prof, profil, putmsg, putpmsg, security, +stty, tuxcall, ulimit, vserver \- unimplemented system calls +.SH SYNOPSIS +.nf +Unimplemented system calls. +.fi +.SH DESCRIPTION +These system calls are not implemented in the Linux kernel. +.SH RETURN VALUE +These system calls always return \-1 and set +.I errno +to +.BR ENOSYS . +.SH NOTES +Note that +.BR ftime (3), +.BR profil (3), +and +.BR ulimit (3) +are implemented as library functions. +.P +Some system calls, like +.BR alloc_hugepages (2), +.BR free_hugepages (2), +.BR ioperm (2), +.BR iopl (2), +and +.BR vm86 (2) +exist only on certain architectures. +.P +Some system calls, like +.BR ipc (2), +.BR create_module (2), +.BR init_module (2), +and +.BR delete_module (2) +exist only when the Linux kernel was built with support for them. +.SH SEE ALSO +.BR syscalls (2) diff --git a/man/man2/unlink.2 b/man/man2/unlink.2 new file mode 100644 index 0000000..311cac7 --- /dev/null +++ b/man/man2/unlink.2 @@ -0,0 +1,298 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Ian Jackson +.\" and Copyright (C) 2006, 2014 Michael Kerrisk. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-09-08 by Arnt Gulbrandsen +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2001-05-17 by aeb +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH unlink 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +unlink, unlinkat \- delete a name and possibly the file it refers to +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int unlink(const char *" pathname ); +.P +.BR "#include " "/* Definition of " AT_* " constants */" +.B #include +.P +.BI "int unlinkat(int " dirfd ", const char *" pathname ", int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR unlinkat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +.BR unlink () +deletes a name from the filesystem. +If that name was the +last link to a file and no processes have the file open, the file is +deleted and the space it was using is made available for reuse. +.P +If the name was the last link to a file but any processes still have +the file open, the file will remain in existence until the last file +descriptor referring to it is closed. +.P +If the name referred to a symbolic link, the link is removed. +.P +If the name referred to a socket, FIFO, or device, the name for it is +removed but processes which have the object open may continue to use +it. +.SS unlinkat() +The +.BR unlinkat () +system call operates in exactly the same way as either +.BR unlink () +or +.BR rmdir (2) +(depending on whether or not +.I flags +includes the +.B AT_REMOVEDIR +flag) +except for the differences described here. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR unlink () +and +.BR rmdir (2) +for a relative pathname). +.P +If the pathname given in +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR unlink () +and +.BR rmdir (2)). +.P +If the pathname given in +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +.I flags +is a bit mask that can either be specified as 0, or by ORing +together flag values that control the operation of +.BR unlinkat (). +Currently, only one such flag is defined: +.TP +.B AT_REMOVEDIR +By default, +.BR unlinkat () +performs the equivalent of +.BR unlink () +on +.IR pathname . +If the +.B AT_REMOVEDIR +flag is specified, it +performs the equivalent of +.BR rmdir (2) +on +.IR pathname . +.P +See +.BR openat (2) +for an explanation of the need for +.BR unlinkat (). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Write access to the directory containing +.I pathname +is not allowed for the process's effective UID, or one of the +directories in +.I pathname +did not allow search permission. +(See also +.BR path_resolution (7).) +.TP +.B EBUSY +The file +.I pathname +cannot be unlinked because it is being used by the system +or another process; +for example, it is a mount point +or the NFS client software created it to represent an +active but otherwise nameless inode ("NFS silly renamed"). +.TP +.B EFAULT +.I pathname +points outside your accessible address space. +.TP +.B EIO +An I/O error occurred. +.TP +.B EISDIR +.I pathname +refers to a directory. +(This is the non-POSIX value returned since Linux 2.1.132.) +.TP +.B ELOOP +Too many symbolic links were encountered in translating +.IR pathname . +.TP +.B ENAMETOOLONG +.IR pathname " was too long." +.TP +.B ENOENT +A component in +.I pathname +does not exist or is a dangling symbolic link, or +.I pathname +is empty. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component used as a directory in +.I pathname +is not, in fact, a directory. +.TP +.B EPERM +The system does not allow unlinking of directories, +or unlinking of directories requires privileges that the +calling process doesn't have. +(This is the POSIX prescribed error return; +as noted above, Linux returns +.B EISDIR +for this case.) +.TP +.BR EPERM " (Linux only)" +The filesystem does not allow unlinking of files. +.TP +.BR EPERM " or " EACCES +The directory containing +.I pathname +has the sticky bit +.RB ( S_ISVTX ) +set and the process's effective UID is neither the UID of the file to +be deleted nor that of the directory containing it, and +the process is not privileged (Linux: does not have the +.B CAP_FOWNER +capability). +.TP +.B EPERM +The file to be unlinked is marked immutable or append-only. +(See +.BR ioctl_iflags (2).) +.TP +.B EROFS +.I pathname +refers to a file on a read-only filesystem. +.P +The same errors that occur for +.BR unlink () +and +.BR rmdir (2) +can also occur for +.BR unlinkat (). +The following additional errors can occur for +.BR unlinkat (): +.TP +.B EBADF +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EINVAL +An invalid flag value was specified in +.IR flags . +.TP +.B EISDIR +.I pathname +refers to a directory, and +.B AT_REMOVEDIR +was not specified in +.IR flags . +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR unlink () +SVr4, 4.3BSD, POSIX.1-2001. +.\" SVr4 documents additional error +.\" conditions EINTR, EMULTIHOP, ETXTBSY, ENOLINK. +.TP +.BR unlinkat () +POSIX.1-2008. +Linux 2.6.16, +glibc 2.4. +.SS glibc +On older kernels where +.BR unlinkat () +is unavailable, the glibc wrapper function falls back to the use of +.BR unlink () +or +.BR rmdir (2). +When +.I pathname +is a relative pathname, +glibc constructs a pathname based on the symbolic link in +.I /proc/self/fd +that corresponds to the +.I dirfd +argument. +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of files which are still being used. +.SH SEE ALSO +.BR rm (1), +.BR unlink (1), +.BR chmod (2), +.BR link (2), +.BR mknod (2), +.BR open (2), +.BR rename (2), +.BR rmdir (2), +.BR mkfifo (3), +.BR remove (3), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/unlinkat.2 b/man/man2/unlinkat.2 new file mode 100644 index 0000000..4921f73 --- /dev/null +++ b/man/man2/unlinkat.2 @@ -0,0 +1 @@ +.so man2/unlink.2 diff --git a/man/man2/unshare.2 b/man/man2/unshare.2 new file mode 100644 index 0000000..ed143f1 --- /dev/null +++ b/man/man2/unshare.2 @@ -0,0 +1,572 @@ +.\" Copyright (C) 2006, Janak Desai +.\" and Copyright (C) 2006, 2012 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Patch Justification: +.\" unshare system call is needed to implement, using PAM, +.\" per-security_context and/or per-user namespace to provide +.\" polyinstantiated directories. Using unshare and bind mounts, a +.\" PAM module can create private namespace with appropriate +.\" directories(based on user's security context) bind mounted on +.\" public directories such as /tmp, thus providing an instance of +.\" /tmp that is based on user's security context. Without the +.\" unshare system call, namespace separation can only be achieved +.\" by clone, which would require porting and maintaining all commands +.\" such as login, and su, that establish a user session. +.\" +.TH unshare 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +unshare \- disassociate parts of the process execution context +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.P +.BI "int unshare(int " flags ); +.fi +.SH DESCRIPTION +.BR unshare () +allows a process (or thread) to disassociate parts of its execution +context that are currently being shared with other processes (or threads). +Part of the execution context, such as the mount namespace, is shared +implicitly when a new process is created using +.BR fork (2) +or +.BR vfork (2), +while other parts, such as virtual memory, may be +shared by explicit request when creating a process or thread using +.BR clone (2). +.P +The main use of +.BR unshare () +is to allow a process to control its +shared execution context without creating a new process. +.P +The +.I flags +argument is a bit mask that specifies which parts of +the execution context should be unshared. +This argument is specified by ORing together zero or more +of the following constants: +.TP +.B CLONE_FILES +Reverse the effect of the +.BR clone (2) +.B CLONE_FILES +flag. +Unshare the file descriptor table, so that the calling process +no longer shares its file descriptors with any other process. +.TP +.B CLONE_FS +Reverse the effect of the +.BR clone (2) +.B CLONE_FS +flag. +Unshare filesystem attributes, so that the calling process +no longer shares its root directory +.RB ( chroot (2)), +current directory +.RB ( chdir (2)), +or umask +.RB ( umask (2)) +attributes with any other process. +.TP +.BR CLONE_NEWCGROUP " (since Linux 4.6)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWCGROUP +flag. +Unshare the cgroup namespace. +Use of +.B CLONE_NEWCGROUP +requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR CLONE_NEWIPC " (since Linux 2.6.19)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWIPC +flag. +Unshare the IPC namespace, +so that the calling process has a private copy of the +IPC namespace which is not shared with any other process. +Specifying this flag automatically implies +.B CLONE_SYSVSEM +as well. +Use of +.B CLONE_NEWIPC +requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR CLONE_NEWNET " (since Linux 2.6.24)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWNET +flag. +Unshare the network namespace, +so that the calling process is moved into a +new network namespace which is not shared +with any previously existing process. +Use of +.B CLONE_NEWNET +requires the +.B CAP_SYS_ADMIN +capability. +.TP +.B CLONE_NEWNS +.\" These flag name are inconsistent: +.\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM, +.\" CLONE_FS, and CLONE_FILES reverse the action of the clone() +.\" flags of the same name. +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWNS +flag. +Unshare the mount namespace, +so that the calling process has a private copy of +its namespace which is not shared with any other process. +Specifying this flag automatically implies +.B CLONE_FS +as well. +Use of +.B CLONE_NEWNS +requires the +.B CAP_SYS_ADMIN +capability. +For further information, see +.BR mount_namespaces (7). +.TP +.BR CLONE_NEWPID " (since Linux 3.8)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWPID +flag. +Unshare the PID namespace, +so that the calling process has a new PID namespace for its children +which is not shared with any previously existing process. +The calling process is +.I not +moved into the new namespace. +The first child created by the calling process will have +the process ID 1 and will assume the role of +.BR init (1) +in the new namespace. +.B CLONE_NEWPID +automatically implies +.B CLONE_THREAD +as well. +Use of +.B CLONE_NEWPID +requires the +.B CAP_SYS_ADMIN +capability. +For further information, see +.BR pid_namespaces (7). +.TP +.BR CLONE_NEWTIME " (since Linux 5.6)" +Unshare the time namespace, +so that the calling process has a new time namespace for its children +which is not shared with any previously existing process. +The calling process is +.I not +moved into the new namespace. +Use of +.B CLONE_NEWTIME +requires the +.B CAP_SYS_ADMIN +capability. +For further information, see +.BR time_namespaces (7). +.TP +.BR CLONE_NEWUSER " (since Linux 3.8)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWUSER +flag. +Unshare the user namespace, +so that the calling process is moved into a new user namespace +which is not shared with any previously existing process. +As with the child process created by +.BR clone (2) +with the +.B CLONE_NEWUSER +flag, the caller obtains a full set of capabilities in the new namespace. +.IP +.B CLONE_NEWUSER +requires that the calling process is not threaded; specifying +.B CLONE_NEWUSER +automatically implies +.BR CLONE_THREAD . +Since Linux 3.9, +.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 +.\" https://lwn.net/Articles/543273/ +.B CLONE_NEWUSER +also automatically implies +.BR CLONE_FS . +.B CLONE_NEWUSER +requires that the user ID and group ID +of the calling process are mapped to user IDs and group IDs in the +user namespace of the calling process at the time of the call. +.IP +For further information on user namespaces, see +.BR user_namespaces (7). +.TP +.BR CLONE_NEWUTS " (since Linux 2.6.19)" +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWUTS +flag. +Unshare the UTS IPC namespace, +so that the calling process has a private copy of the +UTS namespace which is not shared with any other process. +Use of +.B CLONE_NEWUTS +requires the +.B CAP_SYS_ADMIN +capability. +.TP +.BR CLONE_SYSVSEM " (since Linux 2.6.26)" +.\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7 +This flag reverses the effect of the +.BR clone (2) +.B CLONE_SYSVSEM +flag. +Unshare System\ V semaphore adjustment +.RI ( semadj ) +values, +so that the calling process has a new empty +.I semadj +list that is not shared with any other process. +If this is the last process that has a reference to the process's current +.I semadj +list, then the adjustments in that list are applied +to the corresponding semaphores, as described in +.BR semop (2). +.\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared +.\" (i.e., current->signal->count > 1), force CLONE_THREAD. +.P +In addition, +.BR CLONE_THREAD , +.BR CLONE_SIGHAND , +and +.B CLONE_VM +can be specified in +.I flags +if the caller is single threaded (i.e., it is not sharing +its address space with another process or thread). +In this case, these flags have no effect. +(Note also that specifying +.B CLONE_THREAD +automatically implies +.BR CLONE_VM , +and specifying +.B CLONE_VM +automatically implies +.BR CLONE_SIGHAND .) +.\" As at 3.9, the following forced implications also apply, +.\" although the relevant flags are not yet implemented. +.\" If CLONE_THREAD is set force CLONE_VM. +.\" If CLONE_VM is set, force CLONE_SIGHAND. +.\" +If the process is multithreaded, then +the use of these flags results in an error. +.\" See kernel/fork.c::check_unshare_flags() +.P +If +.I flags +is specified as zero, then +.BR unshare () +is a no-op; +no changes are made to the calling process's execution context. +.SH RETURN VALUE +On success, zero returned. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +An invalid bit was specified in +.IR flags . +.TP +.B EINVAL +.BR CLONE_THREAD , +.BR CLONE_SIGHAND , +or +.B CLONE_VM +was specified in +.IR flags , +and the caller is multithreaded. +.TP +.B EINVAL +.B CLONE_NEWIPC +was specified in +.IR flags , +but the kernel was not configured with the +.B CONFIG_SYSVIPC +and +.B CONFIG_IPC_NS +options. +.TP +.B EINVAL +.B CLONE_NEWNET +was specified in +.IR flags , +but the kernel was not configured with the +.B CONFIG_NET_NS +option. +.TP +.B EINVAL +.B CLONE_NEWPID +was specified in +.IR flags , +but the kernel was not configured with the +.B CONFIG_PID_NS +option. +.TP +.B EINVAL +.B CLONE_NEWUSER +was specified in +.IR flags , +but the kernel was not configured with the +.B CONFIG_USER_NS +option. +.TP +.B EINVAL +.B CLONE_NEWUTS +was specified in +.IR flags , +but the kernel was not configured with the +.B CONFIG_UTS_NS +option. +.TP +.B EINVAL +.B CLONE_NEWPID +was specified in +.IR flags , +but the process has previously called +.BR unshare () +with the +.B CLONE_NEWPID +flag. +.TP +.B ENOMEM +Cannot allocate sufficient memory to copy parts of caller's +context that need to be unshared. +.TP +.BR ENOSPC " (since Linux 3.7)" +.\" commit f2302505775fd13ba93f034206f1e2a587017929 +.B CLONE_NEWPID +was specified in flags, +but the limit on the nesting depth of PID namespaces +would have been exceeded; see +.BR pid_namespaces (7). +.TP +.BR ENOSPC " (since Linux 4.9; beforehand " EUSERS ) +.B CLONE_NEWUSER +was specified in +.IR flags , +and the call would cause the limit on the number of +nested user namespaces to be exceeded. +See +.BR user_namespaces (7). +.IP +From Linux 3.11 to Linux 4.8, the error diagnosed in this case was +.BR EUSERS . +.TP +.BR ENOSPC " (since Linux 4.9)" +One of the values in +.I flags +specified the creation of a new user namespace, +but doing so would have caused the limit defined by the corresponding file in +.I /proc/sys/user +to be exceeded. +For further details, see +.BR namespaces (7). +.TP +.B EPERM +The calling process did not have the required privileges for this operation. +.TP +.B EPERM +.B CLONE_NEWUSER +was specified in +.IR flags , +but either the effective user ID or the effective group ID of the caller +does not have a mapping in the parent namespace (see +.BR user_namespaces (7)). +.TP +.BR EPERM " (since Linux 3.9)" +.\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d +.B CLONE_NEWUSER +was specified in +.I flags +and the caller is in a chroot environment +.\" FIXME What is the rationale for this restriction? +(i.e., the caller's root directory does not match the root directory +of the mount namespace in which it resides). +.TP +.BR EUSERS " (from Linux 3.11 to Linux 4.8)" +.B CLONE_NEWUSER +was specified in +.IR flags , +and the limit on the number of nested user namespaces would be exceeded. +See the discussion of the +.B ENOSPC +error above. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.16. +.SH NOTES +Not all of the process attributes that can be shared when +a new process is created using +.BR clone (2) +can be unshared using +.BR unshare (). +In particular, as at kernel 3.8, +.\" FIXME all of the following needs to be reviewed for the current kernel +.BR unshare () +does not implement flags that reverse the effects of +.BR CLONE_SIGHAND , +.\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND +.\" was not specified when doing clone(); i.e., unsharing +.\" signal handlers is permitted if we are not actually +.\" sharing signal handlers. mtk +.BR CLONE_THREAD , +or +.BR CLONE_VM . +.\" However, we can do unshare(CLONE_VM) if CLONE_VM +.\" was not specified when doing clone(); i.e., unsharing +.\" virtual memory is permitted if we are not actually +.\" sharing virtual memory. mtk +Such functionality may be added in the future, if required. +.\" +.\"9) Future Work +.\"-------------- +.\"The current implementation of unshare does not allow unsharing of +.\"signals and signal handlers. Signals are complex to begin with and +.\"to unshare signals and/or signal handlers of a currently running +.\"process is even more complex. If in the future there is a specific +.\"need to allow unsharing of signals and/or signal handlers, it can +.\"be incrementally added to unshare without affecting legacy +.\"applications using unshare. +.\" +.P +Creating all kinds of namespace, except user namespaces, requires the +.B CAP_SYS_ADMIN +capability. +However, since creating a user namespace automatically confers a full set of +capabilities, +creating both a user namespace and any other type of namespace in the same +.BR unshare () +call does not require the +.B CAP_SYS_ADMIN +capability in the original namespace. +.SH EXAMPLES +The program below provides a simple implementation of the +.BR unshare (1) +command, which unshares one or more namespaces and executes the +command supplied in its command-line arguments. +Here's an example of the use of this program, +running a shell in a new mount namespace, +and verifying that the original shell and the +new shell are in separate mount namespaces: +.P +.in +4n +.EX +$ \fBreadlink /proc/$$/ns/mnt\fP +mnt:[4026531840] +$ \fBsudo ./unshare \-m /bin/bash\fP +# \fBreadlink /proc/$$/ns/mnt\fP +mnt:[4026532325] +.EE +.in +.P +The differing output of the two +.BR readlink (1) +commands shows that the two shells are in different mount namespaces. +.SS Program source +\& +.\" SRC BEGIN (unshare.c) +.EX +/* unshare.c +\& + A simple implementation of the unshare(1) command: unshare + namespaces and execute a command. +*/ +#define _GNU_SOURCE +#include +#include +#include +#include +#include +\& +static void +usage(char *pname) +{ + fprintf(stderr, "Usage: %s [options] program [arg...]\en", pname); + fprintf(stderr, "Options can be:\en"); + fprintf(stderr, " \-C unshare cgroup namespace\en"); + fprintf(stderr, " \-i unshare IPC namespace\en"); + fprintf(stderr, " \-m unshare mount namespace\en"); + fprintf(stderr, " \-n unshare network namespace\en"); + fprintf(stderr, " \-p unshare PID namespace\en"); + fprintf(stderr, " \-t unshare time namespace\en"); + fprintf(stderr, " \-u unshare UTS namespace\en"); + fprintf(stderr, " \-U unshare user namespace\en"); + exit(EXIT_FAILURE); +} +\& +int +main(int argc, char *argv[]) +{ + int flags, opt; +\& + flags = 0; +\& + while ((opt = getopt(argc, argv, "CimnptuU")) != \-1) { + switch (opt) { + case \[aq]C\[aq]: flags |= CLONE_NEWCGROUP; break; + case \[aq]i\[aq]: flags |= CLONE_NEWIPC; break; + case \[aq]m\[aq]: flags |= CLONE_NEWNS; break; + case \[aq]n\[aq]: flags |= CLONE_NEWNET; break; + case \[aq]p\[aq]: flags |= CLONE_NEWPID; break; + case \[aq]t\[aq]: flags |= CLONE_NEWTIME; break; + case \[aq]u\[aq]: flags |= CLONE_NEWUTS; break; + case \[aq]U\[aq]: flags |= CLONE_NEWUSER; break; + default: usage(argv[0]); + } + } +\& + if (optind >= argc) + usage(argv[0]); +\& + if (unshare(flags) == \-1) + err(EXIT_FAILURE, "unshare"); +\& + execvp(argv[optind], &argv[optind]); + err(EXIT_FAILURE, "execvp"); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR unshare (1), +.BR clone (2), +.BR fork (2), +.BR kcmp (2), +.BR setns (2), +.BR vfork (2), +.BR namespaces (7) +.P +.I Documentation/userspace\-api/unshare.rst +in the Linux kernel source tree +.\" commit f504d47be5e8fa7ecf2bf660b18b42e6960c0eb2 +(or +.I Documentation/unshare.txt +before Linux 4.12) diff --git a/man/man2/uselib.2 b/man/man2/uselib.2 new file mode 100644 index 0000000..d786008 --- /dev/null +++ b/man/man2/uselib.2 @@ -0,0 +1,106 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1996-10-22 by Eric S. Raymond +.\" Modified 2004-06-23 by Michael Kerrisk +.\" Modified 2005-01-09 by aeb +.\" +.TH uselib 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +uselib \- load shared library +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int uselib(const char *" library ); +.fi +.SH DESCRIPTION +The system call +.BR uselib () +serves to load +a shared library to be used by the calling process. +It is given a pathname. +The address where to load is found +in the library itself. +The library can have any recognized +binary format. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +In addition to all of the error codes returned by +.BR open (2) +and +.BR mmap (2), +the following may also be returned: +.TP +.B EACCES +The library specified by +.I library +does not have read or execute permission, or the caller does not have +search permission for one of the directories in the path prefix. +(See also +.BR path_resolution (7).) +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOEXEC +The file specified by +.I library +is not an executable of a known type; +for example, it does not have the correct magic numbers. +.SH STANDARDS +Linux. +.SH HISTORY +This obsolete system call is not supported by glibc. +No declaration is provided in glibc headers, but, through a quirk of history, +glibc before glibc 2.23 did export an ABI for this system call. +Therefore, in order to employ this system call, +it was sufficient to manually declare the interface in your code; +alternatively, you could invoke the system call using +.BR syscall (2). +.P +In ancient libc versions (before glibc 2.0), +.BR uselib () +was used to load +the shared libraries with names found in an array of names +in the binary. +.\" .P +.\" .\" libc 4.3.1f - changelog 1993-03-02 +.\" Since libc 4.3.2, startup code tries to prefix these names +.\" with "/usr/lib", "/lib" and "" before giving up. +.\" .\" libc 4.3.4 - changelog 1993-04-21 +.\" In libc 4.3.4 and later these names are looked for in the directories +.\" found in +.\" .BR LD_LIBRARY_PATH , +.\" and if not found there, +.\" prefixes "/usr/lib", "/lib" and "/" are tried. +.\" .P +.\" From libc 4.4.4 on only the library "/lib/ld.so" is loaded, +.\" so that this dynamic library can load the remaining libraries needed +.\" (again using this call). +.\" This is also the state of affairs in libc5. +.\" .P +.\" glibc2 does not use this call. +.P +Since Linux 3.15, +.\" commit 69369a7003735d0d8ef22097e27a55a8bad9557a +this system call is available only when the kernel is configured with the +.B CONFIG_USELIB +option. +.SH SEE ALSO +.BR ar (1), +.BR gcc (1), +.BR ld (1), +.BR ldd (1), +.BR mmap (2), +.BR open (2), +.BR dlopen (3), +.BR capabilities (7), +.BR ld.so (8) diff --git a/man/man2/userfaultfd.2 b/man/man2/userfaultfd.2 new file mode 100644 index 0000000..206a8ad --- /dev/null +++ b/man/man2/userfaultfd.2 @@ -0,0 +1,951 @@ +.\" Copyright (c) 2016, IBM Corporation. +.\" Written by Mike Rapoport +.\" and Copyright (C) 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH userfaultfd 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +userfaultfd \- create a file descriptor for handling page faults in user space +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " O_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.BR "#include " " /* Definition of " UFFD_* " constants */" +.B #include +.P +.BI "int syscall(SYS_userfaultfd, int " flags ); +.fi +.P +.IR Note : +glibc provides no wrapper for +.BR userfaultfd (), +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +.BR userfaultfd () +creates a new userfaultfd object that can be used for delegation of page-fault +handling to a user-space application, +and returns a file descriptor that refers to the new object. +The new userfaultfd object is configured using +.BR ioctl (2). +.P +Once the userfaultfd object is configured, the application can use +.BR read (2) +to receive userfaultfd notifications. +The reads from userfaultfd may be blocking or non-blocking, +depending on the value of +.I flags +used for the creation of the userfaultfd or subsequent calls to +.BR fcntl (2). +.P +The following values may be bitwise ORed in +.I flags +to change the behavior of +.BR userfaultfd (): +.TP +.B O_CLOEXEC +Enable the close-on-exec flag for the new userfaultfd file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2). +.TP +.B O_NONBLOCK +Enables non-blocking operation for the userfaultfd object. +See the description of the +.B O_NONBLOCK +flag in +.BR open (2). +.TP +.B UFFD_USER_MODE_ONLY +This is an userfaultfd-specific flag that was introduced in Linux 5.11. +When set, the userfaultfd object will only be able to handle +page faults originated from the user space on the registered regions. +When a kernel-originated fault was triggered +on the registered range with this userfaultfd, a +.B SIGBUS +signal will be delivered. +.P +When the last file descriptor referring to a userfaultfd object is closed, +all memory ranges that were registered with the object are unregistered +and unread events are flushed. +.\" +.P +Userfaultfd supports three modes of registration: +.TP +.BR UFFDIO_REGISTER_MODE_MISSING " (since Linux 4.10)" +When registered with +.B UFFDIO_REGISTER_MODE_MISSING +mode, user-space will receive a page-fault notification +when a missing page is accessed. +The faulted thread will be stopped from execution until the page fault is +resolved from user-space by either an +.B UFFDIO_COPY +or an +.B UFFDIO_ZEROPAGE +ioctl. +.TP +.BR UFFDIO_REGISTER_MODE_MINOR " (since Linux 5.13)" +When registered with +.B UFFDIO_REGISTER_MODE_MINOR +mode, user-space will receive a page-fault notification +when a minor page fault occurs. +That is, +when a backing page is in the page cache, +but page table entries don't yet exist. +The faulted thread will be stopped from execution +until the page fault is resolved from user-space by an +.B UFFDIO_CONTINUE +ioctl. +.TP +.BR UFFDIO_REGISTER_MODE_WP " (since Linux 5.7)" +When registered with +.B UFFDIO_REGISTER_MODE_WP +mode, user-space will receive a page-fault notification +when a write-protected page is written. +The faulted thread will be stopped from execution +until user-space write-unprotects the page using an +.B UFFDIO_WRITEPROTECT +ioctl. +.P +Multiple modes can be enabled at the same time for the same memory range. +.P +Since Linux 4.14, a userfaultfd page-fault notification can selectively embed +faulting thread ID information into the notification. +One needs to enable this feature explicitly using the +.B UFFD_FEATURE_THREAD_ID +feature bit when initializing the userfaultfd context. +By default, thread ID reporting is disabled. +.SS Usage +The userfaultfd mechanism is designed to allow a thread in a multithreaded +program to perform user-space paging for the other threads in the process. +When a page fault occurs for one of the regions registered +to the userfaultfd object, +the faulting thread is put to sleep and +an event is generated that can be read via the userfaultfd file descriptor. +The fault-handling thread reads events from this file descriptor and services +them using the operations described in +.BR ioctl_userfaultfd (2). +When servicing the page fault events, +the fault-handling thread can trigger a wake-up for the sleeping thread. +.P +It is possible for the faulting threads and the fault-handling threads +to run in the context of different processes. +In this case, these threads may belong to different programs, +and the program that executes the faulting threads +will not necessarily cooperate with the program that handles the page faults. +In such non-cooperative mode, +the process that monitors userfaultfd and handles page faults +needs to be aware of the changes in the virtual memory layout +of the faulting process to avoid memory corruption. +.P +Since Linux 4.11, +userfaultfd can also notify the fault-handling threads about changes +in the virtual memory layout of the faulting process. +In addition, if the faulting process invokes +.BR fork (2), +the userfaultfd objects associated with the parent may be duplicated +into the child process and the userfaultfd monitor will be notified +(via the +.B UFFD_EVENT_FORK +described below) +about the file descriptor associated with the userfault objects +created for the child process, +which allows the userfaultfd monitor to perform user-space paging +for the child process. +Unlike page faults which have to be synchronous and require an +explicit or implicit wakeup, +all other events are delivered asynchronously and +the non-cooperative process resumes execution as +soon as the userfaultfd manager executes +.BR read (2). +The userfaultfd manager should carefully synchronize calls to +.B UFFDIO_COPY +with the processing of events. +.P +The current asynchronous model of the event delivery is optimal for +single threaded non-cooperative userfaultfd manager implementations. +.\" Regarding the preceding sentence, Mike Rapoport says: +.\" The major point here is that current events delivery model could be +.\" problematic for multi-threaded monitor. I even suspect that it would be +.\" impossible to ensure synchronization between page faults and non-page +.\" fault events in multi-threaded monitor. +.\" .P +.\" FIXME elaborate about non-cooperating mode, describe its limitations +.\" for kernels before Linux 4.11, features added in Linux 4.11 +.\" and limitations remaining in Linux 4.11 +.\" Maybe it's worth adding a dedicated sub-section... +.\" +.P +Since Linux 5.7, userfaultfd is able to do +synchronous page dirty tracking using the new write-protect register mode. +One should check against the feature bit +.B UFFD_FEATURE_PAGEFAULT_FLAG_WP +before using this feature. +Similar to the original userfaultfd missing mode, the write-protect mode will +generate a userfaultfd notification when the protected page is written. +The user needs to resolve the page fault by unprotecting the faulted page and +kicking the faulted thread to continue. +For more information, +please refer to the "Userfaultfd write-protect mode" section. +.\" +.SS Userfaultfd operation +After the userfaultfd object is created with +.BR userfaultfd (), +the application must enable it using the +.B UFFDIO_API +.BR ioctl (2) +operation. +This operation allows a two-step handshake between the kernel and user space +to determine what API version and features the kernel supports, +and then to enable those features user space wants. +This operation must be performed before any of the other +.BR ioctl (2) +operations described below (or those operations fail with the +.B EINVAL +error). +.P +After a successful +.B UFFDIO_API +operation, +the application then registers memory address ranges using the +.B UFFDIO_REGISTER +.BR ioctl (2) +operation. +After successful completion of a +.B UFFDIO_REGISTER +operation, +a page fault occurring in the requested memory range, and satisfying +the mode defined at the registration time, will be forwarded by the kernel to +the user-space application. +The application can then use various (e.g., +.BR UFFDIO_COPY , +.BR UFFDIO_ZEROPAGE , +or +.BR UFFDIO_CONTINUE ) +.BR ioctl (2) +operations to resolve the page fault. +.P +Since Linux 4.14, if the application sets the +.B UFFD_FEATURE_SIGBUS +feature bit using the +.B UFFDIO_API +.BR ioctl (2), +no page-fault notification will be forwarded to user space. +Instead a +.B SIGBUS +signal is delivered to the faulting process. +With this feature, +userfaultfd can be used for robustness purposes to simply catch +any access to areas within the registered address range that do not +have pages allocated, without having to listen to userfaultfd events. +No userfaultfd monitor will be required for dealing with such memory +accesses. +For example, this feature can be useful for applications that +want to prevent the kernel from automatically allocating pages and filling +holes in sparse files when the hole is accessed through a memory mapping. +.P +The +.B UFFD_FEATURE_SIGBUS +feature is implicitly inherited through +.BR fork (2) +if used in combination with +.BR UFFD_FEATURE_FORK . +.P +Details of the various +.BR ioctl (2) +operations can be found in +.BR ioctl_userfaultfd (2). +.P +Since Linux 4.11, events other than page-fault may enabled during +.B UFFDIO_API +operation. +.P +Up to Linux 4.11, +userfaultfd can be used only with anonymous private memory mappings. +Since Linux 4.11, +userfaultfd can be also used with hugetlbfs and shared memory mappings. +.\" +.SS Userfaultfd write-protect mode (since Linux 5.7) +Since Linux 5.7, userfaultfd supports write-protect mode for anonymous memory. +The user needs to first check availability of this feature using +.B UFFDIO_API +ioctl against the feature bit +.B UFFD_FEATURE_PAGEFAULT_FLAG_WP +before using this feature. +.P +Since Linux 5.19, +the write-protection mode was also supported on +shmem and hugetlbfs memory types. +It can be detected with the feature bit +.BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM . +.P +To register with userfaultfd write-protect mode, the user needs to initiate the +.B UFFDIO_REGISTER +ioctl with mode +.B UFFDIO_REGISTER_MODE_WP +set. +Note that it is legal to monitor the same memory range with multiple modes. +For example, the user can do +.B UFFDIO_REGISTER +with the mode set to +.BR "UFFDIO_REGISTER_MODE_MISSING | UFFDIO_REGISTER_MODE_WP" . +When there is only +.B UFFDIO_REGISTER_MODE_WP +registered, user-space will +.I not +receive any notification when a missing page is written. +Instead, user-space will receive a write-protect page-fault notification +only when an existing but write-protected page got written. +.P +After the +.B UFFDIO_REGISTER +ioctl completed with +.B UFFDIO_REGISTER_MODE_WP +mode set, +the user can write-protect any existing memory within the range using the ioctl +.B UFFDIO_WRITEPROTECT +where +.I uffdio_writeprotect.mode +should be set to +.BR UFFDIO_WRITEPROTECT_MODE_WP . +.P +When a write-protect event happens, +user-space will receive a page-fault notification whose +.I uffd_msg.pagefault.flags +will be with +.B UFFD_PAGEFAULT_FLAG_WP +flag set. +Note: since only writes can trigger this kind of fault, +write-protect notifications will always have the +.B UFFD_PAGEFAULT_FLAG_WRITE +bit set along with the +.B UFFD_PAGEFAULT_FLAG_WP +bit. +.P +To resolve a write-protection page fault, the user should initiate another +.B UFFDIO_WRITEPROTECT +ioctl, whose +.I uffd_msg.pagefault.flags +should have the flag +.B UFFDIO_WRITEPROTECT_MODE_WP +cleared upon the faulted page or range. +.\" +.SS Userfaultfd minor fault mode (since Linux 5.13) +Since Linux 5.13, +userfaultfd supports minor fault mode. +In this mode, +fault messages are produced not for major faults +(where the page was missing), +but rather for minor faults, +where a page exists in the page cache, +but the page table entries are not yet present. +The user needs to first check availability of this feature using the +.B UFFDIO_API +ioctl with the appropriate feature bits set before using this feature: +.B UFFD_FEATURE_MINOR_HUGETLBFS +since Linux 5.13, +or +.B UFFD_FEATURE_MINOR_SHMEM +since Linux 5.14. +.P +To register with userfaultfd minor fault mode, +the user needs to initiate the +.B UFFDIO_REGISTER +ioctl with mode +.B UFFD_REGISTER_MODE_MINOR +set. +.P +When a minor fault occurs, +user-space will receive a page-fault notification +whose +.I uffd_msg.pagefault.flags +will have the +.B UFFD_PAGEFAULT_FLAG_MINOR +flag set. +.P +To resolve a minor page fault, +the handler should decide whether or not +the existing page contents need to be modified first. +If so, +this should be done in-place via a second, +non-userfaultfd-registered mapping +to the same backing page +(e.g., by mapping the shmem or hugetlbfs file twice). +Once the page is considered "up to date", +the fault can be resolved by initiating an +.B UFFDIO_CONTINUE +ioctl, +which installs the page table entries and +(by default) +wakes up the faulting thread(s). +.P +Minor fault mode supports only hugetlbfs-backed (since Linux 5.13) +and shmem-backed (since Linux 5.14) memory. +.\" +.SS Reading from the userfaultfd structure +Each +.BR read (2) +from the userfaultfd file descriptor returns one or more +.I uffd_msg +structures, each of which describes a page-fault event +or an event required for the non-cooperative userfaultfd usage: +.P +.in +4n +.EX +struct uffd_msg { + __u8 event; /* Type of event */ + ... + union { + struct { + __u64 flags; /* Flags describing fault */ + __u64 address; /* Faulting address */ + union { + __u32 ptid; /* Thread ID of the fault */ + } feat; + } pagefault; +\& + struct { /* Since Linux 4.11 */ + __u32 ufd; /* Userfault file descriptor + of the child process */ + } fork; +\& + struct { /* Since Linux 4.11 */ + __u64 from; /* Old address of remapped area */ + __u64 to; /* New address of remapped area */ + __u64 len; /* Original mapping length */ + } remap; +\& + struct { /* Since Linux 4.11 */ + __u64 start; /* Start address of removed area */ + __u64 end; /* End address of removed area */ + } remove; + ... + } arg; +\& + /* Padding fields omitted */ +} __packed; +.EE +.in +.P +If multiple events are available and the supplied buffer is large enough, +.BR read (2) +returns as many events as will fit in the supplied buffer. +If the buffer supplied to +.BR read (2) +is smaller than the size of the +.I uffd_msg +structure, the +.BR read (2) +fails with the error +.BR EINVAL . +.P +The fields set in the +.I uffd_msg +structure are as follows: +.TP +.I event +The type of event. +Depending of the event type, +different fields of the +.I arg +union represent details required for the event processing. +The non-page-fault events are generated only when appropriate feature +is enabled during API handshake with +.B UFFDIO_API +.BR ioctl (2). +.IP +The following values can appear in the +.I event +field: +.RS +.TP +.BR UFFD_EVENT_PAGEFAULT " (since Linux 4.3)" +A page-fault event. +The page-fault details are available in the +.I pagefault +field. +.TP +.BR UFFD_EVENT_FORK " (since Linux 4.11)" +Generated when the faulting process invokes +.BR fork (2) +(or +.BR clone (2) +without the +.B CLONE_VM +flag). +The event details are available in the +.I fork +field. +.\" FIXME describe duplication of userfault file descriptor during fork +.TP +.BR UFFD_EVENT_REMAP " (since Linux 4.11)" +Generated when the faulting process invokes +.BR mremap (2). +The event details are available in the +.I remap +field. +.TP +.BR UFFD_EVENT_REMOVE " (since Linux 4.11)" +Generated when the faulting process invokes +.BR madvise (2) +with +.B MADV_DONTNEED +or +.B MADV_REMOVE +advice. +The event details are available in the +.I remove +field. +.TP +.BR UFFD_EVENT_UNMAP " (since Linux 4.11)" +Generated when the faulting process unmaps a memory range, +either explicitly using +.BR munmap (2) +or implicitly during +.BR mmap (2) +or +.BR mremap (2). +The event details are available in the +.I remove +field. +.RE +.TP +.I pagefault.address +The address that triggered the page fault. +.TP +.I pagefault.flags +A bit mask of flags that describe the event. +For +.BR UFFD_EVENT_PAGEFAULT , +the following flag may appear: +.RS +.TP +.B UFFD_PAGEFAULT_FLAG_WP +If this flag is set, then the fault was a write-protect fault. +.TP +.B UFFD_PAGEFAULT_FLAG_MINOR +If this flag is set, then the fault was a minor fault. +.TP +.B UFFD_PAGEFAULT_FLAG_WRITE +If this flag is set, then the fault was a write fault. +.P +If neither +.B UFFD_PAGEFAULT_FLAG_WP +nor +.B UFFD_PAGEFAULT_FLAG_MINOR +are set, then the fault was a missing fault. +.RE +.TP +.I pagefault.feat.pid +The thread ID that triggered the page fault. +.TP +.I fork.ufd +The file descriptor associated with the userfault object +created for the child created by +.BR fork (2). +.TP +.I remap.from +The original address of the memory range that was remapped using +.BR mremap (2). +.TP +.I remap.to +The new address of the memory range that was remapped using +.BR mremap (2). +.TP +.I remap.len +The original length of the memory range that was remapped using +.BR mremap (2). +.TP +.I remove.start +The start address of the memory range that was freed using +.BR madvise (2) +or unmapped +.TP +.I remove.end +The end address of the memory range that was freed using +.BR madvise (2) +or unmapped +.P +A +.BR read (2) +on a userfaultfd file descriptor can fail with the following errors: +.TP +.B EINVAL +The userfaultfd object has not yet been enabled using the +.B UFFDIO_API +.BR ioctl (2) +operation +.P +If the +.B O_NONBLOCK +flag is enabled in the associated open file description, +the userfaultfd file descriptor can be monitored with +.BR poll (2), +.BR select (2), +and +.BR epoll (7). +When events are available, the file descriptor indicates as readable. +If the +.B O_NONBLOCK +flag is not enabled, then +.BR poll (2) +(always) indicates the file as having a +.B POLLERR +condition, and +.BR select (2) +indicates the file descriptor as both readable and writable. +.\" FIXME What is the reason for this seemingly odd behavior with respect +.\" to the O_NONBLOCK flag? (see userfaultfd_poll() in fs/userfaultfd.c). +.\" Something needs to be said about this. +.SH RETURN VALUE +On success, +.BR userfaultfd () +returns a new file descriptor that refers to the userfaultfd object. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +An unsupported value was specified in +.IR flags . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been +reached +.TP +.B ENFILE +The system-wide limit on the total number of open files has been +reached. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.BR EPERM " (since Linux 5.2)" +.\" cefdca0a86be517bc390fc4541e3674b8e7803b0 +The caller is not privileged (does not have the +.B CAP_SYS_PTRACE +capability in the initial user namespace), and +.I /proc/sys/vm/unprivileged_userfaultfd +has the value 0. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 4.3. +.P +Support for hugetlbfs and shared memory areas and +non-page-fault events was added in Linux 4.11 +.SH NOTES +The userfaultfd mechanism can be used as an alternative to +traditional user-space paging techniques based on the use of the +.B SIGSEGV +signal and +.BR mmap (2). +It can also be used to implement lazy restore +for checkpoint/restore mechanisms, +as well as post-copy migration to allow (nearly) uninterrupted execution +when transferring virtual machines and Linux containers +from one host to another. +.SH BUGS +If the +.B UFFD_FEATURE_EVENT_FORK +is enabled and a system call from the +.BR fork (2) +family is interrupted by a signal or failed, a stale userfaultfd descriptor +might be created. +In this case, a spurious +.B UFFD_EVENT_FORK +will be delivered to the userfaultfd monitor. +.SH EXAMPLES +The program below demonstrates the use of the userfaultfd mechanism. +The program creates two threads, one of which acts as the +page-fault handler for the process, for the pages in a demand-page zero +region created using +.BR mmap (2). +.P +The program takes one command-line argument, +which is the number of pages that will be created in a mapping +whose page faults will be handled via userfaultfd. +After creating a userfaultfd object, +the program then creates an anonymous private mapping of the specified size +and registers the address range of that mapping using the +.B UFFDIO_REGISTER +.BR ioctl (2) +operation. +The program then creates a second thread that will perform the +task of handling page faults. +.P +The main thread then walks through the pages of the mapping fetching +bytes from successive pages. +Because the pages have not yet been accessed, +the first access of a byte in each page will trigger a page-fault event +on the userfaultfd file descriptor. +.P +Each of the page-fault events is handled by the second thread, +which sits in a loop processing input from the userfaultfd file descriptor. +In each loop iteration, the second thread first calls +.BR poll (2) +to check the state of the file descriptor, +and then reads an event from the file descriptor. +All such events should be +.B UFFD_EVENT_PAGEFAULT +events, +which the thread handles by copying a page of data into +the faulting region using the +.B UFFDIO_COPY +.BR ioctl (2) +operation. +.P +The following is an example of what we see when running the program: +.P +.in +4n +.EX +$ \fB./userfaultfd_demo 3\fP +Address returned by mmap() = 0x7fd30106c000 +\& +fault_handler_thread(): + poll() returns: nready = 1; POLLIN = 1; POLLERR = 0 + UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106c00f + (uffdio_copy.copy returned 4096) +Read address 0x7fd30106c00f in main(): A +Read address 0x7fd30106c40f in main(): A +Read address 0x7fd30106c80f in main(): A +Read address 0x7fd30106cc0f in main(): A +\& +fault_handler_thread(): + poll() returns: nready = 1; POLLIN = 1; POLLERR = 0 + UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106d00f + (uffdio_copy.copy returned 4096) +Read address 0x7fd30106d00f in main(): B +Read address 0x7fd30106d40f in main(): B +Read address 0x7fd30106d80f in main(): B +Read address 0x7fd30106dc0f in main(): B +\& +fault_handler_thread(): + poll() returns: nready = 1; POLLIN = 1; POLLERR = 0 + UFFD_EVENT_PAGEFAULT event: flags = 0; address = 7fd30106e00f + (uffdio_copy.copy returned 4096) +Read address 0x7fd30106e00f in main(): C +Read address 0x7fd30106e40f in main(): C +Read address 0x7fd30106e80f in main(): C +Read address 0x7fd30106ec0f in main(): C +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (userfaultfd.c) +.EX +/* userfaultfd_demo.c +\& + Licensed under the GNU General Public License version 2 or later. +*/ +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +static int page_size; +\& +static void * +fault_handler_thread(void *arg) +{ + int nready; + long uffd; /* userfaultfd file descriptor */ + ssize_t nread; + struct pollfd pollfd; + struct uffdio_copy uffdio_copy; +\& + static int fault_cnt = 0; /* Number of faults so far handled */ + static char *page = NULL; + static struct uffd_msg msg; /* Data read from userfaultfd */ +\& + uffd = (long) arg; +\& + /* Create a page that will be copied into the faulting region. */ +\& + if (page == NULL) { + page = mmap(NULL, page_size, PROT_READ | PROT_WRITE, + MAP_PRIVATE | MAP_ANONYMOUS, \-1, 0); + if (page == MAP_FAILED) + err(EXIT_FAILURE, "mmap"); + } +\& + /* Loop, handling incoming events on the userfaultfd + file descriptor. */ +\& + for (;;) { +\& + /* See what poll() tells us about the userfaultfd. */ +\& + pollfd.fd = uffd; + pollfd.events = POLLIN; + nready = poll(&pollfd, 1, \-1); + if (nready == \-1) + err(EXIT_FAILURE, "poll"); +\& + printf("\enfault_handler_thread():\en"); + printf(" poll() returns: nready = %d; " + "POLLIN = %d; POLLERR = %d\en", nready, + (pollfd.revents & POLLIN) != 0, + (pollfd.revents & POLLERR) != 0); +\& + /* Read an event from the userfaultfd. */ +\& + nread = read(uffd, &msg, sizeof(msg)); + if (nread == 0) { + printf("EOF on userfaultfd!\en"); + exit(EXIT_FAILURE); + } +\& + if (nread == \-1) + err(EXIT_FAILURE, "read"); +\& + /* We expect only one kind of event; verify that assumption. */ +\& + if (msg.event != UFFD_EVENT_PAGEFAULT) { + fprintf(stderr, "Unexpected event on userfaultfd\en"); + exit(EXIT_FAILURE); + } +\& + /* Display info about the page\-fault event. */ +\& + printf(" UFFD_EVENT_PAGEFAULT event: "); + printf("flags = %"PRIx64"; ", msg.arg.pagefault.flags); + printf("address = %"PRIx64"\en", msg.arg.pagefault.address); +\& + /* Copy the page pointed to by \[aq]page\[aq] into the faulting + region. Vary the contents that are copied in, so that it + is more obvious that each fault is handled separately. */ +\& + memset(page, \[aq]A\[aq] + fault_cnt % 20, page_size); + fault_cnt++; +\& + uffdio_copy.src = (unsigned long) page; +\& + /* We need to handle page faults in units of pages(!). + So, round faulting address down to page boundary. */ +\& + uffdio_copy.dst = (unsigned long) msg.arg.pagefault.address & + \[ti](page_size \- 1); + uffdio_copy.len = page_size; + uffdio_copy.mode = 0; + uffdio_copy.copy = 0; + if (ioctl(uffd, UFFDIO_COPY, &uffdio_copy) == \-1) + err(EXIT_FAILURE, "ioctl\-UFFDIO_COPY"); +\& + printf(" (uffdio_copy.copy returned %"PRId64")\en", + uffdio_copy.copy); + } +} +\& +int +main(int argc, char *argv[]) +{ + int s; + char c; + char *addr; /* Start of region handled by userfaultfd */ + long uffd; /* userfaultfd file descriptor */ + size_t len, l; /* Length of region handled by userfaultfd */ + pthread_t thr; /* ID of thread that handles page faults */ + struct uffdio_api uffdio_api; + struct uffdio_register uffdio_register; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s num\-pages\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + page_size = sysconf(_SC_PAGE_SIZE); + len = strtoull(argv[1], NULL, 0) * page_size; +\& + /* Create and enable userfaultfd object. */ +\& + uffd = syscall(SYS_userfaultfd, O_CLOEXEC | O_NONBLOCK); + if (uffd == \-1) + err(EXIT_FAILURE, "userfaultfd"); +\& + /* NOTE: Two-step feature handshake is not needed here, since this + example doesn't require any specific features. +\& + Programs that *do* should call UFFDIO_API twice: once with + `features = 0` to detect features supported by this kernel, and + again with the subset of features the program actually wants to + enable. */ + uffdio_api.api = UFFD_API; + uffdio_api.features = 0; + if (ioctl(uffd, UFFDIO_API, &uffdio_api) == \-1) + err(EXIT_FAILURE, "ioctl\-UFFDIO_API"); +\& + /* Create a private anonymous mapping. The memory will be + demand\-zero paged\-\-that is, not yet allocated. When we + actually touch the memory, it will be allocated via + the userfaultfd. */ +\& + addr = mmap(NULL, len, PROT_READ | PROT_WRITE, + MAP_PRIVATE | MAP_ANONYMOUS, \-1, 0); + if (addr == MAP_FAILED) + err(EXIT_FAILURE, "mmap"); +\& + printf("Address returned by mmap() = %p\en", addr); +\& + /* Register the memory range of the mapping we just created for + handling by the userfaultfd object. In mode, we request to track + missing pages (i.e., pages that have not yet been faulted in). */ +\& + uffdio_register.range.start = (unsigned long) addr; + uffdio_register.range.len = len; + uffdio_register.mode = UFFDIO_REGISTER_MODE_MISSING; + if (ioctl(uffd, UFFDIO_REGISTER, &uffdio_register) == \-1) + err(EXIT_FAILURE, "ioctl\-UFFDIO_REGISTER"); +\& + /* Create a thread that will process the userfaultfd events. */ +\& + s = pthread_create(&thr, NULL, fault_handler_thread, (void *) uffd); + if (s != 0) { + errc(EXIT_FAILURE, s, "pthread_create"); + } +\& + /* Main thread now touches memory in the mapping, touching + locations 1024 bytes apart. This will trigger userfaultfd + events for all pages in the region. */ +\& + l = 0xf; /* Ensure that faulting address is not on a page + boundary, in order to test that we correctly + handle that case in fault_handling_thread(). */ + while (l < len) { + c = addr[l]; + printf("Read address %p in %s(): ", addr + l, __func__); + printf("%c\en", c); + l += 1024; + usleep(100000); /* Slow things down a little */ + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fcntl (2), +.BR ioctl (2), +.BR ioctl_userfaultfd (2), +.BR madvise (2), +.BR mmap (2) +.P +.I Documentation/admin\-guide/mm/userfaultfd.rst +in the Linux kernel source tree diff --git a/man/man2/ustat.2 b/man/man2/ustat.2 new file mode 100644 index 0000000..49c0691 --- /dev/null +++ b/man/man2/ustat.2 @@ -0,0 +1,104 @@ +.\" Copyright (C) 1995, Thomas K. Dyas +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created 1995-08-09 Thomas K. Dyas +.\" Modified 1997-01-31 by Eric S. Raymond +.\" Modified 2001-03-22 by aeb +.\" Modified 2003-08-04 by aeb +.\" +.TH ustat 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ustat \- get filesystem statistics +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.BR "#include " " /* libc[45] */" +.BR "#include " " /* glibc2 */" +.P +.BI "[[deprecated]] int ustat(dev_t " dev ", struct ustat *" ubuf ); +.fi +.SH DESCRIPTION +.BR ustat () +returns information about a mounted filesystem. +.I dev +is a device number identifying a device containing +a mounted filesystem. +.I ubuf +is a pointer to a +.I ustat +structure that contains the following +members: +.P +.in +4n +.EX +daddr_t f_tfree; /* Total free blocks */ +ino_t f_tinode; /* Number of free inodes */ +char f_fname[6]; /* Filsys name */ +char f_fpack[6]; /* Filsys pack name */ +.EE +.in +.P +The last two fields, +.I f_fname +and +.IR f_fpack , +are not implemented and will +always be filled with null bytes (\[aq]\e0\[aq]). +.SH RETURN VALUE +On success, zero is returned and the +.I ustat +structure pointed to by +.I ubuf +will be filled in. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I ubuf +points outside of your accessible address space. +.TP +.B EINVAL +.I dev +does not refer to a device containing a mounted filesystem. +.TP +.B ENOSYS +The mounted filesystem referenced by +.I dev +does not support this operation, +or any version of Linux before Linux 1.3.16. +.SH STANDARDS +None. +.SH HISTORY +SVr4. +Removed in glibc 2.28. +.\" SVr4 documents additional error conditions ENOLINK, ECOMM, and EINTR +.\" but has no ENOSYS condition. +.P +.BR ustat () +is deprecated and has been provided only for compatibility. +All new programs should use +.BR statfs (2) +instead. +.SS HP-UX notes +The HP-UX version of the +.I ustat +structure has an additional field, +.IR f_blksize , +that is unknown elsewhere. +HP-UX warns: +For some filesystems, the number of free inodes does not change. +Such filesystems will return \-1 in the field +.IR f_tinode . +.\" Some software tries to use this in order to test whether the +.\" underlying filesystem is NFS. +For some filesystems, inodes are dynamically allocated. +Such filesystems will return the current number of free inodes. +.SH SEE ALSO +.BR stat (2), +.BR statfs (2) diff --git a/man/man2/utime.2 b/man/man2/utime.2 new file mode 100644 index 0000000..4d7082d --- /dev/null +++ b/man/man2/utime.2 @@ -0,0 +1,179 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-06-10 by Andries Brouwer +.\" Modified 2004-06-23 by Michael Kerrisk +.\" Modified 2004-10-10 by Andries Brouwer +.\" +.TH utime 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +utime, utimes \- change file last access and modification times +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int utime(const char *" filename , +.BI " const struct utimbuf *_Nullable " times ); +.P +.B #include +.P +.BI "int utimes(const char *" filename , +.BI " const struct timeval " times "[_Nullable 2]);" +.fi +.SH DESCRIPTION +.B Note: +modern applications may prefer to use the interfaces described in +.BR utimensat (2). +.P +The +.BR utime () +system call +changes the access and modification times of the inode specified by +.I filename +to the +.IR actime " and " modtime +fields of +.I times +respectively. +The status change time (ctime) will be set to the current time, even if the +other time stamps don't actually change. +.P +If +.I times +is NULL, then the access and modification times of the file are set +to the current time. +.P +Changing timestamps is permitted when: either +the process has appropriate privileges, +or the effective user ID equals the user ID +of the file, or +.I times +is NULL and the process has write permission for the file. +.P +The +.I utimbuf +structure is: +.P +.in +4n +.EX +struct utimbuf { + time_t actime; /* access time */ + time_t modtime; /* modification time */ +}; +.EE +.in +.P +The +.BR utime () +system call +allows specification of timestamps with a resolution of 1 second. +.P +The +.BR utimes () +system call +is similar, but the +.I times +argument refers to an array rather than a structure. +The elements of this array are +.I timeval +structures, which allow a precision of 1 microsecond for specifying timestamps. +The +.I timeval +structure is: +.P +.in +4n +.EX +struct timeval { + long tv_sec; /* seconds */ + long tv_usec; /* microseconds */ +}; +.EE +.in +.P +.I times[0] +specifies the new access time, and +.I times[1] +specifies the new modification time. +If +.I times +is NULL, then analogously to +.BR utime (), +the access and modification times of the file are +set to the current time. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission is denied for one of the directories in +the path prefix of +.I path +(see also +.BR path_resolution (7)). +.TP +.B EACCES +.I times +is NULL, +the caller's effective user ID does not match the owner of the file, +the caller does not have write access to the file, +and the caller is not privileged +(Linux: does not have either the +.B CAP_DAC_OVERRIDE +or the +.B CAP_FOWNER +capability). +.TP +.B ENOENT +.I filename +does not exist. +.TP +.B EPERM +.I times +is not NULL, +the caller's effective UID does not match the owner of the file, +and the caller is not privileged +(Linux: does not have the +.B CAP_FOWNER +capability). +.TP +.B EROFS +.I path +resides on a read-only filesystem. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR utime () +SVr4, POSIX.1-2001. +POSIX.1-2008 marks it as obsolete. +.TP +.BR utimes () +4.3BSD, POSIX.1-2001. +.SH NOTES +Linux does not allow changing the timestamps on an immutable file, +or setting the timestamps to something other than the current time +on an append-only file. +.\" +.\" In libc4 and libc5, +.\" .BR utimes () +.\" is just a wrapper for +.\" .BR utime () +.\" and hence does not allow a subsecond resolution. +.SH SEE ALSO +.BR chattr (1), +.BR touch (1), +.BR futimesat (2), +.BR stat (2), +.BR utimensat (2), +.BR futimens (3), +.BR futimes (3), +.BR inode (7) diff --git a/man/man2/utimensat.2 b/man/man2/utimensat.2 new file mode 100644 index 0000000..f178f92 --- /dev/null +++ b/man/man2/utimensat.2 @@ -0,0 +1,633 @@ +'\" t +.\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH utimensat 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +utimensat, futimens \- change file timestamps with nanosecond precision +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " AT_* " constants */" +.B #include +.P +.BI "int utimensat(int " dirfd ", const char *" pathname , +.BI " const struct timespec " times "[_Nullable 2], int " flags ); +.BI "int futimens(int " fd ", const struct timespec " times "[_Nullable 2]);" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR utimensat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.P +.BR futimens (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +.BR utimensat () +and +.BR futimens () +update the timestamps of a file with nanosecond precision. +This contrasts with the historical +.BR utime (2) +and +.BR utimes (2), +which permit only second and microsecond precision, respectively, +when setting file timestamps. +.P +With +.BR utimensat () +the file is specified via the pathname given in +.IR pathname . +With +.BR futimens () +the file whose timestamps are to be updated is specified via +an open file descriptor, +.IR fd . +.P +For both calls, the new file timestamps are specified in the array +.IR times : +.I times[0] +specifies the new "last access time" (\fIatime\fP); +.I times[1] +specifies the new "last modification time" (\fImtime\fP). +Each of the elements of +.I times +specifies a time as the number of seconds and nanoseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +This information is conveyed in a +.BR timespec (3) +structure. +.P +Updated file timestamps are set to the greatest value +supported by the filesystem that is not greater than the specified time. +.P +If the +.I tv_nsec +field of one of the +.I timespec +structures has the special value +.BR UTIME_NOW , +then the corresponding file timestamp is set to the current time. +If the +.I tv_nsec +field of one of the +.I timespec +structures has the special value +.BR UTIME_OMIT , +then the corresponding file timestamp is left unchanged. +In both of these cases, the value of the corresponding +.I tv_sec +.\" 2.6.22 was broken: it is not ignored +field is ignored. +.P +If +.I times +is NULL, then both timestamps are set to the current time. +.\" +.P +The status change time (ctime) will be set to the current time, even if the +other time stamps don't actually change. +.SS Permissions requirements +To set both file timestamps to the current time (i.e., +.I times +is NULL, or both +.I tv_nsec +fields specify +.BR UTIME_NOW ), +either: +.IP \[bu] 3 +the caller must have write access to the file; +.\" 2.6.22 was broken here -- for futimens() the check is +.\" based on whether or not the file descriptor is writable, +.\" not on whether the caller's effective UID has write +.\" permission for the file referred to by the descriptor. +.IP \[bu] +the caller's effective user ID must match the owner of the file; or +.IP \[bu] +the caller must have appropriate privileges. +.P +To make any change other than setting both timestamps to the +current time (i.e., +.I times +is not NULL, and neither +.I tv_nsec +field is +.B UTIME_NOW +.\" 2.6.22 was broken here: +.\" both must be something other than *either* UTIME_OMIT *or* UTIME_NOW. +and neither +.I tv_nsec +field is +.BR UTIME_OMIT ), +either condition 2 or 3 above must apply. +.P +If both +.I tv_nsec +fields are specified as +.BR UTIME_OMIT , +then no file ownership or permission checks are performed, +and the file timestamps are not modified, +but other error conditions may still be detected. +.\" +.\" +.SS utimensat() specifics +If +.I pathname +is relative, then by default it is interpreted relative to the +directory referred to by the open file descriptor, +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR utimes (2) +for a relative pathname). +See +.BR openat (2) +for an explanation of why this can be useful. +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR utimes (2)). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +The +.I flags +argument is a bit mask created by ORing together zero or more of +the following values defined in +.IR : +.TP +.BR AT_EMPTY_PATH " (since Linux 5.8)" +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +to obtain its definition. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I pathname +specifies a symbolic link, then update the timestamps of the link, +rather than the file to which it refers. +.SH RETURN VALUE +On success, +.BR utimensat () +and +.BR futimens () +return 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.I times +is NULL, +or both +.I tv_nsec +values are +.BR UTIME_NOW , +and the effective user ID of the caller does not match +the owner of the file, +the caller does not have write access to the file, +and the caller is not privileged +(Linux: does not have either the +.B CAP_FOWNER +or the +.B CAP_DAC_OVERRIDE +capability). +.\" But Linux 2.6.22 was broken here. +.\" Traditionally, utime()/utimes() gives the error EACCES for the case +.\" where the timestamp pointer argument is NULL (i.e., set both timestamps +.\" to the current time), and the file is owned by a user other than the +.\" effective UID of the caller, and the file is not writable by the +.\" effective UID of the program. utimensat() also gives this error in the +.\" same case. However, in the same circumstances, when utimensat() is +.\" given a 'times' array in which both tv_nsec fields are UTIME_NOW, which +.\" provides equivalent functionality to specifying 'times' as NULL, the +.\" call succeeds. It should fail with the error EACCES in this case. +.\" +.\" POSIX.1-2008 has the following: +.\" .TP +.\" .B EACCES +.\" .RB ( utimensat ()) +.\" .I fd +.\" was not opened with +.\" .B O_SEARCH +.\" and the permissions of the directory to which +.\" .I fd +.\" refers do not allow searches. +.\" EXT2_IMMUTABLE_FL and similar flags for other filesystems. +.TP +.B EBADF +.RB ( futimens ()) +.I fd +is not a valid file descriptor. +.TP +.B EBADF +.RB ( utimensat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I times +pointed to an invalid address; or, +.I dirfd +was +.BR AT_FDCWD , +and +.I pathname +is NULL or an invalid address. +.TP +.B EINVAL +Invalid value in +.IR flags . +.TP +.B EINVAL +Invalid value in one of the +.I tv_nsec +fields (value outside range [0, 999,999,999], and not +.B UTIME_NOW +or +.BR UTIME_OMIT ); +or an invalid value in one of the +.I tv_sec +fields. +.TP +.B EINVAL +.\" SUSv4 does not specify this error. +.I pathname +is NULL, +.I dirfd +is not +.BR AT_FDCWD , +and +.I flags +contains +.BR AT_SYMLINK_NOFOLLOW . +.TP +.B ELOOP +.RB ( utimensat ()) +Too many symbolic links were encountered in resolving +.IR pathname . +.TP +.B ENAMETOOLONG +.RB ( utimensat ()) +.I pathname +is too long. +.TP +.B ENOENT +.RB ( utimensat ()) +A component of +.I pathname +does not refer to an existing directory or file, +or +.I pathname +is an empty string. +.TP +.B ENOTDIR +.RB ( utimensat ()) +.I pathname +is a relative pathname, but +.I dirfd +is neither +.B AT_FDCWD +nor a file descriptor referring to a directory; +or, one of the prefix components of +.I pathname +is not a directory. +.TP +.B EPERM +The caller attempted to change one or both timestamps to a value +other than the current time, +or to change one of the timestamps to the current time while +leaving the other timestamp unchanged, +(i.e., +.I times +is not NULL, neither +.I tv_nsec +field is +.BR UTIME_NOW , +and neither +.I tv_nsec +field is +.BR UTIME_OMIT ) +and either: +.RS +.IP \[bu] 3 +the caller's effective user ID does not match the owner of file, +and the caller is not privileged +(Linux: does not have the +.B CAP_FOWNER +capability); or, +.IP \[bu] +.\" Linux 2.6.22 was broken here: +.\" it was not consistent with the old utimes() implementation, +.\" since the case when both tv_nsec fields are UTIME_NOW, was not +.\" treated like the (times == NULL) case. +the file is marked append-only or immutable (see +.BR chattr (1)). +.\" EXT2_IMMUTABLE_FL EXT_APPEND_FL and similar flags for +.\" other filesystems. +.\" +.\" Why the inconsistency (which is described under NOTES) between +.\" EACCES and EPERM, where only EPERM tests for append-only. +.\" (This was also so for the older utimes() implementation.) +.RE +.TP +.B EROFS +The file is on a read-only filesystem. +.TP +.B ESRCH +.RB ( utimensat ()) +Search permission is denied for one of the prefix components of +.IR pathname . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR utimensat (), +.BR futimens () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS C library/kernel ABI differences +On Linux, +.BR futimens () +is a library function implemented on top of the +.BR utimensat () +system call. +To support this, the Linux +.BR utimensat () +system call implements a nonstandard feature: if +.I pathname +is NULL, then the call modifies the timestamps of +the file referred to by the file descriptor +.I dirfd +(which may refer to any type of file). +Using this feature, the call +.I "futimens(fd,\ times)" +is implemented as: +.P +.in +4n +.EX +utimensat(fd, NULL, times, 0); +.EE +.in +.P +Note, however, that the glibc wrapper for +.BR utimensat () +disallows passing NULL as the value for +.IR pathname : +the wrapper function returns the error +.B EINVAL +in this case. +.SH STANDARDS +POSIX.1-2008. +.SH VERSIONS +.TP +.BR utimensat () +Linux 2.6.22, +glibc 2.6. +POSIX.1-2008. +.TP +.BR futimens () +glibc 2.6. +POSIX.1-2008. +.SH NOTES +.BR utimensat () +obsoletes +.BR futimesat (2). +.P +On Linux, timestamps cannot be changed for a file marked immutable, +and the only change permitted for files marked append-only is to +set the timestamps to the current time. +(This is consistent with the historical behavior of +.BR utime (2) +and +.BR utimes (2) +on Linux.) +.P +If both +.I tv_nsec +fields are specified as +.BR UTIME_OMIT , +then the Linux implementation of +.BR utimensat () +succeeds even if the file referred to by +.I dirfd +and +.I pathname +does not exist. +.SH BUGS +Several bugs afflict +.BR utimensat () +and +.BR futimens () +before Linux 2.6.26. +These bugs are either nonconformances with the POSIX.1 draft specification +or inconsistencies with historical Linux behavior. +.IP \[bu] 3 +POSIX.1 specifies that if one of the +.I tv_nsec +fields has the value +.B UTIME_NOW +or +.BR UTIME_OMIT , +then the value of the corresponding +.I tv_sec +field should be ignored. +Instead, the value of the +.I tv_sec +field is required to be 0 (or the error +.B EINVAL +results). +.IP \[bu] +Various bugs mean that for the purposes of permission checking, +the case where both +.I tv_nsec +fields are set to +.B UTIME_NOW +isn't always treated the same as specifying +.I times +as NULL, +and the case where one +.I tv_nsec +value is +.B UTIME_NOW +and the other is +.B UTIME_OMIT +isn't treated the same as specifying +.I times +as a pointer to an array of structures containing arbitrary time values. +As a result, in some cases: +a) file timestamps can be updated by a process that shouldn't have +permission to perform updates; +b) file timestamps can't be updated by a process that should have +permission to perform updates; and +c) the wrong +.I errno +value is returned in case of an error. +.\" Below, the long description of the errors from the previous bullet +.\" point (abridged because it's too much detail for a man page). +.\" .IP \[bu] +.\" If one of the +.\" .I tv_nsec +.\" fields is +.\" .BR UTIME_OMIT +.\" and the other is +.\" .BR UTIME_NOW , +.\" then the error +.\" .B EPERM +.\" should occur if the process's effective user ID does not match +.\" the file owner and the process is not privileged. +.\" Instead, the call successfully changes one of the timestamps. +.\" .IP \[bu] +.\" If file is not writable by the effective user ID of the process and +.\" the process's effective user ID does not match the file owner and +.\" the process is not privileged, +.\" and +.\" .I times +.\" is NULL, then the error +.\" .B EACCES +.\" results. +.\" This error should also occur if +.\" .I times +.\" points to an array of structures in which both +.\" .I tv_nsec +.\" fields are +.\" .BR UTIME_NOW . +.\" Instead the call succeeds. +.\" .IP \[bu] +.\" If a file is marked as append-only (see +.\" .BR chattr (1)), +.\" then Linux traditionally +.\" (i.e., +.\" .BR utime (2), +.\" .BR utimes (2)), +.\" permits a NULL +.\" .I times +.\" argument to be used in order to update both timestamps to the current time. +.\" For consistency, +.\" .BR utimensat () +.\" and +.\" .BR futimens () +.\" should also produce the same result when given a +.\" .I times +.\" argument that points to an array of structures in which both +.\" .I tv_nsec +.\" fields are +.\" .BR UTIME_NOW . +.\" Instead, the call fails with the error +.\" .BR EPERM . +.\" .IP \[bu] +.\" If a file is marked as immutable (see +.\" .BR chattr (1)), +.\" then Linux traditionally +.\" (i.e., +.\" .BR utime (2), +.\" .BR utimes (2)), +.\" gives an +.\" .B EACCES +.\" error if +.\" .I times +.\" is NULL. +.\" For consistency, +.\" .BR utimensat () +.\" and +.\" .BR futimens () +.\" should also produce the same result when given a +.\" .I times +.\" that points to an array of structures in which both +.\" .I tv_nsec +.\" fields are +.\" .BR UTIME_NOW . +.\" Instead, the call fails with the error +.\" .BR EPERM . +.IP \[bu] +POSIX.1 says that a process that has \fIwrite access to the file\fP +can make a call with +.I times +as NULL, or with +.I times +pointing to an array of structures in which both +.I tv_nsec +fields are +.BR UTIME_NOW , +in order to update both timestamps to the current time. +However, +.BR futimens () +instead checks whether the +.IR "access mode of the file descriptor allows writing" . +.\" This means that a process with a file descriptor that allows +.\" writing could change the timestamps of a file for which it +.\" does not have write permission; +.\" conversely, a process with a read-only file descriptor won't +.\" be able to update the timestamps of a file, +.\" even if it has write permission on the file. +.SH SEE ALSO +.BR chattr (1), +.BR touch (1), +.BR futimesat (2), +.BR openat (2), +.BR stat (2), +.BR utimes (2), +.BR futimes (3), +.BR timespec (3), +.BR inode (7), +.BR path_resolution (7), +.BR symlink (7) diff --git a/man/man2/utimes.2 b/man/man2/utimes.2 new file mode 100644 index 0000000..04372d4 --- /dev/null +++ b/man/man2/utimes.2 @@ -0,0 +1 @@ +.so man2/utime.2 diff --git a/man/man2/vfork.2 b/man/man2/vfork.2 new file mode 100644 index 0000000..a4915c7 --- /dev/null +++ b/man/man2/vfork.2 @@ -0,0 +1,316 @@ +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl), 1 Nov 1999 +.\" and Copyright 2006, 2012, 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 1999-11-10: Merged text taken from the page contributed by +.\" Reed H. Petty (rhp@draper.net) +.\" +.TH vfork 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +vfork \- create a child process and block parent +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B pid_t vfork(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR vfork (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +.SS Standard description +(From POSIX.1) +The +.BR vfork () +function has the same effect as +.BR fork (2), +except that the behavior is undefined if the process created by +.BR vfork () +either modifies any data other than a variable of type +.I pid_t +used to store the return value from +.BR vfork (), +or returns from the function in which +.BR vfork () +was called, or calls any other function before successfully calling +.BR _exit (2) +or one of the +.BR exec (3) +family of functions. +.SS Linux description +.BR vfork (), +just like +.BR fork (2), +creates a child process of the calling process. +For details and return value and errors, see +.BR fork (2). +.P +.BR vfork () +is a special case of +.BR clone (2). +It is used to create new processes without copying the page tables of +the parent process. +It may be useful in performance-sensitive applications +where a child is created which then immediately issues an +.BR execve (2). +.P +.BR vfork () +differs from +.BR fork (2) +in that the calling thread is suspended until the child terminates +(either normally, +by calling +.BR _exit (2), +or abnormally, after delivery of a fatal signal), +or it makes a call to +.BR execve (2). +Until that point, the child shares all memory with its parent, +including the stack. +The child must not return from the current function or call +.BR exit (3) +(which would have the effect of calling exit handlers +established by the parent process and flushing the parent's +.BR stdio (3) +buffers), but may call +.BR _exit (2). +.P +As with +.BR fork (2), +the child process created by +.BR vfork () +inherits copies of various of the caller's process attributes +(e.g., file descriptors, signal dispositions, and current working directory); +the +.BR vfork () +call differs only in the treatment of the virtual address space, +as described above. +.P +Signals sent to the parent +arrive after the child releases the parent's memory +(i.e., after the child terminates +or calls +.BR execve (2)). +.SS Historic description +Under Linux, +.BR fork (2) +is implemented using copy-on-write pages, so the only penalty incurred by +.BR fork (2) +is the time and memory required to duplicate the parent's page tables, +and to create a unique task structure for the child. +However, in the bad old days a +.BR fork (2) +would require making a complete copy of the caller's data space, +often needlessly, since usually immediately afterward an +.BR exec (3) +is done. +Thus, for greater efficiency, BSD introduced the +.BR vfork () +system call, which did not fully copy the address space of +the parent process, but borrowed the parent's memory and thread +of control until a call to +.BR execve (2) +or an exit occurred. +The parent process was suspended while the +child was using its resources. +The use of +.BR vfork () +was tricky: for example, not modifying data +in the parent process depended on knowing which variables were +held in a register. +.SH VERSIONS +The requirements put on +.BR vfork () +by the standards are weaker than those put on +.BR fork (2), +so an implementation where the two are synonymous is compliant. +In particular, the programmer cannot rely on the parent +remaining blocked until the child either terminates or calls +.BR execve (2), +and cannot rely on any specific behavior with respect to shared memory. +.\" In AIXv3.1 vfork is equivalent to fork. +.P +Some consider the semantics of +.BR vfork () +to be an architectural blemish, and the 4.2BSD man page stated: +\[lq]This system call will be eliminated +when proper system sharing mechanisms are implemented. +Users should not depend on the memory sharing semantics of +.I vfork +as it will, in that case, be made synonymous to +.IR fork .\[rq] +However, even though modern memory management hardware +has decreased the performance difference between +.BR fork (2) +and +.BR vfork (), +there are various reasons why Linux and other systems have retained +.BR vfork (): +.IP \[bu] 3 +Some performance-critical applications require the small performance +advantage conferred by +.BR vfork (). +.IP \[bu] +.BR vfork () +can be implemented on systems that lack a memory-management unit (MMU), but +.BR fork (2) +can't be implemented on such systems. +(POSIX.1-2008 removed +.BR vfork () +from the standard; the POSIX rationale for the +.BR posix_spawn (3) +function notes that that function, +which provides functionality equivalent to +.BR fork (2)+\c +.BR exec (3), +is designed to be implementable on systems that lack an MMU.) +.\" http://stackoverflow.com/questions/4259629/what-is-the-difference-between-fork-and-vfork +.\" http://developers.sun.com/solaris/articles/subprocess/subprocess.html +.\" http://mailman.uclinux.org/pipermail/uclinux-dev/2009-April/000684.html +.\" +.IP \[bu] +On systems where memory is constrained, +.BR vfork () +avoids the need to temporarily commit memory (see the description of +.I /proc/sys/vm/overcommit_memory +in +.BR proc (5)) +in order to execute a new program. +(This can be especially beneficial where a large parent process wishes +to execute a small helper program in a child process.) +By contrast, using +.BR fork (2) +in this scenario requires either committing an amount of memory equal +to the size of the parent process (if strict overcommitting is in force) +or overcommitting memory with the risk that a process is terminated +by the out-of-memory (OOM) killer. +.SS Linux notes +Fork handlers established using +.BR pthread_atfork (3) +are not called when a multithreaded program employing +the NPTL threading library calls +.BR vfork (). +Fork handlers are called in this case in a program using the +LinuxThreads threading library. +(See +.BR pthreads (7) +for a description of Linux threading libraries.) +.P +A call to +.BR vfork () +is equivalent to calling +.BR clone (2) +with +.I flags +specified as: +.P +.in +4n +.EX + CLONE_VM | CLONE_VFORK | SIGCHLD +.EE +.in +.SH STANDARDS +None. +.SH HISTORY +4.3BSD; POSIX.1-2001 (but marked OBSOLETE). +POSIX.1-2008 removes the specification of +.BR vfork (). +.P +The +.BR vfork () +system call appeared in 3.0BSD. +.\" In the release notes for 4.2BSD Sam Leffler wrote: `vfork: Is still +.\" present, but definitely on its way out'. +In 4.4BSD it was made synonymous to +.BR fork (2) +but NetBSD introduced it again; +see +.UR http://www.netbsd.org\:/Documentation\:/kernel\:/vfork.html +.UE . +In Linux, it has been equivalent to +.BR fork (2) +until Linux 2.2.0-pre6 or so. +Since Linux 2.2.0-pre9 (on i386, somewhat later on +other architectures) it is an independent system call. +Support was added in glibc 2.0.112. +.\" +.SH CAVEATS +The child process should take care not to modify the memory in unintended ways, +since such changes will be seen by the parent process once +the child terminates or executes another program. +In this regard, signal handlers can be especially problematic: +if a signal handler that is invoked in the child of +.BR vfork () +changes memory, those changes may result in an inconsistent process state +from the perspective of the parent process +(e.g., memory changes would be visible in the parent, +but changes to the state of open file descriptors would not be visible). +.P +When +.BR vfork () +is called in a multithreaded process, +only the calling thread is suspended until the child terminates +or executes a new program. +This means that the child is sharing an address space with other running code. +This can be dangerous if another thread in the parent process +changes credentials (using +.BR setuid (2) +or similar), +since there are now two processes with different privilege levels +running in the same address space. +As an example of the dangers, +suppose that a multithreaded program running as root creates a child using +.BR vfork (). +After the +.BR vfork (), +a thread in the parent process drops the process to an unprivileged user +in order to run some untrusted code +(e.g., perhaps via plug-in opened with +.BR dlopen (3)). +In this case, attacks are possible where the parent process uses +.BR mmap (2) +to map in code that will be executed by the privileged child process. +.\" +.SH BUGS +Details of the signal handling are obscure and differ between systems. +The BSD man page states: +"To avoid a possible deadlock situation, processes that are children +in the middle of a +.BR vfork () +are never sent +.B SIGTTOU +or +.B SIGTTIN +signals; rather, output or +.IR ioctl s +are allowed and input attempts result in an end-of-file indication." +.\" +.\" As far as I can tell, the following is not true in Linux 2.6.19: +.\" Currently (Linux 2.3.25), +.\" .BR strace (1) +.\" cannot follow +.\" .BR vfork () +.\" and requires a kernel patch. +.SH SEE ALSO +.BR clone (2), +.BR execve (2), +.BR _exit (2), +.BR fork (2), +.BR unshare (2), +.BR wait (2) diff --git a/man/man2/vhangup.2 b/man/man2/vhangup.2 new file mode 100644 index 0000000..41e97f8 --- /dev/null +++ b/man/man2/vhangup.2 @@ -0,0 +1,58 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" +.TH vhangup 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +vhangup \- virtually hangup the current terminal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B int vhangup(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR vhangup (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +.BR vhangup () +simulates a hangup on the current terminal. +This call arranges for other +users to have a \*(lqclean\*(rq terminal at login time. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EPERM +The calling process has insufficient privilege to call +.BR vhangup (); +the +.B CAP_SYS_TTY_CONFIG +capability is required. +.SH STANDARDS +Linux. +.SH SEE ALSO +.BR init (1), +.BR capabilities (7) diff --git a/man/man2/vm86.2 b/man/man2/vm86.2 new file mode 100644 index 0000000..fe2aa8a --- /dev/null +++ b/man/man2/vm86.2 @@ -0,0 +1,58 @@ +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Copyright 1997 Andries E. Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH vm86 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +vm86old, vm86 \- enter virtual 8086 mode +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int vm86old(struct vm86_struct *" info ); +.BI "int vm86(unsigned long " fn ", struct vm86plus_struct *" v86 ); +.fi +.SH DESCRIPTION +The system call +.BR vm86 () +was introduced in Linux 0.97p2. +In Linux 2.1.15 and 2.0.28, it was renamed to +.BR vm86old (), +and a new +.BR vm86 () +was introduced. +The definition of +.I struct vm86_struct +was changed +in 1.1.8 and 1.1.9. +.P +These calls cause the process to enter VM86 mode (virtual-8086 in Intel +literature), and are used by +.BR dosemu . +.P +VM86 mode is an emulation of real mode within a protected mode task. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +This return value is specific to i386 and indicates a problem with getting +user-space data. +.TP +.B ENOSYS +This return value indicates the call is not implemented on the present +architecture. +.TP +.B EPERM +Saved kernel stack exists. +(This is a kernel sanity check; the saved +stack should exist only within vm86 mode itself.) +.SH STANDARDS +Linux on 32-bit Intel processors. diff --git a/man/man2/vm86old.2 b/man/man2/vm86old.2 new file mode 100644 index 0000000..bf2581d --- /dev/null +++ b/man/man2/vm86old.2 @@ -0,0 +1 @@ +.so man2/vm86.2 diff --git a/man/man2/vmsplice.2 b/man/man2/vmsplice.2 new file mode 100644 index 0000000..20ffb15 --- /dev/null +++ b/man/man2/vmsplice.2 @@ -0,0 +1,162 @@ +.\" This manpage is Copyright (C) 2006 Jens Axboe +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH vmsplice 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +vmsplice \- splice user pages to/from a pipe +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov , +.BI " size_t " nr_segs ", unsigned int " flags ); +.fi +.\" Return type was long before glibc 2.7 +.SH DESCRIPTION +.\" Linus: vmsplice() system call to basically do a "write to +.\" the buffer", but using the reference counting and VM traversal +.\" to actually fill the buffer. This means that the user needs to +.\" be careful not to reuse the user-space buffer it spliced into +.\" the kernel-space one (contrast this to "write()", which copies +.\" the actual data, and you can thus reuse the buffer immediately +.\" after a successful write), but that is often easy to do. +If +.I fd +is opened for writing, the +.BR vmsplice () +system call maps +.I nr_segs +ranges of user memory described by +.I iov +into a pipe. +If +.I fd +is opened for reading, +.\" Since Linux 2.6.23 +.\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7 +the +.BR vmsplice () +system call fills +.I nr_segs +ranges of user memory described by +.I iov +from a pipe. +The file descriptor +.I fd +must refer to a pipe. +.P +The pointer +.I iov +points to an array of +.I iovec +structures as described in +.BR iovec (3type). +.P +The +.I flags +argument is a bit mask that is composed by ORing together +zero or more of the following values: +.TP +.B SPLICE_F_MOVE +Unused for +.BR vmsplice (); +see +.BR splice (2). +.TP +.B SPLICE_F_NONBLOCK +.\" Not used for vmsplice +.\" May be in the future -- therefore EAGAIN +Do not block on I/O; see +.BR splice (2) +for further details. +.TP +.B SPLICE_F_MORE +Currently has no effect for +.BR vmsplice (), +but may be implemented in the future; see +.BR splice (2). +.TP +.B SPLICE_F_GIFT +The user pages are a gift to the kernel. +The application may not modify this memory ever, +.\" FIXME . Explain the following line in a little more detail: +otherwise the page cache and on-disk data may differ. +Gifting pages to the kernel means that a subsequent +.BR splice (2) +.B SPLICE_F_MOVE +can successfully move the pages; +if this flag is not specified, then a subsequent +.BR splice (2) +.B SPLICE_F_MOVE +must copy the pages. +Data must also be properly page aligned, both in memory and length. +.\" FIXME +.\" It looks like the page-alignment requirement went away with +.\" commit bd1a68b59c8e3bce45fb76632c64e1e063c3962d +.\" +.\" .... if we expect to later SPLICE_F_MOVE to the cache. +.SH RETURN VALUE +Upon successful completion, +.BR vmsplice () +returns the number of bytes transferred to the pipe. +On error, +.BR vmsplice () +returns \-1 and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +.B SPLICE_F_NONBLOCK +was specified in +.IR flags , +and the operation would block. +.TP +.B EBADF +.I fd +either not valid, or doesn't refer to a pipe. +.TP +.B EINVAL +.I nr_segs +is greater than +.BR IOV_MAX ; +or memory not aligned if +.B SPLICE_F_GIFT +set. +.TP +.B ENOMEM +Out of memory. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.17, +glibc 2.5. +.SH NOTES +.BR vmsplice () +follows the other vectorized read/write type functions when it comes to +limitations on the number of segments being passed in. +This limit is +.B IOV_MAX +as defined in +.IR . +Currently, +.\" UIO_MAXIOV in kernel source +this limit is 1024. +.P +.\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7 +.BR vmsplice () +really supports true splicing only from user memory to a pipe. +In the opposite direction, it actually just copies the data to user space. +But this makes the interface nice and symmetric and enables people to build on +.BR vmsplice () +with room for future improvement in performance. +.SH SEE ALSO +.BR splice (2), +.BR tee (2), +.BR pipe (7) diff --git a/man/man2/vserver.2 b/man/man2/vserver.2 new file mode 100644 index 0000000..5d25ea6 --- /dev/null +++ b/man/man2/vserver.2 @@ -0,0 +1 @@ +.so man2/unimplemented.2 diff --git a/man/man2/wait.2 b/man/man2/wait.2 new file mode 100644 index 0000000..818b976 --- /dev/null +++ b/man/man2/wait.2 @@ -0,0 +1,721 @@ +.\" Copyright (c) 1993 by Thomas Koenig +.\" and Copyright (c) 2004 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 13:30:06 1993 by Rik Faith +.\" Modified Sun Aug 21 17:42:42 1994 by Rik Faith +.\" (Thanks to Koen Holtman ) +.\" Modified Wed May 17 15:54:12 1995 by Rik Faith +.\" To remove *'s from status in macros (Thanks to Michael Shields). +.\" Modified as suggested by Nick Duffek , aeb, 960426 +.\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR. +.\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. +.\" Modified Mon Jul 24 21:37:38 2000 by David A. Wheeler +.\" - noted thread issues. +.\" Modified 26 Jun 01 by Michael Kerrisk +.\" Added __WCLONE, __WALL, and __WNOTHREAD descriptions +.\" Modified 2001-09-25, aeb +.\" Modified 26 Jun 01 by Michael Kerrisk, +.\" Updated notes on setting disposition of SIGCHLD to SIG_IGN +.\" 2004-11-11, mtk +.\" Added waitid(2); added WCONTINUED and WIFCONTINUED() +.\" Added text on SA_NOCLDSTOP +.\" Updated discussion of SA_NOCLDWAIT to reflect 2.6 behavior +.\" Much other text rewritten +.\" 2005-05-10, mtk, __W* flags can't be used with waitid() +.\" 2008-07-04, mtk, removed erroneous text about SA_NOCLDSTOP +.\" +.TH wait 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wait, waitpid, waitid \- wait for process to change state +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "pid_t wait(int *_Nullable " "wstatus" ); +.BI "pid_t waitpid(pid_t " pid ", int *_Nullable " wstatus ", int " options ); +.P +.BI "int waitid(idtype_t " idtype ", id_t " id \ +", siginfo_t *" infop ", int " options ); + /* This is the glibc and POSIX interface; see + NOTES for information on the raw system call. */ +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR waitid (): +.nf + Since glibc 2.26: + _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L +.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) + glibc 2.25 and earlier: + _XOPEN_SOURCE + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +All of these system calls are used to wait for state changes +in a child of the calling process, and obtain information +about the child whose state has changed. +A state change is considered to be: the child terminated; +the child was stopped by a signal; or the child was resumed by a signal. +In the case of a terminated child, performing a wait allows +the system to release the resources associated with the child; +if a wait is not performed, then the terminated child remains in +a "zombie" state (see NOTES below). +.P +If a child has already changed state, then these calls return immediately. +Otherwise, they block until either a child changes state or +a signal handler interrupts the call (assuming that system calls +are not automatically restarted using the +.B SA_RESTART +flag of +.BR sigaction (2)). +In the remainder of this page, a child whose state has changed +and which has not yet been waited upon by one of these system +calls is termed +.IR waitable . +.SS wait() and waitpid() +The +.BR wait () +system call suspends execution of the calling thread until one of its +children terminates. +The call +.I wait(&wstatus) +is equivalent to: +.P +.in +4n +.EX +waitpid(\-1, &wstatus, 0); +.EE +.in +.P +The +.BR waitpid () +system call suspends execution of the calling thread until a +child specified by +.I pid +argument has changed state. +By default, +.BR waitpid () +waits only for terminated children, but this behavior is modifiable +via the +.I options +argument, as described below. +.P +The value of +.I pid +can be: +.TP +.RB "< " \-1 +meaning wait for any child process whose process group ID is +equal to the absolute value of +.IR pid . +.TP +.B \-1 +meaning wait for any child process. +.TP +.B 0 +meaning wait for any child process whose process group ID is +equal to that of the calling process at the time of the call to +.BR waitpid (). +.TP +.RB "> " 0 +meaning wait for the child whose process ID is equal to the +value of +.IR pid . +.P +The value of +.I options +is an OR of zero or more of the following constants: +.TP +.B WNOHANG +return immediately if no child has exited. +.TP +.B WUNTRACED +also return if a child has stopped +(but not traced via +.BR ptrace (2)). +Status for +.I traced +children which have stopped is provided +even if this option is not specified. +.TP +.BR WCONTINUED " (since Linux 2.6.10)" +also return if a stopped child has been resumed by delivery of +.BR SIGCONT . +.P +(For Linux-only options, see below.) +.P +If +.I wstatus +is not NULL, +.BR wait () +and +.BR waitpid () +store status information in the \fIint\fP to which it points. +This integer can be inspected with the following macros (which +take the integer itself as an argument, not a pointer to it, +as is done in +.BR wait () +and +.BR waitpid ()!): +.TP +.BI WIFEXITED( wstatus ) +returns true if the child terminated normally, that is, +by calling +.BR exit (3) +or +.BR _exit (2), +or by returning from main(). +.TP +.BI WEXITSTATUS( wstatus ) +returns the exit status of the child. +This consists of the least significant 8 bits of the +.I status +argument that the child specified in a call to +.BR exit (3) +or +.BR _exit (2) +or as the argument for a return statement in main(). +This macro should be employed only if +.B WIFEXITED +returned true. +.TP +.BI WIFSIGNALED( wstatus ) +returns true if the child process was terminated by a signal. +.TP +.BI WTERMSIG( wstatus ) +returns the number of the signal that caused the child process to +terminate. +This macro should be employed only if +.B WIFSIGNALED +returned true. +.TP +.BI WCOREDUMP( wstatus ) +returns true if the child produced a core dump (see +.BR core (5)). +This macro should be employed only if +.B WIFSIGNALED +returned true. +.IP +This macro is not specified in POSIX.1-2001 and is not available on +some UNIX implementations (e.g., AIX, SunOS). +Therefore, enclose its use inside +.IR "#ifdef WCOREDUMP ... #endif" . +.TP +.BI WIFSTOPPED( wstatus ) +returns true if the child process was stopped by delivery of a signal; +this is possible only if the call was done using +.B WUNTRACED +or when the child is being traced (see +.BR ptrace (2)). +.TP +.BI WSTOPSIG( wstatus ) +returns the number of the signal which caused the child to stop. +This macro should be employed only if +.B WIFSTOPPED +returned true. +.TP +.BI WIFCONTINUED( wstatus ) +(since Linux 2.6.10) +returns true if the child process was resumed by delivery of +.BR SIGCONT . +.SS waitid() +The +.BR waitid () +system call (available since Linux 2.6.9) provides more precise +control over which child state changes to wait for. +.P +The +.I idtype +and +.I id +arguments select the child(ren) to wait for, as follows: +.TP +.IR idtype " == " \fBP_PID\fP +Wait for the child whose process ID matches +.IR id . +.TP +.IR idtype " == " \fBP_PIDFD\fP " (since Linux 5.4)" +.\" commit 3695eae5fee0605f316fbaad0b9e3de791d7dfaf +Wait for the child referred to by the PID file descriptor specified in +.IR id . +(See +.BR pidfd_open (2) +for further information on PID file descriptors.) +.TP +.IR idtype " == " \fBP_PGID\fP +Wait for any child whose process group ID matches +.IR id . +Since Linux 5.4, +.\" commit 821cc7b0b205c0df64cce59aacc330af251fa8f7 +if +.I id +is zero, then wait for any child that is in the same process group +as the caller's process group at the time of the call. +.TP +.IR idtype " == " \fBP_ALL\fP +Wait for any child; +.I id +is ignored. +.P +The child state changes to wait for are specified by ORing +one or more of the following flags in +.IR options : +.TP +.B WEXITED +Wait for children that have terminated. +.TP +.B WSTOPPED +Wait for children that have been stopped by delivery of a signal. +.TP +.B WCONTINUED +Wait for (previously stopped) children that have been +resumed by delivery of +.BR SIGCONT . +.P +The following flags may additionally be ORed in +.IR options : +.TP +.B WNOHANG +As for +.BR waitpid (). +.TP +.B WNOWAIT +Leave the child in a waitable state; a later wait call +can be used to again retrieve the child status information. +.P +Upon successful return, +.BR waitid () +fills in the following fields of the +.I siginfo_t +structure pointed to by +.IR infop : +.TP +\fIsi_pid\fP +The process ID of the child. +.TP +\fIsi_uid\fP +The real user ID of the child. +(This field is not set on most other implementations.) +.TP +\fIsi_signo\fP +Always set to +.BR SIGCHLD . +.TP +\fIsi_status\fP +Either the exit status of the child, as given to +.BR _exit (2) +(or +.BR exit (3)), +or the signal that caused the child to terminate, stop, or continue. +The +.I si_code +field can be used to determine how to interpret this field. +.TP +\fIsi_code\fP +Set to one of: +.B CLD_EXITED +(child called +.BR _exit (2)); +.B CLD_KILLED +(child killed by signal); +.B CLD_DUMPED +(child killed by signal, and dumped core); +.B CLD_STOPPED +(child stopped by signal); +.B CLD_TRAPPED +(traced child has trapped); or +.B CLD_CONTINUED +(child continued by +.BR SIGCONT ). +.P +If +.B WNOHANG +was specified in +.I options +and there were no children in a waitable state, then +.BR waitid () +returns 0 immediately and +the state of the +.I siginfo_t +structure pointed to by +.I infop +depends on the implementation. +To (portably) distinguish this case from that where a child was in a +waitable state, zero out the +.I si_pid +field before the call and check for a nonzero value in this field +after the call returns. +.P +POSIX.1-2008 Technical Corrigendum 1 (2013) adds the requirement that when +.B WNOHANG +is specified in +.I options +and there were no children in a waitable state, then +.BR waitid () +should zero out the +.I si_pid +and +.I si_signo +fields of the structure. +On Linux and other implementations that adhere to this requirement, +it is not necessary to zero out the +.I si_pid +field before calling +.BR waitid (). +However, +not all implementations follow the POSIX.1 specification on this point. +.\" POSIX.1-2001 leaves this possibility unspecified; most +.\" implementations (including Linux) zero out the structure +.\" in this case, but at least one implementation (AIX 5.1) +.\" does not -- MTK Nov 04 +.SH RETURN VALUE +.BR wait (): +on success, returns the process ID of the terminated child; +on failure, \-1 is returned. +.P +.BR waitpid (): +on success, returns the process ID of the child whose state has changed; +if +.B WNOHANG +was specified and one or more child(ren) specified by +.I pid +exist, but have not yet changed state, then 0 is returned. +On failure, \-1 is returned. +.P +.BR waitid (): +returns 0 on success or +if +.B WNOHANG +was specified and no child(ren) specified by +.I id +has yet changed state; +on failure, \-1 is returned. +.\" FIXME As reported by Vegard Nossum, if infop is NULL, then waitid() +.\" returns the PID of the child. Either this is a bug, or it is intended +.\" behavior that needs to be documented. See my Jan 2009 LKML mail +.\" "waitid() return value strangeness when infop is NULL". +.P +On failure, each of these calls sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The PID file descriptor specified in +.I id +is nonblocking and the process that it refers to has not terminated. +.TP +.B ECHILD +(for +.BR wait ()) +The calling process does not have any unwaited-for children. +.TP +.B ECHILD +(for +.BR waitpid () +or +.BR waitid ()) +The process specified by +.I pid +.RB ( waitpid ()) +or +.I idtype +and +.I id +.RB ( waitid ()) +does not exist or is not a child of the calling process. +(This can happen for one's own child if the action for +.B SIGCHLD +is set to +.BR SIG_IGN . +See also the \fILinux Notes\fP section about threads.) +.TP +.B EINTR +.B WNOHANG +was not set and an unblocked signal or a +.B SIGCHLD +was caught; see +.BR signal (7). +.TP +.B EINVAL +The +.I options +argument was invalid. +.TP +.B ESRCH +(for +.BR wait () +or +.BR waitpid ()) +.I pid +is equal to +.BR INT_MIN . +.SH VERSIONS +.SS C library/kernel differences +.BR wait () +is actually a library function that (in glibc) is implemented as a call to +.BR wait4 (2). +.P +On some architectures, there is no +.BR waitpid () +system call; +.\" e.g., i386 has the system call, but not x86-64 +instead, this interface is implemented via a C library +wrapper function that calls +.BR wait4 (2). +.P +The raw +.BR waitid () +system call takes a fifth argument, of type +.IR "struct rusage\ *" . +If this argument is non-NULL, +then it is used to return resource usage information about the child, +in the same manner as +.BR wait4 (2). +See +.BR getrusage (2) +for details. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, 4.3BSD, POSIX.1-2001. +.SH NOTES +A child that terminates, but has not been waited for becomes a "zombie". +The kernel maintains a minimal set of information about the zombie +process (PID, termination status, resource usage information) +in order to allow the parent to later perform a wait to obtain +information about the child. +As long as a zombie is not removed from the system via a wait, +it will consume a slot in the kernel process table, and if +this table fills, it will not be possible to create further processes. +If a parent process terminates, then its "zombie" children (if any) +are adopted by +.BR init (1), +(or by the nearest "subreaper" process as defined through the use of the +.BR prctl (2) +.B PR_SET_CHILD_SUBREAPER +operation); +.BR init (1) +automatically performs a wait to remove the zombies. +.P +POSIX.1-2001 specifies that if the disposition of +.B SIGCHLD +is set to +.B SIG_IGN +or the +.B SA_NOCLDWAIT +flag is set for +.B SIGCHLD +(see +.BR sigaction (2)), +then children that terminate do not become zombies and a call to +.BR wait () +or +.BR waitpid () +will block until all children have terminated, and then fail with +.I errno +set to +.BR ECHILD . +(The original POSIX standard left the behavior of setting +.B SIGCHLD +to +.B SIG_IGN +unspecified. +Note that even though the default disposition of +.B SIGCHLD +is "ignore", explicitly setting the disposition to +.B SIG_IGN +results in different treatment of zombie process children.) +.P +Linux 2.6 conforms to the POSIX requirements. +However, Linux 2.4 (and earlier) does not: +if a +.BR wait () +or +.BR waitpid () +call is made while +.B SIGCHLD +is being ignored, the call behaves just as though +.B SIGCHLD +were not being ignored, that is, the call blocks until the next child +terminates and then returns the process ID and status of that child. +.SS Linux notes +In the Linux kernel, a kernel-scheduled thread is not a distinct +construct from a process. +Instead, a thread is simply a process +that is created using the Linux-unique +.BR clone (2) +system call; other routines such as the portable +.BR pthread_create (3) +call are implemented using +.BR clone (2). +Before Linux 2.4, a thread was just a special case of a process, +and as a consequence one thread could not wait on the children +of another thread, even when the latter belongs to the same thread group. +However, POSIX prescribes such functionality, and since Linux 2.4 +a thread can, and by default will, wait on children of other threads +in the same thread group. +.P +The following Linux-specific +.I options +are for use with children created using +.BR clone (2); +they can also, since Linux 4.7, +.\" commit 91c4e8ea8f05916df0c8a6f383508ac7c9e10dba +be used with +.BR waitid (): +.TP +.B __WCLONE +.\" since 0.99pl10 +Wait for "clone" children only. +If omitted, then wait for "non-clone" children only. +(A "clone" child is one which delivers no signal, or a signal other than +.B SIGCHLD +to its parent upon termination.) +This option is ignored if +.B __WALL +is also specified. +.TP +.BR __WALL " (since Linux 2.4)" +.\" since patch-2.3.48 +Wait for all children, regardless of +type ("clone" or "non-clone"). +.TP +.BR __WNOTHREAD " (since Linux 2.4)" +.\" since patch-2.4.0-test8 +Do not wait for children of other threads in +the same thread group. +This was the default before Linux 2.4. +.P +Since Linux 4.7, +.\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c +.\" prevents cases where an unreapable zombie is created if +.\" /sbin/init doesn't use __WALL. +the +.B __WALL +flag is automatically implied if the child is being ptraced. +.SH BUGS +According to POSIX.1-2008, an application calling +.BR waitid () +must ensure that +.I infop +points to a +.I siginfo_t +structure (i.e., that it is a non-null pointer). +On Linux, if +.I infop +is NULL, +.BR waitid () +succeeds, and returns the process ID of the waited-for child. +Applications should avoid relying on this inconsistent, +nonstandard, and unnecessary feature. +.SH EXAMPLES +.\" fork.2 refers to this example program. +The following program demonstrates the use of +.BR fork (2) +and +.BR waitpid (). +The program creates a child process. +If no command-line argument is supplied to the program, +then the child suspends its execution using +.BR pause (2), +to allow the user to send signals to the child. +Otherwise, if a command-line argument is supplied, +then the child exits immediately, +using the integer supplied on the command line as the exit status. +The parent process executes a loop that monitors the child using +.BR waitpid (), +and uses the W*() macros described above to analyze the wait status value. +.P +The following shell session demonstrates the use of the program: +.P +.in +4n +.EX +.RB "$" " ./a.out &" +Child PID is 32360 +[1] 32359 +.RB "$" " kill \-STOP 32360" +stopped by signal 19 +.RB "$" " kill \-CONT 32360" +continued +.RB "$" " kill \-TERM 32360" +killed by signal 15 +[1]+ Done ./a.out +$ +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (wait.c) +.EX +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int wstatus; + pid_t cpid, w; +\& + cpid = fork(); + if (cpid == \-1) { + perror("fork"); + exit(EXIT_FAILURE); + } +\& + if (cpid == 0) { /* Code executed by child */ + printf("Child PID is %jd\en", (intmax_t) getpid()); + if (argc == 1) + pause(); /* Wait for signals */ + _exit(atoi(argv[1])); +\& + } else { /* Code executed by parent */ + do { + w = waitpid(cpid, &wstatus, WUNTRACED | WCONTINUED); + if (w == \-1) { + perror("waitpid"); + exit(EXIT_FAILURE); + } +\& + if (WIFEXITED(wstatus)) { + printf("exited, status=%d\en", WEXITSTATUS(wstatus)); + } else if (WIFSIGNALED(wstatus)) { + printf("killed by signal %d\en", WTERMSIG(wstatus)); + } else if (WIFSTOPPED(wstatus)) { + printf("stopped by signal %d\en", WSTOPSIG(wstatus)); + } else if (WIFCONTINUED(wstatus)) { + printf("continued\en"); + } + } while (!WIFEXITED(wstatus) && !WIFSIGNALED(wstatus)); + exit(EXIT_SUCCESS); + } +} +.EE +.\" SRC END +.SH SEE ALSO +.BR _exit (2), +.BR clone (2), +.BR fork (2), +.BR kill (2), +.BR ptrace (2), +.BR sigaction (2), +.BR signal (2), +.BR wait4 (2), +.BR pthread_create (3), +.BR core (5), +.BR credentials (7), +.BR signal (7) diff --git a/man/man2/wait3.2 b/man/man2/wait3.2 new file mode 100644 index 0000000..097794b --- /dev/null +++ b/man/man2/wait3.2 @@ -0,0 +1 @@ +.so man2/wait4.2 diff --git a/man/man2/wait4.2 b/man/man2/wait4.2 new file mode 100644 index 0000000..92a4bda --- /dev/null +++ b/man/man2/wait4.2 @@ -0,0 +1,169 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (c) 2004 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 13:32:44 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Jun 23 14:09:52 1997 by aeb - add EINTR. +.\" Modified Tue Jul 7 12:26:42 1998 by aeb - changed return value wait3 +.\" Modified 2004-11-11, Michael Kerrisk +.\" Rewrote much of this page, and removed much duplicated text, +.\" replacing with pointers to wait.2 +.\" +.TH wait4 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wait3, wait4 \- wait for process to change state, BSD style +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "pid_t wait3(int *_Nullable " "wstatus" ", int " options , +.BI " struct rusage *_Nullable " rusage ); +.BI "pid_t wait4(pid_t " pid ", int *_Nullable " wstatus ", int " options , +.BI " struct rusage *_Nullable " rusage ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wait3 (): +.nf + Since glibc 2.26: + _DEFAULT_SOURCE + || (_XOPEN_SOURCE >= 500 && + ! (_POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 600)) + From glibc 2.19 to glibc 2.25: + _DEFAULT_SOURCE || _XOPEN_SOURCE >= 500 + glibc 2.19 and earlier: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.P +.BR wait4 (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +These functions are nonstandard; in new programs, the use of +.BR waitpid (2) +or +.BR waitid (2) +is preferable. +.P +The +.BR wait3 () +and +.BR wait4 () +system calls are similar to +.BR waitpid (2), +but additionally return resource usage information about the +child in the structure pointed to by +.IR rusage . +.P +Other than the use of the +.I rusage +argument, the following +.BR wait3 () +call: +.P +.in +4n +.EX +wait3(wstatus, options, rusage); +.EE +.in +.P +is equivalent to: +.P +.in +4n +.EX +waitpid(\-1, wstatus, options); +.EE +.in +.P +Similarly, the following +.BR wait4 () +call: +.P +.in +4n +.EX +wait4(pid, wstatus, options, rusage); +.EE +.in +.P +is equivalent to: +.P +.in +4n +.EX +waitpid(pid, wstatus, options); +.EE +.in +.P +In other words, +.BR wait3 () +waits of any child, while +.BR wait4 () +can be used to select a specific child, or children, on which to wait. +See +.BR wait (2) +for further details. +.P +If +.I rusage +is not NULL, the +.I struct rusage +to which it points will be filled with accounting information +about the child. +See +.BR getrusage (2) +for details. +.SH RETURN VALUE +As for +.BR waitpid (2). +.SH ERRORS +As for +.BR waitpid (2). +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +.P +SUSv1 included a specification of +.BR wait3 (); +SUSv2 included +.BR wait3 (), +but marked it LEGACY; +SUSv3 removed it. +.P +Including +.I +is not required these days, but increases portability. +(Indeed, +.I +defines the +.I rusage +structure with fields of type +.I struct timeval +defined in +.IR .) +.SS C library/kernel differences +On Linux, +.BR wait3 () +is a library function implemented on top of the +.BR wait4 () +system call. +.SH SEE ALSO +.BR fork (2), +.BR getrusage (2), +.BR sigaction (2), +.BR signal (2), +.BR wait (2), +.BR signal (7) diff --git a/man/man2/waitid.2 b/man/man2/waitid.2 new file mode 100644 index 0000000..0605b35 --- /dev/null +++ b/man/man2/waitid.2 @@ -0,0 +1 @@ +.so man2/wait.2 diff --git a/man/man2/waitpid.2 b/man/man2/waitpid.2 new file mode 100644 index 0000000..0605b35 --- /dev/null +++ b/man/man2/waitpid.2 @@ -0,0 +1 @@ +.so man2/wait.2 diff --git a/man/man2/write.2 b/man/man2/write.2 new file mode 100644 index 0000000..3e87069 --- /dev/null +++ b/man/man2/write.2 @@ -0,0 +1,329 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 13:35:59 1993 by Rik Faith +.\" Modified Sun Nov 28 17:19:01 1993 by Rik Faith +.\" Modified Sat Jan 13 12:58:08 1996 by Michael Haardt +.\" +.\" Modified Sun Jul 21 18:59:33 1996 by Andries Brouwer +.\" 2001-12-13 added remark by Zack Weinberg +.\" 2007-06-18 mtk: +.\" Added details about seekable files and file offset. +.\" Noted that write() may write less than 'count' bytes, and +.\" gave some examples of why this might occur. +.\" Noted what happens if write() is interrupted by a signal. +.\" +.TH write 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +write \- write to a file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t write(int " fd ", const void " buf [. count "], size_t " count ); +.fi +.SH DESCRIPTION +.BR write () +writes up to +.I count +bytes from the buffer starting at +.I buf +to the file referred to by the file descriptor +.IR fd . +.P +The number of bytes written may be less than +.I count +if, for example, +there is insufficient space on the underlying physical medium, or the +.B RLIMIT_FSIZE +resource limit is encountered (see +.BR setrlimit (2)), +or the call was interrupted by a signal +handler after having written less than +.I count +bytes. +(See also +.BR pipe (7).) +.P +For a seekable file (i.e., one to which +.BR lseek (2) +may be applied, for example, a regular file) +writing takes place at the file offset, +and the file offset is incremented by +the number of bytes actually written. +If the file was +.BR open (2)ed +with +.BR O_APPEND , +the file offset is first set to the end of the file before writing. +The adjustment of the file offset and the write operation +are performed as an atomic step. +.P +POSIX requires that a +.BR read (2) +that can be proved to occur after a +.BR write () +has returned will return the new data. +Note that not all filesystems are POSIX conforming. +.P +According to POSIX.1, if +.I count +is greater than +.BR SSIZE_MAX , +the result is implementation-defined; +see NOTES for the upper limit on Linux. +.SH RETURN VALUE +On success, the number of bytes written is returned. +On error, \-1 is returned, and \fIerrno\fP is set +to indicate the error. +.P +Note that a successful +.BR write () +may transfer fewer than +.I count +bytes. +Such partial writes can occur for various reasons; +for example, because there was insufficient space on the disk device +to write all of the requested bytes, or because a blocked +.BR write () +to a socket, pipe, or similar was interrupted by a signal handler +after it had transferred some, but before it had transferred all +of the requested bytes. +In the event of a partial write, the caller can make another +.BR write () +call to transfer the remaining bytes. +The subsequent call will either transfer further bytes or +may result in an error (e.g., if the disk is now full). +.P +If \fIcount\fP is zero and +.I fd +refers to a regular file, then +.BR write () +may return a failure status if one of the errors below is detected. +If no errors are detected, or error detection is not performed, +0 is returned without causing any other effect. +If +\fIcount\fP is zero and +.I fd +refers to a file other than a regular file, +the results are not specified. +.SH ERRORS +.TP +.B EAGAIN +The file descriptor +.I fd +refers to a file other than a socket and has been marked nonblocking +.RB ( O_NONBLOCK ), +and the write would block. +See +.BR open (2) +for further details on the +.B O_NONBLOCK +flag. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.\" Actually EAGAIN on Linux +The file descriptor +.I fd +refers to a socket and has been marked nonblocking +.RB ( O_NONBLOCK ), +and the write would block. +POSIX.1-2001 allows either error to be returned for this case, +and does not require these constants to have the same value, +so a portable application should check for both possibilities. +.TP +.B EBADF +.I fd +is not a valid file descriptor or is not open for writing. +.TP +.B EDESTADDRREQ +.I fd +refers to a datagram socket for which a peer address has not been set using +.BR connect (2). +.TP +.B EDQUOT +The user's quota of disk blocks on the filesystem containing the file +referred to by +.I fd +has been exhausted. +.TP +.B EFAULT +.I buf +is outside your accessible address space. +.TP +.B EFBIG +An attempt was made to write a file that exceeds the implementation-defined +maximum file size or the process's file size limit, +or to write at a position past the maximum allowed offset. +.TP +.B EINTR +The call was interrupted by a signal before any data was written; see +.BR signal (7). +.TP +.B EINVAL +.I fd +is attached to an object which is unsuitable for writing; +or the file was opened with the +.B O_DIRECT +flag, and either the address specified in +.IR buf , +the value specified in +.IR count , +or the file offset is not suitably aligned. +.TP +.B EIO +A low-level I/O error occurred while modifying the inode. +This error may relate to the write-back of data written by an earlier +.BR write (), +which may have been issued to a different file descriptor on +the same file. +Since Linux 4.13, errors from write-back come +with a promise that they +.I may +be reported by subsequent. +.BR write () +requests, and +.I will +be reported by a subsequent +.BR fsync (2) +(whether or not they were also reported by +.BR write ()). +.\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750 +An alternate cause of +.B EIO +on networked filesystems is when an advisory lock had been taken out +on the file descriptor and this lock has been lost. +See the +.I "Lost locks" +section of +.BR fcntl (2) +for further details. +.TP +.B ENOSPC +The device containing the file referred to by +.I fd +has no room for the data. +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B EPIPE +.I fd +is connected to a pipe or socket whose reading end is closed. +When this happens the writing process will also receive a +.B SIGPIPE +signal. +(Thus, the write return value is seen only if the program +catches, blocks or ignores this signal.) +.P +Other errors may occur, depending on the object connected to +.IR fd . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, 4.3BSD, POSIX.1-2001. +.\" SVr4 documents additional error +.\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE. +.P +Under SVr4 a write may be interrupted and return +.B EINTR +at any point, +not just before any data is written. +.SH NOTES +A successful return from +.BR write () +does not make any guarantee that data has been committed to disk. +On some filesystems, including NFS, it does not even guarantee +that space has successfully been reserved for the data. +In this case, +some errors might be delayed until a future +.BR write (), +.BR fsync (2), +or even +.BR close (2). +The only way to be sure is to call +.BR fsync (2) +after you are done writing all your data. +.P +If a +.BR write () +is interrupted by a signal handler before any bytes are written, +then the call fails with the error +.BR EINTR ; +if it is interrupted after at least one byte has been written, +the call succeeds, and returns the number of bytes written. +.P +On Linux, +.BR write () +(and similar system calls) will transfer at most +0x7ffff000 (2,147,479,552) bytes, +returning the number of bytes actually transferred. +.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 +(This is true on both 32-bit and 64-bit systems.) +.P +An error return value while performing +.BR write () +using direct I/O does not mean the +entire write has failed. +Partial data may be written +and the data at the file offset on which the +.BR write () +was attempted should be considered inconsistent. +.SH BUGS +According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 +("Thread Interactions with Regular File Operations"): +.P +.RS 4 +All of the following functions shall be atomic with respect to +each other in the effects specified in POSIX.1-2008 when they +operate on regular files or symbolic links: ... +.RE +.P +Among the APIs subsequently listed are +.BR write () +and +.BR writev (2). +And among the effects that should be atomic across threads (and processes) +are updates of the file offset. +However, before Linux 3.14, +this was not the case: if two processes that share +an open file description (see +.BR open (2)) +perform a +.BR write () +(or +.BR writev (2)) +at the same time, then the I/O operations were not atomic +with respect to updating the file offset, +with the result that the blocks of data output by the two processes +might (incorrectly) overlap. +This problem was fixed in Linux 3.14. +.\" http://thread.gmane.org/gmane.linux.kernel/1649458 +.\" From: Michael Kerrisk (man-pages gmail.com> +.\" Subject: Update of file offset on write() etc. is non-atomic with I/O +.\" Date: 2014-02-17 15:41:37 GMT +.\" Newsgroups: gmane.linux.kernel, gmane.linux.file-systems +.\" commit 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4 +.\" Author: Linus Torvalds +.\" Date: Mon Mar 3 09:36:58 2014 -0800 +.\" +.\" vfs: atomic f_pos accesses as per POSIX +.SH SEE ALSO +.BR close (2), +.BR fcntl (2), +.BR fsync (2), +.BR ioctl (2), +.BR lseek (2), +.BR open (2), +.BR pwrite (2), +.BR read (2), +.BR select (2), +.BR writev (2), +.BR fwrite (3) diff --git a/man/man2/writev.2 b/man/man2/writev.2 new file mode 100644 index 0000000..54e3384 --- /dev/null +++ b/man/man2/writev.2 @@ -0,0 +1 @@ +.so man2/readv.2 diff --git a/man/man2type/open_how.2type b/man/man2type/open_how.2type new file mode 100644 index 0000000..b2e3fbf --- /dev/null +++ b/man/man2type/open_how.2type @@ -0,0 +1,51 @@ +.\" Copyright (c) 2022 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH open_how 2type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +open_how \- how to open a pathname +.SH LIBRARY +Linux kernel headers +.SH SYNOPSIS +.EX +.B #include +.P +.B struct open_how { +.BR " u64 flags;" " /* " O_ "* flags */" +.BR " u64 mode;" " /* Mode for " O_ { CREAT , TMPFILE "} */" +.BR " u64 resolve;" " /* " RESOLVE_ "* flags */" + /* ... */ +.B }; +.EE +.SH DESCRIPTION +Specifies how a pathname should be opened. +.P +The fields are as follows: +.TP +.I flags +This field specifies the file creation and file status flags +to use when opening the file. +.TP +.I mode +This field specifies the mode for the new file. +.TP +.I resolve +This is a bit mask of flags that modify the way in which +.I all +components of a pathname will be resolved +(see +.BR path_resolution (7) +for background information). +.SH VERSIONS +Extra fields may be appended to the structure, +with a zero value in a new field resulting in +the kernel behaving as though that extension field was not present. +Therefore, a user +.I must +zero-fill this structure on initialization. +.SH STANDARDS +Linux. +.SH SEE ALSO +.BR openat2 (2) diff --git a/man/man3/CIRCLEQ_EMPTY.3 b/man/man3/CIRCLEQ_EMPTY.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_EMPTY.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_ENTRY.3 b/man/man3/CIRCLEQ_ENTRY.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_FIRST.3 b/man/man3/CIRCLEQ_FIRST.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_FIRST.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_FOREACH.3 b/man/man3/CIRCLEQ_FOREACH.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_FOREACH.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_FOREACH_REVERSE.3 b/man/man3/CIRCLEQ_FOREACH_REVERSE.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_FOREACH_REVERSE.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_HEAD.3 b/man/man3/CIRCLEQ_HEAD.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_HEAD_INITIALIZER.3 b/man/man3/CIRCLEQ_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_INIT.3 b/man/man3/CIRCLEQ_INIT.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_INIT.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_INSERT_AFTER.3 b/man/man3/CIRCLEQ_INSERT_AFTER.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_INSERT_BEFORE.3 b/man/man3/CIRCLEQ_INSERT_BEFORE.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_INSERT_BEFORE.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_INSERT_HEAD.3 b/man/man3/CIRCLEQ_INSERT_HEAD.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_INSERT_TAIL.3 b/man/man3/CIRCLEQ_INSERT_TAIL.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_LAST.3 b/man/man3/CIRCLEQ_LAST.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_LAST.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_LOOP_NEXT.3 b/man/man3/CIRCLEQ_LOOP_NEXT.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_LOOP_NEXT.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_LOOP_PREV.3 b/man/man3/CIRCLEQ_LOOP_PREV.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_LOOP_PREV.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_NEXT.3 b/man/man3/CIRCLEQ_NEXT.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_NEXT.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_PREV.3 b/man/man3/CIRCLEQ_PREV.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_PREV.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CIRCLEQ_REMOVE.3 b/man/man3/CIRCLEQ_REMOVE.3 new file mode 100644 index 0000000..ed0fc9a --- /dev/null +++ b/man/man3/CIRCLEQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/circleq.3 diff --git a/man/man3/CMSG_ALIGN.3 b/man/man3/CMSG_ALIGN.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_ALIGN.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CMSG_DATA.3 b/man/man3/CMSG_DATA.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_DATA.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CMSG_FIRSTHDR.3 b/man/man3/CMSG_FIRSTHDR.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_FIRSTHDR.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CMSG_LEN.3 b/man/man3/CMSG_LEN.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_LEN.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CMSG_NXTHDR.3 b/man/man3/CMSG_NXTHDR.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_NXTHDR.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CMSG_SPACE.3 b/man/man3/CMSG_SPACE.3 new file mode 100644 index 0000000..ad67f43 --- /dev/null +++ b/man/man3/CMSG_SPACE.3 @@ -0,0 +1 @@ +.so man3/cmsg.3 diff --git a/man/man3/CPU_ALLOC.3 b/man/man3/CPU_ALLOC.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ALLOC.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_ALLOC_SIZE.3 b/man/man3/CPU_ALLOC_SIZE.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ALLOC_SIZE.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_AND.3 b/man/man3/CPU_AND.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_AND.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_AND_S.3 b/man/man3/CPU_AND_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_AND_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_CLR.3 b/man/man3/CPU_CLR.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_CLR.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_CLR_S.3 b/man/man3/CPU_CLR_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_CLR_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_COUNT.3 b/man/man3/CPU_COUNT.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_COUNT.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_COUNT_S.3 b/man/man3/CPU_COUNT_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_COUNT_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_EQUAL.3 b/man/man3/CPU_EQUAL.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_EQUAL.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_EQUAL_S.3 b/man/man3/CPU_EQUAL_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_EQUAL_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_FREE.3 b/man/man3/CPU_FREE.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_FREE.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_ISSET.3 b/man/man3/CPU_ISSET.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ISSET.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_ISSET_S.3 b/man/man3/CPU_ISSET_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ISSET_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_OR.3 b/man/man3/CPU_OR.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_OR.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_OR_S.3 b/man/man3/CPU_OR_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_OR_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_SET.3 b/man/man3/CPU_SET.3 new file mode 100644 index 0000000..b937a8e --- /dev/null +++ b/man/man3/CPU_SET.3 @@ -0,0 +1,348 @@ +.\" Copyright (C) 2006 Michael Kerrisk +.\" and Copyright (C) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH CPU_SET 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, +CPU_AND, CPU_OR, CPU_XOR, CPU_EQUAL, +CPU_ALLOC, CPU_ALLOC_SIZE, CPU_FREE, +CPU_SET_S, CPU_CLR_S, CPU_ISSET_S, CPU_ZERO_S, +CPU_COUNT_S, CPU_AND_S, CPU_OR_S, CPU_XOR_S, CPU_EQUAL_S \- +macros for manipulating CPU sets +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "void CPU_ZERO(cpu_set_t *" set ); +.P +.BI "void CPU_SET(int " cpu ", cpu_set_t *" set ); +.BI "void CPU_CLR(int " cpu ", cpu_set_t *" set ); +.BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set ); +.P +.BI "int CPU_COUNT(cpu_set_t *" set ); +.P +.BI "void CPU_AND(cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_OR(cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_XOR(cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.P +.BI "int CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 ); +.P +.BI "cpu_set_t *CPU_ALLOC(int " num_cpus ); +.BI "void CPU_FREE(cpu_set_t *" set ); +.BI "size_t CPU_ALLOC_SIZE(int " num_cpus ); +.P +.BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set ); +.P +.BI "void CPU_SET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); +.BI "void CPU_CLR_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); +.BI "int CPU_ISSET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); +.P +.BI "int CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set ); +.P +.BI "void CPU_AND_S(size_t " setsize ", cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_OR_S(size_t " setsize ", cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.BI "void CPU_XOR_S(size_t " setsize ", cpu_set_t *" destset , +.BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); +.P +.BI "int CPU_EQUAL_S(size_t " setsize ", cpu_set_t *" set1 \ +", cpu_set_t *" set2 ); +.fi +.SH DESCRIPTION +The +.I cpu_set_t +data structure represents a set of CPUs. +CPU sets are used by +.BR sched_setaffinity (2) +and similar interfaces. +.P +The +.I cpu_set_t +data type is implemented as a bit mask. +However, the data structure should be treated as opaque: +all manipulation of CPU sets should be done via the macros +described in this page. +.P +The following macros are provided to operate on the CPU set +.IR set : +.TP +.BR CPU_ZERO () +Clears +.IR set , +so that it contains no CPUs. +.TP +.BR CPU_SET () +Add CPU +.I cpu +to +.IR set . +.TP +.BR CPU_CLR () +Remove CPU +.I cpu +from +.IR set . +.TP +.BR CPU_ISSET () +Test to see if CPU +.I cpu +is a member of +.IR set . +.TP +.BR CPU_COUNT () +Return the number of CPUs in +.IR set . +.P +Where a +.I cpu +argument is specified, it should not produce side effects, +since the above macros may evaluate the argument more than once. +.P +The first CPU on the system corresponds to a +.I cpu +value of 0, the next CPU corresponds to a +.I cpu +value of 1, and so on. +No assumptions should be made about particular CPUs being +available, or the set of CPUs being contiguous, since CPUs can +be taken offline dynamically or be otherwise absent. +The constant +.B CPU_SETSIZE +(currently 1024) specifies a value one greater than the maximum CPU +number that can be stored in +.IR cpu_set_t . +.P +The following macros perform logical operations on CPU sets: +.TP +.BR CPU_AND () +Store the intersection of the sets +.I srcset1 +and +.I srcset2 +in +.I destset +(which may be one of the source sets). +.TP +.BR CPU_OR () +Store the union of the sets +.I srcset1 +and +.I srcset2 +in +.I destset +(which may be one of the source sets). +.TP +.BR CPU_XOR () +Store the XOR of the sets +.I srcset1 +and +.I srcset2 +in +.I destset +(which may be one of the source sets). +The XOR means the set of CPUs that are in either +.I srcset1 +or +.IR srcset2 , +but not both. +.TP +.BR CPU_EQUAL () +Test whether two CPU set contain exactly the same CPUs. +.SS Dynamically sized CPU sets +Because some applications may require the ability to dynamically +size CPU sets (e.g., to allocate sets larger than that +defined by the standard +.I cpu_set_t +data type), glibc nowadays provides a set of macros to support this. +.P +The following macros are used to allocate and deallocate CPU sets: +.TP +.BR CPU_ALLOC () +Allocate a CPU set large enough to hold CPUs +in the range 0 to +.IR num_cpus\-1 . +.TP +.BR CPU_ALLOC_SIZE () +Return the size in bytes of the CPU set that would be needed to +hold CPUs in the range 0 to +.IR num_cpus\-1 . +This macro provides the value that can be used for the +.I setsize +argument in the +.BR CPU_*_S () +macros described below. +.TP +.BR CPU_FREE () +Free a CPU set previously allocated by +.BR CPU_ALLOC (). +.P +The macros whose names end with "_S" are the analogs of +the similarly named macros without the suffix. +These macros perform the same tasks as their analogs, +but operate on the dynamically allocated CPU set(s) whose size is +.I setsize +bytes. +.SH RETURN VALUE +.BR CPU_ISSET () +and +.BR CPU_ISSET_S () +return nonzero if +.I cpu +is in +.IR set ; +otherwise, it returns 0. +.P +.BR CPU_COUNT () +and +.BR CPU_COUNT_S () +return the number of CPUs in +.IR set . +.P +.BR CPU_EQUAL () +and +.BR CPU_EQUAL_S () +return nonzero if the two CPU sets are equal; otherwise they return 0. +.P +.BR CPU_ALLOC () +returns a pointer on success, or NULL on failure. +(Errors are as for +.BR malloc (3).) +.P +.BR CPU_ALLOC_SIZE () +returns the number of bytes required to store a +CPU set of the specified cardinality. +.P +The other functions do not return a value. +.SH STANDARDS +Linux. +.SH HISTORY +The +.BR CPU_ZERO (), +.BR CPU_SET (), +.BR CPU_CLR (), +and +.BR CPU_ISSET () +macros were added in glibc 2.3.3. +.P +.BR CPU_COUNT () +first appeared in glibc 2.6. +.P +.BR CPU_AND (), +.BR CPU_OR (), +.BR CPU_XOR (), +.BR CPU_EQUAL (), +.BR CPU_ALLOC (), +.BR CPU_ALLOC_SIZE (), +.BR CPU_FREE (), +.BR CPU_ZERO_S (), +.BR CPU_SET_S (), +.BR CPU_CLR_S (), +.BR CPU_ISSET_S (), +.BR CPU_AND_S (), +.BR CPU_OR_S (), +.BR CPU_XOR_S (), +and +.BR CPU_EQUAL_S () +first appeared in glibc 2.7. +.SH NOTES +To duplicate a CPU set, use +.BR memcpy (3). +.P +Since CPU sets are bit masks allocated in units of long words, +the actual number of CPUs in a dynamically +allocated CPU set will be rounded up to the next multiple of +.IR "sizeof(unsigned long)" . +An application should consider the contents of these extra bits +to be undefined. +.P +Notwithstanding the similarity in the names, +note that the constant +.B CPU_SETSIZE +indicates the number of CPUs in the +.I cpu_set_t +data type (thus, it is effectively a count of the bits in the bit mask), +while the +.I setsize +argument of the +.BR CPU_*_S () +macros is a size in bytes. +.P +The data types for arguments and return values shown +in the SYNOPSIS are hints what about is expected in each case. +However, since these interfaces are implemented as macros, +the compiler won't necessarily catch all type errors +if you violate the suggestions. +.SH BUGS +On 32-bit platforms with glibc 2.8 and earlier, +.BR CPU_ALLOC () +allocates twice as much space as is required, and +.BR CPU_ALLOC_SIZE () +returns a value twice as large as it should. +This bug should not affect the semantics of a program, +but does result in wasted memory +and less efficient operation of the macros that +operate on dynamically allocated CPU sets. +These bugs are fixed in glibc 2.9. +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7029 +.SH EXAMPLES +The following program demonstrates the use of some of the macros +used for dynamically allocated CPU sets. +.P +.\" SRC BEGIN (CPU_SET.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +\& +#include +\& +int +main(int argc, char *argv[]) +{ + cpu_set_t *cpusetp; + size_t size, num_cpus; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + num_cpus = atoi(argv[1]); +\& + cpusetp = CPU_ALLOC(num_cpus); + if (cpusetp == NULL) { + perror("CPU_ALLOC"); + exit(EXIT_FAILURE); + } +\& + size = CPU_ALLOC_SIZE(num_cpus); +\& + CPU_ZERO_S(size, cpusetp); + for (size_t cpu = 0; cpu < num_cpus; cpu += 2) + CPU_SET_S(cpu, size, cpusetp); +\& + printf("CPU_COUNT() of set: %d\en", CPU_COUNT_S(size, cpusetp)); +\& + CPU_FREE(cpusetp); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sched_setaffinity (2), +.BR pthread_attr_setaffinity_np (3), +.BR pthread_setaffinity_np (3), +.BR cpuset (7) diff --git a/man/man3/CPU_SET_S.3 b/man/man3/CPU_SET_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_SET_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_XOR.3 b/man/man3/CPU_XOR.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_XOR.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_XOR_S.3 b/man/man3/CPU_XOR_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_XOR_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_ZERO.3 b/man/man3/CPU_ZERO.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ZERO.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/CPU_ZERO_S.3 b/man/man3/CPU_ZERO_S.3 new file mode 100644 index 0000000..cdc74d4 --- /dev/null +++ b/man/man3/CPU_ZERO_S.3 @@ -0,0 +1 @@ +.so man3/CPU_SET.3 diff --git a/man/man3/DES_FAILED.3 b/man/man3/DES_FAILED.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man/man3/DES_FAILED.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man/man3/FD_CLR.3 b/man/man3/FD_CLR.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man3/FD_CLR.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man3/FD_ISSET.3 b/man/man3/FD_ISSET.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man3/FD_ISSET.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man3/FD_SET.3 b/man/man3/FD_SET.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man3/FD_SET.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man3/FD_ZERO.3 b/man/man3/FD_ZERO.3 new file mode 100644 index 0000000..e177843 --- /dev/null +++ b/man/man3/FD_ZERO.3 @@ -0,0 +1 @@ +.so man2/select.2 diff --git a/man/man3/HUGE_VAL.3 b/man/man3/HUGE_VAL.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man/man3/HUGE_VAL.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man/man3/HUGE_VALF.3 b/man/man3/HUGE_VALF.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man/man3/HUGE_VALF.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man/man3/HUGE_VALL.3 b/man/man3/HUGE_VALL.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man/man3/HUGE_VALL.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man/man3/INFINITY.3 b/man/man3/INFINITY.3 new file mode 100644 index 0000000..334c79d --- /dev/null +++ b/man/man3/INFINITY.3 @@ -0,0 +1,85 @@ +.\" Copyright 2004 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH INFINITY 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +INFINITY, NAN, HUGE_VAL, HUGE_VALF, HUGE_VALL \- floating-point constants +.SH LIBRARY +Math library +.RI ( libm ) +.SH SYNOPSIS +.nf +.BR "#define _ISOC99_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.B INFINITY +.P +.B NAN +.P +.B HUGE_VAL +.B HUGE_VALF +.B HUGE_VALL +.fi +.SH DESCRIPTION +The macro +.B INFINITY +expands to a +.I float +constant representing positive infinity. +.P +The macro +.B NAN +expands to a +.I float +constant representing a quiet NaN +(when supported). +A +.I quiet +NaN is a NaN ("not-a-number") that does not raise exceptions +when it is used in arithmetic. +The opposite is a +.I signaling +NaN. +See IEC 60559:1989. +.P +The macros +.BR HUGE_VAL , +.BR HUGE_VALF , +.B HUGE_VALL +expand to constants of types +.IR double , +.IR float , +and +.IR "long double" , +respectively, +that represent a large positive value, possibly positive infinity. +.SH STANDARDS +C11. +.SH HISTORY +C99. +.P +On a glibc system, the macro +.B HUGE_VAL +is always available. +Availability of the +.B NAN +macro can be tested using +.BR "#ifdef NAN" , +and similarly for +.BR INFINITY , +.BR HUGE_VALF , +.BR HUGE_VALL . +They will be defined by +.I +if +.B _ISOC99_SOURCE +or +.B _GNU_SOURCE +is defined, or +.B __STDC_VERSION__ +is defined +and has a value not less than 199901L. +.SH SEE ALSO +.BR fpclassify (3), +.BR math_error (7) diff --git a/man/man3/LIST_EMPTY.3 b/man/man3/LIST_EMPTY.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_EMPTY.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_ENTRY.3 b/man/man3/LIST_ENTRY.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_ENTRY.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_FIRST.3 b/man/man3/LIST_FIRST.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_FIRST.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_FOREACH.3 b/man/man3/LIST_FOREACH.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_FOREACH.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_HEAD.3 b/man/man3/LIST_HEAD.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_HEAD.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_HEAD_INITIALIZER.3 b/man/man3/LIST_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_INIT.3 b/man/man3/LIST_INIT.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_INIT.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_INSERT_AFTER.3 b/man/man3/LIST_INSERT_AFTER.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_INSERT_BEFORE.3 b/man/man3/LIST_INSERT_BEFORE.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_INSERT_BEFORE.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_INSERT_HEAD.3 b/man/man3/LIST_INSERT_HEAD.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_NEXT.3 b/man/man3/LIST_NEXT.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_NEXT.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/LIST_REMOVE.3 b/man/man3/LIST_REMOVE.3 new file mode 100644 index 0000000..dfafea8 --- /dev/null +++ b/man/man3/LIST_REMOVE.3 @@ -0,0 +1 @@ +.so man3/list.3 diff --git a/man/man3/MAX.3 b/man/man3/MAX.3 new file mode 100644 index 0000000..e290554 --- /dev/null +++ b/man/man3/MAX.3 @@ -0,0 +1,75 @@ +.\" Copyright (C) 2021 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH MAX 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +MAX, MIN \- maximum or minimum of two values +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI MAX( a ", " b ); +.BI MIN( a ", " b ); +.fi +.SH DESCRIPTION +These macros return the maximum or minimum of +.I a +and +.IR b . +.SH RETURN VALUE +These macros return the value of one of their arguments, +possibly converted to a different type (see BUGS). +.SH ERRORS +These macros may raise the "invalid" floating-point exception +when any of the arguments is NaN. +.SH STANDARDS +GNU, BSD. +.SH NOTES +If either of the arguments is of a floating-point type, +you might prefer to use +.BR fmax (3) +or +.BR fmin (3), +which can handle NaN. +.P +The arguments may be evaluated more than once, or not at all. +.P +Some UNIX systems might provide these macros in a different header, +or not at all. +.SH BUGS +Due to the usual arithmetic conversions, +the result of these macros may be very different from either of the arguments. +To avoid this, ensure that both arguments have the same type. +.SH EXAMPLES +.\" SRC BEGIN (MAX.c) +.EX +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int a, b, x; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + a = atoi(argv[1]); + b = atoi(argv[2]); + x = MAX(a, b); + printf("MAX(%d, %d) is %d\en", a, b, x); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fmax (3), +.BR fmin (3) diff --git a/man/man3/MB_CUR_MAX.3 b/man/man3/MB_CUR_MAX.3 new file mode 100644 index 0000000..3c6e34e --- /dev/null +++ b/man/man3/MB_CUR_MAX.3 @@ -0,0 +1,43 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.\" Modified, aeb, 990824 +.\" +.TH MB_CUR_MAX 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +MB_CUR_MAX \- maximum length of a multibyte character in the current locale +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +The +.B MB_CUR_MAX +macro defines an integer expression giving +the maximum number of bytes needed to represent a single +wide character in the current locale. +This value is locale dependent and therefore not a compile-time constant. +.SH RETURN VALUE +An integer in the range [1, +.BR MB_LEN_MAX ]. +The value 1 denotes traditional 8-bit encoded characters. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH SEE ALSO +.BR MB_LEN_MAX (3), +.BR mblen (3), +.BR mbstowcs (3), +.BR mbtowc (3), +.BR wcstombs (3), +.BR wctomb (3) diff --git a/man/man3/MB_LEN_MAX.3 b/man/man3/MB_LEN_MAX.3 new file mode 100644 index 0000000..a38d675 --- /dev/null +++ b/man/man3/MB_LEN_MAX.3 @@ -0,0 +1,51 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.\" Modified, aeb, 990824 +.\" +.TH MB_LEN_MAX 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +MB_LEN_MAX \- maximum multibyte length of a character across all locales +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +The +.B MB_LEN_MAX +macro is the maximum number of bytes needed to represent a single +wide character, in any of the supported locales. +.SH RETURN VALUE +A constant integer greater than zero. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +The entities +.B MB_LEN_MAX +and +.I sizeof(wchar_t) +are totally unrelated. +In glibc, +.B MB_LEN_MAX +is typically 16 +.\" For an explanation of why the limit was raised to 16, see +.\" http://lists.gnu.org/archive/html/bug-gnulib/2015-05/msg00001.html +.\" From: Bruno Haible +.\" Subject: Re: why is MB_LEN_MAX so large (16) on glibc +.\" Date: Thu, 14 May 2015 02:30:14 +0200 +(6 in glibc versions earlier than 2.2), while +.I sizeof(wchar_t) +is 4. +.SH SEE ALSO +.BR MB_CUR_MAX (3) diff --git a/man/man3/MIN.3 b/man/man3/MIN.3 new file mode 100644 index 0000000..9938abd --- /dev/null +++ b/man/man3/MIN.3 @@ -0,0 +1 @@ +.so man3/MAX.3 diff --git a/man/man3/NAN.3 b/man/man3/NAN.3 new file mode 100644 index 0000000..dd04d2c --- /dev/null +++ b/man/man3/NAN.3 @@ -0,0 +1 @@ +.so man3/INFINITY.3 diff --git a/man/man3/SIMPLEQ_EMPTY.3 b/man/man3/SIMPLEQ_EMPTY.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_EMPTY.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_ENTRY.3 b/man/man3/SIMPLEQ_ENTRY.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_FIRST.3 b/man/man3/SIMPLEQ_FIRST.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_FIRST.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_FOREACH.3 b/man/man3/SIMPLEQ_FOREACH.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_FOREACH.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_HEAD.3 b/man/man3/SIMPLEQ_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_HEAD_INITIALIZER.3 b/man/man3/SIMPLEQ_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_INIT.3 b/man/man3/SIMPLEQ_INIT.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_INIT.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_INSERT_AFTER.3 b/man/man3/SIMPLEQ_INSERT_AFTER.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_INSERT_HEAD.3 b/man/man3/SIMPLEQ_INSERT_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_INSERT_TAIL.3 b/man/man3/SIMPLEQ_INSERT_TAIL.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_NEXT.3 b/man/man3/SIMPLEQ_NEXT.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_NEXT.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_REMOVE.3 b/man/man3/SIMPLEQ_REMOVE.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SIMPLEQ_REMOVE_HEAD.3 b/man/man3/SIMPLEQ_REMOVE_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/SIMPLEQ_REMOVE_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/SLIST_EMPTY.3 b/man/man3/SLIST_EMPTY.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_EMPTY.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_ENTRY.3 b/man/man3/SLIST_ENTRY.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_ENTRY.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_FIRST.3 b/man/man3/SLIST_FIRST.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_FIRST.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_FOREACH.3 b/man/man3/SLIST_FOREACH.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_FOREACH.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_HEAD.3 b/man/man3/SLIST_HEAD.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_HEAD.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_HEAD_INITIALIZER.3 b/man/man3/SLIST_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_INIT.3 b/man/man3/SLIST_INIT.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_INIT.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_INSERT_AFTER.3 b/man/man3/SLIST_INSERT_AFTER.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_INSERT_HEAD.3 b/man/man3/SLIST_INSERT_HEAD.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_NEXT.3 b/man/man3/SLIST_NEXT.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_NEXT.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_REMOVE.3 b/man/man3/SLIST_REMOVE.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_REMOVE.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/SLIST_REMOVE_HEAD.3 b/man/man3/SLIST_REMOVE_HEAD.3 new file mode 100644 index 0000000..260541b --- /dev/null +++ b/man/man3/SLIST_REMOVE_HEAD.3 @@ -0,0 +1 @@ +.so man3/slist.3 diff --git a/man/man3/STAILQ_CONCAT.3 b/man/man3/STAILQ_CONCAT.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_CONCAT.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_EMPTY.3 b/man/man3/STAILQ_EMPTY.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_EMPTY.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_ENTRY.3 b/man/man3/STAILQ_ENTRY.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_FIRST.3 b/man/man3/STAILQ_FIRST.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_FIRST.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_FOREACH.3 b/man/man3/STAILQ_FOREACH.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_FOREACH.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_HEAD.3 b/man/man3/STAILQ_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_HEAD_INITIALIZER.3 b/man/man3/STAILQ_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_INIT.3 b/man/man3/STAILQ_INIT.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_INIT.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_INSERT_AFTER.3 b/man/man3/STAILQ_INSERT_AFTER.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_INSERT_HEAD.3 b/man/man3/STAILQ_INSERT_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_INSERT_TAIL.3 b/man/man3/STAILQ_INSERT_TAIL.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_NEXT.3 b/man/man3/STAILQ_NEXT.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_NEXT.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_REMOVE.3 b/man/man3/STAILQ_REMOVE.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/STAILQ_REMOVE_HEAD.3 b/man/man3/STAILQ_REMOVE_HEAD.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/STAILQ_REMOVE_HEAD.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/S_ISBLK.3 b/man/man3/S_ISBLK.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISBLK.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISCHR.3 b/man/man3/S_ISCHR.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISCHR.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISDIR.3 b/man/man3/S_ISDIR.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISDIR.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISFIFO.3 b/man/man3/S_ISFIFO.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISFIFO.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISLNK.3 b/man/man3/S_ISLNK.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISLNK.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISREG.3 b/man/man3/S_ISREG.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISREG.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/S_ISSOCK.3 b/man/man3/S_ISSOCK.3 new file mode 100644 index 0000000..a5c4b88 --- /dev/null +++ b/man/man3/S_ISSOCK.3 @@ -0,0 +1 @@ +.so man7/inode.7 diff --git a/man/man3/TAILQ_CONCAT.3 b/man/man3/TAILQ_CONCAT.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_CONCAT.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_EMPTY.3 b/man/man3/TAILQ_EMPTY.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_EMPTY.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_ENTRY.3 b/man/man3/TAILQ_ENTRY.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_ENTRY.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_FIRST.3 b/man/man3/TAILQ_FIRST.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_FIRST.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_FOREACH.3 b/man/man3/TAILQ_FOREACH.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_FOREACH.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_FOREACH_REVERSE.3 b/man/man3/TAILQ_FOREACH_REVERSE.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_FOREACH_REVERSE.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_HEAD.3 b/man/man3/TAILQ_HEAD.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_HEAD.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_HEAD_INITIALIZER.3 b/man/man3/TAILQ_HEAD_INITIALIZER.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_HEAD_INITIALIZER.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_INIT.3 b/man/man3/TAILQ_INIT.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_INIT.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_INSERT_AFTER.3 b/man/man3/TAILQ_INSERT_AFTER.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_INSERT_AFTER.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_INSERT_BEFORE.3 b/man/man3/TAILQ_INSERT_BEFORE.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_INSERT_BEFORE.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_INSERT_HEAD.3 b/man/man3/TAILQ_INSERT_HEAD.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_INSERT_HEAD.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_INSERT_TAIL.3 b/man/man3/TAILQ_INSERT_TAIL.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_INSERT_TAIL.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_LAST.3 b/man/man3/TAILQ_LAST.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_LAST.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_NEXT.3 b/man/man3/TAILQ_NEXT.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_NEXT.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_PREV.3 b/man/man3/TAILQ_PREV.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_PREV.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_REMOVE.3 b/man/man3/TAILQ_REMOVE.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_REMOVE.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TAILQ_SWAP.3 b/man/man3/TAILQ_SWAP.3 new file mode 100644 index 0000000..c766ff4 --- /dev/null +++ b/man/man3/TAILQ_SWAP.3 @@ -0,0 +1 @@ +.so man3/tailq.3 diff --git a/man/man3/TIMESPEC_TO_TIMEVAL.3 b/man/man3/TIMESPEC_TO_TIMEVAL.3 new file mode 100644 index 0000000..30ab755 --- /dev/null +++ b/man/man3/TIMESPEC_TO_TIMEVAL.3 @@ -0,0 +1 @@ +.so man3/TIMEVAL_TO_TIMESPEC.3 diff --git a/man/man3/TIMEVAL_TO_TIMESPEC.3 b/man/man3/TIMEVAL_TO_TIMESPEC.3 new file mode 100644 index 0000000..30f3ed1 --- /dev/null +++ b/man/man3/TIMEVAL_TO_TIMESPEC.3 @@ -0,0 +1,32 @@ +.\" Copyright (C) 2024 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH TIMEVAL_TO_TIMESPEC 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +TIMEVAL_TO_TIMESPEC, +TIMESPEC_TO_TIMEVAL +\- +convert between time structures +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.P +.BI "void TIMEVAL_TO_TIMESPEC(const struct timeval *" tv ", struct timespec *" ts ); +.BI "void TIMESPEC_TO_TIMEVAL(struct timeval *" tv ", const struct timespec *" ts ); +.fi +.SH DESCRIPTION +These macros convert from a +.BR timeval (3type) +to a +.BR timespec (3type) +structure, +and vice versa, +respectively. +.P +This is especially useful for writing interfaces that receive a type, +but are implemented with calls to functions that receive the other one. +.SH STANDARDS +GNU, +BSD. diff --git a/man/man3/_Generic.3 b/man/man3/_Generic.3 new file mode 100644 index 0000000..f8e8b1b --- /dev/null +++ b/man/man3/_Generic.3 @@ -0,0 +1,64 @@ +.\" Copyright (C) 2022 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH _Generic 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +_Generic \- type-generic selection +.SH SYNOPSIS +.nf +.BR _Generic( \fIexpression\fP ", type1: " e1 ", " "... /*" \ +", default: " "e */" ); +.fi +.SH DESCRIPTION +.BR _Generic () +evaluates the path of code under the type selector +that is compatible with the type of the controlling +.IR expression , +or +.B default: +if no type is compatible. +.P +.I expression +is not evaluated. +.P +This is especially useful for writing type-generic macros, +that will behave differently depending on the type of the argument. +.SH STANDARDS +C11. +.SH HISTORY +C11. +.SH EXAMPLES +The following program demonstrates how to write +a replacement for the standard +.BR imaxabs (3) +function, which being a function can't really provide what it promises: +seamlessly upgrading to the widest available type. +.IP +.\" SRC BEGIN (_Generic.c) +.EX +#include +#include +#include +\& +#define my_imaxabs _Generic(INTMAX_C(0), \e + long: labs, \e + long long: llabs \e +/* long long long: lllabs */ \e +) +\& +int +main(void) +{ + off_t a; +\& + a = \-42; + printf("imaxabs(%jd) == %jd\en", (intmax_t) a, my_imaxabs(a)); + printf("&imaxabs == %p\en", &my_imaxabs); + printf("&labs == %p\en", &labs); + printf("&llabs == %p\en", &llabs); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END diff --git a/man/man3/_Static_assert.3 b/man/man3/_Static_assert.3 new file mode 100644 index 0000000..30f6353 --- /dev/null +++ b/man/man3/_Static_assert.3 @@ -0,0 +1 @@ +.so man3/static_assert.3 diff --git a/man/man3/__after_morecore_hook.3 b/man/man3/__after_morecore_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__after_morecore_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__fbufsize.3 b/man/man3/__fbufsize.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__fbufsize.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__flbf.3 b/man/man3/__flbf.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__flbf.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__fpending.3 b/man/man3/__fpending.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__fpending.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__fpurge.3 b/man/man3/__fpurge.3 new file mode 100644 index 0000000..d7cfd49 --- /dev/null +++ b/man/man3/__fpurge.3 @@ -0,0 +1 @@ +.so man3/fpurge.3 diff --git a/man/man3/__freadable.3 b/man/man3/__freadable.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__freadable.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__freading.3 b/man/man3/__freading.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__freading.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__free_hook.3 b/man/man3/__free_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__free_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__fsetlocking.3 b/man/man3/__fsetlocking.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__fsetlocking.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__fwritable.3 b/man/man3/__fwritable.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__fwritable.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__fwriting.3 b/man/man3/__fwriting.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/__fwriting.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/__malloc_hook.3 b/man/man3/__malloc_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__malloc_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__malloc_initialize_hook.3 b/man/man3/__malloc_initialize_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__malloc_initialize_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__memalign_hook.3 b/man/man3/__memalign_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__memalign_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__ppc_get_timebase.3 b/man/man3/__ppc_get_timebase.3 new file mode 100644 index 0000000..7a8064d --- /dev/null +++ b/man/man3/__ppc_get_timebase.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 2012, IBM Corporation. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH __ppc_get_timebase 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +__ppc_get_timebase, __ppc_get_timebase_freq \- get the current value +of the Time Base Register on Power architecture and its frequency. +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B uint64_t __ppc_get_timebase(void); +.B uint64_t __ppc_get_timebase_freq(void); +.fi +.SH DESCRIPTION +.BR __ppc_get_timebase () +reads the current value of the Time Base Register and returns its +value, while +.BR __ppc_get_timebase_freq () +returns the frequency in which the Time Base Register is updated. +.P +The Time Base Register is a 64-bit register provided by Power Architecture +processors. +It stores a monotonically incremented value that is updated at a +system-dependent frequency that may be different from the processor +frequency. +.SH RETURN VALUE +.BR __ppc_get_timebase () +returns a 64-bit unsigned integer that represents the current value of the +Time Base Register. +.P +.BR __ppc_get_timebase_freq () +returns a 64-bit unsigned integer that represents the frequency at +which the Time Base Register is updated. +.SH STANDARDS +GNU. +.SH HISTORY +.TP +.BR __ppc_get_timebase () +.\" commit d9dc34cd569bcfe714fe8c708e58c028106e8b2e +glibc 2.16. +.TP +.BR __ppc_get_timebase_freq () +.\" commit 8ad11b9a9cf1de82bd7771306b42070b91417c11 +glibc 2.17. +.SH EXAMPLES +The following program will calculate the time, in microseconds, spent +between two calls to +.BR __ppc_get_timebase (). +.SS Program source +\& +.\" SRC BEGIN (__ppc_get_timebase.c) +.EX +#include +#include +#include +#include +#include +\& +/* Maximum value of the Time Base Register: 2\[ha]60 \- 1. + Source: POWER ISA. */ +#define MAX_TB 0xFFFFFFFFFFFFFFF +\& +int +main(void) +{ + uint64_t tb1, tb2, diff; + uint64_t freq; +\& + freq = __ppc_get_timebase_freq(); + printf("Time Base frequency = %"PRIu64" Hz\en", freq); +\& + tb1 = __ppc_get_timebase(); +\& + // Do some stuff... +\& + tb2 = __ppc_get_timebase(); +\& + if (tb2 > tb1) { + diff = tb2 \- tb1; + } else { + /* Treat Time Base Register overflow. */ + diff = (MAX_TB \- tb2) + tb1; + } +\& + printf("Elapsed time = %1.2f usecs\en", + (double) diff * 1000000 / freq); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR time (2), +.BR usleep (3) diff --git a/man/man3/__ppc_get_timebase_freq.3 b/man/man3/__ppc_get_timebase_freq.3 new file mode 100644 index 0000000..8599293 --- /dev/null +++ b/man/man3/__ppc_get_timebase_freq.3 @@ -0,0 +1 @@ +.so man3/__ppc_get_timebase.3 diff --git a/man/man3/__ppc_mdoio.3 b/man/man3/__ppc_mdoio.3 new file mode 100644 index 0000000..c9f047f --- /dev/null +++ b/man/man3/__ppc_mdoio.3 @@ -0,0 +1 @@ +.so man3/__ppc_yield.3 diff --git a/man/man3/__ppc_mdoom.3 b/man/man3/__ppc_mdoom.3 new file mode 100644 index 0000000..c9f047f --- /dev/null +++ b/man/man3/__ppc_mdoom.3 @@ -0,0 +1 @@ +.so man3/__ppc_yield.3 diff --git a/man/man3/__ppc_set_ppr_low.3 b/man/man3/__ppc_set_ppr_low.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man/man3/__ppc_set_ppr_low.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man/man3/__ppc_set_ppr_med.3 b/man/man3/__ppc_set_ppr_med.3 new file mode 100644 index 0000000..dbfdced --- /dev/null +++ b/man/man3/__ppc_set_ppr_med.3 @@ -0,0 +1,113 @@ +'\" t +.\" Copyright (c) 2015, 2016 IBM Corporation. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH __ppc_set_ppr_med 3 2024-05-02 "Linux man-pages (unreleased)" +Programmer's Manual" +.SH NAME +__ppc_set_ppr_med, __ppc_set_ppr_very_low, __ppc_set_ppr_low, +__ppc_set_ppr_med_low, __ppc_set_ppr_med_high \- +Set the Program Priority Register +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B void __ppc_set_ppr_med(void); +.B void __ppc_set_ppr_very_low(void); +.B void __ppc_set_ppr_low(void); +.B void __ppc_set_ppr_med_low(void); +.B void __ppc_set_ppr_med_high(void); +.fi +.SH DESCRIPTION +These functions provide access to the +.I Program Priority Register +(PPR) on the Power architecture. +.P +The PPR is a 64-bit register that controls the program's priority. +By adjusting the PPR value the programmer may improve system +throughput by causing system resources to be used more +efficiently, especially in contention situations. +The available unprivileged states are covered by the following functions: +.TP +.BR __ppc_set_ppr_med () +sets the Program Priority Register value to +.I medium +(default). +.TP +.BR __ppc_set_ppr_very_low () +sets the Program Priority Register value to +.IR "very low" . +.TP +.BR __ppc_set_ppr_low () +sets the Program Priority Register value to +.IR low . +.TP +.BR __ppc_set_ppr_med_low () +sets the Program Priority Register value to +.IR "medium low" . +.P +The privileged state +.I medium high +may also be set during certain time intervals by problem-state (unprivileged) +programs, with the following function: +.TP +.BR __ppc_set_ppr_med_high () +sets the Program Priority to +.IR "medium high" . +.P +If the program priority is medium high when the time interval expires or if an +attempt is made to set the priority to medium high when it is not allowed, the +priority is set to medium. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR __ppc_set_ppr_med (), +.BR __ppc_set_ppr_very_low (), +.BR __ppc_set_ppr_low (), +.BR __ppc_set_ppr_med_low (), +.BR __ppc_set_ppr_med_high () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +.TP +.BR __ppc_set_ppr_med () +.TQ +.BR __ppc_set_ppr_low () +.TQ +.BR __ppc_set_ppr_med_low () +glibc 2.18. +.TP +.BR __ppc_set_ppr_very_low () +.TQ +.BR __ppc_set_ppr_med_high () +glibc 2.23. +.SH NOTES +The functions +.BR __ppc_set_ppr_very_low () +and +.BR __ppc_set_ppr_med_high () +will be defined by +.I +if +.B _ARCH_PWR8 +is defined. +Availability of these functions can be tested using +.BR "#ifdef _ARCH_PWR8" . +.SH SEE ALSO +.BR __ppc_yield (3) +.P +.I Power ISA, Book\~II - Section\ 3.1 (Program Priority Registers) diff --git a/man/man3/__ppc_set_ppr_med_high.3 b/man/man3/__ppc_set_ppr_med_high.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man/man3/__ppc_set_ppr_med_high.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man/man3/__ppc_set_ppr_med_low.3 b/man/man3/__ppc_set_ppr_med_low.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man/man3/__ppc_set_ppr_med_low.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man/man3/__ppc_set_ppr_very_low.3 b/man/man3/__ppc_set_ppr_very_low.3 new file mode 100644 index 0000000..a6d6cf3 --- /dev/null +++ b/man/man3/__ppc_set_ppr_very_low.3 @@ -0,0 +1 @@ +.so man3/__ppc_set_ppr_med.3 diff --git a/man/man3/__ppc_yield.3 b/man/man3/__ppc_yield.3 new file mode 100644 index 0000000..55f3701 --- /dev/null +++ b/man/man3/__ppc_yield.3 @@ -0,0 +1,67 @@ +'\" t +.\" Copyright (c) 2015, IBM Corporation. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH __ppc_yield 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +__ppc_yield, __ppc_mdoio, __ppc_mdoom \- +Hint the processor to release shared resources +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B void __ppc_yield(void); +.B void __ppc_mdoio(void); +.B void __ppc_mdoom(void); +.fi +.SH DESCRIPTION +These functions +provide hints about the usage of resources that are shared with other +processors on the Power architecture. +They can be used, for example, if a program waiting on a lock intends +to divert the shared resources to be used by other processors. +.P +.BR __ppc_yield () +provides a hint that performance will probably be improved if shared +resources dedicated to the executing processor are released for use by +other processors. +.P +.BR __ppc_mdoio () +provides a hint that performance will probably be improved if shared +resources dedicated to the executing processor are released until all +outstanding storage accesses to caching-inhibited storage have been +completed. +.P +.BR __ppc_mdoom () +provides a hint that performance will probably be improved if shared +resources dedicated to the executing processor are released until all +outstanding storage accesses to cacheable storage for which the data +is not in the cache have been completed. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR __ppc_yield (), +.BR __ppc_mdoio (), +.BR __ppc_mdoom () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.18. +.SH SEE ALSO +.BR __ppc_set_ppr_med (3) +.P +.I Power ISA, Book\~II - Section\~3.2 ("or" architecture) diff --git a/man/man3/__realloc_hook.3 b/man/man3/__realloc_hook.3 new file mode 100644 index 0000000..421aafc --- /dev/null +++ b/man/man3/__realloc_hook.3 @@ -0,0 +1 @@ +.so man3/malloc_hook.3 diff --git a/man/man3/__setfpucw.3 b/man/man3/__setfpucw.3 new file mode 100644 index 0000000..0b0dd26 --- /dev/null +++ b/man/man3/__setfpucw.3 @@ -0,0 +1,72 @@ +.\" Written Sat Mar 8 10:35:08 MEZ 1997 by +.\" J. "MUFTI" Scheurich (mufti@csv.ica.uni-stuttgart.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH __setfpucw 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +__setfpucw \- set FPU control word on i386 architecture (obsolete) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] void __setfpucw(unsigned short " control_word ); +.fi +.SH DESCRIPTION +.BR __setfpucw () +transfers +.I control_word +to the registers of the FPU (floating-point unit) on the i386 architecture. +This was used to control floating-point precision, +rounding and floating-point exceptions. +.SH STANDARDS +GNU. +.SH HISTORY +Removed in glibc 2.1. +.SH NOTES +There are new functions from C99, with prototypes in +.IR , +to control FPU rounding modes, like +.BR fegetround (3), +.BR fesetround (3), +and the floating-point environment, like +.BR fegetenv (3), +.BR feholdexcept (3), +.BR fesetenv (3), +.BR feupdateenv (3), +and FPU exception handling, like +.BR feclearexcept (3), +.BR fegetexceptflag (3), +.BR feraiseexcept (3), +.BR fesetexceptflag (3), +and +.BR fetestexcept (3). +.P +If direct access to the FPU control word is still needed, the +.B _FPU_GETCW +and +.B _FPU_SETCW +macros from +.I +can be used. +.SH EXAMPLES +.B __setfpucw(0x1372) +.P +Set FPU control word on the i386 architecture to +.RS +.PD 0 +.IP \[bu] 3 +extended precision +.IP \[bu] +rounding to nearest +.IP \[bu] +exceptions on overflow, zero divide and NaN +.PD +.RE +.SH SEE ALSO +.BR feclearexcept (3) +.P +.I diff --git a/man/man3/_flushlbf.3 b/man/man3/_flushlbf.3 new file mode 100644 index 0000000..fb0e7c0 --- /dev/null +++ b/man/man3/_flushlbf.3 @@ -0,0 +1 @@ +.so man3/stdio_ext.3 diff --git a/man/man3/a64l.3 b/man/man3/a64l.3 new file mode 100644 index 0000000..9fe156a --- /dev/null +++ b/man/man3/a64l.3 @@ -0,0 +1,111 @@ +'\" t +\t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Corrected, aeb, 2002-05-30 +.\" +.TH a64l 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +a64l, l64a \- convert between long and base-64 +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long a64l(const char *" str64 ); +.BI "char *l64a(long " value ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR a64l (), +.BR l64a (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions provide a conversion between 32-bit long integers +and little-endian base-64 ASCII strings (of length zero to six). +If the string used as argument for +.BR a64l () +has length greater than six, only the first six bytes are used. +If the type +.I long +has more than 32 bits, then +.BR l64a () +uses only the low order 32 bits of +.IR value , +and +.BR a64l () +sign-extends its 32-bit result. +.P +The 64 digits in the base-64 system are: +.P +.RS +.nf +\&\[aq].\[aq] represents a 0 +\&\[aq]/\[aq] represents a 1 +0-9 represent 2-11 +A-Z represent 12-37 +a-z represent 38-63 +.fi +.RE +.P +So 123 = 59*64\[ha]0 + 1*64\[ha]1 = "v/". +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR l64a () +T} Thread safety MT-Unsafe race:l64a +T{ +.na +.nh +.BR a64l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The value returned by +.BR l64a () +may be a pointer to a static buffer, possibly overwritten +by later calls. +.P +The behavior of +.BR l64a () +is undefined when +.I value +is negative. +If +.I value +is zero, it returns an empty string. +.P +These functions are broken before glibc 2.2.5 +(puts most significant digit first). +.P +This is not the encoding used by +.BR uuencode (1). +.SH SEE ALSO +.BR uuencode (1), +.\" .BR itoa (3), +.BR strtoul (3) diff --git a/man/man3/abort.3 b/man/man3/abort.3 new file mode 100644 index 0000000..874ce2b --- /dev/null +++ b/man/man3/abort.3 @@ -0,0 +1,99 @@ +'\" t +.\" Copyright 2007 (C) Michael Kerrisk +.\" some parts Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:46:21 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Aug 4 10:51:53 2000 - patch from Joseph S. Myers +.\" 2007-12-15, mtk, Mostly rewritten +.\" +.TH abort 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +abort \- cause abnormal process termination +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B [[noreturn]] void abort(void); +.fi +.SH DESCRIPTION +The +.BR abort () +function first unblocks the +.B SIGABRT +signal, and then raises that signal for the calling process +(as though +.BR raise (3) +was called). +This results in the abnormal termination of the process unless the +.B SIGABRT +signal is caught and the signal handler does not return +(see +.BR longjmp (3)). +.P +If the +.B SIGABRT +signal is ignored, or caught by a handler that returns, the +.BR abort () +function will still terminate the process. +It does this by restoring the default disposition for +.B SIGABRT +and then raising the signal for a second time. +.P +As with other cases of abnormal termination the functions registered with +.BR atexit (3) +and +.BR on_exit (3) +are not called. +.SH RETURN VALUE +The +.BR abort () +function never returns. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR abort () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +SVr4, POSIX.1-2001, 4.3BSD, C89. +.P +Up until glibc 2.26, +if the +.BR abort () +function caused process termination, +all open streams were closed and flushed (as with +.BR fclose (3)). +However, in some cases this could result in deadlocks and data corruption. +Therefore, starting with glibc 2.27, +.\" glibc commit 91e7cf982d0104f0e71770f5ae8e3faf352dea9f +.BR abort () +terminates the process without flushing streams. +POSIX.1 permits either possible behavior, saying that +.BR abort () +"may include an attempt to effect fclose() on all open streams". +.SH SEE ALSO +.BR gdb (1), +.BR sigaction (2), +.BR assert (3), +.BR exit (3), +.BR longjmp (3), +.BR raise (3) diff --git a/man/man3/abs.3 b/man/man3/abs.3 new file mode 100644 index 0000000..2b8f650 --- /dev/null +++ b/man/man3/abs.3 @@ -0,0 +1,124 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:31:13 1993, David Metcalfe +.\" Modified Sun Jun 6 23:27:50 1993, David Metcalfe +.\" Modified Sat Jul 24 21:45:37 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Dec 16 15:02:59 2000, Joseph S. Myers +.\" +.TH abs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +abs, labs, llabs, imaxabs \- compute the absolute value of an integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int abs(int " j ); +.BI "long labs(long " j ); +.BI "long long llabs(long long " j ); +.P +.B #include +.P +.BI "intmax_t imaxabs(intmax_t " j ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR llabs (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR abs () +function computes the absolute value of the integer +argument \fIj\fP. +The +.BR labs (), +.BR llabs (), +and +.BR imaxabs () +functions compute the absolute value of the argument \fIj\fP of the +appropriate integer type for the function. +.SH RETURN VALUE +Returns the absolute value of the integer argument, of the appropriate +integer type for the function. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR abs (), +.BR labs (), +.BR llabs (), +.BR imaxabs () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99, SVr4, 4.3BSD. +.\" POSIX.1 (1996 edition) requires only the +.\" .BR abs () +.\" function. +.P +C89 only +includes the +.BR abs () +and +.BR labs () +functions; the functions +.BR llabs () +and +.BR imaxabs () +were added in C99. +.SH NOTES +Trying to take the absolute value of the most negative integer +is not defined. +.P +The +.BR llabs () +function is included since glibc 2.0. +The +.BR imaxabs () +function is included since glibc 2.1.1. +.P +For +.BR llabs () +to be declared, it may be necessary to define +\fB_ISOC99_SOURCE\fP or \fB_ISOC9X_SOURCE\fP (depending on the +version of glibc) before including any standard headers. +.P +By default, +GCC handles +.BR abs (), +.BR labs (), +and (since GCC 3.0) +.BR llabs () +and +.BR imaxabs () +as built-in functions. +.SH SEE ALSO +.BR cabs (3), +.BR ceil (3), +.BR fabs (3), +.BR floor (3), +.BR rint (3) diff --git a/man/man3/acos.3 b/man/man3/acos.3 new file mode 100644 index 0000000..9ba9515 --- /dev/null +++ b/man/man3/acos.3 @@ -0,0 +1,121 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH acos 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +acos, acosf, acosl \- arc cosine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double acos(double " x ); +.BI "float acosf(float " x ); +.BI "long double acosl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR acosf (), +.BR acosl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the arc cosine of +.IR x ; +that is +the value whose cosine is +.IR x . +.SH RETURN VALUE +On success, these functions return the arc cosine of +.I x +in radians; the return value is in the range [0,\ pi]. +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +1, ++0 is returned. +.P +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.P +If +.I x +is outside the range [\-1,\ 1], +a domain error occurs, +and a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is outside the range [\-1,\ 1] +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR acos (), +.BR acosf (), +.BR acosl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cacos (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man/man3/acosf.3 b/man/man3/acosf.3 new file mode 100644 index 0000000..66104f7 --- /dev/null +++ b/man/man3/acosf.3 @@ -0,0 +1 @@ +.so man3/acos.3 diff --git a/man/man3/acosh.3 b/man/man3/acosh.3 new file mode 100644 index 0000000..1fb3ed1 --- /dev/null +++ b/man/man3/acosh.3 @@ -0,0 +1,124 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH acosh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +acosh, acoshf, acoshl \- inverse hyperbolic cosine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double acosh(double " x ); +.BI "float acoshf(float " x ); +.BI "long double acoshl(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR acosh (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR acoshf (), +.BR acoshl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the inverse hyperbolic cosine of +.IR x ; +that is the value whose hyperbolic cosine is +.IR x . +.SH RETURN VALUE +On success, these functions return the inverse hyperbolic cosine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +1, +0 is returned. +.P +If +.I x +is positive infinity, positive infinity is returned. +.P +If +.I x +is less than 1, +a domain error occurs, +and the functions return a NaN. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is less than 1 +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR acosh (), +.BR acoshf (), +.BR acoshl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR asinh (3), +.BR atanh (3), +.BR cacosh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man/man3/acoshf.3 b/man/man3/acoshf.3 new file mode 100644 index 0000000..f0f5c7a --- /dev/null +++ b/man/man3/acoshf.3 @@ -0,0 +1 @@ +.so man3/acosh.3 diff --git a/man/man3/acoshl.3 b/man/man3/acoshl.3 new file mode 100644 index 0000000..f0f5c7a --- /dev/null +++ b/man/man3/acoshl.3 @@ -0,0 +1 @@ +.so man3/acosh.3 diff --git a/man/man3/acosl.3 b/man/man3/acosl.3 new file mode 100644 index 0000000..66104f7 --- /dev/null +++ b/man/man3/acosl.3 @@ -0,0 +1 @@ +.so man3/acos.3 diff --git a/man/man3/addmntent.3 b/man/man3/addmntent.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man/man3/addmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man/man3/addseverity.3 b/man/man3/addseverity.3 new file mode 100644 index 0000000..68335cc --- /dev/null +++ b/man/man3/addseverity.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" adapted glibc info page +.\" +.\" polished a little, aeb +.TH addseverity 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +addseverity \- introduce new severity classes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.P +.B #include +.P +.BI "int addseverity(int " severity ", const char *" s ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR addseverity (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +This function allows the introduction of new severity classes +which can be addressed by the +.I severity +argument of the +.BR fmtmsg (3) +function. +By default, that function knows only how to +print messages for severity 0-4 (with strings (none), HALT, +ERROR, WARNING, INFO). +This call attaches the given string +.I s +to the given value +.IR severity . +If +.I s +is NULL, the severity class with the numeric value +.I severity +is removed. +It is not possible to overwrite or remove one of the default +severity classes. +The severity value must be nonnegative. +.SH RETURN VALUE +Upon success, the value +.B MM_OK +is returned. +Upon error, the return value is +.BR MM_NOTOK . +Possible errors include: out of memory, attempt to remove a +nonexistent or default severity class. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR addseverity () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +System V. +.SH NOTES +New severity classes can also be added by setting the environment variable +.BR SEV_LEVEL . +.SH SEE ALSO +.BR fmtmsg (3) diff --git a/man/man3/adjtime.3 b/man/man3/adjtime.3 new file mode 100644 index 0000000..80f1485 --- /dev/null +++ b/man/man3/adjtime.3 @@ -0,0 +1,152 @@ +'\" t +.\" Copyright (c) 2006 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH adjtime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +adjtime \- correct the time to synchronize the system clock +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int adjtime(const struct timeval *" delta ", struct timeval *" olddelta ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR adjtime (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR adjtime () +function gradually adjusts the system clock (as returned by +.BR gettimeofday (2)). +The amount of time by which the clock is to be adjusted is specified +in the structure pointed to by +.IR delta . +This structure has the following form: +.P +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.P +If the adjustment in +.I delta +is positive, then the system clock is speeded up by some +small percentage (i.e., by adding a small +amount of time to the clock value in each second) until the adjustment +has been completed. +If the adjustment in +.I delta +is negative, then the clock is slowed down in a similar fashion. +.P +If a clock adjustment from an earlier +.BR adjtime () +call is already in progress +at the time of a later +.BR adjtime () +call, and +.I delta +is not NULL for the later call, then the earlier adjustment is stopped, +but any already completed part of that adjustment is not undone. +.P +If +.I olddelta +is not NULL, then the buffer that it points to is used to return +the amount of time remaining from any previous adjustment that +has not yet been completed. +.SH RETURN VALUE +On success, +.BR adjtime () +returns 0. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The adjustment in +.I delta +is outside the permitted range. +.TP +.B EPERM +The caller does not have sufficient privilege to adjust the time. +Under Linux, the +.B CAP_SYS_TIME +capability is required. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR adjtime () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD, System V. +.SH NOTES +The adjustment that +.BR adjtime () +makes to the clock is carried out in such a manner that the clock +is always monotonically increasing. +Using +.BR adjtime () +to adjust the time prevents the problems that could be caused for certain +applications (e.g., +.BR make (1)) +by abrupt positive or negative jumps in the system time. +.P +.BR adjtime () +is intended to be used to make small adjustments to the system time. +Most systems impose a limit on the adjustment that can be specified in +.IR delta . +In the glibc implementation, +.I delta +must be less than or equal to (INT_MAX / 1000000 \- 2) +and greater than or equal to (INT_MIN / 1000000 + 2) +(respectively 2145 and \-2145 seconds on i386). +.SH BUGS +A longstanding bug +.\" http://sourceware.org/bugzilla/show_bug?id=2449 +.\" http://bugzilla.kernel.org/show_bug.cgi?id=6761 +meant that if +.I delta +was specified as NULL, +no valid information about the outstanding clock adjustment was returned in +.IR olddelta . +(In this circumstance, +.BR adjtime () +should return the outstanding clock adjustment, without changing it.) +This bug is fixed +.\" Thanks to the new adjtimex() ADJ_OFFSET_SS_READ flag +on systems with glibc 2.8 or later and +Linux kernel 2.6.26 or later. +.SH SEE ALSO +.BR adjtimex (2), +.BR gettimeofday (2), +.BR time (7) diff --git a/man/man3/aio_cancel.3 b/man/man3/aio_cancel.3 new file mode 100644 index 0000000..6ddb301 --- /dev/null +++ b/man/man3/aio_cancel.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_cancel 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_cancel \- cancel an outstanding asynchronous I/O request +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int aio_cancel(int " fd ", struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_cancel () +function attempts to cancel outstanding asynchronous I/O requests +for the file descriptor +.IR fd . +If +.I aiocbp +is NULL, all such requests are canceled. +Otherwise, only the request +described by the control block pointed to by +.I aiocbp +is canceled. +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +Normal asynchronous notification occurs for canceled requests (see +.BR aio (7) +and +.BR sigevent (3type)). +The request return status +.RB ( aio_return (3)) +is set to \-1, and the request error status +.RB ( aio_error (3)) +is set to +.BR ECANCELED . +The control block of requests that cannot be canceled is not changed. +.P +If the request could not be canceled, +then it will terminate in the usual way after performing the I/O operation. +(In this case, +.BR aio_error (3) +will return the status +.BR EINPROGRESSS .) +.P +If +.I aiocbp +is not NULL, and +.I fd +differs from the file descriptor with which the asynchronous operation +was initiated, unspecified results occur. +.P +Which operations are cancelable is implementation-defined. +.\" FreeBSD: not those on raw disk devices. +.SH RETURN VALUE +The +.BR aio_cancel () +function returns one of the following values: +.TP +.B AIO_CANCELED +All requests were successfully canceled. +.TP +.B AIO_NOTCANCELED +At least one of the +requests specified was not canceled because it was in progress. +In this case, one may check the status of individual requests using +.BR aio_error (3). +.TP +.B AIO_ALLDONE +All requests had already been completed before the call. +.TP +\-1 +An error occurred. +The cause of the error can be found by inspecting +.IR errno . +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOSYS +.BR aio_cancel () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_cancel () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH EXAMPLES +See +.BR aio (7). +.SH SEE ALSO +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) diff --git a/man/man3/aio_error.3 b/man/man3/aio_error.3 new file mode 100644 index 0000000..f00e35c --- /dev/null +++ b/man/man3/aio_error.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_error 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_error \- get error status of asynchronous I/O operation +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int aio_error(const struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_error () +function returns the error status for the asynchronous I/O request +with control block pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.SH RETURN VALUE +This function returns one of the following: +.TP +.B EINPROGRESS +if the request has not been +completed yet. +.TP +.B ECANCELED +if the request was canceled. +.TP +.B 0 +if the request completed successfully. +.TP +.RB "> " 0 +A positive error number, if the asynchronous I/O operation failed. +This is the same value that would have been stored in the +.I errno +variable in the case of a synchronous +.BR read (2), +.BR write (2), +.BR fsync (2), +or +.BR fdatasync (2) +call. +.SH ERRORS +.TP +.B EINVAL +.I aiocbp +does not point at a control block for an asynchronous I/O request +of which the return status (see +.BR aio_return (3)) +has not been retrieved yet. +.TP +.B ENOSYS +.BR aio_error () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_error () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH EXAMPLES +See +.BR aio (7). +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) diff --git a/man/man3/aio_fsync.3 b/man/man3/aio_fsync.3 new file mode 100644 index 0000000..f9f22c6 --- /dev/null +++ b/man/man3/aio_fsync.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_fsync 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_fsync \- asynchronous file synchronization +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int aio_fsync(int " op ", struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_fsync () +function does a sync on all outstanding asynchronous I/O operations +associated with +.IR aiocbp\->aio_fildes . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +More precisely, if +.I op +is +.BR O_SYNC , +then all currently queued I/O operations shall be +completed as if by a call of +.BR fsync (2), +and if +.I op +is +.BR O_DSYNC , +this call is the asynchronous analog of +.BR fdatasync (2). +.P +Note that this is a request only; it does not wait for I/O completion. +.P +Apart from +.IR aio_fildes , +the only field in the structure pointed to by +.I aiocbp +that is used by this call is the +.I aio_sigevent +field (a +.I sigevent +structure, described in +.BR sigevent (3type)), +which indicates the desired type of asynchronous notification at completion. +All other fields are ignored. +.SH RETURN VALUE +On success (the sync request was successfully queued) +this function returns 0. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for writing. +.TP +.B EINVAL +Synchronized I/O is not supported for this file, or +.I op +is not +.B O_SYNC +or +.BR O_DSYNC . +.TP +.B ENOSYS +.BR aio_fsync () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_fsync () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7), +.BR sigevent (3type) diff --git a/man/man3/aio_init.3 b/man/man3/aio_init.3 new file mode 100644 index 0000000..67a58cf --- /dev/null +++ b/man/man3/aio_init.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) 2010 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH aio_init 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_init \- asynchronous I/O initialization +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B "#include " +.P +.BI "void aio_init(const struct aioinit *" init ); +.fi +.SH DESCRIPTION +The GNU-specific +.BR aio_init () +function allows the caller to provide tuning hints to the +glibc POSIX AIO implementation. +Use of this function is optional, but to be effective, +it must be called before employing any other functions in the POSIX AIO API. +.P +The tuning information is provided in the buffer pointed to by the argument +.IR init . +This buffer is a structure of the following form: +.P +.in +4n +.EX +struct aioinit { + int aio_threads; /* Maximum number of threads */ + int aio_num; /* Number of expected simultaneous + requests */ + int aio_locks; /* Not used */ + int aio_usedba; /* Not used */ + int aio_debug; /* Not used */ + int aio_numusers; /* Not used */ + int aio_idle_time; /* Number of seconds before idle thread + terminates (since glibc 2.2) */ + int aio_reserved; +}; +.EE +.in +.P +The following fields are used in the +.I aioinit +structure: +.TP +.I aio_threads +This field specifies the maximum number of worker threads that +may be used by the implementation. +If the number of outstanding I/O operations exceeds this limit, +then excess operations will be queued until a worker thread becomes free. +If this field is specified with a value less than 1, the value 1 is used. +The default value is 20. +.TP +.I aio_num +This field should specify the maximum number of simultaneous I/O requests +that the caller expects to enqueue. +If a value less than 32 is specified for this field, +it is rounded up to 32. +.\" FIXME . But, if aio_num > 32, the behavior looks strange. See +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12083 +The default value is 64. +.TP +.I aio_idle_time +This field specifies the amount of time in seconds that a +worker thread should wait for further requests before terminating, +after having completed a previous request. +The default value is 1. +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH SEE ALSO +.BR aio (7) diff --git a/man/man3/aio_read.3 b/man/man3/aio_read.3 new file mode 100644 index 0000000..66d1b66 --- /dev/null +++ b/man/man3/aio_read.3 @@ -0,0 +1,159 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_read 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_read \- asynchronous read +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int aio_read(struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_read () +function queues the I/O request described by the buffer pointed to by +.IR aiocbp . +This function is the asynchronous analog of +.BR read (2). +The arguments of the call +.P +.in +4n +.EX +read(fd, buf, count) +.EE +.in +.P +correspond (in order) to the fields +.IR aio_fildes , +.IR aio_buf , +and +.I aio_nbytes +of the structure pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +The data is read starting at the absolute position +.IR aiocbp\->aio_offset , +regardless of the file offset. +After the call, +the value of the file offset is unspecified. +.P +The "asynchronous" means that this call returns as soon as the +request has been enqueued; the read may or may not have completed +when the call returns. +One tests for completion using +.BR aio_error (3). +The return status of a completed I/O operation can be obtained by +.BR aio_return (3). +Asynchronous notification of I/O completion can be obtained by setting +.I aiocbp\->aio_sigevent +appropriately; see +.BR sigevent (3type) +for details. +.P +If +.B _POSIX_PRIORITIZED_IO +is defined, and this file supports it, +then the asynchronous operation is submitted at a priority equal +to that of the calling process minus +.IR aiocbp\->aio_reqprio . +.P +The field +.I aiocbp\->aio_lio_opcode +is ignored. +.P +No data is read from a regular file beyond its maximum offset. +.SH RETURN VALUE +On success, 0 is returned. +On error, the request is not enqueued, \-1 +is returned, and +.I errno +is set to indicate the error. +If an error is detected only later, it will +be reported via +.BR aio_return (3) +(returns status \-1) and +.BR aio_error (3) +(error status\[em]whatever one would have gotten in +.IR errno , +such as +.BR EBADF ). +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for reading. +.TP +.B EINVAL +One or more of +.IR aio_offset , +.IR aio_reqprio , +or +.I aio_nbytes +are invalid. +.TP +.B ENOSYS +.BR aio_read () +is not implemented. +.TP +.B EOVERFLOW +The file is a regular file, we start reading before end-of-file +and want at least one byte, but the starting position is past +the maximum offset for this file. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_read () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +It is a good idea to zero out the control block before use. +The control block must not be changed while the read operation +is in progress. +The buffer area being read into +.\" or the control block of the operation +must not be accessed during the operation or undefined results may occur. +The memory areas involved must remain valid. +.P +Simultaneous I/O operations specifying the same +.I aiocb +structure produce undefined results. +.SH EXAMPLES +See +.BR aio (7). +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) diff --git a/man/man3/aio_return.3 b/man/man3/aio_return.3 new file mode 100644 index 0000000..c3bd55f --- /dev/null +++ b/man/man3/aio_return.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_return 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_return \- get return status of asynchronous I/O operation +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "ssize_t aio_return(struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_return () +function returns the final return status for the asynchronous I/O request +with control block pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +This function should be called only once for any given request, after +.BR aio_error (3) +returns something other than +.BR EINPROGRESS . +.SH RETURN VALUE +If the asynchronous I/O operation has completed, this function returns +the value that would have been returned in case of a synchronous +.BR read (2), +.BR write (2), +.BR fsync (2), +or +.BR fdatasync (2), +call. +On error, \-1 is returned, and \fIerrno\fP is set to indicate the error. +.P +If the asynchronous I/O operation has not yet completed, +the return value and effect of +.BR aio_return () +are undefined. +.SH ERRORS +.TP +.B EINVAL +.I aiocbp +does not point at a control block for an asynchronous I/O request +of which the return status has not been retrieved yet. +.TP +.B ENOSYS +.BR aio_return () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_return () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH EXAMPLES +See +.BR aio (7). +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7) diff --git a/man/man3/aio_suspend.3 b/man/man3/aio_suspend.3 new file mode 100644 index 0000000..a011534 --- /dev/null +++ b/man/man3/aio_suspend.3 @@ -0,0 +1,143 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2010 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_suspend 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_suspend \- wait for asynchronous I/O operation or timeout +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.P +.B "#include " +.P +.BI "int aio_suspend(const struct aiocb *const " aiocb_list "[], int " nitems , +.BI " const struct timespec *restrict " timeout ); +.fi +.SH DESCRIPTION +The +.BR aio_suspend () +function suspends the calling thread until one of the following occurs: +.IP \[bu] 3 +One or more of the asynchronous I/O requests in the list +.I aiocb_list +has completed. +.IP \[bu] +A signal is delivered. +.IP \[bu] +.I timeout +is not NULL and the specified time interval has passed. +(For details of the +.I timespec +structure, see +.BR nanosleep (2).) +.P +The +.I nitems +argument specifies the number of items in +.IR aiocb_list . +Each item in the list pointed to by +.I aiocb_list +must be either NULL (and then is ignored), +or a pointer to a control block on which I/O was initiated using +.BR aio_read (3), +.BR aio_write (3), +or +.BR lio_listio (3). +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +If +.B CLOCK_MONOTONIC +is supported, this clock is used to measure +the timeout interval (see +.BR clock_gettime (2)). +.SH RETURN VALUE +If this function returns after completion of one of the I/O +requests specified in +.IR aiocb_list , +0 is returned. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The call timed out before any of the indicated operations +had completed. +.TP +.B EINTR +The call was ended by signal +(possibly the completion signal of one of the operations we were +waiting for); see +.BR signal (7). +.TP +.B ENOSYS +.BR aio_suspend () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_suspend () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.P +POSIX doesn't specify the parameters to be +.IR restrict ; +that is specific to glibc. +.SH NOTES +One can achieve polling by using a non-NULL +.I timeout +that specifies a zero time interval. +.P +If one or more of the asynchronous I/O operations specified in +.I aiocb_list +has already completed at the time of the call to +.BR aio_suspend (), +then the call returns immediately. +.P +To determine which I/O operations have completed +after a successful return from +.BR aio_suspend (), +use +.BR aio_error (3) +to scan the list of +.I aiocb +structures pointed to by +.IR aiocb_list . +.SH BUGS +The glibc implementation of +.BR aio_suspend () +is not async-signal-safe, +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=13172 +in violation of the requirements of POSIX.1. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_write (3), +.BR lio_listio (3), +.BR aio (7), +.BR time (7) diff --git a/man/man3/aio_write.3 b/man/man3/aio_write.3 new file mode 100644 index 0000000..800ff3b --- /dev/null +++ b/man/man3/aio_write.3 @@ -0,0 +1,161 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH aio_write 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio_write \- asynchronous write +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int aio_write(struct aiocb *" aiocbp ); +.fi +.SH DESCRIPTION +The +.BR aio_write () +function queues the I/O request described by the buffer pointed to by +.IR aiocbp . +This function is the asynchronous analog of +.BR write (2). +The arguments of the call +.P +.in +4n +.EX +write(fd, buf, count) +.EE +.in +.P +correspond (in order) to the fields +.IR aio_fildes , +.IR aio_buf , +and +.I aio_nbytes +of the structure pointed to by +.IR aiocbp . +(See +.BR aio (7) +for a description of the +.I aiocb +structure.) +.P +If +.B O_APPEND +is not set, the data is written starting at the +absolute position +.IR aiocbp\->aio_offset , +regardless of the file offset. +If +.B O_APPEND +is set, data is written at the end of the file in the same order as +.BR aio_write () +calls are made. +After the call, the value of the file offset is unspecified. +.P +The "asynchronous" means that this call returns as soon as the +request has been enqueued; the write may or may not have completed +when the call returns. +One tests for completion using +.BR aio_error (3). +The return status of a completed I/O operation can be obtained +.BR aio_return (3). +Asynchronous notification of I/O completion can be obtained by setting +.I aiocbp\->aio_sigevent +appropriately; see +.BR sigevent (3type) +for details. +.P +If +.B _POSIX_PRIORITIZED_IO +is defined, and this file supports it, +then the asynchronous operation is submitted at a priority equal +to that of the calling process minus +.IR aiocbp\->aio_reqprio . +.P +The field +.I aiocbp\->aio_lio_opcode +is ignored. +.P +No data is written to a regular file beyond its maximum offset. +.SH RETURN VALUE +On success, 0 is returned. +On error, the request is not enqueued, \-1 +is returned, and +.I errno +is set to indicate the error. +If an error is detected only later, it will +be reported via +.BR aio_return (3) +(returns status \-1) and +.BR aio_error (3) +(error status\[em]whatever one would have gotten in +.IR errno , +such as +.BR EBADF ). +.SH ERRORS +.TP +.B EAGAIN +Out of resources. +.TP +.B EBADF +.I aio_fildes +is not a valid file descriptor open for writing. +.TP +.B EFBIG +The file is a regular file, we want to write at least one byte, +but the starting position is at or beyond the maximum offset for this file. +.TP +.B EINVAL +One or more of +.IR aio_offset , +.IR aio_reqprio , +.I aio_nbytes +are invalid. +.TP +.B ENOSYS +.BR aio_write () +is not implemented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aio_write () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +It is a good idea to zero out the control block before use. +The control block must not be changed while the write operation +is in progress. +The buffer area being written out +.\" or the control block of the operation +must not be accessed during the operation or undefined results may occur. +The memory areas involved must remain valid. +.P +Simultaneous I/O operations specifying the same +.I aiocb +structure produce undefined results. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR lio_listio (3), +.BR aio (7) diff --git a/man/man3/aligned_alloc.3 b/man/man3/aligned_alloc.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man/man3/aligned_alloc.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man/man3/alloca.3 b/man/man3/alloca.3 new file mode 100644 index 0000000..934825f --- /dev/null +++ b/man/man3/alloca.3 @@ -0,0 +1,138 @@ +'\" t +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)alloca.3 5.1 (Berkeley) 5/2/91 +.\" +.\" Converted Mon Nov 29 11:05:55 1993 by Rik Faith +.\" Modified Tue Oct 22 23:41:56 1996 by Eric S. Raymond +.\" Modified 2002-07-17, aeb +.\" 2008-01-24, mtk: +.\" Various rewrites and additions (notes on longjmp() and SIGSEGV). +.\" Weaken warning against use of alloca() (as per Debian bug 461100). +.\" +.TH alloca 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +alloca \- allocate memory that is automatically freed +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *alloca(size_t " size ); +.fi +.SH DESCRIPTION +The +.BR alloca () +function allocates +.I size +bytes of space in the stack frame of the caller. +This temporary space is +automatically freed when the function that called +.BR alloca () +returns to its caller. +.SH RETURN VALUE +The +.BR alloca () +function returns a pointer to the beginning of the allocated space. +If the allocation causes stack overflow, program behavior is undefined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR alloca () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +PWB, 32V. +.SH NOTES +The +.BR alloca () +function is machine- and compiler-dependent. +Because it allocates from the stack, it's faster than +.BR malloc (3) +and +.BR free (3). +In certain cases, +it can also simplify memory deallocation in applications that use +.BR longjmp (3) +or +.BR siglongjmp (3). +Otherwise, its use is discouraged. +.P +Because the space allocated by +.BR alloca () +is allocated within the stack frame, +that space is automatically freed if the function return +is jumped over by a call to +.BR longjmp (3) +or +.BR siglongjmp (3). +.P +The space allocated by +.BR alloca () +is +.I not +automatically deallocated if the pointer that refers to it +simply goes out of scope. +.P +Do not attempt to +.BR free (3) +space allocated by +.BR alloca ()! +.P +By necessity, +.BR alloca () +is a compiler built-in, also known as +.BR __builtin_alloca (). +By default, modern compilers automatically translate all uses of +.BR alloca () +into the built-in, but this is forbidden if standards conformance is requested +.RI ( "\-ansi" , +.IR "\-std=c*" ), +in which case +.I +is required, lest a symbol dependency be emitted. +.P +The fact that +.BR alloca () +is a built-in means it is impossible to take its address +or to change its behavior by linking with a different library. +.P +Variable length arrays (VLAs) are part of the C99 standard, +optional since C11, and can be used for a similar purpose. +However, they do not port to standard C++, and, being variables, +live in their block scope and don't have an allocator-like interface, +making them unfit for implementing functionality like +.BR strdupa (3). +.SH BUGS +Due to the nature of the stack, it is impossible to check if the allocation +would overflow the space available, and, hence, neither is indicating an error. +(However, the program is likely to receive a +.B SIGSEGV +signal if it attempts to access unavailable space.) +.P +On many systems +.BR alloca () +cannot be used inside the list of arguments of a function call, because +the stack space reserved by +.BR alloca () +would appear on the stack in the middle of the space for the +function arguments. +.SH SEE ALSO +.BR brk (2), +.BR longjmp (3), +.BR malloc (3) diff --git a/man/man3/alphasort.3 b/man/man3/alphasort.3 new file mode 100644 index 0000000..7e757c7 --- /dev/null +++ b/man/man3/alphasort.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man/man3/arc4random.3 b/man/man3/arc4random.3 new file mode 100644 index 0000000..44e6674 --- /dev/null +++ b/man/man3/arc4random.3 @@ -0,0 +1,109 @@ +'\" t +.\" Copyright (C) 2023 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH arc4random 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +arc4random, arc4random_uniform, arc4random_buf +\- cryptographically-secure pseudorandom number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B uint32_t arc4random(void); +.BI "uint32_t arc4random_uniform(uint32_t " upper_bound ); +.BI "void arc4random_buf(void " buf [. n "], size_t " n ); +.fi +.SH DESCRIPTION +These functions give cryptographically-secure pseudorandom numbers. +.P +.BR arc4random () +returns a uniformly-distributed value. +.P +.BR arc4random_uniform () +returns a uniformly-distributed value less than +.I upper_bound +(see BUGS). +.P +.BR arc4random_buf () +fills the memory pointed to by +.IR buf , +with +.I n +bytes of pseudorandom data. +.P +The +.BR rand (3) +and +.BR drand48 (3) +families of functions should only be used where +the quality of the pseudorandom numbers is not a concern +.I and +there's a need for repeatability of the results. +Unless you meet both of those conditions, +use the +.BR arc4random () +functions. +.SH RETURN VALUE +.BR arc4random () +returns a pseudorandom number. +.P +.BR arc4random_uniform () +returns a pseudorandom number less than +.I upper_bound +for valid input, or +.B 0 +when +.I upper_bound +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR arc4random (), +.BR arc4random_uniform (), +.BR arc4random_buf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +BSD. +.SH HISTORY +OpenBSD 2.1, +FreeBSD 3.0, +NetBSD 1.6, +DragonFly 1.0, +libbsd, +glibc 2.36. +.SH BUGS +An +.I upper_bound +of +.B 0 +doesn't make sense in a call to +.BR arc4random_uniform (). +Such a call will fail, and return +.BR 0 . +Be careful, +since that value is +.I not +less than +.IR upper_bound . +In some cases, +such as accessing an array, +using that value could result in Undefined Behavior. +.SH SEE ALSO +.BR getrandom (3), +.BR rand (3), +.BR drand48 (3), +.BR random (7) diff --git a/man/man3/arc4random_buf.3 b/man/man3/arc4random_buf.3 new file mode 100644 index 0000000..74a34ce --- /dev/null +++ b/man/man3/arc4random_buf.3 @@ -0,0 +1 @@ +.so man3/arc4random.3 diff --git a/man/man3/arc4random_uniform.3 b/man/man3/arc4random_uniform.3 new file mode 100644 index 0000000..74a34ce --- /dev/null +++ b/man/man3/arc4random_uniform.3 @@ -0,0 +1 @@ +.so man3/arc4random.3 diff --git a/man/man3/argz.3 b/man/man3/argz.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_add.3 b/man/man3/argz_add.3 new file mode 100644 index 0000000..0e8f468 --- /dev/null +++ b/man/man3/argz_add.3 @@ -0,0 +1,237 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" based on the description in glibc source and infopages +.\" +.\" Corrections and additions, aeb +.TH argz_add 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +argz_add, argz_add_sep, argz_append, argz_count, argz_create, +argz_create_sep, argz_delete, argz_extract, argz_insert, +argz_next, argz_replace, argz_stringify \- functions to handle an argz list +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "error_t argz_add(char **restrict " argz ", size_t *restrict " argz_len , +.BI " const char *restrict " str ); +.P +.BI "error_t argz_add_sep(char **restrict " argz \ +", size_t *restrict " argz_len , +.BI " const char *restrict " str ", int " delim ); +.P +.BI "error_t argz_append(char **restrict " argz ", size_t *restrict " argz_len , +.BI " const char *restrict " buf ", size_t " buf_len ); +.P +.BI "size_t argz_count(const char *" argz ", size_t " argz_len ); +.P +.BI "error_t argz_create(char *const " argv "[], char **restrict " argz , +.BI " size_t *restrict " argz_len ); +.P +.BI "error_t argz_create_sep(const char *restrict " str ", int " sep , +.BI " char **restrict " argz ", size_t *restrict " argz_len ); +.P +.BI "void argz_delete(char **restrict " argz ", size_t *restrict " argz_len , +.BI " char *restrict " entry ); +.P +.BI "void argz_extract(const char *restrict " argz ", size_t " argz_len , +.BI " char **restrict " argv ); +.P +.BI "error_t argz_insert(char **restrict " argz ", size_t *restrict " argz_len , +.BI " char *restrict " before ", const char *restrict " entry ); +.P +.BI "char *argz_next(const char *restrict " argz ", size_t " argz_len , +.BI " const char *restrict " entry ); +.P +.BI "error_t argz_replace(char **restrict " argz \ +", size_t *restrict " argz_len , +.BI " const char *restrict " str ", const char *restrict " with , +.BI " unsigned int *restrict " replace_count ); +.P +.BI "void argz_stringify(char *" argz ", size_t " len ", int " sep ); +.fi +.SH DESCRIPTION +These functions are glibc-specific. +.P +An argz vector is a pointer to a character buffer together with a length. +The intended interpretation of the character buffer is an array +of strings, where the strings are separated by null bytes (\[aq]\e0\[aq]). +If the length is nonzero, the last byte of the buffer must be a null byte. +.P +These functions are for handling argz vectors. +The pair (NULL,0) is an argz vector, and, conversely, +argz vectors of length 0 must have null pointer. +Allocation of nonempty argz vectors is done using +.BR malloc (3), +so that +.BR free (3) +can be used to dispose of them again. +.P +.BR argz_add () +adds the string +.I str +at the end of the array +.IR *argz , +and updates +.I *argz +and +.IR *argz_len . +.P +.BR argz_add_sep () +is similar, but splits the string +.I str +into substrings separated by the delimiter +.IR delim . +For example, one might use this on a UNIX search path with +delimiter \[aq]:\[aq]. +.P +.BR argz_append () +appends the argz vector +.RI ( buf ,\ buf_len ) +after +.RI ( *argz ,\ *argz_len ) +and updates +.I *argz +and +.IR *argz_len . +(Thus, +.I *argz_len +will be increased by +.IR buf_len .) +.P +.BR argz_count () +counts the number of strings, that is, +the number of null bytes (\[aq]\e0\[aq]), in +.RI ( argz ,\ argz_len ). +.P +.BR argz_create () +converts a UNIX-style argument vector +.IR argv , +terminated by +.IR "(char\ *)\ 0" , +into an argz vector +.RI ( *argz ,\ *argz_len ). +.P +.BR argz_create_sep () +converts the null-terminated string +.I str +into an argz vector +.RI ( *argz ,\ *argz_len ) +by breaking it up at every occurrence of the separator +.IR sep . +.P +.BR argz_delete () +removes the substring pointed to by +.I entry +from the argz vector +.RI ( *argz ,\ *argz_len ) +and updates +.I *argz +and +.IR *argz_len . +.P +.BR argz_extract () +is the opposite of +.BR argz_create (). +It takes the argz vector +.RI ( argz ,\ argz_len ) +and fills the array starting at +.I argv +with pointers to the substrings, and a final NULL, +making a UNIX-style argv vector. +The array +.I argv +must have room for +.IR argz_count ( argz ", " argz_len ") + 1" +pointers. +.P +.BR argz_insert () +is the opposite of +.BR argz_delete (). +It inserts the argument +.I entry +at position +.I before +into the argz vector +.RI ( *argz ,\ *argz_len ) +and updates +.I *argz +and +.IR *argz_len . +If +.I before +is NULL, then +.I entry +will inserted at the end. +.P +.BR argz_next () +is a function to step through the argz vector. +If +.I entry +is NULL, the first entry is returned. +Otherwise, the entry +following is returned. +It returns NULL if there is no following entry. +.P +.BR argz_replace () +replaces each occurrence of +.I str +with +.IR with , +reallocating argz as necessary. +If +.I replace_count +is non-NULL, +.I *replace_count +will be incremented by the number of replacements. +.P +.BR argz_stringify () +is the opposite of +.BR argz_create_sep (). +It transforms the argz vector into a normal string by replacing +all null bytes (\[aq]\e0\[aq]) except the last by +.IR sep . +.SH RETURN VALUE +All argz functions that do memory allocation have a return type of +.I error_t +(an integer type), +and return 0 for success, and +.B ENOMEM +if an allocation error occurs. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR argz_add (), +.BR argz_add_sep (), +.BR argz_append (), +.BR argz_count (), +.BR argz_create (), +.BR argz_create_sep (), +.BR argz_delete (), +.BR argz_extract (), +.BR argz_insert (), +.BR argz_next (), +.BR argz_replace (), +.BR argz_stringify () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH BUGS +Argz vectors without a terminating null byte may lead to +Segmentation Faults. +.SH SEE ALSO +.BR envz_add (3) diff --git a/man/man3/argz_add_sep.3 b/man/man3/argz_add_sep.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_add_sep.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_append.3 b/man/man3/argz_append.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_append.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_count.3 b/man/man3/argz_count.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_count.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_create.3 b/man/man3/argz_create.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_create.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_create_sep.3 b/man/man3/argz_create_sep.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_create_sep.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_delete.3 b/man/man3/argz_delete.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_delete.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_extract.3 b/man/man3/argz_extract.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_extract.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_insert.3 b/man/man3/argz_insert.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_insert.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_next.3 b/man/man3/argz_next.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_next.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_replace.3 b/man/man3/argz_replace.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_replace.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/argz_stringify.3 b/man/man3/argz_stringify.3 new file mode 100644 index 0000000..25a6e26 --- /dev/null +++ b/man/man3/argz_stringify.3 @@ -0,0 +1 @@ +.so man3/argz_add.3 diff --git a/man/man3/asctime.3 b/man/man3/asctime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/asctime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/asctime_r.3 b/man/man3/asctime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/asctime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/asin.3 b/man/man3/asin.3 new file mode 100644 index 0000000..132d797 --- /dev/null +++ b/man/man3/asin.3 @@ -0,0 +1,117 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-25 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH asin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +asin, asinf, asinl \- arc sine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double asin(double " x ); +.BI "float asinf(float " x ); +.BI "long double asinl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR asinf (), +.BR asinl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the principal value of the arc sine of +.IR x ; +that is the value whose sine is +.IR x . +.SH RETURN VALUE +On success, these functions return the principal value of the arc sine of +.I x +in radians; the return value is in the range [\-pi/2,\ pi/2]. +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), ++0 (\-0) is returned. +.P +If +.I x +is outside the range [\-1,\ 1], +a domain error occurs, +and a NaN is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is outside the range [\-1,\ 1] +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR asin (), +.BR asinf (), +.BR asinl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acos (3), +.BR atan (3), +.BR atan2 (3), +.BR casin (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man/man3/asinf.3 b/man/man3/asinf.3 new file mode 100644 index 0000000..4c88df0 --- /dev/null +++ b/man/man3/asinf.3 @@ -0,0 +1 @@ +.so man3/asin.3 diff --git a/man/man3/asinh.3 b/man/man3/asinh.3 new file mode 100644 index 0000000..36e1930 --- /dev/null +++ b/man/man3/asinh.3 @@ -0,0 +1,109 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH asinh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +asinh, asinhf, asinhl \- inverse hyperbolic sine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double asinh(double " x ); +.BI "float asinhf(float " x ); +.BI "long double asinhl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR asinh (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR asinhf (), +.BR asinhl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the inverse hyperbolic sine of +.IR x ; +that is the value whose hyperbolic sine is +.IR x . +.SH RETURN VALUE +On success, these functions return the inverse hyperbolic sine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR asinh (), +.BR asinhf (), +.BR asinhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR acosh (3), +.BR atanh (3), +.BR casinh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man/man3/asinhf.3 b/man/man3/asinhf.3 new file mode 100644 index 0000000..93c5034 --- /dev/null +++ b/man/man3/asinhf.3 @@ -0,0 +1 @@ +.so man3/asinh.3 diff --git a/man/man3/asinhl.3 b/man/man3/asinhl.3 new file mode 100644 index 0000000..93c5034 --- /dev/null +++ b/man/man3/asinhl.3 @@ -0,0 +1 @@ +.so man3/asinh.3 diff --git a/man/man3/asinl.3 b/man/man3/asinl.3 new file mode 100644 index 0000000..4c88df0 --- /dev/null +++ b/man/man3/asinl.3 @@ -0,0 +1 @@ +.so man3/asin.3 diff --git a/man/man3/asprintf.3 b/man/man3/asprintf.3 new file mode 100644 index 0000000..79d92d5 --- /dev/null +++ b/man/man3/asprintf.3 @@ -0,0 +1,70 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Text fragments inspired by Martin Schulze . +.\" +.TH asprintf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +asprintf, vasprintf \- print to allocated string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int asprintf(char **restrict " strp ", const char *restrict " fmt ", ...);" +.BI "int vasprintf(char **restrict " strp ", const char *restrict " fmt , +.BI " va_list " ap ); +.fi +.SH DESCRIPTION +The functions +.BR asprintf () +and +.BR vasprintf () +are analogs of +.BR sprintf (3) +and +.BR vsprintf (3), +except that they allocate a string large enough to hold the output +including the terminating null byte (\[aq]\e0\[aq]), +and return a pointer to it via the first argument. +This pointer should be passed to +.BR free (3) +to release the allocated storage when it is no longer needed. +.SH RETURN VALUE +When successful, these functions return the number of bytes printed, +just like +.BR sprintf (3). +If memory allocation wasn't possible, or some other error occurs, +these functions will return \-1, and the contents of +.I strp +are undefined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR asprintf (), +.BR vasprintf () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +The FreeBSD implementation sets +.I strp +to NULL on error. +.SH STANDARDS +GNU, BSD. +.SH SEE ALSO +.BR free (3), +.BR malloc (3), +.BR printf (3) diff --git a/man/man3/assert.3 b/man/man3/assert.3 new file mode 100644 index 0000000..f6cc4b6 --- /dev/null +++ b/man/man3/assert.3 @@ -0,0 +1,96 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith +.\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond +.\" Modified Thu Jun 2 23:44:11 2016 by Nikos Mavrogiannopoulos +.TH assert 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +assert \- abort the program if assertion is false +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void assert(scalar " expression ); +.fi +.SH DESCRIPTION +This macro can help programmers find bugs in their programs, +or handle exceptional cases +via a crash that will produce limited debugging output. +.P +If +.I expression +is false (i.e., compares equal to zero), +.BR assert () +prints an error message to standard error +and terminates the program by calling +.BR abort (3). +The error message includes the name of the file and function containing the +.BR assert () +call, the source code line number of the call, and the text of the argument; +something like: +.P +.in +4n +.EX +prog: some_file.c:16: some_func: Assertion \`val == 0\[aq] failed. +.EE +.in +.P +If the macro +.B NDEBUG +is defined at the moment +.I +was last included, the macro +.BR assert () +generates no code, and hence does nothing at all. +It is not recommended to define +.B NDEBUG +if using +.BR assert () +to detect error conditions since the software +may behave non-deterministically. +.SH RETURN VALUE +No value is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR assert () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, C99, POSIX.1-2001. +.P +In C89, +.I expression +is required to be of type +.I int +and undefined behavior results if it is not, but in C99 +it may have any scalar type. +.\" See Defect Report 107 for more details. +.SH BUGS +.BR assert () +is implemented as a macro; if the expression tested has side-effects, +program behavior will be different depending on whether +.B NDEBUG +is defined. +This may create Heisenbugs which go away when debugging +is turned on. +.SH SEE ALSO +.BR abort (3), +.BR assert_perror (3), +.BR exit (3) diff --git a/man/man3/assert_perror.3 b/man/man3/assert_perror.3 new file mode 100644 index 0000000..c2fcb59 --- /dev/null +++ b/man/man3/assert_perror.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH assert_perror 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +assert_perror \- test errnum and abort +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "void assert_perror(int " errnum ); +.fi +.SH DESCRIPTION +If the macro +.B NDEBUG +was defined at the moment +.I +was last included, the macro +.BR assert_perror () +generates no code, and hence does nothing at all. +Otherwise, the macro +.BR assert_perror () +prints an error message to standard error and terminates the program +by calling +.BR abort (3) +if +.I errnum +is nonzero. +The message contains the filename, function name and +line number of the macro call, and the output of +.IR strerror(errnum) . +.SH RETURN VALUE +No value is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR assert_perror () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH BUGS +The purpose of the assert macros is to help programmers find bugs in +their programs, things that cannot happen unless there was a coding mistake. +However, with system or library calls the situation is rather different, +and error returns can happen, and will happen, and should be tested for. +Not by an assert, where the test goes away when +.B NDEBUG +is defined, +but by proper error handling code. +Never use this macro. +.SH SEE ALSO +.BR abort (3), +.BR assert (3), +.BR exit (3), +.BR strerror (3) diff --git a/man/man3/atan.3 b/man/man3/atan.3 new file mode 100644 index 0000000..b5b101e --- /dev/null +++ b/man/man3/atan.3 @@ -0,0 +1,103 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH atan 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atan, atanf, atanl \- arc tangent function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double atan(double " x ); +.BI "float atanf(float " x ); +.BI "long double atanl(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR atanf (), +.BR atanl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the principal value of the arc tangent of +.IR x ; +that is the value whose tangent is +.IR x . +.SH RETURN VALUE +On success, these functions return the principal value of the arc tangent of +.I x +in radians; the return value is in the range [\-pi/2,\ pi/2]. +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), ++0 (\-0) is returned. +.P +If +.I x +is positive infinity (negative infinity), +pi/2 (\-pi/2) is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atan (), +.BR atanf (), +.BR atanl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan2 (3), +.BR carg (3), +.BR catan (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man/man3/atan2.3 b/man/man3/atan2.3 new file mode 100644 index 0000000..d51c4db --- /dev/null +++ b/man/man3/atan2.3 @@ -0,0 +1,174 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH atan2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atan2, atan2f, atan2l \- arc tangent function of two variables +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double atan2(double " y ", double " x ); +.BI "float atan2f(float " y ", float " x ); +.BI "long double atan2l(long double " y ", long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR atan2f (), +.BR atan2l (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the principal value of the arc tangent of +.IR y/x , +using the signs of the two arguments to determine +the quadrant of the result. +.SH RETURN VALUE +On success, these functions return the principal value of the arc tangent of +.I y/x +in radians; the return value is in the range [\-pi,\ pi]. +.P +If +.I y +is +0 (\-0) and +.I x +is less than 0, +pi (\-pi) is returned. +.P +If +.I y +is +0 (\-0) and +.I x +is greater than 0, +0 (\-0) is returned. +.P +If +.I y +is less than 0 and +.I x +is +0 or \-0, \-pi/2 is returned. +.P +If +.I y +is greater than 0 and +.I x +is +0 or \-0, pi/2 is returned. +.P +.\" POSIX.1 says: +.\" If +.\" .I x +.\" is 0, a pole error shall not occur. +.\" +If either +.I x +or +.I y +is NaN, a NaN is returned. +.P +.\" POSIX.1 says: +.\" If the result underflows, a range error may occur and +.\" .I y/x +.\" should be returned. +.\" +If +.I y +is +0 (\-0) and +.I x +is \-0, +pi (\-pi) is returned. +.P +If +.I y +is +0 (\-0) and +.I x +is +0, +0 (\-0) is returned. +.P +If +.I y +is a finite value greater (less) than 0, and +.I x +is negative infinity, +pi (\-pi) is returned. +.P +If +.I y +is a finite value greater (less) than 0, and +.I x +is positive infinity, +0 (\-0) is returned. +.P +If +.I y +is positive infinity (negative infinity), and +.I x +is finite, +pi/2 (\-pi/2) is returned. +.P +If +.I y +is positive infinity (negative infinity) and +.I x +is negative infinity, +3*pi/4 (\-3*pi/4) is returned. +.P +If +.I y +is positive infinity (negative infinity) and +.I x +is positive infinity, +pi/4 (\-pi/4) is returned. +.\" +.\" POSIX.1 says: +.\" If both arguments are 0, a domain error shall not occur. +.SH ERRORS +No errors occur. +.\" POSIX.1 documents an optional underflow error +.\" glibc 2.8 does not do this. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atan2 (), +.BR atan2f (), +.BR atan2l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR carg (3), +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man/man3/atan2f.3 b/man/man3/atan2f.3 new file mode 100644 index 0000000..e445b12 --- /dev/null +++ b/man/man3/atan2f.3 @@ -0,0 +1 @@ +.so man3/atan2.3 diff --git a/man/man3/atan2l.3 b/man/man3/atan2l.3 new file mode 100644 index 0000000..e445b12 --- /dev/null +++ b/man/man3/atan2l.3 @@ -0,0 +1 @@ +.so man3/atan2.3 diff --git a/man/man3/atanf.3 b/man/man3/atanf.3 new file mode 100644 index 0000000..784b32a --- /dev/null +++ b/man/man3/atanf.3 @@ -0,0 +1 @@ +.so man3/atan.3 diff --git a/man/man3/atanh.3 b/man/man3/atanh.3 new file mode 100644 index 0000000..bf36b7f --- /dev/null +++ b/man/man3/atanh.3 @@ -0,0 +1,154 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH atanh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atanh, atanhf, atanhl \- inverse hyperbolic tangent function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double atanh(double " x ); +.BI "float atanhf(float " x ); +.BI "long double atanhl(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR atanh (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR atanhf (), +.BR atanhl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions calculate the inverse hyperbolic tangent of +.IR x ; +that is the value whose hyperbolic tangent is +.IR x . +.SH RETURN VALUE +On success, these functions return the inverse hyperbolic tangent of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is +1 or \-1, +a pole error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the mathematically correct sign. +.P +If the absolute value of +.I x +is greater than 1, +a domain error occurs, +and a NaN is returned. +.\" +.\" POSIX.1-2001 documents an optional range error for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP less than \-1 or greater than +1 +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is +1 or \-1 +.I errno +is set to +.B ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atanh (), +.BR atanhf (), +.BR atanhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH BUGS +In glibc 2.9 and earlier, +.\" Bug: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6759 +.\" This can be seen in sysdeps/ieee754/k_standard.c +when a pole error occurs, +.I errno +is set to +.B EDOM +instead of the POSIX-mandated +.BR ERANGE . +Since glibc 2.10, glibc does the right thing. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR catanh (3), +.BR cosh (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man/man3/atanhf.3 b/man/man3/atanhf.3 new file mode 100644 index 0000000..225a339 --- /dev/null +++ b/man/man3/atanhf.3 @@ -0,0 +1 @@ +.so man3/atanh.3 diff --git a/man/man3/atanhl.3 b/man/man3/atanhl.3 new file mode 100644 index 0000000..225a339 --- /dev/null +++ b/man/man3/atanhl.3 @@ -0,0 +1 @@ +.so man3/atanh.3 diff --git a/man/man3/atanl.3 b/man/man3/atanl.3 new file mode 100644 index 0000000..784b32a --- /dev/null +++ b/man/man3/atanl.3 @@ -0,0 +1 @@ +.so man3/atan.3 diff --git a/man/man3/atexit.3 b/man/man3/atexit.3 new file mode 100644 index 0000000..15ada04 --- /dev/null +++ b/man/man3/atexit.3 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-10-25, Walter Harms +.\" +.TH atexit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atexit \- register a function to be called at normal process termination +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int atexit(void (*" function )(void)); +.fi +.SH DESCRIPTION +The +.BR atexit () +function registers the given +.I function +to be +called at normal process termination, either via +.BR exit (3) +or via return from the program's +.IR main (). +Functions so registered are called in +the reverse order of their registration; no arguments are passed. +.P +The same function may be registered multiple times: +it is called once for each registration. +.P +POSIX.1 requires that an implementation allow at least +.\" POSIX.1-2001, POSIX.1-2008 +.B ATEXIT_MAX +(32) such functions to be registered. +The actual limit supported by an implementation can be obtained using +.BR sysconf (3). +.P +When a child process is created via +.BR fork (2), +it inherits copies of its parent's registrations. +Upon a successful call to one of the +.BR exec (3) +functions, +all registrations are removed. +.SH RETURN VALUE +The +.BR atexit () +function returns the value 0 if successful; otherwise +it returns a nonzero value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atexit () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +POSIX.1 says that the result of calling +.\" POSIX.1-2001, POSIX.1-2008 +.BR exit (3) +more than once (i.e., calling +.BR exit (3) +within a function registered using +.BR atexit ()) +is undefined. +On some systems (but not Linux), this can result in an infinite recursion; +.\" This can happen on OpenBSD 4.2 for example, and is documented +.\" as occurring on FreeBSD as well. +.\" glibc does "the Right Thing" -- invocation of the remaining +.\" exit handlers carries on as normal. +portable programs should not invoke +.BR exit (3) +inside a function registered using +.BR atexit (). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, C99, SVr4, 4.3BSD. +.SH NOTES +Functions registered using +.BR atexit () +(and +.BR on_exit (3)) +are not called if a process terminates abnormally because +of the delivery of a signal. +.P +If one of the registered functions calls +.BR _exit (2), +then any remaining functions are not invoked, +and the other process termination steps performed by +.BR exit (3) +are not performed. +.P +The +.BR atexit () +and +.BR on_exit (3) +functions register functions on the same list: +at normal process termination, +the registered functions are invoked in reverse order +of their registration by these two functions. +.P +According to POSIX.1, the result is undefined if +.BR longjmp (3) +is used to terminate execution of one of the functions registered using +.BR atexit (). +.\" In glibc, things seem to be handled okay +.SS Linux notes +Since glibc 2.2.3, +.BR atexit () +(and +.BR on_exit (3)) +can be used within a shared library to establish functions +that are called when the shared library is unloaded. +.SH EXAMPLES +.\" SRC BEGIN (atexit.c) +.EX +#include +#include +#include +\& +void +bye(void) +{ + printf("That was all, folks\en"); +} +\& +int +main(void) +{ + long a; + int i; +\& + a = sysconf(_SC_ATEXIT_MAX); + printf("ATEXIT_MAX = %ld\en", a); +\& + i = atexit(bye); + if (i != 0) { + fprintf(stderr, "cannot set exit function\en"); + exit(EXIT_FAILURE); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR _exit (2), +.BR dlopen (3), +.BR exit (3), +.BR on_exit (3) diff --git a/man/man3/atof.3 b/man/man3/atof.3 new file mode 100644 index 0000000..a626b63 --- /dev/null +++ b/man/man3/atof.3 @@ -0,0 +1,67 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:39:24 1993, David Metcalfe +.\" Modified Sat Jul 24 21:39:22 1993, Rik Faith (faith@cs.unc.edu) +.TH atof 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atof \- convert a string to a double +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double atof(const char *" nptr ); +.fi +.SH DESCRIPTION +The +.BR atof () +function converts the initial portion of the string +pointed to by \fInptr\fP to +.IR double . +The behavior is the same as +.P +.in +4n +.EX +strtod(nptr, NULL); +.EE +.in +.P +except that +.BR atof () +does not detect errors. +.SH RETURN VALUE +The converted value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atof () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, C99, SVr4, 4.3BSD. +.SH SEE ALSO +.BR atoi (3), +.BR atol (3), +.BR strfromd (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man/man3/atoi.3 b/man/man3/atoi.3 new file mode 100644 index 0000000..3df2e6b --- /dev/null +++ b/man/man3/atoi.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:39:41 1993, David Metcalfe +.\" Modified Sat Jul 24 21:38:42 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Dec 17 18:35:06 2000, Joseph S. Myers +.\" +.TH atoi 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +atoi, atol, atoll \- convert a string to an integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int atoi(const char *" nptr ); +.BI "long atol(const char *" nptr ); +.BI "long long atoll(const char *" nptr ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR atoll (): +.nf + _ISOC99_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR atoi () +function converts the initial portion of the string +pointed to by \fInptr\fP to +.IR int . +The behavior is the same as +.P +.in +4n +.EX +strtol(nptr, NULL, 10); +.EE +.in +.P +except that +.BR atoi () +does not detect errors. +.P +The +.BR atol () +and +.BR atoll () +functions behave the same as +.BR atoi (), +except that they convert the initial portion of the +string to their return type of \fIlong\fP or \fIlong long\fP. +.SH RETURN VALUE +The converted value or 0 on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR atoi (), +.BR atol (), +.BR atoll () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +POSIX.1 leaves the return value of +.BR atoi () +on error unspecified. +On glibc, musl libc, and uClibc, 0 is returned on error. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001, SVr4, 4.3BSD. +.P +C89 and +POSIX.1-1996 include the functions +.BR atoi () +and +.BR atol () +only. +.\" .SH NOTES +.\" Linux libc provided +.\" .BR atoq () +.\" as an obsolete name for +.\" .BR atoll (); +.\" .BR atoq () +.\" is not provided by glibc. +.\" The +.\" .BR atoll () +.\" function is present since glibc 2.0.2, but +.\" not in libc4 or libc5. +.SH BUGS +.I errno +is not set on error so there is no way to distinguish between 0 as an +error and as the converted value. +No checks for overflow or underflow are done. +Only base-10 input can be converted. +It is recommended to instead use the +.BR strtol () +and +.BR strtoul () +family of functions in new programs. +.SH SEE ALSO +.BR atof (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man/man3/atol.3 b/man/man3/atol.3 new file mode 100644 index 0000000..51f084f --- /dev/null +++ b/man/man3/atol.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man/man3/atoll.3 b/man/man3/atoll.3 new file mode 100644 index 0000000..51f084f --- /dev/null +++ b/man/man3/atoll.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man/man3/atoq.3 b/man/man3/atoq.3 new file mode 100644 index 0000000..51f084f --- /dev/null +++ b/man/man3/atoq.3 @@ -0,0 +1 @@ +.so man3/atoi.3 diff --git a/man/man3/auth_destroy.3 b/man/man3/auth_destroy.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/auth_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/authnone_create.3 b/man/man3/authnone_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/authnone_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/authunix_create.3 b/man/man3/authunix_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/authunix_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/authunix_create_default.3 b/man/man3/authunix_create_default.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/authunix_create_default.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/backtrace.3 b/man/man3/backtrace.3 new file mode 100644 index 0000000..04762c5 --- /dev/null +++ b/man/man3/backtrace.3 @@ -0,0 +1,283 @@ +'\" t +.\" Copyright (C) 2007 Michael Kerrisk +.\" drawing on material by Justin Pryzby +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.TH backtrace 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +backtrace, backtrace_symbols, backtrace_symbols_fd \- support +for application self-debugging +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int backtrace(void *" buffer [. size "], int " size ); +.P +.BI "char **backtrace_symbols(void *const " buffer [. size "], int " size ); +.BI "void backtrace_symbols_fd(void *const " buffer [. size "], int " size ", \ +int " fd ); +.fi +.SH DESCRIPTION +.BR backtrace () +returns a backtrace for the calling program, +in the array pointed to by +.IR buffer . +A backtrace is the series of currently active function calls for +the program. +Each item in the array pointed to by +.I buffer +is of type +.IR "void\ *" , +and is the return address from +the corresponding stack frame. +The +.I size +argument specifies the maximum number of addresses +that can be stored in +.IR buffer . +If the backtrace is larger than +.IR size , +then the addresses corresponding to the +.I size +most recent function calls are returned; +to obtain the complete backtrace, make sure that +.I buffer +and +.I size +are large enough. +.P +Given the set of addresses returned by +.BR backtrace () +in +.IR buffer , +.BR backtrace_symbols () +translates the addresses into an array of strings that describe +the addresses symbolically. +The +.I size +argument specifies the number of addresses in +.IR buffer . +The symbolic representation of each address consists of the function name +(if this can be determined), a hexadecimal offset into the function, +and the actual return address (in hexadecimal). +The address of the array of string pointers is returned +as the function result of +.BR backtrace_symbols (). +This array is +.BR malloc (3)ed +by +.BR backtrace_symbols (), +and must be freed by the caller. +(The strings pointed to by the array of pointers +need not and should not be freed.) +.P +.BR backtrace_symbols_fd () +takes the same +.I buffer +and +.I size +arguments as +.BR backtrace_symbols (), +but instead of returning an array of strings to the caller, +it writes the strings, one per line, to the file descriptor +.IR fd . +.BR backtrace_symbols_fd () +does not call +.BR malloc (3), +and so can be employed in situations where the latter function might +fail, but see NOTES. +.SH RETURN VALUE +.BR backtrace () +returns the number of addresses returned in +.IR buffer , +which is not greater than +.IR size . +If the return value is less than +.IR size , +then the full backtrace was stored; if it is equal to +.IR size , +then it may have been truncated, in which case the addresses of the +oldest stack frames are not returned. +.P +On success, +.BR backtrace_symbols () +returns a pointer to the array +.BR malloc (3)ed +by the call; +on error, NULL is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR backtrace (), +.BR backtrace_symbols (), +.BR backtrace_symbols_fd () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH NOTES +These functions make some assumptions about how a function's return +address is stored on the stack. +Note the following: +.IP \[bu] 3 +Omission of the frame pointers (as +implied by any of +.BR gcc (1)'s +nonzero optimization levels) may cause these assumptions to be +violated. +.IP \[bu] +Inlined functions do not have stack frames. +.IP \[bu] +Tail-call optimization causes one stack frame to replace another. +.IP \[bu] +.BR backtrace () +and +.BR backtrace_symbols_fd () +don't call +.BR malloc () +explicitly, but they are part of +.IR libgcc , +which gets loaded dynamically when first used. +Dynamic loading usually triggers a call to +.BR malloc (3). +If you need certain calls to these two functions to not allocate memory +(in signal handlers, for example), you need to make sure +.I libgcc +is loaded beforehand. +.P +The symbol names may be unavailable without the use of special linker +options. +For systems using the GNU linker, it is necessary to use the +.I \-rdynamic +linker option. +Note that names of "static" functions are not exposed, +and won't be available in the backtrace. +.SH EXAMPLES +The program below demonstrates the use of +.BR backtrace () +and +.BR backtrace_symbols (). +The following shell session shows what we might see when running the +program: +.P +.in +4n +.EX +.RB "$" " cc \-rdynamic prog.c \-o prog" +.RB "$" " ./prog 3" +backtrace() returned 8 addresses +\&./prog(myfunc3+0x5c) [0x80487f0] +\&./prog [0x8048871] +\&./prog(myfunc+0x21) [0x8048894] +\&./prog(myfunc+0x1a) [0x804888d] +\&./prog(myfunc+0x1a) [0x804888d] +\&./prog(main+0x65) [0x80488fb] +\&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c] +\&./prog [0x8048711] +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (backtrace.c) +.EX +#include +#include +#include +#include +\& +#define BT_BUF_SIZE 100 +\& +void +myfunc3(void) +{ + int nptrs; + void *buffer[BT_BUF_SIZE]; + char **strings; +\& + nptrs = backtrace(buffer, BT_BUF_SIZE); + printf("backtrace() returned %d addresses\en", nptrs); +\& + /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO) + would produce similar output to the following: */ +\& + strings = backtrace_symbols(buffer, nptrs); + if (strings == NULL) { + perror("backtrace_symbols"); + exit(EXIT_FAILURE); + } +\& + for (size_t j = 0; j < nptrs; j++) + printf("%s\en", strings[j]); +\& + free(strings); +} +\& +static void /* "static" means don\[aq]t export the symbol... */ +myfunc2(void) +{ + myfunc3(); +} +\& +void +myfunc(int ncalls) +{ + if (ncalls > 1) + myfunc(ncalls \- 1); + else + myfunc2(); +} +\& +int +main(int argc, char *argv[]) +{ + if (argc != 2) { + fprintf(stderr, "%s num\-calls\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + myfunc(atoi(argv[1])); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR addr2line (1), +.BR gcc (1), +.BR gdb (1), +.BR ld (1), +.BR dlopen (3), +.BR malloc (3) diff --git a/man/man3/backtrace_symbols.3 b/man/man3/backtrace_symbols.3 new file mode 100644 index 0000000..936a6b9 --- /dev/null +++ b/man/man3/backtrace_symbols.3 @@ -0,0 +1 @@ +.so man3/backtrace.3 diff --git a/man/man3/backtrace_symbols_fd.3 b/man/man3/backtrace_symbols_fd.3 new file mode 100644 index 0000000..936a6b9 --- /dev/null +++ b/man/man3/backtrace_symbols_fd.3 @@ -0,0 +1 @@ +.so man3/backtrace.3 diff --git a/man/man3/basename.3 b/man/man3/basename.3 new file mode 100644 index 0000000..5d1e7fc --- /dev/null +++ b/man/man3/basename.3 @@ -0,0 +1,187 @@ +'\" t +.\" Copyright (c) 2000 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created, 14 Dec 2000 by Michael Kerrisk +.\" +.TH basename 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +basename, dirname \- parse pathname components +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *dirname(char *" path ); +.BI "char *basename(char *" path ); +.fi +.SH DESCRIPTION +Warning: there are two different functions +.BR basename (); +see below. +.P +The functions +.BR dirname () +and +.BR basename () +break a null-terminated pathname string into directory +and filename components. +In the usual case, +.BR dirname () +returns the string up to, but not including, the final \[aq]/\[aq], and +.BR basename () +returns the component following the final \[aq]/\[aq]. +Trailing \[aq]/\[aq] characters are not counted as part of the pathname. +.P +If +.I path +does not contain a slash, +.BR dirname () +returns the string "." while +.BR basename () +returns a copy of +.IR path . +If +.I path +is the string "/", then both +.BR dirname () +and +.BR basename () +return the string "/". +If +.I path +is a null pointer or points to an empty string, then both +.BR dirname () +and +.BR basename () +return the string ".". +.P +Concatenating the string returned by +.BR dirname (), +a "/", and the string returned by +.BR basename () +yields a complete pathname. +.P +Both +.BR dirname () +and +.BR basename () +may modify the contents of +.IR path , +so it may be desirable to pass a copy when calling one of +these functions. +.P +These functions may return pointers to statically allocated memory +which may be overwritten by subsequent calls. +Alternatively, they may return a pointer to some part of +.IR path , +so that the string referred to by +.I path +should not be modified or freed until the pointer returned by +the function is no longer required. +.P +The following list of examples (taken from SUSv2) +shows the strings returned by +.BR dirname () +and +.BR basename () +for different paths: +.RS +.TS +lb lb lb +l l l l. +path dirname basename +/usr/lib /usr lib +/usr/ / usr +usr . usr +/ / / +\&. . . +\&.. . .. +.TE +.RE +.SH RETURN VALUE +Both +.BR dirname () +and +.BR basename () +return pointers to null-terminated strings. +(Do not pass these pointers to +.BR free (3).) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR basename (), +.BR dirname () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +There are two different versions of +.BR basename () +- the POSIX version described above, and the GNU version, which one gets +after +.P +.in +4n +.EX +.BR " #define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B " #include " +.EE +.in +.P +The GNU version never modifies its argument, and returns the +empty string when +.I path +has a trailing slash, and in particular also when it is "/". +There is no GNU version of +.BR dirname (). +.P +With glibc, one gets the POSIX version of +.BR basename () +when +.I +is included, and the GNU version otherwise. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +In the glibc implementation, +the POSIX versions of these functions modify the +.I path +argument, and segfault when called with a static string +such as "/usr/". +.P +Before glibc 2.2.1, the glibc version of +.BR dirname () +did not correctly handle pathnames with trailing \[aq]/\[aq] characters, +and generated a segfault if given a NULL argument. +.SH EXAMPLES +The following code snippet demonstrates the use of +.BR basename () +and +.BR dirname (): +.in +4n +.EX +char *dirc, *basec, *bname, *dname; +char *path = "/etc/passwd"; +\& +dirc = strdup(path); +basec = strdup(path); +dname = dirname(dirc); +bname = basename(basec); +printf("dirname=%s, basename=%s\en", dname, bname); +.EE +.in +.SH SEE ALSO +.BR basename (1), +.BR dirname (1) diff --git a/man/man3/bcmp.3 b/man/man3/bcmp.3 new file mode 100644 index 0000000..4c509de --- /dev/null +++ b/man/man3/bcmp.3 @@ -0,0 +1,30 @@ +.\" Copyright 2022 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH bcmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bcmp \- compare byte sequences +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int bcmp(const void " s1 [. n "], const void " s2 [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +.BR bcmp () +is identical to +.BR memcmp (3); +use the latter instead. +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +Marked as LEGACY in POSIX.1-2001; +removed in POSIX.1-2008. +.SH SEE ALSO +.BR memcmp (3) diff --git a/man/man3/bcopy.3 b/man/man3/bcopy.3 new file mode 100644 index 0000000..5688b6f --- /dev/null +++ b/man/man3/bcopy.3 @@ -0,0 +1,76 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sun Feb 26 14:52:00 1995 by Rik Faith +.\" Modified Tue Oct 22 23:48:10 1996 by Eric S. Raymond +.\" " +.TH bcopy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bcopy \- copy byte sequence +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] void bcopy(const void " src [. n "], void " dest [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The +.BR bcopy () +function copies +.I n +bytes from +.I src +to +.IR dest . +The result is correct, even when both areas overlap. +.SH RETURN VALUE +None. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR bcopy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +.P +Marked as LEGACY in POSIX.1-2001: use +.BR memcpy (3) +or +.BR memmove (3) +in new programs. +Note that the first two arguments +are interchanged for +.BR memcpy (3) +and +.BR memmove (3). +POSIX.1-2008 removes the specification of +.BR bcopy (). +.SH SEE ALSO +.BR bstring (3), +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR strcpy (3), +.BR strncpy (3) diff --git a/man/man3/be16toh.3 b/man/man3/be16toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/be16toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/be32toh.3 b/man/man3/be32toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/be32toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/be64toh.3 b/man/man3/be64toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/be64toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/bindresvport.3 b/man/man3/bindresvport.3 new file mode 100644 index 0000000..1eef397 --- /dev/null +++ b/man/man3/bindresvport.3 @@ -0,0 +1,116 @@ +'\" t +.\" Copyright (C) 2007, Michael Kerrisk +.\" and Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-05-31, mtk: Rewrite and substantial additional text. +.\" 2008-12-03, mtk: Rewrote some pieces and fixed some errors +.\" +.TH bindresvport 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bindresvport \- bind a socket to a privileged IP port +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int bindresvport(int " sockfd ", struct sockaddr_in *" sin ); +.fi +.SH DESCRIPTION +.BR bindresvport () +is used to bind the socket referred to by the +file descriptor +.I sockfd +to a privileged anonymous IP port, +that is, a port number arbitrarily selected from the range 512 to 1023. +.\" glibc actually starts searching with a port # in the range 600 to 1023 +.P +If the +.BR bind (2) +performed by +.BR bindresvport () +is successful, and +.I sin +is not NULL, then +.I sin\->sin_port +returns the port number actually allocated. +.P +.I sin +can be NULL, in which case +.I sin\->sin_family +is implicitly taken to be +.BR AF_INET . +However, in this case, +.BR bindresvport () +has no way to return the port number actually allocated. +(This information can later be obtained using +.BR getsockname (2).) +.SH RETURN VALUE +.BR bindresvport () +returns 0 on success; otherwise \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.BR bindresvport () +can fail for any of the same reasons as +.BR bind (2). +In addition, the following errors may occur: +.TP +.B EACCES +The calling process was not privileged +(on Linux: the calling process did not have the +.B CAP_NET_BIND_SERVICE +capability in the user namespace governing its network namespace). +.TP +.B EADDRINUSE +All privileged ports are in use. +.TP +.BR EAFNOSUPPORT " (" EPFNOSUPPORT " in glibc 2.7 and earlier)" +.I sin +is not NULL and +.I sin\->sin_family +is not +.BR AF_INET . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR bindresvport () +T} Thread safety T{ +.na +.nh +glibc\ >=\ 2.17: MT-Safe; +.\" commit f6da27e53695ad1cc0e2a9490358decbbfdff5e5 +glibc\ <\ 2.17: MT-Unsafe +T} +.TE +.P +The +.BR bindresvport () +function uses a static variable that was not protected by a lock +before glibc 2.17, rendering the function MT-Unsafe. +.SH VERSIONS +Present on the BSDs, Solaris, and many other systems. +.SH NOTES +Unlike some +.BR bindresvport () +implementations, +the glibc implementation ignores any value that the caller supplies in +.IR sin\->sin_port . +.SH STANDARDS +BSD. +.SH SEE ALSO +.BR bind (2), +.BR getsockname (2) diff --git a/man/man3/bsd_signal.3 b/man/man3/bsd_signal.3 new file mode 100644 index 0000000..183ab2e --- /dev/null +++ b/man/man3/bsd_signal.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright (c) 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH bsd_signal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bsd_signal \- signal handling with BSD semantics +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B typedef void (*sighandler_t)(int); +.P +.BI "sighandler_t bsd_signal(int " signum ", sighandler_t " handler ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR bsd_signal (): +.nf + Since glibc 2.26: + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + && ! (_POSIX_C_SOURCE >= 200809L) + glibc 2.25 and earlier: + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +The +.BR bsd_signal () +function takes the same arguments, and performs the same task, as +.BR signal (2). +.P +The difference between the two is that +.BR bsd_signal () +is guaranteed to provide reliable signal semantics, that is: +a) the disposition of the signal is not reset to the default +when the handler is invoked; +b) delivery of further instances of the signal is blocked while +the signal handler is executing; and +c) if the handler interrupts a blocking system call, +then the system call is automatically restarted. +A portable application cannot rely on +.BR signal (2) +to provide these guarantees. +.SH RETURN VALUE +The +.BR bsd_signal () +function returns the previous value of the signal handler, or +.B SIG_ERR +on error. +.SH ERRORS +As for +.BR signal (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR bsd_signal () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Use of +.BR bsd_signal () +should be avoided; use +.BR sigaction (2) +instead. +.P +On modern Linux systems, +.BR bsd_signal () +and +.BR signal (2) +are equivalent. +But on older systems, +.BR signal (2) +provided unreliable signal semantics; see +.BR signal (2) +for details. +.P +The use of +.I sighandler_t +is a GNU extension; +this type is defined only if the +.B _GNU_SOURCE +feature test macro is defined. +.SH STANDARDS +None. +.SH HISTORY +4.2BSD, POSIX.1-2001. +Removed in POSIX.1-2008, +recommending the use of +.BR sigaction (2) +instead. +.SH SEE ALSO +.BR sigaction (2), +.BR signal (2), +.BR sysv_signal (3), +.BR signal (7) diff --git a/man/man3/bsearch.3 b/man/man3/bsearch.3 new file mode 100644 index 0000000..3e6bff4 --- /dev/null +++ b/man/man3/bsearch.3 @@ -0,0 +1,139 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Mar 29 22:41:16 1993, David Metcalfe +.\" Modified Sat Jul 24 21:35:16 1993, Rik Faith (faith@cs.unc.edu) +.TH bsearch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bsearch \- binary search of a sorted array +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *bsearch(const void " key [. size "], \ +const void " base [. size " * ." nmemb ], +.BI " size_t " nmemb ", size_t " size , +.BI " int (*" compar ")(const void [." size "], \ +const void [." size ])); +.fi +.SH DESCRIPTION +The +.BR bsearch () +function searches an array of +.I nmemb +objects, +the initial member of which is pointed to by +.IR base , +for a member +that matches the object pointed to by +.IR key . +The size of each member +of the array is specified by +.IR size . +.P +The contents of the array should be in ascending sorted order according +to the comparison function referenced by +.IR compar . +The +.I compar +routine is expected to have two arguments which point to the +.I key +object and to an array member, in that order, and should return an integer +less than, equal to, or greater than zero if the +.I key +object is found, +respectively, to be less than, to match, or be greater than the array +member. +.SH RETURN VALUE +The +.BR bsearch () +function returns a pointer to a matching member of the +array, or NULL if no match is found. +If there are multiple elements that +match the key, the element returned is unspecified. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR bsearch () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, C99, SVr4, 4.3BSD. +.SH EXAMPLES +The example below first sorts an array of structures using +.BR qsort (3), +then retrieves desired elements using +.BR bsearch (). +.P +.\" SRC BEGIN (bsearch.c) +.EX +#include +#include +#include +\& +#define ARRAY_SIZE(arr) (sizeof((arr)) / sizeof((arr)[0])) +\& +struct mi { + int nr; + const char *name; +}; +\& +static struct mi months[] = { + { 1, "jan" }, { 2, "feb" }, { 3, "mar" }, { 4, "apr" }, + { 5, "may" }, { 6, "jun" }, { 7, "jul" }, { 8, "aug" }, + { 9, "sep" }, {10, "oct" }, {11, "nov" }, {12, "dec" } +}; +\& +static int +compmi(const void *m1, const void *m2) +{ + const struct mi *mi1 = m1; + const struct mi *mi2 = m2; +\& + return strcmp(mi1\->name, mi2\->name); +} +\& +int +main(int argc, char *argv[]) +{ + qsort(months, ARRAY_SIZE(months), sizeof(months[0]), compmi); + for (size_t i = 1; i < argc; i++) { + struct mi key; + struct mi *res; +\& + key.name = argv[i]; + res = bsearch(&key, months, ARRAY_SIZE(months), + sizeof(months[0]), compmi); + if (res == NULL) + printf("\[aq]%s\[aq]: unknown month\en", argv[i]); + else + printf("%s: month #%d\en", res\->name, res\->nr); + } + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR hsearch (3), +.BR lsearch (3), +.BR qsort (3), +.BR tsearch (3) diff --git a/man/man3/bstring.3 b/man/man3/bstring.3 new file mode 100644 index 0000000..3f05757 --- /dev/null +++ b/man/man3/bstring.3 @@ -0,0 +1,76 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-04-12, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-01-20, Walter Harms +.TH bstring 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memfrob, memmem, +memmove, memset \- byte string operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int bcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n ); +.P +.BI "void bcopy(const void " src [. n "], void " dest [. n "], size_t " n ); +.P +.BI "void bzero(void " s [. n "], size_t " n ); +.P +.BI "void *memccpy(void " dest [. n "], const void " src [. n "], int " c ", \ +size_t " n ); +.P +.BI "void *memchr(const void " s [. n "], int " c ", size_t " n ); +.P +.BI "int memcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n ); +.P +.BI "void *memcpy(void " dest [. n "], const void " src [. n "], size_t " n ); +.P +.BI "void *memfrob(void " s [. n "], size_t " n ); +.P +.BI "void *memmem(const void " haystack [. haystacklen "], size_t " haystacklen , +.BI " const void " needle [. needlelen "], size_t " needlelen ); +.P +.BI "void *memmove(void " dest [. n "], const void " src [. n "], size_t " n ); +.P +.BI "void *memset(void " s [. n "], int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The byte string functions perform operations on strings (byte arrays) +that are not necessarily null-terminated. +See the individual man pages +for descriptions of each function. +.SH NOTES +The functions +.BR bcmp () +and +.BR bcopy () +are obsolete. +Use +.BR memcmp () +and +.BR memmove () +instead. +.\" The old functions are not even available on some non-GNU/Linux systems. +.SH SEE ALSO +.BR bcmp (3), +.BR bcopy (3), +.BR bzero (3), +.BR memccpy (3), +.BR memchr (3), +.BR memcmp (3), +.BR memcpy (3), +.BR memfrob (3), +.BR memmem (3), +.BR memmove (3), +.BR memset (3), +.BR string (3) diff --git a/man/man3/bswap.3 b/man/man3/bswap.3 new file mode 100644 index 0000000..0e4808f --- /dev/null +++ b/man/man3/bswap.3 @@ -0,0 +1,68 @@ +.\" Copyright (C) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH bswap 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bswap_16, bswap_32, bswap_64 \- reverse order of bytes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "uint16_t bswap_16(uint16_t " x ); +.BI "uint32_t bswap_32(uint32_t " x ); +.BI "uint64_t bswap_64(uint64_t " x ); +.fi +.SH DESCRIPTION +These functions return a value in which the order of the bytes +in their 2-, 4-, or 8-byte arguments is reversed. +.SH RETURN VALUE +These functions return the value of their argument with the bytes reversed. +.SH ERRORS +These functions always succeed. +.SH STANDARDS +GNU. +.SH EXAMPLES +The program below swaps the bytes of the 8-byte integer supplied as +its command-line argument. +The following shell session demonstrates the use of the program: +.P +.in +4n +.EX +$ \fB./a.out 0x0123456789abcdef\fP +0x123456789abcdef ==> 0xefcdab8967452301 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (bswap.c) +.EX +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + uint64_t x; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + x = strtoull(argv[1], NULL, 0); + printf("%#" PRIx64 " ==> %#" PRIx64 "\en", x, bswap_64(x)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR byteorder (3), +.BR endian (3) diff --git a/man/man3/bswap_16.3 b/man/man3/bswap_16.3 new file mode 100644 index 0000000..15a89ab --- /dev/null +++ b/man/man3/bswap_16.3 @@ -0,0 +1 @@ +.so man3/bswap.3 diff --git a/man/man3/bswap_32.3 b/man/man3/bswap_32.3 new file mode 100644 index 0000000..15a89ab --- /dev/null +++ b/man/man3/bswap_32.3 @@ -0,0 +1 @@ +.so man3/bswap.3 diff --git a/man/man3/bswap_64.3 b/man/man3/bswap_64.3 new file mode 100644 index 0000000..15a89ab --- /dev/null +++ b/man/man3/bswap_64.3 @@ -0,0 +1 @@ +.so man3/bswap.3 diff --git a/man/man3/btowc.3 b/man/man3/btowc.3 new file mode 100644 index 0000000..518211a --- /dev/null +++ b/man/man3/btowc.3 @@ -0,0 +1,86 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH btowc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +btowc \- convert single byte to wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wint_t btowc(int " c ); +.fi +.SH DESCRIPTION +The +.BR btowc () +function converts \fIc\fP, +interpreted as a multibyte sequence +of length 1, starting in the initial shift state, to a wide character and +returns it. +If \fIc\fP is +.B EOF +or not a valid multibyte sequence of length 1, +the +.BR btowc () +function returns +.BR WEOF . +.SH RETURN VALUE +The +.BR btowc () +function returns the wide character +converted from the single byte \fIc\fP. +If \fIc\fP is +.B EOF +or not a valid multibyte sequence of length 1, +it returns +.BR WEOF . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR btowc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +The behavior of +.BR btowc () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +This function should never be used. +It does not work for encodings which have +state, and unnecessarily treats single bytes differently from multibyte +sequences. +Use either +.BR mbtowc (3) +or the thread-safe +.BR mbrtowc (3) +instead. +.SH SEE ALSO +.BR mbrtowc (3), +.BR mbtowc (3), +.BR wctob (3) diff --git a/man/man3/btree.3 b/man/man3/btree.3 new file mode 100644 index 0000000..4919008 --- /dev/null +++ b/man/man3/btree.3 @@ -0,0 +1,229 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)btree.3 8.4 (Berkeley) 8/18/94 +.\" +.TH btree 3 2024-05-02 "Linux man-pages (unreleased)" +.\".UC 7 +.SH NAME +btree \- btree database access method +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.ft B +#include +#include +.ft R +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided up until glibc 2.1. +Since glibc 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.P +The routine +.BR dbopen (3) +is the library interface to database files. +One of the supported file formats is btree files. +The general description of the database access methods is in +.BR dbopen (3), +this manual page describes only the btree-specific information. +.P +The btree data structure is a sorted, balanced tree structure storing +associated key/data pairs. +.P +The btree access-method-specific data structure provided to +.BR dbopen (3) +is defined in the +.I +include file as follows: +.P +.in +4n +.EX +typedef struct { + unsigned long flags; + unsigned int cachesize; + int maxkeypage; + int minkeypage; + unsigned int psize; + int (*compare)(const DBT *key1, const DBT *key2); + size_t (*prefix)(const DBT *key1, const DBT *key2); + int lorder; +} BTREEINFO; +.EE +.in +.P +The elements of this structure are as follows: +.TP +.I flags +The flag value is specified by ORing any of the following values: +.RS +.TP +.B R_DUP +Permit duplicate keys in the tree, that is, +permit insertion if the key to be +inserted already exists in the tree. +The default behavior, as described in +.BR dbopen (3), +is to overwrite a matching key when inserting a new key or to fail if +the +.B R_NOOVERWRITE +flag is specified. +The +.B R_DUP +flag is overridden by the +.B R_NOOVERWRITE +flag, and if the +.B R_NOOVERWRITE +flag is specified, attempts to insert duplicate keys into +the tree will fail. +.IP +If the database contains duplicate keys, the order of retrieval of +key/data pairs is undefined if the +.I get +routine is used, however, +.I seq +routine calls with the +.B R_CURSOR +flag set will always return the logical +"first" of any group of duplicate keys. +.RE +.TP +.I cachesize +A suggested maximum size (in bytes) of the memory cache. +This value is +.I only +advisory, and the access method will allocate more memory rather than fail. +Since every search examines the root page of the tree, caching the most +recently used pages substantially improves access time. +In addition, physical writes are delayed as long as possible, so a moderate +cache can reduce the number of I/O operations significantly. +Obviously, using a cache increases (but only increases) the likelihood of +corruption or lost data if the system crashes while a tree is being modified. +If +.I cachesize +is 0 (no size is specified), a default cache is used. +.TP +.I maxkeypage +The maximum number of keys which will be stored on any single page. +Not currently implemented. +.\" The maximum number of keys which will be stored on any single page. +.\" Because of the way the btree data structure works, +.\" .I maxkeypage +.\" must always be greater than or equal to 2. +.\" If +.\" .I maxkeypage +.\" is 0 (no maximum number of keys is specified), the page fill factor is +.\" made as large as possible (which is almost invariably what is wanted). +.TP +.I minkeypage +The minimum number of keys which will be stored on any single page. +This value is used to determine which keys will be stored on overflow +pages, that is, if a key or data item is longer than the pagesize divided +by the minkeypage value, it will be stored on overflow pages instead +of in the page itself. +If +.I minkeypage +is 0 (no minimum number of keys is specified), a value of 2 is used. +.TP +.I psize +Page size is the size (in bytes) of the pages used for nodes in the tree. +The minimum page size is 512 bytes and the maximum page size is 64\ KiB. +If +.I psize +is 0 (no page size is specified), a page size is chosen based on the +underlying filesystem I/O block size. +.TP +.I compare +Compare is the key comparison function. +It must return an integer less than, equal to, or greater than zero if the +first key argument is considered to be respectively less than, equal to, +or greater than the second key argument. +The same comparison function must be used on a given tree every time it +is opened. +If +.I compare +is NULL (no comparison function is specified), the keys are compared +lexically, with shorter keys considered less than longer keys. +.TP +.I prefix +Prefix is the prefix comparison function. +If specified, this routine must return the number of bytes of the second key +argument which are necessary to determine that it is greater than the first +key argument. +If the keys are equal, the key length should be returned. +Note, the usefulness of this routine is very data-dependent, but, in some +data sets can produce significantly reduced tree sizes and search times. +If +.I prefix +is NULL (no prefix function is specified), +.I and +no comparison function is specified, a default lexical comparison routine +is used. +If +.I prefix +is NULL and a comparison routine is specified, no prefix comparison is +done. +.TP +.I lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified), the current host order is used. +.P +If the file already exists (and the +.B O_TRUNC +flag is not specified), the +values specified for the arguments +.IR flags , +.IR lorder , +and +.I psize +are ignored +in favor of the values used when the tree was created. +.P +Forward sequential scans of a tree are from the least key to the greatest. +.P +Space freed up by deleting key/data pairs from the tree is never reclaimed, +although it is normally made available for reuse. +This means that the btree storage structure is grow-only. +The only solutions are to avoid excessive deletions, or to create a fresh +tree periodically from a scan of an existing one. +.P +Searches, insertions, and deletions in a btree will all complete in +O lg base N where base is the average fill factor. +Often, inserting ordered data into btrees results in a low fill factor. +This implementation has been modified to make ordered insertion the best +case, resulting in a much better than normal page fill factor. +.SH ERRORS +The +.I btree +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR dbopen (3). +.SH BUGS +Only big and little endian byte order is supported. +.SH SEE ALSO +.BR dbopen (3), +.BR hash (3), +.BR mpool (3), +.BR recno (3) +.P +.IR "The Ubiquitous B-tree" , +Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979), 121-138. +.P +.IR "Prefix B-trees" , +Bayer and Unterauer, ACM Transactions on Database Systems, Vol. 2, 1 +(March 1977), 11-26. +.P +.IR "The Art of Computer Programming Vol. 3: Sorting and Searching" , +D.E. Knuth, 1968, pp 471-480. diff --git a/man/man3/byteorder.3 b/man/man3/byteorder.3 new file mode 100644 index 0000000..2e82db2 --- /dev/null +++ b/man/man3/byteorder.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:29:05 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Thu Jul 26 14:06:20 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH BYTEORDER 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +htonl, htons, ntohl, ntohs \- convert values between host and network +byte order +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "uint32_t htonl(uint32_t " hostlong ); +.BI "uint16_t htons(uint16_t " hostshort ); +.P +.BI "uint32_t ntohl(uint32_t " netlong ); +.BI "uint16_t ntohs(uint16_t " netshort ); +.fi +.SH DESCRIPTION +The +.BR htonl () +function converts the unsigned integer +.I hostlong +from host byte order to network byte order. +.P +The +.BR htons () +function converts the unsigned short integer +.I hostshort +from host byte order to network byte order. +.P +The +.BR ntohl () +function converts the unsigned integer +.I netlong +from network byte order to host byte order. +.P +The +.BR ntohs () +function converts the unsigned short integer +.I netshort +from network byte order to host byte order. +.P +On the i386 the host byte order is Least Significant Byte first, +whereas the network byte order, as used on the Internet, is Most +Significant Byte first. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR htonl (), +.BR htons (), +.BR ntohl (), +.BR ntohs () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR bswap (3), +.BR endian (3), +.BR gethostbyname (3), +.BR getservent (3) diff --git a/man/man3/bzero.3 b/man/man3/bzero.3 new file mode 100644 index 0000000..a50746f --- /dev/null +++ b/man/man3/bzero.3 @@ -0,0 +1,158 @@ +'\" t +.\" Copyright (C) 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH bzero 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bzero, explicit_bzero \- zero a byte string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void bzero(void " s [. n "], size_t " n ); +.P +.B #include +.P +.BI "void explicit_bzero(void " s [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR bzero () +function erases the data in the +.I n +bytes of the memory starting at the location pointed to by +.IR s , +by writing zeros (bytes containing \[aq]\e0\[aq]) to that area. +.P +The +.BR explicit_bzero () +function performs the same task as +.BR bzero (). +It differs from +.BR bzero () +in that it guarantees that compiler optimizations will not remove the +erase operation if the compiler deduces that the operation is "unnecessary". +.SH RETURN VALUE +None. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR bzero (), +.BR explicit_bzero () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR explicit_bzero () +glibc 2.25. +.IP +The +.BR explicit_bzero () +function is a nonstandard extension that is also present on some of the BSDs. +Some other implementations have a similar function, such as +.BR memset_explicit () +or +.BR memset_s (). +.TP +.BR bzero () +4.3BSD. +.IP +Marked as LEGACY in POSIX.1-2001. +Removed in POSIX.1-2008. +.SH NOTES +The +.BR explicit_bzero () +function addresses a problem that security-conscious applications +may run into when using +.BR bzero (): +if the compiler can deduce that the location to be zeroed will +never again be touched by a +.I correct +program, then it may remove the +.BR bzero () +call altogether. +This is a problem if the intent of the +.BR bzero () +call was to erase sensitive data (e.g., passwords) +to prevent the possibility that the data was leaked +by an incorrect or compromised program. +Calls to +.BR explicit_bzero () +are never optimized away by the compiler. +.P +The +.BR explicit_bzero () +function does not solve all problems associated with erasing sensitive data: +.IP \[bu] 3 +The +.BR explicit_bzero () +function does +.I not +guarantee that sensitive data is completely erased from memory. +(The same is true of +.BR bzero ().) +For example, there may be copies of the sensitive data in +a register and in "scratch" stack areas. +The +.BR explicit_bzero () +function is not aware of these copies, and can't erase them. +.IP \[bu] +In some circumstances, +.BR explicit_bzero () +can +.I decrease +security. +If the compiler determined that the variable containing the +sensitive data could be optimized to be stored in a register +(because it is small enough to fit in a register, +and no operation other than the +.BR explicit_bzero () +call would need to take the address of the variable), then the +.BR explicit_bzero () +call will force the data to be copied from the register +to a location in RAM that is then immediately erased +(while the copy in the register remains unaffected). +The problem here is that data in RAM is more likely to be exposed +by a bug than data in a register, and thus the +.BR explicit_bzero () +call creates a brief time window where the sensitive data is more +vulnerable than it would otherwise have been +if no attempt had been made to erase the data. +.P +Note that declaring the sensitive variable with the +.B volatile +qualifier does +.I not +eliminate the above problems. +Indeed, it will make them worse, since, for example, +it may force a variable that would otherwise have been optimized +into a register to instead be maintained in (more vulnerable) +RAM for its entire lifetime. +.P +Notwithstanding the above details, for security-conscious applications, using +.BR explicit_bzero () +is generally preferable to not using it. +The developers of +.BR explicit_bzero () +anticipate that future compilers will recognize calls to +.BR explicit_bzero () +and take steps to ensure that all copies of the sensitive data are erased, +including copies in registers or in "scratch" stack areas. +.SH SEE ALSO +.BR bstring (3), +.BR memset (3), +.BR swab (3) diff --git a/man/man3/cabs.3 b/man/man3/cabs.3 new file mode 100644 index 0000000..2a7a7c6 --- /dev/null +++ b/man/man3/cabs.3 @@ -0,0 +1,54 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cabs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cabs, cabsf, cabsl \- absolute value of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double cabs(double complex " z ); +.BI "float cabsf(float complex " z ); +.BI "long double cabsl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions return the absolute value of the complex number +.IR z . +The result is a real number. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cabs (), +.BR cabsf (), +.BR cabsl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH NOTES +The function is actually an alias for +.I "hypot(a,\ b)" +(or, equivalently, +.IR "sqrt(a*a\ +\ b*b)" ). +.SH SEE ALSO +.BR abs (3), +.BR cimag (3), +.BR hypot (3), +.BR complex (7) diff --git a/man/man3/cabsf.3 b/man/man3/cabsf.3 new file mode 100644 index 0000000..e50ac96 --- /dev/null +++ b/man/man3/cabsf.3 @@ -0,0 +1 @@ +.so man3/cabs.3 diff --git a/man/man3/cabsl.3 b/man/man3/cabsl.3 new file mode 100644 index 0000000..e50ac96 --- /dev/null +++ b/man/man3/cabsl.3 @@ -0,0 +1 @@ +.so man3/cabs.3 diff --git a/man/man3/cacos.3 b/man/man3/cacos.3 new file mode 100644 index 0000000..5319074 --- /dev/null +++ b/man/man3/cacos.3 @@ -0,0 +1,93 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cacos 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cacos, cacosf, cacosl \- complex arc cosine +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex cacos(double complex " z ); +.BI "float complex cacosf(float complex " z ); +.BI "long double complex cacosl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc cosine of +.IR z . +If \fIy\ =\ cacos(z)\fP, then \fIz\ =\ ccos(y)\fP. +The real part of +.I y +is chosen in the interval [0,pi]. +.P +One has: +.P +.nf + cacos(z) = \-i * clog(z + i * csqrt(1 \- z * z)) +.fi +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cacos (), +.BR cacosf (), +.BR cacosl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH EXAMPLES +.\" SRC BEGIN (cacos.c) +.EX +/* Link with "\-lm" */ +\& +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + double complex z, c, f; + double complex i = I; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + z = atof(argv[1]) + atof(argv[2]) * I; +\& + c = cacos(z); +\& + printf("cacos() = %6.3f %6.3f*i\en", creal(c), cimag(c)); +\& + f = \-i * clog(z + i * csqrt(1 \- z * z)); +\& + printf("formula = %6.3f %6.3f*i\en", creal(f), cimag(f)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ccos (3), +.BR clog (3), +.BR complex (7) diff --git a/man/man3/cacosf.3 b/man/man3/cacosf.3 new file mode 100644 index 0000000..a4f10e1 --- /dev/null +++ b/man/man3/cacosf.3 @@ -0,0 +1 @@ +.so man3/cacos.3 diff --git a/man/man3/cacosh.3 b/man/man3/cacosh.3 new file mode 100644 index 0000000..c36f08f --- /dev/null +++ b/man/man3/cacosh.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright 2002 Walter Harms(walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cacosh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cacosh, cacoshf, cacoshl \- complex arc hyperbolic cosine +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex cacosh(double complex " z ); +.BI "float complex cacoshf(float complex " z ); +.BI "long double complex cacoshl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc hyperbolic cosine of +.IR z . +If \fIy\ =\ cacosh(z)\fP, then \fIz\ =\ ccosh(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi,pi]. +The real part of +.I y +is chosen nonnegative. +.P +One has: +.P +.nf + cacosh(z) = 2 * clog(csqrt((z + 1) / 2) + csqrt((z \- 1) / 2)) +.fi +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cacosh (), +.BR cacoshf (), +.BR cacoshl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +glibc 2.1. +.SH EXAMPLES +.\" SRC BEGIN (cacosh.c) +.EX +/* Link with "\-lm" */ +\& +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + double complex z, c, f; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + z = atof(argv[1]) + atof(argv[2]) * I; +\& + c = cacosh(z); + printf("cacosh() = %6.3f %6.3f*i\en", creal(c), cimag(c)); +\& + f = 2 * clog(csqrt((z + 1)/2) + csqrt((z \- 1)/2)); + printf("formula = %6.3f %6.3f*i\en", creal(f), cimag(f)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR acosh (3), +.BR cabs (3), +.BR ccosh (3), +.BR cimag (3), +.BR complex (7) diff --git a/man/man3/cacoshf.3 b/man/man3/cacoshf.3 new file mode 100644 index 0000000..c89c010 --- /dev/null +++ b/man/man3/cacoshf.3 @@ -0,0 +1 @@ +.so man3/cacosh.3 diff --git a/man/man3/cacoshl.3 b/man/man3/cacoshl.3 new file mode 100644 index 0000000..c89c010 --- /dev/null +++ b/man/man3/cacoshl.3 @@ -0,0 +1 @@ +.so man3/cacosh.3 diff --git a/man/man3/cacosl.3 b/man/man3/cacosl.3 new file mode 100644 index 0000000..a4f10e1 --- /dev/null +++ b/man/man3/cacosl.3 @@ -0,0 +1 @@ +.so man3/cacos.3 diff --git a/man/man3/calloc.3 b/man/man3/calloc.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man/man3/calloc.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man/man3/callrpc.3 b/man/man3/callrpc.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/callrpc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/canonicalize_file_name.3 b/man/man3/canonicalize_file_name.3 new file mode 100644 index 0000000..a421057 --- /dev/null +++ b/man/man3/canonicalize_file_name.3 @@ -0,0 +1,80 @@ +'\" t +.\" Copyright 2013 Michael Kerrisk +.\" (Replaces an earlier page by Walter Harms and Michael Kerrisk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH canonicalize_file_name 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +canonicalize_file_name \- return the canonicalized absolute pathname +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "char *canonicalize_file_name(const char *" path ");" +.fi +.SH DESCRIPTION +The +.BR canonicalize_file_name () +function returns a null-terminated string containing +the canonicalized absolute pathname corresponding to +.IR path . +In the returned string, symbolic links are resolved, as are +.I . +and +.I .. +pathname components. +Consecutive slash +.RI ( / ) +characters are replaced by a single slash. +.P +The returned string is dynamically allocated by +.BR canonicalize_file_name () +and the caller should deallocate it with +.BR free (3) +when it is no longer required. +.P +The call +.I canonicalize_file_name(path) +is equivalent to the call: +.P +.in +4n +.EX +realpath(path, NULL); +.EE +.in +.SH RETURN VALUE +On success, +.BR canonicalize_file_name () +returns a null-terminated string. +On error (e.g., a pathname component is unreadable or does not exist), +.BR canonicalize_file_name () +returns NULL and sets +.I errno +to indicate the error. +.SH ERRORS +See +.BR realpath (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR canonicalize_file_name () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR readlink (2), +.BR realpath (3) diff --git a/man/man3/carg.3 b/man/man3/carg.3 new file mode 100644 index 0000000..8773247 --- /dev/null +++ b/man/man3/carg.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH carg 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +carg, cargf, cargl \- calculate the complex argument +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double carg(double complex " z ");" +.BI "float cargf(float complex " z ");" +.BI "long double cargl(long double complex " z ");" +.fi +.SH DESCRIPTION +These functions calculate the complex argument (also called phase angle) of +.IR z , +with a branch cut along the negative real axis. +.P +A complex number can be described by two real coordinates. +One may use rectangular coordinates and gets +.P +.in +4n +.EX +z = x + I * y +.EE +.in +.P +where +.I x\~=\~creal(z) +and +.IR y\~=\~cimag(z) . +.P +Or one may use polar coordinates and gets +.P +.in +4n +.EX +z = r * cexp(I * a) +.EE +.in +.P +where +.I r\~=\~cabs(z) +is the "radius", the "modulus", the absolute value of +.IR z , +and +.I a\~=\~carg(z) +is the "phase angle", the argument of +.IR z . +.P +One has: +.P +.in +4n +.EX +tan(carg(z)) = cimag(z) / creal(z) +.EE +.in +.SH RETURN VALUE +The return value is in the range of [\-pi,pi]. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR carg (), +.BR cargf (), +.BR cargl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR complex (7) diff --git a/man/man3/cargf.3 b/man/man3/cargf.3 new file mode 100644 index 0000000..c181aa4 --- /dev/null +++ b/man/man3/cargf.3 @@ -0,0 +1 @@ +.so man3/carg.3 diff --git a/man/man3/cargl.3 b/man/man3/cargl.3 new file mode 100644 index 0000000..c181aa4 --- /dev/null +++ b/man/man3/cargl.3 @@ -0,0 +1 @@ +.so man3/carg.3 diff --git a/man/man3/casin.3 b/man/man3/casin.3 new file mode 100644 index 0000000..95b308c --- /dev/null +++ b/man/man3/casin.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH casin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +casin, casinf, casinl \- complex arc sine +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex casin(double complex " z ); +.BI "float complex casinf(float complex " z ); +.BI "long double complex casinl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc sine of +.IR z . +If \fIy\ =\ casin(z)\fP, then \fIz\ =\ csin(y)\fP. +The real part of +.I y +is chosen in the interval [\-pi/2,pi/2]. +.P +One has: +.P +.nf + casin(z) = \-i clog(iz + csqrt(1 \- z * z)) +.fi +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR casin (), +.BR casinf (), +.BR casinl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR clog (3), +.BR csin (3), +.BR complex (7) diff --git a/man/man3/casinf.3 b/man/man3/casinf.3 new file mode 100644 index 0000000..582875f --- /dev/null +++ b/man/man3/casinf.3 @@ -0,0 +1 @@ +.so man3/casin.3 diff --git a/man/man3/casinh.3 b/man/man3/casinh.3 new file mode 100644 index 0000000..950f011 --- /dev/null +++ b/man/man3/casinh.3 @@ -0,0 +1,61 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH casinh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +casinh, casinhf, casinhl \- complex arc sine hyperbolic +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex casinh(double complex " z ); +.BI "float complex casinhf(float complex " z ); +.BI "long double complex casinhl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc hyperbolic sine of +.IR z . +If \fIy\~=\~casinh(z)\fP, then \fIz\~=\~csinh(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi/2,pi/2]. +.P +One has: +.P +.in +4n +.EX +casinh(z) = clog(z + csqrt(z * z + 1)) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR casinh (), +.BR casinhf (), +.BR casinhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR asinh (3), +.BR cabs (3), +.BR cimag (3), +.BR csinh (3), +.BR complex (7) diff --git a/man/man3/casinhf.3 b/man/man3/casinhf.3 new file mode 100644 index 0000000..c2eada8 --- /dev/null +++ b/man/man3/casinhf.3 @@ -0,0 +1 @@ +.so man3/casinh.3 diff --git a/man/man3/casinhl.3 b/man/man3/casinhl.3 new file mode 100644 index 0000000..c2eada8 --- /dev/null +++ b/man/man3/casinhl.3 @@ -0,0 +1 @@ +.so man3/casinh.3 diff --git a/man/man3/casinl.3 b/man/man3/casinl.3 new file mode 100644 index 0000000..582875f --- /dev/null +++ b/man/man3/casinl.3 @@ -0,0 +1 @@ +.so man3/casin.3 diff --git a/man/man3/catan.3 b/man/man3/catan.3 new file mode 100644 index 0000000..67be9c2 --- /dev/null +++ b/man/man3/catan.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH catan 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +catan, catanf, catanl \- complex arc tangents +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex catan(double complex " z ); +.BI "float complex catanf(float complex " z ); +.BI "long double complex catanl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc tangent of +.IR z . +If \fIy\~=\~catan(z)\fP, then \fIz\~=\~ctan(y)\fP. +The real part of +.I y +is chosen in the interval [\-pi/2, pi/2]. +.P +One has: +.P +.in +4n +.EX +catan(z) = (clog(1 + i * z) \- clog(1 \- i * z)) / (2 * i) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR catan (), +.BR catanf (), +.BR catanl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH EXAMPLES +.\" SRC BEGIN (catan.c) +.EX +/* Link with "\-lm" */ +\& +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + double complex z, c, f; + double complex i = I; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + z = atof(argv[1]) + atof(argv[2]) * I; +\& + c = catan(z); + printf("catan() = %6.3f %6.3f*i\en", creal(c), cimag(c)); +\& + f = (clog(1 + i * z) \- clog(1 \- i * z)) / (2 * i); + printf("formula = %6.3f %6.3f*i\en", creal(f), cimag(f)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ccos (3), +.BR clog (3), +.BR ctan (3), +.BR complex (7) diff --git a/man/man3/catanf.3 b/man/man3/catanf.3 new file mode 100644 index 0000000..d1e2522 --- /dev/null +++ b/man/man3/catanf.3 @@ -0,0 +1 @@ +.so man3/catan.3 diff --git a/man/man3/catanh.3 b/man/man3/catanh.3 new file mode 100644 index 0000000..4567495 --- /dev/null +++ b/man/man3/catanh.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright (C) 2011 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH catanh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +catanh, catanhf, catanhl \- complex arc tangents hyperbolic +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex catanh(double complex " z ); +.BI "float complex catanhf(float complex " z ); +.BI "long double complex catanhl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex arc hyperbolic tangent of +.IR z . +If \fIy\~=\~catanh(z)\fP, then \fIz\~=\~ctanh(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi/2,pi/2]. +.P +One has: +.P +.in +4n +.EX +catanh(z) = 0.5 * (clog(1 + z) \- clog(1 \- z)) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR catanh (), +.BR catanhf (), +.BR catanhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH EXAMPLES +.\" SRC BEGIN (catanh.c) +.EX +/* Link with "\-lm" */ +\& +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + double complex z, c, f; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + z = atof(argv[1]) + atof(argv[2]) * I; +\& + c = catanh(z); + printf("catanh() = %6.3f %6.3f*i\en", creal(c), cimag(c)); +\& + f = 0.5 * (clog(1 + z) \- clog(1 \- z)); + printf("formula = %6.3f %6.3f*i\en", creal(f), cimag(f)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR atanh (3), +.BR cabs (3), +.BR cimag (3), +.BR ctanh (3), +.BR complex (7) diff --git a/man/man3/catanhf.3 b/man/man3/catanhf.3 new file mode 100644 index 0000000..23f22a4 --- /dev/null +++ b/man/man3/catanhf.3 @@ -0,0 +1 @@ +.so man3/catanh.3 diff --git a/man/man3/catanhl.3 b/man/man3/catanhl.3 new file mode 100644 index 0000000..23f22a4 --- /dev/null +++ b/man/man3/catanhl.3 @@ -0,0 +1 @@ +.so man3/catanh.3 diff --git a/man/man3/catanl.3 b/man/man3/catanl.3 new file mode 100644 index 0000000..d1e2522 --- /dev/null +++ b/man/man3/catanl.3 @@ -0,0 +1 @@ +.so man3/catan.3 diff --git a/man/man3/catclose.3 b/man/man3/catclose.3 new file mode 100644 index 0000000..92ff666 --- /dev/null +++ b/man/man3/catclose.3 @@ -0,0 +1 @@ +.so man3/catopen.3 diff --git a/man/man3/catgets.3 b/man/man3/catgets.3 new file mode 100644 index 0000000..02dc5bc --- /dev/null +++ b/man/man3/catgets.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright 1993 Mitchum DSouza +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Updated, aeb, 980809 +.TH catgets 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +catgets \- get message from a message catalog +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *catgets(nl_catd " catalog ", int " set_number \ +", int " message_number , +.BI " const char *" message ); +.fi +.SH DESCRIPTION +.BR catgets () +reads the message +.IR message_number , +in set +.IR set_number , +from the message catalog identified by +.IR catalog , +where +.I catalog +is a catalog descriptor returned from an earlier call to +.BR catopen (3). +The fourth argument, +.IR message , +points to a default message string which will be returned by +.BR catgets () +if the identified message catalog is not currently available. +The +message-text is contained in an internal buffer area and should be copied by +the application if it is to be saved or modified. +The return string is +always terminated with a null byte (\[aq]\e0\[aq]). +.SH RETURN VALUE +On success, +.BR catgets () +returns a pointer to an internal buffer area +containing the null-terminated message string. +On failure, +.BR catgets () +returns the value +.IR message . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR catgets () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +The +.BR catgets () +function is available only in libc.so.4.4.4c and above. +.P +The Jan 1987 X/Open Portability Guide specifies a more subtle +error return: +.I message +is returned if the message catalog specified by +.I catalog +is not available, while an empty string is returned +when the message catalog is available but does not contain +the specified message. +These two possible error returns seem to be discarded in SUSv2 +in favor of always returning +.IR message . +.SH SEE ALSO +.BR catopen (3), +.BR setlocale (3) diff --git a/man/man3/catopen.3 b/man/man3/catopen.3 new file mode 100644 index 0000000..278213f --- /dev/null +++ b/man/man3/catopen.3 @@ -0,0 +1,199 @@ +'\" t +.\" Copyright 1993 Mitchum DSouza +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Thu Dec 13 22:51:19 2001 by Martin Schulze +.\" Modified 2001-12-14 aeb +.\" +.TH catopen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +catopen, catclose \- open/close a message catalog +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "nl_catd catopen(const char *" name ", int " flag ); +.BI "int catclose(nl_catd " catalog ); +.fi +.SH DESCRIPTION +The function +.BR catopen () +opens a message catalog and returns a catalog descriptor. +The descriptor remains valid until +.BR catclose () +or +.BR execve (2). +If a file descriptor is used to implement catalog descriptors, +then the +.B FD_CLOEXEC +flag will be set. +.P +The argument +.I name +specifies the name of the message catalog to be opened. +If +.I name +specifies an absolute path (i.e., contains a \[aq]/\[aq]), +then +.I name +specifies a pathname for the message catalog. +Otherwise, the environment variable +.B NLSPATH +is used with +.I name +substituted for +.B %N +(see +.BR locale (7)). +It is unspecified whether +.B NLSPATH +will be used when the process has root privileges. +If +.B NLSPATH +does not exist in the environment, +or if a message catalog cannot be opened +in any of the paths specified by it, +then an implementation defined path is used. +This latter default path may depend on the +.B LC_MESSAGES +locale setting when the +.I flag +argument is +.B NL_CAT_LOCALE +and on the +.B LANG +environment variable when the +.I flag +argument is 0. +Changing the +.B LC_MESSAGES +part of the locale may invalidate +open catalog descriptors. +.P +The +.I flag +argument to +.BR catopen () +is used to indicate the source for the language to use. +If it is set to +.BR NL_CAT_LOCALE , +then it will use the current locale setting for +.BR LC_MESSAGES . +Otherwise, it will use the +.B LANG +environment variable. +.P +The function +.BR catclose () +closes the message catalog identified by +.IR catalog . +It invalidates any subsequent references to the message catalog +defined by +.IR catalog . +.SH RETURN VALUE +The function +.BR catopen () +returns a message catalog descriptor of type +.I nl_catd +on success. +On failure, it returns +.I (nl_catd)\~\-1 +and sets +.I errno +to indicate the error. +The possible error values include all +possible values for the +.BR open (2) +call. +.P +The function +.BR catclose () +returns 0 on success, or \-1 on failure. +.SH ENVIRONMENT +.TP +.B LC_MESSAGES +May be the source of the +.B LC_MESSAGES +locale setting, and thus +determine the language to use if +.I flag +is set to +.BR NL_CAT_LOCALE . +.TP +.B LANG +The language to use if +.I flag +is 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR catopen () +T} Thread safety MT-Safe env +T{ +.na +.nh +.BR catclose () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The above is the POSIX.1 description. +The glibc value for +.B NL_CAT_LOCALE +is 1. +.\" (Compare +.\" .B MCLoadAll +.\" below.) +The default path varies, but usually looks at a number of places below +.IR /usr/share/locale . +.\" .SS Linux notes +.\" These functions are available for Linux since libc 4.4.4c. +.\" In the case of linux libc4 and libc5, the catalog descriptor +.\" .I nl_catd +.\" is a +.\" .BR mmap (2)'ed +.\" area of memory and not a file descriptor. +.\" The +.\" .I flag +.\" argument to +.\" .BR catopen () +.\" should be either +.\" .B MCLoadBySet +.\" (=0) or +.\" .B MCLoadAll +.\" (=1). +.\" The former value indicates that a set from the catalog is to be +.\" loaded when needed, whereas the latter causes the initial call to +.\" .BR catopen () +.\" to load the entire catalog into memory. +.\" The default search path varies, but usually looks at a number of places below +.\" .I /etc/locale +.\" and +.\" .IR /usr/lib/locale . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.\" In XPG 1987, Vol. 3 it says: +.\" .I "The flag argument of catopen is reserved for future use" +.\" .IR "and should be set to 0" . +.\" +.\" It is unclear what the source was for the constants +.\" .B MCLoadBySet +.\" and +.\" .B MCLoadAll +.\" (see below). +.SH SEE ALSO +.BR catgets (3), +.BR setlocale (3) diff --git a/man/man3/cbc_crypt.3 b/man/man3/cbc_crypt.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man/man3/cbc_crypt.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man/man3/cbrt.3 b/man/man3/cbrt.3 new file mode 100644 index 0000000..bf5a62b --- /dev/null +++ b/man/man3/cbrt.3 @@ -0,0 +1,90 @@ +'\" t +.\" Copyright 1995 Jim Van Zandt +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" changed `square root' into `cube root' - aeb, 950919 +.\" +.\" Modified 2002-07-27 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH cbrt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cbrt, cbrtf, cbrtl \- cube root function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double cbrt(double " x ); +.BI "float cbrtf(float " x ); +.BI "long double cbrtl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR cbrt (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR cbrtf (), +.BR cbrtl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the (real) cube root of +.IR x . +This function cannot fail; +every representable real value +has a real cube root, +and rounding it to a representable value +never causes overflow nor underflow. +.SH RETURN VALUE +These functions return the cube root of +.IR x . +.P +If +.I x +is +0, \-0, positive infinity, negative infinity, or NaN, +.I x +is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cbrt (), +.BR cbrtf (), +.BR cbrtl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.\" .BR cbrt () +.\" was a GNU extension. It is now a C99 requirement. +.SH SEE ALSO +.BR pow (3), +.BR sqrt (3) diff --git a/man/man3/cbrtf.3 b/man/man3/cbrtf.3 new file mode 100644 index 0000000..b662c9e --- /dev/null +++ b/man/man3/cbrtf.3 @@ -0,0 +1 @@ +.so man3/cbrt.3 diff --git a/man/man3/cbrtl.3 b/man/man3/cbrtl.3 new file mode 100644 index 0000000..b662c9e --- /dev/null +++ b/man/man3/cbrtl.3 @@ -0,0 +1 @@ +.so man3/cbrt.3 diff --git a/man/man3/ccos.3 b/man/man3/ccos.3 new file mode 100644 index 0000000..b0c7303 --- /dev/null +++ b/man/man3/ccos.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ccos 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ccos, ccosf, ccosl \- complex cosine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex ccos(double complex " z ); +.BI "float complex ccosf(float complex " z ); +.BI "long double complex ccosl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex cosine of +.IR z . +.P +The complex cosine function is defined as: +.P +.in +4n +.EX +ccos(z) = (exp(i * z) + exp(\-i * z)) / 2 +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ccos (), +.BR ccosf (), +.BR ccosl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cacos (3), +.BR csin (3), +.BR ctan (3), +.BR complex (7) diff --git a/man/man3/ccosf.3 b/man/man3/ccosf.3 new file mode 100644 index 0000000..b4323ff --- /dev/null +++ b/man/man3/ccosf.3 @@ -0,0 +1 @@ +.so man3/ccos.3 diff --git a/man/man3/ccosh.3 b/man/man3/ccosh.3 new file mode 100644 index 0000000..2261873 --- /dev/null +++ b/man/man3/ccosh.3 @@ -0,0 +1,40 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ccosh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ccosh, ccoshf, ccoshl \- complex hyperbolic cosine +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex ccosh(double complex " z ); +.BI "float complex ccoshf(float complex " z ); +.BI "long double complex ccoshl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex hyperbolic cosine of +.IR z . +.P +The complex hyperbolic cosine function is defined as: +.P +.in +4n +.EX +ccosh(z) = (exp(z)+exp(\-z))/2 +.EE +.in +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cacosh (3), +.BR csinh (3), +.BR ctanh (3), +.BR complex (7) diff --git a/man/man3/ccoshf.3 b/man/man3/ccoshf.3 new file mode 100644 index 0000000..a777fbf --- /dev/null +++ b/man/man3/ccoshf.3 @@ -0,0 +1 @@ +.so man3/ccosh.3 diff --git a/man/man3/ccoshl.3 b/man/man3/ccoshl.3 new file mode 100644 index 0000000..a777fbf --- /dev/null +++ b/man/man3/ccoshl.3 @@ -0,0 +1 @@ +.so man3/ccosh.3 diff --git a/man/man3/ccosl.3 b/man/man3/ccosl.3 new file mode 100644 index 0000000..b4323ff --- /dev/null +++ b/man/man3/ccosl.3 @@ -0,0 +1 @@ +.so man3/ccos.3 diff --git a/man/man3/ceil.3 b/man/man3/ceil.3 new file mode 100644 index 0000000..b0f26c6 --- /dev/null +++ b/man/man3/ceil.3 @@ -0,0 +1,115 @@ +'\" t +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH ceil 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ceil, ceilf, ceill \- ceiling function: smallest integral value not +less than argument +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double ceil(double " x ); +.BI "float ceilf(float " x ); +.BI "long double ceill(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ceilf (), +.BR ceill (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the smallest integral value that is not less than +.IR x . +.P +For example, +.I ceil(0.5) +is 1.0, and +.I ceil(\-0.5) +is 0.0. +.SH RETURN VALUE +These functions return the ceiling of +.IR x . +.P +If +.I x +is integral, +0, \-0, NaN, or infinite, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ceil (), +.BR ceilf (), +.BR ceill () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH NOTES +SUSv2 and POSIX.1-2001 contain text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +.\" The POSIX.1-2001 APPLICATION USAGE SECTION discusses this point. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 127 (respectively, 1023), +and the number of mantissa bits +including the implicit bit +is 24 (respectively, 53).) +.P +The integral value returned by these functions may be too large +to store in an integer type +.RI ( int , +.IR long , +etc.). +To avoid an overflow, which will produce undefined results, +an application should perform a range check on the returned value +before assigning it to an integer type. +.SH SEE ALSO +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3), +.BR trunc (3) diff --git a/man/man3/ceilf.3 b/man/man3/ceilf.3 new file mode 100644 index 0000000..569d1ba --- /dev/null +++ b/man/man3/ceilf.3 @@ -0,0 +1 @@ +.so man3/ceil.3 diff --git a/man/man3/ceill.3 b/man/man3/ceill.3 new file mode 100644 index 0000000..569d1ba --- /dev/null +++ b/man/man3/ceill.3 @@ -0,0 +1 @@ +.so man3/ceil.3 diff --git a/man/man3/cexp.3 b/man/man3/cexp.3 new file mode 100644 index 0000000..6894c0d --- /dev/null +++ b/man/man3/cexp.3 @@ -0,0 +1,58 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cexp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cexp, cexpf, cexpl \- complex exponential function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex cexp(double complex " z ); +.BI "float complex cexpf(float complex " z ); +.BI "long double complex cexpl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate e (2.71828..., the base of natural logarithms) +raised to the power of +.IR z . +.P +One has: +.P +.in +4n +.EX +cexp(I * z) = ccos(z) + I * csin(z) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cexp (), +.BR cexpf (), +.BR cexpl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cexp2 (3), +.BR clog (3), +.BR cpow (3), +.BR complex (7) diff --git a/man/man3/cexp2.3 b/man/man3/cexp2.3 new file mode 100644 index 0000000..dcc4839 --- /dev/null +++ b/man/man3/cexp2.3 @@ -0,0 +1,31 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cexp2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cexp2, cexp2f, cexp2l \- base-2 exponent of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex cexp2(double complex " z ); +.BI "float complex cexp2f(float complex " z ); +.BI "long double complex cexp2l(long double complex " z ); +.fi +.SH DESCRIPTION +The function returns 2 raised to the power of +.IR z . +.SH STANDARDS +These function names are reserved for future use in C99. +.P +As at glibc 2.31, these functions are not provided in glibc. +.\" But reserved in NAMESPACE. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog10 (3), +.BR complex (7) diff --git a/man/man3/cexp2f.3 b/man/man3/cexp2f.3 new file mode 100644 index 0000000..759ad34 --- /dev/null +++ b/man/man3/cexp2f.3 @@ -0,0 +1 @@ +.so man3/cexp2.3 diff --git a/man/man3/cexp2l.3 b/man/man3/cexp2l.3 new file mode 100644 index 0000000..759ad34 --- /dev/null +++ b/man/man3/cexp2l.3 @@ -0,0 +1 @@ +.so man3/cexp2.3 diff --git a/man/man3/cexpf.3 b/man/man3/cexpf.3 new file mode 100644 index 0000000..794d707 --- /dev/null +++ b/man/man3/cexpf.3 @@ -0,0 +1 @@ +.so man3/cexp.3 diff --git a/man/man3/cexpl.3 b/man/man3/cexpl.3 new file mode 100644 index 0000000..794d707 --- /dev/null +++ b/man/man3/cexpl.3 @@ -0,0 +1 @@ +.so man3/cexp.3 diff --git a/man/man3/cfgetispeed.3 b/man/man3/cfgetispeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfgetispeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cfgetospeed.3 b/man/man3/cfgetospeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfgetospeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cfmakeraw.3 b/man/man3/cfmakeraw.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfmakeraw.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cfree.3 b/man/man3/cfree.3 new file mode 100644 index 0000000..7862e9a --- /dev/null +++ b/man/man3/cfree.3 @@ -0,0 +1,132 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH cfree 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cfree \- free allocated memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.P +.B "#include " +.P +/* In SunOS 4 */ +.BI "int cfree(void *" ptr ); +.P +/* In glibc or FreeBSD libcompat */ +.BI "void cfree(void *" ptr ); +.P +/* In SCO OpenServer */ +.BI "void cfree(char " ptr [. size " * ." num "], unsigned int " num ", \ +unsigned int " size ); +.P +/* In Solaris watchmalloc.so.1 */ +.BI "void cfree(void " ptr [. elsize " * ." nelem "], size_t " nelem ", \ +size_t " elsize ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR cfree (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +This function should never be used. +Use +.BR free (3) +instead. +Starting with glibc 2.26, it has been removed from glibc. +.SS 1-arg cfree +In glibc, the function +.BR cfree () +is a synonym for +.BR free (3), +"added for compatibility with SunOS". +.P +Other systems have other functions with this name. +The declaration is sometimes in +.I +and sometimes in +.IR . +.SS 3-arg cfree +Some SCO and Solaris versions have malloc libraries with a 3-argument +.BR cfree (), +apparently as an analog to +.BR calloc (3). +.P +If you need it while porting something, add +.P +.in +4n +.EX +#define cfree(p, n, s) free((p)) +.EE +.in +.P +to your file. +.P +A frequently asked question is "Can I use +.BR free (3) +to free memory allocated with +.BR calloc (3), +or do I need +.BR cfree ()?" +Answer: use +.BR free (3). +.P +An SCO manual writes: "The cfree routine is provided for compliance +to the iBCSe2 standard and simply calls free. +The num and size +arguments to cfree are not used." +.SH RETURN VALUE +The SunOS version of +.BR cfree () +(which is a synonym for +.BR free (3)) +returns 1 on success and 0 on failure. +In case of error, +.I errno +is set to +.BR EINVAL : +the value of +.I ptr +was not a pointer to a block previously allocated by +one of the routines in the +.BR malloc (3) +family. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cfree () +T} Thread safety MT-Safe /* In glibc */ +.TE +.SH VERSIONS +The 3-argument version of +.BR cfree () +as used by SCO conforms to the iBCSe2 standard: +Intel386 Binary Compatibility Specification, Edition 2. +.SH STANDARDS +None. +.SH HISTORY +.\" commit 025b33ae84bb8f15b2748a1d8605dca453fce112 +Removed in glibc 2.26. +.SH SEE ALSO +.BR malloc (3) diff --git a/man/man3/cfsetispeed.3 b/man/man3/cfsetispeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfsetispeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cfsetospeed.3 b/man/man3/cfsetospeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfsetospeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cfsetspeed.3 b/man/man3/cfsetspeed.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/cfsetspeed.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/cimag.3 b/man/man3/cimag.3 new file mode 100644 index 0000000..bc231fd --- /dev/null +++ b/man/man3/cimag.3 @@ -0,0 +1,58 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cimag 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cimag, cimagf, cimagl \- get imaginary part of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double cimag(double complex " z ); +.BI "float cimagf(float complex " z ); +.BI "long double cimagl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions return the imaginary part of the complex number +.IR z . +.P +One has: +.P +.in +4n +.EX +z = creal(z) + I * cimag(z) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cimag (), +.BR cimagf (), +.BR cimagl () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +GCC also supports __imag__. +That is a GNU extension. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR creal (3), +.BR complex (7) diff --git a/man/man3/cimagf.3 b/man/man3/cimagf.3 new file mode 100644 index 0000000..e806455 --- /dev/null +++ b/man/man3/cimagf.3 @@ -0,0 +1 @@ +.so man3/cimag.3 diff --git a/man/man3/cimagl.3 b/man/man3/cimagl.3 new file mode 100644 index 0000000..e806455 --- /dev/null +++ b/man/man3/cimagl.3 @@ -0,0 +1 @@ +.so man3/cimag.3 diff --git a/man/man3/circleq.3 b/man/man3/circleq.3 new file mode 100644 index 0000000..5fd74f2 --- /dev/null +++ b/man/man3/circleq.3 @@ -0,0 +1,318 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH CIRCLEQ 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +CIRCLEQ_EMPTY, +CIRCLEQ_ENTRY, +CIRCLEQ_FIRST, +CIRCLEQ_FOREACH, +CIRCLEQ_FOREACH_REVERSE, +CIRCLEQ_HEAD, +CIRCLEQ_HEAD_INITIALIZER, +CIRCLEQ_INIT, +CIRCLEQ_INSERT_AFTER, +CIRCLEQ_INSERT_BEFORE, +CIRCLEQ_INSERT_HEAD, +CIRCLEQ_INSERT_TAIL, +CIRCLEQ_LAST, +CIRCLEQ_LOOP_NEXT, +CIRCLEQ_LOOP_PREV, +CIRCLEQ_NEXT, +CIRCLEQ_PREV, +CIRCLEQ_REMOVE +\- implementation of a doubly linked circular queue +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B CIRCLEQ_ENTRY(TYPE); +.P +.B CIRCLEQ_HEAD(HEADNAME, TYPE); +.BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head ); +.BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head ); +.P +.BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head ); +.P +.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.P +.BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head ); +.BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head ); +.BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "struct TYPE *CIRCLEQ_NEXT(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "struct TYPE *CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.BI "struct TYPE *CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head , +.BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); +.P +.BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head , +.BI " CIRCLEQ_ENTRY " NAME ); +.BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head , +.BI " CIRCLEQ_ENTRY " NAME ); +.P +.BI "void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *" head ", struct TYPE *" elm , +.BI " CIRCLEQ_ENTRY " NAME ); +.fi +.SH DESCRIPTION +These macros define and operate on doubly linked circular queues. +.P +In the macro definitions, +.I TYPE +is the name of a user-defined structure, +that must contain a field of type +.IR CIRCLEQ_ENTRY , +named +.IR NAME . +The argument +.I HEADNAME +is the name of a user-defined structure +that must be declared using the macro +.BR CIRCLEQ_HEAD (). +.SS Creation +A circular queue is headed by a structure defined by the +.BR CIRCLEQ_HEAD () +macro. +This structure contains a pair of pointers, +one to the first element in the queue +and the other to the last element in the queue. +The elements are doubly linked +so that an arbitrary element can be removed without traversing the queue. +New elements can be added to the queue +after an existing element, +before an existing element, +at the head of the queue, +or at the end of the queue. +A +.I CIRCLEQ_HEAD +structure is declared as follows: +.P +.in +4 +.EX +CIRCLEQ_HEAD(HEADNAME, TYPE) head; +.EE +.in +.P +where +.I struct HEADNAME +is the structure to be defined, and +.I struct TYPE +is the type of the elements to be linked into the queue. +A pointer to the head of the queue can later be declared as: +.P +.in +4 +.EX +struct HEADNAME *headp; +.EE +.in +.P +(The names +.I head +and +.I headp +are user selectable.) +.P +.BR CIRCLEQ_ENTRY () +declares a structure that connects the elements in the queue. +.P +.BR CIRCLEQ_HEAD_INITIALIZER () +evaluates to an initializer for the queue +.IR head . +.P +.BR CIRCLEQ_INIT () +initializes the queue referenced by +.IR head . +.P +.BR CIRCLEQ_EMPTY () +evaluates to true if there are no items on the queue. +.SS Insertion +.BR CIRCLEQ_INSERT_HEAD () +inserts the new element +.I elm +at the head of the queue. +.P +.BR CIRCLEQ_INSERT_TAIL () +inserts the new element +.I elm +at the end of the queue. +.P +.BR CIRCLEQ_INSERT_BEFORE () +inserts the new element +.I elm +before the element +.IR listelm . +.P +.BR CIRCLEQ_INSERT_AFTER () +inserts the new element +.I elm +after the element +.IR listelm . +.SS Traversal +.BR CIRCLEQ_FIRST () +returns the first item on the queue. +.P +.BR CIRCLEQ_LAST () +returns the last item on the queue. +.P +.BR CIRCLEQ_PREV () +returns the previous item on the queue, or +.I &head +if this item is the first one. +.P +.BR CIRCLEQ_NEXT () +returns the next item on the queue, or +.I &head +if this item is the last one. +.P +.BR CIRCLEQ_LOOP_PREV () +returns the previous item on the queue. +If +.I elm +is the first element on the queue, the last element is returned. +.P +.BR CIRCLEQ_LOOP_NEXT () +returns the next item on the queue. +If +.I elm +is the last element on the queue, the first element is returned. +.P +.BR CIRCLEQ_FOREACH () +traverses the queue referenced by +.I head +in the forward direction, assigning each element in turn to +.IR var . +.I var +is set to +.I &head +if the loop completes normally, or if there were no elements. +.P +.BR CIRCLEQ_FOREACH_REVERSE () +traverses the queue referenced by +.I head +in the reverse direction, +assigning each element in turn to +.IR var . +.SS Removal +.BR CIRCLEQ_REMOVE () +removes the element +.I elm +from the queue. +.SH RETURN VALUE +.BR CIRCLEQ_EMPTY () +returns nonzero if the queue is empty, +and zero if the queue contains at least one entry. +.P +.BR CIRCLEQ_FIRST (), +.BR CIRCLEQ_LAST (), +.BR CIRCLEQ_LOOP_PREV (), +and +.BR CIRCLEQ_LOOP_NEXT () +return a pointer to the first, last, previous, or next +.I TYPE +structure, respectively. +.P +.BR CIRCLEQ_PREV (), +and +.BR CIRCLEQ_NEXT () +are similar to their +.BR CIRCLEQ_LOOP_* () +counterparts, +except that if the argument is the first or last element, respectively, +they return +.IR &head . +.P +.BR CIRCLEQ_HEAD_INITIALIZER () +returns an initializer that can be assigned to the queue +.IR head . +.SH STANDARDS +BSD. +.SH BUGS +.BR CIRCLEQ_FOREACH () +and +.BR CIRCLEQ_FOREACH_REVERSE () +don't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +.BR CIRCLEQ_FOREACH_SAFE () +and +.BR CIRCLEQ_FOREACH_REVERSE_SAFE (), +which are present on the BSDs but are not present in glibc, +fix this limitation by allowing +.I var +to safely be removed from the list and freed from within the loop +without interfering with the traversal. +.SH EXAMPLES +.\" SRC BEGIN (circleq.c) +.EX +#include +#include +#include +#include +\& +struct entry { + int data; + CIRCLEQ_ENTRY(entry) entries; /* Queue */ +}; +\& +CIRCLEQ_HEAD(circlehead, entry); +\& +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct circlehead head; /* Queue head */ + int i; +\& + CIRCLEQ_INIT(&head); /* Initialize the queue */ +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the head */ + CIRCLEQ_INSERT_HEAD(&head, n1, entries); +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the tail */ + CIRCLEQ_INSERT_TAIL(&head, n1, entries); +\& + n2 = malloc(sizeof(struct entry)); /* Insert after */ + CIRCLEQ_INSERT_AFTER(&head, n1, n2, entries); +\& + n3 = malloc(sizeof(struct entry)); /* Insert before */ + CIRCLEQ_INSERT_BEFORE(&head, n2, n3, entries); +\& + CIRCLEQ_REMOVE(&head, n2, entries); /* Deletion */ + free(n2); + /* Forward traversal */ + i = 0; + CIRCLEQ_FOREACH(np, &head, entries) + np\->data = i++; + /* Reverse traversal */ + CIRCLEQ_FOREACH_REVERSE(np, &head, entries) + printf("%i\en", np\->data); + /* Queue deletion */ + n1 = CIRCLEQ_FIRST(&head); + while (n1 != (void *)&head) { + n2 = CIRCLEQ_NEXT(n1, entries); + free(n1); + n1 = n2; + } + CIRCLEQ_INIT(&head); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR insque (3), +.BR queue (7) diff --git a/man/man3/clearenv.3 b/man/man3/clearenv.3 new file mode 100644 index 0000000..5a6a738 --- /dev/null +++ b/man/man3/clearenv.3 @@ -0,0 +1,137 @@ +'\" t +.\" Copyright 2001 John Levon +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Additions, aeb, 2001-10-17. +.TH clearenv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clearenv \- clear the environment +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B "int clearenv(void);" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR clearenv (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR clearenv () +function clears the environment of all name-value +pairs and sets the value of the external variable +.I environ +to NULL. +After this call, new variables can be added to the environment using +.BR putenv (3) +and +.BR setenv (3). +.SH RETURN VALUE +The +.BR clearenv () +function returns zero on success, and a nonzero +value on failure. +.\" Most versions of UNIX return -1 on error, or do not even have errors. +.\" glibc info and the Watcom C library document "a nonzero value". +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clearenv () +T} Thread safety MT-Unsafe const:env +.TE +.SH STANDARDS +.TP +.BR putenv () +POSIX.1-2008. +.TP +.BR clearenv () +None. +.SH HISTORY +.TP +.BR putenv () +glibc 2.0. +POSIX.1-2001. +.TP +.BR clearenv () +glibc 2.0. +.P +Various UNIX variants (DG/UX, HP-UX, QNX, ...). +POSIX.9 (bindings for FORTRAN77). +POSIX.1-1996 did not accept +.BR clearenv () +and +.BR putenv (3), +but changed its mind and scheduled these functions for some +later issue of this standard (see \[sc]B.4.6.1). +However, POSIX.1-2001 +adds only +.BR putenv (3), +and rejected +.BR clearenv (). +.SH NOTES +On systems where +.BR clearenv () +is unavailable, the assignment +.P +.in +4n +.EX +environ = NULL; +.EE +.in +.P +will probably do. +.P +The +.BR clearenv () +function may be useful in security-conscious applications that want to +precisely control the environment that is passed to programs +executed using +.BR exec (3). +The application would do this by first clearing the environment +and then adding select environment variables. +.P +Note that the main effect of +.BR clearenv () +is to adjust the value of the pointer +.BR environ (7); +this function does not erase the contents of the buffers +containing the environment definitions. +.P +The DG/UX and Tru64 man pages write: If +.I environ +has been modified by anything other than the +.BR putenv (3), +.BR getenv (3), +or +.BR clearenv () +functions, then +.BR clearenv () +will return an error and the process environment will remain unchanged. +.\" .P +.\" HP-UX has a ENOMEM error return. +.SH SEE ALSO +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR environ (7) diff --git a/man/man3/clearerr.3 b/man/man3/clearerr.3 new file mode 100644 index 0000000..3a95cca --- /dev/null +++ b/man/man3/clearerr.3 @@ -0,0 +1 @@ +.so man3/ferror.3 diff --git a/man/man3/clearerr_unlocked.3 b/man/man3/clearerr_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/clearerr_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/clnt_broadcast.3 b/man/man3/clnt_broadcast.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_broadcast.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_call.3 b/man/man3/clnt_call.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_call.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_control.3 b/man/man3/clnt_control.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_control.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_create.3 b/man/man3/clnt_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_destroy.3 b/man/man3/clnt_destroy.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_freeres.3 b/man/man3/clnt_freeres.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_freeres.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_geterr.3 b/man/man3/clnt_geterr.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_geterr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_pcreateerror.3 b/man/man3/clnt_pcreateerror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_pcreateerror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_perrno.3 b/man/man3/clnt_perrno.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_perrno.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_perror.3 b/man/man3/clnt_perror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_perror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_spcreateerror.3 b/man/man3/clnt_spcreateerror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_spcreateerror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_sperrno.3 b/man/man3/clnt_sperrno.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_sperrno.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnt_sperror.3 b/man/man3/clnt_sperror.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnt_sperror.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clntraw_create.3 b/man/man3/clntraw_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clntraw_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clnttcp_create.3 b/man/man3/clnttcp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clnttcp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clntudp_bufcreate.3 b/man/man3/clntudp_bufcreate.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clntudp_bufcreate.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clntudp_create.3 b/man/man3/clntudp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/clntudp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/clock.3 b/man/man3/clock.3 new file mode 100644 index 0000000..0019552 --- /dev/null +++ b/man/man3/clock.3 @@ -0,0 +1,101 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 21:27:01 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 14 Jun 2002, Michael Kerrisk +.\" Added notes on differences from other UNIX systems with respect to +.\" waited-for children. +.TH clock 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clock \- determine processor time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B clock_t clock(void); +.fi +.SH DESCRIPTION +The +.BR clock () +function returns an approximation of processor time used by the program. +.SH RETURN VALUE +The value returned is the CPU time used so far as a +.IR clock_t ; +to get the number of seconds used, divide by +.BR CLOCKS_PER_SEC . +If the processor time used is not available or its value cannot +be represented, the function returns the value +.IR (clock_t)\ \-1 . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clock () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +XSI requires that +.B CLOCKS_PER_SEC +equals 1000000 independent +of the actual resolution. +.P +On several other implementations, +the value returned by +.BR clock () +also includes the times of any children whose status has been +collected via +.BR wait (2) +(or another wait-type call). +Linux does not include the times of waited-for children in the +value returned by +.BR clock (). +.\" I have seen this behavior on Irix 6.3, and the OSF/1, HP/UX, and +.\" Solaris manual pages say that clock() also does this on those systems. +.\" POSIX.1-2001 doesn't explicitly allow this, nor is there an +.\" explicit prohibition. -- MTK +The +.BR times (2) +function, which explicitly returns (separate) information about the +caller and its children, may be preferable. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.P +In glibc 2.17 and earlier, +.BR clock () +was implemented on top of +.BR times (2). +For improved accuracy, +since glibc 2.18, it is implemented on top of +.BR clock_gettime (2) +(using the +.B CLOCK_PROCESS_CPUTIME_ID +clock). +.SH NOTES +The C standard allows for arbitrary values at the start of the program; +subtract the value returned from a call to +.BR clock () +at the start of the program to get maximum portability. +.P +Note that the time can wrap around. +On a 32-bit system where +.B CLOCKS_PER_SEC +equals 1000000 this function will return the same +value approximately every 72 minutes. +.SH SEE ALSO +.BR clock_gettime (2), +.BR getrusage (2), +.BR times (2) diff --git a/man/man3/clock_getcpuclockid.3 b/man/man3/clock_getcpuclockid.3 new file mode 100644 index 0000000..24884d0 --- /dev/null +++ b/man/man3/clock_getcpuclockid.3 @@ -0,0 +1,155 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH clock_getcpuclockid 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clock_getcpuclockid \- obtain ID of a process CPU-time clock +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ), +since glibc 2.17 +.P +Before glibc 2.17, +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.B #include +.nf +.P +.BI "int clock_getcpuclockid(pid_t " pid ", clockid_t *" clockid ); +.fi +.P +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR clock_getcpuclockid (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR clock_getcpuclockid () +function obtains the ID of the CPU-time clock of the process whose ID is +.IR pid , +and returns it in the location pointed to by +.IR clockid . +If +.I pid +is zero, then the clock ID of the CPU-time clock +of the calling process is returned. +.SH RETURN VALUE +On success, +.BR clock_getcpuclockid () +returns 0; +on error, it returns one of the positive error numbers listed in ERRORS. +.SH ERRORS +.TP +.B ENOSYS +The kernel does not support obtaining the per-process +CPU-time clock of another process, and +.I pid +does not specify the calling process. +.TP +.B EPERM +The caller does not have permission to access +the CPU-time clock of the process specified by +.IR pid . +(Specified in POSIX.1-2001; +does not occur on Linux unless the kernel does not support +obtaining the per-process CPU-time clock of another process.) +.TP +.B ESRCH +There is no process with the ID +.IR pid . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clock_getcpuclockid () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.SH NOTES +Calling +.BR clock_gettime (2) +with the clock ID obtained by a call to +.BR clock_getcpuclockid () +with a +.I pid +of 0, +is the same as using the clock ID +.BR CLOCK_PROCESS_CPUTIME_ID . +.SH EXAMPLES +The example program below obtains the +CPU-time clock ID of the process whose ID is given on the command line, +and then uses +.BR clock_gettime (2) +to obtain the time on that clock. +An example run is the following: +.P +.in +4n +.EX +.RB "$" " ./a.out 1" " # Show CPU clock of init process" +CPU\-time clock for PID 1 is 2.213466748 seconds +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (clock_getcpuclockid.c) +.EX +#define _XOPEN_SOURCE 600 +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + clockid_t clockid; + struct timespec ts; +\& + if (argc != 2) { + fprintf(stderr, "%s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (clock_getcpuclockid(atoi(argv[1]), &clockid) != 0) { + perror("clock_getcpuclockid"); + exit(EXIT_FAILURE); + } +\& + if (clock_gettime(clockid, &ts) == \-1) { + perror("clock_gettime"); + exit(EXIT_FAILURE); + } +\& + printf("CPU\-time clock for PID %s is %jd.%09ld seconds\en", + argv[1], (intmax_t) ts.tv_sec, ts.tv_nsec); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clock_getres (2), +.BR timer_create (2), +.BR pthread_getcpuclockid (3), +.BR time (7) diff --git a/man/man3/clog.3 b/man/man3/clog.3 new file mode 100644 index 0000000..6f363dc --- /dev/null +++ b/man/man3/clog.3 @@ -0,0 +1,71 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH clog 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clog, clogf, clogl \- natural logarithm of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex clog(double complex " z ); +.BI "float complex clogf(float complex " z ); +.BI "long double complex clogl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex natural logarithm of +.IR z , +with a branch cut along the negative real axis. +.P +The logarithm +.BR clog () +is the inverse function of the exponential +.BR cexp (3). +Thus, if \fIy\ =\ clog(z)\fP, then \fIz\ =\ cexp(y)\fP. +The imaginary part of +.I y +is chosen in the interval [\-pi,pi]. +.P +One has: +.P +.in +4n +.EX +clog(z) = log(cabs(z)) + I * carg(z) +.EE +.in +.P +Note that +.I z +close to zero will cause an overflow. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clog (), +.BR clogf (), +.BR clogl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog10 (3), +.BR clog2 (3), +.BR complex (7) diff --git a/man/man3/clog10.3 b/man/man3/clog10.3 new file mode 100644 index 0000000..0ad3cdc --- /dev/null +++ b/man/man3/clog10.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH clog10 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clog10, clog10f, clog10l \- base-10 logarithm of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "double complex clog10(double complex " z ); +.BI "float complex clog10f(float complex " z ); +.BI "long double complex clog10l(long double complex " z ); +.fi +.SH DESCRIPTION +The call +.I clog10(z) +is equivalent to: +.P +.in +4n +.EX +clog(z)/log(10) +.EE +.in +.P +or equally: +.P +.in +4n +.EX +log10(cabs(c)) + I * carg(c) / log(10) +.EE +.in +.P +The other functions perform the same task for +.I float +and +.IR "long double" . +.P +Note that +.I z +close to zero will cause an overflow. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clog10 (), +.BR clog10f (), +.BR clog10l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.P +The identifiers are reserved for future use in C99 and C11. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog (3), +.BR clog2 (3), +.BR complex (7) diff --git a/man/man3/clog10f.3 b/man/man3/clog10f.3 new file mode 100644 index 0000000..5840d54 --- /dev/null +++ b/man/man3/clog10f.3 @@ -0,0 +1 @@ +.so man3/clog10.3 diff --git a/man/man3/clog10l.3 b/man/man3/clog10l.3 new file mode 100644 index 0000000..5840d54 --- /dev/null +++ b/man/man3/clog10l.3 @@ -0,0 +1 @@ +.so man3/clog10.3 diff --git a/man/man3/clog2.3 b/man/man3/clog2.3 new file mode 100644 index 0000000..155f8b4 --- /dev/null +++ b/man/man3/clog2.3 @@ -0,0 +1,45 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH clog2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clog2, clog2f, clog2l \- base-2 logarithm of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex clog2(double complex " z ); +.BI "float complex clog2f(float complex " z ); +.BI "long double complex clog2l(long double complex " z ); +.fi +.SH DESCRIPTION +The call +.I clog2(z) +is equivalent to +.IR clog(z)/log(2) . +.P +The other functions perform the same task for +.I float +and +.IR "long double" . +.P +Note that +.I z +close to zero will cause an overflow. +.SH STANDARDS +None. +.SH HISTORY +These function names are reserved for future use in C99. +.P +Not yet in glibc, as at glibc 2.19. +.\" But reserved in NAMESPACE. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR clog (3), +.BR clog10 (3), +.BR complex (7) diff --git a/man/man3/clog2f.3 b/man/man3/clog2f.3 new file mode 100644 index 0000000..23d6834 --- /dev/null +++ b/man/man3/clog2f.3 @@ -0,0 +1 @@ +.so man3/clog2.3 diff --git a/man/man3/clog2l.3 b/man/man3/clog2l.3 new file mode 100644 index 0000000..23d6834 --- /dev/null +++ b/man/man3/clog2l.3 @@ -0,0 +1 @@ +.so man3/clog2.3 diff --git a/man/man3/clogf.3 b/man/man3/clogf.3 new file mode 100644 index 0000000..3cd9533 --- /dev/null +++ b/man/man3/clogf.3 @@ -0,0 +1 @@ +.so man3/clog.3 diff --git a/man/man3/clogl.3 b/man/man3/clogl.3 new file mode 100644 index 0000000..3cd9533 --- /dev/null +++ b/man/man3/clogl.3 @@ -0,0 +1 @@ +.so man3/clog.3 diff --git a/man/man3/closedir.3 b/man/man3/closedir.3 new file mode 100644 index 0000000..f2142d9 --- /dev/null +++ b/man/man3/closedir.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:25:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.TH closedir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +closedir \- close a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int closedir(DIR *" dirp ); +.fi +.SH DESCRIPTION +The +.BR closedir () +function closes the directory stream associated with +.IR dirp . +A successful call to +.BR closedir () +also closes the underlying file descriptor associated with +.IR dirp . +The directory stream descriptor +.I dirp +is not available +after this call. +.SH RETURN VALUE +The +.BR closedir () +function returns 0 on success. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor +.IR dirp . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR closedir () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR close (2), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man/man3/closelog.3 b/man/man3/closelog.3 new file mode 100644 index 0000000..ec352b2 --- /dev/null +++ b/man/man3/closelog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man/man3/cmsg.3 b/man/man3/cmsg.3 new file mode 100644 index 0000000..6a4eee4 --- /dev/null +++ b/man/man3/cmsg.3 @@ -0,0 +1,261 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $ +.TH CMSG 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh ); +.BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh , +.BR " struct cmsghdr *" cmsg ); +.BI "size_t CMSG_ALIGN(size_t " length ); +.BI "size_t CMSG_SPACE(size_t " length ); +.BI "size_t CMSG_LEN(size_t " length ); +.BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg ); +.fi +.SH DESCRIPTION +These macros are used to create and access control messages (also called +ancillary data) that are not a part of the socket payload. +This control information may +include the interface the packet was received on, various rarely used header +fields, an extended error description, a set of file descriptors, or UNIX +credentials. +For instance, control messages can be used to send +additional header fields such as IP options. +Ancillary data is sent by calling +.BR sendmsg (2) +and received by calling +.BR recvmsg (2). +See their manual pages for more information. +.P +Ancillary data is a sequence of +.I cmsghdr +structures with appended data. +See the specific protocol man pages for the available control message types. +The maximum ancillary buffer size allowed per socket can be set using +.IR /proc/sys/net/core/optmem_max ; +see +.BR socket (7). +.P +The +.I cmsghdr +structure is defined as follows: +.P +.in +4n +.EX +struct cmsghdr { + size_t cmsg_len; /* Data byte count, including header + (type is socklen_t in POSIX) */ + int cmsg_level; /* Originating protocol */ + int cmsg_type; /* Protocol\-specific type */ +/* followed by + unsigned char cmsg_data[]; */ +}; +.EE +.in +.P +The sequence of +.I cmsghdr +structures should never be accessed directly. +Instead, use only the following macros: +.TP +.BR CMSG_FIRSTHDR () +returns a pointer to the first +.I cmsghdr +in the ancillary +data buffer associated with the passed +.IR msghdr . +It returns NULL if there isn't enough space for a +.I cmsghdr +in the buffer. +.TP +.BR CMSG_NXTHDR () +returns the next valid +.I cmsghdr +after the passed +.IR cmsghdr . +It returns NULL when there isn't enough space left in the buffer. +.IP +When initializing a buffer that will contain a series of +.I cmsghdr +structures (e.g., to be sent with +.BR sendmsg (2)), +that buffer should first be zero-initialized +to ensure the correct operation of +.BR CMSG_NXTHDR (). +.TP +.BR CMSG_ALIGN (), +given a length, returns it including the required alignment. +This is a +constant expression. +.TP +.BR CMSG_SPACE () +returns the number of bytes an ancillary element with payload of the +passed data length occupies. +This is a constant expression. +.TP +.BR CMSG_DATA () +returns a pointer to the data portion of a +.IR cmsghdr . +The pointer returned cannot be assumed to be suitably aligned for +accessing arbitrary payload data types. +Applications should not cast it to a pointer type matching the payload, +but should instead use +.BR memcpy (3) +to copy data to or from a suitably declared object. +.TP +.BR CMSG_LEN () +returns the value to store in the +.I cmsg_len +member of the +.I cmsghdr +structure, taking into account any necessary +alignment. +It takes the data length as an argument. +This is a constant +expression. +.P +To create ancillary data, first initialize the +.I msg_controllen +member of the +.I msghdr +with the length of the control message buffer. +Use +.BR CMSG_FIRSTHDR () +on the +.I msghdr +to get the first control message and +.BR CMSG_NXTHDR () +to get all subsequent ones. +In each control message, initialize +.I cmsg_len +(with +.BR CMSG_LEN ()), +the other +.I cmsghdr +header fields, and the data portion using +.BR CMSG_DATA (). +Finally, the +.I msg_controllen +field of the +.I msghdr +should be set to the sum of the +.BR CMSG_SPACE () +of the length of +all control messages in the buffer. +For more information on the +.IR msghdr , +see +.BR recvmsg (2). +.SH VERSIONS +For portability, ancillary data should be accessed using only the macros +described here. +.P +In Linux, +.BR CMSG_LEN (), +.BR CMSG_DATA (), +and +.BR CMSG_ALIGN () +are constant expressions (assuming their argument is constant), +meaning that these values can be used to declare the size of global variables. +This may not be portable, however. +.SH STANDARDS +.TP +.BR CMSG_FIRSTHDR () +.TQ +.BR CMSG_NXTHDR () +.TQ +.BR CMSG_DATA () +POSIX.1-2008. +.TP +.BR CMSG_SPACE () +.TQ +.BR CMSG_LEN () +.TQ +.BR CMSG_ALIGN () +Linux. +.SH HISTORY +This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite, +the IPv6 advanced API described in RFC\ 2292 and SUSv2. +.P +.BR CMSG_SPACE () +and +.BR CMSG_LEN () +.\" https://www.austingroupbugs.net/view.php?id=978#c3242 +will be included in the next POSIX release (Issue 8). +.SH EXAMPLES +This code looks for the +.B IP_TTL +option in a received ancillary buffer: +.P +.in +4n +.EX +struct msghdr msgh; +struct cmsghdr *cmsg; +int received_ttl; +\& +/* Receive auxiliary data in msgh */ +\& +for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL; + cmsg = CMSG_NXTHDR(&msgh, cmsg)) { + if (cmsg\->cmsg_level == IPPROTO_IP + && cmsg\->cmsg_type == IP_TTL) { + memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl)); + break; + } +} +\& +if (cmsg == NULL) { + /* Error: IP_TTL not enabled or small buffer or I/O error */ +} +.EE +.in +.P +The code below passes an array of file descriptors over a +UNIX domain socket using +.BR SCM_RIGHTS : +.P +.in +4n +.EX +struct msghdr msg = { 0 }; +struct cmsghdr *cmsg; +int myfds[NUM_FD]; /* Contains the file descriptors to pass */ +char iobuf[1]; +struct iovec io = { + .iov_base = iobuf, + .iov_len = sizeof(iobuf) +}; +union { /* Ancillary data buffer, wrapped in a union + in order to ensure it is suitably aligned */ + char buf[CMSG_SPACE(sizeof(myfds))]; + struct cmsghdr align; +} u; +\& +msg.msg_iov = &io; +msg.msg_iovlen = 1; +msg.msg_control = u.buf; +msg.msg_controllen = sizeof(u.buf); +cmsg = CMSG_FIRSTHDR(&msg); +cmsg\->cmsg_level = SOL_SOCKET; +cmsg\->cmsg_type = SCM_RIGHTS; +cmsg\->cmsg_len = CMSG_LEN(sizeof(myfds)); +memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds)); +.EE +.in +.P +For a complete code example that shows passing of file descriptors +over a UNIX domain socket, see +.BR seccomp_unotify (2). +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2) +.P +RFC\ 2292 diff --git a/man/man3/confstr.3 b/man/man3/confstr.3 new file mode 100644 index 0000000..bdc0c1a --- /dev/null +++ b/man/man3/confstr.3 @@ -0,0 +1,156 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:53:02 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.\" FIXME Many more values for 'name' are supported, some of which +.\" are documented under 'info libc confstr'. +.\" See for the rest. +.\" These should all be added to this page. +.\" See also the POSIX.1-2001 specification of confstr() +.\" +.TH confstr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +confstr \- get configuration dependent string variables +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t confstr(int " "name" ", char " buf [. size "], size_t " size ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR confstr (): +.nf + _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE +.fi +.SH DESCRIPTION +.BR confstr () +gets the value of configuration-dependent string variables. +.P +The +.I name +argument is the system variable to be queried. +The following variables are supported: +.TP +.BR _CS_GNU_LIBC_VERSION " (GNU C library only; since glibc 2.3.2)" +A string which identifies the GNU C library version on this system +(e.g., "glibc 2.3.4"). +.TP +.BR _CS_GNU_LIBPTHREAD_VERSION " (GNU C library only; since glibc 2.3.2)" +A string which identifies the POSIX implementation supplied by this +C library (e.g., "NPTL 2.3.4" or "linuxthreads\-0.10"). +.TP +.B _CS_PATH +A value for the +.B PATH +variable which indicates where all the POSIX.2 standard utilities can +be found. +.P +If +.I buf +is not NULL and +.I size +is not zero, +.BR confstr () +copies the value of the string to +.I buf +truncated to +.I size \- 1 +bytes if necessary, with a null byte (\[aq]\e0\[aq]) as terminator. +This can be detected by comparing the return value of +.BR confstr () +against +.IR size . +.P +If +.I size +is zero and +.I buf +is NULL, +.BR confstr () +just returns the value as defined below. +.SH RETURN VALUE +If +.I name +is a valid configuration variable, +.BR confstr () +returns the number of bytes (including the terminating null byte) +that would be required to hold the entire value of that variable. +This value may be greater than +.IR size , +which means that the value in +.I buf +is truncated. +.P +If +.I name +is a valid configuration variable, +but that variable does not have a value, then +.BR confstr () +returns 0. +If +.I name +does not correspond to a valid configuration variable, +.BR confstr () +returns 0, and +.I errno +is set to +.BR EINVAL . +.SH ERRORS +.TP +.B EINVAL +The value of +.I name +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR confstr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The following code fragment determines the path where to find +the POSIX.2 system utilities: +.P +.in +4n +.EX +char *pathbuf; +size_t n; +\& +n = confstr(_CS_PATH, NULL, (size_t) 0); +pathbuf = malloc(n); +if (pathbuf == NULL) + abort(); +confstr(_CS_PATH, pathbuf, n); +.EE +.in +.SH SEE ALSO +.BR getconf (1), +.BR sh (1), +.BR exec (3), +.BR fpathconf (3), +.BR pathconf (3), +.BR sysconf (3), +.BR system (3) diff --git a/man/man3/conj.3 b/man/man3/conj.3 new file mode 100644 index 0000000..0924417 --- /dev/null +++ b/man/man3/conj.3 @@ -0,0 +1,56 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH conj 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +conj, conjf, conjl \- calculate the complex conjugate +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex conj(double complex " z ); +.BI "float complex conjf(float complex " z ); +.BI "long double complex conjl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions return the complex conjugate value of +.IR z . +That is the value obtained by changing the sign of the imaginary part. +.P +One has: +.P +.in +4n +.EX +cabs(z) = csqrt(z * conj(z)) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR conj (), +.BR conjf (), +.BR conjl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR csqrt (3), +.BR complex (7) diff --git a/man/man3/conjf.3 b/man/man3/conjf.3 new file mode 100644 index 0000000..ef6093f --- /dev/null +++ b/man/man3/conjf.3 @@ -0,0 +1 @@ +.so man3/conj.3 diff --git a/man/man3/conjl.3 b/man/man3/conjl.3 new file mode 100644 index 0000000..ef6093f --- /dev/null +++ b/man/man3/conjl.3 @@ -0,0 +1 @@ +.so man3/conj.3 diff --git a/man/man3/copysign.3 b/man/man3/copysign.3 new file mode 100644 index 0000000..2a99367 --- /dev/null +++ b/man/man3/copysign.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10 by Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.TH copysign 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +copysign, copysignf, copysignl \- copy sign of a number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double copysign(double " x ", double " y ); +.BI "float copysignf(float " x ", float " y ); +.BI "long double copysignl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR copysign (), +.BR copysignf (), +.BR copysignl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return a value whose absolute value matches that of +.IR x , +but whose sign bit matches that of +.IR y . +.P +For example, +.I "copysign(42.0,\ \-1.0)" +and +.I "copysign(\-42.0, \-1.0)" +both return \-42.0. +.SH RETURN VALUE +On success, these functions return a value whose magnitude is taken from +.I x +and whose sign is taken from +.IR y . +.P +If +.I x +is a NaN, +a NaN with the sign bit of +.I y +is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR copysign (), +.BR copysignf (), +.BR copysignl () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On architectures where the floating-point formats are not IEEE 754 compliant, +these functions may treat a negative zero as positive. +.SH STANDARDS +C11, POSIX.1-2008. +.P +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH HISTORY +C99, POSIX.1-2001, 4.3BSD. +.SH SEE ALSO +.BR signbit (3) diff --git a/man/man3/copysignf.3 b/man/man3/copysignf.3 new file mode 100644 index 0000000..46ef5e6 --- /dev/null +++ b/man/man3/copysignf.3 @@ -0,0 +1 @@ +.so man3/copysign.3 diff --git a/man/man3/copysignl.3 b/man/man3/copysignl.3 new file mode 100644 index 0000000..46ef5e6 --- /dev/null +++ b/man/man3/copysignl.3 @@ -0,0 +1 @@ +.so man3/copysign.3 diff --git a/man/man3/cos.3 b/man/man3/cos.3 new file mode 100644 index 0000000..65f4454 --- /dev/null +++ b/man/man3/cos.3 @@ -0,0 +1,118 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH cos 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cos, cosf, cosl \- cosine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double cos(double " x ); +.BI "float cosf(float " x ); +.BI "long double cosl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR cosf (), +.BR cosl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the cosine of +.IR x , +where +.I x +is +given in radians. +.SH RETURN VALUE +On success, these functions return the cosine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cos (), +.BR cosf (), +.BR cosl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH BUGS +Before glibc 2.10, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6780 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR ccos (3), +.BR sin (3), +.BR sincos (3), +.BR tan (3) diff --git a/man/man3/cosf.3 b/man/man3/cosf.3 new file mode 100644 index 0000000..9abaea4 --- /dev/null +++ b/man/man3/cosf.3 @@ -0,0 +1 @@ +.so man3/cos.3 diff --git a/man/man3/cosh.3 b/man/man3/cosh.3 new file mode 100644 index 0000000..aea372e --- /dev/null +++ b/man/man3/cosh.3 @@ -0,0 +1,130 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-06-08 by aeb +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH cosh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cosh, coshf, coshl \- hyperbolic cosine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double cosh(double " x ); +.BI "float coshf(float " x ); +.BI "long double coshl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR coshf (), +.BR coshl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the hyperbolic cosine of +.IR x , +which is defined mathematically as: +.P +.in +4n +.EX +cosh(x) = (exp(x) + exp(\-x)) / 2 +.EE +.in +.SH RETURN VALUE +On success, these functions return the hyperbolic cosine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 or \-0, 1 is returned. +.P +If +.I x +is positive infinity or negative infinity, +positive infinity is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cosh (), +.BR coshf (), +.BR coshl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH BUGS +In glibc 2.3.4 and earlier, +an overflow floating-point +.RB ( FE_OVERFLOW ) +exception is not raised when an overflow occurs. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR ccos (3), +.BR sinh (3), +.BR tanh (3) diff --git a/man/man3/coshf.3 b/man/man3/coshf.3 new file mode 100644 index 0000000..e9bab10 --- /dev/null +++ b/man/man3/coshf.3 @@ -0,0 +1 @@ +.so man3/cosh.3 diff --git a/man/man3/coshl.3 b/man/man3/coshl.3 new file mode 100644 index 0000000..e9bab10 --- /dev/null +++ b/man/man3/coshl.3 @@ -0,0 +1 @@ +.so man3/cosh.3 diff --git a/man/man3/cosl.3 b/man/man3/cosl.3 new file mode 100644 index 0000000..9abaea4 --- /dev/null +++ b/man/man3/cosl.3 @@ -0,0 +1 @@ +.so man3/cos.3 diff --git a/man/man3/cpow.3 b/man/man3/cpow.3 new file mode 100644 index 0000000..47666b5 --- /dev/null +++ b/man/man3/cpow.3 @@ -0,0 +1,53 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cpow 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cpow, cpowf, cpowl \- complex power function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex cpow(double complex " x ", double complex " z ); +.BI "float complex cpowf(float complex " x ", float complex " z ); +.BI "long double complex cpowl(long double complex " x , +.BI " long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate +.I x +raised to the power +.I z +(with a branch cut for +.I x +along the negative real axis). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cpow (), +.BR cpowf (), +.BR cpowl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR pow (3), +.BR complex (7) diff --git a/man/man3/cpowf.3 b/man/man3/cpowf.3 new file mode 100644 index 0000000..7577fcd --- /dev/null +++ b/man/man3/cpowf.3 @@ -0,0 +1 @@ +.so man3/cpow.3 diff --git a/man/man3/cpowl.3 b/man/man3/cpowl.3 new file mode 100644 index 0000000..7577fcd --- /dev/null +++ b/man/man3/cpowl.3 @@ -0,0 +1 @@ +.so man3/cpow.3 diff --git a/man/man3/cproj.3 b/man/man3/cproj.3 new file mode 100644 index 0000000..07b1de3 --- /dev/null +++ b/man/man3/cproj.3 @@ -0,0 +1,59 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH cproj 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cproj, cprojf, cprojl \- project into Riemann Sphere +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex cproj(double complex " z ");" +.BI "float complex cprojf(float complex " z ");" +.BI "long double complex cprojl(long double complex " z ");" +.fi +.SH DESCRIPTION +These functions project a point in the plane onto the surface of a +Riemann Sphere, the one-point compactification of the complex plane. +Each finite point +.I z +projects to +.I z +itself. +Every complex infinite value is projected to a single infinite value, +namely to positive infinity on the real axis. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR cproj (), +.BR cprojf (), +.BR cprojl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.P +In glibc 2.11 and earlier, the implementation does something different +(a +.I stereographic +projection onto a Riemann Sphere). +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=10401 +.SH SEE ALSO +.BR cabs (3), +.BR complex (7) diff --git a/man/man3/cprojf.3 b/man/man3/cprojf.3 new file mode 100644 index 0000000..0a3f31c --- /dev/null +++ b/man/man3/cprojf.3 @@ -0,0 +1 @@ +.so man3/cproj.3 diff --git a/man/man3/cprojl.3 b/man/man3/cprojl.3 new file mode 100644 index 0000000..0a3f31c --- /dev/null +++ b/man/man3/cprojl.3 @@ -0,0 +1 @@ +.so man3/cproj.3 diff --git a/man/man3/creal.3 b/man/man3/creal.3 new file mode 100644 index 0000000..c4e5293 --- /dev/null +++ b/man/man3/creal.3 @@ -0,0 +1,56 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH creal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +creal, crealf, creall \- get real part of a complex number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double creal(double complex " z ); +.BI "float crealf(float complex " z ); +.BI "long double creall(long double complex " z ); +.fi +.SH DESCRIPTION +These functions return the real part of the complex number +.IR z . +.P +One has: +.P +.nf + z = creal(z) + I * cimag(z) +.fi +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR creal (), +.BR crealf (), +.BR creall () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +GCC supports also __real__. +That is a GNU extension. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cimag (3), +.BR complex (7) diff --git a/man/man3/crealf.3 b/man/man3/crealf.3 new file mode 100644 index 0000000..4289f71 --- /dev/null +++ b/man/man3/crealf.3 @@ -0,0 +1 @@ +.so man3/creal.3 diff --git a/man/man3/creall.3 b/man/man3/creall.3 new file mode 100644 index 0000000..4289f71 --- /dev/null +++ b/man/man3/creall.3 @@ -0,0 +1 @@ +.so man3/creal.3 diff --git a/man/man3/crypt.3 b/man/man3/crypt.3 new file mode 100644 index 0000000..831a530 --- /dev/null +++ b/man/man3/crypt.3 @@ -0,0 +1,319 @@ +'\" t +.\" Michael Haardt (michael@cantor.informatik.rwth.aachen.de) +.\" Sat Sep 3 22:00:30 MET DST 1994 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Sun Feb 19 21:32:25 1995, faith@cs.unc.edu edited details away +.\" +.\" TO DO: This manual page should go more into detail how DES is perturbed, +.\" which string will be encrypted, and what determines the repetition factor. +.\" Is a simple repetition using ECB used, or something more advanced? I hope +.\" the presented explanations are at least better than nothing, but by no +.\" means enough. +.\" +.\" added _XOPEN_SOURCE, aeb, 970705 +.\" added GNU MD5 stuff, aeb, 011223 +.\" +.TH crypt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +crypt, crypt_r \- password hashing +.SH LIBRARY +Password hashing library +.RI ( libcrypt ", " \-lcrypt ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *crypt(const char *" key ", const char *" salt ); +.P +.B #include +.P +.BI "char *crypt_r(const char *" key ", const char *" salt , +.BI " struct crypt_data *restrict " data ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR crypt (): +.nf + Since glibc 2.28: + _DEFAULT_SOURCE + glibc 2.27 and earlier: + _XOPEN_SOURCE +.fi +.P +.BR crypt_r (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +.BR crypt () +is the password hashing function. +It is based on the Data Encryption +Standard algorithm with variations intended (among other things) to +discourage use of hardware implementations of a key search. +.P +.I key +is a user's typed password. +.P +.I salt +is a two-character string chosen from the set +[\fBa\-zA\-Z0\-9./\fP]. +This string is used to +perturb the algorithm in one of 4096 different ways. +.P +By taking the lowest 7 bits of each of the first eight characters of the +.IR key , +a 56-bit key is obtained. +This 56-bit key is used to encrypt repeatedly a +constant string (usually a string consisting of all zeros). +The returned +value points to the hashed password, a series of 13 printable ASCII +characters (the first two characters represent the salt itself). +The return value points to static data whose content is +overwritten by each call. +.P +Warning: the key space consists of +.if t 2\s-2\u56\s0\d +.if n 2**56 +equal 7.2e16 possible values. +Exhaustive searches of this key space are +possible using massively parallel computers. +Software, such as +.BR crack (1), +is available which will search the portion of this key space that is +generally used by humans for passwords. +Hence, password selection should, +at minimum, avoid common words and names. +The use of a +.BR passwd (1) +program that checks for crackable passwords during the selection process is +recommended. +.P +The DES algorithm itself has a few quirks which make the use of the +.BR crypt () +interface a very poor choice for anything other than password +authentication. +If you are planning on using the +.BR crypt () +interface for a cryptography project, don't do it: get a good book on +encryption and one of the widely available DES libraries. +.P +.BR crypt_r () +is a reentrant version of +.BR crypt (). +The structure pointed to by +.I data +is used to store result data and bookkeeping information. +Other than allocating it, +the only thing that the caller should do with this structure is to set +.I data\->initialized +to zero before the first call to +.BR crypt_r (). +.SH RETURN VALUE +On success, a pointer to the hashed password is returned. +On error, NULL is returned. +.SH ERRORS +.TP +.B EINVAL +.I salt +has the wrong format. +.TP +.B ENOSYS +The +.BR crypt () +function was not implemented, probably because of U.S.A. export restrictions. +.\" This level of detail is not necessary in this man page. . . +.\" .P +.\" When encrypting a plain text P using DES with the key K results in the +.\" encrypted text C, then the complementary plain text P' being encrypted +.\" using the complementary key K' will result in the complementary encrypted +.\" text C'. +.\" .P +.\" Weak keys are keys which stay invariant under the DES key transformation. +.\" The four known weak keys 0101010101010101, fefefefefefefefe, +.\" 1f1f1f1f0e0e0e0e and e0e0e0e0f1f1f1f1 must be avoided. +.\" .P +.\" There are six known half weak key pairs, which keys lead to the same +.\" encrypted data. Keys which are part of such key clusters should be +.\" avoided. +.\" Sorry, I could not find out what they are. +.\"" +.\" .P +.\" Heavily redundant data causes trouble with DES encryption, when used in the +.\" .I codebook +.\" mode that +.\" .BR crypt () +.\" implements. The +.\" .BR crypt () +.\" interface should be used only for its intended purpose of password +.\" verification, and should not be used as part of a data encryption tool. +.\" .P +.\" The first and last three output bits of the fourth S-box can be +.\" represented as function of their input bits. Empiric studies have +.\" shown that S-boxes partially compute the same output for similar input. +.\" It is suspected that this may contain a back door which could allow the +.\" NSA to decrypt DES encrypted data. +.\" .P +.\" Making encrypted data computed using crypt() publicly available has +.\" to be considered insecure for the given reasons. +.TP +.B EPERM +.I /proc/sys/crypto/fips_enabled +has a nonzero value, +and an attempt was made to use a weak hashing type, such as DES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR crypt () +T} Thread safety MT-Unsafe race:crypt +T{ +.na +.nh +.BR crypt_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR crypt () +POSIX.1-2008. +.TP +.BR crypt_r () +GNU. +.SH HISTORY +.TP +.BR crypt () +POSIX.1-2001, SVr4, 4.3BSD. +.SS Availability in glibc +The +.BR crypt (), +.BR encrypt (3), +and +.BR setkey (3) +functions are part of the POSIX.1-2008 XSI Options Group for Encryption +and are optional. +If the interfaces are not available, then the symbolic constant +.B _XOPEN_CRYPT +is either not defined, +or it is defined to \-1 and availability can be checked at run time with +.BR sysconf (3). +This may be the case if the downstream distribution has switched from glibc +crypt to +.IR libxcrypt . +When recompiling applications in such distributions, +the programmer must detect if +.B _XOPEN_CRYPT +is not available and include +.I +for the function prototypes; +otherwise +.I libxcrypt +is an ABI-compatible drop-in replacement. +.SH NOTES +.SS Features in glibc +The glibc version of this function supports additional +hashing algorithms. +.P +If +.I salt +is a character string starting with the characters "$\fIid\fP$" +followed by a string optionally terminated by "$", +then the result has the form: +.RS +.P +$\fIid\fP$\fIsalt\fP$\fIhashed\fP +.RE +.P +.I id +identifies the hashing method used instead of DES and this +then determines how the rest of the password string is interpreted. +The following values of +.I id +are supported: +.RS +.TS +lb lb +l lx. +ID Method +_ +1 MD5 +2a T{ +Blowfish (not in mainline glibc; added in some +Linux distributions) +T} +.\" openSUSE has Blowfish, but AFAICS, this option is not supported +.\" natively by glibc -- mtk, Jul 08 +.\" +.\" md5 | Sun MD5 +.\" glibc doesn't appear to natively support Sun MD5; I don't know +.\" if any distros add the support. +5 SHA-256 (since glibc 2.7) +6 SHA-512 (since glibc 2.7) +.TE +.RE +.P +Thus, $5$\fIsalt\fP$\fIhashed\fP and $6$\fIsalt\fP$\fIhashed\fP +contain the password hashed with, respectively, functions +based on SHA-256 and SHA-512. +.P +"\fIsalt\fP" stands for the up to 16 characters +following "$\fIid\fP$" in the salt. +The "\fIhashed\fP" +part of the password string is the actual computed password. +The size of this string is fixed: +.RS +.TS +lb l. +MD5 22 characters +SHA-256 43 characters +SHA-512 86 characters +.TE +.RE +.P +The characters in "\fIsalt\fP" and "\fIhashed\fP" are drawn from the set +[\fBa\-zA\-Z0\-9./\fP]. +In the MD5 and SHA implementations the entire +.I key +is significant (instead of only the first +8 bytes in DES). +.P +Since glibc 2.7, +.\" glibc commit 9425cb9eea6a62fc21d99aafe8a60f752b934b05 +the SHA-256 and SHA-512 implementations support a user-supplied number of +hashing rounds, defaulting to 5000. +If the "$\fIid\fP$" characters in the salt are +followed by "rounds=\fIxxx\fP$", where \fIxxx\fP is an integer, then the +result has the form +.RS +.P +$\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIhashed\fP +.RE +.P +where \fIyyy\fP is the number of hashing rounds actually used. +The number of rounds actually used is 1000 if +.I xxx +is less than +1000, 999999999 if +.I xxx +is greater than 999999999, and +is equal to +.I xxx +otherwise. +.SH SEE ALSO +.BR login (1), +.BR passwd (1), +.BR encrypt (3), +.BR getpass (3), +.BR passwd (5) diff --git a/man/man3/crypt_r.3 b/man/man3/crypt_r.3 new file mode 100644 index 0000000..3944ebd --- /dev/null +++ b/man/man3/crypt_r.3 @@ -0,0 +1 @@ +.so man3/crypt.3 diff --git a/man/man3/csin.3 b/man/man3/csin.3 new file mode 100644 index 0000000..350205a --- /dev/null +++ b/man/man3/csin.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH csin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +csin, csinf, csinl \- complex sine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex csin(double complex " z ); +.BI "float complex csinf(float complex " z ); +.BI "long double complex csinl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex sine of +.IR z . +.P +The complex sine function is defined as: +.P +.in +4n +.EX +csin(z) = (exp(i * z) \- exp(\-i * z)) / (2 * i) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR csin (), +.BR csinf (), +.BR csinl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR casin (3), +.BR ccos (3), +.BR ctan (3), +.BR complex (7) diff --git a/man/man3/csinf.3 b/man/man3/csinf.3 new file mode 100644 index 0000000..1ed2a3e --- /dev/null +++ b/man/man3/csinf.3 @@ -0,0 +1 @@ +.so man3/csin.3 diff --git a/man/man3/csinh.3 b/man/man3/csinh.3 new file mode 100644 index 0000000..e6e4378 --- /dev/null +++ b/man/man3/csinh.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH csinh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +csinh, csinhf, csinhl \- complex hyperbolic sine +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex csinh(double complex " z ); +.BI "float complex csinhf(float complex " z ); +.BI "long double complex csinhl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex hyperbolic sine of +.IR z . +.P +The complex hyperbolic sine function is defined as: +.P +.in +4n +.EX +csinh(z) = (exp(z)\-exp(\-z))/2 +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR csinh (), +.BR csinhf (), +.BR csinhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR casinh (3), +.BR ccosh (3), +.BR ctanh (3), +.BR complex (7) diff --git a/man/man3/csinhf.3 b/man/man3/csinhf.3 new file mode 100644 index 0000000..9f6d66f --- /dev/null +++ b/man/man3/csinhf.3 @@ -0,0 +1 @@ +.so man3/csinh.3 diff --git a/man/man3/csinhl.3 b/man/man3/csinhl.3 new file mode 100644 index 0000000..9f6d66f --- /dev/null +++ b/man/man3/csinhl.3 @@ -0,0 +1 @@ +.so man3/csinh.3 diff --git a/man/man3/csinl.3 b/man/man3/csinl.3 new file mode 100644 index 0000000..1ed2a3e --- /dev/null +++ b/man/man3/csinl.3 @@ -0,0 +1 @@ +.so man3/csin.3 diff --git a/man/man3/csqrt.3 b/man/man3/csqrt.3 new file mode 100644 index 0000000..b047a6d --- /dev/null +++ b/man/man3/csqrt.3 @@ -0,0 +1,51 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH csqrt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +csqrt, csqrtf, csqrtl \- complex square root +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex csqrt(double complex " z ); +.BI "float complex csqrtf(float complex " z ); +.BI "long double complex csqrtl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex square root of +.IR z , +with a branch cut along the negative real axis. +(That means that \fIcsqrt(\-1+eps*I)\fP will be close to I while +\fIcsqrt(\-1\-eps*I)\fP will be close to \-I, \fIif eps\fP is a small positive +real number.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR csqrt (), +.BR csqrtf (), +.BR csqrtl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR cexp (3), +.BR complex (7) diff --git a/man/man3/csqrtf.3 b/man/man3/csqrtf.3 new file mode 100644 index 0000000..e3cf329 --- /dev/null +++ b/man/man3/csqrtf.3 @@ -0,0 +1 @@ +.so man3/csqrt.3 diff --git a/man/man3/csqrtl.3 b/man/man3/csqrtl.3 new file mode 100644 index 0000000..e3cf329 --- /dev/null +++ b/man/man3/csqrtl.3 @@ -0,0 +1 @@ +.so man3/csqrt.3 diff --git a/man/man3/ctan.3 b/man/man3/ctan.3 new file mode 100644 index 0000000..4bde5fa --- /dev/null +++ b/man/man3/ctan.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ctan 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ctan, ctanf, ctanl \- complex tangent function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex ctan(double complex " z ); +.BI "float complex ctanf(float complex " z ); +.BI "long double complex ctanl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex tangent of +.IR z . +.P +The complex tangent function is defined as: +.P +.in +4n +.EX +ctan(z) = csin(z) / ccos(z) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ctan (), +.BR ctanf (), +.BR ctanl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR catan (3), +.BR ccos (3), +.BR csin (3), +.BR complex (7) diff --git a/man/man3/ctanf.3 b/man/man3/ctanf.3 new file mode 100644 index 0000000..c0f4a66 --- /dev/null +++ b/man/man3/ctanf.3 @@ -0,0 +1 @@ +.so man3/ctan.3 diff --git a/man/man3/ctanh.3 b/man/man3/ctanh.3 new file mode 100644 index 0000000..cd1d161 --- /dev/null +++ b/man/man3/ctanh.3 @@ -0,0 +1,58 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ctanh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ctanh, ctanhf, ctanhl \- complex hyperbolic tangent +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double complex ctanh(double complex " z ); +.BI "float complex ctanhf(float complex " z ); +.BI "long double complex ctanhl(long double complex " z ); +.fi +.SH DESCRIPTION +These functions calculate the complex hyperbolic tangent of +.IR z . +.P +The complex hyperbolic tangent function is defined +mathematically as: +.P +.in +4n +.EX +ctanh(z) = csinh(z) / ccosh(z) +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ctanh (), +.BR ctanhf (), +.BR ctanhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR cabs (3), +.BR catanh (3), +.BR ccosh (3), +.BR csinh (3), +.BR complex (7) diff --git a/man/man3/ctanhf.3 b/man/man3/ctanhf.3 new file mode 100644 index 0000000..49b9217 --- /dev/null +++ b/man/man3/ctanhf.3 @@ -0,0 +1 @@ +.so man3/ctanh.3 diff --git a/man/man3/ctanhl.3 b/man/man3/ctanhl.3 new file mode 100644 index 0000000..49b9217 --- /dev/null +++ b/man/man3/ctanhl.3 @@ -0,0 +1 @@ +.so man3/ctanh.3 diff --git a/man/man3/ctanl.3 b/man/man3/ctanl.3 new file mode 100644 index 0000000..c0f4a66 --- /dev/null +++ b/man/man3/ctanl.3 @@ -0,0 +1 @@ +.so man3/ctan.3 diff --git a/man/man3/ctermid.3 b/man/man3/ctermid.3 new file mode 100644 index 0000000..b3983a2 --- /dev/null +++ b/man/man3/ctermid.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:51:06 1993 by Rik Faith (faith@cs.unc.edu) +.TH ctermid 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ctermid \- get controlling terminal name +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.\" POSIX also requires this function to be declared in , +.\" and glibc does so if suitable feature test macros are defined. +.P +.BI "char *ctermid(char *" "s" ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ctermid (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +.BR ctermid () +returns a string which is the pathname for the current +controlling terminal for this process. +If +.I s +is NULL, +a static buffer is used, otherwise +.I s +points to a buffer used to hold the terminal pathname. +The symbolic constant +.B L_ctermid +is the maximum number of characters in the returned pathname. +.SH RETURN VALUE +The pointer to the pathname. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ctermid () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, Svr4. +.SH BUGS +The returned pathname may not uniquely identify the controlling +terminal; it may, for example, be +.IR /dev/tty . +.P +It is not assured that the program can open the terminal. +.\" in glibc 2.3.x, x >= 4, the glibc headers threw an error +.\" if ctermid() was given an argument; fixed in glibc 2.4. +.SH SEE ALSO +.BR ttyname (3) diff --git a/man/man3/ctime.3 b/man/man3/ctime.3 new file mode 100644 index 0000000..cb33421 --- /dev/null +++ b/man/man3/ctime.3 @@ -0,0 +1,429 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de) +.\" Modified 2001-11-13, aeb +.\" Modified 2001-12-13, joey, aeb +.\" Modified 2004-11-16, mtk +.\" +.TH ctime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, +localtime_r \- transform date and time to broken-down time or ASCII +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *asctime(const struct tm *" tm ); +.BI "char *asctime_r(const struct tm *restrict " tm , +.BI " char " buf "[restrict 26]);" +.P +.BI "char *ctime(const time_t *" timep ); +.BI "char *ctime_r(const time_t *restrict " timep , +.BI " char " buf "[restrict 26]);" +.P +.BI "struct tm *gmtime(const time_t *" timep ); +.BI "struct tm *gmtime_r(const time_t *restrict " timep , +.BI " struct tm *restrict " result ); +.P +.BI "struct tm *localtime(const time_t *" timep ); +.BI "struct tm *localtime_r(const time_t *restrict " timep , +.BI " struct tm *restrict " result ); +.P +.BI "time_t mktime(struct tm *" tm ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR asctime_r (), +.BR ctime_r (), +.BR gmtime_r (), +.BR localtime_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR ctime (), +.BR gmtime (), +and +.BR localtime () +functions all take +an argument of data type \fItime_t\fP, which represents calendar time. +When interpreted as an absolute time value, it represents the number of +seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.P +The +.BR asctime () +and +.BR mktime () +functions both take an argument +representing broken-down time, which is a representation +separated into year, month, day, and so on. +.P +Broken-down time is stored in the structure +.IR tm , +described in +.BR tm (3type). +.P +The call +.BI ctime( t ) +is equivalent to +.BI asctime(localtime( t )) \fR. +It converts the calendar time \fIt\fP into a +null-terminated string of the form +.P +.in +4n +.EX +"Wed Jun 30 21:49:08 1993\en" +.EE +.in +.P +The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed", +"Thu", "Fri", and "Sat". +The abbreviations for the months are "Jan", +"Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and +"Dec". +The return value points to a statically allocated string which +might be overwritten by subsequent calls to any of the date and time +functions. +The function also sets the external +variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP (see +.BR tzset (3)) +with information about the current timezone. +The reentrant version +.BR ctime_r () +does the same, but stores the +string in a user-supplied buffer +which should have room for at least 26 bytes. +It need not +set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. +.P +The +.BR gmtime () +function converts the calendar time \fItimep\fP to +broken-down time representation, expressed in Coordinated Universal Time +(UTC). +It may return NULL when the year does not fit into an integer. +The return value points to a statically allocated struct which might be +overwritten by subsequent calls to any of the date and time functions. +The +.BR gmtime_r () +function does the same, but stores the data in a +user-supplied struct. +.P +The +.BR localtime () +function converts the calendar time \fItimep\fP to +broken-down time representation, +expressed relative to the user's specified timezone. +The function acts as if it called +.BR tzset (3) +and sets the external variables \fItzname\fP with +information about the current timezone, \fItimezone\fP with the difference +between Coordinated Universal Time (UTC) and local standard time in +seconds, and \fIdaylight\fP to a nonzero value if daylight savings +time rules apply during some part of the year. +The return value points to a statically allocated struct which might be +overwritten by subsequent calls to any of the date and time functions. +The +.BR localtime_r () +function does the same, but stores the data in a +user-supplied struct. +It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. +.P +The +.BR asctime () +function converts the broken-down time value +\fItm\fP into a null-terminated string with the same format as +.BR ctime (). +The return value points to a statically allocated string which might be +overwritten by subsequent calls to any of the date and time functions. +The +.BR asctime_r () +function does the same, but stores the string in +a user-supplied buffer which should have room for at least 26 bytes. +.P +The +.BR mktime () +function converts a broken-down time structure, expressed +as local time, to calendar time representation. +The function ignores +the values supplied by the caller in the +.I tm_wday +and +.I tm_yday +fields. +The value specified in the +.I tm_isdst +field informs +.BR mktime () +whether or not daylight saving time (DST) +is in effect for the time supplied in the +.I tm +structure: +a positive value means DST is in effect; +zero means that DST is not in effect; +and a negative value means that +.BR mktime () +should (use timezone information and system databases to) +attempt to determine whether DST is in effect at the specified time. +.P +The +.BR mktime () +function modifies the fields of the +.I tm +structure as follows: +.I tm_wday +and +.I tm_yday +are set to values determined from the contents of the other fields; +if structure members are outside their valid interval, they will be +normalized (so that, for example, 40 October is changed into 9 November); +.I tm_isdst +is set (regardless of its initial value) +to a positive value or to 0, respectively, +to indicate whether DST is or is not in effect at the specified time. +Calling +.BR mktime () +also sets the external variable \fItzname\fP with +information about the current timezone. +.P +If the specified broken-down +time cannot be represented as calendar time (seconds since the Epoch), +.BR mktime () +returns +.I (time_t)\ \-1 +and does not alter the +members of the broken-down time structure. +.SH RETURN VALUE +On success, +.BR gmtime () +and +.BR localtime () +return a pointer to a +.IR "struct\ tm" . +.P +On success, +.BR gmtime_r () +and +.BR localtime_r () +return the address of the structure pointed to by +.IR result . +.P +On success, +.BR asctime () +and +.BR ctime () +return a pointer to a string. +.P +On success, +.BR asctime_r () +and +.BR ctime_r () +return a pointer to the string pointed to by +.IR buf . +.P +On success, +.BR mktime () +returns the calendar time (seconds since the Epoch), +expressed as a value of type +.IR time_t . +.P +On error, +.BR mktime () +returns the value +.IR "(time_t)\ \-1" . +The remaining functions return NULL on error. +On error, +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EOVERFLOW +The result cannot be represented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR asctime () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:asctime locale +T} +T{ +.na +.nh +.BR asctime_r () +T} Thread safety T{ +.na +.nh +MT-Safe locale +T} +T{ +.na +.nh +.BR ctime () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:tmbuf +race:asctime env locale +T} +T{ +.na +.nh +.BR ctime_r (), +.BR gmtime_r (), +.BR localtime_r (), +.BR mktime () +T} Thread safety T{ +.na +.nh +MT-Safe env locale +T} +T{ +.na +.nh +.BR gmtime (), +.BR localtime () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:tmbuf env locale +T} +.TE +.SH VERSIONS +POSIX doesn't specify the parameters of +.BR ctime_r () +to be +.IR restrict ; +that is specific to glibc. +.P +In many implementations, including glibc, a 0 in +.I tm_mday +is interpreted as meaning the last day of the preceding month. +.P +According to POSIX.1-2001, +.BR localtime () +is required to behave as though +.BR tzset (3) +was called, while +.BR localtime_r () +does not have this requirement. +.\" See http://thread.gmane.org/gmane.comp.time.tz/2034/ +For portable code, +.BR tzset (3) +should be called before +.BR localtime_r (). +.SH STANDARDS +.TP +.BR asctime () +.TQ +.BR ctime () +.TQ +.BR gmtime () +.TQ +.BR localtime () +.TQ +.BR mktime () +C11, POSIX.1-2008. +.TP +.BR asctime_r () +.TQ +.BR ctime_r () +.TQ +.BR gmtime_r () +.TQ +.BR localtime_r () +POSIX.1-2008. +.SH HISTORY +.TP +.BR gmtime () +.TQ +.BR localtime () +.TQ +.BR mktime () +C89, POSIX.1-2001. +.TP +.BR asctime () +.TQ +.BR ctime () +C89, POSIX.1-2001. +Marked obsolete in POSIX.1-2008 (recommending +.BR strftime (3)). +.TP +.BR gmtime_r () +.TQ +.BR localtime_r () +POSIX.1-2001. +.TP +.BR asctime_r () +.TQ +.BR ctime_r () +POSIX.1-2001. +Marked obsolete in POSIX.1-2008 (recommending +.BR strftime (3)). +.SH NOTES +The four functions +.BR asctime (), +.BR ctime (), +.BR gmtime (), +and +.BR localtime () +return a pointer to static data and hence are not thread-safe. +The thread-safe versions, +.BR asctime_r (), +.BR ctime_r (), +.BR gmtime_r (), +and +.BR localtime_r (), +are specified by SUSv2. +.P +POSIX.1-2001 says: +"The +.BR asctime (), +.BR ctime (), +.BR gmtime (), +and +.BR localtime () +functions shall return values in one of two static objects: +a broken-down time structure and an array of type +.IR char . +Execution of any of the functions may overwrite the information returned +in either of these objects by any of the other functions." +This can occur in the glibc implementation. +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR utime (2), +.BR clock (3), +.BR difftime (3), +.BR strftime (3), +.BR strptime (3), +.BR timegm (3), +.BR tzset (3), +.BR time (7) diff --git a/man/man3/ctime_r.3 b/man/man3/ctime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/ctime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/cuserid.3 b/man/man3/cuserid.3 new file mode 100644 index 0000000..b6d53bf --- /dev/null +++ b/man/man3/cuserid.3 @@ -0,0 +1 @@ +.so man3/getlogin.3 diff --git a/man/man3/daemon.3 b/man/man3/daemon.3 new file mode 100644 index 0000000..a3d8794 --- /dev/null +++ b/man/man3/daemon.3 @@ -0,0 +1,129 @@ +'\" t +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)daemon.3 8.1 (Berkeley) 6/9/93 +.\" Added mentioning of glibc weirdness wrt unistd.h. 5/11/98, Al Viro +.TH daemon 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +daemon \- run in the background +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int daemon(int " nochdir ", int " noclose ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR daemon (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +The +.BR daemon () +function is for programs wishing to detach themselves from the +controlling terminal and run in the background as system daemons. +.P +If +.I nochdir +is zero, +.BR daemon () +changes the process's current working directory +to the root directory ("/"); +otherwise, the current working directory is left unchanged. +.P +If +.I noclose +is zero, +.BR daemon () +redirects standard input, standard output, and standard error +to +.IR /dev/null ; +otherwise, no changes are made to these file descriptors. +.SH RETURN VALUE +(This function forks, and if the +.BR fork (2) +succeeds, the parent calls +.\" not .IR in order not to underline _ +.BR _exit (2), +so that further errors are seen by the child only.) +On success +.BR daemon () +returns zero. +If an error occurs, +.BR daemon () +returns \-1 and sets +.I errno +to any of the errors specified for the +.BR fork (2) +and +.BR setsid (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR daemon () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +A similar function appears on the BSDs. +.P +The glibc implementation can also return \-1 when +.I /dev/null +exists but is not a character device with the expected +major and minor numbers. +In this case, +.I errno +need not be set. +.SH STANDARDS +None. +.SH HISTORY +4.4BSD. +.SH BUGS +The GNU C library implementation of this function was taken from BSD, +and does not employ the double-fork technique (i.e., +.BR fork (2), +.BR setsid (2), +.BR fork (2)) +that is necessary to ensure that the resulting daemon process is +not a session leader. +Instead, the resulting daemon +.I is +a session leader. +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=19144 +.\" Tested using a program that uses daemon() and then opens an +.\" otherwise unused console device (/dev/ttyN) that does not +.\" have an associated getty process. +On systems that follow System V semantics (e.g., Linux), +this means that if the daemon opens a terminal that is not +already a controlling terminal for another session, +then that terminal will inadvertently become +the controlling terminal for the daemon. +.SH SEE ALSO +.BR fork (2), +.BR setsid (2), +.BR daemon (7), +.BR logrotate (8) diff --git a/man/man3/daylight.3 b/man/man3/daylight.3 new file mode 100644 index 0000000..8090763 --- /dev/null +++ b/man/man3/daylight.3 @@ -0,0 +1 @@ +.so man3/tzset.3 diff --git a/man/man3/db.3 b/man/man3/db.3 new file mode 100644 index 0000000..03ede66 --- /dev/null +++ b/man/man3/db.3 @@ -0,0 +1 @@ +.so man3/dbopen.3 diff --git a/man/man3/dbopen.3 b/man/man3/dbopen.3 new file mode 100644 index 0000000..e18596f --- /dev/null +++ b/man/man3/dbopen.3 @@ -0,0 +1,536 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 +.\" +.TH dbopen 3 2024-05-02 "Linux man-pages (unreleased)" +.UC 7 +.SH NAME +dbopen \- database access methods +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.P +.BI "DB *dbopen(const char *" file ", int " flags ", int " mode \ +", DBTYPE " type , +.BI " const void *" openinfo ); +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided up until glibc 2.1. +Since glibc 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.P +.BR dbopen () +is the library interface to database files. +The supported file formats are btree, hashed, and UNIX file oriented. +The btree format is a representation of a sorted, balanced tree structure. +The hashed format is an extensible, dynamic hashing scheme. +The flat-file format is a byte stream file with fixed or variable length +records. +The formats and file-format-specific information are described in detail +in their respective manual pages +.BR btree (3), +.BR hash (3), +and +.BR recno (3). +.P +.BR dbopen () +opens +.I file +for reading and/or writing. +Files never intended to be preserved on disk may be created by setting +the +.I file +argument to NULL. +.P +The +.I flags +and +.I mode +arguments are as specified to the +.BR open (2) +routine, however, only the +.BR O_CREAT , +.BR O_EXCL , +.BR O_EXLOCK , +.BR O_NONBLOCK , +.BR O_RDONLY , +.BR O_RDWR , +.BR O_SHLOCK , +and +.B O_TRUNC +flags are meaningful. +(Note, opening a database file +.B O_WRONLY +is not possible.) +.\"Three additional options may be specified by ORing +.\"them into the +.\".I flags +.\"argument. +.\".TP +.\"DB_LOCK +.\"Do the necessary locking in the database to support concurrent access. +.\"If concurrent access isn't needed or the database is read-only this +.\"flag should not be set, as it tends to have an associated performance +.\"penalty. +.\".TP +.\"DB_SHMEM +.\"Place the underlying memory pool used by the database in shared +.\"memory. +.\"Necessary for concurrent access. +.\".TP +.\"DB_TXN +.\"Support transactions in the database. +.\"The DB_LOCK and DB_SHMEM flags must be set as well. +.P +The +.I type +argument is of type +.I DBTYPE +(as defined in the +.I +include file) and +may be set to +.BR DB_BTREE , +.BR DB_HASH , +or +.BR DB_RECNO . +.P +The +.I openinfo +argument is a pointer to an access-method-specific structure described +in the access method's manual page. +If +.I openinfo +is NULL, each access method will use defaults appropriate for the system +and the access method. +.P +.BR dbopen () +returns a pointer to a +.I DB +structure on success and NULL on error. +The +.I DB +structure is defined in the +.I +include file, and contains at +least the following fields: +.P +.in +4n +.EX +typedef struct { + DBTYPE type; + int (*close)(const DB *db); + int (*del)(const DB *db, const DBT *key, unsigned int flags); + int (*fd)(const DB *db); + int (*get)(const DB *db, DBT *key, DBT *data, + unsigned int flags); + int (*put)(const DB *db, DBT *key, const DBT *data, + unsigned int flags); + int (*sync)(const DB *db, unsigned int flags); + int (*seq)(const DB *db, DBT *key, DBT *data, + unsigned int flags); +} DB; +.EE +.in +.P +These elements describe a database type and a set of functions performing +various actions. +These functions take a pointer to a structure as returned by +.BR dbopen (), +and sometimes one or more pointers to key/data structures and a flag value. +.TP +.I type +The type of the underlying access method (and file format). +.TP +.I close +A pointer to a routine to flush any cached information to disk, free any +allocated resources, and close the underlying file(s). +Since key/data pairs may be cached in memory, failing to sync the file +with a +.I close +or +.I sync +function may result in inconsistent or lost information. +.I close +routines return \-1 on error (setting +.IR errno ) +and 0 on success. +.TP +.I del +A pointer to a routine to remove key/data pairs from the database. +.IP +The argument +.I flag +may be set to the following value: +.RS +.TP +.B R_CURSOR +Delete the record referenced by the cursor. +The cursor must have previously been initialized. +.RE +.IP +.I delete +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the specified +.I key +was not in the file. +.TP +.I fd +A pointer to a routine which returns a file descriptor representative +of the underlying database. +A file descriptor referencing the same file will be returned to all +processes which call +.BR dbopen () +with the same +.I file +name. +This file descriptor may be safely used as an argument to the +.BR fcntl (2) +and +.BR flock (2) +locking functions. +The file descriptor is not necessarily associated with any of the +underlying files used by the access method. +No file descriptor is available for in memory databases. +.I fd +routines return \-1 on error (setting +.IR errno ), +and the file descriptor on success. +.TP +.I get +A pointer to a routine which is the interface for keyed retrieval from +the database. +The address and length of the data associated with the specified +.I key +are returned in the structure referenced by +.IR data . +.I get +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the +.I key +was not in the file. +.TP +.I put +A pointer to a routine to store key/data pairs in the database. +.IP +The argument +.I flag +may be set to one of the following values: +.RS +.TP +.B R_CURSOR +Replace the key/data pair referenced by the cursor. +The cursor must have previously been initialized. +.TP +.B R_IAFTER +Append the data immediately after the data referenced by +.IR key , +creating a new key/data pair. +The record number of the appended key/data pair is returned in the +.I key +structure. +(Applicable only to the +.B DB_RECNO +access method.) +.TP +.B R_IBEFORE +Insert the data immediately before the data referenced by +.IR key , +creating a new key/data pair. +The record number of the inserted key/data pair is returned in the +.I key +structure. +(Applicable only to the +.B DB_RECNO +access method.) +.TP +.B R_NOOVERWRITE +Enter the new key/data pair only if the key does not previously exist. +.TP +.B R_SETCURSOR +Store the key/data pair, setting or initializing the position of the +cursor to reference it. +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) +.RE +.IP +.B R_SETCURSOR +is available only for the +.B DB_BTREE +and +.B DB_RECNO +access +methods because it implies that the keys have an inherent order +which does not change. +.IP +.B R_IAFTER +and +.B R_IBEFORE +are available only for the +.B DB_RECNO +access method because they each imply that the access method is able to +create new keys. +This is true only if the keys are ordered and independent, record numbers +for example. +.IP +The default behavior of the +.I put +routines is to enter the new key/data pair, replacing any previously +existing key. +.IP +.I put +routines return \-1 on error (setting +.IR errno ), +0 on success, and 1 if the +.B R_NOOVERWRITE +.I flag +was set and the key already exists in the file. +.TP +.I seq +A pointer to a routine which is the interface for sequential +retrieval from the database. +The address and length of the key are returned in the structure +referenced by +.IR key , +and the address and length of the data are returned in the +structure referenced +by +.IR data . +.IP +Sequential key/data pair retrieval may begin at any time, and the +position of the "cursor" is not affected by calls to the +.IR del , +.IR get , +.IR put , +or +.I sync +routines. +Modifications to the database during a sequential scan will be reflected +in the scan, that is, +records inserted behind the cursor will not be returned +while records inserted in front of the cursor will be returned. +.IP +The flag value +.B must +be set to one of the following values: +.RS +.TP +.B R_CURSOR +The data associated with the specified key is returned. +This differs from the +.I get +routines in that it sets or initializes the cursor to the location of +the key as well. +(Note, for the +.B DB_BTREE +access method, the returned key is not necessarily an +exact match for the specified key. +The returned key is the smallest key greater than or equal to the specified +key, permitting partial key matches and range searches.) +.TP +.B R_FIRST +The first key/data pair of the database is returned, and the cursor +is set or initialized to reference it. +.TP +.B R_LAST +The last key/data pair of the database is returned, and the cursor +is set or initialized to reference it. +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) +.TP +.B R_NEXT +Retrieve the key/data pair immediately after the cursor. +If the cursor is not yet set, this is the same as the +.B R_FIRST +flag. +.TP +.B R_PREV +Retrieve the key/data pair immediately before the cursor. +If the cursor is not yet set, this is the same as the +.B R_LAST +flag. +(Applicable only to the +.B DB_BTREE +and +.B DB_RECNO +access methods.) +.RE +.IP +.B R_LAST +and +.B R_PREV +are available only for the +.B DB_BTREE +and +.B DB_RECNO +access methods because they each imply that the keys have an inherent +order which does not change. +.IP +.I seq +routines return \-1 on error (setting +.IR errno ), +0 on success and 1 if there are no key/data pairs less than or greater +than the specified or current key. +If the +.B DB_RECNO +access method is being used, and if the database file +is a character special file and no complete key/data pairs are currently +available, the +.I seq +routines return 2. +.TP +.I sync +A pointer to a routine to flush any cached information to disk. +If the database is in memory only, the +.I sync +routine has no effect and will always succeed. +.IP +The flag value may be set to the following value: +.RS +.TP +.B R_RECNOSYNC +If the +.B DB_RECNO +access method is being used, this flag causes +the sync routine to apply to the btree file which underlies the +recno file, not the recno file itself. +(See the +.I bfname +field of the +.BR recno (3) +manual page for more information.) +.RE +.IP +.I sync +routines return \-1 on error (setting +.IR errno ) +and 0 on success. +.SS Key/data pairs +Access to all file types is based on key/data pairs. +Both keys and data are represented by the following data structure: +.P +.in +4n +.EX +typedef struct { + void *data; + size_t size; +} DBT; +.EE +.in +.P +The elements of the +.I DBT +structure are defined as follows: +.TP +.I data +A pointer to a byte string. +.TP +.I size +The length of the byte string. +.P +Key and data byte strings may reference strings of essentially unlimited +length although any two of them must fit into available memory at the same +time. +It should be noted that the access methods provide no guarantees about +byte string alignment. +.SH ERRORS +The +.BR dbopen () +routine may fail and set +.I errno +for any of the errors specified for the library routines +.BR open (2) +and +.BR malloc (3) +or the following: +.TP +.B EFTYPE +A file is incorrectly formatted. +.TP +.B EINVAL +A parameter has been specified (hash function, pad byte, etc.) that is +incompatible with the current file specification or which is not +meaningful for the function (for example, use of the cursor without +prior initialization) or there is a mismatch between the version +number of file and the software. +.P +The +.I close +routines may fail and set +.I errno +for any of the errors specified for the library routines +.BR close (2), +.BR read (2), +.BR write (2), +.BR free (3), +or +.BR fsync (2). +.P +The +.IR del , +.IR get , +.IR put , +and +.I seq +routines may fail and set +.I errno +for any of the errors specified for the library routines +.BR read (2), +.BR write (2), +.BR free (3), +or +.BR malloc (3). +.P +The +.I fd +routines will fail and set +.I errno +to +.B ENOENT +for in memory databases. +.P +The +.I sync +routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR fsync (2). +.SH BUGS +The typedef +.I DBT +is a mnemonic for "data base thang", and was used +because no one could think of a reasonable name that wasn't already used. +.P +The file descriptor interface is a kludge and will be deleted in a +future version of the interface. +.P +None of the access methods provide any form of concurrent access, +locking, or transactions. +.SH SEE ALSO +.BR btree (3), +.BR hash (3), +.BR mpool (3), +.BR recno (3) +.P +.IR "LIBTP: Portable, Modular Transactions for UNIX" , +Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. diff --git a/man/man3/des_crypt.3 b/man/man3/des_crypt.3 new file mode 100644 index 0000000..a21638a --- /dev/null +++ b/man/man3/des_crypt.3 @@ -0,0 +1,164 @@ +'\" t +.\" @(#)des_crypt.3 2.1 88/08/11 4.0 RPCSRC; from 1.16 88/03/02 SMI; +.\" +.\" Taken from libc4 sources, which say: +.\" Copyright (C) 1993 Eric Young - can be distributed under GPL. +.\" +.\" However, the above header line suggests that this file in fact is +.\" Copyright Sun Microsystems, Inc (and is provided for unrestricted use, +.\" see other Sun RPC sources). +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH des_crypt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast +DES encryption +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.\" Sun version +.\" .B #include +.B #include +.P +.BI "[[deprecated]] int ecb_crypt(char *" key ", char " data [. datalen ], +.BI " unsigned int " datalen ", \ +unsigned int " mode ); +.BI "[[deprecated]] int cbc_crypt(char *" key ", char " data [. datalen ], +.BI " unsigned int " datalen ", \ +unsigned int " mode , +.BI " char *" ivec ); +.P +.BI "[[deprecated]] void des_setparity(char *" key ); +.P +.BI "[[deprecated]] int DES_FAILED(int " status ); +.fi +.SH DESCRIPTION +.BR ecb_crypt () +and +.BR cbc_crypt () +implement the +NBS +DES +(Data Encryption Standard). +These routines are faster and more general purpose than +.BR crypt (3). +They also are able to utilize +DES +hardware if it is available. +.BR ecb_crypt () +encrypts in +ECB +(Electronic Code Book) +mode, which encrypts blocks of data independently. +.BR cbc_crypt () +encrypts in +CBC +(Cipher Block Chaining) +mode, which chains together +successive blocks. +CBC +mode protects against insertions, deletions, and +substitutions of blocks. +Also, regularities in the clear text will +not appear in the cipher text. +.P +Here is how to use these routines. +The first argument, +.IR key , +is the 8-byte encryption key with parity. +To set the key's parity, which for +DES +is in the low bit of each byte, use +.BR des_setparity (). +The second argument, +.IR data , +contains the data to be encrypted or decrypted. +The +third argument, +.IR datalen , +is the length in bytes of +.IR data , +which must be a multiple of 8. +The fourth argument, +.IR mode , +is formed by ORing together some things. +For the encryption direction OR in either +.B DES_ENCRYPT +or +.BR DES_DECRYPT . +For software versus hardware +encryption, OR in either +.B DES_HW +or +.BR DES_SW . +If +.B DES_HW +is specified, and there is no hardware, then the encryption is performed +in software and the routine returns +.BR DESERR_NOHWDEVICE . +For +.BR cbc_crypt (), +the argument +.I ivec +is the 8-byte initialization +vector for the chaining. +It is updated to the next initialization +vector upon return. +.SH RETURN VALUE +.TP +.B DESERR_NONE +No error. +.TP +.B DESERR_NOHWDEVICE +Encryption succeeded, but done in software instead of the requested hardware. +.TP +.B DESERR_HWERROR +An error occurred in the hardware or driver. +.TP +.B DESERR_BADPARAM +Bad argument to routine. +.P +Given a result status +.IR stat , +the macro +.\" .BR DES_FAILED\c +.\" .BR ( stat ) +.BI DES_FAILED( stat ) +is false only for the first two statuses. +.\" So far the Sun page +.\" Some additions - aeb +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ecb_crypt (), +.BR cbc_crypt (), +.BR des_setparity () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +glibc 2.1. +Removed in glibc 2.28. +.P +Because they employ the DES block cipher, +which is no longer considered secure, +these functions were removed. +Applications should switch to a modern cryptography library, such as +.BR libgcrypt . +.SH SEE ALSO +.BR des (1), +.BR crypt (3), +.BR xcrypt (3) diff --git a/man/man3/des_setparity.3 b/man/man3/des_setparity.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man/man3/des_setparity.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man/man3/difftime.3 b/man/man3/difftime.3 new file mode 100644 index 0000000..aa6b248 --- /dev/null +++ b/man/man3/difftime.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:48:17 1993 by Rik Faith (faith@cs.unc.edu) +.TH difftime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +difftime \- calculate time difference +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double difftime(time_t " time1 ", time_t " time0 ); +.fi +.SH DESCRIPTION +The +.BR difftime () +function returns the number of seconds elapsed +between time \fItime1\fP and time \fItime0\fP, represented as a +.IR double . +Each time is a count of seconds. +.P +.I difftime(b,\~a) +acts like +.I (b\-a) +except that the result does not overflow and is rounded to +.IR double . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR difftime () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR ctime (3), +.BR gmtime (3), +.BR localtime (3) diff --git a/man/man3/dirfd.3 b/man/man3/dirfd.3 new file mode 100644 index 0000000..8fab3c0 --- /dev/null +++ b/man/man3/dirfd.3 @@ -0,0 +1,93 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH dirfd 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dirfd \- get directory stream file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int dirfd(DIR *" dirp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR dirfd (): +.nf + /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The function +.BR dirfd () +returns the file descriptor associated with the directory stream +.IR dirp . +.P +This file descriptor is the one used internally by the directory stream. +As a result, it is useful only for functions which do not depend on +or alter the file position, such as +.BR fstat (2) +and +.BR fchdir (2). +It will be automatically closed when +.BR closedir (3) +is called. +.SH RETURN VALUE +On success, +.BR dirfd () +returns a file descriptor (a nonnegative integer). +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +POSIX.1-2008 specifies two errors, +neither of which is returned by the current +.\" glibc 2.8 +implementation. +.TP +.B EINVAL +.I dirp +does not refer to a valid directory stream. +.TP +.B ENOTSUP +The implementation does not support the association of a file +descriptor with a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dirfd () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +4.3BSD-Reno (not in 4.2BSD). +.\" It is present in libc5 (since 5.1.2) and in glibc 2. +.SH SEE ALSO +.BR open (2), +.BR openat (2), +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man/man3/dirname.3 b/man/man3/dirname.3 new file mode 100644 index 0000000..9099c1a --- /dev/null +++ b/man/man3/dirname.3 @@ -0,0 +1 @@ +.so man3/basename.3 diff --git a/man/man3/div.3 b/man/man3/div.3 new file mode 100644 index 0000000..36e8a6e --- /dev/null +++ b/man/man3/div.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10, 2003-11-01 Walter Harms, aeb +.\" +.TH div 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +div, ldiv, lldiv, imaxdiv \- compute quotient and remainder of +an integer division +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "div_t div(int " numerator ", int " denominator ); +.BI "ldiv_t ldiv(long " numerator ", long " denominator ); +.BI "lldiv_t lldiv(long long " numerator ", long long " denominator ); +.P +.B #include +.P +.BI "imaxdiv_t imaxdiv(intmax_t " numerator ", intmax_t " denominator ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR lldiv (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR div () +function computes the value +\fInumerator\fP/\fIdenominator\fP and +returns the quotient and remainder in a structure +named \fIdiv_t\fP that contains +two integer members (in unspecified order) named \fIquot\fP and \fIrem\fP. +The quotient is rounded toward zero. +The result satisfies \fIquot\fP*\fIdenominator\fP+\fIrem\fP = \fInumerator\fP. +.P +The +.BR ldiv (), +.BR lldiv (), +and +.BR imaxdiv () +functions do the same, +dividing numbers of the indicated type and +returning the result in a structure +of the indicated name, in all cases with fields \fIquot\fP and \fIrem\fP +of the same type as the function arguments. +.SH RETURN VALUE +The \fIdiv_t\fP (etc.) structure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR div (), +.BR ldiv (), +.BR lldiv (), +.BR imaxdiv () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, C99, SVr4, 4.3BSD. +.P +.BR lldiv () +and +.BR imaxdiv () +were added in C99. +.SH EXAMPLES +After +.P +.in +4n +.EX +div_t q = div(\-5, 3); +.EE +.in +.P +the values \fIq.quot\fP and \fIq.rem\fP are \-1 and \-2, respectively. +.SH SEE ALSO +.BR abs (3), +.BR remainder (3) diff --git a/man/man3/dl_iterate_phdr.3 b/man/man3/dl_iterate_phdr.3 new file mode 100644 index 0000000..a533155 --- /dev/null +++ b/man/man3/dl_iterate_phdr.3 @@ -0,0 +1,345 @@ +'\" t +.\" Copyright (c) 2003, 2017 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH dl_iterate_phdr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dl_iterate_phdr \- walk through list of shared objects +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.B int dl_iterate_phdr( +.BI " int (*" callback ")(struct dl_phdr_info *" info , +.BI " size_t " size ", void *" data ), +.BI " void *" data ); +.fi +.SH DESCRIPTION +The +.BR dl_iterate_phdr () +function allows an application to inquire at run time to find +out which shared objects it has loaded, +and the order in which they were loaded. +.P +The +.BR dl_iterate_phdr () +function walks through the list of an +application's shared objects and calls the function +.I callback +once for each object, +until either all shared objects have been processed or +.I callback +returns a nonzero value. +.P +Each call to +.I callback +receives three arguments: +.IR info , +which is a pointer to a structure containing information +about the shared object; +.IR size , +which is the size of the structure pointed to by +.IR info ; +and +.IR data , +which is a copy of whatever value was passed by the calling +program as the second argument (also named +.IR data ) +in the call to +.BR dl_iterate_phdr (). +.P +The +.I info +argument is a structure of the following type: +.P +.in +4n +.EX +struct dl_phdr_info { + ElfW(Addr) dlpi_addr; /* Base address of object */ + const char *dlpi_name; /* (Null\-terminated) name of + object */ + const ElfW(Phdr) *dlpi_phdr; /* Pointer to array of + ELF program headers + for this object */ + ElfW(Half) dlpi_phnum; /* # of items in \fIdlpi_phdr\fP */ +\& + /* The following fields were added in glibc 2.4, after the first + version of this structure was available. Check the \fIsize\fP + argument passed to the dl_iterate_phdr callback to determine + whether or not each later member is available. */ +\& + unsigned long long dlpi_adds; + /* Incremented when a new object may + have been added */ + unsigned long long dlpi_subs; + /* Incremented when an object may + have been removed */ + size_t dlpi_tls_modid; + /* If there is a PT_TLS segment, its module + ID as used in TLS relocations, else zero */ + void *dlpi_tls_data; + /* The address of the calling thread\[aq]s instance + of this module\[aq]s PT_TLS segment, if it has + one and it has been allocated in the calling + thread, otherwise a null pointer */ +}; +.EE +.in +.P +(The +.IR ElfW () +macro definition turns its argument into the name of an ELF data +type suitable for the hardware architecture. +For example, on a 32-bit platform, +.I ElfW(Addr) +yields the data type name +.IR Elf32_Addr . +Further information on these types can be found in the +.IR " and " +header files.) +.P +The +.I dlpi_addr +field indicates the base address of the shared object +(i.e., the difference between the virtual memory address of +the shared object and the offset of that object in the file +from which it was loaded). +The +.I dlpi_name +field is a null-terminated string giving the pathname +from which the shared object was loaded. +.P +To understand the meaning of the +.I dlpi_phdr +and +.I dlpi_phnum +fields, we need to be aware that an ELF shared object consists +of a number of segments, each of which has a corresponding +program header describing the segment. +The +.I dlpi_phdr +field is a pointer to an array of the program headers for this +shared object. +The +.I dlpi_phnum +field indicates the size of this array. +.P +These program headers are structures of the following form: +.P +.in +4n +.EX +typedef struct { + Elf32_Word p_type; /* Segment type */ + Elf32_Off p_offset; /* Segment file offset */ + Elf32_Addr p_vaddr; /* Segment virtual address */ + Elf32_Addr p_paddr; /* Segment physical address */ + Elf32_Word p_filesz; /* Segment size in file */ + Elf32_Word p_memsz; /* Segment size in memory */ + Elf32_Word p_flags; /* Segment flags */ + Elf32_Word p_align; /* Segment alignment */ +} Elf32_Phdr; +.EE +.in +.P +Note that we can calculate the location of a particular program header, +.IR x , +in virtual memory using the formula: +.P +.in +4n +.EX +addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr; +.EE +.in +.P +Possible values for +.I p_type +include the following (see +.I +for further details): +.P +.in +4n +.EX +#define PT_LOAD 1 /* Loadable program segment */ +#define PT_DYNAMIC 2 /* Dynamic linking information */ +#define PT_INTERP 3 /* Program interpreter */ +#define PT_NOTE 4 /* Auxiliary information */ +#define PT_SHLIB 5 /* Reserved */ +#define PT_PHDR 6 /* Entry for header table itself */ +#define PT_TLS 7 /* Thread\-local storage segment */ +#define PT_GNU_EH_FRAME 0x6474e550 /* GCC .eh_frame_hdr segment */ +#define PT_GNU_STACK 0x6474e551 /* Indicates stack executability */ +.\" For PT_GNU_STACK, see http://www.airs.com/blog/archives/518 +#define PT_GNU_RELRO 0x6474e552 /* Read\-only after relocation */ +.EE +.in +.SH RETURN VALUE +The +.BR dl_iterate_phdr () +function returns whatever value was returned by the last call to +.IR callback . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dl_iterate_phdr () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Various other systems provide a version of this function, +although details of the returned +.I dl_phdr_info +structure differ. +On the BSDs and Solaris, the structure includes the fields +.IR dlpi_addr , +.IR dlpi_name , +.IR dlpi_phdr , +and +.I dlpi_phnum +in addition to other implementation-specific fields. +.P +Future versions of the C library may add further fields to the +.I dl_phdr_info +structure; in that event, the +.I size +argument provides a mechanism for the callback function to discover +whether it is running on a system with added fields. +.SH STANDARDS +None. +.SH HISTORY +glibc 2.2.4. +.SH NOTES +The first object visited by +.I callback +is the main program. +For the main program, the +.I dlpi_name +field will be an empty string. +.SH EXAMPLES +The following program displays a list of pathnames of the +shared objects it has loaded. +For each shared object, the program lists some information +(virtual address, size, flags, and type) +for each of the objects ELF segments. +.P +The following shell session demonstrates the output +produced by the program on an x86-64 system. +The first shared object for which output is displayed +(where the name is an empty string) +is the main program. +.P +.in +4n +.EX +$ \fB./a.out\fP +Name: "" (9 segments) + 0: [ 0x400040; memsz: 1f8] flags: 0x5; PT_PHDR + 1: [ 0x400238; memsz: 1c] flags: 0x4; PT_INTERP + 2: [ 0x400000; memsz: ac4] flags: 0x5; PT_LOAD + 3: [ 0x600e10; memsz: 240] flags: 0x6; PT_LOAD + 4: [ 0x600e28; memsz: 1d0] flags: 0x6; PT_DYNAMIC + 5: [ 0x400254; memsz: 44] flags: 0x4; PT_NOTE + 6: [ 0x400970; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME + 7: [ (nil); memsz: 0] flags: 0x6; PT_GNU_STACK + 8: [ 0x600e10; memsz: 1f0] flags: 0x4; PT_GNU_RELRO +Name: "linux\-vdso.so.1" (4 segments) + 0: [0x7ffc6edd1000; memsz: e89] flags: 0x5; PT_LOAD + 1: [0x7ffc6edd1360; memsz: 110] flags: 0x4; PT_DYNAMIC + 2: [0x7ffc6edd17b0; memsz: 3c] flags: 0x4; PT_NOTE + 3: [0x7ffc6edd17ec; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME +Name: "/lib64/libc.so.6" (10 segments) + 0: [0x7f55712ce040; memsz: 230] flags: 0x5; PT_PHDR + 1: [0x7f557145b980; memsz: 1c] flags: 0x4; PT_INTERP + 2: [0x7f55712ce000; memsz: 1b6a5c] flags: 0x5; PT_LOAD + 3: [0x7f55716857a0; memsz: 9240] flags: 0x6; PT_LOAD + 4: [0x7f5571688b80; memsz: 1f0] flags: 0x6; PT_DYNAMIC + 5: [0x7f55712ce270; memsz: 44] flags: 0x4; PT_NOTE + 6: [0x7f55716857a0; memsz: 78] flags: 0x4; PT_TLS + 7: [0x7f557145b99c; memsz: 544c] flags: 0x4; PT_GNU_EH_FRAME + 8: [0x7f55712ce000; memsz: 0] flags: 0x6; PT_GNU_STACK + 9: [0x7f55716857a0; memsz: 3860] flags: 0x4; PT_GNU_RELRO +Name: "/lib64/ld\-linux\-x86\-64.so.2" (7 segments) + 0: [0x7f557168f000; memsz: 20828] flags: 0x5; PT_LOAD + 1: [0x7f55718afba0; memsz: 15a8] flags: 0x6; PT_LOAD + 2: [0x7f55718afe10; memsz: 190] flags: 0x6; PT_DYNAMIC + 3: [0x7f557168f1c8; memsz: 24] flags: 0x4; PT_NOTE + 4: [0x7f55716acec4; memsz: 604] flags: 0x4; PT_GNU_EH_FRAME + 5: [0x7f557168f000; memsz: 0] flags: 0x6; PT_GNU_STACK + 6: [0x7f55718afba0; memsz: 460] flags: 0x4; PT_GNU_RELRO +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (dl_iterate_phdr.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +\& +static int +callback(struct dl_phdr_info *info, size_t size, void *data) +{ + char *type; + int p_type; +\& + printf("Name: \e"%s\e" (%d segments)\en", info\->dlpi_name, + info\->dlpi_phnum); +\& + for (size_t j = 0; j < info\->dlpi_phnum; j++) { + p_type = info\->dlpi_phdr[j].p_type; + type = (p_type == PT_LOAD) ? "PT_LOAD" : + (p_type == PT_DYNAMIC) ? "PT_DYNAMIC" : + (p_type == PT_INTERP) ? "PT_INTERP" : + (p_type == PT_NOTE) ? "PT_NOTE" : + (p_type == PT_INTERP) ? "PT_INTERP" : + (p_type == PT_PHDR) ? "PT_PHDR" : + (p_type == PT_TLS) ? "PT_TLS" : + (p_type == PT_GNU_EH_FRAME) ? "PT_GNU_EH_FRAME" : + (p_type == PT_GNU_STACK) ? "PT_GNU_STACK" : + (p_type == PT_GNU_RELRO) ? "PT_GNU_RELRO" : NULL; +\& + printf(" %2zu: [%14p; memsz:%7jx] flags: %#jx; ", j, + (void *) (info\->dlpi_addr + info\->dlpi_phdr[j].p_vaddr), + (uintmax_t) info\->dlpi_phdr[j].p_memsz, + (uintmax_t) info\->dlpi_phdr[j].p_flags); + if (type != NULL) + printf("%s\en", type); + else + printf("[other (%#x)]\en", p_type); + } +\& + return 0; +} +\& +int +main(void) +{ + dl_iterate_phdr(callback, NULL); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ldd (1), +.BR objdump (1), +.BR readelf (1), +.BR dladdr (3), +.BR dlopen (3), +.BR elf (5), +.BR ld.so (8) +.P +.IR "Executable and Linking Format Specification" , +available at various locations online. diff --git a/man/man3/dladdr.3 b/man/man3/dladdr.3 new file mode 100644 index 0000000..889f60a --- /dev/null +++ b/man/man3/dladdr.3 @@ -0,0 +1,275 @@ +'\" t +.\" Copyright (C) 2015 Michael Kerrisk +.\" and Copyright (C) 2008 Petr Baudis (dladdr caveat) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH dladdr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dladdr, dladdr1 \- translate address to symbolic information +.SH LIBRARY +Dynamic linking library +.RI ( libdl ", " \-ldl ) +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.P +.BI "int dladdr(const void *" addr ", Dl_info *" info ); +.BI "int dladdr1(const void *" addr ", Dl_info *" info ", void **" extra_info , +.BI " int " flags ); +.fi +.SH DESCRIPTION +The function +.BR dladdr () +determines whether the address specified in +.I addr +is located in one of the shared objects loaded by the calling application. +If it is, then +.BR dladdr () +returns information about the shared object and symbol that overlaps +.IR addr . +This information is returned in a +.I Dl_info +structure: +.P +.in +4n +.EX +typedef struct { + const char *dli_fname; /* Pathname of shared object that + contains address */ + void *dli_fbase; /* Base address at which shared + object is loaded */ + const char *dli_sname; /* Name of symbol whose definition + overlaps \fIaddr\fP */ + void *dli_saddr; /* Exact address of symbol named + in \fIdli_sname\fP */ +} Dl_info; +.EE +.in +.P +If no symbol matching +.I addr +could be found, then +.I dli_sname +and +.I dli_saddr +are set to NULL. +.P +The function +.BR dladdr1 () +is like +.BR dladdr (), +but returns additional information via the argument +.IR extra_info . +The information returned depends on the value specified in +.IR flags , +which can have one of the following values: +.TP +.B RTLD_DL_LINKMAP +Obtain a pointer to the link map for the matched file. +The +.I extra_info +argument points to a pointer to a +.I link_map +structure (i.e., +.IR "struct link_map\~**" ), +defined in +.I +as: +.IP +.in +4n +.EX +struct link_map { + ElfW(Addr) l_addr; /* Difference between the + address in the ELF file and + the address in memory */ + char *l_name; /* Absolute pathname where + object was found */ + ElfW(Dyn) *l_ld; /* Dynamic section of the + shared object */ + struct link_map *l_next, *l_prev; + /* Chain of loaded objects */ +\& + /* Plus additional fields private to the + implementation */ +}; +.EE +.in +.TP +.B RTLD_DL_SYMENT +Obtain a pointer to the ELF symbol table entry of the matching symbol. +The +.I extra_info +argument is a pointer to a symbol pointer: +.IR "const ElfW(Sym) **" . +The +.IR ElfW () +macro definition turns its argument into the name of an ELF data +type suitable for the hardware architecture. +For example, on a 64-bit platform, +.I ElfW(Sym) +yields the data type name +.IR Elf64_Sym , +which is defined in +.I +as: +.IP +.in +4n +.EX +typedef struct { + Elf64_Word st_name; /* Symbol name */ + unsigned char st_info; /* Symbol type and binding */ + unsigned char st_other; /* Symbol visibility */ + Elf64_Section st_shndx; /* Section index */ + Elf64_Addr st_value; /* Symbol value */ + Elf64_Xword st_size; /* Symbol size */ +} Elf64_Sym; +.EE +.in +.IP +The +.I st_name +field is an index into the string table. +.IP +The +.I st_info +field encodes the symbol's type and binding. +The type can be extracted using the macro +.B ELF64_ST_TYPE(st_info) +(or +.B ELF32_ST_TYPE() +on 32-bit platforms), which yields one of the following values: +.in +4n +.TS +lb lb +lb l. +Value Description +STT_NOTYPE Symbol type is unspecified +STT_OBJECT Symbol is a data object +STT_FUNC Symbol is a code object +STT_SECTION Symbol associated with a section +STT_FILE Symbol's name is filename +STT_COMMON Symbol is a common data object +STT_TLS Symbol is thread-local data object +STT_GNU_IFUNC Symbol is indirect code object +.TE +.in +.IP +The symbol binding can be extracted from the +.I st_info +field using the macro +.B ELF64_ST_BIND(st_info) +(or +.B ELF32_ST_BIND() +on 32-bit platforms), which yields one of the following values: +.in +4n +.TS +lb lb +lb l. +Value Description +STB_LOCAL Local symbol +STB_GLOBAL Global symbol +STB_WEAK Weak symbol +STB_GNU_UNIQUE Unique symbol +.TE +.in +.IP +The +.I st_other +field contains the symbol's visibility, which can be extracted using the macro +.B ELF64_ST_VISIBILITY(st_info) +(or +.B ELF32_ST_VISIBILITY() +on 32-bit platforms), which yields one of the following values: +.in +4n +.TS +lb lb +lb l. +Value Description +STV_DEFAULT Default symbol visibility rules +STV_INTERNAL Processor-specific hidden class +STV_HIDDEN Symbol unavailable in other modules +STV_PROTECTED Not preemptible, not exported +.TE +.in +.SH RETURN VALUE +On success, these functions return a nonzero value. +If the address specified in +.I addr +could be matched to a shared object, +but not to a symbol in the shared object, then the +.I info\->dli_sname +and +.I info\->dli_saddr +fields are set to NULL. +.P +If the address specified in +.I addr +could not be matched to a shared object, then these functions return 0. +In this case, an error message is +.I not +.\" According to the FreeBSD man page, dladdr1() does signal an +.\" error via dlerror() for this case. +available via +.BR dlerror (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dladdr (), +.BR dladdr1 () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +.TP +.BR dladdr () +glibc 2.0. +.TP +.BR dladdr1 () +glibc 2.3.3. +.P +Solaris. +.SH BUGS +Sometimes, the function pointers you pass to +.BR dladdr () +may surprise you. +On some architectures (notably i386 and x86-64), +.I dli_fname +and +.I dli_fbase +may end up pointing back at the object from which you called +.BR dladdr (), +even if the function used as an argument should come from +a dynamically linked library. +.P +The problem is that the function pointer will still be resolved +at compile time, but merely point to the +.I plt +(Procedure Linkage Table) +section of the original object (which dispatches the call after +asking the dynamic linker to resolve the symbol). +To work around this, +you can try to compile the code to be position-independent: +then, the compiler cannot prepare the pointer +at compile time any more and +.BR gcc (1) +will generate code that just loads the final symbol address from the +.I got +(Global Offset Table) at run time before passing it to +.BR dladdr (). +.SH SEE ALSO +.BR dl_iterate_phdr (3), +.BR dlinfo (3), +.BR dlopen (3), +.BR dlsym (3), +.BR ld.so (8) diff --git a/man/man3/dladdr1.3 b/man/man3/dladdr1.3 new file mode 100644 index 0000000..43979e5 --- /dev/null +++ b/man/man3/dladdr1.3 @@ -0,0 +1 @@ +.so man3/dladdr.3 diff --git a/man/man3/dlclose.3 b/man/man3/dlclose.3 new file mode 100644 index 0000000..15d0968 --- /dev/null +++ b/man/man3/dlclose.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man/man3/dlerror.3 b/man/man3/dlerror.3 new file mode 100644 index 0000000..85c904a --- /dev/null +++ b/man/man3/dlerror.3 @@ -0,0 +1,78 @@ +'\" t +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" and Copyright 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH dlerror 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dlerror \- obtain error diagnostic for functions in the dlopen API +.SH LIBRARY +Dynamic linking library +.RI ( libdl ", " \-ldl ) +.SH SYNOPSIS +.nf +.B #include +.P +.B "char *dlerror(void);" +.fi +.SH DESCRIPTION +The +.BR dlerror () +function returns a human-readable, +null-terminated string describing the most recent error +that occurred from a call to one of the functions in the dlopen API +since the last call to +.BR dlerror (). +The returned string does +.I not +include a trailing newline. +.P +.BR dlerror () +returns NULL if no errors have occurred since initialization or since +it was last called. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dlerror () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0. +POSIX.1-2001. +.P +SunOS. +.SH NOTES +The message returned by +.BR dlerror () +may reside in a statically allocated buffer that is +overwritten by subsequent +.BR dlerror () +calls. +.\" .P +.\" The string returned by +.\" .BR dlerror () +.\" should not be modified. +.\" Some systems give the prototype as +.\" .sp +.\" .in +5 +.\" .B "const char *dlerror(void);" +.\" .in +.SH EXAMPLES +See +.BR dlopen (3). +.SH SEE ALSO +.BR dladdr (3), +.BR dlinfo (3), +.BR dlopen (3), +.BR dlsym (3) diff --git a/man/man3/dlinfo.3 b/man/man3/dlinfo.3 new file mode 100644 index 0000000..a9239d9 --- /dev/null +++ b/man/man3/dlinfo.3 @@ -0,0 +1,317 @@ +'\" t +.\" Copyright (C) 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH dlinfo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dlinfo \- obtain information about a dynamically loaded object +.SH LIBRARY +Dynamic linking library +.RI ( libdl ", " \-ldl ) +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.B #include +.P +.BR "int dlinfo(void *restrict " handle ", int " request \ +", void *restrict " info ); +.fi +.SH DESCRIPTION +The +.BR dlinfo () +function obtains information about the dynamically loaded object +referred to by +.I handle +(typically obtained by an earlier call to +.BR dlopen (3) +or +.BR dlmopen (3)). +The +.I request +argument specifies which information is to be returned. +The +.I info +argument is a pointer to a buffer used to store information +returned by the call; the type of this argument depends on +.IR request . +.P +The following values are supported for +.I request +(with the corresponding type for +.I info +shown in parentheses): +.TP +.BR RTLD_DI_LMID " (\fILmid_t *\fP)" +Obtain the ID of the link-map list (namespace) in which +.I handle +is loaded. +.TP +.BR RTLD_DI_LINKMAP " (\fIstruct link_map **\fP)" +Obtain a pointer to the +.I link_map +structure corresponding to +.IR handle . +The +.I info +argument points to a pointer to a +.I link_map +structure, defined in +.I +as: +.IP +.in +4n +.EX +struct link_map { + ElfW(Addr) l_addr; /* Difference between the + address in the ELF file and + the address in memory */ + char *l_name; /* Absolute pathname where + object was found */ + ElfW(Dyn) *l_ld; /* Dynamic section of the + shared object */ + struct link_map *l_next, *l_prev; + /* Chain of loaded objects */ +\& + /* Plus additional fields private to the + implementation */ +}; +.EE +.in +.TP +.BR RTLD_DI_ORIGIN " (\fIchar *\fP)" +Copy the pathname of the origin of the shared object corresponding to +.I handle +to the location pointed to by +.IR info . +.TP +.BR RTLD_DI_SERINFO " (\fIDl_serinfo *\fP)" +Obtain the library search paths for the shared object referred to by +.IR handle . +The +.I info +argument is a pointer to a +.I Dl_serinfo +that contains the search paths. +Because the number of search paths may vary, +the size of the structure pointed to by +.I info +can vary. +The +.B RTLD_DI_SERINFOSIZE +request described below allows applications to size the buffer suitably. +The caller must perform the following steps: +.RS +.IP (1) 5 +Use a +.B RTLD_DI_SERINFOSIZE +request to populate a +.I Dl_serinfo +structure with the size +.RI ( dls_size ) +of the structure needed for the subsequent +.B RTLD_DI_SERINFO +request. +.IP (2) +Allocate a +.I Dl_serinfo +buffer of the correct size +.RI ( dls_size ). +.IP (3) +Use a further +.B RTLD_DI_SERINFOSIZE +request to populate the +.I dls_size +and +.I dls_cnt +fields of the buffer allocated in the previous step. +.IP (4) +Use a +.B RTLD_DI_SERINFO +to obtain the library search paths. +.RE +.IP +The +.I Dl_serinfo +structure is defined as follows: +.IP +.in +4n +.EX +typedef struct { + size_t dls_size; /* Size in bytes of + the whole buffer */ + unsigned int dls_cnt; /* Number of elements + in \[aq]dls_serpath\[aq] */ + Dl_serpath dls_serpath[1]; /* Actually longer, + \[aq]dls_cnt\[aq] elements */ +} Dl_serinfo; +.EE +.in +.IP +Each of the +.I dls_serpath +elements in the above structure is a structure of the following form: +.IP +.in +4n +.EX +typedef struct { + char *dls_name; /* Name of library search + path directory */ + unsigned int dls_flags; /* Indicates where this + directory came from */ +} Dl_serpath; +.EE +.in +.IP +The +.I dls_flags +field is currently unused, and always contains zero. +.TP +.BR RTLD_DI_SERINFOSIZE " (\fIDl_serinfo *\fP)" +Populate the +.I dls_size +and +.I dls_cnt +fields of the +.I Dl_serinfo +structure pointed to by +.I info +with values suitable for allocating a buffer for use in a subsequent +.B RTLD_DI_SERINFO +request. +.TP +.BR RTLD_DI_TLS_MODID " (\fIsize_t *\fP, since glibc 2.4)" +Obtain the module ID of this shared object's TLS (thread-local storage) +segment, as used in TLS relocations. +If this object does not define a TLS segment, zero is placed in +.IR *info . +.TP +.BR RTLD_DI_TLS_DATA " (\fIvoid **\fP, since glibc 2.4)" +Obtain a pointer to the calling +thread's TLS block corresponding to this shared object's TLS segment. +If this object does not define a PT_TLS segment, +or if the calling thread has not allocated a block for it, +NULL is placed in +.IR *info . +.SH RETURN VALUE +On success, +.BR dlinfo () +returns 0. +On failure, it returns \-1; the cause of the error can be diagnosed using +.BR dlerror (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dlinfo () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The sets of requests supported by the various implementations +overlaps only partially. +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.3.3. +Solaris. +.SH EXAMPLES +The program below opens a shared objects using +.BR dlopen (3) +and then uses the +.B RTLD_DI_SERINFOSIZE +and +.B RTLD_DI_SERINFO +requests to obtain the library search path list for the library. +Here is an example of what we might see when running the program: +.P +.in +4n +.EX +$ \fB./a.out /lib64/libm.so.6\fP +dls_serpath[0].dls_name = /lib64 +dls_serpath[1].dls_name = /usr/lib64 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (dlinfo.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + void *handle; + Dl_serinfo serinfo; + Dl_serinfo *sip; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Obtain a handle for shared object specified on command line. */ +\& + handle = dlopen(argv[1], RTLD_NOW); + if (handle == NULL) { + fprintf(stderr, "dlopen() failed: %s\en", dlerror()); + exit(EXIT_FAILURE); + } +\& + /* Discover the size of the buffer that we must pass to + RTLD_DI_SERINFO. */ +\& + if (dlinfo(handle, RTLD_DI_SERINFOSIZE, &serinfo) == \-1) { + fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\en", dlerror()); + exit(EXIT_FAILURE); + } +\& + /* Allocate the buffer for use with RTLD_DI_SERINFO. */ +\& + sip = malloc(serinfo.dls_size); + if (sip == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + /* Initialize the \[aq]dls_size\[aq] and \[aq]dls_cnt\[aq] fields in the newly + allocated buffer. */ +\& + if (dlinfo(handle, RTLD_DI_SERINFOSIZE, sip) == \-1) { + fprintf(stderr, "RTLD_DI_SERINFOSIZE failed: %s\en", dlerror()); + exit(EXIT_FAILURE); + } +\& + /* Fetch and print library search list. */ +\& + if (dlinfo(handle, RTLD_DI_SERINFO, sip) == \-1) { + fprintf(stderr, "RTLD_DI_SERINFO failed: %s\en", dlerror()); + exit(EXIT_FAILURE); + } +\& + for (size_t j = 0; j < serinfo.dls_cnt; j++) + printf("dls_serpath[%zu].dls_name = %s\en", + j, sip\->dls_serpath[j].dls_name); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR dl_iterate_phdr (3), +.BR dladdr (3), +.BR dlerror (3), +.BR dlopen (3), +.BR dlsym (3), +.BR ld.so (8) diff --git a/man/man3/dlmopen.3 b/man/man3/dlmopen.3 new file mode 100644 index 0000000..15d0968 --- /dev/null +++ b/man/man3/dlmopen.3 @@ -0,0 +1 @@ +.so man3/dlopen.3 diff --git a/man/man3/dlopen.3 b/man/man3/dlopen.3 new file mode 100644 index 0000000..14f1689 --- /dev/null +++ b/man/man3/dlopen.3 @@ -0,0 +1,624 @@ +'\" t +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" written by Adam J. Richter (adam@yggdrasil.com), +.\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com). +.\" and Copyright 2003, 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified by David A. Wheeler 2000-11-28. +.\" Applied patch by Terran Melconian, aeb, 2001-12-14. +.\" Modified by Hacksaw 2003-03-13. +.\" Modified by Matt Domsch, 2003-04-09: _init and _fini obsolete +.\" Modified by Michael Kerrisk 2003-05-16. +.\" Modified by Walter Harms: dladdr, dlvsym +.\" Modified by Petr Baudis , 2008-12-04: dladdr caveat +.\" +.TH dlopen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dlclose, dlopen, dlmopen \- +open and close a shared object +.SH LIBRARY +Dynamic linking library +.RI ( libdl ", " \-ldl ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *dlopen(const char *" filename ", int " flags ); +.BI "int dlclose(void *" handle ); +.P +.B #define _GNU_SOURCE +.br +.B #include +.P +.BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags ); +.fi +.SH DESCRIPTION +.SS dlopen() +The function +.BR dlopen () +loads the dynamic shared object (shared library) +file named by the null-terminated +string +.I filename +and returns an opaque "handle" for the loaded object. +This handle is employed with other functions in the dlopen API, such as +.BR dlsym (3), +.BR dladdr (3), +.BR dlinfo (3), +and +.BR dlclose (). +.P +If +.I filename +.\" FIXME On Solaris, when handle is NULL, we seem to get back +.\" a handle for (something like) the root of the namespace. +.\" The point here is that if we do a dlmopen(LM_ID_NEWLM), then +.\" the filename==NULL case returns a different handle than +.\" in the initial namespace. But, on glibc, the same handle is +.\" returned. This is probably a bug in glibc. +.\" +is NULL, then the returned handle is for the main program. +If +.I filename +contains a slash ("/"), then it is interpreted as a (relative +or absolute) pathname. +Otherwise, the dynamic linker searches for the object as follows +(see +.BR ld.so (8) +for further details): +.IP \[bu] 3 +(ELF only) If the calling object +(i.e., the shared library or executable from which +.BR dlopen () +is called) +contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag, +then the directories listed in the DT_RPATH tag are searched. +.IP \[bu] +If, at the time that the program was started, the environment variable +.B LD_LIBRARY_PATH +was defined to contain a colon-separated list of directories, +then these are searched. +(As a security measure, this variable is ignored for set-user-ID and +set-group-ID programs.) +.IP \[bu] +(ELF only) If the calling object +contains a DT_RUNPATH tag, then the directories listed in that tag +are searched. +.IP \[bu] +The cache file +.I /etc/ld.so.cache +(maintained by +.BR ldconfig (8)) +is checked to see whether it contains an entry for +.IR filename . +.IP \[bu] +The directories +.I /lib +and +.I /usr/lib +are searched (in that order). +.P +If the object specified by +.I filename +has dependencies on other shared objects, +then these are also automatically loaded by the dynamic linker +using the same rules. +(This process may occur recursively, +if those objects in turn have dependencies, and so on.) +.P +One of the following two values must be included in +.IR flags : +.TP +.B RTLD_LAZY +Perform lazy binding. +Resolve symbols only as the code that references them is executed. +If the symbol is never referenced, then it is never resolved. +(Lazy binding is performed only for function references; +references to variables are always immediately bound when +the shared object is loaded.) +Since glibc 2.1.1, +.\" commit 12b5b6b7f78ea111e89bbf638294a5413c791072 +this flag is overridden by the effect of the +.B LD_BIND_NOW +environment variable. +.TP +.B RTLD_NOW +If this value is specified, or the environment variable +.B LD_BIND_NOW +is set to a nonempty string, +all undefined symbols in the shared object are resolved before +.BR dlopen () +returns. +If this cannot be done, an error is returned. +.P +Zero or more of the following values may also be ORed in +.IR flags : +.TP +.B RTLD_GLOBAL +The symbols defined by this shared object will be +made available for symbol resolution of subsequently loaded shared objects. +.TP +.B RTLD_LOCAL +This is the converse of +.BR RTLD_GLOBAL , +and the default if neither flag is specified. +Symbols defined in this shared object are not made available to resolve +references in subsequently loaded shared objects. +.TP +.BR RTLD_NODELETE " (since glibc 2.2)" +Do not unload the shared object during +.BR dlclose (). +Consequently, the object's static and global variables are not reinitialized +if the object is reloaded with +.BR dlopen () +at a later time. +.TP +.BR RTLD_NOLOAD " (since glibc 2.2)" +Don't load the shared object. +This can be used to test if the object is already resident +.RB ( dlopen () +returns NULL if it is not, or the object's handle if it is resident). +This flag can also be used to promote the flags on a shared object +that is already loaded. +For example, a shared object that was previously loaded with +.B RTLD_LOCAL +can be reopened with +.BR RTLD_NOLOAD\ |\ RTLD_GLOBAL . +.\" +.TP +.BR RTLD_DEEPBIND " (since glibc 2.3.4)" +.\" Inimitably described by UD in +.\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html. +Place the lookup scope of the symbols in this +shared object ahead of the global scope. +This means that a self-contained object will use +its own symbols in preference to global symbols with the same name +contained in objects that have already been loaded. +.P +If +.I filename +is NULL, then the returned handle is for the main program. +When given to +.BR dlsym (3), +this handle causes a search for a symbol in the main program, +followed by all shared objects loaded at program startup, +and then all shared objects loaded by +.BR dlopen () +with the flag +.BR RTLD_GLOBAL . +.P +Symbol references in the shared object are resolved using (in order): +symbols in the link map of objects loaded for the main program and its +dependencies; +symbols in shared objects (and their dependencies) +that were previously opened with +.BR dlopen () +using the +.B RTLD_GLOBAL +flag; +and definitions in the shared object itself +(and any dependencies that were loaded for that object). +.P +Any global symbols in the executable that were placed into +its dynamic symbol table by +.BR ld (1) +can also be used to resolve references in a dynamically loaded shared object. +Symbols may be placed in the dynamic symbol table +either because the executable was linked with the flag "\-rdynamic" +(or, synonymously, "\-\-export\-dynamic"), which causes all of +the executable's global symbols to be placed in the dynamic symbol table, +or because +.BR ld (1) +noted a dependency on a symbol in another object during static linking. +.P +If the same shared object is opened again with +.BR dlopen (), +the same object handle is returned. +The dynamic linker maintains reference +counts for object handles, so a dynamically loaded shared object is not +deallocated until +.BR dlclose () +has been called on it as many times as +.BR dlopen () +has succeeded on it. +Constructors (see below) are called only when the object is actually loaded +into memory (i.e., when the reference count increases to 1). +.P +A subsequent +.BR dlopen () +call that loads the same shared object with +.B RTLD_NOW +may force symbol resolution for a shared object earlier loaded with +.BR RTLD_LAZY . +Similarly, an object that was previously opened with +.B RTLD_LOCAL +can be promoted to +.B RTLD_GLOBAL +in a subsequent +.BR dlopen (). +.P +If +.BR dlopen () +fails for any reason, it returns NULL. +.\" +.SS dlmopen() +This function performs the same task as +.BR dlopen ()\[em]the +.I filename +and +.I flags +arguments, as well as the return value, are the same, +except for the differences noted below. +.P +The +.BR dlmopen () +function differs from +.BR dlopen () +primarily in that it accepts an additional argument, +.IR lmid , +that specifies the link-map list (also referred to as a +.IR namespace ) +in which the shared object should be loaded. +(By comparison, +.BR dlopen () +adds the dynamically loaded shared object to the same namespace as +the shared object from which the +.BR dlopen () +call is made.) +The +.I Lmid_t +type is an opaque handle that refers to a namespace. +.P +The +.I lmid +argument is either the ID of an existing namespace +.\" FIXME: Is using dlinfo() RTLD_DI_LMID the right technique? +(which can be obtained using the +.BR dlinfo (3) +.B RTLD_DI_LMID +request) or one of the following special values: +.TP +.B LM_ID_BASE +Load the shared object in the initial namespace +(i.e., the application's namespace). +.TP +.B LM_ID_NEWLM +Create a new namespace and load the shared object in that namespace. +The object must have been correctly linked +to reference all of the other shared objects that it requires, +since the new namespace is initially empty. +.P +If +.I filename +is NULL, then the only permitted value for +.I lmid +is +.BR LM_ID_BASE . +.SS dlclose() +The function +.BR dlclose () +decrements the reference count on the +dynamically loaded shared object referred to by +.IR handle . +.P +If the object's reference count drops to zero +and no symbols in this object are required by other objects, +then the object is unloaded +after first calling any destructors defined for the object. +(Symbols in this object might be required in another object +because this object was opened with the +.B RTLD_GLOBAL +flag and one of its symbols satisfied a relocation in another object.) +.P +All shared objects that were automatically loaded when +.BR dlopen () +was invoked on the object referred to by +.I handle +are recursively closed in the same manner. +.P +A successful return from +.BR dlclose () +does not guarantee that the symbols associated with +.I handle +are removed from the caller's address space. +In addition to references resulting from explicit +.BR dlopen () +calls, a shared object may have been implicitly loaded +(and reference counted) because of dependencies in other shared objects. +Only when all references have been released can the shared object +be removed from the address space. +.SH RETURN VALUE +On success, +.BR dlopen () +and +.BR dlmopen () +return a non-NULL handle for the loaded object. +On error +(file could not be found, was not readable, had the wrong format, +or caused errors during loading), +these functions return NULL. +.P +On success, +.BR dlclose () +returns 0; on error, it returns a nonzero value. +.P +Errors from these functions can be diagnosed using +.BR dlerror (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dlopen (), +.BR dlmopen (), +.BR dlclose () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR dlopen () +.TQ +.BR dlclose () +POSIX.1-2008. +.TP +.BR dlmopen () +.TQ +.B RTLD_NOLOAD +.TQ +.B RTLD_NODELETE +GNU. +.TP +.B RTLD_DEEPBIND +Solaris. +.SH HISTORY +.TP +.BR dlopen () +.TQ +.BR dlclose () +glibc 2.0. +POSIX.1-2001. +.TP +.BR dlmopen () +glibc 2.3.4. +.SH NOTES +.SS dlmopen() and namespaces +A link-map list defines an isolated namespace for the +resolution of symbols by the dynamic linker. +Within a namespace, +dependent shared objects are implicitly loaded according to the usual rules, +and symbol references are likewise resolved according to the usual rules, +but such resolution is confined to the definitions provided by the +objects that have been (explicitly and implicitly) loaded into the namespace. +.P +The +.BR dlmopen () +function permits object-load isolation\[em]the ability +to load a shared object in a new namespace without +exposing the rest of the application to the symbols +made available by the new object. +Note that the use of the +.B RTLD_LOCAL +flag is not sufficient for this purpose, +since it prevents a shared object's symbols from being available to +.I any +other shared object. +In some cases, +we may want to make the symbols provided by a dynamically +loaded shared object available to (a subset of) other shared objects +without exposing those symbols to the entire application. +This can be achieved by using a separate namespace and the +.B RTLD_GLOBAL +flag. +.P +The +.BR dlmopen () +function also can be used to provide better isolation than the +.B RTLD_LOCAL +flag. +In particular, shared objects loaded with +.B RTLD_LOCAL +may be promoted to +.B RTLD_GLOBAL +if they are dependencies of another shared object loaded with +.BR RTLD_GLOBAL . +Thus, +.B RTLD_LOCAL +is insufficient to isolate a loaded shared object except in the (uncommon) +case where one has explicit control over all shared object dependencies. +.P +Possible uses of +.BR dlmopen () +are plugins where the author of the plugin-loading framework +can't trust the plugin authors and does not wish +any undefined symbols from the plugin framework to be resolved to plugin +symbols. +Another use is to load the same object more than once. +Without the use of +.BR dlmopen (), +this would require the creation of distinct copies of the shared object file. +Using +.BR dlmopen (), +this can be achieved by loading the same shared object file into +different namespaces. +.P +The glibc implementation supports a maximum of +.\" DL_NNS +16 namespaces. +.\" +.SS Initialization and finalization functions +Shared objects may export functions using the +.B __attribute__((constructor)) +and +.B __attribute__((destructor)) +function attributes. +Constructor functions are executed before +.BR dlopen () +returns, and destructor functions are executed before +.BR dlclose () +returns. +A shared object may export multiple constructors and destructors, +and priorities can be associated with each function +to determine the order in which they are executed. +See the +.B gcc +info pages (under "Function attributes") +.\" info gcc "C Extensions" "Function attributes" +for further information. +.P +An older method of (partially) achieving the same result is via the use of +two special symbols recognized by the linker: +.B _init +and +.BR _fini . +If a dynamically loaded shared object exports a routine named +.BR _init (), +then that code is executed after loading a shared object, before +.BR dlopen () +returns. +If the shared object exports a routine named +.BR _fini (), +then that routine is called just before the object is unloaded. +In this case, one must avoid linking against the system startup files, +which contain default versions of these files; +this can be done by using the +.BR gcc (1) +.I \-nostartfiles +command-line option. +.P +Use of +.B _init +and +.B _fini +is now deprecated in favor of the aforementioned +constructors and destructors, +which among other advantages, +permit multiple initialization and finalization functions to be defined. +.\" +.\" Using these routines, or the gcc +.\" .B \-nostartfiles +.\" or +.\" .B \-nostdlib +.\" options, is not recommended. +.\" Their use may result in undesired behavior, +.\" since the constructor/destructor routines will not be executed +.\" (unless special measures are taken). +.\" .\" void _init(void) __attribute__((constructor)); +.\" .\" void _fini(void) __attribute__((destructor)); +.\" +.P +Since glibc 2.2.3, +.BR atexit (3) +can be used to register an exit handler that is automatically +called when a shared object is unloaded. +.SS History +These functions are part of the dlopen API, derived from SunOS. +.SH BUGS +As at glibc 2.24, specifying the +.B RTLD_GLOBAL +flag when calling +.BR dlmopen () +.\" dlerror(): "invalid mode" +generates an error. +Furthermore, specifying +.B RTLD_GLOBAL +when calling +.BR dlopen () +results in a program crash +.RB ( SIGSEGV ) +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=18684 +if the call is made from any object loaded in a +namespace other than the initial namespace. +.SH EXAMPLES +The program below loads the (glibc) math library, +looks up the address of the +.BR cos (3) +function, and prints the cosine of 2.0. +The following is an example of building and running the program: +.P +.in +4n +.EX +$ \fBcc dlopen_demo.c \-ldl\fP +$ \fB./a.out\fP +\-0.416147 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (dlopen.c) +.EX +#include +#include +#include +\& +#include /* Defines LIBM_SO (which will be a + string such as "libm.so.6") */ +int +main(void) +{ + void *handle; + double (*cosine)(double); + char *error; +\& + handle = dlopen(LIBM_SO, RTLD_LAZY); + if (!handle) { + fprintf(stderr, "%s\en", dlerror()); + exit(EXIT_FAILURE); + } +\& + dlerror(); /* Clear any existing error */ +\& + cosine = (double (*)(double)) dlsym(handle, "cos"); +\& + /* According to the ISO C standard, casting between function + pointers and \[aq]void *\[aq], as done above, produces undefined results. + POSIX.1\-2001 and POSIX.1\-2008 accepted this state of affairs and + proposed the following workaround: +\& + *(void **) (&cosine) = dlsym(handle, "cos"); +\& + This (clumsy) cast conforms with the ISO C standard and will + avoid any compiler warnings. +\& + The 2013 Technical Corrigendum 1 to POSIX.1\-2008 improved matters + by requiring that conforming implementations support casting + \[aq]void *\[aq] to a function pointer. Nevertheless, some compilers + (e.g., gcc with the \[aq]\-pedantic\[aq] option) may complain about the + cast used in this program. */ +.\" http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08 +.\" http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07 +.\" http://austingroupbugs.net/view.php?id=74 +\& + error = dlerror(); + if (error != NULL) { + fprintf(stderr, "%s\en", error); + exit(EXIT_FAILURE); + } +\& + printf("%f\en", (*cosine)(2.0)); + dlclose(handle); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ld (1), +.BR ldd (1), +.BR pldd (1), +.BR dl_iterate_phdr (3), +.BR dladdr (3), +.BR dlerror (3), +.BR dlinfo (3), +.BR dlsym (3), +.BR rtld\-audit (7), +.BR ld.so (8), +.BR ldconfig (8) +.P +gcc info pages, ld info pages diff --git a/man/man3/dlsym.3 b/man/man3/dlsym.3 new file mode 100644 index 0000000..dd5fb99 --- /dev/null +++ b/man/man3/dlsym.3 @@ -0,0 +1,171 @@ +'\" t +.\" Copyright 1995 Yggdrasil Computing, Incorporated. +.\" and Copyright 2003, 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH dlsym 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dlsym, dlvsym \- obtain address of a symbol in a shared object or executable +.SH LIBRARY +Dynamic linking library +.RI ( libdl ", " \-ldl ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *dlsym(void *restrict " handle ", const char *restrict " symbol ); +.P +.B #define _GNU_SOURCE +.B #include +.P +.BI "void *dlvsym(void *restrict " handle ", const char *restrict " symbol , +.BI " const char *restrict " version ); +.fi +.SH DESCRIPTION +The function +.BR dlsym () +takes a "handle" of a dynamic loaded shared object returned by +.BR dlopen (3) +along with a null-terminated symbol name, +and returns the address where that symbol is +loaded into memory. +If the symbol is not found, in the specified +object or any of the shared objects that were automatically loaded by +.BR dlopen (3) +when that object was loaded, +.BR dlsym () +returns NULL. +(The search performed by +.BR dlsym () +is breadth first through the dependency tree of these shared objects.) +.P +In unusual cases (see NOTES) the value of the symbol could actually be NULL. +Therefore, a NULL return from +.BR dlsym () +need not indicate an error. +The correct way to distinguish an error from a symbol whose value is NULL +is to call +.BR dlerror (3) +to clear any old error conditions, then call +.BR dlsym (), +and then call +.BR dlerror (3) +again, saving its return value into a variable, and check whether +this saved value is not NULL. +.P +There are two special pseudo-handles that may be specified in +.IR handle : +.TP +.B RTLD_DEFAULT +Find the first occurrence of the desired symbol +using the default shared object search order. +The search will include global symbols in the executable +and its dependencies, +as well as symbols in shared objects that were dynamically loaded with the +.B RTLD_GLOBAL +flag. +.TP +.B RTLD_NEXT +Find the next occurrence of the desired symbol in the search order +after the current object. +This allows one to provide a wrapper +around a function in another shared object, so that, for example, +the definition of a function in a preloaded shared object +(see +.B LD_PRELOAD +in +.BR ld.so (8)) +can find and invoke the "real" function provided in another shared object +(or for that matter, the "next" definition of the function in cases +where there are multiple layers of preloading). +.P +The +.B _GNU_SOURCE +feature test macro must be defined in order to obtain the +definitions of +.B RTLD_DEFAULT +and +.B RTLD_NEXT +from +.IR . +.P +The function +.BR dlvsym () +does the same as +.BR dlsym () +but takes a version string as an additional argument. +.SH RETURN VALUE +On success, +these functions return the address associated with +.IR symbol . +On failure, they return NULL; +the cause of the error can be diagnosed using +.BR dlerror (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dlsym (), +.BR dlvsym () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR dlsym () +POSIX.1-2008. +.TP +.BR dlvsym () +GNU. +.SH HISTORY +.TP +.BR dlsym () +glibc 2.0. +POSIX.1-2001. +.TP +.BR dlvsym () +glibc 2.1. +.SH NOTES +There are several scenarios when the address of a global symbol is NULL. +For example, a symbol can be placed at zero address by the linker, via +a linker script or with +.I \-\-defsym +command-line option. +Undefined weak symbols also have NULL value. +Finally, the symbol value may be the result of +a GNU indirect function (IFUNC) resolver function that returns +NULL as the resolved value. +In the latter case, +.BR dlsym () +also returns NULL without error. +However, in the former two cases, the +behavior of GNU dynamic linker is inconsistent: relocation processing +succeeds and the symbol can be observed to have NULL value, but +.BR dlsym () +fails and +.BR dlerror () +indicates a lookup error. +.\" +.SS History +The +.BR dlsym () +function is part of the dlopen API, derived from SunOS. +That system does not have +.BR dlvsym (). +.SH EXAMPLES +See +.BR dlopen (3). +.SH SEE ALSO +.BR dl_iterate_phdr (3), +.BR dladdr (3), +.BR dlerror (3), +.BR dlinfo (3), +.BR dlopen (3), +.BR ld.so (8) diff --git a/man/man3/dlvsym.3 b/man/man3/dlvsym.3 new file mode 100644 index 0000000..df2ca09 --- /dev/null +++ b/man/man3/dlvsym.3 @@ -0,0 +1 @@ +.so man3/dlsym.3 diff --git a/man/man3/dn_comp.3 b/man/man3/dn_comp.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/dn_comp.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/dn_expand.3 b/man/man3/dn_expand.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/dn_expand.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/dprintf.3 b/man/man3/dprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/dprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/drand48.3 b/man/man3/drand48.3 new file mode 100644 index 0000000..6d61a08 --- /dev/null +++ b/man/man3/drand48.3 @@ -0,0 +1,262 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:46:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH drand48 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, +lcong48 \- generate uniformly distributed pseudo-random numbers +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B double drand48(void); +.BI "double erand48(unsigned short " xsubi [3]); +.P +.B long lrand48(void); +.BI "long nrand48(unsigned short " xsubi [3]); +.P +.B long mrand48(void); +.BI "long jrand48(unsigned short " xsubi [3]); +.P +.BI "void srand48(long " seedval ); +.BI "unsigned short *seed48(unsigned short " seed16v [3]); +.BI "void lcong48(unsigned short " param [7]); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.\" .BR drand48 (), +.\" .BR erand48 (), +.\" .BR lrand48 (), +.\" .BR nrand48 (), +.\" .BR mrand48 (), +.\" .BR jrand48 (), +.\" .BR srand48 (), +.\" .BR seed48 (), +.\" .BR lcong48 (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions generate pseudo-random numbers using the linear congruential +algorithm and 48-bit integer arithmetic. +.P +The +.BR drand48 () +and +.BR erand48 () +functions return nonnegative +double-precision floating-point values uniformly distributed over the interval +[0.0,\ 1.0). +.P +The +.BR lrand48 () +and +.BR nrand48 () +functions return nonnegative +long integers uniformly distributed over the interval [0,\ 2\[ha]31). +.P +The +.BR mrand48 () +and +.BR jrand48 () +functions return signed long +integers uniformly distributed over the interval [\-2\[ha]31,\ 2\[ha]31). +.P +The +.BR srand48 (), +.BR seed48 (), +and +.BR lcong48 () +functions are +initialization functions, one of which should be called before using +.BR drand48 (), +.BR lrand48 (), +or +.BR mrand48 (). +The functions +.BR erand48 (), +.BR nrand48 (), +and +.BR jrand48 () +do not require +an initialization function to be called first. +.P +All the functions work by generating a sequence of 48-bit integers, +.IR Xi , +according to the linear congruential formula: +.P +.in +4n +.EX +.B Xn+1 = (aXn + c) mod m, where n >= 0 +.EE +.in +.P +The parameter +.I m += 2\[ha]48, hence 48-bit integer arithmetic is performed. +Unless +.BR lcong48 () +is called, +.I a +and +.I c +are given by: +.P +.in +4n +.EX +.B a = 0x5DEECE66D +.B c = 0xB +.EE +.in +.P +The value returned by any of the functions +.BR drand48 (), +.BR erand48 (), +.BR lrand48 (), +.BR nrand48 (), +.BR mrand48 (), +or +.BR jrand48 () +is +computed by first generating the next 48-bit +.I Xi +in the sequence. +Then the appropriate number of bits, according to the type of data item to +be returned, is copied from the high-order bits of +.I Xi +and transformed +into the returned value. +.P +The functions +.BR drand48 (), +.BR lrand48 (), +and +.BR mrand48 () +store +the last 48-bit +.I Xi +generated in an internal buffer. +The functions +.BR erand48 (), +.BR nrand48 (), +and +.BR jrand48 () +require the calling +program to provide storage for the successive +.I Xi +values in the array +argument +.IR xsubi . +The functions are initialized by placing the initial +value of +.I Xi +into the array before calling the function for the first +time. +.P +The initializer function +.BR srand48 () +sets the high order 32-bits of +.I Xi +to the argument +.IR seedval . +The low order 16-bits are set +to the arbitrary value 0x330E. +.P +The initializer function +.BR seed48 () +sets the value of +.I Xi +to +the 48-bit value specified in the array argument +.IR seed16v . +The +previous value of +.I Xi +is copied into an internal buffer and a +pointer to this buffer is returned by +.BR seed48 (). +.P +The initialization function +.BR lcong48 () +allows the user to specify +initial values for +.IR Xi , +.IR a , +and +.IR c . +Array argument +elements +.I param[0\-2] +specify +.IR Xi , +.I param[3\-5] +specify +.IR a , +and +.I param[6] +specifies +.IR c . +After +.BR lcong48 () +has been called, a subsequent call to either +.BR srand48 () +or +.BR seed48 () +will restore the standard values of +.I a +and +.IR c . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR drand48 (), +.BR erand48 (), +.BR lrand48 (), +.BR nrand48 (), +.BR mrand48 (), +.BR jrand48 (), +.BR srand48 (), +.BR seed48 (), +.BR lcong48 () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:drand48 +T} +.TE +.P +The above +functions record global state information for the random number generator, +so they are not thread-safe. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.SH SEE ALSO +.BR rand (3), +.BR random (3) diff --git a/man/man3/drand48_r.3 b/man/man3/drand48_r.3 new file mode 100644 index 0000000..8191baa --- /dev/null +++ b/man/man3/drand48_r.3 @@ -0,0 +1,104 @@ +'\" t +.\" Copyright 2003 Walter Harms, 2004 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created 2004-10-31. Text taken from a page by Walter Harms, 2003-09-08 +.\" +.TH drand48_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +drand48_r, erand48_r, lrand48_r, nrand48_r, mrand48_r, jrand48_r, +srand48_r, seed48_r, lcong48_r +\- generate uniformly distributed pseudo-random numbers reentrantly +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int drand48_r(struct drand48_data *restrict " buffer , +.BI " double *restrict " result ); +.BI "int erand48_r(unsigned short " xsubi [3] "," +.BI " struct drand48_data *restrict "buffer , +.BI " double *restrict " result ");" +.P +.BI "int lrand48_r(struct drand48_data *restrict " buffer , +.BI " long *restrict " result ); +.BI "int nrand48_r(unsigned short " xsubi[3] "," +.BI " struct drand48_data *restrict "buffer , +.BI " long *restrict " result ");" +.P +.BI "int mrand48_r(struct drand48_data *restrict " buffer , +.BI " long *restrict " result ");" +.BI "int jrand48_r(unsigned short " xsubi[3] "," +.BI " struct drand48_data *restrict " buffer , +.BI " long *restrict " result ");" +.P +.BI "int srand48_r(long int " seedval ", struct drand48_data *" buffer ");" +.BI "int seed48_r(unsigned short " seed16v[3] ", struct drand48_data *" buffer ); +.BI "int lcong48_r(unsigned short " param[7] ", struct drand48_data *" buffer ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.\" .BR drand48_r (), +.\" .BR erand48_r (), +.\" .BR lrand48_r (), +.\" .BR nrand48_r (), +.\" .BR mrand48_r (), +.\" .BR jrand48_r (), +.\" .BR srand48_r (), +.\" .BR seed48_r (), +.\" .BR lcong48_r (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +These functions are the reentrant analogs of the functions described in +.BR drand48 (3). +Instead of modifying the global random generator state, they use +the supplied data +.IR buffer . +.P +Before the first use, this struct must be initialized, for example, +by filling it with zeros, or by calling one of the functions +.BR srand48_r (), +.BR seed48_r (), +or +.BR lcong48_r (). +.SH RETURN VALUE +The return value is 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR drand48_r (), +.BR erand48_r (), +.BR lrand48_r (), +.BR nrand48_r (), +.BR mrand48_r (), +.BR jrand48_r (), +.BR srand48_r (), +.BR seed48_r (), +.BR lcong48_r () +T} Thread safety MT-Safe race:buffer +.TE +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR drand48 (3), +.BR rand (3), +.BR random (3) diff --git a/man/man3/drem.3 b/man/man3/drem.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man/man3/drem.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man/man3/dremf.3 b/man/man3/dremf.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man/man3/dremf.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man/man3/dreml.3 b/man/man3/dreml.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man/man3/dreml.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man/man3/duplocale.3 b/man/man3/duplocale.3 new file mode 100644 index 0000000..6ef42bb --- /dev/null +++ b/man/man3/duplocale.3 @@ -0,0 +1,168 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH duplocale 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +duplocale \- duplicate a locale object +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "locale_t duplocale(locale_t " locobj ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR duplocale (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR duplocale () +function creates a duplicate of the locale object referred to by +.IR locobj . +.P +If +.I locobj +is +.BR LC_GLOBAL_LOCALE , +.BR duplocale () +creates a locale object containing a copy of the global locale +determined by +.BR setlocale (3). +.SH RETURN VALUE +On success, +.BR duplocale () +returns a handle for the new locale object. +On error, it returns +.IR "(locale_t)\ 0", +and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to create the duplicate locale object. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3. +.SH NOTES +Duplicating a locale can serve the following purposes: +.IP \[bu] 3 +To create a copy of a locale object in which one of more categories +are to be modified (using +.BR newlocale (3)). +.IP \[bu] +To obtain a handle for the current locale which can used in +other functions that employ a locale handle, such as +.BR toupper_l (3). +This is done by applying +.BR duplocale () +to the value returned by the following call: +.IP +.in +4n +.EX +loc = uselocale((locale_t) 0); +.EE +.in +.IP +This technique is necessary, because the above +.BR uselocale (3) +call may return the value +.BR LC_GLOBAL_LOCALE , +which results in undefined behavior if passed to functions such as +.BR toupper_l (3). +Calling +.BR duplocale () +can be used to ensure that the +.B LC_GLOBAL_LOCALE +value is converted into a usable locale object. +See EXAMPLES, below. +.P +Each locale object created by +.BR duplocale () +should be deallocated using +.BR freelocale (3). +.SH EXAMPLES +The program below uses +.BR uselocale (3) +and +.BR duplocale () +to obtain a handle for the current locale which is then passed to +.BR toupper_l (3). +The program takes one command-line argument, +a string of characters that is converted to uppercase and +displayed on standard output. +An example of its use is the following: +.P +.in +4n +.EX +$ \fB./a.out abc\fP +ABC +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (duplocale.c) +.EX +#define _XOPEN_SOURCE 700 +#include +#include +#include +#include +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + locale_t loc, nloc; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s string\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* This sequence is necessary, because uselocale() might return + the value LC_GLOBAL_LOCALE, which can\[aq]t be passed as an + argument to toupper_l(). */ +\& + loc = uselocale((locale_t) 0); + if (loc == (locale_t) 0) + errExit("uselocale"); +\& + nloc = duplocale(loc); + if (nloc == (locale_t) 0) + errExit("duplocale"); +\& + for (char *p = argv[1]; *p; p++) + putchar(toupper_l(*p, nloc)); +\& + printf("\en"); +\& + freelocale(nloc); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR freelocale (3), +.BR newlocale (3), +.BR setlocale (3), +.BR uselocale (3), +.BR locale (5), +.BR locale (7) diff --git a/man/man3/dysize.3 b/man/man3/dysize.3 new file mode 100644 index 0000000..40c7410 --- /dev/null +++ b/man/man3/dysize.3 @@ -0,0 +1,69 @@ +'\" t +.\" Copyright 2001 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" aeb: some corrections +.TH dysize 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dysize \- get number of days for a given year +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int dysize(int " year ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR dysize (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The function returns 365 for a normal year and 366 for a leap year. +The calculation for leap year is based on: +.P +.in +4n +.EX +(year) %4 == 0 && ((year) %100 != 0 || (year) %400 == 0) +.EE +.in +.P +The formula is defined in the macro +.I __isleap(year) +also found in +.IR . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR dysize () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +SunOS 4.x. +.P +This is a compatibility function only. +Don't use it in new programs. +.\" The SCO version of this function had a year-2000 problem. +.SH SEE ALSO +.BR strftime (3) diff --git a/man/man3/eaccess.3 b/man/man3/eaccess.3 new file mode 100644 index 0000000..9e50351 --- /dev/null +++ b/man/man3/eaccess.3 @@ -0,0 +1 @@ +.so man3/euidaccess.3 diff --git a/man/man3/ecb_crypt.3 b/man/man3/ecb_crypt.3 new file mode 100644 index 0000000..853c9cb --- /dev/null +++ b/man/man3/ecb_crypt.3 @@ -0,0 +1 @@ +.so man3/des_crypt.3 diff --git a/man/man3/ecvt.3 b/man/man3/ecvt.3 new file mode 100644 index 0000000..539d182 --- /dev/null +++ b/man/man3/ecvt.3 @@ -0,0 +1,133 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:40:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Jun 25 12:10:47 1999 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH ecvt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ecvt, fcvt \- convert a floating-point number to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] char *ecvt(double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign ); +.BI "[[deprecated]] char *fcvt(double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ecvt (), +.BR fcvt (): +.nf + Since glibc 2.17 + (_XOPEN_SOURCE >= 500 && ! (_POSIX_C_SOURCE >= 200809L)) + || /* glibc >= 2.20 */ _DEFAULT_SOURCE + || /* glibc <= 2.19 */ _SVID_SOURCE + glibc 2.12 to glibc 2.16: + (_XOPEN_SOURCE >= 500 && ! (_POSIX_C_SOURCE >= 200112L)) + || _SVID_SOURCE + Before glibc 2.12: + _SVID_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +The +.BR ecvt () +function converts \fInumber\fP to a null-terminated +string of \fIndigits\fP digits (where \fIndigits\fP is reduced to a +system-specific limit determined by the precision of a +.IR double ), +and returns a pointer to the string. +The high-order digit is nonzero, unless +.I number +is zero. +The low order digit is rounded. +The string itself does not contain a decimal point; however, +the position of the decimal point relative to the start of the string +is stored in \fI*decpt\fP. +A negative value for \fI*decpt\fP means that +the decimal point is to the left of the start of the string. +If the sign of +\fInumber\fP is negative, \fI*sign\fP is set to a nonzero value, +otherwise it is set to 0. +If +.I number +is zero, it is unspecified whether \fI*decpt\fP is 0 or 1. +.P +The +.BR fcvt () +function is identical to +.BR ecvt (), +except that +\fIndigits\fP specifies the number of digits after the decimal point. +.SH RETURN VALUE +Both the +.BR ecvt () +and +.BR fcvt () +functions return a pointer to a +static string containing the ASCII representation of \fInumber\fP. +The static string is overwritten by each call to +.BR ecvt () +or +.BR fcvt (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ecvt () +T} Thread safety MT-Unsafe race:ecvt +T{ +.na +.nh +.BR fcvt () +T} Thread safety MT-Unsafe race:fcvt +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr2; +marked as LEGACY in POSIX.1-2001. +POSIX.1-2008 removes the specifications of +.BR ecvt () +and +.BR fcvt (), +recommending the use of +.BR sprintf (3) +instead (though +.BR snprintf (3) +may be preferable). +.SH NOTES +.\" Linux libc4 and libc5 specified the type of +.\" .I ndigits +.\" as +.\" .IR size_t . +Not all locales use a point as the radix character ("decimal point"). +.SH SEE ALSO +.BR ecvt_r (3), +.BR gcvt (3), +.BR qecvt (3), +.BR setlocale (3), +.BR sprintf (3) diff --git a/man/man3/ecvt_r.3 b/man/man3/ecvt_r.3 new file mode 100644 index 0000000..4f83f65 --- /dev/null +++ b/man/man3/ecvt_r.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.\" Corrected return types; from Fabian; 2004-10-05 +.\" +.TH ecvt_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ecvt_r, fcvt_r, qecvt_r, qfcvt_r \- convert a floating-point number to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int ecvt_r(double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign , +.BI " char *restrict " buf ", size_t " len ); +.BI "[[deprecated]] int fcvt_r(double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign , +.BI " char *restrict " buf ", size_t " len ); +.P +.BI "[[deprecated]] int qecvt_r(long double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign , +.BI " char *restrict " buf ", size_t " len ); +.BI "[[deprecated]] int qfcvt_r(long double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign , +.BI " char *restrict " buf ", size_t " len ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ecvt_r (), +.BR fcvt_r (), +.BR qecvt_r (), +.BR qfcvt_r (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR ecvt_r (), +.BR fcvt_r (), +.BR qecvt_r (), +and +.BR qfcvt_r () +are identical to +.BR ecvt (3), +.BR fcvt (3), +.BR qecvt (3), +and +.BR qfcvt (3), +respectively, except that they do not return their result in a static +buffer, but instead use the supplied +.I buf +of size +.IR len . +See +.BR ecvt (3) +and +.BR qecvt (3). +.SH RETURN VALUE +These functions return 0 on success, and \-1 otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ecvt_r (), +.BR fcvt_r (), +.BR qecvt_r (), +.BR qfcvt_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH NOTES +These functions are obsolete. +Instead, +.BR sprintf (3) +is recommended. +.SH SEE ALSO +.BR ecvt (3), +.BR qecvt (3), +.BR sprintf (3) diff --git a/man/man3/edata.3 b/man/man3/edata.3 new file mode 100644 index 0000000..94843fb --- /dev/null +++ b/man/man3/edata.3 @@ -0,0 +1 @@ +.so man3/end.3 diff --git a/man/man3/encrypt.3 b/man/man3/encrypt.3 new file mode 100644 index 0000000..10ec9ec --- /dev/null +++ b/man/man3/encrypt.3 @@ -0,0 +1,211 @@ +'\" t +.\" Copyright 2000 Nicolás Lichtmaier +.\" Created 2000-07-22 00:52-0300 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 2002-07-23 19:21:35 CEST 2002 Walter Harms +.\" +.\" +.\" Modified 2003-04-04, aeb +.\" +.TH encrypt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +encrypt, setkey, encrypt_r, setkey_r \- encrypt 64-bit messages +.SH LIBRARY +Password hashing library +.RI ( libcrypt ", " \-lcrypt ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "[[deprecated]] void encrypt(char " block "[64], int " edflag ); +.P +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "[[deprecated]] void setkey(const char *" key ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "[[deprecated]] void setkey_r(const char *" key ", struct crypt_data *" data ); +.BI "[[deprecated]] void encrypt_r(char *" block ", int " edflag , +.BI " struct crypt_data *" data ); +.fi +.SH DESCRIPTION +These functions encrypt and decrypt 64-bit messages. +The +.BR setkey () +function sets the key used by +.BR encrypt (). +The +.I key +argument used here is an array of 64 bytes, each of which has +numerical value 1 or 0. +The bytes key[n] where n=8*i-1 are ignored, +so that the effective key length is 56 bits. +.P +The +.BR encrypt () +function modifies the passed buffer, encoding if +.I edflag +is 0, and decoding if 1 is being passed. +Like the +.I key +argument, also +.I block +is a bit vector representation of the actual value that is encoded. +The result is returned in that same vector. +.P +These two functions are not reentrant, that is, the key data is +kept in static storage. +The functions +.BR setkey_r () +and +.BR encrypt_r () +are the reentrant versions. +They use the following +structure to hold the key data: +.P +.in +4n +.EX +struct crypt_data { + char keysched[16 * 8]; + char sb0[32768]; + char sb1[32768]; + char sb2[32768]; + char sb3[32768]; + char crypt_3_buf[14]; + char current_salt[2]; + long current_saltbits; + int direction; + int initialized; +}; +.EE +.in +.P +Before calling +.BR setkey_r () +set +.I data\->initialized +to zero. +.SH RETURN VALUE +These functions do not return any value. +.SH ERRORS +Set +.I errno +to zero before calling the above functions. +On success, +.I errno +is unchanged. +.TP +.B ENOSYS +The function is not provided. +(For example because of former USA export restrictions.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR encrypt (), +.BR setkey () +T} Thread safety MT-Unsafe race:crypt +T{ +.na +.nh +.BR encrypt_r (), +.BR setkey_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR encrypt () +.TQ +.BR setkey () +POSIX.1-2008. +.TP +.BR encrypt_r () +.TQ +.BR setkey_r () +None. +.SH HISTORY +Removed in glibc 2.28. +.P +Because they employ the DES block cipher, +which is no longer considered secure, +these functions were removed from glibc. +Applications should switch to a modern cryptography library, such as +.BR libgcrypt . +.TP +.BR encrypt () +.TQ +.BR setkey () +POSIX.1-2001, SUS, SVr4. +.SS Availability in glibc +See +.BR crypt (3). +.SS Features in glibc +In glibc 2.2, these functions use the DES algorithm. +.SH EXAMPLES +.\" SRC BEGIN (encrypt.c) +.EX +#define _XOPEN_SOURCE +#include +#include +#include +#include +\& +int +main(void) +{ + char key[64]; + char orig[9] = "eggplant"; + char buf[64]; + char txt[9]; +\& + for (size_t i = 0; i < 64; i++) { + key[i] = rand() & 1; + } +\& + for (size_t i = 0; i < 8; i++) { + for (size_t j = 0; j < 8; j++) { + buf[i * 8 + j] = orig[i] >> j & 1; + } + setkey(key); + } + printf("Before encrypting: %s\en", orig); +\& + encrypt(buf, 0); + for (size_t i = 0; i < 8; i++) { + for (size_t j = 0, txt[i] = \[aq]\e0\[aq]; j < 8; j++) { + txt[i] |= buf[i * 8 + j] << j; + } + txt[8] = \[aq]\e0\[aq]; + } + printf("After encrypting: %s\en", txt); +\& + encrypt(buf, 1); + for (size_t i = 0; i < 8; i++) { + for (size_t j = 0, txt[i] = \[aq]\e0\[aq]; j < 8; j++) { + txt[i] |= buf[i * 8 + j] << j; + } + txt[8] = \[aq]\e0\[aq]; + } + printf("After decrypting: %s\en", txt); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR cbc_crypt (3), +.BR crypt (3), +.BR ecb_crypt (3) +.\" .BR fcrypt (3) diff --git a/man/man3/encrypt_r.3 b/man/man3/encrypt_r.3 new file mode 100644 index 0000000..e34c9e9 --- /dev/null +++ b/man/man3/encrypt_r.3 @@ -0,0 +1 @@ +.so man3/encrypt.3 diff --git a/man/man3/end.3 b/man/man3/end.3 new file mode 100644 index 0000000..3628107 --- /dev/null +++ b/man/man3/end.3 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH end 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +etext, edata, end \- end of program segments +.SH SYNOPSIS +.nf +.BI extern " etext" ; +.BI extern " edata" ; +.BI extern " end" ; +.fi +.SH DESCRIPTION +The addresses of these symbols indicate the end of various program +segments: +.TP +.I etext +This is the first address past the end of the text segment +(the program code). +.TP +.I edata +This is the first address past the end of the +initialized data segment. +.TP +.I end +This is the first address past the end of the +uninitialized data segment (also known as the BSS segment). +.SH STANDARDS +None. +.SH HISTORY +Although these symbols have long been provided on most UNIX systems, +they are not standardized; use with caution. +.SH NOTES +The program must explicitly declare these symbols; +they are not defined in any header file. +.P +On some systems the names of these symbols are preceded by underscores, +thus: +.IR _etext , +.IR _edata , +and +.IR _end . +These symbols are also defined for programs compiled on Linux. +.P +At the start of program execution, +the program break will be somewhere near +.I &end +(perhaps at the start of the following page). +However, the break will change as memory is allocated via +.BR brk (2) +or +.BR malloc (3). +Use +.BR sbrk (2) +with an argument of zero to find the current value of the program break. +.SH EXAMPLES +When run, the program below produces output such as the following: +.P +.in +4n +.EX +.RB "$" " ./a.out" +First address past: + program text (etext) 0x8048568 + initialized data (edata) 0x804a01c + uninitialized data (end) 0x804a024 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (end.c) +.EX +#include +#include +\& +extern char etext, edata, end; /* The symbols must have some type, + or "gcc \-Wall" complains */ +\& +int +main(void) +{ + printf("First address past:\en"); + printf(" program text (etext) %10p\en", &etext); + printf(" initialized data (edata) %10p\en", &edata); + printf(" uninitialized data (end) %10p\en", &end); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR objdump (1), +.BR readelf (1), +.BR sbrk (2), +.BR elf (5) diff --git a/man/man3/endaliasent.3 b/man/man3/endaliasent.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man/man3/endaliasent.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man/man3/endfsent.3 b/man/man3/endfsent.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man/man3/endfsent.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man/man3/endgrent.3 b/man/man3/endgrent.3 new file mode 100644 index 0000000..bde736f --- /dev/null +++ b/man/man3/endgrent.3 @@ -0,0 +1 @@ +.so man3/getgrent.3 diff --git a/man/man3/endhostent.3 b/man/man3/endhostent.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/endhostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/endian.3 b/man/man3/endian.3 new file mode 100644 index 0000000..7ff7053 --- /dev/null +++ b/man/man3/endian.3 @@ -0,0 +1,164 @@ +.\" Copyright (C) 2009, Linux Foundation, written by Michael Kerrisk +.\" +.\" a few pieces remain from an earlier version +.\" Copyright (C) 2008, Nanno Langstraat +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH endian 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +htobe16, htole16, be16toh, le16toh, htobe32, htole32, be32toh, le32toh, +htobe64, htole64, be64toh, le64toh \- +convert values between host and big-/little-endian byte order +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "uint16_t htobe16(uint16_t " host_16bits ); +.BI "uint16_t htole16(uint16_t " host_16bits ); +.BI "uint16_t be16toh(uint16_t " big_endian_16bits ); +.BI "uint16_t le16toh(uint16_t " little_endian_16bits ); +.P +.BI "uint32_t htobe32(uint32_t " host_32bits ); +.BI "uint32_t htole32(uint32_t " host_32bits ); +.BI "uint32_t be32toh(uint32_t " big_endian_32bits ); +.BI "uint32_t le32toh(uint32_t " little_endian_32bits ); +.P +.BI "uint64_t htobe64(uint64_t " host_64bits ); +.BI "uint64_t htole64(uint64_t " host_64bits ); +.BI "uint64_t be64toh(uint64_t " big_endian_64bits ); +.BI "uint64_t le64toh(uint64_t " little_endian_64bits ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.ad l +.P +.BR htobe16 (), +.BR htole16 (), +.BR be16toh (), +.BR le16toh (), +.BR htobe32 (), +.BR htole32 (), +.BR be32toh (), +.BR le32toh (), +.BR htobe64 (), +.BR htole64 (), +.BR be64toh (), +.BR le64toh (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE +.fi +.ad +.SH DESCRIPTION +These functions convert the byte encoding of integer values from +the byte order that the current CPU (the "host") uses, +to and from little-endian and big-endian byte order. +.P +The number, +.IR nn , +in the name of each function indicates the size of +integer handled by the function, either 16, 32, or 64 bits. +.P +The functions with names of the form "htobe\fInn\fP" convert +from host byte order to big-endian order. +.P +The functions with names of the form "htole\fInn\fP" convert +from host byte order to little-endian order. +.P +The functions with names of the form "be\fInn\fPtoh" convert +from big-endian order to host byte order. +.P +The functions with names of the form "le\fInn\fPtoh" convert +from little-endian order to host byte order. +.SH VERSIONS +Similar functions are present on the BSDs, +where the required header file is +.I +instead of +.IR . +Unfortunately, +NetBSD, FreeBSD, and glibc haven't followed the original +OpenBSD naming convention for these functions, +whereby the +.I nn +component always appears at the end of the function name +(thus, for example, in NetBSD, FreeBSD, and glibc, +the equivalent of OpenBSDs "betoh32" is "be32toh"). +.SH STANDARDS +None. +.SH HISTORY +glibc 2.9. +.P +These functions are similar to the older +.BR byteorder (3) +family of functions. +For example, +.BR be32toh () +is identical to +.BR ntohl (). +.P +The advantage of the +.BR byteorder (3) +functions is that they are standard functions available +on all UNIX systems. +On the other hand, the fact that they were designed +for use in the context of TCP/IP means that +they lack the 64-bit and little-endian variants described in this page. +.SH EXAMPLES +The program below display the results of converting an integer +from host byte order to both little-endian and big-endian byte order. +Since host byte order is either little-endian or big-endian, +only one of these conversions will have an effect. +When we run this program on a little-endian system such as x86-32, +we see the following: +.P +.in +4n +.EX +$ \fB./a.out\fP +x.u32 = 0x44332211 +htole32(x.u32) = 0x44332211 +htobe32(x.u32) = 0x11223344 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (endian.c) +.EX +#include +#include +#include +#include +\& +int +main(void) +{ + union { + uint32_t u32; + uint8_t arr[4]; + } x; +\& + x.arr[0] = 0x11; /* Lowest\-address byte */ + x.arr[1] = 0x22; + x.arr[2] = 0x33; + x.arr[3] = 0x44; /* Highest\-address byte */ +\& + printf("x.u32 = %#x\en", x.u32); + printf("htole32(x.u32) = %#x\en", htole32(x.u32)); + printf("htobe32(x.u32) = %#x\en", htobe32(x.u32)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR bswap (3), +.BR byteorder (3) diff --git a/man/man3/endmntent.3 b/man/man3/endmntent.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man/man3/endmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man/man3/endnetent.3 b/man/man3/endnetent.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man/man3/endnetent.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man/man3/endnetgrent.3 b/man/man3/endnetgrent.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man/man3/endnetgrent.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man/man3/endprotoent.3 b/man/man3/endprotoent.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man/man3/endprotoent.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man/man3/endpwent.3 b/man/man3/endpwent.3 new file mode 100644 index 0000000..f2d121b --- /dev/null +++ b/man/man3/endpwent.3 @@ -0,0 +1 @@ +.so man3/getpwent.3 diff --git a/man/man3/endrpcent.3 b/man/man3/endrpcent.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man/man3/endrpcent.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man/man3/endservent.3 b/man/man3/endservent.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man/man3/endservent.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man/man3/endspent.3 b/man/man3/endspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/endspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/endttyent.3 b/man/man3/endttyent.3 new file mode 100644 index 0000000..1cd11e3 --- /dev/null +++ b/man/man3/endttyent.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man/man3/endusershell.3 b/man/man3/endusershell.3 new file mode 100644 index 0000000..718ed12 --- /dev/null +++ b/man/man3/endusershell.3 @@ -0,0 +1 @@ +.so man3/getusershell.3 diff --git a/man/man3/endutent.3 b/man/man3/endutent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/endutent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/endutxent.3 b/man/man3/endutxent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/endutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/envz.3 b/man/man3/envz.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/envz_add.3 b/man/man3/envz_add.3 new file mode 100644 index 0000000..888fc07 --- /dev/null +++ b/man/man3/envz_add.3 @@ -0,0 +1,168 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" based on the description in glibc source and infopages +.\" +.\" Corrections and additions, aeb +.TH envz_add 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +envz_add, envz_entry, envz_get, envz_merge, +envz_remove, envz_strip \- environment string support +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len , +.BI " const char *restrict " name \ +", const char *restrict " value ); +.P +.BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len , +.BI " const char *restrict " name ); +.P +.BI "char *envz_get(const char *restrict " envz ", size_t " envz_len , +.BI " const char *restrict " name ); +.P +.BI "error_t envz_merge(char **restrict " envz ", size_t *restrict " envz_len , +.BI " const char *restrict " envz2 ", size_t " envz2_len , +.BI " int " override ); +.P +.BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len , +.BI " const char *restrict " name ); +.P +.BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len ); +.fi +.SH DESCRIPTION +These functions are glibc-specific. +.P +An argz vector is a pointer to a character buffer together with a length, +see +.BR argz_add (3). +An envz vector is a special argz vector, namely one where the strings +have the form "name=value". +Everything after the first \[aq]=\[aq] is considered +to be the value. +If there is no \[aq]=\[aq], the value is taken to be NULL. +(While the value in case of a trailing \[aq]=\[aq] is the empty string "".) +.P +These functions are for handling envz vectors. +.P +.BR envz_add () +adds the string +.RI \&" name = value \&" +(in case +.I value +is non-NULL) or +.RI \&" name \&" +(in case +.I value +is NULL) to the envz vector +.RI ( *envz ,\ *envz_len ) +and updates +.I *envz +and +.IR *envz_len . +If an entry with the same +.I name +existed, it is removed. +.P +.BR envz_entry () +looks for +.I name +in the envz vector +.RI ( envz ,\ envz_len ) +and returns the entry if found, or NULL if not. +.P +.BR envz_get () +looks for +.I name +in the envz vector +.RI ( envz ,\ envz_len ) +and returns the value if found, or NULL if not. +(Note that the value can also be NULL, namely when there is +an entry for +.I name +without \[aq]=\[aq] sign.) +.P +.BR envz_merge () +adds each entry in +.I envz2 +to +.IR *envz , +as if with +.BR envz_add (). +If +.I override +is true, then values in +.I envz2 +will supersede those with the same name in +.IR *envz , +otherwise not. +.P +.BR envz_remove () +removes the entry for +.I name +from +.RI ( *envz ,\ *envz_len ) +if there was one. +.P +.BR envz_strip () +removes all entries with value NULL. +.SH RETURN VALUE +All envz functions that do memory allocation have a return type of +.I error_t +(an integer type), +and return 0 for success, and +.B ENOMEM +if an allocation error occurs. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR envz_add (), +.BR envz_entry (), +.BR envz_get (), +.BR envz_merge (), +.BR envz_remove (), +.BR envz_strip () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH EXAMPLES +.\" SRC BEGIN (envz_add.c) +.EX +#include +#include +#include +\& +int +main(int argc, char *argv[], char *envp[]) +{ + char *str; + size_t e_len = 0; +\& + for (size_t i = 0; envp[i] != NULL; i++) + e_len += strlen(envp[i]) + 1; +\& + str = envz_entry(*envp, e_len, "HOME"); + printf("%s\en", str); + str = envz_get(*envp, e_len, "HOME"); + printf("%s\en", str); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR argz_add (3) diff --git a/man/man3/envz_entry.3 b/man/man3/envz_entry.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz_entry.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/envz_get.3 b/man/man3/envz_get.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz_get.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/envz_merge.3 b/man/man3/envz_merge.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz_merge.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/envz_remove.3 b/man/man3/envz_remove.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz_remove.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/envz_strip.3 b/man/man3/envz_strip.3 new file mode 100644 index 0000000..12e0737 --- /dev/null +++ b/man/man3/envz_strip.3 @@ -0,0 +1 @@ +.so man3/envz_add.3 diff --git a/man/man3/erand48.3 b/man/man3/erand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/erand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/erand48_r.3 b/man/man3/erand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/erand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/erf.3 b/man/man3/erf.3 new file mode 100644 index 0000000..3cdfb0a --- /dev/null +++ b/man/man3/erf.3 @@ -0,0 +1,131 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH erf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +erf, erff, erfl \- error function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double erf(double " x ); +.BI "float erff(float " x ); +.BI "long double erfl(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR erf (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR erff (), +.BR erfl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the error function of +.IR x , +defined as +.P +.in +4n +.EX +erf(x) = 2/sqrt(pi) * integral from 0 to x of exp(\-t*t) dt +.EE +.in +.SH RETURN VALUE +On success, these functions return the value of the error function of +.IR x , +a value in the range [\-1,\ 1]. +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is positive infinity (negative infinity), ++1 (\-1) is returned. +.P +If +.I x +is subnormal, +a range error occurs, +and the return value is 2*x/sqrt(pi). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result underflow (\fIx\fP is subnormal) +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.P +These functions do not set +.IR errno . +.\" It is intentional that these functions do not set errno for this case +.\" see https://www.sourceware.org/bugzilla/show_bug.cgi?id=6785 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR erf (), +.BR erff (), +.BR erfl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cerf (3), +.BR erfc (3), +.BR exp (3) diff --git a/man/man3/erfc.3 b/man/man3/erfc.3 new file mode 100644 index 0000000..70bdd7a --- /dev/null +++ b/man/man3/erfc.3 @@ -0,0 +1,134 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH erfc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +erfc, erfcf, erfcl \- complementary error function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double erfc(double " x ); +.BI "float erfcf(float " x ); +.BI "long double erfcl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR erfc (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR erfcf (), +.BR erfcl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the complementary error function of +.IR x , +that is, 1.0 \- erf(x). +.SH RETURN VALUE +On success, these functions return the complementary error function of +.IR x , +a value in the range [0,2]. +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 or \-0, 1 is returned. +.P +If +.I x +is positive infinity, ++0 is returned. +.P +If +.I x +is negative infinity, ++2 is returned. +.P +If the function result underflows and produces an unrepresentable value, +the return value is 0.0. +.P +If the function result underflows but produces a representable +(i.e., subnormal) value, +.\" e.g., erfc(27) on x86-32 +that value is returned, and +a range error occurs. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result underflow (result is subnormal) +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.P +These functions do not set +.IR errno . +.\" It is intentional that these functions do not set errno for this case +.\" see https://www.sourceware.org/bugzilla/show_bug.cgi?id=6785 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR erfc (), +.BR erfcf (), +.BR erfcl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH NOTES +The +.BR erfc (), +.BR erfcf (), +and +.BR erfcl () +functions are provided to avoid the loss accuracy that +would occur for the calculation 1-erf(x) for large values of +.I x +(for which the value of erf(x) approaches 1). +.SH SEE ALSO +.BR cerf (3), +.BR erf (3), +.BR exp (3) diff --git a/man/man3/erfcf.3 b/man/man3/erfcf.3 new file mode 100644 index 0000000..371bd6b --- /dev/null +++ b/man/man3/erfcf.3 @@ -0,0 +1 @@ +.so man3/erfc.3 diff --git a/man/man3/erfcl.3 b/man/man3/erfcl.3 new file mode 100644 index 0000000..371bd6b --- /dev/null +++ b/man/man3/erfcl.3 @@ -0,0 +1 @@ +.so man3/erfc.3 diff --git a/man/man3/erff.3 b/man/man3/erff.3 new file mode 100644 index 0000000..fc5471f --- /dev/null +++ b/man/man3/erff.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man/man3/erfl.3 b/man/man3/erfl.3 new file mode 100644 index 0000000..fc5471f --- /dev/null +++ b/man/man3/erfl.3 @@ -0,0 +1 @@ +.so man3/erf.3 diff --git a/man/man3/err.3 b/man/man3/err.3 new file mode 100644 index 0000000..3db6703 --- /dev/null +++ b/man/man3/err.3 @@ -0,0 +1,154 @@ +'\" t +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" From: @(#)err.3 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD: src/lib/libc/gen/err.3,v 1.11.2.5 2001/08/17 15:42:32 ru Exp $ +.\" +.\" 2011-09-10, mtk, Converted from mdoc to man macros +.\" +.TH err 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[noreturn]] void err(int " eval ", const char *" fmt ", ...);" +.BI "[[noreturn]] void errx(int " eval ", const char *" fmt ", ...);" +.P +.BI "void warn(const char *" fmt ", ...);" +.BI "void warnx(const char *" fmt ", ...);" +.P +.B #include +.P +.BI "[[noreturn]] void verr(int " eval ", const char *" fmt ", va_list " args ); +.BI "[[noreturn]] void verrx(int " eval ", const char *" fmt ", va_list " args ); +.P +.BI "void vwarn(const char *" fmt ", va_list " args ); +.BI "void vwarnx(const char *" fmt ", va_list " args ); +.fi +.SH DESCRIPTION +The +.BR err () +and +.BR warn () +family of functions display a formatted error message on the standard +error output. +In all cases, the last component of the program name, a colon character, +and a space are output. +If the +.I fmt +argument is not NULL, the +.BR printf (3)-like +formatted error message is output. +The output is terminated by a newline character. +.P +The +.BR err (), +.BR verr (), +.BR warn (), +and +.BR vwarn () +functions append an error message obtained from +.BR strerror (3) +based on the global variable +.IR errno , +preceded by another colon and space unless the +.I fmt +argument is +NULL. +.P +The +.BR errx () +and +.BR warnx () +functions do not append an error message. +.P +The +.BR err (), +.BR verr (), +.BR errx (), +and +.BR verrx () +functions do not return, but exit with the value of the argument +.IR eval . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR err (), +.BR errx (), +.BR warn (), +.BR warnx (), +.BR verr (), +.BR verrx (), +.BR vwarn (), +.BR vwarnx () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +BSD. +.SH HISTORY +.TP +.BR err () +.TQ +.BR warn () +4.4BSD. +.SH EXAMPLES +Display the current +.I errno +information string and exit: +.P +.in +4n +.EX +p = malloc(size); +if (p == NULL) + err(EXIT_FAILURE, NULL); +fd = open(file_name, O_RDONLY, 0); +if (fd == \-1) + err(EXIT_FAILURE, "%s", file_name); +.EE +.in +.P +Display an error message and exit: +.P +.in +4n +.EX +if (tm.tm_hour < START_TIME) + errx(EXIT_FAILURE, "too early, wait until %s", + start_time_string); +.EE +.in +.P +Warn of an error: +.P +.in +4n +.EX +fd = open(raw_device, O_RDONLY, 0); +if (fd == \-1) + warnx("%s: %s: trying the block device", + raw_device, strerror(errno)); +fd = open(block_device, O_RDONLY, 0); +if (fd == \-1) + err(EXIT_FAILURE, "%s", block_device); +.EE +.in +.SH SEE ALSO +.BR error (3), +.BR exit (3), +.BR perror (3), +.BR printf (3), +.BR strerror (3) diff --git a/man/man3/errno.3 b/man/man3/errno.3 new file mode 100644 index 0000000..72185eb --- /dev/null +++ b/man/man3/errno.3 @@ -0,0 +1,655 @@ +.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 5 Oct 2002, Modified by Michael Kerrisk +.\" Updated for POSIX.1 2001 +.\" 2004-12-17 Martin Schulze , mtk +.\" Removed errno declaration prototype, added notes +.\" 2006-02-09 Kurt Wall, mtk +.\" Added non-POSIX errors +.\" +.TH errno 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +errno \- number of last error +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.\".P +.\".BI "extern int " errno ; +.fi +.SH DESCRIPTION +The +.I +header file defines the integer variable +.IR errno , +which is set by system calls and some library functions in the event +of an error to indicate what went wrong. +.\" +.SS errno +The value in +.I errno +is significant only when the return value of +the call indicated an error +(i.e., \-1 from most system calls; +\-1 or NULL from most library functions); +a function that succeeds +.I is +allowed to change +.IR errno . +The value of +.I errno +is never set to zero by any system call or library function. +.P +For some system calls and library functions (e.g., +.BR getpriority (2)), +\-1 is a valid return on success. +In such cases, a successful return can be distinguished from an error +return by setting +.I errno +to zero before the call, and then, +if the call returns a status that indicates that an error +may have occurred, checking to see if +.I errno +has a nonzero value. +.P +.I errno +is defined by the ISO C standard to be a modifiable lvalue +of type +.IR int , +and must not be explicitly declared; +.I errno +may be a macro. +.I errno +is thread-local; setting it in one thread +does not affect its value in any other thread. +.\" +.SS Error numbers and names +Valid error numbers are all positive numbers. +The +.I +header file defines symbolic names for each +of the possible error numbers that may appear in +.IR errno . +.P +All the error names specified by POSIX.1 +must have distinct values, with the exception of +.B EAGAIN +and +.BR EWOULDBLOCK , +which may be the same. +On Linux, these two have the same value on all architectures. +.P +The error numbers that correspond to each symbolic name +vary across UNIX systems, +and even across different architectures on Linux. +Therefore, numeric values are not included as part of the list of +error names below. +The +.BR perror (3) +and +.BR strerror (3) +functions can be used to convert these names to +corresponding textual error messages. +.P +On any particular Linux system, +one can obtain a list of all symbolic error names and +the corresponding error numbers using the +.BR errno (1) +command (part of the +.I moreutils +package): +.P +.in +4n +.EX +$ \fBerrno \-l\fP +EPERM 1 Operation not permitted +ENOENT 2 No such file or directory +ESRCH 3 No such process +EINTR 4 Interrupted system call +EIO 5 Input/output error +\&... +.EE +.in +.P +The +.BR errno (1) +command can also be used to look up individual error numbers and names, +and to search for errors using strings from the error description, +as in the following examples: +.P +.in +4n +.EX +$ \fBerrno 2\fP +ENOENT 2 No such file or directory +$ \fBerrno ESRCH\fP +ESRCH 3 No such process +$ \fBerrno \-s permission\fP +EACCES 13 Permission denied +.EE +.in +.\".P +.\" POSIX.1 (2001 edition) lists the following symbolic error names. Of +.\" these, \fBEDOM\fP and \fBERANGE\fP are in the ISO C standard. ISO C +.\" Amendment 1 defines the additional error number \fBEILSEQ\fP for +.\" coding errors in multibyte or wide characters. +.\" +.SS List of error names +In the list of the symbolic error names below, +various names are marked as follows: +.TP +.I POSIX.1-2001 +The name is defined by POSIX.1-2001, +and is defined in later POSIX.1 versions, unless otherwise indicated. +.TP +.I POSIX.1-2008 +The name is defined in POSIX.1-2008, +but was not present in earlier POSIX.1 standards. +.TP +.I C99 +The name is defined by C99. +.P +Below is a list of the symbolic error names that are defined on Linux: +.TP 16 +.B E2BIG +Argument list too long (POSIX.1-2001). +.TP +.B EACCES +Permission denied (POSIX.1-2001). +.TP +.B EADDRINUSE +Address already in use (POSIX.1-2001). +.TP +.B EADDRNOTAVAIL +Address not available (POSIX.1-2001). +.\" EADV is only an error on HURD(?) +.TP +.B EAFNOSUPPORT +Address family not supported (POSIX.1-2001). +.TP +.B EAGAIN +Resource temporarily unavailable (may be the same value as +.BR EWOULDBLOCK ) +(POSIX.1-2001). +.TP +.B EALREADY +Connection already in progress (POSIX.1-2001). +.TP +.B EBADE +Invalid exchange. +.TP +.B EBADF +Bad file descriptor (POSIX.1-2001). +.TP +.B EBADFD +File descriptor in bad state. +.TP +.B EBADMSG +Bad message (POSIX.1-2001). +.TP +.B EBADR +Invalid request descriptor. +.TP +.B EBADRQC +Invalid request code. +.TP +.B EBADSLT +Invalid slot. +.\" EBFONT is defined but appears not to be used by kernel or glibc. +.TP +.B EBUSY +Device or resource busy (POSIX.1-2001). +.TP +.B ECANCELED +Operation canceled (POSIX.1-2001). +.TP +.B ECHILD +No child processes (POSIX.1-2001). +.TP +.B ECHRNG +Channel number out of range. +.TP +.B ECOMM +Communication error on send. +.TP +.B ECONNABORTED +Connection aborted (POSIX.1-2001). +.TP +.B ECONNREFUSED +Connection refused (POSIX.1-2001). +.TP +.B ECONNRESET +Connection reset (POSIX.1-2001). +.TP +.B EDEADLK +Resource deadlock avoided (POSIX.1-2001). +.TP +.B EDEADLOCK +On most architectures, a synonym for +.BR EDEADLK . +On some architectures (e.g., Linux MIPS, PowerPC, SPARC), +it is a separate error code "File locking deadlock error". +.TP +.B EDESTADDRREQ +Destination address required (POSIX.1-2001). +.TP +.B EDOM +Mathematics argument out of domain of function (POSIX.1, C99). +.\" EDOTDOT is defined but appears to be unused +.TP +.B EDQUOT +.\" POSIX just says "Reserved" +Disk quota exceeded (POSIX.1-2001). +.TP +.B EEXIST +File exists (POSIX.1-2001). +.TP +.B EFAULT +Bad address (POSIX.1-2001). +.TP +.B EFBIG +File too large (POSIX.1-2001). +.TP +.B EHOSTDOWN +Host is down. +.TP +.B EHOSTUNREACH +Host is unreachable (POSIX.1-2001). +.TP +.B EHWPOISON +Memory page has hardware error. +.TP +.B EIDRM +Identifier removed (POSIX.1-2001). +.TP +.B EILSEQ +Invalid or incomplete multibyte or wide character (POSIX.1, C99). +.IP +The text shown here is the glibc error description; +in POSIX.1, this error is described as "Illegal byte sequence". +.TP +.B EINPROGRESS +Operation in progress (POSIX.1-2001). +.TP +.B EINTR +Interrupted function call (POSIX.1-2001); see +.BR signal (7). +.TP +.B EINVAL +Invalid argument (POSIX.1-2001). +.TP +.B EIO +Input/output error (POSIX.1-2001). +.TP +.B EISCONN +Socket is connected (POSIX.1-2001). +.TP +.B EISDIR +Is a directory (POSIX.1-2001). +.TP +.B EISNAM +Is a named type file. +.TP +.B EKEYEXPIRED +Key has expired. +.TP +.B EKEYREJECTED +Key was rejected by service. +.TP +.B EKEYREVOKED +Key has been revoked. +.TP +.B EL2HLT +Level 2 halted. +.TP +.B EL2NSYNC +Level 2 not synchronized. +.TP +.B EL3HLT +Level 3 halted. +.TP +.B EL3RST +Level 3 reset. +.TP +.B ELIBACC +Cannot access a needed shared library. +.TP +.B ELIBBAD +Accessing a corrupted shared library. +.TP +.B ELIBMAX +Attempting to link in too many shared libraries. +.TP +.B ELIBSCN +\&.lib section in a.out corrupted +.TP +.B ELIBEXEC +Cannot exec a shared library directly. +.TP +.B ELNRNG +.\" ELNRNG appears to be used by a few drivers +Link number out of range. +.TP +.B ELOOP +Too many levels of symbolic links (POSIX.1-2001). +.TP +.B EMEDIUMTYPE +Wrong medium type. +.TP +.B EMFILE +Too many open files (POSIX.1-2001). +Commonly caused by exceeding the +.B RLIMIT_NOFILE +resource limit described in +.BR getrlimit (2). +Can also be caused by exceeding the limit specified in +.IR /proc/sys/fs/nr_open . +.TP +.B EMLINK +Too many links (POSIX.1-2001). +.TP +.B EMSGSIZE +Message too long (POSIX.1-2001). +.TP +.B EMULTIHOP +.\" POSIX says "Reserved" +Multihop attempted (POSIX.1-2001). +.TP +.B ENAMETOOLONG +Filename too long (POSIX.1-2001). +.\" ENAVAIL is defined, but appears not to be used +.TP +.B ENETDOWN +Network is down (POSIX.1-2001). +.TP +.B ENETRESET +Connection aborted by network (POSIX.1-2001). +.TP +.B ENETUNREACH +Network unreachable (POSIX.1-2001). +.TP +.B ENFILE +Too many open files in system (POSIX.1-2001). +On Linux, this is probably a result of encountering the +.I /proc/sys/fs/file\-max +limit (see +.BR proc (5)). +.TP +.B ENOANO +.\" ENOANO appears to be used by a few drivers +No anode. +.TP +.B ENOBUFS +No buffer space available (POSIX.1 (XSI STREAMS option)). +.\" ENOCSI is defined but appears to be unused. +.TP +.B ENODATA +The named attribute does not exist, +or the process has no access to this attribute; see +.BR xattr (7). +.IP +In POSIX.1-2001 (XSI STREAMS option), +this error was described as +"No message is available on the STREAM head read queue". +.TP +.B ENODEV +No such device (POSIX.1-2001). +.TP +.B ENOENT +No such file or directory (POSIX.1-2001). +.IP +Typically, this error results when a specified pathname does not exist, +or one of the components in the directory prefix of a pathname does not exist, +or the specified pathname is a dangling symbolic link. +.TP +.B ENOEXEC +Exec format error (POSIX.1-2001). +.TP +.B ENOKEY +Required key not available. +.TP +.B ENOLCK +No locks available (POSIX.1-2001). +.TP +.B ENOLINK +.\" POSIX says "Reserved" +Link has been severed (POSIX.1-2001). +.TP +.B ENOMEDIUM +No medium found. +.TP +.B ENOMEM +Not enough space/cannot allocate memory (POSIX.1-2001). +.TP +.B ENOMSG +No message of the desired type (POSIX.1-2001). +.TP +.B ENONET +Machine is not on the network. +.TP +.B ENOPKG +Package not installed. +.TP +.B ENOPROTOOPT +Protocol not available (POSIX.1-2001). +.TP +.B ENOSPC +No space left on device (POSIX.1-2001). +.TP +.B ENOSR +No STREAM resources (POSIX.1 (XSI STREAMS option)). +.TP +.B ENOSTR +Not a STREAM (POSIX.1 (XSI STREAMS option)). +.TP +.B ENOSYS +Function not implemented (POSIX.1-2001). +.TP +.B ENOTBLK +Block device required. +.TP +.B ENOTCONN +The socket is not connected (POSIX.1-2001). +.TP +.B ENOTDIR +Not a directory (POSIX.1-2001). +.TP +.B ENOTEMPTY +Directory not empty (POSIX.1-2001). +.\" ENOTNAM is defined but appears to be unused. +.TP +.B ENOTRECOVERABLE +State not recoverable (POSIX.1-2008). +.TP +.B ENOTSOCK +Not a socket (POSIX.1-2001). +.TP +.B ENOTSUP +Operation not supported (POSIX.1-2001). +.TP +.B ENOTTY +Inappropriate I/O control operation (POSIX.1-2001). +.TP +.B ENOTUNIQ +Name not unique on network. +.TP +.B ENXIO +No such device or address (POSIX.1-2001). +.TP +.B EOPNOTSUPP +Operation not supported on socket (POSIX.1-2001). +.IP +.RB ( ENOTSUP +and +.B EOPNOTSUPP +have the same value on Linux, but +according to POSIX.1 these error values should be distinct.) +.TP +.B EOVERFLOW +Value too large to be stored in data type (POSIX.1-2001). +.TP +.B EOWNERDEAD +.\" Used at least by the user-space side of rubost mutexes +Owner died (POSIX.1-2008). +.TP +.B EPERM +Operation not permitted (POSIX.1-2001). +.TP +.B EPFNOSUPPORT +Protocol family not supported. +.TP +.B EPIPE +Broken pipe (POSIX.1-2001). +.TP +.B EPROTO +Protocol error (POSIX.1-2001). +.TP +.B EPROTONOSUPPORT +Protocol not supported (POSIX.1-2001). +.TP +.B EPROTOTYPE +Protocol wrong type for socket (POSIX.1-2001). +.TP +.B ERANGE +Result too large (POSIX.1, C99). +.TP +.B EREMCHG +Remote address changed. +.TP +.B EREMOTE +Object is remote. +.TP +.B EREMOTEIO +Remote I/O error. +.TP +.B ERESTART +Interrupted system call should be restarted. +.TP +.B ERFKILL +.\" ERFKILL appears to be used by various drivers +Operation not possible due to RF-kill. +.TP +.B EROFS +Read-only filesystem (POSIX.1-2001). +.TP +.B ESHUTDOWN +Cannot send after transport endpoint shutdown. +.TP +.B ESPIPE +Invalid seek (POSIX.1-2001). +.TP +.B ESOCKTNOSUPPORT +Socket type not supported. +.TP +.B ESRCH +No such process (POSIX.1-2001). +.\" ESRMNT is defined but appears not to be used +.TP +.B ESTALE +Stale file handle (POSIX.1-2001). +.IP +This error can occur for NFS and for other filesystems. +.TP +.B ESTRPIPE +Streams pipe error. +.TP +.B ETIME +Timer expired +(POSIX.1 (XSI STREAMS option)). +.IP +(POSIX.1 says "STREAM +.BR ioctl (2) +timeout".) +.TP +.B ETIMEDOUT +Connection timed out (POSIX.1-2001). +.TP +.B ETOOMANYREFS +.\" ETOOMANYREFS seems to be used in net/unix/af_unix.c +Too many references: cannot splice. +.TP +.B ETXTBSY +Text file busy (POSIX.1-2001). +.TP +.B EUCLEAN +Structure needs cleaning. +.TP +.B EUNATCH +Protocol driver not attached. +.TP +.B EUSERS +Too many users. +.TP +.B EWOULDBLOCK +Operation would block (may be same value as +.BR EAGAIN ) +(POSIX.1-2001). +.TP +.B EXDEV +Invalid cross-device link (POSIX.1-2001). +.TP +.B EXFULL +Exchange full. +.SH NOTES +A common mistake is to do +.P +.in +4n +.EX +if (somecall() == \-1) { + printf("somecall() failed\en"); + if (errno == ...) { ... } +} +.EE +.in +.P +where +.I errno +no longer needs to have the value it had upon return from +.IR somecall () +(i.e., it may have been changed by the +.BR printf (3)). +If the value of +.I errno +should be preserved across a library call, it must be saved: +.P +.in +4n +.EX +if (somecall() == \-1) { + int errsv = errno; + printf("somecall() failed\en"); + if (errsv == ...) { ... } +} +.EE +.in +.P +Note that the POSIX threads APIs do +.I not +set +.I errno +on error. +Instead, on failure they return an error number as the function result. +These error numbers have the same meanings as the error numbers returned in +.I errno +by other APIs. +.P +On some ancient systems, +.I +was not present or did not declare +.IR errno , +so that it was necessary to declare +.I errno +manually +(i.e., +.IR "extern int errno" ). +.BR "Do not do this" . +It long ago ceased to be necessary, +and it will cause problems with modern versions of the C library. +.SH SEE ALSO +.BR errno (1), \" In the moreutils package +.BR err (3), +.BR error (3), +.BR perror (3), +.BR strerror (3) diff --git a/man/man3/error.3 b/man/man3/error.3 new file mode 100644 index 0000000..f341c86 --- /dev/null +++ b/man/man3/error.3 @@ -0,0 +1,171 @@ +'\" t +.\" Copyright (C) 2006 Justin Pryzby +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.TH error 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +error, error_at_line, error_message_count, error_one_per_line, +error_print_progname \- glibc error reporting functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void error(int " status ", int " errnum ", const char *" format ", ...);" +.BI "void error_at_line(int " status ", int " errnum ", const char *" filename , +.BI " unsigned int " linenum ", const char *" format ", ...);" +.P +.BI "extern unsigned int " error_message_count ; +.BI "extern int " error_one_per_line ; +.P +.BI "extern void (*" error_print_progname ")(void);" +.fi +.SH DESCRIPTION +.BR error () +is a general error-reporting function. +It flushes +.IR stdout , +and then outputs to +.I stderr +the program name, a colon and a space, the message specified by the +.BR printf (3)-style +format string \fIformat\fP, and, if \fIerrnum\fP is +nonzero, a second colon and a space followed by the string given by +.IR strerror(errnum) . +Any arguments required for +.I format +should follow +.I format +in the argument list. +The output is terminated by a newline character. +.P +The program name printed by +.BR error () +is the value of the global variable +.BR program_invocation_name (3). +.I program_invocation_name +initially has the same value as +.IR main ()'s +.IR argv[0] . +The value of this variable can be modified to change the output of +.BR error (). +.P +If \fIstatus\fP has a nonzero value, then +.BR error () +calls +.BR exit (3) +to terminate the program using the given value as the exit status; +otherwise it returns after printing the error message. +.P +The +.BR error_at_line () +function is exactly the same as +.BR error (), +except for the addition of the arguments +.I filename +and +.IR linenum . +The output produced is as for +.BR error (), +except that after the program name are written: a colon, the value of +.IR filename , +a colon, and the value of +.IR linenum . +The preprocessor values \fB__LINE__\fP and +\fB__FILE__\fP may be useful when calling +.BR error_at_line (), +but other values can also be used. +For example, these arguments could refer to a location in an input file. +.P +If the global variable \fIerror_one_per_line\fP is set nonzero, +a sequence of +.BR error_at_line () +calls with the +same value of \fIfilename\fP and \fIlinenum\fP will result in only +one message (the first) being output. +.P +The global variable \fIerror_message_count\fP counts the number of +messages that have been output by +.BR error () +and +.BR error_at_line (). +.P +If the global variable \fIerror_print_progname\fP +is assigned the address of a function +(i.e., is not NULL), then that function is called +instead of prefixing the message with the program name and colon. +The function should print a suitable string to +.IR stderr . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR error () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR error_at_line () +T} Thread safety T{ +.na +.nh +MT-Unsafe\ race: error_at_line/\:error_one_per_line locale +T} +.TE +.P +The internal +.I error_one_per_line +variable is accessed (without any form of synchronization, but since it's an +.I int +used once, it should be safe enough) and, if +.I error_one_per_line +is set nonzero, the internal static variables (not exposed to users) +used to hold the last printed filename and line number are accessed +and modified without synchronization; the update is not atomic and it +occurs before disabling cancelation, so it can be interrupted only after +one of the two variables is modified. +After that, +.BR error_at_line () +is very much like +.BR error (). +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR err (3), +.BR errno (3), +.BR exit (3), +.BR perror (3), +.BR program_invocation_name (3), +.BR strerror (3) diff --git a/man/man3/error_at_line.3 b/man/man3/error_at_line.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man/man3/error_at_line.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man/man3/error_message_count.3 b/man/man3/error_message_count.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man/man3/error_message_count.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man/man3/error_one_per_line.3 b/man/man3/error_one_per_line.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man/man3/error_one_per_line.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man/man3/error_print_progname.3 b/man/man3/error_print_progname.3 new file mode 100644 index 0000000..7ce8691 --- /dev/null +++ b/man/man3/error_print_progname.3 @@ -0,0 +1 @@ +.so man3/error.3 diff --git a/man/man3/errx.3 b/man/man3/errx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/errx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/etext.3 b/man/man3/etext.3 new file mode 100644 index 0000000..94843fb --- /dev/null +++ b/man/man3/etext.3 @@ -0,0 +1 @@ +.so man3/end.3 diff --git a/man/man3/ether_aton.3 b/man/man3/ether_aton.3 new file mode 100644 index 0000000..dbc6c2f --- /dev/null +++ b/man/man3/ether_aton.3 @@ -0,0 +1,143 @@ +'\" t +.\" Copyright 2002 Ian Redfern (redferni@logica.com) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" FreeBSD 4.4 man pages +.\" +.\" Minor additions, aeb, 2013-06-21 +.\" +.TH ether_aton 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ether_aton, ether_ntoa, ether_ntohost, ether_hostton, ether_line, +ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *ether_ntoa(const struct ether_addr *" addr ); +.BI "struct ether_addr *ether_aton(const char *" asc ); +.P +.BI "int ether_ntohost(char *" hostname ", const struct ether_addr *" addr ); +.BI "int ether_hostton(const char *" hostname ", struct ether_addr *" addr ); +.P +.BI "int ether_line(const char *" line ", struct ether_addr *" addr , +.BI " char *" hostname ); +.P +/* GNU extensions */ +.BI "char *ether_ntoa_r(const struct ether_addr *" addr ", char *" buf ); +.P +.BI "struct ether_addr *ether_aton_r(const char *" asc , +.BI " struct ether_addr *" addr ); +.fi +.SH DESCRIPTION +.BR ether_aton () +converts the 48-bit Ethernet host address +.I asc +from the standard hex-digits-and-colons notation into binary data in +network byte order and returns a pointer to it in a statically +allocated buffer, which subsequent calls will +overwrite. +.BR ether_aton () +returns NULL if the address is invalid. +.P +The +.BR ether_ntoa () +function converts the Ethernet host address +.I addr +given in network byte order to a string in standard +hex-digits-and-colons notation, omitting leading zeros. +The string is returned in a statically allocated buffer, +which subsequent calls will overwrite. +.P +The +.BR ether_ntohost () +function maps an Ethernet address to the +corresponding hostname in +.I /etc/ethers +and returns nonzero if it cannot be found. +.P +The +.BR ether_hostton () +function maps a hostname to the +corresponding Ethernet address in +.I /etc/ethers +and returns nonzero if it cannot be found. +.P +The +.BR ether_line () +function parses a line in +.I /etc/ethers +format (ethernet address followed by whitespace followed by +hostname; \[aq]#\[aq] introduces a comment) and returns an address +and hostname pair, or nonzero if it cannot be parsed. +The buffer pointed to by +.I hostname +must be sufficiently long, for example, have the same length as +.IR line . +.P +The functions +.BR ether_ntoa_r () +and +.BR ether_aton_r () +are reentrant +thread-safe versions of +.BR ether_ntoa () +and +.BR ether_aton () +respectively, and do not use static buffers. +.P +The structure +.I ether_addr +is defined in +.I +as: +.P +.in +4n +.EX +struct ether_addr { + uint8_t ether_addr_octet[6]; +} +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ether_aton (), +.BR ether_ntoa () +T} Thread safety MT-Unsafe +T{ +.na +.nh +.BR ether_ntohost (), +.BR ether_hostton (), +.BR ether_line (), +.BR ether_ntoa_r (), +.BR ether_aton_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD, SunOS. +.SH BUGS +In glibc 2.2.5 and earlier, the implementation of +.BR ether_line () +.\" The fix was presumably commit c0a0f9a32c8baa6ab93d00eb42d92c02e9e146d7 +.\" which was in glibc 2.3 +is broken. +.SH SEE ALSO +.BR ethers (5) diff --git a/man/man3/ether_aton_r.3 b/man/man3/ether_aton_r.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_aton_r.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/ether_hostton.3 b/man/man3/ether_hostton.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_hostton.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/ether_line.3 b/man/man3/ether_line.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_line.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/ether_ntoa.3 b/man/man3/ether_ntoa.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_ntoa.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/ether_ntoa_r.3 b/man/man3/ether_ntoa_r.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_ntoa_r.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/ether_ntohost.3 b/man/man3/ether_ntohost.3 new file mode 100644 index 0000000..f88e044 --- /dev/null +++ b/man/man3/ether_ntohost.3 @@ -0,0 +1 @@ +.so man3/ether_aton.3 diff --git a/man/man3/euidaccess.3 b/man/man3/euidaccess.3 new file mode 100644 index 0000000..7a896a1 --- /dev/null +++ b/man/man3/euidaccess.3 @@ -0,0 +1,104 @@ +'\" t +.\" Copyright (C) 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH euidaccess 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +euidaccess, eaccess \- check effective user's permissions for a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int euidaccess(const char *" pathname ", int " mode ); +.BI "int eaccess(const char *" pathname ", int " mode ); +.fi +.SH DESCRIPTION +Like +.BR access (2), +.BR euidaccess () +checks permissions and existence of the file identified by its argument +.IR pathname . +However, whereas +.BR access (2) +performs checks using the real user and group identifiers of the process, +.BR euidaccess () +uses the effective identifiers. +.P +.I mode +is a mask consisting of one or more of +.BR R_OK ", " W_OK ", " X_OK ", and " F_OK , +with the same meanings as for +.BR access (2). +.P +.BR eaccess () +is a synonym for +.BR euidaccess (), +provided for compatibility with some other systems. +.SH RETURN VALUE +On success (all requested permissions granted), zero is returned. +On error (at least one bit in +.I mode +asked for a permission that is denied, or some other error occurred), +\-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +As for +.BR access (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR euidaccess (), +.BR eaccess () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Some other systems have an +.\" e.g., FreeBSD 6.1. +.BR eaccess () +function. +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR eaccess () +glibc 2.4. +.SH NOTES +.IR Warning : +Using this function to check a process's permissions on a file before +performing some operation based on that information leads to race conditions: +the file permissions may change between the two steps. +Generally, it is safer just to attempt the desired operation and handle +any permission error that occurs. +.P +This function always dereferences symbolic links. +If you need to check the permissions on a symbolic link, use +.BR faccessat (2) +with the flags +.B AT_EACCESS +and +.BR AT_SYMLINK_NOFOLLOW . +.SH SEE ALSO +.BR access (2), +.BR chmod (2), +.BR chown (2), +.BR faccessat (2), +.BR open (2), +.BR setgid (2), +.BR setuid (2), +.BR stat (2), +.BR credentials (7), +.BR path_resolution (7) diff --git a/man/man3/eventfd_read.3 b/man/man3/eventfd_read.3 new file mode 100644 index 0000000..eddfaa8 --- /dev/null +++ b/man/man3/eventfd_read.3 @@ -0,0 +1 @@ +.so man2/eventfd.2 diff --git a/man/man3/eventfd_write.3 b/man/man3/eventfd_write.3 new file mode 100644 index 0000000..eddfaa8 --- /dev/null +++ b/man/man3/eventfd_write.3 @@ -0,0 +1 @@ +.so man2/eventfd.2 diff --git a/man/man3/exec.3 b/man/man3/exec.3 new file mode 100644 index 0000000..a94a2f1 --- /dev/null +++ b/man/man3/exec.3 @@ -0,0 +1,311 @@ +'\" t +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)exec.3 6.4 (Berkeley) 4/19/91 +.\" +.\" Converted for Linux, Mon Nov 29 11:12:48 1993, faith@cs.unc.edu +.\" Updated more for Linux, Tue Jul 15 11:54:18 1997, pacman@cqc.com +.\" Modified, 24 Jun 2004, Michael Kerrisk +.\" Added note on casting NULL +.\" +.TH exec 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +execl, execlp, execle, execv, execvp, execvpe \- execute a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B extern char **environ; +.P +.BI "int execl(const char *" pathname ", const char *" arg ", ..." +.B " /*, (char *) NULL */);" +.BI "int execlp(const char *" file ", const char *" arg ", ..." +.B " /*, (char *) NULL */);" +.BI "int execle(const char *" pathname ", const char *" arg ", ..." +.BI " /*, (char *) NULL, char *const " envp "[] */);" +.BI "int execv(const char *" pathname ", char *const " argv "[]);" +.BI "int execvp(const char *" file ", char *const " argv "[]);" +.BI "int execvpe(const char *" file ", char *const " argv \ +"[], char *const " envp "[]);" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR execvpe (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR exec () +family of functions replaces the current process image with a new process +image. +The functions described in this manual page are layered on top of +.BR execve (2). +(See the manual page for +.BR execve (2) +for further details about the replacement of the current process image.) +.P +The initial argument for these functions is the name of a file that is +to be executed. +.P +The functions can be grouped based on the letters following the "exec" prefix. +.\" +.SS l - execl(), execlp(), execle() +The +.I "const char\ *arg" +and subsequent ellipses can be thought of as +.IR arg0 , +.IR arg1 , +\&..., +.IR argn . +Together they describe a list of one or more pointers to null-terminated +strings that represent the argument list available to the executed program. +The first argument, by convention, should point to the filename associated +with the file being executed. +The list of arguments +.I must +be terminated by a null pointer, +and, since these are variadic functions, this pointer must be cast +.IR "(char\ *) NULL" . +.P +By contrast with the 'l' functions, the 'v' functions (below) specify the +command-line arguments of the executed program as a vector. +.\" +.SS v - execv(), execvp(), execvpe() +The +.I "char\ *const argv[]" +argument is an array of pointers to null-terminated strings that +represent the argument list available to the new program. +The first argument, by convention, should point to the filename +associated with the file being executed. +The array of pointers +.I must +be terminated by a null pointer. +.SS e - execle(), execvpe() +The environment of the new process image is specified via the argument +.IR envp . +The +.I envp +argument is an array of pointers to null-terminated strings and +.I must +be terminated by a null pointer. +.P +All other +.BR exec () +functions (which do not include 'e' in the suffix) +take the environment for the new process +image from the external variable +.I environ +in the calling process. +.SS p - execlp(), execvp(), execvpe() +These functions duplicate the actions of the shell in +searching for an executable file +if the specified filename does not contain a slash (/) character. +The file is sought in the colon-separated list of directory pathnames +specified in the +.B PATH +environment variable. +If this variable isn't defined, the path list defaults to +a list that includes the directories returned by +.I confstr(_CS_PATH) +(which typically returns the value "/bin:/usr/bin") +and possibly also the current working directory; +see NOTES for further details. +.P +.BR execvpe () +searches for the program using the value of +.B PATH +from the caller's environment, not from the +.I envp +argument. +.P +If the specified filename includes a slash character, then +.B PATH +is ignored, and the file at the specified pathname is executed. +.P +In addition, certain errors are treated specially. +.P +If permission is denied for a file (the attempted +.BR execve (2) +failed with the error +.BR EACCES ), +these functions will continue searching the rest of the search path. +If no other file is found, however, +they will return with +.I errno +set to +.BR EACCES . +.P +If the header of a file isn't recognized (the attempted +.BR execve (2) +failed with the error +.BR ENOEXEC ), +these functions will execute the shell +.RI ( /bin/sh ) +with the path of the file as its first argument. +(If this attempt fails, no further searching is done.) +.P +All other +.BR exec () +functions (which do not include 'p' in the suffix) +take as their first argument a (relative or absolute) pathname +that identifies the program to be executed. +.SH RETURN VALUE +The +.BR exec () +functions return only if an error has occurred. +The return value is \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +All of these functions may fail and set +.I errno +for any of the errors specified for +.BR execve (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR execl (), +.BR execle (), +.BR execv () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR execlp (), +.BR execvp (), +.BR execvpe () +T} Thread safety MT-Safe env +.TE +.SH VERSIONS +The default search path (used when the environment +does not contain the variable \fBPATH\fR) +shows some variation across systems. +It generally includes +.I /bin +and +.I /usr/bin +(in that order) and may also include the current working directory. +On some other systems, the current working is included after +.I /bin +and +.IR /usr/bin , +as an anti-Trojan-horse measure. +The glibc implementation long followed the traditional default where +the current working directory is included at the start of the search path. +However, some code refactoring during the development of glibc 2.24 +.\" glibc commit 1eb8930608705702d5746e5491bab4e4429fcb83 +caused the current working directory to be dropped altogether +from the default search path. +This accidental behavior change is considered mildly beneficial, +and won't be reverted. +.P +The behavior of +.BR execlp () +and +.BR execvp () +when errors occur while attempting to execute the file is historic +practice, but has not traditionally been documented and is not specified by +the POSIX standard. +BSD (and possibly other systems) do an automatic +sleep and retry if +.B ETXTBSY +is encountered. +Linux treats it as a hard +error and returns immediately. +.P +Traditionally, the functions +.BR execlp () +and +.BR execvp () +ignored all errors except for the ones described above and +.B ENOMEM +and +.BR E2BIG , +upon which they returned. +They now return if any error other than the ones +described above occurs. +.SH STANDARDS +.TP +.B environ +.TQ +.BR execl () +.TQ +.BR execlp () +.TQ +.BR execle () +.TQ +.BR execv () +.TQ +.BR execvp () +POSIX.1-2008. +.TP +.BR execvpe () +GNU. +.SH HISTORY +.TP +.B environ +.TQ +.BR execl () +.TQ +.BR execlp () +.TQ +.BR execle () +.TQ +.BR execv () +.TQ +.BR execvp () +POSIX.1-2001. +.TP +.BR execvpe () +glibc 2.11. +.SH BUGS +Before glibc 2.24, +.BR execl () +and +.BR execle () +employed +.BR realloc (3) +internally and were consequently not async-signal-safe, +in violation of the requirements of POSIX.1. +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534 +This was fixed in glibc 2.24. +.\" +.SS Architecture-specific details +On sparc and sparc64, +.BR execv () +is provided as a system call by the kernel +(with the prototype shown above) +for compatibility with SunOS. +This function is +.I not +employed by the +.BR execv () +wrapper function on those architectures. +.SH SEE ALSO +.BR sh (1), +.BR execve (2), +.BR execveat (2), +.BR fork (2), +.BR ptrace (2), +.BR fexecve (3), +.BR system (3), +.BR environ (7) diff --git a/man/man3/execl.3 b/man/man3/execl.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execl.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/execle.3 b/man/man3/execle.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execle.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/execlp.3 b/man/man3/execlp.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execlp.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/execv.3 b/man/man3/execv.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execv.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/execvp.3 b/man/man3/execvp.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execvp.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/execvpe.3 b/man/man3/execvpe.3 new file mode 100644 index 0000000..4bf4872 --- /dev/null +++ b/man/man3/execvpe.3 @@ -0,0 +1 @@ +.so man3/exec.3 diff --git a/man/man3/exit.3 b/man/man3/exit.3 new file mode 100644 index 0000000..4fa48e0 --- /dev/null +++ b/man/man3/exit.3 @@ -0,0 +1,202 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" FIXME . There are a lot of other process termination actions that +.\" could be listed on this page. See, for example, the list in the +.\" POSIX exit(3p) page. +.\" +.TH exit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +exit \- cause normal process termination +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[noreturn]] void exit(int " status ); +.fi +.SH DESCRIPTION +The +.BR exit () +function causes normal process termination and the least significant byte of +.I status +(i.e., \fIstatus & 0xFF\fP) is returned to the parent (see +.BR wait (2)). +.P +All functions registered with +.BR atexit (3) +and +.BR on_exit (3) +are called, in the reverse order of their registration. +(It is possible for one of these functions to use +.BR atexit (3) +or +.BR on_exit (3) +to register an additional +function to be executed during exit processing; +the new registration is added to the front of the list of functions +that remain to be called.) +If one of these functions does not return +(e.g., it calls +.BR _exit (2), +or kills itself with a signal), +then none of the remaining functions is called, +and further exit processing (in particular, flushing of +.BR stdio (3) +streams) is abandoned. +If a function has been registered multiple times using +.BR atexit (3) +or +.BR on_exit (3), +then it is called as many times as it was registered. +.P +All open +.BR stdio (3) +streams are flushed and closed. +Files created by +.BR tmpfile (3) +are removed. +.P +The C standard specifies two constants, +\fBEXIT_SUCCESS\fP and \fBEXIT_FAILURE\fP, +that may be passed to +.BR exit () +to indicate successful or unsuccessful +termination, respectively. +.SH RETURN VALUE +The +.BR exit () +function does not return. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR exit () +T} Thread safety MT-Unsafe race:exit +.TE +.P +The +.BR exit () +function uses a global variable that is not protected, +so it is not thread-safe. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +The behavior is undefined if one of the functions registered using +.BR atexit (3) +and +.BR on_exit (3) +calls either +.BR exit () +or +.BR longjmp (3). +Note that a call to +.BR execve (2) +removes registrations created using +.BR atexit (3) +and +.BR on_exit (3). +.P +The use of +.B EXIT_SUCCESS +and +.B EXIT_FAILURE +is slightly more portable +(to non-UNIX environments) than the use of 0 and some nonzero value +like 1 or \-1. +In particular, VMS uses a different convention. +.P +BSD has attempted to standardize exit codes +(which some C libraries such as the GNU C library have also adopted); +see the file +.IR . +.P +After +.BR exit (), +the exit status must be transmitted to the +parent process. +There are three cases: +.IP \[bu] 3 +If the parent has set +.BR SA_NOCLDWAIT , +or has set the +.B SIGCHLD +handler to +.BR SIG_IGN , +the status is discarded and the child dies immediately. +.IP \[bu] +If the parent was waiting on the child, +it is notified of the exit status and the child dies immediately. +.IP \[bu] +Otherwise, +the child becomes a "zombie" process: +most of the process resources are recycled, +but a slot containing minimal information about the child process +(termination status, resource usage statistics) is retained in process table. +This allows the parent to subsequently use +.BR waitpid (2) +(or similar) to learn the termination status of the child; +at that point the zombie process slot is released. +.P +If the implementation supports the +.B SIGCHLD +signal, this signal +is sent to the parent. +If the parent has set +.BR SA_NOCLDWAIT , +it is undefined whether a +.B SIGCHLD +signal is sent. +.\" +.SS Signals sent to other processes +If the exiting process is a session leader and its controlling terminal +is the controlling terminal of the session, then each process in +the foreground process group of this controlling terminal +is sent a +.B SIGHUP +signal, and the terminal is disassociated +from this session, allowing it to be acquired by a new controlling +process. +.P +If the exit of the process causes a process group to become orphaned, +and if any member of the newly orphaned process group is stopped, +then a +.B SIGHUP +signal followed by a +.B SIGCONT +signal will be +sent to each process in this process group. +See +.BR setpgid (2) +for an explanation of orphaned process groups. +.P +Except in the above cases, +where the signalled processes may be children of the terminating process, +termination of a process does +.I not +in general cause a signal to be sent to children of that process. +However, a process can use the +.BR prctl (2) +.B PR_SET_PDEATHSIG +operation to arrange that it receives a signal if its parent terminates. +.SH SEE ALSO +.BR _exit (2), +.BR get_robust_list (2), +.BR setpgid (2), +.BR wait (2), +.BR atexit (3), +.BR on_exit (3), +.BR tmpfile (3) diff --git a/man/man3/exp.3 b/man/man3/exp.3 new file mode 100644 index 0000000..85a3f8f --- /dev/null +++ b/man/man3/exp.3 @@ -0,0 +1,133 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH exp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +exp, expf, expl \- base-e exponential function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double exp(double " x ); +.BI "float expf(float " x ); +.BI "long double expl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR expf (), +.BR expl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the value of e (the base of natural +logarithms) raised to the power of +.IR x . +.SH RETURN VALUE +On success, these functions return the exponential value of +.IR x . +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is positive infinity, +positive infinity is returned. +.P +If +.I x +is negative infinity, ++0 is returned. +.P +If the result underflows, +a range error occurs, +and zero is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error, overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR exp (), +.BR expf (), +.BR expl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR cbrt (3), +.BR cexp (3), +.BR exp10 (3), +.BR exp2 (3), +.BR expm1 (3), +.BR sqrt (3) diff --git a/man/man3/exp10.3 b/man/man3/exp10.3 new file mode 100644 index 0000000..69b6094 --- /dev/null +++ b/man/man3/exp10.3 @@ -0,0 +1,82 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH exp10 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +exp10, exp10f, exp10l \- base-10 exponential function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "double exp10(double " x ); +.BI "float exp10f(float " x ); +.BI "long double exp10l(long double " x ); +.fi +.SH DESCRIPTION +These functions return the value of 10 +raised to the power of +.IR x . +.SH RETURN VALUE +On success, these functions return the base-10 exponential value of +.IR x . +.P +For various special cases, including the handling of infinity and NaN, +as well as overflows and underflows, see +.BR exp (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +For a discussion of the errors that can occur for these functions, see +.BR exp (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR exp10 (), +.BR exp10f (), +.BR exp10l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH BUGS +Before glibc 2.19, the glibc implementation of these functions did not set +.I errno +to +.B ERANGE +when an underflow error occurred. +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6787 +.SH SEE ALSO +.BR cbrt (3), +.BR exp (3), +.BR exp2 (3), +.BR log10 (3), +.BR sqrt (3) diff --git a/man/man3/exp10f.3 b/man/man3/exp10f.3 new file mode 100644 index 0000000..705b75e --- /dev/null +++ b/man/man3/exp10f.3 @@ -0,0 +1 @@ +.so man3/exp10.3 diff --git a/man/man3/exp10l.3 b/man/man3/exp10l.3 new file mode 100644 index 0000000..705b75e --- /dev/null +++ b/man/man3/exp10l.3 @@ -0,0 +1 @@ +.so man3/exp10.3 diff --git a/man/man3/exp2.3 b/man/man3/exp2.3 new file mode 100644 index 0000000..728deb0 --- /dev/null +++ b/man/man3/exp2.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH exp2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +exp2, exp2f, exp2l \- base-2 exponential function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double exp2(double " x ); +.BI "float exp2f(float " x ); +.BI "long double exp2l(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR exp2 (), +.BR exp2f (), +.BR exp2l (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return the value of 2 raised to the power of +.IR x . +.SH RETURN VALUE +On success, these functions return the base-2 exponential value of +.IR x . +.P +For various special cases, including the handling of infinity and NaN, +as well as overflows and underflows, see +.BR exp (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +For a discussion of the errors that can occur for these functions, see +.BR exp (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR exp2 (), +.BR exp2f (), +.BR exp2l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cbrt (3), +.BR cexp2 (3), +.BR exp (3), +.BR exp10 (3), +.BR sqrt (3) diff --git a/man/man3/exp2f.3 b/man/man3/exp2f.3 new file mode 100644 index 0000000..b69beea --- /dev/null +++ b/man/man3/exp2f.3 @@ -0,0 +1 @@ +.so man3/exp2.3 diff --git a/man/man3/exp2l.3 b/man/man3/exp2l.3 new file mode 100644 index 0000000..b69beea --- /dev/null +++ b/man/man3/exp2l.3 @@ -0,0 +1 @@ +.so man3/exp2.3 diff --git a/man/man3/expf.3 b/man/man3/expf.3 new file mode 100644 index 0000000..4b1efda --- /dev/null +++ b/man/man3/expf.3 @@ -0,0 +1 @@ +.so man3/exp.3 diff --git a/man/man3/expl.3 b/man/man3/expl.3 new file mode 100644 index 0000000..4b1efda --- /dev/null +++ b/man/man3/expl.3 @@ -0,0 +1 @@ +.so man3/exp.3 diff --git a/man/man3/explicit_bzero.3 b/man/man3/explicit_bzero.3 new file mode 100644 index 0000000..8a43e76 --- /dev/null +++ b/man/man3/explicit_bzero.3 @@ -0,0 +1 @@ +.so man3/bzero.3 diff --git a/man/man3/expm1.3 b/man/man3/expm1.3 new file mode 100644 index 0000000..0bdfc6b --- /dev/null +++ b/man/man3/expm1.3 @@ -0,0 +1,165 @@ +'\" t +.\" Copyright 1995 Jim Van Zandt +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2002-07-27 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH expm1 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +expm1, expm1f, expm1l \- exponential minus 1 +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double expm1(double " x ); +.BI "float expm1f(float " x ); +.BI "long double expm1l(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR expm1 (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR expm1f (), +.BR expm1l (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return a value equivalent to +.P +.nf + exp(x) \- 1 +.fi +.P +The result is computed in a way that is accurate even if the value of +.I x +is near +zero\[em]a case where +.I "exp(x) \- 1" +would be inaccurate due to +subtraction of two numbers that are nearly equal. +.SH RETURN VALUE +On success, these functions return +.IR "exp(x)\ \-\ 1" . +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is +0 (\-0), ++0 (\-0) is returned. +.P +If +.I x +is positive infinity, positive infinity is returned. +.P +If +.I x +is negative infinity, \-1 is returned. +.P +If the result overflows, a range error occurs, +and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error, overflow +.I errno +is set to +.B ERANGE +(but see BUGS). +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.\" +.\" POSIX.1 specifies an optional range error (underflow) if +.\" x is subnormal. glibc does not implement this. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR expm1 (), +.BR expm1f (), +.BR expm1l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +BSD. +.SH BUGS +Before glibc 2.17, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6778 +on certain architectures (e.g., x86, but not x86_64) +.BR expm1 () +raised a bogus underflow floating-point exception +for some large negative +.I x +values (where the function result approaches \-1). +.P +Before approximately glibc 2.11, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6814 +.\" e.g., expm1(1e5) through expm1(1.00199970127e5), +.\" but not expm1(1.00199970128e5) and beyond. +.BR expm1 () +raised a bogus invalid floating-point exception in addition to the expected +overflow exception, and returned a NaN instead of positive infinity, +for some large positive +.I x +values. +.P +Before glibc 2.11, +.\" It looks like the fix was in glibc 2.11, or possibly glibc 2.12. +.\" I have no test system for glibc 2.11, but glibc 2.12 passes. +.\" From the source (sysdeps/i386/fpu/s_expm1.S) it looks +.\" like the changes were in glibc 2.11. +the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6788 +.I errno +to +.B ERANGE +when a range error occurred. +.SH SEE ALSO +.BR exp (3), +.BR log (3), +.BR log1p (3) diff --git a/man/man3/expm1f.3 b/man/man3/expm1f.3 new file mode 100644 index 0000000..2c9e4ea --- /dev/null +++ b/man/man3/expm1f.3 @@ -0,0 +1 @@ +.so man3/expm1.3 diff --git a/man/man3/expm1l.3 b/man/man3/expm1l.3 new file mode 100644 index 0000000..2c9e4ea --- /dev/null +++ b/man/man3/expm1l.3 @@ -0,0 +1 @@ +.so man3/expm1.3 diff --git a/man/man3/fabs.3 b/man/man3/fabs.3 new file mode 100644 index 0000000..6e6ed08 --- /dev/null +++ b/man/man3/fabs.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:42:04 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added fabsl, fabsf, aeb, 2001-06-07 +.\" +.TH fabs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fabs, fabsf, fabsl \- absolute value of floating-point number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double fabs(double " x ); +.BI "float fabsf(float " x ); +.BI "long double fabsl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fabsf (), +.BR fabsl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the absolute value of the floating-point +number +.IR x . +.SH RETURN VALUE +These functions return the absolute value of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is \-0, +0 is returned. +.P +If +.I x +is negative infinity or positive infinity, positive infinity is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fabs (), +.BR fabsf (), +.BR fabsl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR abs (3), +.BR cabs (3), +.BR ceil (3), +.BR floor (3), +.BR labs (3), +.BR rint (3) diff --git a/man/man3/fabsf.3 b/man/man3/fabsf.3 new file mode 100644 index 0000000..0426cf0 --- /dev/null +++ b/man/man3/fabsf.3 @@ -0,0 +1 @@ +.so man3/fabs.3 diff --git a/man/man3/fabsl.3 b/man/man3/fabsl.3 new file mode 100644 index 0000000..0426cf0 --- /dev/null +++ b/man/man3/fabsl.3 @@ -0,0 +1 @@ +.so man3/fabs.3 diff --git a/man/man3/fclose.3 b/man/man3/fclose.3 new file mode 100644 index 0000000..a39aaa8 --- /dev/null +++ b/man/man3/fclose.3 @@ -0,0 +1,102 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fclose.3 6.7 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:19:14 1993, faith@cs.unc.edu +.\" +.\" Modified 2000-07-22 by Nicolás Lichtmaier +.\" +.TH fclose 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fclose \- close a stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fclose(FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR fclose () +function flushes the stream pointed to by +.I stream +(writing any buffered output data using +.BR fflush (3)) +and closes the underlying file descriptor. +.SH RETURN VALUE +Upon successful completion, 0 is returned. +Otherwise, +.B EOF +is returned and +.I errno +is set to indicate the error. +In either case, any further access +(including another call to +.BR fclose ()) +to the stream results in undefined behavior. +.SH ERRORS +.TP +.B EBADF +The file descriptor underlying +.I stream +is not valid. +.\" This error cannot occur unless you are mixing ANSI C stdio operations and +.\" low-level file operations on the same stream. If you do get this error, +.\" you must have closed the stream's low-level file descriptor using +.\" something like close(fileno(stream)). +.P +The +.BR fclose () +function may also fail and set +.I errno +for any of the errors specified for the routines +.BR close (2), +.BR write (2), +or +.BR fflush (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fclose () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH NOTES +Note that +.BR fclose () +flushes only the user-space buffers provided by the +C library. +To ensure that the data is physically stored +on disk the kernel buffers must be flushed too, for example, with +.BR sync (2) +or +.BR fsync (2). +.SH SEE ALSO +.BR close (2), +.BR fcloseall (3), +.BR fflush (3), +.BR fileno (3), +.BR fopen (3), +.BR setbuf (3) diff --git a/man/man3/fcloseall.3 b/man/man3/fcloseall.3 new file mode 100644 index 0000000..b7ed34b --- /dev/null +++ b/man/man3/fcloseall.3 @@ -0,0 +1,64 @@ +'\" t +.\" Copyright (c) 2006 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fcloseall 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fcloseall \- close all open streams +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.B int fcloseall(void); +.fi +.SH DESCRIPTION +The +.BR fcloseall () +function closes all of the calling process's open streams. +Buffered output for each stream is written before it is closed +(as for +.BR fflush (3)); +buffered input is discarded. +.P +The standard streams, +.IR stdin , +.IR stdout , +and +.I stderr +are also closed. +.SH RETURN VALUE +This function returns 0 if all files were successfully closed; +on error, +.B EOF +is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fcloseall () +T} Thread safety MT-Unsafe race:streams +.TE +.P +The +.BR fcloseall () +function does not lock the streams, so it is not thread-safe. +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR close (2), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR setbuf (3) diff --git a/man/man3/fcvt.3 b/man/man3/fcvt.3 new file mode 100644 index 0000000..39d3770 --- /dev/null +++ b/man/man3/fcvt.3 @@ -0,0 +1 @@ +.so man3/ecvt.3 diff --git a/man/man3/fcvt_r.3 b/man/man3/fcvt_r.3 new file mode 100644 index 0000000..41ce9ee --- /dev/null +++ b/man/man3/fcvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man/man3/fdim.3 b/man/man3/fdim.3 new file mode 100644 index 0000000..271d853 --- /dev/null +++ b/man/man3/fdim.3 @@ -0,0 +1,96 @@ +'\" t +.\" Copyright 2003 Walter Harms, Andries Brouwer +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH fdim 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fdim, fdimf, fdiml \- positive difference +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double fdim(double " x ", double " y ); +.BI "float fdimf(float " x ", float " y ); +.BI "long double fdiml(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fdimf (), +.BR fdiml (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return the positive difference, max(\fIx\fP-\fIy\fP,0), +between their arguments. +.SH RETURN VALUE +On success, these functions return the positive difference. +.P +If +.I x +or +.I y +is a NaN, a NaN is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fdim (), +.BR fdimf (), +.BR fdiml () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH BUGS +Before glibc 2.24 +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6796 +on certain architectures (e.g., x86, but not x86_64) +these functions did not set +.IR errno . +.SH SEE ALSO +.BR fmax (3) diff --git a/man/man3/fdimf.3 b/man/man3/fdimf.3 new file mode 100644 index 0000000..a4058e4 --- /dev/null +++ b/man/man3/fdimf.3 @@ -0,0 +1 @@ +.so man3/fdim.3 diff --git a/man/man3/fdiml.3 b/man/man3/fdiml.3 new file mode 100644 index 0000000..a4058e4 --- /dev/null +++ b/man/man3/fdiml.3 @@ -0,0 +1 @@ +.so man3/fdim.3 diff --git a/man/man3/fdopen.3 b/man/man3/fdopen.3 new file mode 100644 index 0000000..9a40124 --- /dev/null +++ b/man/man3/fdopen.3 @@ -0,0 +1 @@ +.so man3/fopen.3 diff --git a/man/man3/fdopendir.3 b/man/man3/fdopendir.3 new file mode 100644 index 0000000..55b720e --- /dev/null +++ b/man/man3/fdopendir.3 @@ -0,0 +1 @@ +.so man3/opendir.3 diff --git a/man/man3/feclearexcept.3 b/man/man3/feclearexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/feclearexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fedisableexcept.3 b/man/man3/fedisableexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fedisableexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/feenableexcept.3 b/man/man3/feenableexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/feenableexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fegetenv.3 b/man/man3/fegetenv.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fegetenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fegetexcept.3 b/man/man3/fegetexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fegetexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fegetexceptflag.3 b/man/man3/fegetexceptflag.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fegetexceptflag.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fegetround.3 b/man/man3/fegetround.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fegetround.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/feholdexcept.3 b/man/man3/feholdexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/feholdexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fenv.3 b/man/man3/fenv.3 new file mode 100644 index 0000000..04f3dca --- /dev/null +++ b/man/man3/fenv.3 @@ -0,0 +1,334 @@ +'\" t +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2000-08-14 added GNU additions from Andreas Jaeger +.\" 2000-12-05 some changes inspired by acahalan's remarks +.\" +.TH fenv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, +fetestexcept, fegetenv, fegetround, feholdexcept, fesetround, +fesetenv, feupdateenv, feenableexcept, fedisableexcept, +fegetexcept \- floating-point rounding and exception handling +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int feclearexcept(int " excepts ); +.BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts ); +.BI "int feraiseexcept(int " excepts ); +.BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts ); +.BI "int fetestexcept(int " excepts ); +.P +.B "int fegetround(void);" +.BI "int fesetround(int " rounding_mode ); +.P +.BI "int fegetenv(fenv_t *" envp ); +.BI "int feholdexcept(fenv_t *" envp ); +.BI "int fesetenv(const fenv_t *" envp ); +.BI "int feupdateenv(const fenv_t *" envp ); +.fi +.SH DESCRIPTION +These eleven functions were defined in C99, and describe the handling +of floating-point rounding and exceptions (overflow, zero-divide, etc.). +.SS Exceptions +The +.I divide-by-zero +exception occurs when an operation on finite numbers +produces infinity as exact answer. +.P +The +.I overflow +exception occurs when a result has to be represented as a +floating-point number, but has (much) larger absolute value than the +largest (finite) floating-point number that is representable. +.P +The +.I underflow +exception occurs when a result has to be represented as a +floating-point number, but has smaller absolute value than the smallest +positive normalized floating-point number (and would lose much accuracy +when represented as a denormalized number). +.P +The +.I inexact +exception occurs when the rounded result of an operation +is not equal to the infinite precision result. +It may occur whenever +.I overflow +or +.I underflow +occurs. +.P +The +.I invalid +exception occurs when there is no well-defined result +for an operation, as for 0/0 or infinity \- infinity or sqrt(\-1). +.SS Exception handling +Exceptions are represented in two ways: as a single bit +(exception present/absent), and these bits correspond in some +implementation-defined way with bit positions in an integer, +and also as an opaque structure that may contain more information +about the exception (perhaps the code address where it occurred). +.P +Each of the macros +.BR FE_DIVBYZERO , +.BR FE_INEXACT , +.BR FE_INVALID , +.BR FE_OVERFLOW , +.B FE_UNDERFLOW +is defined when the implementation supports handling +of the corresponding exception, and if so then +defines the corresponding bit(s), so that one can call +exception handling functions, for example, using the integer argument +.BR FE_OVERFLOW | FE_UNDERFLOW . +Other exceptions may be supported. +The macro +.B FE_ALL_EXCEPT +is the bitwise OR of all bits corresponding to supported exceptions. +.P +The +.BR feclearexcept () +function clears the supported exceptions represented by the bits +in its argument. +.P +The +.BR fegetexceptflag () +function stores a representation of the state of the exception flags +represented by the argument +.I excepts +in the opaque object +.IR *flagp . +.P +The +.BR feraiseexcept () +function raises the supported exceptions represented by the bits in +.IR excepts . +.P +The +.BR fesetexceptflag () +function sets the complete status for the exceptions represented by +.I excepts +to the value +.IR *flagp . +This value must have been obtained by an earlier call of +.BR fegetexceptflag () +with a last argument that contained all bits in +.IR excepts . +.P +The +.BR fetestexcept () +function returns a word in which the bits are set that were +set in the argument +.I excepts +and for which the corresponding exception is currently set. +.SS Rounding mode +The rounding mode determines how the result of floating-point operations +is treated when the result cannot be exactly represented in the significand. +Various rounding modes may be provided: +round to nearest (the default), +round up (toward positive infinity), +round down (toward negative infinity), and +round toward zero. +.P +Each of the macros +.BR FE_TONEAREST , +.BR FE_UPWARD , +.BR FE_DOWNWARD , +and +.B FE_TOWARDZERO +is defined when the implementation supports getting and setting +the corresponding rounding direction. +.P +The +.BR fegetround () +function returns the macro corresponding to the current +rounding mode. +.P +The +.BR fesetround () +function sets the rounding mode as specified by its argument +and returns zero when it was successful. +.P +C99 and POSIX.1-2008 specify an identifier, +.BR FLT_ROUNDS , +defined in +.IR , +which indicates the implementation-defined rounding +behavior for floating-point addition. +This identifier has one of the following values: +.TP +.B \-1 +The rounding mode is not determinable. +.TP +.B 0 +Rounding is toward 0. +.TP +.B 1 +Rounding is toward nearest number. +.TP +.B 2 +Rounding is toward positive infinity. +.TP +.B 3 +Rounding is toward negative infinity. +.P +Other values represent machine-dependent, nonstandard rounding modes. +.P +The value of +.B FLT_ROUNDS +should reflect the current rounding mode as set by +.BR fesetround () +(but see BUGS). +.SS Floating-point environment +The entire floating-point environment, including +control modes and status flags, can be handled +as one opaque object, of type +.IR fenv_t . +The default environment is denoted by +.B FE_DFL_ENV +(of type +.IR "const fenv_t\ *" ). +This is the environment setup at program start and it is defined by +ISO C to have round to nearest, all exceptions cleared and a nonstop +(continue on exceptions) mode. +.P +The +.BR fegetenv () +function saves the current floating-point environment in the object +.IR *envp . +.P +The +.BR feholdexcept () +function does the same, then clears all exception flags, +and sets a nonstop (continue on exceptions) mode, +if available. +It returns zero when successful. +.P +The +.BR fesetenv () +function restores the floating-point environment from +the object +.IR *envp . +This object must be known to be valid, for example, the result of a call to +.BR fegetenv () +or +.BR feholdexcept () +or equal to +.BR FE_DFL_ENV . +This call does not raise exceptions. +.P +The +.BR feupdateenv () +function installs the floating-point environment represented by +the object +.IR *envp , +except that currently raised exceptions are not cleared. +After calling this function, the raised exceptions will be a bitwise OR +of those previously set with those in +.IR *envp . +As before, the object +.I *envp +must be known to be valid. +.SH RETURN VALUE +These functions return zero on success and nonzero if an error occurred. +.\" Earlier seven of these functions were listed as returning void. +.\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E)) +.\" of the C99 Standard. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.nh +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR feclearexcept (), +.BR fegetexceptflag (), +.BR feraiseexcept (), +.BR fesetexceptflag (), +.BR fetestexcept (), +.BR fegetround (), +.BR fesetround (), +.BR fegetenv (), +.BR feholdexcept (), +.BR fesetenv (), +.BR feupdateenv (), +.BR feenableexcept (), +.BR fedisableexcept (), +.BR fegetexcept () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +.TE +.hy +.SH STANDARDS +C11, POSIX.1-2008, IEC 60559 (IEC 559:1989), ANSI/IEEE 854. +.SH HISTORY +C99, POSIX.1-2001. +glibc 2.1. +.SH NOTES +.SS glibc notes +If possible, the GNU C Library defines a macro +.B FE_NOMASK_ENV +which represents an environment where every exception raised causes a +trap to occur. +You can test for this macro using +.BR #ifdef . +It is defined only if +.B _GNU_SOURCE +is defined. +The C99 standard does not define a way to set individual bits in the +floating-point mask, for example, to trap on specific flags. +Since glibc 2.2, glibc supports the functions +.BR feenableexcept () +and +.BR fedisableexcept () +to set individual floating-point traps, and +.BR fegetexcept () +to query the state. +.P +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B "#include " +.P +.BI "int feenableexcept(int " excepts ); +.BI "int fedisableexcept(int " excepts ); +.B "int fegetexcept(void);" +.fi +.P +The +.BR feenableexcept () +and +.BR fedisableexcept () +functions enable (disable) traps for each of the exceptions represented by +.I excepts +and return the previous set of enabled exceptions when successful, +and \-1 otherwise. +The +.BR fegetexcept () +function returns the set of all currently enabled exceptions. +.SH BUGS +C99 specifies that the value of +.B FLT_ROUNDS +should reflect changes to the current rounding mode, as set by +.BR fesetround (). +Currently, +.\" Aug 08, glibc 2.8 +this does not occur: +.B FLT_ROUNDS +always has the value 1. +.\" See http://gcc.gnu.org/ml/gcc/2002-02/msg01535.html +.SH SEE ALSO +.BR math_error (7) diff --git a/man/man3/feof.3 b/man/man3/feof.3 new file mode 100644 index 0000000..3a95cca --- /dev/null +++ b/man/man3/feof.3 @@ -0,0 +1 @@ +.so man3/ferror.3 diff --git a/man/man3/feof_unlocked.3 b/man/man3/feof_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/feof_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/feraiseexcept.3 b/man/man3/feraiseexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/feraiseexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/ferror.3 b/man/man3/ferror.3 new file mode 100644 index 0000000..cdfc3a7 --- /dev/null +++ b/man/man3/ferror.3 @@ -0,0 +1,118 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" and Copyright (C) 2021 Michael Kerrisk +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)ferror.3 6.8 (Berkeley) 6/29/91 +.\" +.\" +.\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu +.\" +.TH ferror 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clearerr, feof, ferror \- check and reset stream status +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void clearerr(FILE *" stream ); +.BI "int feof(FILE *" stream ); +.BI "int ferror(FILE *" stream ); +.fi +.SH DESCRIPTION +The function +.BR clearerr () +clears the end-of-file and error indicators for the stream pointed to by +.IR stream . +.P +The function +.BR feof () +tests the end-of-file indicator for the stream pointed to by +.IR stream , +returning nonzero if it is set. +The end-of-file indicator can be cleared only by the function +.BR clearerr (). +.P +The function +.BR ferror () +tests the error indicator for the stream pointed to by +.IR stream , +returning nonzero if it is set. +The error indicator can be reset only by the +.BR clearerr () +function. +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR feof () +function returns nonzero if the end-of-file indicator is set for +.IR stream ; +otherwise, it returns zero. +.P +The +.BR ferror () +function returns nonzero if the error indicator is set for +.IR stream ; +otherwise, it returns zero. +.SH ERRORS +These functions should not fail and do not set +.IR errno . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR clearerr (), +.BR feof (), +.BR ferror () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH NOTES +POSIX.1-2008 specifies +.\"https://www.austingroupbugs.net/view.php?id=401 +that these functions shall not change the value of +.I errno +if +.I stream +is valid. +.SH CAVEATS +Normally, +programs should read the return value of an input function, +such as +.BR fgetc (3), +before using functions of the +.BR feof (3) +family. +Only when the function returned the sentinel value +.B EOF +it makes sense to distinguish between the end of a file or an error with +.BR feof (3) +or +.BR ferror (3). +.SH SEE ALSO +.BR open (2), +.BR fdopen (3), +.BR fileno (3), +.BR stdio (3), +.BR unlocked_stdio (3) diff --git a/man/man3/ferror_unlocked.3 b/man/man3/ferror_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/ferror_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fesetenv.3 b/man/man3/fesetenv.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fesetenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fesetexceptflag.3 b/man/man3/fesetexceptflag.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fesetexceptflag.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fesetround.3 b/man/man3/fesetround.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fesetround.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fetestexcept.3 b/man/man3/fetestexcept.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/fetestexcept.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/feupdateenv.3 b/man/man3/feupdateenv.3 new file mode 100644 index 0000000..47668e7 --- /dev/null +++ b/man/man3/feupdateenv.3 @@ -0,0 +1 @@ +.so man3/fenv.3 diff --git a/man/man3/fexecve.3 b/man/man3/fexecve.3 new file mode 100644 index 0000000..d040127 --- /dev/null +++ b/man/man3/fexecve.3 @@ -0,0 +1,172 @@ +'\" t +.\" Copyright (c) 2006, 2014, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fexecve 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fexecve \- execute program specified via file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fexecve(int " fd ", char *const " argv "[], char *const " envp []); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fexecve (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +.BR fexecve () +performs the same task as +.BR execve (2), +with the difference that the file to be executed +is specified via a file descriptor, +.IR fd , +rather than via a pathname. +The file descriptor +.I fd +must be opened read-only +.RB ( O_RDONLY ) +or with the +.B O_PATH +flag +and the caller must have permission to execute the file that it refers to. +.SH RETURN VALUE +A successful call to +.BR fexecve () +never returns. +On error, the function does return, with a result value of \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +Errors are as for +.BR execve (2), +with the following additions: +.TP +.B EINVAL +.I fd +is not a valid file descriptor, or +.I argv +is NULL, or +.I envp +is NULL. +.TP +.B ENOENT +The close-on-exec flag is set on +.IR fd , +and +.I fd +refers to a script. +See BUGS. +.TP +.B ENOSYS +The kernel does not provide the +.BR execveat (2) +system call, and the +.I /proc +filesystem could not be accessed. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fexecve () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3.2. +.P +On Linux with glibc versions 2.26 and earlier, +.BR fexecve () +is implemented using the +.BR proc (5) +filesystem, so +.I /proc +needs to be mounted and available at the time of the call. +Since glibc 2.27, +.\" glibc commit 43ffc53a352a67672210c9dd4959f6c6b7407e60 +if the underlying kernel supports the +.BR execveat (2) +system call, then +.BR fexecve () +is implemented using that system call, with the benefit that +.I /proc +does not need to be mounted. +.SH NOTES +The idea behind +.BR fexecve () +is to allow the caller to verify (checksum) the contents of +an executable before executing it. +Simply opening the file, checksumming the contents, and then doing an +.BR execve (2) +would not suffice, since, between the two steps, the filename, +or a directory prefix of the pathname, could have been exchanged +(by, for example, modifying the target of a symbolic link). +.BR fexecve () +does not mitigate the problem that the +.I contents +of a file could be changed between the checksumming and the call to +.BR fexecve (); +for that, the solution is to ensure that the permissions on the file +prevent it from being modified by malicious users. +.P +The natural idiom when using +.BR fexecve () +is to set the close-on-exec flag on +.IR fd , +so that the file descriptor does not leak through to the program +that is executed. +This approach is natural for two reasons. +First, it prevents file descriptors being consumed unnecessarily. +(The executed program normally has no need of a file descriptor +that refers to the program itself.) +Second, if +.BR fexecve () +is used recursively, +employing the close-on-exec flag prevents the file descriptor exhaustion +that would result from the fact that each step in the recursion would +cause one more file descriptor to be passed to the new program. +(But see BUGS.) +.SH BUGS +If +.I fd +refers to a script (i.e., it is an executable text file that names +a script interpreter with a first line that begins with the characters +.IR #! ) +and the close-on-exec flag has been set for +.IR fd , +then +.BR fexecve () +fails with the error +.BR ENOENT . +This error occurs because, +by the time the script interpreter is executed, +.I fd +has already been closed because of the close-on-exec flag. +Thus, the close-on-exec flag can't be set on +.I fd +if it refers to a script, leading to the problems described in NOTES. +.SH SEE ALSO +.BR execve (2), +.BR execveat (2) diff --git a/man/man3/fflush.3 b/man/man3/fflush.3 new file mode 100644 index 0000000..5670ba4 --- /dev/null +++ b/man/man3/fflush.3 @@ -0,0 +1,115 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fflush.3 5.4 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" +.\" Modified 2000-07-22 by Nicolás Lichtmaier +.\" Modified 2001-10-16 by John Levon +.\" +.TH fflush 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fflush \- flush a stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fflush(FILE *_Nullable " stream ); +.fi +.SH DESCRIPTION +For output streams, +.BR fflush () +forces a write of all user-space buffered data for the given output or update +.I stream +via the stream's underlying write function. +.P +For input streams associated with seekable files +(e.g., disk files, but not pipes or terminals), +.BR fflush () +discards any buffered data that has been fetched from the underlying file, +but has not been consumed by the application. +.P +The open status of the stream is unaffected. +.P +If the +.I stream +argument is NULL, +.BR fflush () +flushes +.I all +open output streams. +.\" mtk: POSIX specifies that only output streams are flushed for this case. +.\" Also verified for glibc by experiment. +.P +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +Upon successful completion 0 is returned. +Otherwise, +.B EOF +is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I stream +is not an open stream, or is not open for writing. +.P +The function +.BR fflush () +may also fail and set +.I errno +for any of the errors specified for +.BR write (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fflush () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001, POSIX.1-2008. +.P +POSIX.1-2001 did not specify the behavior for flushing of input streams, +but the behavior is specified in POSIX.1-2008. +.SH NOTES +Note that +.BR fflush () +flushes only the user-space buffers provided by the C library. +To ensure that the data is physically stored on disk +the kernel buffers must be flushed too, for example, with +.BR sync (2) +or +.BR fsync (2). +.SH SEE ALSO +.BR fsync (2), +.BR sync (2), +.BR write (2), +.BR fclose (3), +.BR fileno (3), +.BR fopen (3), +.BR fpurge (3), +.BR setbuf (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fflush_unlocked.3 b/man/man3/fflush_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fflush_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/ffs.3 b/man/man3/ffs.3 new file mode 100644 index 0000000..f3ce65e --- /dev/null +++ b/man/man3/ffs.3 @@ -0,0 +1,97 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:39:35 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.\" Modified 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH ffs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ffs, ffsl, ffsll \- find first bit set in a word +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int ffs(int " i ); +.BI "int ffsl(long " i ); +.BI "int ffsll(long long " i ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ffs (): +.nf + Since glibc 2.12: + _XOPEN_SOURCE >= 700 + || ! (_POSIX_C_SOURCE >= 200809L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE + Before glibc 2.12: + none +.fi +.P +.BR ffsl (), +.BR ffsll (): +.nf + Since glibc 2.27: +.\" glibc commit 68fe16dd327c895c08b9ee443b234c49c13b36e9 + _DEFAULT_SOURCE + Before glibc 2.27: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR ffs () +function returns the position of the first +(least significant) bit set in the word \fIi\fP. +The least significant bit is position 1 and the +most significant position is, for example, 32 or 64. +The functions +.BR ffsll () +and +.BR ffsl () +do the same but take +arguments of possibly different size. +.SH RETURN VALUE +These functions return the position of the first bit set, +or 0 if no bits are set in +.IR i . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ffs (), +.BR ffsl (), +.BR ffsll () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR ffs () +POSIX.1-2001, POSIX.1-2008, 4.3BSD. +.TP +.BR ffsl () +.TQ +.BR ffsll () +GNU. +.SH SEE ALSO +.BR memchr (3) diff --git a/man/man3/ffsl.3 b/man/man3/ffsl.3 new file mode 100644 index 0000000..23c4024 --- /dev/null +++ b/man/man3/ffsl.3 @@ -0,0 +1 @@ +.so man3/ffs.3 diff --git a/man/man3/ffsll.3 b/man/man3/ffsll.3 new file mode 100644 index 0000000..23c4024 --- /dev/null +++ b/man/man3/ffsll.3 @@ -0,0 +1 @@ +.so man3/ffs.3 diff --git a/man/man3/fgetc.3 b/man/man3/fgetc.3 new file mode 100644 index 0000000..0393712 --- /dev/null +++ b/man/man3/fgetc.3 @@ -0,0 +1,152 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl) +.TH fgetc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetc, fgets, getc, getchar, ungetc \- input of characters and strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fgetc(FILE *" stream ); +.BI "int getc(FILE *" stream ); +.B "int getchar(void);" +.P +.BI "char *fgets(char " s "[restrict ." size "], int " size ", \ +FILE *restrict " stream ); +.P +.BI "int ungetc(int " c ", FILE *" stream ); +.fi +.SH DESCRIPTION +.BR fgetc () +reads the next character from +.I stream +and returns it as an +.I unsigned char +cast to an +.IR int , +or +.B EOF +on end of file or error. +.P +.BR getc () +is equivalent to +.BR fgetc () +except that it may be implemented as a macro which evaluates +.I stream +more than once. +.P +.BR getchar () +is equivalent to +.BI "getc(" stdin ) \fR. +.P +.BR fgets () +reads in at most one less than +.I size +characters from +.I stream +and stores them into the buffer pointed to by +.IR s . +Reading stops after an +.B EOF +or a newline. +If a newline is read, it is stored into the buffer. +A terminating null byte (\[aq]\e0\[aq]) +is stored after the last character in the buffer. +.P +.BR ungetc () +pushes +.I c +back to +.IR stream , +cast to +.IR "unsigned char" , +where it is available for subsequent read operations. +Pushed-back characters +will be returned in reverse order; only one pushback is guaranteed. +.P +Calls to the functions described here can be mixed with each other and with +calls to other input functions from the +.I stdio +library for the same input stream. +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +.BR fgetc (), +.BR getc (), +and +.BR getchar () +return the character read as an +.I unsigned char +cast to an +.I int +or +.B EOF +on end of file or error. +.P +.BR fgets () +returns +.I s +on success, and NULL +on error or when end of file occurs while no characters have been read. +.P +.BR ungetc () +returns +.I c +on success, or +.B EOF +on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fgetc (), +.BR fgets (), +.BR getc (), +.BR getchar (), +.BR ungetc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH NOTES +It is not advisable to mix calls to input functions from the +.I stdio +library with low-level calls to +.BR read (2) +for the file descriptor associated with the input stream; the results +will be undefined and very probably not what you want. +.SH SEE ALSO +.BR read (2), +.BR write (2), +.BR ferror (3), +.BR fgetwc (3), +.BR fgetws (3), +.BR fopen (3), +.BR fread (3), +.BR fseek (3), +.BR getline (3), +.BR gets (3), +.BR getwchar (3), +.BR puts (3), +.BR scanf (3), +.BR ungetwc (3), +.BR unlocked_stdio (3), +.BR feature_test_macros (7) diff --git a/man/man3/fgetc_unlocked.3 b/man/man3/fgetc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fgetc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fgetgrent.3 b/man/man3/fgetgrent.3 new file mode 100644 index 0000000..b69572c --- /dev/null +++ b/man/man3/fgetgrent.3 @@ -0,0 +1,118 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:38:44 1993 by Rik Faith (faith@cs.unc.edu) +.TH fgetgrent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetgrent \- get group file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.BI "struct group *fgetgrent(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fgetgrent (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR fgetgrent () +function returns a pointer to a structure containing +the group information from the file referred to by +.IR stream . +The first time it is called +it returns the first entry; thereafter, it returns successive entries. +The file referred to by +.I stream +must have the same format as +.I /etc/group +(see +.BR group (5)). +.P +The \fIgroup\fP structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL\-terminated array of pointers + to names of group members */ +}; +.EE +.in +.SH RETURN VALUE +The +.BR fgetgrent () +function returns a pointer to a +.I group +structure, +or NULL if there are no more entries or an error occurs. +In the event of an error, +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate +.I group +structure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fgetgrent () +T} Thread safety MT-Unsafe race:fgetgrent +.TE +.\" FIXME The marking is different from that in the glibc manual, +.\" which has: +.\" +.\" fgetgrent: MT-Unsafe race:fgrent +.\" +.\" We think race:fgrent in glibc may be hard for users to understand, +.\" and have sent a patch to the GNU libc community for changing it to +.\" race:fgetgrent, however, something about the copyright impeded the +.\" progress. +.SH STANDARDS +None. +.SH HISTORY +SVr4. +.SH SEE ALSO +.BR endgrent (3), +.BR fgetgrent_r (3), +.BR fopen (3), +.BR getgrent (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR putgrent (3), +.BR setgrent (3), +.BR group (5) diff --git a/man/man3/fgetgrent_r.3 b/man/man3/fgetgrent_r.3 new file mode 100644 index 0000000..7c6dfe4 --- /dev/null +++ b/man/man3/fgetgrent_r.3 @@ -0,0 +1 @@ +.so man3/getgrent_r.3 diff --git a/man/man3/fgetpos.3 b/man/man3/fgetpos.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man/man3/fgetpos.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man/man3/fgetpwent.3 b/man/man3/fgetpwent.3 new file mode 100644 index 0000000..42dd016 --- /dev/null +++ b/man/man3/fgetpwent.3 @@ -0,0 +1,127 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sat Jul 24 19:37:37 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 22:40:48 1996 by Martin Schulze (joey@linux.de) +.\" +.TH fgetpwent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetpwent \- get password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.BI "struct passwd *fgetpwent(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fgetpwent (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR fgetpwent () +function returns a pointer to a structure containing +the broken out fields of a line in the file \fIstream\fP. +The first time it is called it returns the first entry; +thereafter, it returns successive entries. +The file referred to by +.I stream +must have the same format as +.I /etc/passwd +(see +.BR passwd (5)). +.P +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.SH RETURN VALUE +The +.BR fgetpwent () +function returns a pointer to a +.I passwd +structure, or NULL if +there are no more entries or an error occurs. +In the event of an error, +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate +.I passwd +structure. +.SH FILES +.TP +.I /etc/passwd +password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fgetpwent () +T} Thread safety MT-Unsafe race:fgetpwent +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" which has: +.\" +.\" fgetpwent: MT-Unsafe race:fpwent +.\" +.\" We think race:fpwent in glibc maybe hard for users to understand, +.\" and have sent a patch to the GNU libc community for changing it to +.\" race:fgetpwent, however, something about the copyright impeded the +.\" progress. +.SH STANDARDS +None. +.SH HISTORY +SVr4. +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent_r (3), +.BR fopen (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) diff --git a/man/man3/fgetpwent_r.3 b/man/man3/fgetpwent_r.3 new file mode 100644 index 0000000..b2393bb --- /dev/null +++ b/man/man3/fgetpwent_r.3 @@ -0,0 +1 @@ +.so man3/getpwent_r.3 diff --git a/man/man3/fgets.3 b/man/man3/fgets.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man/man3/fgets.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man/man3/fgets_unlocked.3 b/man/man3/fgets_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fgets_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fgetspent.3 b/man/man3/fgetspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/fgetspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/fgetspent_r.3 b/man/man3/fgetspent_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/fgetspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/fgetwc.3 b/man/man3/fgetwc.3 new file mode 100644 index 0000000..510a72d --- /dev/null +++ b/man/man3/fgetwc.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon +.TH fgetwc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetwc, getwc \- read a wide character from a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "wint_t fgetwc(FILE *" stream ); +.BI "wint_t getwc(FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR fgetwc () +function is the wide-character equivalent +of the +.BR fgetc (3) +function. +It reads a wide character from \fIstream\fP and returns it. +If the end of stream is reached, or if \fIferror(stream)\fP becomes true, +it returns +.BR WEOF . +If a wide-character conversion error occurs, it sets +\fIerrno\fP to \fBEILSEQ\fP and returns +.BR WEOF . +.P +The +.BR getwc () +function or macro functions identically to +.BR fgetwc (). +It may be implemented as a macro, and may evaluate its argument +more than once. +There is no reason ever to use it. +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +On success, +.BR fgetwc () +returns the next wide-character from the stream. +Otherwise, +.B WEOF +is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Apart from the usual ones, there is +.TP +.B EILSEQ +The data obtained from the input stream does not +form a valid character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fgetwc (), +.BR getwc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR fgetwc () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fgetwc () +will actually read a multibyte sequence +from the stream and then convert it to a wide character. +.SH SEE ALSO +.BR fgetws (3), +.BR fputwc (3), +.BR ungetwc (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fgetwc_unlocked.3 b/man/man3/fgetwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fgetwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fgetws.3 b/man/man3/fgetws.3 new file mode 100644 index 0000000..4d4f6e1 --- /dev/null +++ b/man/man3/fgetws.3 @@ -0,0 +1,91 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon +.TH fgetws 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetws \- read a wide-character string from a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *fgetws(wchar_t " ws "[restrict ." n "], int " n \ +", FILE *restrict " stream ); +.fi +.SH DESCRIPTION +The +.BR fgetws () +function is the wide-character equivalent +of the +.BR fgets (3) +function. +It reads a string of at most \fIn\-1\fP wide characters into the +wide-character array pointed to by \fIws\fP, +and adds a terminating null wide character (L\[aq]\e0\[aq]). +It stops reading wide characters after it has encountered and +stored a newline wide character. +It also stops when end of stream is reached. +.P +The programmer must ensure that there is room for at least \fIn\fP wide +characters at \fIws\fP. +.P +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR fgetws () +function, if successful, returns \fIws\fP. +If end of stream +was already reached or if an error occurred, it returns NULL. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fgetws () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR fgetws () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fgetws () +will actually read a multibyte string +from the stream and then convert it to a wide-character string. +.P +This function is unreliable, +because it does not permit to deal properly with +null wide characters that may be present in the input. +.SH SEE ALSO +.BR fgetwc (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fgetws_unlocked.3 b/man/man3/fgetws_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fgetws_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fileno.3 b/man/man3/fileno.3 new file mode 100644 index 0000000..81bafb7 --- /dev/null +++ b/man/man3/fileno.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" and Copyright (C) 2021 Michael Kerrisk +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu +.\" Added remark on EBADF for fileno, aeb, 2001-03-22 +.\" +.TH fileno 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fileno \- obtain file descriptor of a stdio stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fileno(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fileno (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The function +.BR fileno () +examines the argument +.I stream +and returns the integer file descriptor used to implement this stream. +The file descriptor is still owned by +.I stream +and will be closed when +.BR fclose (3) +is called. +Duplicate the file descriptor with +.BR dup (2) +before passing it to code that might close it. +.P +For the nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +On success, +.BR fileno () +returns the file descriptor associated with +.IR stream . +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I stream +is not associated with a file. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fileno () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR open (2), +.BR fdopen (3), +.BR stdio (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fileno_unlocked.3 b/man/man3/fileno_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fileno_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/finite.3 b/man/man3/finite.3 new file mode 100644 index 0000000..8cc426d --- /dev/null +++ b/man/man3/finite.3 @@ -0,0 +1,143 @@ +'\" t +.\" Copyright 2004 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH finite 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +finite, finitef, finitel, isinf, isinff, isinfl, isnan, isnanf, isnanl \- +BSD floating-point classification functions +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int finite(double " x ); +.BI "int finitef(float " x ); +.BI "int finitel(long double " x ); +.P +.BI "int isinf(double " x ); +.BI "int isinff(float " x ); +.BI "int isinfl(long double " x ); +.P +.BI "int isnan(double " x ); +.BI "int isnanf(float " x ); +.BI "int isnanl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR finite (), +.BR finitef (), +.BR finitel (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.P +.BR isinf (): + _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR isinff (), +.BR isinfl (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR isnan (): +.nf + _XOPEN_SOURCE || _ISOC99_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR isnanf (), +.BR isnanl (): +.nf + _XOPEN_SOURCE >= 600 + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR finite (), +.BR finitef (), +and +.BR finitel () +functions return a nonzero value if +.I x +is neither infinite +nor a "not-a-number" (NaN) value, and 0 otherwise. +.P +The +.BR isnan (), +.BR isnanf (), +and +.BR isnanl () +functions return a nonzero value if +.I x +is a NaN value, +and 0 otherwise. +.P +The +.BR isinf (), +.BR isinff (), +and +.BR isinfl () +functions return 1 if +.I x +is positive infinity, \-1 if +.I x +is negative infinity, and 0 otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR finite (), +.BR finitef (), +.BR finitel (), +.BR isinf (), +.BR isinff (), +.BR isinfl (), +.BR isnan (), +.BR isnanf (), +.BR isnanl () +T} Thread safety MT-Safe +.TE +.SH NOTES +Note that these functions are obsolete. +C99 defines macros +.BR isfinite (), +.BR isinf (), +and +.BR isnan () +(for all types) replacing them. +Further note that the C99 +.BR isinf () +has weaker guarantees on the return value. +See +.BR fpclassify (3). +.\" +.\" finite* not on HP-UX; they exist on Tru64. +.\" .SH HISTORY +.\" The +.\" .BR finite () +.\" function occurs in 4.3BSD. +.\" see IEEE.3 in the 4.3BSD manual +.SH SEE ALSO +.BR fpclassify (3) diff --git a/man/man3/finitef.3 b/man/man3/finitef.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/finitef.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/finitel.3 b/man/man3/finitel.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/finitel.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/flockfile.3 b/man/man3/flockfile.3 new file mode 100644 index 0000000..325a676 --- /dev/null +++ b/man/man3/flockfile.3 @@ -0,0 +1,133 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH flockfile 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +flockfile, ftrylockfile, funlockfile \- lock FILE for stdio +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void flockfile(FILE *" filehandle ); +.BI "int ftrylockfile(FILE *" filehandle ); +.BI "void funlockfile(FILE *" filehandle ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.nf + /* Since glibc 2.24: */ _POSIX_C_SOURCE >= 199309L + || /* glibc <= 2.23: */ _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The stdio functions are thread-safe. +This is achieved by assigning +to each +.I FILE +object a lockcount and (if the lockcount is nonzero) +an owning thread. +For each library call, these functions wait until the +.I FILE +object +is no longer locked by a different thread, then lock it, do the +requested I/O, and unlock the object again. +.P +(Note: this locking has nothing to do with the file locking done +by functions like +.BR flock (2) +and +.BR lockf (3).) +.P +All this is invisible to the C-programmer, but there may be two +reasons to wish for more detailed control. +On the one hand, maybe +a series of I/O actions by one thread belongs together, and should +not be interrupted by the I/O of some other thread. +On the other hand, maybe the locking overhead should be avoided +for greater efficiency. +.P +To this end, a thread can explicitly lock the +.I FILE +object, +then do its series of I/O actions, then unlock. +This prevents +other threads from coming in between. +If the reason for doing +this was to achieve greater efficiency, one does the I/O with +the nonlocking versions of the stdio functions: with +.BR getc_unlocked (3) +and +.BR putc_unlocked (3) +instead of +.BR getc (3) +and +.BR putc (3). +.P +The +.BR flockfile () +function waits for +.I *filehandle +to be +no longer locked by a different thread, then makes the +current thread owner of +.IR *filehandle , +and increments +the lockcount. +.P +The +.BR funlockfile () +function decrements the lock count. +.P +The +.BR ftrylockfile () +function is a nonblocking version +of +.BR flockfile (). +It does nothing in case some other thread +owns +.IR *filehandle , +and it obtains ownership and increments +the lockcount otherwise. +.SH RETURN VALUE +The +.BR ftrylockfile () +function returns zero for success +(the lock was obtained), and nonzero for failure. +.SH ERRORS +None. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR flockfile (), +.BR ftrylockfile (), +.BR funlockfile () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +These functions are available when +.B _POSIX_THREAD_SAFE_FUNCTIONS +is defined. +.SH SEE ALSO +.BR unlocked_stdio (3) diff --git a/man/man3/floor.3 b/man/man3/floor.3 new file mode 100644 index 0000000..88d8503 --- /dev/null +++ b/man/man3/floor.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH floor 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +floor, floorf, floorl \- largest integral value not greater than argument +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double floor(double " x ); +.BI "float floorf(float " x ); +.BI "long double floorl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR floorf (), +.BR floorl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the largest integral value that is not greater than +.IR x . +.P +For example, +.I floor(0.5) +is 0.0, and +.I floor(\-0.5) +is \-1.0. +.SH RETURN VALUE +These functions return the floor of +.IR x . +.P +If +.I x +is integral, +0, \-0, NaN, or an infinity, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR floor (), +.BR floorf (), +.BR floorl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.P +SUSv2 and POSIX.1-2001 contain text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +.\" The POSIX.1-2001 APPLICATION USAGE SECTION discusses this point. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 127 (respectively, 1023), +and the number of mantissa bits +including the implicit bit +is 24 (respectively, 53).) +.SH SEE ALSO +.BR ceil (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3), +.BR trunc (3) diff --git a/man/man3/floorf.3 b/man/man3/floorf.3 new file mode 100644 index 0000000..1d8e79b --- /dev/null +++ b/man/man3/floorf.3 @@ -0,0 +1 @@ +.so man3/floor.3 diff --git a/man/man3/floorl.3 b/man/man3/floorl.3 new file mode 100644 index 0000000..1d8e79b --- /dev/null +++ b/man/man3/floorl.3 @@ -0,0 +1 @@ +.so man3/floor.3 diff --git a/man/man3/fma.3 b/man/man3/fma.3 new file mode 100644 index 0000000..ecf1140 --- /dev/null +++ b/man/man3/fma.3 @@ -0,0 +1,167 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Modified 2004-11-15, Added further text on FLT_ROUNDS +.\" as suggested by AEB and Fabian Kreutz +.\" +.TH fma 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fma, fmaf, fmal \- floating-point multiply and add +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double fma(double " x ", double " y ", double " z ); +.BI "float fmaf(float " x ", float " y ", float " z ); +.BI "long double fmal(long double " x ", long double " y ", long double " z ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fma (), +.BR fmaf (), +.BR fmal (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions compute +.IR x " * " y " + " z . +The result is rounded as one ternary operation according to the +current rounding mode (see +.BR fenv (3)). +.SH RETURN VALUE +These functions return the value of +.IR x " * " y " + " z , +rounded as one ternary operation. +.P +If +.I x +or +.I y +is a NaN, a NaN is returned. +.P +If +.I x +times +.I y +is an exact infinity, and +.I z +is an infinity with the opposite sign, +a domain error occurs, +and a NaN is returned. +.P +.\" POSIX.1-2008 allows some possible differences for the following two +.\" domain error cases, but on Linux they are treated the same (AFAICS). +.\" Nevertheless, we'll mirror POSIX.1 and describe the two cases +.\" separately. +If one of +.I x +or +.I y +is an infinity, the other is 0, and +.I z +is not a NaN, +a domain error occurs, and +a NaN is returned. +.\" POSIX.1 says that a NaN or an implementation-defined value shall +.\" be returned for this case. +.P +If one of +.I x +or +.I y +is an infinity, and the other is 0, and +.I z +is a NaN, +.\" POSIX.1 makes the domain error optional for this case. +a domain error occurs, and +a NaN is returned. +.P +If +.I x +times +.I y +is not an infinity times zero (or vice versa), and +.I z +is a NaN, +a NaN is returned. +.P +If the result overflows, +a range error occurs, and +an infinity with the correct sign is returned. +.P +If the result underflows, +a range error occurs, and +a signed 0 is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP * \fIy\fP + \fIz\fP, \ +or \fIx\fP * \fIy\fP is invalid and \fIz\fP is not a NaN +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Range error: result overflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: result underflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.P +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6801 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fma (), +.BR fmaf (), +.BR fmal () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR remainder (3), +.BR remquo (3) diff --git a/man/man3/fmaf.3 b/man/man3/fmaf.3 new file mode 100644 index 0000000..e050da0 --- /dev/null +++ b/man/man3/fmaf.3 @@ -0,0 +1 @@ +.so man3/fma.3 diff --git a/man/man3/fmal.3 b/man/man3/fmal.3 new file mode 100644 index 0000000..e050da0 --- /dev/null +++ b/man/man3/fmal.3 @@ -0,0 +1 @@ +.so man3/fma.3 diff --git a/man/man3/fmax.3 b/man/man3/fmax.3 new file mode 100644 index 0000000..9a388c7 --- /dev/null +++ b/man/man3/fmax.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH fmax 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fmax, fmaxf, fmaxl \- determine maximum of two floating-point numbers +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double fmax(double " x ", double " y ); +.BI "float fmaxf(float " x ", float " y ); +.BI "long double fmaxl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fmax (), +.BR fmaxf (), +.BR fmaxl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return the larger value of +.I x +and +.IR y . +.SH RETURN VALUE +These functions return the maximum of +.I x +and +.IR y . +.P +If one argument is a NaN, the other argument is returned. +.P +If both arguments are NaN, a NaN is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmax (), +.BR fmaxf (), +.BR fmaxl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR fdim (3), +.BR fmin (3) diff --git a/man/man3/fmaxf.3 b/man/man3/fmaxf.3 new file mode 100644 index 0000000..5f68a86 --- /dev/null +++ b/man/man3/fmaxf.3 @@ -0,0 +1 @@ +.so man3/fmax.3 diff --git a/man/man3/fmaxl.3 b/man/man3/fmaxl.3 new file mode 100644 index 0000000..5f68a86 --- /dev/null +++ b/man/man3/fmaxl.3 @@ -0,0 +1 @@ +.so man3/fmax.3 diff --git a/man/man3/fmemopen.3 b/man/man3/fmemopen.3 new file mode 100644 index 0000000..eb68fd3 --- /dev/null +++ b/man/man3/fmemopen.3 @@ -0,0 +1,352 @@ +'\" t +.\" Copyright 2005, 2012, 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH fmemopen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fmemopen \- open memory as stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "FILE *fmemopen(void " buf [. size "], size_t " size ", \ +const char *" mode ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fmemopen (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR fmemopen () +function opens a stream that permits the access specified by +.IR mode . +The stream allows I/O to be performed on the string or memory buffer +pointed to by +.IR buf . +.P +The +.I mode +argument specifies the semantics of I/O on the stream, +and is one of the following: +.TP +.I r +The stream is opened for reading. +.TP +.I w +The stream is opened for writing. +.TP +.I a +Append; open the stream for writing, +with the initial buffer position set to the first null byte. +.TP +.I r+ +Open the stream for reading and writing. +.TP +.I w+ +Open the stream for reading and writing. +The buffer contents are truncated +(i.e., \[aq]\e0\[aq] is placed in the first byte of the buffer). +.TP +.I a+ +Append; open the stream for reading and writing, +with the initial buffer position set to the first null byte. +.P +The stream maintains the notion of a current position, +the location where the next I/O operation will be performed. +The current position is implicitly updated by I/O operations. +It can be explicitly updated using +.BR fseek (3), +and determined using +.BR ftell (3). +In all modes other than append, +the initial position is set to the start of the buffer. +In append mode, if no null byte is found within the buffer, +then the initial position is +.IR size+1 . +.P +If +.I buf +is specified as NULL, then +.BR fmemopen () +allocates a buffer of +.I size +bytes. +This is useful for an application that wants to write data to +a temporary buffer and then read it back again. +The initial position is set to the start of the buffer. +The buffer is automatically freed when the stream is closed. +Note that the caller has no way to obtain a pointer to the +temporary buffer allocated by this call (but see +.BR open_memstream (3)). +.P +If +.I buf +is not NULL, then it should point to a buffer of at least +.I size +bytes allocated by the caller. +.P +When a stream that has been opened for writing is flushed +.RB ( fflush (3)) +or closed +.RB ( fclose (3)), +a null byte is written at the end of the buffer if there is space. +The caller should ensure that an extra byte is available in the +buffer +(and that +.I size +counts that byte) +to allow for this. +.P +In a stream opened for reading, +null bytes (\[aq]\e0\[aq]) in the buffer do not cause read +operations to return an end-of-file indication. +A read from the buffer will indicate end-of-file +only when the current buffer position advances +.I size +bytes past the start of the buffer. +.P +Write operations take place either at the current position +(for modes other than append), or at the current size of the stream +(for append modes). +.P +Attempts to write more than +.I size +bytes to the buffer result in an error. +By default, such errors will be visible +(by the absence of data) only when the +.I stdio +buffer is flushed. +Disabling buffering with the following call +may be useful to detect errors at the time of an output operation: +.P +.in +4n +.EX +setbuf(stream, NULL); +.EE +.in +.SH RETURN VALUE +Upon successful completion, +.BR fmemopen () +returns a +.I FILE +pointer. +Otherwise, NULL is returned and +.I errno +is set to indicate the error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmemopen (), +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 1.0.x. +POSIX.1-2008. +.P +POSIX.1-2008 specifies that \[aq]b\[aq] in +.I mode +shall be ignored. +However, Technical Corrigendum 1 +.\" http://austingroupbugs.net/view.php?id=396 +adjusts the standard to allow implementation-specific treatment for this case, +thus permitting the glibc treatment of \[aq]b\[aq]. +.P +With glibc 2.22, binary mode (see below) was removed, +many longstanding bugs in the implementation of +.BR fmemopen () +were fixed, and a new versioned symbol was created for this interface. +.\" +.SS Binary mode +From glibc 2.9 to glibc 2.21, the glibc implementation of +.BR fmemopen () +supported a "binary" mode, +enabled by specifying the letter \[aq]b\[aq] as the second character in +.IR mode . +In this mode, +writes don't implicitly add a terminating null byte, and +.BR fseek (3) +.B SEEK_END +is relative to the end of the buffer (i.e., the value specified by the +.I size +argument), rather than the current string length. +.P +An API bug afflicted the implementation of binary mode: +to specify binary mode, the \[aq]b\[aq] must be the +.I second +character in +.IR mode . +Thus, for example, "wb+" has the desired effect, but "w+b" does not. +This is inconsistent with the treatment of +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12836 +.I mode +by +.BR fopen (3). +.P +Binary mode was removed in glibc 2.22; a \[aq]b\[aq] specified in +.I mode +has no effect. +.SH NOTES +There is no file descriptor associated with the file stream +returned by this function +(i.e., +.BR fileno (3) +will return an error if called on the returned stream). +.SH BUGS +Before glibc 2.22, if +.I size +is specified as zero, +.BR fmemopen () +fails with the error +.BR EINVAL . +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=11216 +It would be more consistent if this case successfully created +a stream that then returned end-of-file on the first attempt at reading; +since glibc 2.22, the glibc implementation provides that behavior. +.P +Before glibc 2.22, +specifying append mode ("a" or "a+") for +.BR fmemopen () +sets the initial buffer position to the first null byte, but +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=13152 +(if the current position is reset to a location other than +the end of the stream) +does not force subsequent writes to append at the end of the stream. +This bug is fixed in glibc 2.22. +.P +Before glibc 2.22, if the +.I mode +argument to +.BR fmemopen () +specifies append ("a" or "a+"), and the +.I size +argument does not cover a null byte in +.IR buf , +then, according to POSIX.1-2008, +the initial buffer position should be set to +the next byte after the end of the buffer. +However, in this case the glibc +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=13151 +.BR fmemopen () +sets the buffer position to \-1. +This bug is fixed in glibc 2.22. +.P +Before glibc 2.22, +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14292 +when a call to +.BR fseek (3) +with a +.I whence +value of +.B SEEK_END +was performed on a stream created by +.BR fmemopen (), +the +.I offset +was +.I subtracted +from the end-of-stream position, instead of being added. +This bug is fixed in glibc 2.22. +.P +The glibc 2.9 addition of "binary" mode for +.BR fmemopen () +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544 +silently changed the ABI: previously, +.BR fmemopen () +ignored \[aq]b\[aq] in +.IR mode . +.SH EXAMPLES +The program below uses +.BR fmemopen () +to open an input buffer, and +.BR open_memstream (3) +to open a dynamically sized output buffer. +The program scans its input string (taken from the program's +first command-line argument) reading integers, +and writes the squares of these integers to the output buffer. +An example of the output produced by this program is the following: +.P +.in +4n +.EX +.RB "$" " ./a.out \[aq]1 23 43\[aq]" +size=11; ptr=1 529 1849 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (fmemopen.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + FILE *out, *in; + int v, s; + size_t size; + char *ptr; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \[aq]...\[aq]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + in = fmemopen(argv[1], strlen(argv[1]), "r"); + if (in == NULL) + err(EXIT_FAILURE, "fmemopen"); +\& + out = open_memstream(&ptr, &size); + if (out == NULL) + err(EXIT_FAILURE, "open_memstream"); +\& + for (;;) { + s = fscanf(in, "%d", &v); + if (s <= 0) + break; +\& + s = fprintf(out, "%d ", v * v); + if (s == \-1) + err(EXIT_FAILURE, "fprintf"); + } +\& + fclose(in); + fclose(out); +\& + printf("size=%zu; ptr=%s\en", size, ptr); +\& + free(ptr); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fopen (3), +.BR fopencookie (3), +.BR open_memstream (3) diff --git a/man/man3/fmin.3 b/man/man3/fmin.3 new file mode 100644 index 0000000..45b83de --- /dev/null +++ b/man/man3/fmin.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH fmin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fmin, fminf, fminl \- determine minimum of two floating-point numbers +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double fmin(double " x ", double " y ); +.BI "float fminf(float " x ", float " y ); +.BI "long double fminl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fmin (), +.BR fminf (), +.BR fminl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return the lesser value of +.I x +and +.IR y . +.SH RETURN VALUE +These functions return the minimum of +.I x +and +.IR y . +.P +If one argument is a NaN, the other argument is returned. +.P +If both arguments are NaN, a NaN is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmin (), +.BR fminf (), +.BR fminl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR fdim (3), +.BR fmax (3) diff --git a/man/man3/fminf.3 b/man/man3/fminf.3 new file mode 100644 index 0000000..a86d77d --- /dev/null +++ b/man/man3/fminf.3 @@ -0,0 +1 @@ +.so man3/fmin.3 diff --git a/man/man3/fminl.3 b/man/man3/fminl.3 new file mode 100644 index 0000000..a86d77d --- /dev/null +++ b/man/man3/fminl.3 @@ -0,0 +1 @@ +.so man3/fmin.3 diff --git a/man/man3/fmod.3 b/man/man3/fmod.3 new file mode 100644 index 0000000..211b2f8 --- /dev/null +++ b/man/man3/fmod.3 @@ -0,0 +1,183 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH fmod 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fmod, fmodf, fmodl \- floating-point remainder function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double fmod(double " x ", double " y ); +.BI "float fmodf(float " x ", float " y ); +.BI "long double fmodl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fmodf (), +.BR fmodl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions compute the floating-point remainder of dividing +.I x +by +.IR y . +The return value is +.I x +\- +.I n +* +.IR y , +where +.I n +is the quotient of +.I x +/ +.IR y , +rounded toward zero to an integer. +.P +To obtain the modulus, more specifically, the Least Positive Residue, +you will need to adjust the result from fmod like so: +.P +.in +4n +.nf +z = fmod(x, y); +if (z < 0) + z += y; +.fi +.in +.P +An alternate way to express this is with +.IR "fmod(fmod(x, y) + y, y)" , +but the second +.BR fmod () +usually costs way more than the one branch. +.SH RETURN VALUE +On success, these +functions return the value \fIx\fP\ \-\ \fIn\fP*\fIy\fP, +for some integer +.IR n , +such that the returned value has the same sign as +.I x +and a magnitude less than the magnitude of +.IR y . +.P +If +.I x +or +.I y +is a NaN, a NaN is returned. +.P +If +.I x +is an infinity, +a domain error occurs, and +a NaN is returned. +.P +If +.I y +is zero, +a domain error occurs, and +a NaN is returned. +.P +If +.I x +is +0 (\-0), and +.I y +is not zero, +0 (\-0) is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Domain error: \fIy\fP is zero +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.\" POSIX.1 documents an optional underflow error, but AFAICT it doesn't +.\" (can't?) occur -- mtk, Jul 2008 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmod (), +.BR fmodf (), +.BR fmodl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +Before glibc 2.10, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6784 +.I errno +to +.B EDOM +when a domain error occurred for an infinite +.IR x . +.SH EXAMPLES +The call +.I fmod(372, 360) +returns 348. +.P +The call +.I fmod(-372, 360) +returns -12. +.P +The call +.I fmod(-372, -360) +also returns -12. +.SH SEE ALSO +.BR remainder (3) diff --git a/man/man3/fmodf.3 b/man/man3/fmodf.3 new file mode 100644 index 0000000..d014cc0 --- /dev/null +++ b/man/man3/fmodf.3 @@ -0,0 +1 @@ +.so man3/fmod.3 diff --git a/man/man3/fmodl.3 b/man/man3/fmodl.3 new file mode 100644 index 0000000..d014cc0 --- /dev/null +++ b/man/man3/fmodl.3 @@ -0,0 +1 @@ +.so man3/fmod.3 diff --git a/man/man3/fmtmsg.3 b/man/man3/fmtmsg.3 new file mode 100644 index 0000000..b4fc2cc --- /dev/null +++ b/man/man3/fmtmsg.3 @@ -0,0 +1,337 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" adapted glibc info page +.\" +.\" This should run as 'Guru Meditation' (amiga joke :) +.\" The function is quite complex and deserves an example +.\" +.\" Polished, aeb, 2003-11-01 +.TH fmtmsg 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fmtmsg \- print formatted error messages +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fmtmsg(long " classification ", const char *" label , +.BI " int " severity ", const char *" text , +.BI " const char *" action ", const char *" tag ); +.fi +.SH DESCRIPTION +This function displays a message described by its arguments on the device(s) +specified in the +.I classification +argument. +For messages written to +.IR stderr , +the format depends on the +.B MSGVERB +environment variable. +.P +The +.I label +argument identifies the source of the message. +The string must consist +of two colon separated parts where the first part has not more +than 10 and the second part not more than 14 characters. +.P +The +.I text +argument describes the condition of the error. +.P +The +.I action +argument describes possible steps to recover from the error. +If it is printed, it is prefixed by "TO FIX: ". +.P +The +.I tag +argument is a reference to the online documentation where more +information can be found. +It should contain the +.I label +value and a unique identification number. +.SS Dummy arguments +Each of the arguments can have a dummy value. +The dummy classification value +.B MM_NULLMC +(0L) does not specify any output, so nothing is printed. +The dummy severity value +.B NO_SEV +(0) says that no severity is supplied. +The values +.BR MM_NULLLBL , +.BR MM_NULLTXT , +.BR MM_NULLACT , +.B MM_NULLTAG +are synonyms for +.IR "((char\ *)\ 0)" , +the empty string, and +.B MM_NULLSEV +is a synonym for +.BR NO_SEV . +.SS The classification argument +The +.I classification +argument is the sum of values describing 4 types of information. +.P +The first value defines the output channel. +.TP 12n +.B MM_PRINT +Output to +.IR stderr . +.TP +.B MM_CONSOLE +Output to the system console. +.TP +.B "MM_PRINT | MM_CONSOLE" +Output to both. +.P +The second value is the source of the error: +.TP 12n +.B MM_HARD +A hardware error occurred. +.TP +.B MM_FIRM +A firmware error occurred. +.TP +.B MM_SOFT +A software error occurred. +.P +The third value encodes the detector of the problem: +.TP 12n +.B MM_APPL +It is detected by an application. +.TP +.B MM_UTIL +It is detected by a utility. +.TP +.B MM_OPSYS +It is detected by the operating system. +.P +The fourth value shows the severity of the incident: +.TP 12n +.B MM_RECOVER +It is a recoverable error. +.TP +.B MM_NRECOV +It is a nonrecoverable error. +.SS The severity argument +The +.I severity +argument can take one of the following values: +.TP 12n +.B MM_NOSEV +No severity is printed. +.TP +.B MM_HALT +This value is printed as HALT. +.TP +.B MM_ERROR +This value is printed as ERROR. +.TP +.B MM_WARNING +This value is printed as WARNING. +.TP +.B MM_INFO +This value is printed as INFO. +.P +The numeric values are between 0 and 4. +Using +.BR addseverity (3) +or the environment variable +.B SEV_LEVEL +you can add more levels and strings to print. +.SH RETURN VALUE +The function can return 4 values: +.TP 12n +.B MM_OK +Everything went smooth. +.TP +.B MM_NOTOK +Complete failure. +.TP +.B MM_NOMSG +Error writing to +.IR stderr . +.TP +.B MM_NOCON +Error writing to the console. +.SH ENVIRONMENT +The environment variable +.B MSGVERB +("message verbosity") can be used to suppress parts of +the output to +.IR stderr . +(It does not influence output to the console.) +When this variable is defined, is non-NULL, and is a colon-separated +list of valid keywords, then only the parts of the message corresponding +to these keywords is printed. +Valid keywords are "label", "severity", "text", "action", and "tag". +.P +The environment variable +.B SEV_LEVEL +can be used to introduce new severity levels. +By default, only the five severity levels described +above are available. +Any other numeric value would make +.BR fmtmsg () +print nothing. +If the user puts +.B SEV_LEVEL +with a format like +.P +.RS +SEV_LEVEL=[description[:description[:...]]] +.RE +.P +in the environment of the process before the first call to +.BR fmtmsg (), +where each description is of the form +.P +.RS +severity-keyword,level,printstring +.RE +.P +then +.BR fmtmsg () +will also accept the indicated values for the level (in addition to +the standard levels 0\[en]4), and use the indicated printstring when +such a level occurs. +.P +The severity-keyword part is not used by +.BR fmtmsg () +but it has to be present. +The level part is a string representation of a number. +The numeric value must be a number greater than 4. +This value must be used in the severity argument of +.BR fmtmsg () +to select this class. +It is not possible to overwrite +any of the predefined classes. +The printstring +is the string printed when a message of this class is processed by +.BR fmtmsg (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fmtmsg () +T} Thread safety T{ +.na +.nh +glibc\ >=\ 2.16: MT-Safe; +glibc\ <\ 2.16: MT-Unsafe +T} +.TE +.P +Before glibc 2.16, the +.BR fmtmsg () +function uses a static variable that is not protected, +so it is not thread-safe. +.P +Since glibc 2.16, +.\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94 +the +.BR fmtmsg () +function uses a lock to protect the static variable, so it is thread-safe. +.SH STANDARDS +.TP +.BR fmtmsg () +.TQ +.B MSGVERB +POSIX.1-2008. +.SH HISTORY +.TP +.BR fmtmsg () +System V. +POSIX.1-2001 and POSIX.1-2008. +glibc 2.1. +.TP +.B MSGVERB +System V. +POSIX.1-2001 and POSIX.1-2008. +.TP +.B SEV_LEVEL +System V. +.P +System V and UnixWare man pages tell us that these functions +have been replaced by "pfmt() and addsev()" or by "pfmt(), +vpfmt(), lfmt(), and vlfmt()", and will be removed later. +.SH EXAMPLES +.\" SRC BEGIN (fmtmsg.c) +.EX +#include +#include +#include +\& +int +main(void) +{ + long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER; + int err; +\& + err = fmtmsg(class, "util\-linux:mount", MM_ERROR, + "unknown mount option", "See mount(8).", + "util\-linux:mount:017"); + switch (err) { + case MM_OK: + break; + case MM_NOTOK: + printf("Nothing printed\en"); + break; + case MM_NOMSG: + printf("Nothing printed to stderr\en"); + break; + case MM_NOCON: + printf("No console output\en"); + break; + default: + printf("Unknown error from fmtmsg()\en"); + } + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.P +The output should be: +.P +.in +4n +.EX +util\-linux:mount: ERROR: unknown mount option +TO FIX: See mount(8). util\-linux:mount:017 +.EE +.in +.P +and after +.P +.in +4n +.EX +MSGVERB=text:action; export MSGVERB +.EE +.in +.P +the output becomes: +.P +.in +4n +.EX +unknown mount option +TO FIX: See mount(8). +.EE +.in +.SH SEE ALSO +.BR addseverity (3), +.BR perror (3) diff --git a/man/man3/fnmatch.3 b/man/man3/fnmatch.3 new file mode 100644 index 0000000..c359a1d --- /dev/null +++ b/man/man3/fnmatch.3 @@ -0,0 +1,141 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:35:54 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Oct 16 00:16:29 2000 following Joseph S. Myers +.\" +.TH fnmatch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fnmatch \- match filename or pathname +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fnmatch(const char *" "pattern" ", const char *" string ", int " flags ); +.fi +.SH DESCRIPTION +The +.BR fnmatch () +function checks whether the +.I string +argument matches the +.I pattern +argument, which is a shell wildcard pattern (see +.BR glob (7)). +.P +The +.I flags +argument modifies the behavior; it is the bitwise OR of zero or more +of the following flags: +.TP +.B FNM_NOESCAPE +If this flag is set, treat backslash as an ordinary character, +instead of an escape character. +.TP +.B FNM_PATHNAME +If this flag is set, match a slash in +.I string +only with a slash in +.I pattern +and not by an asterisk (*) or a question mark (?) metacharacter, +nor by a bracket expression ([]) containing a slash. +.TP +.B FNM_PERIOD +If this flag is set, a leading period in +.I string +has to be matched exactly by a period in +.IR pattern . +A period is considered to be leading if it is the first character in +.IR string , +or if both +.B FNM_PATHNAME +is set and the period immediately follows a slash. +.TP +.B FNM_FILE_NAME +This is a GNU synonym for +.BR FNM_PATHNAME . +.TP +.B FNM_LEADING_DIR +If this flag (a GNU extension) is set, the pattern is considered to be +matched if it matches an initial segment of +.I string +which is followed by a slash. +This flag is mainly for the internal +use of glibc and is implemented only in certain cases. +.TP +.B FNM_CASEFOLD +If this flag (a GNU extension) is set, the pattern is matched +case-insensitively. +.TP +.B FNM_EXTMATCH +If this flag (a GNU extension) is set, extended patterns are +supported, as introduced by \&'ksh' and now supported by other shells. +The extended format is as follows, with \fIpattern\-list\fR +being a \&'|' separated list of patterns. +.TP +\&'?(\fIpattern\-list\fR)' +The pattern matches if zero or one occurrences of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'*(\fIpattern\-list\fR)' +The pattern matches if zero or more occurrences of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'+(\fIpattern\-list\fR)' +The pattern matches if one or more occurrences of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'@(\fIpattern\-list\fR)' +The pattern matches if exactly one occurrence of any of the +patterns in the \fIpattern\-list\fR match the input \fIstring\fR. +.TP +\&'!(\fIpattern\-list\fR)' +The pattern matches if the input \fIstring\fR cannot be matched with +any of the patterns in the \fIpattern\-list\fR. +.SH RETURN VALUE +Zero if +.I string +matches +.IR pattern , +.B FNM_NOMATCH +if there is no match or another nonzero value if there is an error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fnmatch () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +.TP +.BR fnmatch () +POSIX.1-2008. +.TP +.B FNM_FILE_NAME +.TQ +.B FNM_LEADING_DIR +.TQ +.B FNM_CASEFOLD +GNU. +.SH HISTORY +.TP +.BR fnmatch () +POSIX.1-2001, POSIX.2. +.SH SEE ALSO +.BR sh (1), +.BR glob (3), +.BR scandir (3), +.BR wordexp (3), +.BR glob (7) diff --git a/man/man3/fopen.3 b/man/man3/fopen.3 new file mode 100644 index 0000000..bf09c62 --- /dev/null +++ b/man/man3/fopen.3 @@ -0,0 +1,405 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fopen.3 6.8 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" Modified, aeb, 960421, 970806 +.\" Modified, joey, aeb, 2002-01-03 +.\" +.TH fopen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fopen, fdopen, freopen \- stream open functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "FILE *fopen(const char *restrict " pathname \ +", const char *restrict " mode ); +.BI "FILE *fdopen(int " fd ", const char *" mode ); +.BI "FILE *freopen(const char *restrict " pathname \ +", const char *restrict " mode , +.BI " FILE *restrict " stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fdopen (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR fopen () +function opens the file whose name is the string pointed to by +.I pathname +and associates a stream with it. +.P +The argument +.I mode +points to a string beginning with one of the following sequences +(possibly followed by additional characters, as described below): +.TP +.B r +Open text file for reading. +The stream is positioned at the beginning of the file. +.TP +.B r+ +Open for reading and writing. +The stream is positioned at the beginning of the file. +.TP +.B w +Truncate file to zero length or create text file for writing. +The stream is positioned at the beginning of the file. +.TP +.B w+ +Open for reading and writing. +The file is created if it does not exist, otherwise it is truncated. +The stream is positioned at the beginning of +the file. +.TP +.B a +Open for appending (writing at end of file). +The file is created if it does not exist. +The stream is positioned at the end of the file. +.TP +.B a+ +Open for reading and appending (writing at end of file). +The file is created if it does not exist. +Output is always appended to the end of the file. +POSIX is silent on what the initial read position is when using this mode. +For glibc, the initial file position for reading is at +the beginning of the file, but for Android/BSD/MacOS, the +initial file position for reading is at the end of the file. +.P +The +.I mode +string can also include the letter \[aq]b\[aq] either as a last character or as +a character between the characters in any of the two-character strings +described above. +This is strictly for compatibility with ISO C +and has no effect; the \[aq]b\[aq] is ignored on all POSIX +conforming systems, including Linux. +(Other systems may treat text files and binary files differently, +and adding the \[aq]b\[aq] may be a good idea if you do I/O to a binary +file and expect that your program may be ported to non-UNIX +environments.) +.P +See NOTES below for details of glibc extensions for +.IR mode . +.P +Any created file will have the mode +.BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH +(0666), as modified by the process's umask value (see +.BR umask (2)). +.P +Reads and writes may be intermixed on read/write streams in any order. +Note that ANSI C requires that a file positioning function intervene +between output and input, unless an input operation encounters end-of-file. +(If this condition is not met, then a read is allowed to return the +result of writes other than the most recent.) +Therefore it is good practice (and indeed sometimes necessary +under Linux) to put an +.BR fseek (3) +or +.BR fsetpos (3) +operation between write and read operations on such a stream. +This operation may be an apparent no-op +(as in \fIfseek(..., 0L, SEEK_CUR)\fP +called for its synchronizing side effect). +.P +Opening a file in append mode (\fBa\fP as the first character of +.IR mode ) +causes all subsequent write operations to this stream to occur +at end-of-file, as if preceded by the call: +.P +.in +4n +.EX +fseek(stream, 0, SEEK_END); +.EE +.in +.P +The file descriptor associated with the stream is opened as if by a call to +.BR open (2) +with the following flags: +.RS +.TS +allbox; +lb lb +c l. +fopen() mode open() flags +\fIr\fP O_RDONLY +\fIw\fP O_WRONLY | O_CREAT | O_TRUNC +\fIa\fP O_WRONLY | O_CREAT | O_APPEND +\fIr+\fP O_RDWR +\fIw+\fP O_RDWR | O_CREAT | O_TRUNC +\fIa+\fP O_RDWR | O_CREAT | O_APPEND +.TE +.RE +.\" +.SS fdopen() +The +.BR fdopen () +function associates a stream with the existing file descriptor, +.IR fd . +The +.I mode +of the stream (one of the values "r", "r+", "w", "w+", "a", "a+") +must be compatible with the mode of the file descriptor. +The file position indicator of the new stream is set to that +belonging to +.IR fd , +and the error and end-of-file indicators are cleared. +Modes "w" or "w+" do not cause truncation of the file. +The file descriptor is not dup'ed, and will be closed when +the stream created by +.BR fdopen () +is closed. +The result of applying +.BR fdopen () +to a shared memory object is undefined. +.\" +.SS freopen() +The +.BR freopen () +function opens the file whose name is the string pointed to by +.I pathname +and associates the stream pointed to by +.I stream +with it. +The original stream (if it exists) is closed. +The +.I mode +argument is used just as in the +.BR fopen () +function. +.P +If the +.I pathname +argument is a null pointer, +.BR freopen () +changes the mode of the stream to that specified in +.IR mode ; +that is, +.BR freopen () +reopens the pathname that is associated with the stream. +The specification for this behavior was added in the C99 standard, which says: +.P +.RS +In this case, +the file descriptor associated with the stream need not be closed +if the call to +.BR freopen () +succeeds. +It is implementation-defined which changes of mode are permitted (if any), +and under what circumstances. +.RE +.P +The primary use of the +.BR freopen () +function is to change the file associated with a standard text stream +.RI ( stderr ", " stdin ", or " stdout ). +.SH RETURN VALUE +Upon successful completion +.BR fopen (), +.BR fdopen (), +and +.BR freopen () +return a +.I FILE +pointer. +Otherwise, NULL is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The +.I mode +provided to +.BR fopen (), +.BR fdopen (), +or +.BR freopen () +was invalid. +.P +The +.BR fopen (), +.BR fdopen (), +and +.BR freopen () +functions may also fail and set +.I errno +for any of the errors specified for the routine +.BR malloc (3). +.P +The +.BR fopen () +function may also fail and set +.I errno +for any of the errors specified for the routine +.BR open (2). +.P +The +.BR fdopen () +function may also fail and set +.I errno +for any of the errors specified for the routine +.BR fcntl (2). +.P +The +.BR freopen () +function may also fail and set +.I errno +for any of the errors specified for the routines +.BR open (2), +.BR fclose (3), +and +.BR fflush (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fopen (), +.BR fdopen (), +.BR freopen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR fopen () +.TQ +.BR freopen () +C11, POSIX.1-2008. +.TP +.BR fdopen () +POSIX.1-2008. +.SH HISTORY +.TP +.BR fopen () +.TQ +.BR freopen () +POSIX.1-2001, C89. +.TP +.BR fdopen () +POSIX.1-2001. +.SH NOTES +.SS glibc notes +The GNU C library allows the following extensions for the string specified in +.IR mode : +.TP +.BR c " (since glibc 2.3.3)" +Do not make the open operation, +or subsequent read and write operations, +thread cancelation points. +This flag is ignored for +.BR fdopen (). +.TP +.BR e " (since glibc 2.7)" +Open the file with the +.B O_CLOEXEC +flag. +See +.BR open (2) +for more information. +This flag is ignored for +.BR fdopen (). +.TP +.BR m " (since glibc 2.3)" +Attempt to access the file using +.BR mmap (2), +rather than I/O system calls +.RB ( read (2), +.BR write (2)). +Currently, +.\" As at glibc 2.4: +use of +.BR mmap (2) +is attempted only for a file opened for reading. +.TP +.B x +.\" Since glibc 2.0? +.\" FIXME . C11 specifies this flag +Open the file exclusively +(like the +.B O_EXCL +flag of +.BR open (2)). +If the file already exists, +.BR fopen () +fails, and sets +.I errno +to +.BR EEXIST . +This flag is ignored for +.BR fdopen (). +.P +In addition to the above characters, +.BR fopen () +and +.BR freopen () +support the following syntax +in +.IR mode : +.P +.BI " ,ccs=" string +.P +The given +.I string +is taken as the name of a coded character set and +the stream is marked as wide-oriented. +Thereafter, internal conversion functions convert I/O +to and from the character set +.IR string . +If the +.BI ,ccs= string +syntax is not specified, +then the wide-orientation of the stream is +determined by the first file operation. +If that operation is a wide-character operation, +the stream is marked wide-oriented, +and functions to convert to the coded character set are loaded. +.SH BUGS +When parsing for individual flag characters in +.I mode +(i.e., the characters preceding the "ccs" specification), +the glibc implementation of +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685 +.BR fopen () +and +.BR freopen () +limits the number of characters examined in +.I mode +to 7 (or, before glibc 2.14, to 6, +which was not enough to include possible specifications such as "rb+cmxe"). +The current implementation of +.BR fdopen () +parses at most 5 characters in +.IR mode . +.SH SEE ALSO +.BR open (2), +.BR fclose (3), +.BR fileno (3), +.BR fmemopen (3), +.BR fopencookie (3), +.BR open_memstream (3) diff --git a/man/man3/fopencookie.3 b/man/man3/fopencookie.3 new file mode 100644 index 0000000..ac3c082 --- /dev/null +++ b/man/man3/fopencookie.3 @@ -0,0 +1,466 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fopencookie 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fopencookie \- open a custom stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #define _FILE_OFFSET_BITS 64 +.B #include +.P +.BI "FILE *fopencookie(void *restrict " cookie ", const char *restrict " mode , +.BI " cookie_io_functions_t " io_funcs ); +.fi +.SH DESCRIPTION +The +.BR fopencookie () +function allows the programmer to create a custom implementation +for a standard I/O stream. +This implementation can store the stream's data at a location of +its own choosing; for example, +.BR fopencookie () +is used to implement +.BR fmemopen (3), +which provides a stream interface to data that is stored in a +buffer in memory. +.P +In order to create a custom stream the programmer must: +.IP \[bu] 3 +Implement four "hook" functions that are used internally by the +standard I/O library when performing I/O on the stream. +.IP \[bu] +Define a "cookie" data type, +a structure that provides bookkeeping information +(e.g., where to store data) used by the aforementioned hook functions. +The standard I/O package knows nothing about the contents of this cookie +(thus it is typed as +.I void\~* +when passed to +.BR fopencookie ()), +but automatically supplies the cookie +as the first argument when calling the hook functions. +.IP \[bu] +Call +.BR fopencookie () +to open a new stream and associate the cookie and hook functions +with that stream. +.P +The +.BR fopencookie () +function serves a purpose similar to +.BR fopen (3): +it opens a new stream and returns a pointer to a +.I FILE +object that is used to operate on that stream. +.P +The +.I cookie +argument is a pointer to the caller's cookie structure +that is to be associated with the new stream. +This pointer is supplied as the first argument when the standard I/O +library invokes any of the hook functions described below. +.P +The +.I mode +argument serves the same purpose as for +.BR fopen (3). +The following modes are supported: +.IR r , +.IR w , +.IR a , +.IR r+ , +.IR w+ , +and +.IR a+ . +See +.BR fopen (3) +for details. +.P +The +.I io_funcs +argument is a structure that contains four fields pointing to the +programmer-defined hook functions that are used to implement this stream. +The structure is defined as follows +.P +.in +4n +.EX +typedef struct { + cookie_read_function_t *read; + cookie_write_function_t *write; + cookie_seek_function_t *seek; + cookie_close_function_t *close; +} cookie_io_functions_t; +.EE +.in +.P +The four fields are as follows: +.TP +.I cookie_read_function_t *read +This function implements read operations for the stream. +When called, it receives three arguments: +.IP +.in +4n +.EX +ssize_t read(void *cookie, char *buf, size_t size); +.EE +.in +.IP +The +.I buf +and +.I size +arguments are, respectively, +a buffer into which input data can be placed and the size of that buffer. +As its function result, the +.I read +function should return the number of bytes copied into +.IR buf , +0 on end of file, or \-1 on error. +The +.I read +function should update the stream offset appropriately. +.IP +If +.I *read +is a null pointer, +then reads from the custom stream always return end of file. +.TP +.I cookie_write_function_t *write +This function implements write operations for the stream. +When called, it receives three arguments: +.IP +.in +4n +.EX +ssize_t write(void *cookie, const char *buf, size_t size); +.EE +.in +.IP +The +.I buf +and +.I size +arguments are, respectively, +a buffer of data to be output to the stream and the size of that buffer. +As its function result, the +.I write +function should return the number of bytes copied from +.IR buf , +or 0 on error. +(The function must not return a negative value.) +The +.I write +function should update the stream offset appropriately. +.IP +If +.I *write +is a null pointer, +then output to the stream is discarded. +.TP +.I cookie_seek_function_t *seek +This function implements seek operations on the stream. +When called, it receives three arguments: +.IP +.in +4n +.EX +int seek(void *cookie, off_t *offset, int whence); +.EE +.in +.IP +The +.I *offset +argument specifies the new file offset depending on which +of the following three values is supplied in +.IR whence : +.RS +.TP +.B SEEK_SET +The stream offset should be set +.I *offset +bytes from the start of the stream. +.TP +.B SEEK_CUR +.I *offset +should be added to the current stream offset. +.TP +.B SEEK_END +The stream offset should be set to the size of the stream plus +.IR *offset . +.RE +.IP +Before returning, the +.I seek +function should update +.I *offset +to indicate the new stream offset. +.IP +As its function result, the +.I seek +function should return 0 on success, and \-1 on error. +.IP +If +.I *seek +is a null pointer, +then it is not possible to perform seek operations on the stream. +.TP +.I cookie_close_function_t *close +This function closes the stream. +The hook function can do things such as freeing buffers allocated +for the stream. +When called, it receives one argument: +.IP +.in +4n +.EX +int close(void *cookie); +.EE +.in +.IP +The +.I cookie +argument is the cookie that the programmer supplied when calling +.BR fopencookie (). +.IP +As its function result, the +.I close +function should return 0 on success, and +.B EOF +on error. +.IP +If +.I *close +is NULL, then no special action is performed when the stream is closed. +.SH RETURN VALUE +On success +.BR fopencookie () +returns a pointer to the new stream. +On error, NULL is returned. +.\" .SH ERRORS +.\" It's not clear if errno ever gets set... +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fopencookie () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH EXAMPLES +The program below implements a custom stream whose functionality +is similar (but not identical) to that available via +.BR fmemopen (3). +It implements a stream whose data is stored in a memory buffer. +The program writes its command-line arguments to the stream, +and then seeks through the stream reading two out of every +five characters and writing them to standard output. +The following shell session demonstrates the use of the program: +.P +.in +4n +.EX +.RB "$" " ./a.out \[aq]hello world\[aq]" +/he/ +/ w/ +/d/ +Reached end of file +.EE +.in +.P +Note that a more general version of the program below +could be improved to more robustly handle various error situations +(e.g., opening a stream with a cookie that already has an open stream; +closing a stream that has already been closed). +.SS Program source +\& +.\" SRC BEGIN (fopencookie.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +\& +#define INIT_BUF_SIZE 4 +\& +struct memfile_cookie { + char *buf; /* Dynamically sized buffer for data */ + size_t allocated; /* Size of buf */ + size_t endpos; /* Number of characters in buf */ + off_t offset; /* Current file offset in buf */ +}; +\& +ssize_t +memfile_write(void *c, const char *buf, size_t size) +{ + char *new_buff; + struct memfile_cookie *cookie = c; +\& + /* Buffer too small? Keep doubling size until big enough. */ +\& + while (size + cookie\->offset > cookie\->allocated) { + new_buff = realloc(cookie\->buf, cookie\->allocated * 2); + if (new_buff == NULL) + return \-1; + cookie\->allocated *= 2; + cookie\->buf = new_buff; + } +\& + memcpy(cookie\->buf + cookie\->offset, buf, size); +\& + cookie\->offset += size; + if (cookie\->offset > cookie\->endpos) + cookie\->endpos = cookie\->offset; +\& + return size; +} +\& +ssize_t +memfile_read(void *c, char *buf, size_t size) +{ + ssize_t xbytes; + struct memfile_cookie *cookie = c; +\& + /* Fetch minimum of bytes requested and bytes available. */ +\& + xbytes = size; + if (cookie\->offset + size > cookie\->endpos) + xbytes = cookie\->endpos \- cookie\->offset; + if (xbytes < 0) /* offset may be past endpos */ + xbytes = 0; +\& + memcpy(buf, cookie\->buf + cookie\->offset, xbytes); +\& + cookie\->offset += xbytes; + return xbytes; +} +\& +int +memfile_seek(void *c, off_t *offset, int whence) +{ + off_t new_offset; + struct memfile_cookie *cookie = c; +\& + if (whence == SEEK_SET) + new_offset = *offset; + else if (whence == SEEK_END) + new_offset = cookie\->endpos + *offset; + else if (whence == SEEK_CUR) + new_offset = cookie\->offset + *offset; + else + return \-1; +\& + if (new_offset < 0) + return \-1; +\& + cookie\->offset = new_offset; + *offset = new_offset; + return 0; +} +\& +int +memfile_close(void *c) +{ + struct memfile_cookie *cookie = c; +\& + free(cookie\->buf); + cookie\->allocated = 0; + cookie\->buf = NULL; +\& + return 0; +} +\& +int +main(int argc, char *argv[]) +{ + cookie_io_functions_t memfile_func = { + .read = memfile_read, + .write = memfile_write, + .seek = memfile_seek, + .close = memfile_close + }; + FILE *stream; + struct memfile_cookie mycookie; + size_t nread; + char buf[1000]; +\& + /* Set up the cookie before calling fopencookie(). */ +\& + mycookie.buf = malloc(INIT_BUF_SIZE); + if (mycookie.buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + mycookie.allocated = INIT_BUF_SIZE; + mycookie.offset = 0; + mycookie.endpos = 0; +\& + stream = fopencookie(&mycookie, "w+", memfile_func); + if (stream == NULL) { + perror("fopencookie"); + exit(EXIT_FAILURE); + } +\& + /* Write command\-line arguments to our file. */ +\& + for (size_t j = 1; j < argc; j++) + if (fputs(argv[j], stream) == EOF) { + perror("fputs"); + exit(EXIT_FAILURE); + } +\& + /* Read two bytes out of every five, until EOF. */ +\& + for (long p = 0; ; p += 5) { + if (fseek(stream, p, SEEK_SET) == \-1) { + perror("fseek"); + exit(EXIT_FAILURE); + } + nread = fread(buf, 1, 2, stream); + if (nread == 0) { + if (ferror(stream) != 0) { + fprintf(stderr, "fread failed\en"); + exit(EXIT_FAILURE); + } + printf("Reached end of file\en"); + break; + } +\& + printf("/%.*s/\en", (int) nread, buf); + } +\& + free(mycookie.buf); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH NOTES +.B _FILE_OFFSET_BITS +should be defined to be 64 in code that uses non-null +.I seek +or that takes the address of +.BR fopencookie , +if the code is intended to be portable +to traditional 32-bit x86 and ARM platforms where +.BR off_t 's +width defaults to 32 bits. +.SH SEE ALSO +.BR fclose (3), +.BR fmemopen (3), +.BR fopen (3), +.BR fseek (3) diff --git a/man/man3/forkpty.3 b/man/man3/forkpty.3 new file mode 100644 index 0000000..fb4952d --- /dev/null +++ b/man/man3/forkpty.3 @@ -0,0 +1 @@ +.so man3/openpty.3 diff --git a/man/man3/fpathconf.3 b/man/man3/fpathconf.3 new file mode 100644 index 0000000..d879944 --- /dev/null +++ b/man/man3/fpathconf.3 @@ -0,0 +1,273 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (C) 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 28 11:12:26 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.\" FIXME Probably all of the following should be documented: +.\" _PC_SYNC_IO, +.\" _PC_ASYNC_IO, +.\" _PC_PRIO_IO, +.\" _PC_SOCK_MAXBUF, +.\" _PC_FILESIZEBITS, +.\" _PC_REC_INCR_XFER_SIZE, +.\" _PC_REC_MAX_XFER_SIZE, +.\" _PC_REC_MIN_XFER_SIZE, +.\" _PC_REC_XFER_ALIGN, +.\" _PC_ALLOC_SIZE_MIN, +.\" _PC_SYMLINK_MAX, +.\" _PC_2_SYMLINKS +.\" +.TH fpathconf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fpathconf, pathconf \- get configuration values for files +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long fpathconf(int " fd ", int " name ); +.BI "long pathconf(const char *" path ", int " name ); +.fi +.SH DESCRIPTION +.BR fpathconf () +gets a value for the configuration option +.I name +for the open file descriptor +.IR fd . +.P +.BR pathconf () +gets a value for configuration option +.I name +for the filename +.IR path . +.P +The corresponding macros defined in +.I +are minimum values; if an application wants to take advantage of values +which may change, a call to +.BR fpathconf () +or +.BR pathconf () +can be made, which may yield more liberal results. +.P +Setting +.I name +equal to one of the following constants returns the following +configuration options: +.TP +.B _PC_LINK_MAX +The maximum number of links to the file. +If +.I fd +or +.I path +refer to a directory, then the value applies to the whole directory. +The corresponding macro is +.BR _POSIX_LINK_MAX . +.TP +.B _PC_MAX_CANON +The maximum length of a formatted input line, where +.I fd +or +.I path +must refer to a terminal. +The corresponding macro is +.BR _POSIX_MAX_CANON . +.TP +.B _PC_MAX_INPUT +The maximum length of an input line, where +.I fd +or +.I path +must refer to a terminal. +The corresponding macro is +.BR _POSIX_MAX_INPUT . +.TP +.B _PC_NAME_MAX +The maximum length of a filename in the directory +.I path +or +.I fd +that the process is allowed to create. +The corresponding macro is +.BR _POSIX_NAME_MAX . +.TP +.B _PC_PATH_MAX +The maximum length of a relative pathname when +.I path +or +.I fd +is the current working directory. +The corresponding macro is +.BR _POSIX_PATH_MAX . +.TP +.B _PC_PIPE_BUF +The maximum number of bytes that can be written atomically to a pipe of FIFO. +For +.BR fpathconf (), +.I fd +should refer to a pipe or FIFO. +For +.BR fpathconf (), +.I path +should refer to a FIFO or a directory; in the latter case, +the returned value corresponds to FIFOs created in that directory. +The corresponding macro is +.BR _POSIX_PIPE_BUF . +.TP +.B _PC_CHOWN_RESTRICTED +This returns a positive value if the use of +.BR chown (2) +and +.BR fchown (2) +for changing a file's user ID is restricted to a process +with appropriate privileges, +and changing a file's group ID to a value other than the process's +effective group ID or one of its supplementary group IDs +is restricted to a process with appropriate privileges. +According to POSIX.1, +this variable shall always be defined with a value other than \-1. +The corresponding macro is +.BR _POSIX_CHOWN_RESTRICTED . +.IP +If +.I fd +or +.I path +refers to a directory, +then the return value applies to all files in that directory. +.TP +.B _PC_NO_TRUNC +This returns nonzero if accessing filenames longer than +.B _POSIX_NAME_MAX +generates an error. +The corresponding macro is +.BR _POSIX_NO_TRUNC . +.TP +.B _PC_VDISABLE +This returns nonzero if special character processing can be disabled, where +.I fd +or +.I path +must refer to a terminal. +.SH RETURN VALUE +The return value of these functions is one of the following: +.IP \[bu] 3 +On error, \-1 is returned and +.I errno +is set to indicate the error +(for example, +.BR EINVAL , +indicating that +.I name +is invalid). +.IP \[bu] +If +.I name +corresponds to a maximum or minimum limit, and that limit is indeterminate, +\-1 is returned and +.I errno +is not changed. +(To distinguish an indeterminate limit from an error, set +.I errno +to zero before the call, and then check whether +.I errno +is nonzero when \-1 is returned.) +.IP \[bu] +If +.I name +corresponds to an option, +a positive value is returned if the option is supported, +and \-1 is returned if the option is not supported. +.IP \[bu] +Otherwise, +the current value of the option or limit is returned. +This value will not be more restrictive than +the corresponding value that was described to the application in +.I +or +.I +when the application was compiled. +.SH ERRORS +.TP +.B EACCES +.RB ( pathconf ()) +Search permission is denied for one of the directories in the path prefix of +.IR path . +.TP +.B EBADF +.RB ( fpathconf ()) +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I name +is invalid. +.TP +.B EINVAL +The implementation does not support an association of +.I name +with the specified file. +.TP +.B ELOOP +.RB ( pathconf ()) +Too many symbolic links were encountered while resolving +.IR path . +.TP +.B ENAMETOOLONG +.RB ( pathconf ()) +.I path +is too long. +.TP +.B ENOENT +.RB ( pathconf ()) +A component of +.I path +does not exist, or +.I path +is an empty string. +.TP +.B ENOTDIR +.RB ( pathconf ()) +A component used as a directory in +.I path +is not in fact a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fpathconf (), +.BR pathconf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Files with name lengths longer than the value returned for +.I name +equal to +.B _PC_NAME_MAX +may exist in the given directory. +.P +Some returned values may be huge; they are not suitable for allocating +memory. +.SH SEE ALSO +.BR getconf (1), +.BR open (2), +.BR statfs (2), +.BR confstr (3), +.BR sysconf (3) diff --git a/man/man3/fpclassify.3 b/man/man3/fpclassify.3 new file mode 100644 index 0000000..17a0fdd --- /dev/null +++ b/man/man3/fpclassify.3 @@ -0,0 +1,145 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" This was done with the help of the glibc manual. +.\" +.\" 2004-10-31, aeb, corrected +.TH fpclassify 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fpclassify, isfinite, isnormal, isnan, isinf \- floating-point +classification macros +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fpclassify(" x ); +.BI "int isfinite(" x ); +.BI "int isnormal(" x ); +.BI "int isnan(" x ); +.BI "int isinf(" x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.\" I haven't fully grokked the source to determine the FTM requirements; +.\" in part, the following has been tested by experiment. +.BR fpclassify (), +.BR isfinite (), +.BR isnormal (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.P +.BR isnan (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR isinf (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +Floating point numbers can have special values, such as +infinite or NaN. +With the macro +.BI fpclassify( x ) +you can find out what type +.I x +is. +The macro takes any floating-point expression as argument. +The result is one of the following values: +.TP 14 +.B FP_NAN +.I x +is "Not a Number". +.TP +.B FP_INFINITE +.I x +is either positive infinity or negative infinity. +.TP +.B FP_ZERO +.I x +is zero. +.TP +.B FP_SUBNORMAL +.I x +is too small to be represented in normalized format. +.TP +.B FP_NORMAL +if nothing of the above is correct then it must be a +normal floating-point number. +.P +The other macros provide a short answer to some standard questions. +.TP 14 +.BI isfinite( x ) +returns a nonzero value if +.br +(fpclassify(x) != FP_NAN && fpclassify(x) != FP_INFINITE) +.TP +.BI isnormal( x ) +returns a nonzero value if +(fpclassify(x) == FP_NORMAL) +.TP +.BI isnan( x ) +returns a nonzero value if +(fpclassify(x) == FP_NAN) +.TP +.BI isinf( x ) +returns 1 if +.I x +is positive infinity, and \-1 if +.I x +is negative infinity. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fpclassify (), +.BR isfinite (), +.BR isnormal (), +.BR isnan (), +.BR isinf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.P +In glibc 2.01 and earlier, +.BR isinf () +returns a nonzero value (actually: 1) if +.I x +is positive infinity or negative infinity. +(This is all that C99 requires.) +.SH NOTES +For +.BR isinf (), +the standards merely say that the return value is nonzero +if and only if the argument has an infinite value. +.SH SEE ALSO +.BR finite (3), +.BR INFINITY (3), +.BR isgreater (3), +.BR signbit (3) diff --git a/man/man3/fprintf.3 b/man/man3/fprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/fprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/fpurge.3 b/man/man3/fpurge.3 new file mode 100644 index 0000000..4057c90 --- /dev/null +++ b/man/man3/fpurge.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fpurge 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fpurge, __fpurge \- purge a stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +/* unsupported */ +.B #include +.P +.BI "int fpurge(FILE *" stream ); +.P +/* supported */ +.B #include +.B #include +.P +.BI "void __fpurge(FILE *" stream ); +.fi +.SH DESCRIPTION +The function +.BR fpurge () +clears the buffers of the given stream. +For output streams this discards any unwritten output. +For input streams this discards any input read from the underlying object +but not yet obtained via +.BR getc (3); +this includes any text pushed back via +.BR ungetc (3). +See also +.BR fflush (3). +.P +The function +.BR __fpurge () +does precisely the same, but without returning a value. +.SH RETURN VALUE +Upon successful completion +.BR fpurge () +returns 0. +On error, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I stream +is not an open stream. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR __fpurge () +T} Thread safety MT-Safe race:stream +.TE +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR fpurge () +4.4BSD. +Not available under Linux. +.TP +.BR __fpurge () +Solaris, glibc 2.1.95. +.SH NOTES +Usually it is a mistake to want to discard input buffers. +.SH SEE ALSO +.\" .BR fclean (3), +.BR fflush (3), +.BR setbuf (3), +.BR stdio_ext (3) diff --git a/man/man3/fputc.3 b/man/man3/fputc.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man/man3/fputc.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man/man3/fputc_unlocked.3 b/man/man3/fputc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fputc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fputs.3 b/man/man3/fputs.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man/man3/fputs.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man/man3/fputs_unlocked.3 b/man/man3/fputs_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fputs_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fputwc.3 b/man/man3/fputwc.3 new file mode 100644 index 0000000..cdac37d --- /dev/null +++ b/man/man3/fputwc.3 @@ -0,0 +1,104 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH fputwc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fputwc, putwc \- write a wide character to a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "wint_t fputwc(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwc(wchar_t " wc ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR fputwc () +function is the wide-character +equivalent of the +.BR fputc (3) +function. +It writes the wide character \fIwc\fP to \fIstream\fP. +If +\fIferror(stream)\fP becomes true, it returns +.BR WEOF . +If a wide-character conversion error occurs, +it sets \fIerrno\fP to \fBEILSEQ\fP and returns +.BR WEOF . +Otherwise, it returns \fIwc\fP. +.P +The +.BR putwc () +function or macro functions identically to +.BR fputwc (). +It may be implemented as a macro, and may evaluate its argument +more than once. +There is no reason ever to use it. +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +On success, +.BR fputwc () +function returns +.IR wc . +Otherwise, +.B WEOF +is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Apart from the usual ones, there is +.TP +.B EILSEQ +Conversion of \fIwc\fP to the stream's encoding fails. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fputwc (), +.BR putwc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +The behavior of +.BR fputwc () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fputwc () +will actually write the multibyte +sequence corresponding to the wide character \fIwc\fP. +.SH SEE ALSO +.BR fgetwc (3), +.BR fputws (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fputwc_unlocked.3 b/man/man3/fputwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fputwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fputws.3 b/man/man3/fputws.3 new file mode 100644 index 0000000..62b3425 --- /dev/null +++ b/man/man3/fputws.3 @@ -0,0 +1,78 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH fputws 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fputws \- write a wide-character string to a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fputws(const wchar_t *restrict " ws ", FILE *restrict " stream ); +.fi +.SH DESCRIPTION +The +.BR fputws () +function is the wide-character equivalent of +the +.BR fputs (3) +function. +It writes the wide-character string starting at \fIws\fP, +up to but not including the terminating null wide character (L\[aq]\e0\[aq]), +to \fIstream\fP. +.P +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR fputws () +function returns a +nonnegative integer if the operation was +successful, or \-1 to indicate an error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fputws () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR fputws () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +In the absence of additional information passed to the +.BR fopen (3) +call, it is +reasonable to expect that +.BR fputws () +will actually write the multibyte +string corresponding to the wide-character string \fIws\fP. +.SH SEE ALSO +.BR fputwc (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fputws_unlocked.3 b/man/man3/fputws_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fputws_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/fread.3 b/man/man3/fread.3 new file mode 100644 index 0000000..0deecd4 --- /dev/null +++ b/man/man3/fread.3 @@ -0,0 +1,164 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" and Copyright (c) 2020 Arkadiusz Drabczyk +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fread.3 6.6 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:37:33 1993, faith@cs.unc.edu +.\" Sun Feb 19 21:26:54 1995 by faith, return values +.\" Modified Thu Apr 20 20:43:53 1995 by Jim Van Zandt +.\" Modified Fri May 17 10:21:51 1996 by Martin Schulze +.\" +.TH fread 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fread, fwrite \- binary stream input/output +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t fread(void " ptr "[restrict ." size " * ." nmemb ], +.BI " size_t " size ", size_t " nmemb , +.BI " FILE *restrict " stream ); +.BI "size_t fwrite(const void " ptr "[restrict ." size " * ." nmemb ], +.BI " size_t " size ", size_t " nmemb , +.BI " FILE *restrict " stream ); +.fi +.SH DESCRIPTION +The function +.BR fread () +reads +.I nmemb +items of data, each +.I size +bytes long, from the stream pointed to by +.IR stream , +storing them at the location given by +.IR ptr . +.P +The function +.BR fwrite () +writes +.I nmemb +items of data, each +.I size +bytes long, to the stream pointed to by +.IR stream , +obtaining them from the location given by +.IR ptr . +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +On success, +.BR fread () +and +.BR fwrite () +return the number of items read or written. +This number equals the number of bytes transferred only when +.I size +is 1. +If an error occurs, or the end of the file is reached, +the return value is a short item count (or zero). +.P +The file position indicator for the stream is advanced by the number +of bytes successfully read or written. +.P +.BR fread () +does not distinguish between end-of-file and error, and callers must use +.BR feof (3) +and +.BR ferror (3) +to determine which occurred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fread (), +.BR fwrite () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH EXAMPLES +The program below demonstrates the use of +.BR fread () +by parsing /bin/sh ELF executable in binary mode and printing its +magic and class: +.P +.in +4n +.EX +$ \fB./a.out\fP +ELF magic: 0x7f454c46 +Class: 0x02 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (fread.c) +.EX +#include +#include +\& +#define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0])) +\& +int +main(void) +{ + FILE *fp; + size_t ret; + unsigned char buffer[4]; +\& + fp = fopen("/bin/sh", "rb"); + if (!fp) { + perror("fopen"); + return EXIT_FAILURE; + } +\& + ret = fread(buffer, sizeof(*buffer), ARRAY_SIZE(buffer), fp); + if (ret != ARRAY_SIZE(buffer)) { + fprintf(stderr, "fread() failed: %zu\en", ret); + exit(EXIT_FAILURE); + } +\& + printf("ELF magic: %#04x%02x%02x%02x\en", buffer[0], buffer[1], + buffer[2], buffer[3]); +\& + ret = fread(buffer, 1, 1, fp); + if (ret != 1) { + fprintf(stderr, "fread() failed: %zu\en", ret); + exit(EXIT_FAILURE); + } +\& + printf("Class: %#04x\en", buffer[0]); +\& + fclose(fp); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR read (2), +.BR write (2), +.BR feof (3), +.BR ferror (3), +.BR unlocked_stdio (3) diff --git a/man/man3/fread_unlocked.3 b/man/man3/fread_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fread_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/free.3 b/man/man3/free.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man/man3/free.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man/man3/freeaddrinfo.3 b/man/man3/freeaddrinfo.3 new file mode 100644 index 0000000..17f7236 --- /dev/null +++ b/man/man3/freeaddrinfo.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo.3 diff --git a/man/man3/freehostent.3 b/man/man3/freehostent.3 new file mode 100644 index 0000000..82e01df --- /dev/null +++ b/man/man3/freehostent.3 @@ -0,0 +1 @@ +.so man3/getipnodebyname.3 diff --git a/man/man3/freeifaddrs.3 b/man/man3/freeifaddrs.3 new file mode 100644 index 0000000..38f977d --- /dev/null +++ b/man/man3/freeifaddrs.3 @@ -0,0 +1 @@ +.so man3/getifaddrs.3 diff --git a/man/man3/freelocale.3 b/man/man3/freelocale.3 new file mode 100644 index 0000000..a4246c5 --- /dev/null +++ b/man/man3/freelocale.3 @@ -0,0 +1 @@ +.so man3/newlocale.3 diff --git a/man/man3/freopen.3 b/man/man3/freopen.3 new file mode 100644 index 0000000..9a40124 --- /dev/null +++ b/man/man3/freopen.3 @@ -0,0 +1 @@ +.so man3/fopen.3 diff --git a/man/man3/frexp.3 b/man/man3/frexp.3 new file mode 100644 index 0000000..3d357c9 --- /dev/null +++ b/man/man3/frexp.3 @@ -0,0 +1,141 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH frexp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +frexp, frexpf, frexpl \- convert floating-point number to fractional +and integral components +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double frexp(double " x ", int *" exp ); +.BI "float frexpf(float " x ", int *" exp ); +.BI "long double frexpl(long double " x ", int *" exp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR frexpf (), +.BR frexpl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions are used to split the number +.I x +into a +normalized fraction and an exponent which is stored in +.IR exp . +.SH RETURN VALUE +These functions return the normalized fraction. +If the argument +.I x +is not zero, +the normalized fraction is +.I x +times a power of two, +and its absolute value is always in the range 1/2 (inclusive) to +1 (exclusive), that is, [0.5,1). +.P +If +.I x +is zero, then the normalized fraction is +zero and zero is stored in +.IR exp . +.P +If +.I x +is a NaN, +a NaN is returned, and the value of +.I *exp +is unspecified. +.P +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned, and the value of +.I *exp +is unspecified. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR frexp (), +.BR frexpf (), +.BR frexpl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH EXAMPLES +The program below produces results such as the following: +.P +.in +4n +.EX +.RB "$" " ./a.out 2560" +frexp(2560, &e) = 0.625: 0.625 * 2\[ha]12 = 2560 +.RB "$" " ./a.out \-4" +frexp(\-4, &e) = \-0.5: \-0.5 * 2\[ha]3 = \-4 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (frexp.c) +.EX +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + double x, r; + int exp; +\& + x = strtod(argv[1], NULL); + r = frexp(x, &exp); +\& + printf("frexp(%g, &e) = %g: %g * %d\[ha]%d = %g\en", x, r, r, 2, exp, x); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ldexp (3), +.BR modf (3) diff --git a/man/man3/frexpf.3 b/man/man3/frexpf.3 new file mode 100644 index 0000000..980426f --- /dev/null +++ b/man/man3/frexpf.3 @@ -0,0 +1 @@ +.so man3/frexp.3 diff --git a/man/man3/frexpl.3 b/man/man3/frexpl.3 new file mode 100644 index 0000000..980426f --- /dev/null +++ b/man/man3/frexpl.3 @@ -0,0 +1 @@ +.so man3/frexp.3 diff --git a/man/man3/fscanf.3 b/man/man3/fscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man/man3/fscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man/man3/fseek.3 b/man/man3/fseek.3 new file mode 100644 index 0000000..89948f0 --- /dev/null +++ b/man/man3/fseek.3 @@ -0,0 +1,177 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fseek.3 6.11 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" +.TH fseek 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fseek(FILE *" stream ", long " offset ", int " whence ); +.BI "long ftell(FILE *" stream ); +.P +.BI "void rewind(FILE *" stream ); +.P +.BI "int fgetpos(FILE *restrict " stream ", fpos_t *restrict " pos ); +.BI "int fsetpos(FILE *" stream ", const fpos_t *" pos ); +.fi +.SH DESCRIPTION +The +.BR fseek () +function sets the file position indicator for the stream pointed to by +.IR stream . +The new position, measured in bytes, is obtained by adding +.I offset +bytes to the position specified by +.IR whence . +If +.I whence +is set to +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +the offset is relative to the start of the file, the current position +indicator, or end-of-file, respectively. +A successful call to the +.BR fseek () +function clears the end-of-file indicator for the stream and undoes +any effects of the +.BR ungetc (3) +function on the same stream. +.P +The +.BR ftell () +function obtains the current value of the file position indicator for the +stream pointed to by +.IR stream . +.P +The +.BR rewind () +function sets the file position indicator for the stream pointed to by +.I stream +to the beginning of the file. +It is equivalent to: +.P +.RS +(void) fseek(stream, 0L, SEEK_SET) +.RE +.P +except that the error indicator for the stream is also cleared (see +.BR clearerr (3)). +.P +The +.BR fgetpos () +and +.BR fsetpos () +functions are alternate interfaces equivalent to +.BR ftell () +and +.BR fseek () +(with +.I whence +set to +.BR SEEK_SET ), +setting and storing the current value of the file offset into or from the +object referenced by +.IR pos . +On some non-UNIX systems, an +.I fpos_t +object may be a complex object and these routines may be the only way to +portably reposition a text stream. +.P +If the stream refers to a regular file +and the resulting stream offset is beyond the size of the file, +subsequent writes will extend the file with a hole, up to the offset, +before committing any data. +See +.BR lseek (2) +for details on file seeking semantics. +.SH RETURN VALUE +The +.BR rewind () +function returns no value. +Upon successful completion, +.BR fgetpos (), +.BR fseek (), +.BR fsetpos () +return 0, +and +.BR ftell () +returns the current offset. +Otherwise, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The +.I whence +argument to +.BR fseek () +was not +.BR SEEK_SET , +.BR SEEK_END , +or +.BR SEEK_CUR . +Or: the resulting file offset would be negative. +.TP +.B ESPIPE +The file descriptor underlying +.I stream +is not seekable (e.g., it refers to a pipe, FIFO, or socket). +.P +The functions +.BR fgetpos (), +.BR fseek (), +.BR fsetpos (), +and +.BR ftell () +may also fail and set +.I errno +for any of the errors specified for the routines +.BR fflush (3), +.BR fstat (2), +.BR lseek (2), +and +.BR malloc (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fseek (), +.BR ftell (), +.BR rewind (), +.BR fgetpos (), +.BR fsetpos () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH SEE ALSO +.BR lseek (2), +.BR fseeko (3) diff --git a/man/man3/fseeko.3 b/man/man3/fseeko.3 new file mode 100644 index 0000000..e108ec7 --- /dev/null +++ b/man/man3/fseeko.3 @@ -0,0 +1,102 @@ +'\" t +.\" Copyright 2001 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fseeko 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fseeko, ftello \- seek to or report file position +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fseeko(FILE *" stream ", off_t " offset ", int " whence ); +.BI "off_t ftello(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fseeko (), +.BR ftello (): +.nf + _FILE_OFFSET_BITS == 64 || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR fseeko () +and +.BR ftello () +functions are identical to +.BR fseek (3) +and +.BR ftell (3) +(see +.BR fseek (3)), +respectively, except that the +.I offset +argument of +.BR fseeko () +and the return value of +.BR ftello () +is of type +.I off_t +instead of +.IR long . +.P +On some architectures, both +.I off_t +and +.I long +are 32-bit types, but defining +.B _FILE_OFFSET_BITS +with the value 64 (before including +.I any +header files) +will turn +.I off_t +into a 64-bit type. +.SH RETURN VALUE +On successful completion, +.BR fseeko () +returns 0, while +.BR ftello () +returns the current offset. +Otherwise, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +See the ERRORS in +.BR fseek (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fseeko (), +.BR ftello () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001, SUSv2. +.SH NOTES +The declarations of these functions can also be obtained by defining +the obsolete +.B _LARGEFILE_SOURCE +feature test macro. +.SH SEE ALSO +.BR fseek (3) diff --git a/man/man3/fsetpos.3 b/man/man3/fsetpos.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man/man3/fsetpos.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man/man3/fstatvfs.3 b/man/man3/fstatvfs.3 new file mode 100644 index 0000000..adec9dd --- /dev/null +++ b/man/man3/fstatvfs.3 @@ -0,0 +1 @@ +.so man3/statvfs.3 diff --git a/man/man3/ftell.3 b/man/man3/ftell.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man/man3/ftell.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man/man3/ftello.3 b/man/man3/ftello.3 new file mode 100644 index 0000000..d5628f4 --- /dev/null +++ b/man/man3/ftello.3 @@ -0,0 +1 @@ +.so man3/fseeko.3 diff --git a/man/man3/ftime.3 b/man/man3/ftime.3 new file mode 100644 index 0000000..0c4a22e --- /dev/null +++ b/man/man3/ftime.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 14:23:14 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Oct 18 17:31:43 1998 by Andries Brouwer (aeb@cwi.nl) +.\" 2008-06-23, mtk, minor rewrites, added some details +.\" +.TH ftime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ftime \- return date and time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int ftime(struct timeb *" tp ); +.fi +.SH DESCRIPTION +.BR NOTE : +This function is no longer provided by the GNU C library. +Use +.BR clock_gettime (2) +instead. +.P +This function returns the current time as seconds and milliseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +The time is returned in +.IR tp , +which is declared as follows: +.P +.in +4n +.EX +struct timeb { + time_t time; + unsigned short millitm; + short timezone; + short dstflag; +}; +.EE +.in +.P +Here \fItime\fP is the number of seconds since the Epoch, +and \fImillitm\fP is the number of milliseconds since \fItime\fP +seconds since the Epoch. +The \fItimezone\fP field is the local timezone measured in minutes +of time west of Greenwich (with a negative value indicating minutes +east of Greenwich). +The \fIdstflag\fP field +is a flag that, if nonzero, indicates that Daylight Saving time +applies locally during the appropriate part of the year. +.P +POSIX.1-2001 says that the contents of the \fItimezone\fP and \fIdstflag\fP +fields are unspecified; avoid relying on them. +.SH RETURN VALUE +This function always returns 0. +(POSIX.1-2001 specifies, and some systems document, a \-1 error return.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ftime () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +Removed in glibc 2.33. +4.2BSD, POSIX.1-2001. +Removed in POSIX.1-2008. +.P +This function is obsolete. +Don't use it. +If the time in seconds +suffices, +.BR time (2) +can be used; +.BR gettimeofday (2) +gives microseconds; +.BR clock_gettime (2) +gives nanoseconds but is not as widely available. +.SH BUGS +Early glibc2 is buggy and returns 0 in the +.I millitm +field; +glibc 2.1.1 is correct again. +.\" .SH HISTORY +.\" The +.\" .BR ftime () +.\" function appeared in 4.2BSD. +.SH SEE ALSO +.BR gettimeofday (2), +.BR time (2) diff --git a/man/man3/ftok.3 b/man/man3/ftok.3 new file mode 100644 index 0000000..b8df38d --- /dev/null +++ b/man/man3/ftok.3 @@ -0,0 +1,110 @@ +'\" t +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2001-11-28, by Michael Kerrisk, +.\" Changed data type of proj_id; minor fixes +.\" aeb: further fixes; added notes. +.\" +.TH ftok 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ftok \- convert a pathname and a project identifier to a System V IPC key +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.fi +.P +.BI "key_t ftok(const char *" pathname ", int " proj_id ); +.SH DESCRIPTION +The +.BR ftok () +function uses the identity of the file named by the given +.I pathname +(which must refer to an existing, accessible file) +and the least significant 8 bits of +.I proj_id +(which must be nonzero) to generate a +.I key_t +type System V IPC key, suitable for use with +.BR msgget (2), +.BR semget (2), +or +.BR shmget (2). +.P +The resulting value is the same for all pathnames that +name the same file, when the same value of +.I proj_id +is used. +The value returned should be different when the +(simultaneously existing) files or the project IDs differ. +.SH RETURN VALUE +On success, the generated +.I key_t +value is returned. +On failure \-1 is returned, with +.I errno +indicating the error as for the +.BR stat (2) +system call. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ftok () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +On some ancient systems, the prototype was: +.P +.in +4n +.EX +.BI "key_t ftok(char *" pathname ", char " proj_id ); +.EE +.in +.P +Today, +.I proj_id +is an +.IR int , +but still only 8 bits are used. +Typical usage has an ASCII character +.IR proj_id , +that is why the behavior is said to be undefined when +.I proj_id +is zero. +.P +Of course, no guarantee can be given that the resulting +.I key_t +is unique. +Typically, a best-effort attempt combines the given +.I proj_id +byte, the lower 16 bits of the inode number, and the +lower 8 bits of the device number into a 32-bit result. +Collisions may easily happen, for example between files on +.I /dev/hda1 +and files on +.IR /dev/sda1 . +.SH EXAMPLES +See +.BR semget (2). +.SH SEE ALSO +.BR msgget (2), +.BR semget (2), +.BR shmget (2), +.BR stat (2), +.BR sysvipc (7) diff --git a/man/man3/ftrylockfile.3 b/man/man3/ftrylockfile.3 new file mode 100644 index 0000000..b33c2ee --- /dev/null +++ b/man/man3/ftrylockfile.3 @@ -0,0 +1 @@ +.so man3/flockfile.3 diff --git a/man/man3/fts.3 b/man/man3/fts.3 new file mode 100644 index 0000000..6a8b922 --- /dev/null +++ b/man/man3/fts.3 @@ -0,0 +1,826 @@ +'\" t +.\" $NetBSD: fts.3,v 1.13.2.1 1997/11/14 02:09:32 mrg Exp $ +.\" +.\" Copyright (c) 1989, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)fts.3 8.5 (Berkeley) 4/16/94 +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH fts 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fts, fts_open, fts_read, fts_children, fts_set, fts_close \- \ +traverse a file hierarchy +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.BI "FTS *fts_open(char *const *" path_argv ", int " options , +.BI " int (*_Nullable " compar ")(const FTSENT **, const FTSENT **));" +.P +.BI "FTSENT *fts_read(FTS *" ftsp ); +.P +.BI "FTSENT *fts_children(FTS *" ftsp ", int " instr ); +.P +.BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " instr ); +.P +.BI "int fts_close(FTS *" ftsp ); +.fi +.SH DESCRIPTION +The +fts functions are provided for traversing +file hierarchies. +A simple overview is that the +.BR fts_open () +function returns a "handle" (of type +.IR "FTS\ *" ) +that refers to a file hierarchy "stream". +This handle is then supplied to the other +fts functions. +The function +.BR fts_read () +returns a pointer to a structure describing one of the files in the file +hierarchy. +The function +.BR fts_children () +returns a pointer to a linked list of structures, each of which describes +one of the files contained in a directory in the hierarchy. +.P +In general, directories are visited two distinguishable times; in preorder +(before any of their descendants are visited) and in postorder (after all +of their descendants have been visited). +Files are visited once. +It is possible to walk the hierarchy "logically" (visiting the files that +symbolic links point to) +or physically (visiting the symbolic links themselves), +order the walk of the hierarchy or +prune and/or revisit portions of the hierarchy. +.P +Two structures (and associated types) are defined in the include file +.IR . +The first type is +.IR FTS , +the structure that represents the file hierarchy itself. +The second type is +.IR FTSENT , +the structure that represents a file in the file +hierarchy. +Normally, an +.I FTSENT +structure is returned for every file in the file +hierarchy. +In this manual page, "file" and +"FTSENT structure" +are generally interchangeable. +.P +The +.I FTSENT +structure contains fields describing a file. +The structure contains at least the following fields +(there are additional fields that +should be considered private to the implementation): +.P +.in +4n +.EX +typedef struct _ftsent { + unsigned short fts_info; /* flags for FTSENT structure */ + char *fts_accpath; /* access path */ + char *fts_path; /* root path */ + short fts_pathlen; /* strlen(fts_path) + + strlen(fts_name) */ + char *fts_name; /* filename */ + short fts_namelen; /* strlen(fts_name) */ + short fts_level; /* depth (\-1 to N) */ + int fts_errno; /* file errno */ + long fts_number; /* local numeric value */ + void *fts_pointer; /* local address value */ + struct _ftsent *fts_parent; /* parent directory */ + struct _ftsent *fts_link; /* next file structure */ + struct _ftsent *fts_cycle; /* cycle structure */ + struct stat *fts_statp; /* [l]stat(2) information */ +.\" Also: +.\" ino_t fts_ino; /* inode (only for directories)*/ +.\" dev_t fts_dev; /* device (only for directories)*/ +.\" nlink_t fts_nlink; /* link count (only for directories)*/ +.\" u_short fts_flags; /* private flags for FTSENT structure */ +.\" u_short fts_instr; /* fts_set() instructions */ +} FTSENT; +.EE +.in +.P +These fields are defined as follows: +.\" .Bl -tag -width "fts_namelen" +.TP +.I fts_info +One of the following values describing the returned +.I FTSENT +structure and +the file it represents. +With the exception of directories without errors +.RB ( FTS_D ), +all of these +entries are terminal, that is, they will not be revisited, nor will any +of their descendants be visited. +.\" .Bl -tag -width FTS_DEFAULT +.RS +.TP +.B FTS_D +A directory being visited in preorder. +.TP +.B FTS_DC +A directory that causes a cycle in the tree. +(The +.I fts_cycle +field of the +.I FTSENT +structure will be filled in as well.) +.TP +.B FTS_DEFAULT +Any +.I FTSENT +structure that represents a file type not explicitly described +by one of the other +.I fts_info +values. +.TP +.B FTS_DNR +A directory which cannot be read. +This is an error return, and the +.I fts_errno +field will be set to indicate what caused the error. +.TP +.B FTS_DOT +A file named +"." +or +".." +which was not specified as a filename to +.BR fts_open () +(see +.BR FTS_SEEDOT ). +.TP +.B FTS_DP +A directory being visited in postorder. +The contents of the +.I FTSENT +structure will be unchanged from when +it was returned in preorder, that is, with the +.I fts_info +field set to +.BR FTS_D . +.TP +.B FTS_ERR +This is an error return, and the +.I fts_errno +field will be set to indicate what caused the error. +.TP +.B FTS_F +A regular file. +.TP +.B FTS_NS +A file for which no +.RB [ l ]\c +.BR stat (2) +information was available. +The contents of the +.I fts_statp +field are undefined. +This is an error return, and the +.I fts_errno +field will be set to indicate what caused the error. +.TP +.B FTS_NSOK +A file for which no +.RB [ l ]\c +.BR stat (2) +information was requested. +The contents of the +.I fts_statp +field are undefined. +.TP +.B FTS_SL +A symbolic link. +.TP +.B FTS_SLNONE +A symbolic link with a nonexistent target. +The contents of the +.I fts_statp +field reference the file characteristic information for the symbolic link +itself. +.\" .El +.RE +.TP +.I fts_accpath +A path for accessing the file from the current directory. +.TP +.I fts_path +The path for the file relative to the root of the traversal. +This path contains the path specified to +.BR fts_open () +as a prefix. +.TP +.I fts_pathlen +The sum of the lengths of the strings referenced by +.I fts_path +and +.IR fts_name . +.TP +.I fts_name +The name of the file. +.TP +.I fts_namelen +The length of the string referenced by +.IR fts_name . +.TP +.I fts_level +The depth of the traversal, numbered from \-1 to N, where this file +was found. +The +.I FTSENT +structure representing the parent of the starting point (or root) +of the traversal is numbered \-1, and the +.I FTSENT +structure for the root +itself is numbered 0. +.TP +.I fts_errno +If +.BR fts_children () +or +.BR fts_read () +returns an +.I FTSENT +structure whose +.I fts_info +field is set to +.BR FTS_DNR , +.BR FTS_ERR , +or +.BR FTS_NS , +the +.I fts_errno +field contains the error number (i.e., the +.I errno +value) +specifying the cause of the error. +Otherwise, the contents of the +.I fts_errno +field are undefined. +.TP +.I fts_number +This field is provided for the use of the application program and is +not modified by the +fts functions. +It is initialized to 0. +.TP +.I fts_pointer +This field is provided for the use of the application program and is +not modified by the +fts functions. +It is initialized to +NULL. +.TP +.I fts_parent +A pointer to the +.I FTSENT +structure referencing the file in the hierarchy +immediately above the current file, that is, the directory of which this +file is a member. +A parent structure for the initial entry point is provided as well, +however, only the +.IR fts_level , +.IR fts_number , +and +.I fts_pointer +fields are guaranteed to be initialized. +.TP +.I fts_link +Upon return from the +.BR fts_children () +function, the +.I fts_link +field points to the next structure in the NULL-terminated linked list of +directory members. +Otherwise, the contents of the +.I fts_link +field are undefined. +.TP +.I fts_cycle +If a directory causes a cycle in the hierarchy (see +.BR FTS_DC ), +either because +of a hard link between two directories, or a symbolic link pointing to a +directory, the +.I fts_cycle +field of the structure will point to the +.I FTSENT +structure in the hierarchy that references the same file as the current +.I FTSENT +structure. +Otherwise, the contents of the +.I fts_cycle +field are undefined. +.TP +.I fts_statp +A pointer to +.RB [ l ]\c +.BR stat (2) +information for the file. +.\" .El +.P +A single buffer is used for all of the paths of all of the files in the +file hierarchy. +Therefore, the +.I fts_path +and +.I fts_accpath +fields are guaranteed to be +null-terminated +.I only +for the file most recently returned by +.BR fts_read (). +To use these fields to reference any files represented by other +.I FTSENT +structures will require that the path buffer be modified using the +information contained in that +.I FTSENT +structure's +.I fts_pathlen +field. +Any such modifications should be undone before further calls to +.BR fts_read () +are attempted. +The +.I fts_name +field is always +null-terminated. +.SS fts_open() +The +.BR fts_open () +function takes a pointer to an array of character pointers naming one +or more paths which make up a logical file hierarchy to be traversed. +The array must be terminated by a +null pointer. +.P +There are +a number of options, at least one of which (either +.B FTS_LOGICAL +or +.BR FTS_PHYSICAL ) +must be specified. +The options are selected by ORing +the following values: +.\" .Bl -tag -width "FTS_PHYSICAL" +.TP +.B FTS_LOGICAL +This option causes the +fts routines to return +.I FTSENT +structures for the targets of symbolic links +instead of the symbolic links themselves. +If this option is set, the only symbolic links for which +.I FTSENT +structures +are returned to the application are those referencing nonexistent files: +the +.I fts_statp +field is obtained via +.BR stat (2) +with a fallback to +.BR lstat (2). +.TP +.B FTS_PHYSICAL +This option causes the +fts routines to return +.I FTSENT +structures for symbolic links themselves instead +of the target files they point to. +If this option is set, +.I FTSENT +structures for all symbolic links in the +hierarchy are returned to the application: +the +.I fts_statp +field is obtained via +.BR lstat (2). +.TP +.B FTS_COMFOLLOW +This option causes any symbolic link specified as a root path to be +followed immediately, as if via +.BR FTS_LOGICAL , +regardless of the primary mode. +.TP +.B FTS_NOCHDIR +As a performance optimization, the +fts functions change directories as they walk the file hierarchy. +This has the side-effect that an application cannot rely on being +in any particular directory during the traversal. +This +option turns off this optimization, and the +fts functions will not change the current directory. +Note that applications should not themselves change their current directory +and try to access files unless +.B FTS_NOCHDIR +is specified and absolute +pathnames were provided as arguments to +.BR fts_open (). +.TP +.B FTS_NOSTAT +By default, returned +.I FTSENT +structures reference file characteristic information (the +.I fts_statp +field) for each file visited. +This option relaxes that requirement as a performance optimization, +allowing the +fts functions to set the +.I fts_info +field to +.B FTS_NSOK +and leave the contents of the +.I fts_statp +field undefined. +.TP +.B FTS_SEEDOT +By default, unless they are specified as path arguments to +.BR fts_open (), +any files named +"." +or +".." +encountered in the file hierarchy are ignored. +This option causes the +fts routines to return +.I FTSENT +structures for them. +.TP +.B FTS_XDEV +This option prevents +fts from descending into directories that have a different device number +than the file from which the descent began. +.\" .El +.P +The argument +.BR compar () +specifies a user-defined function which may be used to order the traversal +of the hierarchy. +It +takes two pointers to pointers to +.I FTSENT +structures as arguments and +should return a negative value, zero, or a positive value to indicate +if the file referenced by its first argument comes before, in any order +with respect to, or after, the file referenced by its second argument. +The +.IR fts_accpath , +.IR fts_path , +and +.I fts_pathlen +fields of the +.I FTSENT +structures may +.I never +be used in this comparison. +If the +.I fts_info +field is set to +.B FTS_NS +or +.BR FTS_NSOK , +the +.I fts_statp +field may not either. +If the +.BR compar () +argument is +NULL, +the directory traversal order is in the order listed in +.I path_argv +for the root paths, and in the order listed in the directory for +everything else. +.SS fts_read() +The +.BR fts_read () +function returns a pointer to an +.I FTSENT +structure describing a file in +the hierarchy. +Directories (that are readable and do not cause cycles) are visited at +least twice, once in preorder and once in postorder. +All other files are visited at least once. +(Hard links between directories that do not cause cycles or symbolic +links to symbolic links may cause files to be visited more than once, +or directories more than twice.) +.P +If all the members of the hierarchy have been returned, +.BR fts_read () +returns NULL and sets +.I errno +to 0. +If an error unrelated to a file in the hierarchy occurs, +.BR fts_read () +returns +NULL +and sets +.I errno +to indicate the error. +If an error related to a returned file occurs, a pointer to an +.I FTSENT +structure is returned, and +.I errno +may or may not have been set (see +.IR fts_info ). +.P +The +.I FTSENT +structures returned by +.BR fts_read () +may be overwritten after a call to +.BR fts_close () +on the same file hierarchy stream, or, after a call to +.BR fts_read () +on the same file hierarchy stream unless they represent a file of type +directory, in which case they will not be overwritten until after a call to +.BR fts_read () +after the +.I FTSENT +structure has been returned by the function +.BR fts_read () +in postorder. +.SS fts_children() +The +.BR fts_children () +function returns a pointer to an +.I FTSENT +structure describing the first entry in a NULL-terminated linked list of +the files in the directory represented by the +.I FTSENT +structure most recently returned by +.BR fts_read (). +The list is linked through the +.I fts_link +field of the +.I FTSENT +structure, and is ordered by the user-specified comparison function, if any. +Repeated calls to +.BR fts_children () +will re-create this linked list. +.P +As a special case, if +.BR fts_read () +has not yet been called for a hierarchy, +.BR fts_children () +will return a pointer to the files in the logical directory specified to +.BR fts_open (), +that is, the arguments specified to +.BR fts_open (). +Otherwise, if the +.I FTSENT +structure most recently returned by +.BR fts_read () +is not a directory being visited in preorder, +or the directory does not contain any files, +.BR fts_children () +returns +NULL +and sets +.I errno +to zero. +If an error occurs, +.BR fts_children () +returns +NULL +and sets +.I errno +to indicate the error. +.P +The +.I FTSENT +structures returned by +.BR fts_children () +may be overwritten after a call to +.BR fts_children (), +.BR fts_close (), +or +.BR fts_read () +on the same file hierarchy stream. +.P +The +.I instr +argument is either zero or the following value: +.\" .Bl -tag -width FTS_NAMEONLY +.TP +.B FTS_NAMEONLY +Only the names of the files are needed. +The contents of all the fields in the returned linked list of structures +are undefined with the exception of the +.I fts_name +and +.I fts_namelen +fields. +.\" .El +.SS fts_set() +The function +.BR fts_set () +allows the user application to determine further processing for the +file +.I f +of the stream +.IR ftsp . +The +.BR fts_set () +function +returns 0 on success, and \-1 if an error occurs. +.P +The +.I instr +argument is either 0 (meaning "do nothing") or one of the following values: +.\" .Bl -tag -width FTS_PHYSICAL +.TP +.B FTS_AGAIN +Revisit the file; any file type may be revisited. +The next call to +.BR fts_read () +will return the referenced file. +The +.I fts_stat +and +.I fts_info +fields of the structure will be reinitialized at that time, +but no other fields will have been changed. +This option is meaningful only for the most recently returned +file from +.BR fts_read (). +Normal use is for postorder directory visits, where it causes the +directory to be revisited (in both preorder and postorder) as well as all +of its descendants. +.TP +.B FTS_FOLLOW +The referenced file must be a symbolic link. +If the referenced file is the one most recently returned by +.BR fts_read (), +the next call to +.BR fts_read () +returns the file with the +.I fts_info +and +.I fts_statp +fields reinitialized to reflect the target of the symbolic link instead +of the symbolic link itself. +If the file is one of those most recently returned by +.BR fts_children (), +the +.I fts_info +and +.I fts_statp +fields of the structure, when returned by +.BR fts_read (), +will reflect the target of the symbolic link instead of the symbolic link +itself. +In either case, if the target of the symbolic link does not exist, the +fields of the returned structure will be unchanged and the +.I fts_info +field will be set to +.BR FTS_SLNONE . +.IP +If the target of the link is a directory, the preorder return, followed +by the return of all of its descendants, followed by a postorder return, +is done. +.TP +.B FTS_SKIP +No descendants of this file are visited. +The file may be one of those most recently returned by either +.BR fts_children () +or +.BR fts_read (). +.\" .El +.SS fts_close() +The +.BR fts_close () +function closes the file hierarchy stream referred to by +.I ftsp +and restores the current directory to the directory from which +.BR fts_open () +was called to open +.IR ftsp . +The +.BR fts_close () +function +returns 0 on success, and \-1 if an error occurs. +.SH ERRORS +The function +.BR fts_open () +may fail and set +.I errno +for any of the errors specified for +.BR open (2) +and +.BR malloc (3). +.P +In addition, +.BR fts_open () +may fail and set +.I errno +as follows: +.TP +.B ENOENT +Any element of +.I path_argv +was an empty string. +.P +The function +.BR fts_close () +may fail and set +.I errno +for any of the errors specified for +.BR chdir (2) +and +.BR close (2). +.P +The functions +.BR fts_read () +and +.BR fts_children () +may fail and set +.I errno +for any of the errors specified for +.BR chdir (2), +.BR malloc (3), +.BR opendir (3), +.BR readdir (3), +and +.RB [ l ]\c +.BR stat (2). +.P +In addition, +.BR fts_children (), +.BR fts_open (), +and +.BR fts_set () +may fail and set +.I errno +as follows: +.TP +.B EINVAL +.I options +or +.I instr +was invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fts_open (), +.BR fts_set (), +.BR fts_close () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR fts_read (), +.BR fts_children () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +None. +.SH HISTORY +glibc 2. +4.4BSD. +.SH BUGS +Before glibc 2.23, +.\" Fixed by commit 8b7b7f75d91f7bac323dd6a370aeb3e9c5c4a7d5 +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=15838 +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=11460 +all of the APIs described in this man page are not safe when compiling +a program using the LFS APIs (e.g., when compiling with +.IR \-D_FILE_OFFSET_BITS=64 ). +.\" +.\" The following statement is years old, and seems no closer to +.\" being true -- mtk +.\" The +.\" .I fts +.\" utility is expected to be included in a future +.\" POSIX.1 +.\" revision. +.SH SEE ALSO +.BR find (1), +.BR chdir (2), +.BR lstat (2), +.BR stat (2), +.BR ftw (3), +.BR qsort (3) diff --git a/man/man3/fts_children.3 b/man/man3/fts_children.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man/man3/fts_children.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man/man3/fts_close.3 b/man/man3/fts_close.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man/man3/fts_close.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man/man3/fts_open.3 b/man/man3/fts_open.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man/man3/fts_open.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man/man3/fts_read.3 b/man/man3/fts_read.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man/man3/fts_read.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man/man3/fts_set.3 b/man/man3/fts_set.3 new file mode 100644 index 0000000..85caf75 --- /dev/null +++ b/man/man3/fts_set.3 @@ -0,0 +1 @@ +.so man3/fts.3 diff --git a/man/man3/ftw.3 b/man/man3/ftw.3 new file mode 100644 index 0000000..41fd4dc --- /dev/null +++ b/man/man3/ftw.3 @@ -0,0 +1,502 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) +.\" and copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" and copyright (c) 2006 Justin Pryzby +.\" and copyright (c) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 11:02:22 1993 by Rik Faith (faith@cs.unc.edu) +.\" 2006-05-24, Justin Pryzby +.\" document FTW_ACTIONRETVAL; include .SH RETURN VALUE; +.\" 2006-05-24, Justin Pryzby and +.\" Michael Kerrisk +.\" reorganized and rewrote much of the page +.\" 2006-05-24, Michael Kerrisk +.\" Added an example program. +.\" +.TH ftw 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ftw, nftw \- file tree walk +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int nftw(const char *" dirpath , +.BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb , +.BI " int " typeflag ", struct FTW *" ftwbuf ), +.BI " int " nopenfd ", int " flags ); +.P +.B [[deprecated]] +.BI "int ftw(const char *" dirpath , +.BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb , +.BI " int " typeflag ), +.BI " int " nopenfd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nftw (): +.nf + _XOPEN_SOURCE >= 500 +.fi +.SH DESCRIPTION +.BR nftw () +walks through the directory tree that is +located under the directory \fIdirpath\fP, +and calls \fIfn\fP() once for each entry in the tree. +By default, directories are handled before the files and +subdirectories they contain (preorder traversal). +.P +To avoid using up all of the calling process's file descriptors, +\fInopenfd\fP specifies the maximum number of directories that +.BR nftw () +will hold open simultaneously. +When +the search depth exceeds this, +.BR nftw () +will become slower because +directories have to be closed and reopened. +.BR nftw () +uses at most +one file descriptor for each level in the directory tree. +.P +For each entry found in the tree, +.BR nftw () +calls +\fIfn\fP() with four arguments: +.IR fpath , +.IR sb , +.IR typeflag , +and +.IR ftwbuf . +.I fpath +is the pathname of the entry, +and is expressed either as a pathname relative to the calling process's +current working directory at the time of the call to +.BR nftw (), +if +.I dirpath +was expressed as a relative pathname, +or as an absolute pathname, if +.I dirpath +was expressed as an absolute pathname. +.I sb +is a pointer to the +.I stat +structure returned by a call to +.BR stat (2) +for +.IR fpath . +.P +The +.I typeflag +argument passed to +.IR fn () +is an integer that has one of the following values: +.TP +.B FTW_F +.I fpath +is a regular file. +.TP +.B FTW_D +.I fpath +is a directory. +.TP +.B FTW_DNR +.I fpath +is a directory which can't be read. +.TP +.B FTW_DP +.I fpath +is a directory, and \fBFTW_DEPTH\fP was specified in \fIflags\fP. +(If +.B FTW_DEPTH +was not specified in +.IR flags , +then directories will always be visited with +.I typeflag +set to +.BR FTW_D .) +All of the files +and subdirectories within \fIfpath\fP have been processed. +.TP +.B FTW_NS +The +.BR stat (2) +call failed on +.IR fpath , +which is not a symbolic link. +The probable cause for this is that the caller had read permission +on the parent directory, so that the filename +.I fpath +could be seen, +but did not have execute permission, +so that the file could not be reached for +.BR stat (2). +The contents of the buffer pointed to by +.I sb +are undefined. +.TP +.B FTW_SL +.I fpath +is a symbolic link, and \fBFTW_PHYS\fP was set in \fIflags\fP. +.\" To obtain the definition of this constant from +.\" .IR , +.\" either +.\" .B _BSD_SOURCE +.\" must be defined, or +.\" .BR _XOPEN_SOURCE +.\" must be defined with a value of 500 or more. +.TP +.B FTW_SLN +.I fpath +is a symbolic link pointing to a nonexistent file. +(This occurs only if \fBFTW_PHYS\fP is not set.) +In this case the +.I sb +argument passed to +.IR fn () +contains information returned by performing +.BR lstat (2) +on the "dangling" symbolic link. +(But see BUGS.) +.P +The fourth argument +.RI ( ftwbuf ) +that +.BR nftw () +supplies when calling +\fIfn\fP() +is a pointer to a structure of type \fIFTW\fP: +.P +.in +4n +.EX +struct FTW { + int base; + int level; +}; +.EE +.in +.P +.I base +is the offset of the filename (i.e., basename component) +in the pathname given in +.IR fpath . +.I level +is the depth of +.I fpath +in the directory tree, relative to the root of the tree +.RI ( dirpath , +which has depth 0). +.P +To stop the tree walk, \fIfn\fP() returns a nonzero value; this +value will become the return value of +.BR nftw (). +As long as \fIfn\fP() returns 0, +.BR nftw () +will continue either until it has traversed the entire tree, +in which case it will return zero, +or until it encounters an error (such as a +.BR malloc (3) +failure), in which case it will return \-1. +.P +Because +.BR nftw () +uses dynamic data structures, the only safe way to +exit out of a tree walk is to return a nonzero value from \fIfn\fP(). +To allow a signal to terminate the walk without causing a memory leak, +have the handler set a global flag that is checked by \fIfn\fP(). +\fIDon't\fP use +.BR longjmp (3) +unless the program is going to terminate. +.P +The \fIflags\fP argument of +.BR nftw () +is formed by ORing zero or more of the +following flags: +.TP +.BR FTW_ACTIONRETVAL " (since glibc 2.3.3)" +If this glibc-specific flag is set, then +.BR nftw () +handles the return value from +.IR fn () +differently. +.IR fn () +should return one of the following values: +.RS +.TP +.B FTW_CONTINUE +Instructs +.BR nftw () +to continue normally. +.TP +.B FTW_SKIP_SIBLINGS +If \fIfn\fP() returns this value, then +siblings of the current entry will be skipped, +and processing continues in the parent. +.\" If \fBFTW_DEPTH\fP +.\" is set, the entry's parent directory is processed next (with +.\" \fIflag\fP set to \fBFTW_DP\fP). +.TP +.B FTW_SKIP_SUBTREE +If \fIfn\fP() is called with an entry that is a directory +(\fItypeflag\fP is \fBFTW_D\fP), this return +value will prevent objects within that directory from being passed as +arguments to \fIfn\fP(). +.BR nftw () +continues processing with the next sibling of the directory. +.TP +.B FTW_STOP +Causes +.BR nftw () +to return immediately with the return value +\fBFTW_STOP\fP. +.P +Other return values could be associated with new actions in the future; +\fIfn\fP() should not return values other than those listed above. +.P +The feature test macro +.B _GNU_SOURCE +must be defined +(before including +.I any +header files) +in order to +obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI\fP. +.RE +.TP +.B FTW_CHDIR +If set, do a +.BR chdir (2) +to each directory before handling its contents. +This is useful if the program needs to perform some action +in the directory in which \fIfpath\fP resides. +(Specifying this flag has no effect on the pathname that is passed in the +.I fpath +argument of +.IR fn .) +.TP +.B FTW_DEPTH +If set, do a post-order traversal, that is, call \fIfn\fP() for +the directory itself \fIafter\fP handling the contents of the directory +and its subdirectories. +(By default, each directory is handled \fIbefore\fP its contents.) +.TP +.B FTW_MOUNT +If set, stay within the same filesystem +(i.e., do not cross mount points). +.TP +.B FTW_PHYS +If set, do not follow symbolic links. +(This is what you want.) +If not set, symbolic links are followed, but no file is reported twice. +.IP +If \fBFTW_PHYS\fP is not set, but \fBFTW_DEPTH\fP is set, +then the function +.IR fn () +is never called for a directory that would be a descendant of itself. +.SS ftw() +.BR ftw () +is an older function that offers a subset of the functionality of +.BR nftw (). +The notable differences are as follows: +.IP \[bu] 3 +.BR ftw () +has no +.I flags +argument. +It behaves the same as when +.BR nftw () +is called with +.I flags +specified as zero. +.IP \[bu] +The callback function, +.IR fn (), +is not supplied with a fourth argument. +.IP \[bu] +The range of values that is passed via the +.I typeflag +argument supplied to +.IR fn () +is smaller: just +.BR FTW_F , +.BR FTW_D , +.BR FTW_DNR , +.BR FTW_NS , +and (possibly) +.BR FTW_SL . +.SH RETURN VALUE +These functions return 0 on success, and \-1 if an error occurs. +.P +If \fIfn\fP() returns nonzero, +then the tree walk is terminated and the value returned by \fIfn\fP() +is returned as the result of +.BR ftw () +or +.BR nftw (). +.P +If +.BR nftw () +is called with the \fBFTW_ACTIONRETVAL\fP flag, +then the only nonzero value that should be used by \fIfn\fP() +to terminate the tree walk is \fBFTW_STOP\fP, +and that value is returned as the result of +.BR nftw (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nftw () +T} Thread safety MT-Safe cwd +T{ +.na +.nh +.BR ftw () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +In some implementations (e.g., glibc), +.BR ftw () +will never use \fBFTW_SL\fP; on other systems \fBFTW_SL\fP occurs only +for symbolic links that do not point to an existing file; +and again on other systems +.BR ftw () +will use \fBFTW_SL\fP for each symbolic link. +If +.I fpath +is a symbolic link and +.BR stat (2) +failed, POSIX.1-2008 states +that it is undefined whether \fBFTW_NS\fP or \fBFTW_SL\fP +is passed in +.IR typeflag . +For predictable results, use +.BR nftw (). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR ftw () +POSIX.1-2001, SVr4, SUSv1. +POSIX.1-2008 marks it as obsolete. +.TP +.BR nftw () +glibc 2.1. +POSIX.1-2001, SUSv1. +.TP +.B FTW_SL +POSIX.1-2001, SUSv1. +.SH NOTES +POSIX.1-2008 notes that the results are unspecified if +.I fn +does not preserve the current working directory. +.SH BUGS +According to POSIX.1-2008, when the +.I typeflag +argument passed to +.IR fn () +contains +.BR FTW_SLN , +the buffer pointed to by +.I sb +should contain information about the dangling symbolic link +(obtained by calling +.BR lstat (2) +on the link). +Early glibc versions correctly followed the POSIX specification on this point. +However, as a result of a regression introduced in glibc 2.4, +the contents of the buffer pointed to by +.I sb +were undefined when +.B FTW_SLN +is passed in +.IR typeflag . +(More precisely, the contents of the buffer were left unchanged in this case.) +This regression was eventually fixed in glibc 2.30, +.\" https://bugzilla.redhat.com/show_bug.cgi?id=1422736 +.\" http://austingroupbugs.net/view.php?id=1121 +.\" glibc commit 6ba205b2c35e3e024c8c12d2ee1b73363e84da87 +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=23501 +so that the glibc implementation (once more) follows the POSIX specification. +.SH EXAMPLES +The following program traverses the directory tree under the path named +in its first command-line argument, or under the current directory +if no argument is supplied. +It displays various information about each file. +The second command-line argument can be used to specify characters that +control the value assigned to the \fIflags\fP +argument when calling +.BR nftw (). +.SS Program source +\& +.\" SRC BEGIN (ftw.c) +.EX +#define _XOPEN_SOURCE 500 +#include +#include +#include +#include +#include +\& +static int +display_info(const char *fpath, const struct stat *sb, + int tflag, struct FTW *ftwbuf) +{ + printf("%\-3s %2d ", + (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" : + (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? "f" : + (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" : + (tflag == FTW_SLN) ? "sln" : "???", + ftwbuf\->level); +\& + if (tflag == FTW_NS) + printf("\-\-\-\-\-\-\-"); + else + printf("%7jd", (intmax_t) sb\->st_size); +\& + printf(" %\-40s %d %s\en", + fpath, ftwbuf\->base, fpath + ftwbuf\->base); +\& + return 0; /* To tell nftw() to continue */ +} +\& +int +main(int argc, char *argv[]) +{ + int flags = 0; +\& + if (argc > 2 && strchr(argv[2], \[aq]d\[aq]) != NULL) + flags |= FTW_DEPTH; + if (argc > 2 && strchr(argv[2], \[aq]p\[aq]) != NULL) + flags |= FTW_PHYS; +\& + if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) + == \-1) + { + perror("nftw"); + exit(EXIT_FAILURE); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR stat (2), +.BR fts (3), +.BR readdir (3) diff --git a/man/man3/funlockfile.3 b/man/man3/funlockfile.3 new file mode 100644 index 0000000..b33c2ee --- /dev/null +++ b/man/man3/funlockfile.3 @@ -0,0 +1 @@ +.so man3/flockfile.3 diff --git a/man/man3/futimens.3 b/man/man3/futimens.3 new file mode 100644 index 0000000..a365c7b --- /dev/null +++ b/man/man3/futimens.3 @@ -0,0 +1 @@ +.so man2/utimensat.2 diff --git a/man/man3/futimes.3 b/man/man3/futimes.3 new file mode 100644 index 0000000..2ac7627 --- /dev/null +++ b/man/man3/futimes.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright (c) 2006, 2008, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH futimes 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +futimes, lutimes \- change file timestamps +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int futimes(int " fd ", const struct timeval " tv [2]); +.BI "int lutimes(const char *" filename ", const struct timeval " tv [2]); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR futimes (), +.BR lutimes (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR futimes () +changes the access and modification times of a file in the same way as +.BR utimes (2), +with the difference that the file whose timestamps are to be changed +is specified via a file descriptor, +.IR fd , +rather than via a pathname. +.P +.BR lutimes () +changes the access and modification times of a file in the same way as +.BR utimes (2), +with the difference that if +.I filename +refers to a symbolic link, then the link is not dereferenced: +instead, the timestamps of the symbolic link are changed. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Errors are as for +.BR utimes (2), +with the following additions for +.BR futimes (): +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOSYS +The +.I /proc +filesystem could not be accessed. +.P +The following additional error may occur for +.BR lutimes (): +.TP +.B ENOSYS +The kernel does not support this call; Linux 2.6.22 or later is required. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR futimes (), +.BR lutimes () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +Linux, BSD. +.SH HISTORY +.TP +.BR futimes () +glibc 2.3. +.TP +.BR lutimes () +glibc 2.6. +.SH NOTES +.BR lutimes () +is implemented using the +.BR utimensat (2) +system call. +.SH SEE ALSO +.BR utime (2), +.BR utimensat (2), +.BR symlink (7) diff --git a/man/man3/fwide.3 b/man/man3/fwide.3 new file mode 100644 index 0000000..01f2081 --- /dev/null +++ b/man/man3/fwide.3 @@ -0,0 +1,92 @@ +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH fwide 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fwide \- set and determine the orientation of a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fwide(FILE *" stream ", int " mode ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fwide (): +.nf + _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE + || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +When \fImode\fP is zero, the +.BR fwide () +function determines the current +orientation of \fIstream\fP. +It returns a positive value if \fIstream\fP is +wide-character oriented, that is, if wide-character I/O is permitted but char +I/O is disallowed. +It returns a negative value if \fIstream\fP is byte oriented\[em]that is, +if char I/O is permitted but wide-character I/O is disallowed. +It +returns zero if \fIstream\fP has no orientation yet; in this case the next +I/O operation might change the orientation (to byte oriented if it is a char +I/O operation, or to wide-character oriented if it is a wide-character I/O +operation). +.P +Once a stream has an orientation, it cannot be changed and persists until +the stream is closed. +.P +When \fImode\fP is nonzero, the +.BR fwide () +function first attempts to set +\fIstream\fP's orientation (to wide-character oriented +if \fImode\fP is greater than 0, or +to byte oriented if \fImode\fP is less than 0). +It then returns a value denoting the +current orientation, as above. +.SH RETURN VALUE +The +.BR fwide () +function returns the stream's orientation, after possibly +changing it. +A positive return value means wide-character oriented. +A negative return value means byte oriented. +A return value of zero means undecided. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +Wide-character output to a byte oriented stream can be performed through the +.BR fprintf (3) +function with the +.B %lc +and +.B %ls +directives. +.P +Char oriented output to a wide-character oriented stream can be performed +through the +.BR fwprintf (3) +function with the +.B %c +and +.B %s +directives. +.SH SEE ALSO +.BR fprintf (3), +.BR fwprintf (3) diff --git a/man/man3/fwprintf.3 b/man/man3/fwprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man/man3/fwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man/man3/fwrite.3 b/man/man3/fwrite.3 new file mode 100644 index 0000000..86906ed --- /dev/null +++ b/man/man3/fwrite.3 @@ -0,0 +1 @@ +.so man3/fread.3 diff --git a/man/man3/fwrite_unlocked.3 b/man/man3/fwrite_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/fwrite_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/gai_cancel.3 b/man/man3/gai_cancel.3 new file mode 100644 index 0000000..1b0f392 --- /dev/null +++ b/man/man3/gai_cancel.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo_a.3 diff --git a/man/man3/gai_error.3 b/man/man3/gai_error.3 new file mode 100644 index 0000000..1b0f392 --- /dev/null +++ b/man/man3/gai_error.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo_a.3 diff --git a/man/man3/gai_strerror.3 b/man/man3/gai_strerror.3 new file mode 100644 index 0000000..17f7236 --- /dev/null +++ b/man/man3/gai_strerror.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo.3 diff --git a/man/man3/gai_suspend.3 b/man/man3/gai_suspend.3 new file mode 100644 index 0000000..1b0f392 --- /dev/null +++ b/man/man3/gai_suspend.3 @@ -0,0 +1 @@ +.so man3/getaddrinfo_a.3 diff --git a/man/man3/gamma.3 b/man/man3/gamma.3 new file mode 100644 index 0000000..082da41 --- /dev/null +++ b/man/man3/gamma.3 @@ -0,0 +1,121 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Modified 2003-11-18, aeb: historical remarks +.\" +.TH gamma 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gamma, gammaf, gammal \- (logarithm of the) gamma function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] double gamma(double " x ");" +.BI "[[deprecated]] float gammaf(float " x ");" +.BI "[[deprecated]] long double gammal(long double " x ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gamma (): +.nf + _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR gammaf (), +.BR gammal (): +.nf + _XOPEN_SOURCE >= 600 || (_XOPEN_SOURCE && _ISOC99_SOURCE) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions are deprecated: instead, use either the +.BR tgamma (3) +or the +.BR lgamma (3) +functions, as appropriate. +.P +For the definition of the Gamma function, see +.BR tgamma (3). +.SS *BSD version +The libm in 4.4BSD and some versions of FreeBSD had a +.BR gamma () +function that computes the Gamma function, as one would expect. +.SS glibc version +glibc has a +.BR gamma () +function that is equivalent to +.BR lgamma (3) +and computes the natural logarithm of the Gamma function. +.SH RETURN VALUE +See +.BR lgamma (3). +.SH ERRORS +See +.BR lgamma (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gamma (), +.BR gammaf (), +.BR gammal () +T} Thread safety MT-Unsafe race:signgam +.TE +.SH STANDARDS +None. +.SH HISTORY +SVID 2. +.P +Because of historical variations in behavior across systems, +this function is not specified in any recent standard. +.P +4.2BSD had a +.BR gamma () +that computed +.RI ln(|Gamma(| x |)|), +leaving the sign of +.RI Gamma(| x |) +in the external integer +.IR signgam . +In 4.3BSD the name was changed to +.BR lgamma (3), +and the man page promises +.P +.in +4n +"At some time in the future the name gamma will be rehabilitated +and used for the Gamma function" +.in +.P +This did indeed happen in 4.4BSD, where +.BR gamma () +computes the Gamma function (with no effect on +.IR signgam ). +However, this came too late, and we now have +.BR tgamma (3), +the "true gamma" function. +.\" The FreeBSD man page says about gamma() that it is like lgamma() +.\" except that is does not set signgam. +.\" Also, that 4.4BSD has a gamma() that computes the true gamma function. +.SH SEE ALSO +.BR lgamma (3), +.BR signgam (3), +.BR tgamma (3) diff --git a/man/man3/gammaf.3 b/man/man3/gammaf.3 new file mode 100644 index 0000000..64ab6ee --- /dev/null +++ b/man/man3/gammaf.3 @@ -0,0 +1 @@ +.so man3/gamma.3 diff --git a/man/man3/gammal.3 b/man/man3/gammal.3 new file mode 100644 index 0000000..64ab6ee --- /dev/null +++ b/man/man3/gammal.3 @@ -0,0 +1 @@ +.so man3/gamma.3 diff --git a/man/man3/gcvt.3 b/man/man3/gcvt.3 new file mode 100644 index 0000000..d563327 --- /dev/null +++ b/man/man3/gcvt.3 @@ -0,0 +1,82 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:32:25 1993 by Rik Faith (faith@cs.unc.edu) +.TH gcvt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gcvt \- convert a floating-point number to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *gcvt(double " number ", int " ndigit ", char *" buf ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gcvt (): +.nf + Since glibc 2.17 + (_XOPEN_SOURCE >= 500 && ! (_POSIX_C_SOURCE >= 200809L)) + || /* glibc >= 2.20 */ _DEFAULT_SOURCE + || /* glibc <= 2.19 */ _SVID_SOURCE + glibc 2.12 to glibc 2.16: + (_XOPEN_SOURCE >= 500 && ! (_POSIX_C_SOURCE >= 200112L)) + || _SVID_SOURCE + Before glibc 2.12: + _SVID_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +The +.BR gcvt () +function converts \fInumber\fP to a minimal length null-terminated +ASCII string and stores the result in \fIbuf\fP. +It produces \fIndigit\fP significant digits in either +.BR printf (3) +F format or E format. +.SH RETURN VALUE +The +.BR gcvt () +function returns +\fIbuf\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gcvt () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +Marked as LEGACY in POSIX.1-2001. +POSIX.1-2008 removed it, +recommending the use of +.BR sprintf (3) +instead (though +.BR snprintf (3) +may be preferable). +.SH SEE ALSO +.BR ecvt (3), +.BR fcvt (3), +.BR sprintf (3) diff --git a/man/man3/get_avphys_pages.3 b/man/man3/get_avphys_pages.3 new file mode 100644 index 0000000..cbd22cc --- /dev/null +++ b/man/man3/get_avphys_pages.3 @@ -0,0 +1 @@ +.so man3/get_phys_pages.3 diff --git a/man/man3/get_current_dir_name.3 b/man/man3/get_current_dir_name.3 new file mode 100644 index 0000000..f73c157 --- /dev/null +++ b/man/man3/get_current_dir_name.3 @@ -0,0 +1 @@ +.so man3/getcwd.3 diff --git a/man/man3/get_myaddress.3 b/man/man3/get_myaddress.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/get_myaddress.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/get_nprocs.3 b/man/man3/get_nprocs.3 new file mode 100644 index 0000000..96446a5 --- /dev/null +++ b/man/man3/get_nprocs.3 @@ -0,0 +1,93 @@ +'\" t +.\" Copyright (c) 2012, Petr Benas +.\" and Copyright (c) 2012, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH get_nprocs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +get_nprocs, get_nprocs_conf \- get number of processors +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B int get_nprocs(void); +.B int get_nprocs_conf(void); +.fi +.SH DESCRIPTION +The function +.BR get_nprocs_conf () +returns the number of processors configured by the operating system. +.P +The function +.BR get_nprocs () +returns the number of processors currently available in the system. +This may be less than the number returned by +.BR get_nprocs_conf () +because processors may be offline (e.g., on hotpluggable systems). +.SH RETURN VALUE +As given in DESCRIPTION. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR get_nprocs (), +.BR get_nprocs_conf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH NOTES +The current +.\" glibc 2.15 +implementation of these functions is rather expensive, +since they open and parse files in the +.I /sys +filesystem each time they are called. +.P +The following +.BR sysconf (3) +calls make use of the functions documented on this page +to return the same information. +.P +.in +4n +.EX +np = sysconf(_SC_NPROCESSORS_CONF); /* processors configured */ +np = sysconf(_SC_NPROCESSORS_ONLN); /* processors available */ +.EE +.in +.SH EXAMPLES +The following example shows how +.BR get_nprocs () +and +.BR get_nprocs_conf () +can be used. +.P +.\" SRC BEGIN (get_nprocs_conf.c) +.EX +#include +#include +#include +\& +int +main(void) +{ + printf("This system has %d processors configured and " + "%d processors available.\en", + get_nprocs_conf(), get_nprocs()); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR nproc (1) diff --git a/man/man3/get_nprocs_conf.3 b/man/man3/get_nprocs_conf.3 new file mode 100644 index 0000000..7de3e2b --- /dev/null +++ b/man/man3/get_nprocs_conf.3 @@ -0,0 +1 @@ +.so man3/get_nprocs.3 diff --git a/man/man3/get_phys_pages.3 b/man/man3/get_phys_pages.3 new file mode 100644 index 0000000..6915d7f --- /dev/null +++ b/man/man3/get_phys_pages.3 @@ -0,0 +1,90 @@ +.\" Copyright (c) 2015 William Woodruff (william@tuffbizz.com) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH get_phys_pages 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +get_phys_pages, get_avphys_pages \- get total and available physical +page counts +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.B long get_phys_pages(void); +.B long get_avphys_pages(void); +.fi +.SH DESCRIPTION +The function +.BR get_phys_pages () +returns the total number of physical pages of memory available on the system. +.P +The function +.BR get_avphys_pages () +returns the number of currently available physical pages of memory on the +system. +.SH RETURN VALUE +On success, +these functions return a nonnegative value as given in DESCRIPTION. +On failure, they return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B ENOSYS +The system could not provide the required information +(possibly because the +.I /proc +filesystem was not mounted). +.SH STANDARDS +GNU. +.SH HISTORY +Before glibc 2.23, +these functions obtained the required information by scanning the +.I MemTotal +and +.I MemFree +fields of +.IR /proc/meminfo . +Since glibc 2.23, +these functions obtain the required information by calling +.BR sysinfo (2). +.SH NOTES +The following +.BR sysconf (3) +calls provide a portable means of obtaining the same information as the +functions described on this page. +.P +.in +4n +.EX +total_pages = sysconf(_SC_PHYS_PAGES); /* total pages */ +avl_pages = sysconf(_SC_AVPHYS_PAGES); /* available pages */ +.EE +.in +.SH EXAMPLES +The following example shows how +.BR get_phys_pages () +and +.BR get_avphys_pages () +can be used. +.P +.\" SRC BEGIN (get_phys_pages.c) +.EX +#include +#include +#include +\& +int +main(void) +{ + printf("This system has %ld pages of physical memory and " + "%ld pages of physical memory available.\en", + get_phys_pages(), get_avphys_pages()); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sysconf (3) diff --git a/man/man3/getaddrinfo.3 b/man/man3/getaddrinfo.3 new file mode 100644 index 0000000..d8be6f1 --- /dev/null +++ b/man/man3/getaddrinfo.3 @@ -0,0 +1,854 @@ +'\" t +.\" Copyright (c) 2007, 2008 Michael Kerrisk +.\" and Copyright (c) 2006 Ulrich Drepper +.\" A few pieces of an earlier version remain: +.\" Copyright 2000, Sam Varshavchik +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References: RFC 2553 +.\" +.\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED, +.\" and AI_NUMERICSERV. +.\" 2006-11-25, Ulrich Drepper +.\" Add text describing Internationalized Domain Name extensions. +.\" 2007-06-08, mtk: added example programs +.\" 2008-02-26, mtk; clarify discussion of NULL 'hints' argument; other +.\" minor rewrites. +.\" 2008-06-18, mtk: many parts rewritten +.\" 2008-12-04, Petr Baudis +.\" Describe results ordering and reference /etc/gai.conf. +.\" +.\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support +.\" and is SCTP support now also there? +.\" +.TH getaddrinfo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getaddrinfo, freeaddrinfo, gai_strerror \- network address and +service translation +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.BI "int getaddrinfo(const char *restrict " node , +.BI " const char *restrict " service , +.BI " const struct addrinfo *restrict " hints , +.BI " struct addrinfo **restrict " res ); +.P +.BI "void freeaddrinfo(struct addrinfo *" res ); +.P +.BI "const char *gai_strerror(int " errcode ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getaddrinfo (), +.BR freeaddrinfo (), +.BR gai_strerror (): +.nf + Since glibc 2.22: + _POSIX_C_SOURCE >= 200112L + glibc 2.21 and earlier: + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +Given +.I node +and +.IR service , +which identify an Internet host and a service, +.BR getaddrinfo () +returns one or more +.I addrinfo +structures, each of which contains an Internet address +that can be specified in a call to +.BR bind (2) +or +.BR connect (2). +The +.BR getaddrinfo () +function combines the functionality provided by the +.\" .BR getipnodebyname (3), +.\" .BR getipnodebyaddr (3), +.BR gethostbyname (3) +and +.BR getservbyname (3) +functions into a single interface, but unlike the latter functions, +.BR getaddrinfo () +is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies. +.P +The +.I addrinfo +structure used by +.BR getaddrinfo () +contains the following fields: +.P +.in +4n +.EX +struct addrinfo { + int ai_flags; + int ai_family; + int ai_socktype; + int ai_protocol; + socklen_t ai_addrlen; + struct sockaddr *ai_addr; + char *ai_canonname; + struct addrinfo *ai_next; +}; +.EE +.in +.P +The +.I hints +argument points to an +.I addrinfo +structure that specifies criteria for selecting the socket address +structures returned in the list pointed to by +.IR res . +If +.I hints +is not NULL it points to an +.I addrinfo +structure whose +.IR ai_family , +.IR ai_socktype , +and +.I ai_protocol +specify criteria that limit the set of socket addresses returned by +.BR getaddrinfo (), +as follows: +.TP +.I ai_family +This field specifies the desired address family for the returned addresses. +Valid values for this field include +.B AF_INET +and +.BR AF_INET6 . +The value +.B AF_UNSPEC +indicates that +.BR getaddrinfo () +should return socket addresses for any address family +(either IPv4 or IPv6, for example) that can be used with +.I node +and +.IR service . +.TP +.I ai_socktype +This field specifies the preferred socket type, for example +.B SOCK_STREAM +or +.BR SOCK_DGRAM . +Specifying 0 in this field indicates that socket addresses of any type +can be returned by +.BR getaddrinfo (). +.TP +.I ai_protocol +This field specifies the protocol for the returned socket addresses. +Specifying 0 in this field indicates that socket addresses with +any protocol can be returned by +.BR getaddrinfo (). +.TP +.I ai_flags +This field specifies additional options, described below. +Multiple flags are specified by bitwise OR-ing them together. +.P +All the other fields in the structure pointed to by +.I hints +must contain either 0 or a null pointer, as appropriate. +.P +Specifying +.I hints +as NULL is equivalent to setting +.I ai_socktype +and +.I ai_protocol +to 0; +.I ai_family +to +.BR AF_UNSPEC ; +and +.I ai_flags +to +.BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)" . +(POSIX specifies different defaults for +.IR ai_flags ; +see NOTES.) +.I node +specifies either a numerical network address +(for IPv4, numbers-and-dots notation as supported by +.BR inet_aton (3); +for IPv6, hexadecimal string format as supported by +.BR inet_pton (3)), +or a network hostname, whose network addresses are looked up and resolved. +If +.I hints.ai_flags +contains the +.B AI_NUMERICHOST +flag, then +.I node +must be a numerical network address. +The +.B AI_NUMERICHOST +flag suppresses any potentially lengthy network host address lookups. +.P +If the +.B AI_PASSIVE +flag is specified in +.IR hints.ai_flags , +and +.I node +is NULL, +then the returned socket addresses will be suitable for +.BR bind (2)ing +a socket that will +.BR accept (2) +connections. +The returned socket address will contain the "wildcard address" +.RB ( INADDR_ANY +for IPv4 addresses, +.B IN6ADDR_ANY_INIT +for IPv6 address). +The wildcard address is used by applications (typically servers) +that intend to accept connections on any of the host's network addresses. +If +.I node +is not NULL, then the +.B AI_PASSIVE +flag is ignored. +.P +If the +.B AI_PASSIVE +flag is not set in +.IR hints.ai_flags , +then the returned socket addresses will be suitable for use with +.BR connect (2), +.BR sendto (2), +or +.BR sendmsg (2). +If +.I node +is NULL, +then the network address will be set to the loopback interface address +.RB ( INADDR_LOOPBACK +for IPv4 addresses, +.B IN6ADDR_LOOPBACK_INIT +for IPv6 address); +this is used by applications that intend to communicate +with peers running on the same host. +.P +.I service +sets the port in each returned address structure. +If this argument is a service name (see +.BR services (5)), +it is translated to the corresponding port number. +This argument can also be specified as a decimal number, +which is simply converted to binary. +If +.I service +is NULL, then the port number of the returned socket addresses +will be left uninitialized. +If +.B AI_NUMERICSERV +is specified in +.I hints.ai_flags +and +.I service +is not NULL, then +.I service +must point to a string containing a numeric port number. +This flag is used to inhibit the invocation of a name resolution service +in cases where it is known not to be required. +.P +Either +.I node +or +.IR service , +but not both, may be NULL. +.P +The +.BR getaddrinfo () +function allocates and initializes a linked list of +.I addrinfo +structures, one for each network address that matches +.I node +and +.IR service , +subject to any restrictions imposed by +.IR hints , +and returns a pointer to the start of the list in +.IR res . +The items in the linked list are linked by the +.I ai_next +field. +.P +There are several reasons why +the linked list may have more than one +.I addrinfo +structure, including: the network host is multihomed, accessible +over multiple protocols (e.g., both +.B AF_INET +and +.BR AF_INET6 ); +or the same service is available from multiple socket types (one +.B SOCK_STREAM +address and another +.B SOCK_DGRAM +address, for example). +Normally, the application should try +using the addresses in the order in which they are returned. +The sorting function used within +.BR getaddrinfo () +is defined in RFC\ 3484; the order can be tweaked for a particular +system by editing +.I /etc/gai.conf +(available since glibc 2.5). +.P +If +.I hints.ai_flags +includes the +.B AI_CANONNAME +flag, then the +.I ai_canonname +field of the first of the +.I addrinfo +structures in the returned list is set to point to the +official name of the host. +.\" Prior to glibc 2.3.4, the ai_canonname of each addrinfo +.\" structure was set pointing to the canonical name; that was +.\" more than POSIX.1-2001 specified, or other implementations provided. +.\" MTK, Aug 05 +.P +The remaining fields of each returned +.I addrinfo +structure are initialized as follows: +.IP \[bu] 3 +The +.IR ai_family , +.IR ai_socktype , +and +.I ai_protocol +fields return the socket creation parameters (i.e., these fields have +the same meaning as the corresponding arguments of +.BR socket (2)). +For example, +.I ai_family +might return +.B AF_INET +or +.BR AF_INET6 ; +.I ai_socktype +might return +.B SOCK_DGRAM +or +.BR SOCK_STREAM ; +and +.I ai_protocol +returns the protocol for the socket. +.IP \[bu] +A pointer to the socket address is placed in the +.I ai_addr +field, and the length of the socket address, in bytes, +is placed in the +.I ai_addrlen +field. +.P +If +.I hints.ai_flags +includes the +.B AI_ADDRCONFIG +flag, then IPv4 addresses are returned in the list pointed to by +.I res +only if the local system has at least one +IPv4 address configured, and IPv6 addresses are returned +only if the local system has at least one IPv6 address configured. +The loopback address is not considered for this case as valid +as a configured address. +This flag is useful on, for example, +IPv4-only systems, to ensure that +.BR getaddrinfo () +does not return IPv6 socket addresses that would always fail in +.BR connect (2) +or +.BR bind (2). +.P +If +.I hints.ai_flags +specifies the +.B AI_V4MAPPED +flag, and +.I hints.ai_family +was specified as +.BR AF_INET6 , +and no matching IPv6 addresses could be found, +then return IPv4-mapped IPv6 addresses in the list pointed to by +.IR res . +If both +.B AI_V4MAPPED +and +.B AI_ALL +are specified in +.IR hints.ai_flags , +then return both IPv6 and IPv4-mapped IPv6 addresses +in the list pointed to by +.IR res . +.B AI_ALL +is ignored if +.B AI_V4MAPPED +is not also specified. +.P +The +.BR freeaddrinfo () +function frees the memory that was allocated +for the dynamically allocated linked list +.IR res . +.SS Extensions to getaddrinfo() for Internationalized Domain Names +Starting with glibc 2.3.4, +.BR getaddrinfo () +has been extended to selectively allow the incoming and outgoing +hostnames to be transparently converted to and from the +Internationalized Domain Name (IDN) format (see RFC 3490, +.IR "Internationalizing Domain Names in Applications (IDNA)" ). +Four new flags are defined: +.TP +.B AI_IDN +If this flag is specified, then the node name given in +.I node +is converted to IDN format if necessary. +The source encoding is that of the current locale. +.IP +If the input name contains non-ASCII characters, then the IDN encoding +is used. +Those parts of the node name (delimited by dots) that contain +non-ASCII characters are encoded using ASCII Compatible Encoding (ACE) +before being passed to the name resolution functions. +.\" Implementation Detail: +.\" To minimize effects on system performance the implementation might +.\" want to check whether the input string contains any non-ASCII +.\" characters. If there are none the IDN step can be skipped completely. +.\" On systems which allow not-ASCII safe encodings for a locale this +.\" might be a problem. +.TP +.B AI_CANONIDN +After a successful name lookup, and if the +.B AI_CANONNAME +flag was specified, +.BR getaddrinfo () +will return the canonical name of the +node corresponding to the +.I addrinfo +structure value passed back. +The return value is an exact copy of the value returned by the name +resolution function. +.IP +If the name is encoded using ACE, then it will contain the +.I xn\-\- +prefix for one or more components of the name. +To convert these components into a readable form the +.B AI_CANONIDN +flag can be passed in addition to +.BR AI_CANONNAME . +The resulting string is encoded using the current locale's encoding. +.\" +.\"Implementation Detail: +.\"If no component of the returned name starts with xn\-\- the IDN +.\"step can be skipped, therefore avoiding unnecessary slowdowns. +.TP +.B AI_IDN_ALLOW_UNASSIGNED +.TQ +.B AI_IDN_USE_STD3_ASCII_RULES +Setting these flags will enable the +IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and +IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 +conforming hostname) +flags respectively to be used in the IDNA handling. +.SH RETURN VALUE +.\" FIXME glibc defines the following additional errors, some which +.\" can probably be returned by getaddrinfo(); they need to +.\" be documented. +.\" #ifdef __USE_GNU +.\" #define EAI_INPROGRESS -100 /* Processing request in progress. */ +.\" #define EAI_CANCELED -101 /* Request canceled. */ +.\" #define EAI_NOTCANCELED -102 /* Request not canceled. */ +.\" #define EAI_ALLDONE -103 /* All requests done. */ +.\" #define EAI_INTR -104 /* Interrupted by a signal. */ +.\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */ +.\" #endif +.BR getaddrinfo () +returns 0 if it succeeds, or one of the following nonzero error codes: +.TP +.B EAI_ADDRFAMILY +.\" Not in SUSv3 +The specified network host does not have any network addresses in the +requested address family. +.TP +.B EAI_AGAIN +The name server returned a temporary failure indication. +Try again later. +.TP +.B EAI_BADFLAGS +.I hints.ai_flags +contains invalid flags; or, +.I hints.ai_flags +included +.B AI_CANONNAME +and +.I node +was NULL. +.TP +.B EAI_FAIL +The name server returned a permanent failure indication. +.TP +.B EAI_FAMILY +The requested address family is not supported. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_NODATA +.\" Not in SUSv3 +The specified network host exists, but does not have any +network addresses defined. +.TP +.B EAI_NONAME +The +.I node +or +.I service +is not known; or both +.I node +and +.I service +are NULL; or +.B AI_NUMERICSERV +was specified in +.I hints.ai_flags +and +.I service +was not a numeric port-number string. +.TP +.B EAI_SERVICE +The requested service is not available for the requested socket type. +It may be available through another socket type. +For example, this error could occur if +.I service +was "shell" (a service available only on stream sockets), and either +.I hints.ai_protocol +was +.BR IPPROTO_UDP , +or +.I hints.ai_socktype +was +.BR SOCK_DGRAM ; +or the error could occur if +.I service +was not NULL, and +.I hints.ai_socktype +was +.B SOCK_RAW +(a socket type that does not support the concept of services). +.TP +.B EAI_SOCKTYPE +The requested socket type is not supported. +This could occur, for example, if +.I hints.ai_socktype +and +.I hints.ai_protocol +are inconsistent (e.g., +.B SOCK_DGRAM +and +.BR IPPROTO_TCP , +respectively). +.TP +.B EAI_SYSTEM +Other system error; +.I errno +is set to indicate the error. +.P +The +.BR gai_strerror () +function translates these error codes to a human readable string, +suitable for error reporting. +.SH FILES +.I /etc/gai.conf +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getaddrinfo () +T} Thread safety MT-Safe env locale +T{ +.na +.nh +.BR freeaddrinfo (), +.BR gai_strerror () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +According to POSIX.1, specifying +.\" POSIX.1-2001, POSIX.1-2008 +.I hints +as NULL should cause +.I ai_flags +to be assumed as 0. +The GNU C library instead assumes a value of +.B (AI_V4MAPPED\~|\~AI_ADDRCONFIG) +for this case, +since this value is considered an improvement on the specification. +.SH STANDARDS +POSIX.1-2008. +.TP +.BR getaddrinfo () +RFC\ 2553. +.SH HISTORY +POSIX.1-2001. +.TP +.B AI_ADDRCONFIG +.TQ +.B AI_ALL +.TQ +.B AI_V4MAPPED +glibc 2.3.3. +.TP +.B AI_NUMERICSERV +glibc 2.3.4. +.SH NOTES +.BR getaddrinfo () +supports the +.IB address % scope-id +notation for specifying the IPv6 scope-ID. +.SH EXAMPLES +.\" getnameinfo.3 refers to this example +.\" socket.2 refers to this example +.\" bind.2 refers to this example +.\" connect.2 refers to this example +.\" recvfrom.2 refers to this example +.\" sendto.2 refers to this example +The following programs demonstrate the use of +.BR getaddrinfo (), +.BR gai_strerror (), +.BR freeaddrinfo (), +and +.BR getnameinfo (3). +The programs are an echo server and client for UDP datagrams. +.SS Server program +\& +.\" SRC BEGIN (server.c) +.EX +#include +#include +#include +#include +#include +#include +#include +\& +#define BUF_SIZE 500 +\& +int +main(int argc, char *argv[]) +{ + int sfd, s; + char buf[BUF_SIZE]; + ssize_t nread; + socklen_t peer_addrlen; + struct addrinfo hints; + struct addrinfo *result, *rp; + struct sockaddr_storage peer_addr; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s port\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + memset(&hints, 0, sizeof(hints)); + hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */ + hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */ + hints.ai_flags = AI_PASSIVE; /* For wildcard IP address */ + hints.ai_protocol = 0; /* Any protocol */ + hints.ai_canonname = NULL; + hints.ai_addr = NULL; + hints.ai_next = NULL; +\& + s = getaddrinfo(NULL, argv[1], &hints, &result); + if (s != 0) { + fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s)); + exit(EXIT_FAILURE); + } +\& + /* getaddrinfo() returns a list of address structures. + Try each address until we successfully bind(2). + If socket(2) (or bind(2)) fails, we (close the socket + and) try the next address. */ +\& + for (rp = result; rp != NULL; rp = rp\->ai_next) { + sfd = socket(rp\->ai_family, rp\->ai_socktype, + rp\->ai_protocol); + if (sfd == \-1) + continue; +\& + if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0) + break; /* Success */ +\& + close(sfd); + } +\& + freeaddrinfo(result); /* No longer needed */ +\& + if (rp == NULL) { /* No address succeeded */ + fprintf(stderr, "Could not bind\en"); + exit(EXIT_FAILURE); + } +\& + /* Read datagrams and echo them back to sender. */ +\& + for (;;) { + char host[NI_MAXHOST], service[NI_MAXSERV]; +\& + peer_addrlen = sizeof(peer_addr); + nread = recvfrom(sfd, buf, BUF_SIZE, 0, + (struct sockaddr *) &peer_addr, &peer_addrlen); + if (nread == \-1) + continue; /* Ignore failed request */ +\& + s = getnameinfo((struct sockaddr *) &peer_addr, + peer_addrlen, host, NI_MAXHOST, + service, NI_MAXSERV, NI_NUMERICSERV); + if (s == 0) + printf("Received %zd bytes from %s:%s\en", + nread, host, service); + else + fprintf(stderr, "getnameinfo: %s\en", gai_strerror(s)); +\& + if (sendto(sfd, buf, nread, 0, (struct sockaddr *) &peer_addr, + peer_addrlen) != nread) + { + fprintf(stderr, "Error sending response\en"); + } + } +} +.EE +.\" SRC END +.SS Client program +\& +.\" SRC BEGIN (client.c) +.EX +#include +#include +#include +#include +#include +#include +#include +\& +#define BUF_SIZE 500 +\& +int +main(int argc, char *argv[]) +{ + int sfd, s; + char buf[BUF_SIZE]; + size_t len; + ssize_t nread; + struct addrinfo hints; + struct addrinfo *result, *rp; +\& + if (argc < 3) { + fprintf(stderr, "Usage: %s host port msg...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Obtain address(es) matching host/port. */ +\& + memset(&hints, 0, sizeof(hints)); + hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */ + hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */ + hints.ai_flags = 0; + hints.ai_protocol = 0; /* Any protocol */ +\& + s = getaddrinfo(argv[1], argv[2], &hints, &result); + if (s != 0) { + fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s)); + exit(EXIT_FAILURE); + } +\& + /* getaddrinfo() returns a list of address structures. + Try each address until we successfully connect(2). + If socket(2) (or connect(2)) fails, we (close the socket + and) try the next address. */ +\& + for (rp = result; rp != NULL; rp = rp\->ai_next) { + sfd = socket(rp\->ai_family, rp\->ai_socktype, + rp\->ai_protocol); + if (sfd == \-1) + continue; +\& + if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1) + break; /* Success */ +\& + close(sfd); + } +\& + freeaddrinfo(result); /* No longer needed */ +\& + if (rp == NULL) { /* No address succeeded */ + fprintf(stderr, "Could not connect\en"); + exit(EXIT_FAILURE); + } +\& + /* Send remaining command\-line arguments as separate + datagrams, and read responses from server. */ +\& + for (size_t j = 3; j < argc; j++) { + len = strlen(argv[j]) + 1; + /* +1 for terminating null byte */ +\& + if (len > BUF_SIZE) { + fprintf(stderr, + "Ignoring long message in argument %zu\en", j); + continue; + } +\& + if (write(sfd, argv[j], len) != len) { + fprintf(stderr, "partial/failed write\en"); + exit(EXIT_FAILURE); + } +\& + nread = read(sfd, buf, BUF_SIZE); + if (nread == \-1) { + perror("read"); + exit(EXIT_FAILURE); + } +\& + printf("Received %zd bytes: %s\en", nread, buf); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.\" .BR getipnodebyaddr (3), +.\" .BR getipnodebyname (3), +.BR getaddrinfo_a (3), +.BR gethostbyname (3), +.BR getnameinfo (3), +.BR inet (3), +.BR gai.conf (5), +.BR hostname (7), +.BR ip (7) diff --git a/man/man3/getaddrinfo_a.3 b/man/man3/getaddrinfo_a.3 new file mode 100644 index 0000000..373165a --- /dev/null +++ b/man/man3/getaddrinfo_a.3 @@ -0,0 +1,645 @@ +'\" t +.\" Copyright (c) 2009 Petr Baudis +.\" and clean-ups and additions (C) Copyright 2010 Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References: http://people.redhat.com/drepper/asynchnl.pdf, +.\" http://www.imperialviolet.org/2005/06/01/asynchronous-dns-lookups-with-glibc.html +.\" +.TH getaddrinfo_a 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getaddrinfo_a, gai_suspend, gai_error, gai_cancel \- asynchronous +network address and service translation +.SH LIBRARY +Asynchronous name lookup library +.RI ( libanl ", " \-lanl ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int getaddrinfo_a(int " mode ", struct gaicb *" list [restrict], +.BI " int " nitems ", struct sigevent *restrict " sevp ); +.BI "int gai_suspend(const struct gaicb *const " list "[], int " nitems , +.BI " const struct timespec *" timeout ); +.P +.BI "int gai_error(struct gaicb *" req ); +.BI "int gai_cancel(struct gaicb *" req ); +.fi +.SH DESCRIPTION +The +.BR getaddrinfo_a () +function performs the same task as +.BR getaddrinfo (3), +but allows multiple name look-ups to be performed asynchronously, +with optional notification on completion of look-up operations. +.P +The +.I mode +argument has one of the following values: +.TP +.B GAI_WAIT +Perform the look-ups synchronously. +The call blocks until the look-ups have completed. +.TP +.B GAI_NOWAIT +Perform the look-ups asynchronously. +The call returns immediately, +and the requests are resolved in the background. +See the discussion of the +.I sevp +argument below. +.P +The array +.I list +specifies the look-up requests to process. +The +.I nitems +argument specifies the number of elements in +.IR list . +The requested look-up operations are started in parallel. +NULL elements in +.I list +are ignored. +Each request is described by a +.I gaicb +structure, defined as follows: +.P +.in +4n +.EX +struct gaicb { + const char *ar_name; + const char *ar_service; + const struct addrinfo *ar_request; + struct addrinfo *ar_result; +}; +.EE +.in +.P +The elements of this structure correspond to the arguments of +.BR getaddrinfo (3). +Thus, +.I ar_name +corresponds to the +.I node +argument and +.I ar_service +to the +.I service +argument, identifying an Internet host and a service. +The +.I ar_request +element corresponds to the +.I hints +argument, specifying the criteria for selecting +the returned socket address structures. +Finally, +.I ar_result +corresponds to the +.I res +argument; you do not need to initialize this element, +it will be automatically set when the request +is resolved. +The +.I addrinfo +structure referenced by the last two elements is described in +.BR getaddrinfo (3). +.P +When +.I mode +is specified as +.BR GAI_NOWAIT , +notifications about resolved requests +can be obtained by employing the +.I sigevent +structure pointed to by the +.I sevp +argument. +For the definition and general details of this structure, see +.BR sigevent (3type). +The +.I sevp\->sigev_notify +field can have the following values: +.TP +.B SIGEV_NONE +Don't provide any notification. +.TP +.B SIGEV_SIGNAL +When a look-up completes, generate the signal +.I sigev_signo +for the process. +See +.BR sigevent (3type) +for general details. +The +.I si_code +field of the +.I siginfo_t +structure will be set to +.BR SI_ASYNCNL . +.\" si_pid and si_uid are also set, to the values of the calling process, +.\" which doesn't provide useful information, so we'll skip mentioning it. +.TP +.B SIGEV_THREAD +When a look-up completes, invoke +.I sigev_notify_function +as if it were the start function of a new thread. +See +.BR sigevent (3type) +for details. +.P +For +.B SIGEV_SIGNAL +and +.BR SIGEV_THREAD , +it may be useful to point +.I sevp\->sigev_value.sival_ptr +to +.IR list . +.P +The +.BR gai_suspend () +function suspends execution of the calling thread, +waiting for the completion of one or more requests in the array +.IR list . +The +.I nitems +argument specifies the size of the array +.IR list . +The call blocks until one of the following occurs: +.IP \[bu] 3 +One or more of the operations in +.I list +completes. +.IP \[bu] +The call is interrupted by a signal that is caught. +.IP \[bu] +The time interval specified in +.I timeout +elapses. +This argument specifies a timeout in seconds plus nanoseconds (see +.BR nanosleep (2) +for details of the +.I timespec +structure). +If +.I timeout +is NULL, then the call blocks indefinitely +(until one of the events above occurs). +.P +No explicit indication of which request was completed is given; +you must determine which request(s) have completed by iterating with +.BR gai_error () +over the list of requests. +.P +The +.BR gai_error () +function returns the status of the request +.IR req : +either +.B EAI_INPROGRESS +if the request was not completed yet, +0 if it was handled successfully, +or an error code if the request could not be resolved. +.P +The +.BR gai_cancel () +function cancels the request +.IR req . +If the request has been canceled successfully, +the error status of the request will be set to +.B EAI_CANCELED +and normal asynchronous notification will be performed. +The request cannot be canceled if it is currently being processed; +in that case, it will be handled as if +.BR gai_cancel () +has never been called. +If +.I req +is NULL, an attempt is made to cancel all outstanding requests +that the process has made. +.SH RETURN VALUE +The +.BR getaddrinfo_a () +function returns 0 if all of the requests have been enqueued successfully, +or one of the following nonzero error codes: +.TP +.B EAI_AGAIN +The resources necessary to enqueue the look-up requests were not available. +The application may check the error status of each +request to determine which ones failed. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_SYSTEM +.I mode +is invalid. +.P +The +.BR gai_suspend () +function returns 0 if at least one of the listed requests has been completed. +Otherwise, it returns one of the following nonzero error codes: +.TP +.B EAI_AGAIN +The given timeout expired before any of the requests could be completed. +.TP +.B EAI_ALLDONE +There were no actual requests given to the function. +.TP +.B EAI_INTR +A signal has interrupted the function. +Note that this interruption might have been +caused by signal notification of some completed look-up request. +.P +The +.BR gai_error () +function can return +.B EAI_INPROGRESS +for an unfinished look-up request, +0 for a successfully completed look-up +(as described above), one of the error codes that could be returned by +.BR getaddrinfo (3), +or the error code +.B EAI_CANCELED +if the request has been canceled explicitly before it could be finished. +.P +The +.BR gai_cancel () +function can return one of these values: +.TP +.B EAI_CANCELED +The request has been canceled successfully. +.TP +.B EAI_NOTCANCELED +The request has not been canceled. +.TP +.B EAI_ALLDONE +The request has already completed. +.P +The +.BR gai_strerror (3) +function translates these error codes to a human readable string, +suitable for error reporting. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getaddrinfo_a (), +.BR gai_suspend (), +.BR gai_error (), +.BR gai_cancel () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.2.3. +.P +The interface of +.BR getaddrinfo_a () +was modeled after the +.BR lio_listio (3) +interface. +.SH EXAMPLES +Two examples are provided: a simple example that resolves +several requests in parallel synchronously, and a complex example +showing some of the asynchronous capabilities. +.SS Synchronous example +The program below simply resolves several hostnames in parallel, +giving a speed-up compared to resolving the hostnames sequentially using +.BR getaddrinfo (3). +The program might be used like this: +.P +.in +4n +.EX +$ \fB./a.out mirrors.kernel.org enoent.linuxfoundation.org gnu.org\fP +mirrors.kernel.org: 139.178.88.99 +enoent.linuxfoundation.org: Name or service not known +gnu.org: 209.51.188.116 +.EE +.in +.P +Here is the program source code +.P +.\" SRC BEGIN (sync.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +\& +#define MALLOC(n, type) ((type *) reallocarray(NULL, n, sizeof(type))) +\& +int +main(int argc, char *argv[]) +{ + int ret; + struct gaicb *reqs[argc \- 1]; + char host[NI_MAXHOST]; + struct addrinfo *res; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s HOST...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + for (size_t i = 0; i < argc \- 1; i++) { + reqs[i] = MALLOC(1, struct gaicb); + if (reqs[i] == NULL) + err(EXIT_FAILURE, "malloc"); +\& + memset(reqs[i], 0, sizeof(*reqs[0])); + reqs[i]\->ar_name = argv[i + 1]; + } +\& + ret = getaddrinfo_a(GAI_WAIT, reqs, argc \- 1, NULL); + if (ret != 0) { + fprintf(stderr, "getaddrinfo_a() failed: %s\en", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } +\& + for (size_t i = 0; i < argc \- 1; i++) { + printf("%s: ", reqs[i]\->ar_name); + ret = gai_error(reqs[i]); + if (ret == 0) { + res = reqs[i]\->ar_result; +\& + ret = getnameinfo(res\->ai_addr, res\->ai_addrlen, + host, sizeof(host), + NULL, 0, NI_NUMERICHOST); + if (ret != 0) { + fprintf(stderr, "getnameinfo() failed: %s\en", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } + puts(host); +\& + } else { + puts(gai_strerror(ret)); + } + } + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS Asynchronous example +This example shows a simple interactive +.BR getaddrinfo_a () +front-end. +The notification facility is not demonstrated. +.P +An example session might look like this: +.P +.in +4n +.EX +$ \fB./a.out\fP +> a mirrors.kernel.org enoent.linuxfoundation.org gnu.org +> c 2 +[2] gnu.org: Request not canceled +> w 0 1 +[00] mirrors.kernel.org: Finished +> l +[00] mirrors.kernel.org: 139.178.88.99 +[01] enoent.linuxfoundation.org: Processing request in progress +[02] gnu.org: 209.51.188.116 +> l +[00] mirrors.kernel.org: 139.178.88.99 +[01] enoent.linuxfoundation.org: Name or service not known +[02] gnu.org: 209.51.188.116 +.EE +.in +.P +The program source is as follows: +.P +.\" SRC BEGIN (async.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +\& +#define CALLOC(n, type) ((type *) calloc(n, sizeof(type))) +\& +#define REALLOCF(ptr, n, type) \e +({ \e + static_assert(__builtin_types_compatible_p(typeof(ptr), type *)); \e + \e + (type *) reallocarrayf(ptr, n, sizeof(type)); \e +}) +\& +static struct gaicb **reqs = NULL; +static size_t nreqs = 0; +\& +static inline void * +reallocarrayf(void *p, size_t nmemb, size_t size) +{ + void *q; +\& + q = reallocarray(p, nmemb, size); + if (q == NULL && nmemb != 0 && size != 0) + free(p); + return q; +} +\& +static char * +getcmd(void) +{ + static char buf[256]; +\& + fputs("> ", stdout); fflush(stdout); + if (fgets(buf, sizeof(buf), stdin) == NULL) + return NULL; +\& + if (buf[strlen(buf) \- 1] == \[aq]\en\[aq]) + buf[strlen(buf) \- 1] = 0; +\& + return buf; +} +\& +/* Add requests for specified hostnames. */ +static void +add_requests(void) +{ + size_t nreqs_base = nreqs; + char *host; + int ret; +\& + while ((host = strtok(NULL, " "))) { + nreqs++; + reqs = REALLOCF(reqs, nreqs, struct gaicb *); + if (reqs == NULL) + err(EXIT_FAILURE, "reallocf"); +\& + reqs[nreqs \- 1] = CALLOC(1, struct gaicb); + if (reqs[nreqs \- 1] == NULL) + err(EXIT_FAILURE, "calloc"); +\& + reqs[nreqs \- 1]\->ar_name = strdup(host); + } +\& + /* Queue nreqs_base..nreqs requests. */ +\& + ret = getaddrinfo_a(GAI_NOWAIT, &reqs[nreqs_base], + nreqs \- nreqs_base, NULL); + if (ret) { + fprintf(stderr, "getaddrinfo_a() failed: %s\en", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } +} +\& +/* Wait until at least one of specified requests completes. */ +static void +wait_requests(void) +{ + char *id; + int ret; + size_t n; + struct gaicb const **wait_reqs; +\& + wait_reqs = CALLOC(nreqs, const struct gaicb *); + if (wait_reqs == NULL) + err(EXIT_FAILURE, "calloc"); +\& + /* NULL elements are ignored by gai_suspend(). */ +\& + while ((id = strtok(NULL, " ")) != NULL) { + n = atoi(id); +\& + if (n >= nreqs) { + printf("Bad request number: %s\en", id); + return; + } +\& + wait_reqs[n] = reqs[n]; + } +\& + ret = gai_suspend(wait_reqs, nreqs, NULL); + if (ret) { + printf("gai_suspend(): %s\en", gai_strerror(ret)); + return; + } +\& + for (size_t i = 0; i < nreqs; i++) { + if (wait_reqs[i] == NULL) + continue; +\& + ret = gai_error(reqs[i]); + if (ret == EAI_INPROGRESS) + continue; +\& + printf("[%02zu] %s: %s\en", i, reqs[i]\->ar_name, + ret == 0 ? "Finished" : gai_strerror(ret)); + } +} +\& +/* Cancel specified requests. */ +static void +cancel_requests(void) +{ + char *id; + int ret; + size_t n; +\& + while ((id = strtok(NULL, " ")) != NULL) { + n = atoi(id); +\& + if (n >= nreqs) { + printf("Bad request number: %s\en", id); + return; + } +\& + ret = gai_cancel(reqs[n]); + printf("[%s] %s: %s\en", id, reqs[atoi(id)]\->ar_name, + gai_strerror(ret)); + } +} +\& +/* List all requests. */ +static void +list_requests(void) +{ + int ret; + char host[NI_MAXHOST]; + struct addrinfo *res; +\& + for (size_t i = 0; i < nreqs; i++) { + printf("[%02zu] %s: ", i, reqs[i]\->ar_name); + ret = gai_error(reqs[i]); +\& + if (!ret) { + res = reqs[i]\->ar_result; +\& + ret = getnameinfo(res\->ai_addr, res\->ai_addrlen, + host, sizeof(host), + NULL, 0, NI_NUMERICHOST); + if (ret) { + fprintf(stderr, "getnameinfo() failed: %s\en", + gai_strerror(ret)); + exit(EXIT_FAILURE); + } + puts(host); + } else { + puts(gai_strerror(ret)); + } + } +} +\& +int +main(void) +{ + char *cmdline; + char *cmd; +\& + while ((cmdline = getcmd()) != NULL) { + cmd = strtok(cmdline, " "); +\& + if (cmd == NULL) { + list_requests(); + } else { + switch (cmd[0]) { + case \[aq]a\[aq]: + add_requests(); + break; + case \[aq]w\[aq]: + wait_requests(); + break; + case \[aq]c\[aq]: + cancel_requests(); + break; + case \[aq]l\[aq]: + list_requests(); + break; + default: + fprintf(stderr, "Bad command: %c\en", cmd[0]); + break; + } + } + } + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getaddrinfo (3), +.BR inet (3), +.BR lio_listio (3), +.BR hostname (7), +.BR ip (7), +.BR sigevent (3type) diff --git a/man/man3/getaliasbyname.3 b/man/man3/getaliasbyname.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man/man3/getaliasbyname.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man/man3/getaliasbyname_r.3 b/man/man3/getaliasbyname_r.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man/man3/getaliasbyname_r.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man/man3/getaliasent.3 b/man/man3/getaliasent.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man/man3/getaliasent.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man/man3/getaliasent_r.3 b/man/man3/getaliasent_r.3 new file mode 100644 index 0000000..37dcf19 --- /dev/null +++ b/man/man3/getaliasent_r.3 @@ -0,0 +1 @@ +.so man3/setaliasent.3 diff --git a/man/man3/getauxval.3 b/man/man3/getauxval.3 new file mode 100644 index 0000000..8639916 --- /dev/null +++ b/man/man3/getauxval.3 @@ -0,0 +1,272 @@ +'\" t +.\" Copyright 2012 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" See also https://lwn.net/Articles/519085/ +.\" +.TH getauxval 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getauxval \- retrieve a value from the auxiliary vector +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "unsigned long getauxval(unsigned long " type ); +.fi +.SH DESCRIPTION +The +.BR getauxval () +function retrieves values from the auxiliary vector, +a mechanism that the kernel's ELF binary loader +uses to pass certain information to +user space when a program is executed. +.P +Each entry in the auxiliary vector consists of a pair of values: +a type that identifies what this entry represents, +and a value for that type. +Given the argument +.IR type , +.BR getauxval () +returns the corresponding value. +.P +The value returned for each +.I type +is given in the following list. +Not all +.I type +values are present on all architectures. +.TP +.B AT_BASE +The base address of the program interpreter (usually, the dynamic linker). +.TP +.B AT_BASE_PLATFORM +A pointer to a string (PowerPC and MIPS only). +On PowerPC, this identifies the real platform; may differ from +.BR AT_PLATFORM "." +On MIPS, +.\" commit e585b768da111f2c2d413de6214e83bbdfee8f22 +this identifies the ISA level (since Linux 5.7). +.TP +.B AT_CLKTCK +The frequency with which +.BR times (2) +counts. +This value can also be obtained via +.IR sysconf(_SC_CLK_TCK) . +.TP +.B AT_DCACHEBSIZE +The data cache block size. +.TP +.B AT_EGID +The effective group ID of the thread. +.TP +.B AT_ENTRY +The entry address of the executable. +.TP +.B AT_EUID +The effective user ID of the thread. +.TP +.B AT_EXECFD +File descriptor of program. +.TP +.B AT_EXECFN +A pointer to a string containing the pathname used to execute the program. +.TP +.B AT_FLAGS +Flags (unused). +.TP +.B AT_FPUCW +Used FPU control word (SuperH architecture only). +This gives some information about the FPU initialization +performed by the kernel. +.TP +.B AT_GID +The real group ID of the thread. +.TP +.B AT_HWCAP +An architecture and ABI dependent bit-mask whose settings +indicate detailed processor capabilities. +The contents of the bit mask are hardware dependent +(for example, see the kernel source file +.I arch/x86/include/asm/cpufeature.h +for details relating to the Intel x86 architecture; the value +returned is the first 32-bit word of the array described there). +A human-readable version of the same information is available via +.IR /proc/cpuinfo . +.TP +.BR AT_HWCAP2 " (since glibc 2.18)" +Further machine-dependent hints about processor capabilities. +.TP +.B AT_ICACHEBSIZE +The instruction cache block size. +.\" .TP +.\" .BR AT_IGNORE +.\" .TP +.\" .BR AT_IGNOREPPC +.\" .TP +.\" .BR AT_NOTELF +.TP +.\" Kernel commit 98a5f361b8625c6f4841d6ba013bbf0e80d08147 +.B AT_L1D_CACHEGEOMETRY +Geometry of the L1 data cache, encoded with the cache line size in bytes +in the bottom 16 bits and the cache associativity in the next 16 bits. +The associativity is such that if N is the 16-bit value, +the cache is N-way set associative. +.TP +.B AT_L1D_CACHESIZE +The L1 data cache size. +.TP +.B AT_L1I_CACHEGEOMETRY +Geometry of the L1 instruction cache, encoded as for +.BR AT_L1D_CACHEGEOMETRY . +.TP +.B AT_L1I_CACHESIZE +The L1 instruction cache size. +.TP +.B AT_L2_CACHEGEOMETRY +Geometry of the L2 cache, encoded as for +.BR AT_L1D_CACHEGEOMETRY . +.TP +.B AT_L2_CACHESIZE +The L2 cache size. +.TP +.B AT_L3_CACHEGEOMETRY +Geometry of the L3 cache, encoded as for +.BR AT_L1D_CACHEGEOMETRY . +.TP +.B AT_L3_CACHESIZE +The L3 cache size. +.TP +.B AT_PAGESZ +The system page size (the same value returned by +.IR sysconf(_SC_PAGESIZE) ). +.TP +.B AT_PHDR +The address of the program headers of the executable. +.TP +.B AT_PHENT +The size of program header entry. +.TP +.B AT_PHNUM +The number of program headers. +.TP +.B AT_PLATFORM +A pointer to a string that identifies the hardware platform +that the program is running on. +The dynamic linker uses this in the interpretation of +.I rpath +values. +.TP +.B AT_RANDOM +The address of sixteen bytes containing a random value. +.TP +.B AT_SECURE +Has a nonzero value if this executable should be treated securely. +Most commonly, a nonzero value indicates that the process is +executing a set-user-ID or set-group-ID binary +(so that its real and effective UIDs or GIDs differ from one another), +or that it gained capabilities by executing +a binary file that has capabilities (see +.BR capabilities (7)). +Alternatively, +a nonzero value may be triggered by a Linux Security Module. +When this value is nonzero, +the dynamic linker disables the use of certain environment variables (see +.BR ld\-linux.so (8)) +and glibc changes other aspects of its behavior. +(See also +.BR secure_getenv (3).) +.TP +.B AT_SYSINFO +The entry point to the system call function in the vDSO. +Not present/needed on all architectures (e.g., absent on x86-64). +.TP +.B AT_SYSINFO_EHDR +The address of a page containing the virtual Dynamic Shared Object (vDSO) +that the kernel creates in order to provide fast implementations of +certain system calls. +.TP +.B AT_UCACHEBSIZE +The unified cache block size. +.TP +.B AT_UID +The real user ID of the thread. +.SH RETURN VALUE +On success, +.BR getauxval () +returns the value corresponding to +.IR type . +If +.I type +is not found, 0 is returned. +.SH ERRORS +.TP +.BR ENOENT " (since glibc 2.19)" +.\" commit b9ab448f980e296eac21ac65f53783967cc6037b +No entry corresponding to +.I type +could be found in the auxiliary vector. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getauxval () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.16. +.SH NOTES +The primary consumer of the information in the auxiliary vector +is the dynamic linker, +.BR ld\-linux.so (8). +The auxiliary vector is a convenient and efficient shortcut +that allows the kernel to communicate a certain set of standard +information that the dynamic linker usually or always needs. +In some cases, the same information could be obtained by system calls, +but using the auxiliary vector is cheaper. +.P +The auxiliary vector resides just above the argument list and +environment in the process address space. +The auxiliary vector supplied to a program can be viewed by setting the +.B LD_SHOW_AUXV +environment variable when running a program: +.P +.in +4n +.EX +$ LD_SHOW_AUXV=1 sleep 1 +.EE +.in +.P +The auxiliary vector of any process can (subject to file permissions) +be obtained via +.IR /proc/ pid /auxv ; +see +.BR proc (5) +for more information. +.SH BUGS +Before the addition of the +.B ENOENT +error in glibc 2.19, +there was no way to unambiguously distinguish the case where +.I type +could not be found from the case where the value corresponding to +.I type +was zero. +.SH SEE ALSO +.BR execve (2), +.BR secure_getenv (3), +.BR vdso (7), +.BR ld\-linux.so (8) diff --git a/man/man3/getc.3 b/man/man3/getc.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man/man3/getc.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man/man3/getc_unlocked.3 b/man/man3/getc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/getc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/getchar.3 b/man/man3/getchar.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man/man3/getchar.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man/man3/getchar_unlocked.3 b/man/man3/getchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/getchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/getcontext.3 b/man/man3/getcontext.3 new file mode 100644 index 0000000..879cfe8 --- /dev/null +++ b/man/man3/getcontext.3 @@ -0,0 +1,201 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getcontext 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getcontext, setcontext \- get or set the user context +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getcontext(ucontext_t *" ucp ); +.BI "int setcontext(const ucontext_t *" ucp ); +.fi +.SH DESCRIPTION +In a System V-like environment, one has the two types +.I mcontext_t +and +.I ucontext_t +defined in +.I +and the four functions +.BR getcontext (), +.BR setcontext (), +.BR makecontext (3), +and +.BR swapcontext (3) +that allow user-level context switching between multiple +threads of control within a process. +.P +The +.I mcontext_t +type is machine-dependent and opaque. +The +.I ucontext_t +type is a structure that has at least +the following fields: +.P +.in +4n +.EX +typedef struct ucontext_t { + struct ucontext_t *uc_link; + sigset_t uc_sigmask; + stack_t uc_stack; + mcontext_t uc_mcontext; + ... +} ucontext_t; +.EE +.in +.P +with +.I sigset_t +and +.I stack_t +defined in +.IR . +Here +.I uc_link +points to the context that will be resumed +when the current context terminates (in case the current context +was created using +.BR makecontext (3)), +.I uc_sigmask +is the +set of signals blocked in this context (see +.BR sigprocmask (2)), +.I uc_stack +is the stack used by this context (see +.BR sigaltstack (2)), +and +.I uc_mcontext +is the +machine-specific representation of the saved context, +that includes the calling thread's machine registers. +.P +The function +.BR getcontext () +initializes the structure +pointed to by +.I ucp +to the currently active context. +.P +The function +.BR setcontext () +restores the user context +pointed to by +.IR ucp . +A successful call does not return. +The context should have been obtained by a call of +.BR getcontext (), +or +.BR makecontext (3), +or received as the third argument to a signal +handler (see the discussion of the +.B SA_SIGINFO +flag in +.BR sigaction (2)). +.P +If the context was obtained by a call of +.BR getcontext (), +program execution continues as if this call just returned. +.P +If the context was obtained by a call of +.BR makecontext (3), +program execution continues by a call to the function +.I func +specified as the second argument of that call to +.BR makecontext (3). +When the function +.I func +returns, we continue with the +.I uc_link +member of the structure +.I ucp +specified as the +first argument of that call to +.BR makecontext (3). +When this member is NULL, the thread exits. +.P +If the context was obtained by a call to a signal handler, +then old standard text says that "program execution continues with the +program instruction following the instruction interrupted +by the signal". +However, this sentence was removed in SUSv2, +and the present verdict is "the result is unspecified". +.SH RETURN VALUE +When successful, +.BR getcontext () +returns 0 and +.BR setcontext () +does not return. +On error, both return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +None defined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getcontext (), +.BR setcontext () +T} Thread safety MT-Safe race:ucp +.TE +.SH STANDARDS +None. +.SH HISTORY +SUSv2, POSIX.1-2001. +.P +POSIX.1-2008 removes these functions, +citing portability issues, and +recommending that applications be rewritten to use POSIX threads instead. +.SH NOTES +The earliest incarnation of this mechanism was the +.BR setjmp (3)/\c +.BR longjmp (3) +mechanism. +Since that does not define +the handling of the signal context, the next stage was the +.BR sigsetjmp (3)/\c +.BR siglongjmp (3) +pair. +The present mechanism gives much more control. +On the other hand, +there is no easy way to detect whether a return from +.BR getcontext () +is from the first call, or via a +.BR setcontext () +call. +The user has to invent their own bookkeeping device, and a register +variable won't do since registers are restored. +.P +When a signal occurs, the current user context is saved and +a new context is created by the kernel for the signal handler. +Do not leave the handler using +.BR longjmp (3): +it is undefined what would happen with contexts. +Use +.BR siglongjmp (3) +or +.BR setcontext () +instead. +.SH SEE ALSO +.BR sigaction (2), +.BR sigaltstack (2), +.BR sigprocmask (2), +.BR longjmp (3), +.BR makecontext (3), +.BR sigsetjmp (3), +.BR signal (7) diff --git a/man/man3/getcwd.3 b/man/man3/getcwd.3 new file mode 100644 index 0000000..ea3c4cf --- /dev/null +++ b/man/man3/getcwd.3 @@ -0,0 +1,311 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 21 22:35:42 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 18 Mar 1996 by Martin Schulze (joey@infodrom.north.de): +.\" Corrected description of getwd(). +.\" Modified Sat Aug 21 12:32:12 MET 1999 by aeb - applied fix by aj +.\" Modified Mon Dec 11 13:32:51 MET 2000 by aeb +.\" Modified Thu Apr 22 03:49:15 CEST 2002 by Roger Luethi +.\" +.TH getcwd 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getcwd, getwd, get_current_dir_name \- get current working directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *getcwd(char " buf [. size "], size_t " size ); +.B "char *get_current_dir_name(void);" +.P +.BI "[[deprecated]] char *getwd(char " buf [PATH_MAX]); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR get_current_dir_name (): +.nf + _GNU_SOURCE +.fi +.P +.BR getwd (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +These functions return a null-terminated string containing an +absolute pathname that is the current working directory of +the calling process. +The pathname is returned as the function result and via the argument +.IR buf , +if present. +.P +The +.BR getcwd () +function copies an absolute pathname of the current working directory +to the array pointed to by +.IR buf , +which is of length +.IR size . +.P +If the length of the absolute pathname of the current working directory, +including the terminating null byte, exceeds +.I size +bytes, NULL is returned, and +.I errno +is set to +.BR ERANGE ; +an application should check for this error, and allocate a larger +buffer if necessary. +.P +As an extension to the POSIX.1-2001 standard, glibc's +.BR getcwd () +allocates the buffer dynamically using +.BR malloc (3) +if +.I buf +is NULL. +In this case, the allocated buffer has the length +.I size +unless +.I size +is zero, when +.I buf +is allocated as big as necessary. +The caller should +.BR free (3) +the returned buffer. +.P +.BR get_current_dir_name () +will +.BR malloc (3) +an array big enough to hold the absolute pathname of +the current working directory. +If the environment +variable +.B PWD +is set, and its value is correct, then that value will be returned. +The caller should +.BR free (3) +the returned buffer. +.P +.BR getwd () +does not +.BR malloc (3) +any memory. +The +.I buf +argument should be a pointer to an array at least +.B PATH_MAX +bytes long. +If the length of the absolute pathname of the current working directory, +including the terminating null byte, exceeds +.B PATH_MAX +bytes, NULL is returned, and +.I errno +is set to +.BR ENAMETOOLONG . +(Note that on some systems, +.B PATH_MAX +may not be a compile-time constant; +furthermore, its value may depend on the filesystem, see +.BR pathconf (3).) +For portability and security reasons, use of +.BR getwd () +is deprecated. +.SH RETURN VALUE +On success, these functions return a pointer to a string containing +the pathname of the current working directory. +In the case of +.BR getcwd () +and +.BR getwd () +this is the same value as +.IR buf . +.P +On failure, these functions return NULL, and +.I errno +is set to indicate the error. +The contents of the array pointed to by +.I buf +are undefined on error. +.SH ERRORS +.TP +.B EACCES +Permission to read or search a component of the filename was denied. +.TP +.B EFAULT +.I buf +points to a bad address. +.TP +.B EINVAL +The +.I size +argument is zero and +.I buf +is not a null pointer. +.TP +.B EINVAL +.BR getwd (): +.I buf +is NULL. +.TP +.B ENAMETOOLONG +.BR getwd (): +The size of the null-terminated absolute pathname string exceeds +.B PATH_MAX +bytes. +.TP +.B ENOENT +The current working directory has been unlinked. +.TP +.B ENOMEM +Out of memory. +.TP +.B ERANGE +The +.I size +argument is less than the length of the absolute pathname of the +working directory, including the terminating null byte. +You need to allocate a bigger array and try again. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getcwd (), +.BR getwd () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR get_current_dir_name () +T} Thread safety MT-Safe env +.TE +.SH VERSIONS +POSIX.1-2001 leaves the behavior of +.BR getcwd () +unspecified if +.I buf +is NULL. +.P +POSIX.1-2001 +does not define any errors for +.BR getwd (). +.SH VERSIONS +.SS C library/kernel differences +On Linux, the kernel provides a +.BR getcwd () +system call, which the functions described in this page will use if possible. +The system call takes the same arguments as the library function +of the same name, but is limited to returning at most +.B PATH_MAX +bytes. +(Before Linux 3.12, +.\" commit 3272c544da48f8915a0e34189182aed029bd0f2b +the limit on the size of the returned pathname was the system page size. +On many architectures, +.B PATH_MAX +and the system page size are both 4096 bytes, +but a few architectures have a larger page size.) +If the length of the pathname of the current working directory +exceeds this limit, then the system call fails with the error +.BR ENAMETOOLONG . +In this case, the library functions fall back to +a (slower) alternative implementation that returns the full pathname. +.P +Following a change in Linux 2.6.36, +.\" commit 8df9d1a4142311c084ffeeacb67cd34d190eff74 +the pathname returned by the +.BR getcwd () +system call will be prefixed with the string "(unreachable)" +if the current directory is not below the root directory of the current +process (e.g., because the process set a new filesystem root using +.BR chroot (2) +without changing its current directory into the new root). +Such behavior can also be caused by an unprivileged user by changing +the current directory into another mount namespace. +When dealing with pathname from untrusted sources, callers of the +functions described in this page +should consider checking whether the returned pathname starts +with '/' or '(' to avoid misinterpreting an unreachable path +as a relative pathname. +.SH STANDARDS +.TP +.BR getcwd () +POSIX.1-2008. +.TP +.BR get_current_dir_name () +GNU. +.TP +.BR getwd () +None. +.SH HISTORY +.TP +.BR getcwd () +POSIX.1-2001. +.TP +.BR getwd () +POSIX.1-2001, but marked LEGACY. +Removed in POSIX.1-2008. +Use +.BR getcwd () +instead. +.P +Under Linux, these functions make use of the +.BR getcwd () +system call (available since Linux 2.1.92). +On older systems they would query +.IR /proc/self/cwd . +If both system call and proc filesystem are missing, a +generic implementation is called. +Only in that case can +these calls fail under Linux with +.BR EACCES . +.SH NOTES +These functions are often used to save the location of the current working +directory for the purpose of returning to it later. +Opening the current +directory (".") and calling +.BR fchdir (2) +to return is usually a faster and more reliable alternative when sufficiently +many file descriptors are available, especially on platforms other than Linux. +.SH BUGS +Since the Linux 2.6.36 change that added "(unreachable)" in the +circumstances described above, the glibc implementation of +.BR getcwd () +has failed to conform to POSIX and returned a relative pathname when the API +contract requires an absolute pathname. +With glibc 2.27 onwards this is corrected; +calling +.BR getcwd () +from such a pathname will now result in failure with +.BR ENOENT . +.SH SEE ALSO +.BR pwd (1), +.BR chdir (2), +.BR fchdir (2), +.BR open (2), +.BR unlink (2), +.BR free (3), +.BR malloc (3) diff --git a/man/man3/getdate.3 b/man/man3/getdate.3 new file mode 100644 index 0000000..f710356 --- /dev/null +++ b/man/man3/getdate.3 @@ -0,0 +1,322 @@ +'\" t +.\" Copyright 2001 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified, 2001-12-26, aeb +.\" 2008-09-07, mtk, Various rewrites; added an example program. +.\" +.TH getdate 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getdate, getdate_r \- convert a date-plus-time string to broken-down time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "struct tm *getdate(const char *" string ); +.P +.B "extern int getdate_err;" +.P +.BI "int getdate_r(const char *restrict " string ", struct tm *restrict " res ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getdate (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.P +.BR getdate_r (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The function +.BR getdate () +converts a string representation of a date and time, +contained in the buffer pointed to by +.IR string , +into a broken-down time. +The broken-down time is stored in a +.I tm +structure, and a pointer to this +structure is returned as the function result. +This +.I tm +structure is allocated in static storage, +and consequently it will be overwritten by further calls to +.BR getdate (). +.P +In contrast to +.BR strptime (3), +(which has a +.I format +argument), +.BR getdate () +uses the formats found in the file +whose full pathname is given in the environment variable +.BR DATEMSK . +The first line in the file that matches the given input string +is used for the conversion. +.P +The matching is done case insensitively. +Superfluous whitespace, either in the pattern or in the string to +be converted, is ignored. +.P +The conversion specifications that a pattern can contain are those given for +.BR strptime (3). +One more conversion specification is specified in POSIX.1-2001: +.TP +.B %Z +Timezone name. +.\" FIXME Is it (still) true that %Z is not supported in glibc? +.\" Looking at the glibc 2.21 source code, where the implementation uses +.\" strptime(), suggests that it might be supported. +This is not implemented in glibc. +.P +When +.B %Z +is given, the structure containing the broken-down time +is initialized with values corresponding to the current +time in the given timezone. +Otherwise, the structure is initialized to the broken-down time +corresponding to the current local time (as by a call to +.BR localtime (3)). +.P +When only the day of the week is given, +the day is taken to be the first such day +on or after today. +.P +When only the month is given (and no year), the month is taken to +be the first such month equal to or after the current month. +If no day is given, it is the first day of the month. +.P +When no hour, minute, and second are given, the current +hour, minute, and second are taken. +.P +If no date is given, but we know the hour, then that hour is taken +to be the first such hour equal to or after the current hour. +.P +.BR getdate_r () +is a GNU extension that provides a reentrant version of +.BR getdate (). +Rather than using a global variable to report errors and a static buffer +to return the broken down time, +it returns errors via the function result value, +and returns the resulting broken-down time in the +caller-allocated buffer pointed to by the argument +.IR res . +.SH RETURN VALUE +When successful, +.BR getdate () +returns a pointer to a +.IR "struct tm" . +Otherwise, it returns NULL and sets the global variable +.I getdate_err +to one of the error numbers shown below. +Changes to +.I errno +are unspecified. +.P +On success +.BR getdate_r () +returns 0; +on error it returns one of the error numbers shown below. +.SH ERRORS +The following errors are returned via +.I getdate_err +(for +.BR getdate ()) +or as the function result (for +.BR getdate_r ()): +.TP 4n +.B 1 +The +.B DATEMSK +environment variable is not defined, or its value is an empty string. +.TP +.B 2 +The template file specified by +.B DATEMSK +cannot be opened for reading. +.TP +.B 3 +Failed to get file status information. +.\" stat() +.TP +.B 4 +The template file is not a regular file. +.TP +.B 5 +An error was encountered while reading the template file. +.TP +.B 6 +Memory allocation failed (not enough memory available). +.\" Error 6 doesn't seem to occur in glibc +.TP +.B 7 +There is no line in the file that matches the input. +.TP +.B 8 +Invalid input specification. +.SH ENVIRONMENT +.TP +.B DATEMSK +File containing format patterns. +.TP +.B TZ +.TQ +.B LC_TIME +Variables used by +.BR strptime (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getdate () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getdate env locale +T} +T{ +.na +.nh +.BR getdate_r () +T} Thread safety T{ +.na +.nh +MT-Safe env locale +T} +.TE +.SH VERSIONS +The POSIX.1 specification for +.BR strptime (3) +contains conversion specifications using the +.B %E +or +.B %O +modifier, while such specifications are not given for +.BR getdate (). +In glibc, +.BR getdate () +is implemented using +.BR strptime (3), +so that precisely the same conversions are supported by both. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The program below calls +.BR getdate () +for each of its command-line arguments, +and for each call displays the values in the fields of the returned +.I tm +structure. +The following shell session demonstrates the operation of the program: +.P +.in +4n +.EX +.RB "$" " TFILE=$PWD/tfile" +.RB "$" " echo \[aq]%A\[aq] > $TFILE " " # Full name of the day of the week" +.RB "$" " echo \[aq]%T\[aq] >> $TFILE" " # Time (HH:MM:SS)" +.RB "$" " echo \[aq]%F\[aq] >> $TFILE" " # ISO date (YYYY\-MM\-DD)" +.RB "$" " date" +.RB "$" " export DATEMSK=$TFILE" +.RB "$" " ./a.out Tuesday \[aq]2009\-12\-28\[aq] \[aq]12:22:33\[aq]" +Sun Sep 7 06:03:36 CEST 2008 +Call 1 ("Tuesday") succeeded: + tm_sec = 36 + tm_min = 3 + tm_hour = 6 + tm_mday = 9 + tm_mon = 8 + tm_year = 108 + tm_wday = 2 + tm_yday = 252 + tm_isdst = 1 +Call 2 ("2009\-12\-28") succeeded: + tm_sec = 36 + tm_min = 3 + tm_hour = 6 + tm_mday = 28 + tm_mon = 11 + tm_year = 109 + tm_wday = 1 + tm_yday = 361 + tm_isdst = 0 +Call 3 ("12:22:33") succeeded: + tm_sec = 33 + tm_min = 22 + tm_hour = 12 + tm_mday = 7 + tm_mon = 8 + tm_year = 108 + tm_wday = 0 + tm_yday = 250 + tm_isdst = 1 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (getdate.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + struct tm *tmp; +\& + for (size_t j = 1; j < argc; j++) { + tmp = getdate(argv[j]); +\& + if (tmp == NULL) { + printf("Call %zu failed; getdate_err = %d\en", + j, getdate_err); + continue; + } +\& + printf("Call %zu (\e"%s\e") succeeded:\en", j, argv[j]); + printf(" tm_sec = %d\en", tmp\->tm_sec); + printf(" tm_min = %d\en", tmp\->tm_min); + printf(" tm_hour = %d\en", tmp\->tm_hour); + printf(" tm_mday = %d\en", tmp\->tm_mday); + printf(" tm_mon = %d\en", tmp\->tm_mon); + printf(" tm_year = %d\en", tmp\->tm_year); + printf(" tm_wday = %d\en", tmp\->tm_wday); + printf(" tm_yday = %d\en", tmp\->tm_yday); + printf(" tm_isdst = %d\en", tmp\->tm_isdst); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR time (2), +.BR localtime (3), +.BR setlocale (3), +.BR strftime (3), +.BR strptime (3) diff --git a/man/man3/getdate_err.3 b/man/man3/getdate_err.3 new file mode 100644 index 0000000..c78ed34 --- /dev/null +++ b/man/man3/getdate_err.3 @@ -0,0 +1 @@ +.so man3/getdate.3 diff --git a/man/man3/getdate_r.3 b/man/man3/getdate_r.3 new file mode 100644 index 0000000..c78ed34 --- /dev/null +++ b/man/man3/getdate_r.3 @@ -0,0 +1 @@ +.so man3/getdate.3 diff --git a/man/man3/getdelim.3 b/man/man3/getdelim.3 new file mode 100644 index 0000000..caf4e48 --- /dev/null +++ b/man/man3/getdelim.3 @@ -0,0 +1 @@ +.so man3/getline.3 diff --git a/man/man3/getdirentries.3 b/man/man3/getdirentries.3 new file mode 100644 index 0000000..3eae3f0 --- /dev/null +++ b/man/man3/getdirentries.3 @@ -0,0 +1,80 @@ +'\" t +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" Portions extracted from /usr/include/dirent.h are: +.\" Copyright 1991, 1992 Free Software Foundation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getdirentries 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getdirentries \- get directory entries in a filesystem-independent format +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t getdirentries(int " fd ", char " buf "[restrict ." nbytes "], \ +size_t " nbytes , +.BI " off_t *restrict " basep ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getdirentries (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +Read directory entries from the directory specified by +.I fd +into +.IR buf . +At most +.I nbytes +are read. +Reading starts at offset +.IR *basep , +and +.I *basep +is updated with the new position after reading. +.SH RETURN VALUE +.BR getdirentries () +returns the number of bytes read or zero when at the end of the directory. +If an error occurs, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +See the Linux library source code for details. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getdirentries () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +BSD. +.SH NOTES +Use +.BR opendir (3) +and +.BR readdir (3) +instead. +.SH SEE ALSO +.BR lseek (2), +.BR open (2) diff --git a/man/man3/getdtablesize.3 b/man/man3/getdtablesize.3 new file mode 100644 index 0000000..f9b24c0 --- /dev/null +++ b/man/man3/getdtablesize.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2002-04-15 by Roger Luethi and aeb +.\" +.TH getdtablesize 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getdtablesize \- get file descriptor table size +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B int getdtablesize(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getdtablesize (): +.nf + Since glibc 2.20: + _DEFAULT_SOURCE || ! (_POSIX_C_SOURCE >= 200112L) + glibc 2.12 to glibc 2.19: + _BSD_SOURCE || ! (_POSIX_C_SOURCE >= 200112L) + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +.BR getdtablesize () +returns the maximum number of files a process can have open, +one more than the largest possible value for a file descriptor. +.SH RETURN VALUE +The current limit on the number of open files per process. +.SH ERRORS +On Linux, +.BR getdtablesize () +can return any of the errors described for +.BR getrlimit (2); +see NOTES below. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getdtablesize () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The glibc version of +.BR getdtablesize () +calls +.BR getrlimit (2) +and returns the current +.B RLIMIT_NOFILE +limit, or +.B OPEN_MAX +when that fails. +.\" The libc4 and libc5 versions return +.\" .B OPEN_MAX +.\" (set to 256 since Linux 0.98.4). +.P +Portable applications should employ +.I sysconf(_SC_OPEN_MAX) +instead of this call. +.SH STANDARDS +None. +.SH HISTORY +SVr4, 4.4BSD +(first appeared in 4.2BSD). +.SH SEE ALSO +.BR close (2), +.BR dup (2), +.BR getrlimit (2), +.BR open (2) diff --git a/man/man3/getentropy.3 b/man/man3/getentropy.3 new file mode 100644 index 0000000..4f5d3f8 --- /dev/null +++ b/man/man3/getentropy.3 @@ -0,0 +1,103 @@ +.\" Copyright (C) 2017, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getentropy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getentropy \- fill a buffer with random bytes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getentropy(void " buffer [. length "], size_t " length ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getentropy (): +.nf + _DEFAULT_SOURCE +.fi +.SH DESCRIPTION +The +.BR getentropy () +function writes +.I length +bytes of high-quality random data to the buffer starting +at the location pointed to by +.IR buffer . +The maximum permitted value for the +.I length +argument is 256. +.P +A successful call to +.BR getentropy () +always provides the requested number of bytes of entropy. +.SH RETURN VALUE +On success, this function returns zero. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +Part or all of the buffer specified by +.I buffer +and +.I length +is not in valid addressable memory. +.TP +.B EIO +.I length +is greater than 256. +.TP +.B EIO +An unspecified error occurred while trying to overwrite +.I buffer +with random data. +.TP +.B ENOSYS +This kernel version does not implement the +.BR getrandom (2) +system call required to implement this function. +.SH STANDARDS +None. +.SH HISTORY +glibc 2.25. +OpenBSD. +.SH NOTES +The +.BR getentropy () +function is implemented using +.BR getrandom (2). +.P +Whereas the glibc wrapper makes +.BR getrandom (2) +a cancelation point, +.BR getentropy () +is not a cancelation point. +.P +.BR getentropy () +is also declared in +.BR . +(No feature test macro need be defined to obtain the declaration from +that header file.) +.P +A call to +.BR getentropy () +may block if the system has just booted and the kernel has +not yet collected enough randomness to initialize the entropy pool. +In this case, +.BR getentropy () +will keep blocking even if a signal is handled, +and will return only once the entropy pool has been initialized. +.SH SEE ALSO +.BR getrandom (2), +.BR urandom (4), +.BR random (7) diff --git a/man/man3/getenv.3 b/man/man3/getenv.3 new file mode 100644 index 0000000..c0105df --- /dev/null +++ b/man/man3/getenv.3 @@ -0,0 +1,141 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2007, 2012 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:30:29 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH getenv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getenv, secure_getenv \- get an environment variable +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *getenv(const char *" name ); +.BI "char *secure_getenv(const char *" name ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR secure_getenv (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR getenv () +function searches the environment list to find the +environment variable +.IR name , +and returns a pointer to the corresponding +.I value +string. +.P +The GNU-specific +.BR secure_getenv () +function is just like +.BR getenv () +except that it returns NULL in cases where "secure execution" is required. +Secure execution is required if one of the following conditions +was true when the program run by the calling process was loaded: +.IP \[bu] 3 +the process's effective user ID did not match its real user ID or +the process's effective group ID did not match its real group ID +(typically this is the result of executing a set-user-ID or +set-group-ID program); +.IP \[bu] +the effective capability bit was set on the executable file; or +.IP \[bu] +the process has a nonempty permitted capability set. +.P +Secure execution may also be required if triggered +by some Linux security modules. +.P +The +.BR secure_getenv () +function is intended for use in general-purpose libraries +to avoid vulnerabilities that could occur if +set-user-ID or set-group-ID programs accidentally +trusted the environment. +.SH RETURN VALUE +The +.BR getenv () +function returns a pointer to the value in the +environment, or NULL if there is no match. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getenv (), +.BR secure_getenv () +T} Thread safety MT-Safe env +.TE +.SH STANDARDS +.TP +.BR getenv () +C11, POSIX.1-2008. +.TP +.BR secure_getenv () +GNU. +.SH HISTORY +.TP +.BR getenv () +POSIX.1-2001, C89, C99, SVr4, 4.3BSD. +.TP +.BR secure_getenv () +glibc 2.17. +.SH NOTES +The strings in the environment list are of the form \fIname=value\fP. +.P +As typically implemented, +.BR getenv () +returns a pointer to a string within the environment list. +The caller must take care not to modify this string, +since that would change the environment of the process. +.P +The implementation of +.BR getenv () +is not required to be reentrant. +The string pointed to by the return value of +.BR getenv () +may be statically allocated, +and can be modified by a subsequent call to +.BR getenv (), +.BR putenv (3), +.BR setenv (3), +or +.BR unsetenv (3). +.P +The "secure execution" mode of +.BR secure_getenv () +is controlled by the +.B AT_SECURE +flag contained in the auxiliary vector passed from the kernel to user space. +.SH SEE ALSO +.BR clearenv (3), +.BR getauxval (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR capabilities (7), +.BR environ (7) diff --git a/man/man3/getfsent.3 b/man/man3/getfsent.3 new file mode 100644 index 0000000..87f3d8a --- /dev/null +++ b/man/man3/getfsent.3 @@ -0,0 +1,155 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Inspired by a page written by Walter Harms. +.\" +.TH getfsent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getfsent, getfsspec, getfsfile, setfsent, endfsent \- handle fstab entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B "int setfsent(void);" +.B "struct fstab *getfsent(void);" +.B "void endfsent(void);" +.P +.BI "struct fstab *getfsfile(const char *" mount_point ); +.BI "struct fstab *getfsspec(const char *" special_file ); +.fi +.SH DESCRIPTION +These functions read from the file +.IR /etc/fstab . +The +.I struct fstab +is defined by: +.P +.in +4n +.EX +struct fstab { + char *fs_spec; /* block device name */ + char *fs_file; /* mount point */ + char *fs_vfstype; /* filesystem type */ + char *fs_mntops; /* mount options */ + const char *fs_type; /* rw/rq/ro/sw/xx option */ + int fs_freq; /* dump frequency, in days */ + int fs_passno; /* pass number on parallel dump */ +}; +.EE +.in +.P +Here the field +.I fs_type +contains (on a *BSD system) +one of the five strings "rw", "rq", "ro", "sw", "xx" +(read-write, read-write with quota, read-only, swap, ignore). +.P +The function +.BR setfsent () +opens the file when required and positions it at the first line. +.P +The function +.BR getfsent () +parses the next line from the file. +(After opening it when required.) +.P +The function +.BR endfsent () +closes the file when required. +.P +The function +.BR getfsspec () +searches the file from the start and returns the first entry found +for which the +.I fs_spec +field matches the +.I special_file +argument. +.P +The function +.BR getfsfile () +searches the file from the start and returns the first entry found +for which the +.I fs_file +field matches the +.I mount_point +argument. +.SH RETURN VALUE +Upon success, the functions +.BR getfsent (), +.BR getfsfile (), +and +.BR getfsspec () +return a pointer to a +.IR "struct fstab" , +while +.BR setfsent () +returns 1. +Upon failure or end-of-file, these functions return NULL and 0, respectively. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR endfsent (), +.BR setfsent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:fsent +T} +T{ +.na +.nh +.BR getfsent (), +.BR getfsspec (), +.BR getfsfile () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:fsent locale +T} +.TE +.SH VERSIONS +Several operating systems have these functions, for example, +*BSD, SunOS, Digital UNIX, AIX (which also has a +.BR getfstype ()). +HP-UX has functions of the same names, +that however use a +.I struct checklist +instead of a +.IR "struct fstab" , +and calls these functions obsolete, superseded by +.BR getmntent (3). +.SH STANDARDS +None. +.SH HISTORY +The +.BR getfsent () +function appeared in 4.0BSD; the other four functions appeared in 4.3BSD. +.SH NOTES +These functions are not thread-safe. +.P +Since Linux allows mounting a block special device in several places, +and since several devices can have the same mount point, where the +last device with a given mount point is the interesting one, +while +.BR getfsfile () +and +.BR getfsspec () +only return the first occurrence, these two functions are not suitable +for use under Linux. +.SH SEE ALSO +.BR getmntent (3), +.BR fstab (5) diff --git a/man/man3/getfsfile.3 b/man/man3/getfsfile.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man/man3/getfsfile.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man/man3/getfsspec.3 b/man/man3/getfsspec.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man/man3/getfsspec.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man/man3/getgrent.3 b/man/man3/getgrent.3 new file mode 100644 index 0000000..a9c937b --- /dev/null +++ b/man/man3/getgrent.3 @@ -0,0 +1,206 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:29:54 1993 by Rik Faith (faith@cs.unc.edu) +.TH getgrent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getgrent, setgrent, endgrent \- get group file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.B struct group *getgrent(void); +.P +.B void setgrent(void); +.B void endgrent(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setgrent (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR getgrent (), +.BR endgrent (): +.nf + Since glibc 2.22: + _XOPEN_SOURCE >= 500 || _DEFAULT_SOURCE +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + glibc 2.21 and earlier + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getgrent () +function returns a pointer to a structure containing +the broken-out fields of a record in the group database +(e.g., the local group file +.IR /etc/group , +NIS, and LDAP). +The first time +.BR getgrent () +is called, +it returns the first entry; thereafter, it returns successive entries. +.P +The +.BR setgrent () +function rewinds to the beginning +of the group database, to allow repeated scans. +.P +The +.BR endgrent () +function is used to close the group database +after all processing has been performed. +.P +The \fIgroup\fP structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL\-terminated array of pointers + to names of group members */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR group (5). +.SH RETURN VALUE +The +.BR getgrent () +function returns a pointer to a +.I group +structure, +or NULL if there are no more entries or an error occurs. +.P +Upon error, +.I errno +may be set. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.P +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getgrent (), +.BR getgrgid (3), +or +.BR getgrnam (3). +(Do not pass the returned pointer to +.BR free (3).) +.SH ERRORS +.TP +.B EAGAIN +The service was temporarily unavailable; try again later. +For NSS backends in glibc +this indicates a temporary error talking to the backend. +The error may correct itself, retrying later is suggested. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.\" not in POSIX +.B ENOENT +A necessary input file cannot be found. +For NSS backends in glibc +this indicates the backend is not correctly configured. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I group +structure. +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/group +local group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getgrent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grent +race:grentbuf locale +T} +T{ +.na +.nh +.BR setgrent (), +.BR endgrent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grent locale +T} +.TE +.P +In the above table, +.I grent +in +.I race:grent +signifies that if any of the functions +.BR setgrent (), +.BR getgrent (), +or +.BR endgrent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent_r (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR getgrouplist (3), +.BR putgrent (3), +.BR group (5) diff --git a/man/man3/getgrent_r.3 b/man/man3/getgrent_r.3 new file mode 100644 index 0000000..23da51f --- /dev/null +++ b/man/man3/getgrent_r.3 @@ -0,0 +1,228 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH getgrent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getgrent_r, fgetgrent_r \- get group file entry reentrantly +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getgrent_r(struct group *restrict " gbuf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " gbufp ); +.BI "int fgetgrent_r(FILE *restrict " stream ", struct group *restrict " gbuf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " gbufp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getgrent_r (): +.nf + _GNU_SOURCE +.fi +.\" FIXME . The FTM requirements seem inconsistent here. File a glibc bug? +.P +.BR fgetgrent_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR getgrent_r () +and +.BR fgetgrent_r () +are the reentrant versions of +.BR getgrent (3) +and +.BR fgetgrent (3). +The former reads the next group entry from the stream initialized by +.BR setgrent (3). +The latter reads the next group entry from +.IR stream . +.P +The \fIgroup\fP structure is defined in +.I +as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL\-terminated array of pointers + to names of group members */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR group (5). +.P +The nonreentrant functions return a pointer to static storage, +where this static storage contains further pointers to group +name, password, and members. +The reentrant functions described here return all of that in +caller-provided buffers. +First of all there is the buffer +.I gbuf +that can hold a \fIstruct group\fP. +And next the buffer +.I buf +of size +.I buflen +that can hold additional strings. +The result of these functions, the \fIstruct group\fP read from the stream, +is stored in the provided buffer +.IR *gbuf , +and a pointer to this \fIstruct group\fP is returned in +.IR *gbufp . +.SH RETURN VALUE +On success, these functions return 0 and +.I *gbufp +is a pointer to the \fIstruct group\fP. +On error, these functions return an error value and +.I *gbufp +is NULL. +.SH ERRORS +.TP +.B ENOENT +No more entries. +.TP +.B ERANGE +Insufficient buffer space supplied. +Try again with larger buffer. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getgrent_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grent locale +T} +T{ +.na +.nh +.BR fgetgrent_r () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +.TE +.P +In the above table, +.I grent +in +.I race:grent +signifies that if any of the functions +.BR setgrent (3), +.BR getgrent (3), +.BR endgrent (3), +or +.BR getgrent_r () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +Other systems use the prototype +.P +.in +4n +.EX +struct group *getgrent_r(struct group *grp, char *buf, + int buflen); +.EE +.in +.P +or, better, +.P +.in +4n +.EX +int getgrent_r(struct group *grp, char *buf, int buflen, + FILE **gr_fp); +.EE +.in +.SH STANDARDS +GNU. +.SH HISTORY +These functions are done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +.SH NOTES +The function +.BR getgrent_r () +is not really reentrant since it shares the reading position +in the stream with all other threads. +.SH EXAMPLES +.\" SRC BEGIN (getgrent_r.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#define BUFLEN 4096 +\& +int +main(void) +{ + struct group grp; + struct group *grpp; + char buf[BUFLEN]; + int i; +\& + setgrent(); + while (1) { + i = getgrent_r(&grp, buf, sizeof(buf), &grpp); + if (i) + break; + printf("%s (%jd):", grpp\->gr_name, (intmax_t) grpp\->gr_gid); + for (size_t j = 0; ; j++) { + if (grpp\->gr_mem[j] == NULL) + break; + printf(" %s", grpp\->gr_mem[j]); + } + printf("\en"); + } + endgrent(); + exit(EXIT_SUCCESS); +} +.EE +.\" perhaps add error checking - should use strerror_r +.\" #include +.\" #include +.\" if (i) { +.\" if (i == ENOENT) +.\" break; +.\" printf("getgrent_r: %s", strerror(i)); +.\" exit(EXIT_FAILURE); +.\" } +.\" SRC END +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR putgrent (3), +.BR group (5) diff --git a/man/man3/getgrgid.3 b/man/man3/getgrgid.3 new file mode 100644 index 0000000..f9a97b4 --- /dev/null +++ b/man/man3/getgrgid.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man/man3/getgrgid_r.3 b/man/man3/getgrgid_r.3 new file mode 100644 index 0000000..f9a97b4 --- /dev/null +++ b/man/man3/getgrgid_r.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man/man3/getgrnam.3 b/man/man3/getgrnam.3 new file mode 100644 index 0000000..d19d414 --- /dev/null +++ b/man/man3/getgrnam.3 @@ -0,0 +1,260 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-11-15 by aeb +.\" +.TH getgrnam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getgrnam, getgrnam_r, getgrgid, getgrgid_r \- get group file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "struct group *getgrnam(const char *" name ); +.BI "struct group *getgrgid(gid_t " gid ); +.P +.BI "int getgrnam_r(const char *restrict " name \ +", struct group *restrict " grp , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " result ); +.BI "int getgrgid_r(gid_t " gid ", struct group *restrict " grp , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " result ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getgrnam_r (), +.BR getgrgid_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getgrnam () +function returns a pointer to a structure containing +the broken-out fields of the record in the group database +(e.g., the local group file +.IR /etc/group , +NIS, and LDAP) +that matches the group name +.IR name . +.P +The +.BR getgrgid () +function returns a pointer to a structure containing +the broken-out fields of the record in the group database +that matches the group ID +.IR gid . +.P +The \fIgroup\fP structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL\-terminated array of pointers + to names of group members */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR group (5). +.P +The +.BR getgrnam_r () +and +.BR getgrgid_r () +functions obtain the same information as +.BR getgrnam () +and +.BR getgrgid (), +but store the retrieved +.I group +structure +in the space pointed to by +.IR grp . +The string fields pointed to by the members of the +.I group +structure are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.IR *result . +.P +The call +.P +.in +4n +.EX +sysconf(_SC_GETGR_R_SIZE_MAX) +.EE +.in +.P +returns either \-1, without changing +.IR errno , +or an initial suggested size for +.IR buf . +(If this size is too small, +the call fails with +.BR ERANGE , +in which case the caller can retry with a larger buffer.) +.SH RETURN VALUE +The +.BR getgrnam () +and +.BR getgrgid () +functions return a pointer to a +.I group +structure, or NULL if the matching entry +is not found or an error occurs. +If an error occurs, +.I errno +is set to indicate the error. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.P +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getgrent (3), +.BR getgrgid (), +or +.BR getgrnam (). +(Do not pass the returned pointer to +.BR free (3).) +.P +On success, +.BR getgrnam_r () +and +.BR getgrgid_r () +return zero, and set +.I *result +to +.IR grp . +If no matching group record was found, +these functions return 0 and store NULL in +.IR *result . +In case of error, an error number is returned, and NULL is stored in +.IR *result . +.SH ERRORS +.TP +.BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ..." +The given +.I name +or +.I gid +was not found. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I group +structure. +.\" to allocate the group structure, or to allocate buffers +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/group +local group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getgrnam () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grnam locale +T} +T{ +.na +.nh +.BR getgrgid () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grgid locale +T} +T{ +.na +.nh +.BR getgrnam_r (), +.BR getgrgid_r () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +The formulation given above under "RETURN VALUE" is from POSIX.1. +.\" POSIX.1-2001, POSIX.1-2008 +It does not call "not found" an error, hence does not specify what value +.I errno +might have in this situation. +But that makes it impossible to recognize +errors. +One might argue that according to POSIX +.I errno +should be left unchanged if an entry is not found. +Experiments on various +UNIX-like systems show that lots of different values occur in this +situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others. +.\" more precisely: +.\" AIX 5.1 - gives ESRCH +.\" OSF1 4.0g - gives EWOULDBLOCK +.\" libc, glibc up to glibc 2.6, Irix 6.5 - give ENOENT +.\" since glibc 2.7 - give 0 +.\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM +.\" SunOS 5.8 - gives EBADF +.\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR endgrent (3), +.BR fgetgrent (3), +.BR getgrent (3), +.BR getpwnam (3), +.BR setgrent (3), +.BR group (5) diff --git a/man/man3/getgrnam_r.3 b/man/man3/getgrnam_r.3 new file mode 100644 index 0000000..f9a97b4 --- /dev/null +++ b/man/man3/getgrnam_r.3 @@ -0,0 +1 @@ +.so man3/getgrnam.3 diff --git a/man/man3/getgrouplist.3 b/man/man3/getgrouplist.3 new file mode 100644 index 0000000..4a8f5fb --- /dev/null +++ b/man/man3/getgrouplist.3 @@ -0,0 +1,205 @@ +'\" t +.\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" A few pieces remain from an earlier version written in +.\" 2002 by Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getgrouplist 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getgrouplist \- get list of groups to which a user belongs +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getgrouplist(const char *" user ", gid_t " group , +.BI " gid_t *" groups ", int *" ngroups ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getgrouplist (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR getgrouplist () +function scans the group database (see +.BR group (5)) +to obtain the list of groups that +.I user +belongs to. +Up to +.I *ngroups +of these groups are returned in the array +.IR groups . +.P +If it was not among the groups defined for +.I user +in the group database, then +.I group +is included in the list of groups returned by +.BR getgrouplist (); +typically this argument is specified as the group ID from +the password record for +.IR user . +.P +The +.I ngroups +argument is a value-result argument: +on return it always contains the number of groups found for +.IR user , +including +.IR group ; +this value may be greater than the number of groups stored in +.IR groups . +.SH RETURN VALUE +If the number of groups of which +.I user +is a member is less than or equal to +.IR *ngroups , +then the value +.I *ngroups +is returned. +.P +If the user is a member of more than +.I *ngroups +groups, then +.BR getgrouplist () +returns \-1. +In this case, the value returned in +.I *ngroups +can be used to resize the buffer passed to a further call to +.BR getgrouplist (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getgrouplist () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +glibc 2.2.4. +.SH BUGS +Before glibc 2.3.3, +the implementation of this function contains a buffer-overrun bug: +it returns the complete list of groups for +.I user +in the array +.IR groups , +even when the number of groups exceeds +.IR *ngroups . +.SH EXAMPLES +The program below displays the group list for the user named in its +first command-line argument. +The second command-line argument specifies the +.I ngroups +value to be supplied to +.BR getgrouplist (). +The following shell session shows examples of the use of this program: +.P +.in +4n +.EX +.RB "$" " ./a.out cecilia 0" +getgrouplist() returned \-1; ngroups = 3 +.RB "$" " ./a.out cecilia 3" +ngroups = 3 +16 (dialout) +33 (video) +100 (users) +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (getgrouplist.c) +.EX +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int ngroups; + gid_t *groups; + struct group *gr; + struct passwd *pw; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + ngroups = atoi(argv[2]); +\& + groups = malloc(sizeof(*groups) * ngroups); + if (groups == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + /* Fetch passwd structure (contains first group ID for user). */ +\& + errno = 0; + pw = getpwnam(argv[1]); + if (pw == NULL) { + if (errno) + perror("getpwnam"); + else + fprintf(stderr, "no such user\en"); + exit(EXIT_FAILURE); + } +\& + /* Retrieve group list. */ +\& + if (getgrouplist(argv[1], pw\->pw_gid, groups, &ngroups) == \-1) { + fprintf(stderr, "getgrouplist() returned \-1; ngroups = %d\en", + ngroups); + exit(EXIT_FAILURE); + } +\& + /* Display list of retrieved groups, along with group names. */ +\& + fprintf(stderr, "ngroups = %d\en", ngroups); + for (int j = 0; j < ngroups; j++) { + printf("%d", groups[j]); + gr = getgrgid(groups[j]); + if (gr != NULL) + printf(" (%s)", gr\->gr_name); + printf("\en"); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getgroups (2), +.BR setgroups (2), +.BR getgrent (3), +.BR group_member (3), +.BR group (5), +.BR passwd (5) diff --git a/man/man3/gethostbyaddr.3 b/man/man3/gethostbyaddr.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostbyaddr.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostbyaddr_r.3 b/man/man3/gethostbyaddr_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostbyaddr_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostbyname.3 b/man/man3/gethostbyname.3 new file mode 100644 index 0000000..88ca5ac --- /dev/null +++ b/man/man3/gethostbyname.3 @@ -0,0 +1,553 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-05-22, David Metcalfe +.\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) +.\" Modified 1997-02-16, Andries Brouwer (aeb@cwi.nl) +.\" Modified 1998-12-21, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2000-08-12, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2001-05-19, Andries Brouwer (aeb@cwi.nl) +.\" Modified 2002-08-05, Michael Kerrisk +.\" Modified 2004-10-31, Andries Brouwer +.\" +.TH gethostbyname 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, +h_errno, +herror, hstrerror, +gethostbyaddr_r, +gethostbyname2, gethostbyname2_r, gethostbyname_r, +gethostent_r \- get network host entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void sethostent(int " stayopen ); +.B void endhostent(void); +.P +.B [[deprecated]] extern int h_errno; +.P +.BI "[[deprecated]] struct hostent *gethostbyname(const char *" name ); +.BI "[[deprecated]] struct hostent *gethostbyaddr(const void " addr [. len ], +.BI " socklen_t " len ", int " type ); +.P +.BI "[[deprecated]] void herror(const char *" s ); +.BI "[[deprecated]] const char *hstrerror(int " err ); +.P +/* System V/POSIX extension */ +.B struct hostent *gethostent(void); +.P +/* GNU extensions */ +.B [[deprecated]] +.BI "struct hostent *gethostbyname2(const char *" name ", int " af ); +.P +.BI "int gethostent_r(struct hostent *restrict " ret , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct hostent **restrict " result , +.BI " int *restrict " h_errnop ); +.P +.B [[deprecated]] +.BI "int gethostbyaddr_r(const void " addr "[restrict ." len "], socklen_t " len , +.BI " int " type , +.BI " struct hostent *restrict " ret , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct hostent **restrict " result , +.BI " int *restrict " h_errnop ); +.B [[deprecated]] +.BI "int gethostbyname_r(const char *restrict " name , +.BI " struct hostent *restrict " ret , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct hostent **restrict " result , +.BI " int *restrict " h_errnop ); +.B [[deprecated]] +.BI "int gethostbyname2_r(const char *restrict " name ", int " af, +.BI " struct hostent *restrict " ret , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct hostent **restrict " result , +.BI " int *restrict " h_errnop ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gethostbyname2 (), +.BR gethostent_r (), +.BR gethostbyaddr_r (), +.BR gethostbyname_r (), +.BR gethostbyname2_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc up to and including 2.19: + _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR herror (), +.BR hstrerror (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.8 to glibc 2.19: + _BSD_SOURCE || _SVID_SOURCE + Before glibc 2.8: + none +.fi +.P +.BR h_errno : +.nf + Since glibc 2.19 + _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L + glibc 2.12 to glibc 2.19: + _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L + Before glibc 2.12: + none +.fi +.SH DESCRIPTION +The +.BR gethostbyname* (), +.BR gethostbyaddr* (), +.BR herror (), +and +.BR hstrerror () +functions are obsolete. +Applications should use +.BR getaddrinfo (3), +.BR getnameinfo (3), +and +.BR gai_strerror (3) +instead. +.P +The +.BR sethostent () +function specifies, if \fIstayopen\fP is true (1), +that a connected TCP socket should be used for the name server queries and +that the connection should remain open during successive queries. +Otherwise, name server queries will use UDP datagrams. +.P +The +.BR endhostent () +function ends the use of a TCP connection for name +server queries. +.P +The +.BR gethostbyname () +function returns a structure of type +.I hostent +for the given host +.IR name . +Here +.I name +is either a hostname or an IPv4 address in standard dot notation (as for +.BR inet_addr (3)). +If +.I name +is an IPv4 address, no lookup is performed and +.BR gethostbyname () +simply copies +.I name +into the +.I h_name +field and its +.I struct in_addr +equivalent into the +.I h_addr_list[0] +field of the returned +.I hostent +structure. +If +.I name +doesn't end in a dot and the environment variable +.B HOSTALIASES +is set, the alias file pointed to by +.B HOSTALIASES +will first be searched for +.I name +(see +.BR hostname (7) +for the file format). +The current domain and its parents are searched unless \fIname\fP +ends in a dot. +.P +The +.BR gethostbyaddr () +function returns a structure of type \fIhostent\fP +for the given host address \fIaddr\fP of length \fIlen\fP and address type +\fItype\fP. +Valid address types are +.B AF_INET +and +.B AF_INET6 +(defined in +.IR ). +The host address argument is a pointer to a struct of a type depending +on the address type, for example a \fIstruct in_addr *\fP (probably +obtained via a call to +.BR inet_addr (3)) +for address type +.BR AF_INET . +.P +The (obsolete) +.BR herror () +function prints the error message associated +with the current value of \fIh_errno\fP on \fIstderr\fP. +.P +The (obsolete) +.BR hstrerror () +function takes an error number +(typically \fIh_errno\fP) and returns the corresponding message string. +.P +The domain name queries carried out by +.BR gethostbyname () +and +.BR gethostbyaddr () +rely on the Name Service Switch +.RB ( nsswitch.conf (5)) +configured sources or a local name server +.RB ( named (8)). +The default action is to query the Name Service Switch +.RB ( nsswitch.conf (5)) +configured sources, failing that, a local name server +.RB ( named (8)). +.\" +.SS Historical +The +.BR nsswitch.conf (5) +file is the modern way of controlling the order of host lookups. +.P +In glibc 2.4 and earlier, the +.I order +keyword was used to control the order of host lookups as defined in +.I /etc/host.conf +.RB ( host.conf (5)). +.P +The \fIhostent\fP structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses */ +} +#define h_addr h_addr_list[0] /* for backward compatibility */ +.EE +.in +.P +The members of the \fIhostent\fP structure are: +.TP +.I h_name +The official name of the host. +.TP +.I h_aliases +An array of alternative names for the host, terminated by a null pointer. +.TP +.I h_addrtype +The type of address; always +.B AF_INET +or +.B AF_INET6 +at present. +.TP +.I h_length +The length of the address in bytes. +.TP +.I h_addr_list +An array of pointers to network addresses for the host (in network byte +order), terminated by a null pointer. +.TP +.I h_addr +The first address in \fIh_addr_list\fP for backward compatibility. +.SH RETURN VALUE +The +.BR gethostbyname () +and +.BR gethostbyaddr () +functions return the +.I hostent +structure or a null pointer if an error occurs. +On error, the +.I h_errno +variable holds an error number. +When non-NULL, the return value may point at static data, see the notes below. +.SH ERRORS +The variable \fIh_errno\fP can have the following values: +.TP +.B HOST_NOT_FOUND +The specified host is unknown. +.TP +.B NO_DATA +The requested name is valid but does not have an IP address. +Another type of request to the name server for this domain +may return an answer. +The constant +.B NO_ADDRESS +is a synonym for +.BR NO_DATA . +.TP +.B NO_RECOVERY +A nonrecoverable name server error occurred. +.TP +.B TRY_AGAIN +A temporary error occurred on an authoritative name server. +Try again later. +.SH FILES +.TP +.I /etc/host.conf +resolver configuration file +.TP +.I /etc/hosts +host database file +.TP +.I /etc/nsswitch.conf +name service switch configuration +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gethostbyname () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:hostbyname env +locale +T} +T{ +.na +.nh +.BR gethostbyaddr () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:hostbyaddr env +locale +T} +T{ +.na +.nh +.BR sethostent (), +.BR endhostent (), +.BR gethostent_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:hostent env +locale +T} +T{ +.na +.nh +.BR herror (), +.BR hstrerror () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR gethostent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:hostent +race:hostentbuf env locale +T} +T{ +.na +.nh +.BR gethostbyname2 () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:hostbyname2 +env locale +T} +T{ +.na +.nh +.BR gethostbyaddr_r (), +.BR gethostbyname_r (), +.BR gethostbyname2_r () +T} Thread safety MT-Safe env locale +.TE +.P +In the above table, +.I hostent +in +.I race:hostent +signifies that if any of the functions +.BR sethostent (), +.BR gethostent (), +.BR gethostent_r (), +or +.BR \%endhostent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +.TP +.BR sethostent () +.TQ +.BR endhostent () +.TQ +.BR gethostent () +POSIX.1-2008. +.TP +.BR gethostent_r () +GNU. +.TP +Others: +None. +.SH HISTORY +.TP +.BR sethostent () +.TQ +.BR endhostent () +.TQ +.BR gethostent () +POSIX.1-2001. +.TP +.BR gethostbyname () +.TQ +.BR gethostbyaddr () +.TQ +.I h_errno +Marked obsolescent in POSIX.1-2001. +Removed in POSIX.1-2008, +recommending the use of +.BR getaddrinfo (3) +and +.BR getnameinfo (3) +instead. +.SH NOTES +The functions +.BR gethostbyname () +and +.BR gethostbyaddr () +may return pointers to static data, which may be overwritten by +later calls. +Copying the +.I struct hostent +does not suffice, since it contains pointers; a deep copy is required. +.P +In the original BSD implementation the +.I len +argument +of +.BR gethostbyname () +was an +.IR int . +The SUSv2 standard is buggy and declares the +.I len +argument of +.BR gethostbyaddr () +to be of type +.IR size_t . +(That is wrong, because it has to be +.IR int , +and +.I size_t +is not. +POSIX.1-2001 makes it +.IR socklen_t , +which is OK.) +See also +.BR accept (2). +.P +The BSD prototype for +.BR gethostbyaddr () +uses +.I "const char\ *" +for the first argument. +.SS System V/POSIX extension +POSIX requires the +.BR gethostent () +call, which should return the next entry in the host data base. +When using DNS/BIND this does not make much sense, but it may +be reasonable if the host data base is a file that can be read +line by line. +On many systems, a routine of this name reads +from the file +.IR /etc/hosts . +.\" e.g., Linux, FreeBSD, UnixWare, HP-UX +It may be available only when the library was built without DNS support. +.\" e.g., FreeBSD, AIX +The glibc version will ignore ipv6 entries. +This function is not reentrant, +and glibc adds a reentrant version +.BR gethostent_r (). +.SS GNU extensions +glibc2 also has a +.BR gethostbyname2 () +that works like +.BR gethostbyname (), +but permits to specify the address family to which the address must belong. +.P +glibc2 also has reentrant versions +.BR gethostent_r (), +.BR gethostbyaddr_r (), +.BR gethostbyname_r (), +and +.BR gethostbyname2_r (). +The caller supplies a +.I hostent +structure +.I ret +which will be filled in on success, and a temporary work buffer +.I buf +of size +.IR buflen . +After the call, +.I result +will point to the result on success. +In case of an error +or if no entry is found +.I result +will be NULL. +The functions return 0 on success and a nonzero error number on failure. +In addition to the errors returned by the nonreentrant +versions of these functions, if +.I buf +is too small, the functions will return +.BR ERANGE , +and the call should be retried with a larger buffer. +The global variable +.I h_errno +is not modified, but the address of a variable in which to store error numbers +is passed in +.IR h_errnop . +.SH BUGS +.BR gethostbyname () +does not recognize components of a dotted IPv4 address string +that are expressed in hexadecimal. +.\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973 +.SH SEE ALSO +.BR getaddrinfo (3), +.\" .BR getipnodebyaddr (3), +.\" .BR getipnodebyname (3), +.BR getnameinfo (3), +.BR inet (3), +.BR inet_ntop (3), +.BR inet_pton (3), +.BR resolver (3), +.BR hosts (5), +.BR nsswitch.conf (5), +.BR hostname (7), +.BR named (8) +.\" .BR resolv+ (8) diff --git a/man/man3/gethostbyname2.3 b/man/man3/gethostbyname2.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostbyname2.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostbyname2_r.3 b/man/man3/gethostbyname2_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostbyname2_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostbyname_r.3 b/man/man3/gethostbyname_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostbyname_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostent.3 b/man/man3/gethostent.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostent_r.3 b/man/man3/gethostent_r.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/gethostent_r.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/gethostid.3 b/man/man3/gethostid.3 new file mode 100644 index 0000000..f4ee425 --- /dev/null +++ b/man/man3/gethostid.3 @@ -0,0 +1,149 @@ +'\" t +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" Updated with additions from Mitchum DSouza +.\" Portions Copyright 1993 Mitchum DSouza +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond +.TH gethostid 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gethostid, sethostid \- get or set the unique identifier of the current host +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B long gethostid(void); +.BI "int sethostid(long " hostid ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gethostid (): +.nf + Since glibc 2.20: + _DEFAULT_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + Up to and including glibc 2.19: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.P +.BR sethostid (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +.BR gethostid () +and +.BR sethostid () +respectively get or set a unique 32-bit identifier for the current machine. +The 32-bit identifier was intended to be unique among all UNIX systems in +existence. +This normally resembles the Internet address for the local +machine, as returned by +.BR gethostbyname (3), +and thus usually never needs to be set. +.P +The +.BR sethostid () +call is restricted to the superuser. +.SH RETURN VALUE +.BR gethostid () +returns the 32-bit identifier for the current host as set by +.BR sethostid (). +.P +On success, +.BR sethostid () +returns 0; on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR sethostid () +can fail with the following errors: +.TP +.B EACCES +The caller did not have permission to write to the file used +to store the host ID. +.TP +.B EPERM +The calling process's effective user or group ID is not the same +as its corresponding real ID. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gethostid () +T} Thread safety T{ +.na +.nh +MT-Safe hostid env locale +T} +T{ +.na +.nh +.BR sethostid () +T} Thread safety T{ +.na +.nh +MT-Unsafe const:hostid +T} +.TE +.SH VERSIONS +In the glibc implementation, the +.I hostid +is stored in the file +.IR /etc/hostid . +(Before glibc 2.2, the file +.I /var/adm/hostid +was used.) +.\" libc5 used /etc/hostid; libc4 didn't have these functions +.P +In the glibc implementation, if +.BR gethostid () +cannot open the file containing the host ID, +then it obtains the hostname using +.BR gethostname (2), +passes that hostname to +.BR gethostbyname_r (3) +in order to obtain the host's IPv4 address, +and returns a value obtained by bit-twiddling the IPv4 address. +(This value may not be unique.) +.SH STANDARDS +.TP +.BR gethostid () +POSIX.1-2008. +.TP +.BR sethostid () +None. +.SH HISTORY +4.2BSD; dropped in 4.4BSD. +SVr4 and POSIX.1-2001 include +.BR gethostid () +but not +.BR sethostid (). +.SH BUGS +It is impossible to ensure that the identifier is globally unique. +.SH SEE ALSO +.BR hostid (1), +.BR gethostbyname (3) diff --git a/man/man3/getifaddrs.3 b/man/man3/getifaddrs.3 new file mode 100644 index 0000000..825e38c --- /dev/null +++ b/man/man3/getifaddrs.3 @@ -0,0 +1,313 @@ +'\" t +.\" Copyright (c) 2008 Petr Baudis +.\" and copyright (c) 2009, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 2008-12-08 Petr Baudis +.\" Rewrite the BSD manpage in the Linux man pages style and account +.\" for glibc specificities, provide an example. +.\" 2009-01-14 mtk, many edits and changes, rewrote example program. +.\" +.TH getifaddrs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getifaddrs, freeifaddrs \- get interface addresses +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int getifaddrs(struct ifaddrs **" "ifap" ); +.BI "void freeifaddrs(struct ifaddrs *" "ifa" ); +.fi +.SH DESCRIPTION +The +.BR getifaddrs () +function creates a linked list of structures describing +the network interfaces of the local system, +and stores the address of the first item of the list in +.IR *ifap . +The list consists of +.I ifaddrs +structures, defined as follows: +.P +.in +4n +.EX +struct ifaddrs { + struct ifaddrs *ifa_next; /* Next item in list */ + char *ifa_name; /* Name of interface */ + unsigned int ifa_flags; /* Flags from SIOCGIFFLAGS */ + struct sockaddr *ifa_addr; /* Address of interface */ + struct sockaddr *ifa_netmask; /* Netmask of interface */ + union { + struct sockaddr *ifu_broadaddr; + /* Broadcast address of interface */ + struct sockaddr *ifu_dstaddr; + /* Point\-to\-point destination address */ + } ifa_ifu; +#define ifa_broadaddr ifa_ifu.ifu_broadaddr +#define ifa_dstaddr ifa_ifu.ifu_dstaddr + void *ifa_data; /* Address\-specific data */ +}; +.EE +.in +.P +The +.I ifa_next +field contains a pointer to the next structure on the list, +or NULL if this is the last item of the list. +.P +The +.I ifa_name +points to the null-terminated interface name. +.\" The constant +.\" .B IF NAMESIZE +.\" indicates the maximum length of this field. +.P +The +.I ifa_flags +field contains the interface flags, as returned by the +.B SIOCGIFFLAGS +.BR ioctl (2) +operation (see +.BR netdevice (7) +for a list of these flags). +.P +The +.I ifa_addr +field points to a structure containing the interface address. +(The +.I sa_family +subfield should be consulted to determine the format of the +address structure.) +This field may contain a null pointer. +.P +The +.I ifa_netmask +field points to a structure containing the netmask associated with +.IR ifa_addr , +if applicable for the address family. +This field may contain a null pointer. +.P +Depending on whether the bit +.B IFF_BROADCAST +or +.B IFF_POINTOPOINT +is set in +.I ifa_flags +(only one can be set at a time), +either +.I ifa_broadaddr +will contain the broadcast address associated with +.I ifa_addr +(if applicable for the address family) or +.I ifa_dstaddr +will contain the destination address of the point-to-point interface. +.P +The +.I ifa_data +field points to a buffer containing address-family-specific data; +this field may be NULL if there is no such data for this interface. +.P +The data returned by +.BR getifaddrs () +is dynamically allocated and should be freed using +.BR freeifaddrs () +when no longer needed. +.SH RETURN VALUE +On success, +.BR getifaddrs () +returns zero; +on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR getifaddrs () +may fail and set +.I errno +for any of the errors specified for +.BR socket (2), +.BR bind (2), +.BR getsockname (2), +.BR recvmsg (2), +.BR sendto (2), +.BR malloc (3), +or +.BR realloc (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getifaddrs (), +.BR freeifaddrs () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +This function first appeared in BSDi and is +present on the BSD systems, but with slightly different +semantics documented\[em]returning one entry per interface, +not per address. +This means +.I ifa_addr +and other fields can actually be NULL if the interface has no address, +and no link-level address is returned if the interface has an IP address +assigned. +Also, the way of choosing either +.I ifa_broadaddr +or +.I ifa_dstaddr +differs on various systems. +.\" , but the BSD-derived documentation generally +.\" appears to be confused and obsolete on this point. +.\" i.e., commonly it still says one of them will be NULL, even if +.\" the ifa_ifu union is already present +.P +.BR getifaddrs () +first appeared in glibc 2.3, but before glibc 2.3.3, +the implementation supported only IPv4 addresses; +IPv6 support was added in glibc 2.3.3. +Support of address families other than IPv4 is available only +on kernels that support netlink. +.SH NOTES +The addresses returned on Linux will usually be the IPv4 and IPv6 addresses +assigned to the interface, but also one +.B AF_PACKET +address per interface containing lower-level details about the interface +and its physical layer. +In this case, the +.I ifa_data +field may contain a pointer to a +.IR "struct rtnl_link_stats" , +defined in +.I +(in Linux 2.4 and earlier, +.IR "struct net_device_stats" , +defined in +.IR ), +which contains various interface attributes and statistics. +.SH EXAMPLES +The program below demonstrates the use of +.BR getifaddrs (), +.BR freeifaddrs (), +and +.BR getnameinfo (3). +Here is what we see when running this program on one system: +.P +.in +4n +.EX +$ \fB./a.out\fP +lo AF_PACKET (17) + tx_packets = 524; rx_packets = 524 + tx_bytes = 38788; rx_bytes = 38788 +wlp3s0 AF_PACKET (17) + tx_packets = 108391; rx_packets = 130245 + tx_bytes = 30420659; rx_bytes = 94230014 +em1 AF_PACKET (17) + tx_packets = 0; rx_packets = 0 + tx_bytes = 0; rx_bytes = 0 +lo AF_INET (2) + address: <127.0.0.1> +wlp3s0 AF_INET (2) + address: <192.168.235.137> +lo AF_INET6 (10) + address: <::1> +wlp3s0 AF_INET6 (10) + address: +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE /* To get defns of NI_MAXSERV and NI_MAXHOST */ +#include +#include +#include +#include +#include +#include +#include +#include +\& +int main(int argc, char *argv[]) +{ + struct ifaddrs *ifaddr; + int family, s; + char host[NI_MAXHOST]; +\& + if (getifaddrs(&ifaddr) == \-1) { + perror("getifaddrs"); + exit(EXIT_FAILURE); + } +\& + /* Walk through linked list, maintaining head pointer so we + can free list later. */ +\& + for (struct ifaddrs *ifa = ifaddr; ifa != NULL; + ifa = ifa\->ifa_next) { + if (ifa\->ifa_addr == NULL) + continue; +\& + family = ifa\->ifa_addr\->sa_family; +\& + /* Display interface name and family (including symbolic + form of the latter for the common families). */ +\& + printf("%\-8s %s (%d)\en", + ifa\->ifa_name, + (family == AF_PACKET) ? "AF_PACKET" : + (family == AF_INET) ? "AF_INET" : + (family == AF_INET6) ? "AF_INET6" : "???", + family); +\& + /* For an AF_INET* interface address, display the address. */ +\& + if (family == AF_INET || family == AF_INET6) { + s = getnameinfo(ifa\->ifa_addr, + (family == AF_INET) ? sizeof(struct sockaddr_in) : + sizeof(struct sockaddr_in6), + host, NI_MAXHOST, + NULL, 0, NI_NUMERICHOST); + if (s != 0) { + printf("getnameinfo() failed: %s\en", gai_strerror(s)); + exit(EXIT_FAILURE); + } +\& + printf("\et\etaddress: <%s>\en", host); +\& + } else if (family == AF_PACKET && ifa\->ifa_data != NULL) { + struct rtnl_link_stats *stats = ifa\->ifa_data; +\& + printf("\et\ettx_packets = %10u; rx_packets = %10u\en" + "\et\ettx_bytes = %10u; rx_bytes = %10u\en", + stats\->tx_packets, stats\->rx_packets, + stats\->tx_bytes, stats\->rx_bytes); + } + } +\& + freeifaddrs(ifaddr); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR bind (2), +.BR getsockname (2), +.BR socket (2), +.BR packet (7), +.BR ifconfig (8) diff --git a/man/man3/getipnodebyaddr.3 b/man/man3/getipnodebyaddr.3 new file mode 100644 index 0000000..82e01df --- /dev/null +++ b/man/man3/getipnodebyaddr.3 @@ -0,0 +1 @@ +.so man3/getipnodebyname.3 diff --git a/man/man3/getipnodebyname.3 b/man/man3/getipnodebyname.3 new file mode 100644 index 0000000..c52dfa1 --- /dev/null +++ b/man/man3/getipnodebyname.3 @@ -0,0 +1,253 @@ +.\" Copyright 2000 Sam Varshavchik +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References: RFC 2553 +.TH getipnodebyname 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getipnodebyname, getipnodebyaddr, freehostent \- get network +hostnames and addresses +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.BI "[[deprecated]] struct hostent *getipnodebyname(const char *" name ", int " af , +.BI " int " flags ", int *" error_num ); +.BI "[[deprecated]] struct hostent *getipnodebyaddr(const void " addr [. len ], +.BI " size_t " len ", int " af , +.BI " int *" "error_num" ); +.BI "[[deprecated]] void freehostent(struct hostent *" "ip" ); +.fi +.SH DESCRIPTION +These functions are deprecated (and unavailable in glibc). +Use +.BR getaddrinfo (3) +and +.BR getnameinfo (3) +instead. +.P +The +.BR getipnodebyname () +and +.BR getipnodebyaddr () +functions return the names and addresses of a network host. +These functions return a pointer to the +following structure: +.P +.in +4n +.EX +struct hostent { + char *h_name; + char **h_aliases; + int h_addrtype; + int h_length; + char **h_addr_list; +}; +.EE +.in +.P +These functions replace the +.BR gethostbyname (3) +and +.BR gethostbyaddr (3) +functions, which could access only the IPv4 network address family. +The +.BR getipnodebyname () +and +.BR getipnodebyaddr () +functions can access multiple network address families. +.P +Unlike the +.B gethostby +functions, +these functions return pointers to dynamically allocated memory. +The +.BR freehostent () +function is used to release the dynamically allocated memory +after the caller no longer needs the +.I hostent +structure. +.SS getipnodebyname() arguments +The +.BR getipnodebyname () +function +looks up network addresses for the host +specified by the +.I name +argument. +The +.I af +argument specifies one of the following values: +.TP +.B AF_INET +The +.I name +argument points to a dotted-quad IPv4 address or a name +of an IPv4 network host. +.TP +.B AF_INET6 +The +.I name +argument points to a hexadecimal IPv6 address or a name +of an IPv6 network host. +.P +The +.I flags +argument specifies additional options. +More than one option can be specified by bitwise OR-ing +them together. +.I flags +should be set to 0 +if no options are desired. +.TP +.B AI_V4MAPPED +This flag is used with +.B AF_INET6 +to request a query for IPv4 addresses instead of +IPv6 addresses; the IPv4 addresses will +be mapped to IPv6 addresses. +.TP +.B AI_ALL +This flag is used with +.B AI_V4MAPPED +to request a query for both IPv4 and IPv6 addresses. +Any IPv4 address found will be mapped to an IPv6 address. +.TP +.B AI_ADDRCONFIG +This flag is used with +.B AF_INET6 +to +further request that queries for IPv6 addresses should not be made unless +the system has at least one IPv6 address assigned to a network interface, +and that queries for IPv4 addresses should not be made unless the +system has at least one IPv4 address assigned to a network interface. +This flag may be used by itself or with the +.B AI_V4MAPPED +flag. +.TP +.B AI_DEFAULT +This flag is equivalent to +.BR "(AI_ADDRCONFIG | AI_V4MAPPED)" . +.SS getipnodebyaddr() arguments +The +.BR getipnodebyaddr () +function +looks up the name of the host whose +network address is +specified by the +.I addr +argument. +The +.I af +argument specifies one of the following values: +.TP +.B AF_INET +The +.I addr +argument points to a +.I struct in_addr +and +.I len +must be set to +.IR "sizeof(struct in_addr)" . +.TP +.B AF_INET6 +The +.I addr +argument points to a +.I struct in6_addr +and +.I len +must be set to +.IR "sizeof(struct in6_addr)" . +.SH RETURN VALUE +NULL is returned if an error occurred, and +.I error_num +will contain an error code from the following list: +.TP +.B HOST_NOT_FOUND +The hostname or network address was not found. +.TP +.B NO_ADDRESS +The domain name server recognized the network address or name, +but no answer was returned. +This can happen if the network host has only IPv4 addresses and +a request has been made for IPv6 information only, or vice versa. +.TP +.B NO_RECOVERY +The domain name server returned a permanent failure response. +.TP +.B TRY_AGAIN +The domain name server returned a temporary failure response. +You might have better luck next time. +.P +A successful query returns a pointer to a +.I hostent +structure that contains the following fields: +.TP +.I h_name +This is the official name of this network host. +.TP +.I h_aliases +This is an array of pointers to unofficial aliases for the same host. +The array is terminated by a null pointer. +.TP +.I h_addrtype +This is a copy of the +.I af +argument to +.BR getipnodebyname () +or +.BR getipnodebyaddr (). +.I h_addrtype +will always be +.B AF_INET +if the +.I af +argument was +.BR AF_INET . +.I h_addrtype +will always be +.B AF_INET6 +if the +.I af +argument was +.BR AF_INET6 . +.TP +.I h_length +This field will be set to +.I sizeof(struct in_addr) +if +.I h_addrtype +is +.BR AF_INET , +and to +.I sizeof(struct in6_addr) +if +.I h_addrtype +is +.BR AF_INET6 . +.TP +.I h_addr_list +This is an array of one or more pointers to network address structures for the +network host. +The array is terminated by a null pointer. +.SH STANDARDS +None. +.SH HISTORY +.\" Not in POSIX.1-2001. +RFC\ 2553. +.P +Present in glibc 2.1.91-95, but removed again. +Several UNIX-like systems support them, but all +call them deprecated. +.SH SEE ALSO +.BR getaddrinfo (3), +.BR getnameinfo (3), +.BR inet_ntop (3), +.BR inet_pton (3) diff --git a/man/man3/getline.3 b/man/man3/getline.3 new file mode 100644 index 0000000..fc960f0 --- /dev/null +++ b/man/man3/getline.3 @@ -0,0 +1,182 @@ +'\" t +.\" Copyright (c) 2001 John Levon +.\" Based in part on GNU libc documentation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getline 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getline, getdelim \- delimited string input +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t getline(char **restrict " lineptr ", size_t *restrict " n , +.BI " FILE *restrict " stream ); +.BI "ssize_t getdelim(char **restrict " lineptr ", size_t *restrict " n , +.BI " int " delim ", FILE *restrict " stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getline (), +.BR getdelim (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +.BR getline () +reads an entire line from \fIstream\fP, +storing the address of the buffer containing the text into +.IR *lineptr . +The buffer is null-terminated and includes the newline character, if +one was found. +.P +If +.I *lineptr +is set to NULL before the call, then +.BR getline () +will allocate a buffer for storing the line. +This buffer should be freed by the user program +even if +.BR getline () +failed. +.P +Alternatively, before calling +.BR getline (), +.I *lineptr +can contain a pointer to a +.BR malloc (3)\-allocated +buffer +.I *n +bytes in size. +If the buffer is not large enough to hold the line, +.BR getline () +resizes it with +.BR realloc (3), +updating +.I *lineptr +and +.I *n +as necessary. +.P +In either case, on a successful call, +.I *lineptr +and +.I *n +will be updated to reflect the buffer address and allocated size respectively. +.P +.BR getdelim () +works like +.BR getline (), +except that a line delimiter other than newline can be specified as the +.I delimiter +argument. +As with +.BR getline (), +a delimiter character is not added if one was not present +in the input before end of file was reached. +.SH RETURN VALUE +On success, +.BR getline () +and +.BR getdelim () +return the number of characters read, including the delimiter character, +but not including the terminating null byte (\[aq]\e0\[aq]). +This value can be used +to handle embedded null bytes in the line read. +.P +Both functions return \-1 on failure to read a line (including end-of-file +condition). +In the event of a failure, +.I errno +is set to indicate the error. +.P +If +.I *lineptr +was set to NULL before the call, then the buffer should be freed by the +user program even on failure. +.SH ERRORS +.TP +.B EINVAL +Bad arguments +.RI ( n +or +.I lineptr +is NULL, or +.I stream +is not valid). +.TP +.B ENOMEM +Allocation or reallocation of the line buffer failed. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getline (), +.BR getdelim () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +GNU, POSIX.1-2008. +.SH EXAMPLES +.\" SRC BEGIN (getline.c) +.EX +#define _GNU_SOURCE +#include +#include +\& +int +main(int argc, char *argv[]) +{ + FILE *stream; + char *line = NULL; + size_t len = 0; + ssize_t nread; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + stream = fopen(argv[1], "r"); + if (stream == NULL) { + perror("fopen"); + exit(EXIT_FAILURE); + } +\& + while ((nread = getline(&line, &len, stream)) != \-1) { + printf("Retrieved line of length %zd:\en", nread); + fwrite(line, nread, 1, stdout); + } +\& + free(line); + fclose(stream); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR read (2), +.BR fgets (3), +.BR fopen (3), +.BR fread (3), +.BR scanf (3) diff --git a/man/man3/getloadavg.3 b/man/man3/getloadavg.3 new file mode 100644 index 0000000..7f45786 --- /dev/null +++ b/man/man3/getloadavg.3 @@ -0,0 +1,71 @@ +'\" t +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" @(#)getloadavg.3 8.1 (Berkeley) 6/4/93 +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH getloadavg 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getloadavg \- get system load averages +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getloadavg(double " loadavg[] ", int " nelem ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getloadavg (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR getloadavg () +function returns the number of processes in the system run queue +averaged over various periods of time. +Up to +.I nelem +samples are retrieved and assigned to successive elements of +.IR loadavg[] . +The system imposes a maximum of 3 samples, representing averages +over the last 1, 5, and 15 minutes, respectively. +.SH RETURN VALUE +If the load average was unobtainable, \-1 is returned; otherwise, +the number of samples actually retrieved is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getloadavg () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +BSD. +.SH HISTORY +4.3BSD-Reno, Solaris. +glibc 2.2. +.SH SEE ALSO +.BR uptime (1), +.BR proc (5) diff --git a/man/man3/getlogin.3 b/man/man3/getlogin.3 new file mode 100644 index 0000000..6ac36f8 --- /dev/null +++ b/man/man3/getlogin.3 @@ -0,0 +1,259 @@ +'\" t +.\" Copyright 1995 James R. Van Zandt +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Changed Tue Sep 19 01:49:29 1995, aeb: moved from man2 to man3 +.\" added ref to /etc/utmp, added BUGS section, etc. +.\" modified 2003 Walter Harms, aeb - added getlogin_r, note on stdin use +.TH getlogin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getlogin, getlogin_r, cuserid \- get username +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B "char *getlogin(void);" +.BI "int getlogin_r(char " buf [. bufsize "], size_t " bufsize ); +.P +.B #include +.P +.BI "char *cuserid(char *" string ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getlogin_r (): +.nf +.\" Deprecated: _REENTRANT || + _POSIX_C_SOURCE >= 199506L +.fi +.P +.BR cuserid (): +.nf + Since glibc 2.24: + (_XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L) + || _GNU_SOURCE + Up to and including glibc 2.23: + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +.BR getlogin () +returns a pointer to a string containing the name of +the user logged in on the controlling terminal of the process, or a +null pointer if this information cannot be determined. +The string is +statically allocated and might be overwritten on subsequent calls to +this function or to +.BR cuserid (). +.P +.BR getlogin_r () +returns this same username in the array +.I buf +of size +.IR bufsize . +.P +.BR cuserid () +returns a pointer to a string containing a username +associated with the effective user ID of the process. +If \fIstring\fP +is not a null pointer, it should be an array that can hold at least +\fBL_cuserid\fP characters; the string is returned in this array. +Otherwise, a pointer to a string in a static area is returned. +This +string is statically allocated and might be overwritten on subsequent +calls to this function or to +.BR getlogin (). +.P +The macro \fBL_cuserid\fP is an integer constant that indicates how +long an array you might need to store a username. +\fBL_cuserid\fP is declared in \fI\fP. +.P +These functions let your program identify positively the user who is +running +.RB ( cuserid ()) +or the user who logged in this session +.RB ( getlogin ()). +(These can differ when set-user-ID programs are involved.) +.P +For most purposes, it is more useful to use the environment variable +\fBLOGNAME\fP to find out who the user is. +This is more flexible +precisely because the user can set \fBLOGNAME\fP arbitrarily. +.SH RETURN VALUE +.BR getlogin () +returns a pointer to the username when successful, +and NULL on failure, with +.I errno +set to indicate the error. +.BR getlogin_r () +returns 0 when successful, and nonzero on failure. +.SH ERRORS +POSIX specifies: +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENXIO +The calling process has no controlling terminal. +.TP +.B ERANGE +(getlogin_r) +The length of the username, including the terminating null byte (\[aq]\e0\[aq]), +is larger than +.IR bufsize . +.P +Linux/glibc also has: +.TP +.B ENOENT +There was no corresponding entry in the utmp-file. +.TP +.B ENOMEM +Insufficient memory to allocate passwd structure. +.TP +.B ENOTTY +Standard input didn't refer to a terminal. +(See BUGS.) +.SH FILES +.TP +\fI/etc/passwd\fP +password database file +.TP +\fI/var/run/utmp\fP +(traditionally \fI/etc/utmp\fP; +some libc versions used \fI/var/adm/utmp\fP) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getlogin () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getlogin race:utent +sig:ALRM timer locale +T} +T{ +.na +.nh +.BR getlogin_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent sig:ALRM timer +locale +T} +T{ +.na +.nh +.BR cuserid () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:cuserid/!string locale +T} +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR getlogin () +and +.BR getlogin_r () +call those functions, +so we use race:utent to remind users. +.SH VERSIONS +OpenBSD has +.BR getlogin () +and +.BR setlogin (), +and a username +associated with a session, even if it has no controlling terminal. +.SH STANDARDS +.TP +.BR getlogin () +.TQ +.BR getlogin_r () +POSIX.1-2008. +.TP +.BR cuserid () +None. +.SH STANDARDS +.TP +.BR getlogin () +.TQ +.BR getlogin_r (): +POSIX.1-2001. +OpenBSD. +.TP +.BR cuserid () +System V, POSIX.1-1988. +Removed in POSIX.1-1990. +SUSv2. +Removed in POSIX.1-2001. +.IP +System V has a +.BR cuserid () +function which uses the real +user ID rather than the effective user ID. +.SH BUGS +Unfortunately, it is often rather easy to fool +.BR getlogin (). +Sometimes it does not work at all, because some program messed up +the utmp file. +Often, it gives only the first 8 characters of +the login name. +The user currently logged in on the controlling terminal +of our program need not be the user who started it. +Avoid +.BR getlogin () +for security-related purposes. +.P +Note that glibc does not follow the POSIX specification and uses +.I stdin +instead of +.IR /dev/tty . +A bug. +(Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8 +all return the login name also when +.I stdin +is redirected.) +.P +Nobody knows precisely what +.BR cuserid () +does; avoid it in portable programs. +Or avoid it altogether: use +.I getpwuid(geteuid()) +instead, if that is +what you meant. +.B Do not use +.BR cuserid (). +.SH SEE ALSO +.BR logname (1), +.BR geteuid (2), +.BR getuid (2), +.BR utmp (5) diff --git a/man/man3/getlogin_r.3 b/man/man3/getlogin_r.3 new file mode 100644 index 0000000..b6d53bf --- /dev/null +++ b/man/man3/getlogin_r.3 @@ -0,0 +1 @@ +.so man3/getlogin.3 diff --git a/man/man3/getmntent.3 b/man/man3/getmntent.3 new file mode 100644 index 0000000..93d5100 --- /dev/null +++ b/man/man3/getmntent.3 @@ -0,0 +1,265 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:46:57 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 961109, 031115, aeb +.\" +.TH getmntent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getmntent, setmntent, addmntent, endmntent, hasmntopt, +getmntent_r \- get filesystem descriptor file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "FILE *setmntent(const char *" filename ", const char *" type ); +.P +.BI "struct mntent *getmntent(FILE *" stream ); +.P +.BI "int addmntent(FILE *restrict " stream , +.BI " const struct mntent *restrict " mnt ); +.P +.BI "int endmntent(FILE *" streamp ); +.P +.BI "char *hasmntopt(const struct mntent *" mnt ", const char *" opt ); +.P +/* GNU extension */ +.B #include +.P +.BI "struct mntent *getmntent_r(FILE *restrict " streamp , +.BI " struct mntent *restrict " mntbuf , +.BI " char " buf "[restrict ." buflen "], int " buflen ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getmntent_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These routines are used to access the filesystem description file +.I /etc/fstab +and the mounted filesystem description file +.IR /etc/mtab . +.P +The +.BR setmntent () +function opens the filesystem description file +.I filename +and returns a file pointer which can be used by +.BR getmntent (). +The argument +.I type +is the type of access +required and can take the same values as the +.I mode +argument of +.BR fopen (3). +The returned stream should be closed using +.BR endmntent () +rather than +.BR fclose (3). +.P +The +.BR getmntent () +function reads the next line of the filesystem +description file from +.I stream +and returns a pointer to a structure +containing the broken out fields from a line in the file. +The pointer +points to a static area of memory which is overwritten by subsequent +calls to +.BR getmntent (). +.P +The +.BR addmntent () +function adds the +.I mntent +structure +.I mnt +to +the end of the open +.IR stream . +.P +The +.BR endmntent () +function closes the +.I stream +associated with the filesystem description file. +.P +The +.BR hasmntopt () +function scans the +.I mnt_opts +field (see below) +of the +.I mntent +structure +.I mnt +for a substring that matches +.IR opt . +See +.I +and +.BR mount (8) +for valid mount options. +.P +The reentrant +.BR getmntent_r () +function is similar to +.BR getmntent (), +but stores the +.I mntent +structure +in the provided +.IR *mntbuf , +and stores the strings pointed to by the entries in that structure +in the provided array +.I buf +of size +.IR buflen . +.P +The +.I mntent +structure is defined in +.I +as follows: +.P +.in +4n +.EX +struct mntent { + char *mnt_fsname; /* name of mounted filesystem */ + char *mnt_dir; /* filesystem path prefix */ + char *mnt_type; /* mount type (see mntent.h) */ + char *mnt_opts; /* mount options (see mntent.h) */ + int mnt_freq; /* dump frequency in days */ + int mnt_passno; /* pass number on parallel fsck */ +}; +.EE +.in +.P +Since fields in the mtab and fstab files are separated by whitespace, +octal escapes are used to represent the characters space (\e040), +tab (\e011), newline (\e012), and backslash (\e\e) in those files +when they occur in one of the four strings in a +.I mntent +structure. +The routines +.BR addmntent () +and +.BR getmntent () +will convert +from string representation to escaped representation and back. +When converting from escaped representation, the sequence \e134 is +also converted to a backslash. +.SH RETURN VALUE +The +.BR getmntent () +and +.BR getmntent_r () +functions return +a pointer to the +.I mntent +structure or NULL on failure. +.P +The +.BR addmntent () +function returns 0 on success and 1 on failure. +.P +The +.BR endmntent () +function always returns 1. +.P +The +.BR hasmntopt () +function returns the address of the substring if +a match is found and NULL otherwise. +.SH FILES +.TP +.I /etc/fstab +filesystem description file +.TP +.I /etc/mtab +mounted filesystem description file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setmntent (), +.BR endmntent (), +.BR hasmntopt () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR getmntent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:mntentbuf locale +T} +T{ +.na +.nh +.BR addmntent () +T} Thread safety T{ +.na +.nh +MT-Safe race:stream locale +T} +T{ +.na +.nh +.BR getmntent_r () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +The nonreentrant functions are from SunOS 4.1.3. +A routine +.BR getmntent_r () +was introduced in HP-UX 10, but it returns an +.IR int . +The prototype shown above is glibc-only. +.P +System V also has a +.BR getmntent () +function but the calling sequence +differs, and the returned structure is different. +Under System V +.I /etc/mnttab +is used. +4.4BSD and Digital UNIX have a routine +.BR \%getmntinfo (), +a wrapper around the system call +.BR getfsstat (). +.SH SEE ALSO +.BR fopen (3), +.BR fstab (5), +.BR mount (8) diff --git a/man/man3/getmntent_r.3 b/man/man3/getmntent_r.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man/man3/getmntent_r.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man/man3/getnameinfo.3 b/man/man3/getnameinfo.3 new file mode 100644 index 0000000..4fb632c --- /dev/null +++ b/man/man3/getnameinfo.3 @@ -0,0 +1,345 @@ +'\" t +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. +.\" %%%LICENSE_END +.\" +.\" Almost all details are from RFC 2553. +.\" +.\" 2004-12-14, mtk, Added EAI_OVERFLOW error +.\" 2004-12-14 Fixed description of error return +.\" +.TH getnameinfo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getnameinfo \- address-to-name translation in protocol-independent manner +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int getnameinfo(const struct sockaddr *restrict " addr \ +", socklen_t " addrlen , +.BI " char " host "[_Nullable restrict ." hostlen ], +.BI " socklen_t " hostlen , +.BI " char " serv "[_Nullable restrict ." servlen ], +.BI " socklen_t " servlen , +.BI " int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getnameinfo (): +.nf + Since glibc 2.22: + _POSIX_C_SOURCE >= 200112L + glibc 2.21 and earlier: + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR getnameinfo () +function is the inverse of +.BR getaddrinfo (3): +it converts a socket address to a corresponding host and service, +in a protocol-independent manner. +It combines the functionality of +.BR gethostbyaddr (3) +and +.BR getservbyport (3), +but unlike those functions, +.BR getnameinfo () +is reentrant and allows programs to eliminate +IPv4-versus-IPv6 dependencies. +.P +The +.I addr +argument is a pointer to a generic socket address structure +(of type +.I sockaddr_in +or +.IR sockaddr_in6 ) +of size +.I addrlen +that holds the input IP address and port number. +The arguments +.I host +and +.I serv +are pointers to caller-allocated buffers (of size +.I hostlen +and +.I servlen +respectively) into which +.BR getnameinfo () +places null-terminated strings containing the host and +service names respectively. +.P +The caller can specify that no hostname (or no service name) +is required by providing a NULL +.I host +(or +.IR serv ) +argument or a zero +.I hostlen +(or +.IR servlen ) +argument. +However, at least one of hostname or service name +must be requested. +.P +The +.I flags +argument modifies the behavior of +.BR getnameinfo () +as follows: +.TP +.B NI_NAMEREQD +If set, then an error is returned if the hostname cannot be determined. +.TP +.B NI_DGRAM +If set, then the service is datagram (UDP) based rather than +stream (TCP) based. +This is required for the few ports (512\[en]514) +that have different services for UDP and TCP. +.TP +.B NI_NOFQDN +If set, return only the hostname part of the fully qualified domain name +for local hosts. +.TP +.B NI_NUMERICHOST +If set, then the numeric form of the hostname is returned. +.\" For example, by calling +.\" .BR inet_ntop () +.\" instead of +.\" .BR gethostbyaddr (). +(When not set, this will still happen in case the node's name +cannot be determined.) +.\" POSIX.1-2001 TC1 has NI_NUMERICSCOPE, but glibc doesn't have it. +.TP +.B NI_NUMERICSERV +If set, then the numeric form of the service address is returned. +(When not set, this will still happen in case the service's name +cannot be determined.) +.SS Extensions to getnameinfo() for Internationalized Domain Names +Starting with glibc 2.3.4, +.BR getnameinfo () +has been extended to selectively allow +hostnames to be transparently converted to and from the +Internationalized Domain Name (IDN) format (see RFC 3490, +.IR "Internationalizing Domain Names in Applications (IDNA)" ). +Three new flags are defined: +.TP +.B NI_IDN +If this flag is used, then the name found in the lookup process is +converted from IDN format to the locale's encoding if necessary. +ASCII-only names are not affected by the conversion, which +makes this flag usable in existing programs and environments. +.TP +.B NI_IDN_ALLOW_UNASSIGNED +.TQ +.B NI_IDN_USE_STD3_ASCII_RULES +Setting these flags will enable the +IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and +IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 +conforming hostname) +flags respectively to be used in the IDNA handling. +.SH RETURN VALUE +.\" FIXME glibc defines the following additional errors, some which +.\" can probably be returned by getnameinfo(); they need to +.\" be documented. +.\" +.\" #ifdef __USE_GNU +.\" #define EAI_INPROGRESS -100 /* Processing request in progress. */ +.\" #define EAI_CANCELED -101 /* Request canceled. */ +.\" #define EAI_NOTCANCELED -102 /* Request not canceled. */ +.\" #define EAI_ALLDONE -103 /* All requests done. */ +.\" #define EAI_INTR -104 /* Interrupted by a signal. */ +.\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */ +.\" #endif +On success, 0 is returned, and node and service names, if requested, +are filled with null-terminated strings, possibly truncated to fit +the specified buffer lengths. +On error, one of the following nonzero error codes is returned: +.TP +.B EAI_AGAIN +The name could not be resolved at this time. +Try again later. +.TP +.B EAI_BADFLAGS +The +.I flags +argument has an invalid value. +.TP +.B EAI_FAIL +A nonrecoverable error occurred. +.TP +.B EAI_FAMILY +The address family was not recognized, +or the address length was invalid for the specified family. +.TP +.B EAI_MEMORY +Out of memory. +.TP +.B EAI_NONAME +The name does not resolve for the supplied arguments. +.B NI_NAMEREQD +is set and the host's name cannot be located, +or neither hostname nor service name were requested. +.TP +.B EAI_OVERFLOW +The buffer pointed to by +.I host +or +.I serv +was too small. +.TP +.B EAI_SYSTEM +A system error occurred. +The error code can be found in +.IR errno . +.P +The +.BR gai_strerror (3) +function translates these error codes to a human readable string, +suitable for error reporting. +.SH FILES +.I /etc/hosts +.br +.I /etc/nsswitch.conf +.br +.I /etc/resolv.conf +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getnameinfo () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +POSIX.1-2008. +RFC\ 2553. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.P +Before glibc 2.2, the +.I hostlen +and +.I servlen +arguments were typed as +.IR size_t . +.SH NOTES +In order to assist the programmer in choosing reasonable sizes +for the supplied buffers, +.I +defines the constants +.P +.in +4n +.EX +#define NI_MAXHOST 1025 +#define NI_MAXSERV 32 +.EE +.in +.P +Since glibc 2.8, +these definitions are exposed only if suitable +feature test macros are defined, namely: +.BR _GNU_SOURCE , +.B _DEFAULT_SOURCE +(since glibc 2.19), +or (in glibc versions up to and including 2.19) +.B _BSD_SOURCE +or +.BR _SVID_SOURCE . +.P +The former is the constant +.B MAXDNAME +in recent versions of BIND's +.I +header file. +The latter is a guess based on the services listed +in the current Assigned Numbers RFC. +.SH EXAMPLES +The following code tries to get the numeric hostname and service name, +for a given socket address. +Note that there is no hardcoded reference to +a particular address family. +.P +.in +4n +.EX +struct sockaddr *addr; /* input */ +socklen_t addrlen; /* input */ +char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; +\& +if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf, + sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0) + printf("host=%s, serv=%s\en", hbuf, sbuf); +.EE +.in +.P +The following version checks if the socket address has a +reverse address mapping. +.P +.in +4n +.EX +struct sockaddr *addr; /* input */ +socklen_t addrlen; /* input */ +char hbuf[NI_MAXHOST]; +\& +if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), + NULL, 0, NI_NAMEREQD)) + printf("could not resolve hostname"); +else + printf("host=%s\en", hbuf); +.EE +.in +.P +An example program using +.BR getnameinfo () +can be found in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR accept (2), +.BR getpeername (2), +.BR getsockname (2), +.BR recvfrom (2), +.BR socket (2), +.BR getaddrinfo (3), +.BR gethostbyaddr (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR inet_ntop (3), +.BR hosts (5), +.BR services (5), +.BR hostname (7), +.BR named (8) +.P +R.\& Gilligan, S.\& Thomson, J.\& Bound and W.\& Stevens, +.IR "Basic Socket Interface Extensions for IPv6" , +RFC\ 2553, March 1999. +.P +Tatsuya Jinmei and Atsushi Onoe, +.IR "An Extension of Format for IPv6 Scoped Addresses" , +internet draft, work in progress +.UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt +.UE . +.P +Craig Metz, +.IR "Protocol Independence Using the Sockets API" , +Proceedings of the freenix track: +2000 USENIX annual technical conference, June 2000 +.ad l +.UR http://www.usenix.org\:/publications\:/library\:/proceedings\:/usenix2000\:/freenix\:/metzprotocol.html +.UE . diff --git a/man/man3/getnetbyaddr.3 b/man/man3/getnetbyaddr.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man/man3/getnetbyaddr.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man/man3/getnetbyaddr_r.3 b/man/man3/getnetbyaddr_r.3 new file mode 100644 index 0000000..316d315 --- /dev/null +++ b/man/man3/getnetbyaddr_r.3 @@ -0,0 +1 @@ +.so man3/getnetent_r.3 diff --git a/man/man3/getnetbyname.3 b/man/man3/getnetbyname.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man/man3/getnetbyname.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man/man3/getnetbyname_r.3 b/man/man3/getnetbyname_r.3 new file mode 100644 index 0000000..316d315 --- /dev/null +++ b/man/man3/getnetbyname_r.3 @@ -0,0 +1 @@ +.so man3/getnetent_r.3 diff --git a/man/man3/getnetent.3 b/man/man3/getnetent.3 new file mode 100644 index 0000000..80fc853 --- /dev/null +++ b/man/man3/getnetent.3 @@ -0,0 +1,206 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu) +.TH getnetent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getnetent, getnetbyname, getnetbyaddr, setnetent, endnetent \- +get network entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B struct netent *getnetent(void); +.P +.BI "struct netent *getnetbyname(const char *" name ); +.BI "struct netent *getnetbyaddr(uint32_t " net ", int " type ); +.P +.BI "void setnetent(int " stayopen ); +.B void endnetent(void); +.fi +.SH DESCRIPTION +The +.BR getnetent () +function reads the next entry from the networks database +and returns a +.I netent +structure containing +the broken-out fields from the entry. +A connection is opened to the database if necessary. +.P +The +.BR getnetbyname () +function returns a +.I netent +structure +for the entry from the database +that matches the network +.IR name . +.P +The +.BR getnetbyaddr () +function returns a +.I netent +structure +for the entry from the database +that matches the network number +.I net +of type +.IR type . +The +.I net +argument must be in host byte order. +.P +The +.BR setnetent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getnet* () +functions. +.P +The +.BR endnetent () +function closes the connection to the database. +.P +The +.I netent +structure is defined in +.I +as follows: +.P +.in +4n +.EX +struct netent { + char *n_name; /* official network name */ + char **n_aliases; /* alias list */ + int n_addrtype; /* net address type */ + uint32_t n_net; /* network number */ +} +.EE +.in +.P +The members of the +.I netent +structure are: +.TP +.I n_name +The official name of the network. +.TP +.I n_aliases +A NULL-terminated list of alternative names for the network. +.TP +.I n_addrtype +The type of the network number; always +.BR AF_INET . +.TP +.I n_net +The network number in host byte order. +.SH RETURN VALUE +The +.BR getnetent (), +.BR getnetbyname (), +and +.BR getnetbyaddr () +functions return a pointer to a +statically allocated +.I netent +structure, or a null pointer if an +error occurs or the end of the file is reached. +.SH FILES +.TP +.I /etc/networks +networks database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getnetent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netent +race:netentbuf env locale +T} +T{ +.na +.nh +.BR getnetbyname () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netbyname +env locale +T} +T{ +.na +.nh +.BR getnetbyaddr () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netbyaddr +locale +T} +T{ +.na +.nh +.BR setnetent (), +.BR endnetent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netent env +locale +T} +.TE +.P +In the above table, +.I netent +in +.I race:netent +signifies that if any of the functions +.BR setnetent (), +.BR getnetent (), +or +.BR endnetent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.P +Before glibc 2.2, the +.I net +argument of +.BR getnetbyaddr () +was of type +.IR long . +.SH SEE ALSO +.BR getnetent_r (3), +.BR getprotoent (3), +.BR getservent (3) +.\" .BR networks (5) +.br +RFC\ 1101 diff --git a/man/man3/getnetent_r.3 b/man/man3/getnetent_r.3 new file mode 100644 index 0000000..c7548c2 --- /dev/null +++ b/man/man3/getnetent_r.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getnetent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getnetent_r, getnetbyname_r, getnetbyaddr_r \- get +network entry (reentrant) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getnetent_r(struct netent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct netent **restrict " result , +.BI " int *restrict " h_errnop ); +.BI "int getnetbyname_r(const char *restrict " name , +.BI " struct netent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct netent **restrict " result , +.BI " int *restrict " h_errnop ); +.BI "int getnetbyaddr_r(uint32_t " net ", int " type , +.BI " struct netent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct netent **restrict " result , +.BI " int *restrict " h_errnop ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getnetent_r (), +.BR getnetbyname_r (), +.BR getnetbyaddr_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getnetent_r (), +.BR getnetbyname_r (), +and +.BR getnetbyaddr_r () +functions are the reentrant equivalents of, respectively, +.BR getnetent (3), +.BR getnetbyname (3), +and +.BR getnetbynumber (3). +They differ in the way that the +.I netent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.P +Instead of returning a pointer to a statically allocated +.I netent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.P +The +.I buf +array is used to store the string fields pointed to by the returned +.I netent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer -- mtk. +.P +If the function call successfully obtains a network record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.P +The buffer pointed to by +.I h_errnop +is used to return the value that would be stored in the global variable +.I h_errno +by the nonreentrant versions of these functions. +.\" getnetent.3 doesn't document any use of h_errno, but nevertheless +.\" the nonreentrant functions no seem to set h_errno. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in ERRORS. +.P +On error, record not found +.RB ( getnetbyname_r (), +.BR getnetbyaddr_r ()), +or end of input +.RB ( getnetent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getnetent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getnetent_r (), +.BR getnetbyname_r (), +.BR getnetbyaddr_r () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR getnetent (3), +.BR networks (5) diff --git a/man/man3/getnetgrent.3 b/man/man3/getnetgrent.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man/man3/getnetgrent.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man/man3/getnetgrent_r.3 b/man/man3/getnetgrent_r.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man/man3/getnetgrent_r.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man/man3/getopt.3 b/man/man3/getopt.3 new file mode 100644 index 0000000..828394a --- /dev/null +++ b/man/man3/getopt.3 @@ -0,0 +1,577 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 2006-2008, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt +.\" longindex is a pointer, has_arg can take 3 values, using consistent +.\" names for optstring and longindex, "\n" in formats fixed. Documenting +.\" opterr and getopt_long_only. Clarified explanations (borrowing heavily +.\" from the source code). +.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX +.\" says; moreover, EOF is not defined in . +.\" Modified 2002-02-16, joey: added information about nonexistent +.\" option character and colon as first option character +.\" Modified 2004-07-28, Michael Kerrisk +.\" Added text to explain how to order both '[-+]' and ':' at +.\" the start of optstring +.\" Modified 2006-12-15, mtk, Added getopt() example program. +.\" +.TH getopt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getopt, getopt_long, getopt_long_only, +optarg, optind, opterr, optopt \- Parse command-line options +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getopt(int " argc ", char *" argv [], +.BI " const char *" optstring ); +.P +.BI "extern char *" optarg ; +.BI "extern int " optind ", " opterr ", " optopt ; +.P +.B #include +.P +.BI "int getopt_long(int " argc ", char *" argv [], +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.BI "int getopt_long_only(int " argc ", char *" argv [], +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getopt (): +.nf + _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE +.fi +.P +.BR getopt_long (), +.BR getopt_long_only (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR getopt () +function parses the command-line arguments. +Its arguments +.I argc +and +.I argv +are the argument count and array as passed to the +.IR main () +function on program invocation. +An element of \fIargv\fP that starts with \[aq]\-\[aq] +(and is not exactly "\-" or "\-\-") +is an option element. +The characters of this element +(aside from the initial \[aq]\-\[aq]) are option characters. +If +.BR getopt () +is called repeatedly, it returns successively each of the option characters +from each of the option elements. +.P +The variable +.I optind +is the index of the next element to be processed in +.IR argv . +The system initializes this value to 1. +The caller can reset it to 1 to restart scanning of the same +.IR argv , +or when scanning a new argument vector. +.P +If +.BR getopt () +finds another option character, it returns that +character, updating the external variable \fIoptind\fP and a static +variable \fInextchar\fP so that the next call to +.BR getopt () +can +resume the scan with the following option character or +\fIargv\fP-element. +.P +If there are no more option characters, +.BR getopt () +returns \-1. +Then \fIoptind\fP is the index in \fIargv\fP of the first +\fIargv\fP-element that is not an option. +.P +.I optstring +is a string containing the legitimate option characters. +A legitimate option character is any visible one byte +.BR ascii (7) +character (for which +.BR isgraph (3) +would return nonzero) that is not \[aq]\-\[aq], \[aq]:\[aq], or \[aq];\[aq]. +If such a +character is followed by a colon, the option requires an argument, so +.BR getopt () +places a pointer to the following text in the same +\fIargv\fP-element, or the text of the following \fIargv\fP-element, in +.IR optarg . +Two colons mean an option takes +an optional arg; if there is text in the current \fIargv\fP-element +(i.e., in the same word as the option name itself, for example, "\-oarg"), +then it is returned in \fIoptarg\fP, otherwise \fIoptarg\fP is set to zero. +This is a GNU extension. +If +.I optstring +contains +.B W +followed by a semicolon, then +.B \-W foo +is treated as the long option +.BR \-\-foo . +(The +.B \-W +option is reserved by POSIX.2 for implementation extensions.) +This behavior is a GNU extension, not available with libraries before +glibc 2. +.P +By default, +.BR getopt () +permutes the contents of \fIargv\fP as it +scans, so that eventually all the nonoptions are at the end. +Two other scanning modes are also implemented. +If the first character of +\fIoptstring\fP is \[aq]+\[aq] or the environment variable +.B POSIXLY_CORRECT +is set, then option processing stops as soon as a nonoption argument is +encountered. +If \[aq]+\[aq] is not the first character of +.IR optstring , +it is treated as a normal option. +If +.B POSIXLY_CORRECT +behaviour is required in this case +.I optstring +will contain two \[aq]+\[aq] symbols. +If the first character of \fIoptstring\fP is \[aq]\-\[aq], then +each nonoption \fIargv\fP-element is handled as if it were the argument of +an option with character code 1. +(This is used by programs that were +written to expect options and other \fIargv\fP-elements in any order +and that care about the ordering of the two.) +The special argument "\-\-" forces an end of option-scanning regardless +of the scanning mode. +.P +While processing the option list, +.BR getopt () +can detect two kinds of errors: +(1) an option character that was not specified in +.I optstring +and (2) a missing option argument +(i.e., an option at the end of the command line without an expected argument). +Such errors are handled and reported as follows: +.IP \[bu] 3 +By default, +.BR getopt () +prints an error message on standard error, +places the erroneous option character in +.IR optopt , +and returns \[aq]?\[aq] as the function result. +.IP \[bu] +If the caller has set the global variable +.I opterr +to zero, then +.BR getopt () +does not print an error message. +The caller can determine that there was an error by testing whether +the function return value is \[aq]?\[aq]. +(By default, +.I opterr +has a nonzero value.) +.IP \[bu] +If the first character +(following any optional \[aq]+\[aq] or \[aq]\-\[aq] described above) +of \fIoptstring\fP +is a colon (\[aq]:\[aq]), then +.BR getopt () +likewise does not print an error message. +In addition, it returns \[aq]:\[aq] instead of \[aq]?\[aq] to +indicate a missing option argument. +This allows the caller to distinguish the two different types of errors. +.\" +.SS getopt_long() and getopt_long_only() +The +.BR getopt_long () +function works like +.BR getopt () +except that it also accepts long options, started with two dashes. +(If the program accepts only long options, then +.I optstring +should be specified as an empty string (""), not NULL.) +Long option names may be abbreviated if the abbreviation is +unique or is an exact match for some defined option. +A long option +may take a parameter, of the form +.B \-\-arg=param +or +.BR "\-\-arg param" . +.P +.I longopts +is a pointer to the first element of an array of +.I struct option +declared in +.I +as +.P +.in +4n +.EX +struct option { + const char *name; + int has_arg; + int *flag; + int val; +}; +.EE +.in +.P +The meanings of the different fields are: +.TP +.I name +is the name of the long option. +.TP +.I has_arg +is: +\fBno_argument\fP (or 0) if the option does not take an argument; +\fBrequired_argument\fP (or 1) if the option requires an argument; or +\fBoptional_argument\fP (or 2) if the option takes an optional argument. +.TP +.I flag +specifies how results are returned for a long option. +If \fIflag\fP +is NULL, then +.BR getopt_long () +returns \fIval\fP. +(For example, the calling program may set \fIval\fP to the equivalent short +option character.) +Otherwise, +.BR getopt_long () +returns 0, and +\fIflag\fP points to a variable which is set to \fIval\fP if the +option is found, but left unchanged if the option is not found. +.TP +\fIval\fP +is the value to return, or to load into the variable pointed +to by \fIflag\fP. +.P +The last element of the array has to be filled with zeros. +.P +If \fIlongindex\fP is not NULL, it +points to a variable which is set to the index of the long option relative to +.IR longopts . +.P +.BR getopt_long_only () +is like +.BR getopt_long (), +but \[aq]\-\[aq] as well +as "\-\-" can indicate a long option. +If an option that starts with \[aq]\-\[aq] +(not "\-\-") doesn't match a long option, but does match a short option, +it is parsed as a short option instead. +.SH RETURN VALUE +If an option was successfully found, then +.BR getopt () +returns the option character. +If all command-line options have been parsed, then +.BR getopt () +returns \-1. +If +.BR getopt () +encounters an option character that was not in +.IR optstring , +then \[aq]?\[aq] is returned. +If +.BR getopt () +encounters an option with a missing argument, +then the return value depends on the first character in +.IR optstring : +if it is \[aq]:\[aq], then \[aq]:\[aq] is returned; +otherwise \[aq]?\[aq] is returned. +.P +.BR getopt_long () +and +.BR getopt_long_only () +also return the option +character when a short option is recognized. +For a long option, they +return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise. +Error and \-1 returns are the same as for +.BR getopt (), +plus \[aq]?\[aq] for an +ambiguous match or an extraneous parameter. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +If this is set, then option processing stops as soon as a nonoption +argument is encountered. +.TP +.B __GNU_nonoption_argv_flags_ +This variable was used by +.BR bash (1) +2.0 to communicate to glibc which arguments are the results of +wildcard expansion and so should not be considered as options. +This behavior was removed in +.BR bash (1) +2.01, but the support remains in glibc. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getopt (), +.BR getopt_long (), +.BR getopt_long_only () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getopt env +T} +.TE +.SH VERSIONS +POSIX specifies that the +.I argv +array argument should be +.IR const , +but these functions permute its elements +unless the environment variable +.B POSIXLY_CORRECT +is set. +.I const +is used in the actual prototype to be compatible with other systems; +however, this page doesn't show the qualifier, +to avoid confusing readers. +.SH STANDARDS +.TP +.BR getopt () +POSIX.1-2008. +.TP +.BR getopt_long () +.TQ +.BR getopt_long_only () +GNU. +.IP +The use of \[aq]+\[aq] and \[aq]\-\[aq] in +.I optstring +is a GNU extension. +.SH HISTORY +.TP +.BR getopt () +POSIX.1-2001, and POSIX.2. +.P +On some older implementations, +.BR getopt () +was declared in +.IR . +SUSv1 permitted the declaration to appear in either +.I +or +.IR . +POSIX.1-1996 marked the use of +.I +for this purpose as LEGACY. +POSIX.1-2001 does not require the declaration to appear in +.IR . +.SH NOTES +A program that scans multiple argument vectors, +or rescans the same vector more than once, +and wants to make use of GNU extensions such as \[aq]+\[aq] +and \[aq]\-\[aq] at the start of +.IR optstring , +or changes the value of +.B POSIXLY_CORRECT +between scans, +must reinitialize +.BR getopt () +by resetting +.I optind +to 0, rather than the traditional value of 1. +(Resetting to 0 forces the invocation of an internal initialization +routine that rechecks +.B POSIXLY_CORRECT +and checks for GNU extensions in +.IR optstring .) +.P +Command-line arguments are parsed in strict order +meaning that an option requiring an argument will consume the next argument, +regardless of whether that argument is the correctly specified option argument +or simply the next option +(in the scenario the user mis-specifies the command line). +For example, if +.I optstring +is specified as "1n:" +and the user specifies the command line arguments incorrectly as +.IR "prog\ \-n\ \-1" , +the +.I \-n +option will be given the +.B optarg +value "\-1", and the +.I \-1 +option will be considered to have not been specified. +.SH EXAMPLES +.SS getopt() +The following trivial example program uses +.BR getopt () +to handle two program options: +.IR \-n , +with no associated value; and +.IR "\-t val" , +which expects an associated value. +.P +.\" SRC BEGIN (getopt.c) +.EX +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int flags, opt; + int nsecs, tfnd; +\& + nsecs = 0; + tfnd = 0; + flags = 0; + while ((opt = getopt(argc, argv, "nt:")) != \-1) { + switch (opt) { + case \[aq]n\[aq]: + flags = 1; + break; + case \[aq]t\[aq]: + nsecs = atoi(optarg); + tfnd = 1; + break; + default: /* \[aq]?\[aq] */ + fprintf(stderr, "Usage: %s [\-t nsecs] [\-n] name\en", + argv[0]); + exit(EXIT_FAILURE); + } + } +\& + printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\en", + flags, tfnd, nsecs, optind); +\& + if (optind >= argc) { + fprintf(stderr, "Expected argument after options\en"); + exit(EXIT_FAILURE); + } +\& + printf("name argument = %s\en", argv[optind]); +\& + /* Other code omitted */ +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS getopt_long() +The following example program illustrates the use of +.BR getopt_long () +with most of its features. +.P +.\" SRC BEGIN (getopt_long.c) +.EX +#include +#include /* for printf */ +#include /* for exit */ +\& +int +main(int argc, char *argv[]) +{ + int c; + int digit_optind = 0; +\& + while (1) { + int this_option_optind = optind ? optind : 1; + int option_index = 0; + static struct option long_options[] = { + {"add", required_argument, 0, 0 }, + {"append", no_argument, 0, 0 }, + {"delete", required_argument, 0, 0 }, + {"verbose", no_argument, 0, 0 }, + {"create", required_argument, 0, \[aq]c\[aq]}, + {"file", required_argument, 0, 0 }, + {0, 0, 0, 0 } + }; +\& + c = getopt_long(argc, argv, "abc:d:012", + long_options, &option_index); + if (c == \-1) + break; +\& + switch (c) { + case 0: + printf("option %s", long_options[option_index].name); + if (optarg) + printf(" with arg %s", optarg); + printf("\en"); + break; +\& + case \[aq]0\[aq]: + case \[aq]1\[aq]: + case \[aq]2\[aq]: + if (digit_optind != 0 && digit_optind != this_option_optind) + printf("digits occur in two different argv\-elements.\en"); + digit_optind = this_option_optind; + printf("option %c\en", c); + break; +\& + case \[aq]a\[aq]: + printf("option a\en"); + break; +\& + case \[aq]b\[aq]: + printf("option b\en"); + break; +\& + case \[aq]c\[aq]: + printf("option c with value \[aq]%s\[aq]\en", optarg); + break; +\& + case \[aq]d\[aq]: + printf("option d with value \[aq]%s\[aq]\en", optarg); + break; +\& + case \[aq]?\[aq]: + break; +\& + default: + printf("?? getopt returned character code 0%o ??\en", c); + } + } +\& + if (optind < argc) { + printf("non\-option ARGV\-elements: "); + while (optind < argc) + printf("%s ", argv[optind++]); + printf("\en"); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getopt (1), +.BR getsubopt (3) diff --git a/man/man3/getopt_long.3 b/man/man3/getopt_long.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/getopt_long.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/getopt_long_only.3 b/man/man3/getopt_long_only.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/getopt_long_only.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/getpass.3 b/man/man3/getpass.3 new file mode 100644 index 0000000..6986a83 --- /dev/null +++ b/man/man3/getpass.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH getpass 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpass \- get a password +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] char *getpass(const char *" prompt ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getpass (): +.nf + Since glibc 2.2.2: + _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.2.2: + none +.fi +.SH DESCRIPTION +This function is obsolete. +Do not use it. +See NOTES. +If you want to read input without terminal echoing enabled, +see the description of the +.I ECHO +flag in +.BR termios (3). +.P +The +.BR getpass () +function opens +.I /dev/tty +(the controlling terminal of the process), outputs the string +.IR prompt , +turns off echoing, reads one line (the "password"), +restores the terminal state and closes +.I /dev/tty +again. +.SH RETURN VALUE +The function +.BR getpass () +returns a pointer to a static buffer containing (the first +.B PASS_MAX +bytes of) the password without the trailing +newline, terminated by a null byte (\[aq]\e0\[aq]). +This buffer may be overwritten by a following call. +On error, the terminal state is restored, +.I errno +is set to indicate the error, and NULL is returned. +.SH ERRORS +.TP +.B ENXIO +The process does not have a controlling terminal. +.SH FILES +.I /dev/tty +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpass () +T} Thread safety MT-Unsafe term +.TE +.SH STANDARDS +None. +.SH HISTORY +Version 7 AT&T UNIX. +Present in SUSv2, but marked LEGACY. +Removed in POSIX.1-2001. +.SH NOTES +.\" For libc4 and libc5, the prompt is not written to +.\" .I /dev/tty +.\" but to +.\" .IR stderr . +.\" Moreover, if +.\" .I /dev/tty +.\" cannot be opened, the password is read from +.\" .IR stdin . +.\" The static buffer has length 128 so that only the first 127 +.\" bytes of the password are returned. +.\" While reading the password, signal generation +.\" .RB ( SIGINT , +.\" .BR SIGQUIT , +.\" .BR SIGSTOP , +.\" .BR SIGTSTP ) +.\" is disabled and the corresponding characters +.\" (usually control-C, control-\e, control-Z and control-Y) +.\" are transmitted as part of the password. +.\" Since libc 5.4.19 also line editing is disabled, so that also +.\" backspace and the like will be seen as part of the password. +You should use instead +.BR readpassphrase (3bsd), +provided by +.IR libbsd . +.P +In the GNU C library implementation, if +.I /dev/tty +cannot be opened, the prompt is written to +.I stderr +and the password is read from +.IR stdin . +There is no limit on the length of the password. +Line editing is not disabled. +.P +According to SUSv2, the value of +.B PASS_MAX +must be defined in +.I +in case it is smaller than 8, and can in any case be obtained using +.IR sysconf(_SC_PASS_MAX) . +However, POSIX.2 withdraws the constants +.B PASS_MAX +and +.BR _SC_PASS_MAX , +and the function +.BR getpass (). +.\" Libc4 and libc5 have never supported +.\" .B PASS_MAX +.\" or +.\" .BR _SC_PASS_MAX . +The glibc version accepts +.B _SC_PASS_MAX +and returns +.B BUFSIZ +(e.g., 8192). +.SH BUGS +The calling process should zero the password as soon as possible to avoid +leaving the cleartext password visible in the process's address space. +.SH SEE ALSO +.BR crypt (3) diff --git a/man/man3/getprotobyname.3 b/man/man3/getprotobyname.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man/man3/getprotobyname.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man/man3/getprotobyname_r.3 b/man/man3/getprotobyname_r.3 new file mode 100644 index 0000000..9936ea8 --- /dev/null +++ b/man/man3/getprotobyname_r.3 @@ -0,0 +1 @@ +.so man3/getprotoent_r.3 diff --git a/man/man3/getprotobynumber.3 b/man/man3/getprotobynumber.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man/man3/getprotobynumber.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man/man3/getprotobynumber_r.3 b/man/man3/getprotobynumber_r.3 new file mode 100644 index 0000000..9936ea8 --- /dev/null +++ b/man/man3/getprotobynumber_r.3 @@ -0,0 +1 @@ +.so man3/getprotoent_r.3 diff --git a/man/man3/getprotoent.3 b/man/man3/getprotoent.3 new file mode 100644 index 0000000..1052299 --- /dev/null +++ b/man/man3/getprotoent.3 @@ -0,0 +1,192 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH getprotoent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getprotoent, getprotobyname, getprotobynumber, setprotoent, +endprotoent \- get protocol entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B struct protoent *getprotoent(void); +.P +.BI "struct protoent *getprotobyname(const char *" name ); +.BI "struct protoent *getprotobynumber(int " proto ); +.P +.BI "void setprotoent(int " stayopen ); +.B void endprotoent(void); +.fi +.SH DESCRIPTION +The +.BR getprotoent () +function reads the next entry from the protocols database (see +.BR protocols (5)) +and returns a +.I protoent +structure +containing the broken-out fields from the entry. +A connection is opened to the database if necessary. +.P +The +.BR getprotobyname () +function returns a +.I protoent +structure +for the entry from the database +that matches the protocol name +.IR name . +A connection is opened to the database if necessary. +.P +The +.BR getprotobynumber () +function returns a +.I protoent +structure +for the entry from the database +that matches the protocol number +.IR number . +A connection is opened to the database if necessary. +.P +The +.BR setprotoent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getproto* () +functions. +.P +The +.BR endprotoent () +function closes the connection to the database. +.P +The +.I protoent +structure is defined in +.I +as follows: +.P +.in +4n +.EX +struct protoent { + char *p_name; /* official protocol name */ + char **p_aliases; /* alias list */ + int p_proto; /* protocol number */ +} +.EE +.in +.P +The members of the +.I protoent +structure are: +.TP +.I p_name +The official name of the protocol. +.TP +.I p_aliases +A NULL-terminated list of alternative names for the protocol. +.TP +.I p_proto +The protocol number. +.SH RETURN VALUE +The +.BR getprotoent (), +.BR getprotobyname (), +and +.BR getprotobynumber () +functions return a pointer to a +statically allocated +.I protoent +structure, or a null pointer if an +error occurs or the end of the file is reached. +.SH FILES +.PD 0 +.TP +.I /etc/protocols +protocol database file +.PD +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getprotoent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:protoent +race:protoentbuf locale +T} +T{ +.na +.nh +.BR getprotobyname () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:protobyname +locale +T} +T{ +.na +.nh +.BR getprotobynumber () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:protobynumber +locale +T} +T{ +.na +.nh +.BR setprotoent (), +.BR endprotoent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:protoent +locale +T} +.TE +.P +In the above table, +.I protoent +in +.I race:protoent +signifies that if any of the functions +.BR setprotoent (), +.BR getprotoent (), +or +.BR endprotoent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.SH SEE ALSO +.BR getnetent (3), +.BR getprotoent_r (3), +.BR getservent (3), +.BR protocols (5) diff --git a/man/man3/getprotoent_r.3 b/man/man3/getprotoent_r.3 new file mode 100644 index 0000000..ac2f160 --- /dev/null +++ b/man/man3/getprotoent_r.3 @@ -0,0 +1,243 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getprotoent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getprotoent_r, getprotobyname_r, getprotobynumber_r \- get +protocol entry (reentrant) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getprotoent_r(struct protoent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct protoent **restrict " result ); +.BI "int getprotobyname_r(const char *restrict " name , +.BI " struct protoent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct protoent **restrict " result ); +.BI "int getprotobynumber_r(int " proto , +.BI " struct protoent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct protoent **restrict " result ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getprotoent_r (), +.BR getprotobyname_r (), +.BR getprotobynumber_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getprotoent_r (), +.BR getprotobyname_r (), +and +.BR getprotobynumber_r () +functions are the reentrant equivalents of, respectively, +.BR getprotoent (3), +.BR getprotobyname (3), +and +.BR getprotobynumber (3). +They differ in the way that the +.I protoent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.P +Instead of returning a pointer to a statically allocated +.I protoent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.P +The +.I buf +array is used to store the string fields pointed to by the returned +.I protoent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer. +.\" The 1024 byte value is also what the Solaris man page suggests. -- mtk +.P +If the function call successfully obtains a protocol record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in ERRORS. +.P +On error, record not found +.RB ( getprotobyname_r (), +.BR getprotobynumber_r ()), +or end of input +.RB ( getprotoent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getprotoent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getprotoent_r (), +.BR getprotobyname_r (), +.BR getprotobynumber_r () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH STANDARDS +GNU. +.SH EXAMPLES +The program below uses +.BR getprotobyname_r () +to retrieve the protocol record for the protocol named +in its first command-line argument. +If a second (integer) command-line argument is supplied, +it is used as the initial value for +.IR buflen ; +if +.BR getprotobyname_r () +fails with the error +.BR ERANGE , +the program retries with larger buffer sizes. +The following shell session shows a couple of sample runs: +.P +.in +4n +.EX +.RB "$" " ./a.out tcp 1" +ERANGE! Retrying with larger buffer +getprotobyname_r() returned: 0 (success) (buflen=78) +p_name=tcp; p_proto=6; aliases=TCP +.RB "$" " ./a.out xxx 1" +ERANGE! Retrying with larger buffer +getprotobyname_r() returned: 0 (success) (buflen=100) +Call failed/record not found +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (getprotoent_r.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +\& +#define MAX_BUF 10000 +\& +int +main(int argc, char *argv[]) +{ + int buflen, erange_cnt, s; + struct protoent result_buf; + struct protoent *result; + char buf[MAX_BUF]; +\& + if (argc < 2) { + printf("Usage: %s proto\-name [buflen]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + buflen = 1024; + if (argc > 2) + buflen = atoi(argv[2]); +\& + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\en", MAX_BUF); + exit(EXIT_FAILURE); + } +\& + erange_cnt = 0; + do { + s = getprotobyname_r(argv[1], &result_buf, + buf, buflen, &result); + if (s == ERANGE) { + if (erange_cnt == 0) + printf("ERANGE! Retrying with larger buffer\en"); + erange_cnt++; +\& + /* Increment a byte at a time so we can see exactly + what size buffer was required. */ +\& + buflen++; +\& + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\en", MAX_BUF); + exit(EXIT_FAILURE); + } + } + } while (s == ERANGE); +\& + printf("getprotobyname_r() returned: %s (buflen=%d)\en", + (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" : + strerror(s), buflen); +\& + if (s != 0 || result == NULL) { + printf("Call failed/record not found\en"); + exit(EXIT_FAILURE); + } +\& + printf("p_name=%s; p_proto=%d; aliases=", + result_buf.p_name, result_buf.p_proto); + for (char **p = result_buf.p_aliases; *p != NULL; p++) + printf("%s ", *p); + printf("\en"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getprotoent (3), +.BR protocols (5) diff --git a/man/man3/getpt.3 b/man/man3/getpt.3 new file mode 100644 index 0000000..8b2064f --- /dev/null +++ b/man/man3/getpt.3 @@ -0,0 +1,74 @@ +'\" t +.\" This man page was written by Jeremy Phelps . +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" Redistribute and modify at will. +.\" %%%LICENSE_END +.\" +.TH getpt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpt \- open a new pseudoterminal master +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.B "int getpt(void);" +.fi +.SH DESCRIPTION +.BR getpt () +opens a new pseudoterminal device and returns a file descriptor +that refers to that device. +It is equivalent to opening the pseudoterminal multiplexor device +.P +.in +4n +.EX +open("/dev/ptmx", O_RDWR); +.EE +.in +.P +on Linux systems, though the pseudoterminal multiplexor device is located +elsewhere on some systems that use the GNU C library. +.SH RETURN VALUE +.BR getpt () +returns an open file descriptor upon successful completion. +Otherwise, it +returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.BR getpt () +can fail with various errors described in +.BR open (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpt () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Use +.BR posix_openpt (3) +instead. +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH SEE ALSO +.BR grantpt (3), +.BR posix_openpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR ptmx (4), +.BR pty (7) diff --git a/man/man3/getpw.3 b/man/man3/getpw.3 new file mode 100644 index 0000000..39e8483 --- /dev/null +++ b/man/man3/getpw.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:23:25 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) +.\" +.TH getpw 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpw \- reconstruct password line entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.B #include +.P +.BI "[[deprecated]] int getpw(uid_t " uid ", char *" buf ); +.fi +.SH DESCRIPTION +The +.BR getpw () +function reconstructs the password line entry for +the given user ID \fIuid\fP in the buffer \fIbuf\fP. +The returned buffer contains a line of format +.P +.in +4n +.EX +.B name:passwd:uid:gid:gecos:dir:shell +.EE +.in +.P +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR passwd (5). +.SH RETURN VALUE +The +.BR getpw () +function returns 0 on success; on error, it returns \-1, and +.I errno +is set to indicate the error. +.P +If +.I uid +is not found in the password database, +.BR getpw () +returns \-1, sets +.I errno +to 0, and leaves +.I buf +unchanged. +.SH ERRORS +.TP +.BR 0 " or " ENOENT +No user corresponding to +.IR uid . +.TP +.B EINVAL +.I buf +is NULL. +.TP +.B ENOMEM +Insufficient memory to allocate +.I passwd +structure. +.SH FILES +.TP +.I /etc/passwd +password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpw () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr2. +.SH BUGS +The +.BR getpw () +function is dangerous as it may overflow the provided buffer +.IR buf . +It is obsoleted by +.BR getpwuid (3). +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) diff --git a/man/man3/getpwent.3 b/man/man3/getpwent.3 new file mode 100644 index 0000000..6b3ef03 --- /dev/null +++ b/man/man3/getpwent.3 @@ -0,0 +1,191 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sat Jul 24 19:22:14 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) +.\" +.TH getpwent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpwent, setpwent, endpwent \- get password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.B struct passwd *getpwent(void); +.B void setpwent(void); +.B void endpwent(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getpwent (), +.BR setpwent (), +.BR endpwent (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getpwent () +function returns a pointer to a structure containing +the broken-out fields of a record from the password database +(e.g., the local password file +.IR /etc/passwd , +NIS, and LDAP). +The first time +.BR getpwent () +is called, it returns the first entry; thereafter, it returns successive +entries. +.P +The +.BR setpwent () +function rewinds to the beginning +of the password database. +.P +The +.BR endpwent () +function is used to close the password database +after all processing has been performed. +.P +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR passwd (5). +.SH RETURN VALUE +The +.BR getpwent () +function returns a pointer to a +.I passwd +structure, or NULL if +there are no more entries or an error occurred. +If an error occurs, +.I errno +is set to indicate the error. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.P +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getpwent (), +.BR getpwnam (3), +or +.BR getpwuid (3). +(Do not pass the returned pointer to +.BR free (3).) +.SH ERRORS +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I passwd +structure. +.\" to allocate the passwd structure, or to allocate buffers +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/passwd +local password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpwent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:pwent +race:pwentbuf locale +T} +T{ +.na +.nh +.BR setpwent (), +.BR endpwent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:pwent locale +T} +.TE +.P +In the above table, +.I pwent +in +.I race:pwent +signifies that if any of the functions +.BR setpwent (), +.BR getpwent (), +or +.BR endpwent () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +The +.I pw_gecos +field is not specified in POSIX, but is present on most implementations. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent_r (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR passwd (5) diff --git a/man/man3/getpwent_r.3 b/man/man3/getpwent_r.3 new file mode 100644 index 0000000..60f1414 --- /dev/null +++ b/man/man3/getpwent_r.3 @@ -0,0 +1,227 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH getpwent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpwent_r, fgetpwent_r \- get passwd file entry reentrantly +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getpwent_r(struct passwd *restrict " pwbuf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct passwd **restrict " pwbufp ); +.BI "int fgetpwent_r(FILE *restrict " stream \ +", struct passwd *restrict " pwbuf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct passwd **restrict " pwbufp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getpwent_r (), +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR fgetpwent_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR getpwent_r () +and +.BR fgetpwent_r () +are the reentrant versions of +.BR getpwent (3) +and +.BR fgetpwent (3). +The former reads the next passwd entry from the stream initialized by +.BR setpwent (3). +The latter reads the next passwd entry from +.IR stream . +.P +The \fIpasswd\fP structure is defined in +.I +as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR passwd (5). +.P +The nonreentrant functions return a pointer to static storage, +where this static storage contains further pointers to user +name, password, gecos field, home directory and shell. +The reentrant functions described here return all of that in +caller-provided buffers. +First of all there is the buffer +.I pwbuf +that can hold a \fIstruct passwd\fP. +And next the buffer +.I buf +of size +.I buflen +that can hold additional strings. +The result of these functions, the \fIstruct passwd\fP read from the stream, +is stored in the provided buffer +.IR *pwbuf , +and a pointer to this \fIstruct passwd\fP is returned in +.IR *pwbufp . +.SH RETURN VALUE +On success, these functions return 0 and +.I *pwbufp +is a pointer to the \fIstruct passwd\fP. +On error, these functions return an error value and +.I *pwbufp +is NULL. +.SH ERRORS +.TP +.B ENOENT +No more entries. +.TP +.B ERANGE +Insufficient buffer space supplied. +Try again with larger buffer. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpwent_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:pwent locale +T} +T{ +.na +.nh +.BR fgetpwent_r () +T} Thread safety MT-Safe +.TE +.P +In the above table, +.I pwent +in +.I race:pwent +signifies that if any of the functions +.BR setpwent (), +.BR getpwent (), +.BR endpwent (), +or +.BR getpwent_r () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +Other systems use the prototype +.P +.in +4n +.EX +struct passwd * +getpwent_r(struct passwd *pwd, char *buf, int buflen); +.EE +.in +.P +or, better, +.P +.in +4n +.EX +int +getpwent_r(struct passwd *pwd, char *buf, int buflen, + FILE **pw_fp); +.EE +.in +.SH STANDARDS +None. +.SH HISTORY +These functions are done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +.SH NOTES +The function +.BR getpwent_r () +is not really reentrant since it shares the reading position +in the stream with all other threads. +.SH EXAMPLES +.\" SRC BEGIN (getpwent_r.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +\& +#define BUFLEN 4096 +\& +int +main(void) +{ + struct passwd pw; + struct passwd *pwp; + char buf[BUFLEN]; + int i; +\& + setpwent(); + while (1) { + i = getpwent_r(&pw, buf, sizeof(buf), &pwp); + if (i) + break; + printf("%s (%jd)\etHOME %s\etSHELL %s\en", pwp\->pw_name, + (intmax_t) pwp\->pw_uid, pwp\->pw_dir, pwp\->pw_shell); + } + endpwent(); + exit(EXIT_SUCCESS); +} +.EE +.\" perhaps add error checking - should use strerror_r +.\" #include +.\" #include +.\" if (i) { +.\" if (i == ENOENT) +.\" break; +.\" printf("getpwent_r: %s", strerror(i)); +.\" exit(EXIT_SUCCESS); +.\" } +.\" SRC END +.SH SEE ALSO +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR passwd (5) diff --git a/man/man3/getpwnam.3 b/man/man3/getpwnam.3 new file mode 100644 index 0000000..3547ca5 --- /dev/null +++ b/man/man3/getpwnam.3 @@ -0,0 +1,350 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-05-27 by Martin Schulze (joey@linux.de) +.\" Modified 2003-11-15 by aeb +.\" 2008-11-07, mtk, Added an example program for getpwnam_r(). +.\" +.TH getpwnam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "struct passwd *getpwnam(const char *" name ); +.BI "struct passwd *getpwuid(uid_t " uid ); +.P +.BI "int getpwnam_r(const char *restrict " name ", \ +struct passwd *restrict " pwd , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct passwd **restrict " result ); +.BI "int getpwuid_r(uid_t " uid ", struct passwd *restrict " pwd , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct passwd **restrict " result ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getpwnam_r (), +.BR getpwuid_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getpwnam () +function returns a pointer to a structure containing +the broken-out fields of the record in the password database +(e.g., the local password file +.IR /etc/passwd , +NIS, and LDAP) +that matches the username +.IR name . +.P +The +.BR getpwuid () +function returns a pointer to a structure containing +the broken-out fields of the record in the password database +that matches the user ID +.IR uid . +.P +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* user information */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.P +See +.BR passwd (5) +for more information about these fields. +.P +The +.BR getpwnam_r () +and +.BR getpwuid_r () +functions obtain the same information as +.BR getpwnam () +and +.BR getpwuid (), +but store the retrieved +.I passwd +structure in the space pointed to by +.IR pwd . +The string fields pointed to by the members of the +.I passwd +structure are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.IR *result . +.P +The call +.P +.in +4n +.EX +sysconf(_SC_GETPW_R_SIZE_MAX) +.EE +.in +.P +returns either \-1, without changing +.IR errno , +or an initial suggested size for +.IR buf . +(If this size is too small, +the call fails with +.BR ERANGE , +in which case the caller can retry with a larger buffer.) +.SH RETURN VALUE +The +.BR getpwnam () +and +.BR getpwuid () +functions return a pointer to a +.I passwd +structure, or NULL if the matching entry is not found or +an error occurs. +If an error occurs, +.I errno +is set to indicate the error. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.P +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getpwent (3), +.BR getpwnam (), +or +.BR getpwuid (). +(Do not pass the returned pointer to +.BR free (3).) +.P +On success, +.BR getpwnam_r () +and +.BR getpwuid_r () +return zero, and set +.I *result +to +.IR pwd . +If no matching password record was found, +these functions return 0 and store NULL in +.IR *result . +In case of error, an error number is returned, and NULL is stored in +.IR *result . +.SH ERRORS +.TP +.BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ..." +The given +.I name +or +.I uid +was not found. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I passwd +structure. +.\" This structure is static, allocated 0 or 1 times. No memory leak. (libc45) +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/passwd +local password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getpwnam () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:pwnam locale +T} +T{ +.na +.nh +.BR getpwuid () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:pwuid locale +T} +T{ +.na +.nh +.BR getpwnam_r (), +.BR getpwuid_r () +T} Thread safety T{ +.na +.nh +MT-Safe locale +T} +.TE +.SH VERSIONS +The +.I pw_gecos +field is not specified in POSIX, but is present on most implementations. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +The formulation given above under "RETURN VALUE" is from POSIX.1-2001. +It does not call "not found" an error, and hence does not specify what value +.I errno +might have in this situation. +But that makes it impossible to recognize +errors. +One might argue that according to POSIX +.I errno +should be left unchanged if an entry is not found. +Experiments on various +UNIX-like systems show that lots of different values occur in this +situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others. +.\" more precisely: +.\" AIX 5.1 - gives ESRCH +.\" OSF1 4.0g - gives EWOULDBLOCK +.\" libc, glibc up to glibc 2.6, Irix 6.5 - give ENOENT +.\" since glibc 2.7 - give 0 +.\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM +.\" SunOS 5.8 - gives EBADF +.\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 +.P +The +.I pw_dir +field contains the name of the initial working directory of the user. +Login programs use the value of this field to initialize the +.B HOME +environment variable for the login shell. +An application that wants to determine its user's home directory +should inspect the value of +.B HOME +(rather than the value +.IR getpwuid(getuid())\->pw_dir ) +since this allows the user to modify their notion of +"the home directory" during a login session. +To determine the (initial) home directory of another user, +it is necessary to use +.I getpwnam("username")\->pw_dir +or similar. +.SH EXAMPLES +The program below demonstrates the use of +.BR getpwnam_r () +to find the full username and user ID for the username +supplied as a command-line argument. +.P +.\" SRC BEGIN (getpwnam.c) +.EX +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + struct passwd pwd; + struct passwd *result; + char *buf; + long bufsize; + int s; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s username\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + bufsize = sysconf(_SC_GETPW_R_SIZE_MAX); + if (bufsize == \-1) /* Value was indeterminate */ + bufsize = 16384; /* Should be more than enough */ +\& + buf = malloc(bufsize); + if (buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +\& + s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result); + if (result == NULL) { + if (s == 0) + printf("Not found\en"); + else { + errno = s; + perror("getpwnam_r"); + } + exit(EXIT_FAILURE); + } +\& + printf("Name: %s; UID: %jd\en", pwd.pw_gecos, + (intmax_t) pwd.pw_uid); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent (3), +.BR getgrnam (3), +.BR getpw (3), +.BR getpwent (3), +.BR getspnam (3), +.BR putpwent (3), +.BR setpwent (3), +.BR passwd (5) diff --git a/man/man3/getpwnam_r.3 b/man/man3/getpwnam_r.3 new file mode 100644 index 0000000..e83dcaf --- /dev/null +++ b/man/man3/getpwnam_r.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man/man3/getpwuid.3 b/man/man3/getpwuid.3 new file mode 100644 index 0000000..e83dcaf --- /dev/null +++ b/man/man3/getpwuid.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man/man3/getpwuid_r.3 b/man/man3/getpwuid_r.3 new file mode 100644 index 0000000..e83dcaf --- /dev/null +++ b/man/man3/getpwuid_r.3 @@ -0,0 +1 @@ +.so man3/getpwnam.3 diff --git a/man/man3/getrpcbyname.3 b/man/man3/getrpcbyname.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man/man3/getrpcbyname.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man/man3/getrpcbyname_r.3 b/man/man3/getrpcbyname_r.3 new file mode 100644 index 0000000..78323ea --- /dev/null +++ b/man/man3/getrpcbyname_r.3 @@ -0,0 +1 @@ +.so man3/getrpcent_r.3 diff --git a/man/man3/getrpcbynumber.3 b/man/man3/getrpcbynumber.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man/man3/getrpcbynumber.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man/man3/getrpcbynumber_r.3 b/man/man3/getrpcbynumber_r.3 new file mode 100644 index 0000000..78323ea --- /dev/null +++ b/man/man3/getrpcbynumber_r.3 @@ -0,0 +1 @@ +.so man3/getrpcent_r.3 diff --git a/man/man3/getrpcent.3 b/man/man3/getrpcent.3 new file mode 100644 index 0000000..e1c2f9e --- /dev/null +++ b/man/man3/getrpcent.3 @@ -0,0 +1,136 @@ +'\" t +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)getrpcent.3n 2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI +.TH getrpcent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getrpcent, getrpcbyname, getrpcbynumber, setrpcent, endrpcent \- get +RPC entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B struct rpcent *getrpcent(void); +.P +.BI "struct rpcent *getrpcbyname(const char *" name ); +.BI "struct rpcent *getrpcbynumber(int " number ); +.P +.BI "void setrpcent(int " stayopen ); +.B void endrpcent(void); +.fi +.SH DESCRIPTION +The +.BR getrpcent (), +.BR getrpcbyname (), +and +.BR getrpcbynumber () +functions each return a pointer to an object with the +following structure containing the broken-out +fields of an entry in the RPC program number data base. +.P +.in +4n +.EX +struct rpcent { + char *r_name; /* name of server for this RPC program */ + char **r_aliases; /* alias list */ + long r_number; /* RPC program number */ +}; +.EE +.in +.P +The members of this structure are: +.TP +.I r_name +The name of the server for this RPC program. +.TP +.I r_aliases +A NULL-terminated list of alternate names for the RPC program. +.TP +.I r_number +The RPC program number for this service. +.P +The +.BR getrpcent () +function reads the next entry from the database. +A connection is opened to the database if necessary. +.P +The +.BR setrpcent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getrpc* () +functions. +.P +The +.BR endrpcent () +function closes the connection to the database. +.P +The +.BR getrpcbyname () +and +.BR getrpcbynumber () +functions sequentially search from the beginning +of the file until a matching RPC program name or +program number is found, or until end-of-file is encountered. +.SH RETURN VALUE +On success, +.BR getrpcent (), +.BR getrpcbyname (), +and +.BR getrpcbynumber () +return a pointer to a statically allocated +.I rpcent +structure. +NULL is returned on EOF or error. +.SH FILES +.TP +.I /etc/rpc +RPC program number database. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getrpcent (), +.BR getrpcbyname (), +.BR getrpcbynumber () +T} Thread safety MT-Unsafe +T{ +.na +.nh +.BR setrpcent (), +.BR endrpcent () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +BSD. +.SH HISTORY +BSD, Solaris. +.SH BUGS +All information +is contained in a static area +so it must be copied if it is +to be saved. +.SH SEE ALSO +.BR getrpcent_r (3), +.BR rpc (5), +.BR rpcinfo (8), +.BR ypserv (8) diff --git a/man/man3/getrpcent_r.3 b/man/man3/getrpcent_r.3 new file mode 100644 index 0000000..aa20597 --- /dev/null +++ b/man/man3/getrpcent_r.3 @@ -0,0 +1,136 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getrpcent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getrpcent_r, getrpcbyname_r, getrpcbynumber_r \- get +RPC entry (reentrant) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getrpcent_r(struct rpcent *" result_buf ", char " buf [. buflen ], +.BI " size_t " buflen ", struct rpcent **" result ); +.BI "int getrpcbyname_r(const char *" name , +.BI " struct rpcent *" result_buf ", char " buf [. buflen ], +.BI " size_t " buflen ", struct rpcent **" result ); +.BI "int getrpcbynumber_r(int " number , +.BI " struct rpcent *" result_buf ", char " buf [. buflen ], +.BI " size_t " buflen ", struct rpcent **" result ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getrpcent_r (), +.BR getrpcbyname_r (), +.BR getrpcbynumber_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getrpcent_r (), +.BR getrpcbyname_r (), +and +.BR getrpcbynumber_r () +functions are the reentrant equivalents of, respectively, +.BR getrpcent (3), +.BR getrpcbyname (3), +and +.BR getrpcbynumber (3). +They differ in the way that the +.I rpcent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.P +Instead of returning a pointer to a statically allocated +.I rpcent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.P +The +.I buf +array is used to store the string fields pointed to by the returned +.I rpcent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer -- mtk. +.P +If the function call successfully obtains an RPC record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in ERRORS. +.P +On error, record not found +.RB ( getrpcbyname_r (), +.BR getrpcbynumber_r ()), +or end of input +.RB ( getrpcent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getrpcent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getrpcent_r (), +.BR getrpcbyname_r (), +.BR getrpcbynumber_r () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR getrpcent (3), +.BR rpc (5) diff --git a/man/man3/getrpcport.3 b/man/man3/getrpcport.3 new file mode 100644 index 0000000..23b1171 --- /dev/null +++ b/man/man3/getrpcport.3 @@ -0,0 +1,59 @@ +'\" t +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)getrpcport.3r 2.2 88/08/02 4.0 RPCSRC; from 1.12 88/02/26 SMI +.TH getrpcport 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getrpcport \- get RPC port number +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int getrpcport(const char *" host ", unsigned long " prognum , +.BI " unsigned long " versnum ", unsigned int " proto ); +.fi +.SH DESCRIPTION +.BR getrpcport () +returns the port number for version +.I versnum +of the RPC program +.I prognum +running on +.I host +and using protocol +.IR proto . +It returns 0 if it cannot contact the portmapper, or if +.I prognum +is not registered. +If +.I prognum +is registered but not with version +.IR versnum , +it will still return a port number (for some version of the program) +indicating that the program is indeed registered. +The version mismatch will be detected upon the first call to the service. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getrpcport () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +BSD. +.SH HISTORY +BSD, Solaris. diff --git a/man/man3/gets.3 b/man/man3/gets.3 new file mode 100644 index 0000000..371829b --- /dev/null +++ b/man/man3/gets.3 @@ -0,0 +1,107 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 2013-12-31, David Malcolm +.\" Split gets(3) into its own page; fgetc() et al. move to fgetc(3) +.TH gets 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gets \- get a string from standard input (DEPRECATED) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] char *gets(char *" "s" ); +.fi +.SH DESCRIPTION +.IR "Never use this function" . +.P +.BR gets () +reads a line from +.I stdin +into the buffer pointed to by +.I s +until either a terminating newline or +.BR EOF , +which it replaces with a null byte (\[aq]\e0\[aq]). +No check for buffer overrun is performed (see BUGS below). +.SH RETURN VALUE +.BR gets () +returns +.I s +on success, and NULL +on error or when end of file occurs while no characters have been read. +However, given the lack of buffer overrun checking, there can be no +guarantees that the function will even return. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gets () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.P +LSB deprecates +.BR gets (). +POSIX.1-2008 marks +.BR gets () +obsolescent. +ISO C11 removes the specification of +.BR gets () +from the C language, and since glibc 2.16, +glibc header files don't expose the function declaration if the +.B _ISOC11_SOURCE +feature test macro is defined. +.SH BUGS +Never use +.BR gets (). +Because it is impossible to tell without knowing the data in advance how many +characters +.BR gets () +will read, and because +.BR gets () +will continue to store characters past the end of the buffer, +it is extremely dangerous to use. +It has been used to break computer security. +Use +.BR fgets () +instead. +.P +For more information, see CWE-242 (aka "Use of Inherently Dangerous +Function") at +http://cwe.mitre.org/data/definitions/242.html +.SH SEE ALSO +.BR read (2), +.BR write (2), +.BR ferror (3), +.BR fgetc (3), +.BR fgets (3), +.BR fgetwc (3), +.BR fgetws (3), +.BR fopen (3), +.BR fread (3), +.BR fseek (3), +.BR getline (3), +.BR getwchar (3), +.BR puts (3), +.BR scanf (3), +.BR ungetwc (3), +.BR unlocked_stdio (3), +.BR feature_test_macros (7) diff --git a/man/man3/getservbyname.3 b/man/man3/getservbyname.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man/man3/getservbyname.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man/man3/getservbyname_r.3 b/man/man3/getservbyname_r.3 new file mode 100644 index 0000000..b36a442 --- /dev/null +++ b/man/man3/getservbyname_r.3 @@ -0,0 +1 @@ +.so man3/getservent_r.3 diff --git a/man/man3/getservbyport.3 b/man/man3/getservbyport.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man/man3/getservbyport.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man/man3/getservbyport_r.3 b/man/man3/getservbyport_r.3 new file mode 100644 index 0000000..b36a442 --- /dev/null +++ b/man/man3/getservbyport_r.3 @@ -0,0 +1 @@ +.so man3/getservent_r.3 diff --git a/man/man3/getservent.3 b/man/man3/getservent.3 new file mode 100644 index 0000000..b3c4b26 --- /dev/null +++ b/man/man3/getservent.3 @@ -0,0 +1,209 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:19:11 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Oct 18 20:23:54 1995 by Martin Schulze +.\" Modified Mon Apr 22 01:50:54 1996 by Martin Schulze +.\" 2001-07-25 added a clause about NULL proto (Martin Michlmayr or David N. Welton) +.\" +.TH getservent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getservent, getservbyname, getservbyport, setservent, endservent \- +get service entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B struct servent *getservent(void); +.P +.BI "struct servent *getservbyname(const char *" name ", const char *" proto ); +.BI "struct servent *getservbyport(int " port ", const char *" proto ); +.P +.BI "void setservent(int " stayopen ); +.B void endservent(void); +.fi +.SH DESCRIPTION +The +.BR getservent () +function reads the next entry from the services database (see +.BR services (5)) +and returns a +.I servent +structure containing +the broken-out fields from the entry. +A connection is opened to the database if necessary. +.P +The +.BR getservbyname () +function returns a +.I servent +structure +for the entry from the database +that matches the service +.I name +using protocol +.IR proto . +If +.I proto +is NULL, any protocol will be matched. +A connection is opened to the database if necessary. +.P +The +.BR getservbyport () +function returns a +.I servent +structure +for the entry from the database +that matches the port +.I port +(given in network byte order) +using protocol +.IR proto . +If +.I proto +is NULL, any protocol will be matched. +A connection is opened to the database if necessary. +.P +The +.BR setservent () +function opens a connection to the database, +and sets the next entry to the first entry. +If +.I stayopen +is nonzero, +then the connection to the database +will not be closed between calls to one of the +.BR getserv* () +functions. +.P +The +.BR endservent () +function closes the connection to the database. +.P +The +.I servent +structure is defined in +.I +as follows: +.P +.in +4n +.EX +struct servent { + char *s_name; /* official service name */ + char **s_aliases; /* alias list */ + int s_port; /* port number */ + char *s_proto; /* protocol to use */ +} +.EE +.in +.P +The members of the +.I servent +structure are: +.TP +.I s_name +The official name of the service. +.TP +.I s_aliases +A NULL-terminated list of alternative names for the service. +.TP +.I s_port +The port number for the service given in network byte order. +.TP +.I s_proto +The name of the protocol to use with this service. +.SH RETURN VALUE +The +.BR getservent (), +.BR getservbyname (), +and +.BR getservbyport () +functions return a pointer to a +statically allocated +.I servent +structure, or NULL if an +error occurs or the end of the file is reached. +.SH FILES +.TP +.I /etc/services +services database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getservent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:servent +race:serventbuf locale +T} +T{ +.na +.nh +.BR getservbyname () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:servbyname +locale +T} +T{ +.na +.nh +.BR getservbyport () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:servbyport +locale +T} +T{ +.na +.nh +.BR setservent (), +.BR endservent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:servent +locale +T} +.TE +.P +In the above table, +.I servent +in +.I race:servent +signifies that if any of the functions +.BR setservent (), +.BR getservent (), +or +.BR endservent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.SH SEE ALSO +.BR getnetent (3), +.BR getprotoent (3), +.BR getservent_r (3), +.BR services (5) diff --git a/man/man3/getservent_r.3 b/man/man3/getservent_r.3 new file mode 100644 index 0000000..e2fe200 --- /dev/null +++ b/man/man3/getservent_r.3 @@ -0,0 +1,249 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getservent_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getservent_r, getservbyname_r, getservbyport_r \- get +service entry (reentrant) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getservent_r(struct servent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct servent **restrict " result ); +.BI "int getservbyname_r(const char *restrict " name , +.BI " const char *restrict " proto , +.BI " struct servent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct servent **restrict " result ); +.BI "int getservbyport_r(int " port , +.BI " const char *restrict " proto , +.BI " struct servent *restrict " result_buf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct servent **restrict " result ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getservent_r (), +.BR getservbyname_r (), +.BR getservbyport_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getservent_r (), +.BR getservbyname_r (), +and +.BR getservbyport_r () +functions are the reentrant equivalents of, respectively, +.BR getservent (3), +.BR getservbyname (3), +and +.BR getservbyport (3). +They differ in the way that the +.I servent +structure is returned, +and in the function calling signature and return value. +This manual page describes just the differences from +the nonreentrant functions. +.P +Instead of returning a pointer to a statically allocated +.I servent +structure as the function result, +these functions copy the structure into the location pointed to by +.IR result_buf . +.P +The +.I buf +array is used to store the string fields pointed to by the returned +.I servent +structure. +(The nonreentrant functions allocate these strings in static storage.) +The size of this array is specified in +.IR buflen . +If +.I buf +is too small, the call fails with the error +.BR ERANGE , +and the caller must try again with a larger buffer. +(A buffer of length 1024 bytes should be sufficient for most applications.) +.\" I can find no information on the required/recommended buffer size; +.\" the nonreentrant functions use a 1024 byte buffer -- mtk. +.P +If the function call successfully obtains a service record, then +.I *result +is set pointing to +.IR result_buf ; +otherwise, +.I *result +is set to NULL. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return one of the positive error numbers listed in errors. +.P +On error, record not found +.RB ( getservbyname_r (), +.BR getservbyport_r ()), +or end of input +.RB ( getservent_r ()) +.I result +is set to NULL. +.SH ERRORS +.TP +.B ENOENT +.RB ( getservent_r ()) +No more records in database. +.TP +.B ERANGE +.I buf +is too small. +Try again with a larger buffer +(and increased +.IR buflen ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getservent_r (), +.BR getservbyname_r (), +.BR getservbyport_r () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +Functions with similar names exist on some other systems, +though typically with different calling signatures. +.SH STANDARDS +GNU. +.SH EXAMPLES +The program below uses +.BR getservbyport_r () +to retrieve the service record for the port and protocol named +in its first command-line argument. +If a third (integer) command-line argument is supplied, +it is used as the initial value for +.IR buflen ; +if +.BR getservbyport_r () +fails with the error +.BR ERANGE , +the program retries with larger buffer sizes. +The following shell session shows a couple of sample runs: +.P +.in +4n +.EX +.RB "$" " ./a.out 7 tcp 1" +ERANGE! Retrying with larger buffer +getservbyport_r() returned: 0 (success) (buflen=87) +s_name=echo; s_proto=tcp; s_port=7; aliases= +.RB "$" " ./a.out 77777 tcp" +getservbyport_r() returned: 0 (success) (buflen=1024) +Call failed/record not found +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (getservent_r.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +\& +#define MAX_BUF 10000 +\& +int +main(int argc, char *argv[]) +{ + int buflen, erange_cnt, port, s; + struct servent result_buf; + struct servent *result; + char buf[MAX_BUF]; + char *protop; +\& + if (argc < 3) { + printf("Usage: %s port\-num proto\-name [buflen]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + port = htons(atoi(argv[1])); + protop = (strcmp(argv[2], "null") == 0 || + strcmp(argv[2], "NULL") == 0) ? NULL : argv[2]; +\& + buflen = 1024; + if (argc > 3) + buflen = atoi(argv[3]); +\& + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\en", MAX_BUF); + exit(EXIT_FAILURE); + } +\& + erange_cnt = 0; + do { + s = getservbyport_r(port, protop, &result_buf, + buf, buflen, &result); + if (s == ERANGE) { + if (erange_cnt == 0) + printf("ERANGE! Retrying with larger buffer\en"); + erange_cnt++; +\& + /* Increment a byte at a time so we can see exactly + what size buffer was required. */ +\& + buflen++; +\& + if (buflen > MAX_BUF) { + printf("Exceeded buffer limit (%d)\en", MAX_BUF); + exit(EXIT_FAILURE); + } + } + } while (s == ERANGE); +\& + printf("getservbyport_r() returned: %s (buflen=%d)\en", + (s == 0) ? "0 (success)" : (s == ENOENT) ? "ENOENT" : + strerror(s), buflen); +\& + if (s != 0 || result == NULL) { + printf("Call failed/record not found\en"); + exit(EXIT_FAILURE); + } +\& + printf("s_name=%s; s_proto=%s; s_port=%d; aliases=", + result_buf.s_name, result_buf.s_proto, + ntohs(result_buf.s_port)); + for (char **p = result_buf.s_aliases; *p != NULL; p++) + printf("%s ", *p); + printf("\en"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getservent (3), +.BR services (5) diff --git a/man/man3/getspent.3 b/man/man3/getspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/getspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/getspent_r.3 b/man/man3/getspent_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/getspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/getspnam.3 b/man/man3/getspnam.3 new file mode 100644 index 0000000..03fca91 --- /dev/null +++ b/man/man3/getspnam.3 @@ -0,0 +1,344 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and +.\" Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH getspnam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, +fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent, +lckpwdf, ulckpwdf \- get shadow password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +/* General shadow password file API */ +.B #include +.P +.BI "struct spwd *getspnam(const char *" name ); +.B struct spwd *getspent(void); +.P +.B void setspent(void); +.B void endspent(void); +.P +.BI "struct spwd *fgetspent(FILE *" stream ); +.BI "struct spwd *sgetspent(const char *" s ); +.P +.BI "int putspent(const struct spwd *" p ", FILE *" stream ); +.P +.B int lckpwdf(void); +.B int ulckpwdf(void); +.P +/* GNU extension */ +.B #include +.P +.BI "int getspent_r(struct spwd *" spbuf , +.BI " char " buf [. buflen "], size_t " buflen ", \ +struct spwd **" spbufp ); +.BI "int getspnam_r(const char *" name ", struct spwd *" spbuf , +.BI " char " buf [. buflen "], size_t " buflen ", \ +struct spwd **" spbufp ); +.P +.BI "int fgetspent_r(FILE *" stream ", struct spwd *" spbuf , +.BI " char " buf [. buflen "], size_t " buflen ", \ +struct spwd **" spbufp ); +.BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf , +.BI " char " buf [. buflen "], size_t " buflen ", \ +struct spwd **" spbufp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getspent_r (), +.BR getspnam_r (), +.BR fgetspent_r (), +.BR sgetspent_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +Long ago it was considered safe to have encrypted passwords openly +visible in the password file. +When computers got faster and people +got more security-conscious, this was no longer acceptable. +Julianne Frances Haugh implemented the shadow password suite +that keeps the encrypted passwords in +the shadow password database +(e.g., the local shadow password file +.IR /etc/shadow , +NIS, and LDAP), +readable only by root. +.P +The functions described below resemble those for +the traditional password database +(e.g., see +.BR getpwnam (3) +and +.BR getpwent (3)). +.\" FIXME . I've commented out the following for the +.\" moment. The relationship between PAM and nsswitch.conf needs +.\" to be clearly documented in one place, which is pointed to by +.\" the pages for the user, group, and shadow password functions. +.\" (Jul 2005, mtk) +.\" +.\" This shadow password setup has been superseded by PAM +.\" (pluggable authentication modules), and the file +.\" .I /etc/nsswitch.conf +.\" now describes the sources to be used. +.P +The +.BR getspnam () +function returns a pointer to a structure containing +the broken-out fields of the record in the shadow password database +that matches the username +.IR name . +.P +The +.BR getspent () +function returns a pointer to the next entry in the shadow password +database. +The position in the input stream is initialized by +.BR setspent (). +When done reading, the program may call +.BR endspent () +so that resources can be deallocated. +.\" some systems require a call of setspent() before the first getspent() +.\" glibc does not +.P +The +.BR fgetspent () +function is similar to +.BR getspent () +but uses the supplied stream instead of the one implicitly opened by +.BR setspent (). +.P +The +.BR sgetspent () +function parses the supplied string +.I s +into a struct +.IR spwd . +.P +The +.BR putspent () +function writes the contents of the supplied struct +.I spwd +.I *p +as a text line in the shadow password file format to +.IR stream . +String entries with value NULL and numerical entries with value \-1 +are written as an empty string. +.P +The +.BR lckpwdf () +function is intended to protect against multiple simultaneous accesses +of the shadow password database. +It tries to acquire a lock, and returns 0 on success, +or \-1 on failure (lock not obtained within 15 seconds). +The +.BR ulckpwdf () +function releases the lock again. +Note that there is no protection against direct access of the shadow +password file. +Only programs that use +.BR lckpwdf () +will notice the lock. +.P +These were the functions that formed the original shadow API. +They are widely available. +.\" Also in libc5 +.\" SUN doesn't have sgetspent() +.SS Reentrant versions +Analogous to the reentrant functions for the password database, glibc +also has reentrant functions for the shadow password database. +The +.BR getspnam_r () +function is like +.BR getspnam () +but stores the retrieved shadow password structure in the space pointed to by +.IR spbuf . +This shadow password structure contains pointers to strings, and these strings +are stored in the buffer +.I buf +of size +.IR buflen . +A pointer to the result (in case of success) or NULL (in case no entry +was found or an error occurred) is stored in +.IR *spbufp . +.P +The functions +.BR getspent_r (), +.BR fgetspent_r (), +and +.BR sgetspent_r () +are similarly analogous to their nonreentrant counterparts. +.P +Some non-glibc systems also have functions with these names, +often with different prototypes. +.\" SUN doesn't have sgetspent_r() +.SS Structure +The shadow password structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct spwd { + char *sp_namp; /* Login name */ + char *sp_pwdp; /* Encrypted password */ + long sp_lstchg; /* Date of last change + (measured in days since + 1970\-01\-01 00:00:00 +0000 (UTC)) */ + long sp_min; /* Min # of days between changes */ + long sp_max; /* Max # of days between changes */ + long sp_warn; /* # of days before password expires + to warn user to change it */ + long sp_inact; /* # of days after password expires + until account is disabled */ + long sp_expire; /* Date when account expires + (measured in days since + 1970\-01\-01 00:00:00 +0000 (UTC)) */ + unsigned long sp_flag; /* Reserved */ +}; +.EE +.in +.SH RETURN VALUE +The functions that return a pointer return NULL if no more entries +are available or if an error occurs during processing. +The functions which have \fIint\fP as the return value return 0 for +success and \-1 for failure, with +.I errno +set to indicate the error. +.P +For the nonreentrant functions, the return value may point to static area, +and may be overwritten by subsequent calls to these functions. +.P +The reentrant functions return zero on success. +In case of error, an error number is returned. +.SH ERRORS +.TP +.B EACCES +The caller does not have permission to access the shadow password file. +.TP +.B ERANGE +Supplied buffer is too small. +.SH FILES +.TP +.I /etc/shadow +local shadow password database file +.TP +.I /etc/.pwd.lock +lock file +.P +The include file +.I +defines the constant +.B _PATH_SHADOW +to the pathname of the shadow password file. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getspnam () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getspnam locale +T} +T{ +.na +.nh +.BR getspent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getspent +race:spentbuf locale +T} +T{ +.na +.nh +.BR setspent (), +.BR endspent (), +.BR getspent_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getspent locale +T} +T{ +.na +.nh +.BR fgetspent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:fgetspent +T} +T{ +.na +.nh +.BR sgetspent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:sgetspent +T} +T{ +.na +.nh +.BR putspent (), +.BR getspnam_r (), +.BR sgetspent_r () +T} Thread safety T{ +.na +.nh +MT-Safe locale +T} +T{ +.na +.nh +.BR lckpwdf (), +.BR ulckpwdf (), +.BR fgetspent_r () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +.TE +.P +In the above table, +.I getspent +in +.I race:getspent +signifies that if any of the functions +.BR setspent (), +.BR getspent (), +.BR getspent_r (), +or +.BR endspent () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +Many other systems provide a similar API. +.SH STANDARDS +None. +.SH SEE ALSO +.BR getgrnam (3), +.BR getpwnam (3), +.BR getpwnam_r (3), +.BR shadow (5) diff --git a/man/man3/getspnam_r.3 b/man/man3/getspnam_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/getspnam_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/getsubopt.3 b/man/man3/getsubopt.3 new file mode 100644 index 0000000..99bb4dd --- /dev/null +++ b/man/man3/getsubopt.3 @@ -0,0 +1,251 @@ +'\" t +.\" Copyright (C) 2007 Michael Kerrisk +.\" and Copyright (C) 2007 Justin Pryzby +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.TH getsubopt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getsubopt \- parse suboption arguments from a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getsubopt(char **restrict " optionp ", char *const *restrict " tokens , +.BI " char **restrict " valuep ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getsubopt (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +.BR getsubopt () +parses the list of comma-separated suboptions provided in +.IR optionp . +(Such a suboption list is typically produced when +.BR getopt (3) +is used to parse a command line; +see for example the \fI\-o\fP option of +.BR mount (8).) +Each suboption may include an associated value, +which is separated from the suboption name by an equal sign. +The following is an example of the kind of string +that might be passed in +.IR optionp : +.P +.in +4n +.EX +.B ro,name=xyz +.EE +.in +.P +The +.I tokens +argument is a pointer to a NULL-terminated array of pointers to the tokens that +.BR getsubopt () +will look for in +.IR optionp . +The tokens should be distinct, null-terminated strings containing at +least one character, with no embedded equal signs or commas. +.P +Each call to +.BR getsubopt () +returns information about the next unprocessed suboption in +.IR optionp . +The first equal sign in a suboption (if any) is interpreted as a +separator between the name and the value of that suboption. +The value extends to the next comma, +or (for the last suboption) to the end of the string. +If the name of the suboption matches a known name from +.IR tokens , +and a value string was found, +.BR getsubopt () +sets +.I *valuep +to the address of that string. +The first comma in +.I optionp +is overwritten with a null byte, so +.I *valuep +is precisely the "value string" for that suboption. +.P +If the suboption is recognized, but no value string was found, +.I *valuep +is set to NULL. +.P +When +.BR getsubopt () +returns, +.I optionp +points to the next suboption, +or to the null byte (\[aq]\e0\[aq]) at the end of the +string if the last suboption was just processed. +.SH RETURN VALUE +If the first suboption in +.I optionp +is recognized, +.BR getsubopt () +returns the index of the matching suboption element in +.IR tokens . +Otherwise, \-1 is returned and +.I *valuep +is the entire +.IB name [= value ] +string. +.P +Since +.I *optionp +is changed, the first suboption before the call to +.BR getsubopt () +is not (necessarily) the same as the first suboption after +.BR getsubopt (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getsubopt () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Since +.BR getsubopt () +overwrites any commas it finds in the string +.IR *optionp , +that string must be writable; it cannot be a string constant. +.SH EXAMPLES +The following program expects suboptions following a "\-o" option. +.P +.\" SRC BEGIN (getsubopt.c) +.EX +#define _XOPEN_SOURCE 500 +#include +#include +\& +#include +\& +int +main(int argc, char *argv[]) +{ + enum { + RO_OPT = 0, + RW_OPT, + NAME_OPT + }; + char *const token[] = { + [RO_OPT] = "ro", + [RW_OPT] = "rw", + [NAME_OPT] = "name", + NULL + }; + char *subopts; + char *value; + int opt; +\& + int readonly = 0; + int readwrite = 0; + char *name = NULL; + int errfnd = 0; +\& + while ((opt = getopt(argc, argv, "o:")) != \-1) { + switch (opt) { + case \[aq]o\[aq]: + subopts = optarg; + while (*subopts != \[aq]\e0\[aq] && !errfnd) { +\& + switch (getsubopt(&subopts, token, &value)) { + case RO_OPT: + readonly = 1; + break; +\& + case RW_OPT: + readwrite = 1; + break; +\& + case NAME_OPT: + if (value == NULL) { + fprintf(stderr, + "Missing value for suboption \[aq]%s\[aq]\en", + token[NAME_OPT]); + errfnd = 1; + continue; + } +\& + name = value; + break; +\& + default: + fprintf(stderr, + "No match found for token: /%s/\en", value); + errfnd = 1; + break; + } + } + if (readwrite && readonly) { + fprintf(stderr, + "Only one of \[aq]%s\[aq] and \[aq]%s\[aq] can be specified\en", + token[RO_OPT], token[RW_OPT]); + errfnd = 1; + } + break; +\& + default: + errfnd = 1; + } + } +\& + if (errfnd || argc == 1) { + fprintf(stderr, "\enUsage: %s \-o \en", argv[0]); + fprintf(stderr, + "suboptions are \[aq]ro\[aq], \[aq]rw\[aq], and \[aq]name=\[aq]\en"); + exit(EXIT_FAILURE); + } +\& + /* Remainder of program... */ +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getopt (3) diff --git a/man/man3/getttyent.3 b/man/man3/getttyent.3 new file mode 100644 index 0000000..b8869cb --- /dev/null +++ b/man/man3/getttyent.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH getttyent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getttyent, getttynam, setttyent, endttyent \- get ttys file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.B "struct ttyent *getttyent(void);" +.BI "struct ttyent *getttynam(const char *" name ); +.P +.B "int setttyent(void);" +.B "int endttyent(void);" +.fi +.SH DESCRIPTION +These functions provide an interface to the file +.B _PATH_TTYS +(e.g., +.IR /etc/ttys ). +.P +The function +.BR setttyent () +opens the file or rewinds it if already open. +.P +The function +.BR endttyent () +closes the file. +.P +The function +.BR getttynam () +searches for a given terminal name in the file. +It returns a pointer to a +.I ttyent +structure (description below). +.P +The function +.BR getttyent () +opens the file +.B _PATH_TTYS +(if necessary) and returns the first entry. +If the file is already open, the next entry. +The +.I ttyent +structure has the form: +.P +.in +4n +.EX +struct ttyent { + char *ty_name; /* terminal device name */ + char *ty_getty; /* command to execute, usually getty */ + char *ty_type; /* terminal type for termcap */ + int ty_status; /* status flags */ + char *ty_window; /* command to start up window manager */ + char *ty_comment; /* comment field */ +}; +.EE +.in +.P +.I ty_status +can be: +.P +.in +4n +.EX +#define TTY_ON 0x01 /* enable logins (start ty_getty program) */ +#define TTY_SECURE 0x02 /* allow UID 0 to login */ +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getttyent (), +.BR setttyent (), +.BR endttyent (), +.BR getttynam () +T} Thread safety MT-Unsafe race:ttyent +.TE +.SH STANDARDS +BSD. +.SH NOTES +Under Linux, the file +.IR /etc/ttys , +and the functions described above, are not used. +.SH SEE ALSO +.BR ttyname (3), +.BR ttyslot (3) diff --git a/man/man3/getttynam.3 b/man/man3/getttynam.3 new file mode 100644 index 0000000..1cd11e3 --- /dev/null +++ b/man/man3/getttynam.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man/man3/getusershell.3 b/man/man3/getusershell.3 new file mode 100644 index 0000000..142b36e --- /dev/null +++ b/man/man3/getusershell.3 @@ -0,0 +1,98 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:17:53 1993 by Rik Faith (faith@cs.unc.edu) +.TH getusershell 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getusershell, setusershell, endusershell \- get permitted user shells +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B char *getusershell(void); +.B void setusershell(void); +.B void endusershell(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getusershell (), +.BR setusershell (), +.BR endusershell (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +The +.BR getusershell () +function returns the next line from the file +.IR /etc/shells , +opening the file if necessary. +The line should contain +the pathname of a valid user shell. +If +.I /etc/shells +does not exist or +is unreadable, +.BR getusershell () +behaves as if +.I /bin/sh +and +.I /bin/csh +were listed in the file. +.P +The +.BR setusershell () +function rewinds +.IR /etc/shells . +.P +The +.BR endusershell () +function closes +.IR /etc/shells . +.SH RETURN VALUE +The +.BR getusershell () +function returns NULL on end-of-file. +.SH FILES +.I /etc/shells +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getusershell (), +.BR setusershell (), +.BR endusershell () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +.SH SEE ALSO +.BR shells (5) diff --git a/man/man3/getutent.3 b/man/man3/getutent.3 new file mode 100644 index 0000000..88ba149 --- /dev/null +++ b/man/man3/getutent.3 @@ -0,0 +1,355 @@ +'\" t +.\" Copyright 1995 Mark D. Roth (roth@uiuc.edu) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" Linux libc source code +.\" Solaris manpages +.\" +.\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt +.\" +.\" +.TH getutent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getutent, getutid, getutline, pututline, setutent, endutent, +utmpname \- access utmp file entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B struct utmp *getutent(void); +.BI "struct utmp *getutid(const struct utmp *" ut ); +.BI "struct utmp *getutline(const struct utmp *" ut ); +.P +.BI "struct utmp *pututline(const struct utmp *" ut ); +.P +.B void setutent(void); +.B void endutent(void); +.P +.BI "int utmpname(const char *" file ); +.fi +.SH DESCRIPTION +New applications should use the POSIX.1-specified "utmpx" versions of +these functions; see STANDARDS. +.P +.BR utmpname () +sets the name of the utmp-format file for the other utmp +functions to access. +If +.BR utmpname () +is not used to set the filename +before the other functions are used, they assume \fB_PATH_UTMP\fP, as +defined in \fI\fP. +.P +.BR setutent () +rewinds the file pointer to the beginning of the utmp file. +It is generally a good idea to call it before any of the other +functions. +.P +.BR endutent () +closes the utmp file. +It should be called when the user +code is done accessing the file with the other functions. +.P +.BR getutent () +reads a line from the current file position in the utmp file. +It returns a pointer to a structure containing the fields of +the line. +The definition of this structure is shown in +.BR utmp (5). +.P +.BR getutid () +searches forward from the current file position in the utmp +file based upon \fIut\fP. +If \fIut\->ut_type\fP is one of \fBRUN_LVL\fP, +\fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP, +.BR getutid () +will +find the first entry whose \fIut_type\fP field matches \fIut\->ut_type\fP. +If \fIut\->ut_type\fP is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP, +\fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP, +.BR getutid () +will find the +first entry whose +.I ut_id +field matches \fIut\->ut_id\fP. +.P +.BR getutline () +searches forward from the current file position in the utmp file. +It scans entries whose +.I ut_type +is \fBUSER_PROCESS\fP +or \fBLOGIN_PROCESS\fP and returns the first one whose +.I ut_line +field +matches \fIut\->ut_line\fP. +.P +.BR pututline () +writes the +.I utmp +structure \fIut\fP into the utmp file. +It uses +.BR getutid () +to search for the proper place in the file to insert +the new entry. +If it cannot find an appropriate slot for \fIut\fP, +.BR pututline () +will append the new entry to the end of the file. +.SH RETURN VALUE +.BR getutent (), +.BR getutid (), +and +.BR getutline () +return a pointer to a \fIstruct utmp\fP on success, +and NULL on failure (which includes the "record not found" case). +This \fIstruct utmp\fP is allocated in static storage, and may be +overwritten by subsequent calls. +.P +On success +.BR pututline () +returns +.IR ut ; +on failure, it returns NULL. +.P +.BR utmpname () +returns 0 if the new name was successfully stored, or \-1 on failure. +.P +On failure, these functions +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Out of memory. +.TP +.B ESRCH +Record not found. +.P +.BR setutent (), +.BR pututline (), +and the +.BR getut* () +functions can also fail for the reasons described in +.BR open (2). +.SH FILES +.TP +.I /var/run/utmp +database of currently logged-in users +.TP +.I /var/log/wtmp +database of past user logins +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getutent () +T} Thread safety T{ +.na +.nh +MT-Unsafe init race:utent +race:utentbuf sig:ALRM timer +T} +T{ +.na +.nh +.BR getutid (), +.BR getutline () +T} Thread safety T{ +.na +.nh +MT-Unsafe init race:utent +sig:ALRM timer +T} +T{ +.na +.nh +.BR pututline () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent +sig:ALRM timer +T} +T{ +.na +.nh +.BR setutent (), +.BR endutent (), +.BR utmpname () +T} Thread safety MT-Unsafe race:utent +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (), +.BR getutent (), +.BR getutid (), +.BR getutline (), +.BR pututline (), +.BR utmpname (), +or +.BR endutent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +None. +.SH HISTORY +XPG2, SVr4. +.P +In XPG2 and SVID 2 the function +.BR pututline () +is documented to return void, and that is what it does on many systems +(AIX, HP-UX). +HP-UX introduces a new function +.BR _pututline () +with the prototype given above for +.BR pututline (). +.P +All these functions are obsolete now on non-Linux systems. +POSIX.1-2001 and POSIX.1-2008, following SUSv1, +does not have any of these functions, but instead uses +.P +.RS 4 +.EX +.B #include +.P +.B struct utmpx *getutxent(void); +.B struct utmpx *getutxid(const struct utmpx *); +.B struct utmpx *getutxline(const struct utmpx *); +.B struct utmpx *pututxline(const struct utmpx *); +.B void setutxent(void); +.B void endutxent(void); +.EE +.RE +.P +These functions are provided by glibc, +and perform the same task as their equivalents without the "x", but use +.IR "struct utmpx" , +defined on Linux to be the same as +.IR "struct utmp" . +For completeness, glibc also provides +.BR utmpxname (), +although this function is not specified by POSIX.1. +.P +On some other systems, +the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure, +with additional fields, and larger versions of the existing fields, +and parallel files are maintained, often +.I /var/*/utmpx +and +.IR /var/*/wtmpx . +.P +Linux glibc on the other hand does not use a parallel \fIutmpx\fP file +since its \fIutmp\fP structure is already large enough. +The "x" functions listed above are just aliases for +their counterparts without the "x" (e.g., +.BR getutxent () +is an alias for +.BR getutent ()). +.SH NOTES +.SS glibc notes +The above functions are not thread-safe. +glibc adds reentrant versions +.P +.nf +.B #include +.P +.BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp ); +.BI "int getutid_r(struct utmp *" ut , +.BI " struct utmp *" ubuf ", struct utmp **" ubufp ); +.BI "int getutline_r(struct utmp *" ut , +.BI " struct utmp *" ubuf ", struct utmp **" ubufp ); +.fi +.P +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.P +.BR getutent_r (), +.BR getutid_r (), +.BR getutline_r (): +.nf + _GNU_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +These functions are GNU extensions, analogs of the functions of the +same name without the _r suffix. +The +.I ubuf +argument gives these functions a place to store their result. +On success, they return 0, and a pointer to the result is written in +.IR *ubufp . +On error, these functions return \-1. +There are no utmpx equivalents of the above functions. +(POSIX.1 does not specify such functions.) +.SH EXAMPLES +The following example adds and removes a utmp record, assuming it is run +from within a pseudo terminal. +For usage in a real application, you +should check the return values of +.BR getpwuid (3) +and +.BR ttyname (3). +.P +.\" SRC BEGIN (getutent.c) +.EX +#include +#include +#include +#include +#include +#include +\& +int +main(void) +{ + struct utmp entry; +\& + system("echo before adding entry:;who"); +\& + entry.ut_type = USER_PROCESS; + entry.ut_pid = getpid(); + strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/")); + /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */ + strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty")); + entry.ut_time = time(NULL); + strcpy(entry.ut_user, getpwuid(getuid())\->pw_name); + memset(entry.ut_host, 0, UT_HOSTSIZE); + entry.ut_addr = 0; + setutent(); + pututline(&entry); +\& + system("echo after adding entry:;who"); +\& + entry.ut_type = DEAD_PROCESS; + memset(entry.ut_line, 0, UT_LINESIZE); + entry.ut_time = 0; + memset(entry.ut_user, 0, UT_NAMESIZE); + setutent(); + pututline(&entry); +\& + system("echo after removing entry:;who"); +\& + endutent(); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getutmp (3), +.BR utmp (5) diff --git a/man/man3/getutent_r.3 b/man/man3/getutent_r.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutent_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutid.3 b/man/man3/getutid.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutid.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutid_r.3 b/man/man3/getutid_r.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutid_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutline.3 b/man/man3/getutline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutline_r.3 b/man/man3/getutline_r.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutline_r.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutmp.3 b/man/man3/getutmp.3 new file mode 100644 index 0000000..1d857fe --- /dev/null +++ b/man/man3/getutmp.3 @@ -0,0 +1,71 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getutmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getutmp, getutmpx \- copy utmp structure to utmpx, and vice versa +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "void getutmp(const struct utmpx *" ux ", struct utmp *" u ); +.BI "void getutmpx(const struct utmp *" u ", struct utmpx *" ux ); +.fi +.SH DESCRIPTION +The +.BR getutmp () +function copies the fields of the +.I utmpx +structure pointed to by +.I ux +to the corresponding fields of the +.I utmp +structure pointed to by +.IR u . +The +.BR getutmpx () +function performs the converse operation. +.SH RETURN VALUE +These functions do not return a value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getutmp (), +.BR getutmpx () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +glibc 2.1.1. +Solaris, NetBSD. +.SH NOTES +These functions exist primarily for compatibility with other +systems where the +.I utmp +and +.I utmpx +structures contain different fields, +or the size of corresponding fields differs. +.\" e.g., on Solaris, the utmpx structure is rather larger than utmp. +On Linux, the two structures contain the same fields, +and the fields have the same sizes. +.SH SEE ALSO +.BR utmpdump (1), +.BR getutent (3), +.BR utmp (5) diff --git a/man/man3/getutmpx.3 b/man/man3/getutmpx.3 new file mode 100644 index 0000000..668ecb5 --- /dev/null +++ b/man/man3/getutmpx.3 @@ -0,0 +1 @@ +.so man3/getutmp.3 diff --git a/man/man3/getutxent.3 b/man/man3/getutxent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutxid.3 b/man/man3/getutxid.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutxid.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getutxline.3 b/man/man3/getutxline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/getutxline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/getw.3 b/man/man3/getw.3 new file mode 100644 index 0000000..843d280 --- /dev/null +++ b/man/man3/getw.3 @@ -0,0 +1,84 @@ +'\" t +.\" Copyright (c) 1995 by Jim Van Zandt +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getw 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getw, putw \- input and output of words (ints) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getw(FILE *" stream ); +.BI "int putw(int " w ", FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getw (), +.BR putw (): +.nf + Since glibc 2.3.3: + _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE + Before glibc 2.3.3: + _SVID_SOURCE || _BSD_SOURCE || _XOPEN_SOURCE +.fi +.SH DESCRIPTION +.BR getw () +reads a word (that is, an \fIint\fP) from \fIstream\fP. +It's provided for compatibility with SVr4. +We recommend you use +.BR fread (3) +instead. +.P +.BR putw () +writes the word \fIw\fP (that is, +an \fIint\fP) to \fIstream\fP. +It is provided for compatibility with SVr4, but we recommend you use +.BR fwrite (3) +instead. +.SH RETURN VALUE +Normally, +.BR getw () +returns the word read, and +.BR putw () +returns 0. +On error, they return \fBEOF\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getw (), +.BR putw () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr4, SUSv2. +.SH BUGS +The value returned on error is also a legitimate data value. +.BR ferror (3) +can be used to distinguish between the two cases. +.SH SEE ALSO +.BR ferror (3), +.BR fread (3), +.BR fwrite (3), +.BR getc (3), +.BR putc (3) diff --git a/man/man3/getwc.3 b/man/man3/getwc.3 new file mode 100644 index 0000000..358c2d2 --- /dev/null +++ b/man/man3/getwc.3 @@ -0,0 +1 @@ +.so man3/fgetwc.3 diff --git a/man/man3/getwc_unlocked.3 b/man/man3/getwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/getwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/getwchar.3 b/man/man3/getwchar.3 new file mode 100644 index 0000000..47a53ca --- /dev/null +++ b/man/man3/getwchar.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH getwchar 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getwchar \- read a wide character from standard input +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B "wint_t getwchar(void);" +.fi +.SH DESCRIPTION +The +.BR getwchar () +function is the wide-character equivalent of the +.BR getchar (3) +function. +It reads a wide character from +.I stdin +and returns +it. +If the end of stream is reached, or if +.I ferror(stdin) +becomes true, it returns +.BR WEOF . +If a wide-character conversion error occurs, it sets +.I errno +to +.B EILSEQ +and returns +.BR WEOF . +.P +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR getwchar () +function returns the next wide-character from +standard input, or +.BR WEOF . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getwchar () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +The behavior of +.BR getwchar () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +It is reasonable to expect that +.BR getwchar () +will actually +read a multibyte sequence from standard input and then +convert it to a wide character. +.SH SEE ALSO +.BR fgetwc (3), +.BR unlocked_stdio (3) diff --git a/man/man3/getwchar_unlocked.3 b/man/man3/getwchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/getwchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/getwd.3 b/man/man3/getwd.3 new file mode 100644 index 0000000..f73c157 --- /dev/null +++ b/man/man3/getwd.3 @@ -0,0 +1 @@ +.so man3/getcwd.3 diff --git a/man/man3/glob.3 b/man/man3/glob.3 new file mode 100644 index 0000000..98ea94f --- /dev/null +++ b/man/man3/glob.3 @@ -0,0 +1,353 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 28 11:12:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 13 23:08:50 1996 by Martin Schulze (joey@linux.de) +.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 990912 by aeb +.\" 2007-10-10 mtk +.\" Added description of GLOB_TILDE_NOMATCH +.\" Expanded the description of various flags +.\" Various wording fixes. +.\" +.TH glob 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +glob, globfree \- find pathnames matching a pattern, free memory from glob() +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int glob(const char *restrict " pattern ", int " flags , +.BI " int (*" errfunc ")(const char *" epath ", int " eerrno ), +.BI " glob_t *restrict " pglob ); +.BI "void globfree(glob_t *" pglob ); +.fi +.SH DESCRIPTION +The +.BR glob () +function searches for all the pathnames matching +.I pattern +according to the rules used by the shell (see +.BR glob (7)). +No tilde expansion or parameter substitution is done; if you want +these, use +.BR wordexp (3). +.P +The +.BR globfree () +function frees the dynamically allocated storage from an earlier call +to +.BR glob (). +.P +The results of a +.BR glob () +call are stored in the structure pointed to by +.IR pglob . +This structure is of type +.I glob_t +(declared in +.IR ) +and includes the following elements defined by POSIX.2 (more may be +present as an extension): +.P +.in +4n +.EX +typedef struct { + size_t gl_pathc; /* Count of paths matched so far */ + char **gl_pathv; /* List of matched pathnames. */ + size_t gl_offs; /* Slots to reserve in \fIgl_pathv\fP. */ +} glob_t; +.EE +.in +.P +Results are stored in dynamically allocated storage. +.P +The argument +.I flags +is made up of the bitwise OR of zero or more the following symbolic +constants, which modify the behavior of +.BR glob (): +.TP +.B GLOB_ERR +Return upon a read error (because a directory does not +have read permission, for example). +By default, +.BR glob () +attempts carry on despite errors, +reading all of the directories that it can. +.TP +.B GLOB_MARK +Append a slash to each path which corresponds to a directory. +.TP +.B GLOB_NOSORT +Don't sort the returned pathnames. +The only reason to do this is to save processing time. +By default, the returned pathnames are sorted. +.TP +.B GLOB_DOOFFS +Reserve +.I pglob\->gl_offs +slots at the beginning of the list of strings in +.IR pglob\->pathv . +The reserved slots contain null pointers. +.TP +.B GLOB_NOCHECK +If no pattern matches, return the original pattern. +By default, +.BR glob () +returns +.B GLOB_NOMATCH +if there are no matches. +.TP +.B GLOB_APPEND +Append the results of this call to the vector of results +returned by a previous call to +.BR glob (). +Do not set this flag on the first invocation of +.BR glob (). +.TP +.B GLOB_NOESCAPE +Don't allow backslash (\[aq]\e\[aq]) to be used as an escape +character. +Normally, a backslash can be used to quote the following character, +providing a mechanism to turn off the special meaning +metacharacters. +.P +.I flags +may also include any of the following, which are GNU +extensions and not defined by POSIX.2: +.TP +.B GLOB_PERIOD +Allow a leading period to be matched by metacharacters. +By default, metacharacters can't match a leading period. +.TP +.B GLOB_ALTDIRFUNC +Use alternative functions +.IR pglob\->gl_closedir , +.IR pglob\->gl_readdir , +.IR pglob\->gl_opendir , +.IR pglob\->gl_lstat , +and +.I pglob\->gl_stat +for filesystem access instead of the normal library +functions. +.TP +.B GLOB_BRACE +Expand +.BR csh (1) +style brace expressions of the form +.BR {a,b} . +Brace expressions can be nested. +Thus, for example, specifying the pattern +"{foo/{,cat,dog},bar}" would return the same results as four separate +.BR glob () +calls using the strings: +"foo/", +"foo/cat", +"foo/dog", +and +"bar". +.TP +.B GLOB_NOMAGIC +If the pattern contains no metacharacters, +then it should be returned as the sole matching word, +even if there is no file with that name. +.TP +.B GLOB_TILDE +Carry out tilde expansion. +If a tilde (\[aq]\[ti]\[aq]) is the only character in the pattern, +or an initial tilde is followed immediately by a slash (\[aq]/\[aq]), +then the home directory of the caller is substituted for +the tilde. +If an initial tilde is followed by a username (e.g., "\[ti]andrea/bin"), +then the tilde and username are substituted by the home directory +of that user. +If the username is invalid, or the home directory cannot be +determined, then no substitution is performed. +.TP +.B GLOB_TILDE_CHECK +This provides behavior similar to that of +.BR GLOB_TILDE . +The difference is that if the username is invalid, or the +home directory cannot be determined, then +instead of using the pattern itself as the name, +.BR glob () +returns +.B GLOB_NOMATCH +to indicate an error. +.TP +.B GLOB_ONLYDIR +This is a +.I hint +to +.BR glob () +that the caller is interested only in directories that match the pattern. +If the implementation can easily determine file-type information, +then nondirectory files are not returned to the caller. +However, the caller must still check that returned files +are directories. +(The purpose of this flag is merely to optimize performance when +the caller is interested only in directories.) +.P +If +.I errfunc +is not NULL, +it will be called in case of an error with the arguments +.IR epath , +a pointer to the path which failed, and +.IR eerrno , +the value of +.I errno +as returned from one of the calls to +.BR opendir (3), +.BR readdir (3), +or +.BR stat (2). +If +.I errfunc +returns nonzero, or if +.B GLOB_ERR +is set, +.BR glob () +will terminate after the call to +.IR errfunc . +.P +Upon successful return, +.I pglob\->gl_pathc +contains the number of matched pathnames and +.I pglob\->gl_pathv +contains a pointer to the list of pointers to matched pathnames. +The list of pointers is terminated by a null pointer. +.P +It is possible to call +.BR glob () +several times. +In that case, the +.B GLOB_APPEND +flag has to be set in +.I flags +on the second and later invocations. +.P +As a GNU extension, +.I pglob\->gl_flags +is set to the flags specified, +.BR or ed +with +.B GLOB_MAGCHAR +if any metacharacters were found. +.SH RETURN VALUE +On successful completion, +.BR glob () +returns zero. +Other possible returns are: +.TP +.B GLOB_NOSPACE +for running out of memory, +.TP +.B GLOB_ABORTED +for a read error, and +.TP +.B GLOB_NOMATCH +for no found matches. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR glob () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent env +sig:ALRM timer locale +T} +T{ +.na +.nh +.BR globfree () +T} Thread safety MT-Safe +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR glob () +calls those functions, +so we use race:utent to remind users. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, POSIX.2. +.SH NOTES +The structure elements +.I gl_pathc +and +.I gl_offs +are declared as +.I size_t +in glibc 2.1, as they should be according to POSIX.2, +but are declared as +.I int +in glibc 2.0. +.SH BUGS +The +.BR glob () +function may fail due to failure of underlying function calls, such as +.BR malloc (3) +or +.BR opendir (3). +These will store their error code in +.IR errno . +.SH EXAMPLES +One example of use is the following code, which simulates typing +.P +.in +4n +.EX +ls \-l *.c ../*.c +.EE +.in +.P +in the shell: +.P +.in +4n +.EX +glob_t globbuf; +\& +globbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +glob("../*.c", GLOB_DOOFFS | GLOB_APPEND, NULL, &globbuf); +globbuf.gl_pathv[0] = "ls"; +globbuf.gl_pathv[1] = "\-l"; +execvp("ls", &globbuf.gl_pathv[0]); +.EE +.in +.SH SEE ALSO +.BR ls (1), +.BR sh (1), +.BR stat (2), +.BR exec (3), +.BR fnmatch (3), +.BR malloc (3), +.BR opendir (3), +.BR readdir (3), +.BR wordexp (3), +.BR glob (7) diff --git a/man/man3/globfree.3 b/man/man3/globfree.3 new file mode 100644 index 0000000..20056c6 --- /dev/null +++ b/man/man3/globfree.3 @@ -0,0 +1 @@ +.so man3/glob.3 diff --git a/man/man3/gmtime.3 b/man/man3/gmtime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/gmtime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/gmtime_r.3 b/man/man3/gmtime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/gmtime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/gnu_dev_major.3 b/man/man3/gnu_dev_major.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man/man3/gnu_dev_major.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man/man3/gnu_dev_makedev.3 b/man/man3/gnu_dev_makedev.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man/man3/gnu_dev_makedev.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man/man3/gnu_dev_minor.3 b/man/man3/gnu_dev_minor.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man/man3/gnu_dev_minor.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man/man3/gnu_get_libc_release.3 b/man/man3/gnu_get_libc_release.3 new file mode 100644 index 0000000..7f84005 --- /dev/null +++ b/man/man3/gnu_get_libc_release.3 @@ -0,0 +1 @@ +.so man3/gnu_get_libc_version.3 diff --git a/man/man3/gnu_get_libc_version.3 b/man/man3/gnu_get_libc_version.3 new file mode 100644 index 0000000..20fc521 --- /dev/null +++ b/man/man3/gnu_get_libc_version.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH gnu_get_libc_version 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gnu_get_libc_version, gnu_get_libc_release \- get glibc version and release +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B const char *gnu_get_libc_version(void); +.B const char *gnu_get_libc_release(void); +.fi +.SH DESCRIPTION +The function +.BR gnu_get_libc_version () +returns a string that identifies the glibc version available on the system. +.P +The function +.BR gnu_get_libc_release () +returns a string indicates the release status of the glibc version +available on the system. +This will be a string such as +.IR "stable" . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gnu_get_libc_version (), +.BR gnu_get_libc_release () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH EXAMPLES +When run, the program below will produce output such as the following: +.P +.in +4n +.EX +.RB "$" " ./a.out" +GNU libc version: 2.8 +GNU libc release: stable +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (gnu_get_libc_version.c) +.EX +#include +#include +\& +#include +\& +int +main(void) +{ + printf("GNU libc version: %s\en", gnu_get_libc_version()); + printf("GNU libc release: %s\en", gnu_get_libc_release()); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR confstr (3) diff --git a/man/man3/grantpt.3 b/man/man3/grantpt.3 new file mode 100644 index 0000000..8ac498e --- /dev/null +++ b/man/man3/grantpt.3 @@ -0,0 +1,107 @@ +'\" t +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. - aeb +.\" %%%LICENSE_END +.\" +.TH grantpt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +grantpt \- grant access to the slave pseudoterminal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int grantpt(int " fd ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR grantpt (): +.nf + Since glibc 2.24: + _XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) + glibc 2.23 and earlier: + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +The +.BR grantpt () +function changes the mode and owner of the slave pseudoterminal device +corresponding to the master pseudoterminal referred to by the file descriptor +.IR fd . +The user ID of the slave is set to the real UID of the calling process. +The group ID is set to an unspecified value (e.g., +.IR tty ). +The mode of the slave is set to 0620 (crw\-\-w\-\-\-\-). +.P +The behavior of +.BR grantpt () +is unspecified if a signal handler is installed to catch +.B SIGCHLD +signals. +.SH RETURN VALUE +When successful, +.BR grantpt () +returns 0. +Otherwise, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EACCES +The corresponding slave pseudoterminal could not be accessed. +.TP +.B EBADF +The +.I fd +argument is not a valid open file descriptor. +.TP +.B EINVAL +The +.I fd +argument is valid but not associated with a master pseudoterminal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR grantpt () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.P +This is part of the UNIX 98 pseudoterminal support, see +.BR pts (4). +.P +Historical systems implemented this function via a set-user-ID helper binary +called "pt_chown". +glibc on Linux before glibc 2.33 could do so as well, +in order to support configurations with only BSD pseudoterminals; +this support has been removed. +On modern systems this is either a no-op +\[em]with permissions configured on pty allocation, as is the case on Linux\[em] +or an +.BR ioctl (2). +.SH SEE ALSO +.BR open (2), +.BR posix_openpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR pts (4), +.BR pty (7) diff --git a/man/man3/group_member.3 b/man/man3/group_member.3 new file mode 100644 index 0000000..32f00cc --- /dev/null +++ b/man/man3/group_member.3 @@ -0,0 +1,48 @@ +.\" Copyright (C) 2014, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH group_member 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +group_member \- test whether a process is in a group +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int group_member(gid_t " gid ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR group_member (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR group_member () +function tests whether any of the caller's supplementary group IDs +(as returned by +.BR getgroups (2)) +matches +.IR gid . +.SH RETURN VALUE +The +.BR group_member () +function returns nonzero if any of the caller's +supplementary group IDs matches +.IR gid , +and zero otherwise. +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR getgid (2), +.BR getgroups (2), +.BR getgrouplist (3), +.BR group (5) diff --git a/man/man3/gsignal.3 b/man/man3/gsignal.3 new file mode 100644 index 0000000..748d320 --- /dev/null +++ b/man/man3/gsignal.3 @@ -0,0 +1,118 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.TH gsignal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gsignal, ssignal \- software signal facility +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B typedef void (*sighandler_t)(int); +.P +.BI "[[deprecated]] int gsignal(int " signum ); +.P +.BI "[[deprecated]] sighandler_t ssignal(int " signum ", sighandler_t " action ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR gsignal (), +.BR ssignal (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +Don't use these functions under Linux. +Due to a historical mistake, under Linux these functions are +aliases for +.BR raise (3) +and +.BR signal (2), +respectively. +.P +Elsewhere, on System V-like systems, these functions implement +software signaling, entirely independent of the classical +.BR signal (2) +and +.BR kill (2) +functions. +The function +.BR ssignal () +defines the action to take when the software signal with +number +.I signum +is raised using the function +.BR gsignal (), +and returns the previous such action or +.BR SIG_DFL . +The function +.BR gsignal () +does the following: if no action (or the action +.BR SIG_DFL ) +was +specified for +.IR signum , +then it does nothing and returns 0. +If the action +.B SIG_IGN +was specified for +.IR signum , +then it does nothing and returns 1. +Otherwise, it resets the action to +.B SIG_DFL +and calls +the action function with argument +.IR signum , +and returns the value returned by that function. +The range of possible values +.I signum +varies (often 1\[en]15 or 1\[en]17). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR gsignal () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR ssignal () +T} Thread safety MT-Safe sigintr +.TE +.SH STANDARDS +None. +.SH HISTORY +AIX, DG/UX, HP-UX, SCO, Solaris, Tru64. +They are called obsolete under most of these systems, and are +broken under +.\" Linux libc and +glibc. +Some systems also have +.BR gsignal_r () +and +.BR ssignal_r (). +.SH SEE ALSO +.BR kill (2), +.BR signal (2), +.BR raise (3) diff --git a/man/man3/h_errno.3 b/man/man3/h_errno.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/h_errno.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/hash.3 b/man/man3/hash.3 new file mode 100644 index 0000000..4ccbaca --- /dev/null +++ b/man/man3/hash.3 @@ -0,0 +1,145 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)hash.3 8.6 (Berkeley) 8/18/94 +.\" +.TH hash 3 2024-05-02 "Linux man-pages (unreleased)" +.UC 7 +.SH NAME +hash \- hash database access method +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.ft B +#include +#include +.ft R +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided up until glibc 2.1. +Since glibc 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.P +The routine +.BR dbopen (3) +is the library interface to database files. +One of the supported file formats is hash files. +The general description of the database access methods is in +.BR dbopen (3), +this manual page describes only the hash-specific information. +.P +The hash data structure is an extensible, dynamic hashing scheme. +.P +The access-method-specific data structure provided to +.BR dbopen (3) +is defined in the +.I +include file as follows: +.P +.in +4n +.EX +typedef struct { + unsigned int bsize; + unsigned int ffactor; + unsigned int nelem; + unsigned int cachesize; + uint32_t (*hash)(const void *, size_t); + int lorder; +} HASHINFO; +.EE +.in +.P +The elements of this structure are as follows: +.TP 10 +.I bsize +defines the hash table bucket size, and is, by default, 256 bytes. +It may be preferable to increase the page size for disk-resident tables +and tables with large data items. +.TP +.I ffactor +indicates a desired density within the hash table. +It is an approximation of the number of keys allowed to accumulate in any +one bucket, determining when the hash table grows or shrinks. +The default value is 8. +.TP +.I nelem +is an estimate of the final size of the hash table. +If not set or set too low, hash tables will expand gracefully as keys +are entered, although a slight performance degradation may be noticed. +The default value is 1. +.TP +.I cachesize +is the suggested maximum size, in bytes, of the memory cache. +This value is +.IR "only advisory" , +and the access method will allocate more memory rather than fail. +.TP +.I hash +is a user-defined hash function. +Since no hash function performs equally well on all possible data, the +user may find that the built-in hash function does poorly on a particular +data set. +A user-specified hash functions must take two arguments (a pointer to a byte +string and a length) and return a 32-bit quantity to be used as the hash +value. +.TP +.I lorder +is the byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified), the current host order is used. +If the file already exists, the specified value is ignored and the +value specified when the tree was created is used. +.P +If the file already exists (and the +.B O_TRUNC +flag is not specified), the +values specified for +.IR bsize , +.IR ffactor , +.IR lorder , +and +.I nelem +are +ignored and the values specified when the tree was created are used. +.P +If a hash function is specified, +.I hash_open +attempts to determine if the hash function specified is the same as +the one with which the database was created, and fails if it is not. +.P +Backward-compatible interfaces to the routines described in +.BR dbm (3), +and +.BR ndbm (3) +are provided, however these interfaces are not compatible with +previous file formats. +.SH ERRORS +The +.I hash +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR dbopen (3). +.SH BUGS +Only big and little endian byte order are supported. +.SH SEE ALSO +.BR btree (3), +.BR dbopen (3), +.BR mpool (3), +.BR recno (3) +.P +.IR "Dynamic Hash Tables" , +Per-Ake Larson, Communications of the ACM, April 1988. +.P +.IR "A New Hash Package for UNIX" , +Margo Seltzer, USENIX Proceedings, Winter 1991. diff --git a/man/man3/hasmntopt.3 b/man/man3/hasmntopt.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man/man3/hasmntopt.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man/man3/hcreate.3 b/man/man3/hcreate.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man/man3/hcreate.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man/man3/hcreate_r.3 b/man/man3/hcreate_r.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man/man3/hcreate_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man/man3/hdestroy.3 b/man/man3/hdestroy.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man/man3/hdestroy.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man/man3/hdestroy_r.3 b/man/man3/hdestroy_r.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man/man3/hdestroy_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man/man3/herror.3 b/man/man3/herror.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/herror.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/hsearch.3 b/man/man3/hsearch.3 new file mode 100644 index 0000000..7dc38ee --- /dev/null +++ b/man/man3/hsearch.3 @@ -0,0 +1,355 @@ +'\" t +.\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" SunOS 4.1.1 man pages +.\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt +.\" Remarks from dhw@gamgee.acad.emich.edu Fri Jun 19 06:46:31 1998 +.\" Modified 2001-12-26, 2003-11-28, 2004-05-20, aeb +.\" 2008-09-02, mtk: various additions and rewrites +.\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from +.\" Timothy S. Nelson +.\" +.TH hsearch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, +hsearch_r \- hash table management +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int hcreate(size_t " nel ); +.B "void hdestroy(void);" +.P +.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" htab ); +.BI "void hdestroy_r(struct hsearch_data *" htab ); +.P +.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" retval , +.BI " struct hsearch_data *" htab ); +.fi +.SH DESCRIPTION +The three functions +.BR hcreate (), +.BR hsearch (), +and +.BR hdestroy () +allow the caller to create and manage a hash search table +containing entries consisting of a key (a string) and associated data. +Using these functions, only one hash table can be used at a time. +.P +The three functions +.BR hcreate_r (), +.BR hsearch_r (), +.BR hdestroy_r () +are reentrant versions that allow a program to use +more than one hash search table at the same time. +The last argument, +.IR htab , +points to a structure that describes the table +on which the function is to operate. +The programmer should treat this structure as opaque +(i.e., do not attempt to directly access or modify +the fields in this structure). +.P +First a hash table must be created using +.BR hcreate (). +The argument \fInel\fP specifies the maximum number of entries +in the table. +(This maximum cannot be changed later, so choose it wisely.) +The implementation may adjust this value upward to improve the +performance of the resulting hash table. +.\" e.g., in glibc it is raised to the next higher prime number +.P +The +.BR hcreate_r () +function performs the same task as +.BR hcreate (), +but for the table described by the structure +.IR *htab . +The structure pointed to by +.I htab +must be zeroed before the first call to +.BR hcreate_r (). +.P +The function +.BR hdestroy () +frees the memory occupied by the hash table that was created by +.BR hcreate (). +After calling +.BR hdestroy (), +a new hash table can be created using +.BR hcreate (). +The +.BR hdestroy_r () +function performs the analogous task for a hash table described by +.IR *htab , +which was previously created using +.BR hcreate_r (). +.P +The +.BR hsearch () +function searches the hash table for an +item with the same key as \fIitem\fP (where "the same" is determined using +.BR strcmp (3)), +and if successful returns a pointer to it. +.P +The argument \fIitem\fP is of type \fIENTRY\fP, which is defined in +\fI\fP as follows: +.P +.in +4n +.EX +typedef struct entry { + char *key; + void *data; +} ENTRY; +.EE +.in +.P +The field \fIkey\fP points to a null-terminated string which is the +search key. +The field \fIdata\fP points to data that is associated with that key. +.P +The argument \fIaction\fP determines what +.BR hsearch () +does after an unsuccessful search. +This argument must either have the value +.BR ENTER , +meaning insert a copy of +.I item +(and return a pointer to the new hash table entry as the function result), +or the value +.BR FIND , +meaning that NULL should be returned. +(If +.I action +is +.BR FIND , +then +.I data +is ignored.) +.P +The +.BR hsearch_r () +function is like +.BR hsearch () +but operates on the hash table described by +.IR *htab . +The +.BR hsearch_r () +function differs from +.BR hsearch () +in that a pointer to the found item is returned in +.IR *retval , +rather than as the function result. +.SH RETURN VALUE +.BR hcreate () +and +.BR hcreate_r () +return nonzero on success. +They return 0 on error, with +.I errno +set to indicate the error. +.P +On success, +.BR hsearch () +returns a pointer to an entry in the hash table. +.BR hsearch () +returns NULL on error, that is, +if \fIaction\fP is \fBENTER\fP and +the hash table is full, or \fIaction\fP is \fBFIND\fP and \fIitem\fP +cannot be found in the hash table. +.BR hsearch_r () +returns nonzero on success, and 0 on error. +In the event of an error, these two functions set +.I errno +to indicate the error. +.SH ERRORS +.BR hcreate_r () +and +.BR hdestroy_r () +can fail for the following reasons: +.TP +.B EINVAL +.I htab +is NULL. +.P +.BR hsearch () +and +.BR hsearch_r () +can fail for the following reasons: +.TP +.B ENOMEM +.I action +was +.BR ENTER , +.I key +was not found in the table, +and there was no room in the table to add a new entry. +.TP +.B ESRCH +.I action +was +.BR FIND , +and +.I key +was not found in the table. +.P +POSIX.1 specifies only the +.\" PROX.1-2001, POSIX.1-2008 +.B ENOMEM +error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR hcreate (), +.BR hsearch (), +.BR hdestroy () +T} Thread safety MT-Unsafe race:hsearch +T{ +.na +.nh +.BR hcreate_r (), +.BR hsearch_r (), +.BR hdestroy_r () +T} Thread safety MT-Safe race:htab +.TE +.SH STANDARDS +.TP +.BR hcreate () +.TQ +.BR hsearch () +.TQ +.BR hdestroy () +POSIX.1-2008. +.TP +.BR hcreate_r () +.TQ +.BR hsearch_r () +.TQ +.BR hdestroy_r () +GNU. +.SH HISTORY +.TP +.BR hcreate () +.TQ +.BR hsearch () +.TQ +.BR hdestroy () +SVr4, POSIX.1-2001. +.TP +.BR hcreate_r () +.TQ +.BR hsearch_r () +.TQ +.BR hdestroy_r () +GNU. +.SH NOTES +Hash table implementations are usually more efficient when the +table contains enough free space to minimize collisions. +Typically, this means that +.I nel +should be at least 25% larger than the maximum number of elements +that the caller expects to store in the table. +.P +The +.BR hdestroy () +and +.BR hdestroy_r () +functions do not free the buffers pointed to by the +.I key +and +.I data +elements of the hash table entries. +(It can't do this because it doesn't know +whether these buffers were allocated dynamically.) +If these buffers need to be freed (perhaps because the program +is repeatedly creating and destroying hash tables, +rather than creating a single table whose lifetime +matches that of the program), +then the program must maintain bookkeeping data structures that +allow it to free them. +.SH BUGS +SVr4 and POSIX.1-2001 specify that \fIaction\fP +is significant only for unsuccessful searches, so that an \fBENTER\fP +should not do anything for a successful search. +In libc and glibc (before glibc 2.3), the +implementation violates the specification, +updating the \fIdata\fP for the given \fIkey\fP in this case. +.P +Individual hash table entries can be added, but not deleted. +.SH EXAMPLES +The following program inserts 24 items into a hash table, then prints +some of them. +.P +.\" SRC BEGIN (hsearch.c) +.EX +#include +#include +#include +\& +static char *data[] = { "alpha", "bravo", "charlie", "delta", + "echo", "foxtrot", "golf", "hotel", "india", "juliet", + "kilo", "lima", "mike", "november", "oscar", "papa", + "quebec", "romeo", "sierra", "tango", "uniform", + "victor", "whisky", "x\-ray", "yankee", "zulu" +}; +\& +int +main(void) +{ + ENTRY e; + ENTRY *ep; +\& + hcreate(30); +\& + for (size_t i = 0; i < 24; i++) { + e.key = data[i]; + /* data is just an integer, instead of a + pointer to something */ + e.data = (void *) i; + ep = hsearch(e, ENTER); + /* there should be no failures */ + if (ep == NULL) { + fprintf(stderr, "entry failed\en"); + exit(EXIT_FAILURE); + } + } +\& + for (size_t i = 22; i < 26; i++) { + /* print two entries from the table, and + show that two are not in the table */ + e.key = data[i]; + ep = hsearch(e, FIND); + printf("%9.9s \-> %9.9s:%d\en", e.key, + ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0); + } + hdestroy(); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR bsearch (3), +.BR lsearch (3), +.BR malloc (3), +.BR tsearch (3) diff --git a/man/man3/hsearch_r.3 b/man/man3/hsearch_r.3 new file mode 100644 index 0000000..f4a0405 --- /dev/null +++ b/man/man3/hsearch_r.3 @@ -0,0 +1 @@ +.so man3/hsearch.3 diff --git a/man/man3/hstrerror.3 b/man/man3/hstrerror.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/hstrerror.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/htobe16.3 b/man/man3/htobe16.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htobe16.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htobe32.3 b/man/man3/htobe32.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htobe32.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htobe64.3 b/man/man3/htobe64.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htobe64.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htole16.3 b/man/man3/htole16.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htole16.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htole32.3 b/man/man3/htole32.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htole32.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htole64.3 b/man/man3/htole64.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/htole64.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/htonl.3 b/man/man3/htonl.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man/man3/htonl.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man/man3/htons.3 b/man/man3/htons.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man/man3/htons.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man/man3/hypot.3 b/man/man3/hypot.3 new file mode 100644 index 0000000..19f028c --- /dev/null +++ b/man/man3/hypot.3 @@ -0,0 +1,155 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH hypot 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +hypot, hypotf, hypotl \- Euclidean distance function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double hypot(double " x ", double " y ); +.BI "float hypotf(float " x ", float " y ); +.BI "long double hypotl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR hypot (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR hypotf (), +.BR hypotl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return +.RI sqrt( x * x + y * y ). +This is the length of the hypotenuse of a right-angled triangle +with sides of length +.I x +and +.IR y , +or the distance of the point +.RI ( x , y ) +from the origin. +.P +The calculation is performed without undue overflow or underflow +during the intermediate steps of the calculation. +.\" e.g., hypot(DBL_MIN, DBL_MIN) does the right thing, as does, say +.\" hypot(DBL_MAX/2.0, DBL_MAX/2.0). +.SH RETURN VALUE +On success, these functions return the length of the hypotenuse of +a right-angled triangle +with sides of length +.I x +and +.IR y . +.P +If +.I x +or +.I y +is an infinity, +positive infinity is returned. +.P +If +.I x +or +.I y +is a NaN, +and the other argument is not an infinity, +a NaN is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively. +.P +If both arguments are subnormal, and the result is subnormal, +.\" Actually, could the result not be subnormal if both arguments +.\" are subnormal? I think not -- mtk, Jul 2008 +a range error occurs, +and the correct result is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: result underflow +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.IP +These functions do not set +.I errno +for this case. +.\" This is intentional; see +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6795 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR hypot (), +.BR hypotf (), +.BR hypotl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cabs (3), +.BR sqrt (3) diff --git a/man/man3/hypotf.3 b/man/man3/hypotf.3 new file mode 100644 index 0000000..e5c8ab8 --- /dev/null +++ b/man/man3/hypotf.3 @@ -0,0 +1 @@ +.so man3/hypot.3 diff --git a/man/man3/hypotl.3 b/man/man3/hypotl.3 new file mode 100644 index 0000000..e5c8ab8 --- /dev/null +++ b/man/man3/hypotl.3 @@ -0,0 +1 @@ +.so man3/hypot.3 diff --git a/man/man3/iconv.3 b/man/man3/iconv.3 new file mode 100644 index 0000000..120fbbc --- /dev/null +++ b/man/man3/iconv.3 @@ -0,0 +1,233 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" +.\" 2000-06-30 correction by Yuichi SATO +.\" 2000-11-15 aeb, fixed prototype +.\" +.TH iconv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iconv \- perform character set conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t iconv(iconv_t " cd , +.BI " char **restrict " inbuf ", size_t *restrict " inbytesleft , +.BI " char **restrict " outbuf ", size_t *restrict " outbytesleft ); +.fi +.SH DESCRIPTION +The +.BR iconv () +function converts a sequence of characters in one character encoding +to a sequence of characters in another character encoding. +The +.I cd +argument is a conversion descriptor, +previously created by a call to +.BR iconv_open (3); +the conversion descriptor defines the character encodings that +.BR iconv () +uses for the conversion. +The +.I inbuf +argument is the address of a variable that points to +the first character of the input sequence; +.I inbytesleft +indicates the number of bytes in that buffer. +The +.I outbuf +argument is the address of a variable that points to +the first byte available in the output buffer; +.I outbytesleft +indicates the number of bytes available in the output buffer. +.P +The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL. +In this case, the +.BR iconv () +function converts the multibyte sequence +starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP. +At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read. +At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. +.P +The +.BR iconv () +function converts one multibyte character at a time, and for +each character conversion it increments \fI*inbuf\fP and decrements +\fI*inbytesleft\fP by the number of converted input bytes, it increments +\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted +output bytes, and it updates the conversion state contained in \fIcd\fP. +If the character encoding of the input is stateful, the +.BR iconv () +function can also convert a sequence of input bytes +to an update to the conversion state without producing any output bytes; +such input is called a \fIshift sequence\fP. +The conversion can stop for five reasons: +.IP \[bu] 3 +An invalid multibyte sequence is encountered in the input. +In this case, +it sets \fIerrno\fP to \fBEILSEQ\fP and returns +.IR (size_t)\ \-1 . +\fI*inbuf\fP +is left pointing to the beginning of the invalid multibyte sequence. +.IP \[bu] +A multibyte sequence is encountered that is valid but that +cannot be translated to the character encoding of the output. +This condition depends on the implementation and on the conversion descriptor. +In the GNU C library and GNU libiconv, if +.I cd +was created without the suffix +.B //TRANSLIT +or +.BR //IGNORE , +the conversion is strict: +lossy conversions produce this condition. +If the suffix +.B //TRANSLIT +was specified, +transliteration can avoid this condition in some cases. +In the musl C library, +this condition cannot occur because a conversion to +.B \[aq]*\[aq] +is used as a fallback. +In the FreeBSD, NetBSD, and Solaris implementations of +.BR iconv (), +this condition cannot occur either, +because a conversion to +.B \[aq]?\[aq] +is used as a fallback. +When this condition is met, +.BR iconv () +sets +.I errno +to +.B EILSEQ +and returns +.IR (size_t)\ \-1 . +.I *inbuf +is left pointing to the beginning of the unconvertible multibyte sequence. +.IP \[bu] +The input byte sequence has been entirely converted, +that is, \fI*inbytesleft\fP has gone down to 0. +In this case, +.BR iconv () +returns the number of +nonreversible conversions performed during this call. +.IP \[bu] +An incomplete multibyte sequence is encountered in the input, and the +input byte sequence terminates after it. +In this case, it sets \fIerrno\fP to +\fBEINVAL\fP and returns +.IR (size_t)\ \-1 . +\fI*inbuf\fP is left pointing to the +beginning of the incomplete multibyte sequence. +.IP \[bu] +The output buffer has no more room for the next converted character. +In this case, it sets \fIerrno\fP to \fBE2BIG\fP and returns +.IR (size_t)\ \-1 . +.P +A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but +\fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. +In this case, the +.BR iconv () +function attempts to set \fIcd\fP's conversion state to the +initial state and store a corresponding shift sequence at \fI*outbuf\fP. +At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. +If the output buffer has no more room for this reset sequence, it sets +\fIerrno\fP to \fBE2BIG\fP and returns +.IR (size_t)\ \-1 . +Otherwise, it increments +\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes +written. +.P +A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and +\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. +In this case, the +.BR iconv () +function sets \fIcd\fP's conversion state to the initial state. +.SH RETURN VALUE +The +.BR iconv () +function returns the number of characters converted in a +nonreversible way during this call; reversible conversions are not counted. +In case of error, +.BR iconv () +returns +.I (size_t)\ \-1 +and sets +.I errno +to indicate the error. +.SH ERRORS +The following errors can occur, among others: +.TP +.B E2BIG +There is not sufficient room at \fI*outbuf\fP. +.TP +.B EILSEQ +An invalid multibyte sequence has been encountered in the input. +.TP +.B EINVAL +An incomplete multibyte sequence has been encountered in the input. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iconv () +T} Thread safety MT-Safe race:cd +.TE +.P +The +.BR iconv () +function is MT-Safe, as long as callers arrange for +mutual exclusion on the +.I cd +argument. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +In each series of calls to +.BR iconv (), +the last should be one with \fIinbuf\fP or \fI*inbuf\fP equal to NULL, +in order to flush out any partially converted input. +.P +Although +.I inbuf +and +.I outbuf +are typed as +.IR "char\ **" , +this does not mean that the objects they point can be interpreted +as C strings or as arrays of characters: +the interpretation of character byte sequences is +handled internally by the conversion functions. +In some encodings, a zero byte may be a valid part of a multibyte character. +.P +The caller of +.BR iconv () +must ensure that the pointers passed to the function are suitable +for accessing characters in the appropriate character set. +This includes ensuring correct alignment on platforms that have +tight restrictions on alignment. +.SH SEE ALSO +.BR iconv_close (3), +.BR iconv_open (3), +.BR iconvconfig (8) diff --git a/man/man3/iconv_close.3 b/man/man3/iconv_close.3 new file mode 100644 index 0000000..f5014e3 --- /dev/null +++ b/man/man3/iconv_close.3 @@ -0,0 +1,56 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH iconv_close 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iconv_close \- deallocate descriptor for character set conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iconv_close(iconv_t " cd ); +.fi +.SH DESCRIPTION +The +.BR iconv_close () +function deallocates a conversion descriptor +.I cd +previously allocated using +.BR iconv_open (3). +.SH RETURN VALUE +On success, +.BR iconv_close () +returns 0; otherwise, it returns \-1 and sets +.I errno +to indicate the error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iconv_close () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH SEE ALSO +.BR iconv (3), +.BR iconv_open (3) diff --git a/man/man3/iconv_open.3 b/man/man3/iconv_open.3 new file mode 100644 index 0000000..86333f9 --- /dev/null +++ b/man/man3/iconv_open.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" +.\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT +.\" and //IGNORE extensions for 'tocode'. +.\" +.TH iconv_open 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iconv_open \- allocate descriptor for character set conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode ); +.fi +.SH DESCRIPTION +The +.BR iconv_open () +function allocates a conversion descriptor suitable +for converting byte sequences from character encoding +.I fromcode +to +character encoding +.IR tocode . +.P +The values permitted for +.I fromcode +and +.I tocode +and the supported +combinations are system-dependent. +For the GNU C library, the permitted +values are listed by the +.I "iconv \-\-list" +command, and all combinations +of the listed values are supported. +Furthermore the GNU C library and the +GNU libiconv library support the following two suffixes: +.TP +//TRANSLIT +When the string "//TRANSLIT" is appended to +.IR tocode , +transliteration +is activated. +This means that when a character cannot be represented in the +target character set, it can be approximated through one or several +similarly looking characters. +.TP +//IGNORE +When the string "//IGNORE" is appended to +.IR tocode , +characters that +cannot be represented in the target character set will be silently discarded. +.P +The resulting conversion descriptor can be used with +.BR iconv (3) +any number of times. +It remains valid until deallocated using +.BR iconv_close (3). +.P +A conversion descriptor contains a conversion state. +After creation using +.BR iconv_open (), +the state is in the initial state. +Using +.BR iconv (3) +modifies the descriptor's conversion state. +To bring the state back to the initial state, use +.BR iconv (3) +with NULL as +.I inbuf +argument. +.SH RETURN VALUE +On success, +.BR iconv_open () +returns a freshly allocated conversion +descriptor. +On failure, it returns +.I (iconv_t)\ \-1 +and sets +.I errno +to indicate the error. +.SH ERRORS +The following error can occur, among others: +.TP +.B EINVAL +The conversion from +.I fromcode +to +.I tocode +is not supported by the +implementation. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iconv_open () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001, SUSv2. +.SH SEE ALSO +.BR iconv (1), +.BR iconv (3), +.BR iconv_close (3) diff --git a/man/man3/if_freenameindex.3 b/man/man3/if_freenameindex.3 new file mode 100644 index 0000000..d8aac84 --- /dev/null +++ b/man/man3/if_freenameindex.3 @@ -0,0 +1 @@ +.so man3/if_nameindex.3 diff --git a/man/man3/if_indextoname.3 b/man/man3/if_indextoname.3 new file mode 100644 index 0000000..4379659 --- /dev/null +++ b/man/man3/if_indextoname.3 @@ -0,0 +1 @@ +.so man3/if_nametoindex.3 diff --git a/man/man3/if_nameindex.3 b/man/man3/if_nameindex.3 new file mode 100644 index 0000000..42b325b --- /dev/null +++ b/man/man3/if_nameindex.3 @@ -0,0 +1,154 @@ +'\" t +.\" Copyright (c) 2012 YOSHIFUJI Hideaki +.\" and Copyright (c) 2012 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH if_nameindex 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +if_nameindex, if_freenameindex \- get network interface names and indexes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "struct if_nameindex *if_nameindex(" void ); +.BI "void if_freenameindex(struct if_nameindex *" "ptr" ); +.fi +.SH DESCRIPTION +The +.BR if_nameindex () +function returns an array of +.I if_nameindex +structures, each containing information +about one of the network interfaces on the local system. +The +.I if_nameindex +structure contains at least the following entries: +.P +.in +4n +.EX +unsigned int if_index; /* Index of interface (1, 2, ...) */ +char *if_name; /* Null\-terminated name ("eth0", etc.) */ +.EE +.in +.P +The +.I if_index +field contains the interface index. +The +.I if_name +field points to the null-terminated interface name. +The end of the array is indicated by entry with +.I if_index +set to zero and +.I if_name +set to NULL. +.P +The data structure returned by +.BR if_nameindex () +is dynamically allocated and should be freed using +.BR if_freenameindex () +when no longer needed. +.SH RETURN VALUE +On success, +.BR if_nameindex () +returns pointer to the array; +on error, NULL is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.BR if_nameindex () +may fail and set +.I errno +if: +.TP +.B ENOBUFS +Insufficient resources available. +.P +.BR if_nameindex () +may also fail for any of the errors specified for +.BR socket (2), +.BR bind (2), +.BR ioctl (2), +.BR getsockname (2), +.BR recvmsg (2), +.BR sendto (2), +or +.BR malloc (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR if_nameindex (), +.BR if_freenameindex () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008, RFC\ 3493. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +BSDi. +.P +Before glibc 2.3.4, +the implementation supported only interfaces with IPv4 addresses. +Support of interfaces that don't have IPv4 addresses is available only +on kernels that support netlink. +.SH EXAMPLES +The program below demonstrates the use of the functions described +on this page. +An example of the output this program might produce is the following: +.P +.in +4n +.EX +$ \fB./a.out\fI +1: lo +2: wlan0 +3: em1 +.EE +.in +.SS Program source +.\" SRC BEGIN (if_nameindex.c) +.EX +#include +#include +#include +#include +\& +int +main(void) +{ + struct if_nameindex *if_ni, *i; +\& + if_ni = if_nameindex(); + if (if_ni == NULL) { + perror("if_nameindex"); + exit(EXIT_FAILURE); + } +\& + for (i = if_ni; !(i\->if_index == 0 && i\->if_name == NULL); i++) + printf("%u: %s\en", i\->if_index, i\->if_name); +\& + if_freenameindex(if_ni); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getsockopt (2), +.BR setsockopt (2), +.BR getifaddrs (3), +.BR if_indextoname (3), +.BR if_nametoindex (3), +.BR ifconfig (8) diff --git a/man/man3/if_nametoindex.3 b/man/man3/if_nametoindex.3 new file mode 100644 index 0000000..1a1272a --- /dev/null +++ b/man/man3/if_nametoindex.3 @@ -0,0 +1,99 @@ +'\" t +.\" Copyright (c) 2012 YOSHIFUJI Hideaki +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH if_nametoindex 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +if_nametoindex, if_indextoname \- mappings between network interface +names and indexes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "unsigned int if_nametoindex(const char *" "ifname" ); +.BI "char *if_indextoname(unsigned int ifindex, char *" ifname ); +.fi +.SH DESCRIPTION +The +.BR if_nametoindex () +function returns the index of the network interface +corresponding to the name +.IR ifname . +.P +The +.BR if_indextoname () +function returns the name of the network interface +corresponding to the interface index +.IR ifindex . +The name is placed in the buffer pointed to by +.IR ifname . +The buffer must allow for the storage of at least +.B IF_NAMESIZE +bytes. +.SH RETURN VALUE +On success, +.BR if_nametoindex () +returns the index number of the network interface; +on error, 0 is returned and +.I errno +is set to indicate the error. +.P +On success, +.BR if_indextoname () +returns +.IR ifname ; +on error, NULL is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.BR if_nametoindex () +may fail and set +.I errno +if: +.TP +.B ENODEV +No interface found with given name. +.P +.BR if_indextoname () +may fail and set +.I errno +if: +.TP +.B ENXIO +No interface found for the index. +.P +.BR if_nametoindex () +and +.BR if_indextoname () +may also fail for any of the errors specified for +.BR socket (2) +or +.BR ioctl (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR if_nametoindex (), +.BR if_indextoname () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008, RFC\ 3493. +.SH HISTORY +POSIX.1-2001. +BSDi. +.SH SEE ALSO +.BR getifaddrs (3), +.BR if_nameindex (3), +.BR ifconfig (8) diff --git a/man/man3/ilogb.3 b/man/man3/ilogb.3 new file mode 100644 index 0000000..07ce896 --- /dev/null +++ b/man/man3/ilogb.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright 2004 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Inspired by a page by Walter Harms created 2002-08-10 +.\" +.TH ilogb 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ilogb, ilogbf, ilogbl \- get integer exponent of a floating-point value +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int ilogb(double " x ); +.BI "int ilogbf(float " x ); +.BI "int ilogbl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ilogb (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR ilogbf (), +.BR ilogbl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the exponent part of their argument +as a signed integer. +When no error occurs, these functions +are equivalent to the corresponding +.BR logb (3) +functions, cast to +.IR int . +.SH RETURN VALUE +On success, these functions return the exponent of +.IR x , +as a signed integer. +.P +If +.I x +is zero, then a domain error occurs, and the functions return +.\" the POSIX.1 spec for logb() says logb() gives pole error for this +.\" case, but for ilogb() it says domain error. +.BR FP_ILOGB0 . +.\" glibc: The numeric value is either `INT_MIN' or `-INT_MAX'. +.P +If +.I x +is a NaN, then a domain error occurs, and the functions return +.BR FP_ILOGBNAN . +.\" glibc: The numeric value is either `INT_MIN' or `INT_MAX'. +.\" On i386, FP_ILOGB0 and FP_ILOGBNAN have the same value. +.P +If +.I x +is negative infinity or positive infinity, then +a domain error occurs, and the functions return +.BR INT_MAX . +.\" +.\" POSIX.1-2001 also says: +.\" If the correct value is greater than {INT_MAX}, {INT_MAX} +.\" shall be returned and a domain error shall occur. +.\" +.\" If the correct value is less than {INT_MIN}, {INT_MIN} +.\" shall be returned and a domain error shall occur. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is 0 or a NaN +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised, and +.I errno +is set to +.B EDOM +(but see BUGS). +.TP +Domain error: \fIx\fP is an infinity +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised, and +.I errno +is set to +.B EDOM +(but see BUGS). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ilogb (), +.BR ilogbf (), +.BR ilogbl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH BUGS +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6794 +Before glibc 2.16, the following bugs existed in the +glibc implementation of these functions: +.IP \[bu] 3 +The domain error case where +.I x +is 0 or a NaN did not cause +.I errno +to be set or (on some architectures) raise a floating-point exception. +.IP \[bu] +The domain error case where +.I x +is an infinity did not cause +.I errno +to be set or raise a floating-point exception. +.SH SEE ALSO +.BR log (3), +.BR logb (3), +.BR significand (3) diff --git a/man/man3/ilogbf.3 b/man/man3/ilogbf.3 new file mode 100644 index 0000000..213d00a --- /dev/null +++ b/man/man3/ilogbf.3 @@ -0,0 +1 @@ +.so man3/ilogb.3 diff --git a/man/man3/ilogbl.3 b/man/man3/ilogbl.3 new file mode 100644 index 0000000..213d00a --- /dev/null +++ b/man/man3/ilogbl.3 @@ -0,0 +1 @@ +.so man3/ilogb.3 diff --git a/man/man3/imaxabs.3 b/man/man3/imaxabs.3 new file mode 100644 index 0000000..97db8d2 --- /dev/null +++ b/man/man3/imaxabs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man/man3/imaxdiv.3 b/man/man3/imaxdiv.3 new file mode 100644 index 0000000..934824e --- /dev/null +++ b/man/man3/imaxdiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man/man3/index.3 b/man/man3/index.3 new file mode 100644 index 0000000..77f2b5a --- /dev/null +++ b/man/man3/index.3 @@ -0,0 +1,44 @@ +.\" Copyright 2022 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH index 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +index, rindex \- locate character in string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] char *index(const char *" s ", int " c ); +.BI "[[deprecated]] char *rindex(const char *" s ", int " c ); +.fi +.SH DESCRIPTION +.BR index () +is identical to +.BR strchr (3). +.P +.BR rindex () +is identical to +.BR strrchr (3). +.P +Use +.BR strchr (3) +and +.BR strrchr (3) +instead of these functions. +.SH STANDARDS +None. +.SH HISTORY +4.3BSD; marked as LEGACY in POSIX.1-2001. +Removed in POSIX.1-2008, +recommending +.BR strchr (3) +and +.BR strrchr (3) +instead. +.SH SEE ALSO +.BR strchr (3), +.BR strrchr (3) diff --git a/man/man3/inet.3 b/man/man3/inet.3 new file mode 100644 index 0000000..04cfdb7 --- /dev/null +++ b/man/man3/inet.3 @@ -0,0 +1,336 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" libc.info (from glibc distribution) +.\" Modified Sat Jul 24 19:12:00 1993 by Rik Faith +.\" Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt +.\" Changed network into host byte order (for inet_network), +.\" Andreas Jaeger , 980130. +.\" 2008-06-19, mtk +.\" Describe the various address forms supported by inet_aton(). +.\" Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr(). +.\" Add discussion of Classful Addressing, noting that it is obsolete. +.\" Added an EXAMPLE program. +.\" +.TH inet 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, +inet_netof \- Internet address manipulation routines +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.BI "int inet_aton(const char *" cp ", struct in_addr *" inp ); +.P +.BI "in_addr_t inet_addr(const char *" cp ); +.BI "in_addr_t inet_network(const char *" cp ); +.P +.BI "[[deprecated]] char *inet_ntoa(struct in_addr " in ); +.P +.BI "[[deprecated]] struct in_addr inet_makeaddr(in_addr_t " net , +.BI " in_addr_t " host ); +.P +.BI "[[deprecated]] in_addr_t inet_lnaof(struct in_addr " in ); +.BI "[[deprecated]] in_addr_t inet_netof(struct in_addr " in ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR inet_aton (), +.BR inet_ntoa (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR inet_aton () +converts the Internet host address \fIcp\fP from the +IPv4 numbers-and-dots notation into binary form (in network byte order) +and stores it in the structure that \fIinp\fP points to. +.BR inet_aton () +returns nonzero if the address is valid, zero if not. +The address supplied in +.I cp +can have one of the following forms: +.TP 10 +.I a.b.c.d +Each of the four numeric parts specifies a byte of the address; +the bytes are assigned in left-to-right order to produce the binary address. +.TP +.I a.b.c +Parts +.I a +and +.I b +specify the first two bytes of the binary address. +Part +.I c +is interpreted as a 16-bit value that defines the rightmost two bytes +of the binary address. +This notation is suitable for specifying (outmoded) Class B +network addresses. +.TP +.I a.b +Part +.I a +specifies the first byte of the binary address. +Part +.I b +is interpreted as a 24-bit value that defines the rightmost three bytes +of the binary address. +This notation is suitable for specifying (outmoded) Class A +network addresses. +.TP +.I a +The value +.I a +is interpreted as a 32-bit value that is stored directly +into the binary address without any byte rearrangement. +.P +In all of the above forms, +components of the dotted address can be specified in decimal, +octal (with a leading +.IR 0 ), +or hexadecimal, with a leading +.IR 0X ). +Addresses in any of these forms are collectively termed +.IR "IPV4 numbers-and-dots notation" . +The form that uses exactly four decimal numbers is referred to as +.I IPv4 dotted-decimal notation +(or sometimes: +.IR "IPv4 dotted-quad notation" ). +.P +.BR inet_aton () +returns 1 if the supplied string was successfully interpreted, +or 0 if the string is invalid +.RB ( errno +is +.I not +set on error). +.P +The +.BR inet_addr () +function converts the Internet host address +\fIcp\fP from IPv4 numbers-and-dots notation into binary data in network +byte order. +If the input is invalid, +.B INADDR_NONE +(usually \-1) is returned. +Use of this function is problematic because \-1 is a valid address +(255.255.255.255). +Avoid its use in favor of +.BR inet_aton (), +.BR inet_pton (3), +or +.BR getaddrinfo (3), +which provide a cleaner way to indicate error return. +.P +The +.BR inet_network () +function converts +.IR cp , +a string in IPv4 numbers-and-dots notation, +into a number in host byte order suitable for use as an +Internet network address. +On success, the converted address is returned. +If the input is invalid, \-1 is returned. +.P +The +.BR inet_ntoa () +function converts the Internet host address +\fIin\fP, given in network byte order, to a string in IPv4 +dotted-decimal notation. +The string is returned in a statically +allocated buffer, which subsequent calls will overwrite. +.P +The +.BR inet_lnaof () +function returns the local network address part +of the Internet address \fIin\fP. +The returned value is in host byte order. +.P +The +.BR inet_netof () +function returns the network number part of +the Internet address \fIin\fP. +The returned value is in host byte order. +.P +The +.BR inet_makeaddr () +function is the converse of +.BR inet_netof () +and +.BR inet_lnaof (). +It returns an Internet host address in network byte order, +created by combining the network number \fInet\fP +with the local address \fIhost\fP, both in +host byte order. +.P +The structure \fIin_addr\fP as used in +.BR inet_ntoa (), +.BR inet_makeaddr (), +.BR inet_lnaof (), +and +.BR inet_netof () +is defined in +.I +as: +.P +.in +4n +.EX +typedef uint32_t in_addr_t; +\& +struct in_addr { + in_addr_t s_addr; +}; +.EE +.in +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR inet_aton (), +.BR inet_addr (), +.BR inet_network (), +.BR inet_ntoa () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR inet_makeaddr (), +.BR inet_lnaof (), +.BR inet_netof () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR inet_addr () +.TQ +.BR inet_ntoa () +POSIX.1-2008. +.TP +.BR inet_aton () +None. +.SH STANDARDS +.TP +.BR inet_addr () +.TQ +.BR inet_ntoa () +POSIX.1-2001, 4.3BSD. +.P +.BR inet_lnaof (), +.BR inet_netof (), +and +.BR inet_makeaddr () +are legacy functions that assume they are dealing with +.IR "classful network addresses" . +Classful networking divides IPv4 network addresses into host and network +components at byte boundaries, as follows: +.TP 10 +Class A +This address type is indicated by the value 0 in the +most significant bit of the (network byte ordered) address. +The network address is contained in the most significant byte, +and the host address occupies the remaining three bytes. +.TP +Class B +This address type is indicated by the binary value 10 in the +most significant two bits of the address. +The network address is contained in the two most significant bytes, +and the host address occupies the remaining two bytes. +.TP +Class C +This address type is indicated by the binary value 110 in the +most significant three bits of the address. +The network address is contained in the three most significant bytes, +and the host address occupies the remaining byte. +.P +Classful network addresses are now obsolete, +having been superseded by Classless Inter-Domain Routing (CIDR), +which divides addresses into network and host components at +arbitrary bit (rather than byte) boundaries. +.SH NOTES +On x86 architectures, the host byte order is Least Significant Byte +first (little endian), whereas the network byte order, as used on the +Internet, is Most Significant Byte first (big endian). +.SH EXAMPLES +An example of the use of +.BR inet_aton () +and +.BR inet_ntoa () +is shown below. +Here are some example runs: +.P +.in +4n +.EX +.RB "$" " ./a.out 226.000.000.037" " # Last byte is in octal" +226.0.0.31 +.RB "$" " ./a.out 0x7f.1 " " # First byte is in hex" +127.0.0.1 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (inet.c) +.EX +#define _DEFAULT_SOURCE +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + struct in_addr addr; +\& + if (argc != 2) { + fprintf(stderr, "%s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (inet_aton(argv[1], &addr) == 0) { + fprintf(stderr, "Invalid address\en"); + exit(EXIT_FAILURE); + } +\& + printf("%s\en", inet_ntoa(addr)); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR byteorder (3), +.BR getaddrinfo (3), +.BR gethostbyname (3), +.BR getnameinfo (3), +.BR getnetent (3), +.BR inet_net_pton (3), +.BR inet_ntop (3), +.BR inet_pton (3), +.BR hosts (5), +.BR networks (5) diff --git a/man/man3/inet_addr.3 b/man/man3/inet_addr.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_addr.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_aton.3 b/man/man3/inet_aton.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_aton.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_lnaof.3 b/man/man3/inet_lnaof.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_lnaof.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_makeaddr.3 b/man/man3/inet_makeaddr.3 new file mode 100644 index 0000000..4a9e0fd --- /dev/null +++ b/man/man3/inet_makeaddr.3 @@ -0,0 +1 @@ +.so man3/inet_addr.3 diff --git a/man/man3/inet_net_ntop.3 b/man/man3/inet_net_ntop.3 new file mode 100644 index 0000000..10b8d44 --- /dev/null +++ b/man/man3/inet_net_ntop.3 @@ -0,0 +1 @@ +.so man3/inet_net_pton.3 diff --git a/man/man3/inet_net_pton.3 b/man/man3/inet_net_pton.3 new file mode 100644 index 0000000..09bff61 --- /dev/null +++ b/man/man3/inet_net_pton.3 @@ -0,0 +1,369 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH inet_net_pton 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inet_net_pton, inet_net_ntop \- Internet network number conversion +.SH LIBRARY +Resolver library +.RI ( libresolv ", " \-lresolv ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int inet_net_pton(int " af ", const char *" pres , +.BI " void " netp [. nsize "], size_t " nsize ); +.BI "char *inet_net_ntop(int " af , +.BI " const void " netp [(. bits " - CHAR_BIT + 1) / CHAR_BIT]," +.BI " int " bits , +.BI " char " pres [. psize "], size_t " psize ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR inet_net_pton (), +.BR inet_net_ntop (): +.nf + Since glibc 2.20: + _DEFAULT_SOURCE + Before glibc 2.20: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions convert network numbers between +presentation (i.e., printable) format and network (i.e., binary) format. +.P +For both functions, +.I af +specifies the address family for the conversion; +the only supported value is +.BR AF_INET . +.SS inet_net_pton() +The +.BR inet_net_pton () +function converts +.IR pres , +a null-terminated string containing an Internet network number in +presentation format to network format. +The result of the conversion, which is in network byte order, +is placed in the buffer pointed to by +.IR netp . +(The +.I netp +argument typically points to an +.I in_addr +structure.) +The +.I nsize +argument specifies the number of bytes available in +.IR netp . +.P +On success, +.BR inet_net_pton () +returns the number of bits in the network number field +of the result placed in +.IR netp . +For a discussion of the input presentation format and the return value, +see NOTES. +.P +.IR Note : +the buffer pointed to by +.I netp +should be zeroed out before calling +.BR inet_net_pton (), +since the call writes only as many bytes as are required +for the network number (or as are explicitly specified by +.IR pres ), +which may be less than the number of bytes in a complete network address. +.SS inet_net_ntop() +The +.BR inet_net_ntop () +function converts the network number in the buffer pointed to by +.I netp +to presentation format; +.I *netp +is interpreted as a value in network byte order. +The +.I bits +argument specifies the number of bits in the network number in +.IR *netp . +.P +The null-terminated presentation-format string +is placed in the buffer pointed to by +.IR pres . +The +.I psize +argument specifies the number of bytes available in +.IR pres . +The presentation string is in CIDR format: +a dotted-decimal number representing the network address, +followed by a slash, and the size of the network number in bits. +.SH RETURN VALUE +On success, +.BR inet_net_pton () +returns the number of bits in the network number. +On error, it returns \-1, and +.I errno +is set to indicate the error. +.P +On success, +.BR inet_net_ntop () +returns +.IR pres . +On error, it returns NULL, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAFNOSUPPORT +.I af +specified a value other than +.BR AF_INET . +.TP +.B EMSGSIZE +The size of the output buffer was insufficient. +.TP +.B ENOENT +.RB ( inet_net_pton ()) +.I pres +was not in correct presentation format. +.SH STANDARDS +None. +.SH NOTES +.SS Input presentation format for inet_net_pton() +The network number may be specified either +as a hexadecimal value +or in dotted-decimal notation. +.P +Hexadecimal values are indicated by an initial "0x" or "0X". +The hexadecimal digits populate the nibbles (half octets) of the +network number from left to right in network byte order. +.\" If the hexadecimal string is short, the remaining nibbles are zeroed. +.P +In dotted-decimal notation, up to four octets are specified, +as decimal numbers separated by dots. +Thus, any of the following forms are accepted: +.P +.in +4n +.EX +a.b.c.d +a.b.c +a.b +a +.EE +.in +.P +Each part is a number in the range 0 to 255 that +populates one byte of the resulting network number, +going from left to right, in network-byte (big endian) order. +Where a part is omitted, the resulting byte in the network number is zero. +.\" Reading other man pages, some other implementations treat +.\" 'c' in a.b.c as a 16-bit number that populates right-most two bytes +.\" 'b' in a.b as a 24-bit number that populates right-most three bytes +.P +For either hexadecimal or dotted-decimal format, +the network number can optionally be followed by a slash +and a number in the range 0 to 32, +which specifies the size of the network number in bits. +.SS Return value of inet_net_pton() +The return value of +.BR inet_net_pton () +is the number of bits in the network number field. +If the input presentation string terminates with a slash and +an explicit size value, then that size becomes the return value of +.BR inet_net_pton (). +Otherwise, the return value, +.IR bits , +is inferred as follows: +.IP \[bu] 3 +If the most significant byte of the network number is +greater than or equal to 240, +then +.I bits +is 32. +.IP \[bu] +Otherwise, +if the most significant byte of the network number is +greater than or equal to 224, +then +.I bits +is 4. +.IP \[bu] +Otherwise, +if the most significant byte of the network number is +greater than or equal to 192, +then +.I bits +is 24. +.IP \[bu] +Otherwise, +if the most significant byte of the network number is +greater than or equal to 128, +then +.I bits +is 16. +.IP \[bu] +Otherwise, +.I bits +is 8. +.P +If the resulting +.I bits +value from the above steps is greater than or equal to 8, +but the number of octets specified in the network number exceed +.IR "bits/8" , +then +.I bits +is set to 8 times the number of octets actually specified. +.SH EXAMPLES +The program below demonstrates the use of +.BR inet_net_pton () +and +.BR inet_net_ntop (). +It uses +.BR inet_net_pton () +to convert the presentation format network address provided in +its first command-line argument to binary form, displays the return value from +.BR inet_net_pton (). +It then uses +.BR inet_net_ntop () +to convert the binary form back to presentation format, +and displays the resulting string. +.P +In order to demonstrate that +.BR inet_net_pton () +may not write to all bytes of its +.I netp +argument, the program allows an optional second command-line argument, +a number used to initialize the buffer before +.BR inet_net_pton () +is called. +As its final line of output, +the program displays all of the bytes of the buffer returned by +.BR inet_net_pton () +allowing the user to see which bytes have not been touched by +.BR inet_net_pton (). +.P +An example run, showing that +.BR inet_net_pton () +infers the number of bits in the network number: +.P +.in +4n +.EX +$ \fB./a.out 193.168\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.0/24 +Raw address: c1a80000 +.EE +.in +.P +Demonstrate that +.BR inet_net_pton () +does not zero out unused bytes in its result buffer: +.P +.in +4n +.EX +$ \fB./a.out 193.168 0xffffffff\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.0/24 +Raw address: c1a800ff +.EE +.in +.P +Demonstrate that +.BR inet_net_pton () +will widen the inferred size of the network number, +if the supplied number of bytes in the presentation +string exceeds the inferred value: +.P +.in +4n +.EX +$ \fB./a.out 193.168.1.128\fP +inet_net_pton() returned: 32 +inet_net_ntop() yielded: 193.168.1.128/32 +Raw address: c1a80180 +.EE +.in +.P +Explicitly specifying the size of the network number overrides any +inference about its size +(but any extra bytes that are explicitly specified will still be used by +.BR inet_net_pton (): +to populate the result buffer): +.P +.in +4n +.EX +$ \fB./a.out 193.168.1.128/24\fP +inet_net_pton() returned: 24 +inet_net_ntop() yielded: 193.168.1/24 +Raw address: c1a80180 +.EE +.in +.SS Program source +.\" SRC BEGIN (inet_net_pton.c) +.EX +/* Link with "\-lresolv" */ +\& +#include +#include +#include +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + char buf[100]; + struct in_addr addr; + int bits; +\& + if (argc < 2) { + fprintf(stderr, + "Usage: %s presentation\-form [addr\-init\-value]\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + /* If argv[2] is supplied (a numeric value), use it to initialize + the output buffer given to inet_net_pton(), so that we can see + that inet_net_pton() initializes only those bytes needed for + the network number. If argv[2] is not supplied, then initialize + the buffer to zero (as is recommended practice). */ +\& + addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0; +\& + /* Convert presentation network number in argv[1] to binary. */ +\& + bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr)); + if (bits == \-1) + errExit("inet_net_ntop"); +\& + printf("inet_net_pton() returned: %d\en", bits); +\& + /* Convert binary format back to presentation, using \[aq]bits\[aq] + returned by inet_net_pton(). */ +\& + if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL) + errExit("inet_net_ntop"); +\& + printf("inet_net_ntop() yielded: %s\en", buf); +\& + /* Display \[aq]addr\[aq] in raw form (in network byte order), so we can + see bytes not displayed by inet_net_ntop(); some of those bytes + may not have been touched by inet_net_ntop(), and so will still + have any initial value that was specified in argv[2]. */ +\& + printf("Raw address: %x\en", htonl(addr.s_addr)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR inet (3), +.BR networks (5) diff --git a/man/man3/inet_netof.3 b/man/man3/inet_netof.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_netof.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_network.3 b/man/man3/inet_network.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_network.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_ntoa.3 b/man/man3/inet_ntoa.3 new file mode 100644 index 0000000..0eba30e --- /dev/null +++ b/man/man3/inet_ntoa.3 @@ -0,0 +1 @@ +.so man3/inet.3 diff --git a/man/man3/inet_ntop.3 b/man/man3/inet_ntop.3 new file mode 100644 index 0000000..6f2ce5d --- /dev/null +++ b/man/man3/inet_ntop.3 @@ -0,0 +1,122 @@ +'\" t +.\" Copyright 2000 Sam Varshavchik +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References: RFC 2553 +.TH inet_ntop 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inet_ntop \- convert IPv4 and IPv6 addresses from binary to text form +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "const char *inet_ntop(int " af ", const void *restrict " src , +.BI " char " dst "[restrict ." size "], socklen_t " size ); +.fi +.SH DESCRIPTION +This function converts the network address structure +.I src +in the +.I af +address family into a character string. +The resulting string is copied to the buffer pointed to by +.IR dst , +which must be a non-null pointer. +The caller specifies the number of bytes available in this buffer in +the argument +.IR size . +.P +.BR inet_ntop () +extends the +.BR inet_ntoa (3) +function to support multiple address families, +.BR inet_ntoa (3) +is now considered to be deprecated in favor of +.BR inet_ntop (). +The following address families are currently supported: +.TP +.B AF_INET +.I src +points to a +.I struct in_addr +(in network byte order) +which is converted to an IPv4 network address in +the dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP". +The buffer +.I dst +must be at least +.B INET_ADDRSTRLEN +bytes long. +.TP +.B AF_INET6 +.I src +points to a +.I struct in6_addr +(in network byte order) +which is converted to a representation of this address in the +most appropriate IPv6 network address format for this address. +The buffer +.I dst +must be at least +.B INET6_ADDRSTRLEN +bytes long. +.SH RETURN VALUE +On success, +.BR inet_ntop () +returns a non-null pointer to +.IR dst . +NULL is returned if there was an error, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAFNOSUPPORT +.I af +was not a valid address family. +.TP +.B ENOSPC +The converted address string would exceed the size given by +.IR size . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR inet_ntop () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Note that RFC\ 2553 defines a prototype where the last argument +.I size +is of type +.IR size_t . +Many systems follow RFC\ 2553. +glibc 2.0 and 2.1 have +.IR size_t , +but 2.2 and later have +.IR socklen_t . +.\" 2.1.3: size_t, 2.1.91: socklen_t +.SH BUGS +.B AF_INET6 +converts IPv4-mapped IPv6 addresses into an IPv6 format. +.SH EXAMPLES +See +.BR inet_pton (3). +.SH SEE ALSO +.BR getnameinfo (3), +.BR inet (3), +.BR inet_pton (3) diff --git a/man/man3/inet_pton.3 b/man/man3/inet_pton.3 new file mode 100644 index 0000000..89b10c3 --- /dev/null +++ b/man/man3/inet_pton.3 @@ -0,0 +1,223 @@ +'\" t +.\" Copyright 2000 Sam Varshavchik +.\" and Copyright (c) 2008 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References: RFC 2553 +.TH inet_pton 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inet_pton \- convert IPv4 and IPv6 addresses from text to binary form +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int inet_pton(int " af ", const char *restrict " src \ +", void *restrict " dst ); +.fi +.SH DESCRIPTION +This function converts the character string +.I src +into a network address structure in the +.I af +address family, then +copies +the network address structure to +.IR dst . +The +.I af +argument must be either +.B AF_INET +or +.BR AF_INET6 . +.I dst +is written in network byte order. +.P +The following address families are currently supported: +.TP +.B AF_INET +.I src +points to a character string containing an IPv4 network address in +dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP", where +.I ddd +is a decimal number of up to three digits in the range 0 to 255. +The address is converted to a +.I struct in_addr +and copied to +.IR dst , +which must be +.I sizeof(struct in_addr) +(4) bytes (32 bits) long. +.TP +.B AF_INET6 +.I src +points to a character string containing an IPv6 network address. +The address is converted to a +.I struct in6_addr +and copied to +.IR dst , +which must be +.I sizeof(struct in6_addr) +(16) bytes (128 bits) long. +The allowed formats for IPv6 addresses follow these rules: +.RS +.IP \[bu] 3 +The preferred format is +.IR x:x:x:x:x:x:x:x . +This form consists of eight hexadecimal numbers, +each of which expresses a 16-bit value (i.e., each +.I x +can be up to 4 hex digits). +.IP \[bu] +A series of contiguous zero values in the preferred format +can be abbreviated to +.IR :: . +Only one instance of +.I :: +can occur in an address. +For example, the loopback address +.I 0:0:0:0:0:0:0:1 +can be abbreviated as +.IR ::1 . +The wildcard address, consisting of all zeros, can be written as +.IR :: . +.IP \[bu] +An alternate format is useful for expressing IPv4-mapped IPv6 addresses. +This form is written as +.IR x:x:x:x:x:x:d.d.d.d , +where the six leading +.IR x s +are hexadecimal values that define the six most-significant +16-bit pieces of the address (i.e., 96 bits), and the +.IR d s +express a value in dotted-decimal notation that +defines the least significant 32 bits of the address. +An example of such an address is +.IR ::FFFF:204.152.189.116 . +.RE +.IP +See RFC 2373 for further details on the representation of IPv6 addresses. +.SH RETURN VALUE +.BR inet_pton () +returns 1 on success (network address was successfully converted). +0 is returned if +.I src +does not contain a character string representing a valid network +address in the specified address family. +If +.I af +does not contain a valid address family, \-1 is returned and +.I errno +is set to +.BR EAFNOSUPPORT . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR inet_pton () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +Unlike +.BR inet_aton (3) +and +.BR inet_addr (3), +.BR inet_pton () +supports IPv6 addresses. +On the other hand, +.BR inet_pton () +accepts only IPv4 addresses in dotted-decimal notation, whereas +.BR inet_aton (3) +and +.BR inet_addr (3) +allow the more general numbers-and-dots notation (hexadecimal +and octal number formats, and formats that don't require all +four bytes to be explicitly written). +For an interface that handles both IPv6 addresses, and IPv4 +addresses in numbers-and-dots notation, see +.BR getaddrinfo (3). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +.B AF_INET6 +does not recognize IPv4 addresses. +An explicit IPv4-mapped IPv6 address must be supplied in +.I src +instead. +.SH EXAMPLES +The program below demonstrates the use of +.BR inet_pton () +and +.BR inet_ntop (3). +Here are some example runs: +.P +.in +4n +.EX +.RB "$" " ./a.out i6 0:0:0:0:0:0:0:0" +:: +.RB "$" " ./a.out i6 1:0:0:0:0:0:0:8" +1::8 +.RB "$" " ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116" +::ffff:204.152.189.116 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (inet_pton.c) +.EX +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + unsigned char buf[sizeof(struct in6_addr)]; + int domain, s; + char str[INET6_ADDRSTRLEN]; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s {i4|i6|} string\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + domain = (strcmp(argv[1], "i4") == 0) ? AF_INET : + (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]); +\& + s = inet_pton(domain, argv[2], buf); + if (s <= 0) { + if (s == 0) + fprintf(stderr, "Not in presentation format"); + else + perror("inet_pton"); + exit(EXIT_FAILURE); + } +\& + if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) { + perror("inet_ntop"); + exit(EXIT_FAILURE); + } +\& + printf("%s\en", str); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getaddrinfo (3), +.BR inet (3), +.BR inet_ntop (3) diff --git a/man/man3/initgroups.3 b/man/man3/initgroups.3 new file mode 100644 index 0000000..ea68719 --- /dev/null +++ b/man/man3/initgroups.3 @@ -0,0 +1,98 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 2004-10-10 by aeb +.\" +.TH initgroups 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +initgroups \- initialize the supplementary group access list +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int initgroups(const char *" user ", gid_t " group ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR initgroups (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR initgroups () +function initializes the group access list by +reading the group database +.I /etc/group +and using all groups of +which +.I user +is a member. +The additional group +.I group +is +also added to the list. +.P +The +.I user +argument must be non-NULL. +.SH RETURN VALUE +The +.BR initgroups () +function returns 0 on success. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to allocate group information structure. +.TP +.B EPERM +The calling process has insufficient privilege. +See the underlying system call +.BR setgroups (2). +.SH FILES +.TP +.I /etc/group +group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR initgroups () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr4, 4.3BSD. +.SH SEE ALSO +.BR getgroups (2), +.BR setgroups (2), +.BR credentials (7) diff --git a/man/man3/initstate.3 b/man/man3/initstate.3 new file mode 100644 index 0000000..6e34104 --- /dev/null +++ b/man/man3/initstate.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man/man3/initstate_r.3 b/man/man3/initstate_r.3 new file mode 100644 index 0000000..b01937f --- /dev/null +++ b/man/man3/initstate_r.3 @@ -0,0 +1 @@ +.so man3/random_r.3 diff --git a/man/man3/innetgr.3 b/man/man3/innetgr.3 new file mode 100644 index 0000000..34268f9 --- /dev/null +++ b/man/man3/innetgr.3 @@ -0,0 +1 @@ +.so man3/setnetgrent.3 diff --git a/man/man3/insque.3 b/man/man3/insque.3 new file mode 100644 index 0000000..905d803 --- /dev/null +++ b/man/man3/insque.3 @@ -0,0 +1,248 @@ +'\" t +.\" peter memishian -- meem@gnu.ai.mit.edu +.\" $Id: insque.3,v 1.2 1996/10/30 21:03:39 meem Exp meem $ +.\" and Copyright (c) 2010, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code (5.4.7) +.\" Solaris 2.x, OSF/1, and HP-UX manpages +.\" Curry's "UNIX Systems Programming for SVR4" (O'Reilly & Associates 1996) +.\" +.\" Changed to POSIX, 2003-08-11, aeb+wh +.\" mtk, 2010-09-09: Noted glibc 2.4 bug, added info on circular +.\" lists, added example program +.\" +.TH insque 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +insque, remque \- insert/remove an item from a queue +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void insque(void *" elem ", void *" prev ); +.BI "void remque(void *" elem ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR insque (), +.BR remque (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR insque () +and +.BR remque () +functions manipulate doubly linked lists. +Each element in the list is a structure of +which the first two elements are a forward and a +backward pointer. +The linked list may be linear (i.e., NULL forward pointer at +the end of the list and NULL backward pointer at the start of the list) +or circular. +.P +The +.BR insque () +function inserts the element pointed to by \fIelem\fP +immediately after the element pointed to by \fIprev\fP. +.P +If the list is linear, then the call +.I "insque(elem, NULL)" +can be used to insert the initial list element, +and the call sets the forward and backward pointers of +.I elem +to NULL. +.P +If the list is circular, +the caller should ensure that the forward and backward pointers of the +first element are initialized to point to that element, +and the +.I prev +argument of the +.BR insque () +call should also point to the element. +.P +The +.BR remque () +function removes the element pointed to by \fIelem\fP from the +doubly linked list. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR insque (), +.BR remque () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On ancient systems, +.\" e.g., SunOS, Linux libc4 and libc5 +the arguments of these functions were of type \fIstruct qelem *\fP, +defined as: +.P +.in +4n +.EX +struct qelem { + struct qelem *q_forw; + struct qelem *q_back; + char q_data[1]; +}; +.EE +.in +.P +This is still what you will get if +.B _GNU_SOURCE +is defined before +including \fI\fP. +.P +The location of the prototypes for these functions differs among several +versions of UNIX. +The above is the POSIX version. +Some systems place them in \fI\fP. +.\" Linux libc4 and libc 5 placed them +.\" in \fI\fP. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +In glibc 2.4 and earlier, it was not possible to specify +.I prev +as NULL. +Consequently, to build a linear list, the caller had to build a list +using an initial call that contained the first two elements of the list, +with the forward and backward pointers in each element suitably initialized. +.SH EXAMPLES +The program below demonstrates the use of +.BR insque (). +Here is an example run of the program: +.P +.in +4n +.EX +.RB "$ " "./a.out \-c a b c" +Traversing completed list: + a + b + c +That was a circular list +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (insque.c) +.EX +#include +#include +#include +#include +\& +struct element { + struct element *forward; + struct element *backward; + char *name; +}; +\& +static struct element * +new_element(void) +{ + struct element *e; +\& + e = malloc(sizeof(*e)); + if (e == NULL) { + fprintf(stderr, "malloc() failed\en"); + exit(EXIT_FAILURE); + } +\& + return e; +} +\& +int +main(int argc, char *argv[]) +{ + struct element *first, *elem, *prev; + int circular, opt, errfnd; +\& + /* The "\-c" command\-line option can be used to specify that the + list is circular. */ +\& + errfnd = 0; + circular = 0; + while ((opt = getopt(argc, argv, "c")) != \-1) { + switch (opt) { + case \[aq]c\[aq]: + circular = 1; + break; + default: + errfnd = 1; + break; + } + } +\& + if (errfnd || optind >= argc) { + fprintf(stderr, "Usage: %s [\-c] string...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Create first element and place it in the linked list. */ +\& + elem = new_element(); + first = elem; +\& + elem\->name = argv[optind]; +\& + if (circular) { + elem\->forward = elem; + elem\->backward = elem; + insque(elem, elem); + } else { + insque(elem, NULL); + } +\& + /* Add remaining command\-line arguments as list elements. */ +\& + while (++optind < argc) { + prev = elem; +\& + elem = new_element(); + elem\->name = argv[optind]; + insque(elem, prev); + } +\& + /* Traverse the list from the start, printing element names. */ +\& + printf("Traversing completed list:\en"); + elem = first; + do { + printf(" %s\en", elem\->name); + elem = elem\->forward; + } while (elem != NULL && elem != first); +\& + if (elem == first) + printf("That was a circular list\en"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR queue (7) diff --git a/man/man3/intro.3 b/man/man3/intro.3 new file mode 100644 index 0000000..fbf9f65 --- /dev/null +++ b/man/man3/intro.3 @@ -0,0 +1,135 @@ +.\" Copyright (C) 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-10-23 mtk, Nearly a complete rewrite of the earlier page. +.TH intro 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intro \- introduction to library functions +.SH DESCRIPTION +Section 3 of the manual describes all library functions +excluding the library functions +(system call wrappers) +described in Section 2, +which implement system calls. +.P +Many of the functions described in the section are part of the +Standard C Library +.RI ( libc ). +Some functions are part of other libraries +(e.g., +the math library, +.IR libm , +or the real-time library, +.IR librt ) +in which case the manual page will indicate +the linker option needed to link against the required library +(e.g., +.I \-lm +and +.IR \-lrt , +respectively, +for the aforementioned libraries). +.P +In some cases, +the programmer must define a feature test macro in order to obtain +the declaration of a function from the header file specified +in the man page SYNOPSIS section. +(Where required, +these +.I feature test macros +must be defined before including +.I any +header files.) +In such cases, +the required macro is described in the man page. +For further information on feature test macros, +see +.BR feature_test_macros (7). +.\" +.\" There +.\" are various function groups which can be identified by a letter which +.\" is appended to the chapter number: +.\" .IP (3C) +.\" These functions, +.\" the functions from chapter 2 and from chapter 3S are +.\" contained in the C standard library libc, +.\" which will be used by +.\" .BR cc (1) +.\" by default. +.\" .IP (3S) +.\" These functions are parts of the +.\" .BR stdio (3) +.\" library. They are contained in the standard C library libc. +.\" .IP (3M) +.\" These functions are contained in the arithmetic library libm. They are +.\" used by the +.\" .BR f77 (1) +.\" FORTRAN compiler by default, +.\" but not by the +.\" .BR cc (1) +.\" C compiler, +.\" which needs the option \fI\-lm\fP. +.\" .IP (3F) +.\" These functions are part of the FORTRAN library libF77. There are no +.\" special compiler flags needed to use these functions. +.\" .IP (3X) +.\" Various special libraries. The manual pages documenting their functions +.\" specify the library names. +.SS Subsections +Section 3 of this manual is organized into subsections +that reflect the complex structure of the standard C library +and its many implementations: +.IP \[bu] 3 +3const +.IP \[bu] +3head +.IP \[bu] +3type +.P +This difficult history frequently makes it a poor example to follow +in design, +implementation, +and presentation. +.P +Ideally, +a library for the C language +is designed such that each header file +presents the interface to a coherent software module. +It provides a small number of function declarations +and exposes only data types and constants that +are required for use of those functions. +Together, +these are termed an API or +.IR "application program interface" . +Types and constants to be shared among multiple APIs +should be placed in header files that declare no functions. +This organization permits a C library module +to be documented concisely with one header file per manual page. +Such an approach +improves the readability and accessibility of library documentation, +and thereby the usability of the software. +.SH STANDARDS +Certain terms and abbreviations are used to indicate UNIX variants +and standards to which calls in this section conform. +See +.BR standards (7). +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source +for the author(s) and copyright conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR intro (2), +.BR errno (3), +.BR capabilities (7), +.BR credentials (7), +.BR environ (7), +.BR feature_test_macros (7), +.BR libc (7), +.BR math_error (7), +.BR path_resolution (7), +.BR pthreads (7), +.BR signal (7), +.BR standards (7), +.BR system_data_types (7) diff --git a/man/man3/iruserok.3 b/man/man3/iruserok.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/iruserok.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/iruserok_af.3 b/man/man3/iruserok_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/iruserok_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/isalnum.3 b/man/man3/isalnum.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isalnum.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isalnum_l.3 b/man/man3/isalnum_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isalnum_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isalpha.3 b/man/man3/isalpha.3 new file mode 100644 index 0000000..3625685 --- /dev/null +++ b/man/man3/isalpha.3 @@ -0,0 +1,405 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:10:00 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 21 17:51:50 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Sep 2 21:52:01 1995 by Jim Van Zandt +.\" Modified Mon May 27 22:55:26 1996 by Martin Schulze (joey@linux.de) +.\" +.TH isalpha 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, +isprint, ispunct, isspace, isupper, isxdigit, +isalnum_l, isalpha_l, isascii_l, isblank_l, iscntrl_l, +isdigit_l, isgraph_l, islower_l, +isprint_l, ispunct_l, isspace_l, isupper_l, isxdigit_l +\- character classification functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int isalnum(int " c ); +.BI "int isalpha(int " c ); +.BI "int iscntrl(int " c ); +.BI "int isdigit(int " c ); +.BI "int isgraph(int " c ); +.BI "int islower(int " c ); +.BI "int isprint(int " c ); +.BI "int ispunct(int " c ); +.BI "int isspace(int " c ); +.BI "int isupper(int " c ); +.BI "int isxdigit(int " c ); +.P +.BI "int isascii(int " c ); +.BI "int isblank(int " c ); +.P +.BI "int isalnum_l(int " c ", locale_t " locale ); +.BI "int isalpha_l(int " c ", locale_t " locale ); +.BI "int isblank_l(int " c ", locale_t " locale ); +.BI "int iscntrl_l(int " c ", locale_t " locale ); +.BI "int isdigit_l(int " c ", locale_t " locale ); +.BI "int isgraph_l(int " c ", locale_t " locale ); +.BI "int islower_l(int " c ", locale_t " locale ); +.BI "int isprint_l(int " c ", locale_t " locale ); +.BI "int ispunct_l(int " c ", locale_t " locale ); +.BI "int isspace_l(int " c ", locale_t " locale ); +.BI "int isupper_l(int " c ", locale_t " locale ); +.BI "int isxdigit_l(int " c ", locale_t " locale ); +.P +.BI "int isascii_l(int " c ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.ad l +.P +.BR isascii (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.P +.BR isblank (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.P +.BR \%salnum_l (), +.BR \%salpha_l (), +.BR \%sblank_l (), +.BR \%scntrl_l (), +.BR \%sdigit_l (), +.BR \%sgraph_l (), +.BR \%slower_l (), +.BR \%sprint_l (), +.BR \%spunct_l (), +.BR \%sspace_l (), +.BR \%supper_l (), +.BR \%sxdigit_l (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.P +.BR isascii_l (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 && (_SVID_SOURCE || _BSD_SOURCE) + Before glibc 2.10: + _GNU_SOURCE +.fi +.ad +.SH DESCRIPTION +These functions check whether +.IR c , +which must have the value of an +.I unsigned char +or +.BR EOF , +falls into a certain character class according to the specified locale. +The functions without the +"_l" suffix perform the check based on the current locale. +.P +The functions with the "_l" suffix perform the check +based on the locale specified by the locale object +.IR locale . +The behavior of these functions is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.P +The list below explains the operation of the functions without +the "_l" suffix; +the functions with the "_l" suffix differ only in using the locale object +.I locale +instead of the current locale. +.TP +.BR isalnum () +checks for an alphanumeric character; it is equivalent to +.BI "(isalpha(" c ") || isdigit(" c "))" \fR. +.TP +.BR isalpha () +checks for an alphabetic character; in the standard \fB"C"\fP +locale, it is equivalent to +.BI "(isupper(" c ") || islower(" c "))" \fR. +In some locales, there may be additional characters for which +.BR isalpha () +is true\[em]letters which are neither uppercase nor lowercase. +.TP +.BR isascii () +checks whether \fIc\fP is a 7-bit +.I unsigned char +value that fits into +the ASCII character set. +.TP +.BR isblank () +checks for a blank character; that is, a space or a tab. +.TP +.BR iscntrl () +checks for a control character. +.TP +.BR isdigit () +checks for a digit (0 through 9). +.TP +.BR isgraph () +checks for any printable character except space. +.TP +.BR islower () +checks for a lowercase character. +.TP +.BR isprint () +checks for any printable character including space. +.TP +.BR ispunct () +checks for any printable character which is not a space or an +alphanumeric character. +.TP +.BR isspace () +checks for white-space characters. +In the +.B \[dq]C\[dq] +and +.B \[dq]POSIX\[dq] +locales, these are: space, form-feed +.RB ( \[aq]\ef\[aq] ), +newline +.RB ( \[aq]\en\[aq] ), +carriage return +.RB ( \[aq]\er\[aq] ), +horizontal tab +.RB ( \[aq]\et\[aq] ), +and vertical tab +.RB ( \[aq]\ev\[aq] ). +.TP +.BR isupper () +checks for an uppercase letter. +.TP +.BR isxdigit () +checks for hexadecimal digits, that is, one of +.br +.BR "0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F" . +.SH RETURN VALUE +The values returned are nonzero if the character +.I c +falls into the tested class, and zero if not. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR isalnum (), +.BR isalpha (), +.BR isascii (), +.BR isblank (), +.BR iscntrl (), +.BR isdigit (), +.BR isgraph (), +.BR islower (), +.BR isprint (), +.BR ispunct (), +.BR isspace (), +.BR isupper (), +.BR isxdigit () +T} Thread safety MT-Safe +.TE +.\" FIXME: need a thread-safety statement about the *_l functions +.SH STANDARDS +.TP +.BR isalnum () +.TQ +.BR isalpha () +.TQ +.BR iscntrl () +.TQ +.BR isdigit () +.TQ +.BR isgraph () +.TQ +.BR islower () +.TQ +.BR isprint () +.TQ +.BR ispunct () +.TQ +.BR isspace () +.TQ +.BR isupper () +.TQ +.BR isxdigit () +.TQ +.BR isblank () +C11, POSIX.1-2008. +.TP +.BR isascii () +.TQ +.BR isalnum_l () +.TQ +.BR isalpha_l () +.TQ +.BR isblank_l () +.TQ +.BR iscntrl_l () +.TQ +.BR isdigit_l () +.TQ +.BR isgraph_l () +.TQ +.BR islower_l () +.TQ +.BR isprint_l () +.TQ +.BR ispunct_l () +.TQ +.BR isspace_l () +.TQ +.BR isupper_l () +.TQ +.BR isxdigit_l () +POSIX.1-2008. +.TP +.BR isascii_l () +GNU. +.SH HISTORY +.TP +.BR isalnum () +.TQ +.BR isalpha () +.TQ +.BR iscntrl () +.TQ +.BR isdigit () +.TQ +.BR isgraph () +.TQ +.BR islower () +.TQ +.BR isprint () +.TQ +.BR ispunct () +.TQ +.BR isspace () +.TQ +.BR isupper () +.TQ +.BR isxdigit () +C89, POSIX.1-2001. +.TP +.BR isblank () +C99, POSIX.1-2001. +.TP +.BR isascii () +POSIX.1-2001 (XSI). +.IP +POSIX.1-2008 marks it as obsolete, +noting that it cannot be used portably in a localized application. +.TP +.BR isalnum_l () +.TQ +.BR isalpha_l () +.TQ +.BR isblank_l () +.TQ +.BR iscntrl_l () +.TQ +.BR isdigit_l () +.TQ +.BR isgraph_l () +.TQ +.BR islower_l () +.TQ +.BR isprint_l () +.TQ +.BR ispunct_l () +.TQ +.BR isspace_l () +.TQ +.BR isupper_l () +.TQ +.BR isxdigit_l () +glibc 2.3. +POSIX.1-2008. +.TP +.BR isascii_l () +glibc 2.3. +.SH CAVEATS +The standards require that the argument +.I c +for these functions is either +.B EOF +or a value that is representable in the type +.IR "unsigned char" ; +otherwise, +the behavior is undefined. +If the argument +.I c +is of type +.IR char , +it must be cast to +.IR "unsigned char" , +as in the following example: +.P +.in +4n +.EX +char c; +\&... +res = toupper((unsigned char) c); +.EE +.in +.P +This is necessary because +.I char +may be the equivalent of +.IR "signed char" , +in which case a byte where the top bit is set would be sign extended when +converting to +.IR int , +yielding a value that is outside the range of +.IR "unsigned char" . +.P +The details of what characters belong to which class depend on the +locale. +For example, +.BR isupper () +will not recognize an A-umlaut (\(:A) as an uppercase letter in the default +.B "C" +locale. +.SH SEE ALSO +.BR iswalnum (3), +.BR iswalpha (3), +.BR iswblank (3), +.BR iswcntrl (3), +.BR iswdigit (3), +.BR iswgraph (3), +.BR iswlower (3), +.BR iswprint (3), +.BR iswpunct (3), +.BR iswspace (3), +.BR iswupper (3), +.BR iswxdigit (3), +.BR newlocale (3), +.BR setlocale (3), +.BR toascii (3), +.BR tolower (3), +.BR toupper (3), +.BR uselocale (3), +.BR ascii (7), +.BR locale (7) diff --git a/man/man3/isalpha_l.3 b/man/man3/isalpha_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isalpha_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isascii.3 b/man/man3/isascii.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isascii.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isascii_l.3 b/man/man3/isascii_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isascii_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isatty.3 b/man/man3/isatty.3 new file mode 100644 index 0000000..99cb872 --- /dev/null +++ b/man/man3/isatty.3 @@ -0,0 +1,68 @@ +'\" t +.\" Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH isatty 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +isatty \- test whether a file descriptor refers to a terminal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int isatty(int " fd ); +.fi +.SH DESCRIPTION +The +.BR isatty () +function tests whether +.I fd +is an open file descriptor referring to a terminal. +.SH RETURN VALUE +.BR isatty () +returns 1 if +.I fd +is an open file descriptor referring to a terminal; +otherwise 0 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOTTY +.I fd +refers to a file other than a terminal. +On some older kernels, some types of files +.\" e.g., FIFOs and pipes on 2.6.32 +resulted in the error +.B EINVAL +in this case (which is a violation of POSIX, which specifies the error +.BR ENOTTY ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR isatty () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR fstat (2), +.BR ttyname (3) diff --git a/man/man3/isblank.3 b/man/man3/isblank.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isblank.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isblank_l.3 b/man/man3/isblank_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isblank_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/iscntrl.3 b/man/man3/iscntrl.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/iscntrl.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/iscntrl_l.3 b/man/man3/iscntrl_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/iscntrl_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isdigit.3 b/man/man3/isdigit.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isdigit.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isdigit_l.3 b/man/man3/isdigit_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isdigit_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isfdtype.3 b/man/man3/isfdtype.3 new file mode 100644 index 0000000..74ecf93 --- /dev/null +++ b/man/man3/isfdtype.3 @@ -0,0 +1,77 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH isfdtype 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +isfdtype \- test file type of a file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int isfdtype(int " fd ", int " fdtype ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR isfdtype (): +.nf + Since glibc 2.20: + _DEFAULT_SOURCE + Before glibc 2.20: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR isfdtype () +function tests whether the file descriptor +.I fd +refers to a file of type +.IR fdtype . +The +.I fdtype +argument specifies one of the +.B S_IF* +constants defined in +.I +and documented in +.BR stat (2) +(e.g., +.BR S_IFREG ). +.SH RETURN VALUE +The +.BR isfdtype () +function returns 1 if the file descriptor +.I fd +is of type +.I fdtype +and 0 if it is not. +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +The +.BR isfdtype () +function can fail with any of the same errors as +.BR fstat (2). +.SH VERSIONS +Portable applications should use +.BR fstat (2) +instead. +.SH STANDARDS +None. +.SH HISTORY +It appeared in the draft POSIX.1g standard. +It is present on OpenBSD and Tru64 UNIX +(where the required header file in both cases is just +.IR , +as shown in the POSIX.1g draft). +.SH SEE ALSO +.BR fstat (2) diff --git a/man/man3/isfinite.3 b/man/man3/isfinite.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man/man3/isfinite.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man/man3/isgraph.3 b/man/man3/isgraph.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isgraph.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isgraph_l.3 b/man/man3/isgraph_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isgraph_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isgreater.3 b/man/man3/isgreater.3 new file mode 100644 index 0000000..9252b63 --- /dev/null +++ b/man/man3/isgreater.3 @@ -0,0 +1,144 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" 2002-07-27 Walter Harms +.\" this was done with the help of the glibc manual +.\" +.TH isgreater 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +isgreater, isgreaterequal, isless, islessequal, islessgreater, +isunordered \- floating-point relational tests without exception for NaN +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int isgreater(" x ", " y ); +.BI "int isgreaterequal(" x ", " y ); +.BI "int isless(" x ", " y ); +.BI "int islessequal(" x ", " y ); +.BI "int islessgreater(" x ", " y ); +.BI "int isunordered(" x ", " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.nf + All functions described here: + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The normal relational operations (like +.BR < , +"less than") +fail if one of the operands is NaN. +This will cause an exception. +To avoid this, C99 defines the macros listed below. +.P +These macros are guaranteed to evaluate their arguments only once. +The arguments must be of real floating-point type (note: do not pass +integer values as arguments to these macros, since the arguments will +.I not +be promoted to real-floating types). +.TP +.BR isgreater () +determines \fI(x)\ >\ (y)\fP without an exception +if +.I x +or +.I y +is NaN. +.TP +.BR isgreaterequal () +determines \fI(x)\ >=\ (y)\fP without an exception +if +.I x +or +.I y +is NaN. +.TP +.BR isless () +determines \fI(x)\ <\ (y)\fP without an exception +if +.I x +or +.I y +is NaN. +.TP +.BR islessequal () +determines \fI(x)\ <=\ (y)\fP without an exception +if +.I x +or +.I y +is NaN. +.TP +.BR islessgreater () +determines \fI(x)\ < (y) || (x) >\ (y)\fP +without an exception if +.I x +or +.I y +is NaN. +This macro is not equivalent to \fIx\ !=\ y\fP because that expression is +true if +.I x +or +.I y +is NaN. +.TP +.BR isunordered () +determines whether its arguments are unordered, that is, whether +at least one of the arguments is a NaN. +.SH RETURN VALUE +The macros other than +.BR isunordered () +return the result of the relational comparison; +these macros return 0 if either argument is a NaN. +.P +.BR isunordered () +returns 1 if +.I x +or +.I y +is NaN and 0 otherwise. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR isgreater (), +.BR isgreaterequal (), +.BR isless (), +.BR islessequal (), +.BR islessgreater (), +.BR isunordered () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Not all hardware supports these functions, +and where hardware support isn't provided, they will be emulated by macros. +This will result in a performance penalty. +Don't use these functions if NaN is of no concern for you. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR fpclassify (3), +.BR isnan (3) diff --git a/man/man3/isgreaterequal.3 b/man/man3/isgreaterequal.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man/man3/isgreaterequal.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man/man3/isinf.3 b/man/man3/isinf.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man/man3/isinf.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man/man3/isinff.3 b/man/man3/isinff.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/isinff.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/isinfl.3 b/man/man3/isinfl.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/isinfl.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/isless.3 b/man/man3/isless.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man/man3/isless.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man/man3/islessequal.3 b/man/man3/islessequal.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man/man3/islessequal.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man/man3/islessgreater.3 b/man/man3/islessgreater.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man/man3/islessgreater.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man/man3/islower.3 b/man/man3/islower.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/islower.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/islower_l.3 b/man/man3/islower_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/islower_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isnan.3 b/man/man3/isnan.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man/man3/isnan.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man/man3/isnanf.3 b/man/man3/isnanf.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/isnanf.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/isnanl.3 b/man/man3/isnanl.3 new file mode 100644 index 0000000..19f709b --- /dev/null +++ b/man/man3/isnanl.3 @@ -0,0 +1 @@ +.so man3/finite.3 diff --git a/man/man3/isnormal.3 b/man/man3/isnormal.3 new file mode 100644 index 0000000..17676c2 --- /dev/null +++ b/man/man3/isnormal.3 @@ -0,0 +1 @@ +.so man3/fpclassify.3 diff --git a/man/man3/isprint.3 b/man/man3/isprint.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isprint.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isprint_l.3 b/man/man3/isprint_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isprint_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/ispunct.3 b/man/man3/ispunct.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/ispunct.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/ispunct_l.3 b/man/man3/ispunct_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/ispunct_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isspace.3 b/man/man3/isspace.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isspace.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isspace_l.3 b/man/man3/isspace_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isspace_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isunordered.3 b/man/man3/isunordered.3 new file mode 100644 index 0000000..24410b9 --- /dev/null +++ b/man/man3/isunordered.3 @@ -0,0 +1 @@ +.so man3/isgreater.3 diff --git a/man/man3/isupper.3 b/man/man3/isupper.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isupper.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isupper_l.3 b/man/man3/isupper_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isupper_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/iswalnum.3 b/man/man3/iswalnum.3 new file mode 100644 index 0000000..2d05ee1 --- /dev/null +++ b/man/man3/iswalnum.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswalnum 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswalnum \- test for alphanumeric wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswalnum(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswalnum () +function is the wide-character equivalent of the +.BR isalnum (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "alnum". +.P +The wide-character class "alnum" is a subclass of the wide-character class +"graph", and therefore also a subclass of the wide-character class "print". +.P +Being a subclass of the wide-character class "print", +the wide-character class +"alnum" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", +the wide-character class "alnum" is disjoint from +the wide-character class "space" and its subclass "blank". +.P +The wide-character class "alnum" is disjoint from the wide-character class +"punct". +.P +The wide-character class "alnum" is the union of the wide-character classes +"alpha" and "digit". +As such, it also contains the wide-character class +"xdigit". +.P +The wide-character class "alnum" +always contains at least the letters +\[aq]A\[aq] to \[aq]Z\[aq], +\[aq]a\[aq] to \[aq]z\[aq], +and the digits \[aq]0\[aq] to \[aq]9\[aq]. +.SH RETURN VALUE +The +.BR iswalnum () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "alnum". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswalnum () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswalnum () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isalnum (3), +.BR iswctype (3) diff --git a/man/man3/iswalpha.3 b/man/man3/iswalpha.3 new file mode 100644 index 0000000..0f309a5 --- /dev/null +++ b/man/man3/iswalpha.3 @@ -0,0 +1,96 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswalpha 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswalpha \- test for alphabetic wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswalpha(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswalpha () +function is the wide-character equivalent of the +.BR isalpha (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "alpha". +.P +The wide-character class "alpha" is a subclass of the +wide-character class "alnum", +and therefore also a subclass of the wide-character class "graph" and +of the wide-character class "print". +.P +Being a subclass of the wide-character class "print", +the wide-character class +"alpha" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", +the wide-character class "alpha" is disjoint from +the wide-character class "space" and its subclass "blank". +.P +Being a subclass of the wide-character class "alnum", +the wide-character class "alpha" is disjoint from the +wide-character class "punct". +.P +The wide-character class "alpha" is disjoint from the wide-character class +"digit". +.P +The wide-character class "alpha" contains the wide-character classes "upper" +and "lower". +.P +The wide-character class "alpha" always contains at least the +letters \[aq]A\[aq] to \[aq]Z\[aq] and \[aq]a\[aq] to \[aq]z\[aq]. +.SH RETURN VALUE +The +.BR iswalpha () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "alpha". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswalpha () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswalpha () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isalpha (3), +.BR iswctype (3) diff --git a/man/man3/iswblank.3 b/man/man3/iswblank.3 new file mode 100644 index 0000000..81e3953 --- /dev/null +++ b/man/man3/iswblank.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswblank 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswblank \- test for whitespace wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswblank(wint_t " wc ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR iswblank (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR iswblank () +function is the wide-character equivalent of the +.BR isblank (3) +function. +It tests whether \fIwc\fP is a wide character +belonging to the wide-character class "blank". +.P +The wide-character class "blank" is a subclass of the wide-character class +"space". +.P +Being a subclass of the wide-character class "space", +the wide-character class "blank" is disjoint from the +wide-character class "graph" and therefore also disjoint +from its subclasses "alnum", "alpha", "upper", "lower", "digit", +"xdigit", "punct". +.P +The wide-character class "blank" always contains +at least the space character +and the control character \[aq]\et\[aq]. +.SH RETURN VALUE +The +.BR iswblank () +function returns nonzero +if \fIwc\fP is a wide character +belonging to the wide-character class "blank". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswblank () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The behavior of +.BR iswblank () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isblank (3), +.BR iswctype (3) diff --git a/man/man3/iswcntrl.3 b/man/man3/iswcntrl.3 new file mode 100644 index 0000000..424fb9d --- /dev/null +++ b/man/man3/iswcntrl.3 @@ -0,0 +1,80 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswcntrl 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswcntrl \- test for control wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswcntrl(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswcntrl () +function is the wide-character equivalent of the +.BR iscntrl (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "cntrl". +.P +The wide-character class "cntrl" is disjoint from the wide-character class +"print" and therefore also disjoint from its subclasses "graph", "alpha", +"upper", "lower", "digit", "xdigit", "punct". +.P +For an unsigned char +.IR c , +.I iscntrl(c) +implies +.IR iswcntrl(btowc(c)) , +but not vice versa. +.SH RETURN VALUE +The +.BR iswcntrl () +function returns nonzero if +.I wc +is a +wide character belonging to the wide-character class "cntrl". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswcntrl () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswcntrl () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iscntrl (3), +.BR iswctype (3) diff --git a/man/man3/iswctype.3 b/man/man3/iswctype.3 new file mode 100644 index 0000000..f49aff2 --- /dev/null +++ b/man/man3/iswctype.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswctype 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswctype \- wide-character classification +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswctype(wint_t " wc ", wctype_t " desc ); +.fi +.SH DESCRIPTION +If +.I wc +is a wide character having the character property designated by +.I desc +(or in other words: belongs to the character class designated by +.IR desc ), +then the +.BR iswctype () +function returns nonzero. +Otherwise, it +returns zero. +If +.I wc +is +.BR WEOF , +zero is returned. +.P +.I desc +must be a character property descriptor +returned by the +.BR wctype (3) +function. +.SH RETURN VALUE +The +.BR iswctype () +function returns nonzero if +the +.I wc +has the designated +property. +Otherwise, it returns 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswctype () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswctype () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswalnum (3), +.BR iswalpha (3), +.BR iswblank (3), +.BR iswcntrl (3), +.BR iswdigit (3), +.BR iswgraph (3), +.BR iswlower (3), +.BR iswprint (3), +.BR iswpunct (3), +.BR iswspace (3), +.BR iswupper (3), +.BR iswxdigit (3), +.BR wctype (3) diff --git a/man/man3/iswdigit.3 b/man/man3/iswdigit.3 new file mode 100644 index 0000000..d6caa4f --- /dev/null +++ b/man/man3/iswdigit.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswdigit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswdigit \- test for decimal digit wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswdigit(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswdigit () +function is the wide-character equivalent of the +.BR isdigit (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "digit". +.P +The wide-character class "digit" is a subclass of the wide-character class +"xdigit", and therefore also a subclass +of the wide-character class "alnum", of +the wide-character class "graph" and of the wide-character class "print". +.P +Being a subclass of the wide character +class "print", the wide-character class +"digit" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", +the wide-character class +"digit" is disjoint from the wide-character class "space" and its subclass +"blank". +.P +Being a subclass of the wide-character +class "alnum", the wide-character class +"digit" is disjoint from the wide-character class "punct". +.P +The wide-character class "digit" is +disjoint from the wide-character class +"alpha" and therefore also disjoint from its subclasses "lower", "upper". +.P +The wide-character class "digit" always +contains exactly the digits \[aq]0\[aq] to \[aq]9\[aq]. +.SH RETURN VALUE +The +.BR iswdigit () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "digit". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswdigit () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswdigit () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isdigit (3), +.BR iswctype (3) diff --git a/man/man3/iswgraph.3 b/man/man3/iswgraph.3 new file mode 100644 index 0000000..cedc72f --- /dev/null +++ b/man/man3/iswgraph.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswgraph 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswgraph \- test for graphic wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswgraph(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswgraph () +function is the wide-character equivalent of the +.BR isgraph (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "graph". +.P +The wide-character class "graph" is a subclass of the wide-character class +"print". +.P +Being a subclass of the wide-character class "print", +the wide-character class +"graph" is disjoint from the wide-character class "cntrl". +.P +The wide-character class "graph" is disjoint from the wide-character class +"space" and therefore also disjoint from its subclass "blank". +.\" Note: UNIX98 (susv2/xbd/locale.html) says that "graph" and "space" may +.\" have characters in common, except U+0020. But C99 (ISO/IEC 9899:1999 +.\" section 7.25.2.1.10) says that "space" and "graph" are disjoint. +.P +The wide-character class "graph" contains all the wide characters from the +wide-character class "print" except the space character. +It therefore contains +the wide-character classes "alnum" and "punct". +.SH RETURN VALUE +The +.BR iswgraph () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "graph". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswgraph () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswgraph () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isgraph (3), +.BR iswctype (3) diff --git a/man/man3/iswlower.3 b/man/man3/iswlower.3 new file mode 100644 index 0000000..41051b9 --- /dev/null +++ b/man/man3/iswlower.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswlower 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswlower \- test for lowercase wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswlower(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswlower () +function is the wide-character equivalent of the +.BR islower (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "lower". +.P +The wide-character class "lower" is a subclass of the wide-character class +"alpha", and therefore also a subclass +of the wide-character class "alnum", of +the wide-character class "graph" and of the wide-character class "print". +.P +Being a subclass of the wide-character class "print", +the wide-character class +"lower" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", +the wide-character class "lower" is disjoint from the +wide-character class "space" and its subclass "blank". +.P +Being a subclass of the wide-character class "alnum", +the wide-character class +"lower" is disjoint from the wide-character class "punct". +.P +Being a subclass of the wide-character class "alpha", +the wide-character class +"lower" is disjoint from the wide-character class "digit". +.P +The wide-character class "lower" contains at least +those characters +.I wc +which are equal to +.I towlower(wc) +and different from +.IR towupper(wc) . +.P +The wide-character class "lower" always contains +at least the letters \[aq]a\[aq] to \[aq]z\[aq]. +.SH RETURN VALUE +The +.BR iswlower () +function returns nonzero +if +.I wc +is a wide character +belonging to the wide-character class "lower". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswlower () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswlower () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +This function is not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower, and title case. +.SH SEE ALSO +.BR islower (3), +.BR iswctype (3), +.BR towlower (3) diff --git a/man/man3/iswprint.3 b/man/man3/iswprint.3 new file mode 100644 index 0000000..e570b0b --- /dev/null +++ b/man/man3/iswprint.3 @@ -0,0 +1,74 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswprint 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswprint \- test for printing wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswprint(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswprint () +function is the wide-character equivalent of the +.BR isprint (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "print". +.P +The wide-character class "print" is disjoint from the wide-character class +"cntrl". +.P +The wide-character class "print" contains the wide-character class "graph". +.SH RETURN VALUE +The +.BR iswprint () +function returns nonzero if +.I wc +is a +wide character belonging to the wide-character class "print". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswprint () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswprint () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isprint (3), +.BR iswctype (3) diff --git a/man/man3/iswpunct.3 b/man/man3/iswpunct.3 new file mode 100644 index 0000000..426bd2d --- /dev/null +++ b/man/man3/iswpunct.3 @@ -0,0 +1,90 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswpunct 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswpunct \- test for punctuation or symbolic wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswpunct(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswpunct () +function is the wide-character equivalent of the +.BR ispunct (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "punct". +.P +The wide-character class "punct" is a subclass of the wide-character class +"graph", and therefore also a subclass of the wide-character class "print". +.P +The wide-character class "punct" is disjoint from the wide-character class +"alnum" and therefore also disjoint from its subclasses "alpha", "upper", +"lower", "digit", "xdigit". +.P +Being a subclass of the wide-character class "print", +the wide-character class +"punct" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", +the wide-character class +"punct" is disjoint from the wide-character class "space" and its subclass +"blank". +.SH RETURN VALUE +The +.BR iswpunct () +function returns nonzero +if +.I wc +is a wide-character +belonging to the wide-character class "punct". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswpunct () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswpunct () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +This function's name is a misnomer when dealing with Unicode characters, +because the wide-character class "punct" contains both punctuation characters +and symbol (math, currency, etc.) characters. +.SH SEE ALSO +.BR ispunct (3), +.BR iswctype (3) diff --git a/man/man3/iswspace.3 b/man/man3/iswspace.3 new file mode 100644 index 0000000..fdddacb --- /dev/null +++ b/man/man3/iswspace.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswspace 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswspace \- test for whitespace wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswspace(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswspace () +function is the wide-character equivalent of the +.BR isspace (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "space". +.P +The wide-character class "space" is disjoint from the wide-character class +"graph" and therefore also disjoint from its subclasses "alnum", "alpha", +"upper", "lower", "digit", "xdigit", "punct". +.\" Note: UNIX98 (susv2/xbd/locale.html) says that "space" and "graph" may +.\" have characters in common, except U+0020. But C99 (ISO/IEC 9899:1999 +.\" section 7.25.2.1.10) says that "space" and "graph" are disjoint. +.P +The wide-character class "space" contains the wide-character class "blank". +.P +The wide-character class "space" +always contains at least the space character +and the control characters +\[aq]\ef\[aq], \[aq]\en\[aq], \[aq]\er\[aq], \[aq]\et\[aq], and \[aq]\ev\[aq]. +.SH RETURN VALUE +The +.BR iswspace () +function returns nonzero if +.I wc +is a wide character +belonging to the wide-character class "space". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswspace () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswspace () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR isspace (3), +.BR iswctype (3) diff --git a/man/man3/iswupper.3 b/man/man3/iswupper.3 new file mode 100644 index 0000000..27371e9 --- /dev/null +++ b/man/man3/iswupper.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswupper 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswupper \- test for uppercase wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswupper(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswupper () +function is the wide-character equivalent of the +.BR isupper (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "upper". +.P +The wide-character class "upper" is a subclass of the wide-character class +"alpha", and therefore also a subclass of the wide-character class "alnum", of +the wide-character class "graph" and of the wide-character class "print". +.P +Being a subclass of the wide-character class "print", the wide-character class +"upper" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", the wide-character class +"upper" is disjoint from the wide-character class "space" and its subclass +"blank". +.P +Being a subclass of the wide-character class "alnum", the wide-character class +"upper" is disjoint from the wide-character class "punct". +.P +Being a subclass of the wide-character class "alpha", the wide-character class +"upper" is disjoint from the wide-character class "digit". +.P +The wide-character class "upper" contains at least those characters +.I wc +which are equal to +.I towupper(wc) +and different from +.IR towlower(wc) . +.P +The wide-character class "upper" always contains at least the +letters \[aq]A\[aq] to \[aq]Z\[aq]. +.SH RETURN VALUE +The +.BR iswupper () +function returns nonzero if +.I wc +is a wide character +belonging to the wide-character class "upper". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswupper () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswupper () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +This function is not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower, and title case. +.SH SEE ALSO +.BR isupper (3), +.BR iswctype (3), +.BR towupper (3) diff --git a/man/man3/iswxdigit.3 b/man/man3/iswxdigit.3 new file mode 100644 index 0000000..063743b --- /dev/null +++ b/man/man3/iswxdigit.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH iswxdigit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iswxdigit \- test for hexadecimal digit wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int iswxdigit(wint_t " wc ); +.fi +.SH DESCRIPTION +The +.BR iswxdigit () +function is the wide-character equivalent of the +.BR isxdigit (3) +function. +It tests whether +.I wc +is a wide character +belonging to the wide-character class "xdigit". +.P +The wide-character class "xdigit" is a subclass of the wide-character class +"alnum", and therefore also a subclass of the wide-character class "graph" and +of the wide-character class "print". +.P +Being a subclass of the wide-character class "print", the wide-character class +"xdigit" is disjoint from the wide-character class "cntrl". +.P +Being a subclass of the wide-character class "graph", the wide-character class +"xdigit" is disjoint from the wide-character class "space" and its subclass +"blank". +.P +Being a subclass of the wide-character class "alnum", the wide-character class +"xdigit" is disjoint from the wide-character class "punct". +.P +The wide-character class "xdigit" always contains at least the +letters \[aq]A\[aq] to \[aq]F\[aq], \[aq]a\[aq] to \[aq]f\[aq] +and the digits \[aq]0\[aq] to \[aq]9\[aq]. +.SH RETURN VALUE +The +.BR iswxdigit () +function returns nonzero if +.I wc +is a wide character +belonging to the wide-character class "xdigit". +Otherwise, it returns zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR iswxdigit () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR iswxdigit () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswctype (3), +.BR isxdigit (3) diff --git a/man/man3/isxdigit.3 b/man/man3/isxdigit.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isxdigit.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/isxdigit_l.3 b/man/man3/isxdigit_l.3 new file mode 100644 index 0000000..0b69c75 --- /dev/null +++ b/man/man3/isxdigit_l.3 @@ -0,0 +1 @@ +.so man3/isalpha.3 diff --git a/man/man3/j0.3 b/man/man3/j0.3 new file mode 100644 index 0000000..4a97b3f --- /dev/null +++ b/man/man3/j0.3 @@ -0,0 +1,195 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:08:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-25, aeb +.\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB +.\" 2008-07-24, mtk, moved yxx() material into separate y0.3 page +.\" +.TH j0 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +j0, j0f, j0l, j1, j1f, j1l, jn, jnf, jnl \- +Bessel functions of the first kind +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double j0(double " x ); +.BI "double j1(double " x ); +.BI "double jn(int " n ", double " x ); +.P +.BI "float j0f(float " x ); +.BI "float j1f(float " x ); +.BI "float jnf(int " n ", float " x ); +.P +.BI "long double j0l(long double " x ); +.BI "long double j1l(long double " x ); +.BI "long double jnl(int " n ", long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR j0 (), +.BR j1 (), +.BR jn (): +.nf + _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR j0f (), +.BR j0l (), +.BR j1f (), +.BR j1l (), +.BR jnf (), +.BR jnl (): +.nf + _XOPEN_SOURCE >= 600 + || (_ISOC99_SOURCE && _XOPEN_SOURCE) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR j0 () +and +.BR j1 () +functions return Bessel functions of +.I x +of the first kind of orders 0 and 1, respectively. +The +.BR jn () +function +returns the Bessel function of +.I x +of the first kind of order +.IR n . +.P +The +.BR j0f (), +.BR j1f (), +and +.BR jnf (), +functions are versions that take and return +.I float +values. +The +.BR j0l (), +.BR j1l (), +and +.BR jnl () +functions are versions that take and return +.I "long double" +values. +.SH RETURN VALUE +On success, these functions return the appropriate +Bessel value of the first kind for +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is too large in magnitude, +or the result underflows, +a range error occurs, +and the return value is 0. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result underflow, or \fIx\fP is too large in magnitude +.I errno +is set to +.BR ERANGE . +.P +These functions do not raise exceptions for +.BR fetestexcept (3). +.\" e.g., j0(1.5e16) +.\" This is intentional. +.\" See https://www.sourceware.org/bugzilla/show_bug.cgi?id=6805 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR j0 (), +.BR j0f (), +.BR j0l () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR j1 (), +.BR j1f (), +.BR j1l () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR jn (), +.BR jnf (), +.BR jnl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR j0 () +.TQ +.BR j1 () +.TQ +.BR jn () +POSIX.1-2008. +.TP +Others: +BSD. +.SH HISTORY +.TP +.BR j0 () +.TQ +.BR j1 () +.TQ +.BR jn () +SVr4, 4.3BSD, +POSIX.1-2001, POSIX.1-2008. +.TP +Others: +BSD. +.SH BUGS +There are errors of up to 2e\-16 in the values returned by +.BR j0 (), +.BR j1 (), +and +.BR jn () +for values of +.I x +between \-8 and 8. +.SH SEE ALSO +.BR y0 (3) diff --git a/man/man3/j0f.3 b/man/man3/j0f.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/j0f.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/j0l.3 b/man/man3/j0l.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/j0l.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/j1.3 b/man/man3/j1.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/j1.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/j1f.3 b/man/man3/j1f.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/j1f.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/j1l.3 b/man/man3/j1l.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/j1l.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/jn.3 b/man/man3/jn.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/jn.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/jnf.3 b/man/man3/jnf.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/jnf.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/jnl.3 b/man/man3/jnl.3 new file mode 100644 index 0000000..6dc1818 --- /dev/null +++ b/man/man3/jnl.3 @@ -0,0 +1 @@ +.so man3/j0.3 diff --git a/man/man3/jrand48.3 b/man/man3/jrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/jrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/jrand48_r.3 b/man/man3/jrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/jrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/key_decryptsession.3 b/man/man3/key_decryptsession.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man/man3/key_decryptsession.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man/man3/key_encryptsession.3 b/man/man3/key_encryptsession.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man/man3/key_encryptsession.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man/man3/key_gendes.3 b/man/man3/key_gendes.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man/man3/key_gendes.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man/man3/key_secretkey_is_set.3 b/man/man3/key_secretkey_is_set.3 new file mode 100644 index 0000000..bc4bb02 --- /dev/null +++ b/man/man3/key_secretkey_is_set.3 @@ -0,0 +1 @@ +.so man3/key_setsecret.3 diff --git a/man/man3/key_setsecret.3 b/man/man3/key_setsecret.3 new file mode 100644 index 0000000..5ea22c9 --- /dev/null +++ b/man/man3/key_setsecret.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" I had no way the check the functions out +.\" be careful +.TH key_setsecret 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +key_decryptsession, key_encryptsession, key_setsecret, key_gendes, +key_secretkey_is_set \- interfaces to rpc keyserver daemon +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int key_decryptsession(char *" remotename ", des_block *" deskey ); +.BI "int key_encryptsession(char *" remotename ", des_block *" deskey ); +.P +.BI "int key_gendes(des_block *" deskey ); +.P +.BI "int key_setsecret(char *" key ); +.B int key_secretkey_is_set(void); +.fi +.SH DESCRIPTION +The functions here are used within the RPC's secure authentication +mechanism (AUTH_DES). +There should be no need for user programs to +use this functions. +.P +The function +.BR key_decryptsession () +uses the (remote) server netname and takes the DES key +for decrypting. +It uses the public key of the server and the +secret key associated with the effective UID of the calling process. +.P +The function +.BR key_encryptsession () +is the inverse of +.BR key_decryptsession (). +It encrypts the DES keys with the public key of the server and +the secret key associated with the effective UID of the calling process. +.P +The function +.BR key_gendes () +is used to ask the keyserver for a secure conversation key. +.P +The function +.BR key_setsecret () +is used to set the key for the effective UID of the calling process. +.P +The function +.BR key_secretkey_is_set () +can be used to determine whether a key has been +set for the effective UID of the calling process. +.SH RETURN VALUE +These functions return 1 on success and 0 on failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR key_decryptsession (), +.BR key_encryptsession (), +.BR key_gendes (), +.BR key_setsecret (), +.BR key_secretkey_is_set () +T} Thread safety MT-Safe +.TE +.SH NOTES +Note that we talk about two types of encryption here. +One is asymmetric using a public and secret key. +The other is symmetric, the +64-bit DES. +.P +These routines were part of the Linux/Doors-project, abandoned by now. +.SH SEE ALSO +.BR crypt (3) diff --git a/man/man3/killpg.3 b/man/man3/killpg.3 new file mode 100644 index 0000000..35edc0e --- /dev/null +++ b/man/man3/killpg.3 @@ -0,0 +1,113 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)killpg.2 6.5 (Berkeley) 3/10/91 +.\" +.\" Modified Fri Jul 23 21:55:01 1993 by Rik Faith +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond +.\" Modified 2004-06-16 by Michael Kerrisk +.\" Added notes on CAP_KILL +.\" Modified 2004-06-21 by aeb +.\" +.TH killpg 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +killpg \- send signal to a process group +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int killpg(int " pgrp ", int " sig ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR killpg (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR killpg () +sends the signal +.I sig +to the process group +.IR pgrp . +See +.BR signal (7) +for a list of signals. +.P +If +.I pgrp +is 0, +.BR killpg () +sends the signal to the calling process's process group. +(POSIX says: if +.I pgrp +is less than or equal to 1, the behavior is undefined.) +.P +For the permissions required to send a signal to another process, see +.BR kill (2). +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sig +is not a valid signal number. +.TP +.B EPERM +The process does not have permission to send the signal +to any of the target processes. +For the required permissions, see +.BR kill (2). +.TP +.B ESRCH +No process can be found in the process group specified by +.IR pgrp . +.TP +.B ESRCH +The process group was given as 0 but the sending process does not +have a process group. +.SH VERSIONS +There are various differences between the permission checking +in BSD-type systems and System\ V-type systems. +See the POSIX rationale for +.BR kill (3p). +A difference not mentioned by POSIX concerns the return +value +.BR EPERM : +BSD documents that no signal is sent and +.B EPERM +returned when the permission check failed for at least one target process, +while POSIX documents +.B EPERM +only when the permission check failed for all target processes. +.SS C library/kernel differences +On Linux, +.BR killpg () +is implemented as a library function that makes the call +.IR "kill(\-pgrp,\ sig)" . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.4BSD +(first appeared in 4BSD). +.SH SEE ALSO +.BR getpgrp (2), +.BR kill (2), +.BR signal (2), +.BR capabilities (7), +.BR credentials (7) diff --git a/man/man3/klogctl.3 b/man/man3/klogctl.3 new file mode 100644 index 0000000..bbe6ab2 --- /dev/null +++ b/man/man3/klogctl.3 @@ -0,0 +1 @@ +.so man2/syslog.2 diff --git a/man/man3/l64a.3 b/man/man3/l64a.3 new file mode 100644 index 0000000..e54ce27 --- /dev/null +++ b/man/man3/l64a.3 @@ -0,0 +1 @@ +.so man3/a64l.3 diff --git a/man/man3/labs.3 b/man/man3/labs.3 new file mode 100644 index 0000000..97db8d2 --- /dev/null +++ b/man/man3/labs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man/man3/lckpwdf.3 b/man/man3/lckpwdf.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/lckpwdf.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/lcong48.3 b/man/man3/lcong48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/lcong48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/lcong48_r.3 b/man/man3/lcong48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/lcong48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/ldexp.3 b/man/man3/ldexp.3 new file mode 100644 index 0000000..5e00270 --- /dev/null +++ b/man/man3/ldexp.3 @@ -0,0 +1,131 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2004-10-31 by aeb +.\" +.TH ldexp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ldexp, ldexpf, ldexpl \- multiply floating-point number by integral power of 2 +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double ldexp(double " x ", int " exp ); +.BI "float ldexpf(float " x ", int " exp ); +.BI "long double ldexpl(long double " x ", int " exp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ldexpf (), +.BR ldexpl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the result of multiplying the floating-point number +.I x +by 2 raised to the power +.IR exp . +.SH RETURN VALUE +On success, these functions return +.IR "x * (2\[ha]exp)" . +.P +If +.I exp +is zero, then +.I x +is returned. +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.P +If the result underflows, +a range error occurs, +and zero is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with a sign the same as +.IR x . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error, overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ldexp (), +.BR ldexpf (), +.BR ldexpl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR frexp (3), +.BR modf (3), +.BR scalbln (3) diff --git a/man/man3/ldexpf.3 b/man/man3/ldexpf.3 new file mode 100644 index 0000000..0e74a02 --- /dev/null +++ b/man/man3/ldexpf.3 @@ -0,0 +1 @@ +.so man3/ldexp.3 diff --git a/man/man3/ldexpl.3 b/man/man3/ldexpl.3 new file mode 100644 index 0000000..0e74a02 --- /dev/null +++ b/man/man3/ldexpl.3 @@ -0,0 +1 @@ +.so man3/ldexp.3 diff --git a/man/man3/ldiv.3 b/man/man3/ldiv.3 new file mode 100644 index 0000000..934824e --- /dev/null +++ b/man/man3/ldiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man/man3/le16toh.3 b/man/man3/le16toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/le16toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/le32toh.3 b/man/man3/le32toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/le32toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/le64toh.3 b/man/man3/le64toh.3 new file mode 100644 index 0000000..8b7bc77 --- /dev/null +++ b/man/man3/le64toh.3 @@ -0,0 +1 @@ +.so man3/endian.3 diff --git a/man/man3/lfind.3 b/man/man3/lfind.3 new file mode 100644 index 0000000..24179b4 --- /dev/null +++ b/man/man3/lfind.3 @@ -0,0 +1 @@ +.so man3/lsearch.3 diff --git a/man/man3/lgamma.3 b/man/man3/lgamma.3 new file mode 100644 index 0000000..8b1381b --- /dev/null +++ b/man/man3/lgamma.3 @@ -0,0 +1,202 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" based on glibc infopages +.\" +.TH lgamma 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lgamma, lgammaf, lgammal, lgamma_r, lgammaf_r, lgammal_r, signgam \- +log gamma function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double lgamma(double " x ); +.BI "float lgammaf(float " x ); +.BI "long double lgammal(long double " x ); +.P +.BI "double lgamma_r(double " x ", int *" signp ); +.BI "float lgammaf_r(float " x ", int *" signp ); +.BI "long double lgammal_r(long double " x ", int *" signp ); +.P +.BI "extern int " signgam ; +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.nf +.BR lgamma (): + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR lgammaf (), +.BR lgammal (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR lgamma_r (), +.BR lgammaf_r (), +.BR lgammal_r (): +.nf + /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.IR signgam : +.nf + _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +For the definition of the Gamma function, see +.BR tgamma (3). +.P +The +.BR lgamma (), +.BR lgammaf (), +and +.BR lgammal () +functions return the natural logarithm of +the absolute value of the Gamma function. +The sign of the Gamma function is returned in the +external integer +.I signgam +declared in +.IR . +It is 1 when the Gamma function is positive or zero, \-1 +when it is negative. +.P +Since using a constant location +.I signgam +is not thread-safe, the functions +.BR lgamma_r (), +.BR lgammaf_r (), +and +.BR lgammal_r () +have been introduced; they return the sign via the argument +.IR signp . +.SH RETURN VALUE +On success, these functions return the natural logarithm of Gamma(x). +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is 1 or 2, +0 is returned. +.P +If +.I x +is positive infinity or negative infinity, +positive infinity is returned. +.P +If +.I x +is a nonpositive integer, +a pole error occurs, +and the functions return +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +respectively. +.P +If the result overflows, +a range error occurs, +.\" e.g., lgamma(DBL_MAX) +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the correct mathematical sign. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Pole error: \fIx\fP is a nonpositive integer +.I errno +is set to +.B ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.\" glibc (as at 2.8) also supports an inexact +.\" exception for various cases. +.SH STANDARDS +.TP +.BR lgamma () +.TQ +.BR lgammaf () +.TQ +.BR lgammal () +C11, POSIX.1-2008. +.TP +.I signgam +POSIX.1-2008. +.TP +.BR lgamma_r () +.TQ +.BR lgammaf_r () +.TQ +.BR lgammal_r () +None. +.SH HISTORY +.TP +.BR lgamma () +.TQ +.BR lgammaf () +.TQ +.BR lgammal () +C99, POSIX.1-2001. +.TP +.I signgam +POSIX.1-2001. +.TP +.BR lgamma_r () +.TQ +.BR lgammaf_r () +.TQ +.BR lgammal_r () +None. +.SH BUGS +In glibc 2.9 and earlier, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6777 +when a pole error occurs, +.I errno +is set to +.BR EDOM ; +instead of the POSIX-mandated +.BR ERANGE . +Since glibc 2.10, glibc does the right thing. +.SH SEE ALSO +.BR tgamma (3) diff --git a/man/man3/lgamma_r.3 b/man/man3/lgamma_r.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/lgamma_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/lgammaf.3 b/man/man3/lgammaf.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/lgammaf.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/lgammaf_r.3 b/man/man3/lgammaf_r.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/lgammaf_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/lgammal.3 b/man/man3/lgammal.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/lgammal.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/lgammal_r.3 b/man/man3/lgammal_r.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/lgammal_r.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/lio_listio.3 b/man/man3/lio_listio.3 new file mode 100644 index 0000000..2e38492 --- /dev/null +++ b/man/man3/lio_listio.3 @@ -0,0 +1,224 @@ +'\" t +.\" Copyright (C) 2010, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH lio_listio 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lio_listio \- initiate a list of I/O requests +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int lio_listio(int " mode , +.BI " struct aiocb *restrict const " aiocb_list [restrict], +.BI " int " nitems ", struct sigevent *restrict " sevp ); +.fi +.SH DESCRIPTION +The +.BR lio_listio () +function initiates the list of I/O operations described by the array +.IR aiocb_list . +.P +The +.I mode +operation has one of the following values: +.TP +.B LIO_WAIT +The call blocks until all operations are complete. +The +.I sevp +argument is ignored. +.TP +.B LIO_NOWAIT +The I/O operations are queued for processing and the call returns immediately. +When all of the I/O operations complete, asynchronous notification occurs, +as specified by the +.I sevp +argument; see +.BR sigevent (3type) +for details. +If +.I sevp +is NULL, no asynchronous notification occurs. +.P +The +.I aiocb_list +argument is an array of pointers to +.I aiocb +structures that describe I/O operations. +These operations are executed in an unspecified order. +The +.I nitems +argument specifies the size of the array +.IR aiocb_list . +Null pointers in +.I aiocb_list +are ignored. +.P +In each control block in +.IR aiocb_list , +the +.I aio_lio_opcode +field specifies the I/O operation to be initiated, as follows: +.TP +.B LIO_READ +Initiate a read operation. +The operation is queued as for a call to +.BR aio_read (3) +specifying this control block. +.TP +.B LIO_WRITE +Initiate a write operation. +The operation is queued as for a call to +.BR aio_write (3) +specifying this control block. +.TP +.B LIO_NOP +Ignore this control block. +.P +The remaining fields in each control block have the same meanings as for +.BR aio_read (3) +and +.BR aio_write (3). +The +.I aio_sigevent +fields of each control block can be used to specify notifications +for the individual I/O operations (see +.BR sigevent (7)). +.SH RETURN VALUE +If +.I mode +is +.BR LIO_NOWAIT , +.BR lio_listio () +returns 0 if all I/O operations are successfully queued. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.P +If +.I mode +is +.BR LIO_WAIT , +.BR lio_listio () +returns 0 when all of the I/O operations have completed successfully. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.P +The return status from +.BR lio_listio () +provides information only about the call itself, +not about the individual I/O operations. +One or more of the I/O operations may fail, +but this does not prevent other operations completing. +The status of individual I/O operations in +.I aiocb_list +can be determined using +.BR aio_error (3). +When an operation has completed, +its return status can be obtained using +.BR aio_return (3). +Individual I/O operations can fail for the reasons described in +.BR aio_read (3) +and +.BR aio_write (3). +.SH ERRORS +The +.BR lio_listio () +function may fail for the following reasons: +.TP +.B EAGAIN +Out of resources. +.TP +.B EAGAIN +.\" Doesn't happen in glibc(?) +The number of I/O operations specified by +.I nitems +would cause the limit +.B AIO_MAX +to be exceeded. +.TP +.B EINTR +.I mode +was +.B LIO_WAIT +and a signal +was caught before all I/O operations completed; see +.BR signal (7). +(This may even be one of the signals used for +asynchronous I/O completion notification.) +.TP +.B EINVAL +.I mode +is invalid, or +.\" Doesn't happen in glibc(?) +.I nitems +exceeds the limit +.BR AIO_LISTIO_MAX . +.TP +.B EIO +One of more of the operations specified by +.I aiocb_list +failed. +.\" e.g., ioa_reqprio or aio_lio_opcode was invalid +The application can check the status of each operation using +.BR aio_return (3). +.P +If +.BR lio_listio () +fails with the error +.BR EAGAIN , +.BR EINTR , +or +.BR EIO , +then some of the operations in +.I aiocb_list +may have been initiated. +If +.BR lio_listio () +fails for any other reason, +then none of the I/O operations has been initiated. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lio_listio () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +It is a good idea to zero out the control blocks before use. +The control blocks must not be changed while the I/O operations +are in progress. +The buffer areas being read into or written from +.\" or the control block of the operation +must not be accessed during the operations or undefined results may occur. +The memory areas involved must remain valid. +.P +Simultaneous I/O operations specifying the same +.I aiocb +structure produce undefined results. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR aio (7) diff --git a/man/man3/list.3 b/man/man3/list.3 new file mode 100644 index 0000000..bab95a0 --- /dev/null +++ b/man/man3/list.3 @@ -0,0 +1,308 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH LIST 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +LIST_EMPTY, +LIST_ENTRY, +LIST_FIRST, +LIST_FOREACH, +.\"LIST_FOREACH_FROM, +.\"LIST_FOREACH_SAFE, +.\"LIST_FOREACH_FROM_SAFE, +LIST_HEAD, +LIST_HEAD_INITIALIZER, +LIST_INIT, +LIST_INSERT_AFTER, +LIST_INSERT_BEFORE, +LIST_INSERT_HEAD, +LIST_NEXT, +.\"LIST_PREV, +LIST_REMOVE +.\"LIST_SWAP +\- implementation of a doubly linked list +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B LIST_ENTRY(TYPE); +.P +.B LIST_HEAD(HEADNAME, TYPE); +.BI "LIST_HEAD LIST_HEAD_INITIALIZER(LIST_HEAD " head ); +.BI "void LIST_INIT(LIST_HEAD *" head ); +.P +.BI "int LIST_EMPTY(LIST_HEAD *" head ); +.P +.BI "void LIST_INSERT_HEAD(LIST_HEAD *" head , +.BI " struct TYPE *" elm ", LIST_ENTRY " NAME ); +.BI "void LIST_INSERT_BEFORE(struct TYPE *" listelm , +.BI " struct TYPE *" elm ", LIST_ENTRY " NAME ); +.BI "void LIST_INSERT_AFTER(struct TYPE *" listelm , +.BI " struct TYPE *" elm ", LIST_ENTRY " NAME ); +.P +.BI "struct TYPE *LIST_FIRST(LIST_HEAD *" head ); +.\" .BI "struct TYPE *LIST_PREV(struct TYPE *" elm ", LIST_HEAD *" head , +.\" .BI " struct TYPE, LIST_ENTRY " NAME ); +.BI "struct TYPE *LIST_NEXT(struct TYPE *" elm ", LIST_ENTRY " NAME ); +.P +.BI "LIST_FOREACH(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ); +.\" .BI "LIST_FOREACH_FROM(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ); +.\" .P +.\" .BI "LIST_FOREACH_SAFE(struct TYPE *" var ", LIST_HEAD *" head , +.\" .BI " LIST_ENTRY " NAME ", struct TYPE *" temp_var ); +.\" .BI "LIST_FOREACH_FROM_SAFE(struct TYPE *" var ", LIST_HEAD *" head , +.\" .BI " LIST_ENTRY " NAME ", struct TYPE *" temp_var ); +.P +.BI "void LIST_REMOVE(struct TYPE *" elm ", LIST_ENTRY " NAME ); +.\" .P +.\" .BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 , +.\" .BI " struct TYPE, LIST_ENTRY " NAME ); +.fi +.SH DESCRIPTION +These macros define and operate on doubly linked lists. +.P +In the macro definitions, +.I TYPE +is the name of a user-defined structure, +that must contain a field of type +.IR LIST_ENTRY , +named +.IR NAME . +The argument +.I HEADNAME +is the name of a user-defined structure +that must be declared using the macro +.BR LIST_HEAD (). +.SS Creation +A list is headed by a structure defined by the +.BR LIST_HEAD () +macro. +This structure contains a single pointer to the first element on the list. +The elements are doubly linked +so that an arbitrary element can be removed without traversing the list. +New elements can be added to the list +after an existing element, +before an existing element, +or at the head of the list. +A +.I LIST_HEAD +structure is declared as follows: +.P +.in +4 +.EX +LIST_HEAD(HEADNAME, TYPE) head; +.EE +.in +.P +where +.I struct HEADNAME +is the structure to be defined, and +.I struct TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.P +.in +4 +.EX +struct HEADNAME *headp; +.EE +.in +.P +(The names +.I head +and +.I headp +are user selectable.) +.P +.BR LIST_ENTRY () +declares a structure that connects the elements in the list. +.P +.BR LIST_HEAD_INITIALIZER () +evaluates to an initializer for the list +.IR head . +.P +.BR LIST_INIT () +initializes the list referenced by +.IR head . +.P +.BR LIST_EMPTY () +evaluates to true if there are no elements in the list. +.SS Insertion +.BR LIST_INSERT_HEAD () +inserts the new element +.I elm +at the head of the list. +.P +.BR LIST_INSERT_BEFORE () +inserts the new element +.I elm +before the element +.IR listelm . +.P +.BR LIST_INSERT_AFTER () +inserts the new element +.I elm +after the element +.IR listelm . +.SS Traversal +.BR LIST_FIRST () +returns the first element in the list, or NULL if the list is empty. +.\" .P +.\" .BR LIST_PREV () +.\" returns the previous element in the list, or NULL if this is the first. +.\" List +.\" .I head +.\" must contain element +.\" .IR elm . +.P +.BR LIST_NEXT () +returns the next element in the list, or NULL if this is the last. +.P +.BR LIST_FOREACH () +traverses the list referenced by +.I head +in the forward direction, +assigning each element in turn to +.IR var . +.\" .P +.\" .BR LIST_FOREACH_FROM () +.\" behaves identically to +.\" .BR LIST_FOREACH () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found LIST element and begins the loop at +.\" .I var +.\" instead of the first element in the LIST referenced by +.\" .IR head . +.\" .P +.\" .BR LIST_FOREACH_SAFE () +.\" traverses the list referenced by +.\" .I head +.\" in the forward direction, assigning each element in turn to +.\" .IR var . +.\" However, unlike +.\" .BR LIST_FOREACH () +.\" here it is permitted to both remove +.\" .I var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .P +.\" .BR LIST_FOREACH_FROM_SAFE () +.\" behaves identically to +.\" .BR LIST_FOREACH_SAFE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found LIST element and begins the loop at +.\" .I var +.\" instead of the first element in the LIST referenced by +.\" .IR head . +.SS Removal +.BR LIST_REMOVE () +removes the element +.I elm +from the list. +.\" .SS Other features +.\" .BR LIST_SWAP () +.\" swaps the contents of +.\" .I head1 +.\" and +.\" .IR head2 . +.SH RETURN VALUE +.BR LIST_EMPTY () +returns nonzero if the list is empty, +and zero if the list contains at least one entry. +.P +.BR LIST_FIRST (), +and +.BR LIST_NEXT () +return a pointer to the first or next +.I TYPE +structure, respectively. +.P +.BR LIST_HEAD_INITIALIZER () +returns an initializer that can be assigned to the list +.IR head . +.SH STANDARDS +BSD. +.SH HISTORY +4.4BSD. +.SH BUGS +.BR LIST_FOREACH () +doesn't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +.BR LIST_FOREACH_SAFE (), +which is present on the BSDs but is not present in glibc, +fixes this limitation by allowing +.I var +to safely be removed from the list and freed from within the loop +without interfering with the traversal. +.SH EXAMPLES +.\" SRC BEGIN (list.c) +.EX +#include +#include +#include +#include +\& +struct entry { + int data; + LIST_ENTRY(entry) entries; /* List */ +}; +\& +LIST_HEAD(listhead, entry); +\& +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct listhead head; /* List head */ + int i; +\& + LIST_INIT(&head); /* Initialize the list */ +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the head */ + LIST_INSERT_HEAD(&head, n1, entries); +\& + n2 = malloc(sizeof(struct entry)); /* Insert after */ + LIST_INSERT_AFTER(n1, n2, entries); +\& + n3 = malloc(sizeof(struct entry)); /* Insert before */ + LIST_INSERT_BEFORE(n2, n3, entries); +\& + i = 0; /* Forward traversal */ + LIST_FOREACH(np, &head, entries) + np\->data = i++; +\& + LIST_REMOVE(n2, entries); /* Deletion */ + free(n2); + /* Forward traversal */ + LIST_FOREACH(np, &head, entries) + printf("%i\en", np\->data); + /* List deletion */ + n1 = LIST_FIRST(&head); + while (n1 != NULL) { + n2 = LIST_NEXT(n1, entries); + free(n1); + n1 = n2; + } + LIST_INIT(&head); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR insque (3), +.BR queue (7) diff --git a/man/man3/llabs.3 b/man/man3/llabs.3 new file mode 100644 index 0000000..97db8d2 --- /dev/null +++ b/man/man3/llabs.3 @@ -0,0 +1 @@ +.so man3/abs.3 diff --git a/man/man3/lldiv.3 b/man/man3/lldiv.3 new file mode 100644 index 0000000..934824e --- /dev/null +++ b/man/man3/lldiv.3 @@ -0,0 +1 @@ +.so man3/div.3 diff --git a/man/man3/llrint.3 b/man/man3/llrint.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man/man3/llrint.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man/man3/llrintf.3 b/man/man3/llrintf.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man/man3/llrintf.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man/man3/llrintl.3 b/man/man3/llrintl.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man/man3/llrintl.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man/man3/llround.3 b/man/man3/llround.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man/man3/llround.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man/man3/llroundf.3 b/man/man3/llroundf.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man/man3/llroundf.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man/man3/llroundl.3 b/man/man3/llroundl.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man/man3/llroundl.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man/man3/localeconv.3 b/man/man3/localeconv.3 new file mode 100644 index 0000000..0077714 --- /dev/null +++ b/man/man3/localeconv.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:01:20 1993 by Rik Faith (faith@cs.unc.edu) +.TH localeconv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +localeconv \- get numeric formatting information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B struct lconv *localeconv(void); +.fi +.SH DESCRIPTION +The +.BR localeconv () +function returns a pointer to a +.I struct lconv +for the current locale. +This structure is shown in +.BR locale (7), +and contains all values associated with the locale categories +.B LC_NUMERIC +and +.BR LC_MONETARY . +Programs may also use the functions +.BR printf (3) +and +.BR strfmon (3), +which behave according to the actual locale in use. +.SH RETURN VALUE +The +.BR localeconv () +function returns a pointer to a filled in +.IR "struct lconv" . +This structure may be (in glibc, +.IR is ) +statically allocated, and may be overwritten by subsequent calls. +According to POSIX, +the caller should not modify the contents of this structure. +The +.BR localeconv () +function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR localeconv () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:localeconv locale +T} +.TE +.SH STANDARDS +C11. +.SH HISTORY +C89. +.SH BUGS +The +.BR printf (3) +family of functions may or may not honor the current locale. +.SH SEE ALSO +.BR locale (1), +.BR localedef (1), +.BR isalpha (3), +.BR nl_langinfo (3), +.BR setlocale (3), +.BR strcoll (3), +.BR strftime (3), +.BR locale (7) diff --git a/man/man3/localtime.3 b/man/man3/localtime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/localtime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/localtime_r.3 b/man/man3/localtime_r.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/localtime_r.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/lockf.3 b/man/man3/lockf.3 new file mode 100644 index 0000000..c86895a --- /dev/null +++ b/man/man3/lockf.3 @@ -0,0 +1,179 @@ +'\" t +.\" Copyright 1997 Nicolás Lichtmaier +.\" Created Thu Aug 7 00:44:00 ART 1997 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Added section stuff, aeb, 2002-04-22. +.\" Corrected include file, drepper, 2003-06-15. +.\" +.TH lockf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lockf \- apply, test or remove a POSIX lock on an open file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int lockf(int " fd ", int " op ", off_t " len ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR lockf (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +Apply, test, or remove a POSIX lock on a section of an open file. +The file is specified by +.IR fd , +a file descriptor open for writing, the action by +.IR op , +and the section consists of byte positions +.IR pos .. pos + len \-1 +if +.I len +is positive, and +.IR pos \- len .. pos \-1 +if +.I len +is negative, where +.I pos +is the current file position, and if +.I len +is zero, the section extends from the current file position to +infinity, encompassing the present and future end-of-file positions. +In all cases, the section may extend past current end-of-file. +.P +On Linux, +.BR lockf () +is just an interface on top of +.BR fcntl (2) +locking. +Many other systems implement +.BR lockf () +in this way, but note that POSIX.1 leaves the relationship between +.BR lockf () +and +.BR fcntl (2) +locks unspecified. +A portable application should probably avoid mixing calls +to these interfaces. +.P +Valid operations are given below: +.TP +.B F_LOCK +Set an exclusive lock on the specified section of the file. +If (part of) this section is already locked, the call +blocks until the previous lock is released. +If this section overlaps an earlier locked section, +both are merged. +File locks are released as soon as the process holding the locks +closes some file descriptor for the file. +A child process does not inherit these locks. +.TP +.B F_TLOCK +Same as +.B F_LOCK +but the call never blocks and returns an error instead if the file is +already locked. +.TP +.B F_ULOCK +Unlock the indicated section of the file. +This may cause a locked section to be split into two locked sections. +.TP +.B F_TEST +Test the lock: return 0 if the specified section +is unlocked or locked by this process; return \-1, set +.I errno +to +.B EAGAIN +.RB ( EACCES +on some other systems), +if another process holds a lock. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.BR EACCES " or " EAGAIN +The file is locked and +.B F_TLOCK +or +.B F_TEST +was specified, or the operation is prohibited because the file has +been memory-mapped by another process. +.TP +.B EBADF +.I fd +is not an open file descriptor; or +.I op +is +.B F_LOCK +or +.B F_TLOCK +and +.I fd +is not a writable file descriptor. +.TP +.B EDEADLK +.I op +was +.B F_LOCK +and this lock operation would cause a deadlock. +.TP +.B EINTR +While waiting to acquire a lock, the call was interrupted by +delivery of a signal caught by a handler; see +.BR signal (7). +.TP +.B EINVAL +An invalid operation was specified in +.IR op . +.TP +.B ENOLCK +Too many segment locks open, lock table is full. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lockf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.SH SEE ALSO +.BR fcntl (2), +.BR flock (2) +.P +.I locks.txt +and +.I mandatory\-locking.txt +in the Linux kernel source directory +.I Documentation/filesystems +(on older kernels, these files are directly under the +.I Documentation +directory, and +.I mandatory\-locking.txt +is called +.IR mandatory.txt ) diff --git a/man/man3/log.3 b/man/man3/log.3 new file mode 100644 index 0000000..29ec350 --- /dev/null +++ b/man/man3/log.3 @@ -0,0 +1,140 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH log 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +log, logf, logl \- natural logarithmic function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double log(double " x ); +.BI "float logf(float " x ); +.BI "long double logl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR logf (), +.BR logl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the natural logarithm of +.IR x . +.SH RETURN VALUE +On success, these functions return the natural logarithm of +.IR x . +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is 1, the result is +0. +.P +If +.I x +is positive infinity, +positive infinity is returned. +.P +If +.I x +is zero, +then a pole error occurs, and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +.P +If +.I x +is negative (including negative infinity), then +a domain error occurs, and a NaN (not a number) is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is negative +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is zero +.I errno +is set to +.BR ERANGE . +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR log (), +.BR logf (), +.BR logl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +In glibc 2.5 and earlier, +taking the +.BR log () +of a NaN produces a bogus invalid floating-point +.RB ( FE_INVALID ) +exception. +.SH SEE ALSO +.BR cbrt (3), +.BR clog (3), +.BR log10 (3), +.BR log1p (3), +.BR log2 (3), +.BR sqrt (3) diff --git a/man/man3/log10.3 b/man/man3/log10.3 new file mode 100644 index 0000000..33bdaf0 --- /dev/null +++ b/man/man3/log10.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH log10 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +log10, log10f, log10l \- base-10 logarithmic function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double log10(double " x ); +.BI "float log10f(float " x ); +.BI "long double log10l(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR log10f (), +.BR log10l (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the base-10 logarithm of +.IR x . +.SH RETURN VALUE +On success, these functions return the base-10 logarithm of +.IR x . +.P +For special cases, including where +.I x +is 0, 1, negative, infinity, or NaN, see +.BR log (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +For a discussion of the errors that can occur for these functions, see +.BR log (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR log10 (), +.BR log10f (), +.BR log10l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR cbrt (3), +.BR clog10 (3), +.BR exp10 (3), +.BR log (3), +.BR log2 (3), +.BR sqrt (3) diff --git a/man/man3/log10f.3 b/man/man3/log10f.3 new file mode 100644 index 0000000..dfa5796 --- /dev/null +++ b/man/man3/log10f.3 @@ -0,0 +1 @@ +.so man3/log10.3 diff --git a/man/man3/log10l.3 b/man/man3/log10l.3 new file mode 100644 index 0000000..dfa5796 --- /dev/null +++ b/man/man3/log10l.3 @@ -0,0 +1 @@ +.so man3/log10.3 diff --git a/man/man3/log1p.3 b/man/man3/log1p.3 new file mode 100644 index 0000000..0eadb1f --- /dev/null +++ b/man/man3/log1p.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright 1995 Jim Van Zandt +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH log1p 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +log1p, log1pf, log1pl \- logarithm of 1 plus argument +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double log1p(double " x ); +.BI "float log1pf(float " x ); +.BI "long double log1pl(long double " x ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.nf +.BR log1p (): + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR log1pf (), +.BR log1pl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return a value equivalent to +.P +.nf + log (1 + \fIx\fP) +.fi +.P +The result is computed in a way +that is accurate even if the value of +.I x +is near zero. +.SH RETURN VALUE +On success, these functions return the natural logarithm of +.IR "(1\ +\ x)" . +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is positive infinity, positive infinity is returned. +.P +If +.I x +is \-1, a pole error occurs, +and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +.P +If +.I x +is less than \-1 (including negative infinity), +a domain error occurs, +and a NaN (not a number) is returned. +.\" POSIX.1 specifies a possible range error if x is subnormal +.\" glibc 2.8 doesn't do this +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is less than \-1 +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is \-1 +.I errno +is set to +.B ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR log1p (), +.BR log1pf (), +.BR log1pl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.\" BSD +.SH BUGS +Before glibc 2.22, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6792 +.I errno +to +.B EDOM +when a domain error occurred. +.P +Before glibc 2.22, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6792 +.I errno +to +.B ERANGE +when a range error occurred. +.SH SEE ALSO +.BR exp (3), +.BR expm1 (3), +.BR log (3) diff --git a/man/man3/log1pf.3 b/man/man3/log1pf.3 new file mode 100644 index 0000000..a4dec80 --- /dev/null +++ b/man/man3/log1pf.3 @@ -0,0 +1 @@ +.so man3/log1p.3 diff --git a/man/man3/log1pl.3 b/man/man3/log1pl.3 new file mode 100644 index 0000000..a4dec80 --- /dev/null +++ b/man/man3/log1pl.3 @@ -0,0 +1 @@ +.so man3/log1p.3 diff --git a/man/man3/log2.3 b/man/man3/log2.3 new file mode 100644 index 0000000..64ea6d3 --- /dev/null +++ b/man/man3/log2.3 @@ -0,0 +1,93 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH log2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +log2, log2f, log2l \- base-2 logarithmic function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double log2(double " x ); +.BI "float log2f(float " x ); +.BI "long double log2l(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR log2 (), +.BR log2f (), +.BR log2l (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return the base-2 logarithm of +.IR x . +.SH RETURN VALUE +On success, these functions return the base-2 logarithm of +.IR x . +.P +For special cases, including where +.I x +is 0, 1, negative, infinity, or NaN, see +.BR log (3). +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +For a discussion of the errors that can occur for these functions, see +.BR log (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR log2 (), +.BR log2f (), +.BR log2l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD. +.SH SEE ALSO +.BR cbrt (3), +.BR clog2 (3), +.BR log (3), +.BR log10 (3), +.BR sqrt (3) diff --git a/man/man3/log2f.3 b/man/man3/log2f.3 new file mode 100644 index 0000000..23aeb4a --- /dev/null +++ b/man/man3/log2f.3 @@ -0,0 +1 @@ +.so man3/log2.3 diff --git a/man/man3/log2l.3 b/man/man3/log2l.3 new file mode 100644 index 0000000..23aeb4a --- /dev/null +++ b/man/man3/log2l.3 @@ -0,0 +1 @@ +.so man3/log2.3 diff --git a/man/man3/logb.3 b/man/man3/logb.3 new file mode 100644 index 0000000..9205905 --- /dev/null +++ b/man/man3/logb.3 @@ -0,0 +1,142 @@ +'\" t +.\" Copyright 2004 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Inspired by a page by Walter Harms created 2002-08-10 +.\" +.TH logb 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +logb, logbf, logbl \- get exponent of a floating-point value +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double logb(double " x ); +.BI "float logbf(float " x ); +.BI "long double logbl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR logb (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR logbf (), +.BR logbl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions extract the exponent from the +internal floating-point representation of +.I x +and return it as a floating-point value. +The integer constant +.BR FLT_RADIX , +defined in +.IR , +indicates the radix used for the system's floating-point representation. +If +.B FLT_RADIX +is 2, +.BI logb( x ) +is similar to +.BI floor(log2(fabs( x )))\f[R],\f[] +except that the latter may give an incorrect integer +due to intermediate rounding. +.P +If +.I x +is subnormal, +.BR logb () +returns the exponent +.I x +would have if it were normalized. +.SH RETURN VALUE +On success, these functions return the exponent of +.IR x . +.P +If +.I x +is a NaN, +a NaN is returned. +.P +If +.I x +is zero, then a pole error occurs, and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +.P +If +.I x +is negative infinity or positive infinity, then +positive infinity is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Pole error: \fIx\fP is 0 +.\" .I errno +.\" is set to +.\" .BR ERANGE . +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.P +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" log(), log2(), log10() do set errno +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6793 +.\" +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR logb (), +.BR logbf (), +.BR logbl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.TP +.BR logb () +4.3BSD +(see IEEE.3 in the 4.3BSD manual). +.SH SEE ALSO +.BR ilogb (3), +.BR log (3) diff --git a/man/man3/logbf.3 b/man/man3/logbf.3 new file mode 100644 index 0000000..4a70936 --- /dev/null +++ b/man/man3/logbf.3 @@ -0,0 +1 @@ +.so man3/logb.3 diff --git a/man/man3/logbl.3 b/man/man3/logbl.3 new file mode 100644 index 0000000..4a70936 --- /dev/null +++ b/man/man3/logbl.3 @@ -0,0 +1 @@ +.so man3/logb.3 diff --git a/man/man3/logf.3 b/man/man3/logf.3 new file mode 100644 index 0000000..7807e76 --- /dev/null +++ b/man/man3/logf.3 @@ -0,0 +1 @@ +.so man3/log.3 diff --git a/man/man3/login.3 b/man/man3/login.3 new file mode 100644 index 0000000..b0df3ad --- /dev/null +++ b/man/man3/login.3 @@ -0,0 +1,151 @@ +'\" t +.\" Derived from text written by Martin Schulze (or taken from glibc.info) +.\" and text written by Paul Thompson - both copyright 2002. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH login 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +login, logout \- write utmp and wtmp entries +.SH LIBRARY +System utilities library +.RI ( libutil ", " \-lutil ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void login(const struct utmp *" ut ); +.BI "int logout(const char *" ut_line ); +.fi +.SH DESCRIPTION +The utmp file records who is currently using the system. +The wtmp file records all logins and logouts. +See +.BR utmp (5). +.P +The function +.BR login () +takes the supplied +.IR "struct utmp" , +.IR ut , +and writes it to both the utmp and the wtmp file. +.P +The function +.BR logout () +clears the entry in the utmp file again. +.SS GNU details +More precisely, +.BR login () +takes the argument +.I ut +struct, fills the field +.I ut\->ut_type +(if there is such a field) with the value +.BR USER_PROCESS , +and fills the field +.I ut\->ut_pid +(if there is such a field) with the process ID of the calling process. +Then it tries to fill the field +.IR ut\->ut_line . +It takes the first of +.IR stdin , +.IR stdout , +.I stderr +that is a terminal, and +stores the corresponding pathname minus a possible leading +.I /dev/ +into this field, and then writes the struct to the utmp file. +On the other hand, +if no terminal name was found, this field is filled with "???" +and the struct is not written to the utmp file. +After this, the struct is written to the wtmp file. +.P +The +.BR logout () +function searches the utmp file for an entry matching the +.I ut_line +argument. +If a record is found, it is updated by zeroing out the +.I ut_name +and +.I ut_host +fields, updating the +.I ut_tv +timestamp field and setting +.I ut_type +(if there is such a field) to +.BR DEAD_PROCESS . +.SH RETURN VALUE +The +.BR logout () +function returns 1 if the entry was successfully written to the +database, or 0 if an error occurred. +.SH FILES +.TP +.I /var/run/utmp +user accounting database, configured through +.B _PATH_UTMP +in +.I +.TP +.I /var/log/wtmp +user accounting log file, configured through +.B _PATH_WTMP +in +.I +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR login (), +.BR logout () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent +sig:ALRM timer +T} +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR login () +and +.BR logout () +calls those functions, +so we use race:utent to remind users. +.SH VERSIONS +The member +.I ut_user +of +.I struct utmp +is called +.I ut_name +in BSD. +Therefore, +.I ut_name +is defined as an alias for +.I ut_user +in +.IR . +.SH STANDARDS +BSD. +.SH SEE ALSO +.BR getutent (3), +.BR utmp (5) diff --git a/man/man3/login_tty.3 b/man/man3/login_tty.3 new file mode 100644 index 0000000..fb4952d --- /dev/null +++ b/man/man3/login_tty.3 @@ -0,0 +1 @@ +.so man3/openpty.3 diff --git a/man/man3/logl.3 b/man/man3/logl.3 new file mode 100644 index 0000000..7807e76 --- /dev/null +++ b/man/man3/logl.3 @@ -0,0 +1 @@ +.so man3/log.3 diff --git a/man/man3/logout.3 b/man/man3/logout.3 new file mode 100644 index 0000000..a1ee672 --- /dev/null +++ b/man/man3/logout.3 @@ -0,0 +1 @@ +.so man3/login.3 diff --git a/man/man3/logwtmp.3 b/man/man3/logwtmp.3 new file mode 100644 index 0000000..0dc4dea --- /dev/null +++ b/man/man3/logwtmp.3 @@ -0,0 +1 @@ +.so man3/updwtmp.3 diff --git a/man/man3/longjmp.3 b/man/man3/longjmp.3 new file mode 100644 index 0000000..7cf497f --- /dev/null +++ b/man/man3/longjmp.3 @@ -0,0 +1 @@ +.so man3/setjmp.3 diff --git a/man/man3/lrand48.3 b/man/man3/lrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/lrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/lrand48_r.3 b/man/man3/lrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/lrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/lrint.3 b/man/man3/lrint.3 new file mode 100644 index 0000000..990b8d1 --- /dev/null +++ b/man/man3/lrint.3 @@ -0,0 +1,110 @@ +'\" t +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH lrint 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lrint, lrintf, lrintl, llrint, llrintf, llrintl \- round to nearest integer +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long lrint(double " x ); +.BI "long lrintf(float " x ); +.BI "long lrintl(long double " x ); +.P +.BI "long long llrint(double " x ); +.BI "long long llrintf(float " x ); +.BI "long long llrintl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions round their argument to the nearest integer value, +using the current rounding direction (see +.BR fesetround (3)). +.P +Note that unlike the +.BR rint (3) +family of functions, +the return type of these functions differs from +that of their arguments. +.SH RETURN VALUE +These functions return the rounded integer value. +.P +If +.I x +is a NaN or an infinity, +or the rounded value is too large to be stored in a +.I long +.RI ( "long long" +in the case of the +.B ll* +functions), +then a domain error occurs, and the return value is unspecified. +.\" The return value is -(LONG_MAX - 1) or -(LLONG_MAX -1) +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.P +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6798 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lrint (), +.BR lrintf (), +.BR lrintl (), +.BR llrint (), +.BR llrintf (), +.BR llrintl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lround (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) diff --git a/man/man3/lrintf.3 b/man/man3/lrintf.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man/man3/lrintf.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man/man3/lrintl.3 b/man/man3/lrintl.3 new file mode 100644 index 0000000..d1c0af3 --- /dev/null +++ b/man/man3/lrintl.3 @@ -0,0 +1 @@ +.so man3/lrint.3 diff --git a/man/man3/lround.3 b/man/man3/lround.3 new file mode 100644 index 0000000..24533f7 --- /dev/null +++ b/man/man3/lround.3 @@ -0,0 +1,113 @@ +'\" t +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH lround 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lround, lroundf, lroundl, llround, llroundf, llroundl \- round to +nearest integer +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long lround(double " x ); +.BI "long lroundf(float " x ); +.BI "long lroundl(long double " x ); +.P +.BI "long long llround(double " x ); +.BI "long long llroundf(float " x ); +.BI "long long llroundl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions round their argument to the nearest integer value, +rounding halfway cases away from zero, +regardless of the current rounding direction (see +.BR fenv (3)). +.P +Note that unlike the +.BR round (3) +and +.BR ceil (3), +functions, the return type of these functions differs from +that of their arguments. +.SH RETURN VALUE +These functions return the rounded integer value. +.P +If +.I x +is a NaN or an infinity, +or the rounded value is too large to be stored in a +.I long +.RI ( "long long" +in the case of the +.B ll* +functions), +then a domain error occurs, and the return value is unspecified. +.\" The return value is -(LONG_MAX - 1) or -(LLONG_MAX -1) +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.P +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6797 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lround (), +.BR lroundf (), +.BR lroundl (), +.BR llround (), +.BR llroundf (), +.BR llroundl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) diff --git a/man/man3/lroundf.3 b/man/man3/lroundf.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man/man3/lroundf.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man/man3/lroundl.3 b/man/man3/lroundl.3 new file mode 100644 index 0000000..bcc9b0f --- /dev/null +++ b/man/man3/lroundl.3 @@ -0,0 +1 @@ +.so man3/lround.3 diff --git a/man/man3/lsearch.3 b/man/man3/lsearch.3 new file mode 100644 index 0000000..ea25d5f --- /dev/null +++ b/man/man3/lsearch.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 1995 Jim Van Zandt +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Corrected prototype and include, aeb, 990927 +.TH lsearch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lfind, lsearch \- linear search of an array +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *lfind(const void " key [. size "], \ +const void " base [. size " * ." nmemb ], +.BI " size_t *" nmemb ", size_t " size , +.BI " int(*" compar ")(const void [." size "], \ +const void [." size ])); +.BI "void *lsearch(const void " key [. size "], \ +void " base [. size " * ." nmemb ], +.BI " size_t *" nmemb ", size_t " size , +.BI " int(*" compar ")(const void [." size "], \ +const void [." size ])); +.fi +.SH DESCRIPTION +.BR lfind () +and +.BR lsearch () +perform a linear search for +.I key +in the array +.I base +which has +.I *nmemb +elements of +.I size +bytes each. +The comparison function referenced by +.I compar +is expected to have two arguments which point to the +.I key +object and to an array member, in that order, and which +returns zero if the +.I key +object matches the array member, and +nonzero otherwise. +.P +If +.BR lsearch () +does not find a matching element, then the +.I key +object is inserted at the end of the table, and +.I *nmemb +is +incremented. +In particular, one should know that a matching element +exists, or that more room is available. +.SH RETURN VALUE +.BR lfind () +returns a pointer to a matching member of the array, or +NULL if no match is found. +.BR lsearch () +returns a pointer to +a matching member of the array, or to the newly added member if no +match is found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lfind (), +.BR lsearch () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +libc-4.6.27. +.SH BUGS +The naming is unfortunate. +.SH SEE ALSO +.BR bsearch (3), +.BR hsearch (3), +.BR tsearch (3) diff --git a/man/man3/lseek64.3 b/man/man3/lseek64.3 new file mode 100644 index 0000000..2e1d7ec --- /dev/null +++ b/man/man3/lseek64.3 @@ -0,0 +1,206 @@ +'\" t +.\" Copyright 2004 Andries Brouwer . +.\" and Copyright (c) 2020 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH lseek64 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lseek64 \- reposition 64-bit read/write file offset +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _LARGEFILE64_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.B #include +.P +.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence ); +.fi +.SH DESCRIPTION +The +.BR lseek () +family of functions reposition the offset of the open file associated +with the file descriptor +.I fd +to +.I offset +bytes relative to the start, current position, or end of the file, +when +.I whence +has the value +.BR SEEK_SET , +.BR SEEK_CUR , +or +.BR SEEK_END , +respectively. +.P +For more details, return value, and errors, see +.BR lseek (2). +.P +Four interfaces are available: +.BR lseek (), +.BR lseek64 (), +.BR llseek (), +and +.BR _llseek (). +.\" +.\" For some background details, see: +.\" https://lore.kernel.org/linux-man/CAKgNAkhNSWR3uYhYYaxx74fZfJ3JrpfAAPVrK0AFk_cAOUsbDg@mail.gmail.com/ +.\" +.SS lseek() +Prototype: +.P +.in +4n +.EX +.BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); +.EE +.in +.P +The C library's +.BR lseek () +wrapper function uses the type +.IR off_t . +This is a 32-bit signed type on 32-bit architectures, unless one +compiles with +.P +.in +4n +.EX +#define _FILE_OFFSET_BITS 64 +.EE +.in +.P +in which case it is a 64-bit signed type. +.SS lseek64() +Prototype: +.P +.in +4n +.EX +.BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence ); +.EE +.in +.P +The +.BR lseek64 () +library function uses a 64-bit type even when +.I off_t +is a 32-bit type. +Its prototype (and the type +.IR off64_t ) +is available only when one compiles with +.P +.in +4n +.EX +#define _LARGEFILE64_SOURCE +.EE +.in +.P +The function +.BR lseek64 () +.\" in glibc 2.0.94, not in glibc 2.0.6 +is available since glibc 2.1. +.\" +.SS llseek() +Prototype: +.P +.in +4n +.EX +.BI "loff_t llseek(int " fd ", loff_t " offset ", int " whence ); +.EE +.in +.P +The type +.I loff_t +is a 64-bit signed type. +The +.BR llseek () +library function is available in glibc and works without special defines. +However, the glibc headers do not provide a prototype. +Users should add +the above prototype, or something equivalent, to their own source. +When users complained about data loss caused by a miscompilation of +.BR e2fsck (8), +glibc 2.1.3 added the link-time warning +.P +.in +4n +"the \`llseek\' function may be dangerous; use \`lseek64\' instead." +.in +.P +This makes this function unusable if one desires a warning-free +compilation. +.P +Since glibc 2.28, +.\" glibc commit 5c5c0dd747070db624c8e2c43691cec854f114ef +this function symbol is no longer available to newly linked applications. +.\" +.SS _llseek() +On 32-bit architectures, +this is the system call that is used (by the C library wrapper functions) +to implement all of the above functions. +The prototype is: +.P +.in +4n +.EX +.BI "int _llseek(int " fd ", off_t " offset_hi ", off_t " offset_lo , +.BI " loff_t *" result ", int " whence ); +.EE +.in +.P +For more details, see +.BR llseek (2). +.P +64-bit systems don't need an +.BR _llseek () +system call. +Instead, they have an +.BR lseek (2) +system call that supports 64-bit file offsets. +.\" In arch/x86/entry/syscalls/syscall_32.tbl, +.\" we see the following line: +.\" +.\" 140 i386 _llseek sys_llseek +.\" +.\" This is essentially telling us that 'sys_llseek' (the name generated +.\" by SYSCALL_DEFINE5(llseek...)) is exposed to user-space as system call +.\" number 140, and that system call number will (IIUC) be exposed in +.\" autogenerated headers with the name "__NR__llseek" (i.e., "_llseek"). +.\" The "i386" is telling us that this happens in i386 (32-bit Intel). +.\" There is nothing equivalent on x86-64, because 64 bit systems don't +.\" need an _llseek system call. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR lseek64 () +T} Thread safety MT-Safe +.TE +.SH NOTES +.BR lseek64 () +is one of the functions that was specified in the Large File Summit (LFS) +specification that was completed in 1996. +The purpose of the specification was to provide transitional support +that allowed applications on 32-bit systems to access +files whose size exceeds that which can be represented with a 32-bit +.I off_t +type. +As noted above, this symbol is exposed by header files if the +.B _LARGEFILE64_SOURCE +feature test macro is defined. +ALternatively, on a 32-bit system, the symbol +.I lseek +is aliased to +.I lseek64 +if the macro +.B _FILE_OFFSET_BITS +is defined with the value 64. +.SH SEE ALSO +.BR llseek (2), +.BR lseek (2) diff --git a/man/man3/lutimes.3 b/man/man3/lutimes.3 new file mode 100644 index 0000000..3145980 --- /dev/null +++ b/man/man3/lutimes.3 @@ -0,0 +1 @@ +.so man3/futimes.3 diff --git a/man/man3/major.3 b/man/man3/major.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man/man3/major.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man/man3/makecontext.3 b/man/man3/makecontext.3 new file mode 100644 index 0000000..a478fd9 --- /dev/null +++ b/man/man3/makecontext.3 @@ -0,0 +1,236 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2006-08-02, mtk, Added example program +.\" +.TH makecontext 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +makecontext, swapcontext \- manipulate user context +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void makecontext(ucontext_t *" ucp ", void (*" func ")(), int " argc \ +", ...);" +.BI "int swapcontext(ucontext_t *restrict " oucp , +.BI " const ucontext_t *restrict " ucp ); +.fi +.SH DESCRIPTION +In a System V-like environment, one has the type +.I ucontext_t +(defined in +.I +and described in +.BR getcontext (3)) +and the four functions +.BR getcontext (3), +.BR setcontext (3), +.BR makecontext (), +and +.BR swapcontext () +that allow user-level context switching +between multiple threads of control within a process. +.P +The +.BR makecontext () +function modifies the context pointed to +by \fIucp\fP (which was obtained from a call to +.BR getcontext (3)). +Before invoking +.BR makecontext (), +the caller must allocate a new stack +for this context and assign its address to \fIucp\->uc_stack\fP, +and define a successor context and +assign its address to \fIucp\->uc_link\fP. +.P +When this context is later activated (using +.BR setcontext (3) +or +.BR swapcontext ()) +the function \fIfunc\fP is called, +and passed the series of integer +.RI ( int ) +arguments that follow +.IR argc ; +the caller must specify the number of these arguments in +.IR argc . +When this function returns, the successor context is activated. +If the successor context pointer is NULL, the thread exits. +.P +The +.BR swapcontext () +function saves the current context in +the structure pointed to by \fIoucp\fP, and then activates the +context pointed to by \fIucp\fP. +.SH RETURN VALUE +When successful, +.BR swapcontext () +does not return. +(But we may return later, in case \fIoucp\fP is +activated, in which case it looks like +.BR swapcontext () +returns 0.) +On error, +.BR swapcontext () +returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient stack space left. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR makecontext () +T} Thread safety T{ +.na +.nh +MT-Safe race:ucp +T} +T{ +.na +.nh +.BR swapcontext () +T} Thread safety T{ +.na +.nh +MT-Safe race:oucp race:ucp +T} +.TE +.SH STANDARDS +None. +.SH HISTORY +glibc 2.1. +SUSv2, POSIX.1-2001. +Removed in POSIX.1-2008, +citing portability issues, and +recommending that applications be rewritten to use POSIX threads instead. +.SH NOTES +The interpretation of \fIucp\->uc_stack\fP is just as in +.BR sigaltstack (2), +namely, this struct contains the start and length of a memory area +to be used as the stack, regardless of the direction of growth of +the stack. +Thus, it is not necessary for the user program to +worry about this direction. +.P +On architectures where +.I int +and pointer types are the same size +(e.g., x86-32, where both types are 32 bits), +you may be able to get away with passing pointers as arguments to +.BR makecontext () +following +.IR argc . +However, doing this is not guaranteed to be portable, +is undefined according to the standards, +and won't work on architectures where pointers are larger than +.IR int s. +Nevertheless, starting with glibc 2.8, glibc makes some changes to +.BR makecontext (), +to permit this on some 64-bit architectures (e.g., x86-64). +.SH EXAMPLES +The example program below demonstrates the use of +.BR getcontext (3), +.BR makecontext (), +and +.BR swapcontext (). +Running the program produces the following output: +.P +.in +4n +.EX +.RB "$" " ./a.out" +main: swapcontext(&uctx_main, &uctx_func2) +func2: started +func2: swapcontext(&uctx_func2, &uctx_func1) +func1: started +func1: swapcontext(&uctx_func1, &uctx_func2) +func2: returning +func1: returning +main: exiting +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (makecontext.c) +.EX +#include +#include +#include +\& +static ucontext_t uctx_main, uctx_func1, uctx_func2; +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void +func1(void) +{ + printf("%s: started\en", __func__); + printf("%s: swapcontext(&uctx_func1, &uctx_func2)\en", __func__); + if (swapcontext(&uctx_func1, &uctx_func2) == \-1) + handle_error("swapcontext"); + printf("%s: returning\en", __func__); +} +\& +static void +func2(void) +{ + printf("%s: started\en", __func__); + printf("%s: swapcontext(&uctx_func2, &uctx_func1)\en", __func__); + if (swapcontext(&uctx_func2, &uctx_func1) == \-1) + handle_error("swapcontext"); + printf("%s: returning\en", __func__); +} +\& +int +main(int argc, char *argv[]) +{ + char func1_stack[16384]; + char func2_stack[16384]; +\& + if (getcontext(&uctx_func1) == \-1) + handle_error("getcontext"); + uctx_func1.uc_stack.ss_sp = func1_stack; + uctx_func1.uc_stack.ss_size = sizeof(func1_stack); + uctx_func1.uc_link = &uctx_main; + makecontext(&uctx_func1, func1, 0); +\& + if (getcontext(&uctx_func2) == \-1) + handle_error("getcontext"); + uctx_func2.uc_stack.ss_sp = func2_stack; + uctx_func2.uc_stack.ss_size = sizeof(func2_stack); + /* Successor context is f1(), unless argc > 1 */ + uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1; + makecontext(&uctx_func2, func2, 0); +\& + printf("%s: swapcontext(&uctx_main, &uctx_func2)\en", __func__); + if (swapcontext(&uctx_main, &uctx_func2) == \-1) + handle_error("swapcontext"); +\& + printf("%s: exiting\en", __func__); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sigaction (2), +.BR sigaltstack (2), +.BR sigprocmask (2), +.BR getcontext (3), +.BR sigsetjmp (3) diff --git a/man/man3/makedev.3 b/man/man3/makedev.3 new file mode 100644 index 0000000..019ac09 --- /dev/null +++ b/man/man3/makedev.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH makedev 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +makedev, major, minor \- manage a device number +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "dev_t makedev(unsigned int " maj ", unsigned int " min ); +.P +.BI "unsigned int major(dev_t " dev ); +.BI "unsigned int minor(dev_t " dev ); +.fi +.SH DESCRIPTION +A device ID consists of two parts: +a major ID, identifying the class of the device, +and a minor ID, identifying a specific instance of a device in that class. +A device ID is represented using the type +.IR dev_t . +.P +Given major and minor device IDs, +.BR makedev () +combines these to produce a device ID, returned as the function result. +This device ID can be given to +.BR mknod (2), +for example. +.P +The +.BR major () +and +.BR minor () +functions perform the converse task: given a device ID, +they return, respectively, the major and minor components. +These macros can be useful to, for example, +decompose the device IDs in the structure returned by +.BR stat (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR makedev (), +.BR major (), +.BR minor () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The BSDs expose the definitions for these macros via +.IR . +.SH STANDARDS +None. +.SH HISTORY +BSD, HP-UX, Solaris, AIX, Irix. +.\" The header location is inconsistent: +.\" Could be sys/mkdev.h, sys/sysmacros.h, or sys/types.h. +.P +These interfaces are defined as macros. +Since glibc 2.3.3, +they have been aliases for three GNU-specific functions: +.BR gnu_dev_makedev (), +.BR gnu_dev_major (), +and +.BR gnu_dev_minor (). +The latter names are exported, but the traditional names are more portable. +.P +Depending on the version, +glibc also exposes definitions for these macros from +.I +if suitable feature test macros are defined. +However, this behavior was deprecated in glibc 2.25, +.\" glibc commit dbab6577c6684c62bd2521c1c29dc25c3cac966f +and since glibc 2.28, +.\" glibc commit e16deca62e16f645213dffd4ecd1153c37765f17 +.I +no longer provides these definitions. +.SH SEE ALSO +.BR mknod (2), +.BR stat (2) diff --git a/man/man3/mallinfo.3 b/man/man3/mallinfo.3 new file mode 100644 index 0000000..aa4b2cc --- /dev/null +++ b/man/man3/mallinfo.3 @@ -0,0 +1,338 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mallinfo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mallinfo, mallinfo2 \- obtain memory allocation information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B struct mallinfo mallinfo(void); +.B struct mallinfo2 mallinfo2(void); +.fi +.SH DESCRIPTION +These functions return a copy of a structure containing information about +memory allocations performed by +.BR malloc (3) +and related functions. +The structure returned by each function contains the same fields. +However, the older function, +.BR mallinfo (), +is deprecated since the type used for the fields is too small (see BUGS). +.P +Note that not all allocations are visible to these functions; +see BUGS and consider using +.BR malloc_info (3) +instead. +.P +The +.I mallinfo2 +structure returned by +.BR mallinfo2 () +is defined as follows: +.P +.in +4n +.EX +struct mallinfo2 { + size_t arena; /* Non\-mmapped space allocated (bytes) */ + size_t ordblks; /* Number of free chunks */ + size_t smblks; /* Number of free fastbin blocks */ + size_t hblks; /* Number of mmapped regions */ + size_t hblkhd; /* Space allocated in mmapped regions + (bytes) */ + size_t usmblks; /* See below */ + size_t fsmblks; /* Space in freed fastbin blocks (bytes) */ + size_t uordblks; /* Total allocated space (bytes) */ + size_t fordblks; /* Total free space (bytes) */ + size_t keepcost; /* Top\-most, releasable space (bytes) */ +}; +.EE +.in +.P +The +.I mallinfo +structure returned by the deprecated +.BR mallinfo () +function is exactly the same, except that the fields are typed as +.IR int . +.P +The structure fields contain the following information: +.TP 10 +.I arena +The total amount of memory allocated by means other than +.BR mmap (2) +(i.e., memory allocated on the heap). +This figure includes both in-use blocks and blocks on the free list. +.TP +.I ordblks +The number of ordinary (i.e., non-fastbin) free blocks. +.TP +.I smblks +.\" the glibc info page wrongly says this field is unused +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746 +The number of fastbin free blocks (see +.BR mallopt (3)). +.TP +.I hblks +The number of blocks currently allocated using +.BR mmap (2). +(See the discussion of +.B M_MMAP_THRESHOLD +in +.BR mallopt (3).) +.TP +.I hblkhd +The number of bytes in blocks currently allocated using +.BR mmap (2). +.TP +.I usmblks +This field is unused, and is always 0. +.\" It seems to have been zero since at least as far back as glibc 2.15 +Historically, it was the "highwater mark" for allocated space\[em]that is, +the maximum amount of space that was ever allocated (in bytes); +this field was maintained only in nonthreading environments. +.TP +.I fsmblks +.\" the glibc info page wrongly says this field is unused +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746 +The total number of bytes in fastbin free blocks. +.TP +.I uordblks +The total number of bytes used by in-use allocations. +.TP +.I fordblks +The total number of bytes in free blocks. +.TP +.I keepcost +The total amount of releasable free space at the top +of the heap. +This is the maximum number of bytes that could ideally +(i.e., ignoring page alignment restrictions, and so on) be released by +.BR malloc_trim (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mallinfo (), +.BR mallinfo2 () +T} Thread safety T{ +.na +.nh +MT-Unsafe init const:mallopt +T} +.TE +.P +.BR mallinfo ()/ +.BR mallinfo2 () +would access some global internal objects. +If modify them with non-atomically, +may get inconsistent results. +The identifier +.I mallopt +in +.I const:mallopt +mean that +.BR mallopt () +would modify the global internal objects with atomics, that make sure +.BR mallinfo ()/ +.BR mallinfo2 () +is safe enough, others modify with non-atomically maybe not. +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR mallinfo () +glibc 2.0. +SVID. +.TP +.BR mallinfo2 () +.\" commit e3960d1c57e57f33e0e846d615788f4ede73b945 +glibc 2.33. +.SH BUGS +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=208 +.\" See the 24 Aug 2011 mail by Paul Pluzhnikov: +.\" "[patch] Fix mallinfo() to accumulate results for all arenas" +.\" on libc-alpha@sourceware.org +.B Information is returned for only the main memory allocation area. +Allocations in other arenas are excluded. +See +.BR malloc_stats (3) +and +.BR malloc_info (3) +for alternatives that include information about other arenas. +.P +The fields of the +.I mallinfo +structure that is returned by the older +.BR mallinfo () +function are typed as +.IR int . +However, because some internal bookkeeping values may be of type +.IR long , +the reported values may wrap around zero and thus be inaccurate. +.SH EXAMPLES +The program below employs +.BR mallinfo2 () +to retrieve memory allocation statistics before and after +allocating and freeing some blocks of memory. +The statistics are displayed on standard output. +.P +The first two command-line arguments specify the number and size of +blocks to be allocated with +.BR malloc (3). +.P +The remaining three arguments specify which of the allocated blocks +should be freed with +.BR free (3). +These three arguments are optional, and specify (in order): +the step size to be used in the loop that frees blocks +(the default is 1, meaning free all blocks in the range); +the ordinal position of the first block to be freed +(default 0, meaning the first allocated block); +and a number one greater than the ordinal position +of the last block to be freed +(default is one greater than the maximum block number). +If these three arguments are omitted, +then the defaults cause all allocated blocks to be freed. +.P +In the following example run of the program, +1000 allocations of 100 bytes are performed, +and then every second allocated block is freed: +.P +.in +4n +.EX +$ \fB./a.out 1000 100 2\fP +============== Before allocating blocks ============== +Total non\-mmapped bytes (arena): 0 +# of free chunks (ordblks): 1 +# of free fastbin blocks (smblks): 0 +# of mapped regions (hblks): 0 +Bytes in mapped regions (hblkhd): 0 +Max. total allocated space (usmblks): 0 +Free bytes held in fastbins (fsmblks): 0 +Total allocated space (uordblks): 0 +Total free space (fordblks): 0 +Topmost releasable block (keepcost): 0 +\& +============== After allocating blocks ============== +Total non\-mmapped bytes (arena): 135168 +# of free chunks (ordblks): 1 +# of free fastbin blocks (smblks): 0 +# of mapped regions (hblks): 0 +Bytes in mapped regions (hblkhd): 0 +Max. total allocated space (usmblks): 0 +Free bytes held in fastbins (fsmblks): 0 +Total allocated space (uordblks): 104000 +Total free space (fordblks): 31168 +Topmost releasable block (keepcost): 31168 +\& +============== After freeing blocks ============== +Total non\-mmapped bytes (arena): 135168 +# of free chunks (ordblks): 501 +# of free fastbin blocks (smblks): 0 +# of mapped regions (hblks): 0 +Bytes in mapped regions (hblkhd): 0 +Max. total allocated space (usmblks): 0 +Free bytes held in fastbins (fsmblks): 0 +Total allocated space (uordblks): 52000 +Total free space (fordblks): 83168 +Topmost releasable block (keepcost): 31168 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mallinfo.c) +.EX +#include +#include +#include +\& +static void +display_mallinfo2(void) +{ + struct mallinfo2 mi; +\& + mi = mallinfo2(); +\& + printf("Total non\-mmapped bytes (arena): %zu\en", mi.arena); + printf("# of free chunks (ordblks): %zu\en", mi.ordblks); + printf("# of free fastbin blocks (smblks): %zu\en", mi.smblks); + printf("# of mapped regions (hblks): %zu\en", mi.hblks); + printf("Bytes in mapped regions (hblkhd): %zu\en", mi.hblkhd); + printf("Max. total allocated space (usmblks): %zu\en", mi.usmblks); + printf("Free bytes held in fastbins (fsmblks): %zu\en", mi.fsmblks); + printf("Total allocated space (uordblks): %zu\en", mi.uordblks); + printf("Total free space (fordblks): %zu\en", mi.fordblks); + printf("Topmost releasable block (keepcost): %zu\en", mi.keepcost); +} +\& +int +main(int argc, char *argv[]) +{ +#define MAX_ALLOCS 2000000 + char *alloc[MAX_ALLOCS]; + size_t blockSize, numBlocks, freeBegin, freeEnd, freeStep; +\& + if (argc < 3 || strcmp(argv[1], "\-\-help") == 0) { + fprintf(stderr, "%s num\-blocks block\-size [free\-step " + "[start\-free [end\-free]]]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + numBlocks = atoi(argv[1]); + blockSize = atoi(argv[2]); + freeStep = (argc > 3) ? atoi(argv[3]) : 1; + freeBegin = (argc > 4) ? atoi(argv[4]) : 0; + freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks; +\& + printf("============== Before allocating blocks ==============\en"); + display_mallinfo2(); +\& + for (size_t j = 0; j < numBlocks; j++) { + if (numBlocks >= MAX_ALLOCS) { + fprintf(stderr, "Too many allocations\en"); + exit(EXIT_FAILURE); + } +\& + alloc[j] = malloc(blockSize); + if (alloc[j] == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } + } +\& + printf("\en============== After allocating blocks ==============\en"); + display_mallinfo2(); +\& + for (size_t j = freeBegin; j < freeEnd; j += freeStep) + free(alloc[j]); +\& + printf("\en============== After freeing blocks ==============\en"); + display_mallinfo2(); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR mmap (2), +.BR malloc (3), +.BR malloc_info (3), +.BR malloc_stats (3), +.BR malloc_trim (3), +.BR mallopt (3) diff --git a/man/man3/mallinfo2.3 b/man/man3/mallinfo2.3 new file mode 100644 index 0000000..25caee7 --- /dev/null +++ b/man/man3/mallinfo2.3 @@ -0,0 +1 @@ +.so man3/mallinfo.3 diff --git a/man/man3/malloc.3 b/man/man3/malloc.3 new file mode 100644 index 0000000..5edae40 --- /dev/null +++ b/man/man3/malloc.3 @@ -0,0 +1,460 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 2007, 2012, 2018, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu) +.\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701 +.\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de) +.\" 2007-09-15 mtk: added notes on malloc()'s use of sbrk() and mmap(). +.\" +.\" FIXME . Review http://austingroupbugs.net/view.php?id=374 +.\" to see what changes are required on this page. +.\" +.TH malloc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc, free, calloc, realloc, reallocarray \- allocate and free dynamic memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *malloc(size_t " size ); +.BI "void free(void *_Nullable " ptr ); +.BI "void *calloc(size_t " nmemb ", size_t " size ); +.BI "void *realloc(void *_Nullable " ptr ", size_t " size ); +.BI "void *reallocarray(void *_Nullable " ptr ", size_t " nmemb ", size_t " size ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR reallocarray (): +.nf + Since glibc 2.29: + _DEFAULT_SOURCE + glibc 2.28 and earlier: + _GNU_SOURCE +.fi +.SH DESCRIPTION +.SS malloc() +The +.BR malloc () +function allocates +.I size +bytes and returns a pointer to the allocated memory. +.IR "The memory is not initialized" . +If +.I size +is 0, then +.BR malloc () +returns a unique pointer value that can later be successfully passed to +.BR free (). +(See "Nonportable behavior" for portability issues.) +.SS free() +The +.BR free () +function frees the memory space pointed to by +.IR ptr , +which must have been returned by a previous call to +.BR malloc () +or related functions. +Otherwise, or if +.I ptr +has already been freed, undefined behavior occurs. +If +.I ptr +is NULL, no operation is performed. +.SS calloc() +The +.BR calloc () +function allocates memory for an array of +.I nmemb +elements of +.I size +bytes each and returns a pointer to the allocated memory. +The memory is set to zero. +If +.I nmemb +or +.I size +is 0, then +.BR calloc () +returns a unique pointer value that can later be successfully passed to +.BR free (). +.P +If the multiplication of +.I nmemb +and +.I size +would result in integer overflow, then +.BR calloc () +returns an error. +By contrast, +an integer overflow would not be detected in the following call to +.BR malloc (), +with the result that an incorrectly sized block of memory would be allocated: +.P +.in +4n +.EX +malloc(nmemb * size); +.EE +.in +.SS realloc() +The +.BR realloc () +function changes the size of the memory block pointed to by +.I ptr +to +.I size +bytes. +The contents of the memory +will be unchanged in the range from the start of the region +up to the minimum of the old and new sizes. +If the new size is larger than the old size, the added memory will +.I not +be initialized. +.P +If +.I ptr +is NULL, then the call is equivalent to +.IR malloc(size) , +for all values of +.IR size . +.P +If +.I size +is equal to zero, +and +.I ptr +is not NULL, then the call is equivalent to +.I free(ptr) +(but see "Nonportable behavior" for portability issues). +.P +Unless +.I ptr +is NULL, it must have been returned by an earlier call to +.B malloc +or related functions. +If the area pointed to was moved, a +.I free(ptr) +is done. +.SS reallocarray() +The +.BR reallocarray () +function changes the size of (and possibly moves) +the memory block pointed to by +.I ptr +to be large enough for an array of +.I nmemb +elements, each of which is +.I size +bytes. +It is equivalent to the call +.P +.in +4n +.EX +realloc(ptr, nmemb * size); +.EE +.in +.P +However, unlike that +.BR realloc () +call, +.BR reallocarray () +fails safely in the case where the multiplication would overflow. +If such an overflow occurs, +.BR reallocarray () +returns an error. +.SH RETURN VALUE +The +.BR malloc (), +.BR calloc (), +.BR realloc (), +and +.BR reallocarray () +functions return a pointer to the allocated memory, +which is suitably aligned for any type that fits into +the requested size or less. +On error, these functions return NULL and set +.IR errno . +Attempting to allocate more than +.B PTRDIFF_MAX +bytes is considered an error, as an object that large +could cause later pointer subtraction to overflow. +.P +The +.BR free () +function returns no value, and preserves +.IR errno . +.P +The +.BR realloc () +and +.BR reallocarray () +functions return NULL if +.I ptr +is not NULL and the requested size is zero; +this is not considered an error. +(See "Nonportable behavior" for portability issues.) +Otherwise, the returned pointer may be the same as +.I ptr +if the allocation was not moved +(e.g., there was room to expand the allocation in-place), or different from +.I ptr +if the allocation was moved to a new address. +If these functions fail, +the original block is left untouched; it is not freed or moved. +.SH ERRORS +.BR calloc (), +.BR malloc (), +.BR realloc (), +and +.BR reallocarray () +can fail with the following error: +.TP +.B ENOMEM +Out of memory. +Possibly, the application hit the +.B RLIMIT_AS +or +.B RLIMIT_DATA +limit described in +.BR getrlimit (2). +Another reason could be that +the number of mappings created by the caller process +exceeded the limit specified by +.IR /proc/sys/vm/max_map_count . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc (), +.BR free (), +.BR calloc (), +.BR realloc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR malloc () +.TQ +.BR free () +.TQ +.BR calloc () +.TQ +.BR realloc () +C11, POSIX.1-2008. +.TP +.BR reallocarray () +None. +.SH HISTORY +.TP +.BR malloc () +.TQ +.BR free () +.TQ +.BR calloc () +.TQ +.BR realloc () +POSIX.1-2001, C89. +.TP +.BR reallocarray () +glibc 2.26. +OpenBSD 5.6, FreeBSD 11.0. +.P +.BR malloc () +and related functions rejected sizes greater than +.B PTRDIFF_MAX +starting in glibc 2.30. +.P +.BR free () +preserved +.I errno +starting in glibc 2.33. +.SH NOTES +By default, Linux follows an optimistic memory allocation strategy. +This means that when +.BR malloc () +returns non-NULL there is no guarantee that the memory really +is available. +In case it turns out that the system is out of memory, +one or more processes will be killed by the OOM killer. +For more information, see the description of +.I /proc/sys/vm/overcommit_memory +and +.I /proc/sys/vm/oom_adj +in +.BR proc (5), +and the Linux kernel source file +.IR Documentation/vm/overcommit\-accounting.rst . +.P +Normally, +.BR malloc () +allocates memory from the heap, and adjusts the size of the heap +as required, using +.BR sbrk (2). +When allocating blocks of memory larger than +.B MMAP_THRESHOLD +bytes, the glibc +.BR malloc () +implementation allocates the memory as a private anonymous mapping using +.BR mmap (2). +.B MMAP_THRESHOLD +is 128\ kB by default, but is adjustable using +.BR mallopt (3). +Prior to Linux 4.7 +allocations performed using +.BR mmap (2) +were unaffected by the +.B RLIMIT_DATA +resource limit; +since Linux 4.7, this limit is also enforced for allocations performed using +.BR mmap (2). +.P +To avoid corruption in multithreaded applications, +mutexes are used internally to protect the memory-management +data structures employed by these functions. +In a multithreaded application in which threads simultaneously +allocate and free memory, +there could be contention for these mutexes. +To scalably handle memory allocation in multithreaded applications, +glibc creates additional +.I memory allocation arenas +if mutex contention is detected. +Each arena is a large region of memory that is internally allocated +by the system +(using +.BR brk (2) +or +.BR mmap (2)), +and managed with its own mutexes. +.P +If your program uses a private memory allocator, +it should do so by replacing +.BR malloc (), +.BR free (), +.BR calloc (), +and +.BR realloc (). +The replacement functions must implement the documented glibc behaviors, +including +.I errno +handling, size-zero allocations, and overflow checking; +otherwise, other library routines may crash or operate incorrectly. +For example, if the replacement +.IR free () +does not preserve +.IR errno , +then seemingly unrelated library routines may +fail without having a valid reason in +.IR errno . +Private memory allocators may also need to replace other glibc functions; +see "Replacing malloc" in the glibc manual for details. +.P +Crashes in memory allocators +are almost always related to heap corruption, such as overflowing +an allocated chunk or freeing the same pointer twice. +.P +The +.BR malloc () +implementation is tunable via environment variables; see +.BR mallopt (3) +for details. +.SS Nonportable behavior +The behavior of +these functions when the requested size is zero +is glibc specific; +other implementations may return NULL without setting +.IR errno , +and portable POSIX programs should tolerate such behavior. +See +.BR realloc (3p). +.P +POSIX requires memory allocators +to set +.I errno +upon failure. +However, the C standard does not require this, and applications +portable to non-POSIX platforms should not assume this. +.P +Portable programs should not use private memory allocators, +as POSIX and the C standard do not allow replacement of +.BR malloc (), +.BR free (), +.BR calloc (), +and +.BR realloc (). +.SH EXAMPLES +.EX +#include +#include +#include +#include +#include +\& +#define MALLOCARRAY(n, type) ((type *) my_mallocarray(n, sizeof(type))) +#define MALLOC(type) MALLOCARRAY(1, type) +\& +static inline void *my_mallocarray(size_t nmemb, size_t size); +\& +int +main(void) +{ + char *p; +\& + p = MALLOCARRAY(32, char); + if (p == NULL) + err(EXIT_FAILURE, "malloc"); +\& + strlcpy(p, "foo", 32); + puts(p); +} +\& +static inline void * +my_mallocarray(size_t nmemb, size_t size) +{ + return reallocarray(NULL, nmemb, size); +} +.EE +.SH SEE ALSO +.\" http://g.oswego.edu/dl/html/malloc.html +.\" A Memory Allocator - by Doug Lea +.\" +.\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html +.\" Linux Heap, Contention in free() - David Boreham +.\" +.\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html +.\" malloc() Performance in a Multithreaded Linux Environment - +.\" Check Lever, David Boreham +.\" +.ad l +.nh +.BR valgrind (1), +.BR brk (2), +.BR mmap (2), +.BR alloca (3), +.BR malloc_get_state (3), +.BR malloc_info (3), +.BR malloc_trim (3), +.BR malloc_usable_size (3), +.BR mallopt (3), +.BR mcheck (3), +.BR mtrace (3), +.BR posix_memalign (3) +.P +For details of the GNU C library implementation, see +.UR https://sourceware.org/glibc/wiki/MallocInternals +.UE . diff --git a/man/man3/malloc_get_state.3 b/man/man3/malloc_get_state.3 new file mode 100644 index 0000000..8a24f85 --- /dev/null +++ b/man/man3/malloc_get_state.3 @@ -0,0 +1,115 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_get_state 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc_get_state, malloc_set_state \- +record and restore state of malloc implementation +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B void *malloc_get_state(void); +.BI "int malloc_set_state(void *" state ); +.fi +.SH DESCRIPTION +.IR Note : +these functions are removed in glibc 2.25. +.P +The +.BR malloc_get_state () +function records the current state of all +.BR malloc (3) +internal bookkeeping variables +(but not the actual contents of the heap +or the state of +.BR malloc_hook (3) +functions pointers). +The state is recorded in a system-dependent opaque data structure +dynamically allocated via +.BR malloc (3), +and a pointer to that data structure is returned as the function result. +(It is the caller's responsibility to +.BR free (3) +this memory.) +.P +The +.BR malloc_set_state () +function restores the state of all +.BR malloc (3) +internal bookkeeping variables to the values recorded in +the opaque data structure pointed to by +.IR state . +.SH RETURN VALUE +On success, +.BR malloc_get_state () +returns a pointer to a newly allocated opaque data structure. +On error (for example, memory could not be allocated for the data structure), +.BR malloc_get_state () +returns NULL. +.P +On success, +.BR malloc_set_state () +returns 0. +If the implementation detects that +.I state +does not point to a correctly formed data structure, +.\" if(ms->magic != MALLOC_STATE_MAGIC) return -1; +.BR malloc_set_state () +returns \-1. +If the implementation detects that +the version of the data structure referred to by +.I state +is a more recent version than this implementation knows about, +.\" /* Must fail if the major version is too high. */ +.\" if((ms->version & ~0xffl) > (MALLOC_STATE_VERSION & ~0xffl)) return -2; +.BR malloc_set_state () +returns \-2. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc_get_state (), +.BR malloc_set_state () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH NOTES +These functions are useful when using this +.BR malloc (3) +implementation as part of a shared library, +and the heap contents are saved/restored via some other method. +This technique is used by GNU Emacs to implement its "dumping" function. +.P +Hook function pointers are never saved or restored by these +functions, with two exceptions: +if malloc checking (see +.BR mallopt (3)) +was in use when +.BR malloc_get_state () +was called, then +.BR malloc_set_state () +resets malloc checking hooks +.\" i.e., calls __malloc_check_init() +if possible; +.\" i.e., malloc checking is not already in use +.\" and the caller requested malloc checking +if malloc checking was not in use in the recorded state, +but the caller has requested malloc checking, +then the hooks are reset to 0. +.SH SEE ALSO +.BR malloc (3), +.BR mallopt (3) diff --git a/man/man3/malloc_hook.3 b/man/man3/malloc_hook.3 new file mode 100644 index 0000000..5b10cfd --- /dev/null +++ b/man/man3/malloc_hook.3 @@ -0,0 +1,154 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Heavily based on glibc documentation +.\" Polished, added docs, removed glibc doc bug, 2002-07-20, aeb +.\" +.TH __malloc_hook 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +__malloc_hook, __malloc_initialize_hook, +__memalign_hook, __free_hook, __realloc_hook, +__after_morecore_hook \- malloc debugging variables (DEPRECATED) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "void *(*volatile __malloc_hook)(size_t " size ", const void *" caller ); +.P +.BI "void *(*volatile __realloc_hook)(void *" ptr ", size_t " size , +.BI " const void *" caller ); +.P +.BI "void *(*volatile __memalign_hook)(size_t " alignment ", size_t " size , +.BI " const void *" caller ); +.P +.BI "void (*volatile __free_hook)(void *" ptr ", const void *" caller ); +.P +.B "void (*__malloc_initialize_hook)(void);" +.P +.B "void (*volatile __after_morecore_hook)(void);" +.fi +.SH DESCRIPTION +The GNU C library lets you modify the behavior of +.BR malloc (3), +.BR realloc (3), +and +.BR free (3) +by specifying appropriate hook functions. +You can use these hooks +to help you debug programs that use dynamic memory allocation, +for example. +.P +The variable +.B __malloc_initialize_hook +points at a function that is called once when the malloc implementation +is initialized. +This is a weak variable, so it can be overridden in +the application with a definition like the following: +.P +.in +4n +.EX +void (*__malloc_initialize_hook)(void) = my_init_hook; +.EE +.in +.P +Now the function +.IR my_init_hook () +can do the initialization of all hooks. +.P +The four functions pointed to by +.BR __malloc_hook , +.BR __realloc_hook , +.BR __memalign_hook , +.B __free_hook +have a prototype like the functions +.BR malloc (3), +.BR realloc (3), +.BR memalign (3), +.BR free (3), +respectively, except that they have a final argument +.I caller +that gives the address of the caller of +.BR malloc (3), +etc. +.P +The variable +.B __after_morecore_hook +points at a function that is called each time after +.BR sbrk (2) +was asked for more memory. +.SH STANDARDS +GNU. +.SH NOTES +The use of these hook functions is not safe in multithreaded programs, +and they are now deprecated. +From glibc 2.24 onwards, the +.B __malloc_initialize_hook +variable has been removed from the API, +and from glibc 2.34 onwards, all +the hook variables have been removed from the API. +.\" https://bugzilla.redhat.com/show_bug.cgi?id=450187 +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=9957 +Programmers should instead preempt calls to the relevant functions +by defining and exporting +.BR malloc (), +.BR free (), +.BR realloc (), +and +.BR calloc (). +.SH EXAMPLES +Here is a short example of how to use these variables. +.P +.EX +#include +#include +\& +/* Prototypes for our hooks */ +static void my_init_hook(void); +static void *my_malloc_hook(size_t, const void *); +\& +/* Variables to save original hooks */ +static void *(*old_malloc_hook)(size_t, const void *); +\& +/* Override initializing hook from the C library */ +void (*__malloc_initialize_hook)(void) = my_init_hook; +\& +static void +my_init_hook(void) +{ + old_malloc_hook = __malloc_hook; + __malloc_hook = my_malloc_hook; +} +\& +static void * +my_malloc_hook(size_t size, const void *caller) +{ + void *result; +\& + /* Restore all old hooks */ + __malloc_hook = old_malloc_hook; +\& + /* Call recursively */ + result = malloc(size); +\& + /* Save underlying hooks */ + old_malloc_hook = __malloc_hook; +\& + /* printf() might call malloc(), so protect it too */ + printf("malloc(%zu) called from %p returns %p\en", + size, caller, result); +\& + /* Restore our own hooks */ + __malloc_hook = my_malloc_hook; +\& + return result; +} +.EE +.SH SEE ALSO +.BR mallinfo (3), +.BR malloc (3), +.BR mcheck (3), +.BR mtrace (3) diff --git a/man/man3/malloc_info.3 b/man/man3/malloc_info.3 new file mode 100644 index 0000000..086b3b2 --- /dev/null +++ b/man/man3/malloc_info.3 @@ -0,0 +1,257 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_info 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc_info \- export malloc state to a stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int malloc_info(int " options ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR malloc_info () +function exports an XML string that describes the current state +of the memory-allocation +implementation in the caller. +The string is printed on the file stream +.IR stream . +The exported string includes information about all arenas (see +.BR malloc (3)). +.P +As currently implemented, +.I options +must be zero. +.SH RETURN VALUE +On success, +.BR malloc_info () +returns 0. +On failure, it returns \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I options +was nonzero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc_info () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.10. +.SH NOTES +The memory-allocation information is provided as an XML string +(rather than a C structure) +because the information may change over time +(according to changes in the underlying implementation). +The output XML string includes a version field. +.P +The +.BR open_memstream (3) +function can be used to send the output of +.BR malloc_info () +directly into a buffer in memory, rather than to a file. +.P +The +.BR malloc_info () +function is designed to address deficiencies in +.BR malloc_stats (3) +and +.BR mallinfo (3). +.SH EXAMPLES +The program below takes up to four command-line arguments, +of which the first three are mandatory. +The first argument specifies the number of threads that +the program should create. +All of the threads, including the main thread, +allocate the number of blocks of memory specified by the second argument. +The third argument controls the size of the blocks to be allocated. +The main thread creates blocks of this size, +the second thread created by the program allocates blocks of twice this size, +the third thread allocates blocks of three times this size, and so on. +.P +The program calls +.BR malloc_info () +twice to display the memory-allocation state. +The first call takes place before any threads +are created or memory allocated. +The second call is performed after all threads have allocated memory. +.P +In the following example, +the command-line arguments specify the creation of one additional thread, +and both the main thread and the additional thread +allocate 10000 blocks of memory. +After the blocks of memory have been allocated, +.BR malloc_info () +shows the state of two allocation arenas. +.P +.in +4n +.EX +.RB "$ " "getconf GNU_LIBC_VERSION" +glibc 2.13 +.RB "$ " "./a.out 1 10000 100" +============ Before allocating blocks ============ + + + + + + + + + + + + + + + + + + +\& +============ After allocating blocks ============ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +.EE +.in +.SS Program source +.\" SRC BEGIN (malloc_info.c) +.EX +#include +#include +#include +#include +#include +#include +\& +static size_t blockSize; +static size_t numThreads; +static unsigned int numBlocks; +\& +static void * +thread_func(void *arg) +{ + int tn = (int) arg; +\& + /* The multiplier \[aq](2 + tn)\[aq] ensures that each thread (including + the main thread) allocates a different amount of memory. */ +\& + for (unsigned int j = 0; j < numBlocks; j++) + if (malloc(blockSize * (2 + tn)) == NULL) + err(EXIT_FAILURE, "malloc\-thread"); +\& + sleep(100); /* Sleep until main thread terminates. */ + return NULL; +} +\& +int +main(int argc, char *argv[]) +{ + int sleepTime; + pthread_t *thr; +\& + if (argc < 4) { + fprintf(stderr, + "%s num\-threads num\-blocks block\-size [sleep\-time]\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + numThreads = atoi(argv[1]); + numBlocks = atoi(argv[2]); + blockSize = atoi(argv[3]); + sleepTime = (argc > 4) ? atoi(argv[4]) : 0; +\& + thr = calloc(numThreads, sizeof(*thr)); + if (thr == NULL) + err(EXIT_FAILURE, "calloc"); +\& + printf("============ Before allocating blocks ============\en"); + malloc_info(0, stdout); +\& + /* Create threads that allocate different amounts of memory. */ +\& + for (size_t tn = 0; tn < numThreads; tn++) { + errno = pthread_create(&thr[tn], NULL, thread_func, + (void *) tn); + if (errno != 0) + err(EXIT_FAILURE, "pthread_create"); +\& + /* If we add a sleep interval after the start\-up of each + thread, the threads likely won\[aq]t contend for malloc + mutexes, and therefore additional arenas won\[aq]t be + allocated (see malloc(3)). */ +\& + if (sleepTime > 0) + sleep(sleepTime); + } +\& + /* The main thread also allocates some memory. */ +\& + for (unsigned int j = 0; j < numBlocks; j++) + if (malloc(blockSize) == NULL) + err(EXIT_FAILURE, "malloc"); +\& + sleep(2); /* Give all threads a chance to + complete allocations. */ +\& + printf("\en============ After allocating blocks ============\en"); + malloc_info(0, stdout); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR mallinfo (3), +.BR malloc (3), +.BR malloc_stats (3), +.BR mallopt (3), +.BR open_memstream (3) diff --git a/man/man3/malloc_set_state.3 b/man/man3/malloc_set_state.3 new file mode 100644 index 0000000..ff16dd7 --- /dev/null +++ b/man/man3/malloc_set_state.3 @@ -0,0 +1 @@ +.so man3/malloc_get_state.3 diff --git a/man/man3/malloc_stats.3 b/man/man3/malloc_stats.3 new file mode 100644 index 0000000..30df458 --- /dev/null +++ b/man/man3/malloc_stats.3 @@ -0,0 +1,65 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_stats 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc_stats \- print memory allocation statistics +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B void malloc_stats(void); +.fi +.SH DESCRIPTION +The +.BR malloc_stats () +function prints (on standard error) statistics about memory allocated by +.BR malloc (3) +and related functions. +For each arena (allocation area), this function prints +the total amount of memory allocated +and the total number of bytes consumed by in-use allocations. +(These two values correspond to the +.I arena +and +.I uordblks +fields retrieved by +.BR mallinfo (3).) +In addition, +the function prints the sum of these two statistics for all arenas, +and the maximum number of blocks and bytes that were ever simultaneously +allocated using +.BR mmap (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc_stats () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.0. +.SH NOTES +More detailed information about memory allocations in the main arena +can be obtained using +.BR mallinfo (3). +.SH SEE ALSO +.BR mmap (2), +.BR mallinfo (3), +.BR malloc (3), +.BR malloc_info (3), +.BR mallopt (3) diff --git a/man/man3/malloc_trim.3 b/man/man3/malloc_trim.3 new file mode 100644 index 0000000..4049b24 --- /dev/null +++ b/man/man3/malloc_trim.3 @@ -0,0 +1,81 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_trim 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc_trim \- release free memory from the heap +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int malloc_trim(size_t " pad ); +.fi +.SH DESCRIPTION +The +.BR malloc_trim () +function attempts to release free memory from the heap +(by calling +.BR sbrk (2) +or +.BR madvise (2) +with suitable arguments). +.P +The +.I pad +argument specifies the amount of free space to leave untrimmed +at the top of the heap. +If this argument is 0, only the minimum amount of memory is maintained +at the top of the heap (i.e., one page or less). +A nonzero argument can be used to maintain some trailing space +at the top of the heap in order to allow future allocations +to be made without having to extend the heap with +.BR sbrk (2). +.SH RETURN VALUE +The +.BR malloc_trim () +function returns 1 if memory was actually released back to the system, +or 0 if it was not possible to release any memory. +.SH ERRORS +No errors are defined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc_trim () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH VERSIONS +glibc 2.0. +.SH NOTES +Only the main heap (using +.BR sbrk (2)) +honors the +.I pad +argument; thread heaps do not. +.P +Since glibc 2.8 this function frees memory in all arenas and in all +chunks with whole free pages. +.\" See commit 68631c8eb92ff38d9da1ae34f6aa048539b199cc +.\" (dated 2007-12-16) which adds iteration over all +.\" arenas and frees all pages in chunks which are free. +.P +Before glibc 2.8 this function only freed memory at the +top of the heap in the main arena. +.SH SEE ALSO +.BR sbrk (2), +.BR malloc (3), +.BR mallopt (3) diff --git a/man/man3/malloc_usable_size.3 b/man/man3/malloc_usable_size.3 new file mode 100644 index 0000000..c0aa6b8 --- /dev/null +++ b/man/man3/malloc_usable_size.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH malloc_usable_size 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +malloc_usable_size \- obtain size of block of memory allocated from heap +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t malloc_usable_size(void *_Nullable " ptr ); +.fi +.SH DESCRIPTION +This function can be used for +diagnostics or statistics about allocations from +.BR malloc (3) +or a related function. +.SH RETURN VALUE +.BR malloc_usable_size () +returns a value no less than +the size of the block of allocated memory pointed to by +.IR ptr . +If +.I ptr +is NULL, 0 is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc_usable_size () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH CAVEATS +The value returned by +.BR malloc_usable_size () +may be greater than the requested size of the allocation +because of various internal implementation details, +none of which the programmer should rely on. +This function is intended to only be used +for diagnostics and statistics; +writing to the excess memory without first calling +.BR realloc (3) +to resize the allocation is not supported. +The returned value is only valid at the time of the call. +.SH SEE ALSO +.BR malloc (3) diff --git a/man/man3/mallopt.3 b/man/man3/mallopt.3 new file mode 100644 index 0000000..d684eb1 --- /dev/null +++ b/man/man3/mallopt.3 @@ -0,0 +1,619 @@ +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mallopt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mallopt \- set memory allocation parameters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mallopt(int " param ", int " value ); +.fi +.SH DESCRIPTION +The +.BR mallopt () +function adjusts parameters that control the behavior of the +memory-allocation functions (see +.BR malloc (3)). +The +.I param +argument specifies the parameter to be modified, and +.I value +specifies the new value for that parameter. +.P +The following values can be specified for +.IR param : +.TP +.B M_ARENA_MAX +If this parameter has a nonzero value, +it defines a hard limit on the maximum number of arenas that can be created. +An arena represents a pool of memory that can be used by +.BR malloc (3) +(and similar) calls to service allocation requests. +Arenas are thread safe and +therefore may have multiple concurrent memory requests. +The trade-off is between the number of threads and the number of arenas. +The more arenas you have, the lower the per-thread contention, +but the higher the memory usage. +.IP +The default value of this parameter is 0, +meaning that the limit on the number of arenas is determined +according to the setting of +.BR M_ARENA_TEST . +.IP +This parameter has been available since glibc 2.10 via +.BR \-\-enable\-experimental\-malloc , +and since glibc 2.15 by default. +In some versions of the allocator there was no limit on the number +of created arenas (e.g., CentOS 5, RHEL 5). +.IP +When employing newer glibc versions, applications may in +some cases exhibit high contention when accessing arenas. +In these cases, it may be beneficial to increase +.B M_ARENA_MAX +to match the number of threads. +This is similar in behavior to strategies taken by tcmalloc and jemalloc +(e.g., per-thread allocation pools). +.TP +.B M_ARENA_TEST +This parameter specifies a value, in number of arenas created, +at which point the system configuration will be examined +to determine a hard limit on the number of created arenas. +(See +.B M_ARENA_MAX +for the definition of an arena.) +.IP +The computation of the arena hard limit is implementation-defined +and is usually calculated as a multiple of the number of available CPUs. +Once the hard limit is computed, the result is final and constrains +the total number of arenas. +.IP +The default value for the +.B M_ARENA_TEST +parameter is 2 on systems where +.I sizeof(long) +is 4; otherwise the default value is 8. +.IP +This parameter has been available since glibc 2.10 via +.BR \-\-enable\-experimental\-malloc , +and since glibc 2.15 by default. +.IP +The value of +.B M_ARENA_TEST +is not used when +.B M_ARENA_MAX +has a nonzero value. +.TP +.B M_CHECK_ACTION +Setting this parameter controls how glibc responds when various kinds +of programming errors are detected (e.g., freeing the same pointer twice). +The 3 least significant bits (2, 1, and 0) of the value assigned +to this parameter determine the glibc behavior, as follows: +.RS +.TP +Bit 0 +If this bit is set, then print a one-line message on +.I stderr +that provides details about the error. +The message starts with the string "***\ glibc detected\ ***", +followed by the program name, +the name of the memory-allocation function in which the error was detected, +a brief description of the error, +and the memory address where the error was detected. +.TP +Bit 1 +If this bit is set, then, +after printing any error message specified by bit 0, +the program is terminated by calling +.BR abort (3). +Since glibc 2.4, +if bit 0 is also set, +then, between printing the error message and aborting, +the program also prints a stack trace in the manner of +.BR backtrace (3), +and prints the process's memory mapping in the style of +.IR /proc/ pid /maps +(see +.BR proc (5)). +.TP +Bit 2 (since glibc 2.4) +This bit has an effect only if bit 0 is also set. +If this bit is set, +then the one-line message describing the error is simplified +to contain just the name of the function where the error +was detected and the brief description of the error. +.RE +.IP +The remaining bits in +.I value +are ignored. +.IP +Combining the above details, +the following numeric values are meaningful for +.BR M_CHECK_ACTION : +.RS 12 +.TP +.B 0 +Ignore error conditions; continue execution (with undefined results). +.TP +.B 1 +Print a detailed error message and continue execution. +.TP +.B 2 +Abort the program. +.TP +.B 3 +Print detailed error message, stack trace, and memory mappings, +and abort the program. +.TP +.B 5 +Print a simple error message and continue execution. +.TP +.B 7 +Print simple error message, stack trace, and memory mappings, +and abort the program. +.RE +.IP +Since glibc 2.3.4, the default value for the +.B M_CHECK_ACTION +parameter is 3. +In glibc 2.3.3 and earlier, the default value is 1. +.IP +Using a nonzero +.B M_CHECK_ACTION +value can be useful because otherwise a crash may happen much later, +and the true cause of the problem is then very hard to track down. +.TP +.B M_MMAP_MAX +.\" The following text adapted from comments in the glibc source: +This parameter specifies the maximum number of allocation requests that +may be simultaneously serviced using +.BR mmap (2). +This parameter exists because some systems have a limited number +of internal tables for use by +.BR mmap (2), +and using more than a few of them may degrade performance. +.IP +The default value is 65,536, +a value which has no special significance and +which serves only as a safeguard. +Setting this parameter to 0 disables the use of +.BR mmap (2) +for servicing large allocation requests. +.TP +.B M_MMAP_THRESHOLD +For allocations greater than or equal to the limit specified (in bytes) by +.B M_MMAP_THRESHOLD +that can't be satisfied from the free list, +the memory-allocation functions employ +.BR mmap (2) +instead of increasing the program break using +.BR sbrk (2). +.IP +Allocating memory using +.BR mmap (2) +has the significant advantage that the allocated memory blocks +can always be independently released back to the system. +(By contrast, +the heap can be trimmed only if memory is freed at the top end.) +On the other hand, there are some disadvantages to the use of +.BR mmap (2): +deallocated space is not placed on the free list +for reuse by later allocations; +memory may be wasted because +.BR mmap (2) +allocations must be page-aligned; +and the kernel must perform the expensive task of zeroing out +memory allocated via +.BR mmap (2). +Balancing these factors leads to a default setting of 128*1024 for the +.B M_MMAP_THRESHOLD +parameter. +.IP +The lower limit for this parameter is 0. +The upper limit is +.BR DEFAULT_MMAP_THRESHOLD_MAX : +512*1024 on 32-bit systems or +.I 4*1024*1024*sizeof(long) +on 64-bit systems. +.IP +.IR Note : +Nowadays, glibc uses a dynamic mmap threshold by default. +The initial value of the threshold is 128*1024, +but when blocks larger than the current threshold and less than or equal to +.B DEFAULT_MMAP_THRESHOLD_MAX +are freed, +the threshold is adjusted upward to the size of the freed block. +When dynamic mmap thresholding is in effect, +the threshold for trimming the heap is also dynamically adjusted +to be twice the dynamic mmap threshold. +Dynamic adjustment of the mmap threshold is disabled if any of the +.BR M_TRIM_THRESHOLD , +.BR M_TOP_PAD , +.BR M_MMAP_THRESHOLD , +or +.B M_MMAP_MAX +parameters is set. +.TP +.BR M_MXFAST " (since glibc 2.3)" +.\" The following text adapted from comments in the glibc sources: +Set the upper limit for memory allocation requests that are satisfied +using "fastbins". +(The measurement unit for this parameter is bytes.) +Fastbins are storage areas that hold deallocated blocks of memory +of the same size without merging adjacent free blocks. +Subsequent reallocation of blocks of the same size can be handled +very quickly by allocating from the fastbin, +although memory fragmentation and the overall memory footprint +of the program can increase. +.IP +The default value for this parameter is +.I 64*sizeof(size_t)/4 +(i.e., 64 on 32-bit architectures). +The range for this parameter is 0 to +.IR 80*sizeof(size_t)/4 . +Setting +.B M_MXFAST +to 0 disables the use of fastbins. +.TP +.BR M_PERTURB " (since glibc 2.4)" +If this parameter is set to a nonzero value, +then bytes of allocated memory (other than allocations via +.BR calloc (3)) +are initialized to the complement of the value +in the least significant byte of +.IR value , +and when allocated memory is released using +.BR free (3), +the freed bytes are set to the least significant byte of +.IR value . +This can be useful for detecting errors where programs +incorrectly rely on allocated memory being initialized to zero, +or reuse values in memory that has already been freed. +.IP +The default value for this parameter is 0. +.TP +.B M_TOP_PAD +This parameter defines the amount of padding to employ when calling +.BR sbrk (2) +to modify the program break. +(The measurement unit for this parameter is bytes.) +This parameter has an effect in the following circumstances: +.RS +.IP \[bu] 3 +When the program break is increased, then +.B M_TOP_PAD +bytes are added to the +.BR sbrk (2) +request. +.IP \[bu] +When the heap is trimmed as a consequence of calling +.BR free (3) +(see the discussion of +.BR M_TRIM_THRESHOLD ) +this much free space is preserved at the top of the heap. +.RE +.IP +In either case, +the amount of padding is always rounded to a system page boundary. +.IP +Modifying +.B M_TOP_PAD +is a trade-off between increasing the number of system calls +(when the parameter is set low) +and wasting unused memory at the top of the heap +(when the parameter is set high). +.IP +The default value for this parameter is 128*1024. +.\" DEFAULT_TOP_PAD in glibc source +.TP +.B M_TRIM_THRESHOLD +When the amount of contiguous free memory at the top of the heap +grows sufficiently large, +.BR free (3) +employs +.BR sbrk (2) +to release this memory back to the system. +(This can be useful in programs that continue to execute for +a long period after freeing a significant amount of memory.) +The +.B M_TRIM_THRESHOLD +parameter specifies the minimum size (in bytes) that +this block of memory must reach before +.BR sbrk (2) +is used to trim the heap. +.IP +The default value for this parameter is 128*1024. +Setting +.B M_TRIM_THRESHOLD +to \-1 disables trimming completely. +.IP +Modifying +.B M_TRIM_THRESHOLD +is a trade-off between increasing the number of system calls +(when the parameter is set low) +and wasting unused memory at the top of the heap +(when the parameter is set high). +.\" +.SS Environment variables +A number of environment variables can be defined +to modify some of the same parameters as are controlled by +.BR mallopt (). +Using these variables has the advantage that the source code +of the program need not be changed. +To be effective, these variables must be defined before the +first call to a memory-allocation function. +(If the same parameters are adjusted via +.BR mallopt (), +then the +.BR mallopt () +settings take precedence.) +For security reasons, +these variables are ignored in set-user-ID and set-group-ID programs. +.P +The environment variables are as follows +(note the trailing underscore at the end of the name of some variables): +.TP +.B MALLOC_ARENA_MAX +Controls the same parameter as +.BR mallopt () +.BR M_ARENA_MAX . +.TP +.B MALLOC_ARENA_TEST +Controls the same parameter as +.BR mallopt () +.BR M_ARENA_TEST . +.TP +.B MALLOC_CHECK_ +This environment variable controls the same parameter as +.BR mallopt () +.BR M_CHECK_ACTION . +If this variable is set to a nonzero value, +then a special implementation of the memory-allocation functions is used. +(This is accomplished using the +.BR malloc_hook (3) +feature.) +This implementation performs additional error checking, +but is slower +.\" On glibc 2.12/x86, a simple malloc()+free() loop is about 70% slower +.\" when MALLOC_CHECK_ was set. +than the standard set of memory-allocation functions. +(This implementation does not detect all possible errors; +memory leaks can still occur.) +.IP +The value assigned to this environment variable should be a single digit, +whose meaning is as described for +.BR M_CHECK_ACTION . +Any characters beyond the initial digit are ignored. +.IP +For security reasons, the effect of +.B MALLOC_CHECK_ +is disabled by default for set-user-ID and set-group-ID programs. +However, if the file +.I /etc/suid\-debug +exists (the content of the file is irrelevant), then +.B MALLOC_CHECK_ +also has an effect for set-user-ID and set-group-ID programs. +.TP +.B MALLOC_MMAP_MAX_ +Controls the same parameter as +.BR mallopt () +.BR M_MMAP_MAX . +.TP +.B MALLOC_MMAP_THRESHOLD_ +Controls the same parameter as +.BR mallopt () +.BR M_MMAP_THRESHOLD . +.TP +.B MALLOC_PERTURB_ +Controls the same parameter as +.BR mallopt () +.BR M_PERTURB . +.TP +.B MALLOC_TRIM_THRESHOLD_ +Controls the same parameter as +.BR mallopt () +.BR M_TRIM_THRESHOLD . +.TP +.B MALLOC_TOP_PAD_ +Controls the same parameter as +.BR mallopt () +.BR M_TOP_PAD . +.SH RETURN VALUE +On success, +.BR mallopt () +returns 1. +On error, it returns 0. +.SH ERRORS +On error, +.I errno +is +.I not +set. +.SH VERSIONS +A similar function exists on many System V derivatives, +but the range of values for +.I param +varies across systems. +The SVID defined options +.BR M_MXFAST , +.BR M_NLBLKS , +.BR M_GRAIN , +and +.BR M_KEEP , +but only the first of these is implemented in glibc. +.SH STANDARDS +None. +.SH HISTORY +glibc 2.0. +.SH BUGS +Specifying an invalid value for +.I param +does not generate an error. +.P +A calculation error within the glibc implementation means that +a call of the form: +.\" FIXME . This looks buggy: +.\" setting the M_MXFAST limit rounds up: (s + SIZE_SZ) & ~MALLOC_ALIGN_MASK) +.\" malloc requests are rounded up: +.\" (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12129 +.P +.in +4n +.EX +mallopt(M_MXFAST, n) +.EE +.in +.P +does not result in fastbins being employed for all allocations of size up to +.IR n . +To ensure desired results, +.I n +should be rounded up to the next multiple greater than or equal to +.IR (2k+1)*sizeof(size_t) , +where +.I k +is an integer. +.\" Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t) +.P +If +.BR mallopt () +is used to set +.BR M_PERTURB , +then, as expected, the bytes of allocated memory are initialized +to the complement of the byte in +.IR value , +and when that memory is freed, +the bytes of the region are initialized to the byte specified in +.IR value . +However, there is an +.RI off-by- sizeof(size_t) +error in the implementation: +.\" FIXME . https://www.sourceware.org/bugzilla/show_bug.cgi?id=12140 +instead of initializing precisely the block of memory +being freed by the call +.IR free(p) , +the block starting at +.I p+sizeof(size_t) +is initialized. +.SH EXAMPLES +The program below demonstrates the use of +.BR M_CHECK_ACTION . +If the program is supplied with an (integer) command-line argument, +then that argument is used to set the +.B M_CHECK_ACTION +parameter. +The program then allocates a block of memory, +and frees it twice (an error). +.P +The following shell session shows what happens when we run this program +under glibc, with the default value for +.BR M_CHECK_ACTION : +.P +.in +4n +.EX +$ \fB./a.out\fP +main(): returned from first free() call +*** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 *** +======= Backtrace: ========= +/lib/libc.so.6(+0x6c501)[0x523501] +/lib/libc.so.6(+0x6dd70)[0x524d70] +/lib/libc.so.6(cfree+0x6d)[0x527e5d] +\&./a.out[0x80485db] +/lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7] +\&./a.out[0x8048471] +======= Memory map: ======== +001e4000\-001fe000 r\-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1 +001fe000\-001ff000 r\-\-p 00019000 08:06 1083555 /lib/libgcc_s.so.1 +[some lines omitted] +b7814000\-b7817000 rw\-p 00000000 00:00 0 +bff53000\-bff74000 rw\-p 00000000 00:00 0 [stack] +Aborted (core dumped) +.EE +.in +.P +The following runs show the results when employing other values for +.BR M_CHECK_ACTION : +.P +.in +4n +.EX +$ \fB./a.out 1\fP # Diagnose error and continue +main(): returned from first free() call +*** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 *** +main(): returned from second free() call +$ \fB./a.out 2\fP # Abort without error message +main(): returned from first free() call +Aborted (core dumped) +$ \fB./a.out 0\fP # Ignore error and continue +main(): returned from first free() call +main(): returned from second free() call +.EE +.in +.P +The next run shows how to set the same parameter using the +.B MALLOC_CHECK_ +environment variable: +.P +.in +4n +.EX +$ \fBMALLOC_CHECK_=1 ./a.out\fP +main(): returned from first free() call +*** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 *** +main(): returned from second free() call +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mallopt.c) +.EX +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + char *p; +\& + if (argc > 1) { + if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) { + fprintf(stderr, "mallopt() failed"); + exit(EXIT_FAILURE); + } + } +\& + p = malloc(1000); + if (p == NULL) { + fprintf(stderr, "malloc() failed"); + exit(EXIT_FAILURE); + } +\& + free(p); + printf("%s(): returned from first free() call\en", __func__); +\& + free(p); + printf("%s(): returned from second free() call\en", __func__); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR mmap (2), +.BR sbrk (2), +.BR mallinfo (3), +.BR malloc (3), +.BR malloc_hook (3), +.BR malloc_info (3), +.BR malloc_stats (3), +.BR malloc_trim (3), +.BR mcheck (3), +.BR mtrace (3), +.BR posix_memalign (3) diff --git a/man/man3/matherr.3 b/man/man3/matherr.3 new file mode 100644 index 0000000..4536e01 --- /dev/null +++ b/man/man3/matherr.3 @@ -0,0 +1,428 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH matherr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +matherr \- SVID math library exception handling +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int matherr(struct exception *" exc ); +.P +.B [[deprecated]] extern _LIB_VERSION_TYPE _LIB_VERSION; +.fi +.SH DESCRIPTION +.IR Note : +the mechanism described in this page is no longer supported by glibc. +Before glibc 2.27, it had been marked as obsolete. +Since glibc 2.27, +.\" glibc commit 813378e9fe17e029caf627cab76fe23eb46815fa +the mechanism has been removed altogether. +New applications should use the techniques described in +.BR math_error (7) +and +.BR fenv (3). +This page documents the +.BR matherr () +mechanism as an aid for maintaining and porting older applications. +.P +The System V Interface Definition (SVID) specifies that various +math functions should invoke a function called +.BR matherr () +if a math exception is detected. +This function is called before the math function returns; +after +.BR matherr () +returns, the system then returns to the math function, +which in turn returns to the caller. +.P +To employ +.BR matherr (), +the programmer must define the +.B _SVID_SOURCE +feature test macro +(before including +.I any +header files), +and assign the value +.B _SVID_ +to the external variable +.BR _LIB_VERSION . +.P +The system provides a default version of +.BR matherr (). +This version does nothing, and returns zero +(see below for the significance of this). +The default +.BR matherr () +can be overridden by a programmer-defined +version, which will be invoked when an exception occurs. +The function is invoked with one argument, a pointer to an +.I exception +structure, defined as follows: +.P +.in +4n +.EX +struct exception { + int type; /* Exception type */ + char *name; /* Name of function causing exception */ + double arg1; /* 1st argument to function */ + double arg2; /* 2nd argument to function */ + double retval; /* Function return value */ +} +.EE +.in +.P +The +.I type +field has one of the following values: +.TP 12 +.B DOMAIN +A domain error occurred (the function argument was outside the range +for which the function is defined). +The return value depends on the function; +.I errno +is set to +.BR EDOM . +.TP +.B SING +A pole error occurred (the function result is an infinity). +The return value in most cases is +.B HUGE +(the largest single precision floating-point number), +appropriately signed. +In most cases, +.I errno +is set to +.BR EDOM . +.TP +.B OVERFLOW +An overflow occurred. +In most cases, the value +.B HUGE +is returned, and +.I errno +is set to +.BR ERANGE . +.TP +.B UNDERFLOW +An underflow occurred. +0.0 is returned, and +.I errno +is set to +.BR ERANGE . +.TP +.B TLOSS +Total loss of significance. +0.0 is returned, and +.I errno +is set to +.BR ERANGE . +.TP +.B PLOSS +Partial loss of significance. +This value is unused on glibc +(and many other systems). +.P +The +.I arg1 +and +.I arg2 +fields are the arguments supplied to the function +.RI ( arg2 +is undefined for functions that take only one argument). +.P +The +.I retval +field specifies the return value that the math +function will return to its caller. +The programmer-defined +.BR matherr () +can modify this field to change the return value of the math function. +.P +If the +.BR matherr () +function returns zero, then the system sets +.I errno +as described above, and may print an error message on standard error +(see below). +.P +If the +.BR matherr () +function returns a nonzero value, then the system does not set +.IR errno , +and doesn't print an error message. +.SS Math functions that employ matherr() +The table below lists the functions and circumstances in which +.BR matherr () +is called. +The "Type" column indicates the value assigned to +.I exc\->type +when calling +.BR matherr (). +The "Result" column is the default return value assigned to +.IR exc\->retval . +.P +The "Msg?" and "errno" columns describe the default behavior if +.BR matherr () +returns zero. +If the "Msg?" columns contains "y", +then the system prints an error message on standard error. +.P +The table uses the following notations and abbreviations: +.P +.RS +.TS +l l. +x first argument to function +y second argument to function +fin finite value for argument +neg negative value for argument +int integral value for argument +o/f result overflowed +u/f result underflowed +|x| absolute value of x +X_TLOSS is a constant defined in \fI\fP +.TE +.RE +.\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c +.\" A subset of cases were test by experimental programs. +.TS +lB lB lB cB lB +l l l c l. +Function Type Result Msg? errno +acos(|x|>1) DOMAIN HUGE y EDOM +asin(|x|>1) DOMAIN HUGE y EDOM +atan2(0,0) DOMAIN HUGE y EDOM +acosh(x<1) DOMAIN NAN y EDOM \" retval is 0.0/0.0 +atanh(|x|>1) DOMAIN NAN y EDOM \" retval is 0.0/0.0 +atanh(|x|==1) SING (x>0.0)? y EDOM \" retval is x/0.0 +\ \ HUGE_VAL : +\ \ \-HUGE_VAL +cosh(fin) o/f OVERFLOW HUGE n ERANGE +sinh(fin) o/f OVERFLOW (x>0.0) ? n ERANGE +\ \ HUGE : \-HUGE +sqrt(x<0) DOMAIN 0.0 y EDOM +hypot(fin,fin) o/f OVERFLOW HUGE n ERANGE +exp(fin) o/f OVERFLOW HUGE n ERANGE +exp(fin) u/f UNDERFLOW 0.0 n ERANGE +exp2(fin) o/f OVERFLOW HUGE n ERANGE +exp2(fin) u/f UNDERFLOW 0.0 n ERANGE +exp10(fin) o/f OVERFLOW HUGE n ERANGE +exp10(fin) u/f UNDERFLOW 0.0 n ERANGE +j0(|x|>X_TLOSS) TLOSS 0.0 y ERANGE +j1(|x|>X_TLOSS) TLOSS 0.0 y ERANGE +jn(|x|>X_TLOSS) TLOSS 0.0 y ERANGE +y0(x>X_TLOSS) TLOSS 0.0 y ERANGE +y1(x>X_TLOSS) TLOSS 0.0 y ERANGE +yn(x>X_TLOSS) TLOSS 0.0 y ERANGE +y0(0) DOMAIN \-HUGE y EDOM +y0(x<0) DOMAIN \-HUGE y EDOM +y1(0) DOMAIN \-HUGE y EDOM +y1(x<0) DOMAIN \-HUGE y EDOM +yn(n,0) DOMAIN \-HUGE y EDOM +yn(x<0) DOMAIN \-HUGE y EDOM +lgamma(fin) o/f OVERFLOW HUGE n ERANGE +lgamma(\-int) or SING HUGE y EDOM +\ \ lgamma(0) +tgamma(fin) o/f OVERFLOW HUGE_VAL n ERANGE +tgamma(\-int) SING NAN y EDOM +tgamma(0) SING copysign( y ERANGE +\ \ HUGE_VAL,x) +log(0) SING \-HUGE y EDOM +log(x<0) DOMAIN \-HUGE y EDOM +log2(0) SING \-HUGE n EDOM \" different from log() +log2(x<0) DOMAIN \-HUGE n EDOM \" different from log() +log10(0) SING \-HUGE y EDOM +log10(x<0) DOMAIN \-HUGE y EDOM +pow(0.0,0.0) DOMAIN 0.0 y EDOM +pow(x,y) o/f OVERFLOW HUGE n ERANGE +pow(x,y) u/f UNDERFLOW 0.0 n ERANGE +pow(NaN,0.0) DOMAIN x n EDOM +0**neg DOMAIN 0.0 y EDOM \" +0 and -0 +neg**non-int DOMAIN 0.0 y EDOM +scalb() o/f OVERFLOW (x>0.0) ? n ERANGE +\ \ HUGE_VAL : +\ \ \-HUGE_VAL +scalb() u/f UNDERFLOW copysign( n ERANGE +\ \ \ \ 0.0,x) +fmod(x,0) DOMAIN x y EDOM +remainder(x,0) DOMAIN NAN y EDOM \" retval is 0.0/0.0 +.TE +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR matherr () +T} Thread safety MT-Safe +.TE +.SH EXAMPLES +The example program demonstrates the use of +.BR matherr () +when calling +.BR log (3). +The program takes up to three command-line arguments. +The first argument is the floating-point number to be given to +.BR log (3). +If the optional second argument is provided, then +.B _LIB_VERSION +is set to +.B _SVID_ +so that +.BR matherr () +is called, and the integer supplied in the +command-line argument is used as the return value from +.BR matherr (). +If the optional third command-line argument is supplied, +then it specifies an alternative return value that +.BR matherr () +should assign as the return value of the math function. +.P +The following example run, where +.BR log (3) +is given an argument of 0.0, does not use +.BR matherr (): +.P +.in +4n +.EX +.RB "$" " ./a.out 0.0" +errno: Numerical result out of range +x=\-inf +.EE +.in +.P +In the following run, +.BR matherr () +is called, and returns 0: +.P +.in +4n +.EX +.RB "$" " ./a.out 0.0 0" +matherr SING exception in log() function + args: 0.000000, 0.000000 + retval: \-340282346638528859811704183484516925440.000000 +log: SING error +errno: Numerical argument out of domain +x=\-340282346638528859811704183484516925440.000000 +.EE +.in +.P +The message "log: SING error" was printed by the C library. +.P +In the following run, +.BR matherr () +is called, and returns a nonzero value: +.P +.in +4n +.EX +.RB "$" " ./a.out 0.0 1" +matherr SING exception in log() function + args: 0.000000, 0.000000 + retval: \-340282346638528859811704183484516925440.000000 +x=\-340282346638528859811704183484516925440.000000 +.EE +.in +.P +In this case, the C library did not print a message, and +.I errno +was not set. +.P +In the following run, +.BR matherr () +is called, changes the return value of the math function, +and returns a nonzero value: +.P +.in +4n +.EX +.RB "$" " ./a.out 0.0 1 12345.0" +matherr SING exception in log() function + args: 0.000000, 0.000000 + retval: \-340282346638528859811704183484516925440.000000 +x=12345.000000 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (matherr.c) +.EX +#define _SVID_SOURCE +#include +#include +#include +#include +\& +static int matherr_ret = 0; /* Value that matherr() + should return */ +static int change_retval = 0; /* Should matherr() change + function\[aq]s return value? */ +static double new_retval; /* New function return value */ +\& +int +matherr(struct exception *exc) +{ + fprintf(stderr, "matherr %s exception in %s() function\en", + (exc\->type == DOMAIN) ? "DOMAIN" : + (exc\->type == OVERFLOW) ? "OVERFLOW" : + (exc\->type == UNDERFLOW) ? "UNDERFLOW" : + (exc\->type == SING) ? "SING" : + (exc\->type == TLOSS) ? "TLOSS" : + (exc\->type == PLOSS) ? "PLOSS" : "???", + exc\->name); + fprintf(stderr, " args: %f, %f\en", + exc\->arg1, exc\->arg2); + fprintf(stderr, " retval: %f\en", exc\->retval); +\& + if (change_retval) + exc\->retval = new_retval; +\& + return matherr_ret; +} +\& +int +main(int argc, char *argv[]) +{ + double x; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s " + " [ []]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (argc > 2) { + _LIB_VERSION = _SVID_; + matherr_ret = atoi(argv[2]); + } +\& + if (argc > 3) { + change_retval = 1; + new_retval = atof(argv[3]); + } +\& + x = log(atof(argv[1])); + if (errno != 0) + perror("errno"); +\& + printf("x=%f\en", x); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fenv (3), +.BR math_error (7), +.BR standards (7) diff --git a/man/man3/mblen.3 b/man/man3/mblen.3 new file mode 100644 index 0000000..f253965 --- /dev/null +++ b/man/man3/mblen.3 @@ -0,0 +1,117 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mblen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mblen \- determine number of bytes in next multibyte character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mblen(const char " s [. n "], size_t " n ); +.fi +.SH DESCRIPTION +If +.I s +is not NULL, the +.BR mblen () +function inspects at most +.I n +bytes of the multibyte string starting at +.I s +and extracts the +next complete multibyte character. +It uses a static anonymous shift state known only to the +.BR mblen () +function. +If the multibyte character is not the null wide +character, it returns the number of bytes that were consumed from +.IR s . +If the multibyte character is the null wide character, it returns 0. +.P +If the +.I n +bytes starting at +.I s +do not contain a complete multibyte +character, +.BR mblen () +returns \-1. +This can happen even if +.I n +is greater than or equal to +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift sequences. +.P +If the multibyte string starting at +.I s +contains an invalid multibyte +sequence before the next complete character, +.BR mblen () +also returns \-1. +.P +If +.I s +is NULL, the +.BR mblen () +function +.\" The Dinkumware doc and the Single UNIX specification say this, but +.\" glibc doesn't implement this. +resets the shift state, known to only this function, to the initial state, and +returns nonzero if the encoding has nontrivial shift state, or zero if the +encoding is stateless. +.SH RETURN VALUE +The +.BR mblen () +function returns the number of +bytes parsed from the multibyte +sequence starting at +.IR s , +if a non-null wide character was recognized. +It returns 0, if a null wide character was recognized. +It returns \-1, if an +invalid multibyte sequence was encountered or if it couldn't parse a complete +multibyte character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mblen () +T} Thread safety MT-Unsafe race +.TE +.SH VERSIONS +The function +.BR mbrlen (3) +provides a better interface to the same +functionality. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mblen () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbrlen (3) diff --git a/man/man3/mbrlen.3 b/man/man3/mbrlen.3 new file mode 100644 index 0000000..83d9d36 --- /dev/null +++ b/man/man3/mbrlen.3 @@ -0,0 +1,130 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbrlen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbrlen \- determine number of bytes in next multibyte character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t mbrlen(const char " s "[restrict ." n "], size_t " n , +.BI " mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +The +.BR mbrlen () +function inspects at most +.I n +bytes of the multibyte +string starting at +.I s +and extracts the next complete multibyte character. +It updates the shift state +.IR *ps . +If the multibyte character is not the +null wide character, it returns the number of bytes that were consumed from +.IR s . +If the multibyte character is the null wide character, it resets the +shift state +.I *ps +to the initial state and returns 0. +.P +If the +.I n +bytes starting at +.I s +do not contain a complete multibyte +character, +.BR mbrlen () +returns +.IR "(size_t)\ \-2" . +This can happen even if +.I n +>= +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift +sequences. +.P +If the multibyte string starting at +.I s +contains an invalid multibyte +sequence before the next complete character, +.BR mbrlen () +returns +.I (size_t)\ \-1 +and sets +.I errno +to +.BR EILSEQ . +In this case, +the effects on +.I *ps +are undefined. +.P +If +.I ps +is NULL, a static anonymous state known only to the +.BR mbrlen () +function is used instead. +.SH RETURN VALUE +The +.BR mbrlen () +function returns the number of bytes +parsed from the multibyte +sequence starting at +.IR s , +if a non-null wide character was recognized. +It returns 0, if a null wide character was recognized. +It returns +.I "(size_t)\ \-1" +and sets +.I errno +to +.BR EILSEQ , +if an invalid multibyte sequence was +encountered. +It returns +.I (size_t)\ \-2 +if it couldn't parse a complete multibyte +character, meaning that +.I n +should be increased. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbrlen () +T} Thread safety MT-Unsafe race:mbrlen/!ps +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbrlen () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbrtowc (3) diff --git a/man/man3/mbrtowc.3 b/man/man3/mbrtowc.3 new file mode 100644 index 0000000..e0cc56e --- /dev/null +++ b/man/man3/mbrtowc.3 @@ -0,0 +1,201 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbrtowc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbrtowc \- convert a multibyte sequence to a wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t mbrtowc(wchar_t *restrict " pwc ", const char " s "[restrict ." n ], +.BI " size_t " n ", mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +The main case for this function is when +.I s +is not NULL and +.I pwc +is +not NULL. +In this case, the +.BR mbrtowc () +function inspects at most +.I n +bytes of the multibyte string starting at +.IR s , +extracts the next complete +multibyte character, converts it to a wide character and stores it at +.IR *pwc . +It updates the shift state +.IR *ps . +If the converted wide +character is not L\[aq]\e0\[aq] (the null wide character), +it returns the number of bytes that were consumed +from +.IR s . +If the converted wide character is L\[aq]\e0\[aq], it resets the shift +state +.I *ps +to the initial state and returns 0. +.P +If the +.I n +bytes starting at +.I s +do not contain a complete multibyte +character, +.BR mbrtowc () +returns +.IR "(size_t)\ \-2" . +This can happen even if +.I n +>= +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift +sequences. +.P +If the multibyte string starting at +.I s +contains an invalid multibyte +sequence before the next complete character, +.BR mbrtowc () +returns +.I (size_t)\ \-1 +and sets +.I errno +to +.BR EILSEQ . +In this case, +the effects on +.I *ps +are undefined. +.P +A different case is when +.I s +is not NULL but +.I pwc +is NULL. +In this case, the +.BR mbrtowc () +function behaves as above, except that it does not +store the converted wide character in memory. +.P +A third case is when +.I s +is NULL. +In this case, +.I pwc +and +.I n +are +ignored. +If the conversion state represented by +.I *ps +denotes an +incomplete multibyte character conversion, the +.BR mbrtowc () +function +returns +.IR "(size_t)\ \-1" , +sets +.I errno +to +.BR EILSEQ , +and +leaves +.I *ps +in an undefined state. +Otherwise, the +.BR mbrtowc () +function +puts +.I *ps +in the initial state and returns 0. +.P +In all of the above cases, if +.I ps +is NULL, a static anonymous +state known only to the +.BR mbrtowc () +function is used instead. +Otherwise, +.I *ps +must be a valid +.I mbstate_t +object. +An +.I mbstate_t +object +.I a +can be initialized to the initial state +by zeroing it, for example using +.P +.in +4n +.EX +memset(&a, 0, sizeof(a)); +.EE +.in +.SH RETURN VALUE +The +.BR mbrtowc () +function returns the number of bytes parsed from the +multibyte sequence starting at +.IR s , +if a non-L\[aq]\e0\[aq] wide character +was recognized. +It returns 0, if a L\[aq]\e0\[aq] wide character was recognized. +It returns +.I (size_t)\ \-1 +and sets +.I errno +to +.BR EILSEQ , +if an invalid multibyte sequence was +encountered. +It returns +.I "(size_t)\ \-2" +if it couldn't parse a complete multibyte +character, meaning that +.I n +should be increased. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbrtowc () +T} Thread safety MT-Unsafe race:mbrtowc/!ps +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbrtowc () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbsinit (3), +.BR mbsrtowcs (3) diff --git a/man/man3/mbsinit.3 b/man/man3/mbsinit.3 new file mode 100644 index 0000000..00049c5 --- /dev/null +++ b/man/man3/mbsinit.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright, Bruno Haible +.\" Copyright 2024, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbsinit 3 2024-05-03 "Linux man-pages (unreleased)" +.SH NAME +mbsinit +\- +test for initial shift state +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mbsinit(const mbstate_t *" ps ); +.fi +.SH DESCRIPTION +The function +.BR mbsinit () +tests whether +.I *ps +corresponds to an +initial state. +.SH RETURN VALUE +.BR mbsinit () +returns nonzero if +.I *ps +is an initial state, or if +.I ps +is NULL. +Otherwise, it returns 0. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbsinit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbsinit () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mbstate_t (3type), +.BR mbrlen (3), +.BR mbrtowc (3), +.BR mbsrtowcs (3), +.BR wcrtomb (3), +.BR wcsrtombs (3) diff --git a/man/man3/mbsnrtowcs.3 b/man/man3/mbsnrtowcs.3 new file mode 100644 index 0000000..5b03f7c --- /dev/null +++ b/man/man3/mbsnrtowcs.3 @@ -0,0 +1,199 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH mbsnrtowcs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbsnrtowcs \- convert a multibyte string to a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t mbsnrtowcs(wchar_t " dest "[restrict ." len "], const char **restrict " src , +.BI " size_t " nms ", size_t " len \ +", mbstate_t *restrict " ps ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mbsnrtowcs (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR mbsnrtowcs () +function is like the +.BR mbsrtowcs (3) +function, except that +the number of bytes to be converted, starting at +.IR *src , +is limited to at most +.I nms +bytes. +.P +If +.I dest +is not NULL, the +.BR mbsnrtowcs () +function converts at +most +.I nms +bytes from the +multibyte string +.I *src +to a wide-character string starting at +.IR dest . +At most +.I len +wide characters are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.I "mbrtowc(dest, *src, n, ps)" +where +.I n +is some +positive number, as long as this call succeeds, and then incrementing +.I dest +by one and +.I *src +by the number of bytes consumed. +The +conversion can stop for three reasons: +.IP \[bu] 3 +An invalid multibyte sequence has been encountered. +In this case, +.I *src +is left pointing to the invalid multibyte sequence, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP \[bu] +The +.I nms +limit forces a stop, +or +.I len +non-L\[aq]\e0\[aq] wide characters +have been stored at +.IR dest . +In this case, +.I *src +is left pointing to the +next multibyte sequence to be converted, and the number of wide characters +written to +.I dest +is returned. +.IP \[bu] +The multibyte string has been completely converted, including the +terminating null wide character (\[aq]\e0\[aq]) +(which has the side effect of bringing back +.I *ps +to the +initial state). +In this case, +.I *src +is set to NULL, and the number of wide +characters written to +.IR dest , +excluding the terminating null wide character, +is returned. +.P +According to POSIX.1, +if the input buffer ends with an incomplete character, +it is unspecified whether conversion stops at the end of +the previous character (if any), or at the end of the input buffer. +The glibc implementation adopts the former behavior. +.P +If +.I dest +is NULL, +.I len +is ignored, and the conversion proceeds as +above, except that the converted wide characters +are not written out to memory, +and that no destination length limit exists. +.P +In both of the above cases, if +.I ps +is NULL, a static anonymous +state known only to the +.BR mbsnrtowcs () +function is used instead. +.P +The programmer must ensure that there is room for at least +.I len +wide +characters at +.IR dest . +.SH RETURN VALUE +The +.BR mbsnrtowcs () +function returns the number of wide characters +that make up the converted part of the wide-character string, +not including the terminating null wide character. +If an invalid multibyte sequence was +encountered, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbsnrtowcs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:mbsnrtowcs/!ps +T} +.TE +.SH STANDARDS +POSIX.1-2008. +.SH NOTES +The behavior of +.BR mbsnrtowcs () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbrtowc (3), +.BR mbsinit (3), +.BR mbsrtowcs (3) diff --git a/man/man3/mbsrtowcs.3 b/man/man3/mbsrtowcs.3 new file mode 100644 index 0000000..bf70295 --- /dev/null +++ b/man/man3/mbsrtowcs.3 @@ -0,0 +1,170 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbsrtowcs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbsrtowcs \- convert a multibyte string to a wide-character string (restartable) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t mbsrtowcs(wchar_t " dest "[restrict ." dsize ], +.BI " const char **restrict " src , +.BI " size_t " dsize ", mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, +convert the +multibyte string +.I *src +to a wide-character string starting at +.IR dest . +At most +.I dsize +wide characters are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.I "mbrtowc(dest, *src, n, ps)" +where +.I n +is some +positive number, as long as this call succeeds, and then incrementing +.I dest +by one and +.I *src +by the number of bytes consumed. +The conversion can stop for three reasons: +.IP \[bu] 3 +An invalid multibyte sequence has been encountered. +In this case, +.I *src +is left pointing to the invalid multibyte sequence, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP \[bu] +.I dsize +non-L\[aq]\e0\[aq] wide characters have been stored at +.IR dest . +In this case, +.I *src +is left pointing to the next +multibyte sequence to be converted, +and the number of wide characters written to +.I dest +is returned. +.IP \[bu] +The multibyte string has been completely converted, including the +terminating null wide character (\[aq]\e0\[aq]), which has the side +effect of bringing back +.I *ps +to the +initial state. +In this case, +.I *src +is set to NULL, and the number of wide +characters written to +.IR dest , +excluding the terminating null wide character, is returned. +.P +If +.I dest +is NULL, +.I dsize +is ignored, +and the conversion proceeds as above, +except that the converted wide characters are not written out to memory, +and that no length limit exists. +.P +In both of the above cases, +if +.I ps +is NULL, a static anonymous +state known only to the +.BR mbsrtowcs () +function is used instead. +.P +In order to avoid the case 2 above, the programmer should make sure +.I dsize +is +greater than or equal to +.IR "mbsrtowcs(NULL,src,0,ps)+1" . +.P +The programmer must ensure that there is room for at least +.I dsize +wide +characters at +.IR dest . +.P +This function is a restartable version of +.BR mbstowcs (3). +.SH RETURN VALUE +The number of wide characters that make +up the converted part of the wide-character string, not including the +terminating null wide character. +If an invalid multibyte sequence was +encountered, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbsrtowcs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:mbsrtowcs/!ps +T} +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbsrtowcs () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbrtowc (3), +.BR mbsinit (3), +.BR mbsnrtowcs (3), +.BR mbstowcs (3) diff --git a/man/man3/mbstowcs.3 b/man/man3/mbstowcs.3 new file mode 100644 index 0000000..f1c4ea5 --- /dev/null +++ b/man/man3/mbstowcs.3 @@ -0,0 +1,237 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" and Copyright 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbstowcs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbstowcs \- convert a multibyte string to a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t mbstowcs(wchar_t " dest "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, +convert the +multibyte string +.I src +to a wide-character string starting at +.IR dest . +At most +.I dsize +wide characters are written to +.IR dest . +The sequence of characters in the string +.I src +shall begin in the initial shift state. +The conversion can stop for three reasons: +.IP \[bu] 3 +An invalid multibyte sequence has been encountered. +In this case, +.I (size_t)\ \-1 +is returned. +.IP \[bu] +.I dsize +non-L\[aq]\e0\[aq] wide characters have been stored at +.IR dest . +In this case, the number of wide characters written to +.I dest +is returned, but the +shift state at this point is lost. +.IP \[bu] +The multibyte string has been completely converted, including the +terminating null character (\[aq]\e0\[aq]). +In this case, the number of wide characters written to +.IR dest , +excluding the terminating null wide character, is returned. +.P +If +.I dest +is NULL, +.I dsize +is ignored, and the conversion proceeds as +above, except that the converted wide characters are not written out to memory, +and that no length limit exists. +.P +In order to avoid the case 2 above, the programmer should make sure +.I dsize +is +greater than or equal to +.IR "mbstowcs(NULL,src,0)+1" . +.P +The programmer must ensure that there is room for at least +.I dsize +wide +characters at +.IR dest . +.SH RETURN VALUE +The number of wide characters that make +up the converted part of the wide-character string, not including the +terminating null wide character. +If an invalid multibyte sequence was +encountered, +.I (size_t)\ \-1 +is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbstowcs () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The function +.BR mbsrtowcs (3) +provides a better interface to the same +functionality. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbstowcs () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH EXAMPLES +The program below illustrates the use of +.BR mbstowcs (), +as well as some of the wide character classification functions. +An example run is the following: +.P +.in +4n +.EX +$ ./t_mbstowcs de_DE.UTF\-8 Grüße! +Length of source string (excluding terminator): + 8 bytes + 6 multibyte characters +\& +Wide character string is: Grüße! (6 characters) + G alpha upper + r alpha lower + ü alpha lower + ß alpha lower + e alpha lower + ! !alpha +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mbstowcs.c) +.EX +#include +#include +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + size_t mbslen; /* Number of multibyte characters in source */ + wchar_t *wcs; /* Pointer to converted wide character string */ +\& + if (argc < 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Apply the specified locale. */ +\& + if (setlocale(LC_ALL, argv[1]) == NULL) { + perror("setlocale"); + exit(EXIT_FAILURE); + } +\& + /* Calculate the length required to hold argv[2] converted to + a wide character string. */ +\& + mbslen = mbstowcs(NULL, argv[2], 0); + if (mbslen == (size_t) \-1) { + perror("mbstowcs"); + exit(EXIT_FAILURE); + } +\& + /* Describe the source string to the user. */ +\& + printf("Length of source string (excluding terminator):\en"); + printf(" %zu bytes\en", strlen(argv[2])); + printf(" %zu multibyte characters\en\en", mbslen); +\& + /* Allocate wide character string of the desired size. Add 1 + to allow for terminating null wide character (L\[aq]\e0\[aq]). */ +\& + wcs = calloc(mbslen + 1, sizeof(*wcs)); + if (wcs == NULL) { + perror("calloc"); + exit(EXIT_FAILURE); + } +\& + /* Convert the multibyte character string in argv[2] to a + wide character string. */ +\& + if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) { + perror("mbstowcs"); + exit(EXIT_FAILURE); + } +\& + printf("Wide character string is: %ls (%zu characters)\en", + wcs, mbslen); +\& + /* Now do some inspection of the classes of the characters in + the wide character string. */ +\& + for (wchar_t *wp = wcs; *wp != 0; wp++) { + printf(" %lc ", (wint_t) *wp); +\& + if (!iswalpha(*wp)) + printf("!"); + printf("alpha "); +\& + if (iswalpha(*wp)) { + if (iswupper(*wp)) + printf("upper "); +\& + if (iswlower(*wp)) + printf("lower "); + } +\& + putchar(\[aq]\en\[aq]); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR mblen (3), +.BR mbsrtowcs (3), +.BR mbtowc (3), +.BR wcstombs (3), +.BR wctomb (3) diff --git a/man/man3/mbtowc.3 b/man/man3/mbtowc.3 new file mode 100644 index 0000000..4057959 --- /dev/null +++ b/man/man3/mbtowc.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbtowc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mbtowc \- convert a multibyte sequence to a wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mbtowc(wchar_t *restrict " pwc ", const char " s "[restrict ." n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The main case for this function is when +.I s +is not NULL and +.I pwc +is +not NULL. +In this case, the +.BR mbtowc () +function inspects at most +.I n +bytes of the multibyte string starting at +.IR s , +extracts the next complete +multibyte character, converts it to a wide character and stores it at +.IR *pwc . +It updates an internal shift state known only to the +.BR mbtowc () +function. +If +.I s +does not point to a null byte (\[aq]\e0\[aq]), it returns the number +of bytes that were consumed from +.IR s , +otherwise it returns 0. +.P +If the +.I n +bytes starting at +.I s +do not contain a complete multibyte +character, or if they contain an invalid multibyte sequence, +.BR mbtowc () +returns \-1. +This can happen even if +.I n +>= +.IR MB_CUR_MAX , +if the multibyte string contains redundant shift sequences. +.P +A different case is when +.I s +is not NULL but +.I pwc +is NULL. +In this case, the +.BR mbtowc () +function behaves as above, except that it does not +store the converted wide character in memory. +.P +A third case is when +.I s +is NULL. +In this case, +.I pwc +and +.I n +are +ignored. +The +.BR mbtowc () +function +.\" The Dinkumware doc and the Single UNIX specification say this, but +.\" glibc doesn't implement this. +resets the shift state, only known to this function, +to the initial state, and +returns nonzero if the encoding has nontrivial shift state, or zero if the +encoding is stateless. +.SH RETURN VALUE +If +.I s +is not NULL, the +.BR mbtowc () +function returns the number of +consumed bytes starting at +.IR s , +or 0 if +.I s +points to a null byte, +or \-1 upon failure. +.P +If +.I s +is NULL, the +.BR mbtowc () +function +returns nonzero if the encoding +has nontrivial shift state, or zero if the encoding is stateless. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mbtowc () +T} Thread safety MT-Unsafe race +.TE +.SH VERSIONS +This function is not multithread safe. +The function +.BR mbrtowc (3) +provides +a better interface to the same functionality. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR mbtowc () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR MB_CUR_MAX (3), +.BR mblen (3), +.BR mbrtowc (3), +.BR mbstowcs (3), +.BR wcstombs (3), +.BR wctomb (3) diff --git a/man/man3/mcheck.3 b/man/man3/mcheck.3 new file mode 100644 index 0000000..0d3a7da --- /dev/null +++ b/man/man3/mcheck.3 @@ -0,0 +1,213 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mcheck 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mcheck, mcheck_check_all, mcheck_pedantic, mprobe \- heap consistency checking +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mcheck(void (*" abortfunc ")(enum mcheck_status " mstatus )); +.BI "int mcheck_pedantic(void (*" abortfunc ")(enum mcheck_status " mstatus )); +.B void mcheck_check_all(void); +.P +.BI "enum mcheck_status mprobe(void *" ptr ); +.fi +.SH DESCRIPTION +The +.BR mcheck () +function installs a set of debugging hooks for the +.BR malloc (3) +family of memory-allocation functions. +These hooks cause certain consistency checks to be performed +on the state of the heap. +The checks can detect application errors such as freeing a block of memory +more than once or corrupting the bookkeeping data structures +that immediately precede a block of allocated memory. +.P +To be effective, the +.BR mcheck () +function must be called before the first call to +.BR malloc (3) +or a related function. +In cases where this is difficult to ensure, linking the program with +.I \-lmcheck +inserts an implicit call to +.BR mcheck () +(with a NULL argument) +before the first call to a memory-allocation function. +.P +The +.BR mcheck_pedantic () +function is similar to +.BR mcheck (), +but performs checks on all allocated blocks whenever +one of the memory-allocation functions is called. +This can be very slow! +.P +The +.BR mcheck_check_all () +function causes an immediate check on all allocated blocks. +This call is effective only if +.BR mcheck () +is called beforehand. +.P +If the system detects an inconsistency in the heap, +the caller-supplied function pointed to by +.I abortfunc +is invoked with a single argument, +.IR mstatus , +that indicates what type of inconsistency was detected. +If +.I abortfunc +is NULL, a default function prints an error message on +.I stderr +and calls +.BR abort (3). +.P +The +.BR mprobe () +function performs a consistency check on +the block of allocated memory pointed to by +.IR ptr . +The +.BR mcheck () +function should be called beforehand (otherwise +.BR mprobe () +returns +.BR MCHECK_DISABLED ). +.P +The following list describes the values returned by +.BR mprobe () +or passed as the +.I mstatus +argument when +.I abortfunc +is invoked: +.TP +.BR MCHECK_DISABLED " (" mprobe "() only)" +.BR mcheck () +was not called before the first memory allocation function was called. +Consistency checking is not possible. +.TP +.BR MCHECK_OK " (" mprobe "() only)" +No inconsistency detected. +.TP +.B MCHECK_HEAD +Memory preceding an allocated block was clobbered. +.TP +.B MCHECK_TAIL +Memory following an allocated block was clobbered. +.TP +.B +MCHECK_FREE +A block of memory was freed twice. +.SH RETURN VALUE +.BR mcheck () +and +.BR mcheck_pedantic () +return 0 on success, or \-1 on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mcheck (), +.BR mcheck_pedantic (), +.BR mcheck_check_all (), +.BR mprobe () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:mcheck +const:malloc_hooks +T} +.TE +.SH STANDARDS +GNU. +.SH HISTORY +.TP +.BR mcheck_pedantic () +.TQ +.BR mcheck_check_all () +glibc 2.2. +.TP +.BR mcheck () +.TQ +.BR mprobe () +glibc 2.0. +.SH NOTES +Linking a program with +.I \-lmcheck +and using the +.B MALLOC_CHECK_ +environment variable (described in +.BR mallopt (3)) +cause the same kinds of errors to be detected. +But, using +.B MALLOC_CHECK_ +does not require the application to be relinked. +.\" But is MALLOC_CHECK_ slower? +.SH EXAMPLES +The program below calls +.BR mcheck () +with a NULL argument and then frees the same block of memory twice. +The following shell session demonstrates what happens +when running the program: +.P +.in +4n +.EX +.RB "$" " ./a.out" +About to free +\& +About to free a second time +block freed twice +Aborted (core dumped) +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mcheck.c) +.EX +#include +#include +#include +\& +int +main(void) +{ + char *p; +\& + if (mcheck(NULL) != 0) { + fprintf(stderr, "mcheck() failed\en"); +\& + exit(EXIT_FAILURE); + } +\& + p = malloc(1000); +\& + fprintf(stderr, "About to free\en"); + free(p); + fprintf(stderr, "\enAbout to free a second time\en"); + free(p); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR malloc (3), +.BR mallopt (3), +.BR mtrace (3) diff --git a/man/man3/mcheck_check_all.3 b/man/man3/mcheck_check_all.3 new file mode 100644 index 0000000..4baeaf2 --- /dev/null +++ b/man/man3/mcheck_check_all.3 @@ -0,0 +1 @@ +.so man3/mcheck.3 diff --git a/man/man3/mcheck_pedantic.3 b/man/man3/mcheck_pedantic.3 new file mode 100644 index 0000000..4baeaf2 --- /dev/null +++ b/man/man3/mcheck_pedantic.3 @@ -0,0 +1 @@ +.so man3/mcheck.3 diff --git a/man/man3/memalign.3 b/man/man3/memalign.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man/man3/memalign.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man/man3/memccpy.3 b/man/man3/memccpy.3 new file mode 100644 index 0000000..da4acf9 --- /dev/null +++ b/man/man3/memccpy.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:57:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH memccpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memccpy \- copy memory area +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *memccpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ], +.BI " int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memccpy () +function copies no more than +.I n +bytes from +memory area +.I src +to memory area +.IR dest , +stopping when the +character +.I c +is found. +.P +If the memory areas overlap, the results are undefined. +.SH RETURN VALUE +The +.BR memccpy () +function returns a pointer to the next character +in +.I dest +after +.IR c , +or NULL if +.I c +was not found in the +first +.I n +characters of +.IR src . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memccpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bcopy (3), +.BR bstring (3), +.BR memcpy (3), +.BR memmove (3), +.BR strcpy (3), +.BR strncpy (3) diff --git a/man/man3/memchr.3 b/man/man3/memchr.3 new file mode 100644 index 0000000..f831625 --- /dev/null +++ b/man/man3/memchr.3 @@ -0,0 +1,142 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Mon Apr 12 12:49:57 1993, David Metcalfe +.\" Modified Sat Jul 24 18:56:22 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Feb 20 21:09:36 2002, Ian Redfern (redferni@logica.com) +.\" 2008-07-09, mtk, add rawmemchr() +.\" +.TH memchr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memchr, memrchr, rawmemchr \- scan memory for a character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *memchr(const void " s [. n "], int " c ", size_t " n ); +.BI "void *memrchr(const void " s [. n "], int " c ", size_t " n ); +.P +.BI "[[deprecated]] void *rawmemchr(const void *" s ", int " c ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR memrchr (), +.BR rawmemchr (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR memchr () +function scans the initial +.I n +bytes of the memory +area pointed to by +.I s +for the first instance of +.IR c . +Both +.I c +and the bytes of the memory area pointed to by +.I s +are interpreted as +.IR "unsigned char" . +.P +The +.BR memrchr () +function is like the +.BR memchr () +function, +except that it searches backward from the end of the +.I n +bytes pointed to by +.I s +instead of forward from the beginning. +.P +The +.BR rawmemchr () +function is similar to +.BR memchr (), +but it assumes +(i.e., the programmer knows for certain) +that an instance of +.I c +lies somewhere in the memory area starting at the location pointed to by +.IR s . +If an instance of +.I c +is not found, the behavior is undefined. +Use either +.BR strlen (3) +or +.BR memchr (3) +instead. +.SH RETURN VALUE +The +.BR memchr () +and +.BR memrchr () +functions return a pointer +to the matching byte or NULL if the character does not occur in +the given memory area. +.P +The +.BR rawmemchr () +function returns a pointer to the matching byte. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memchr (), +.BR memrchr (), +.BR rawmemchr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR memchr () +C11, POSIX.1-2008. +.TP +.BR memrchr () +.TQ +.BR rawmemchr () +GNU. +.SH HISTORY +.TP +.BR memchr () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR memrchr () +glibc 2.2. +.TP +.BR rawmemchr () +glibc 2.1. +.SH SEE ALSO +.BR bstring (3), +.BR ffs (3), +.BR memmem (3), +.BR strchr (3), +.BR strpbrk (3), +.BR strrchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR wmemchr (3) diff --git a/man/man3/memcmp.3 b/man/man3/memcmp.3 new file mode 100644 index 0000000..efd362a --- /dev/null +++ b/man/man3/memcmp.3 @@ -0,0 +1,91 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:55:27 1993 by Rik Faith (faith@cs.unc.edu) +.TH memcmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memcmp \- compare memory areas +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int memcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memcmp () +function compares the first \fIn\fP bytes (each interpreted as +.IR "unsigned char" ) +of the memory areas \fIs1\fP and \fIs2\fP. +.SH RETURN VALUE +The +.BR memcmp () +function returns an integer less than, equal to, or +greater than zero if the first \fIn\fP bytes of \fIs1\fP is found, +respectively, to be less than, to match, or be greater than the first +\fIn\fP bytes of \fIs2\fP. +.P +For a nonzero return value, the sign is determined by the sign of +the difference between the first pair of bytes (interpreted as +.IR "unsigned char" ) +that differ in +.I s1 +and +.IR s2 . +.P +If +.I n +is zero, the return value is zero. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memcmp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH CAVEATS +Do not use +.BR memcmp () +to compare confidential data, +such as cryptographic secrets, +because the CPU time required for the comparison +depends on the contents of the addresses compared, +this function is subject to timing-based side-channel attacks. +In such cases, +a function that performs comparisons in deterministic time, +depending only on +.I n +(the quantity of bytes compared) +is required. +Some operating systems provide such a function (e.g., NetBSD's +.BR consttime_memequal ()), +but no such function is specified in POSIX. +On Linux, you may need to implement such a function yourself. +.SH SEE ALSO +.BR bstring (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strncasecmp (3), +.BR strncmp (3), +.BR wmemcmp (3) diff --git a/man/man3/memcpy.3 b/man/man3/memcpy.3 new file mode 100644 index 0000000..0c1d801 --- /dev/null +++ b/man/man3/memcpy.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:09 1993 by Rik Faith (faith@cs.unc.edu) +.TH memcpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memcpy \- copy memory area +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *memcpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memcpy () +function copies \fIn\fP bytes from memory area +\fIsrc\fP to memory area \fIdest\fP. +The memory areas must not overlap. +Use +.BR memmove (3) +if the memory areas do overlap. +.SH RETURN VALUE +The +.BR memcpy () +function returns a pointer to \fIdest\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memcpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH CAVEATS +Failure to observe the requirement that the memory areas +do not overlap has been the source of significant bugs. +(POSIX and the C standards are explicit that employing +.BR memcpy () +with overlapping areas produces undefined behavior.) +Most notably, in glibc 2.13 +.\" glibc commit 6fb8cbcb58a29fff73eb2101b34caa19a7f88eba +a performance optimization of +.BR memcpy () +on some platforms (including x86-64) included changing the order +.\" From forward copying to backward copying +in which bytes were copied from +.I src +to +.IR dest . +.P +This change revealed breakages in a number of applications that performed +copying with overlapping areas. +.\" Adobe Flash player was the highest profile example: +.\" https://bugzilla.redhat.com/show_bug.cgi?id=638477 +.\" Reported: 2010-09-29 02:35 EDT by JCHuynh +.\" Bug 638477 - Strange sound on mp3 flash website +.\" +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=12518 +.\" Bug 12518 - memcpy acts randomly (and differently) with overlapping areas +.\" Reported: 2011-02-25 02:26 UTC by Linus Torvalds +.\" +Under the previous implementation, +the order in which the bytes were copied had fortuitously hidden the bug, +which was revealed when the copying order was reversed. +In glibc 2.14, +.\" glibc commit 0354e355014b7bfda32622e0255399d859862fcd +a versioned symbol was added so that old binaries +(i.e., those linked against glibc versions earlier than 2.14) +employed a +.BR memcpy () +implementation that safely handles the overlapping buffers case +(by providing an "older" +.BR memcpy () +implementation that was aliased to +.BR memmove (3)). +.SH SEE ALSO +.BR bcopy (3), +.BR bstring (3), +.BR memccpy (3), +.BR memmove (3), +.BR mempcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR wmemcpy (3) diff --git a/man/man3/memfrob.3 b/man/man3/memfrob.3 new file mode 100644 index 0000000..c6178e5 --- /dev/null +++ b/man/man3/memfrob.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:54:45 1993 by Rik Faith (faith@cs.unc.edu) +.TH memfrob 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memfrob \- frobnicate (obfuscate) a memory area +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "void *memfrob(void " s [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memfrob () +function obfuscates the first \fIn\fP bytes of the +memory area \fIs\fP by exclusive-ORing each character with the number +42. +The effect can be reversed by using +.BR memfrob () +on the +obfuscated memory area. +.P +Note that this function is not a proper encryption routine as the XOR +constant is fixed, and is suitable only for hiding strings. +.SH RETURN VALUE +The +.BR memfrob () +function returns a pointer to the obfuscated memory +area. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memfrob () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR bstring (3), +.BR strfry (3) diff --git a/man/man3/memmem.3 b/man/man3/memmem.3 new file mode 100644 index 0000000..825a0d4 --- /dev/null +++ b/man/man3/memmem.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:50:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" Interchanged 'needle' and 'haystack'; added history, aeb, 980113. +.TH memmem 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memmem \- locate a substring +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "void *memmem(const void " haystack [. haystacklen "], size_t " haystacklen , +.BI " const void " needle [. needlelen "], size_t " needlelen ); +.fi +.SH DESCRIPTION +The +.BR memmem () +function finds the start of the first occurrence +of the substring +.I needle +of length +.I needlelen +in the memory +area +.I haystack +of length +.IR haystacklen . +.SH RETURN VALUE +The +.BR memmem () +function returns a pointer to the beginning of the +substring, or NULL if the substring is not found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memmem () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +musl libc 0.9.7; +FreeBSD 6.0, OpenBSD 5.4, NetBSD, Illumos. +.SH BUGS +.\" This function was broken in Linux libraries up to and including libc 5.0.9; +.\" there the +.\" .IR needle +.\" and +.\" .I haystack +.\" arguments were interchanged, +.\" and a pointer to the end of the first occurrence of +.\" .I needle +.\" was returned. +.\" +.\" Both old and new libc's have the bug that if +.\" .I needle +.\" is empty, +.\" .I haystack\-1 +.\" (instead of +.\" .IR haystack ) +.\" is returned. +In glibc 2.0, if +.I needle +is empty, +.BR memmem () +returns a pointer to the last byte of +.IR haystack . +This is fixed in glibc 2.1. +.SH SEE ALSO +.BR bstring (3), +.BR strstr (3) diff --git a/man/man3/memmove.3 b/man/man3/memmove.3 new file mode 100644 index 0000000..598fec7 --- /dev/null +++ b/man/man3/memmove.3 @@ -0,0 +1,71 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:49:59 1993 by Rik Faith (faith@cs.unc.edu) +.TH memmove 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memmove \- copy memory area +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *memmove(void " dest [. n "], const void " src [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memmove () +function copies +.I n +bytes from memory area +.I src +to memory area +.IR dest . +The memory areas may overlap: copying takes place as though +the bytes in +.I src +are first copied into a temporary array that does not overlap +.I src +or +.IR dest , +and the bytes are then copied from the temporary array to +.IR dest . +.SH RETURN VALUE +The +.BR memmove () +function returns a pointer to +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memmove () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bcopy (3), +.BR bstring (3), +.BR memccpy (3), +.BR memcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR wmemmove (3) diff --git a/man/man3/mempcpy.3 b/man/man3/mempcpy.3 new file mode 100644 index 0000000..f685a74 --- /dev/null +++ b/man/man3/mempcpy.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Heavily based on glibc infopages, copyright Free Software Foundation +.\" +.\" aeb, 2003, polished a little +.TH mempcpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mempcpy, wmempcpy \- copy memory area +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "void *mempcpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ], +.BI " size_t " n ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "wchar_t *wmempcpy(wchar_t " dest "[restrict ." n ], +.BI " const wchar_t " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR mempcpy () +function is nearly identical to the +.BR memcpy (3) +function. +It copies +.I n +bytes from the object beginning at +.I src +into the object pointed to by +.IR dest . +But instead of returning the value of +.I dest +it returns a pointer to the byte following the last written byte. +.P +This function is useful in situations where a number of objects +shall be copied to consecutive memory positions. +.P +The +.BR wmempcpy () +function is identical but takes +.I wchar_t +type arguments and copies +.I n +wide characters. +.SH RETURN VALUE +.I dest ++ +.IR n . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mempcpy (), +.BR wmempcpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH EXAMPLES +.EX +void * +combine(void *o1, size_t s1, void *o2, size_t s2) +{ + void *result = malloc(s1 + s2); + if (result != NULL) + mempcpy(mempcpy(result, o1, s1), o2, s2); + return result; +} +.EE +.SH SEE ALSO +.BR memccpy (3), +.BR memcpy (3), +.BR memmove (3), +.BR wmemcpy (3) diff --git a/man/man3/memrchr.3 b/man/man3/memrchr.3 new file mode 100644 index 0000000..b62c8f1 --- /dev/null +++ b/man/man3/memrchr.3 @@ -0,0 +1 @@ +.so man3/memchr.3 diff --git a/man/man3/memset.3 b/man/man3/memset.3 new file mode 100644 index 0000000..cb3c143 --- /dev/null +++ b/man/man3/memset.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:49:23 1993 by Rik Faith (faith@cs.unc.edu) +.TH memset 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +memset \- fill memory with a constant byte +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void *memset(void " s [. n "], int " c ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR memset () +function fills the first +.I n +bytes of the +memory area pointed to by +.I s +with the constant byte +.IR c . +.SH RETURN VALUE +The +.BR memset () +function returns a pointer to the memory area +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR memset () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bstring (3), +.BR bzero (3), +.BR swab (3), +.BR wmemset (3) diff --git a/man/man3/minor.3 b/man/man3/minor.3 new file mode 100644 index 0000000..eabbdd0 --- /dev/null +++ b/man/man3/minor.3 @@ -0,0 +1 @@ +.so man3/makedev.3 diff --git a/man/man3/mkdtemp.3 b/man/man3/mkdtemp.3 new file mode 100644 index 0000000..5a2332a --- /dev/null +++ b/man/man3/mkdtemp.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright 2001 John Levon +.\" Based on mkstemp(3), Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and GNU libc documentation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH mkdtemp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mkdtemp \- create a unique temporary directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *mkdtemp(char *" template ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mkdtemp (): +.nf + /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc 2.19 and earlier: */ _BSD_SOURCE + || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +The +.BR mkdtemp () +function generates a uniquely named temporary +directory from \fItemplate\fP. +The last six characters of \fItemplate\fP +must be XXXXXX and these are replaced with a string that makes the +directory name unique. +The directory is then created with +permissions 0700. +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.SH RETURN VALUE +The +.BR mkdtemp () +function returns a pointer to the modified template +string on success, and NULL on failure, in which case +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The last six characters of \fItemplate\fP were not XXXXXX. +Now \fItemplate\fP is unchanged. +.P +Also see +.BR mkdir (2) +for other possible values for \fIerrno\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mkdtemp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1.91. +NetBSD 1.4. +POSIX.1-2008. +.SH SEE ALSO +.BR mktemp (1), +.BR mkdir (2), +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man/man3/mkfifo.3 b/man/man3/mkfifo.3 new file mode 100644 index 0000000..46e1c14 --- /dev/null +++ b/man/man3/mkfifo.3 @@ -0,0 +1,201 @@ +'\" t +.\" This manpage is Copyright (C) 1995 James R. Van Zandt +.\" and Copyright (C) 2006, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" changed section from 2 to 3, aeb, 950919 +.\" +.TH mkfifo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mkfifo, mkfifoat \- make a FIFO special file (a named pipe) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int mkfifo(const char *" pathname ", mode_t " mode ); +.P +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.P +.BI "int mkfifoat(int " dirfd ", const char *" pathname ", mode_t " mode ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mkfifoat (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _ATFILE_SOURCE +.fi +.SH DESCRIPTION +.BR mkfifo () +makes a FIFO special file with name \fIpathname\fP. +\fImode\fP specifies the FIFO's permissions. +It is modified by the +process's \fBumask\fP in the usual way: the permissions of the created +file are \fB(\fP\fImode\fP\fB & \[ti]umask)\fP. +.P +A FIFO special file is similar to a pipe, except that it is created +in a different way. +Instead of being an anonymous communications +channel, a FIFO special file is entered into the filesystem by +calling +.BR mkfifo (). +.P +Once you have created a FIFO special file in this way, any process can +open it for reading or writing, in the same way as an ordinary file. +However, it has to be open at both ends simultaneously before you can +proceed to do any input or output operations on it. +Opening a FIFO for reading normally blocks until some +other process opens the same FIFO for writing, and vice versa. +See +.BR fifo (7) +for nonblocking handling of FIFO special files. +.SS mkfifoat() +The +.BR mkfifoat () +function operates in exactly the same way as +.BR mkfifo (), +except for the differences described here. +.P +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR mkfifo () +for a relative pathname). +.P +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR mkfifo ()). +.P +If +.I pathname +is absolute, then +.I dirfd +is ignored. +.P +See +.BR openat (2) +for an explanation of the need for +.BR mkfifoat (). +.SH RETURN VALUE +On success +.BR mkfifo () +and +.BR mkfifoat () +return 0. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +One of the directories in \fIpathname\fP did not allow search +(execute) permission. +.TP +.B EBADF +.RB ( mkfifoat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EDQUOT +The user's quota of disk blocks or inodes on the filesystem has been +exhausted. +.TP +.B EEXIST +\fIpathname\fP already exists. +This includes the case where +.I pathname +is a symbolic link, dangling or not. +.TP +.B ENAMETOOLONG +Either the total length of \fIpathname\fP is greater than +\fBPATH_MAX\fP, or an individual filename component has a length +greater than \fBNAME_MAX\fP. +In the GNU system, there is no imposed +limit on overall filename length, but some filesystems may place +limits on the length of a component. +.TP +.B ENOENT +A directory component in \fIpathname\fP does not exist or is a +dangling symbolic link. +.TP +.B ENOSPC +The directory or filesystem has no room for the new file. +.TP +.B ENOTDIR +A component used as a directory in \fIpathname\fP is not, in fact, a +directory. +.TP +.B ENOTDIR +.RB ( mkfifoat ()) +.I pathname +is a relative pathname and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B EROFS +\fIpathname\fP refers to a read-only filesystem. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mkfifo (), +.BR mkfifoat () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +It is implemented using +.BR mknodat (2). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR mkfifo () +POSIX.1-2001. +.TP +.BR mkfifoat () +glibc 2.4. +POSIX.1-2008. +.SH SEE ALSO +.BR mkfifo (1), +.BR close (2), +.BR open (2), +.BR read (2), +.BR stat (2), +.BR umask (2), +.BR write (2), +.BR fifo (7) diff --git a/man/man3/mkfifoat.3 b/man/man3/mkfifoat.3 new file mode 100644 index 0000000..25f4896 --- /dev/null +++ b/man/man3/mkfifoat.3 @@ -0,0 +1 @@ +.so man3/mkfifo.3 diff --git a/man/man3/mkostemp.3 b/man/man3/mkostemp.3 new file mode 100644 index 0000000..08cc2de --- /dev/null +++ b/man/man3/mkostemp.3 @@ -0,0 +1 @@ +.so man3/mkstemp.3 diff --git a/man/man3/mkostemps.3 b/man/man3/mkostemps.3 new file mode 100644 index 0000000..08cc2de --- /dev/null +++ b/man/man3/mkostemps.3 @@ -0,0 +1 @@ +.so man3/mkstemp.3 diff --git a/man/man3/mkstemp.3 b/man/man3/mkstemp.3 new file mode 100644 index 0000000..8461aae --- /dev/null +++ b/man/man3/mkstemp.3 @@ -0,0 +1,247 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2008, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:48:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 980310, aeb +.\" Modified 990328, aeb +.\" 2008-06-19, mtk, Added mkostemp(); various other changes +.\" +.TH mkstemp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mkstemp, mkostemp, mkstemps, mkostemps \- create a unique temporary file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mkstemp(char *" template ); +.BI "int mkostemp(char *" template ", int " flags ); +.BI "int mkstemps(char *" template ", int " suffixlen ); +.BI "int mkostemps(char *" template ", int " suffixlen ", int " flags ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mkstemp (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR mkostemp (): +.nf + _GNU_SOURCE +.fi +.P +.BR mkstemps (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR mkostemps (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR mkstemp () +function generates a unique temporary filename from +.IR template , +creates and opens the file, +and returns an open file descriptor for the file. +.P +The last six characters of +.I template +must be "XXXXXX" and these are replaced with a string that makes the +filename unique. +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.P +The file is created with +permissions 0600, that is, read plus write for owner only. +The returned file descriptor provides both read and write access to the file. +The file is opened with the +.BR open (2) +.B O_EXCL +flag, guaranteeing that the caller is the process that creates the file. +.P +The +.BR mkostemp () +function is like +.BR mkstemp (), +with the difference that the following bits\[em]with the same meaning as for +.BR open (2)\[em]may +be specified in +.IR flags : +.BR O_APPEND , +.BR O_CLOEXEC , +and +.BR O_SYNC . +Note that when creating the file, +.BR mkostemp () +includes the values +.BR O_RDWR , +.BR O_CREAT , +and +.B O_EXCL +in the +.I flags +argument given to +.BR open (2); +including these values in the +.I flags +argument given to +.BR mkostemp () +is unnecessary, and produces errors on some +.\" Reportedly, FreeBSD +systems. +.P +The +.BR mkstemps () +function is like +.BR mkstemp (), +except that the string in +.I template +contains a suffix of +.I suffixlen +characters. +Thus, +.I template +is of the form +.IR "prefixXXXXXXsuffix" , +and the string XXXXXX is modified as for +.BR mkstemp (). +.P +The +.BR mkostemps () +function is to +.BR mkstemps () +as +.BR mkostemp () +is to +.BR mkstemp (). +.SH RETURN VALUE +On success, these functions return the file descriptor +of the temporary file. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EEXIST +Could not create a unique temporary filename. +Now the contents of \fItemplate\fP are undefined. +.TP +.B EINVAL +For +.BR mkstemp () +and +.BR mkostemp (): +The last six characters of \fItemplate\fP were not XXXXXX; +now \fItemplate\fP is unchanged. +.IP +For +.BR mkstemps () +and +.BR mkostemps (): +.I template +is less than +.I "(6 + suffixlen)" +characters long, or the last 6 characters before the suffix in +.I template +were not XXXXXX. +.P +These functions may also fail with any of the errors described for +.BR open (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mkstemp (), +.BR mkostemp (), +.BR mkstemps (), +.BR mkostemps () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR mkstemp () +POSIX.1-2001. +.TP +.BR mkstemps () +BSD. +.\" mkstemps() appears to be at least on the BSDs, Mac OS X, Solaris, +.\" and Tru64. +.TP +.BR mkostemp () +.TQ +.BR mkostemps () +GNU. +.SH HISTORY +.TP +.BR mkstemp () +4.3BSD, POSIX.1-2001. +.TP +.BR mkstemps () +glibc 2.11. +BSD, Mac OS X, Solaris, Tru64. +.TP +.BR mkostemp () +glibc 2.7. +.TP +.BR mkostemps () +glibc 2.11. +.P +In glibc versions 2.06 and earlier, the file is created with permissions 0666, +that is, read and write for all users. +This old behavior may be +a security risk, especially since other UNIX flavors use 0600, +and somebody might overlook this detail when porting programs. +POSIX.1-2008 adds a requirement that the file be created with mode 0600. +.P +More generally, the POSIX specification of +.BR mkstemp () +does not say anything +about file modes, so the application should make sure its +file mode creation mask (see +.BR umask (2)) +is set appropriately before calling +.BR mkstemp () +(and +.BR mkostemp ()). +.\" +.\" The prototype for +.\" .BR mkstemp () +.\" is in +.\" .I +.\" for libc4, libc5, glibc1; glibc2 follows POSIX.1 and has the prototype in +.\" .IR . +.SH SEE ALSO +.BR mkdtemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man/man3/mkstemps.3 b/man/man3/mkstemps.3 new file mode 100644 index 0000000..08cc2de --- /dev/null +++ b/man/man3/mkstemps.3 @@ -0,0 +1 @@ +.so man3/mkstemp.3 diff --git a/man/man3/mktemp.3 b/man/man3/mktemp.3 new file mode 100644 index 0000000..54e5b1f --- /dev/null +++ b/man/man3/mktemp.3 @@ -0,0 +1,118 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:48:06 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Jun 23 01:26:34 1995 by Andries Brouwer (aeb@cwi.nl) +.\" (prompted by Scott Burkett ) +.\" Modified Sun Mar 28 23:44:38 1999 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH mktemp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mktemp \- make a unique temporary filename +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *mktemp(char *" template ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mktemp (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200112L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +.IR "Never use this function" ; +see BUGS. +.P +The +.BR mktemp () +function generates a unique temporary filename +from \fItemplate\fP. +The last six characters of \fItemplate\fP must +be XXXXXX and these are replaced with a string that makes the +filename unique. +Since it will be modified, +.I template +must not be a string constant, but should be declared as a character array. +.SH RETURN VALUE +The +.BR mktemp () +function always returns \fItemplate\fP. +If a unique name was created, the last six bytes of \fItemplate\fP will +have been modified in such a way that the resulting name is unique +(i.e., does not exist already) +If a unique name could not be created, +\fItemplate\fP is made an empty string, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The last six characters of \fItemplate\fP were not XXXXXX. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mktemp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD, POSIX.1-2001. +Removed in POSIX.1-2008. +.\" .SH NOTES +.\" The prototype is in +.\" .I +.\" for libc4, libc5, glibc1; glibc2 follows the Single UNIX Specification +.\" and has the prototype in +.\" .IR . +.SH BUGS +Never use +.BR mktemp (). +Some implementations follow 4.3BSD +and replace XXXXXX by the current process ID and a single letter, +so that at most 26 different names can be returned. +Since on the one hand the names are easy to guess, and on the other +hand there is a race between testing whether the name exists and +opening the file, every use of +.BR mktemp () +is a security risk. +The race is avoided by +.BR mkstemp (3) +and +.BR mkdtemp (3). +.SH SEE ALSO +.BR mktemp (1), +.BR mkdtemp (3), +.BR mkstemp (3), +.BR tempnam (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man/man3/mktime.3 b/man/man3/mktime.3 new file mode 100644 index 0000000..84a3baa --- /dev/null +++ b/man/man3/mktime.3 @@ -0,0 +1 @@ +.so man3/ctime.3 diff --git a/man/man3/mmap64.3 b/man/man3/mmap64.3 new file mode 100644 index 0000000..8902d1b --- /dev/null +++ b/man/man3/mmap64.3 @@ -0,0 +1 @@ +.so man2/mmap.2 diff --git a/man/man3/modf.3 b/man/man3/modf.3 new file mode 100644 index 0000000..89db053 --- /dev/null +++ b/man/man3/modf.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH modf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +modf, modff, modfl \- extract signed integral and fractional values from +floating-point number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double modf(double " x ", double *" iptr ); +.BI "float modff(float " x ", float *" iptr ); +.BI "long double modfl(long double " x ", long double *" iptr ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR modff (), +.BR modfl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions break the argument +.I x +into an integral +part and a fractional part, each of which has the same sign as +.IR x . +The integral part is stored in the location pointed to by +.IR iptr . +.SH RETURN VALUE +These functions return the fractional part of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned, and +.I *iptr +is set to a NaN. +.P +If +.I x +is positive infinity (negative infinity), +0 (\-0) is returned, and +.I *iptr +is set to positive infinity (negative infinity). +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR modf (), +.BR modff (), +.BR modfl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR frexp (3), +.BR ldexp (3) diff --git a/man/man3/modff.3 b/man/man3/modff.3 new file mode 100644 index 0000000..84af2e3 --- /dev/null +++ b/man/man3/modff.3 @@ -0,0 +1 @@ +.so man3/modf.3 diff --git a/man/man3/modfl.3 b/man/man3/modfl.3 new file mode 100644 index 0000000..84af2e3 --- /dev/null +++ b/man/man3/modfl.3 @@ -0,0 +1 @@ +.so man3/modf.3 diff --git a/man/man3/mpool.3 b/man/man3/mpool.3 new file mode 100644 index 0000000..038be70 --- /dev/null +++ b/man/man3/mpool.3 @@ -0,0 +1,205 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 +.\" +.TH mpool 3 2024-05-02 "Linux man-pages (unreleased)" +.UC 7 +.SH NAME +mpool \- shared memory buffer pool +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \ +", pgno_t " maxcache ); +.P +.BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *)," +.BI " void (*" pgout ")(void *, pgno_t, void *)," +.BI " void *" pgcookie ); +.P +.BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr ); +.BI "void *mpool_get(MPOOL *" mp ", pgno_t " pgno ", unsigned int " flags ); +.BI "int mpool_put(MPOOL *" mp ", void *" pgaddr ", unsigned int " flags ); +.P +.BI "int mpool_sync(MPOOL *" mp ); +.BI "int mpool_close(MPOOL *" mp ); +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided up until glibc 2.1. +Since glibc 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.P +.I Mpool +is the library interface intended to provide page oriented buffer management +of files. +The buffers may be shared between processes. +.P +The function +.BR mpool_open () +initializes a memory pool. +The +.I key +argument is the byte string used to negotiate between multiple +processes wishing to share buffers. +If the file buffers are mapped in shared memory, all processes using +the same key will share the buffers. +If +.I key +is NULL, the buffers are mapped into private memory. +The +.I fd +argument is a file descriptor for the underlying file, which must be seekable. +If +.I key +is non-NULL and matches a file already being mapped, the +.I fd +argument is ignored. +.P +The +.I pagesize +argument is the size, in bytes, of the pages into which the file is broken up. +The +.I maxcache +argument is the maximum number of pages from the underlying file to cache +at any one time. +This value is not relative to the number of processes which share a file's +buffers, but will be the largest value specified by any of the processes +sharing the file. +.P +The +.BR mpool_filter () +function is intended to make transparent input and output processing of the +pages possible. +If the +.I pgin +function is specified, it is called each time a buffer is read into the memory +pool from the backing file. +If the +.I pgout +function is specified, it is called each time a buffer is written into the +backing file. +Both functions are called with the +.I pgcookie +pointer, the page number and a pointer to the page to being read or written. +.P +The function +.BR mpool_new () +takes an +.I MPOOL +pointer and an address as arguments. +If a new page can be allocated, a pointer to the page is returned and +the page number is stored into the +.I pgnoaddr +address. +Otherwise, NULL is returned and +.I errno +is set. +.P +The function +.BR mpool_get () +takes an +.I MPOOL +pointer and a page number as arguments. +If the page exists, a pointer to the page is returned. +Otherwise, NULL is returned and +.I errno +is set. +The +.I flags +argument is not currently used. +.P +The function +.BR mpool_put () +unpins the page referenced by +.IR pgaddr . +.I pgaddr +must be an address previously returned by +.BR mpool_get () +or +.BR mpool_new (). +The flag value is specified by ORing +any of the following values: +.TP +.B MPOOL_DIRTY +The page has been modified and needs to be written to the backing file. +.P +.BR mpool_put () +returns 0 on success and \-1 if an error occurs. +.P +The function +.BR mpool_sync () +writes all modified pages associated with the +.I MPOOL +pointer to the +backing file. +.BR mpool_sync () +returns 0 on success and \-1 if an error occurs. +.P +The +.BR mpool_close () +function free's up any allocated memory associated with the memory pool +cookie. +Modified pages are +.B not +written to the backing file. +.BR mpool_close () +returns 0 on success and \-1 if an error occurs. +.SH ERRORS +The +.BR mpool_open () +function may fail and set +.I errno +for any of the errors specified for the library routine +.BR malloc (3). +.P +The +.BR mpool_get () +function may fail and set +.I errno +for the following: +.TP 15 +.B EINVAL +The requested record doesn't exist. +.P +The +.BR mpool_new () +and +.BR mpool_get () +functions may fail and set +.I errno +for any of the errors specified for the library routines +.BR read (2), +.BR write (2), +and +.BR malloc (3). +.P +The +.BR mpool_sync () +function may fail and set +.I errno +for any of the errors specified for the library routine +.BR write (2). +.P +The +.BR mpool_close () +function may fail and set +.I errno +for any of the errors specified for the library routine +.BR free (3). +.SH STANDARDS +BSD. +.SH SEE ALSO +.BR btree (3), +.BR dbopen (3), +.BR hash (3), +.BR recno (3) diff --git a/man/man3/mprobe.3 b/man/man3/mprobe.3 new file mode 100644 index 0000000..4baeaf2 --- /dev/null +++ b/man/man3/mprobe.3 @@ -0,0 +1 @@ +.so man3/mcheck.3 diff --git a/man/man3/mq_close.3 b/man/man3/mq_close.3 new file mode 100644 index 0000000..8ec220f --- /dev/null +++ b/man/man3/mq_close.3 @@ -0,0 +1,70 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_close 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_close \- close a message queue descriptor +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mq_close(mqd_t " mqdes ); +.fi +.SH DESCRIPTION +.BR mq_close () +closes the message queue descriptor +.IR mqdes . +.P +If the calling process has attached a notification request (see +.BR mq_notify (3)) +to this message queue via +.IR mqdes , +then this request is removed, +and another process can now attach a notification request. +.SH RETURN VALUE +On success +.BR mq_close () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The message queue descriptor specified in +.I mqdes +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_close () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +All open message queues are automatically closed on process termination, +or upon +.BR execve (2). +.SH SEE ALSO +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7) diff --git a/man/man3/mq_getattr.3 b/man/man3/mq_getattr.3 new file mode 100644 index 0000000..d6d5996 --- /dev/null +++ b/man/man3/mq_getattr.3 @@ -0,0 +1,229 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_getattr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_getattr, mq_setattr \- get/set message queue attributes +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mq_getattr(mqd_t " mqdes ", struct mq_attr *" attr ); +.BI "int mq_setattr(mqd_t " mqdes ", const struct mq_attr *restrict " newattr , +.BI " struct mq_attr *restrict " oldattr ); +.fi +.SH DESCRIPTION +.BR mq_getattr () +and +.BR mq_setattr () +respectively retrieve and modify attributes of the message queue +referred to by the message queue descriptor +.IR mqdes . +.P +.BR mq_getattr () +returns an +.I mq_attr +structure in the buffer pointed by +.IR attr . +This structure is defined as: +.P +.in +4n +.EX +struct mq_attr { + long mq_flags; /* Flags: 0 or O_NONBLOCK */ + long mq_maxmsg; /* Max. # of messages on queue */ + long mq_msgsize; /* Max. message size (bytes) */ + long mq_curmsgs; /* # of messages currently in queue */ +}; +.EE +.in +.P +The +.I mq_flags +field contains flags associated with the open message queue description. +This field is initialized when the queue is created by +.BR mq_open (3). +The only flag that can appear in this field is +.BR O_NONBLOCK . +.P +The +.I mq_maxmsg +and +.I mq_msgsize +fields are set when the message queue is created by +.BR mq_open (3). +The +.I mq_maxmsg +field is an upper limit on the number of messages +that may be placed on the queue using +.BR mq_send (3). +The +.I mq_msgsize +field is an upper limit on the size of messages +that may be placed on the queue. +Both of these fields must have a value greater than zero. +Two +.I /proc +files that place ceilings on the values for these fields are described in +.BR mq_overview (7). +.P +The +.I mq_curmsgs +field returns the number of messages currently held in the queue. +.P +.BR mq_setattr () +sets message queue attributes using information supplied in the +.I mq_attr +structure pointed to by +.IR newattr . +The only attribute that can be modified is the setting of the +.B O_NONBLOCK +flag in +.IR mq_flags . +The other fields in +.I newattr +are ignored. +If the +.I oldattr +field is not NULL, +then the buffer that it points to is used to return an +.I mq_attr +structure that contains the same information that is returned by +.BR mq_getattr (). +.SH RETURN VALUE +On success +.BR mq_getattr () +and +.BR mq_setattr () +return 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The message queue descriptor specified in +.I mqdes +is invalid. +.TP +.B EINVAL +.I newattr\->mq_flags +contained set bits other than +.BR O_NONBLOCK . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_getattr (), +.BR mq_setattr () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, +.BR mq_getattr () +and +.BR mq_setattr () +are library functions layered on top of the +.BR mq_getsetattr (2) +system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The program below can be used to show the default +.I mq_maxmsg +and +.I mq_msgsize +values that are assigned to a message queue that is created with a call to +.BR mq_open (3) +in which the +.I attr +argument is NULL. +Here is an example run of the program: +.P +.in +4n +.EX +$ \fB./a.out /testq\fP +Maximum # of messages on queue: 10 +Maximum message size: 8192 +.EE +.in +.P +Since Linux 3.5, the following +.I /proc +files (described in +.BR mq_overview (7)) +can be used to control the defaults: +.P +.in +4n +.EX +$ \fBuname \-sr\fP +Linux 3.8.0 +$ \fBcat /proc/sys/fs/mqueue/msg_default\fP +10 +$ \fBcat /proc/sys/fs/mqueue/msgsize_default\fP +8192 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (mq_getattr.c) +.EX +#include +#include +#include +#include +#include +#include +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + mqd_t mqd; + struct mq_attr attr; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s mq\-name\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + mqd = mq_open(argv[1], O_CREAT | O_EXCL, 0600, NULL); + if (mqd == (mqd_t) \-1) + errExit("mq_open"); +\& + if (mq_getattr(mqd, &attr) == \-1) + errExit("mq_getattr"); +\& + printf("Maximum # of messages on queue: %ld\en", attr.mq_maxmsg); + printf("Maximum message size: %ld\en", attr.mq_msgsize); +\& + if (mq_unlink(argv[1]) == \-1) + errExit("mq_unlink"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR mq_close (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7) diff --git a/man/man3/mq_notify.3 b/man/man3/mq_notify.3 new file mode 100644 index 0000000..7c4dc50 --- /dev/null +++ b/man/man3/mq_notify.3 @@ -0,0 +1,273 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_notify 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_notify \- register for notification when a message is available +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.BR "#include " "/* Definition of SIGEV_* constants */" +.P +.BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp ); +.fi +.SH DESCRIPTION +.BR mq_notify () +allows the calling process to register or unregister for delivery of +an asynchronous notification when a new message arrives on +the empty message queue referred to by the message queue descriptor +.IR mqdes . +.P +The +.I sevp +argument is a pointer to a +.I sigevent +structure. +For the definition and general details of this structure, see +.BR sigevent (3type). +.P +If +.I sevp +is a non-null pointer, then +.BR mq_notify () +registers the calling process to receive message notification. +The +.I sigev_notify +field of the +.I sigevent +structure to which +.I sevp +points specifies how notification is to be performed. +This field has one of the following values: +.TP +.B SIGEV_NONE +A "null" notification: the calling process is registered as the target +for notification, but when a message arrives, no notification is sent. +.\" When is SIGEV_NONE useful? +.TP +.B SIGEV_SIGNAL +Notify the process by sending the signal specified in +.IR sigev_signo . +See +.BR sigevent (3type) +for general details. +The +.I si_code +field of the +.I siginfo_t +structure will be set to +.BR SI_MESGQ . +In addition, +.\" I don't know of other implementations that set +.\" si_pid and si_uid -- MTK +.I si_pid +will be set to the PID of the process that sent the message, and +.I si_uid +will be set to the real user ID of the sending process. +.TP +.B SIGEV_THREAD +Upon message delivery, invoke +.I sigev_notify_function +as if it were the start function of a new thread. +See +.BR sigevent (3type) +for details. +.P +Only one process can be registered to receive notification +from a message queue. +.P +If +.I sevp +is NULL, and the calling process is currently registered to receive +notifications for this message queue, then the registration is removed; +another process can then register to receive a message notification +for this queue. +.P +Message notification occurs only when a new message arrives and +the queue was previously empty. +If the queue was not empty at the time +.BR mq_notify () +was called, then a notification will occur only after +the queue is emptied and a new message arrives. +.P +If another process or thread is waiting to read a message +from an empty queue using +.BR mq_receive (3), +then any message notification registration is ignored: +the message is delivered to the process or thread calling +.BR mq_receive (3), +and the message notification registration remains in effect. +.P +Notification occurs once: after a notification is delivered, +the notification registration is removed, +and another process can register for message notification. +If the notified process wishes to receive the next notification, +it can use +.BR mq_notify () +to request a further notification. +This should be done before emptying all unread messages from the queue. +(Placing the queue in nonblocking mode is useful for emptying +the queue of messages without blocking once it is empty.) +.SH RETURN VALUE +On success +.BR mq_notify () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EBADF +The message queue descriptor specified in +.I mqdes +is invalid. +.TP +.B EBUSY +Another process has already registered to receive notification +for this message queue. +.TP +.B EINVAL +.I sevp\->sigev_notify +is not one of the permitted values; or +.I sevp\->sigev_notify +is +.B SIGEV_SIGNAL +and +.I sevp\->sigev_signo +is not a valid signal number. +.TP +.B ENOMEM +Insufficient memory. +.P +POSIX.1-2008 says that an implementation +.I may +generate an +.B EINVAL +.\" Linux does not do this +error if +.I sevp +is NULL, and the caller is not currently registered to receive +notifications for the queue +.IR mqdes . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_notify () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS C library/kernel differences +In the glibc implementation, the +.BR mq_notify () +library function is implemented on top of the system call of the same name. +When +.I sevp +is NULL, or specifies a notification mechanism other than +.BR SIGEV_THREAD , +the library function directly invokes the system call. +For +.BR SIGEV_THREAD , +much of the implementation resides within the library, +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.) +The implementation involves the use of a raw +.BR netlink (7) +socket and creates a new thread for each notification that is +delivered to the process. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The following program registers a notification request for the +message queue named in its command-line argument. +Notification is performed by creating a thread. +The thread executes a function which reads one message from the +queue and then terminates the process. +.SS Program source +.\" SRC BEGIN (mq_notify.c) +.EX +#include +#include +#include +#include +#include +#include +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void /* Thread start function */ +tfunc(union sigval sv) +{ + struct mq_attr attr; + ssize_t nr; + void *buf; + mqd_t mqdes = *((mqd_t *) sv.sival_ptr); +\& + /* Determine max. msg size; allocate buffer to receive msg */ +\& + if (mq_getattr(mqdes, &attr) == \-1) + handle_error("mq_getattr"); + buf = malloc(attr.mq_msgsize); + if (buf == NULL) + handle_error("malloc"); +\& + nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL); + if (nr == \-1) + handle_error("mq_receive"); +\& + printf("Read %zd bytes from MQ\en", nr); + free(buf); + exit(EXIT_SUCCESS); /* Terminate the process */ +} +\& +int +main(int argc, char *argv[]) +{ + mqd_t mqdes; + struct sigevent sev; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + mqdes = mq_open(argv[1], O_RDONLY); + if (mqdes == (mqd_t) \-1) + handle_error("mq_open"); +\& + sev.sigev_notify = SIGEV_THREAD; + sev.sigev_notify_function = tfunc; + sev.sigev_notify_attributes = NULL; + sev.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */ + if (mq_notify(mqdes, &sev) == \-1) + handle_error("mq_notify"); +\& + pause(); /* Process will be terminated by thread function */ +} +.EE +.\" SRC END +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7), +.BR sigevent (3type) diff --git a/man/man3/mq_open.3 b/man/man3/mq_open.3 new file mode 100644 index 0000000..8dde565 --- /dev/null +++ b/man/man3/mq_open.3 @@ -0,0 +1,298 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_open 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_open \- open a message queue +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.BR "#include " " /* For O_* constants */" +.BR "#include " " /* For mode constants */" +.B #include +.P +.BI "mqd_t mq_open(const char *" name ", int " oflag ); +.BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode , +.BI " struct mq_attr *" attr ); +.fi +.SH DESCRIPTION +.BR mq_open () +creates a new POSIX message queue or opens an existing queue. +The queue is identified by +.IR name . +For details of the construction of +.IR name , +see +.BR mq_overview (7). +.P +The +.I oflag +argument specifies flags that control the operation of the call. +(Definitions of the flags values can be obtained by including +.IR .) +Exactly one of the following must be specified in +.IR oflag : +.TP +.B O_RDONLY +Open the queue to receive messages only. +.TP +.B O_WRONLY +Open the queue to send messages only. +.TP +.B O_RDWR +Open the queue to both send and receive messages. +.P +Zero or more of the following flags can additionally be +.IR OR ed +in +.IR oflag : +.TP +.BR O_CLOEXEC " (since Linux 2.6.26)" +.\" commit 269f21344b23e552c21c9e2d7ca258479dcd7a0a +Set the close-on-exec flag for the message queue descriptor. +See +.BR open (2) +for a discussion of why this flag is useful. +.TP +.B O_CREAT +Create the message queue if it does not exist. +The owner (user ID) of the message queue is set to the effective +user ID of the calling process. +The group ownership (group ID) is set to the effective group ID +of the calling process. +.\" In reality the filesystem IDs are used on Linux. +.TP +.B O_EXCL +If +.B O_CREAT +was specified in +.IR oflag , +and a queue with the given +.I name +already exists, then fail with the error +.BR EEXIST . +.TP +.B O_NONBLOCK +Open the queue in nonblocking mode. +In circumstances where +.BR mq_receive (3) +and +.BR mq_send (3) +would normally block, these functions instead fail with the error +.BR EAGAIN . +.P +If +.B O_CREAT +is specified in +.IR oflag , +then two additional arguments must be supplied. +The +.I mode +argument specifies the permissions to be placed on the new queue, +as for +.BR open (2). +(Symbolic definitions for the permissions bits can be obtained by including +.IR .) +The permissions settings are masked against the process umask. +.P +The fields of the +.I struct mq_attr +pointed to +.I attr +specify the maximum number of messages and +the maximum size of messages that the queue will allow. +This structure is defined as follows: +.P +.in +4n +.EX +struct mq_attr { + long mq_flags; /* Flags (ignored for mq_open()) */ + long mq_maxmsg; /* Max. # of messages on queue */ + long mq_msgsize; /* Max. message size (bytes) */ + long mq_curmsgs; /* # of messages currently in queue + (ignored for mq_open()) */ +}; +.EE +.in +.P +Only the +.I mq_maxmsg +and +.I mq_msgsize +fields are employed when calling +.BR mq_open (); +the values in the remaining fields are ignored. +.P +If +.I attr +is NULL, then the queue is created with implementation-defined +default attributes. +Since Linux 3.5, two +.I /proc +files can be used to control these defaults; see +.BR mq_overview (7) +for details. +.SH RETURN VALUE +On success, +.BR mq_open () +returns a message queue descriptor for use by other +message queue functions. +On error, +.BR mq_open () +returns +.IR "(mqd_t)\ \-1", +with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The queue exists, but the caller does not have permission to +open it in the specified mode. +.TP +.B EACCES +.I name +contained more than one slash. +.\" Note that this isn't consistent with the same case for sem_open() +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified in +.IR oflag , +but a queue with this +.I name +already exists. +.TP +.B EINVAL +.\" glibc checks whether the name starts with a "/" and if not, +.\" gives this error +.I name +doesn't follow the format in +.BR mq_overview (7). +.TP +.B EINVAL +.B O_CREAT +was specified in +.IR oflag , +and +.I attr +was not NULL, but +.I attr\->mq_maxmsg +or +.I attr\->mq_msqsize +was invalid. +Both of these fields must be greater than zero. +In a process that is unprivileged (does not have the +.B CAP_SYS_RESOURCE +capability), +.I attr\->mq_maxmsg +must be less than or equal to the +.I msg_max +limit, and +.I attr\->mq_msgsize +must be less than or equal to the +.I msgsize_max +limit. +In addition, even in a privileged process, +.I attr\->mq_maxmsg +cannot exceed the +.B HARD_MAX +limit. +(See +.BR mq_overview (7) +for details of these limits.) +.TP +.B EMFILE +The per-process limit on the number of open file +and message queue descriptors has been reached +(see the description of +.B RLIMIT_NOFILE +in +.BR getrlimit (2)). +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files +and message queues has been reached. +.TP +.B ENOENT +The +.B O_CREAT +flag was not specified in +.IR oflag , +and no queue with this +.I name +exists. +.TP +.B ENOENT +.I name +was just "/" followed by no other characters. +.\" Note that this isn't consistent with the same case for sem_open() +.TP +.B ENOMEM +Insufficient memory. +.TP +.B ENOSPC +Insufficient space for the creation of a new message queue. +This probably occurred because the +.I queues_max +limit was encountered; see +.BR mq_overview (7). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_open () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS C library/kernel differences +The +.BR mq_open () +library function is implemented on top of a system call of the same name. +The library function performs the check that the +.I name +starts with a slash (/), giving the +.B EINVAL +error if it does not. +The kernel system call expects +.I name +to contain no preceding slash, +so the C library function passes +.I name +without the preceding slash (i.e., +.IR name+1 ) +to the system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +Before Linux 2.6.14, +the process umask was not applied to the permissions specified in +.IR mode . +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR mq_overview (7) diff --git a/man/man3/mq_receive.3 b/man/man3/mq_receive.3 new file mode 100644 index 0000000..368177f --- /dev/null +++ b/man/man3/mq_receive.3 @@ -0,0 +1,163 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_receive 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_receive, mq_timedreceive \- receive a message from a message queue +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t mq_receive(mqd_t " mqdes ", char " msg_ptr [. msg_len ], +.BI " size_t " msg_len ", unsigned int *" msg_prio ); +.P +.B #include +.B #include +.P +.BI "ssize_t mq_timedreceive(mqd_t " mqdes ", \ +char *restrict " msg_ptr [. msg_len ], +.BI " size_t " msg_len ", unsigned int *restrict " msg_prio , +.BI " const struct timespec *restrict " abs_timeout ); +.fi +.P +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mq_timedreceive (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR mq_receive () +removes the oldest message with the highest priority from +the message queue referred to by the message queue descriptor +.IR mqdes , +and places it in the buffer pointed to by +.IR msg_ptr . +The +.I msg_len +argument specifies the size of the buffer pointed to by +.IR msg_ptr ; +this must be greater than or equal to the +.I mq_msgsize +attribute of the queue (see +.BR mq_getattr (3)). +If +.I msg_prio +is not NULL, then the buffer to which it points is used +to return the priority associated with the received message. +.P +If the queue is empty, then, by default, +.BR mq_receive () +blocks until a message becomes available, +or the call is interrupted by a signal handler. +If the +.B O_NONBLOCK +flag is enabled for the message queue description, +then the call instead fails immediately with the error +.BR EAGAIN . +.P +.BR mq_timedreceive () +behaves just like +.BR mq_receive (), +except that if the queue is empty and the +.B O_NONBLOCK +flag is not enabled for the message queue description, then +.I abs_timeout +points to a structure which specifies how long the call will block. +This value is an absolute timeout in seconds and nanoseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), +specified in a +.BR timespec (3) +structure. +.P +If no message is available, +and the timeout has already expired by the time of the call, +.BR mq_timedreceive () +returns immediately. +.SH RETURN VALUE +On success, +.BR mq_receive () +and +.BR mq_timedreceive () +return the number of bytes in the received message; +on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The queue was empty, and the +.B O_NONBLOCK +flag was set for the message queue description referred to by +.IR mqdes . +.TP +.B EBADF +The descriptor specified in +.I mqdes +was invalid or not opened for reading. +.TP +.B EINTR +The call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The call would have blocked, and +.I abs_timeout +was invalid, either because +.I tv_sec +was less than zero, or because +.I tv_nsec +was less than zero or greater than 1000 million. +.TP +.B EMSGSIZE +.I msg_len +was less than the +.I mq_msgsize +attribute of the message queue. +.TP +.B ETIMEDOUT +The call timed out before a message could be transferred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_receive (), +.BR mq_timedreceive () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, +.BR mq_timedreceive () +is a system call, and +.BR mq_receive () +is a library function layered on top of that system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR timespec (3), +.BR mq_overview (7), +.BR time (7) diff --git a/man/man3/mq_send.3 b/man/man3/mq_send.3 new file mode 100644 index 0000000..de182b9 --- /dev/null +++ b/man/man3/mq_send.3 @@ -0,0 +1,170 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_send 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_send, mq_timedsend \- send a message to a message queue +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mq_send(mqd_t " mqdes ", const char " msg_ptr [. msg_len ], +.BI " size_t " msg_len ", unsigned int " msg_prio ); +.P +.B #include +.B #include +.P +.BI "int mq_timedsend(mqd_t " mqdes ", const char " msg_ptr [. msg_len ], +.BI " size_t " msg_len ", unsigned int " msg_prio , +.BI " const struct timespec *" abs_timeout ); +.fi +.P +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR mq_timedsend (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR mq_send () +adds the message pointed to by +.I msg_ptr +to the message queue referred to by the message queue descriptor +.IR mqdes . +The +.I msg_len +argument specifies the length of the message pointed to by +.IR msg_ptr ; +this length must be less than or equal to the queue's +.I mq_msgsize +attribute. +Zero-length messages are allowed. +.P +The +.I msg_prio +argument is a nonnegative integer that specifies the priority +of this message. +Messages are placed on the queue in decreasing order of priority, +with newer messages of the same priority being placed after +older messages with the same priority. +See +.BR mq_overview (7) +for details on the range for the message priority. +.P +If the message queue is already full +(i.e., the number of messages on the queue equals the queue's +.I mq_maxmsg +attribute), then, by default, +.BR mq_send () +blocks until sufficient space becomes available to allow the message +to be queued, or until the call is interrupted by a signal handler. +If the +.B O_NONBLOCK +flag is enabled for the message queue description, +then the call instead fails immediately with the error +.BR EAGAIN . +.P +.BR mq_timedsend () +behaves just like +.BR mq_send (), +except that if the queue is full and the +.B O_NONBLOCK +flag is not enabled for the message queue description, then +.I abs_timeout +points to a structure which specifies how long the call will block. +This value is an absolute timeout in seconds and nanoseconds +since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), +specified in a +.BR timespec (3) +structure. +.P +If the message queue is full, +and the timeout has already expired by the time of the call, +.BR mq_timedsend () +returns immediately. +.SH RETURN VALUE +On success, +.BR mq_send () +and +.BR mq_timedsend () +return zero; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The queue was full, and the +.B O_NONBLOCK +flag was set for the message queue description referred to by +.IR mqdes . +.TP +.B EBADF +The descriptor specified in +.I mqdes +was invalid or not opened for writing. +.TP +.B EINTR +The call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +The call would have blocked, and +.I abs_timeout +was invalid, either because +.I tv_sec +was less than zero, or because +.I tv_nsec +was less than zero or greater than 1000 million. +.TP +.B EMSGSIZE +.I msg_len +was greater than the +.I mq_msgsize +attribute of the message queue. +.TP +.B ETIMEDOUT +The call timed out before a message could be transferred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_send (), +.BR mq_timedsend () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, +.BR mq_timedsend () +is a system call, and +.BR mq_send () +is a library function layered on top of that system call. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_unlink (3), +.BR timespec (3), +.BR mq_overview (7), +.BR time (7) diff --git a/man/man3/mq_setattr.3 b/man/man3/mq_setattr.3 new file mode 100644 index 0000000..a3818a2 --- /dev/null +++ b/man/man3/mq_setattr.3 @@ -0,0 +1 @@ +.so man3/mq_getattr.3 diff --git a/man/man3/mq_timedreceive.3 b/man/man3/mq_timedreceive.3 new file mode 100644 index 0000000..9fed5f2 --- /dev/null +++ b/man/man3/mq_timedreceive.3 @@ -0,0 +1 @@ +.so man3/mq_receive.3 diff --git a/man/man3/mq_timedsend.3 b/man/man3/mq_timedsend.3 new file mode 100644 index 0000000..28b1eff --- /dev/null +++ b/man/man3/mq_timedsend.3 @@ -0,0 +1 @@ +.so man3/mq_send.3 diff --git a/man/man3/mq_unlink.3 b/man/man3/mq_unlink.3 new file mode 100644 index 0000000..4cdb604 --- /dev/null +++ b/man/man3/mq_unlink.3 @@ -0,0 +1,68 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_unlink 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_unlink \- remove a message queue +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int mq_unlink(const char *" name ); +.fi +.SH DESCRIPTION +.BR mq_unlink () +removes the specified message queue +.IR name . +The message queue name is removed immediately. +The queue itself is destroyed once any other processes that have +the queue open close their descriptors referring to the queue. +.SH RETURN VALUE +On success +.BR mq_unlink () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The caller does not have permission to unlink this message queue. +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENOENT +There is no message queue with the given +.IR name . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mq_unlink () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_overview (7) diff --git a/man/man3/mrand48.3 b/man/man3/mrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/mrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/mrand48_r.3 b/man/man3/mrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/mrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/mtrace.3 b/man/man3/mtrace.3 new file mode 100644 index 0000000..d332cc1 --- /dev/null +++ b/man/man3/mtrace.3 @@ -0,0 +1,180 @@ +'\" t +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mtrace 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mtrace, muntrace \- malloc tracing +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.B "void mtrace(void);" +.B "void muntrace(void);" +.fi +.SH DESCRIPTION +The +.BR mtrace () +function installs hook functions for the memory-allocation functions +.RB ( malloc (3), +.BR realloc (3) +.BR memalign (3), +.BR free (3)). +These hook functions record tracing information about memory allocation +and deallocation. +The tracing information can be used to discover memory leaks and +attempts to free nonallocated memory in a program. +.P +The +.BR muntrace () +function disables the hook functions installed by +.BR mtrace (), +so that tracing information is no longer recorded +for the memory-allocation functions. +If no hook functions were successfully installed by +.BR mtrace (), +.BR muntrace () +does nothing. +.P +When +.BR mtrace () +is called, it checks the value of the environment variable +.BR MALLOC_TRACE , +which should contain the pathname of a file in which +the tracing information is to be recorded. +If the pathname is successfully opened, it is truncated to zero length. +.P +If +.B MALLOC_TRACE +is not set, +or the pathname it specifies is invalid or not writable, +then no hook functions are installed, and +.BR mtrace () +has no effect. +In set-user-ID and set-group-ID programs, +.B MALLOC_TRACE +is ignored, and +.BR mtrace () +has no effect. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR mtrace (), +.BR muntrace () +T} Thread safety MT-Unsafe +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" markings in glibc manual are more detailed: +.\" +.\" mtrace: MT-Unsafe env race:mtrace const:malloc_hooks init +.\" muntrace: MT-Unsafe race:mtrace const:malloc_hooks locale +.\" +.\" But there is something wrong in glibc manual, for example: +.\" glibc manual says muntrace should have marking locale because it calls +.\" fprintf(), but muntrace does not execute area which cause locale problem. +.SH STANDARDS +GNU. +.SH NOTES +In normal usage, +.BR mtrace () +is called once at the start of execution of a program, and +.BR muntrace () +is never called. +.P +The tracing output produced after a call to +.BR mtrace () +is textual, but not designed to be human readable. +The GNU C library provides a Perl script, +.BR mtrace (1), +that interprets the trace log and produces human-readable output. +For best results, +the traced program should be compiled with debugging enabled, +so that line-number information is recorded in the executable. +.P +The tracing performed by +.BR mtrace () +incurs a performance penalty (if +.B MALLOC_TRACE +points to a valid, writable pathname). +.SH BUGS +The line-number information produced by +.BR mtrace (1) +is not always precise: +the line number references may refer to the previous or following (nonblank) +line of the source code. +.SH EXAMPLES +The shell session below demonstrates the use of the +.BR mtrace () +function and the +.BR mtrace (1) +command in a program that has memory leaks at two different locations. +The demonstration uses the following program: +.P +.in +4n +.RB "$ " "cat t_mtrace.c" +.\" SRC BEGIN (t_mtrace.c) +.EX +#include +#include +#include +\& +int +main(void) +{ + mtrace(); +\& + for (unsigned int j = 0; j < 2; j++) + malloc(100); /* Never freed\-\-a memory leak */ +\& + calloc(16, 16); /* Never freed\-\-a memory leak */ + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.P +When we run the program as follows, we see that +.BR mtrace () +diagnosed memory leaks at two different locations in the program: +.P +.in +4n +.EX +.RB "$ " "cc \-g t_mtrace.c \-o t_mtrace" +.RB "$ " "export MALLOC_TRACE=/tmp/t" +.RB "$ " "./t_mtrace" +.RB "$ " "mtrace ./t_mtrace $MALLOC_TRACE" +Memory not freed: +-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + Address Size Caller +0x084c9378 0x64 at /home/cecilia/t_mtrace.c:12 +0x084c93e0 0x64 at /home/cecilia/t_mtrace.c:12 +0x084c9448 0x100 at /home/cecilia/t_mtrace.c:16 +.EE +.in +.P +The first two messages about unfreed memory correspond to the two +.BR malloc (3) +calls inside the +.I for +loop. +The final message corresponds to the call to +.BR calloc (3) +(which in turn calls +.BR malloc (3)). +.SH SEE ALSO +.BR mtrace (1), +.BR malloc (3), +.BR malloc_hook (3), +.BR mcheck (3) diff --git a/man/man3/muntrace.3 b/man/man3/muntrace.3 new file mode 100644 index 0000000..2b03d10 --- /dev/null +++ b/man/man3/muntrace.3 @@ -0,0 +1 @@ +.so man3/mtrace.3 diff --git a/man/man3/nan.3 b/man/man3/nan.3 new file mode 100644 index 0000000..2fb8bc5 --- /dev/null +++ b/man/man3/nan.3 @@ -0,0 +1,96 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on glibc infopages +.\" +.\" Corrections by aeb +.\" +.TH nan 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nan, nanf, nanl \- return 'Not a Number' +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double nan(const char *" tagp ); +.BI "float nanf(const char *" tagp ); +.BI "long double nanl(const char *" tagp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nan (), +.BR nanf (), +.BR nanl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions return a representation (determined by +.IR tagp ) +of a quiet NaN. +If the implementation does not support +quiet NaNs, these functions return zero. +.P +The call +.I nan("char\-sequence") +is equivalent to: +.P +.in +4n +.EX +strtod("NAN(char\-sequence)", NULL); +.EE +.in +.P +Similarly, calls to +.BR nanf () +and +.BR nanl () +are equivalent to analogous calls to +.BR strtof (3) +and +.BR strtold (3). +.P +The argument +.I tagp +is used in an unspecified manner. +On IEEE 754 systems, there are many representations of NaN, and +.I tagp +selects one. +On other systems it may do nothing. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nan (), +.BR nanf (), +.BR nanl () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.P +See also IEC 559 and the appendix with +recommended functions in IEEE 754/IEEE 854. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR isnan (3), +.BR strtod (3), +.BR math_error (7) diff --git a/man/man3/nanf.3 b/man/man3/nanf.3 new file mode 100644 index 0000000..08e9aa7 --- /dev/null +++ b/man/man3/nanf.3 @@ -0,0 +1 @@ +.so man3/nan.3 diff --git a/man/man3/nanl.3 b/man/man3/nanl.3 new file mode 100644 index 0000000..08e9aa7 --- /dev/null +++ b/man/man3/nanl.3 @@ -0,0 +1 @@ +.so man3/nan.3 diff --git a/man/man3/nearbyint.3 b/man/man3/nearbyint.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man/man3/nearbyint.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man/man3/nearbyintf.3 b/man/man3/nearbyintf.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man/man3/nearbyintf.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man/man3/nearbyintl.3 b/man/man3/nearbyintl.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man/man3/nearbyintl.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man/man3/netlink.3 b/man/man3/netlink.3 new file mode 100644 index 0000000..0722568 --- /dev/null +++ b/man/man3/netlink.3 @@ -0,0 +1,87 @@ +.\" This manpage copyright 1998 by Andi Kleen. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on the original comments from Alexey Kuznetsov +.\" $Id: netlink.3,v 1.1 1999/05/14 17:17:24 freitag Exp $ +.\" +.TH netlink 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +netlink \- Netlink macros +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int NLMSG_ALIGN(size_t " len ); +.BI "int NLMSG_LENGTH(size_t " len ); +.BI "int NLMSG_SPACE(size_t " len ); +.BI "void *NLMSG_DATA(struct nlmsghdr *" nlh ); +.BI "struct nlmsghdr *NLMSG_NEXT(struct nlmsghdr *" nlh ", int " len ); +.BI "int NLMSG_OK(struct nlmsghdr *" nlh ", int " len ); +.BI "int NLMSG_PAYLOAD(struct nlmsghdr *" nlh ", int " len ); +.fi +.SH DESCRIPTION +.I +defines several standard macros to access or create a netlink datagram. +They are similar in spirit to the macros defined in +.BR cmsg (3) +for auxiliary data. +The buffer passed to and from a netlink socket should +be accessed using only these macros. +.TP +.BR NLMSG_ALIGN () +Round the length of a netlink message up to align it properly. +.TP +.BR NLMSG_LENGTH () +Given the payload length, +.IR len , +this macro returns the aligned length to store in the +.I nlmsg_len +field of the +.IR nlmsghdr . +.TP +.BR NLMSG_SPACE () +Return the number of bytes that a netlink message with payload of +.I len +would occupy. +.TP +.BR NLMSG_DATA () +Return a pointer to the payload associated with the passed +.IR nlmsghdr . +.TP +.\" this is bizarre, maybe the interface should be fixed. +.BR NLMSG_NEXT () +Get the next +.I nlmsghdr +in a multipart message. +The caller must check if the current +.I nlmsghdr +didn't have the +.B NLMSG_DONE +set\[em]this function doesn't return NULL on end. +The +.I len +argument is an lvalue containing the remaining length +of the message buffer. +This macro decrements it by the length of the message header. +.TP +.BR NLMSG_OK () +Return true if the netlink message is not truncated and +is in a form suitable for parsing. +.TP +.BR NLMSG_PAYLOAD () +Return the length of the payload associated with the +.IR nlmsghdr . +.SH VERSIONS +It is often better to use netlink via +.I libnetlink +than via the low-level kernel interface. +.SH STANDARDS +Linux. +.SH SEE ALSO +.BR libnetlink (3), +.BR netlink (7) diff --git a/man/man3/newlocale.3 b/man/man3/newlocale.3 new file mode 100644 index 0000000..198120f --- /dev/null +++ b/man/man3/newlocale.3 @@ -0,0 +1,356 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH newlocale 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +newlocale, freelocale \- create, modify, and free a locale object +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "locale_t newlocale(int " category_mask ", const char *" locale , +.BI " locale_t " base ); +.BI "void freelocale(locale_t " locobj ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR newlocale (), +.BR freelocale (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR newlocale () +function creates a new locale object, or modifies an existing object, +returning a reference to the new or modified object as the function result. +Whether the call creates a new object or modifies an existing object +is determined by the value of +.IR base : +.IP \[bu] 3 +If +.I base +is +.IR "(locale_t)\ 0" , +a new object is created. +.IP \[bu] +If +.I base +refers to valid existing locale object +(i.e., an object returned by a previous call to +.BR newlocale () +or +.BR duplocale (3)), +then that object is modified by the call. +If the call is successful, the contents of +.I base +are unspecified (in particular, the object referred to by +.I base +may be freed, and a new object created). +Therefore, the caller should ensure that it stops using +.I base +before the call to +.BR newlocale (), +and should subsequently refer to the modified object via the +reference returned as the function result. +If the call fails, the contents of +.I base +remain valid and unchanged. +.P +If +.I base +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)), +or is not +.I (locale_t)\ 0 +and is not a valid locale object handle, +the behavior is undefined. +.P +The +.I category_mask +argument is a bit mask that specifies the locale categories +that are to be set in a newly created locale object +or modified in an existing object. +The mask is constructed by a bitwise OR of the constants +.BR LC_ADDRESS_MASK , +.BR LC_CTYPE_MASK , +.BR LC_COLLATE_MASK , +.BR LC_IDENTIFICATION_MASK , +.BR LC_MEASUREMENT_MASK , +.BR LC_MESSAGES_MASK , +.BR LC_MONETARY_MASK , +.BR LC_NUMERIC_MASK , +.BR LC_NAME_MASK , +.BR LC_PAPER_MASK , +.BR LC_TELEPHONE_MASK , +and +.BR LC_TIME_MASK . +Alternatively, the mask can be specified as +.BR LC_ALL_MASK , +which is equivalent to ORing all of the preceding constants. +.P +For each category specified in +.IR category_mask , +the locale data from +.I locale +will be used in the object returned by +.BR newlocale (). +If a new locale object is being created, +data for all categories not specified in +.I category_mask +is taken from the default ("POSIX") locale. +.P +The following preset values of +.I locale +are defined for all categories that can be specified in +.IR category_mask : +.TP +"POSIX" +A minimal locale environment for C language programs. +.TP +"C" +Equivalent to "POSIX". +.TP +"" +An implementation-defined native environment +corresponding to the values of the +.B LC_* +and +.B LANG +environment variables (see +.BR locale (7)). +.SS freelocale() +The +.BR freelocale () +function deallocates the resources associated with +.IR locobj , +a locale object previously returned by a call to +.BR newlocale () +or +.BR duplocale (3). +If +.I locobj +is +.B LC_GLOBAL_LOCALE +or is not valid locale object handle, the results are undefined. +.P +Once a locale object has been freed, +the program should make no further use of it. +.SH RETURN VALUE +On success, +.BR newlocale () +returns a handle that can be used in calls to +.BR duplocale (3), +.BR freelocale (), +and other functions that take a +.I locale_t +argument. +On error, +.BR newlocale () +returns +.IR "(locale_t)\ 0", +and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EINVAL +One or more bits in +.I category_mask +do not correspond to a valid locale category. +.TP +.B EINVAL +.I locale +is NULL. +.TP +.B ENOENT +.I locale +is not a string pointer referring to a valid locale. +.TP +.B ENOMEM +Insufficient memory to create a locale object. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3. +.SH NOTES +Each locale object created by +.BR newlocale () +should be deallocated using +.BR freelocale (). +.SH EXAMPLES +The program below takes up to two command-line arguments, +which each identify locales. +The first argument is required, and is used to set the +.B LC_NUMERIC +category in a locale object created using +.BR newlocale (). +The second command-line argument is optional; +if it is present, it is used to set the +.B LC_TIME +category of the locale object. +.P +Having created and initialized the locale object, +the program then applies it using +.BR uselocale (3), +and then tests the effect of the locale changes by: +.IP (1) 5 +Displaying a floating-point number with a fractional part. +This output will be affected by the +.B LC_NUMERIC +setting. +In many European-language locales, +the fractional part of the number is separated from the integer part +using a comma, rather than a period. +.IP (2) +Displaying the date. +The format and language of the output will be affected by the +.B LC_TIME +setting. +.P +The following shell sessions show some example runs of this program. +.P +Set the +.B LC_NUMERIC +category to +.I fr_FR +(French): +.P +.in +4n +.EX +$ \fB./a.out fr_FR\fP +123456,789 +Fri Mar 7 00:25:08 2014 +.EE +.in +.P +Set the +.B LC_NUMERIC +category to +.I fr_FR +(French), +and the +.B LC_TIME +category to +.I it_IT +(Italian): +.P +.in +4n +.EX +$ \fB./a.out fr_FR it_IT\fP +123456,789 +ven 07 mar 2014 00:26:01 CET +.EE +.in +.P +Specify the +.B LC_TIME +setting as an empty string, +which causes the value to be taken from environment variable settings +(which, here, specify +.IR mi_NZ , +New Zealand Māori): +.P +.in +4n +.EX +$ LC_ALL=mi_NZ ./a.out fr_FR "" +123456,789 +Te Paraire, te 07 o Poutū\-te\-rangi, 2014 00:38:44 CET +.EE +.in +.SS Program source +.\" SRC BEGIN (newlocale.c) +.EX +#define _XOPEN_SOURCE 700 +#include +#include +#include +#include +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + char buf[100]; + time_t t; + size_t s; + struct tm *tm; + locale_t loc, nloc; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s locale1 [locale2]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* Create a new locale object, taking the LC_NUMERIC settings + from the locale specified in argv[1]. */ +\& + loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0); + if (loc == (locale_t) 0) + errExit("newlocale"); +\& + /* If a second command\-line argument was specified, modify the + locale object to take the LC_TIME settings from the locale + specified in argv[2]. We assign the result of this newlocale() + call to \[aq]nloc\[aq] rather than \[aq]loc\[aq], since in some cases, we might + want to preserve \[aq]loc\[aq] if this call fails. */ +\& + if (argc > 2) { + nloc = newlocale(LC_TIME_MASK, argv[2], loc); + if (nloc == (locale_t) 0) + errExit("newlocale"); + loc = nloc; + } +\& + /* Apply the newly created locale to this thread. */ +\& + uselocale(loc); +\& + /* Test effect of LC_NUMERIC. */ +\& + printf("%8.3f\en", 123456.789); +\& + /* Test effect of LC_TIME. */ +\& + t = time(NULL); + tm = localtime(&t); + if (tm == NULL) + errExit("time"); +\& + s = strftime(buf, sizeof(buf), "%c", tm); + if (s == 0) + errExit("strftime"); +\& + printf("%s\en", buf); +\& + /* Free the locale object. */ +\& + uselocale(LC_GLOBAL_LOCALE); /* So \[aq]loc\[aq] is no longer in use */ + freelocale(loc); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR locale (1), +.BR duplocale (3), +.BR setlocale (3), +.BR uselocale (3), +.BR locale (5), +.BR locale (7) diff --git a/man/man3/nextafter.3 b/man/man3/nextafter.3 new file mode 100644 index 0000000..a48fa43 --- /dev/null +++ b/man/man3/nextafter.3 @@ -0,0 +1,200 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on glibc infopages +.\" +.TH nextafter 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl \- +floating-point number manipulation +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double nextafter(double " x ", double " y ); +.BI "float nextafterf(float " x ", float " y ); +.BI "long double nextafterl(long double " x ", long double " y ); +.P +.BI "double nexttoward(double " x ", long double " y ); +.BI "float nexttowardf(float " x ", long double " y ); +.BI "long double nexttowardl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nextafter (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR nextafterf (), +.BR nextafterl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR nexttoward (), +.BR nexttowardf (), +.BR nexttowardl (): +.nf + _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE + || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR nextafter (), +.BR nextafterf (), +and +.BR nextafterl () +functions return the next representable floating-point value following +.I x +in the direction of +.IR y . +If +.I y +is less than +.IR x , +these functions will return the largest representable number less than +.IR x . +.P +If +.I x +equals +.IR y , +the functions return +.IR y . +.P +The +.BR nexttoward (), +.BR nexttowardf (), +and +.BR nexttowardl () +functions do the same as the corresponding +.BR nextafter () +functions, except that they have a +.I "long double" +second argument. +.SH RETURN VALUE +On success, +these functions return the next representable floating-point value after +.I x +in the direction of +.IR y . +.P +If +.I x +equals +.IR y , +then +.I y +(cast to the same type as +.IR x ) +is returned. +.P +If +.I x +or +.I y +is a NaN, +a NaN is returned. +.P +If +.I x +is finite, +.\" e.g., DBL_MAX +and the result would overflow, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the correct mathematical sign. +.P +If +.I x +is not equal to +.IR y , +and the correct function result would be subnormal, zero, or underflow, +a range error occurs, +and either the correct value (if it can be represented), +or 0.0, is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result overflow +.\" e.g., nextafter(DBL_MAX, HUGE_VAL); +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: result is subnormal or underflows +.\" e.g., nextafter(DBL_MIN, 0.0); +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nextafter (), +.BR nextafterf (), +.BR nextafterl (), +.BR nexttoward (), +.BR nexttowardf (), +.BR nexttowardl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.P +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH HISTORY +C99, POSIX.1-2001. +.SH BUGS +In glibc 2.5 and earlier, these functions do not raise an underflow +floating-point +.RB ( FE_UNDERFLOW ) +exception when an underflow occurs. +.P +Before glibc 2.23 +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6799 +these functions did not set +.IR errno . +.SH SEE ALSO +.BR nearbyint (3) diff --git a/man/man3/nextafterf.3 b/man/man3/nextafterf.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man/man3/nextafterf.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man/man3/nextafterl.3 b/man/man3/nextafterl.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man/man3/nextafterl.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man/man3/nextdown.3 b/man/man3/nextdown.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man/man3/nextdown.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man/man3/nextdownf.3 b/man/man3/nextdownf.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man/man3/nextdownf.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man/man3/nextdownl.3 b/man/man3/nextdownl.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man/man3/nextdownl.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man/man3/nexttoward.3 b/man/man3/nexttoward.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man/man3/nexttoward.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man/man3/nexttowardf.3 b/man/man3/nexttowardf.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man/man3/nexttowardf.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man/man3/nexttowardl.3 b/man/man3/nexttowardl.3 new file mode 100644 index 0000000..531e48f --- /dev/null +++ b/man/man3/nexttowardl.3 @@ -0,0 +1 @@ +.so man3/nextafter.3 diff --git a/man/man3/nextup.3 b/man/man3/nextup.3 new file mode 100644 index 0000000..6c74a36 --- /dev/null +++ b/man/man3/nextup.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright (C) 2016, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH nextup 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nextup, nextupf, nextupl, nextdown, nextdownf, nextdownl \- +return next floating-point number toward positive/negative infinity +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "double nextup(double " x ); +.BI "float nextupf(float " x ); +.BI "long double nextupl(long double " x ); +.P +.BI "double nextdown(double " x ); +.BI "float nextdownf(float " x ); +.BI "long double nextdownl(long double " x ); +.fi +.SH DESCRIPTION +The +.BR nextup (), +.BR nextupf (), +and +.BR nextupl () +functions return the next representable floating-point number greater than +.IR x . +.P +If +.I x +is the smallest representable negative number in the corresponding type, +these functions return \-0. +If +.I x +is 0, the returned value is the smallest representable positive number +of the corresponding type. +.P +If +.I x +is positive infinity, the returned value is positive infinity. +If +.I x +is negative infinity, +the returned value is the largest representable finite negative number +of the corresponding type. +.P +If +.I x +is Nan, +the returned value is NaN. +.P +The value returned by +.I nextdown(x) +is +.IR \-nextup(\-x) , +and similarly for the other types. +.SH RETURN VALUE +See DESCRIPTION. +.\" .SH ERRORS +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nextup (), +.BR nextupf (), +.BR nextupl (), +.BR nextdown (), +.BR nextdownf (), +.BR nextdownl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +These functions are described in +.I IEEE Std 754-2008 - Standard for Floating-Point Arithmetic +and +.IR "ISO/IEC TS 18661". +.SH HISTORY +glibc 2.24. +.SH SEE ALSO +.BR nearbyint (3), +.BR nextafter (3) diff --git a/man/man3/nextupf.3 b/man/man3/nextupf.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man/man3/nextupf.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man/man3/nextupl.3 b/man/man3/nextupl.3 new file mode 100644 index 0000000..853b388 --- /dev/null +++ b/man/man3/nextupl.3 @@ -0,0 +1 @@ +.so man3/nextup.3 diff --git a/man/man3/nftw.3 b/man/man3/nftw.3 new file mode 100644 index 0000000..1a5c9c9 --- /dev/null +++ b/man/man3/nftw.3 @@ -0,0 +1 @@ +.so man3/ftw.3 diff --git a/man/man3/nl_langinfo.3 b/man/man3/nl_langinfo.3 new file mode 100644 index 0000000..fb1be16 --- /dev/null +++ b/man/man3/nl_langinfo.3 @@ -0,0 +1,353 @@ +'\" t +.\" Copyright (c) 2001 Markus Kuhn +.\" and Copyright (c) 2015 Sam Varshavchik +.\" and Copyright (c) 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 manual +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.\" Corrected prototype, 2002-10-18, aeb +.\" +.TH nl_langinfo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nl_langinfo, nl_langinfo_l \- query language and locale information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *nl_langinfo(nl_item " item ); +.BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nl_langinfo_l (): +.nf + Since glibc 2.24: + _POSIX_C_SOURCE >= 200809L + glibc 2.23 and earlier: + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR nl_langinfo () +and +.BR nl_langinfo_l () +functions provide access to locale information +in a more flexible way than +.BR localeconv (3). +.BR nl_langinfo () +returns a string which is the value corresponding to +\fIitem\fP in the program's current global +locale. +.BR nl_langinfo_l () +returns a string which is the value corresponding to \fIitem\fP +for the locale identified by the locale object \fIlocale\fP, +which was previously created by +.BR newlocale (3). +Individual and additional elements of the locale categories can +be queried. +.P +Examples for the locale elements that can be specified in \fIitem\fP +using the constants defined in \fI\fP are: +.TP +.BR CODESET \ (LC_CTYPE) +Return a string with the name of the character encoding used in the +selected locale, such as "UTF\-8", "ISO\-8859\-1", or "ANSI_X3.4\-1968" +(better known as US-ASCII). +This is the same string that you get with +"locale charmap". +For a list of character encoding names, +try "locale \-m" (see +.BR locale (1)). +.TP +.BR D_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent time and date in a locale-specific way +.RB ( %c +conversion specification). +.TP +.BR D_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a date in a locale-specific way +.RB ( %x +conversion specification). +.TP +.BR T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a time in a locale-specific way +.RB ( %X +conversion specification). +.TP +.BR AM_STR \ (LC_TIME) +Return a string that represents affix for ante meridiem (before noon, "AM") +time. +(Used in +.B %p +.BR strftime (3) +conversion specification.) +.TP +.BR PM_STR \ (LC_TIME) +Return a string that represents affix for post meridiem (before midnight, "PM") +time. +(Used in +.B %p +.BR strftime (3) +conversion specification.) +.TP +.BR T_FMT_AMPM \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +to represent a time in a.m. or p.m. notation in a locale-specific way +.RB ( %r +conversion specification). +.TP +.BR ERA \ (LC_TIME) +Return era description, which contains information about how years are counted +and displayed for each era in a locale. +Each era description segment shall have the format: +.RS +.IP +.IR direction : offset : start_date : end_date : era_name : era_format +.RE +.IP +according to the definitions below: +.RS +.TP 12 +.I direction +Either a +.RB \[dq] + "\[dq] or a \[dq]" - \[dq] +character. +The +.RB \[dq] + \[dq] +means that years increase from the +.I start_date +towards the +.IR end_date , +.RB \[dq] - \[dq] +means the opposite. +.TP +.I offset +The epoch year of the +.IR start_date . +.TP +.I start_date +A date in the form +.IR yyyy / mm / dd , +where +.IR yyyy ", " mm ", and " dd +are the year, month, and day numbers respectively of the start of the era. +.TP +.I end_date +The ending date of the era, in the same format as the +.IR start_date , +or one of the two special values +.RB \[dq] -* \[dq] +(minus infinity) or +.RB \[dq] +* \[dq] +(plus infinity). +.TP +.I era_name +The name of the era, corresponding to the +.B %EC +.BR strftime (3) +conversion specification. +.TP +.I era_format +The format of the year in the era, corresponding to the +.B %EY +.BR strftime (3) +conversion specification. +.RE +.IP +Era description segments are separated by semicolons. +Most locales do not define this value. +Examples of locales that do define this value are the Japanese and Thai +locales. +.TP +.BR ERA_D_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +for alternative representation of time and date in a locale-specific way +.RB ( %Ec +conversion specification). +.TP +.BR ERA_D_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +for alternative representation of a date in a locale-specific way +.RB ( %Ex +conversion specification). +.TP +.BR ERA_T_FMT \ (LC_TIME) +Return a string that can be used as a format string for +.BR strftime (3) +for alternative representation of a time in a locale-specific way +.RB ( %EX +conversion specification). +.TP +.BR DAY_ "{1\[en]7} (LC_TIME)" +Return name of the \fIn\fP-th day of the week. +[Warning: this follows +the US convention DAY_1 = Sunday, not the international convention +(ISO\~8601) that Monday is the first day of the week.] +(Used in +.B %A +.BR strftime (3) +conversion specification.) +.TP +.BR ABDAY_ "{1\[en]7} (LC_TIME)" +Return abbreviated name of the \fIn\fP-th day of the week. +(Used in +.B %a +.BR strftime (3) +conversion specification.) +.TP +.BR MON_ "{1\[en]12} (LC_TIME)" +Return name of the \fIn\fP-th month. +(Used in +.B %B +.BR strftime (3) +conversion specification.) +.TP +.BR ABMON_ "{1\[en]12} (LC_TIME)" +Return abbreviated name of the \fIn\fP-th month. +(Used in +.B %b +.BR strftime (3) +conversion specification.) +.TP +.BR RADIXCHAR \ (LC_NUMERIC) +Return radix character (decimal dot, decimal comma, etc.). +.TP +.BR THOUSEP \ (LC_NUMERIC) +Return separator character for thousands (groups of three digits). +.TP +.BR YESEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the +.BR regex (3) +function to recognize a positive response to a yes/no question. +.TP +.BR NOEXPR \ (LC_MESSAGES) +Return a regular expression that can be used with the +.BR regex (3) +function to recognize a negative response to a yes/no question. +.TP +.BR CRNCYSTR \ (LC_MONETARY) +Return the currency symbol, preceded by "\-" if the symbol should +appear before the value, "+" if the symbol should appear after the +value, or "." if the symbol should replace the radix character. +.P +The above list covers just some examples of items that can be requested. +For a more detailed list, consult +.IR "The GNU C Library Reference Manual" . +.SH RETURN VALUE +On success, these functions return a pointer to a string which +is the value corresponding to +.I item +in the specified locale. +.P +If no locale has been selected by +.BR setlocale (3) +for the appropriate category, +.BR nl_langinfo () +return a pointer to the corresponding string in the "C" locale. +The same is true of +.BR nl_langinfo_l () +if +.I locale +specifies a locale where +.I langinfo +data is not defined. +.P +If \fIitem\fP is not valid, a pointer to an empty string is returned. +.P +The pointer returned by these functions may point to static data that +may be overwritten, or the pointer itself may be invalidated, +by a subsequent call to +.BR nl_langinfo (), +.BR nl_langinfo_l (), +or +.BR setlocale (3). +The same statements apply to +.BR nl_langinfo_l () +if the locale object referred to by +.I locale +is freed or modified by +.BR freelocale (3) +or +.BR newlocale (3). +.P +POSIX specifies that the application may not modify +the string returned by these functions. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nl_langinfo () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SUSv2. +.SH NOTES +The behavior of +.BR nl_langinfo_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +or is not a valid locale object handle. +.SH EXAMPLES +The following program sets the character type and the numeric locale +according to the environment and queries the terminal character set and +the radix character. +.P +.\" SRC BEGIN (nl_langinfo.c) +.EX +#include +#include +#include +#include +\& +int +main(void) +{ + setlocale(LC_CTYPE, ""); + setlocale(LC_NUMERIC, ""); +\& + printf("%s\en", nl_langinfo(CODESET)); + printf("%s\en", nl_langinfo(RADIXCHAR)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR locale (1), +.BR localeconv (3), +.BR setlocale (3), +.BR charsets (7), +.BR locale (7) +.P +The GNU C Library Reference Manual diff --git a/man/man3/nl_langinfo_l.3 b/man/man3/nl_langinfo_l.3 new file mode 100644 index 0000000..36c3e35 --- /dev/null +++ b/man/man3/nl_langinfo_l.3 @@ -0,0 +1 @@ +.so man3/nl_langinfo.3 diff --git a/man/man3/nrand48.3 b/man/man3/nrand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/nrand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/nrand48_r.3 b/man/man3/nrand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/nrand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/ntohl.3 b/man/man3/ntohl.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man/man3/ntohl.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man/man3/ntohs.3 b/man/man3/ntohs.3 new file mode 100644 index 0000000..ba374e8 --- /dev/null +++ b/man/man3/ntohs.3 @@ -0,0 +1 @@ +.so man3/byteorder.3 diff --git a/man/man3/ntp_adjtime.3 b/man/man3/ntp_adjtime.3 new file mode 100644 index 0000000..b08b9c8 --- /dev/null +++ b/man/man3/ntp_adjtime.3 @@ -0,0 +1 @@ +.so man2/adjtimex.2 diff --git a/man/man3/ntp_gettime.3 b/man/man3/ntp_gettime.3 new file mode 100644 index 0000000..96ac817 --- /dev/null +++ b/man/man3/ntp_gettime.3 @@ -0,0 +1,135 @@ +'\" t +.\" Copyright (c) 2016 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH ntp_gettime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ntp_gettime, ntp_gettimex \- get time parameters (NTP daemon interface) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int ntp_gettime(struct ntptimeval *" ntv ); +.BI "int ntp_gettimex(struct ntptimeval *" ntv ); +.fi +.SH DESCRIPTION +Both of these APIs return information to the caller via the +.I ntv +argument, a structure of the following type: +.P +.in +4n +.EX +struct ntptimeval { + struct timeval time; /* Current time */ + long maxerror; /* Maximum error */ + long esterror; /* Estimated error */ + long tai; /* TAI offset */ +\& + /* Further padding bytes allowing for future expansion */ +}; +.EE +.in +.P +The fields of this structure are as follows: +.TP +.I time +The current time, expressed as a +.I timeval +structure: +.IP +.in +4n +.EX +struct timeval { + time_t tv_sec; /* Seconds since the Epoch */ + suseconds_t tv_usec; /* Microseconds */ +}; +.EE +.in +.TP +.I maxerror +Maximum error, in microseconds. +This value can be initialized by +.BR ntp_adjtime (3), +and is increased periodically (on Linux: each second), +but is clamped to an upper limit (the kernel constant +.BR NTP_PHASE_MAX , +with a value of 16,000). +.TP +.I esterror +Estimated error, in microseconds. +This value can be set via +.BR ntp_adjtime (3) +to contain an estimate of the difference between the system clock +and the true time. +This value is not used inside the kernel. +.TP +.I tai +TAI (Atomic International Time) offset. +.P +.BR ntp_gettime () +returns an +.I ntptimeval +structure in which the +.IR time , +.IR maxerror , +and +.I esterror +fields are filled in. +.P +.BR ntp_gettimex () +performs the same task as +.BR ntp_gettime (), +but also returns information in the +.I tai +field. +.SH RETURN VALUE +The return values for +.BR ntp_gettime () +and +.BR ntp_gettimex () +are as for +.BR adjtimex (2). +Given a correct pointer argument, these functions always succeed. +.\" FIXME . the info page incorrectly describes the return values. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ntp_gettime (), +.BR ntp_gettimex () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR ntp_gettime () +NTP Kernel Application Program Interface. +.TP +.BR ntp_gettimex () +GNU. +.SH HISTORY +.TP +.BR ntp_gettime () +glibc 2.1. +.TP +.BR ntp_gettimex () +glibc 2.12. +.SH SEE ALSO +.BR adjtimex (2), +.BR ntp_adjtime (3), +.BR time (7) +.P +.ad l +.UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm +NTP "Kernel Application Program Interface" +.UE diff --git a/man/man3/ntp_gettimex.3 b/man/man3/ntp_gettimex.3 new file mode 100644 index 0000000..142d76b --- /dev/null +++ b/man/man3/ntp_gettimex.3 @@ -0,0 +1 @@ +.so man3/ntp_gettime.3 diff --git a/man/man3/offsetof.3 b/man/man3/offsetof.3 new file mode 100644 index 0000000..e9ce590 --- /dev/null +++ b/man/man3/offsetof.3 @@ -0,0 +1,110 @@ +.\" Copyright (C) 2006 Justin Pryzby +.\" and Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" /usr/lib/gcc/i486-linux-gnu/4.1.1/include/stddef.h +.\" glibc-doc +.TH offsetof 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +offsetof \- offset of a structure member +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t offsetof(" type ", " member ); +.fi +.SH DESCRIPTION +The macro +.BR offsetof () +returns the offset of the field +.I member +from the start of the structure +.IR type . +.P +This macro is useful because the sizes of the fields that compose +a structure can vary across implementations, +and compilers may insert different numbers of padding +bytes between fields. +Consequently, an element's offset is not necessarily +given by the sum of the sizes of the previous elements. +.P +A compiler error will result if +.I member +is not aligned to a byte boundary +(i.e., it is a bit field). +.SH RETURN VALUE +.BR offsetof () +returns the offset of the given +.I member +within the given +.IR type , +in units of bytes. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH EXAMPLES +On a Linux/i386 system, when compiled using the default +.BR gcc (1) +options, the program below produces the following output: +.P +.in +4n +.EX +.RB "$" " ./a.out" +offsets: i=0; c=4; d=8 a=16 +sizeof(struct s)=16 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (offsetof.c) +.EX +#include +#include +#include +\& +int +main(void) +{ + struct s { + int i; + char c; + double d; + char a[]; + }; +\& + /* Output is compiler dependent */ +\& + printf("offsets: i=%zu; c=%zu; d=%zu a=%zu\en", + offsetof(struct s, i), offsetof(struct s, c), + offsetof(struct s, d), offsetof(struct s, a)); + printf("sizeof(struct s)=%zu\en", sizeof(struct s)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END diff --git a/man/man3/on_exit.3 b/man/man3/on_exit.3 new file mode 100644 index 0000000..517c6e2 --- /dev/null +++ b/man/man3/on_exit.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-04-02, David Metcalfe +.\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) +.TH on_exit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +on_exit \- register a function to be called at normal process termination +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int on_exit(void (*" function ")(int, void *), void *" arg ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR on_exit (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR on_exit () +function registers the given +.I function +to be +called at normal process termination, whether via +.BR exit (3) +or via return from the program's +.IR main (). +The +.I function +is passed the status argument given to the last call to +.BR exit (3) +and the +.I arg +argument from +.BR on_exit (). +.P +The same function may be registered multiple times: +it is called once for each registration. +.P +When a child process is created via +.BR fork (2), +it inherits copies of its parent's registrations. +Upon a successful call to one of the +.BR exec (3) +functions, all registrations are removed. +.SH RETURN VALUE +The +.BR on_exit () +function returns the value 0 if successful; otherwise +it returns a nonzero value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR on_exit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +SunOS 4, glibc. +Removed in Solaris (SunOS 5). +Use the standard +.BR atexit (3) +instead. +.SH CAVEATS +By the time +.I function +is executed, stack +.RI ( auto ) +variables may already have gone out of scope. +Therefore, +.I arg +should not be a pointer to a stack variable; +it may however be a pointer to a heap variable or a global variable. +.SH SEE ALSO +.BR _exit (2), +.BR atexit (3), +.BR exit (3) diff --git a/man/man3/open_memstream.3 b/man/man3/open_memstream.3 new file mode 100644 index 0000000..d2a18ec --- /dev/null +++ b/man/man3/open_memstream.3 @@ -0,0 +1,141 @@ +'\" t +.\" Copyright 2005, 2012, 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" 2008-12-04, Petr Baudis : Document open_wmemstream() +.\" +.TH open_memstream 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +open_memstream, open_wmemstream \- open a dynamic memory buffer stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc ); +.P +.B #include +.P +.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR open_memstream (), +.BR open_wmemstream (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR open_memstream () +function opens a stream for writing to a memory buffer. +The function dynamically allocates the buffer, +and the buffer automatically grows as needed. +Initially, the buffer has a size of zero. +After closing the stream, the caller should +.BR free (3) +this buffer. +.P +The locations pointed to by +.I ptr +and +.I sizeloc +are used to report, respectively, +the current location and the size of the buffer. +The locations referred to by these pointers are updated +each time the stream is flushed +.RB ( fflush (3)) +and when the stream is closed +.RB ( fclose (3)). +These values remain valid only as long as the caller +performs no further output on the stream. +If further output is performed, then the stream +must again be flushed before trying to access these values. +.P +A null byte is maintained at the end of the buffer. +This byte is +.I not +included in the size value stored at +.IR sizeloc . +.P +The stream maintains the notion of a current position, +which is initially zero (the start of the buffer). +Each write operation implicitly adjusts the buffer position. +The stream's buffer position can be explicitly changed with +.BR fseek (3) +or +.BR fseeko (3). +Moving the buffer position past the end +of the data already written fills the intervening space with +null characters. +.P +The +.BR open_wmemstream () +is similar to +.BR open_memstream (), +but operates on wide characters instead of bytes. +.SH RETURN VALUE +Upon successful completion, +.BR open_memstream () +and +.BR open_wmemstream () +return a +.I FILE +pointer. +Otherwise, NULL is returned and +.I errno +is set to indicate the error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR open_memstream (), +.BR open_wmemstream () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +.TP +.BR open_memstream () +glibc 1.0.x. +.TP +.BR open_wmemstream () +glibc 2.4. +.SH NOTES +There is no file descriptor associated with the file stream +returned by these functions +(i.e., +.BR fileno (3) +will return an error if called on the returned stream). +.SH BUGS +Before glibc 2.7, seeking past the end of a stream created by +.BR open_memstream () +does not enlarge the buffer; instead the +.BR fseek (3) +call fails, returning \-1. +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996 +.SH EXAMPLES +See +.BR fmemopen (3). +.SH SEE ALSO +.BR fmemopen (3), +.BR fopen (3), +.BR setbuf (3) diff --git a/man/man3/open_wmemstream.3 b/man/man3/open_wmemstream.3 new file mode 100644 index 0000000..a113f13 --- /dev/null +++ b/man/man3/open_wmemstream.3 @@ -0,0 +1 @@ +.so man3/open_memstream.3 diff --git a/man/man3/opendir.3 b/man/man3/opendir.3 new file mode 100644 index 0000000..9a558e4 --- /dev/null +++ b/man/man3/opendir.3 @@ -0,0 +1,145 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:46:01 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.\" 2007-07-30 Ulrich Drepper : document fdopendir(). +.TH opendir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +opendir, fdopendir \- open a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "DIR *opendir(const char *" name ); +.BI "DIR *fdopendir(int " fd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR fdopendir (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR opendir () +function opens a directory stream corresponding to the +directory \fIname\fP, and returns a pointer to the directory stream. +The stream is positioned at the first entry in the directory. +.P +The +.BR fdopendir () +function +is like +.BR opendir (), +but returns a directory stream for the directory referred +to by the open file descriptor +.IR fd . +After a successful call to +.BR fdopendir (), +.I fd +is used internally by the implementation, +and should not otherwise be used by the application. +.SH RETURN VALUE +The +.BR opendir () +and +.BR fdopendir () +functions return a pointer to the directory stream. +On error, NULL is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Permission denied. +.TP +.B EBADF +.I fd +is not a valid file descriptor opened for reading. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +Directory does not exist, or \fIname\fP is an empty string. +.TP +.B ENOMEM +Insufficient memory to complete the operation. +.TP +.B ENOTDIR +\fIname\fP is not a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR opendir (), +.BR fdopendir () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH STANDARDS +.TP +.BR opendir () +SVr4, 4.3BSD, POSIX.1-2001. +.TP +.BR fdopendir () +POSIX.1-2008. +glibc 2.4. +.SH NOTES +Filename entries can be read from a directory stream using +.BR readdir (3). +.P +The underlying file descriptor of the directory stream can be obtained using +.BR dirfd (3). +.P +The +.BR opendir () +function sets the close-on-exec flag for the file descriptor underlying the +.IR "DIR *" . +The +.BR fdopendir () +function leaves the setting of the close-on-exec +flag unchanged for the file descriptor, +.IR fd . +POSIX.1-200x leaves it unspecified whether a successful call to +.BR fdopendir () +will set the close-on-exec flag for the file descriptor, +.IR fd . +.SH SEE ALSO +.BR open (2), +.BR closedir (3), +.BR dirfd (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man/man3/openlog.3 b/man/man3/openlog.3 new file mode 100644 index 0000000..ec352b2 --- /dev/null +++ b/man/man3/openlog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man/man3/openpty.3 b/man/man3/openpty.3 new file mode 100644 index 0000000..09eb223 --- /dev/null +++ b/man/man3/openpty.3 @@ -0,0 +1,179 @@ +'\" t +.\" Copyright (c) OpenBSD Group +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Converted into a manpage again by Martin Schulze +.\" +.\" Added -lutil remark, 030718 +.\" +.TH openpty 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +openpty, login_tty, forkpty \- terminal utility functions +.SH LIBRARY +System utilities library +.RI ( libutil ", " \-lutil ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int openpty(int *" amaster ", int *" aslave ", char *" name , +.BI " const struct termios *" termp , +.BI " const struct winsize *" winp ); +.BI "pid_t forkpty(int *" amaster ", char *" name , +.BI " const struct termios *" termp , +.BI " const struct winsize *" winp ); +.P +.B #include +.P +.BI "int login_tty(int " fd ); +.fi +.SH DESCRIPTION +The +.BR openpty () +function finds an available pseudoterminal and returns file descriptors +for the master and slave in +.I amaster +and +.IR aslave . +If +.I name +is not NULL, the filename of the slave is returned in +.IR name . +If +.I termp +is not NULL, the terminal parameters of the slave will be set to the +values in +.IR termp . +If +.I winp +is not NULL, the window size of the slave will be set to the values in +.IR winp . +.P +The +.BR login_tty () +function prepares for a login on the terminal +referred to by the file descriptor +.I fd +(which may be a real terminal device, or the slave of a pseudoterminal as +returned by +.BR openpty ()) +by creating a new session, making +.I fd +the controlling terminal for the calling process, setting +.I fd +to be the standard input, output, and error streams of the current +process, and closing +.IR fd . +.P +The +.BR forkpty () +function combines +.BR openpty (), +.BR fork (2), +and +.BR login_tty () +to create a new process operating in a pseudoterminal. +A file descriptor referring to +master side of the pseudoterminal is returned in +.IR amaster . +If +.I name +is not NULL, the buffer it points to is used to return the +filename of the slave. +The +.I termp +and +.I winp +arguments, if not NULL, +will determine the terminal attributes and window size of the slave +side of the pseudoterminal. +.SH RETURN VALUE +If a call to +.BR openpty (), +.BR login_tty (), +or +.BR forkpty () +is not successful, \-1 is returned and +.I errno +is set to indicate the error. +Otherwise, +.BR openpty (), +.BR login_tty (), +and the child process of +.BR forkpty () +return 0, and the parent process of +.BR forkpty () +returns the process ID of the child process. +.SH ERRORS +.BR openpty () +fails if: +.TP +.B ENOENT +There are no available terminals. +.P +.BR login_tty () +fails if +.BR ioctl (2) +fails to set +.I fd +to the controlling terminal of the calling process. +.P +.BR forkpty () +fails if either +.BR openpty () +or +.BR fork (2) +fails. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR forkpty (), +.BR openpty () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR login_tty () +T} Thread safety MT-Unsafe race:ttyname +.TE +.SH STANDARDS +BSD. +.SH HISTORY +The +.B const +modifiers were added to the structure pointer arguments of +.BR openpty () +and +.BR forkpty () +in glibc 2.8. +.P +Before glibc 2.0.92, +.BR openpty () +returns file descriptors for a BSD pseudoterminal pair; +since glibc 2.0.92, +it first attempts to open a UNIX 98 pseudoterminal pair, +and falls back to opening a BSD pseudoterminal pair if that fails. +.SH BUGS +Nobody knows how much space should be reserved for +.IR name . +So, calling +.BR openpty () +or +.BR forkpty () +with non-NULL +.I name +may not be secure. +.SH SEE ALSO +.BR fork (2), +.BR ttyname (3), +.BR pty (7) diff --git a/man/man3/optarg.3 b/man/man3/optarg.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/optarg.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/opterr.3 b/man/man3/opterr.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/opterr.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/optind.3 b/man/man3/optind.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/optind.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/optopt.3 b/man/man3/optopt.3 new file mode 100644 index 0000000..7612d3f --- /dev/null +++ b/man/man3/optopt.3 @@ -0,0 +1 @@ +.so man3/getopt.3 diff --git a/man/man3/passwd2des.3 b/man/man3/passwd2des.3 new file mode 100644 index 0000000..01b6ce6 --- /dev/null +++ b/man/man3/passwd2des.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man/man3/pathconf.3 b/man/man3/pathconf.3 new file mode 100644 index 0000000..46d8c8b --- /dev/null +++ b/man/man3/pathconf.3 @@ -0,0 +1 @@ +.so man3/fpathconf.3 diff --git a/man/man3/pclose.3 b/man/man3/pclose.3 new file mode 100644 index 0000000..663d4a0 --- /dev/null +++ b/man/man3/pclose.3 @@ -0,0 +1 @@ +.so man3/popen.3 diff --git a/man/man3/perror.3 b/man/man3/perror.3 new file mode 100644 index 0000000..4ad088b --- /dev/null +++ b/man/man3/perror.3 @@ -0,0 +1,142 @@ +'\" t +.\" Copyright (c) 1994 Michael Haardt (michael@moria.de), 1994-06-04 +.\" Copyright (c) 1995 Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de), 1995-03-16 +.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl), 1996-01-13 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1996-01-13 aeb: merged in some text contributed by Melvin Smith +.\" (msmith@falcon.mercer.peachnet.edu) and various other changes. +.\" Modified 1996-05-16 by Martin Schulze (joey@infodrom.north.de) +.\" +.TH perror 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +perror \- print a system error message +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void perror(const char *" s ); +.P +.B #include +.P +.BI "int " errno "; \fR/* Not really declared this way; see errno(3) */" +.P +.BI "[[deprecated]] const char *const " sys_errlist []; +.BI "[[deprecated]] int " sys_nerr ; +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.IR sys_errlist , +.IR sys_nerr : +.nf + From glibc 2.19 to glibc 2.31: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR perror () +function produces a message on standard error describing the last +error encountered during a call to a system or library function. +.P +First (if +.I s +is not NULL and +.I *s +is not a null byte (\[aq]\e0\[aq])), the argument string +.I s +is printed, followed by a colon and a blank. +Then an error message corresponding to the current value of +.I errno +and a new-line. +.P +To be of most use, the argument string should include the name +of the function that incurred the error. +.P +The global error list +.IR sys_errlist "[]," +which can be indexed by +.IR errno , +can be used to obtain the error message without the newline. +The largest message number provided in the table is +.IR sys_nerr "\-1." +Be careful when directly accessing this list, because new error values +may not have been added to +.IR sys_errlist "[]." +The use of +.IR sys_errlist "[]" +is nowadays deprecated; use +.BR strerror (3) +instead. +.P +When a system call fails, it usually returns \-1 and sets the +variable +.I errno +to a value describing what went wrong. +(These values can be found in +.IR .) +Many library functions do likewise. +The function +.BR perror () +serves to translate this error code into human-readable form. +Note that +.I errno +is undefined after a successful system call or library function call: +this call may well change this variable, even though it succeeds, +for example because it internally used some other library function that failed. +Thus, if a failing call is not immediately followed by a call to +.BR perror (), +the value of +.I errno +should be saved. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR perror () +T} Thread safety MT-Safe race:stderr +.TE +.SH STANDARDS +.TP +.I errno +.TQ +.BR perror () +C11, POSIX.1-2008. +.TP +.I sys_nerr +.TQ +.I sys_errlist +BSD. +.SH HISTORY +.TP +.I errno +.TQ +.BR perror () +POSIX.1-2001, C89, 4.3BSD. +.TP +.I sys_nerr +.TQ +.I sys_errlist +Removed in glibc 2.32. +.SH SEE ALSO +.BR err (3), +.BR errno (3), +.BR error (3), +.BR strerror (3) diff --git a/man/man3/pmap_getmaps.3 b/man/man3/pmap_getmaps.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/pmap_getmaps.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/pmap_getport.3 b/man/man3/pmap_getport.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/pmap_getport.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/pmap_rmtcall.3 b/man/man3/pmap_rmtcall.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/pmap_rmtcall.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/pmap_set.3 b/man/man3/pmap_set.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/pmap_set.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/pmap_unset.3 b/man/man3/pmap_unset.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/pmap_unset.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/popen.3 b/man/man3/popen.3 new file mode 100644 index 0000000..9467e06 --- /dev/null +++ b/man/man3/popen.3 @@ -0,0 +1,208 @@ +'\" t +.\" Copyright 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)popen.3 6.4 (Berkeley) 4/30/91 +.\" +.\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu +.\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de) +.\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" +.TH popen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +popen, pclose \- pipe stream to or from a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "FILE *popen(const char *" command ", const char *" type ); +.BI "int pclose(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR popen (), +.BR pclose (): +.nf + _POSIX_C_SOURCE >= 2 + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR popen () +function opens a process by creating a pipe, forking, and invoking the +shell. +Since a pipe is by definition unidirectional, the +.I type +argument may specify only reading or writing, not both; the resulting +stream is correspondingly read-only or write-only. +.P +The +.I command +argument is a pointer to a null-terminated string containing a shell +command line. +This command is passed to +.I /bin/sh +using the +.B \-c +flag; interpretation, if any, is performed by the shell. +.P +The +.I type +argument is a pointer to a null-terminated string which must contain +either the letter \[aq]r\[aq] for reading or the letter \[aq]w\[aq] for writing. +Since glibc 2.9, +this argument can additionally include the letter \[aq]e\[aq], +which causes the close-on-exec flag +.RB ( FD_CLOEXEC ) +to be set on the underlying file descriptor; +see the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.P +The return value from +.BR popen () +is a normal standard I/O stream in all respects save that it must be closed +with +.BR pclose () +rather than +.BR fclose (3). +Writing to such a stream writes to the standard input of the command; the +command's standard output is the same as that of the process that called +.BR popen (), +unless this is altered by the command itself. +Conversely, reading from +the stream reads the command's standard output, and the command's +standard input is the same as that of the process that called +.BR popen (). +.P +Note that output +.BR popen () +streams are block buffered by default. +.P +The +.BR pclose () +function waits for the associated process to terminate and returns the exit +status of the command as returned by +.BR wait4 (2). +.SH RETURN VALUE +.BR popen (): +on success, returns a pointer to an open stream that +can be used to read or write to the pipe; +if the +.BR fork (2) +or +.BR pipe (2) +calls fail, or if the function cannot allocate memory, +NULL is returned. +.P +.BR pclose (): +on success, returns the exit status of the command; if +.\" These conditions actually give undefined results, so I commented +.\" them out. +.\" .I stream +.\" is not associated with a "popen()ed" command, if +.\".I stream +.\" already "pclose()d", or if +.BR wait4 (2) +returns an error, or some other error is detected, +\-1 is returned. +.P +On failure, both functions set +.I errno +to indicate the error. +.SH ERRORS +The +.BR popen () +function does not set +.I errno +if memory allocation fails. +If the underlying +.BR fork (2) +or +.BR pipe (2) +fails, +.I errno +is set to indicate the error. +If the +.I type +argument is invalid, and this condition is detected, +.I errno +is set to +.BR EINVAL . +.P +If +.BR pclose () +cannot obtain the child status, +.I errno +is set to +.BR ECHILD . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR popen (), +.BR pclose () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The \[aq]e\[aq] value for +.I type +is a Linux extension. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH CAVEATS +Carefully read Caveats in +.BR system (3). +.SH BUGS +Since the standard input of a command opened for reading shares its seek +offset with the process that called +.BR popen (), +if the original process has done a buffered read, the command's input +position may not be as expected. +Similarly, the output from a command +opened for writing may become intermingled with that of the original +process. +The latter can be avoided by calling +.BR fflush (3) +before +.BR popen (). +.P +Failure to execute the shell is indistinguishable from the shell's failure +to execute the command, or an immediate exit of the command. +The only hint is an exit status of 127. +.\" .SH HISTORY +.\" A +.\" .BR popen () +.\" and a +.\" .BR pclose () +.\" function appeared in Version 7 AT&T UNIX. +.SH SEE ALSO +.BR sh (1), +.BR fork (2), +.BR pipe (2), +.BR wait4 (2), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR stdio (3), +.BR system (3) diff --git a/man/man3/posix_fallocate.3 b/man/man3/posix_fallocate.3 new file mode 100644 index 0000000..8736f74 --- /dev/null +++ b/man/man3/posix_fallocate.3 @@ -0,0 +1,181 @@ +'\" t +.\" Copyright (c) 2006, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH posix_fallocate 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_fallocate \- allocate file space +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int posix_fallocate(int " fd ", off_t " offset ", off_t " len ); +.fi +.P +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR posix_fallocate (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The function +.BR posix_fallocate () +ensures that disk space is allocated for the file referred to by the +file descriptor +.I fd +for the bytes in the range starting at +.I offset +and continuing for +.I len +bytes. +After a successful call to +.BR posix_fallocate (), +subsequent writes to bytes in the specified range are +guaranteed not to fail because of lack of disk space. +.P +If the size of the file is less than +.IR offset + len , +then the file is increased to this size; +otherwise the file size is left unchanged. +.SH RETURN VALUE +.BR posix_fallocate () +returns zero on success, or an error number on failure. +Note that +.I errno +is not set. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor, or is not opened for writing. +.TP +.B EFBIG +.I offset+len +exceeds the maximum file size. +.TP +.B EINTR +A signal was caught during execution. +.TP +.B EINVAL +.I offset +was less than 0, or +.I len +was less than or equal to 0, or the underlying filesystem does not +support the operation. +.TP +.B ENODEV +.I fd +does not refer to a regular file. +.TP +.B ENOSPC +There is not enough space left on the device containing the file +referred to by +.IR fd . +.TP +.B EOPNOTSUPP +The filesystem containing the file referred to by +.I fd +does not support this operation. +This error code can be returned by C libraries that don't perform the +emulation shown in NOTES, such as musl libc. +.TP +.B ESPIPE +.I fd +refers to a pipe. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR posix_fallocate () +T} Thread safety T{ +.na +.nh +MT-Safe (but see NOTES) +T} +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1.94. +POSIX.1-2001 +.P +POSIX.1-2008 says that an implementation +.I shall +give the +.B EINVAL +error if +.I len +was 0, or +.I offset +was less than 0. +POSIX.1-2001 says that an implementation +.I shall +give the +.B EINVAL +error if +.I len +is less than 0, or +.I offset +was less than 0, and +.I may +give the error if +.I len +equals zero. +.SH CAVEATS +In the glibc implementation, +.BR posix_fallocate () +is implemented using the +.BR fallocate (2) +system call, which is MT-safe. +If the underlying filesystem does not support +.BR fallocate (2), +then the operation is emulated with the following caveats: +.IP \[bu] 3 +The emulation is inefficient. +.IP \[bu] +There is a race condition where concurrent writes from another thread or +process could be overwritten with null bytes. +.IP \[bu] +There is a race condition where concurrent file size increases by +another thread or process could result in a file whose size is smaller +than expected. +.IP \[bu] +If +.I fd +has been opened with the +.B O_APPEND +or +.B O_WRONLY +flags, the function fails with the error +.BR EBADF . +.P +In general, the emulation is not MT-safe. +On Linux, applications may use +.BR fallocate (2) +if they cannot tolerate the emulation caveats. +In general, this is +only recommended if the application plans to terminate the operation if +.B EOPNOTSUPP +is returned, otherwise the application itself will need to implement a +fallback with all the same problems as the emulation provided by glibc. +.SH SEE ALSO +.BR fallocate (1), +.BR fallocate (2), +.BR lseek (2), +.BR posix_fadvise (2) diff --git a/man/man3/posix_madvise.3 b/man/man3/posix_madvise.3 new file mode 100644 index 0000000..383f4f5 --- /dev/null +++ b/man/man3/posix_madvise.3 @@ -0,0 +1,112 @@ +.\" Copyright (C) 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH posix_madvise 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_madvise \- give advice about patterns of memory usage +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int posix_madvise(void " addr [. len "], size_t " len ", int " advice ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR posix_madvise (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR posix_madvise () +function allows an application to advise the system about its expected +patterns of usage of memory in the address range starting at +.I addr +and continuing for +.I len +bytes. +The system is free to use this advice in order to improve the performance +of memory accesses (or to ignore the advice altogether), but calling +.BR posix_madvise () +shall not affect the semantics of access to memory in the specified range. +.P +The +.I advice +argument is one of the following: +.TP +.B POSIX_MADV_NORMAL +The application has no special advice regarding its memory usage patterns +for the specified address range. +This is the default behavior. +.TP +.B POSIX_MADV_SEQUENTIAL +The application expects to access the specified address range sequentially, +running from lower addresses to higher addresses. +Hence, pages in this region can be aggressively read ahead, +and may be freed soon after they are accessed. +.TP +.B POSIX_MADV_RANDOM +The application expects to access the specified address range randomly. +Thus, read ahead may be less useful than normally. +.TP +.B POSIX_MADV_WILLNEED +The application expects to access the specified address range +in the near future. +Thus, read ahead may be beneficial. +.TP +.B POSIX_MADV_DONTNEED +The application expects that it will not access the specified address range +in the near future. +.SH RETURN VALUE +On success, +.BR posix_madvise () +returns 0. +On failure, it returns a positive error number. +.SH ERRORS +.TP +.B EINVAL +.I addr +is not a multiple of the system page size or +.I len +is negative. +.TP +.B EINVAL +.I advice +is invalid. +.TP +.B ENOMEM +Addresses in the specified range are partially or completely outside +the caller's address space. +.SH VERSIONS +POSIX.1 permits an implementation to generate an error if +.I len +is 0. +On Linux, specifying +.I len +as 0 is permitted (as a successful no-op). +.P +In glibc, this function is implemented using +.BR madvise (2). +However, since glibc 2.6, +.B POSIX_MADV_DONTNEED +is treated as a no-op, because the corresponding +.BR madvise (2) +value, +.BR MADV_DONTNEED , +has destructive semantics. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.SH SEE ALSO +.BR madvise (2), +.BR posix_fadvise (2) diff --git a/man/man3/posix_memalign.3 b/man/man3/posix_memalign.3 new file mode 100644 index 0000000..e89e1f9 --- /dev/null +++ b/man/man3/posix_memalign.3 @@ -0,0 +1,276 @@ +'\" t +.\" Copyright (c) 2001 by John Levon +.\" Based in part on GNU libc documentation. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2001-10-11, 2003-08-22, aeb, added some details +.\" 2012-03-23, Michael Kerrisk +.\" Document pvalloc() and aligned_alloc() +.TH posix_memalign 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- +allocate aligned memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size ); +.BI "void *aligned_alloc(size_t " alignment ", size_t " size ); +.BI "[[deprecated]] void *valloc(size_t " size ); +.P +.B #include +.P +.BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size ); +.BI "[[deprecated]] void *pvalloc(size_t " size ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR posix_memalign (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.P +.BR aligned_alloc (): +.nf + _ISOC11_SOURCE +.fi +.P +.BR valloc (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +.BR posix_memalign () +allocates +.I size +bytes and places the address of the allocated memory in +.IR "*memptr" . +The address of the allocated memory will be a multiple of +.IR "alignment" , +which must be a power of two and a multiple of +.IR "sizeof(void\ *)" . +This address can later be successfully passed to +.BR free (3). +If +.I size +is 0, then +the value placed in +.I *memptr +is either NULL +.\" glibc does this: +or a unique pointer value. +.P +The obsolete function +.BR memalign () +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory address will be a multiple of +.IR alignment , +which must be a power of two. +.\" The behavior of memalign() for size==0 is as for posix_memalign() +.\" but no standards govern this. +.P +.BR aligned_alloc () +is the same as +.BR memalign (), +except for the added restriction that +.I alignment +must be a power of two. +.P +The obsolete function +.BR valloc () +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory address will be a multiple of the page size. +It is equivalent to +.IR "memalign(sysconf(_SC_PAGESIZE),size)" . +.P +The obsolete function +.BR pvalloc () +is similar to +.BR valloc (), +but rounds the size of the allocation up to +the next multiple of the system page size. +.P +For all of these functions, the memory is not zeroed. +.SH RETURN VALUE +.BR aligned_alloc (), +.BR memalign (), +.BR valloc (), +and +.BR pvalloc () +return a pointer to the allocated memory on success. +On error, NULL is returned, and \fIerrno\fP is set +to indicate the error. +.P +.BR posix_memalign () +returns zero on success, or one of the error values listed in the +next section on failure. +The value of +.I errno +is not set. +On Linux (and other systems), +.BR posix_memalign () +does not modify +.I memptr +on failure. +A requirement standardizing this behavior was added in POSIX.1-2008 TC2. +.\" http://austingroupbugs.net/view.php?id=520 +.SH ERRORS +.TP +.B EINVAL +The +.I alignment +argument was not a power of two, or was not a multiple of +.IR "sizeof(void\ *)" . +.TP +.B ENOMEM +Out of memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aligned_alloc (), +.BR memalign (), +.BR posix_memalign () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR valloc (), +.BR pvalloc () +T} Thread safety MT-Unsafe init +.TE +.SH STANDARDS +.TP +.BR aligned_alloc () +C11. +.TP +.BR posix_memalign () +POSIX.1-2008. +.TP +.BR memalign () +.TQ +.BR valloc () +None. +.TP +.BR pvalloc () +GNU. +.SH HISTORY +.TP +.BR aligned_alloc () +glibc 2.16. +C11. +.TP +.BR posix_memalign () +glibc 2.1.91. +POSIX.1d, POSIX.1-2001. +.TP +.BR memalign () +glibc 2.0. +SunOS 4.1.3. +.TP +.BR valloc () +glibc 2.0. +3.0BSD. +Documented as obsolete in 4.3BSD, +and as legacy in SUSv2. +.TP +.BR pvalloc () +glibc 2.0. +.\" +.SS Headers +Everybody agrees that +.BR posix_memalign () +is declared in \fI\fP. +.P +On some systems +.BR memalign () +is declared in \fI\fP instead of \fI\fP. +.P +According to SUSv2, +.BR valloc () +is declared in \fI\fP. +.\" Libc4,5 and +glibc declares it in \fI\fP, and also in +\fI\fP +if suitable feature test macros are defined (see above). +.SH NOTES +On many systems there are alignment restrictions, for example, on buffers +used for direct block device I/O. +POSIX specifies the +.I "pathconf(path,_PC_REC_XFER_ALIGN)" +call that tells what alignment is needed. +Now one can use +.BR posix_memalign () +to satisfy this requirement. +.P +.BR posix_memalign () +verifies that +.I alignment +matches the requirements detailed above. +.BR memalign () +may not check that the +.I alignment +argument is correct. +.P +POSIX requires that memory obtained from +.BR posix_memalign () +can be freed using +.BR free (3). +Some systems provide no way to reclaim memory allocated with +.BR memalign () +or +.BR valloc () +(because one can pass to +.BR free (3) +only a pointer obtained from +.BR malloc (3), +while, for example, +.BR memalign () +would call +.BR malloc (3) +and then align the obtained value). +.\" Other systems allow passing the result of +.\" .IR valloc () +.\" to +.\" .IR free (3), +.\" but not to +.\" .IR realloc (3). +The glibc implementation +allows memory obtained from any of these functions to be +reclaimed with +.BR free (3). +.P +The glibc +.BR malloc (3) +always returns 8-byte aligned memory addresses, so these functions are +needed only if you require larger alignment values. +.SH SEE ALSO +.BR brk (2), +.BR getpagesize (2), +.BR free (3), +.BR malloc (3) diff --git a/man/man3/posix_openpt.3 b/man/man3/posix_openpt.3 new file mode 100644 index 0000000..04abebe --- /dev/null +++ b/man/man3/posix_openpt.3 @@ -0,0 +1,107 @@ +'\" t +.\" Copyright (C) 2004 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH posix_openpt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_openpt \- open a pseudoterminal device +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int posix_openpt(int " flags ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR posix_openpt (): +.nf + _XOPEN_SOURCE >= 600 +.fi +.SH DESCRIPTION +The +.BR posix_openpt () +function opens an unused pseudoterminal master device, returning a +file descriptor that can be used to refer to that device. +.P +The +.I flags +argument is a bit mask that ORs together zero or more of +the following flags: +.TP +.B O_RDWR +Open the device for both reading and writing. +It is usual to specify this flag. +.TP +.B O_NOCTTY +Do not make this device the controlling terminal for the process. +.SH RETURN VALUE +On success, +.BR posix_openpt () +returns a file descriptor (a nonnegative integer) which is the lowest +numbered unused file descriptor. +On failure, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +See +.BR open (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR posix_openpt () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2.1. +POSIX.1-2001. +.P +It is part of the UNIX 98 pseudoterminal support (see +.BR pts (4)). +.SH NOTES +Some older UNIX implementations that support System V +(aka UNIX 98) pseudoterminals don't have this function, but it +can be easily implemented by opening the pseudoterminal multiplexor device: +.P +.in +4n +.EX +int +posix_openpt(int flags) +{ + return open("/dev/ptmx", flags); +} +.EE +.in +.P +Calling +.BR posix_openpt () +creates a pathname for the corresponding pseudoterminal slave device. +The pathname of the slave device can be obtained using +.BR ptsname (3). +The slave device pathname exists only as long as the master device is open. +.SH SEE ALSO +.BR open (2), +.BR getpt (3), +.BR grantpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR pts (4), +.BR pty (7) diff --git a/man/man3/posix_spawn.3 b/man/man3/posix_spawn.3 new file mode 100644 index 0000000..71a5b84 --- /dev/null +++ b/man/man3/posix_spawn.3 @@ -0,0 +1,823 @@ +.\" Copyright (c) 2009 Bill O. Gallmeister (bgallmeister@gmail.com) +.\" and Copyright 2010 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux glibc source code +.\" POSIX 1003.1-2004 documentation +.\" (http://www.opengroup.org/onlinepubs/009695399) +.\" +.TH posix_spawn 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posix_spawn, posix_spawnp \- spawn a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int posix_spawn(pid_t *restrict " pid ", const char *restrict " path , +.BI " const posix_spawn_file_actions_t *restrict " file_actions , +.BI " const posix_spawnattr_t *restrict " attrp , +.BI " char *const " argv [restrict], +.BI " char *const " envp [restrict]); +.BI "int posix_spawnp(pid_t *restrict " pid ", const char *restrict " file , +.BI " const posix_spawn_file_actions_t *restrict " file_actions , +.BI " const posix_spawnattr_t *restrict " attrp , +.BI " char *const " argv [restrict], +.BI " char *const " envp [restrict]); +.fi +.SH DESCRIPTION +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions are used to create a new child process that executes +a specified file. +These functions were specified by POSIX to provide a standardized method +of creating new processes on machines that lack the capability +to support the +.BR fork (2) +system call. +These machines are generally small, embedded systems lacking MMU support. +.P +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions provide the functionality of a combined +.BR fork (2) +and +.BR exec (3), +with some optional housekeeping steps in the child process before the +.BR exec (3). +These functions are not meant to replace the +.BR fork (2) +and +.BR execve (2) +system calls. +In fact, they provide only a subset of the functionality +that can be achieved by using the system calls. +.P +The only difference between +.BR posix_spawn () +and +.BR posix_spawnp () +is the manner in which they specify the file to be executed by +the child process. +With +.BR posix_spawn (), +the executable file is specified as a pathname +(which can be absolute or relative). +With +.BR posix_spawnp (), +the executable file is specified as a simple filename; +the system searches for this file in the list of directories specified by +.B PATH +(in the same way as for +.BR execvp (3)). +For the remainder of this page, the discussion is phrased in terms of +.BR posix_spawn (), +with the understanding that +.BR posix_spawnp () +differs only on the point just described. +.P +The remaining arguments to these two functions are as follows: +.TP +.I pid +points to a buffer that is used to return the process ID +of the new child process. +.TP +.I file_actions +points to a +.I "spawn file actions object" +that specifies file-related actions to be performed in the child +between the +.BR fork (2) +and +.BR exec (3) +steps. +This object is initialized and populated before the +.BR posix_spawn () +call using +.BR posix_spawn_file_actions_init (3) +and the +.BR posix_spawn_file_actions_* () +functions. +.TP +.I attrp +points to an +.I attributes objects +that specifies various attributes of the created child process. +This object is initialized and populated before the +.BR posix_spawn () +call using +.BR posix_spawnattr_init (3) +and the +.BR posix_spawnattr_* () +functions. +.TP +.I argv +.TQ +.I envp +specify the argument list and environment for the program +that is executed in the child process, as for +.BR execve (2). +.P +Below, the functions are described in terms of a three-step process: the +.BR fork () +step, the +.RB pre- exec () +step (executed in the child), +and the +.BR exec () +step (executed in the child). +.SS fork() step +Since glibc 2.24, the +.BR posix_spawn () +function commences by calling +.BR clone (2) +with +.B CLONE_VM +and +.B CLONE_VFORK +flags. +Older implementations use +.BR fork (2), +or possibly +.BR vfork (2) +(see below). +.P +The PID of the new child process is placed in +.IR *pid . +The +.BR posix_spawn () +function then returns control to the parent process. +.P +Subsequently, the parent can use one of the system calls described in +.BR wait (2) +to check the status of the child process. +If the child fails in any of the housekeeping steps described below, +or fails to execute the desired file, +it exits with a status of 127. +.P +Before glibc 2.24, the child process is created using +.BR vfork (2) +instead of +.BR fork (2) +when either of the following is true: +.IP \[bu] 3 +the +.I spawn-flags +element of the attributes object pointed to by +.I attrp +contains the GNU-specific flag +.BR POSIX_SPAWN_USEVFORK ; +or +.IP \[bu] +.I file_actions +is NULL and the +.I spawn-flags +element of the attributes object pointed to by +.I attrp +does \fInot\fP contain +.BR POSIX_SPAWN_SETSIGMASK , +.BR POSIX_SPAWN_SETSIGDEF , +.BR POSIX_SPAWN_SETSCHEDPARAM , +.BR POSIX_SPAWN_SETSCHEDULER , +.BR POSIX_SPAWN_SETPGROUP , +or +.BR POSIX_SPAWN_RESETIDS . +.P +In other words, +.BR vfork (2) +is used if the caller requests it, +or if there is no cleanup expected in the child before it +.BR exec (3)s +the requested file. +.SS pre-exec() step: housekeeping +In between the +.B fork() +and the +.B exec() +steps, a child process may need to perform a set of housekeeping actions. +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions support a small, well-defined set of system tasks that the child +process can accomplish before it executes the executable file. +These operations are controlled by the attributes object pointed to by +.I attrp +and the file actions object pointed to by +.IR file_actions . +In the child, processing is done in the following sequence: +.IP (1) 5 +Process attribute actions: signal mask, signal default handlers, +scheduling algorithm and parameters, +process group, and effective user and group IDs +are changed as specified by the attributes object pointed to by +.IR attrp . +.IP (2) +File actions, as specified in the +.I file_actions +argument, +are performed in the order that they were specified using calls to the +.BR posix_spawn_file_actions_add* () +functions. +.IP (3) +File descriptors with the +.B FD_CLOEXEC +flag set are closed. +.P +All process attributes in the child, +other than those affected by attributes specified in the +object pointed to by +.I attrp +and the file actions in the object pointed to by +.IR file_actions , +will be affected as though the child was created with +.BR fork (2) +and it executed the program with +.BR execve (2). +.P +The process attributes actions are defined by the attributes object +pointed to by +.IR attrp . +The +.I spawn-flags +attribute (set using +.BR posix_spawnattr_setflags (3)) +controls the general actions that occur, +and other attributes in the object specify values +to be used during those actions. +.P +The effects of the flags that may be specified in +.I spawn-flags +are as follows: +.TP +.B POSIX_SPAWN_SETSIGMASK +Set the signal mask to the signal set specified in the +.I spawn-sigmask +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setsigmask (3)) +of the object pointed to by +.IR attrp . +If the +.B POSIX_SPAWN_SETSIGMASK +flag is not set, then the child inherits the parent's signal mask. +.TP +.B POSIX_SPAWN_SETSIGDEF +Reset the disposition of all signals in the set specified in the +.I spawn-sigdefault +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setsigdefault (3)) +of the object pointed to by +.I attrp +to the default. +For the treatment of the dispositions of signals not specified in the +.I spawn-sigdefault +attribute, or the treatment when +.B POSIX_SPAWN_SETSIGDEF +is not specified, see +.BR execve (2). +.TP +.B POSIX_SPAWN_SETSCHEDPARAM +.\" (POSIX_PRIORITY_SCHEDULING only) +If this flag is set, and the +.B POSIX_SPAWN_SETSCHEDULER +flag is not set, then set the scheduling parameters +to the parameters specified in the +.I spawn-schedparam +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setschedparam (3)) +of the object pointed to by +.IR attrp . +.TP +.B POSIX_SPAWN_SETSCHEDULER +Set the scheduling policy algorithm and parameters of the child, +as follows: +.RS +.IP \[bu] 3 +The scheduling policy is set to the value specified in the +.I spawn-schedpolicy +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setpolicy (3)) +of the object pointed to by +.IR attrp . +.IP \[bu] +The scheduling parameters are set to the value specified in the +.I spawn-schedparam +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setschedparam (3)) +of the object pointed to by +.I attrp +(but see BUGS). +.P +If the +.B POSIX_SPAWN_SETSCHEDPARAM +and +.B POSIX_SPAWN_SETSCHEDPOLICY +flags are not specified, +the child inherits the corresponding scheduling attributes from the parent. +.RE +.TP +.B POSIX_SPAWN_RESETIDS +If this flag is set, +reset the effective UID and GID to the +real UID and GID of the parent process. +If this flag is not set, +then the child retains the effective UID and GID of the parent. +In either case, if the set-user-ID and set-group-ID permission +bits are enabled on the executable file, their effect will override +the setting of the effective UID and GID (se +.BR execve (2)). +.TP +.B POSIX_SPAWN_SETPGROUP +Set the process group to the value specified in the +.I spawn-pgroup +attribute +.\" FIXME . +.\" (see +.\" .BR posix_spawnattr_setpgroup (3)) +of the object pointed to by +.IR attrp . +If the +.I spawn-pgroup +attribute has the value 0, +the child's process group ID is made the same as its process ID. +If the +.B POSIX_SPAWN_SETPGROUP +flag is not set, the child inherits the parent's process group ID. +.TP +.B POSIX_SPAWN_USEVFORK +Since glibc 2.24, this flag has no effect. +On older implementations, setting this flag forces the +.B fork() +step to use +.BR vfork (2) +instead of +.BR fork (2). +The +.B _GNU_SOURCE +feature test macro must be defined to obtain the definition of this constant. +.TP +.BR POSIX_SPAWN_SETSID " (since glibc 2.26)" +If this flag is set, +the child process shall create a new session and become the session leader. +The child process shall also become the process group leader of the new process +group in the session (see +.BR setsid (2)). +The +.B _GNU_SOURCE +feature test macro must be defined to obtain the definition of this constant. +.\" This flag has been accepted in POSIX, see: +.\" http://austingroupbugs.net/view.php?id=1044 +.\" and has been implemented since glibc 2.26 +.\" commit daeb1fa2e1b33323e719015f5f546988bd4cc73b +.P +If +.I attrp +is NULL, then the default behaviors described above for each flag apply. +.\" mtk: I think we probably don't want to say the following, since it +.\" could lead people to do the wrong thing +.\" The POSIX standard tells you to call +.\" this function to de-initialize the attributes object pointed to by +.\" .I attrp +.\" when you are done with it; +.\" however, on Linux systems this operation is a no-op. +.P +The +.I file_actions +argument specifies a sequence of file operations +that are performed in the child process after +the general processing described above, and before it performs the +.BR exec (3). +If +.I file_actions +is NULL, then no special action is taken, and standard +.BR exec (3) +semantics apply\[em]file descriptors open before the exec +remain open in the new process, +except those for which the +.B FD_CLOEXEC +flag has been set. +File locks remain in place. +.P +If +.I file_actions +is not NULL, then it contains an ordered set of requests to +.BR open (2), +.BR close (2), +and +.BR dup2 (2) +files. +These requests are added to the +.I file_actions +by +.BR posix_spawn_file_actions_addopen (3), +.BR posix_spawn_file_actions_addclose (3), +and +.BR posix_spawn_file_actions_adddup2 (3). +The requested operations are performed in the order they were added to +.IR file_actions . +.\" FIXME . I think the following is best placed in the +.\" posix_spawn_file_actions_adddup2(3) page, and a similar statement is +.\" also needed in posix_spawn_file_actions_addclose(3) +.\" Note that you can specify file descriptors in +.\" .I posix_spawn_file_actions_adddup2 (3) +.\" which would not be usable if you called +.\" .BR dup2 (2) +.\" at that time--i.e., file descriptors that are opened or +.\" closed by the earlier operations +.\" added to +.\" .I file_actions . +.P +If any of the housekeeping actions fails +(due to bogus values being passed or other reasons why signal handling, +process scheduling, process group ID functions, +and file descriptor operations might fail), +the child process exits with exit value 127. +.SS exec() step +Once the child has successfully forked and performed +all requested pre-exec steps, +the child runs the requested executable. +.P +The child process takes its environment from the +.I envp +argument, which is interpreted as if it had been passed to +.BR execve (2). +The arguments to the created process come from the +.I argv +argument, which is processed as for +.BR execve (2). +.SH RETURN VALUE +Upon successful completion, +.BR posix_spawn () +and +.BR posix_spawnp () +place the PID of the child process in +.IR pid , +and return 0. +If there is an error during the +.B fork() +step, +then no child is created, +the contents of +.I *pid +are unspecified, +and these functions return an error number as described below. +.P +Even when these functions return a success status, +the child process may still fail for a plethora of reasons related to its +pre-\fBexec\fR() initialization. +In addition, the +.BR exec (3) +may fail. +In all of these cases, the child process will exit with the exit value of 127. +.SH ERRORS +The +.BR posix_spawn () +and +.BR posix_spawnp () +functions fail only in the case where the underlying +.BR fork (2), +.BR vfork (2), +or +.BR clone (2) +call fails; in these cases, these functions return an error number, +which will be one of the errors described for +.BR fork (2), +.BR vfork (2), +or +.BR clone (2). +.P +In addition, these functions fail if: +.TP +.B ENOSYS +Function not supported on this system. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.\" FIXME . This piece belongs in spawnattr_setflags(3) +.\" The +.\" .B POSIX_SPAWN_USEVFORK +.\" flag is a GNU extension; the +.\" .B _GNU_SOURCE +.\" feature test macro must be defined (before including any header files) +.\" to obtain the definition of this constant. +.SH NOTES +The housekeeping activities in the child are controlled by +the objects pointed to by +.I attrp +(for non-file actions) and +.I file_actions +In POSIX parlance, the +.I posix_spawnattr_t +and +.I posix_spawn_file_actions_t +data types are referred to as objects, +and their elements are not specified by name. +Portable programs should initialize these objects using +only the POSIX-specified functions. +(In other words, +although these objects may be implemented as structures containing fields, +portable programs must avoid dependence on such implementation details.) +.P +According to POSIX, it is unspecified whether fork handlers established with +.BR pthread_atfork (3) +are called when +.BR posix_spawn () +is invoked. +Since glibc 2.24, the fork handlers are not executed in any case. +.\" Tested on glibc 2.12 +On older implementations, +fork handlers are called only if the child is created using +.BR fork (2). +.P +There is no "posix_fspawn" function (i.e., a function that is to +.BR posix_spawn () +as +.BR fexecve (3) +is to +.BR execve (2)). +However, this functionality can be obtained by specifying the +.I path +argument as one of the files in the caller's +.I /proc/self/fd +directory. +.SH BUGS +POSIX.1 says that when +.B POSIX_SPAWN_SETSCHEDULER +is specified in +.IR spawn-flags , +then the +.B POSIX_SPAWN_SETSCHEDPARAM +(if present) is ignored. +However, before glibc 2.14, calls to +.BR posix_spawn () +failed with an error if +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12052 +.B POSIX_SPAWN_SETSCHEDULER +was specified without also specifying +.BR POSIX_SPAWN_SETSCHEDPARAM . +.SH EXAMPLES +The program below demonstrates the use of various functions in the +POSIX spawn API. +The program accepts command-line attributes that can be used +to create file actions and attributes objects. +The remaining command-line arguments are used as the executable name +and command-line arguments of the program that is executed in the child. +.P +In the first run, the +.BR date (1) +command is executed in the child, and the +.BR posix_spawn () +call employs no file actions or attributes objects. +.P +.in +4n +.EX +$ \fB./a.out date\fP +PID of child: 7634 +Tue Feb 1 19:47:50 CEST 2011 +Child status: exited, status=0 +.EE +.in +.P +In the next run, the +.I \-c +command-line option is used to create a file actions object that closes +standard output in the child. +Consequently, +.BR date (1) +fails when trying to perform output and exits with a status of 1. +.P +.in +4n +.EX +$ \fB./a.out \-c date\fP +PID of child: 7636 +date: write error: Bad file descriptor +Child status: exited, status=1 +.EE +.in +.P +In the next run, the +.I \-s +command-line option is used to create an attributes object that +specifies that all (blockable) signals in the child should be blocked. +Consequently, trying to kill child with the default signal sent by +.BR kill (1) +(i.e., +.BR SIGTERM ) +fails, because that signal is blocked. +Therefore, to kill the child, +.B SIGKILL +is necessary +.RB ( SIGKILL +can't be blocked). +.P +.in +4n +.EX +$ \fB./a.out \-s sleep 60 &\fP +[1] 7637 +$ PID of child: 7638 +.P +$ \fBkill 7638\fP +$ \fBkill \-KILL 7638\fP +$ Child status: killed by signal 9 +[1]+ Done ./a.out \-s sleep 60 +.EE +.in +.P +When we try to execute a nonexistent command in the child, the +.BR exec (3) +fails and the child exits with a status of 127. +.P +.in +4n +.EX +$ \fB./a.out xxxxx +PID of child: 10190 +Child status: exited, status=127 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (posix_spawn.c) +.EX +#include +#include +#include +#include +#include +#include +#include +#include +\& +#define errExit(msg) do { perror(msg); \e + exit(EXIT_FAILURE); } while (0) +\& +#define errExitEN(en, msg) \e + do { errno = en; perror(msg); \e + exit(EXIT_FAILURE); } while (0) +\& +char **environ; +\& +int +main(int argc, char *argv[]) +{ + pid_t child_pid; + int s, opt, status; + sigset_t mask; + posix_spawnattr_t attr; + posix_spawnattr_t *attrp; + posix_spawn_file_actions_t file_actions; + posix_spawn_file_actions_t *file_actionsp; +\& + /* Parse command\-line options, which can be used to specify an + attributes object and file actions object for the child. */ +\& + attrp = NULL; + file_actionsp = NULL; +\& + while ((opt = getopt(argc, argv, "sc")) != \-1) { + switch (opt) { + case \[aq]c\[aq]: /* \-c: close standard output in child */ +\& + /* Create a file actions object and add a "close" + action to it. */ +\& + s = posix_spawn_file_actions_init(&file_actions); + if (s != 0) + errExitEN(s, "posix_spawn_file_actions_init"); +\& + s = posix_spawn_file_actions_addclose(&file_actions, + STDOUT_FILENO); + if (s != 0) + errExitEN(s, "posix_spawn_file_actions_addclose"); +\& + file_actionsp = &file_actions; + break; +\& + case \[aq]s\[aq]: /* \-s: block all signals in child */ +\& + /* Create an attributes object and add a "set signal mask" + action to it. */ +\& + s = posix_spawnattr_init(&attr); + if (s != 0) + errExitEN(s, "posix_spawnattr_init"); + s = posix_spawnattr_setflags(&attr, POSIX_SPAWN_SETSIGMASK); + if (s != 0) + errExitEN(s, "posix_spawnattr_setflags"); +\& + sigfillset(&mask); + s = posix_spawnattr_setsigmask(&attr, &mask); + if (s != 0) + errExitEN(s, "posix_spawnattr_setsigmask"); +\& + attrp = &attr; + break; + } + } +\& + /* Spawn the child. The name of the program to execute and the + command\-line arguments are taken from the command\-line arguments + of this program. The environment of the program execed in the + child is made the same as the parent\[aq]s environment. */ +\& + s = posix_spawnp(&child_pid, argv[optind], file_actionsp, attrp, + &argv[optind], environ); + if (s != 0) + errExitEN(s, "posix_spawn"); +\& + /* Destroy any objects that we created earlier. */ +\& + if (attrp != NULL) { + s = posix_spawnattr_destroy(attrp); + if (s != 0) + errExitEN(s, "posix_spawnattr_destroy"); + } +\& + if (file_actionsp != NULL) { + s = posix_spawn_file_actions_destroy(file_actionsp); + if (s != 0) + errExitEN(s, "posix_spawn_file_actions_destroy"); + } +\& + printf("PID of child: %jd\en", (intmax_t) child_pid); +\& + /* Monitor status of the child until it terminates. */ +\& + do { + s = waitpid(child_pid, &status, WUNTRACED | WCONTINUED); + if (s == \-1) + errExit("waitpid"); +\& + printf("Child status: "); + if (WIFEXITED(status)) { + printf("exited, status=%d\en", WEXITSTATUS(status)); + } else if (WIFSIGNALED(status)) { + printf("killed by signal %d\en", WTERMSIG(status)); + } else if (WIFSTOPPED(status)) { + printf("stopped by signal %d\en", WSTOPSIG(status)); + } else if (WIFCONTINUED(status)) { + printf("continued\en"); + } + } while (!WIFEXITED(status) && !WIFSIGNALED(status)); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.nh \" Disable hyphenation +.ad l +.BR close (2), +.BR dup2 (2), +.BR execl (2), +.BR execlp (2), +.BR fork (2), +.BR open (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR setpgid (2), +.BR setuid (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR posix_spawn_file_actions_addclose (3), +.BR posix_spawn_file_actions_adddup2 (3), +.BR posix_spawn_file_actions_addopen (3), +.BR posix_spawn_file_actions_destroy (3), +.BR posix_spawn_file_actions_init (3), +.BR posix_spawnattr_destroy (3), +.BR posix_spawnattr_getflags (3), +.BR posix_spawnattr_getpgroup (3), +.BR posix_spawnattr_getschedparam (3), +.BR posix_spawnattr_getschedpolicy (3), +.BR posix_spawnattr_getsigdefault (3), +.BR posix_spawnattr_getsigmask (3), +.BR posix_spawnattr_init (3), +.BR posix_spawnattr_setflags (3), +.BR posix_spawnattr_setpgroup (3), +.BR posix_spawnattr_setschedparam (3), +.BR posix_spawnattr_setschedpolicy (3), +.BR posix_spawnattr_setsigdefault (3), +.BR posix_spawnattr_setsigmask (3), +.BR pthread_atfork (3), +.IR , +Base Definitions volume of POSIX.1-2001, +.I http://www.opengroup.org/unix/online.html diff --git a/man/man3/posix_spawnp.3 b/man/man3/posix_spawnp.3 new file mode 100644 index 0000000..a6f49d0 --- /dev/null +++ b/man/man3/posix_spawnp.3 @@ -0,0 +1 @@ +.so man3/posix_spawn.3 diff --git a/man/man3/pow.3 b/man/man3/pow.3 new file mode 100644 index 0000000..6c252cd --- /dev/null +++ b/man/man3/pow.3 @@ -0,0 +1,383 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-08-14 by Arnt Gulbrandsen +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH pow 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pow, powf, powl \- power functions +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double pow(double " x ", double " y ); +.BI "float powf(float " x ", float " y ); +.BI "long double powl(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR powf (), +.BR powl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the value of +.I x +raised to the +power of +.IR y . +.SH RETURN VALUE +On success, these functions return the value of +.I x +to the power of +.IR y . +.P +If the result overflows, +a range error occurs, +.\" The range error is generated at least as far back as glibc 2.4 +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the mathematically correct sign. +.P +If result underflows, and is not representable, +a range error occurs, +and 0.0 with the appropriate sign is returned. +.\" POSIX.1 does not specify the sign of the zero, +.\" but https://www.sourceware.org/bugzilla/show_bug.cgi?id=2678 +.\" points out that the zero has the wrong sign in some cases. +.P +.\" pow(\(+-0, <0 [[odd]]) = HUGE_VAL* +If +.I x +is +0 or \-0, +and +.I y +is an odd integer less than 0, +a pole error occurs and +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +is returned, +with the same sign as +.IR x . +.P +.\" pow(\(+-0, <0 [[!odd]]) = HUGE_VAL* +If +.I x +is +0 or \-0, +and +.I y +is less than 0 and not an odd integer, +a pole error occurs and +.\" The pole error is generated at least as far back as glibc 2.4 +.RB + HUGE_VAL , +.RB + HUGE_VALF , +or +.RB + HUGE_VALL , +is returned. +.P +.\" pow(\(+-0, >0 [[odd]]) = \(+-0 +If +.I x +is +0 (\-0), +and +.I y +is an odd integer greater than 0, +the result is +0 (\-0). +.P +.\" pow(\(+-0, >0 [[!odd]]) = +0 +If +.I x +is 0, +and +.I y +greater than 0 and not an odd integer, +the result is +0. +.P +.\" pow(-1, \(+-INFINITY) = 1.0 +If +.I x +is \-1, +and +.I y +is positive infinity or negative infinity, +the result is 1.0. +.P +.\" pow(+1, y) = 1.0 +If +.I x +is +1, the result is 1.0 (even if +.I y +is a NaN). +.P +.\" pow(x, \(+-0) = 1.0 +If +.I y +is 0, the result is 1.0 (even if +.I x +is a NaN). +.P +.\" pow(<0, y) = NaN +If +.I x +is a finite value less than 0, and +.I y +is a finite noninteger, a domain error occurs, +.\" The domain error is generated at least as far back as glibc 2.4 +and a NaN is returned. +.P +.\" pow(|x|<1, -INFINITY) = INFINITY +If the absolute value of +.I x +is less than 1, +and +.I y +is negative infinity, +the result is positive infinity. +.P +.\" pow(|x|>1, -INFINITY) = +0 +If the absolute value of +.I x +is greater than 1, +and +.I y +is negative infinity, +the result is +0. +.P +.\" pow(|x|<1, INFINITY) = +0 +If the absolute value of +.I x +is less than 1, +and +.I y +is positive infinity, +the result is +0. +.P +.\" pow(|x|>1, INFINITY) = INFINITY +If the absolute value of +.I x +is greater than 1, +and +.I y +is positive infinity, +the result is positive infinity. +.P +.\" pow(-INFINITY, <0 [[odd]]) = -0 +If +.I x +is negative infinity, +and +.I y +is an odd integer less than 0, +the result is \-0. +.P +.\" pow(-INFINITY, <0 [[!odd]]) = +0 +If +.I x +is negative infinity, +and +.I y +less than 0 and not an odd integer, +the result is +0. +.P +.\" pow(-INFINITY, >0 [[odd]]) = -INFINITY +If +.I x +is negative infinity, +and +.I y +is an odd integer greater than 0, +the result is negative infinity. +.P +.\" pow(-INFINITY, >0 [[!odd]]) = INFINITY +If +.I x +is negative infinity, +and +.I y +greater than 0 and not an odd integer, +the result is positive infinity. +.P +.\" pow(INFINITY, <0) = +0 +If +.I x +is positive infinity, +and +.I y +less than 0, +the result is +0. +.P +.\" pow(INFINITY, >0) = INFINITY +If +.I x +is positive infinity, +and +.I y +greater than 0, +the result is positive infinity. +.P +.\" pow(NaN, y) or pow(x, NaN) = NaN +Except as specified above, if +.I x +or +.I y +is a NaN, the result is a NaN. +.SH ERRORS +.\" FIXME . review status of this error +.\" longstanding bug report for glibc: +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=369 +.\" For negative x, and -large and +large y, glibc 2.8 gives incorrect +.\" results +.\" pow(-0.5,-DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF) +.\" +.\" pow(-1.5,-DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0) +.\" +.\" pow(-0.5,DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0) +.\" +.\" pow(-1.5,DBL_MAX)=nan +.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result; +.\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF) +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is negative, and \fIy\fP is a finite noninteger +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is zero, and \fIy\fP is negative +.I errno +is set to +.B ERANGE +(but see BUGS). +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.TP +Range error: the result overflows +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error: the result underflows +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pow (), +.BR powf (), +.BR powl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +.SS Historical bugs (now fixed) +Before glibc 2.28, +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=13932 +on some architectures (e.g., x86-64) +.BR pow () +may be more than 10,000 times slower for some inputs +than for other nearby inputs. +This affects only +.BR pow (), +and not +.BR powf () +nor +.BR powl (). +This problem was fixed +.\" commit c3d466cba1692708a19c6ff829d0386c83a0c6e5 +in glibc 2.28. +.P +A number of bugs +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=3866 +in the glibc implementation of +.BR pow () +were fixed in glibc 2.16. +.P +In glibc 2.9 and earlier, +.\" +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6776 +when a pole error occurs, +.I errno +is set to +.B EDOM +instead of the POSIX-mandated +.BR ERANGE . +Since glibc 2.10, +.\" or possibly 2.9, I haven't found the source code change +.\" and I don't have a 2.9 system to test +glibc does the right thing. +.P +In glibc 2.3.2 and earlier, +.\" Actually, glibc 2.3.2 is the earliest test result I have; so yet +.\" to confirm if this error occurs only in glibc 2.3.2. +when an overflow or underflow error occurs, glibc's +.BR pow () +generates a bogus invalid floating-point exception +.RB ( FE_INVALID ) +in addition to the overflow or underflow exception. +.SH SEE ALSO +.BR cbrt (3), +.BR cpow (3), +.BR sqrt (3) diff --git a/man/man3/pow10.3 b/man/man3/pow10.3 new file mode 100644 index 0000000..b8c9bc6 --- /dev/null +++ b/man/man3/pow10.3 @@ -0,0 +1,56 @@ +'\" t +.\" Copyright 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pow10 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pow10, pow10f, pow10l \- base-10 power functions +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "double pow10(double " x ); +.BI "float pow10f(float " x ); +.BI "long double pow10l(long double " x ); +.fi +.SH DESCRIPTION +These functions return the value of 10 raised to the power +.IR x . +.P +.BR "Note well" : +These functions perform exactly the same task as the functions described in +.BR exp10 (3), +with the difference that the latter functions are now standardized +in TS\ 18661-4:2015. +Those latter functions should be used in preference +to the functions described in this page. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pow10 (), +.BR pow10f (), +.BR pow10l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH VERSIONS +glibc 2.1. +Removed in glibc 2.27. +.\" glibc commit 5a80d39d0d2587e9bd8e72f19e92eeb2a66fbe9e +.SH SEE ALSO +.BR exp10 (3), +.BR pow (3) diff --git a/man/man3/pow10f.3 b/man/man3/pow10f.3 new file mode 100644 index 0000000..8a71580 --- /dev/null +++ b/man/man3/pow10f.3 @@ -0,0 +1 @@ +.so man3/pow10.3 diff --git a/man/man3/pow10l.3 b/man/man3/pow10l.3 new file mode 100644 index 0000000..8a71580 --- /dev/null +++ b/man/man3/pow10l.3 @@ -0,0 +1 @@ +.so man3/pow10.3 diff --git a/man/man3/powerof2.3 b/man/man3/powerof2.3 new file mode 100644 index 0000000..c6e82d4 --- /dev/null +++ b/man/man3/powerof2.3 @@ -0,0 +1,46 @@ +.\" Copyright (C) 2022 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH powerof2 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +powerof2 \- test if a value is a power of 2 +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int powerof2(" x ); +.fi +.SH DESCRIPTION +This macro returns true if +.I x +is a power of 2, +and false otherwise. +.P +.B 0 +is considered a power of 2. +This can make sense considering wrapping of unsigned integers, +and has interesting properties. +.SH RETURN VALUE +True or false, +if +.I x +is a power of 2 or not, +respectively. +.SH STANDARDS +BSD. +.SH CAVEATS +The arguments may be evaluated more than once. +.P +Because this macro is implemented using bitwise operations, +some negative values can invoke undefined behavior. +For example, +the following invokes undefined behavior: +.IR "powerof2(INT_MIN);". +Call it only with unsigned types to be safe. +.SH SEE ALSO +.BR stdc_bit_ceil (3), +.BR stdc_bit_floor (3) diff --git a/man/man3/powf.3 b/man/man3/powf.3 new file mode 100644 index 0000000..63da756 --- /dev/null +++ b/man/man3/powf.3 @@ -0,0 +1 @@ +.so man3/pow.3 diff --git a/man/man3/powl.3 b/man/man3/powl.3 new file mode 100644 index 0000000..63da756 --- /dev/null +++ b/man/man3/powl.3 @@ -0,0 +1 @@ +.so man3/pow.3 diff --git a/man/man3/printf.3 b/man/man3/printf.3 new file mode 100644 index 0000000..7023e2d --- /dev/null +++ b/man/man3/printf.3 @@ -0,0 +1,1239 @@ +'\" t +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" Earlier versions of this page influenced the present text. +.\" It was derived from a Berkeley page with version +.\" @(#)printf.3 6.14 (Berkeley) 7/30/91 +.\" converted for Linux by faith@cs.unc.edu, updated by +.\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99. +.\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes +.\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes +.\" +.TH printf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, +vsprintf, vsnprintf \- formatted output conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int printf(const char *restrict " format ", ...);" +.BI "int fprintf(FILE *restrict " stream , +.BI " const char *restrict " format ", ...);" +.BI "int dprintf(int " fd , +.BI " const char *restrict " format ", ...);" +.BI "int sprintf(char *restrict " str , +.BI " const char *restrict " format ", ...);" +.BI "int snprintf(char " str "[restrict ." size "], size_t " size , +.BI " const char *restrict " format ", ...);" +.P +.BI "int vprintf(const char *restrict " format ", va_list " ap ); +.BI "int vfprintf(FILE *restrict " stream , +.BI " const char *restrict " format ", va_list " ap ); +.BI "int vdprintf(int " fd , +.BI " const char *restrict " format ", va_list " ap ); +.BI "int vsprintf(char *restrict " str , +.BI " const char *restrict " format ", va_list " ap ); +.BI "int vsnprintf(char " str "[restrict ." size "], size_t " size , +.BI " const char *restrict " format ", va_list " ap ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR snprintf (), +.BR vsnprintf (): +.nf + _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.P +.BR dprintf (), +.BR vdprintf (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The functions in the +.BR printf () +family produce output according to a +.I format +as described below. +The functions +.BR printf () +and +.BR vprintf () +write output to +.IR stdout , +the standard output stream; +.BR fprintf () +and +.BR vfprintf () +write output to the given output +.IR stream ; +.BR sprintf (), +.BR snprintf (), +.BR vsprintf (), +and +.BR vsnprintf () +write to the character string +.IR str . +.P +The function +.BR dprintf () +is the same as +.BR fprintf () +except that it outputs to a file descriptor, +.IR fd , +instead of to a +.BR stdio (3) +stream. +.P +The functions +.BR snprintf () +and +.BR vsnprintf () +write at most +.I size +bytes (including the terminating null byte (\[aq]\e0\[aq])) to +.IR str . +.P +The functions +.BR vprintf (), +.BR vfprintf (), +.BR vdprintf (), +.BR vsprintf (), +.BR vsnprintf () +are equivalent to the functions +.BR printf (), +.BR fprintf (), +.BR dprintf (), +.BR sprintf (), +.BR snprintf (), +respectively, except that they are called with a +.I va_list +instead of a variable number of arguments. +These functions do not call the +.I va_end +macro. +Because they invoke the +.I va_arg +macro, the value of +.I ap +is undefined after the call. +See +.BR stdarg (3). +.P +All of these functions write the output under the control of a +.I format +string that specifies how subsequent arguments (or arguments accessed via +the variable-length argument facilities of +.BR stdarg (3)) +are converted for output. +.P +C99 and POSIX.1-2001 specify that the results are undefined if a call to +.BR sprintf (), +.BR snprintf (), +.BR vsprintf (), +or +.BR vsnprintf () +would cause copying to take place between objects that overlap +(e.g., if the target string array and one of the supplied input arguments +refer to the same buffer). +See CAVEATS. +.SS Format of the format string +The format string is a character string, beginning and ending +in its initial shift state, if any. +The format string is composed of zero or more directives: ordinary +characters (not +.BR % ), +which are copied unchanged to the output stream; +and conversion specifications, each of which results in fetching zero or +more subsequent arguments. +Each conversion specification is introduced by +the character +.BR % , +and ends with a +.IR "conversion specifier" . +In between there may be (in this order) zero or more +.IR flags , +an optional minimum +.IR "field width" , +an optional +.I precision +and an optional +.IR "length modifier" . +.P +The overall syntax of a conversion specification is: +.P +.in +4n +.nf +%[$][flags][width][.precision][length modifier]conversion +.fi +.in +.P +The arguments must correspond properly (after type promotion) with the +conversion specifier. +By default, the arguments are used in the order +given, where each \[aq]*\[aq] (see +.I "Field width" +and +.I Precision +below) and each conversion specifier asks for the next +argument (and it is an error if insufficiently many arguments are given). +One can also specify explicitly which argument is taken, +at each place where an argument is required, by writing "%m$" instead +of \[aq]%\[aq] and "*m$" instead of \[aq]*\[aq], +where the decimal integer \fIm\fP denotes +the position in the argument list of the desired argument, indexed starting +from 1. +Thus, +.P +.in +4n +.EX +printf("%*d", width, num); +.EE +.in +.P +and +.P +.in +4n +.EX +printf("%2$*1$d", width, num); +.EE +.in +.P +are equivalent. +The second style allows repeated references to the +same argument. +The C99 standard does not include the style using \[aq]$\[aq], +which comes from the Single UNIX Specification. +If the style using +\[aq]$\[aq] is used, it must be used throughout for all conversions taking an +argument and all width and precision arguments, but it may be mixed +with "%%" formats, which do not consume an argument. +There may be no +gaps in the numbers of arguments specified using \[aq]$\[aq]; for example, if +arguments 1 and 3 are specified, argument 2 must also be specified +somewhere in the format string. +.P +For some numeric conversions a radix character ("decimal point") or +thousands' grouping character is used. +The actual character used +depends on the +.B LC_NUMERIC +part of the locale. +(See +.BR setlocale (3).) +The POSIX locale +uses \[aq].\[aq] as radix character, and does not have a grouping character. +Thus, +.P +.in +4n +.EX +printf("%\[aq].2f", 1234567.89); +.EE +.in +.P +results in "1234567.89" in the POSIX locale, in "1234567,89" in the +nl_NL locale, and in "1.234.567,89" in the da_DK locale. +.SS Flag characters +The character % is followed by zero or more of the following flags: +.TP +.B # +The value should be converted to an "alternate form". +For +.B o +conversions, the first character of the output string is made zero +(by prefixing a 0 if it was not zero already). +For +.B x +and +.B X +conversions, a nonzero result has the string "0x" (or "0X" for +.B X +conversions) prepended to it. +For +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.B G +conversions, the result will always contain a decimal point, even if no +digits follow it (normally, a decimal point appears in the results of those +conversions only if a digit follows). +For +.B g +and +.B G +conversions, trailing zeros are not removed from the result as they would +otherwise be. +For +.BR m , +if +.I errno +contains a valid error code, +the output of +.I strerrorname_np(errno) +is printed; +otherwise, the value stored in +.I errno +is printed as a decimal number. +For other conversions, the result is undefined. +.TP +.B \&0 +The value should be zero padded. +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.B G +conversions, the converted value is padded on the left with zeros rather +than blanks. +If the +.B \&0 +and +.B \- +flags both appear, the +.B \&0 +flag is ignored. +If a precision is given with an integer conversion +.RB ( d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X ), +the +.B \&0 +flag is ignored. +For other conversions, the behavior is undefined. +.TP +.B \- +The converted value is to be left adjusted on the field boundary. +(The default is right justification.) +The converted value is padded on the right with blanks, rather +than on the left with blanks or zeros. +A +.B \- +overrides a +.B \&0 +if both are given. +.TP +.B \[aq] \[aq] +(a space) A blank should be left before a positive number +(or empty string) produced by a signed conversion. +.TP +.B + +A sign (+ or \-) should always be placed before a number produced by a signed +conversion. +By default, a sign is used only for negative numbers. +A +.B + +overrides a space if both are used. +.P +The five flag characters above are defined in the C99 standard. +The Single UNIX Specification specifies one further flag character. +.TP +.B \[aq] +For decimal conversion +.RB ( i , +.BR d , +.BR u , +.BR f , +.BR F , +.BR g , +.BR G ) +the output is to be grouped with thousands' grouping characters +if the locale information indicates any. +(See +.BR setlocale (3).) +Note that many versions of +.BR gcc (1) +cannot parse this option and will issue a warning. +(SUSv2 did not +include \fI%\[aq]F\fP, but SUSv3 added it.) +Note also that the default locale of a C program is "C" +whose locale information indicates no thousands' grouping character. +Therefore, without a prior call to +.BR setlocale (3), +no thousands' grouping characters will be printed. +.P +glibc 2.2 adds one further flag character. +.TP +.B I +For decimal integer conversion +.RB ( i , +.BR d , +.BR u ) +the output uses the locale's alternative output digits, if any. +For example, since glibc 2.2.3 this will give Arabic-Indic digits +in the Persian ("fa_IR") locale. +.\" outdigits keyword in locale file +.SS Field width +An optional decimal digit string (with nonzero first digit) specifying +a minimum field width. +If the converted value has fewer characters +than the field width, it will be padded with spaces on the left +(or right, if the left-adjustment flag has been given). +Instead of a decimal digit string one may write "*" or "*m$" +(for some decimal integer \fIm\fP) to specify that the field width +is given in the next argument, or in the \fIm\fP-th argument, respectively, +which must be of type +.IR int . +A negative field width is taken as a \[aq]\-\[aq] flag followed by a +positive field width. +In no case does a nonexistent or small field width cause truncation of a +field; if the result of a conversion is wider than the field width, the +field is expanded to contain the conversion result. +.SS Precision +An optional precision, in the form of a period (\[aq].\[aq]) followed by an +optional decimal digit string. +Instead of a decimal digit string one may write "*" or "*m$" +(for some decimal integer \fIm\fP) to specify that the precision +is given in the next argument, or in the \fIm\fP-th argument, respectively, +which must be of type +.IR int . +If the precision is given as just \[aq].\[aq], the precision is taken to +be zero. +A negative precision is taken as if the precision were omitted. +This gives the minimum number of digits to appear for +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.B X +conversions, the number of digits to appear after the radix character for +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +and +.B F +conversions, the maximum number of significant digits for +.B g +and +.B G +conversions, or the maximum number of characters to be printed from a +string for +.B s +and +.B S +conversions. +.SS Length modifier +Here, "integer conversion" stands for +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.B X +conversion. +.TP +.B hh +A following integer conversion corresponds to a +.I signed char +or +.I unsigned char +argument, or a following +.B n +conversion corresponds to a pointer to a +.I signed char +argument. +.TP +.B h +A following integer conversion corresponds to a +.I short +or +.I unsigned short +argument, or a following +.B n +conversion corresponds to a pointer to a +.I short +argument. +.TP +.B l +(ell) A following integer conversion corresponds to a +.I long +or +.I unsigned long +argument, or a following +.B n +conversion corresponds to a pointer to a +.I long +argument, or a following +.B c +conversion corresponds to a +.I wint_t +argument, or a following +.B s +conversion corresponds to a pointer to +.I wchar_t +argument. +On a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.B G +conversion, this length modifier is ignored (C99; not in SUSv2). +.TP +.B ll +(ell-ell). +A following integer conversion corresponds to a +.I long long +or +.I unsigned long long +argument, or a following +.B n +conversion corresponds to a pointer to a +.I long long +argument. +.TP +.B q +A synonym for +.BR ll . +This is a nonstandard extension, derived from BSD; +avoid its use in new code. +.TP +.B L +A following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.B G +conversion corresponds to a +.I long double +argument. +(C99 allows %LF, but SUSv2 does not.) +.TP +.B j +A following integer conversion corresponds to an +.I intmax_t +or +.I uintmax_t +argument, or a following +.B n +conversion corresponds to a pointer to an +.I intmax_t +argument. +.TP +.B z +A following integer conversion corresponds to a +.I size_t +or +.I ssize_t +argument, or a following +.B n +conversion corresponds to a pointer to a +.I size_t +argument. +.TP +.B Z +A nonstandard synonym for +.B z +that predates the appearance of +.BR z . +Do not use in new code. +.TP +.B t +A following integer conversion corresponds to a +.I ptrdiff_t +argument, or a following +.B n +conversion corresponds to a pointer to a +.I ptrdiff_t +argument. +.P +SUSv3 specifies all of the above, +except for those modifiers explicitly noted as being nonstandard extensions. +SUSv2 specified only the length modifiers +.B h +(in +.BR hd , +.BR hi , +.BR ho , +.BR hx , +.BR hX , +.BR hn ) +and +.B l +(in +.BR ld , +.BR li , +.BR lo , +.BR lx , +.BR lX , +.BR ln , +.BR lc , +.BR ls ) +and +.B L +(in +.BR Le , +.BR LE , +.BR Lf , +.BR Lg , +.BR LG ). +.P +As a nonstandard extension, the GNU implementations treats +.B ll +and +.B L +as synonyms, so that one can, for example, write +.B llg +(as a synonym for the standards-compliant +.BR Lg ) +and +.B Ld +(as a synonym for the standards compliant +.BR lld ). +Such usage is nonportable. +.\" +.SS Conversion specifiers +A character that specifies the type of conversion to be applied. +The conversion specifiers and their meanings are: +.TP +.BR d ", " i +The +.I int +argument is converted to signed decimal notation. +The precision, if any, gives the minimum number of digits +that must appear; if the converted value requires fewer digits, it is +padded on the left with zeros. +The default precision is 1. +When 0 is printed with an explicit precision 0, the output is empty. +.TP +.BR o ", " u ", " x ", " X +The +.I "unsigned int" +argument is converted to unsigned octal +.RB ( o ), +unsigned decimal +.RB ( u ), +or unsigned hexadecimal +.RB ( x +and +.BR X ) +notation. +The letters +.B abcdef +are used for +.B x +conversions; the letters +.B ABCDEF +are used for +.B X +conversions. +The precision, if any, gives the minimum number of digits +that must appear; if the converted value requires fewer digits, it is +padded on the left with zeros. +The default precision is 1. +When 0 is printed with an explicit precision 0, the output is empty. +.TP +.BR e ", " E +The +.I double +argument is rounded and converted in the style +.RB [\-]d \&. ddd e \(+-dd +where there is one digit (which is nonzero if the argument is nonzero) +before the decimal-point character and the number +of digits after it is equal to the precision; if the precision is missing, +it is taken as 6; if the precision is zero, no decimal-point character +appears. +An +.B E +conversion uses the letter +.B E +(rather than +.BR e ) +to introduce the exponent. +The exponent always contains at least two +digits; if the value is zero, the exponent is 00. +.TP +.BR f ", " F +The +.I double +argument is rounded and converted to decimal notation in the style +.RB [\-]ddd \&. ddd, +where the number of digits after the decimal-point character is equal to +the precision specification. +If the precision is missing, it is taken as +6; if the precision is explicitly zero, no decimal-point character appears. +If a decimal point appears, at least one digit appears before it. +.IP +(SUSv2 does not know about +.B F +and says that character string representations for infinity and NaN +may be made available. +SUSv3 adds a specification for +.BR F . +The C99 standard specifies "[\-]inf" or "[\-]infinity" +for infinity, and a string starting with "nan" for NaN, in the case of +.B f +conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of +.B F +conversion.) +.TP +.BR g ", " G +The +.I double +argument is converted in style +.B f +or +.B e +(or +.B F +or +.B E +for +.B G +conversions). +The precision specifies the number of significant digits. +If the precision is missing, 6 digits are given; if the precision is zero, +it is treated as 1. +Style +.B e +is used if the exponent from its conversion is less than \-4 or greater +than or equal to the precision. +Trailing zeros are removed from the +fractional part of the result; a decimal point appears only if it is +followed by at least one digit. +.TP +.BR a ", " A +(C99; not in SUSv2, but added in SUSv3) +For +.B a +conversion, the +.I double +argument is converted to hexadecimal notation (using the letters abcdef) +in the style +.RB [\-] 0x h \&. hhhh p \(+-d; +for +.B A +conversion the prefix +.BR 0X , +the letters ABCDEF, and the exponent separator +.B P +is used. +There is one hexadecimal digit before the decimal point, +and the number of digits after it is equal to the precision. +The default precision suffices for an exact representation of the value +if an exact representation in base 2 exists +and otherwise is sufficiently large to distinguish values of type +.IR double . +The digit before the decimal point is unspecified for nonnormalized +numbers, and nonzero but otherwise unspecified for normalized numbers. +The exponent always contains at least one +digit; if the value is zero, the exponent is 0. +.TP +.B c +If no +.B l +modifier is present, the +.I int +argument is converted to an +.IR "unsigned char" , +and the resulting character is written. +If an +.B l +modifier is present, the +.I wint_t +(wide character) argument is converted to a multibyte sequence by a call +to the +.BR wcrtomb (3) +function, with a conversion state starting in the initial state, and the +resulting multibyte string is written. +.TP +.B s +If no +.B l +modifier is present: the +.I "const char\ *" +argument is expected to be a pointer to an array of character type (pointer +to a string). +Characters from the array are written up to (but not +including) a terminating null byte (\[aq]\e0\[aq]); +if a precision is specified, no more than the number specified +are written. +If a precision is given, no null byte need be present; +if the precision is not specified, or is greater than the size of the +array, the array must contain a terminating null byte. +.IP +If an +.B l +modifier is present: the +.I "const wchar_t\ *" +argument is expected to be a pointer to an array of wide characters. +Wide characters from the array are converted to multibyte characters +(each by a call to the +.BR wcrtomb (3) +function, with a conversion state starting in the initial state before +the first wide character), up to and including a terminating null +wide character. +The resulting multibyte characters are written up to +(but not including) the terminating null byte. +If a precision is +specified, no more bytes than the number specified are written, but +no partial multibyte characters are written. +Note that the precision +determines the number of +.I bytes +written, not the number of +.I wide characters +or +.IR "screen positions" . +The array must contain a terminating null wide character, unless a +precision is given and it is so small that the number of bytes written +exceeds it before the end of the array is reached. +.TP +.B C +(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) +Synonym for +.BR lc . +Don't use. +.TP +.B S +(Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) +Synonym for +.BR ls . +Don't use. +.TP +.B p +The +.I "void\ *" +pointer argument is printed in hexadecimal (as if by +.B %#x +or +.BR %#lx ). +.TP +.B n +The number of characters written so far is stored into the integer +pointed to by the corresponding argument. +That argument shall be an +.IR "int\ *" , +or variant whose size matches the (optionally) +supplied integer length modifier. +No argument is converted. +(This specifier is not supported by the bionic C library.) +The behavior is undefined if the conversion specification includes +any flags, a field width, or a precision. +.TP +.B m +(glibc extension; supported by uClibc and musl.) +Print output of +.I strerror(errno) +(or +.I strerrorname_np(errno) +in the alternate form). +No argument is required. +.TP +.B % +A \[aq]%\[aq] is written. +No argument is converted. +The complete conversion +specification is \[aq]%%\[aq]. +.SH RETURN VALUE +Upon successful return, these functions return the number of bytes +printed (excluding the null byte used to end output to strings). +.P +The functions +.BR snprintf () +and +.BR vsnprintf () +do not write more than +.I size +bytes (including the terminating null byte (\[aq]\e0\[aq])). +If the output was truncated due to this limit, then the return value +is the number of characters (excluding the terminating null byte) +which would have been written to the final string if enough space +had been available. +Thus, a return value of +.I size +or more means that the output was truncated. +(See also below under CAVEATS.) +.P +If an output error is encountered, a negative value is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR printf (), +.BR fprintf (), +.BR sprintf (), +.BR snprintf (), +.BR vprintf (), +.BR vfprintf (), +.BR vsprintf (), +.BR vsnprintf () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +.TP +.BR fprintf () +.TQ +.BR printf () +.TQ +.BR sprintf () +.TQ +.BR vprintf () +.TQ +.BR vfprintf () +.TQ +.BR vsprintf () +.TQ +.BR snprintf () +.TQ +.BR vsnprintf () +C11, POSIX.1-2008. +.TP +.BR dprintf () +.TQ +.BR vdprintf () +GNU, POSIX.1-2008. +.SH HISTORY +.TP +.BR fprintf () +.TQ +.BR printf () +.TQ +.BR sprintf () +.TQ +.BR vprintf () +.TQ +.BR vfprintf () +.TQ +.BR vsprintf () +C89, POSIX.1-2001. +.TP +.BR snprintf () +.TQ +.BR vsnprintf () +SUSv2, C99, POSIX.1-2001. +.IP +Concerning the return value of +.BR snprintf (), +SUSv2 and C99 contradict each other: when +.BR snprintf () +is called with +.IR size =0 +then SUSv2 stipulates an unspecified return value less than 1, +while C99 allows +.I str +to be NULL in this case, and gives the return value (as always) +as the number of characters that would have been written in case +the output string has been large enough. +POSIX.1-2001 and later align their specification of +.BR snprintf () +with C99. +.TP +.BR dprintf () +.TQ +.BR vdprintf () +GNU, POSIX.1-2008. +.P +.\" Linux libc4 knows about the five C standard flags. +.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, +.\" and the conversions +.\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, +.\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP, +.\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP, +.\" where \fBF\fP is a synonym for \fBf\fP. +.\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms +.\" for \fBld\fP, \fBlo\fP, and \fBlu\fP. +.\" (This is bad, and caused serious bugs later, when +.\" support for \fB%D\fP disappeared.) +.\" No locale-dependent radix character, +.\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$". +.\" .P +.\" Linux libc5 knows about the five C standard flags and the \[aq] flag, +.\" locale, "%m$" and "*m$". +.\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, +.\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP +.\" both for \fIlong double\fP and for \fIlong long\fP (this is a bug). +.\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP, +.\" but adds the conversion character +.\" .BR m , +.\" which outputs +.\" .IR strerror(errno) . +.\" .P +.\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP. +.\" .P +glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP +and conversion characters \fBa\fP and \fBA\fP. +.P +glibc 2.2 adds the conversion character \fBF\fP with C99 semantics, +and the flag character \fBI\fP. +.P +glibc 2.35 gives a meaning to the alternate form +.RB ( # ) +of the +.B m +conversion specifier, that is +.IR %#m . +.SH CAVEATS +Some programs imprudently rely on code such as the following +.P +.in +4n +.EX +sprintf(buf, "%s some further text", buf); +.EE +.in +.P +to append text to +.IR buf . +However, the standards explicitly note that the results are undefined +if source and destination buffers overlap when calling +.BR sprintf (), +.BR snprintf (), +.BR vsprintf (), +and +.BR vsnprintf (). +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7075 +Depending on the version of +.BR gcc (1) +used, and the compiler options employed, calls such as the above will +.B not +produce the expected results. +.P +The glibc implementation of the functions +.BR snprintf () +and +.BR vsnprintf () +conforms to the C99 standard, that is, behaves as described above, +since glibc 2.1. +Until glibc 2.0.6, they would return \-1 +when the output was truncated. +.\" .SH HISTORY +.\" UNIX V7 defines the three routines +.\" .BR printf (), +.\" .BR fprintf (), +.\" .BR sprintf (), +.\" and has the flag \-, the width or precision *, the length modifier l, +.\" and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx. +.\" This is still true for 2.9.1BSD, but 2.10BSD has the flags +.\" #, + and and no longer mentions D,O,U,X. +.\" 2.11BSD has +.\" .BR vprintf (), +.\" .BR vfprintf (), +.\" .BR vsprintf (), +.\" and warns not to use D,O,U,X. +.\" 4.3BSD Reno has the flag 0, the length modifiers h and L, +.\" and the conversions n, p, E, G, X (with current meaning) +.\" and deprecates D,O,U. +.\" 4.4BSD introduces the functions +.\" .BR snprintf () +.\" and +.\" .BR vsnprintf (), +.\" and the length modifier q. +.\" FreeBSD also has functions +.\" .BR asprintf () +.\" and +.\" .BR vasprintf (), +.\" that allocate a buffer large enough for +.\" .BR sprintf (). +.\" In glibc there are functions +.\" .BR dprintf () +.\" and +.\" .BR vdprintf () +.\" that print to a file descriptor instead of a stream. +.SH BUGS +Because +.BR sprintf () +and +.BR vsprintf () +assume an arbitrarily long string, callers must be careful not to overflow +the actual space; this is often impossible to assure. +Note that the length +of the strings produced is locale-dependent and difficult to predict. +Use +.BR snprintf () +and +.BR vsnprintf () +instead (or +.BR asprintf (3) +and +.BR vasprintf (3)). +.\" .P +.\" Linux libc4.[45] does not have a +.\" .BR snprintf (), +.\" but provides a libbsd that contains an +.\" .BR snprintf () +.\" equivalent to +.\" .BR sprintf (), +.\" that is, one that ignores the +.\" .I size +.\" argument. +.\" Thus, the use of +.\" .BR snprintf () +.\" with early libc4 leads to serious security problems. +.P +Code such as +.BI printf( foo ); +often indicates a bug, since +.I foo +may contain a % character. +If +.I foo +comes from untrusted user input, it may contain \fB%n\fP, causing the +.BR printf () +call to write to memory and creating a security hole. +.\" .P +.\" Some floating-point conversions under early libc4 +.\" caused memory leaks. +.SH EXAMPLES +To print +.I Pi +to five decimal places: +.P +.in +4n +.EX +#include +#include +fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); +.EE +.in +.P +To print a date and time in the form "Sunday, July 3, 10:02", +where +.I weekday +and +.I month +are pointers to strings: +.P +.in +4n +.EX +#include +fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", + weekday, month, day, hour, min); +.EE +.in +.P +Many countries use the day-month-year order. +Hence, an internationalized version must be able to print +the arguments in an order specified by the format: +.P +.in +4n +.EX +#include +fprintf(stdout, format, + weekday, month, day, hour, min); +.EE +.in +.P +where +.I format +depends on locale, and may permute the arguments. +With the value: +.P +.in +4n +.EX +"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.EE +.in +.P +one might obtain "Sonntag, 3. Juli, 10:02". +.P +To allocate a sufficiently large string and print into it +(code correct for both glibc 2.0 and glibc 2.1): +.P +.EX +#include +#include +#include +\& +char * +make_message(const char *fmt, ...) +{ + int n = 0; + size_t size = 0; + char *p = NULL; + va_list ap; +\& + /* Determine required size. */ +\& + va_start(ap, fmt); + n = vsnprintf(p, size, fmt, ap); + va_end(ap); +\& + if (n < 0) + return NULL; +\& + size = (size_t) n + 1; /* One extra byte for \[aq]\e0\[aq] */ + p = malloc(size); + if (p == NULL) + return NULL; +\& + va_start(ap, fmt); + n = vsnprintf(p, size, fmt, ap); + va_end(ap); +\& + if (n < 0) { + free(p); + return NULL; + } +\& + return p; +} +.EE +.P +If truncation occurs in glibc versions prior to glibc 2.0.6, +this is treated as an error instead of being handled gracefully. +.SH SEE ALSO +.BR printf (1), +.BR asprintf (3), +.BR puts (3), +.BR scanf (3), +.BR setlocale (3), +.BR strfromd (3), +.BR wcrtomb (3), +.BR wprintf (3), +.BR locale (5) diff --git a/man/man3/profil.3 b/man/man3/profil.3 new file mode 100644 index 0000000..d4773c3 --- /dev/null +++ b/man/man3/profil.3 @@ -0,0 +1,94 @@ +'\" t +.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Fri Jun 23 01:35:19 1995 Andries Brouwer +.\" (prompted by Bas V. de Bakker ) +.\" Corrected (and moved to man3), 980612, aeb +.TH profil 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +profil \- execution time profile +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int profil(unsigned short *" buf ", size_t " bufsiz , +.BI " size_t " offset ", unsigned int " scale ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR profil (): +.nf + Since glibc 2.21: +.\" commit 266865c0e7b79d4196e2cc393693463f03c90bd8 + _DEFAULT_SOURCE + In glibc 2.19 and 2.20: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + Up to and including glibc 2.19: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +This routine provides a means to find out in what areas your program +spends most of its time. +The argument +.I buf +points to +.I bufsiz +bytes of core. +Every virtual 10 milliseconds, the user's program counter (PC) +is examined: +.I offset +is subtracted and the result is multiplied by +.I scale +and divided by 65536. +If the resulting value is less than +.IR bufsiz , +then the corresponding entry in +.I buf +is incremented. +If +.I buf +is NULL, profiling is disabled. +.SH RETURN VALUE +Zero is always returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR profil () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +None. +.SH HISTORY +Similar to a call in SVr4. +.SH BUGS +.BR profil () +cannot be used on a program that also uses +.B ITIMER_PROF +interval timers (see +.BR setitimer (2)). +.P +True kernel profiling provides more accurate results. +.\" Libc 4.4 contained a kernel patch providing a system call profil. +.SH SEE ALSO +.BR gprof (1), +.BR sprof (1), +.BR setitimer (2), +.BR sigaction (2), +.BR signal (2) diff --git a/man/man3/program_invocation_name.3 b/man/man3/program_invocation_name.3 new file mode 100644 index 0000000..874420d --- /dev/null +++ b/man/man3/program_invocation_name.3 @@ -0,0 +1,66 @@ +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.TH program_invocation_name 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +program_invocation_name, program_invocation_short_name \- \ +obtain name used to invoke calling program +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "extern char *" program_invocation_name ; +.BI "extern char *" program_invocation_short_name ; +.fi +.SH DESCRIPTION +.I program_invocation_name +contains the name that was used to invoke the calling program. +This is the same as the value of +.I argv[0] +in +.IR main (), +with the difference that the scope of +.I program_invocation_name +is global. +.P +.I program_invocation_short_name +contains the basename component of name that was used to invoke +the calling program. +That is, it is the same value as +.IR program_invocation_name , +with all text up to and including the final slash (/), if any, removed. +.P +These variables are automatically initialized by the glibc run-time +startup code. +.SH VERSIONS +The Linux-specific +.IR /proc/ pid /cmdline +file provides access to similar information. +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man3/program_invocation_short_name.3 b/man/man3/program_invocation_short_name.3 new file mode 100644 index 0000000..f603f6c --- /dev/null +++ b/man/man3/program_invocation_short_name.3 @@ -0,0 +1 @@ +.so man3/program_invocation_name.3 diff --git a/man/man3/psiginfo.3 b/man/man3/psiginfo.3 new file mode 100644 index 0000000..cd748fa --- /dev/null +++ b/man/man3/psiginfo.3 @@ -0,0 +1 @@ +.so man3/psignal.3 diff --git a/man/man3/psignal.3 b/man/man3/psignal.3 new file mode 100644 index 0000000..b453ae7 --- /dev/null +++ b/man/man3/psignal.3 @@ -0,0 +1,114 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:45:17 1993 by Rik Faith (faith@cs.unc.edu) +.TH psignal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +psignal, psiginfo \- print signal description +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void psignal(int " sig ", const char *" s ); +.BI "void psiginfo(const siginfo_t *" pinfo ", const char *" s ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR psignal (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR psiginfo (): +.nf + _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +The +.BR psignal () +function displays a message on \fIstderr\fP +consisting of the string \fIs\fP, a colon, a space, a string +describing the signal number \fIsig\fP, and a trailing newline. +If the string \fIs\fP is NULL or empty, the colon and space are omitted. +If \fIsig\fP is invalid, +the message displayed will indicate an unknown signal. +.P +The +.BR psiginfo () +function is like +.BR psignal (), +except that it displays information about the signal described by +.IR pinfo , +which should point to a valid +.I siginfo_t +structure. +As well as the signal description, +.BR psiginfo () +displays information about the origin of the signal, +and other information relevant to the signal +(e.g., the relevant memory address for hardware-generated signals, +the child process ID for +.BR SIGCHLD , +and the user ID and process ID of the sender, for signals set using +.BR kill (2) +or +.BR sigqueue (3)). +.SH RETURN VALUE +The +.BR psignal () +and +.BR psiginfo () +functions return no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR psignal (), +.BR psiginfo () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.10. +POSIX.1-2008, 4.3BSD. +.SH BUGS +Up to glibc 2.12, +.BR psiginfo () +had the following bugs: +.IP \[bu] 3 +In some circumstances, a trailing newline is not printed. +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12107 +.\" Reportedly now fixed; check glibc 2.13 +.IP \[bu] +Additional details are not displayed for real-time signals. +.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12108 +.\" Reportedly now fixed; check glibc 2.13 +.SH SEE ALSO +.BR sigaction (2), +.BR perror (3), +.BR strsignal (3), +.BR signal (7) diff --git a/man/man3/pthread_atfork.3 b/man/man3/pthread_atfork.3 new file mode 100644 index 0000000..a5844ab --- /dev/null +++ b/man/man3/pthread_atfork.3 @@ -0,0 +1,108 @@ +.\" Copyright (C) 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_atfork 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_atfork \- register fork handlers +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_atfork(void (*" prepare ")(void), void (*" parent ")(void)," +.BI " void (*" child ")(void));" +.fi +.SH DESCRIPTION +The +.BR pthread_atfork () +function registers fork handlers that are to be executed when +.BR fork (2) +is called by any thread in a process. +The handlers are executed in the context of the thread that calls +.BR fork (2). +.P +Three kinds of handler can be registered: +.IP \[bu] 3 +.I prepare +specifies a handler that is executed in the parent process before +.BR fork (2) +processing starts. +.IP \[bu] +.I parent +specifies a handler that is executed in the parent process after +.BR fork (2) +processing completes. +.IP \[bu] +.I child +specifies a handler that is executed in the child process after +.BR fork (2) +processing completes. +.P +Any of the three arguments may be NULL if no handler is needed +in the corresponding phase of +.BR fork (2) +processing. +.SH RETURN VALUE +On success, +.BR pthread_atfork () +returns zero. +On error, it returns an error number. +.BR pthread_atfork () +may be called multiple times by a process +to register additional handlers. +The handlers for each phase are called in a specified order: the +.I prepare +handlers are called in reverse order of registration; the +.I parent +and +.I child +handlers are called in the order of registration. +.SH ERRORS +.TP +.B ENOMEM +Could not allocate memory to record the fork handler list entry. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +When +.BR fork (2) +is called in a multithreaded process, +only the calling thread is duplicated in the child process. +The original intention of +.BR pthread_atfork () +was to allow the child process to be returned to a consistent state. +For example, at the time of the call to +.BR fork (2), +other threads may have locked mutexes that are visible in the +user-space memory duplicated in the child. +Such mutexes would never be unlocked, +since the threads that placed the locks are not duplicated in the child. +The intent of +.BR pthread_atfork () +was to provide a mechanism whereby the application (or a library) +could ensure that mutexes and other process and thread state would be +restored to a consistent state. +In practice, this task is generally too difficult to be practicable. +.P +After a +.BR fork (2) +in a multithreaded process returns in the child, +the child should call only async-signal-safe functions (see +.BR signal\-safety (7)) +until such time as it calls +.BR execve (2) +to execute a new program. +.P +POSIX.1 specifies that +.BR pthread_atfork () +shall not fail with the error +.BR EINTR . +.SH SEE ALSO +.BR fork (2), +.BR atexit (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_destroy.3 b/man/man3/pthread_attr_destroy.3 new file mode 100644 index 0000000..4e7c949 --- /dev/null +++ b/man/man3/pthread_attr_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_init.3 diff --git a/man/man3/pthread_attr_getaffinity_np.3 b/man/man3/pthread_attr_getaffinity_np.3 new file mode 100644 index 0000000..c6af8fa --- /dev/null +++ b/man/man3/pthread_attr_getaffinity_np.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setaffinity_np.3 diff --git a/man/man3/pthread_attr_getdetachstate.3 b/man/man3/pthread_attr_getdetachstate.3 new file mode 100644 index 0000000..c57ecd5 --- /dev/null +++ b/man/man3/pthread_attr_getdetachstate.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setdetachstate.3 diff --git a/man/man3/pthread_attr_getguardsize.3 b/man/man3/pthread_attr_getguardsize.3 new file mode 100644 index 0000000..766ca2f --- /dev/null +++ b/man/man3/pthread_attr_getguardsize.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setguardsize.3 diff --git a/man/man3/pthread_attr_getinheritsched.3 b/man/man3/pthread_attr_getinheritsched.3 new file mode 100644 index 0000000..65239cb --- /dev/null +++ b/man/man3/pthread_attr_getinheritsched.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setinheritsched.3 diff --git a/man/man3/pthread_attr_getschedparam.3 b/man/man3/pthread_attr_getschedparam.3 new file mode 100644 index 0000000..3f830fd --- /dev/null +++ b/man/man3/pthread_attr_getschedparam.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setschedparam.3 diff --git a/man/man3/pthread_attr_getschedpolicy.3 b/man/man3/pthread_attr_getschedpolicy.3 new file mode 100644 index 0000000..10f740c --- /dev/null +++ b/man/man3/pthread_attr_getschedpolicy.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setschedpolicy.3 diff --git a/man/man3/pthread_attr_getscope.3 b/man/man3/pthread_attr_getscope.3 new file mode 100644 index 0000000..965fd62 --- /dev/null +++ b/man/man3/pthread_attr_getscope.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setscope.3 diff --git a/man/man3/pthread_attr_getsigmask_np.3 b/man/man3/pthread_attr_getsigmask_np.3 new file mode 100644 index 0000000..92b55d3 --- /dev/null +++ b/man/man3/pthread_attr_getsigmask_np.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setsigmask_np.3 diff --git a/man/man3/pthread_attr_getstack.3 b/man/man3/pthread_attr_getstack.3 new file mode 100644 index 0000000..2b20d7e --- /dev/null +++ b/man/man3/pthread_attr_getstack.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setstack.3 diff --git a/man/man3/pthread_attr_getstackaddr.3 b/man/man3/pthread_attr_getstackaddr.3 new file mode 100644 index 0000000..49d8a85 --- /dev/null +++ b/man/man3/pthread_attr_getstackaddr.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setstackaddr.3 diff --git a/man/man3/pthread_attr_getstacksize.3 b/man/man3/pthread_attr_getstacksize.3 new file mode 100644 index 0000000..52431f5 --- /dev/null +++ b/man/man3/pthread_attr_getstacksize.3 @@ -0,0 +1 @@ +.so man3/pthread_attr_setstacksize.3 diff --git a/man/man3/pthread_attr_init.3 b/man/man3/pthread_attr_init.3 new file mode 100644 index 0000000..0cb3a5a --- /dev/null +++ b/man/man3/pthread_attr_init.3 @@ -0,0 +1,313 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_init 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_init, pthread_attr_destroy \- initialize and destroy +thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_attr_init(pthread_attr_t *" attr ); +.BI "int pthread_attr_destroy(pthread_attr_t *" attr ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_init () +function initializes the thread attributes object pointed to by +.I attr +with default attribute values. +After this call, individual attributes of the object can be set +using various related functions (listed under SEE ALSO), +and then the object can be used in one or more +.BR pthread_create (3) +calls that create threads. +.P +Calling +.BR pthread_attr_init () +on a thread attributes object that has already been initialized +results in undefined behavior. +.P +When a thread attributes object is no longer required, +it should be destroyed using the +.BR pthread_attr_destroy () +function. +Destroying a thread attributes object has no effect +on threads that were created using that object. +.P +Once a thread attributes object has been destroyed, +it can be reinitialized using +.BR pthread_attr_init (). +Any other use of a destroyed thread attributes object +has undefined results. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +POSIX.1 documents an +.B ENOMEM +error for +.BR pthread_attr_init (); +on Linux these functions always succeed +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_init (), +.BR pthread_attr_destroy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The +.I pthread_attr_t +type should be treated as opaque: +any access to the object other than via pthreads functions +is nonportable and produces undefined results. +.SH EXAMPLES +The program below optionally makes use of +.BR pthread_attr_init () +and various related functions to initialize a thread attributes +object that is used to create a single thread. +Once created, the thread uses the +.BR pthread_getattr_np (3) +function (a nonstandard GNU extension) to retrieve the thread's +attributes, and then displays those attributes. +.P +If the program is run with no command-line argument, +then it passes NULL as the +.I attr +argument of +.BR pthread_create (3), +so that the thread is created with default attributes. +Running the program on Linux/x86-32 with the NPTL threading implementation, +we see the following: +.P +.in +4n +.EX +.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 +.RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB" +unlimited +.RB "$" " ./a.out" +Thread attributes: + Detach state = PTHREAD_CREATE_JOINABLE + Scope = PTHREAD_SCOPE_SYSTEM + Inherit scheduler = PTHREAD_INHERIT_SCHED + Scheduling policy = SCHED_OTHER + Scheduling priority = 0 + Guard size = 4096 bytes + Stack address = 0x40196000 + Stack size = 0x201000 bytes +.EE +.in +.P +When we supply a stack size as a command-line argument, +the program initializes a thread attributes object, +sets various attributes in that object, +and passes a pointer to the object in the call to +.BR pthread_create (3). +Running the program on Linux/x86-32 with the NPTL threading implementation, +we see the following: +.P +.in +4n +.EX +.\" Results from glibc 2.8, SUSE 11.0; Oct 2008 +.RB "$" " ./a.out 0x3000000" +posix_memalign() allocated at 0x40197000 +Thread attributes: + Detach state = PTHREAD_CREATE_DETACHED + Scope = PTHREAD_SCOPE_SYSTEM + Inherit scheduler = PTHREAD_EXPLICIT_SCHED + Scheduling policy = SCHED_OTHER + Scheduling priority = 0 + Guard size = 0 bytes + Stack address = 0x40197000 + Stack size = 0x3000000 bytes +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_attr_init.c) +.EX +#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ +#include +#include +#include +#include +#include +#include +\& +static void +display_pthread_attr(pthread_attr_t *attr, char *prefix) +{ + int s, i; + size_t v; + void *stkaddr; + struct sched_param sp; +\& + s = pthread_attr_getdetachstate(attr, &i); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getdetachstate"); + printf("%sDetach state = %s\en", prefix, + (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" : + (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" : + "???"); +\& + s = pthread_attr_getscope(attr, &i); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getscope"); + printf("%sScope = %s\en", prefix, + (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" : + (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" : + "???"); +\& + s = pthread_attr_getinheritsched(attr, &i); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getinheritsched"); + printf("%sInherit scheduler = %s\en", prefix, + (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" : + (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" : + "???"); +\& + s = pthread_attr_getschedpolicy(attr, &i); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getschedpolicy"); + printf("%sScheduling policy = %s\en", prefix, + (i == SCHED_OTHER) ? "SCHED_OTHER" : + (i == SCHED_FIFO) ? "SCHED_FIFO" : + (i == SCHED_RR) ? "SCHED_RR" : + "???"); +\& + s = pthread_attr_getschedparam(attr, &sp); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getschedparam"); + printf("%sScheduling priority = %d\en", prefix, sp.sched_priority); +\& + s = pthread_attr_getguardsize(attr, &v); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getguardsize"); + printf("%sGuard size = %zu bytes\en", prefix, v); +\& + s = pthread_attr_getstack(attr, &stkaddr, &v); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getstack"); + printf("%sStack address = %p\en", prefix, stkaddr); + printf("%sStack size = %#zx bytes\en", prefix, v); +} +\& +static void * +thread_start(void *arg) +{ + int s; + pthread_attr_t gattr; +\& + /* pthread_getattr_np() is a non\-standard GNU extension that + retrieves the attributes of the thread specified in its + first argument. */ +\& + s = pthread_getattr_np(pthread_self(), &gattr); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_getattr_np"); +\& + printf("Thread attributes:\en"); + display_pthread_attr(&gattr, "\et"); +\& + exit(EXIT_SUCCESS); /* Terminate all threads */ +} +\& +int +main(int argc, char *argv[]) +{ + pthread_t thr; + pthread_attr_t attr; + pthread_attr_t *attrp; /* NULL or &attr */ + int s; +\& + attrp = NULL; +\& + /* If a command\-line argument was supplied, use it to set the + stack\-size attribute and set a few other thread attributes, + and set attrp pointing to thread attributes object. */ +\& + if (argc > 1) { + size_t stack_size; + void *sp; +\& + attrp = &attr; +\& + s = pthread_attr_init(&attr); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_init"); +\& + s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setdetachstate"); +\& + s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setinheritsched"); +\& + stack_size = strtoul(argv[1], NULL, 0); +\& + s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "posix_memalign"); +\& + printf("posix_memalign() allocated at %p\en", sp); +\& + s = pthread_attr_setstack(&attr, sp, stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setstack"); + } +\& + s = pthread_create(&thr, attrp, &thread_start, NULL); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_create"); +\& + if (attrp != NULL) { + s = pthread_attr_destroy(attrp); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_destroy"); + } +\& + pause(); /* Terminates when other thread calls exit() */ +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_setaffinity_np (3), +.BR pthread_attr_setdetachstate (3), +.BR pthread_attr_setguardsize (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_attr_setscope (3), +.BR pthread_attr_setsigmask_np (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstackaddr (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthread_getattr_np (3), +.BR pthread_setattr_default_np (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setaffinity_np.3 b/man/man3/pthread_attr_setaffinity_np.3 new file mode 100644 index 0000000..a7d104a --- /dev/null +++ b/man/man3/pthread_attr_setaffinity_np.3 @@ -0,0 +1,120 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setaffinity_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- set/get +CPU affinity attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int pthread_attr_setaffinity_np(pthread_attr_t *" attr , +.BI " size_t " cpusetsize ", const cpu_set_t *" cpuset ); +.BI "int pthread_attr_getaffinity_np(const pthread_attr_t *" attr , +.BI " size_t " cpusetsize ", cpu_set_t *" cpuset ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setaffinity_np () +function +sets the CPU affinity mask attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR cpuset . +This attribute determines the CPU affinity mask +of a thread created using the thread attributes object +.IR attr . +.P +The +.BR pthread_attr_getaffinity_np () +function +returns the CPU affinity mask attribute of the thread attributes object +referred to by +.I attr +in the buffer pointed to by +.IR cpuset . +.P +The argument +.I cpusetsize +is the length (in bytes) of the buffer pointed to by +.IR cpuset . +Typically, this argument would be specified as +.IR sizeof(cpu_set_t) . +.P +For more details on CPU affinity masks, see +.BR sched_setaffinity (2). +For a description of a set of macros +that can be used to manipulate and inspect CPU sets, see +.BR CPU_SET (3). +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.TP +.B EINVAL +.RB ( pthread_attr_setaffinity_np ()) +.I cpuset +specified a CPU that was outside the set supported by the kernel. +(The kernel configuration option +.B CONFIG_NR_CPUS +defines the range of the set supported by the kernel data type +.\" cpumask_t +used to represent CPU sets.) +.\" The raw sched_getaffinity() system call returns the size (in bytes) +.\" of the cpumask_t type. +.TP +.B EINVAL +.RB ( pthread_attr_getaffinity_np ()) +A CPU in the affinity mask of the thread attributes object referred to by +.I attr +lies outside the range specified by +.I cpusetsize +(i.e., +.IR cpuset / cpusetsize +is too small). +.TP +.B ENOMEM +.RB ( pthread_attr_setaffinity_np ()) +Could not allocate memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setaffinity_np (), +.BR pthread_attr_getaffinity_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.3.4. +.SH NOTES +In glibc 2.3.3 only, +versions of these functions were provided that did not have a +.I cpusetsize +argument. +Instead the CPU set size given to the underlying system calls was always +.IR sizeof(cpu_set_t) . +.SH SEE ALSO +.BR sched_setaffinity (2), +.BR pthread_attr_init (3), +.BR pthread_setaffinity_np (3), +.BR cpuset (7), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setdetachstate.3 b/man/man3/pthread_attr_setdetachstate.3 new file mode 100644 index 0000000..eeb5c03 --- /dev/null +++ b/man/man3/pthread_attr_setdetachstate.3 @@ -0,0 +1,115 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setdetachstate 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setdetachstate, pthread_attr_getdetachstate \- +set/get detach state attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_attr_setdetachstate(pthread_attr_t *" attr \ +", int " detachstate ); +.BI "int pthread_attr_getdetachstate(const pthread_attr_t *" attr , +.BI " int *" detachstate ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setdetachstate () +function sets the detach state attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR detachstate . +The detach state attribute determines whether a thread created using +the thread attributes object +.I attr +will be created in a joinable or a detached state. +.P +The following values may be specified in +.IR detachstate : +.TP +.B PTHREAD_CREATE_DETACHED +Threads that are created using +.I attr +will be created in a detached state. +.TP +.B PTHREAD_CREATE_JOINABLE +Threads that are created using +.I attr +will be created in a joinable state. +.P +The default setting of the detach state attribute in a newly initialized +thread attributes object is +.BR PTHREAD_CREATE_JOINABLE . +.P +The +.BR pthread_attr_getdetachstate () +returns the detach state attribute of the thread attributes object +.I attr +in the buffer pointed to by +.IR detachstate . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setdetachstate () +can fail with the following error: +.TP +.B EINVAL +An invalid value was specified in +.IR detachstate . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setdetachstate (), +.BR pthread_attr_getdetachstate () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +See +.BR pthread_create (3) +for more details on detached and joinable threads. +.P +A thread that is created in a joinable state should +eventually either be joined using +.BR pthread_join (3) +or detached using +.BR pthread_detach (3); +see +.BR pthread_create (3). +.P +It is an error to specify the thread ID of +a thread that was created in a detached state +in a later call to +.BR pthread_detach (3) +or +.BR pthread_join (3). +.SH EXAMPLES +See +.BR pthread_attr_init (3). +.SH SEE ALSO +.BR pthread_attr_init (3), +.BR pthread_create (3), +.BR pthread_detach (3), +.BR pthread_join (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setguardsize.3 b/man/man3/pthread_attr_setguardsize.3 new file mode 100644 index 0000000..0056650 --- /dev/null +++ b/man/man3/pthread_attr_setguardsize.3 @@ -0,0 +1,163 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setguardsize 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setguardsize, pthread_attr_getguardsize \- set/get guard size +attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_attr_setguardsize(pthread_attr_t *" attr \ +", size_t " guardsize ); +.BI "int pthread_attr_getguardsize(const pthread_attr_t *restrict " attr , +.BI " size_t *restrict " guardsize ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setguardsize () +function sets the guard size attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR guardsize . +.P +If +.I guardsize +is greater than 0, +then for each new thread created using +.I attr +the system allocates an additional region of at least +.I guardsize +bytes at the end of the thread's stack to act as the guard area +for the stack (but see BUGS). +.P +If +.I guardsize +is 0, then new threads created with +.I attr +will not have a guard area. +.P +The default guard size is the same as the system page size. +.P +If the stack address attribute has been set in +.I attr +(using +.BR pthread_attr_setstack (3) +or +.BR pthread_attr_setstackaddr (3)), +meaning that the caller is allocating the thread's stack, +then the guard size attribute is ignored +(i.e., no guard area is created by the system): +it is the application's responsibility to handle stack overflow +(perhaps by using +.BR mprotect (2) +to manually define a guard area at the end of the stack +that it has allocated). +.P +The +.BR pthread_attr_getguardsize () +function returns the guard size attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR guardsize . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +POSIX.1 documents an +.B EINVAL +error if +.I attr +or +.I guardsize +is invalid. +On Linux these functions always succeed +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setguardsize (), +.BR pthread_attr_getguardsize () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +A guard area consists of virtual memory pages that are protected +to prevent read and write access. +If a thread overflows its stack into the guard area, +then, on most hard architectures, it receives a +.B SIGSEGV +signal, thus notifying it of the overflow. +Guard areas start on page boundaries, +and the guard size is internally rounded up to +the system page size when creating a thread. +(Nevertheless, +.BR pthread_attr_getguardsize () +returns the guard size that was set by +.BR pthread_attr_setguardsize ().) +.P +Setting a guard size of 0 may be useful to save memory +in an application that creates many threads +and knows that stack overflow can never occur. +.P +Choosing a guard size larger than the default size +may be necessary for detecting stack overflows +if a thread allocates large data structures on the stack. +.SH BUGS +As at glibc 2.8, the NPTL threading implementation includes +the guard area within the stack size allocation, +rather than allocating extra space at the end of the stack, +as POSIX.1 requires. +(This can result in an +.B EINVAL +error from +.BR pthread_create (3) +if the guard size value is too large, +leaving no space for the actual stack.) +.P +The obsolete LinuxThreads implementation did the right thing, +allocating extra space at the end of the stack for the guard area. +.\" glibc includes the guardsize within the allocated stack size, +.\" which looks pretty clearly to be in violation of POSIX. +.\" +.\" Filed bug, 22 Oct 2008: +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6973 +.\" +.\" Older reports: +.\" https//bugzilla.redhat.com/show_bug.cgi?id=435337 +.\" Reportedly, LinuxThreads did the right thing, allocating +.\" extra space at the end of the stack: +.\" http://sourceware.org/ml/libc-alpha/2008-05/msg00086.html +.SH EXAMPLES +See +.BR pthread_getattr_np (3). +.SH SEE ALSO +.BR mmap (2), +.BR mprotect (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setinheritsched.3 b/man/man3/pthread_attr_setinheritsched.3 new file mode 100644 index 0000000..48406e2 --- /dev/null +++ b/man/man3/pthread_attr_setinheritsched.3 @@ -0,0 +1,140 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setinheritsched 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setinheritsched, pthread_attr_getinheritsched \- set/get +inherit-scheduler attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_attr_setinheritsched(pthread_attr_t *" attr , +.BI " int " inheritsched ); +.BI "int pthread_attr_getinheritsched(const pthread_attr_t *restrict " attr , +.BI " int *restrict " inheritsched ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setinheritsched () +function sets the inherit-scheduler attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR inheritsched . +The inherit-scheduler attribute determines whether a thread created using +the thread attributes object +.I attr +will inherit its scheduling attributes from the calling thread +or whether it will take them from +.IR attr . +.P +The following scheduling attributes are affected by the +inherit-scheduler attribute: +scheduling policy +.RB ( pthread_attr_setschedpolicy (3)), +scheduling priority +.RB ( pthread_attr_setschedparam (3)), +and contention scope +.RB ( pthread_attr_setscope (3)). +.P +The following values may be specified in +.IR inheritsched : +.TP +.B PTHREAD_INHERIT_SCHED +Threads that are created using +.I attr +inherit scheduling attributes from the creating thread; +the scheduling attributes in +.I attr +are ignored. +.TP +.B PTHREAD_EXPLICIT_SCHED +Threads that are created using +.I attr +take their scheduling attributes from the values specified +by the attributes object. +.\" FIXME Document the defaults for scheduler settings +.P +The default setting of the inherit-scheduler attribute in +a newly initialized thread attributes object is +.BR PTHREAD_INHERIT_SCHED . +.P +The +.BR pthread_attr_getinheritsched () +returns the inherit-scheduler attribute of the thread attributes object +.I attr +in the buffer pointed to by +.IR inheritsched . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setinheritsched () +can fail with the following error: +.TP +.B EINVAL +Invalid value in +.IR inheritsched . +.P +POSIX.1 also documents an optional +.B ENOTSUP +error ("attempt was made to set the attribute to an unsupported value") for +.BR pthread_attr_setinheritsched (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setinheritsched (), +.BR pthread_attr_getinheritsched () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0. +POSIX.1-2001. +.SH BUGS +As at glibc 2.8, if a thread attributes object is initialized using +.BR pthread_attr_init (3), +then the scheduling policy of the attributes object is set to +.B SCHED_OTHER +and the scheduling priority is set to 0. +However, if the inherit-scheduler attribute is then set to +.BR PTHREAD_EXPLICIT_SCHED , +then a thread created using the attribute object +wrongly inherits its scheduling attributes from the creating thread. +This bug does not occur if either the scheduling policy or +scheduling priority attribute is explicitly set +in the thread attributes object before calling +.BR pthread_create (3). +.\" FIXME . Track status of the following bug: +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7007 +.SH EXAMPLES +See +.BR pthread_setschedparam (3). +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_init (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_attr_setscope (3), +.BR pthread_create (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_attr_setschedparam.3 b/man/man3/pthread_attr_setschedparam.3 new file mode 100644 index 0000000..e3403b0 --- /dev/null +++ b/man/man3/pthread_attr_setschedparam.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setschedparam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setschedparam, pthread_attr_getschedparam \- set/get +scheduling parameter attributes in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_attr_setschedparam(pthread_attr_t *restrict " attr , +.BI " const struct sched_param *restrict " param ); +.BI "int pthread_attr_getschedparam(const pthread_attr_t *restrict " attr , +.BI " struct sched_param *restrict " param ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setschedparam () +function sets the scheduling parameter attributes of the +thread attributes object referred to by +.I attr +to the values specified in the buffer pointed to by +.IR param . +These attributes determine the scheduling parameters of +a thread created using the thread attributes object +.IR attr . +.P +The +.BR pthread_attr_getschedparam () +returns the scheduling parameter attributes of the thread attributes object +.I attr +in the buffer pointed to by +.IR param . +.P +Scheduling parameters are maintained in the following structure: +.P +.in +4n +.EX +struct sched_param { + int sched_priority; /* Scheduling priority */ +}; +.EE +.in +.P +As can be seen, only one scheduling parameter is supported. +For details of the permitted ranges for scheduling priorities +in each scheduling policy, see +.BR sched (7). +.P +In order for the parameter setting made by +.BR pthread_attr_setschedparam () +to have effect when calling +.BR pthread_create (3), +the caller must use +.BR pthread_attr_setinheritsched (3) +to set the inherit-scheduler attribute of the attributes object +.I attr +to +.BR PTHREAD_EXPLICIT_SCHED . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setschedparam () +can fail with the following error: +.TP +.B EINVAL +The priority specified in +.I param +does not make sense for the current scheduling policy of +.IR attr . +.P +POSIX.1 also documents an +.B ENOTSUP +error for +.BR pthread_attr_setschedparam (). +This value is never returned on Linux +(but portable and future-proof applications should nevertheless +handle this error return value). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setschedparam (), +.BR pthread_attr_getschedparam () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +glibc 2.0. +.SH NOTES +See +.BR pthread_attr_setschedpolicy (3) +for a list of the thread scheduling policies supported on Linux. +.SH EXAMPLES +See +.BR pthread_setschedparam (3). +.SH SEE ALSO +.ad l +.nh +.BR sched_get_priority_min (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_attr_setschedpolicy.3 b/man/man3/pthread_attr_setschedpolicy.3 new file mode 100644 index 0000000..5217fe2 --- /dev/null +++ b/man/man3/pthread_attr_setschedpolicy.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setschedpolicy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setschedpolicy, pthread_attr_getschedpolicy \- set/get +scheduling policy attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_attr_setschedpolicy(pthread_attr_t *" attr ", int " policy ); +.BI "int pthread_attr_getschedpolicy(const pthread_attr_t *restrict " attr , +.BI " int *restrict " policy ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setschedpolicy () +function sets the scheduling policy attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR policy . +This attribute determines the scheduling policy of +a thread created using the thread attributes object +.IR attr . +.P +The supported values for +.I policy +are +.BR SCHED_FIFO , +.BR SCHED_RR , +and +.BR SCHED_OTHER , +with the semantics described in +.BR sched (7). +.\" FIXME . pthread_setschedparam() places no restriction on the policy, +.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013 +.P +The +.BR pthread_attr_getschedpolicy () +returns the scheduling policy attribute of the thread attributes object +.I attr +in the buffer pointed to by +.IR policy . +.P +In order for the policy setting made by +.BR pthread_attr_setschedpolicy () +to have effect when calling +.BR pthread_create (3), +the caller must use +.BR pthread_attr_setinheritsched (3) +to set the inherit-scheduler attribute of the attributes object +.I attr +to +.BR PTHREAD_EXPLICIT_SCHED . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setschedpolicy () +can fail with the following error: +.TP +.B EINVAL +Invalid value in +.IR policy . +.P +POSIX.1 also documents an optional +.B ENOTSUP +error ("attempt was made to set the attribute to an unsupported value") for +.BR pthread_attr_setschedpolicy (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setschedpolicy (), +.BR pthread_attr_getschedpolicy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0. +POSIX.1-2001. +.SH EXAMPLES +See +.BR pthread_setschedparam (3). +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_create (3), +.BR pthread_setschedparam (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_attr_setscope.3 b/man/man3/pthread_attr_setscope.3 new file mode 100644 index 0000000..6fc3fc0 --- /dev/null +++ b/man/man3/pthread_attr_setscope.3 @@ -0,0 +1,139 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setscope 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setscope, pthread_attr_getscope \- set/get contention scope +attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_attr_setscope(pthread_attr_t *" attr ", int " scope ); +.BI "int pthread_attr_getscope(const pthread_attr_t *restrict " attr , +.BI " int *restrict " scope ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setscope () +function sets the contention scope attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR scope . +The contention scope attribute defines the set of threads +against which a thread competes for resources such as the CPU. +POSIX.1 specifies two possible values for +.IR scope : +.TP +.B PTHREAD_SCOPE_SYSTEM +The thread competes for resources with all other threads +in all processes on the system that are in the same scheduling +allocation domain (a group of one or more processors). +.B PTHREAD_SCOPE_SYSTEM +threads are scheduled relative to one another +according to their scheduling policy and priority. +.TP +.B PTHREAD_SCOPE_PROCESS +The thread competes for resources with all other threads +in the same process that were also created with the +.B PTHREAD_SCOPE_PROCESS +contention scope. +.B PTHREAD_SCOPE_PROCESS +threads are scheduled relative to other threads in the process +according to their scheduling policy and priority. +POSIX.1 leaves it unspecified how these threads contend +with other threads in other process on the system or +with other threads in the same process that +were created with the +.B PTHREAD_SCOPE_SYSTEM +contention scope. +.P +POSIX.1 requires that an implementation support at least one of these +contention scopes. +Linux supports +.BR PTHREAD_SCOPE_SYSTEM , +but not +.BR PTHREAD_SCOPE_PROCESS . +.P +On systems that support multiple contention scopes, then, +in order for the parameter setting made by +.BR pthread_attr_setscope () +to have effect when calling +.BR pthread_create (3), +the caller must use +.BR pthread_attr_setinheritsched (3) +to set the inherit-scheduler attribute of the attributes object +.I attr +to +.BR PTHREAD_EXPLICIT_SCHED . +.P +The +.BR pthread_attr_getscope () +function returns the contention scope attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR scope . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setscope () +can fail with the following errors: +.TP +.B EINVAL +An invalid value was specified in +.IR scope . +.TP +.B ENOTSUP +.I scope +specified the value +.BR PTHREAD_SCOPE_PROCESS , +which is not supported on Linux. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setscope (), +.BR pthread_attr_getscope () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The +.B PTHREAD_SCOPE_SYSTEM +contention scope typically indicates that a user-space thread is +bound directly to a single kernel-scheduling entity. +This is the case on Linux for the obsolete LinuxThreads implementation +and the modern NPTL implementation, +which are both 1:1 threading implementations. +.P +POSIX.1 specifies that the default contention scope is +implementation-defined. +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_init (3), +.BR pthread_attr_setaffinity_np (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setsigmask_np.3 b/man/man3/pthread_attr_setsigmask_np.3 new file mode 100644 index 0000000..9b75a49 --- /dev/null +++ b/man/man3/pthread_attr_setsigmask_np.3 @@ -0,0 +1,130 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setsigmask_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setsigmask_np, pthread_attr_getsigmask_np \- set/get +signal mask attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int pthread_attr_setsigmask_np(pthread_attr_t *" attr , +.BI " const sigset_t *" sigmask ); +.BI "int pthread_attr_getsigmask_np(const pthread_attr_t *" attr , +.BI " sigset_t *" sigmask ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setsigmask_np () +function sets the signal mask attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR *sigmask . +If +.I sigmask +is specified as NULL, then any existing signal mask attribute in +.I attr +is unset. +.P +The +.BR pthread_attr_getsigmask_np () +function returns the signal mask attribute of the thread attributes object +referred to by +.I attr +in the buffer pointed to by +.IR sigmask . +If the signal mask attribute is currently unset, +then this function returns the special value +.B PTHREAD_ATTR_NO_SIGMASK_NP +as its result. +.SH RETURN VALUE +The +.BR pthread_attr_setsigmask_np () +function returns 0 on success, or a nonzero error number on failure. +.P +the +.BR pthread_attr_getsigmask_np () +function returns either 0 or +.BR PTHREAD_ATTR_NO_SIGMASK_NP . +When 0 is returned, the signal mask attribute is returned via +.IR sigmask . +A return value of +.B PTHREAD_ATTR_NO_SIGMASK_NP +indicates that the signal mask attribute is not set in +.IR attr . +.P +On error, these functions return a positive error number. +.SH ERRORS +.TP +.B ENOMEM +.RB ( pthread_attr_setsigmask_np ()) +Could not allocate memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setsigmask_np (), +.BR pthread_attr_getsigmask_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.32. +.SH NOTES +The signal mask attribute determines the signal mask that will be assigned to +a thread created using the thread attributes object +.IR attr . +If this attribute is not set, then a thread created using +.I attr +will inherit a copy of the creating thread's signal mask. +.P +For more details on signal masks, see +.BR sigprocmask (2). +For a description of a set of macros +that can be used to manipulate and inspect signal sets, see +.BR sigsetops (3). +.P +In the absence of +.BR pthread_attr_setsigmask_np () +it is possible to create a thread with a desired signal mask as follows: +.IP \[bu] 3 +The creating thread uses +.BR pthread_sigmask (3) +to save its current signal mask and set its mask to block all signals. +.IP \[bu] +The new thread is then created using +.BR pthread_create (); +the new thread will inherit the creating thread's signal mask. +.IP \[bu] +The new thread sets its signal mask to the desired value using +.BR pthread_sigmask (3). +.IP \[bu] +The creating thread restores its signal mask to the original value. +.P +Following the above steps, +there is no possibility for the new thread to receive a signal +before it has adjusted its signal mask to the desired value. +.SH SEE ALSO +.BR sigprocmask (2), +.BR pthread_attr_init (3), +.BR pthread_sigmask (3), +.BR pthreads (7), +.BR signal (7) diff --git a/man/man3/pthread_attr_setstack.3 b/man/man3/pthread_attr_setstack.3 new file mode 100644 index 0000000..e060f43 --- /dev/null +++ b/man/man3/pthread_attr_setstack.3 @@ -0,0 +1,164 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setstack 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setstack, pthread_attr_getstack \- set/get stack +attributes in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_attr_setstack(pthread_attr_t *" attr , +.BI " void " stackaddr [. stacksize ], +.BI " size_t " stacksize ); +.BI "int pthread_attr_getstack(const pthread_attr_t *restrict " attr , +.BI " void **restrict " stackaddr , +.BI " size_t *restrict " stacksize ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_attr_getstack (), +.BR pthread_attr_setstack (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setstack () +function sets the stack address and stack size attributes of the +thread attributes object referred to by +.I attr +to the values specified in +.I stackaddr +and +.IR stacksize , +respectively. +These attributes specify the location and size of the stack that should +be used by a thread that is created using the thread attributes object +.IR attr . +.P +.I stackaddr +should point to the lowest addressable byte of a buffer of +.I stacksize +bytes that was allocated by the caller. +The pages of the allocated buffer should be both readable and writable. +.P +The +.BR pthread_attr_getstack () +function returns the stack address and stack size attributes of the +thread attributes object referred to by +.I attr +in the buffers pointed to by +.I stackaddr +and +.IR stacksize , +respectively. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setstack () +can fail with the following error: +.TP +.B EINVAL +.I stacksize +is less than +.B PTHREAD_STACK_MIN +(16384) bytes. +On some systems, this error may also occur if +.I stackaddr +or +.I stackaddr\~+\~stacksize +is not suitably aligned. +.P +POSIX.1 also documents an +.B EACCES +error if the stack area described by +.I stackaddr +and +.I stacksize +is not both readable and writable by the caller. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setstack (), +.BR pthread_attr_getstack () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.SH NOTES +These functions are provided for applications that must ensure that +a thread's stack is placed in a particular location. +For most applications, this is not necessary, +and the use of these functions should be avoided. +(Use +.BR pthread_attr_setstacksize (3) +if an application simply requires a stack size other than the default.) +.P +When an application employs +.BR pthread_attr_setstack (), +it takes over the responsibility of allocating the stack. +Any guard size value that was set using +.BR pthread_attr_setguardsize (3) +is ignored. +If deemed necessary, +it is the application's responsibility to allocate a guard area +(one or more pages protected against reading and writing) +to handle the possibility of stack overflow. +.P +The address specified in +.I stackaddr +should be suitably aligned: +for full portability, align it on a page boundary +.RI ( sysconf(_SC_PAGESIZE) ). +.BR posix_memalign (3) +may be useful for allocation. +Probably, +.I stacksize +should also be a multiple of the system page size. +.P +If +.I attr +is used to create multiple threads, then the caller must change the +stack address attribute between calls to +.BR pthread_create (3); +otherwise, the threads will attempt to use the same memory area +for their stacks, and chaos will ensue. +.SH EXAMPLES +See +.BR pthread_attr_init (3). +.SH SEE ALSO +.ad l +.nh +.BR mmap (2), +.BR mprotect (2), +.BR posix_memalign (3), +.BR pthread_attr_init (3), +.BR pthread_attr_setguardsize (3), +.BR pthread_attr_setstackaddr (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setstackaddr.3 b/man/man3/pthread_attr_setstackaddr.3 new file mode 100644 index 0000000..9744a57 --- /dev/null +++ b/man/man3/pthread_attr_setstackaddr.3 @@ -0,0 +1,115 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setstackaddr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setstackaddr, pthread_attr_getstackaddr \- +set/get stack address attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.B [[deprecated]] +.BI "int pthread_attr_setstackaddr(pthread_attr_t *" attr \ +", void *" stackaddr ); +.B [[deprecated]] +.BI "int pthread_attr_getstackaddr(const pthread_attr_t *restrict " attr , +.BI " void **restrict " stackaddr ); +.fi +.SH DESCRIPTION +These functions are obsolete: +.B do not use them. +Use +.BR pthread_attr_setstack (3) +and +.BR pthread_attr_getstack (3) +instead. +.P +The +.BR pthread_attr_setstackaddr () +function sets the stack address attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR stackaddr . +This attribute specifies the location of the stack that should +be used by a thread that is created using the thread attributes object +.IR attr . +.P +.I stackaddr +should point to a buffer of at least +.B PTHREAD_STACK_MIN +bytes that was allocated by the caller. +The pages of the allocated buffer should be both readable and writable. +.P +The +.BR pthread_attr_getstackaddr () +function returns the stack address attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR stackaddr . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +No errors are defined +(but applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setstackaddr (), +.BR pthread_attr_getstackaddr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +glibc 2.1. +Marked obsolete in POSIX.1-2001. +Removed in POSIX.1-2008. +.SH NOTES +.I Do not use these functions! +They cannot be portably used, since they provide no way of specifying +the direction of growth or the range of the stack. +For example, on architectures with a stack that grows downward, +.I stackaddr +specifies the next address past the +.I highest +address of the allocated stack area. +However, on architectures with a stack that grows upward, +.I stackaddr +specifies the +.I lowest +address in the allocated stack area. +By contrast, the +.I stackaddr +used by +.BR pthread_attr_setstack (3) +and +.BR pthread_attr_getstack (3), +is always a pointer to the lowest address in the allocated stack area +(and the +.I stacksize +argument specifies the range of the stack). +.SH SEE ALSO +.BR pthread_attr_init (3), +.BR pthread_attr_setstack (3), +.BR pthread_attr_setstacksize (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_attr_setstacksize.3 b/man/man3/pthread_attr_setstacksize.3 new file mode 100644 index 0000000..9c98ef0 --- /dev/null +++ b/man/man3/pthread_attr_setstacksize.3 @@ -0,0 +1,114 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setstacksize 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_attr_setstacksize, pthread_attr_getstacksize \- set/get stack size +attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_attr_setstacksize(pthread_attr_t *" attr \ +", size_t " stacksize ); +.BI "int pthread_attr_getstacksize(const pthread_attr_t *restrict " attr , +.BI " size_t *restrict " stacksize ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setstacksize () +function sets the stack size attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR stacksize . +.P +The stack size attribute determines the minimum size (in bytes) that +will be allocated for threads created using the thread attributes object +.IR attr . +.P +The +.BR pthread_attr_getstacksize () +function returns the stack size attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR stacksize . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setstacksize () +can fail with the following error: +.TP +.B EINVAL +The stack size is less than +.B PTHREAD_STACK_MIN +(16384) bytes. +.P +On some systems, +.\" e.g., MacOS +.BR pthread_attr_setstacksize () +can fail with the error +.B EINVAL +if +.I stacksize +is not a multiple of the system page size. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setstacksize (), +.BR pthread_attr_getstacksize () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +These functions are provided since glibc 2.1. +.SH STANDARDS +POSIX.1-2001, POSIX.1-2008. +.SH NOTES +For details on the default stack size of new threads, see +.BR pthread_create (3). +.P +A thread's stack size is fixed at the time of thread creation. +Only the main thread can dynamically grow its stack. +.P +The +.BR pthread_attr_setstack (3) +function allows an application to set both the size and location +of a caller-allocated stack that is to be used by a thread. +.SH BUGS +As at glibc 2.8, +if the specified +.I stacksize +is not a multiple of +.B STACK_ALIGN +(16 bytes on most architectures), it may be rounded +.IR downward , +in violation of POSIX.1, which says that the allocated stack will +be at least +.I stacksize +bytes. +.SH EXAMPLES +See +.BR pthread_create (3). +.SH SEE ALSO +.BR getrlimit (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setguardsize (3), +.BR pthread_attr_setstack (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_cancel.3 b/man/man3/pthread_cancel.3 new file mode 100644 index 0000000..99232b4 --- /dev/null +++ b/man/man3/pthread_cancel.3 @@ -0,0 +1,237 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_cancel 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_cancel \- send a cancelation request to a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_cancel(pthread_t " thread ); +.fi +.SH DESCRIPTION +The +.BR pthread_cancel () +function sends a cancelation request to the thread +.IR thread . +Whether and when the target thread +reacts to the cancelation request depends on +two attributes that are under the control of that thread: +its cancelability +.I state +and +.IR type . +.P +A thread's cancelability state, determined by +.BR pthread_setcancelstate (3), +can be +.I enabled +(the default for new threads) or +.IR disabled . +If a thread has disabled cancelation, +then a cancelation request remains queued until the thread +enables cancelation. +If a thread has enabled cancelation, +then its cancelability type determines when cancelation occurs. +.P +A thread's cancelation type, determined by +.BR pthread_setcanceltype (3), +may be either +.I asynchronous +or +.I deferred +(the default for new threads). +Asynchronous cancelability +means that the thread can be canceled at any time +(usually immediately, but the system does not guarantee this). +Deferred cancelability means that cancelation will be delayed until +the thread next calls a function that is a +.IR "cancelation point" . +A list of functions that are or may be cancelation points is provided in +.BR pthreads (7). +.P +When a cancelation requested is acted on, the following steps occur for +.I thread +(in this order): +.IP (1) 5 +Cancelation clean-up handlers are popped +(in the reverse of the order in which they were pushed) and called. +(See +.BR pthread_cleanup_push (3).) +.IP (2) +Thread-specific data destructors are called, +in an unspecified order. +(See +.BR pthread_key_create (3).) +.IP (3) +The thread is terminated. +(See +.BR pthread_exit (3).) +.P +The above steps happen asynchronously with respect to the +.BR pthread_cancel () +call; +the return status of +.BR pthread_cancel () +merely informs the caller whether the cancelation request +was successfully queued. +.P +After a canceled thread has terminated, +a join with that thread using +.BR pthread_join (3) +obtains +.B PTHREAD_CANCELED +as the thread's exit status. +(Joining with a thread is the only way to know that cancelation +has completed.) +.SH RETURN VALUE +On success, +.BR pthread_cancel () +returns 0; +on error, it returns a nonzero error number. +.SH ERRORS +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_cancel () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, cancelation is implemented using signals. +Under the NPTL threading implementation, +the first real-time signal (i.e., signal 32) is used for this purpose. +On LinuxThreads, the second real-time signal is used, +if real-time signals are available, otherwise +.B SIGUSR2 +is used. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0 +POSIX.1-2001. +.SH EXAMPLES +The program below creates a thread and then cancels it. +The main thread joins with the canceled thread to check +that its exit status was +.BR PTHREAD_CANCELED . +The following shell session shows what happens when we run the program: +.P +.in +4n +.EX +$ ./a.out +thread_func(): started; cancelation disabled +main(): sending cancelation request +thread_func(): about to enable cancelation +main(): thread was canceled +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_cancel.c) +.EX +#include +#include +#include +#include +#include +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void * +thread_func(void *ignored_argument) +{ + int s; +\& + /* Disable cancelation for a while, so that we don\[aq]t + immediately react to a cancelation request. */ +\& + s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL); + if (s != 0) + handle_error_en(s, "pthread_setcancelstate"); +\& + printf("%s(): started; cancelation disabled\en", __func__); + sleep(5); + printf("%s(): about to enable cancelation\en", __func__); +\& + s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL); + if (s != 0) + handle_error_en(s, "pthread_setcancelstate"); +\& + /* sleep() is a cancelation point. */ +\& + sleep(1000); /* Should get canceled while we sleep */ +\& + /* Should never get here. */ +\& + printf("%s(): not canceled!\en", __func__); + return NULL; +} +\& +int +main(void) +{ + pthread_t thr; + void *res; + int s; +\& + /* Start a thread and then send it a cancelation request. */ +\& + s = pthread_create(&thr, NULL, &thread_func, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + sleep(2); /* Give thread a chance to get started */ +\& + printf("%s(): sending cancelation request\en", __func__); + s = pthread_cancel(thr); + if (s != 0) + handle_error_en(s, "pthread_cancel"); +\& + /* Join with thread to see what its exit status was. */ +\& + s = pthread_join(thr, &res); + if (s != 0) + handle_error_en(s, "pthread_join"); +\& + if (res == PTHREAD_CANCELED) + printf("%s(): thread was canceled\en", __func__); + else + printf("%s(): thread wasn\[aq]t canceled (shouldn\[aq]t happen!)\en", + __func__); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR pthread_cleanup_push (3), +.BR pthread_create (3), +.BR pthread_exit (3), +.BR pthread_join (3), +.BR pthread_key_create (3), +.BR pthread_setcancelstate (3), +.BR pthread_setcanceltype (3), +.BR pthread_testcancel (3), +.BR pthreads (7) diff --git a/man/man3/pthread_cleanup_pop.3 b/man/man3/pthread_cleanup_pop.3 new file mode 100644 index 0000000..fb0e68b --- /dev/null +++ b/man/man3/pthread_cleanup_pop.3 @@ -0,0 +1 @@ +.so man3/pthread_cleanup_push.3 diff --git a/man/man3/pthread_cleanup_pop_restore_np.3 b/man/man3/pthread_cleanup_pop_restore_np.3 new file mode 100644 index 0000000..c47e20a --- /dev/null +++ b/man/man3/pthread_cleanup_pop_restore_np.3 @@ -0,0 +1 @@ +.so man3/pthread_cleanup_push_defer_np.3 diff --git a/man/man3/pthread_cleanup_push.3 b/man/man3/pthread_cleanup_push.3 new file mode 100644 index 0000000..729e086 --- /dev/null +++ b/man/man3/pthread_cleanup_push.3 @@ -0,0 +1,319 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_cleanup_push 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_cleanup_push, pthread_cleanup_pop \- push and pop +thread cancelation clean-up handlers +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void pthread_cleanup_push(void (*" routine ")(void *), void *" arg ); +.BI "void pthread_cleanup_pop(int " execute ); +.fi +.SH DESCRIPTION +These functions manipulate the calling thread's stack of +thread-cancelation clean-up handlers. +A clean-up handler is a function that is automatically executed +when a thread is canceled (or in various other circumstances +described below); +it might, for example, unlock a mutex so that +it becomes available to other threads in the process. +.P +The +.BR pthread_cleanup_push () +function pushes +.I routine +onto the top of the stack of clean-up handlers. +When +.I routine +is later invoked, it will be given +.I arg +as its argument. +.P +The +.BR pthread_cleanup_pop () +function removes the routine at the top of the stack of clean-up handlers, +and optionally executes it if +.I execute +is nonzero. +.P +A cancelation clean-up handler is popped from the stack +and executed in the following circumstances: +.IP \[bu] 3 +When a thread is canceled, +all of the stacked clean-up handlers are popped and executed in +the reverse of the order in which they were pushed onto the stack. +.IP \[bu] +When a thread terminates by calling +.BR pthread_exit (3), +all clean-up handlers are executed as described in the preceding point. +(Clean-up handlers are +.I not +called if the thread terminates by +performing a +.I return +from the thread start function.) +.IP \[bu] +When a thread calls +.BR pthread_cleanup_pop () +with a nonzero +.I execute +argument, the top-most clean-up handler is popped and executed. +.P +POSIX.1 permits +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop () +to be implemented as macros that expand to text +containing \[aq]\fB{\fP\[aq] and \[aq]\fB}\fP\[aq], respectively. +For this reason, the caller must ensure that calls to these +functions are paired within the same function, +and at the same lexical nesting level. +(In other words, a clean-up handler is established only +during the execution of a specified section of code.) +.P +Calling +.BR longjmp (3) +.RB ( siglongjmp (3)) +produces undefined results if any call has been made to +.BR pthread_cleanup_push () +or +.BR pthread_cleanup_pop () +without the matching call of the pair since the jump buffer +was filled by +.BR setjmp (3) +.RB ( sigsetjmp (3)). +Likewise, calling +.BR longjmp (3) +.RB ( siglongjmp (3)) +from inside a clean-up handler produces undefined results +unless the jump buffer was also filled by +.BR setjmp (3) +.RB ( sigsetjmp (3)) +inside the handler. +.SH RETURN VALUE +These functions do not return a value. +.SH ERRORS +There are no errors. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_cleanup_push (), +.BR pthread_cleanup_pop () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On glibc, the +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop () +functions +.I are +implemented as macros that expand to text +containing \[aq]\fB{\fP\[aq] and \[aq]\fB}\fP\[aq], respectively. +This means that variables declared within the scope of +paired calls to these functions will be visible within only that scope. +.P +POSIX.1 +.\" The text was actually added in the 2004 TC2 +says that the effect of using +.IR return , +.IR break , +.IR continue , +or +.I goto +to prematurely leave a block bracketed +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop () +is undefined. +Portable applications should avoid doing this. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +glibc 2.0. +.SH EXAMPLES +The program below provides a simple example of the use of the functions +described in this page. +The program creates a thread that executes a loop bracketed by +.BR pthread_cleanup_push () +and +.BR pthread_cleanup_pop (). +This loop increments a global variable, +.IR cnt , +once each second. +Depending on what command-line arguments are supplied, +the main thread sends the other thread a cancelation request, +or sets a global variable that causes the other thread +to exit its loop and terminate normally (by doing a +.IR return ). +.P +In the following shell session, +the main thread sends a cancelation request to the other thread: +.P +.in +4n +.EX +$ \fB./a.out\fP +New thread started +cnt = 0 +cnt = 1 +Canceling thread +Called clean\-up handler +Thread was canceled; cnt = 0 +.EE +.in +.P +From the above, we see that the thread was canceled, +and that the cancelation clean-up handler was called +and it reset the value of the global variable +.I cnt +to 0. +.P +In the next run, the main program sets a +global variable that causes other thread to terminate normally: +.P +.in +4n +.EX +$ \fB./a.out x\fP +New thread started +cnt = 0 +cnt = 1 +Thread terminated normally; cnt = 2 +.EE +.in +.P +From the above, we see that the clean-up handler was not executed (because +.I cleanup_pop_arg +was 0), and therefore the value of +.I cnt +was not reset. +.P +In the next run, the main program sets a global variable that +causes the other thread to terminate normally, +and supplies a nonzero value for +.IR cleanup_pop_arg : +.P +.in +4n +.EX +$ \fB./a.out x 1\fP +New thread started +cnt = 0 +cnt = 1 +Called clean\-up handler +Thread terminated normally; cnt = 0 +.EE +.in +.P +In the above, we see that although the thread was not canceled, +the clean-up handler was executed, because the argument given to +.BR pthread_cleanup_pop () +was nonzero. +.SS Program source +\& +.\" SRC BEGIN (pthread_cleanup_push.c) +.EX +#include +#include +#include +#include +#include +#include +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static int done = 0; +static int cleanup_pop_arg = 0; +static int cnt = 0; +\& +static void +cleanup_handler(void *arg) +{ + printf("Called clean\-up handler\en"); + cnt = 0; +} +\& +static void * +thread_start(void *arg) +{ + time_t curr; +\& + printf("New thread started\en"); +\& + pthread_cleanup_push(cleanup_handler, NULL); +\& + curr = time(NULL); +\& + while (!done) { + pthread_testcancel(); /* A cancelation point */ + if (curr < time(NULL)) { + curr = time(NULL); + printf("cnt = %d\en", cnt); /* A cancelation point */ + cnt++; + } + } +\& + pthread_cleanup_pop(cleanup_pop_arg); + return NULL; +} +\& +int +main(int argc, char *argv[]) +{ + pthread_t thr; + int s; + void *res; +\& + s = pthread_create(&thr, NULL, thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + sleep(2); /* Allow new thread to run a while */ +\& + if (argc > 1) { + if (argc > 2) + cleanup_pop_arg = atoi(argv[2]); + done = 1; +\& + } else { + printf("Canceling thread\en"); + s = pthread_cancel(thr); + if (s != 0) + handle_error_en(s, "pthread_cancel"); + } +\& + s = pthread_join(thr, &res); + if (s != 0) + handle_error_en(s, "pthread_join"); +\& + if (res == PTHREAD_CANCELED) + printf("Thread was canceled; cnt = %d\en", cnt); + else + printf("Thread terminated normally; cnt = %d\en", cnt); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push_defer_np (3), +.BR pthread_setcancelstate (3), +.BR pthread_testcancel (3), +.BR pthreads (7) diff --git a/man/man3/pthread_cleanup_push_defer_np.3 b/man/man3/pthread_cleanup_push_defer_np.3 new file mode 100644 index 0000000..d1d2792 --- /dev/null +++ b/man/man3/pthread_cleanup_push_defer_np.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_cleanup_push_defer_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_cleanup_push_defer_np, pthread_cleanup_pop_restore_np \- push and pop +thread cancelation clean-up handlers while saving cancelability type +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void pthread_cleanup_push_defer_np(void (*" routine ")(void *), void *" arg ); +.BI "void pthread_cleanup_pop_restore_np(int " execute ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_cleanup_push_defer_np (), +.BR pthread_cleanup_pop_defer_np (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +These functions are the same as +.BR pthread_cleanup_push (3) +and +.BR pthread_cleanup_pop (3), +except for the differences noted on this page. +.P +Like +.BR pthread_cleanup_push (3), +.BR pthread_cleanup_push_defer_np () +pushes +.I routine +onto the thread's stack of cancelation clean-up handlers. +In addition, it also saves the thread's current cancelability type, +and sets the cancelability type to "deferred" (see +.BR pthread_setcanceltype (3)); +this ensures that cancelation clean-up will occur +even if the thread's cancelability type was "asynchronous" +before the call. +.P +Like +.BR pthread_cleanup_pop (3), +.BR pthread_cleanup_pop_restore_np () +pops the top-most clean-up handler from the thread's +stack of cancelation clean-up handlers. +In addition, it restores the thread's cancelability +type to its value at the time of the matching +.BR pthread_cleanup_push_defer_np (). +.P +The caller must ensure that calls to these +functions are paired within the same function, +and at the same lexical nesting level. +Other restrictions apply, as described in +.BR pthread_cleanup_push (3). +.P +This sequence of calls: +.P +.in +4n +.EX +pthread_cleanup_push_defer_np(routine, arg); +pthread_cleanup_pop_restore_np(execute); +.EE +.in +.P +is equivalent to (but shorter and more efficient than): +.P +.\" As far as I can see, LinuxThreads reverses the two substeps +.\" in the push and pop below. +.in +4n +.EX +int oldtype; +\& +pthread_cleanup_push(routine, arg); +pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype); +\&... +pthread_setcanceltype(oldtype, NULL); +pthread_cleanup_pop(execute); +.EE +.in +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.0 +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_setcancelstate (3), +.BR pthread_testcancel (3), +.BR pthreads (7) diff --git a/man/man3/pthread_cond_broadcast.3 b/man/man3/pthread_cond_broadcast.3 new file mode 100644 index 0000000..0fe85ad --- /dev/null +++ b/man/man3/pthread_cond_broadcast.3 @@ -0,0 +1 @@ +.so man3/pthread_cond_init.3 diff --git a/man/man3/pthread_cond_destroy.3 b/man/man3/pthread_cond_destroy.3 new file mode 100644 index 0000000..0fe85ad --- /dev/null +++ b/man/man3/pthread_cond_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_cond_init.3 diff --git a/man/man3/pthread_cond_init.3 b/man/man3/pthread_cond_init.3 new file mode 100644 index 0000000..0b7468d --- /dev/null +++ b/man/man3/pthread_cond_init.3 @@ -0,0 +1,268 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_cond_init 3 2024-05-19 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_cond_init, +pthread_cond_signal, +pthread_cond_broadcast, +pthread_cond_wait, +pthread_cond_timedwait, +pthread_cond_destroy +\- +operations on conditions +. +. +.SH SYNOPSIS +.nf +.B #include +.P +.BI "pthread_cond_t " cond " = PTHREAD_COND_INITIALIZER;" +.P +.BI "int pthread_cond_init(pthread_cond_t *" cond , +.BI " pthread_condattr_t *" cond_attr ); +.BI "int pthread_cond_signal(pthread_cond_t *" cond ); +.BI "int pthread_cond_broadcast(pthread_cond_t *" cond ); +.BI "int pthread_cond_wait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ); +.BI "int pthread_cond_timedwait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex , +.BI " const struct timespec *" abstime ); +.BI "int pthread_cond_destroy(pthread_cond_t *" cond ); +.fi +. +. +.SH DESCRIPTION +A condition (short for ``condition variable'') +is a synchronization device that allows threads +to suspend execution and relinquish the processors +until some predicate on shared data is satisfied. +The basic operations on conditions are: +signal the condition (when the predicate becomes true), +and wait for the condition, +suspending the thread execution until another thread signals the condition. +.P +A condition variable must always be associated with a mutex, +to avoid the race condition where +a thread prepares to wait on a condition variable +and another thread signals the condition +just before the first thread actually waits on it. +.P +\fBpthread_cond_init\fP initializes the condition variable \fIcond\fP, +using the condition attributes specified in \fIcond_attr\fP, +or default attributes if \fIcond_attr\fP is \fBNULL\fP. +The LinuxThreads implementation supports no attributes for conditions, +hence the \fIcond_attr\fP parameter is actually ignored. +.P +Variables of type \fBpthread_cond_t\fP can also be initialized statically, +using the constant \fBPTHREAD_COND_INITIALIZER\fP. +.P +\fBpthread_cond_signal\fP restarts one of the threads that +are waiting on the condition variable \fIcond\fP. +If no threads are waiting on \fIcond\fP, +nothing happens. +If several threads are waiting on \fIcond\fP, +exactly one is restarted, +but it is not specified which. +.P +\fBpthread_cond_broadcast\fP restarts all the threads that +are waiting on the condition variable \fIcond\fP. +Nothing happens if no threads are waiting on \fIcond\fP. +.P +\fBpthread_cond_wait\fP atomically unlocks the \fImutex\fP +(as per \fBpthread_unlock_mutex\fP) +and waits for the condition variable \fIcond\fP to be signaled. +The thread execution is suspended and does not consume any CPU time +until the condition variable is signaled. +The \fImutex\fP must be locked by the calling thread +on entrance to \fBpthread_cond_wait\fP. +Before returning to the calling thread, +\fBpthread_cond_wait\fP re-acquires \fImutex\fP +(as per \fBpthread_lock_mutex\fP). +.P +Unlocking the mutex and suspending on the condition variable is done atomically. +Thus, +if all threads always acquire the mutex before signaling the condition, +this guarantees that the condition cannot be signaled (and thus ignored) +between the time a thread locks the mutex +and the time it waits on the condition variable. +.P +\fBpthread_cond_timedwait\fP atomically unlocks \fImutex\fP +and waits on \fIcond\fP, +as \fBpthread_cond_wait\fP does, +but it also bounds the duration of the wait. +If \fIcond\fP has not been signaled +within the amount of time specified by \fIabstime\fP, +the mutex \fImutex\fP is re-acquired +and \fBpthread_cond_timedwait\fP returns the error \fBETIMEDOUT\fP. +The \fIabstime\fP parameter specifies an absolute time, +with the same origin as \fBtime\fP(2) and \fBgettimeofday\fP(2): +an \fIabstime\fP of 0 +corresponds to 00:00:00 GMT, January 1, 1970. +.P +\fBpthread_cond_destroy\fP destroys a condition variable, +freeing the resources it might hold. +No threads must be waiting on the condition variable +on entrance to \fBpthread_cond_destroy\fP. +In the LinuxThreads implementation, +no resources are associated with condition variables, +thus \fBpthread_cond_destroy\fP actually does nothing +except checking that the condition has no waiting threads. +. +. +.SH CANCELLATION +\fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP +are cancelation points. +If a thread is cancelled while suspended in one of these functions, +the thread immediately resumes execution, +then locks again the \fImutex\fP +argument to \fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP, +and finally executes the cancelation. +Consequently, +cleanup handlers are assured that \fImutex\fP is locked +when they are called. +. +. +.SH "ASYNC-SIGNAL SAFETY" +The condition functions are not async-signal safe, +and should not be called from a signal handler. +In particular, +calling \fBpthread_cond_signal\fP or \fBpthread_cond_broadcast\fP +from a signal handler +may deadlock the calling thread. +. +. +.SH "RETURN VALUE" +All condition variable functions return 0 on success +and a non-zero error code on error. +. +. +.SH ERRORS +\fBpthread_cond_init\fP, +\fBpthread_cond_signal\fP, +\fBpthread_cond_broadcast\fP, +and \fBpthread_cond_wait\fP +never return an error code. +.P +The \fBpthread_cond_timedwait\fP function returns +the following error codes on error: +.RS +.TP +\fBETIMEDOUT\fP +The condition variable was not signaled +until the timeout specified by \fIabstime\fP. +.TP +\fBEINTR\fP +\fBpthread_cond_timedwait\fP was interrupted by a signal. +.RE +.P +The \fBpthread_cond_destroy\fP function returns +the following error code on error: +.RS +.TP +\fBEBUSY\fP +Some threads are currently waiting on \fIcond\fP. +.RE +. +. +.SH "SEE ALSO" +\fBpthread_condattr_init\fP(3), +\fBpthread_mutex_lock\fP(3), +\fBpthread_mutex_unlock\fP(3), +\fBgettimeofday\fP(2), +\fBnanosleep\fP(2). +. +. +.SH EXAMPLE +Consider two shared variables \fIx\fP and \fIy\fP, +protected by the mutex \fImut\fP, +and a condition variable \fIcond\fP +that is to be signaled +whenever \fIx\fP becomes greater than \fIy\fP. +.P +.RS +.ft 3 +.nf +.sp +int x,y; +pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; +pthread_cond_t cond = PTHREAD_COND_INITIALIZER; +.ft +.P +.RE +.fi +.P +Waiting until \fIx\fP is greater than \fIy\fP is performed as follows: +.P +.RS +.ft 3 +.nf +.sp +pthread_mutex_lock(&mut); +while (x <= y) { + pthread_cond_wait(&cond, &mut); +} +/* operate on x and y */ +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi +.P +Modifications on \fIx\fP and \fIy\fP +that may cause \fIx\fP to become greater than \fIy\fP +should signal the condition if needed: +.P +.RS +.ft 3 +.nf +.sp +pthread_mutex_lock(&mut); +/* modify x and y */ +if (x > y) pthread_cond_broadcast(&cond); +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi +.P +If it can be proved that at most one waiting thread needs to be waken up +(for instance, +if there are only two threads communicating through \fIx\fP and \fIy\fP), +\fBpthread_cond_signal\fP can be used as +a slightly more efficient alternative to \fBpthread_cond_broadcast\fP. +In doubt, +use \fBpthread_cond_broadcast\fP. +.P +To wait for \fIx\fP to become greater than \fIy\fP +with a timeout of 5 seconds, +do: +.P +.RS +.ft 3 +.nf +.sp +struct timeval now; +struct timespec timeout; +int retcode; +\& +pthread_mutex_lock(&mut); +gettimeofday(&now); +timeout.tv_sec = now.tv_sec + 5; +timeout.tv_nsec = now.tv_usec * 1000; +retcode = 0; +while (x <= y && retcode != ETIMEDOUT) { + retcode = pthread_cond_timedwait(&cond, &mut, &timeout); +} +if (retcode == ETIMEDOUT) { + /* timeout occurred */ +} else { + /* operate on x and y */ +} +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi diff --git a/man/man3/pthread_cond_signal.3 b/man/man3/pthread_cond_signal.3 new file mode 100644 index 0000000..0fe85ad --- /dev/null +++ b/man/man3/pthread_cond_signal.3 @@ -0,0 +1 @@ +.so man3/pthread_cond_init.3 diff --git a/man/man3/pthread_cond_timedwait.3 b/man/man3/pthread_cond_timedwait.3 new file mode 100644 index 0000000..0fe85ad --- /dev/null +++ b/man/man3/pthread_cond_timedwait.3 @@ -0,0 +1 @@ +.so man3/pthread_cond_init.3 diff --git a/man/man3/pthread_cond_wait.3 b/man/man3/pthread_cond_wait.3 new file mode 100644 index 0000000..0fe85ad --- /dev/null +++ b/man/man3/pthread_cond_wait.3 @@ -0,0 +1 @@ +.so man3/pthread_cond_init.3 diff --git a/man/man3/pthread_condattr_destroy.3 b/man/man3/pthread_condattr_destroy.3 new file mode 100644 index 0000000..ae5c63c --- /dev/null +++ b/man/man3/pthread_condattr_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_condattr_init.3 diff --git a/man/man3/pthread_condattr_init.3 b/man/man3/pthread_condattr_init.3 new file mode 100644 index 0000000..cf7fd33 --- /dev/null +++ b/man/man3/pthread_condattr_init.3 @@ -0,0 +1,48 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_condattr_init 3 2024-05-02 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_condattr_init, +pthread_condattr_destroy +\- +condition creation attributes +. +. +.SH SYNOPSIS +.B #include +.P +.BI "int pthread_condattr_init(pthread_condattr_t *" attr ");" +.BI "int pthread_condattr_destroy(pthread_condattr_t *" attr ");" +. +. +.SH DESCRIPTION +Condition attributes can be specified at condition creation time, +by passing a condition attribute object +as second argument to \fBpthread_cond_init\fP(3). +Passing \fBNULL\fP is equivalent to +passing a condition attribute object +with all attributes set to their default values. +.P +The LinuxThreads implementation supports no attributes for conditions. +The functions on condition attributes are +included only for compliance with the POSIX standard. +.P +\fBpthread_condattr_init\fP +initializes the condition attribute object \fIattr\fP +and fills it with default values for the attributes. +\fBpthread_condattr_destroy\fP destroys a condition attribute object, +which must not be reused until it is reinitialized. +Both functions do nothing in the LinuxThreads implementation. +. +. +.SH "RETURN VALUE" +\fBpthread_condattr_init\fP and \fBpthread_condattr_destroy\fP always return 0. +. +. +.SH "SEE ALSO" +\fBpthread_cond_init\fP(3). diff --git a/man/man3/pthread_create.3 b/man/man3/pthread_create.3 new file mode 100644 index 0000000..a7f33de --- /dev/null +++ b/man/man3/pthread_create.3 @@ -0,0 +1,395 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_create 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_create \- create a new thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_create(pthread_t *restrict " thread , +.BI " const pthread_attr_t *restrict " attr , +.BI " void *(*" start_routine ")(void *)," +.BI " void *restrict " arg ); +.fi +.SH DESCRIPTION +The +.BR pthread_create () +function starts a new thread in the calling process. +The new thread starts execution by invoking +.IR start_routine (); +.I arg +is passed as the sole argument of +.IR start_routine (). +.P +The new thread terminates in one of the following ways: +.IP \[bu] 3 +It calls +.BR pthread_exit (3), +specifying an exit status value that is available to another thread +in the same process that calls +.BR pthread_join (3). +.IP \[bu] +It returns from +.IR start_routine (). +This is equivalent to calling +.BR pthread_exit (3) +with the value supplied in the +.I return +statement. +.IP \[bu] +It is canceled (see +.BR pthread_cancel (3)). +.IP \[bu] +Any of the threads in the process calls +.BR exit (3), +or the main thread performs a return from +.IR main (). +This causes the termination of all threads in the process. +.P +The +.I attr +argument points to a +.I pthread_attr_t +structure whose contents are used at thread creation time to +determine attributes for the new thread; +this structure is initialized using +.BR pthread_attr_init (3) +and related functions. +If +.I attr +is NULL, +then the thread is created with default attributes. +.P +Before returning, a successful call to +.BR pthread_create () +stores the ID of the new thread in the buffer pointed to by +.IR thread ; +this identifier is used to refer to the thread +in subsequent calls to other pthreads functions. +.P +The new thread inherits a copy of the creating thread's signal mask +.RB ( pthread_sigmask (3)). +The set of pending signals for the new thread is empty +.RB ( sigpending (2)). +The new thread does not inherit the creating thread's +alternate signal stack +.RB ( sigaltstack (2)). +.P +The new thread inherits the calling thread's floating-point environment +.RB ( fenv (3)). +.P +The initial value of the new thread's CPU-time clock is 0 +(see +.BR pthread_getcpuclockid (3)). +.\" CLOCK_THREAD_CPUTIME_ID in clock_gettime(2) +.SS Linux-specific details +The new thread inherits copies of the calling thread's capability sets +(see +.BR capabilities (7)) +and CPU affinity mask (see +.BR sched_setaffinity (2)). +.SH RETURN VALUE +On success, +.BR pthread_create () +returns 0; +on error, it returns an error number, and the contents of +.I *thread +are undefined. +.SH ERRORS +.TP +.B EAGAIN +Insufficient resources to create another thread. +.TP +.B EAGAIN +.\" NOTE! The following should match the description in fork(2) +A system-imposed limit on the number of threads was encountered. +There are a number of limits that may trigger this error: the +.B RLIMIT_NPROC +soft resource limit (set via +.BR setrlimit (2)), +which limits the number of processes and threads for a real user ID, +was reached; +the kernel's system-wide limit on the number of processes and threads, +.IR /proc/sys/kernel/threads\-max , +was reached (see +.BR proc (5)); +or the maximum number of PIDs, +.IR /proc/sys/kernel/pid_max , +was reached (see +.BR proc (5)). +.TP +.B EINVAL +Invalid settings in +.IR attr . +.TP +.\" FIXME . Test the following +.B EPERM +No permission to set the scheduling policy and parameters specified in +.IR attr . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_create () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +See +.BR pthread_self (3) +for further information on the thread ID returned in +.I *thread +by +.BR pthread_create (). +Unless real-time scheduling policies are being employed, +after a call to +.BR pthread_create (), +it is indeterminate which thread\[em]the caller or the new thread\[em]will +next execute. +.P +A thread may either be +.I joinable +or +.IR detached . +If a thread is joinable, then another thread can call +.BR pthread_join (3) +to wait for the thread to terminate and fetch its exit status. +Only when a terminated joinable thread has been joined are +the last of its resources released back to the system. +When a detached thread terminates, +its resources are automatically released back to the system: +it is not possible to join with the thread in order to obtain +its exit status. +Making a thread detached is useful for some types of daemon threads +whose exit status the application does not need to care about. +By default, a new thread is created in a joinable state, unless +.I attr +was set to create the thread in a detached state (using +.BR pthread_attr_setdetachstate (3)). +.P +Under the NPTL threading implementation, if the +.B RLIMIT_STACK +soft resource limit +.I at the time the program started +has any value other than "unlimited", +then it determines the default stack size of new threads. +Using +.BR pthread_attr_setstacksize (3), +the stack size attribute can be explicitly set in the +.I attr +argument used to create a thread, +in order to obtain a stack size other than the default. +If the +.B RLIMIT_STACK +resource limit is set to "unlimited", +a per-architecture value is used for the stack size: +2 MB on most architectures; 4 MB on POWER and Sparc-64. +.SH BUGS +In the obsolete LinuxThreads implementation, +each of the threads in a process has a different process ID. +This is in violation of the POSIX threads specification, +and is the source of many other nonconformances to the standard; see +.BR pthreads (7). +.SH EXAMPLES +The program below demonstrates the use of +.BR pthread_create (), +as well as a number of other functions in the pthreads API. +.P +In the following run, +on a system providing the NPTL threading implementation, +the stack size defaults to the value given by the +"stack size" resource limit: +.P +.in +4n +.EX +.RB "$" " ulimit \-s" +8192 # The stack size limit is 8 MB (0x800000 bytes) +.RB "$" " ./a.out hola salut servus" +Thread 1: top of stack near 0xb7dd03b8; argv_string=hola +Thread 2: top of stack near 0xb75cf3b8; argv_string=salut +Thread 3: top of stack near 0xb6dce3b8; argv_string=servus +Joined with thread 1; returned value was HOLA +Joined with thread 2; returned value was SALUT +Joined with thread 3; returned value was SERVUS +.EE +.in +.P +In the next run, the program explicitly sets a stack size of 1\ MB (using +.BR pthread_attr_setstacksize (3)) +for the created threads: +.P +.in +4n +.EX +.RB "$" " ./a.out \-s 0x100000 hola salut servus" +Thread 1: top of stack near 0xb7d723b8; argv_string=hola +Thread 2: top of stack near 0xb7c713b8; argv_string=salut +Thread 3: top of stack near 0xb7b703b8; argv_string=servus +Joined with thread 1; returned value was HOLA +Joined with thread 2; returned value was SALUT +Joined with thread 3; returned value was SERVUS +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_create.c) +.EX +#include +#include +#include +#include +#include +#include +#include +#include +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +struct thread_info { /* Used as argument to thread_start() */ + pthread_t thread_id; /* ID returned by pthread_create() */ + int thread_num; /* Application\-defined thread # */ + char *argv_string; /* From command\-line argument */ +}; +\& +/* Thread start function: display address near top of our stack, + and return upper\-cased copy of argv_string. */ +\& +static void * +thread_start(void *arg) +{ + struct thread_info *tinfo = arg; + char *uargv; +\& + printf("Thread %d: top of stack near %p; argv_string=%s\en", + tinfo\->thread_num, (void *) &tinfo, tinfo\->argv_string); +\& + uargv = strdup(tinfo\->argv_string); + if (uargv == NULL) + handle_error("strdup"); +\& + for (char *p = uargv; *p != \[aq]\e0\[aq]; p++) + *p = toupper(*p); +\& + return uargv; +} +\& +int +main(int argc, char *argv[]) +{ + int s, opt; + void *res; + size_t num_threads; + ssize_t stack_size; + pthread_attr_t attr; + struct thread_info *tinfo; +\& + /* The "\-s" option specifies a stack size for our threads. */ +\& + stack_size = \-1; + while ((opt = getopt(argc, argv, "s:")) != \-1) { + switch (opt) { + case \[aq]s\[aq]: + stack_size = strtoul(optarg, NULL, 0); + break; +\& + default: + fprintf(stderr, "Usage: %s [\-s stack\-size] arg...\en", + argv[0]); + exit(EXIT_FAILURE); + } + } +\& + num_threads = argc \- optind; +\& + /* Initialize thread creation attributes. */ +\& + s = pthread_attr_init(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_init"); +\& + if (stack_size > 0) { + s = pthread_attr_setstacksize(&attr, stack_size); + if (s != 0) + handle_error_en(s, "pthread_attr_setstacksize"); + } +\& + /* Allocate memory for pthread_create() arguments. */ +\& + tinfo = calloc(num_threads, sizeof(*tinfo)); + if (tinfo == NULL) + handle_error("calloc"); +\& + /* Create one thread for each command\-line argument. */ +\& + for (size_t tnum = 0; tnum < num_threads; tnum++) { + tinfo[tnum].thread_num = tnum + 1; + tinfo[tnum].argv_string = argv[optind + tnum]; +\& + /* The pthread_create() call stores the thread ID into + corresponding element of tinfo[]. */ +\& + s = pthread_create(&tinfo[tnum].thread_id, &attr, + &thread_start, &tinfo[tnum]); + if (s != 0) + handle_error_en(s, "pthread_create"); + } +\& + /* Destroy the thread attributes object, since it is no + longer needed. */ +\& + s = pthread_attr_destroy(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); +\& + /* Now join with each thread, and display its returned value. */ +\& + for (size_t tnum = 0; tnum < num_threads; tnum++) { + s = pthread_join(tinfo[tnum].thread_id, &res); + if (s != 0) + handle_error_en(s, "pthread_join"); +\& + printf("Joined with thread %d; returned value was %s\en", + tinfo[tnum].thread_num, (char *) res); + free(res); /* Free memory allocated by thread */ + } +\& + free(tinfo); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR getrlimit (2), +.BR pthread_attr_init (3), +.BR pthread_cancel (3), +.BR pthread_detach (3), +.BR pthread_equal (3), +.BR pthread_exit (3), +.BR pthread_getattr_np (3), +.BR pthread_join (3), +.BR pthread_self (3), +.BR pthread_setattr_default_np (3), +.BR pthreads (7) diff --git a/man/man3/pthread_detach.3 b/man/man3/pthread_detach.3 new file mode 100644 index 0000000..b3c924d --- /dev/null +++ b/man/man3/pthread_detach.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_detach 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_detach \- detach a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_detach(pthread_t " thread ); +.fi +.SH DESCRIPTION +The +.BR pthread_detach () +function marks the thread identified by +.I thread +as detached. +When a detached thread terminates, +its resources are automatically released back to the system without +the need for another thread to join with the terminated thread. +.P +Attempting to detach an already detached thread results +in unspecified behavior. +.SH RETURN VALUE +On success, +.BR pthread_detach () +returns 0; +on error, it returns an error number. +.SH ERRORS +.TP +.B EINVAL +.I thread +is not a joinable thread. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_detach () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Once a thread has been detached, it can't be joined with +.BR pthread_join (3) +or be made joinable again. +.P +A new thread can be created in a detached state using +.BR pthread_attr_setdetachstate (3) +to set the detached attribute of the +.I attr +argument of +.BR pthread_create (3). +.P +The detached attribute merely determines the behavior of the system +when the thread terminates; +it does not prevent the thread from being terminated +if the process terminates using +.BR exit (3) +(or equivalently, if the main thread returns). +.P +Either +.BR pthread_join (3) +or +.BR pthread_detach () +should be called for each thread that an application creates, +so that system resources for the thread can be released. +(But note that the resources of any threads for which one of these +actions has not been done will be freed when the process terminates.) +.SH EXAMPLES +The following statement detaches the calling thread: +.P +.in +4n +.EX +pthread_detach(pthread_self()); +.EE +.in +.SH SEE ALSO +.BR pthread_attr_setdetachstate (3), +.BR pthread_cancel (3), +.BR pthread_create (3), +.BR pthread_exit (3), +.BR pthread_join (3), +.BR pthreads (7) diff --git a/man/man3/pthread_equal.3 b/man/man3/pthread_equal.3 new file mode 100644 index 0000000..f8a861b --- /dev/null +++ b/man/man3/pthread_equal.3 @@ -0,0 +1,57 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_equal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_equal \- compare thread IDs +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_equal(pthread_t " t1 ", pthread_t " t2 ); +.fi +.SH DESCRIPTION +The +.BR pthread_equal () +function compares two thread identifiers. +.SH RETURN VALUE +If the two thread IDs are equal, +.BR pthread_equal () +returns a nonzero value; otherwise, it returns 0. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_equal () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The +.BR pthread_equal () +function is necessary because thread IDs should be considered opaque: +there is no portable way for applications to directly compare two +.I pthread_t +values. +.SH SEE ALSO +.BR pthread_create (3), +.BR pthread_self (3), +.BR pthreads (7) diff --git a/man/man3/pthread_exit.3 b/man/man3/pthread_exit.3 new file mode 100644 index 0000000..479e40a --- /dev/null +++ b/man/man3/pthread_exit.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_exit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_exit \- terminate calling thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[noreturn]] void pthread_exit(void *" retval ); +.fi +.SH DESCRIPTION +The +.BR pthread_exit () +function terminates the calling thread and returns a value via +.I retval +that (if the thread is joinable) +is available to another thread in the same process that calls +.BR pthread_join (3). +.P +Any clean-up handlers established by +.BR pthread_cleanup_push (3) +that have not yet been popped, +are popped (in the reverse of the order in which they were pushed) +and executed. +If the thread has any thread-specific data, then, +after the clean-up handlers have been executed, +the corresponding destructor functions are called, +in an unspecified order. +.P +When a thread terminates, +process-shared resources (e.g., mutexes, condition variables, +semaphores, and file descriptors) are not released, +and functions registered using +.BR atexit (3) +are not called. +.P +After the last thread in a process terminates, +the process terminates as by calling +.BR exit (3) +with an exit status of zero; +thus, process-shared resources +are released and functions registered using +.BR atexit (3) +are called. +.SH RETURN VALUE +This function does not return to the caller. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_exit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Performing a return from the start function of any thread other +than the main thread results in an implicit call to +.BR pthread_exit (), +using the function's return value as the thread's exit status. +.P +To allow other threads to continue execution, +the main thread should terminate by calling +.BR pthread_exit () +rather than +.BR exit (3). +.P +The value pointed to by +.I retval +should not be located on the calling thread's stack, +since the contents of that stack are undefined after the thread terminates. +.SH BUGS +Currently, +.\" Linux 2.6.27 +there are limitations in the kernel implementation logic for +.BR wait (2)ing +on a stopped thread group with a dead thread group leader. +This can manifest in problems such as a locked terminal if a stop signal is +sent to a foreground process whose thread group leader has already called +.BR pthread_exit (). +.\" FIXME . review a later kernel to see if this gets fixed +.\" http://thread.gmane.org/gmane.linux.kernel/611611 +.\" http://marc.info/?l=linux-kernel&m=122525468300823&w=2 +.SH SEE ALSO +.BR pthread_create (3), +.BR pthread_join (3), +.BR pthreads (7) diff --git a/man/man3/pthread_getaffinity_np.3 b/man/man3/pthread_getaffinity_np.3 new file mode 100644 index 0000000..c4cd6af --- /dev/null +++ b/man/man3/pthread_getaffinity_np.3 @@ -0,0 +1 @@ +.so man3/pthread_setaffinity_np.3 diff --git a/man/man3/pthread_getattr_default_np.3 b/man/man3/pthread_getattr_default_np.3 new file mode 100644 index 0000000..c185c96 --- /dev/null +++ b/man/man3/pthread_getattr_default_np.3 @@ -0,0 +1,192 @@ +'\" t +.\" Copyright (c) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_getattr_default_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_getattr_default_np, pthread_setattr_default_np, \- +get or set default thread-creation attributes +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int pthread_getattr_default_np(pthread_attr_t *" attr ); +.BI "int pthread_setattr_default_np(const pthread_attr_t *" attr ); +.fi +.SH DESCRIPTION +The +.BR pthread_setattr_default_np () +function sets the default attributes used for creation of a new +thread\[em]that is, the attributes that are used when +.BR pthread_create (3) +is called with a second argument that is NULL. +The default attributes are set using the attributes supplied in +.IR *attr , +a previously initialized thread attributes object. +Note the following details about the supplied attributes object: +.IP \[bu] 3 +The attribute settings in the object must be valid. +.IP \[bu] +The +.I stack address +attribute must not be set in the object. +.IP \[bu] +Setting the +.I stack size +attribute to zero means leave the default stack size unchanged. +.P +The +.BR pthread_getattr_default_np () +function initializes the thread attributes object referred to by +.I attr +so that it contains the default attributes used for thread creation. +.SH ERRORS +.TP +.B EINVAL +.RB ( pthread_setattr_default_np ()) +One of the attribute settings in +.I attr +is invalid, or the stack address attribute is set in +.IR attr . +.TP +.B ENOMEM +.\" Can happen (but unlikely) while trying to allocate memory for cpuset +.RB ( pthread_setattr_default_np ()) +Insufficient memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_getattr_default_np (), +.BR pthread_setattr_default_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in their names. +.SH HISTORY +glibc 2.18. +.SH EXAMPLES +The program below uses +.BR pthread_getattr_default_np () +to fetch the default thread-creation attributes and then displays +various settings from the returned thread attributes object. +When running the program, we see the following output: +.P +.in +4n +.EX +$ \fB./a.out\fP +Stack size: 8388608 +Guard size: 4096 +Scheduling policy: SCHED_OTHER +Scheduling priority: 0 +Detach state: JOINABLE +Inherit scheduler: INHERIT +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_getattr_default_np.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +\& +static void +display_pthread_attr(pthread_attr_t *attr) +{ + int s; + size_t stacksize; + size_t guardsize; + int policy; + struct sched_param schedparam; + int detachstate; + int inheritsched; +\& + s = pthread_attr_getstacksize(attr, &stacksize); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getstacksize"); + printf("Stack size: %zu\en", stacksize); +\& + s = pthread_attr_getguardsize(attr, &guardsize); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getguardsize"); + printf("Guard size: %zu\en", guardsize); +\& + s = pthread_attr_getschedpolicy(attr, &policy); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getschedpolicy"); + printf("Scheduling policy: %s\en", + (policy == SCHED_FIFO) ? "SCHED_FIFO" : + (policy == SCHED_RR) ? "SCHED_RR" : + (policy == SCHED_OTHER) ? "SCHED_OTHER" : "[unknown]"); +\& + s = pthread_attr_getschedparam(attr, &schedparam); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getschedparam"); + printf("Scheduling priority: %d\en", schedparam.sched_priority); +\& + s = pthread_attr_getdetachstate(attr, &detachstate); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getdetachstate"); + printf("Detach state: %s\en", + (detachstate == PTHREAD_CREATE_DETACHED) ? "DETACHED" : + (detachstate == PTHREAD_CREATE_JOINABLE) ? "JOINABLE" : + "???"); +\& + s = pthread_attr_getinheritsched(attr, &inheritsched); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getinheritsched"); + printf("Inherit scheduler: %s\en", + (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" : + (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" : + "???"); +} +\& +int +main(void) +{ + int s; + pthread_attr_t attr; +\& + s = pthread_getattr_default_np(&attr); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_getattr_default_np"); +\& + display_pthread_attr(&attr); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_getaffinity_np (3), +.BR pthread_attr_getdetachstate (3), +.BR pthread_attr_getguardsize (3), +.BR pthread_attr_getinheritsched (3), +.BR pthread_attr_getschedparam (3), +.BR pthread_attr_getschedpolicy (3), +.BR pthread_attr_getscope (3), +.BR pthread_attr_getstack (3), +.BR pthread_attr_getstackaddr (3), +.BR pthread_attr_getstacksize (3), +.BR pthread_attr_init (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_getattr_np.3 b/man/man3/pthread_getattr_np.3 new file mode 100644 index 0000000..6135cc4 --- /dev/null +++ b/man/man3/pthread_getattr_np.3 @@ -0,0 +1,356 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_getattr_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_getattr_np \- get attributes of created thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int pthread_getattr_np(pthread_t " thread ", pthread_attr_t *" attr ); +.fi +.SH DESCRIPTION +The +.BR pthread_getattr_np () +function initializes the thread attributes object referred to by +.I attr +so that it contains actual attribute values describing the running thread +.IR thread . +.P +The returned attribute values may differ from +the corresponding attribute values passed in the +.I attr +object that was used to create the thread using +.BR pthread_create (3). +In particular, the following attributes may differ: +.IP \[bu] 3 +the detach state, since a joinable thread may have detached itself +after creation; +.IP \[bu] +the stack size, +which the implementation may align to a suitable boundary. +.IP \[bu] +and the guard size, +which the implementation may round upward to a multiple of the page size, +or ignore (i.e., treat as 0), +if the application is allocating its own stack. +.P +Furthermore, if the stack address attribute was not set +in the thread attributes object used to create the thread, +then the returned thread attributes object will report the actual +stack address that the implementation selected for the thread. +.P +When the thread attributes object returned by +.BR pthread_getattr_np () +is no longer required, it should be destroyed using +.BR pthread_attr_destroy (3). +.SH RETURN VALUE +On success, this function returns 0; +on error, it returns a nonzero error number. +.SH ERRORS +.TP +.B ENOMEM +.\" Can happen (but unlikely) while trying to allocate memory for cpuset +Insufficient memory. +.P +In addition, if +.I thread +refers to the main thread, then +.BR pthread_getattr_np () +can fail because of errors from various underlying calls: +.BR fopen (3), +if +.I /proc/self/maps +can't be opened; +and +.BR getrlimit (2), +if the +.B RLIMIT_STACK +resource limit is not supported. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_getattr_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the name. +.SH HISTORY +glibc 2.2.3. +.SH EXAMPLES +The program below demonstrates the use of +.BR pthread_getattr_np (). +The program creates a thread that then uses +.BR pthread_getattr_np () +to retrieve and display its guard size, stack address, +and stack size attributes. +Command-line arguments can be used to set these attributes +to values other than the default when creating the thread. +The shell sessions below demonstrate the use of the program. +.P +In the first run, on an x86-32 system, +a thread is created using default attributes: +.P +.in +4n +.EX +.RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB" +unlimited +.RB "$" " ./a.out" +Attributes of created thread: + Guard size = 4096 bytes + Stack address = 0x40196000 (EOS = 0x40397000) + Stack size = 0x201000 (2101248) bytes +.EE +.in +.P +In the following run, we see that if a guard size is specified, +it is rounded up to the next multiple of the system page size +(4096 bytes on x86-32): +.P +.in +4n +.EX +.RB "$" " ./a.out \-g 4097" +Thread attributes object after initializations: + Guard size = 4097 bytes + Stack address = (nil) + Stack size = 0x0 (0) bytes +\& +Attributes of created thread: + Guard size = 8192 bytes + Stack address = 0x40196000 (EOS = 0x40397000) + Stack size = 0x201000 (2101248) bytes +.EE +.in +.\".in +4n +.\".nf +.\"$ ./a.out \-s 0x8000 +.\"Thread attributes object after initializations: +.\" Guard size = 4096 bytes +.\" Stack address = 0xffff8000 (EOS = (nil)) +.\" Stack size = 0x8000 (32768) bytes +.\" +.\"Attributes of created thread: +.\" Guard size = 4096 bytes +.\" Stack address = 0x4001e000 (EOS = 0x40026000) +.\" Stack size = 0x8000 (32768) bytes +.\".fi +.\".in +.P +In the last run, the program manually allocates a stack for the thread. +In this case, the guard size attribute is ignored. +.P +.in +4n +.EX +.RB "$" " ./a.out \-g 4096 \-s 0x8000 \-a" +Allocated thread stack at 0x804d000 +\& +Thread attributes object after initializations: + Guard size = 4096 bytes + Stack address = 0x804d000 (EOS = 0x8055000) + Stack size = 0x8000 (32768) bytes +\& +Attributes of created thread: + Guard size = 0 bytes + Stack address = 0x804d000 (EOS = 0x8055000) + Stack size = 0x8000 (32768) bytes +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_getattr_np.c) +.EX +#define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ +#include +#include +#include +#include +#include +#include +\& +static void +display_stack_related_attributes(pthread_attr_t *attr, char *prefix) +{ + int s; + size_t stack_size, guard_size; + void *stack_addr; +\& + s = pthread_attr_getguardsize(attr, &guard_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getguardsize"); + printf("%sGuard size = %zu bytes\en", prefix, guard_size); +\& + s = pthread_attr_getstack(attr, &stack_addr, &stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_getstack"); + printf("%sStack address = %p", prefix, stack_addr); + if (stack_size > 0) + printf(" (EOS = %p)", (char *) stack_addr + stack_size); + printf("\en"); + printf("%sStack size = %#zx (%zu) bytes\en", + prefix, stack_size, stack_size); +} +\& +static void +display_thread_attributes(pthread_t thread, char *prefix) +{ + int s; + pthread_attr_t attr; +\& + s = pthread_getattr_np(thread, &attr); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_getattr_np"); +\& + display_stack_related_attributes(&attr, prefix); +\& + s = pthread_attr_destroy(&attr); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_destroy"); +} +\& +static void * /* Start function for thread we create */ +thread_start(void *arg) +{ + printf("Attributes of created thread:\en"); + display_thread_attributes(pthread_self(), "\et"); +\& + exit(EXIT_SUCCESS); /* Terminate all threads */ +} +\& +static void +usage(char *pname, char *msg) +{ + if (msg != NULL) + fputs(msg, stderr); + fprintf(stderr, "Usage: %s [\-s stack\-size [\-a]]" + " [\-g guard\-size]\en", pname); + fprintf(stderr, "\et\et\-a means program should allocate stack\en"); + exit(EXIT_FAILURE); +} +\& +static pthread_attr_t * /* Get thread attributes from command line */ +get_thread_attributes_from_cl(int argc, char *argv[], + pthread_attr_t *attrp) +{ + int s, opt, allocate_stack; + size_t stack_size, guard_size; + void *stack_addr; + pthread_attr_t *ret_attrp = NULL; /* Set to attrp if we initialize + a thread attributes object */ + allocate_stack = 0; + stack_size = \-1; + guard_size = \-1; +\& + while ((opt = getopt(argc, argv, "ag:s:")) != \-1) { + switch (opt) { + case \[aq]a\[aq]: allocate_stack = 1; break; + case \[aq]g\[aq]: guard_size = strtoul(optarg, NULL, 0); break; + case \[aq]s\[aq]: stack_size = strtoul(optarg, NULL, 0); break; + default: usage(argv[0], NULL); + } + } +\& + if (allocate_stack && stack_size == \-1) + usage(argv[0], "Specifying \-a without \-s makes no sense\en"); +\& + if (argc > optind) + usage(argv[0], "Extraneous command\-line arguments\en"); +\& + if (stack_size != -1 || guard_size > 0) { + ret_attrp = attrp; +\& + s = pthread_attr_init(attrp); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_init"); + } +\& + if (stack_size != -1) { + if (!allocate_stack) { + s = pthread_attr_setstacksize(attrp, stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setstacksize"); + } else { + s = posix_memalign(&stack_addr, sysconf(_SC_PAGESIZE), + stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "posix_memalign"); + printf("Allocated thread stack at %p\en\en", stack_addr); +\& + s = pthread_attr_setstack(attrp, stack_addr, stack_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setstacksize"); + } + } +\& + if (guard_size != -1) { + s = pthread_attr_setguardsize(attrp, guard_size); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_setstacksize"); + } +\& + return ret_attrp; +} +\& +int +main(int argc, char *argv[]) +{ + int s; + pthread_t thr; + pthread_attr_t attr; + pthread_attr_t *attrp = NULL; /* Set to &attr if we initialize + a thread attributes object */ +\& + attrp = get_thread_attributes_from_cl(argc, argv, &attr); +\& + if (attrp != NULL) { + printf("Thread attributes object after initializations:\en"); + display_stack_related_attributes(attrp, "\et"); + printf("\en"); + } +\& + s = pthread_create(&thr, attrp, &thread_start, NULL); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_create"); +\& + if (attrp != NULL) { + s = pthread_attr_destroy(attrp); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_attr_destroy"); + } +\& + pause(); /* Terminates when other thread calls exit() */ +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_getaffinity_np (3), +.BR pthread_attr_getdetachstate (3), +.BR pthread_attr_getguardsize (3), +.BR pthread_attr_getinheritsched (3), +.BR pthread_attr_getschedparam (3), +.BR pthread_attr_getschedpolicy (3), +.BR pthread_attr_getscope (3), +.BR pthread_attr_getstack (3), +.BR pthread_attr_getstackaddr (3), +.BR pthread_attr_getstacksize (3), +.BR pthread_attr_init (3), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_getconcurrency.3 b/man/man3/pthread_getconcurrency.3 new file mode 100644 index 0000000..8b2d543 --- /dev/null +++ b/man/man3/pthread_getconcurrency.3 @@ -0,0 +1 @@ +.so man3/pthread_setconcurrency.3 diff --git a/man/man3/pthread_getcpuclockid.3 b/man/man3/pthread_getcpuclockid.3 new file mode 100644 index 0000000..7ad000d --- /dev/null +++ b/man/man3/pthread_getcpuclockid.3 @@ -0,0 +1,180 @@ +'\" t +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_getcpuclockid 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_getcpuclockid \- retrieve ID of a thread's CPU time clock +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int pthread_getcpuclockid(pthread_t " thread ", clockid_t *" clockid ); +.fi +.SH DESCRIPTION +The +.BR pthread_getcpuclockid () +function obtains the ID of the CPU-time clock of the thread whose ID is +given in +.IR thread , +and returns it in the location pointed to by +.IR clockid . +.\" The clockid is constructed as follows: +.\" *clockid = CLOCK_THREAD_CPUTIME_ID | (pd->tid << CLOCK_IDFIELD_SIZE) +.\" where CLOCK_IDFIELD_SIZE is 3. +.SH RETURN VALUE +On success, this function returns 0; +on error, it returns a nonzero error number. +.SH ERRORS +.TP +.B ENOENT +.\" CLOCK_THREAD_CPUTIME_ID not defined +Per-thread CPU time clocks are not supported by the system. +.\" +.\" Looking at nptl/pthread_getcpuclockid.c an ERANGE error would +.\" be possible if kernel thread IDs took more than 29 bits (which +.\" they currently cannot). +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_getcpuclockid () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.SH NOTES +When +.I thread +refers to the calling thread, +this function returns an identifier that refers to the same clock +manipulated by +.BR clock_gettime (2) +and +.BR clock_settime (2) +when given the clock ID +.BR CLOCK_THREAD_CPUTIME_ID . +.SH EXAMPLES +The program below creates a thread and then uses +.BR clock_gettime (2) +to retrieve the total process CPU time, +and the per-thread CPU time consumed by the two threads. +The following shell session shows an example run: +.P +.in +4n +.EX +$ \fB./a.out\fP +Main thread sleeping +Subthread starting infinite loop +Main thread consuming some CPU time... +Process total CPU time: 1.368 +Main thread CPU time: 0.376 +Subthread CPU time: 0.992 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_getcpuclockid.c) +.EX +/* Link with "\-lrt" */ +\& +#include +#include +#include +#include +#include +#include +#include +#include +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void * +thread_start(void *arg) +{ + printf("Subthread starting infinite loop\en"); + for (;;) + continue; +} +\& +static void +pclock(char *msg, clockid_t cid) +{ + struct timespec ts; +\& + printf("%s", msg); + if (clock_gettime(cid, &ts) == \-1) + handle_error("clock_gettime"); + printf("%4jd.%03ld\en", (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000); +} +\& +int +main(void) +{ + pthread_t thread; + clockid_t cid; + int s; +\& + s = pthread_create(&thread, NULL, thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + printf("Main thread sleeping\en"); + sleep(1); +\& + printf("Main thread consuming some CPU time...\en"); + for (unsigned int j = 0; j < 2000000; j++) + getppid(); +\& + pclock("Process total CPU time: ", CLOCK_PROCESS_CPUTIME_ID); +\& + s = pthread_getcpuclockid(pthread_self(), &cid); + if (s != 0) + handle_error_en(s, "pthread_getcpuclockid"); + pclock("Main thread CPU time: ", cid); +\& + /* The preceding 4 lines of code could have been replaced by: + pclock("Main thread CPU time: ", CLOCK_THREAD_CPUTIME_ID); */ +\& + s = pthread_getcpuclockid(thread, &cid); + if (s != 0) + handle_error_en(s, "pthread_getcpuclockid"); + pclock("Subthread CPU time: 1 ", cid); +\& + exit(EXIT_SUCCESS); /* Terminates both threads */ +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clock_gettime (2), +.BR clock_settime (2), +.BR timer_create (2), +.BR clock_getcpuclockid (3), +.BR pthread_self (3), +.BR pthreads (7), +.BR time (7) diff --git a/man/man3/pthread_getname_np.3 b/man/man3/pthread_getname_np.3 new file mode 100644 index 0000000..a385c6e --- /dev/null +++ b/man/man3/pthread_getname_np.3 @@ -0,0 +1 @@ +.so man3/pthread_setname_np.3 diff --git a/man/man3/pthread_getschedparam.3 b/man/man3/pthread_getschedparam.3 new file mode 100644 index 0000000..67299c5 --- /dev/null +++ b/man/man3/pthread_getschedparam.3 @@ -0,0 +1 @@ +.so man3/pthread_setschedparam.3 diff --git a/man/man3/pthread_getspecific.3 b/man/man3/pthread_getspecific.3 new file mode 100644 index 0000000..307a947 --- /dev/null +++ b/man/man3/pthread_getspecific.3 @@ -0,0 +1 @@ +.so man3/pthread_key_create.3 diff --git a/man/man3/pthread_join.3 b/man/man3/pthread_join.3 new file mode 100644 index 0000000..1d3fbb8 --- /dev/null +++ b/man/man3/pthread_join.3 @@ -0,0 +1,134 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_join 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_join \- join with a terminated thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_join(pthread_t " thread ", void **" retval ); +.fi +.SH DESCRIPTION +The +.BR pthread_join () +function waits for the thread specified by +.I thread +to terminate. +If that thread has already terminated, then +.BR pthread_join () +returns immediately. +The thread specified by +.I thread +must be joinable. +.P +If +.I retval +is not NULL, then +.BR pthread_join () +copies the exit status of the target thread +(i.e., the value that the target thread supplied to +.BR pthread_exit (3)) +into the location pointed to by +.IR retval . +If the target thread was canceled, then +.B PTHREAD_CANCELED +is placed in the location pointed to by +.IR retval . +.P +If multiple threads simultaneously try to join with the same thread, +the results are undefined. +If the thread calling +.BR pthread_join () +is canceled, then the target thread will remain joinable +(i.e., it will not be detached). +.SH RETURN VALUE +On success, +.BR pthread_join () +returns 0; +on error, it returns an error number. +.SH ERRORS +.TP +.B EDEADLK +A deadlock was detected +.\" The following verified by testing on glibc 2.8/NPTL: +(e.g., two threads tried to join with each other); +or +.\" The following verified by testing on glibc 2.8/NPTL: +.I thread +specifies the calling thread. +.TP +.B EINVAL +.I thread +is not a joinable thread. +.TP +.B EINVAL +Another thread is already waiting to join with this thread. +.\" POSIX.1-2001 does not specify this error case. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_join () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +After a successful call to +.BR pthread_join (), +the caller is guaranteed that the target thread has terminated. +The caller may then choose to do any clean-up that is required +after termination of the thread (e.g., freeing memory or other +resources that were allocated to the target thread). +.P +Joining with a thread that has previously been joined results in +undefined behavior. +.P +Failure to join with a thread that is joinable +(i.e., one that is not detached), +produces a "zombie thread". +Avoid doing this, +since each zombie thread consumes some system resources, +and when enough zombie threads have accumulated, +it will no longer be possible to create new threads (or processes). +.P +There is no pthreads analog of +.IR "waitpid(\-1,\ &status,\ 0)" , +that is, "join with any terminated thread". +If you believe you need this functionality, +you probably need to rethink your application design. +.P +All of the threads in a process are peers: +any thread can join with any other thread in the process. +.SH EXAMPLES +See +.BR pthread_create (3). +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_create (3), +.BR pthread_detach (3), +.BR pthread_exit (3), +.BR pthread_tryjoin_np (3), +.BR pthreads (7) diff --git a/man/man3/pthread_key_create.3 b/man/man3/pthread_key_create.3 new file mode 100644 index 0000000..f319426 --- /dev/null +++ b/man/man3/pthread_key_create.3 @@ -0,0 +1,181 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_key_create 3 2024-05-19 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_key_create, +pthread_key_delete, +pthread_setspecific, +pthread_getspecific +\- +management of thread-specific data +. +. +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_key_create(pthread_key_t *" key , +.BI " void (*" destr_function ") (void *));" +.BI "int pthread_key_delete(pthread_key_t " key ); +.BI "int pthread_setspecific(pthread_key_t " key ", const void *" pointer ); +.BI "void * pthread_getspecific(pthread_key_t " key ); +.fi +. +. +.SH DESCRIPTION +Programs often need global or static variables +that have different values in different threads. +Since threads share one memory space, +this cannot be achieved with regular variables. +Thread-specific data is the POSIX threads answer to this need. +.P +Each thread possesses a private memory block, +the thread-specific data area, +or TSD area for short. +This area is indexed by TSD keys. +The TSD area associates values of type \fBvoid *\fP to TSD keys. +TSD keys are common to all threads, +but the value associated with a given TSD key +can be different in each thread. +.P +For concreteness, +the TSD areas can be viewed as arrays of \fBvoid *\fP pointers, +TSD keys as integer indices into these arrays, +and the value of a TSD key +as the value of the corresponding array element in the calling thread. +.P +When a thread is created, +its TSD area initially associates \fBNULL\fP with all keys. +.P +\fBpthread_key_create\fP allocates a new TSD key. +The key is stored in the location pointed to by \fIkey\fP. +There is a limit of \fBPTHREAD_KEYS_MAX\fP +on the number of keys allocated at a given time. +The value initially associated with the returned key +is \fBNULL\fP in all currently executing threads. +.P +The \fIdestr_function\fP argument, +if not \fBNULL\fP, +specifies a destructor function associated with the key. +When a thread terminates via \fBpthread_exit\fP or by cancelation, +\fIdestr_function\fP is called with arguments +the value associated with the key in that thread. +The \fIdestr_function\fP is not called if that value is \fBNULL\fP. +The order in which destructor functions are called at thread termination time +is unspecified. +.P +Before the destructor function is called, +the \fBNULL\fP value is associated with the key in the current thread. +A destructor function might, +however, +re-associate non-\fBNULL\fP values to that key or some other key. +To deal with this, +if after all the destructors have been called +for all non-\fBNULL\fP values, +there are still some non-\fBNULL\fP values with associated destructors, +then the process is repeated. +The glibc implementation stops the process +after \fBPTHREAD_DESTRUCTOR_ITERATIONS\fP iterations, +even if some non-\fBNULL\fP values with associated descriptors remain. +Other implementations may loop indefinitely. +.P +\fBpthread_key_delete\fP deallocates a TSD key. +It does not check +whether non-\fBNULL\fP values are associated with that key +in the currently executing threads, +nor call the destructor function associated with the key. +.P +\fBpthread_setspecific\fP changes the value +associated with \fIkey\fP in the calling thread, +storing the given \fIpointer\fP instead. +.P +\fBpthread_getspecific\fP returns the value +currently associated with \fIkey\fP in the calling thread. +. +. +.SH "RETURN VALUE" +\fBpthread_key_create\fP, +\fBpthread_key_delete\fP, +and \fBpthread_setspecific\fP +return 0 on success and a non-zero error code on failure. +If successful, +\fBpthread_key_create\fP stores the newly allocated key +in the location pointed to by its \fIkey\fP argument. +.P +\fBpthread_getspecific\fP returns +the value associated with \fIkey\fP on success, +and \fBNULL\fP on error. +. +. +.SH ERRORS +\fBpthread_key_create\fP returns the following error code on error: +.RS +.TP +\fBEAGAIN\fP +\fBPTHREAD_KEYS_MAX\fP keys are already allocated. +.RE +.P +\fBpthread_key_delete\fP and \fBpthread_setspecific\fP return +the following error code on error: +.RS +.TP +\fBEINVAL\fP +\fIkey\fP is not a valid, allocated TSD key. +.RE +.P +\fBpthread_getspecific\fP returns \fBNULL\fP if \fIkey\fP is not a valid, +allocated TSD key. +. +. +.SH "SEE ALSO" +pthread_create(3), pthread_exit(3), pthread_testcancel(3). +. +. +.SH EXAMPLE +The following code fragment +allocates a thread-specific array of 100 characters, +with automatic reclamation at thread exit: +.P +.RS +.ft 3 +.nf +.sp +/* Key for the thread-specific buffer */ +static pthread_key_t buffer_key; +\& +/* Once-only initialisation of the key */ +static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT; +\& +/* Allocate the thread-specific buffer */ +void buffer_alloc(void) +{ + pthread_once(&buffer_key_once, buffer_key_alloc); + pthread_setspecific(buffer_key, malloc(100)); +} +\& +/* Return the thread-specific buffer */ +char * get_buffer(void) +{ + return (char *) pthread_getspecific(buffer_key); +} +\& +/* Allocate the key */ +static void buffer_key_alloc() +{ + pthread_key_create(&buffer_key, buffer_destroy); +} +\& +/* Free the thread-specific buffer */ +static void buffer_destroy(void * buf) +{ + free(buf); +} +.ft +.P +.RE +.fi diff --git a/man/man3/pthread_key_delete.3 b/man/man3/pthread_key_delete.3 new file mode 100644 index 0000000..307a947 --- /dev/null +++ b/man/man3/pthread_key_delete.3 @@ -0,0 +1 @@ +.so man3/pthread_key_create.3 diff --git a/man/man3/pthread_kill.3 b/man/man3/pthread_kill.3 new file mode 100644 index 0000000..3d445ed --- /dev/null +++ b/man/man3/pthread_kill.3 @@ -0,0 +1,108 @@ +'\" t +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_kill 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_kill \- send a signal to a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_kill(pthread_t " thread ", int " sig ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_kill (): +.nf + _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500 +.fi +.SH DESCRIPTION +The +.BR pthread_kill () +function sends the signal +.I sig +to +.IR thread , +a thread in the same process as the caller. +The signal is asynchronously directed to +.IR thread . +.P +If +.I sig +is 0, then no signal is sent, but error checking is still performed. +.SH RETURN VALUE +On success, +.BR pthread_kill () +returns 0; +on error, it returns an error number, and no signal is sent. +.SH ERRORS +.TP +.B EINVAL +An invalid signal was specified. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_kill () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The glibc implementation of +.BR pthread_kill () +gives an error +.RB ( EINVAL ) +on attempts to send either of the real-time signals +used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.P +POSIX.1-2008 recommends that if an implementation detects the use +of a thread ID after the end of its lifetime, +.BR pthread_kill () +should return the error +.BR ESRCH . +The glibc implementation returns this error in the cases where +an invalid thread ID can be detected. +But note also that POSIX says that an attempt to use a thread ID whose +lifetime has ended produces undefined behavior, +and an attempt to use an invalid thread ID in a call to +.BR pthread_kill () +can, for example, cause a segmentation fault. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Signal dispositions are process-wide: +if a signal handler is installed, +the handler will be invoked in the thread +.IR thread , +but if the disposition of the signal is "stop", "continue", or "terminate", +this action will affect the whole process. +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR sigpending (2), +.BR pthread_self (3), +.BR pthread_sigmask (3), +.BR raise (3), +.BR pthreads (7), +.BR signal (7) diff --git a/man/man3/pthread_kill_other_threads_np.3 b/man/man3/pthread_kill_other_threads_np.3 new file mode 100644 index 0000000..dea465f --- /dev/null +++ b/man/man3/pthread_kill_other_threads_np.3 @@ -0,0 +1,69 @@ +'\" t +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_kill_other_threads_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_kill_other_threads_np \- terminate all other threads in process +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.B void pthread_kill_other_threads_np(void); +.fi +.SH DESCRIPTION +.BR pthread_kill_other_threads_np () +has an effect only in the LinuxThreads threading implementation. +On that implementation, +calling this function causes the immediate termination of +all threads in the application, +except the calling thread. +The cancelation state and cancelation type of the +to-be-terminated threads are ignored, +and the cleanup handlers are not called in those threads. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_kill_other_threads_np () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +In the NPTL threading implementation, +.BR pthread_kill_other_threads_np () +exists, but does nothing. +(Nothing needs to be done, +because the implementation does the right thing during an +.BR execve (2).) +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the name. +.SH HISTORY +glibc 2.0 +.SH NOTES +.BR pthread_kill_other_threads_np () +is intended to be called just before a thread calls +.BR execve (2) +or a similar function. +This function is designed to address a limitation in the obsolete +LinuxThreads implementation whereby the other threads of an application +are not automatically terminated (as POSIX.1-2001 requires) during +.BR execve (2). +.SH SEE ALSO +.BR execve (2), +.BR pthread_cancel (3), +.BR pthread_setcancelstate (3), +.BR pthread_setcanceltype (3), +.BR pthreads (7) diff --git a/man/man3/pthread_mutex_consistent.3 b/man/man3/pthread_mutex_consistent.3 new file mode 100644 index 0000000..d81b364 --- /dev/null +++ b/man/man3/pthread_mutex_consistent.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 2017, Yubin Ruan +.\" and Copyright (c) 2017, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutex_consistent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_mutex_consistent \- make a robust mutex consistent +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_mutex_consistent(pthread_mutex_t *" mutex ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_mutex_consistent (): +.nf + _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +This function makes a robust mutex consistent if it is in an inconsistent +state. +A mutex can be left in an inconsistent state if its owner terminates +while holding the mutex, in which case the next owner who acquires the +mutex will succeed and be notified by a return value of +.B EOWNERDEAD +from a call to +.BR pthread_mutex_lock (). +.SH RETURN VALUE +On success, +.IR pthread_mutex_consistent () +returns 0. +Otherwise, +it returns a positive error number to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The mutex is either not robust or is not in an inconsistent state. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.12. +POSIX.1-2008. +.P +Before the addition of +.BR pthread_mutex_consistent () +to POSIX, +glibc defined the following equivalent nonstandard function if +.B _GNU_SOURCE +was defined: +.P +.nf +.B [[deprecated]] +.BI "int pthread_mutex_consistent_np(const pthread_mutex_t *" mutex ); +.fi +.P +This GNU-specific API, which first appeared in glibc 2.4, +is nowadays obsolete and should not be used in new programs; +since glibc 2.34 it has been marked as deprecated. +.SH NOTES +.BR pthread_mutex_consistent () +simply informs the implementation that the state (shared data) +guarded by the mutex has been restored to a consistent state and that +normal operations can now be performed with the mutex. +It is the application's responsibility to ensure that the +shared data has been restored to a consistent state before calling +.BR pthread_mutex_consistent (). +.SH EXAMPLES +See +.BR pthread_mutexattr_setrobust (3). +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutex_lock (3), +.BR pthread_mutexattr_getrobust (3), +.BR pthread_mutexattr_init (3), +.BR pthread_mutexattr_setrobust (3), +.BR pthreads (7) diff --git a/man/man3/pthread_mutex_consistent_np.3 b/man/man3/pthread_mutex_consistent_np.3 new file mode 100644 index 0000000..a45bea4 --- /dev/null +++ b/man/man3/pthread_mutex_consistent_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_consistent.3 diff --git a/man/man3/pthread_mutex_destroy.3 b/man/man3/pthread_mutex_destroy.3 new file mode 100644 index 0000000..1b7eb83 --- /dev/null +++ b/man/man3/pthread_mutex_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_init.3 diff --git a/man/man3/pthread_mutex_init.3 b/man/man3/pthread_mutex_init.3 new file mode 100644 index 0000000..0b05459 --- /dev/null +++ b/man/man3/pthread_mutex_init.3 @@ -0,0 +1,244 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutex_init 3 2024-05-19 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_mutex_init, +pthread_mutex_lock, +pthread_mutex_trylock, +pthread_mutex_unlock, +pthread_mutex_destroy +\- +operations on mutexes +. +. +.SH SYNOPSIS +.nf +.B #include +.P +.BI "pthread_mutex_t " fastmutex " = PTHREAD_MUTEX_INITIALIZER;" +.BI "pthread_mutex_t " recmutex " = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;" +.BI "pthread_mutex_t " errchkmutex " = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;" +.P +.BI "int pthread_mutex_init(pthread_mutex_t *" mutex , +.BI " const pthread_mutexattr_t *" mutexattr ); +.BI "int pthread_mutex_lock(pthread_mutex_t *" mutex ); +.BI "int pthread_mutex_trylock(pthread_mutex_t *" mutex ); +.BI "int pthread_mutex_unlock(pthread_mutex_t *" mutex ); +.BI "int pthread_mutex_destroy(pthread_mutex_t *" mutex ); +.fi +. +. +.SH DESCRIPTION +A mutex is a MUTual EXclusion device, +and is useful for +protecting shared data structures from concurrent modifications, +and implementing critical sections and monitors. +.P +A mutex has two possible states: +unlocked (not owned by any thread), +and locked (owned by one thread). +A mutex can never be owned by two different threads simultaneously. +A thread attempting to lock a mutex +that is already locked by another thread +is suspended until the owning thread unlocks the mutex first. +.P +\fBpthread_mutex_init\fP initializes the mutex object pointed to by \fImutex\fP +according to the mutex attributes specified in \fImutexattr\fP. +If \fImutexattr\fP is \fBNULL\fP, +default attributes are used instead. +.P +The LinuxThreads implementation supports only one mutex attributes, +the \fImutex kind\fP, +which is either ``fast'', +``recursive'', +or ``error checking''. +The kind of a mutex determines +whether it can be locked again by a thread that already owns it. +The default kind is ``fast''. +See \fBpthread_mutexattr_init\fP(3) for more information on mutex attributes. +.P +Variables of type \fBpthread_mutex_t\fP can also be initialized statically, +using the constants +\fBPTHREAD_MUTEX_INITIALIZER\fP +(for fast mutexes), +\fBPTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP\fP +(for recursive mutexes), +and \fBPTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP\fP +(for error checking mutexes). +.P +\fBpthread_mutex_lock\fP locks the given mutex. +If the mutex is currently unlocked, +it becomes locked and owned by the calling thread, +and \fBpthread_mutex_lock\fP returns immediately. +If the mutex is already locked by another thread, +\fBpthread_mutex_lock\fP suspends the calling thread +until the mutex is unlocked. +.P +If the mutex is already locked by the calling thread, +the behavior of \fBpthread_mutex_lock\fP depends on the kind of the mutex. +If the mutex is of the ``fast'' kind, +the calling thread is suspended until the mutex is unlocked, +thus effectively causing the calling thread to deadlock. +If the mutex is of the ``error checking'' kind, +\fBpthread_mutex_lock\fP returns immediately with the error code \fBEDEADLK\fP. +If the mutex is of the ``recursive'' kind, +\fBpthread_mutex_lock\fP succeeds and returns immediately, +recording the number of times the calling thread has locked the mutex. +An equal number of \fBpthread_mutex_unlock\fP operations +must be performed before the mutex returns to the unlocked state. +.P +\fBpthread_mutex_trylock\fP behaves identically to \fBpthread_mutex_lock\fP, +except that it does not block the calling thread +if the mutex is already locked by another thread +(or by the calling thread in the case of a ``fast'' mutex). +Instead, +\fBpthread_mutex_trylock\fP returns immediately +with the error code \fBEBUSY\fP. +.P +\fBpthread_mutex_unlock\fP unlocks the given mutex. +The mutex is assumed to be locked and owned by the calling thread +on entrance to \fBpthread_mutex_unlock\fP. +If the mutex is of the ``fast'' kind, +\fBpthread_mutex_unlock\fP always returns it to the unlocked state. +If it is of the ``recursive'' kind, +it decrements the locking count of the mutex +(number of \fBpthread_mutex_lock\fP operations +performed on it by the calling thread), +and only when this count reaches zero is the mutex actually unlocked. +.P +On ``error checking'' and ``recursive'' mutexes, +\fBpthread_mutex_unlock\fP actually checks at run-time +that the mutex is locked on entrance, +and that it was locked by the same thread +that is now calling \fBpthread_mutex_unlock\fP. +If these conditions are not met, +an error code is returned and the mutex remains unchanged. +``Fast'' mutexes perform no such checks, +thus allowing a locked mutex to be +unlocked by a thread other than its owner. +This is non-portable behavior and must not be relied upon. +.P +\fBpthread_mutex_destroy\fP destroys a mutex object, +freeing the resources it might hold. +The mutex must be unlocked on entrance. +In the LinuxThreads implementation, +no resources are associated with mutex objects, +thus \fBpthread_mutex_destroy\fP actually does nothing +except checking that the mutex is unlocked. +. +. +.SH CANCELLATION +None of the mutex functions is a cancelation point, +not even \fBpthread_mutex_lock\fP, +in spite of the fact that it can suspend a thread for arbitrary durations. +This way, +the status of mutexes at cancelation points is predictable, +allowing cancelation handlers +to unlock precisely those mutexes that need to be unlocked +before the thread stops executing. +Consequently, +threads using deferred cancelation +should never hold a mutex for extended periods of time. +. +. +.SH "ASYNC-SIGNAL SAFETY" +The mutex functions are not async-signal safe. +What this means is that they should not be called from a signal handler. +In particular, +calling \fBpthread_mutex_lock\fP or \fBpthread_mutex_unlock\fP +from a signal handler +may deadlock the calling thread. +. +. +.SH "RETURN VALUE" +\fBpthread_mutex_init\fP always returns 0. +The other mutex functions +return 0 on success and a non-zero error code on error. +. +. +.SH ERRORS +The \fBpthread_mutex_lock\fP function returns +the following error code on error: +.RS +.TP +\fBEINVAL\fP +The mutex has not been properly initialized. +.TP +\fBEDEADLK\fP +The mutex is already locked by the calling thread +(``error checking'' mutexes only). +.RE +.P +The \fBpthread_mutex_trylock\fP function returns +the following error codes on error: +.RS +.TP +\fBEBUSY\fP +The mutex could not be acquired because it was currently locked. +.TP +\fBEINVAL\fP +The mutex has not been properly initialized. +.RE +.P +The \fBpthread_mutex_unlock\fP function returns +the following error code on error: +.RS +.TP +\fBEINVAL\fP +The mutex has not been properly initialized. +.TP +\fBEPERM\fP +The calling thread does not own the mutex +(``error checking'' mutexes only). +.RE +.P +The \fBpthread_mutex_destroy\fP function returns +the following error code on error: +.RS +.TP +\fBEBUSY\fP +The mutex is currently locked. +.RE +. +. +.SH "SEE ALSO" +\fBpthread_mutexattr_init\fP(3), +\fBpthread_mutexattr_setkind_np\fP(3), +\fBpthread_cancel\fP(3). +. +. +.SH EXAMPLE +A shared global variable \fIx\fP can be protected by a mutex as follows: +.P +.RS +.ft 3 +.nf +.sp +int x; +pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; +.ft +.P +.RE +.fi +.P +All accesses and modifications to \fIx\fP +should be bracketed by calls to +\fBpthread_mutex_lock\fP and \fBpthread_mutex_unlock\fP +as follows: +.P +.RS +.ft 3 +.nf +.sp +pthread_mutex_lock(&mut); +/* operate on x */ +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi diff --git a/man/man3/pthread_mutex_lock.3 b/man/man3/pthread_mutex_lock.3 new file mode 100644 index 0000000..1b7eb83 --- /dev/null +++ b/man/man3/pthread_mutex_lock.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_init.3 diff --git a/man/man3/pthread_mutex_trylock.3 b/man/man3/pthread_mutex_trylock.3 new file mode 100644 index 0000000..1b7eb83 --- /dev/null +++ b/man/man3/pthread_mutex_trylock.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_init.3 diff --git a/man/man3/pthread_mutex_unlock.3 b/man/man3/pthread_mutex_unlock.3 new file mode 100644 index 0000000..1b7eb83 --- /dev/null +++ b/man/man3/pthread_mutex_unlock.3 @@ -0,0 +1 @@ +.so man3/pthread_mutex_init.3 diff --git a/man/man3/pthread_mutexattr_destroy.3 b/man/man3/pthread_mutexattr_destroy.3 new file mode 100644 index 0000000..eadaa9b --- /dev/null +++ b/man/man3/pthread_mutexattr_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_init.3 diff --git a/man/man3/pthread_mutexattr_getkind_np.3 b/man/man3/pthread_mutexattr_getkind_np.3 new file mode 100644 index 0000000..af2ab96 --- /dev/null +++ b/man/man3/pthread_mutexattr_getkind_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setkind_np.3 diff --git a/man/man3/pthread_mutexattr_getpshared.3 b/man/man3/pthread_mutexattr_getpshared.3 new file mode 100644 index 0000000..0d19e60 --- /dev/null +++ b/man/man3/pthread_mutexattr_getpshared.3 @@ -0,0 +1,82 @@ +.\" Copyright (c) 2017, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutexattr_getpshared 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_mutexattr_getpshared, pthread_mutexattr_setpshared \- get/set +process-shared mutex attribute +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.B int pthread_mutexattr_getpshared( +.BI " const pthread_mutexattr_t *restrict " attr , +.BI " int *restrict " pshared ); +.BI "int pthread_mutexattr_setpshared(pthread_mutexattr_t *" attr , +.BI " int " pshared ); +.fi +.SH DESCRIPTION +These functions get and set the process-shared attribute +in a mutex attributes object. +This attribute must be appropriately set to ensure correct, +efficient operation of a mutex created using this attributes object. +.P +The process-shared attribute can have one of the following values: +.TP +.B PTHREAD_PROCESS_PRIVATE +Mutexes created with this attributes object are to be shared +only among threads in the same process that initialized the mutex. +This is the default value for the process-shared mutex attribute. +.TP +.B PTHREAD_PROCESS_SHARED +Mutexes created with this attributes object can be shared between +any threads that have access to the memory containing the object, +including threads in different processes. +.P +.BR pthread_mutexattr_getpshared () +places the value of the process-shared attribute of +the mutex attributes object referred to by +.I attr +in the location pointed to by +.IR pshared . +.P +.BR pthread_mutexattr_setpshared () +sets the value of the process-shared attribute of +the mutex attributes object referred to by +.I attr +to the value specified in +.BR pshared . +.P +If +.I attr +does not refer to an initialized mutex attributes object, +the behavior is undefined. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return a positive error number. +.SH ERRORS +.BR pthread_mutexattr_setpshared () +can fail with the following errors: +.TP +.B EINVAL +The value specified in +.I pshared +is invalid. +.TP +.B ENOTSUP +.I pshared is +.B PTHREAD_PROCESS_SHARED +but the implementation does not support process-shared mutexes. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutexattr_init (3), +.BR pthreads (7) diff --git a/man/man3/pthread_mutexattr_getrobust.3 b/man/man3/pthread_mutexattr_getrobust.3 new file mode 100644 index 0000000..8c40cc0 --- /dev/null +++ b/man/man3/pthread_mutexattr_getrobust.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setrobust.3 diff --git a/man/man3/pthread_mutexattr_getrobust_np.3 b/man/man3/pthread_mutexattr_getrobust_np.3 new file mode 100644 index 0000000..8c40cc0 --- /dev/null +++ b/man/man3/pthread_mutexattr_getrobust_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setrobust.3 diff --git a/man/man3/pthread_mutexattr_gettype.3 b/man/man3/pthread_mutexattr_gettype.3 new file mode 100644 index 0000000..eadaa9b --- /dev/null +++ b/man/man3/pthread_mutexattr_gettype.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_init.3 diff --git a/man/man3/pthread_mutexattr_init.3 b/man/man3/pthread_mutexattr_init.3 new file mode 100644 index 0000000..8b89bad --- /dev/null +++ b/man/man3/pthread_mutexattr_init.3 @@ -0,0 +1,53 @@ +.\" Copyright (c) 2017, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutexattr_init 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_mutexattr_init, pthread_mutexattr_destroy \- initialize and +destroy a mutex attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_mutexattr_init(pthread_mutexattr_t *" attr ");" +.BI "int pthread_mutexattr_destroy(pthread_mutexattr_t *" attr ");" +.fi +.SH DESCRIPTION +The +.BR pthread_mutexattr_init () +function initializes the mutex attributes object pointed to by +.I attr +with default values for all attributes defined by the implementation. +.P +The results of initializing an already initialized mutex attributes +object are undefined. +.P +The +.BR pthread_mutexattr_destroy () +function destroys a mutex attribute object (making it uninitialized). +Once a mutex attributes object has been destroyed, it can be reinitialized with +.BR pthread_mutexattr_init (). +.P +The results of destroying an uninitialized mutex attributes +object are undefined. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return a positive error number. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +Subsequent changes to a mutex attributes object do not affect mutex that +have already been initialized using that object. +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutex_init (3), +.BR pthread_mutexattr_getpshared (3), +.BR pthread_mutexattr_getrobust (3), +.BR pthreads (7) diff --git a/man/man3/pthread_mutexattr_setkind_np.3 b/man/man3/pthread_mutexattr_setkind_np.3 new file mode 100644 index 0000000..4480d88 --- /dev/null +++ b/man/man3/pthread_mutexattr_setkind_np.3 @@ -0,0 +1,55 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutexattr_setkind_np 3 2024-05-19 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_mutexattr_setkind_np, +pthread_mutexattr_getkind_np +\- +deprecated mutex creation attributes +. +. +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_mutexattr_setkind_np(pthread_mutexattr_t *" attr ", int " kind ); +.BI "int pthread_mutexattr_getkind_np(const pthread_mutexattr_t *" attr , +.BI " int *" kind ); +.fi +. +. +.SH DESCRIPTION +These functions are deprecated, +use \fBpthread_mutexattr_settype\fP(3) +and \fBpthread_mutexattr_gettype\fP(3) +instead. +. +. +.SH "RETURN VALUE" +\fBpthread_mutexattr_getkind_np\fP always returns 0. +.P +\fBpthread_mutexattr_setkind_np\fP +returns 0 on success and a non-zero error code on error. +. +. +.SH ERRORS +On error, +\fBpthread_mutexattr_setkind_np\fP returns the following error code: +.TP +\fBEINVAL\fP +\fIkind\fP is neither +\fBPTHREAD_MUTEX_FAST_NP\fP +nor +\fBPTHREAD_MUTEX_RECURSIVE_NP\fP +nor +\fBPTHREAD_MUTEX_ERRORCHECK_NP\fP. +. +. +.SH "SEE ALSO" +\fBpthread_mutexattr_settype\fP(3), +\fBpthread_mutexattr_gettype\fP(3). diff --git a/man/man3/pthread_mutexattr_setpshared.3 b/man/man3/pthread_mutexattr_setpshared.3 new file mode 100644 index 0000000..07899fd --- /dev/null +++ b/man/man3/pthread_mutexattr_setpshared.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_getpshared.3 diff --git a/man/man3/pthread_mutexattr_setrobust.3 b/man/man3/pthread_mutexattr_setrobust.3 new file mode 100644 index 0000000..7467722 --- /dev/null +++ b/man/man3/pthread_mutexattr_setrobust.3 @@ -0,0 +1,264 @@ +.\" Copyright (c) 2017, Yubin Ruan +.\" and Copyright (c) 2017, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutexattr_setrobust 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_mutexattr_getrobust, pthread_mutexattr_setrobust +\- get and set the robustness attribute of a mutex attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr , +.BI " int *" robustness ");" +.BI "int pthread_mutexattr_setrobust(pthread_mutexattr_t *" attr , +.BI " int " robustness ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_mutexattr_getrobust (), +.BR pthread_mutexattr_setrobust (): +.nf + _POSIX_C_SOURCE >= 200809L +.\" FIXME . +.\" But see https://sourceware.org/bugzilla/show_bug.cgi?id=22125 +.fi +.SH DESCRIPTION +The +.BR pthread_mutexattr_getrobust () +function places the value of the robustness attribute of +the mutex attributes object referred to by +.I attr +in +.IR *robustness . +The +.BR pthread_mutexattr_setrobust () +function sets the value of the robustness attribute of +the mutex attributes object referred to by +.I attr +to the value specified in +.IR *robustness . +.P +The robustness attribute specifies the behavior of the mutex when +the owning thread dies without unlocking the mutex. +The following values are valid for +.IR robustness : +.TP +.B PTHREAD_MUTEX_STALLED +This is the default value for a mutex attributes object. +If a mutex is initialized with the +.B PTHREAD_MUTEX_STALLED +attribute and its owner dies without unlocking it, +the mutex remains locked afterwards and any future attempts to call +.BR pthread_mutex_lock (3) +on the mutex will block indefinitely. +.TP +.B PTHREAD_MUTEX_ROBUST +If a mutex is initialized with the +.B PTHREAD_MUTEX_ROBUST +attribute and its owner dies without unlocking it, +any future attempts to call +.BR pthread_mutex_lock (3) +on this mutex will succeed and return +.B EOWNERDEAD +to indicate that the original owner no longer exists and the mutex is in +an inconsistent state. +Usually after +.B EOWNERDEAD +is returned, the next owner should call +.BR pthread_mutex_consistent (3) +on the acquired mutex to make it consistent again before using it any further. +.IP +If the next owner unlocks the mutex using +.BR pthread_mutex_unlock (3) +before making it consistent, the mutex will be permanently unusable and any +subsequent attempts to lock it using +.BR pthread_mutex_lock (3) +will fail with the error +.BR ENOTRECOVERABLE . +The only permitted operation on such a mutex is +.BR pthread_mutex_destroy (3). +.IP +If the next owner terminates before calling +.BR pthread_mutex_consistent (3), +further +.BR pthread_mutex_lock (3) +operations on this mutex will still return +.BR EOWNERDEAD . +.P +Note that the +.I attr +argument of +.BR pthread_mutexattr_getrobust () +and +.BR pthread_mutexattr_setrobust () +should refer to a mutex attributes object that was initialized by +.BR pthread_mutexattr_init (3), +otherwise the behavior is undefined. +.SH RETURN VALUE +On success, these functions return 0. +On error, they return a positive error number. +.P +In the glibc implementation, +.BR pthread_mutexattr_getrobust () +always return zero. +.SH ERRORS +.TP +.B EINVAL +A value other than +.B PTHREAD_MUTEX_STALLED +or +.B PTHREAD_MUTEX_ROBUST +was passed to +.BR pthread_mutexattr_setrobust (). +.SH VERSIONS +In the Linux implementation, +when using process-shared robust mutexes, a waiting thread also receives the +.B EOWNERDEAD +notification if the owner of a robust mutex performs an +.BR execve (2) +without first unlocking the mutex. +POSIX.1 does not specify this detail, +but the same behavior also occurs in at least some +.\" E.g., Solaris, according to its manual page +other implementations. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.12. +POSIX.1-2008. +.P +Before the addition of +.BR pthread_mutexattr_getrobust () +and +.BR pthread_mutexattr_setrobust () +to POSIX, +glibc defined the following equivalent nonstandard functions if +.B _GNU_SOURCE +was defined: +.P +.nf +.B [[deprecated]] +.BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr , +.BI " int *" robustness ");" +.B [[deprecated]] +.BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr , +.BI " int " robustness ");" +.fi +.P +Correspondingly, the constants +.B PTHREAD_MUTEX_STALLED_NP +and +.B PTHREAD_MUTEX_ROBUST_NP +were also defined. +.P +These GNU-specific APIs, which first appeared in glibc 2.4, +are nowadays obsolete and should not be used in new programs; +since glibc 2.34 these APIs are marked as deprecated. +.SH EXAMPLES +The program below demonstrates the use of the robustness attribute of a +mutex attributes object. +In this program, a thread holding the mutex +dies prematurely without unlocking the mutex. +The main thread subsequently acquires the mutex +successfully and gets the error +.BR EOWNERDEAD , +after which it makes the mutex consistent. +.P +The following shell session shows what we see when running this program: +.P +.in +4n +.EX +$ \fB./a.out\fP +[original owner] Setting lock... +[original owner] Locked. Now exiting without unlocking. +[main] Attempting to lock the robust mutex. +[main] pthread_mutex_lock() returned EOWNERDEAD +[main] Now make the mutex consistent +[main] Mutex is now consistent; unlocking +.EE +.in +.SS Program source +.\" SRC BEGIN (pthread_mutexattr_setrobust.c) +.EX +#include +#include +#include +#include +#include +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static pthread_mutex_t mtx; +\& +static void * +original_owner_thread(void *ptr) +{ + printf("[original owner] Setting lock...\en"); + pthread_mutex_lock(&mtx); + printf("[original owner] Locked. Now exiting without unlocking.\en"); + pthread_exit(NULL); +} +\& +int +main(void) +{ + pthread_t thr; + pthread_mutexattr_t attr; + int s; +\& + pthread_mutexattr_init(&attr); +\& + pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST); +\& + pthread_mutex_init(&mtx, &attr); +\& + pthread_create(&thr, NULL, original_owner_thread, NULL); +\& + sleep(2); +\& + /* "original_owner_thread" should have exited by now. */ +\& + printf("[main] Attempting to lock the robust mutex.\en"); + s = pthread_mutex_lock(&mtx); + if (s == EOWNERDEAD) { + printf("[main] pthread_mutex_lock() returned EOWNERDEAD\en"); + printf("[main] Now make the mutex consistent\en"); + s = pthread_mutex_consistent(&mtx); + if (s != 0) + handle_error_en(s, "pthread_mutex_consistent"); + printf("[main] Mutex is now consistent; unlocking\en"); + s = pthread_mutex_unlock(&mtx); + if (s != 0) + handle_error_en(s, "pthread_mutex_unlock"); +\& + exit(EXIT_SUCCESS); + } else if (s == 0) { + printf("[main] pthread_mutex_lock() unexpectedly succeeded\en"); + exit(EXIT_FAILURE); + } else { + printf("[main] pthread_mutex_lock() unexpectedly failed\en"); + handle_error_en(s, "pthread_mutex_lock"); + } +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR get_robust_list (2), +.BR set_robust_list (2), +.BR pthread_mutex_consistent (3), +.BR pthread_mutex_init (3), +.BR pthread_mutex_lock (3), +.BR pthreads (7) diff --git a/man/man3/pthread_mutexattr_setrobust_np.3 b/man/man3/pthread_mutexattr_setrobust_np.3 new file mode 100644 index 0000000..8c40cc0 --- /dev/null +++ b/man/man3/pthread_mutexattr_setrobust_np.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_setrobust.3 diff --git a/man/man3/pthread_mutexattr_settype.3 b/man/man3/pthread_mutexattr_settype.3 new file mode 100644 index 0000000..eadaa9b --- /dev/null +++ b/man/man3/pthread_mutexattr_settype.3 @@ -0,0 +1 @@ +.so man3/pthread_mutexattr_init.3 diff --git a/man/man3/pthread_once.3 b/man/man3/pthread_once.3 new file mode 100644 index 0000000..86ecd84 --- /dev/null +++ b/man/man3/pthread_once.3 @@ -0,0 +1,44 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_once 3 2024-05-02 "Linux man-pages (unreleased)" +. +. +.SH NAME +pthread_once +\- +once-only initialization +. +. +.SH SYNOPSIS +.B #include +.P +.BI "pthread_once_t " once_control " = PTHREAD_ONCE_INIT;" +.P +.BI "int pthread_once(pthread_once_t *" once_control ", void (*" init_routine ") (void));" +. +. +.SH DESCRIPTION +The purpose of \fBpthread_once\fP is +to ensure that a piece of initialization code is executed at most once. +The \fIonce_control\fP argument points to a static or extern variable +statically initialized to \fBPTHREAD_ONCE_INIT\fP. +.P +The first time \fBpthread_once\fP is called +with a given \fIonce_control\fP argument, +it calls \fIinit_routine\fP with no argument +and changes the value of the \fIonce_control\fP variable +to record that initialization has been performed. +Subsequent calls to \fBpthread_once\fP +with the same \fBonce_control\fP argument +do nothing. +. +. +.SH "RETURN VALUE" +\fBpthread_once\fP always returns 0. +. +. +.SH ERRORS +None. diff --git a/man/man3/pthread_rwlockattr_getkind_np.3 b/man/man3/pthread_rwlockattr_getkind_np.3 new file mode 100644 index 0000000..6f3f740 --- /dev/null +++ b/man/man3/pthread_rwlockattr_getkind_np.3 @@ -0,0 +1 @@ +.so man3/pthread_rwlockattr_setkind_np.3 diff --git a/man/man3/pthread_rwlockattr_setkind_np.3 b/man/man3/pthread_rwlockattr_setkind_np.3 new file mode 100644 index 0000000..ce6a14c --- /dev/null +++ b/man/man3/pthread_rwlockattr_setkind_np.3 @@ -0,0 +1,119 @@ +.\"Copyright (c) 2010 Novell Inc., written by Robert Schweikert +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_rwlockattr_setkind_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_rwlockattr_setkind_np, pthread_rwlockattr_getkind_np \- set/get +the read-write lock kind of the thread read-write lock attribute object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_rwlockattr_setkind_np(pthread_rwlockattr_t *" attr , +.BI " int " pref ); +.B int pthread_rwlockattr_getkind_np( +.BI " const pthread_rwlockattr_t *restrict " attr , +.BI " int *restrict " pref ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_rwlockattr_setkind_np (), +.BR pthread_rwlockattr_getkind_np (): +.nf + _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200809L +.fi +.SH DESCRIPTION +The +.BR pthread_rwlockattr_setkind_np () +function sets the "lock kind" attribute of the +read-write lock attribute object referred to by +.I attr +to the value specified in +.IR pref . +The argument +.I pref +may be set to one of the following: +.TP +.B PTHREAD_RWLOCK_PREFER_READER_NP +This is the default. +A thread may hold multiple read locks; that is, read locks are recursive. +According to The Single Unix Specification, the behavior is unspecified when a +reader tries to place a lock, and there is no write lock but writers are +waiting. +Giving preference to the reader, as is set by +.BR PTHREAD_RWLOCK_PREFER_READER_NP , +implies that the reader will receive the requested lock, even if +a writer is waiting. +As long as there are readers, the writer will be +starved. +.TP +.B PTHREAD_RWLOCK_PREFER_WRITER_NP +This is intended as the write lock analog of +.BR PTHREAD_RWLOCK_PREFER_READER_NP . +This is ignored by glibc because the POSIX requirement to support +recursive read locks would cause this option to create trivial +deadlocks; instead use +.B PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP +which ensures the application developer will not take recursive +read locks thus avoiding deadlocks. +.\" --- +.\" Here is the relevant wording: +.\" +.\" A thread may hold multiple concurrent read locks on rwlock (that is, +.\" successfully call the pthread_rwlock_rdlock() function n times). If +.\" so, the thread must perform matching unlocks (that is, it must call +.\" the pthread_rwlock_unlock() function n times). +.\" +.\" By making write-priority work correctly, I broke the above requirement, +.\" because I had no clue that recursive read locks are permissible. +.\" +.\" If a thread which holds a read lock tries to acquire another read lock, +.\" and now one or more writers is waiting for a write lock, then the algorithm +.\" will lead to an obvious deadlock. The reader will be suspended, waiting for +.\" the writers to acquire and release the lock, and the writers will be +.\" suspended waiting for every existing read lock to be released. +.\" --- +.\" https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_rwlock_rdlock.html +.\" https://sourceware.org/legacy-ml/libc-alpha/2000-01/msg00055.html +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=7057 +.TP +.B PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP +Setting the lock kind to this +avoids writer starvation as long as any read locking is not done in a +recursive fashion. +.P +The +.BR pthread_rwlockattr_getkind_np () +function returns the value of the lock kind attribute of the +read-write lock attribute object referred to by +.I attr +in the pointer +.IR pref . +.SH RETURN VALUE +On success, these functions return 0. +Given valid pointer arguments, +.BR pthread_rwlockattr_getkind_np () +always succeeds. +On error, +.BR pthread_rwlockattr_setkind_np () +returns a nonzero error number. +.SH ERRORS +.TP +.B EINVAL +.I pref +specifies an unsupported value. +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.1. +.SH SEE ALSO +.BR pthreads (7) diff --git a/man/man3/pthread_self.3 b/man/man3/pthread_self.3 new file mode 100644 index 0000000..1d2f5ce --- /dev/null +++ b/man/man3/pthread_self.3 @@ -0,0 +1,77 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_self 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_self \- obtain ID of the calling thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.B pthread_t pthread_self(void); +.fi +.SH DESCRIPTION +The +.BR pthread_self () +function returns the ID of the calling thread. +This is the same value that is returned in +.I *thread +in the +.BR pthread_create (3) +call that created this thread. +.SH RETURN VALUE +This function always succeeds, returning the calling thread's ID. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_self () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +POSIX.1 allows an implementation wide freedom in choosing +the type used to represent a thread ID; +for example, representation using either an arithmetic type or +a structure is permitted. +Therefore, variables of type +.I pthread_t +can't portably be compared using the C equality operator (\fB==\fP); +use +.BR pthread_equal (3) +instead. +.P +Thread identifiers should be considered opaque: +any attempt to use a thread ID other than in pthreads calls +is nonportable and can lead to unspecified results. +.P +Thread IDs are guaranteed to be unique only within a process. +A thread ID may be reused after a terminated thread has been joined, +or a detached thread has terminated. +.P +The thread ID returned by +.BR pthread_self () +is not the same thing as the kernel thread ID returned by a call to +.BR gettid (2). +.SH SEE ALSO +.BR pthread_create (3), +.BR pthread_equal (3), +.BR pthreads (7) diff --git a/man/man3/pthread_setaffinity_np.3 b/man/man3/pthread_setaffinity_np.3 new file mode 100644 index 0000000..779f389 --- /dev/null +++ b/man/man3/pthread_setaffinity_np.3 @@ -0,0 +1,207 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setaffinity_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setaffinity_np, pthread_getaffinity_np \- set/get +CPU affinity of a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int pthread_setaffinity_np(pthread_t " thread ", size_t " cpusetsize , +.BI " const cpu_set_t *" cpuset ); +.BI "int pthread_getaffinity_np(pthread_t " thread ", size_t " cpusetsize , +.BI " cpu_set_t *" cpuset ); +.fi +.SH DESCRIPTION +The +.BR pthread_setaffinity_np () +function +sets the CPU affinity mask of the thread +.I thread +to the CPU set pointed to by +.IR cpuset . +If the call is successful, +and the thread is not currently running on one of the CPUs in +.IR cpuset , +then it is migrated to one of those CPUs. +.P +The +.BR pthread_getaffinity_np () +function returns the CPU affinity mask of the thread +.I thread +in the buffer pointed to by +.IR cpuset . +.P +For more details on CPU affinity masks, see +.BR sched_setaffinity (2). +For a description of a set of macros +that can be used to manipulate and inspect CPU sets, see +.BR CPU_SET (3). +.P +The argument +.I cpusetsize +is the length (in bytes) of the buffer pointed to by +.IR cpuset . +Typically, this argument would be specified as +.IR sizeof(cpu_set_t) . +(It may be some other value, if using the macros described in +.BR CPU_SET (3) +for dynamically allocating a CPU set.) +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.TP +.B EFAULT +A supplied memory address was invalid. +.TP +.B EINVAL +.RB ( pthread_setaffinity_np ()) +The affinity bit mask +.I mask +contains no processors that are currently physically on the system +and permitted to the thread according to any restrictions that +may be imposed by the "cpuset" mechanism described in +.BR cpuset (7). +.TP +.B EINVAL +.RB ( pthread_setaffinity_np ()) +.I cpuset +specified a CPU that was outside the set supported by the kernel. +(The kernel configuration option +.B CONFIG_NR_CPUS +defines the range of the set supported by the kernel data type +.\" cpumask_t +used to represent CPU sets.) +.\" The raw sched_getaffinity() system call returns the size (in bytes) +.\" of the cpumask_t type. +.TP +.B EINVAL +.RB ( pthread_getaffinity_np ()) +.I cpusetsize +is smaller than the size of the affinity mask used by the kernel. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setaffinity_np (), +.BR pthread_getaffinity_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.3.4. +.P +In glibc 2.3.3 only, +versions of these functions were provided that did not have a +.I cpusetsize +argument. +Instead the CPU set size given to the underlying system calls was always +.IR sizeof(cpu_set_t) . +.SH NOTES +After a call to +.BR pthread_setaffinity_np (), +the set of CPUs on which the thread will actually run is +the intersection of the set specified in the +.I cpuset +argument and the set of CPUs actually present on the system. +The system may further restrict the set of CPUs on which the thread +runs if the "cpuset" mechanism described in +.BR cpuset (7) +is being used. +These restrictions on the actual set of CPUs on which the thread +will run are silently imposed by the kernel. +.P +These functions are implemented on top of the +.BR sched_setaffinity (2) +and +.BR sched_getaffinity (2) +system calls. +.P +A new thread created by +.BR pthread_create (3) +inherits a copy of its creator's CPU affinity mask. +.SH EXAMPLES +In the following program, the main thread uses +.BR pthread_setaffinity_np () +to set its CPU affinity mask to include CPUs 0 to 7 +(which may not all be available on the system), +and then calls +.BR pthread_getaffinity_np () +to check the resulting CPU affinity mask of the thread. +.P +.\" SRC BEGIN (pthread_setaffinity_np.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +\& +int +main(void) +{ + int s; + cpu_set_t cpuset; + pthread_t thread; +\& + thread = pthread_self(); +\& + /* Set affinity mask to include CPUs 0 to 7. */ +\& + CPU_ZERO(&cpuset); + for (size_t j = 0; j < 8; j++) + CPU_SET(j, &cpuset); +\& + s = pthread_setaffinity_np(thread, sizeof(cpuset), &cpuset); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_setaffinity_np"); +\& + /* Check the actual affinity mask assigned to the thread. */ +\& + s = pthread_getaffinity_np(thread, sizeof(cpuset), &cpuset); + if (s != 0) + errc(EXIT_FAILURE, s, "pthread_getaffinity_np"); +\& + printf("Set returned by pthread_getaffinity_np() contained:\en"); + for (size_t j = 0; j < CPU_SETSIZE; j++) + if (CPU_ISSET(j, &cpuset)) + printf(" CPU %zu\en", j); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sched_setaffinity (2), +.BR CPU_SET (3), +.BR pthread_attr_setaffinity_np (3), +.BR pthread_self (3), +.BR sched_getcpu (3), +.BR cpuset (7), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_setattr_default_np.3 b/man/man3/pthread_setattr_default_np.3 new file mode 100644 index 0000000..1ea2ab6 --- /dev/null +++ b/man/man3/pthread_setattr_default_np.3 @@ -0,0 +1 @@ +.so man3/pthread_getattr_default_np.3 diff --git a/man/man3/pthread_setcancelstate.3 b/man/man3/pthread_setcancelstate.3 new file mode 100644 index 0000000..6b65f0f --- /dev/null +++ b/man/man3/pthread_setcancelstate.3 @@ -0,0 +1,200 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setcancelstate 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setcancelstate, pthread_setcanceltype \- +set cancelability state and type +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_setcancelstate(int " state ", int *" oldstate ); +.BI "int pthread_setcanceltype(int " type ", int *" oldtype ); +.fi +.SH DESCRIPTION +The +.BR pthread_setcancelstate () +sets the cancelability state of the calling thread to the value +given in +.IR state . +The previous cancelability state of the thread is returned +in the buffer pointed to by +.IR oldstate . +The +.I state +argument must have one of the following values: +.TP +.B PTHREAD_CANCEL_ENABLE +The thread is cancelable. +This is the default cancelability state in all new threads, +including the initial thread. +The thread's cancelability type determines when a cancelable thread +will respond to a cancelation request. +.TP +.B PTHREAD_CANCEL_DISABLE +The thread is not cancelable. +If a cancelation request is received, +it is blocked until cancelability is enabled. +.P +The +.BR pthread_setcanceltype () +sets the cancelability type of the calling thread to the value +given in +.IR type . +The previous cancelability type of the thread is returned +in the buffer pointed to by +.IR oldtype . +The +.I type +argument must have one of the following values: +.TP +.B PTHREAD_CANCEL_DEFERRED +A cancelation request is deferred until the thread next calls +a function that is a cancelation point (see +.BR pthreads (7)). +This is the default cancelability type in all new threads, +including the initial thread. +.IP +Even with deferred cancelation, a +cancelation point in an asynchronous signal handler may still +be acted upon and the effect is as if it was an asynchronous +cancelation. +.TP +.B PTHREAD_CANCEL_ASYNCHRONOUS +The thread can be canceled at any time. +(Typically, +it will be canceled immediately upon receiving a cancelation request, +but the system doesn't guarantee this.) +.P +The set-and-get operation performed by each of these functions +is atomic with respect to other threads in the process +calling the same function. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +The +.BR pthread_setcancelstate () +can fail with the following error: +.TP +.B EINVAL +Invalid value for +.IR state . +.P +The +.BR pthread_setcanceltype () +can fail with the following error: +.TP +.B EINVAL +Invalid value for +.IR type . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setcancelstate (), +.BR pthread_setcanceltype () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +T{ +.na +.nh +.BR pthread_setcancelstate (), +.BR pthread_setcanceltype () +T} Async-cancel safety T{ +.na +.nh +AC-Safe +T} +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0 +POSIX.1-2001. +.SH NOTES +For details of what happens when a thread is canceled, see +.BR \%pthread_cancel (3). +.P +Briefly disabling cancelability is useful +if a thread performs some critical action +that must not be interrupted by a cancelation request. +Beware of disabling cancelability for long periods, +or around operations that may block for long periods, +since that will render the thread unresponsive to cancelation requests. +.SS Asynchronous cancelability +Setting the cancelability type to +.B PTHREAD_CANCEL_ASYNCHRONOUS +is rarely useful. +Since the thread could be canceled at +.I any +time, it cannot safely reserve resources (e.g., allocating memory with +.BR malloc (3)), +acquire mutexes, semaphores, or locks, and so on. +Reserving resources is unsafe because the application has no way of +knowing what the state of these resources is when the thread is canceled; +that is, did cancelation occur before the resources were reserved, +while they were reserved, or after they were released? +Furthermore, some internal data structures +(e.g., the linked list of free blocks managed by the +.BR malloc (3) +family of functions) may be left in an inconsistent state +if cancelation occurs in the middle of the function call. +Consequently, clean-up handlers cease to be useful. +.P +Functions that can be safely asynchronously canceled are called +.IR "async-cancel-safe functions" . +POSIX.1-2001 and POSIX.1-2008 require only that +.BR pthread_cancel (3), +.BR pthread_setcancelstate (), +and +.BR pthread_setcanceltype () +be async-cancel-safe. +In general, other library functions +can't be safely called from an asynchronously cancelable thread. +.P +One of the few circumstances in which asynchronous cancelability is useful +is for cancelation of a thread that is in a pure compute-bound loop. +.SS Portability notes +The Linux threading implementations permit the +.I oldstate +argument of +.BR pthread_setcancelstate () +to be NULL, in which case the information about the previous +cancelability state is not returned to the caller. +Many other implementations also permit a NULL +.I oldstat +argument, +.\" It looks like at least Solaris, FreeBSD and Tru64 support this. +but POSIX.1 does not specify this point, +so portable applications should always specify a non-NULL value in +.IR oldstate . +A precisely analogous set of statements applies for the +.I oldtype +argument of +.BR pthread_setcanceltype (). +.SH EXAMPLES +See +.BR pthread_cancel (3). +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_testcancel (3), +.BR pthreads (7) diff --git a/man/man3/pthread_setcanceltype.3 b/man/man3/pthread_setcanceltype.3 new file mode 100644 index 0000000..9625bc2 --- /dev/null +++ b/man/man3/pthread_setcanceltype.3 @@ -0,0 +1 @@ +.so man3/pthread_setcancelstate.3 diff --git a/man/man3/pthread_setconcurrency.3 b/man/man3/pthread_setconcurrency.3 new file mode 100644 index 0000000..cee31b6 --- /dev/null +++ b/man/man3/pthread_setconcurrency.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright (c) 2009 Michael Kerrisk, +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setconcurrency 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setconcurrency, pthread_getconcurrency \- set/get +the concurrency level +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_setconcurrency(int " new_level ); +.BI "int pthread_getconcurrency(" void ); +.fi +.SH DESCRIPTION +The +.BR pthread_setconcurrency () +function informs the implementation of the application's +desired concurrency level, specified in +.IR new_level . +The implementation takes this only as a hint: +POSIX.1 does not specify the level of concurrency that +should be provided as a result of calling +.BR pthread_setconcurrency (). +.P +Specifying +.I new_level +as 0 instructs the implementation to manage the concurrency level +as it deems appropriate. +.P +.BR pthread_getconcurrency () +returns the current value of the concurrency level for this process. +.SH RETURN VALUE +On success, +.BR pthread_setconcurrency () +returns 0; +on error, it returns a nonzero error number. +.P +.BR pthread_getconcurrency () +always succeeds, returning the concurrency level set by a previous call to +.BR pthread_setconcurrency (), +or 0, if +.BR pthread_setconcurrency () +has not previously been called. +.SH ERRORS +.BR pthread_setconcurrency () +can fail with the following error: +.TP +.B EINVAL +.I new_level +is negative. +.P +POSIX.1 also documents an +.B EAGAIN +error ("the value specified by +.I new_level +would cause a system resource to be exceeded"). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setconcurrency (), +.BR pthread_getconcurrency () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH NOTES +The default concurrency level is 0. +.P +Concurrency levels are meaningful only for M:N threading implementations, +where at any moment a subset of a process's set of user-level threads +may be bound to a smaller number of kernel-scheduling entities. +Setting the concurrency level allows the application to +give the system a hint as to the number of kernel-scheduling entities +that should be provided for efficient execution of the application. +.P +Both LinuxThreads and NPTL are 1:1 threading implementations, +so setting the concurrency level has no meaning. +In other words, +on Linux these functions merely exist for compatibility with other systems, +and they have no effect on the execution of a program. +.SH SEE ALSO +.BR pthread_attr_setscope (3), +.BR pthreads (7) diff --git a/man/man3/pthread_setname_np.3 b/man/man3/pthread_setname_np.3 new file mode 100644 index 0000000..b426d51 --- /dev/null +++ b/man/man3/pthread_setname_np.3 @@ -0,0 +1,202 @@ +'\" t +.\" Copyright (C) 2012 Chandan Apsangi +.\" and Copyright (C) 2013 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setname_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setname_np, pthread_getname_np \- set/get the name of a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int pthread_setname_np(pthread_t " thread ", const char *" name ); +.BI "int pthread_getname_np(pthread_t " thread ", char " name [. size "], \ +size_t " size ); +.fi +.SH DESCRIPTION +By default, all the threads created using +.BR pthread_create () +inherit the program name. +The +.BR pthread_setname_np () +function can be used to set a unique name for a thread, +which can be useful for debugging +multithreaded applications. +The thread name is a meaningful C language string, +whose length is restricted to 16 characters, +including the terminating null byte (\[aq]\e0\[aq]). +The +.I thread +argument specifies the thread whose name is to be changed; +.I name +specifies the new name. +.P +The +.BR pthread_getname_np () +function can be used to retrieve the name of the thread. +The +.I thread +argument specifies the thread whose name is to be retrieved. +The buffer +.I name +is used to return the thread name; +.I size +specifies the number of bytes available in +.IR name . +The buffer specified by +.I name +should be at least 16 characters in length. +The returned thread name in the output buffer will be null terminated. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +The +.BR pthread_setname_np () +function can fail with the following error: +.TP +.B ERANGE +The length of the string specified pointed to by +.I name +exceeds the allowed limit. +.P +The +.BR pthread_getname_np () +function can fail with the following error: +.TP +.B ERANGE +The buffer specified by +.I name +and +.I size +is too small to hold the thread name. +.P +If either of these functions fails to open +.IR /proc/self/task/ tid /comm , +then the call may fail with one of the errors described in +.BR open (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setname_np (), +.BR pthread_getname_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.12. +.SH NOTES +.BR pthread_setname_np () +internally writes to the thread-specific +.I comm +file under the +.I /proc +filesystem: +.IR /proc/self/task/ tid /comm . +.BR pthread_getname_np () +retrieves it from the same location. +.SH EXAMPLES +The program below demonstrates the use of +.BR pthread_setname_np () +and +.BR pthread_getname_np (). +.P +The following shell session shows a sample run of the program: +.P +.in +4n +.EX +.RB "$" " ./a.out" +Created a thread. Default name is: a.out +The thread name after setting it is THREADFOO. +\fB\[ha]Z\fP # Suspend the program +[1]+ Stopped ./a.out +.RB "$ " "ps H \-C a.out \-o \[aq]pid tid cmd comm\[aq]" + PID TID CMD COMMAND + 5990 5990 ./a.out a.out + 5990 5991 ./a.out THREADFOO +.RB "$ " "cat /proc/5990/task/5990/comm" +a.out +.RB "$ " "cat /proc/5990/task/5991/comm" +THREADFOO +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_setname_np.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +\& +#define NAMELEN 16 +\& +static void * +threadfunc(void *parm) +{ + sleep(5); // allow main program to set the thread name + return NULL; +} +\& +int +main(int argc, char *argv[]) +{ + pthread_t thread; + int rc; + char thread_name[NAMELEN]; +\& + rc = pthread_create(&thread, NULL, threadfunc, NULL); + if (rc != 0) + errc(EXIT_FAILURE, rc, "pthread_create"); +\& + rc = pthread_getname_np(thread, thread_name, NAMELEN); + if (rc != 0) + errc(EXIT_FAILURE, rc, "pthread_getname_np"); +\& + printf("Created a thread. Default name is: %s\en", thread_name); + rc = pthread_setname_np(thread, (argc > 1) ? argv[1] : "THREADFOO"); + if (rc != 0) + errc(EXIT_FAILURE, rc, "pthread_setname_np"); +\& + sleep(2); +\& + rc = pthread_getname_np(thread, thread_name, NAMELEN); + if (rc != 0) + errc(EXIT_FAILURE, rc, "pthread_getname_np"); + printf("The thread name after setting it is %s.\en", thread_name); +\& + rc = pthread_join(thread, NULL); + if (rc != 0) + errc(EXIT_FAILURE, rc, "pthread_join"); +\& + printf("Done\en"); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR prctl (2), +.BR pthread_create (3), +.BR pthreads (7) diff --git a/man/man3/pthread_setschedparam.3 b/man/man3/pthread_setschedparam.3 new file mode 100644 index 0000000..f212f33 --- /dev/null +++ b/man/man3/pthread_setschedparam.3 @@ -0,0 +1,448 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setschedparam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setschedparam, pthread_getschedparam \- set/get +scheduling policy and parameters of a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_setschedparam(pthread_t " thread ", int " policy , +.BI " const struct sched_param *" param ); +.BI "int pthread_getschedparam(pthread_t " thread ", int *restrict " policy , +.BI " struct sched_param *restrict " param ); +.fi +.SH DESCRIPTION +The +.BR pthread_setschedparam () +function sets the scheduling policy and parameters of the thread +.IR thread . +.P +.I policy +specifies the new scheduling policy for +.IR thread . +The supported values for +.IR policy , +and their semantics, are described in +.BR sched (7). +.\" FIXME . pthread_setschedparam() places no restriction on the policy, +.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013 +.P +The structure pointed to by +.I param +specifies the new scheduling parameters for +.IR thread . +Scheduling parameters are maintained in the following structure: +.P +.in +4n +.EX +struct sched_param { + int sched_priority; /* Scheduling priority */ +}; +.EE +.in +.P +As can be seen, only one scheduling parameter is supported. +For details of the permitted ranges for scheduling priorities +in each scheduling policy, see +.BR sched (7). +.P +The +.BR pthread_getschedparam () +function returns the scheduling policy and parameters of the thread +.IR thread , +in the buffers pointed to by +.I policy +and +.IR param , +respectively. +The returned priority value is that set by the most recent +.BR pthread_setschedparam (), +.BR pthread_setschedprio (3), +or +.BR pthread_create (3) +call that affected +.IR thread . +The returned priority does not reflect any temporary priority adjustments +as a result of calls to any priority inheritance or +priority ceiling functions (see, for example, +.BR pthread_mutexattr_setprioceiling (3) +and +.BR pthread_mutexattr_setprotocol (3)). +.\" FIXME . nptl/pthread_setschedparam.c has the following +.\" /* If the thread should have higher priority because of some +.\" PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */ +.\" Eventually (perhaps after writing the mutexattr pages), we +.\" may want to add something on the topic to this page. +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +If +.BR pthread_setschedparam () +fails, the scheduling policy and parameters of +.I thread +are not changed. +.SH ERRORS +Both of these functions can fail with the following error: +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.P +.BR pthread_setschedparam () +may additionally fail with the following errors: +.TP +.B EINVAL +.I policy +is not a recognized policy, or +.I param +does not make sense for the +.IR policy . +.TP +.B EPERM +The caller does not have appropriate privileges +to set the specified scheduling policy and parameters. +.P +POSIX.1 also documents an +.B ENOTSUP +("attempt was made to set the policy or scheduling parameters +to an unsupported value") error for +.BR pthread_setschedparam (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setschedparam (), +.BR pthread_getschedparam () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0 +POSIX.1-2001. +.SH NOTES +For a description of the permissions required to, and the effect of, +changing a thread's scheduling policy and priority, +and details of the permitted ranges for priorities +in each scheduling policy, see +.BR sched (7). +.SH EXAMPLES +The program below demonstrates the use of +.BR pthread_setschedparam () +and +.BR pthread_getschedparam (), +as well as the use of a number of other scheduling-related +pthreads functions. +.P +In the following run, the main thread sets its scheduling policy to +.B SCHED_FIFO +with a priority of 10, +and initializes a thread attributes object with +a scheduling policy attribute of +.B SCHED_RR +and a scheduling priority attribute of 20. +The program then sets (using +.BR pthread_attr_setinheritsched (3)) +the inherit scheduler attribute of the thread attributes object to +.BR PTHREAD_EXPLICIT_SCHED , +meaning that threads created using this attributes object should +take their scheduling attributes from the thread attributes object. +The program then creates a thread using the thread attributes object, +and that thread displays its scheduling policy and priority. +.P +.in +4n +.EX +$ \fBsu\fP # Need privilege to set real\-time scheduling policies +Password: +# \fB./a.out \-mf10 \-ar20 \-i e\fP +Scheduler settings of main thread + policy=SCHED_FIFO, priority=10 +\& +Scheduler settings in \[aq]attr\[aq] + policy=SCHED_RR, priority=20 + inheritsched is EXPLICIT +\& +Scheduler attributes of new thread + policy=SCHED_RR, priority=20 +.EE +.in +.P +In the above output, one can see that the scheduling policy and priority +were taken from the values specified in the thread attributes object. +.P +The next run is the same as the previous, +except that the inherit scheduler attribute is set to +.BR PTHREAD_INHERIT_SCHED , +meaning that threads created using the thread attributes object should +ignore the scheduling attributes specified in the attributes object +and instead take their scheduling attributes from the creating thread. +.P +.in +4n +.EX +# \fB./a.out \-mf10 \-ar20 \-i i\fP +Scheduler settings of main thread + policy=SCHED_FIFO, priority=10 +\& +Scheduler settings in \[aq]attr\[aq] + policy=SCHED_RR, priority=20 + inheritsched is INHERIT +\& +Scheduler attributes of new thread + policy=SCHED_FIFO, priority=10 +.EE +.in +.P +In the above output, one can see that the scheduling policy and priority +were taken from the creating thread, +rather than the thread attributes object. +.P +Note that if we had omitted the +.I \-i\~i +option, the output would have been the same, since +.B PTHREAD_INHERIT_SCHED +is the default for the inherit scheduler attribute. +.SS Program source +\& +.\" SRC BEGIN (pthreads_sched_test.c) +.EX +/* pthreads_sched_test.c */ +\& +#include +#include +#include +#include +#include +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +[[noreturn]] +static void +usage(char *prog_name, char *msg) +{ + if (msg != NULL) + fputs(msg, stderr); +\& + fprintf(stderr, "Usage: %s [options]\en", prog_name); + fprintf(stderr, "Options are:\en"); +#define fpe(msg) fprintf(stderr, "\et%s", msg) /* Shorter */ + fpe("\-a Set scheduling policy and priority in\en"); + fpe(" thread attributes object\en"); + fpe(" can be\en"); + fpe(" f SCHED_FIFO\en"); + fpe(" r SCHED_RR\en"); + fpe(" o SCHED_OTHER\en"); + fpe("\-A Use default thread attributes object\en"); + fpe("\-i {e|i} Set inherit scheduler attribute to\en"); + fpe(" \[aq]explicit\[aq] or \[aq]inherit\[aq]\en"); + fpe("\-m Set scheduling policy and priority on\en"); + fpe(" main thread before pthread_create() call\en"); + exit(EXIT_FAILURE); +} +\& +static int +get_policy(char p, int *policy) +{ + switch (p) { + case \[aq]f\[aq]: *policy = SCHED_FIFO; return 1; + case \[aq]r\[aq]: *policy = SCHED_RR; return 1; + case \[aq]o\[aq]: *policy = SCHED_OTHER; return 1; + default: return 0; + } +} +\& +static void +display_sched_attr(int policy, const struct sched_param *param) +{ + printf(" policy=%s, priority=%d\en", + (policy == SCHED_FIFO) ? "SCHED_FIFO" : + (policy == SCHED_RR) ? "SCHED_RR" : + (policy == SCHED_OTHER) ? "SCHED_OTHER" : + "???", + param\->sched_priority); +} +\& +static void +display_thread_sched_attr(char *msg) +{ + int policy, s; + struct sched_param param; +\& + s = pthread_getschedparam(pthread_self(), &policy, ¶m); + if (s != 0) + handle_error_en(s, "pthread_getschedparam"); +\& + printf("%s\en", msg); + display_sched_attr(policy, ¶m); +} +\& +static void * +thread_start(void *arg) +{ + display_thread_sched_attr("Scheduler attributes of new thread"); +\& + return NULL; +} +\& +int +main(int argc, char *argv[]) +{ + int s, opt, inheritsched, use_null_attrib, policy; + pthread_t thread; + pthread_attr_t attr; + pthread_attr_t *attrp; + char *attr_sched_str, *main_sched_str, *inheritsched_str; + struct sched_param param; +\& + /* Process command\-line options. */ +\& + use_null_attrib = 0; + attr_sched_str = NULL; + main_sched_str = NULL; + inheritsched_str = NULL; +\& + while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) { + switch (opt) { + case \[aq]a\[aq]: attr_sched_str = optarg; break; + case \[aq]A\[aq]: use_null_attrib = 1; break; + case \[aq]i\[aq]: inheritsched_str = optarg; break; + case \[aq]m\[aq]: main_sched_str = optarg; break; + default: usage(argv[0], "Unrecognized option\en"); + } + } +\& + if (use_null_attrib + && (inheritsched_str != NULL || attr_sched_str != NULL)) + { + usage(argv[0], "Can\[aq]t specify \-A with \-i or \-a\en"); + } +\& + /* Optionally set scheduling attributes of main thread, + and display the attributes. */ +\& + if (main_sched_str != NULL) { + if (!get_policy(main_sched_str[0], &policy)) + usage(argv[0], "Bad policy for main thread (\-m)\en"); + param.sched_priority = strtol(&main_sched_str[1], NULL, 0); +\& + s = pthread_setschedparam(pthread_self(), policy, ¶m); + if (s != 0) + handle_error_en(s, "pthread_setschedparam"); + } +\& + display_thread_sched_attr("Scheduler settings of main thread"); + printf("\en"); +\& + /* Initialize thread attributes object according to options. */ +\& + attrp = NULL; +\& + if (!use_null_attrib) { + s = pthread_attr_init(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_init"); + attrp = &attr; + } +\& + if (inheritsched_str != NULL) { + if (inheritsched_str[0] == \[aq]e\[aq]) + inheritsched = PTHREAD_EXPLICIT_SCHED; + else if (inheritsched_str[0] == \[aq]i\[aq]) + inheritsched = PTHREAD_INHERIT_SCHED; + else + usage(argv[0], "Value for \-i must be \[aq]e\[aq] or \[aq]i\[aq]\en"); +\& + s = pthread_attr_setinheritsched(&attr, inheritsched); + if (s != 0) + handle_error_en(s, "pthread_attr_setinheritsched"); + } +\& + if (attr_sched_str != NULL) { + if (!get_policy(attr_sched_str[0], &policy)) + usage(argv[0], "Bad policy for \[aq]attr\[aq] (\-a)\en"); + param.sched_priority = strtol(&attr_sched_str[1], NULL, 0); +\& + s = pthread_attr_setschedpolicy(&attr, policy); + if (s != 0) + handle_error_en(s, "pthread_attr_setschedpolicy"); + s = pthread_attr_setschedparam(&attr, ¶m); + if (s != 0) + handle_error_en(s, "pthread_attr_setschedparam"); + } +\& + /* If we initialized a thread attributes object, display + the scheduling attributes that were set in the object. */ +\& + if (attrp != NULL) { + s = pthread_attr_getschedparam(&attr, ¶m); + if (s != 0) + handle_error_en(s, "pthread_attr_getschedparam"); + s = pthread_attr_getschedpolicy(&attr, &policy); + if (s != 0) + handle_error_en(s, "pthread_attr_getschedpolicy"); +\& + printf("Scheduler settings in \[aq]attr\[aq]\en"); + display_sched_attr(policy, ¶m); +\& + pthread_attr_getinheritsched(&attr, &inheritsched); + printf(" inheritsched is %s\en", + (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" : + (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" : + "???"); + printf("\en"); + } +\& + /* Create a thread that will display its scheduling attributes. */ +\& + s = pthread_create(&thread, attrp, &thread_start, NULL); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + /* Destroy unneeded thread attributes object. */ +\& + if (!use_null_attrib) { + s = pthread_attr_destroy(&attr); + if (s != 0) + handle_error_en(s, "pthread_attr_destroy"); + } +\& + s = pthread_join(thread, NULL); + if (s != 0) + handle_error_en(s, "pthread_join"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.ad l +.nh +.BR getrlimit (2), +.BR sched_get_priority_min (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthread_self (3), +.BR pthread_setschedprio (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_setschedprio.3 b/man/man3/pthread_setschedprio.3 new file mode 100644 index 0000000..668d1ec --- /dev/null +++ b/man/man3/pthread_setschedprio.3 @@ -0,0 +1,101 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_setschedprio 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_setschedprio \- set scheduling priority of a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_setschedprio(pthread_t " thread ", int " prio ); +.fi +.SH DESCRIPTION +The +.BR pthread_setschedprio () +function sets the scheduling priority of the thread +.I thread +to the value specified in +.IR prio . +(By contrast +.BR pthread_setschedparam (3) +changes both the scheduling policy and priority of a thread.) +.\" FIXME . nptl/pthread_setschedprio.c has the following +.\" /* If the thread should have higher priority because of some +.\" PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */ +.\" Eventually (perhaps after writing the mutexattr pages), we +.\" may want to add something on the topic to this page. +.\" nptl/pthread_setschedparam.c has a similar case. +.SH RETURN VALUE +On success, this function returns 0; +on error, it returns a nonzero error number. +If +.BR pthread_setschedprio () +fails, the scheduling priority of +.I thread +is not changed. +.SH ERRORS +.TP +.B EINVAL +.I prio +is not valid for the scheduling policy of the specified thread. +.TP +.B EPERM +The caller does not have appropriate privileges +to set the specified priority. +.TP +.B ESRCH +No thread with the ID +.I thread +could be found. +.P +POSIX.1 also documents an +.B ENOTSUP +("attempt was made to set the priority +to an unsupported value") error for +.BR pthread_setschedparam (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_setschedprio () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3.4. +POSIX.1-2001. +.SH NOTES +For a description of the permissions required to, and the effect of, +changing a thread's scheduling priority, +and details of the permitted ranges for priorities +in each scheduling policy, see +.BR sched (7). +.SH SEE ALSO +.ad l +.nh +.BR getrlimit (2), +.BR sched_get_priority_min (2), +.BR pthread_attr_init (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthread_self (3), +.BR pthread_setschedparam (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/pthread_setspecific.3 b/man/man3/pthread_setspecific.3 new file mode 100644 index 0000000..307a947 --- /dev/null +++ b/man/man3/pthread_setspecific.3 @@ -0,0 +1 @@ +.so man3/pthread_key_create.3 diff --git a/man/man3/pthread_sigmask.3 b/man/man3/pthread_sigmask.3 new file mode 100644 index 0000000..810edf3 --- /dev/null +++ b/man/man3/pthread_sigmask.3 @@ -0,0 +1,162 @@ +'\" t +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_sigmask 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_sigmask \- examine and change mask of blocked signals +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_sigmask(int " how ", const sigset_t *" set \ +", sigset_t *" oldset ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_sigmask (): +.nf + _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500 +.fi +.SH DESCRIPTION +The +.BR pthread_sigmask () +function is just like +.BR sigprocmask (2), +with the difference that its use in multithreaded programs +is explicitly specified by POSIX.1. +Other differences are noted in this page. +.P +For a description of the arguments and operation of this function, see +.BR sigprocmask (2). +.SH RETURN VALUE +On success, +.BR pthread_sigmask () +returns 0; +on error, it returns an error number. +.SH ERRORS +See +.BR sigprocmask (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_sigmask () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +A new thread inherits a copy of its creator's signal mask. +.P +The glibc +.BR pthread_sigmask () +function silently ignores attempts to block the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH EXAMPLES +The program below blocks some signals in the main thread, +and then creates a dedicated thread to fetch those signals via +.BR sigwait (3). +The following shell session demonstrates its use: +.P +.in +4n +.EX +.RB "$" " ./a.out &" +[1] 5423 +.RB "$" " kill \-QUIT %1" +Signal handling thread got signal 3 +.RB "$" " kill \-USR1 %1" +Signal handling thread got signal 10 +.RB "$" " kill \-TERM %1" +[1]+ Terminated ./a.out +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (pthread_sigmask.c) +.EX +#include +#include +#include +#include +#include +#include +\& +/* Simple error handling functions */ +\& +#define handle_error_en(en, msg) \e + do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void * +sig_thread(void *arg) +{ + sigset_t *set = arg; + int s, sig; +\& + for (;;) { + s = sigwait(set, &sig); + if (s != 0) + handle_error_en(s, "sigwait"); + printf("Signal handling thread got signal %d\en", sig); + } +} +\& +int +main(void) +{ + pthread_t thread; + sigset_t set; + int s; +\& + /* Block SIGQUIT and SIGUSR1; other threads created by main() + will inherit a copy of the signal mask. */ +\& + sigemptyset(&set); + sigaddset(&set, SIGQUIT); + sigaddset(&set, SIGUSR1); + s = pthread_sigmask(SIG_BLOCK, &set, NULL); + if (s != 0) + handle_error_en(s, "pthread_sigmask"); +\& + s = pthread_create(&thread, NULL, &sig_thread, &set); + if (s != 0) + handle_error_en(s, "pthread_create"); +\& + /* Main thread carries on to create other threads and/or do + other work. */ +\& + pause(); /* Dummy pause so we can test program */ +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sigaction (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR pthread_attr_setsigmask_np (3), +.BR pthread_create (3), +.BR pthread_kill (3), +.BR sigsetops (3), +.BR pthreads (7), +.BR signal (7) diff --git a/man/man3/pthread_sigqueue.3 b/man/man3/pthread_sigqueue.3 new file mode 100644 index 0000000..32e234a --- /dev/null +++ b/man/man3/pthread_sigqueue.3 @@ -0,0 +1,109 @@ +'\" t +.\" Copyright (c) 2010 Michael Kerrisk, +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_sigqueue 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_sigqueue \- queue a signal and data to a thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int pthread_sigqueue(pthread_t " thread ", int " sig , +.BI " const union sigval " value ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_sigqueue (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR pthread_sigqueue () +function performs a similar task to +.BR sigqueue (3), +but, rather than sending a signal to a process, +it sends a signal to a thread in the same process as the +calling thread. +.P +The +.I thread +argument is the ID of a thread in the same process as the caller. +The +.I sig +argument specifies the signal to be sent. +The +.I value +argument specifies data to accompany the signal; see +.BR sigqueue (3) +for details. +.SH RETURN VALUE +On success, +.BR pthread_sigqueue () +returns 0; +on error, it returns an error number. +.SH ERRORS +.TP +.B EAGAIN +The limit of signals which may be queued has been reached. +(See +.BR signal (7) +for further information.) +.TP +.B EINVAL +.I sig +was invalid. +.TP +.B ENOSYS +.BR pthread_sigqueue () +is not supported on this system. +.TP +.B ESRCH +.I thread +is not valid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_sigqueue () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The glibc implementation of +.BR pthread_sigqueue () +gives an error +.RB ( EINVAL ) +on attempts to send either of the real-time signals +used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.11. +.SH SEE ALSO +.BR rt_tgsigqueueinfo (2), +.BR sigaction (2), +.BR pthread_sigmask (3), +.BR sigqueue (3), +.BR sigwait (3), +.BR pthreads (7), +.BR signal (7) diff --git a/man/man3/pthread_spin_destroy.3 b/man/man3/pthread_spin_destroy.3 new file mode 100644 index 0000000..f19c345 --- /dev/null +++ b/man/man3/pthread_spin_destroy.3 @@ -0,0 +1 @@ +.so man3/pthread_spin_init.3 diff --git a/man/man3/pthread_spin_init.3 b/man/man3/pthread_spin_init.3 new file mode 100644 index 0000000..74b6414 --- /dev/null +++ b/man/man3/pthread_spin_init.3 @@ -0,0 +1,148 @@ +.\" Copyright (c) 2017, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_spin_init 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_spin_init(pthread_spinlock_t *" lock ", int " pshared ");" +.BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_spin_init (), +.BR pthread_spin_destroy (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.IR "General note" : +Most programs should use mutexes +instead of spin locks. +Spin locks are primarily useful in conjunction with real-time +scheduling policies. +See NOTES. +.P +The +.BR pthread_spin_init () +function allocates any resources required for the use of +the spin lock referred to by +.I lock +and initializes the lock to be in the unlocked state. +The +.I pshared +argument must have one of the following values: +.TP +.B PTHREAD_PROCESS_PRIVATE +The spin lock is to be operated on only by threads in the same process +as the thread that calls +.BR pthread_spin_init (). +(Attempting to share the spin lock between processes +results in undefined behavior.) +.TP +.B PTHREAD_PROCESS_SHARED +The spin lock may be operated on by any thread in any process that +has access to the memory containing the lock +(i.e., the lock may be in a shared memory object that is +shared among multiple processes). +.P +Calling +.BR pthread_spin_init () +on a spin lock that has already been initialized results +in undefined behavior. +.P +The +.BR pthread_spin_destroy () +function destroys a previously initialized spin lock, +freeing any resources that were allocated for that lock. +Destroying a spin lock that has not been previously been initialized +or destroying a spin lock while another thread holds the lock +results in undefined behavior. +.P +Once a spin lock has been destroyed, +performing any operation on the lock other than +once more initializing it with +.BR pthread_spin_init () +results in undefined behavior. +.P +The result of performing operations such as +.BR pthread_spin_lock (3), +.BR pthread_spin_unlock (3), +and +.BR pthread_spin_destroy () +on +.I copies +of the object referred to by +.I lock +is undefined. +.SH RETURN VALUE +On success, there functions return zero. +On failure, they return an error number. +In the event that +.BR pthread_spin_init () +fails, the lock is not initialized. +.SH ERRORS +.BR pthread_spin_init () +may fail with the following errors: +.\" These errors don't occur on the glibc implementation +.TP +.B EAGAIN +The system has insufficient resources to initialize +a new spin lock. +.TP +.B ENOMEM +Insufficient memory to initialize the spin lock. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.P +Support for process-shared spin locks is a POSIX option. +The option is supported in the glibc implementation. +.SH NOTES +Spin locks should be employed in conjunction with +real-time scheduling policies +.RB ( SCHED_FIFO , +or possibly +.BR SCHED_RR ). +Use of spin locks with nondeterministic scheduling policies such as +.B SCHED_OTHER +probably indicates a design mistake. +The problem is that if a thread operating under such a policy +is scheduled off the CPU while it holds a spin lock, +then other threads will waste time spinning on the lock +until the lock holder is once more rescheduled and releases the lock. +.P +If threads create a deadlock situation while employing spin locks, +those threads will spin forever consuming CPU time. +.P +User-space spin locks are +.I not +applicable as a general locking solution. +They are, by definition, +prone to priority inversion and unbounded spin times. +A programmer using spin locks must be exceptionally careful not +only in the code, but also in terms of system configuration, +thread placement, and priority assignment. +.\" FIXME . When PTHREAD_MUTEX_ADAPTIVE_NP is one day document +.\" make reference to it here +.SH SEE ALSO +.ad l +.nh +.BR pthread_mutex_init (3), +.BR pthread_mutex_lock (3), +.BR pthread_spin_lock (3), +.BR pthread_spin_unlock (3), +.BR pthreads (7) diff --git a/man/man3/pthread_spin_lock.3 b/man/man3/pthread_spin_lock.3 new file mode 100644 index 0000000..56c31da --- /dev/null +++ b/man/man3/pthread_spin_lock.3 @@ -0,0 +1,102 @@ +.\" Copyright (c) 2017, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_spin_lock 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_spin_lock, pthread_spin_trylock, pthread_spin_unlock \- +lock and unlock a spin lock +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int pthread_spin_lock(pthread_spinlock_t *" lock ); +.BI "int pthread_spin_trylock(pthread_spinlock_t *" lock ); +.BI "int pthread_spin_unlock(pthread_spinlock_t *" lock ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR pthread_spin_lock (), +.BR pthread_spin_trylock (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR pthread_spin_lock () +function locks the spin lock referred to by +.IR lock . +If the spin lock is currently unlocked, +the calling thread acquires the lock immediately. +If the spin lock is currently locked by another thread, +the calling thread spins, testing the lock until it becomes available, +at which point the calling thread acquires the lock. +.P +Calling +.BR pthread_spin_lock () +on a lock that is already held by the caller +or a lock that has not been initialized with +.BR pthread_spin_init (3) +results in undefined behavior. +.P +The +.BR pthread_spin_trylock () +function is like +.BR pthread_spin_lock (), +except that if the spin lock referred to by +.I lock +is currently locked, +then, instead of spinning, the call returns immediately with the error +.BR EBUSY . +.P +The +.BR pthread_spin_unlock () +function unlocks the spin lock referred to +.IR lock . +If any threads are spinning on the lock, +one of those threads will then acquire the lock. +.P +Calling +.BR pthread_spin_unlock () +on a lock that is not held by the caller results in undefined behavior. +.SH RETURN VALUE +On success, these functions return zero. +On failure, they return an error number. +.SH ERRORS +.BR pthread_spin_lock () +may fail with the following errors: +.TP +.B EDEADLOCK +.\" Not detected in glibc +The system detected a deadlock condition. +.P +.BR pthread_spin_trylock () +fails with the following errors: +.TP +.B EBUSY +The spin lock is currently locked by another thread. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.SH CAVEATS +Applying any of the functions described on this page to +an uninitialized spin lock results in undefined behavior. +.P +Carefully read NOTES in +.BR pthread_spin_init (3). +.SH SEE ALSO +.ad l +.nh +.\" FIXME . .BR pthread_mutex_lock (3), +.BR pthread_spin_destroy (3), +.BR pthread_spin_init (3), +.BR pthreads (7) diff --git a/man/man3/pthread_spin_trylock.3 b/man/man3/pthread_spin_trylock.3 new file mode 100644 index 0000000..ad2969a --- /dev/null +++ b/man/man3/pthread_spin_trylock.3 @@ -0,0 +1 @@ +.so man3/pthread_spin_lock.3 diff --git a/man/man3/pthread_spin_unlock.3 b/man/man3/pthread_spin_unlock.3 new file mode 100644 index 0000000..ad2969a --- /dev/null +++ b/man/man3/pthread_spin_unlock.3 @@ -0,0 +1 @@ +.so man3/pthread_spin_lock.3 diff --git a/man/man3/pthread_testcancel.3 b/man/man3/pthread_testcancel.3 new file mode 100644 index 0000000..b1ce9fa --- /dev/null +++ b/man/man3/pthread_testcancel.3 @@ -0,0 +1,64 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_testcancel 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_testcancel \- request delivery of any pending cancelation request +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.B void pthread_testcancel(void); +.fi +.SH DESCRIPTION +Calling +.BR pthread_testcancel () +creates a cancelation point within the calling thread, +so that a thread that is otherwise executing code that contains +no cancelation points will respond to a cancelation request. +.P +If cancelability is disabled (using +.BR pthread_setcancelstate (3)), +or no cancelation request is pending, +then a call to +.BR pthread_testcancel () +has no effect. +.SH RETURN VALUE +This function does not return a value. +If the calling thread is canceled as a consequence of a call +to this function, then the function does not return. +.SH ERRORS +This function always succeeds. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_testcancel () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.0. +POSIX.1-2001. +.SH EXAMPLES +See +.BR pthread_cleanup_push (3). +.SH SEE ALSO +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_setcancelstate (3), +.BR pthreads (7) diff --git a/man/man3/pthread_timedjoin_np.3 b/man/man3/pthread_timedjoin_np.3 new file mode 100644 index 0000000..a741f46 --- /dev/null +++ b/man/man3/pthread_timedjoin_np.3 @@ -0,0 +1 @@ +.so man3/pthread_tryjoin_np.3 diff --git a/man/man3/pthread_tryjoin_np.3 b/man/man3/pthread_tryjoin_np.3 new file mode 100644 index 0000000..3e2a32a --- /dev/null +++ b/man/man3/pthread_tryjoin_np.3 @@ -0,0 +1,154 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_tryjoin_np 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_tryjoin_np, pthread_timedjoin_np \- try to join with a +terminated thread +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int pthread_tryjoin_np(pthread_t " thread ", void **" retval ); +.BI "int pthread_timedjoin_np(pthread_t " thread ", void **" retval , +.BI " const struct timespec *" abstime ); +.fi +.SH DESCRIPTION +These functions operate in the same way as +.BR pthread_join (3), +except for the differences described on this page. +.P +The +.BR pthread_tryjoin_np () +function performs a nonblocking join with the thread +.IR thread , +returning the exit status of the thread in +.IR *retval . +If +.I thread +has not yet terminated, then instead of blocking, as is done by +.BR pthread_join (3), +the call returns an error. +.P +The +.BR pthread_timedjoin_np () +function performs a join-with-timeout. +If +.I thread +has not yet terminated, +then the call blocks until a maximum time, specified in +.IR abstime , +measured against the +.B CLOCK_REALTIME +clock. +If the timeout expires before +.I thread +terminates, +the call returns an error. +The +.I abstime +argument is a +.BR timespec (3) +structure, +specifying an absolute time measured since the Epoch (see +.BR time (2)). +.SH RETURN VALUE +On success, +these functions return 0; +on error, they return an error number. +.SH ERRORS +These functions can fail with the same errors as +.BR pthread_join (3). +.BR pthread_tryjoin_np () +can in addition fail with the following error: +.TP +.B EBUSY +.I thread +had not yet terminated at the time of the call. +.P +.BR pthread_timedjoin_np () +can in addition fail with the following errors: +.TP +.B EINVAL +.I abstime +value is invalid +.RI ( tv_sec +is less than 0 or +.I tv_nsec +is greater than 1e9). +.TP +.B ETIMEDOUT +The call timed out before +.I thread +terminated. +.P +.BR pthread_timedjoin_np () +never returns the error +.BR EINTR . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_tryjoin_np (), +.BR pthread_timedjoin_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU; +hence the suffix "_np" (nonportable) in the names. +.SH HISTORY +glibc 2.3.3. +.SH BUGS +The +.BR pthread_timedjoin_np () +function measures time by internally calculating a relative sleep interval +that is then measured against the +.B CLOCK_MONOTONIC +clock instead of the +.B CLOCK_REALTIME +clock. +Consequently, the timeout is unaffected by discontinuous changes to the +.B CLOCK_REALTIME +clock. +.SH EXAMPLES +The following code waits to join for up to 5 seconds: +.P +.in +4n +.EX +struct timespec ts; +int s; +\& +\&... +\& +if (clock_gettime(CLOCK_REALTIME, &ts) == \-1) { + /* Handle error */ +} +\& +ts.tv_sec += 5; +\& +s = pthread_timedjoin_np(thread, NULL, &ts); +if (s != 0) { + /* Handle error */ +} +.EE +.in +.SH SEE ALSO +.BR clock_gettime (2), +.BR pthread_exit (3), +.BR pthread_join (3), +.BR timespec (3), +.BR pthreads (7) diff --git a/man/man3/pthread_yield.3 b/man/man3/pthread_yield.3 new file mode 100644 index 0000000..14ff6b5 --- /dev/null +++ b/man/man3/pthread_yield.3 @@ -0,0 +1,78 @@ +'\" t +.\" Copyright (c) 2009 Michael Kerrisk, +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_yield 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthread_yield \- yield the processor +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.B [[deprecated]] int pthread_yield(void); +.fi +.SH DESCRIPTION +.BR Note : +This function is deprecated; see below. +.P +.BR pthread_yield () +causes the calling thread to relinquish the CPU. +The thread is placed at the end of the run queue for its static +priority and another thread is scheduled to run. +For further details, see +.BR sched_yield (2) +.SH RETURN VALUE +On success, +.BR pthread_yield () +returns 0; +on error, it returns an error number. +.SH ERRORS +On Linux, this call always succeeds +(but portable and future-proof applications should nevertheless +handle a possible error return). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_yield () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On Linux, this function is implemented as a call to +.BR sched_yield (2). +.SH STANDARDS +None. +.SH HISTORY +.\" BSD, Tru64, AIX, and Irix. +Deprecated since glibc 2.34. +Use the standardized +.BR sched_yield (2) +instead. +.SH NOTES +.BR pthread_yield () +is intended for use with real-time scheduling policies (i.e., +.B SCHED_FIFO +or +.BR SCHED_RR ). +Use of +.BR pthread_yield () +with nondeterministic scheduling policies such as +.B SCHED_OTHER +is unspecified and very likely means your application design is broken. +.SH SEE ALSO +.BR sched_yield (2), +.\" FIXME . .BR pthread_cond_wait (3), +.BR pthreads (7), +.BR sched (7) diff --git a/man/man3/ptsname.3 b/man/man3/ptsname.3 new file mode 100644 index 0000000..14cad01 --- /dev/null +++ b/man/man3/ptsname.3 @@ -0,0 +1,146 @@ +'\" t +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. - aeb +.\" %%%LICENSE_END +.\" +.\" 2004-12-17, mtk, added description of ptsname_r() + ERRORS +.\" +.TH ptsname 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ptsname, ptsname_r \- get the name of the slave pseudoterminal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *ptsname(int " fd ); +.BI "int ptsname_r(int " fd ", char " buf [. buflen "], size_t " buflen ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ptsname (): +.nf + Since glibc 2.24: + _XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) + glibc 2.23 and earlier: + _XOPEN_SOURCE +.fi +.P +.BR ptsname_r (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR ptsname () +function returns the name of the slave pseudoterminal device +corresponding to the master referred to by the file descriptor +.IR fd . +.P +The +.BR ptsname_r () +function is the reentrant equivalent of +.BR ptsname (). +It returns the name of the slave pseudoterminal device as a +null-terminated string in the buffer pointed to by +.IR buf . +The +.I buflen +argument specifies the number of bytes available in +.IR buf . +.SH RETURN VALUE +On success, +.BR ptsname () +returns a pointer to a string in static storage which will be +overwritten by subsequent calls. +This pointer must not be freed. +On failure, NULL is returned. +.P +On success, +.BR ptsname_r () +returns 0. +On failure, an error number is returned to indicate the error. +.\" In glibc, the error number is not only returned as the return value +.\" but also stored in errno. But this is not true for musl libc. +.SH ERRORS +.TP +.B EINVAL +.RB ( ptsname_r () +only) +.I buf +is NULL. +(This error is returned only for +.\" glibc commit 8f0a947cf55f3b0c4ebdf06953c57eff67a22fa9 +glibc 2.25 and earlier.) +.TP +.B ENOTTY +.I fd +does not refer to a pseudoterminal master device. +.TP +.B ERANGE +.RB ( ptsname_r () +only) +.I buf +is too small. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ptsname () +T} Thread safety MT-Unsafe race:ptsname +T{ +.na +.nh +.BR ptsname_r () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +A version of +.BR ptsname_r () +is documented on Tru64 and HP-UX, +but on those implementations, +\-1 is returned on error, with +.I errno +set to indicate the error. +Avoid using this function in portable programs. +.SH STANDARDS +.TP +.BR ptsname (): +POSIX.1-2008. +.P +.BR ptsname_r () +is a Linux extension, that is proposed for inclusion +.\" FIXME . for later review when Issue 8 is one day released +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=508 +in the next major revision of POSIX.1 (Issue 8). +.SH HISTORY +.TP +.BR ptsname (): +POSIX.1-2001. +glibc 2.1. +.P +.BR ptsname () +is part of the UNIX 98 pseudoterminal support (see +.BR pts (4)). +.SH SEE ALSO +.BR grantpt (3), +.BR posix_openpt (3), +.BR ttyname (3), +.BR unlockpt (3), +.BR pts (4), +.BR pty (7) diff --git a/man/man3/ptsname_r.3 b/man/man3/ptsname_r.3 new file mode 100644 index 0000000..0a5f98d --- /dev/null +++ b/man/man3/ptsname_r.3 @@ -0,0 +1 @@ +.so man3/ptsname.3 diff --git a/man/man3/putc.3 b/man/man3/putc.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man/man3/putc.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man/man3/putc_unlocked.3 b/man/man3/putc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/putc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/putchar.3 b/man/man3/putchar.3 new file mode 100644 index 0000000..a7c3b57 --- /dev/null +++ b/man/man3/putchar.3 @@ -0,0 +1 @@ +.so man3/puts.3 diff --git a/man/man3/putchar_unlocked.3 b/man/man3/putchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/putchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/putenv.3 b/man/man3/putenv.3 new file mode 100644 index 0000000..fd6bc81 --- /dev/null +++ b/man/man3/putenv.3 @@ -0,0 +1,141 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Single UNIX Specification, Version 2 +.\" Modified Thu Apr 8 15:00:12 1993, David Metcalfe +.\" Modified Sat Jul 24 18:44:45 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Oct 11 11:11:11 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Wed Nov 10 00:02:26 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun May 20 22:17:20 2001 by Andries Brouwer (aeb@cwi.nl) +.TH putenv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +putenv \- change or add an environment variable +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int putenv(char *" string ); +.\" Not: const char * +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR putenv (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR putenv () +function adds or changes the value of environment +variables. +The argument \fIstring\fP is of the form \fIname\fP=\fIvalue\fP. +If \fIname\fP does not already exist in the environment, then +\fIstring\fP is added to the environment. +If \fIname\fP does exist, +then the value of \fIname\fP in the environment is changed to +\fIvalue\fP. +The string pointed to by \fIstring\fP becomes part of the environment, +so altering the string changes the environment. +.SH RETURN VALUE +The +.BR putenv () +function returns zero on success. +On failure, it returns a nonzero value, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient space to allocate new environment. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR putenv () +T} Thread safety MT-Unsafe const:env +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr2, 4.3BSD-Reno. +.P +The +.BR putenv () +function is not required to be reentrant, and the +one in glibc 2.0 is not, but the glibc 2.1 version is. +.\" .P +.\" Description for libc4, libc5, glibc: +.\" If the argument \fIstring\fP is of the form \fIname\fP, +.\" and does not contain an \[aq]=\[aq] character, then the variable \fIname\fP +.\" is removed from the environment. +.\" If +.\" .BR putenv () +.\" has to allocate a new array \fIenviron\fP, +.\" and the previous array was also allocated by +.\" .BR putenv (), +.\" then it will be freed. +.\" In no case will the old storage associated +.\" to the environment variable itself be freed. +.P +Since glibc 2.1.2, the glibc implementation conforms to SUSv2: +the pointer \fIstring\fP given to +.BR putenv () +is used. +In particular, this string becomes part of the environment; +changing it later will change the environment. +(Thus, it is an error to call +.BR putenv () +with an automatic variable +as the argument, then return from the calling function while \fIstring\fP +is still part of the environment.) +However, from glibc 2.0 to glibc 2.1.1, it differs: +a copy of the string is used. +On the one hand this causes a memory leak, and on the other hand +it violates SUSv2. +.P +The 4.3BSD-Reno version, like glibc 2.0, uses a copy; +this is fixed in all modern BSDs. +.P +SUSv2 removes the \fIconst\fP from the prototype, and so does glibc 2.1.3. +.P +The GNU C library implementation provides a nonstandard extension. +If +.I string +does not include an equal sign: +.P +.in +4n +.EX +putenv("NAME"); +.EE +.in +.P +then the named variable is removed from the caller's environment. +.SH SEE ALSO +.BR clearenv (3), +.BR getenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR environ (7) diff --git a/man/man3/putgrent.3 b/man/man3/putgrent.3 new file mode 100644 index 0000000..6437698 --- /dev/null +++ b/man/man3/putgrent.3 @@ -0,0 +1,66 @@ +'\" t +.\" Copyright 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH putgrent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +putgrent \- write a group database entry to a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int putgrent(const struct group *restrict " grp \ +", FILE *restrict " stream ); +.fi +.SH DESCRIPTION +The +.BR putgrent () +function is the counterpart for +.BR fgetgrent (3). +The function writes the content of the provided +.I struct group +into the +.IR stream . +The list of group members must be NULL-terminated or NULL-initialized. +.P +The +.I struct group +is defined as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* group members */ +}; +.EE +.in +.SH RETURN VALUE +The function returns zero on success, and a nonzero value on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR putgrent () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent (3), +.BR group (5) diff --git a/man/man3/putpwent.3 b/man/man3/putpwent.3 new file mode 100644 index 0000000..6742b79 --- /dev/null +++ b/man/man3/putpwent.3 @@ -0,0 +1,96 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:43:46 1993 by Rik Faith (faith@cs.unc.edu) +.TH putpwent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +putpwent \- write a password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.BI "int putpwent(const struct passwd *restrict " p \ +", FILE *restrict " stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR putpwent (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR putpwent () +function writes a password entry from the +structure \fIp\fP in the file associated with \fIstream\fP. +.P +The \fIpasswd\fP structure is defined in \fI\fP as follows: +.P +.in +4n +.EX +struct passwd { + char *pw_name; /* username */ + char *pw_passwd; /* user password */ + uid_t pw_uid; /* user ID */ + gid_t pw_gid; /* group ID */ + char *pw_gecos; /* real name */ + char *pw_dir; /* home directory */ + char *pw_shell; /* shell program */ +}; +.EE +.in +.SH RETURN VALUE +The +.BR putpwent () +function returns 0 on success. +On failure, it returns \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Invalid (NULL) argument given. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR putpwent () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr4. +.SH SEE ALSO +.BR endpwent (3), +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR setpwent (3) diff --git a/man/man3/puts.3 b/man/man3/puts.3 new file mode 100644 index 0000000..5724f62 --- /dev/null +++ b/man/man3/puts.3 @@ -0,0 +1,124 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 18:42:59 1993 by Rik Faith (faith@cs.unc.edu) +.TH puts 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fputc, fputs, putc, putchar, puts \- output of characters and strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int fputc(int " c ", FILE *" stream ); +.BI "int putc(int " c ", FILE *" stream ); +.BI "int putchar(int " c ); +.P +.BI "int fputs(const char *restrict " s ", FILE *restrict " stream ); +.BI "int puts(const char *" s ); +.fi +.SH DESCRIPTION +.BR fputc () +writes the character +.IR c , +cast to an +.IR "unsigned char" , +to +.IR stream . +.P +.BR putc () +is equivalent to +.BR fputc () +except that it may be implemented as a macro which evaluates +.I stream +more than once. +.P +.BI "putchar(" c ) +is equivalent to +.BI "putc(" c ", " stdout ) \fR. +.P +.BR fputs () +writes the string +.I s +to +.IR stream , +without its terminating null byte (\[aq]\e0\[aq]). +.P +.BR puts () +writes the string +.I s +and a trailing newline +to +.IR stdout . +.P +Calls to the functions described here can be mixed with each other and with +calls to other output functions from the +.I stdio +library for the same output stream. +.P +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +.BR fputc (), +.BR putc (), +and +.BR putchar () +return the character written as an +.I unsigned char +cast to an +.I int +or +.B EOF +on error. +.P +.BR puts () +and +.BR fputs () +return a nonnegative number on success, or +.B EOF +on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR fputc (), +.BR fputs (), +.BR putc (), +.BR putchar (), +.BR puts () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, C99. +.SH BUGS +It is not advisable to mix calls to output functions from the +.I stdio +library with low-level calls to +.BR write (2) +for the file descriptor associated with the same output stream; the results +will be undefined and very probably not what you want. +.SH SEE ALSO +.BR write (2), +.BR ferror (3), +.BR fgets (3), +.BR fopen (3), +.BR fputwc (3), +.BR fputws (3), +.BR fseek (3), +.BR fwrite (3), +.BR putwchar (3), +.BR scanf (3), +.BR unlocked_stdio (3) diff --git a/man/man3/putspent.3 b/man/man3/putspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/putspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/pututline.3 b/man/man3/pututline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/pututline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/pututxline.3 b/man/man3/pututxline.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/pututxline.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/putw.3 b/man/man3/putw.3 new file mode 100644 index 0000000..7509345 --- /dev/null +++ b/man/man3/putw.3 @@ -0,0 +1 @@ +.so man3/getw.3 diff --git a/man/man3/putwc.3 b/man/man3/putwc.3 new file mode 100644 index 0000000..81826be --- /dev/null +++ b/man/man3/putwc.3 @@ -0,0 +1 @@ +.so man3/fputwc.3 diff --git a/man/man3/putwc_unlocked.3 b/man/man3/putwc_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/putwc_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/putwchar.3 b/man/man3/putwchar.3 new file mode 100644 index 0000000..14a01ea --- /dev/null +++ b/man/man3/putwchar.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification +.\" http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH putwchar 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +putwchar \- write a wide character to standard output +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wint_t putwchar(wchar_t " wc ); +.fi +.SH DESCRIPTION +The +.BR putwchar () +function is the wide-character equivalent of the +.BR putchar (3) +function. +It writes the wide character +.I wc +to +.IR stdout . +If +.I ferror(stdout) +becomes true, it returns +.BR WEOF . +If a wide character +conversion error occurs, it sets +.I errno +to +.B EILSEQ +and returns +.BR WEOF . +Otherwise, it returns +.IR wc . +.P +For a nonlocking counterpart, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +The +.BR putwchar () +function returns +.I wc +if no error occurred, or +.B WEOF +to indicate an error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR putwchar () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR putwchar () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +It is reasonable to expect that +.BR putwchar () +will actually write +the multibyte sequence corresponding to the wide character +.IR wc . +.SH SEE ALSO +.BR fputwc (3), +.BR unlocked_stdio (3) diff --git a/man/man3/putwchar_unlocked.3 b/man/man3/putwchar_unlocked.3 new file mode 100644 index 0000000..858bd08 --- /dev/null +++ b/man/man3/putwchar_unlocked.3 @@ -0,0 +1 @@ +.so man3/unlocked_stdio.3 diff --git a/man/man3/pvalloc.3 b/man/man3/pvalloc.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man/man3/pvalloc.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man/man3/qecvt.3 b/man/man3/qecvt.3 new file mode 100644 index 0000000..89b169b --- /dev/null +++ b/man/man3/qecvt.3 @@ -0,0 +1,110 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH qecvt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +qecvt, qfcvt, qgcvt \- convert a floating-point number to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] char *qecvt(long double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign ); +.BI "[[deprecated]] char *qfcvt(long double " number ", int " ndigits , +.BI " int *restrict " decpt ", int *restrict " sign ); +.BI "[[deprecated]] char *qgcvt(long double " number ", int " ndigit ", char *" buf ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR qecvt (), +.BR qfcvt (), +.BR qgcvt (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _SVID_SOURCE +.fi +.\" FIXME . The full FTM picture looks to have been something like the +.\" following mess: +.\" glibc 2.20 onward +.\" _DEFAULT_SOURCE +.\" glibc 2.18 to glibc 2.19 +.\" _BSD_SOURCE || _SVID_SOURCE +.\" glibc 2.10 to glibc 2.17 +.\" _SVID_SOURCE || (_XOPEN_SOURCE >= 500 || +.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) && +.\" ! (_POSIX_C_SOURCE >= 200809L)) +.\" Before glibc 2.10: +.\" _SVID_SOURCE || _XOPEN_SOURCE >= 500 || +.\" (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) +.SH DESCRIPTION +The functions +.BR qecvt (), +.BR qfcvt (), +and +.BR qgcvt () +are identical to +.BR ecvt (3), +.BR fcvt (3), +and +.BR gcvt (3) +respectively, except that they use a +.I "long double" +argument +.IR number . +See +.BR ecvt (3) +and +.BR gcvt (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR qecvt () +T} Thread safety MT-Unsafe race:qecvt +T{ +.na +.nh +.BR qfcvt () +T} Thread safety MT-Unsafe race:qfcvt +T{ +.na +.nh +.BR qgcvt () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +SVr4, SunOS, GNU. +.\" Not supported by libc4 and libc5. +.P +These functions are obsolete. +Instead, +.BR snprintf (3) +is recommended. +.SH SEE ALSO +.BR ecvt (3), +.BR ecvt_r (3), +.BR gcvt (3), +.BR sprintf (3) diff --git a/man/man3/qecvt_r.3 b/man/man3/qecvt_r.3 new file mode 100644 index 0000000..41ce9ee --- /dev/null +++ b/man/man3/qecvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man/man3/qfcvt.3 b/man/man3/qfcvt.3 new file mode 100644 index 0000000..7e58310 --- /dev/null +++ b/man/man3/qfcvt.3 @@ -0,0 +1 @@ +.so man3/qecvt.3 diff --git a/man/man3/qfcvt_r.3 b/man/man3/qfcvt_r.3 new file mode 100644 index 0000000..41ce9ee --- /dev/null +++ b/man/man3/qfcvt_r.3 @@ -0,0 +1 @@ +.so man3/ecvt_r.3 diff --git a/man/man3/qgcvt.3 b/man/man3/qgcvt.3 new file mode 100644 index 0000000..7e58310 --- /dev/null +++ b/man/man3/qgcvt.3 @@ -0,0 +1 @@ +.so man3/qecvt.3 diff --git a/man/man3/qsort.3 b/man/man3/qsort.3 new file mode 100644 index 0000000..9cb493e --- /dev/null +++ b/man/man3/qsort.3 @@ -0,0 +1,157 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" 2006-01-15, mtk, Added example program. +.\" Modified 2012-03-08, Mark R. Bannister +.\" and Ben Bacarisse +.\" Document qsort_r() +.\" +.TH qsort 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +qsort, qsort_r \- sort an array +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void qsort(void " base [. size " * ." nmemb "], size_t " nmemb ", \ +size_t " size , +.BI " int (*" compar ")(const void [." size "], \ +const void [." size ])); +.BI "void qsort_r(void " base [. size " * ." nmemb "], size_t " nmemb ", \ +size_t " size , +.BI " int (*" compar ")(const void [." size "], \ +const void [." size "], void *)," +.BI " void *" arg ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR qsort_r (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR qsort () +function sorts an array with \fInmemb\fP elements of +size \fIsize\fP. +The \fIbase\fP argument points to the start of the +array. +.P +The contents of the array are sorted in ascending order according to a +comparison function pointed to by \fIcompar\fP, which is called with two +arguments that point to the objects being compared. +.P +The comparison function must return an integer less than, equal to, or +greater than zero if the first argument is considered to be respectively +less than, equal to, or greater than the second. +If two members compare as equal, +their order in the sorted array is undefined. +.P +The +.BR qsort_r () +function is identical to +.BR qsort () +except that the comparison function +.I compar +takes a third argument. +A pointer is passed to the comparison function via +.IR arg . +In this way, the comparison function does not need to use global variables to +pass through arbitrary arguments, and is therefore reentrant and safe to +use in threads. +.SH RETURN VALUE +The +.BR qsort () +and +.BR qsort_r () +functions return no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR qsort (), +.BR qsort_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR qsort () +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR qsort () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR qsort_r () +glibc 2.8. +.SH NOTES +To compare C strings, the comparison function can call +.BR strcmp (3), +as shown in the example below. +.SH EXAMPLES +For one example of use, see the example under +.BR bsearch (3). +.P +Another example is the following program, +which sorts the strings given in its command-line arguments: +.P +.\" SRC BEGIN (qsort.c) +.EX +#include +#include +#include +\& +static int +cmpstringp(const void *p1, const void *p2) +{ + /* The actual arguments to this function are "pointers to + pointers to char", but strcmp(3) arguments are "pointers + to char", hence the following cast plus dereference. */ +\& + return strcmp(*(const char **) p1, *(const char **) p2); +} +\& +int +main(int argc, char *argv[]) +{ + if (argc < 2) { + fprintf(stderr, "Usage: %s ...\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + qsort(&argv[1], argc \- 1, sizeof(char *), cmpstringp); +\& + for (size_t j = 1; j < argc; j++) + puts(argv[j]); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR sort (1), +.BR alphasort (3), +.BR strcmp (3), +.BR versionsort (3) diff --git a/man/man3/qsort_r.3 b/man/man3/qsort_r.3 new file mode 100644 index 0000000..d073335 --- /dev/null +++ b/man/man3/qsort_r.3 @@ -0,0 +1 @@ +.so man3/qsort.3 diff --git a/man/man3/queue.3 b/man/man3/queue.3 new file mode 100644 index 0000000..000e4b1 --- /dev/null +++ b/man/man3/queue.3 @@ -0,0 +1 @@ +.so man7/queue.7 diff --git a/man/man3/raise.3 b/man/man3/raise.3 new file mode 100644 index 0000000..b4ac02d --- /dev/null +++ b/man/man3/raise.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (C) 2008 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 18:40:56 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995 by Mike Battersby (mib@deakin.edu.au) +.\" +.TH raise 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +raise \- send a signal to the caller +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int raise(int " sig ); +.fi +.SH DESCRIPTION +The +.BR raise () +function sends a signal to the calling process or thread. +In a single-threaded program it is equivalent to +.P +.in +4n +.EX +kill(getpid(), sig); +.EE +.in +.P +In a multithreaded program it is equivalent to +.P +.in +4n +.EX +pthread_kill(pthread_self(), sig); +.EE +.in +.P +If the signal causes a handler to be called, +.BR raise () +will return only after the signal handler has returned. +.SH RETURN VALUE +.BR raise () +returns 0 on success, and nonzero for failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR raise () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.P +Since glibc 2.3.3, +.BR raise () +is implemented by calling +.BR tgkill (2), +.\" 2.3.2 used the obsolete tkill(), if available. +if the kernel supports that system call. +Older glibc versions implemented +.BR raise () +using +.BR kill (2). +.SH SEE ALSO +.BR getpid (2), +.BR kill (2), +.BR sigaction (2), +.BR signal (2), +.BR pthread_kill (3), +.BR signal (7) diff --git a/man/man3/rand.3 b/man/man3/rand.3 new file mode 100644 index 0000000..d5357fb --- /dev/null +++ b/man/man3/rand.3 @@ -0,0 +1,240 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-03-29, David Metcalfe +.\" Modified 1993-04-28, Lars Wirzenius +.\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-05-18, Rik Faith (faith@cs.unc.edu) to add +.\" better discussion of problems with rand on other systems. +.\" (Thanks to Esa Hyyti{ (ehyytia@snakemail.hut.fi).) +.\" Modified 1998-04-10, Nicolás Lichtmaier +.\" with contribution from Francesco Potorti +.\" Modified 2003-11-15, aeb, added rand_r +.\" 2010-09-13, mtk, added example program +.\" +.TH rand 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rand, rand_r, srand \- pseudo-random number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B int rand(void); +.BI "void srand(unsigned int " seed ); +.P +.BI "[[deprecated]] int rand_r(unsigned int *" seedp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR rand_r (): +.nf + Since glibc 2.24: + _POSIX_C_SOURCE >= 199506L + glibc 2.23 and earlier + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR rand () +function returns a pseudo-random integer in the range 0 to +.B RAND_MAX +inclusive (i.e., the mathematical range [0,\ \fBRAND_MAX\fR]). +.P +The +.BR srand () +function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by +.BR rand (). +These sequences are repeatable by calling +.BR srand () +with the same seed value. +.P +If no seed value is provided, the +.BR rand () +function is automatically seeded with a value of 1. +.P +The function +.BR rand () +is not reentrant, since it +uses hidden state that is modified on each call. +This might just be the seed value to be used by the next call, +or it might be something more elaborate. +In order to get reproducible behavior in a threaded +application, this state must be made explicit; +this can be done using the reentrant function +.BR rand_r (). +.P +Like +.BR rand (), +.BR rand_r () +returns a pseudo-random integer in the range [0,\ \fBRAND_MAX\fR]. +The +.I seedp +argument is a pointer to an +.I unsigned int +that is used to store state between calls. +If +.BR rand_r () +is called with the same initial value for the integer pointed to by +.IR seedp , +and that value is not modified between calls, +then the same pseudo-random sequence will result. +.P +The value pointed to by the +.I seedp +argument of +.BR rand_r () +provides only a very small amount of state, +so this function will be a weak pseudo-random generator. +Try +.BR drand48_r (3) +instead. +.SH RETURN VALUE +The +.BR rand () +and +.BR rand_r () +functions return a value between 0 and +.B RAND_MAX +(inclusive). +The +.BR srand () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rand (), +.BR rand_r (), +.BR srand () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The versions of +.BR rand () +and +.BR srand () +in the Linux C Library use the same random number generator as +.BR random (3) +and +.BR srandom (3), +so the lower-order bits should be as random as the higher-order bits. +However, on older +.BR rand () +implementations, and on current implementations on different systems, +the lower-order bits are much less random than the higher-order bits. +Do not use this function in applications intended to be portable +when good randomness is needed. +(Use +.BR random (3) +instead.) +.SH STANDARDS +.TP +.BR rand () +.TQ +.BR srand () +C11, POSIX.1-2008. +.TP +.BR rand_r () +POSIX.1-2008. +.SH HISTORY +.TP +.BR rand () +.TQ +.BR srand () +SVr4, 4.3BSD, C89, POSIX.1-2001. +.TP +.BR rand_r () +POSIX.1-2001. +Obsolete in POSIX.1-2008. +.SH EXAMPLES +POSIX.1-2001 gives the following example of an implementation of +.BR rand () +and +.BR srand (), +possibly useful when one needs the same sequence on two different machines. +.P +.in +4n +.EX +static unsigned long next = 1; +\& +/* RAND_MAX assumed to be 32767 */ +int myrand(void) { + next = next * 1103515245 + 12345; + return((unsigned)(next/65536) % 32768); +} +\& +void mysrand(unsigned int seed) { + next = seed; +} +.EE +.in +.P +The following program can be used to display the +pseudo-random sequence produced by +.BR rand () +when given a particular seed. +When the seed is +.IR \-1 , +the program uses a random seed. +.P +.in +4n +.\" SRC BEGIN (rand.c) +.EX +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int r; + unsigned int seed, nloops; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + seed = atoi(argv[1]); + nloops = atoi(argv[2]); +\& + if (seed == \-1) { + seed = arc4random(); + printf("seed: %u\en", seed); + } +\& + srand(seed); + for (unsigned int j = 0; j < nloops; j++) { + r = rand(); + printf("%d\en", r); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR drand48 (3), +.BR random (3) diff --git a/man/man3/rand_r.3 b/man/man3/rand_r.3 new file mode 100644 index 0000000..b007c2f --- /dev/null +++ b/man/man3/rand_r.3 @@ -0,0 +1 @@ +.so man3/rand.3 diff --git a/man/man3/random.3 b/man/man3/random.3 new file mode 100644 index 0000000..ff788e4 --- /dev/null +++ b/man/man3/random.3 @@ -0,0 +1,193 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Mar 28 00:25:51 1993, David Metcalfe +.\" Modified Sat Jul 24 18:13:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 20 21:47:07 2000, aeb +.\" +.TH random 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +random, srandom, initstate, setstate \- random number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B long random(void); +.BI "void srandom(unsigned int " seed ); +.P +.BI "char *initstate(unsigned int " seed ", char " state [. n "], size_t " n ); +.BI "char *setstate(char *" state ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR random (), +.BR srandom (), +.BR initstate (), +.BR setstate (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR random () +function uses a nonlinear additive feedback random +number generator employing a default table of size 31 long integers to +return successive pseudo-random numbers in +the range from 0 to 2\[ha]31\ \-\ 1. +The period of this random number generator is very large, approximately +.IR "16\ *\ ((2\[ha]31)\ \-\ 1)" . +.P +The +.BR srandom () +function sets its argument as the seed for a new +sequence of pseudo-random integers to be returned by +.BR random (). +These sequences are repeatable by calling +.BR srandom () +with the same +seed value. +If no seed value is provided, the +.BR random () +function +is automatically seeded with a value of 1. +.P +The +.BR initstate () +function allows a state array \fIstate\fP to +be initialized for use by +.BR random (). +The size of the state array +\fIn\fP is used by +.BR initstate () +to decide how sophisticated a +random number generator it should use\[em]the larger the state array, +the better the random numbers will be. +Current "optimal" values for the size of the state array \fIn\fP are +8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to +the nearest known amount. +Using less than 8 bytes results in an error. +\fIseed\fP is the seed for the +initialization, which specifies a starting point for the random number +sequence, and provides for restarting at the same point. +.P +The +.BR setstate () +function changes the state array used by the +.BR random () +function. +The state array \fIstate\fP is used for +random number generation until the next call to +.BR initstate () +or +.BR setstate (). +\fIstate\fP must first have been initialized +using +.BR initstate () +or be the result of a previous call of +.BR setstate (). +.SH RETURN VALUE +The +.BR random () +function returns a value between 0 and +.IR "(2\[ha]31)\ \-\ 1" . +The +.BR srandom () +function returns no value. +.P +The +.BR initstate () +function returns a pointer to the previous state array. +On failure, it returns NULL, and +.I errno +is set to indicate the error. +.P +On success, +.BR setstate () +returns a pointer to the previous state array. +On failure, it returns NULL, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The +.I state +argument given to +.BR setstate () +was NULL. +.TP +.B EINVAL +A state array of less than 8 bytes was specified to +.BR initstate (). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR random (), +.BR srandom (), +.BR initstate (), +.BR setstate () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.SH NOTES +Random-number generation is a complex topic. +.I Numerical Recipes in C: The Art of Scientific Computing +(William H.\& Press, Brian P.\& Flannery, Saul A.\& Teukolsky, +William T.\& Vetterling; New York: Cambridge University Press, 2007, 3rd ed.) +provides an excellent discussion of practical random-number generation +issues in Chapter 7 (Random Numbers). +.P +For a more theoretical discussion which also covers many practical issues +in depth, see Chapter 3 (Random Numbers) in Donald E.\& Knuth's +.IR "The Art of Computer Programming" , +volume 2 (Seminumerical Algorithms), 2nd ed.; Reading, Massachusetts: +Addison-Wesley Publishing Company, 1981. +.SH CAVEATS +The +.BR random () +function should not be used in multithreaded programs +where reproducible behavior is required. +Use +.BR random_r (3) +for that purpose. +.SH BUGS +According to POSIX, +.BR initstate () +should return NULL on error. +In the glibc implementation, +.I errno +is (as specified) set on error, but the function does not return NULL. +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=15380 +.SH SEE ALSO +.BR getrandom (2), +.BR drand48 (3), +.BR rand (3), +.BR random_r (3), +.BR srand (3) diff --git a/man/man3/random_r.3 b/man/man3/random_r.3 new file mode 100644 index 0000000..5215975 --- /dev/null +++ b/man/man3/random_r.3 @@ -0,0 +1,176 @@ +'\" t +.\" Copyright 2008 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH random_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +random_r, srandom_r, initstate_r, setstate_r \- reentrant +random number generator +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int random_r(struct random_data *restrict " buf , +.BI " int32_t *restrict " result ); +.BI "int srandom_r(unsigned int " seed ", struct random_data *" buf ); +.P +.BI "int initstate_r(unsigned int " seed ", \ +char " statebuf "[restrict ." statelen ], +.BI " size_t " statelen ", struct random_data *restrict " buf ); +.BI "int setstate_r(char *restrict " statebuf , +.BI " struct random_data *restrict " buf ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR random_r (), +.BR srandom_r (), +.BR initstate_r (), +.BR setstate_r (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +These functions are the reentrant equivalents +of the functions described in +.BR random (3). +They are suitable for use in multithreaded programs where each thread +needs to obtain an independent, reproducible sequence of random numbers. +.P +The +.BR random_r () +function is like +.BR random (3), +except that instead of using state information maintained +in a global variable, +it uses the state information in the argument pointed to by +.IR buf , +which must have been previously initialized by +.BR initstate_r (). +The generated random number is returned in the argument +.IR result . +.P +The +.BR srandom_r () +function is like +.BR srandom (3), +except that it initializes the seed for the random number generator +whose state is maintained in the object pointed to by +.IR buf , +which must have been previously initialized by +.BR initstate_r (), +instead of the seed associated with the global state variable. +.P +The +.BR initstate_r () +function is like +.BR initstate (3) +except that it initializes the state in the object pointed to by +.IR buf , +rather than initializing the global state variable. +Before calling this function, the +.I buf.state +field must be initialized to NULL. +The +.BR initstate_r () +function records a pointer to the +.I statebuf +argument inside the structure pointed to by +.IR buf . +Thus, +.I statebuf +should not be deallocated so long as +.I buf +is still in use. +(So, +.I statebuf +should typically be allocated as a static variable, +or allocated on the heap using +.BR malloc (3) +or similar.) +.P +The +.BR setstate_r () +function is like +.BR setstate (3) +except that it modifies the state in the object pointed to by +.IR buf , +rather than modifying the global state variable. +\fIstate\fP must first have been initialized +using +.BR initstate_r () +or be the result of a previous call of +.BR setstate_r (). +.SH RETURN VALUE +All of these functions return 0 on success. +On error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +A state array of less than 8 bytes was specified to +.BR initstate_r (). +.TP +.B EINVAL +The +.I statebuf +or +.I buf +argument to +.BR setstate_r () +was NULL. +.TP +.B EINVAL +The +.I buf +or +.I result +argument to +.BR random_r () +was NULL. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR random_r (), +.BR srandom_r (), +.BR initstate_r (), +.BR setstate_r () +T} Thread safety MT-Safe race:buf +.TE +.SH STANDARDS +GNU. +.\" These functions appear to be on Tru64, but don't seem to be on +.\" Solaris, HP-UX, or FreeBSD. +.SH BUGS +The +.BR initstate_r () +interface is confusing. +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=3662 +It appears that the +.I random_data +type is intended to be opaque, +but the implementation requires the user to either initialize the +.I buf.state +field to NULL or zero out the entire structure before the call. +.SH SEE ALSO +.BR drand48 (3), +.BR rand (3), +.BR random (3) diff --git a/man/man3/rawmemchr.3 b/man/man3/rawmemchr.3 new file mode 100644 index 0000000..b62c8f1 --- /dev/null +++ b/man/man3/rawmemchr.3 @@ -0,0 +1 @@ +.so man3/memchr.3 diff --git a/man/man3/rcmd.3 b/man/man3/rcmd.3 new file mode 100644 index 0000000..718a049 --- /dev/null +++ b/man/man3/rcmd.3 @@ -0,0 +1,304 @@ +'\" t +.\" $NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)rcmd.3 8.1 (Berkeley) 6/4/93 +.\" +.\" Contributed as Linux man page by David A. Holland, 970908 +.\" I have not checked whether the Linux situation is exactly the same. +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH rcmd 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rcmd, rresvport, iruserok, ruserok, rcmd_af, +rresvport_af, iruserok_af, ruserok_af \- routines for returning a +stream to a remote command +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " "/* Or on some systems */" +.P +.BI "int rcmd(char **restrict " ahost ", unsigned short " inport , +.BI " const char *restrict " locuser , +.BI " const char *restrict " remuser , +.BI " const char *restrict " cmd ", int *restrict " fd2p ); +.P +.BI "int rresvport(int *" port ); +.P +.BI "int iruserok(uint32_t " raddr ", int " superuser , +.BI " const char *" ruser ", const char *" luser ); +.BI "int ruserok(const char *" rhost ", int " superuser , +.BI " const char *" ruser ", const char *" luser ); +.P +.BI "int rcmd_af(char **restrict " ahost ", unsigned short " inport , +.BI " const char *restrict " locuser , +.BI " const char *restrict " remuser , +.BI " const char *restrict " cmd ", int *restrict " fd2p , +.BI " sa_family_t " af ); +.P +.BI "int rresvport_af(int *" port ", sa_family_t " af ); +.P +.BI "int iruserok_af(const void *restrict " raddr ", int " superuser , +.BI " const char *restrict " ruser ", const char *restrict " luser , +.BI " sa_family_t " af ); +.BI "int ruserok_af(const char *" rhost ", int " superuser , +.BI " const char *" ruser ", const char *" luser , +.BI " sa_family_t " af ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.ad l +.P +.BR rcmd (), +.BR rcmd_af (), +.BR rresvport (), +.BR rresvport_af (), +.BR iruserok (), +.BR iruserok_af (), +.BR ruserok (), +.BR ruserok_af (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.ad +.SH DESCRIPTION +The +.BR rcmd () +function is used by the superuser to execute a command on +a remote machine using an authentication scheme based +on privileged port numbers. +The +.BR rresvport () +function +returns a file descriptor to a socket +with an address in the privileged port space. +The +.BR iruserok () +and +.BR ruserok () +functions are used by servers +to authenticate clients requesting service with +.BR rcmd (). +All four functions are used by the +.BR rshd (8) +server (among others). +.SS rcmd() +The +.BR rcmd () +function +looks up the host +.I *ahost +using +.BR gethostbyname (3), +returning \-1 if the host does not exist. +Otherwise, +.I *ahost +is set to the standard name of the host +and a connection is established to a server +residing at the well-known Internet port +.IR inport . +.P +If the connection succeeds, +a socket in the Internet domain of type +.B SOCK_STREAM +is returned to the caller, and given to the remote +command as +.I stdin +and +.IR stdout . +If +.I fd2p +is nonzero, then an auxiliary channel to a control +process will be set up, and a file descriptor for it will be placed +in +.IR *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being UNIX signal numbers, to be +forwarded to the process group of the command. +If +.I fd2p +is 0, then the +.I stderr +(unit 2 of the remote +command) will be made the same as the +.I stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.P +The protocol is described in detail in +.BR rshd (8). +.SS rresvport() +The +.BR rresvport () +function is used to obtain a socket with a privileged +port bound to it. +This socket is suitable for use by +.BR rcmd () +and several other functions. +Privileged ports are those in the range 0 to 1023. +Only a privileged process +(on Linux, a process that has the +.B CAP_NET_BIND_SERVICE +capability in the user namespace governing its network namespace) +is allowed to bind to a privileged port. +In the glibc implementation, +this function restricts its search to the ports from 512 to 1023. +The +.I port +argument is value-result: +the value it supplies to the call is used as the starting point +for a circular search of the port range; +on (successful) return, it contains the port number that was bound to. +.\" +.SS iruserok() and ruserok() +The +.BR iruserok () +and +.BR ruserok () +functions take a remote host's IP address or name, respectively, +two usernames and a flag indicating whether the local user's +name is that of the superuser. +Then, if the user is +.I not +the superuser, it checks the +.I /etc/hosts.equiv +file. +If that lookup is not done, or is unsuccessful, the +.I .rhosts +in the local user's home directory is checked to see if the request for +service is allowed. +.P +If this file does not exist, is not a regular file, is owned by anyone +other than the user or the superuser, is writable by anyone other +than the owner, or is hardlinked anywhere, the check automatically fails. +Zero is returned if the machine name is listed in the +.I hosts.equiv +file, or the host and remote username are found in the +.I .rhosts +file; otherwise +.BR iruserok () +and +.BR ruserok () +return \-1. +If the local domain (as obtained from +.BR gethostname (2)) +is the same as the remote domain, only the machine name need be specified. +.P +If the IP address of the remote host is known, +.BR iruserok () +should be used in preference to +.BR ruserok (), +as it does not require trusting the DNS server for the remote host's domain. +.SS *_af() variants +All of the functions described above work with IPv4 +.RB ( AF_INET ) +sockets. +The "_af" variants take an extra argument that allows the +socket address family to be specified. +For these functions, the +.I af +argument can be specified as +.B AF_INET +or +.BR AF_INET6 . +In addition, +.BR rcmd_af () +supports the use of +.BR AF_UNSPEC . +.SH RETURN VALUE +The +.BR rcmd () +function +returns a valid socket descriptor on success. +It returns \-1 on error and prints a diagnostic message on the standard error. +.P +The +.BR rresvport () +function +returns a valid, bound socket descriptor on success. +On failure, it returns \-1 and sets +.I errno +to indicate the error. +The error code +.B EAGAIN +is overloaded to mean: "All network ports in use". +.P +For information on the return from +.BR ruserok () +and +.BR iruserok (), +see above. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rcmd (), +.BR rcmd_af () +T} Thread safety MT-Unsafe +T{ +.na +.nh +.BR rresvport (), +.BR rresvport_af () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR iruserok (), +.BR ruserok (), +.BR iruserok_af (), +.BR ruserok_af () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +BSD. +.SH HISTORY +.TP +.BR iruserok_af () +.TQ +.BR rcmd_af () +.TQ +.BR rresvport_af () +.TQ +.BR ruserok_af () +glibc 2.2. +.P +Solaris, 4.2BSD. +The "_af" variants are more recent additions, +and are not present on as wide a range of systems. +.SH BUGS +.BR iruserok () +and +.BR iruserok_af () +are declared in glibc headers only since glibc 2.12. +.\" Bug filed 25 Nov 2007: +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=5399 +.SH SEE ALSO +.BR rlogin (1), +.BR rsh (1), +.BR rexec (3), +.BR rexecd (8), +.BR rlogind (8), +.BR rshd (8) diff --git a/man/man3/rcmd_af.3 b/man/man3/rcmd_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/rcmd_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/re_comp.3 b/man/man3/re_comp.3 new file mode 100644 index 0000000..16e0a5a --- /dev/null +++ b/man/man3/re_comp.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@@ee.surrey.ac.uk) +.\" +.TH re_comp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +re_comp, re_exec \- BSD regex functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #define _REGEX_RE_COMP +.B #include +.B #include +.P +.BI "[[deprecated]] char *re_comp(const char *" regex ); +.BI "[[deprecated]] int re_exec(const char *" string ); +.fi +.SH DESCRIPTION +.BR re_comp () +is used to compile the null-terminated regular expression pointed to by +.IR regex . +The compiled pattern occupies a static area, the pattern buffer, +which is overwritten by subsequent use of +.BR re_comp (). +If +.I regex +is NULL, +no operation is performed and the pattern buffer's contents are not +altered. +.P +.BR re_exec () +is used to assess whether the null-terminated string pointed to by +.I string +matches the previously compiled +.IR regex . +.SH RETURN VALUE +.BR re_comp () +returns NULL on successful compilation of +.I regex +otherwise it returns a pointer to an appropriate error message. +.P +.BR re_exec () +returns 1 for a successful match, zero for failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR re_comp (), +.BR re_exec () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +.P +These functions are obsolete; the functions documented in +.BR regcomp (3) +should be used instead. +.SH SEE ALSO +.BR regcomp (3), +.BR regex (7), +GNU regex manual diff --git a/man/man3/re_exec.3 b/man/man3/re_exec.3 new file mode 100644 index 0000000..36aba39 --- /dev/null +++ b/man/man3/re_exec.3 @@ -0,0 +1 @@ +.so man3/re_comp.3 diff --git a/man/man3/readdir.3 b/man/man3/readdir.3 new file mode 100644 index 0000000..887dde8 --- /dev/null +++ b/man/man3/readdir.3 @@ -0,0 +1,304 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2008, 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 16:09:49 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 22 July 1996 by Andries Brouwer (aeb@cwi.nl) +.\" 2007-07-30 Ulrich Drepper , mtk: +.\" Rework discussion of nonstandard structure fields. +.\" +.TH readdir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +readdir \- read a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "struct dirent *readdir(DIR *" dirp ); +.fi +.SH DESCRIPTION +The +.BR readdir () +function returns a pointer to a \fIdirent\fP structure +representing the next directory entry in the directory stream pointed +to by \fIdirp\fP. +It returns NULL on reaching the end of the directory stream or if +an error occurred. +.P +In the glibc implementation, the +.I dirent +structure is defined as follows: +.P +.in +4n +.EX +struct dirent { + ino_t d_ino; /* Inode number */ + off_t d_off; /* Not an offset; see below */ + unsigned short d_reclen; /* Length of this record */ + unsigned char d_type; /* Type of file; not supported + by all filesystem types */ + char d_name[256]; /* Null\-terminated filename */ +}; +.EE +.in +.P +The only fields in the +.I dirent +structure that are mandated by POSIX.1 are +.I d_name +and +.IR d_ino . +The other fields are unstandardized, and not present on all systems; +see NOTES below for some further details. +.P +The fields of the +.I dirent +structure are as follows: +.TP +.I d_ino +This is the inode number of the file. +.TP +.I d_off +The value returned in +.I d_off +is the same as would be returned by calling +.BR telldir (3) +at the current position in the directory stream. +Be aware that despite its type and name, the +.I d_off +field is seldom any kind of directory offset on modern filesystems. +.\" https://lwn.net/Articles/544298/ +Applications should treat this field as an opaque value, +making no assumptions about its contents; see also +.BR telldir (3). +.TP +.I d_reclen +This is the size (in bytes) of the returned record. +This may not match the size of the structure definition shown above; +see NOTES. +.TP +.I d_type +This field contains a value indicating the file type, +making it possible to avoid the expense of calling +.BR lstat (2) +if further actions depend on the type of the file. +.IP +When a suitable feature test macro is defined +.RB ( _DEFAULT_SOURCE +since glibc 2.19, or +.B _BSD_SOURCE +on glibc 2.19 and earlier), +glibc defines the following macro constants for the value returned in +.IR d_type : +.RS +.TP 12 +.B DT_BLK +This is a block device. +.TP +.B DT_CHR +This is a character device. +.TP +.B DT_DIR +This is a directory. +.TP +.B DT_FIFO +This is a named pipe (FIFO). +.TP +.B DT_LNK +This is a symbolic link. +.TP +.B DT_REG +This is a regular file. +.TP +.B DT_SOCK +This is a UNIX domain socket. +.TP +.B DT_UNKNOWN +The file type could not be determined. +.RE +.IP +Currently, +.\" kernel 2.6.27 +.\" The same sentence is in getdents.2 +only some filesystems (among them: Btrfs, ext2, ext3, and ext4) +have full support for returning the file type in +.IR d_type . +All applications must properly handle a return of +.BR DT_UNKNOWN . +.TP +.I d_name +This field contains the null terminated filename. +.IR "See NOTES" . +.P +The data returned by +.BR readdir () +may be overwritten by subsequent calls to +.BR readdir () +for the same directory stream. +.SH RETURN VALUE +On success, +.BR readdir () +returns a pointer to a +.I dirent +structure. +(This structure may be statically allocated; do not attempt to +.BR free (3) +it.) +.P +If the end of the directory stream is reached, NULL is returned and +.I errno +is not changed. +If an error occurs, NULL is returned and +.I errno +is set to indicate the error. +To distinguish end of stream from an error, set +.I errno +to zero before calling +.BR readdir () +and then check the value of +.I errno +if NULL is returned. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdirp\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR readdir () +T} Thread safety MT-Unsafe race:dirstream +.TE +.P +In the current POSIX.1 specification (POSIX.1-2008), +.BR readdir () +is not required to be thread-safe. +However, in modern implementations (including the glibc implementation), +concurrent calls to +.BR readdir () +that specify different directory streams are thread-safe. +In cases where multiple threads must read from the same directory stream, +using +.BR readdir () +with external synchronization is still preferable to the use of the deprecated +.BR readdir_r (3) +function. +It is expected that a future version of POSIX.1 +.\" FIXME . +.\" http://www.austingroupbugs.net/view.php?id=696 +will require that +.BR readdir () +be thread-safe when concurrently employed on different directory streams. +.SH VERSIONS +Only the fields +.I d_name +and (as an XSI extension) +.I d_ino +are specified in POSIX.1. +.\" POSIX.1-2001, POSIX.1-2008 +Other than Linux, the +.I d_type +field is available mainly only on BSD systems. +The remaining fields are available on many, but not all systems. +Under glibc, +programs can check for the availability of the fields not defined +in POSIX.1 by testing whether the macros +.BR _DIRENT_HAVE_D_NAMLEN , +.BR _DIRENT_HAVE_D_RECLEN , +.BR _DIRENT_HAVE_D_OFF , +or +.B _DIRENT_HAVE_D_TYPE +are defined. +.\" +.SS The d_name field +The +.I dirent +structure definition shown above is taken from the glibc headers, +and shows the +.I d_name +field with a fixed size. +.P +.IR Warning : +applications should avoid any dependence on the size of the +.I d_name +field. +POSIX defines it as +.IR "char\ d_name[]", +a character array of unspecified size, with at most +.B NAME_MAX +characters preceding the terminating null byte (\[aq]\e0\[aq]). +.P +POSIX.1 explicitly notes that this field should not be used as an lvalue. +The standard also notes that the use of +.I sizeof(d_name) +is incorrect; use +.I strlen(d_name) +instead. +(On some systems, this field is defined as +.IR char\~d_name[1] !) +By implication, the use +.I sizeof(struct dirent) +to capture the size of the record including the size of +.I d_name +is also incorrect. +.P +Note that while the call +.P +.in +4n +.EX +fpathconf(fd, _PC_NAME_MAX) +.EE +.in +.P +returns the value 255 for most filesystems, +on some filesystems (e.g., CIFS, Windows SMB servers), +the null-terminated filename that is (correctly) returned in +.I d_name +can actually exceed this size. +In such cases, the +.I d_reclen +field will contain a value that exceeds the size of the glibc +.I dirent +structure shown above. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH NOTES +A directory stream is opened using +.BR opendir (3). +.P +The order in which filenames are read by successive calls to +.BR readdir () +depends on the filesystem implementation; +it is unlikely that the names will be sorted in any fashion. +.SH SEE ALSO +.BR getdents (2), +.BR read (2), +.BR closedir (3), +.BR dirfd (3), +.BR ftw (3), +.BR offsetof (3), +.BR opendir (3), +.BR readdir_r (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man/man3/readdir_r.3 b/man/man3/readdir_r.3 new file mode 100644 index 0000000..a46c19c --- /dev/null +++ b/man/man3/readdir_r.3 @@ -0,0 +1,145 @@ +'\" t +.\" Copyright (C) 2008, 2016 Michael Kerrisk +.\" and Copyright (C) 2016 Florian Weimer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH readdir_r 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +readdir_r \- read a directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int readdir_r(DIR *restrict " dirp , +.BI " struct dirent *restrict " entry , +.BI " struct dirent **restrict " result ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR readdir_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +This function is deprecated; use +.BR readdir (3) +instead. +.P +The +.BR readdir_r () +function was invented as a reentrant version of +.BR readdir (3). +It reads the next directory entry from the directory stream +.IR dirp , +and returns it in the caller-allocated buffer pointed to by +.IR entry . +For details of the +.I dirent +structure, see +.BR readdir (3). +.P +A pointer to the returned buffer is placed in +.IR *result ; +if the end of the directory stream was encountered, +then NULL is instead returned in +.IR *result . +.P +It is recommended that applications use +.BR readdir (3) +instead of +.BR readdir_r (). +Furthermore, since glibc 2.24, glibc deprecates +.BR readdir_r (). +The reasons are as follows: +.IP \[bu] 3 +On systems where +.B NAME_MAX +is undefined, calling +.BR readdir_r () +may be unsafe because the interface does not allow the caller to specify +the length of the buffer used for the returned directory entry. +.IP \[bu] +On some systems, +.BR readdir_r () +can't read directory entries with very long names. +When the glibc implementation encounters such a name, +.BR readdir_r () +fails with the error +.B ENAMETOOLONG +.IR "after the final directory entry has been read" . +On some other systems, +.BR readdir_r () +may return a success status, but the returned +.I d_name +field may not be null terminated or may be truncated. +.IP \[bu] +In the current POSIX.1 specification (POSIX.1-2008), +.BR readdir (3) +is not required to be thread-safe. +However, in modern implementations (including the glibc implementation), +concurrent calls to +.BR readdir (3) +that specify different directory streams are thread-safe. +Therefore, the use of +.BR readdir_r () +is generally unnecessary in multithreaded programs. +In cases where multiple threads must read from the same directory stream, +using +.BR readdir (3) +with external synchronization is still preferable to the use of +.BR readdir_r (), +for the reasons given in the points above. +.IP \[bu] +It is expected that a future version of POSIX.1 +.\" FIXME . +.\" http://www.austingroupbugs.net/view.php?id=696 +will make +.BR readdir_r () +obsolete, and require that +.BR readdir (3) +be thread-safe when concurrently employed on different directory streams. +.SH RETURN VALUE +The +.BR readdir_r () +function returns 0 on success. +On error, it returns a positive error number (listed under ERRORS). +If the end of the directory stream is reached, +.BR readdir_r () +returns 0, and returns NULL in +.IR *result . +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdirp\fP. +.TP +.B ENAMETOOLONG +A directory entry whose name was too long to be read was encountered. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR readdir_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR readdir (3) diff --git a/man/man3/realloc.3 b/man/man3/realloc.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man/man3/realloc.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man/man3/reallocarray.3 b/man/man3/reallocarray.3 new file mode 100644 index 0000000..a4b9d44 --- /dev/null +++ b/man/man3/reallocarray.3 @@ -0,0 +1 @@ +.so man3/malloc.3 diff --git a/man/man3/realpath.3 b/man/man3/realpath.3 new file mode 100644 index 0000000..581edf8 --- /dev/null +++ b/man/man3/realpath.3 @@ -0,0 +1,231 @@ +'\" t +.\" Copyright (C) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Rewritten old page, 990824, aeb@cwi.nl +.\" 2004-12-14, mtk, added discussion of resolved_path == NULL +.\" +.TH realpath 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +realpath \- return the canonicalized absolute pathname +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "char *realpath(const char *restrict " path , +.BI " char *restrict " resolved_path ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR realpath (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR realpath () +expands all symbolic links and resolves references +to +.IR "/./" ", " "/../" +and extra \[aq]/\[aq] +characters in the null-terminated string named by +.I path +to produce a canonicalized absolute pathname. +The resulting pathname is stored as a null-terminated string, +up to a maximum of +.B PATH_MAX +bytes, +in the buffer pointed to by +.IR resolved_path . +The resulting path will have no symbolic link, +.I "/./" +or +.I "/../" +components. +.P +If +.I resolved_path +is specified as NULL, then +.BR realpath () +uses +.BR malloc (3) +to allocate a buffer of up to +.B PATH_MAX +bytes to hold the resolved pathname, +and returns a pointer to this buffer. +The caller should deallocate this buffer using +.BR free (3). +.\" Even if we use resolved_path == NULL, then realpath() will still +.\" return ENAMETOOLONG if the resolved pathname would exceed PATH_MAX +.\" bytes -- MTK, Dec 04 +.SH RETURN VALUE +If there is no error, +.BR realpath () +returns a pointer to the +.IR resolved_path . +.P +Otherwise, it returns NULL, the contents +of the array +.I resolved_path +are undefined, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Read or search permission was denied for a component of the path prefix. +.TP +.B EINVAL +.I path +is NULL. +.\" (In libc5 this would just cause a segfault.) +(Before glibc 2.3, +this error is also returned if +.I resolved_path +is NULL.) +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A component of a pathname exceeded +.B NAME_MAX +characters, or an entire pathname exceeded +.B PATH_MAX +characters. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR realpath () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS GNU extensions +If the call fails with either +.B EACCES +or +.B ENOENT +and +.I resolved_path +is not NULL, then the prefix of +.I path +that is not readable or does not exist is returned in +.IR resolved_path . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +4.4BSD, POSIX.1-2001, Solaris. +.P +POSIX.1-2001 says that the behavior if +.I resolved_path +is NULL is implementation-defined. +POSIX.1-2008 specifies the behavior described in this page. +.P +In 4.4BSD and Solaris, the limit on the pathname length is +.B MAXPATHLEN +(found in \fI\fP). +SUSv2 prescribes +.B PATH_MAX +and +.BR NAME_MAX , +as found in \fI\fP or provided by the +.BR pathconf (3) +function. +A typical source fragment would be +.P +.in +4n +.EX +#ifdef PATH_MAX + path_max = PATH_MAX; +#else + path_max = pathconf(path, _PC_PATH_MAX); + if (path_max <= 0) + path_max = 4096; +#endif +.EE +.in +.P +(But see the BUGS section.) +.\".P +.\" 2012-05-05, According to Casper Dik, the statement about +.\" Solaris was not true at least as far back as 1997, and +.\" may never have been true. +.\" +.\" The 4.4BSD, Linux and SUSv2 versions always return an absolute +.\" pathname. +.\" Solaris may return a relative pathname when the +.\" .I path +.\" argument is relative. +.\" The prototype of +.\" .BR realpath () +.\" is given in \fI\fP in libc4 and libc5, +.\" but in \fI\fP everywhere else. +.SH BUGS +The POSIX.1-2001 standard version of this function is broken by design, +since it is impossible to determine a suitable size for the output buffer, +.IR resolved_path . +According to POSIX.1-2001 a buffer of size +.B PATH_MAX +suffices, but +.B PATH_MAX +need not be a defined constant, and may have to be obtained using +.BR pathconf (3). +And asking +.BR pathconf (3) +does not really help, since, on the one hand POSIX warns that +the result of +.BR pathconf (3) +may be huge and unsuitable for mallocing memory, +and on the other hand +.BR pathconf (3) +may return \-1 to signify that +.B PATH_MAX +is not bounded. +The +.I "resolved_path\ ==\ NULL" +feature, not standardized in POSIX.1-2001, +but standardized in POSIX.1-2008, allows this design problem to be avoided. +.\" .P +.\" The libc4 and libc5 implementation contained a buffer overflow +.\" (fixed in libc-5.4.13). +.\" Thus, set-user-ID programs like +.\" .BR mount (8) +.\" needed a private version. +.SH SEE ALSO +.BR realpath (1), +.BR readlink (2), +.BR canonicalize_file_name (3), +.BR getcwd (3), +.BR pathconf (3), +.BR sysconf (3) diff --git a/man/man3/recno.3 b/man/man3/recno.3 new file mode 100644 index 0000000..03bcf1c --- /dev/null +++ b/man/man3/recno.3 @@ -0,0 +1,207 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)recno.3 8.5 (Berkeley) 8/18/94 +.\" +.TH recno 3 2024-05-02 "Linux man-pages (unreleased)" +.UC 7 +.SH NAME +recno \- record number database access method +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.ft B +#include +#include +.ft R +.fi +.SH DESCRIPTION +.IR "Note well" : +This page documents interfaces provided up until glibc 2.1. +Since glibc 2.2, glibc no longer provides these interfaces. +Probably, you are looking for the APIs provided by the +.I libdb +library instead. +.P +The routine +.BR dbopen (3) +is the library interface to database files. +One of the supported file formats is record number files. +The general description of the database access methods is in +.BR dbopen (3), +this manual page describes only the recno-specific information. +.P +The record number data structure is either variable or fixed-length +records stored in a flat-file format, accessed by the logical record +number. +The existence of record number five implies the existence of records +one through four, and the deletion of record number one causes +record number five to be renumbered to record number four, as well +as the cursor, if positioned after record number one, to shift down +one record. +.P +The recno access-method-specific data structure provided to +.BR dbopen (3) +is defined in the +.I +include file as follows: +.P +.in +4n +.EX +typedef struct { + unsigned long flags; + unsigned int cachesize; + unsigned int psize; + int lorder; + size_t reclen; + unsigned char bval; + char *bfname; +} RECNOINFO; +.EE +.in +.P +The elements of this structure are defined as follows: +.TP +.I flags +The flag value is specified by ORing +any of the following values: +.RS +.TP +.B R_FIXEDLEN +The records are fixed-length, not byte delimited. +The structure element +.I reclen +specifies the length of the record, and the structure element +.I bval +is used as the pad character. +Any records, inserted into the database, that are less than +.I reclen +bytes long are automatically padded. +.TP +.B R_NOKEY +In the interface specified by +.BR dbopen (3), +the sequential record retrieval fills in both the caller's key and +data structures. +If the +.B R_NOKEY +flag is specified, the +.I cursor +routines are not required to fill in the key structure. +This permits applications to retrieve records at the end of files without +reading all of the intervening records. +.TP +.B R_SNAPSHOT +This flag requires that a snapshot of the file be taken when +.BR dbopen (3) +is called, instead of permitting any unmodified records to be read from +the original file. +.RE +.TP +.I cachesize +A suggested maximum size, in bytes, of the memory cache. +This value is +.B only +advisory, and the access method will allocate more memory rather than fail. +If +.I cachesize +is 0 (no size is specified), a default cache is used. +.TP +.I psize +The recno access method stores the in-memory copies of its records +in a btree. +This value is the size (in bytes) of the pages used for nodes in that tree. +If +.I psize +is 0 (no page size is specified), a page size is chosen based on the +underlying filesystem I/O block size. +See +.BR btree (3) +for more information. +.TP +.I lorder +The byte order for integers in the stored database metadata. +The number should represent the order as an integer; for example, +big endian order would be the number 4,321. +If +.I lorder +is 0 (no order is specified), the current host order is used. +.TP +.I reclen +The length of a fixed-length record. +.TP +.I bval +The delimiting byte to be used to mark the end of a record for +variable-length records, and the pad character for fixed-length +records. +If no value is specified, newlines ("\en") are used to mark the end +of variable-length records and fixed-length records are padded with +spaces. +.TP +.I bfname +The recno access method stores the in-memory copies of its records +in a btree. +If +.I bfname +is non-NULL, it specifies the name of the btree file, +as if specified as the filename for a +.BR dbopen (3) +of a btree file. +.P +The data part of the key/data pair used by the +.I recno +access method +is the same as other access methods. +The key is different. +The +.I data +field of the key should be a pointer to a memory location of type +.IR recno_t , +as defined in the +.I +include file. +This type is normally the largest unsigned integral type available to +the implementation. +The +.I size +field of the key should be the size of that type. +.P +Because there can be no metadata associated with the underlying +recno access method files, any changes made to the default values +(e.g., fixed record length or byte separator value) must be explicitly +specified each time the file is opened. +.P +In the interface specified by +.BR dbopen (3), +using the +.I put +interface to create a new record will cause the creation of multiple, +empty records if the record number is more than one greater than the +largest record currently in the database. +.SH ERRORS +The +.I recno +access method routines may fail and set +.I errno +for any of the errors specified for the library routine +.BR dbopen (3) +or the following: +.TP +.B EINVAL +An attempt was made to add a record to a fixed-length database that +was too large to fit. +.SH BUGS +Only big and little endian byte order is supported. +.SH SEE ALSO +.BR btree (3), +.BR dbopen (3), +.BR hash (3), +.BR mpool (3) +.P +.IR "Document Processing in a Relational Database System" , +Michael Stonebraker, Heidi Stettner, Joseph Kalash, Antonin Guttman, +Nadene Lynn, Memorandum No. UCB/ERL M82/32, May 1982. diff --git a/man/man3/regcomp.3 b/man/man3/regcomp.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3/regcomp.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3/regerror.3 b/man/man3/regerror.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3/regerror.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3/regex.3 b/man/man3/regex.3 new file mode 100644 index 0000000..2b3c795 --- /dev/null +++ b/man/man3/regex.3 @@ -0,0 +1,411 @@ +'\" t +.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) +.\" Copyright 2023, Ahelenia Ziemiańska +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@ee.surrey.ac.uk) +.\" Tiny change in formatting - aeb, 950812 +.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" +.\" show the synopsis section nicely +.TH regex 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +regcomp, regexec, regerror, regfree \- POSIX regex functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int regcomp(regex_t *restrict " preg ", const char *restrict " regex , +.BI " int " cflags ); +.BI "int regexec(const regex_t *restrict " preg \ +", const char *restrict " string , +.BI " size_t " nmatch ", \ +regmatch_t " pmatch "[_Nullable restrict ." nmatch ], +.BI " int " eflags ); +.P +.BI "size_t regerror(int " errcode ", const regex_t *_Nullable restrict " preg , +.BI " char " errbuf "[_Nullable restrict ." errbuf_size ], +.BI " size_t " errbuf_size ); +.BI "void regfree(regex_t *" preg ); +.P +.B typedef struct { +.B " size_t re_nsub;" +.B } regex_t; +.P +.B typedef struct { +.B " regoff_t rm_so;" +.B " regoff_t rm_eo;" +.B } regmatch_t; +.P +.BR typedef " /* ... */ " regoff_t; +.fi +.SH DESCRIPTION +.SS Compilation +.BR regcomp () +is used to compile a regular expression into a form that is suitable +for subsequent +.BR regexec () +searches. +.P +On success, the pattern buffer at +.I *preg +is initialized. +.I regex +is a null-terminated string. +The locale must be the same when running +.BR regexec (). +.P +After +.BR regcomp () +succeeds, +.I preg->re_nsub +holds the number of subexpressions in +.IR regex . +Thus, a value of +.I preg->re_nsub ++ 1 +passed as +.I nmatch +to +.BR regexec () +is sufficient to capture all matches. +.P +.I cflags +is the +bitwise OR +of zero or more of the following: +.TP +.B REG_EXTENDED +Use +POSIX +Extended Regular Expression syntax when interpreting +.IR regex . +If not set, +POSIX +Basic Regular Expression syntax is used. +.TP +.B REG_ICASE +Do not differentiate case. +Subsequent +.BR regexec () +searches using this pattern buffer will be case insensitive. +.TP +.B REG_NOSUB +Report only overall success. +.BR regexec () +will use only +.I pmatch +for +.BR REG_STARTEND , +ignoring +.IR nmatch . +.TP +.B REG_NEWLINE +Match-any-character operators don't match a newline. +.IP +A nonmatching list +.RB ( [\[ha]...\&] ) +not containing a newline does not match a newline. +.IP +Match-beginning-of-line operator +.RB ( \[ha] ) +matches the empty string immediately after a newline, regardless of +whether +.IR eflags , +the execution flags of +.BR regexec (), +contains +.BR REG_NOTBOL . +.IP +Match-end-of-line operator +.RB ( $ ) +matches the empty string immediately before a newline, regardless of +whether +.I eflags +contains +.BR REG_NOTEOL . +.SS Matching +.BR regexec () +is used to match a null-terminated string +against the compiled pattern buffer in +.IR *preg , +which must have been initialised with +.BR regexec (). +.I eflags +is the +bitwise OR +of zero or more of the following flags: +.TP +.B REG_NOTBOL +The match-beginning-of-line operator always fails to match (but see the +compilation flag +.B REG_NEWLINE +above). +This flag may be used when different portions of a string are passed to +.BR regexec () +and the beginning of the string should not be interpreted as the +beginning of the line. +.TP +.B REG_NOTEOL +The match-end-of-line operator always fails to match (but see the +compilation flag +.B REG_NEWLINE +above). +.TP +.B REG_STARTEND +Match +.RI [ "string + pmatch[0].rm_so" , " string + pmatch[0].rm_eo" ) +instead of +.RI [ string , " string + strlen(string)" ). +This allows matching embedded NUL bytes +and avoids a +.BR strlen (3) +on known-length strings. +If any matches are returned +.RB ( REG_NOSUB +wasn't passed to +.BR regcomp (), +the match succeeded, and +.I nmatch +> 0), they overwrite +.I pmatch +as usual, and the match offsets remain relative to +.I string +(not +.IR "string + pmatch[0].rm_so" ). +This flag is a BSD extension, not present in POSIX. +.SS Match offsets +Unless +.B REG_NOSUB +was passed to +.BR regcomp (), +it is possible to +obtain the locations of matches within +.IR string : +.BR regexec () +fills +.I nmatch +elements of +.I pmatch +with results: +.I pmatch[0] +corresponds to the entire match, +.I pmatch[1] +to the first subexpression, etc. +If there were more matches than +.IR nmatch , +they are discarded; +if fewer, +unused elements of +.I pmatch +are filled with +.BR \-1 s. +.P +Each returned valid +.RB (non- \-1 ) +match corresponds to the range +.RI [ "string + rm_so" , " string + rm_eo" ). +.P +.I regoff_t +is a signed integer type +capable of storing the largest value that can be stored in either an +.I ptrdiff_t +type or a +.I ssize_t +type. +.SS Error reporting +.BR regerror () +is used to turn the error codes that can be returned by both +.BR regcomp () +and +.BR regexec () +into error message strings. +.P +If +.I preg +isn't a null pointer, +.I errcode +must be the latest error returned from an operation on +.IR preg . +.P +If +.I errbuf_size +isn't 0, up to +.I errbuf_size +bytes are copied to +.IR errbuf ; +the error string is always null-terminated, and truncated to fit. +.SS Freeing +.BR regfree () +deinitializes the pattern buffer at +.IR *preg , +freeing any associated memory; +.I *preg +must have been initialized via +.BR regcomp (). +.SH RETURN VALUE +.BR regcomp () +returns zero for a successful compilation or an error code for failure. +.P +.BR regexec () +returns zero for a successful match or +.B REG_NOMATCH +for failure. +.P +.BR regerror () +returns the size of the buffer required to hold the string. +.SH ERRORS +The following errors can be returned by +.BR regcomp (): +.TP +.B REG_BADBR +Invalid use of back reference operator. +.TP +.B REG_BADPAT +Invalid use of pattern operators such as group or list. +.TP +.B REG_BADRPT +Invalid use of repetition operators such as using \[aq]*\[aq] +as the first character. +.TP +.B REG_EBRACE +Un-matched brace interval operators. +.TP +.B REG_EBRACK +Un-matched bracket list operators. +.TP +.B REG_ECOLLATE +Invalid collating element. +.TP +.B REG_ECTYPE +Unknown character class name. +.TP +.B REG_EEND +Nonspecific error. +This is not defined by POSIX. +.TP +.B REG_EESCAPE +Trailing backslash. +.TP +.B REG_EPAREN +Un-matched parenthesis group operators. +.TP +.B REG_ERANGE +Invalid use of the range operator; for example, the ending point of the range +occurs prior to the starting point. +.TP +.B REG_ESIZE +Compiled regular expression requires a pattern buffer larger than 64\ kB. +This is not defined by POSIX. +.TP +.B REG_ESPACE +The regex routines ran out of memory. +.TP +.B REG_ESUBREG +Invalid back reference to a subexpression. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR regcomp (), +.BR regexec () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR regerror () +T} Thread safety MT-Safe env +T{ +.na +.nh +.BR regfree () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Prior to POSIX.1-2008, +.I regoff_t +was required to be +capable of storing the largest value that can be stored in either an +.I off_t +type or a +.I ssize_t +type. +.SH CAVEATS +.I re_nsub +is only required to be initialized if +.B REG_NOSUB +wasn't specified, but all known implementations initialize it regardless. +.\" glibc, musl, 4.4BSD, illumos +.P +Both +.I regex_t +and +.I regmatch_t +may (and do) have more members, in any order. +Always reference them by name. +.\" illumos has two more start/end pairs and the first one is of pointers +.SH EXAMPLES +.EX +#include +#include +#include +#include +\& +#define ARRAY_SIZE(arr) (sizeof((arr)) / sizeof((arr)[0])) +\& +static const char *const str = + "1) John Driverhacker;\en2) John Doe;\en3) John Foo;\en"; +static const char *const re = "John.*o"; +\& +int main(void) +{ + static const char *s = str; + regex_t regex; + regmatch_t pmatch[1]; + regoff_t off, len; +\& + if (regcomp(®ex, re, REG_NEWLINE)) + exit(EXIT_FAILURE); +\& + printf("String = \e"%s\e"\en", str); + printf("Matches:\en"); +\& + for (unsigned int i = 0; ; i++) { + if (regexec(®ex, s, ARRAY_SIZE(pmatch), pmatch, 0)) + break; +\& + off = pmatch[0].rm_so + (s \- str); + len = pmatch[0].rm_eo \- pmatch[0].rm_so; + printf("#%zu:\en", i); + printf("offset = %jd; length = %jd\en", (intmax_t) off, + (intmax_t) len); + printf("substring = \e"%.*s\e"\en", len, s + pmatch[0].rm_so); +\& + s += pmatch[0].rm_eo; + } +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR grep (1), +.BR regex (7) +.P +The glibc manual section, +.I "Regular Expressions" diff --git a/man/man3/regexec.3 b/man/man3/regexec.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3/regexec.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3/regfree.3 b/man/man3/regfree.3 new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3/regfree.3 @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3/register_printf_modifier.3 b/man/man3/register_printf_modifier.3 new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3/register_printf_modifier.3 @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3/register_printf_specifier.3 b/man/man3/register_printf_specifier.3 new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3/register_printf_specifier.3 @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3/register_printf_type.3 b/man/man3/register_printf_type.3 new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3/register_printf_type.3 @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3/registerrpc.3 b/man/man3/registerrpc.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/registerrpc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/remainder.3 b/man/man3/remainder.3 new file mode 100644 index 0000000..430e81c --- /dev/null +++ b/man/man3/remainder.3 @@ -0,0 +1,234 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-10 Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" Modified 2003-11-18, 2004-10-05 aeb +.\" +.TH remainder 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +drem, dremf, dreml, remainder, remainderf, remainderl \- \ +floating-point remainder function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double remainder(double " x ", double " y ); +.BI "float remainderf(float " x ", float " y ); +.BI "long double remainderl(long double " x ", long double " y ); +.P +/* Obsolete synonyms */ +.BI "[[deprecated]] double drem(double " x ", double " y ); +.BI "[[deprecated]] float dremf(float " x ", float " y ); +.BI "[[deprecated]] long double dreml(long double " x ", long double " y ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR remainder (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR remainderf (), +.BR remainderl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR drem (), +.BR dremf (), +.BR dreml (): +.nf + /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These +functions compute the remainder of dividing +.I x +by +.IR y . +The return value is +\fIx\fP\-\fIn\fP*\fIy\fP, +where +.I n +is the value +.IR "x\ /\ y" , +rounded to the nearest integer. +If the absolute value of +\fIx\fP\-\fIn\fP*\fIy\fP +is 0.5, +.I n +is chosen to be even. +.P +These functions are unaffected by the current rounding mode (see +.BR fenv (3)). +.P +The +.BR drem () +function does precisely the same thing. +.SH RETURN VALUE +On success, these +functions return the floating-point remainder, +\fIx\fP\-\fIn\fP*\fIy\fP. +If the return value is 0, it has the sign of +.IR x . +.P +If +.I x +or +.I y +is a NaN, a NaN is returned. +.P +If +.I x +is an infinity, +and +.I y +is not a NaN, +a domain error occurs, and +a NaN is returned. +.P +If +.I y +is zero, +.\" FIXME . Instead, glibc gives a domain error even if x is a NaN +and +.I x +is not a NaN, +.\" Interestingly, remquo(3) does not have the same problem. +a domain error occurs, and +a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity and \fIy\fP is not a NaN +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.IP +These functions do not set +.I errno +for this case. +.TP +Domain error: \fIy\fP is zero\" [XXX see bug above] and \fIx\fP is not a NaN +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR drem (), +.BR dremf (), +.BR dreml (), +.BR remainder (), +.BR remainderf (), +.BR remainderl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.\" IEC 60559. +.TP +.BR remainder () +.TQ +.BR remainderf () +.TQ +.BR remainderl () +C11, POSIX.1-2008. +.TP +.BR drem () +.TQ +.BR dremf () +.TQ +.BR dreml () +None. +.SH HISTORY +.\" IEC 60559. +.TP +.BR remainder () +.TQ +.BR remainderf () +.TQ +.BR remainderl () +C99, POSIX.1-2001. +.TP +.BR drem () +4.3BSD. +.TP +.BR dremf () +.TQ +.BR dreml () +Tru64, glibc2. +.SH BUGS +Before glibc 2.15, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6779 +the call +.P +.in +4n +.EX +remainder(nan(""), 0); +.EE +.in +.P +returned a NaN, as expected, but wrongly caused a domain error. +Since glibc 2.15, a silent NaN (i.e., no domain error) is returned. +.P +Before glibc 2.15, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6783 +.I errno +was not set to +.B EDOM +for the domain error that occurs when +.I x +is an infinity and +.I y +is not a NaN. +.SH EXAMPLES +The call "remainder(29.0, 3.0)" returns \-1. +.SH SEE ALSO +.BR div (3), +.BR fmod (3), +.BR remquo (3) diff --git a/man/man3/remainderf.3 b/man/man3/remainderf.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man/man3/remainderf.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man/man3/remainderl.3 b/man/man3/remainderl.3 new file mode 100644 index 0000000..b7a5b23 --- /dev/null +++ b/man/man3/remainderl.3 @@ -0,0 +1 @@ +.so man3/remainder.3 diff --git a/man/man3/remove.3 b/man/man3/remove.3 new file mode 100644 index 0000000..b6bedf1 --- /dev/null +++ b/man/man3/remove.3 @@ -0,0 +1,93 @@ +'\" t +.\" This file is derived from unlink.2, which has the following copyright: +.\" +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Ian Jackson. +.\" +.\" Edited into remove.3 shape by: +.\" Graeme W. Wilford (G.Wilford@ee.surrey.ac.uk) on 13th July 1994 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH remove 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +remove \- remove a file or directory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int remove(const char *" pathname ); +.fi +.SH DESCRIPTION +.BR remove () +deletes a name from the filesystem. +It calls +.BR unlink (2) +for files, and +.BR rmdir (2) +for directories. +.P +If the removed name was the +last link to a file and no processes have the file open, the file is +deleted and the space it was using is made available for reuse. +.P +If the name was the last link to a file, +but any processes still have the file open, +the file will remain in existence until the last file +descriptor referring to it is closed. +.P +If the name referred to a symbolic link, the link is removed. +.P +If the name referred to a socket, FIFO, or device, the name is removed, +but processes which have the object open may continue to use it. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +The errors that occur are those for +.BR unlink (2) +and +.BR rmdir (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR remove () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, 4.3BSD. +.\" .SH NOTES +.\" Under libc4 and libc5, +.\" .BR remove () +.\" was an alias for +.\" .BR unlink (2) +.\" (and hence would not remove directories). +.SH BUGS +Infelicities in the protocol underlying NFS can cause the unexpected +disappearance of files which are still being used. +.SH SEE ALSO +.BR rm (1), +.BR unlink (1), +.BR link (2), +.BR mknod (2), +.BR open (2), +.BR rename (2), +.BR rmdir (2), +.BR unlink (2), +.BR mkfifo (3), +.BR symlink (7) diff --git a/man/man3/remque.3 b/man/man3/remque.3 new file mode 100644 index 0000000..a0c8836 --- /dev/null +++ b/man/man3/remque.3 @@ -0,0 +1 @@ +.so man3/insque.3 diff --git a/man/man3/remquo.3 b/man/man3/remquo.3 new file mode 100644 index 0000000..4a78671 --- /dev/null +++ b/man/man3/remquo.3 @@ -0,0 +1,138 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" based on glibc infopages +.\" polished, aeb +.\" +.TH remquo 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +remquo, remquof, remquol \- remainder and part of quotient +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double remquo(double " x ", double " y ", int *" quo ); +.BI "float remquof(float " x ", float " y ", int *" quo ); +.BI "long double remquol(long double " x ", long double " y ", int *" quo ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR remquo (), +.BR remquof (), +.BR remquol (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions compute the remainder and part of the quotient +upon division of +.I x +by +.IR y . +A few bits of the quotient are stored via the +.I quo +pointer. +The remainder is returned as the function result. +.P +The value of the remainder is the same as that computed by the +.BR remainder (3) +function. +.P +The value stored via the +.I quo +pointer has the sign of +.I x\~/\~y +and agrees with the quotient in at least the low order 3 bits. +.P +For example, \fIremquo(29.0,\ 3.0)\fP returns \-1.0 and might store 2. +Note that the actual quotient might not fit in an integer. +.\" A possible application of this function might be the computation +.\" of sin(x). Compute remquo(x, pi/2, &quo) or so. +.\" +.\" glibc, UnixWare: return 3 bits +.\" MacOS 10: return 7 bits +.SH RETURN VALUE +On success, these functions return the same value as +the analogous functions described in +.BR remainder (3). +.P +If +.I x +or +.I y +is a NaN, a NaN is returned. +.P +If +.I x +is an infinity, +and +.I y +is not a NaN, +a domain error occurs, and +a NaN is returned. +.P +If +.I y +is zero, +and +.I x +is not a NaN, +a domain error occurs, and +a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity or \fIy\fP is 0, \ +and the other argument is not a NaN +.\" .I errno +.\" is set to +.\" .BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.P +These functions do not set +.IR errno . +.\" FIXME . Is it intentional that these functions do not set errno? +.\" Bug raised: https://www.sourceware.org/bugzilla/show_bug.cgi?id=6802 +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR remquo (), +.BR remquof (), +.BR remquol () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH SEE ALSO +.BR fmod (3), +.BR logb (3), +.BR remainder (3) diff --git a/man/man3/remquof.3 b/man/man3/remquof.3 new file mode 100644 index 0000000..458f051 --- /dev/null +++ b/man/man3/remquof.3 @@ -0,0 +1 @@ +.so man3/remquo.3 diff --git a/man/man3/remquol.3 b/man/man3/remquol.3 new file mode 100644 index 0000000..458f051 --- /dev/null +++ b/man/man3/remquol.3 @@ -0,0 +1 @@ +.so man3/remquo.3 diff --git a/man/man3/res_init.3 b/man/man3/res_init.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_init.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_mkquery.3 b/man/man3/res_mkquery.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_mkquery.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nclose.3 b/man/man3/res_nclose.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nclose.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_ninit.3 b/man/man3/res_ninit.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_ninit.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nmkquery.3 b/man/man3/res_nmkquery.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nmkquery.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nquery.3 b/man/man3/res_nquery.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nquery.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nquerydomain.3 b/man/man3/res_nquerydomain.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nquerydomain.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nsearch.3 b/man/man3/res_nsearch.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nsearch.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_nsend.3 b/man/man3/res_nsend.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_nsend.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_query.3 b/man/man3/res_query.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_query.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_querydomain.3 b/man/man3/res_querydomain.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_querydomain.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_search.3 b/man/man3/res_search.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_search.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/res_send.3 b/man/man3/res_send.3 new file mode 100644 index 0000000..87a6d0e --- /dev/null +++ b/man/man3/res_send.3 @@ -0,0 +1 @@ +.so man3/resolver.3 diff --git a/man/man3/resolver.3 b/man/man3/resolver.3 new file mode 100644 index 0000000..cc5f404 --- /dev/null +++ b/man/man3/resolver.3 @@ -0,0 +1,511 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and (C) Copyright 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2004-10-31 by aeb +.\" +.TH resolver 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend, +res_nclose, +res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, +dn_comp, dn_expand \- +resolver routines +.SH LIBRARY +Resolver library +.RI ( libresolv ", " \-lresolv ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.B struct __res_state; +.B typedef struct __res_state *res_state; +.P +.BI "int res_ninit(res_state " statep ); +.P +.BI "void res_nclose(res_state " statep ); +.P +.BI "int res_nquery(res_state " statep , +.BI " const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.BI "int res_nsearch(res_state " statep , +.BI " const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.BI "int res_nquerydomain(res_state " statep , +.BI " const char *" name ", const char *" domain , +.BI " int " class ", int " type ", unsigned char " answer [. anslen ], +.BI " int " anslen ); +.P +.BI "int res_nmkquery(res_state " statep , +.BI " int " op ", const char *" dname ", int " class , +.BI " int " type ", const unsigned char " data [. datalen "], \ +int " datalen , +.BI " const unsigned char *" newrr , +.BI " unsigned char " buf [. buflen "], int " buflen ); +.P +.BI "int res_nsend(res_state " statep , +.BI " const unsigned char " msg [. msglen "], int " msglen , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.BI "int dn_comp(const char *" exp_dn ", unsigned char " comp_dn [. length ], +.BI " int " length ", unsigned char **" dnptrs , +.BI " unsigned char **" lastdnptr ); +.P +.BI "int dn_expand(const unsigned char *" msg , +.BI " const unsigned char *" eomorig , +.BI " const unsigned char *" comp_dn ", char " exp_dn [. length ], +.BI " int " length ); +.P +.B [[deprecated]] extern struct __res_state _res; +.P +.B [[deprecated]] int res_init(void); +.P +.B [[deprecated]] +.BI "int res_query(const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.B [[deprecated]] +.BI "int res_search(const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.B [[deprecated]] +.BI "int res_querydomain(const char *" name ", const char *" domain , +.BI " int " class ", int " type ", unsigned char " answer [. anslen ], +.BI " int " anslen ); +.P +.B [[deprecated]] +.BI "int res_mkquery(int " op ", const char *" dname ", int " class , +.BI " int " type ", const unsigned char " data [. datalen "], \ +int " datalen , +.BI " const unsigned char *" newrr , +.BI " unsigned char " buf [. buflen "], int " buflen ); +.P +.B [[deprecated]] +.BI "int res_send(const unsigned char " msg [. msglen "], int " msglen , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.fi +.SH DESCRIPTION +.B Note: +This page is incomplete (various resolver functions provided by glibc +are not described) and likely out of date. +.P +The functions described below make queries to and interpret +the responses from Internet domain name servers. +.P +The API consists of a set of more modern, reentrant functions +and an older set of nonreentrant functions that have been superseded. +The traditional resolver interfaces such as +.BR res_init () +and +.BR res_query () +use some static (global) state stored in the +.I _res +structure, rendering these functions non-thread-safe. +BIND 8.2 introduced a set of new interfaces +.BR res_ninit (), +.BR res_nquery (), +and so on, which take a +.I res_state +as their first argument, so you can use a per-thread resolver state. +.P +The +.BR res_ninit () +and +.BR res_init () +functions read the configuration files (see +.BR resolv.conf (5)) +to get the default domain name and name +server address(es). +If no server is given, the local host is tried. +If no domain is given, that associated with the local host is used. +It can be overridden with the environment variable +.BR LOCALDOMAIN . +.BR res_ninit () +or +.BR res_init () +is normally executed by the first call to one of the +other functions. +Every call to +.BR res_ninit () +requires a corresponding call to +.BR res_nclose () +to free memory allocated by +.BR res_ninit () +and subsequent calls to +.BR res_nquery (). +.P +The +.BR res_nquery () +and +.BR res_query () +functions query the name server for the +fully qualified domain name \fIname\fP of specified \fItype\fP and +\fIclass\fP. +The reply is left in the buffer \fIanswer\fP of length +\fIanslen\fP supplied by the caller. +.P +The +.BR res_nsearch () +and +.BR res_search () +functions make a query and waits for the response like +.BR res_nquery () +and +.BR res_query (), +but in addition they implement the default and search +rules controlled by +.B RES_DEFNAMES +and +.B RES_DNSRCH +(see description of +\fI_res\fP options below). +.P +The +.BR res_nquerydomain () +and +.BR res_querydomain () +functions make a query using +.BR res_nquery ()/ res_query () +on the concatenation of \fIname\fP and \fIdomain\fP. +.P +The following functions are lower-level routines used by +.BR res_nquery ()/ res_query (). +.P +The +.BR res_nmkquery () +and +.BR res_mkquery () +functions construct a query message in \fIbuf\fP +of length \fIbuflen\fP for the domain name \fIdname\fP. +The query type +\fIop\fP is one of the following (typically +.BR QUERY ): +.TP +.B QUERY +Standard query. +.TP +.B IQUERY +Inverse query. +This option was removed in glibc 2.26, +.\" commit e4e794841e3140875f2aa86b90e2ada3d61e1244 +since it has not been supported by DNS servers for a very long time. +.TP +.B NS_NOTIFY_OP +Notify secondary of SOA (Start of Authority) change. +.P +\fInewrr\fP is currently unused. +.P +The +.BR res_nsend () +and +.BR res_send () +function send a preformatted query given in +\fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP +which is of length \fIanslen\fP. +They will call +.BR res_ninit ()/ res_init () +if it has not already been called. +.P +The +.BR dn_comp () +function compresses the domain name \fIexp_dn\fP +and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP. +The compression uses an array of pointers \fIdnptrs\fP to previously +compressed names in the current message. +The first pointer points +to the beginning of the message and the list ends with NULL. +The limit of the array is specified by \fIlastdnptr\fP. +If \fIdnptr\fP is NULL, domain names are not compressed. +If \fIlastdnptr\fP is NULL, the list +of labels is not updated. +.P +The +.BR dn_expand () +function expands the compressed domain name +\fIcomp_dn\fP to a full domain name, which is placed in the buffer +\fIexp_dn\fP of size \fIlength\fP. +The compressed name is contained +in a query or reply message, and \fImsg\fP points to the beginning of +the message. +.P +The resolver routines use configuration and state information +contained in a +.I __res_state +structure (either passed as the +.I statep +argument, or in the global variable +.IR _res , +in the case of the older nonreentrant functions). +The only field of this structure that is normally manipulated by the +user is the +.I options +field. +This field can contain the bitwise "OR" +of the following options: +.TP +.B RES_INIT +True if +.BR res_ninit () +or +.BR res_init () +has been called. +.TP +.B RES_DEBUG +Print debugging messages. +This option is available only if glibc was built with debugging enabled, +.\" See resolv/README. +.\" Support for RES_DEBUG was made conditional in glibc 2.2. +which is not the default. +.TP +.BR RES_AAONLY " (unimplemented; deprecated in glibc 2.25)" +Accept authoritative answers only. +.BR res_send () +continues until +it finds an authoritative answer or returns an error. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.B RES_USEVC +Use TCP connections for queries rather than UDP datagrams. +.TP +.BR RES_PRIMARY " (unimplemented; deprecated in glibc 2.25)" +Query primary domain name server only. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.B RES_IGNTC +Ignore truncation errors. +Don't retry with TCP. +.TP +.B RES_RECURSE +Set the recursion desired bit in queries. +Recursion is carried out +by the domain name server, not by +.BR res_send (). +[Enabled by default]. +.TP +.B RES_DEFNAMES +If set, +.BR res_search () +will append the default domain name to +single component names\[em]that is, those that do not contain a dot. +[Enabled by default]. +.TP +.B RES_STAYOPEN +Used with +.B RES_USEVC +to keep the TCP connection open between queries. +.TP +.B RES_DNSRCH +If set, +.BR res_search () +will search for hostnames in the current +domain and in parent domains. +This option is used by +.BR gethostbyname (3). +[Enabled by default]. +.TP +.B RES_INSECURE1 +Accept a response from a wrong server. +This can be used to detect potential security hazards, +but you need to compile glibc with debugging enabled and use +.B RES_DEBUG +option (for debug purpose only). +.TP +.B RES_INSECURE2 +Accept a response which contains a wrong query. +This can be used to detect potential security hazards, +but you need to compile glibc with debugging enabled and use +.B RES_DEBUG +option (for debug purpose only). +.TP +.B RES_NOALIASES +Disable usage of +.B HOSTALIASES +environment variable. +.TP +.B RES_USE_INET6 +Try an AAAA query before an A query inside the +.BR gethostbyname (3) +function, and map IPv4 responses in IPv6 "tunneled form" if no AAAA records +are found but an A record set exists. +Since glibc 2.25, this option is deprecated, +and its usage produces a warning; +applications should use +.BR getaddrinfo (3), +rather than +.BR gethostbyname (3). +.TP +.B RES_ROTATE +Causes round-robin selection of name servers from among those listed. +This has the effect of spreading the query load among all listed servers, +rather than having all clients try the first listed server first every +time. +.TP +.BR RES_NOCHECKNAME " (unimplemented; deprecated in glibc 2.25)" +Disable the modern BIND checking of incoming hostnames and mail names +for invalid characters such as underscore (_), non-ASCII, +or control characters. +This option was present until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_KEEPTSIG " (unimplemented; deprecated in glibc 2.25)" +Do not strip TSIG records. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_BLAST " (unimplemented; deprecated in glibc 2.25)" +Send each query simultaneously and recursively to all servers. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_USEBSTRING " (glibc 2.3.4 to glibc 2.24)" +Make reverse IPv6 lookups using the bit-label format described in RFC 2673; +if this option is not set (which is the default), then nibble format is used. +This option was removed in glibc 2.25, +since it relied on a backward-incompatible +DNS extension that was never deployed on the Internet. +.TP +.BR RES_NOIP6DOTINT " (glibc 2.24 and earlier)" +Use +.I ip6.arpa +zone in IPv6 reverse lookup instead of +.IR ip6.int , +which is deprecated since glibc 2.3.4. +This option is present up to and including glibc 2.24, +where it is enabled by default. +In glibc 2.25, this option was removed. +.TP +.BR RES_USE_EDNS0 " (since glibc 2.6)" +Enables support for the DNS extensions (EDNS0) described in RFC 2671. +.TP +.BR RES_SNGLKUP " (since glibc 2.10)" +By default, glibc performs IPv4 and IPv6 lookups in parallel +since glibc 2.9. +Some appliance DNS servers cannot handle these queries properly +and make the requests time out. +This option disables the behavior and makes glibc +perform the IPv6 and IPv4 requests sequentially +(at the cost of some slowdown of the resolving process). +.TP +.B RES_SNGLKUPREOP +When +.B RES_SNGLKUP +option is enabled, opens a new socket for the each request. +.TP +.B RES_USE_DNSSEC +Use DNSSEC with OK bit in OPT record. +This option implies +.BR RES_USE_EDNS0 . +.TP +.B RES_NOTLDQUERY +Do not look up unqualified name as a top-level domain (TLD). +.TP +.B RES_DEFAULT +Default option which implies: +.BR RES_RECURSE , +.BR RES_DEFNAMES , +.BR RES_DNSRCH , +and +.BR RES_NOIP6DOTINT . +.\" +.SH RETURN VALUE +The +.BR res_ninit () +and +.BR res_init () +functions return 0 on success, or \-1 if an error +occurs. +.P +The +.BR res_nquery (), +.BR res_query (), +.BR res_nsearch (), +.BR res_search (), +.BR res_nquerydomain (), +.BR res_querydomain (), +.BR res_nmkquery (), +.BR res_mkquery (), +.BR res_nsend (), +and +.BR res_send () +functions return the length +of the response, or \-1 if an error occurs. +.P +The +.BR dn_comp () +and +.BR dn_expand () +functions return the length +of the compressed name, or \-1 if an error occurs. +.P +In the case of an error return from +.BR res_nquery (), +.BR res_query (), +.BR res_nsearch (), +.BR res_search (), +.BR res_nquerydomain (), +or +.BR res_querydomain (), +the global variable +.I h_errno +(see +.BR gethostbyname (3)) +can be consulted to determine the cause of the error. +.SH FILES +.TP +.I /etc/resolv.conf +resolver configuration file +.TP +.I /etc/host.conf +resolver configuration file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR res_ninit (), +.BR res_nclose (), +.BR res_nquery (), +.BR res_nsearch (), +.BR res_nquerydomain (), +.BR res_nsend () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR res_nmkquery (), +.BR dn_comp (), +.BR dn_expand () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +.SH SEE ALSO +.BR gethostbyname (3), +.BR resolv.conf (5), +.BR resolver (5), +.BR hostname (7), +.BR named (8) +.P +The GNU C library source file +.IR resolv/README . diff --git a/man/man3/rewind.3 b/man/man3/rewind.3 new file mode 100644 index 0000000..a1487b5 --- /dev/null +++ b/man/man3/rewind.3 @@ -0,0 +1 @@ +.so man3/fseek.3 diff --git a/man/man3/rewinddir.3 b/man/man3/rewinddir.3 new file mode 100644 index 0000000..74ab903 --- /dev/null +++ b/man/man3/rewinddir.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:29:11 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) +.TH rewinddir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rewinddir \- reset directory stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "void rewinddir(DIR *" dirp ); +.fi +.SH DESCRIPTION +The +.BR rewinddir () +function resets the position of the directory +stream +.I dirp +to the beginning of the directory. +.SH RETURN VALUE +The +.BR rewinddir () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rewinddir () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR scandir (3), +.BR seekdir (3), +.BR telldir (3) diff --git a/man/man3/rexec.3 b/man/man3/rexec.3 new file mode 100644 index 0000000..7b6c839 --- /dev/null +++ b/man/man3/rexec.3 @@ -0,0 +1,161 @@ +'\" t +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)rexec.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD: src/lib/libcompat/4.3/rexec.3,v 1.12 2004/07/02 23:52:14 ru Exp $ +.\" +.\" Taken from FreeBSD 5.4; not checked against Linux reality (mtk) +.\" +.\" 2013-06-21, mtk, Converted from mdoc to man macros +.\" +.TH rexec 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rexec, rexec_af \- return stream to a remote command +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B [[deprecated]] +.BI "int rexec(char **restrict " ahost ", int " inport , +.BI " const char *restrict " user ", const char *restrict " passwd , +.BI " const char *restrict " cmd ", int *restrict " fd2p ); +.P +.B [[deprecated]] +.BI "int rexec_af(char **restrict " ahost ", int " inport , +.BI " const char *restrict " user ", const char *restrict " passwd , +.BI " const char *restrict " cmd ", int *restrict " fd2p , +.BI " sa_family_t " af ); +.fi +.P +.BR rexec (), +.BR rexec_af (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + In glibc up to and including 2.19: + _BSD_SOURCE +.fi +.SH DESCRIPTION +This interface is obsoleted by +.BR rcmd (3). +.P +The +.BR rexec () +function +looks up the host +.I *ahost +using +.BR gethostbyname (3), +returning \-1 if the host does not exist. +Otherwise, +.I *ahost +is set to the standard name of the host. +If a username and password are both specified, then these +are used to authenticate to the foreign host; otherwise +the environment and then the +.I .netrc +file in user's +home directory are searched for appropriate information. +If all this fails, the user is prompted for the information. +.P +The port +.I inport +specifies which well-known DARPA Internet port to use for +the connection; the call +.I "getservbyname(""exec"", ""tcp"")" +(see +.BR getservent (3)) +will return a pointer to a structure that contains the necessary port. +The protocol for connection is described in detail in +.BR rexecd (8). +.P +If the connection succeeds, +a socket in the Internet domain of type +.B SOCK_STREAM +is returned to +the caller, and given to the remote command as +.I stdin +and +.IR stdout . +If +.I fd2p +is nonzero, then an auxiliary channel to a control +process will be setup, and a file descriptor for it will be placed +in +.IR *fd2p . +The control process will return diagnostic +output from the command (unit 2) on this channel, and will also +accept bytes on this channel as being UNIX signal numbers, to be +forwarded to the process group of the command. +The diagnostic +information returned does not include remote authorization failure, +as the secondary connection is set up after authorization has been +verified. +If +.I fd2p +is 0, then the +.I stderr +(unit 2 of the remote +command) will be made the same as the +.I stdout +and no +provision is made for sending arbitrary signals to the remote process, +although you may be able to get its attention by using out-of-band data. +.SS rexec_af() +The +.BR rexec () +function works over IPv4 +.RB ( AF_INET ). +By contrast, the +.BR rexec_af () +function provides an extra argument, +.IR af , +that allows the caller to select the protocol. +This argument can be specified as +.BR AF_INET , +.BR AF_INET6 , +or +.B AF_UNSPEC +(to allow the implementation to select the protocol). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rexec (), +.BR rexec_af () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR rexec () +4.2BSD, BSD, Solaris. +.TP +.BR rexec_af () +glibc 2.2. +.SH BUGS +The +.BR rexec () +function sends the unencrypted password across the network. +.P +The underlying service is considered a big security hole and therefore +not enabled on many sites; see +.BR rexecd (8) +for explanations. +.SH SEE ALSO +.BR rcmd (3), +.BR rexecd (8) diff --git a/man/man3/rexec_af.3 b/man/man3/rexec_af.3 new file mode 100644 index 0000000..517a2d2 --- /dev/null +++ b/man/man3/rexec_af.3 @@ -0,0 +1 @@ +.so man3/rexec.3 diff --git a/man/man3/rindex.3 b/man/man3/rindex.3 new file mode 100644 index 0000000..a9cd4b3 --- /dev/null +++ b/man/man3/rindex.3 @@ -0,0 +1 @@ +.so man3/index.3 diff --git a/man/man3/rint.3 b/man/man3/rint.3 new file mode 100644 index 0000000..87538b0 --- /dev/null +++ b/man/man3/rint.3 @@ -0,0 +1,145 @@ +'\" t +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH rint 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nearbyint, nearbyintf, nearbyintl, rint, rintf, rintl \- round +to nearest integer +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double nearbyint(double " x ); +.BI "float nearbyintf(float " x ); +.BI "long double nearbyintl(long double " x ); +.P +.BI "double rint(double " x ); +.BI "float rintf(float " x ); +.BI "long double rintl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR nearbyint (), +.BR nearbyintf (), +.BR nearbyintl (): +.nf + _POSIX_C_SOURCE >= 200112L || _ISOC99_SOURCE +.fi +.P +.BR rint (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR rintf (), +.BR rintl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR nearbyint (), +.BR nearbyintf (), +and +.BR nearbyintl () +functions round their argument to an integer value in floating-point +format, using the current rounding direction (see +.BR fesetround (3)) +and without raising the +.I inexact +exception. +When the current rounding direction is to nearest, these +functions round halfway cases to the even integer in accordance with +IEEE-754. +.P +The +.BR rint (), +.BR rintf (), +and +.BR rintl () +functions do the same, but will raise the +.I inexact +exception +.RB ( FE_INEXACT , +checkable via +.BR fetestexcept (3)) +when the result differs in value from the argument. +.SH RETURN VALUE +These functions return the rounded integer value. +.P +If +.I x +is integral, +0, \-0, NaN, or infinite, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR nearbyint (), +.BR nearbyintf (), +.BR nearbyintl (), +.BR rint (), +.BR rintf (), +.BR rintl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +SUSv2 and POSIX.1-2001 contain text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 127 (respectively, 1023), +and the number of mantissa bits +including the implicit bit +is 24 (respectively, 53).) +.P +If you want to store the rounded value in an integer type, +you probably want to use one of the functions described in +.BR lrint (3) +instead. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR round (3), +.BR trunc (3) diff --git a/man/man3/rintf.3 b/man/man3/rintf.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man/man3/rintf.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man/man3/rintl.3 b/man/man3/rintl.3 new file mode 100644 index 0000000..3300c2c --- /dev/null +++ b/man/man3/rintl.3 @@ -0,0 +1 @@ +.so man3/rint.3 diff --git a/man/man3/round.3 b/man/man3/round.3 new file mode 100644 index 0000000..86bc373 --- /dev/null +++ b/man/man3/round.3 @@ -0,0 +1,110 @@ +'\" t +.\" Copyright 2001 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH round 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +round, roundf, roundl \- round to nearest integer, away from zero +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double round(double " x ); +.BI "float roundf(float " x ); +.BI "long double roundl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR round (), +.BR roundf (), +.BR roundl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions round +.I x +to the nearest integer, but +round halfway cases away from zero (regardless of the current rounding +direction, see +.BR fenv (3)), +instead of to the nearest even integer like +.BR rint (3). +.P +For example, +.I round(0.5) +is 1.0, and +.I round(\-0.5) +is \-1.0. +.SH RETURN VALUE +These functions return the rounded integer value. +.P +If +.I x +is integral, +0, \-0, NaN, or infinite, +.I x +itself is returned. +.SH ERRORS +No errors occur. +POSIX.1-2001 documents a range error for overflows, but see NOTES. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR round (), +.BR roundf (), +.BR roundl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH NOTES +POSIX.1-2001 contains text about overflow (which might set +.I errno +to +.BR ERANGE , +or raise an +.B FE_OVERFLOW +exception). +In practice, the result cannot overflow on any current machine, +so this error-handling stuff is just nonsense. +.\" The POSIX.1-2001 APPLICATION USAGE SECTION discusses this point. +(More precisely, overflow can happen only when the maximum value +of the exponent is smaller than the number of mantissa bits. +For the IEEE-754 standard 32-bit and 64-bit floating-point numbers +the maximum value of the exponent is 127 (respectively, 1023), +and the number of mantissa bits +including the implicit bit +is 24 (respectively, 53).) +.P +If you want to store the rounded value in an integer type, +you probably want to use one of the functions described in +.BR lround (3) +instead. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lround (3), +.BR nearbyint (3), +.BR rint (3), +.BR trunc (3) diff --git a/man/man3/roundf.3 b/man/man3/roundf.3 new file mode 100644 index 0000000..f7ab386 --- /dev/null +++ b/man/man3/roundf.3 @@ -0,0 +1 @@ +.so man3/round.3 diff --git a/man/man3/roundl.3 b/man/man3/roundl.3 new file mode 100644 index 0000000..f7ab386 --- /dev/null +++ b/man/man3/roundl.3 @@ -0,0 +1 @@ +.so man3/round.3 diff --git a/man/man3/roundup.3 b/man/man3/roundup.3 new file mode 100644 index 0000000..4265e96 --- /dev/null +++ b/man/man3/roundup.3 @@ -0,0 +1,56 @@ +.\" Copyright (C) 2023 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH roundup 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +roundup \- round up in steps +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI roundup( x ", " step ); +.fi +.SH DESCRIPTION +This macro rounds +.I x +to the nearest multiple of +.I step +that is not less than +.IR x . +.P +It is typically used for +rounding up a pointer to align it or +increasing a buffer to be allocated. +.P +This API is not designed to be generic, +and doesn't work in some cases +that are not important for the typical use cases described above. +See CAVEATS. +.SH RETURN VALUE +This macro returns the rounded value. +.SH STANDARDS +None. +.SH CAVEATS +The arguments may be evaluated more than once. +.P +.I x +should be nonnegative, +and +.I step +should be positive. +.P +If +.I x + step +would overflow or wrap around, +the behavior is undefined. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR rint (3), +.BR lround (3), +.BR round (3) diff --git a/man/man3/rpc.3 b/man/man3/rpc.3 new file mode 100644 index 0000000..3de9704 --- /dev/null +++ b/man/man3/rpc.3 @@ -0,0 +1,1201 @@ +'\" t +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)rpc.3n 2.4 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI +.\" +.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax +.\" +.TH rpc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rpc \- library routines for remote procedure calls +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS AND DESCRIPTION +These routines allow C programs to make procedure +calls on other machines across the network. +First, the client calls a procedure to send a data packet to the server. +Upon receipt of the packet, the server calls a dispatch routine +to perform the requested service, and then sends back a reply. +Finally, the procedure call returns to the client. +.\" .P +.\" We don't have an rpc_secure.3 page at the moment -- MTK, 19 Sep 05 +.\" Routines that are used for Secure RPC (DES authentication) are described in +.\" .BR rpc_secure (3). +.\" Secure RPC can be used only if DES encryption is available. +.P +To take use of these routines, include the header file +.IR "" . +.P +The prototypes below make use of the following types: +.P +.RS 4 +.EX +.BI "typedef int " bool_t ; +.P +.BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *, ...);" +.P +.BI "typedef bool_t (*" resultproc_t ")(caddr_t " resp , +.BI " struct sockaddr_in *" raddr ); +.EE +.RE +.P +See the header files for the declarations of the +.IR AUTH , +.IR CLIENT , +.IR SVCXPRT , +and +.I XDR +types. +.P +.nf +.BI "void auth_destroy(AUTH *" auth ); +.fi +.IP +A macro that destroys the authentication information associated with +.IR auth . +Destruction usually involves deallocation of private data structures. +The use of +.I auth +is undefined after calling +.BR auth_destroy (). +.P +.nf +.B AUTH *authnone_create(void); +.fi +.IP +Create and return an RPC +authentication handle that passes nonusable authentication +information with each remote procedure call. +This is the default authentication used by RPC. +.P +.nf +.BI "AUTH *authunix_create(char *" host ", uid_t " uid ", gid_t " gid , +.BI " int " len ", gid_t " aup_gids [. len ]); +.fi +.IP +Create and return an RPC authentication handle that contains +authentication information. +The parameter +.I host +is the name of the machine on which the information was created; +.I uid +is the user's user ID; +.I gid +is the user's current group ID; +.I len +and +.I aup_gids +refer to a counted array of groups to which the user belongs. +It is easy to impersonate a user. +.P +.nf +.B AUTH *authunix_create_default(void); +.fi +.IP +Calls +.BR authunix_create () +with the appropriate parameters. +.P +.nf +.BI "int callrpc(char *" host ", unsigned long " prognum , +.BI " unsigned long " versnum ", unsigned long " procnum , +.BI " xdrproc_t " inproc ", const char *" in , +.BI " xdrproc_t " outproc ", char *" out ); +.fi +.IP +Call the remote procedure associated with +.IR prognum , +.IR versnum , +and +.I procnum +on the machine, +.IR host . +The parameter +.I in +is the address of the procedure's argument(s), and +.I out +is the address of where to place the result(s); +.I inproc +is used to encode the procedure's parameters, and +.I outproc +is used to decode the procedure's results. +This routine returns zero if it succeeds, or the value of +.B "enum clnt_stat" +cast to an integer if it fails. +The routine +.BR clnt_perrno () +is handy for translating failure statuses into messages. +.IP +Warning: calling remote procedures with this routine +uses UDP/IP as a transport; see +.BR clntudp_create () +for restrictions. +You do not have control of timeouts or authentication using this routine. +.P +.nf +.BI "enum clnt_stat clnt_broadcast(unsigned long " prognum , +.BI " unsigned long " versnum ", unsigned long " procnum , +.BI " xdrproc_t " inproc ", char *" in , +.BI " xdrproc_t " outproc ", char *" out , +.BI " resultproc_t " eachresult ); +.fi +.IP +Like +.BR callrpc (), +except the call message is broadcast to all locally +connected broadcast nets. +Each time it receives a response, this routine calls +.BR eachresult (), +whose form is: +.IP +.in +4n +.EX +.BI "eachresult(char *" out ", struct sockaddr_in *" addr ); +.EE +.in +.IP +where +.I out +is the same as +.I out +passed to +.BR clnt_broadcast (), +except that the remote procedure's output is decoded there; +.I addr +points to the address of the machine that sent the results. +If +.BR eachresult () +returns zero, +.BR clnt_broadcast () +waits for more replies; otherwise it returns with appropriate status. +.IP +Warning: broadcast sockets are limited in size to the +maximum transfer unit of the data link. +For ethernet, this value is 1500 bytes. +.P +.nf +.BI "enum clnt_stat clnt_call(CLIENT *" clnt ", unsigned long " procnum , +.BI " xdrproc_t " inproc ", char *" in , +.BI " xdrproc_t " outproc ", char *" out , +.BI " struct timeval " tout ); +.fi +.IP +A macro that calls the remote procedure +.I procnum +associated with the client handle, +.IR clnt , +which is obtained with an RPC client creation routine such as +.BR clnt_create (). +The parameter +.I in +is the address of the procedure's argument(s), and +.I out +is the address of where to place the result(s); +.I inproc +is used to encode the procedure's parameters, and +.I outproc +is used to decode the procedure's results; +.I tout +is the time allowed for results to come back. +.P +.nf +.BI "clnt_destroy(CLIENT *" clnt ); +.fi +.IP +A macro that destroys the client's RPC handle. +Destruction usually involves deallocation +of private data structures, including +.I clnt +itself. +Use of +.I clnt +is undefined after calling +.BR clnt_destroy (). +If the RPC library opened the associated socket, it will close it also. +Otherwise, the socket remains open. +.P +.nf +.BI "CLIENT *clnt_create(const char *" host ", unsigned long " prog , +.BI " unsigned long " vers ", const char *" proto ); +.fi +.IP +Generic client creation routine. +.I host +identifies the name of the remote host where the server is located. +.I proto +indicates which kind of transport protocol to use. +The currently supported values for this field are \[lq]udp\[rq] +and \[lq]tcp\[rq]. +Default timeouts are set, but can be modified using +.BR clnt_control (). +.IP +Warning: using UDP has its shortcomings. +Since UDP-based RPC messages can hold only up to 8 Kbytes of encoded data, +this transport cannot be used for procedures that take +large arguments or return huge results. +.P +.nf +.BI "bool_t clnt_control(CLIENT *" cl ", int " req ", char *" info ); +.fi +.IP +A macro used to change or retrieve various information +about a client object. +.I req +indicates the type of operation, and +.I info +is a pointer to the information. +For both UDP and TCP, the supported values of +.I req +and their argument types and what they do are: +.IP +.in +4n +.EX +\fBCLSET_TIMEOUT\fP \fIstruct timeval\fP // set total timeout +\fBCLGET_TIMEOUT\fP \fIstruct timeval\fP // get total timeout +.EE +.in +.IP +Note: if you set the timeout using +.BR clnt_control (), +the timeout parameter passed to +.BR clnt_call () +will be ignored in all future calls. +.IP +.in +4n +.EX +\fBCLGET_SERVER_ADDR\fP \fIstruct sockaddr_in\fP + // get server\[aq]s address +.EE +.in +.IP +The following operations are valid for UDP only: +.IP +.in +4n +.EX +\fBCLSET_RETRY_TIMEOUT\fP \fIstruct timeval\fP // set the retry timeout +\fBCLGET_RETRY_TIMEOUT\fP \fIstruct timeval\fP // get the retry timeout +.EE +.in +.IP +The retry timeout is the time that "UDP RPC" +waits for the server to reply before +retransmitting the request. +.P +.nf +.BI "clnt_freeres(CLIENT * " clnt ", xdrproc_t " outproc ", char *" out ); +.fi +.IP +A macro that frees any data allocated by the RPC/XDR +system when it decoded the results of an RPC call. +The parameter +.I out +is the address of the results, and +.I outproc +is the XDR routine describing the results. +This routine returns one if the results were successfully freed, +and zero otherwise. +.P +.nf +.BI "void clnt_geterr(CLIENT *" clnt ", struct rpc_err *" errp ); +.fi +.IP +A macro that copies the error structure out of the client +handle to the structure at address +.IR errp . +.P +.nf +.BI "void clnt_pcreateerror(const char *" s ); +.fi +.IP +Print a message to standard error indicating why a client RPC +handle could not be created. +The message is prepended with string +.I s +and a colon. +Used when a +.BR clnt_create (), +.BR clntraw_create (), +.BR clnttcp_create (), +or +.BR clntudp_create () +call fails. +.P +.nf +.BI "void clnt_perrno(enum clnt_stat " stat ); +.fi +.IP +Print a message to standard error corresponding +to the condition indicated by +.IR stat . +Used after +.BR callrpc (). +.P +.nf +.BI "clnt_perror(CLIENT *" clnt ", const char *" s ); +.fi +.IP +Print a message to standard error indicating why an RPC call failed; +.I clnt +is the handle used to do the call. +The message is prepended with string +.I s +and a colon. +Used after +.BR clnt_call (). +.P +.nf +.BI "char *clnt_spcreateerror(const char *" s ); +.fi +.IP +Like +.BR clnt_pcreateerror (), +except that it returns a string instead of printing to the standard error. +.IP +Bugs: returns pointer to static data that is overwritten on each call. +.P +.nf +.BI "char *clnt_sperrno(enum clnt_stat " stat ); +.fi +.IP +Take the same arguments as +.BR clnt_perrno (), +but instead of sending a message to the standard error indicating why an RPC +call failed, return a pointer to a string which contains the message. +The string ends with a NEWLINE. +.IP +.BR clnt_sperrno () +is used instead of +.BR clnt_perrno () +if the program does not have a standard error (as a program +running as a server quite likely does not), or if the programmer +does not want the message to be output with +.BR printf (3), +or if a message format different than that supported by +.BR clnt_perrno () +is to be used. +Note: unlike +.BR clnt_sperror () +and +.BR clnt_spcreateerror (), +.BR clnt_sperrno () +returns pointer to static data, but the +result will not get overwritten on each call. +.P +.nf +.BI "char *clnt_sperror(CLIENT *" rpch ", const char *" s ); +.fi +.IP +Like +.BR clnt_perror (), +except that (like +.BR clnt_sperrno ()) +it returns a string instead of printing to standard error. +.IP +Bugs: returns pointer to static data that is overwritten on each call. +.P +.nf +.BI "CLIENT *clntraw_create(unsigned long " prognum \ +", unsigned long " versnum ); +.fi +.IP +This routine creates a toy RPC client for the remote program +.IR prognum , +version +.IR versnum . +The transport used to pass messages to the service is +actually a buffer within the process's address space, so the +corresponding RPC server should live in the same address space; see +.BR svcraw_create (). +This allows simulation of RPC and acquisition of RPC +overheads, such as round trip times, without any kernel interference. +This routine returns NULL if it fails. +.P +.nf +.BI "CLIENT *clnttcp_create(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " int *" sockp ", unsigned int " sendsz \ +", unsigned int " recvsz ); +.fi +.IP +This routine creates an RPC client for the remote program +.IR prognum , +version +.IR versnum ; +the client uses TCP/IP as a transport. +The remote program is located at Internet address +.IR *addr . +If +.\"The following inline font conversion is necessary for the hyphen indicator +.I addr\->sin_port +is zero, then it is set to the actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). +The parameter +.I sockp +is a socket; if it is +.BR RPC_ANYSOCK , +then this routine opens a new one and sets +.IR sockp . +Since TCP-based RPC uses buffered I/O, +the user may specify the size of the send and receive buffers +with the parameters +.I sendsz +and +.IR recvsz ; +values of zero choose suitable defaults. +This routine returns NULL if it fails. +.P +.nf +.BI "CLIENT *clntudp_create(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " struct timeval " wait ", int *" sockp ); +.fi +.IP +This routine creates an RPC client for the remote program +.IR prognum , +version +.IR versnum ; +the client uses use UDP/IP as a transport. +The remote program is located at Internet address +.IR addr . +If +.I addr\->sin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). +The parameter +.I sockp +is a socket; if it is +.BR RPC_ANYSOCK , +then this routine opens a new one and sets +.IR sockp . +The UDP transport resends the call message in intervals of +.I wait +time until a response is received or until the call times out. +The total time for the call to time out is specified by +.BR clnt_call (). +.IP +Warning: since UDP-based RPC messages can hold only up to 8 Kbytes +of encoded data, this transport cannot be used for procedures +that take large arguments or return huge results. +.P +.nf +.BI "CLIENT *clntudp_bufcreate(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " struct timeval " wait ", int *" sockp , +.BI " unsigned int " sendsize ", unsigned int "recosize ); +.fi +.IP +This routine creates an RPC client for the remote program +.IR prognum , +on +.IR versnum ; +the client uses use UDP/IP as a transport. +The remote program is located at Internet address +.IR addr . +If +.I addr\->sin_port +is zero, then it is set to actual port that the remote +program is listening on (the remote +.B portmap +service is consulted for this information). +The parameter +.I sockp +is a socket; if it is +.BR RPC_ANYSOCK , +then this routine opens a new one and sets +.IR sockp . +The UDP transport resends the call message in intervals of +.I wait +time until a response is received or until the call times out. +The total time for the call to time out is specified by +.BR clnt_call (). +.IP +This allows the user to specify the maximum packet +size for sending and receiving UDP-based RPC messages. +.P +.nf +.BI "void get_myaddress(struct sockaddr_in *" addr ); +.fi +.IP +Stuff the machine's IP address into +.IR *addr , +without consulting the library routines that deal with +.IR /etc/hosts . +The port number is always set to +.BR htons(PMAPPORT) . +.P +.nf +.BI "struct pmaplist *pmap_getmaps(struct sockaddr_in *" addr ); +.fi +.IP +A user interface to the +.B portmap +service, which returns a list of the current RPC +program-to-port mappings on the host located at IP address +.IR *addr . +This routine can return NULL. +The command +.I rpcinfo\~\-p +uses this routine. +.P +.nf +.BI "unsigned short pmap_getport(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " unsigned int " protocol ); +.fi +.IP +A user interface to the +.B portmap +service, which returns the port number +on which waits a service that supports program number +.IR prognum , +version +.IR versnum , +and speaks the transport protocol associated with +.IR protocol . +The value of +.I protocol +is most likely +.B IPPROTO_UDP +or +.BR IPPROTO_TCP . +A return value of zero means that the mapping does not exist +or that the RPC system failed to contact the remote +.B portmap +service. +In the latter case, the global variable +.I rpc_createerr +contains the RPC status. +.P +.nf +.BI "enum clnt_stat pmap_rmtcall(struct sockaddr_in *" addr , +.BI " unsigned long " prognum ", unsigned long " versnum , +.BI " unsigned long " procnum , +.BI " xdrproc_t " inproc ", char *" in , +.BI " xdrproc_t " outproc ", char *" out , +.BI " struct timeval " tout ", unsigned long *" portp ); +.fi +.IP +A user interface to the +.B portmap +service, which instructs +.B portmap +on the host at IP address +.I *addr +to make an RPC call on your behalf to a procedure on that host. +The parameter +.I *portp +will be modified to the program's port number if the procedure succeeds. +The definitions of other parameters are discussed +in +.BR callrpc () +and +.BR clnt_call (). +This procedure should be used for a \[lq]ping\[rq] and nothing else. +See also +.BR clnt_broadcast (). +.P +.nf +.BI "bool_t pmap_set(unsigned long " prognum ", unsigned long " versnum , +.BI " int " protocol ", unsigned short " port ); +.fi +.IP +A user interface to the +.B portmap +service, which establishes a mapping between the triple +.RI [ prognum , versnum , protocol ] +and +.I port +on the machine's +.B portmap +service. +The value of +.I protocol +is most likely +.B IPPROTO_UDP +or +.BR IPPROTO_TCP . +This routine returns one if it succeeds, zero otherwise. +Automatically done by +.BR svc_register (). +.P +.nf +.BI "bool_t pmap_unset(unsigned long " prognum ", unsigned long " versnum ); +.fi +.IP +A user interface to the +.B portmap +service, which destroys all mapping between the triple +.RI [ prognum , versnum , * ] +and +.B ports +on the machine's +.B portmap +service. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "int registerrpc(unsigned long " prognum ", unsigned long " versnum , +.BI " unsigned long " procnum ", char *(*" procname ")(char *)," +.BI " xdrproc_t " inproc ", xdrproc_t " outproc ); +.fi +.IP +Register procedure +.I procname +with the RPC service package. +If a request arrives for program +.IR prognum , +version +.IR versnum , +and procedure +.IR procnum , +.I procname +is called with a pointer to its parameter(s); +.I procname +should return a pointer to its static result(s); +.I inproc +is used to decode the parameters while +.I outproc +is used to encode the results. +This routine returns zero if the registration succeeded, \-1 otherwise. +.IP +Warning: remote procedures registered in this form +are accessed using the UDP/IP transport; see +.BR svcudp_create () +for restrictions. +.P +.nf +.BI "struct rpc_createerr " rpc_createerr ; +.fi +.IP +A global variable whose value is set by any RPC client creation routine +that does not succeed. +Use the routine +.BR clnt_pcreateerror () +to print the reason why. +.P +.nf +.BI "void svc_destroy(SVCXPRT *" xprt ); +.fi +.IP +A macro that destroys the RPC service transport handle, +.IR xprt . +Destruction usually involves deallocation +of private data structures, including +.I xprt +itself. +Use of +.I xprt +is undefined after calling this routine. +.P +.nf +.BI "fd_set " svc_fdset ; +.fi +.IP +A global variable reflecting the RPC service side's +read file descriptor bit mask; it is suitable as a parameter to the +.BR select (2) +system call. +This is of interest only if a service implementor does their own +asynchronous event processing, instead of calling +.BR svc_run (). +This variable is read-only (do not pass its address to +.BR select (2)!), +yet it may change after calls to +.BR svc_getreqset () +or any creation routines. +.P +.nf +.BI "int " svc_fds ; +.fi +.IP +Similar to +.BR svc_fdset , +but limited to 32 file descriptors. +This interface is obsoleted by +.BR svc_fdset . +.P +.nf +.BI "svc_freeargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in ); +.fi +.IP +A macro that frees any data allocated by the RPC/XDR +system when it decoded the arguments to a service procedure using +.BR svc_getargs (). +This routine returns 1 if the results were successfully freed, +and zero otherwise. +.P +.nf +.BI "svc_getargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in ); +.fi +.IP +A macro that decodes the arguments of an RPC request +associated with the RPC service transport handle, +.IR xprt . +The parameter +.I in +is the address where the arguments will be placed; +.I inproc +is the XDR routine used to decode the arguments. +This routine returns one if decoding succeeds, and zero otherwise. +.P +.nf +.BI "struct sockaddr_in *svc_getcaller(SVCXPRT *" xprt ); +.fi +.IP +The approved way of getting the network address of the caller +of a procedure associated with the RPC service transport handle, +.IR xprt . +.P +.nf +.BI "void svc_getreqset(fd_set *" rdfds ); +.fi +.IP +This routine is of interest only if a service implementor does not call +.BR svc_run (), +but instead implements custom asynchronous event processing. +It is called when the +.BR select (2) +system call has determined that an RPC request has arrived on some +RPC socket(s); +.I rdfds +is the resultant read file descriptor bit mask. +The routine returns when all sockets associated with the value of +.I rdfds +have been serviced. +.P +.nf +.BI "void svc_getreq(int " rdfds ); +.fi +.IP +Similar to +.BR svc_getreqset (), +but limited to 32 file descriptors. +This interface is obsoleted by +.BR svc_getreqset (). +.P +.nf +.BI "bool_t svc_register(SVCXPRT *" xprt ", unsigned long " prognum , +.BI " unsigned long " versnum , +.BI " void (*" dispatch ")(struct svc_req *, SVCXPRT *)," +.BI " unsigned long " protocol ); +.fi +.IP +Associates +.I prognum +and +.I versnum +with the service dispatch procedure, +.IR dispatch . +If +.I protocol +is zero, the service is not registered with the +.B portmap +service. +If +.I protocol +is nonzero, then a mapping of the triple +.RI [ prognum , versnum , protocol ] +to +.I xprt\->xp_port +is established with the local +.B portmap +service (generally +.I protocol +is zero, +.B IPPROTO_UDP +or +.BR IPPROTO_TCP ). +The procedure +.I dispatch +has the following form: +.IP +.in +4n +.EX +dispatch(struct svc_req *request, SVCXPRT *xprt); +.EE +.in +.IP +The +.BR svc_register () +routine returns one if it succeeds, and zero otherwise. +.P +.nf +.B "void svc_run(void);" +.fi +.IP +This routine never returns. +It waits for RPC requests to arrive, and calls the appropriate service +procedure using +.BR svc_getreq () +when one arrives. +This procedure is usually waiting for a +.BR select (2) +system call to return. +.P +.nf +.BI "bool_t svc_sendreply(SVCXPRT *" xprt ", xdrproc_t " outproc \ +", char *" out ); +.fi +.IP +Called by an RPC service's dispatch routine to send the results of a +remote procedure call. +The parameter +.I xprt +is the request's associated transport handle; +.I outproc +is the XDR routine which is used to encode the results; and +.I out +is the address of the results. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "void svc_unregister(unsigned long " prognum ", unsigned long " versnum ); +.fi +.IP +Remove all mapping of the double +.RI [ prognum , versnum ] +to dispatch routines, and of the triple +.RI [ prognum , versnum , * ] +to port number. +.P +.nf +.BI "void svcerr_auth(SVCXPRT *" xprt ", enum auth_stat " why ); +.fi +.IP +Called by a service dispatch routine that refuses to perform +a remote procedure call due to an authentication error. +.P +.nf +.BI "void svcerr_decode(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine that cannot successfully +decode its parameters. +See also +.BR svc_getargs (). +.P +.nf +.BI "void svcerr_noproc(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine that does not implement +the procedure number that the caller requests. +.P +.nf +.BI "void svcerr_noprog(SVCXPRT *" xprt ); +.fi +.IP +Called when the desired program is not registered with the RPC package. +Service implementors usually do not need this routine. +.P +.nf +.BI "void svcerr_progvers(SVCXPRT *" xprt ", unsigned long " low_vers , +.BI " unsigned long " high_vers ); +.fi +.IP +Called when the desired version of a program is not registered +with the RPC package. +Service implementors usually do not need this routine. +.P +.nf +.BI "void svcerr_systemerr(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine when it detects a system +error not covered by any particular protocol. +For example, if a service can no longer allocate storage, +it may call this routine. +.P +.nf +.BI "void svcerr_weakauth(SVCXPRT *" xprt ); +.fi +.IP +Called by a service dispatch routine that refuses to perform +a remote procedure call due to insufficient authentication parameters. +The routine calls +.BR "svcerr_auth(xprt, AUTH_TOOWEAK)" . +.P +.nf +.BI "SVCXPRT *svcfd_create(int " fd ", unsigned int " sendsize , +.BI " unsigned int " recvsize ); +.fi +.IP +Create a service on top of any open file descriptor. +Typically, this file descriptor is a connected socket for a stream protocol such +as TCP. +.I sendsize +and +.I recvsize +indicate sizes for the send and receive buffers. +If they are zero, a reasonable default is chosen. +.P +.nf +.B SVCXPRT *svcraw_create(void); +.fi +.IP +This routine creates a toy RPC +service transport, to which it returns a pointer. +The transport is really a buffer within the process's address space, +so the corresponding RPC client should live in the same address space; see +.BR clntraw_create (). +This routine allows simulation of RPC and acquisition of RPC +overheads (such as round trip times), without any kernel interference. +This routine returns NULL if it fails. +.P +.nf +.BI "SVCXPRT *svctcp_create(int " sock ", unsigned int " send_buf_size , +.BI " unsigned int " recv_buf_size ); +.fi +.IP +This routine creates a TCP/IP-based RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.IR sock , +which may be +.BR RPC_ANYSOCK , +in which case a new socket is created. +If the socket is not bound to a local TCP +port, then this routine binds it to an arbitrary port. +Upon completion, +.I xprt\->xp_sock +is the transport's socket descriptor, and +.I xprt\->xp_port +is the transport's port number. +This routine returns NULL if it fails. +Since TCP-based RPC uses buffered I/O, +users may specify the size of buffers; values of zero +choose suitable defaults. +.P +.nf +.BI "SVCXPRT *svcudp_bufcreate(int " sock ", unsigned int " sendsize , +.BI " unsigned int " recosize ); +.fi +.IP +This routine creates a UDP/IP-based RPC +service transport, to which it returns a pointer. +The transport is associated with the socket +.IR sock , +which may be +.BR RPC_ANYSOCK , +in which case a new socket is created. +If the socket is not bound to a local UDP +port, then this routine binds it to an arbitrary port. +Upon completion, +.I xprt\->xp_sock +is the transport's socket descriptor, and +.I xprt\->xp_port +is the transport's port number. +This routine returns NULL if it fails. +.IP +This allows the user to specify the maximum packet size for sending and +receiving UDP-based RPC messages. +.P +.nf +.BI "SVCXPRT *svcudp_create(int " sock ); +.fi +.IP +This call is equivalent to +.I svcudp_bufcreate(sock,SZ,SZ) +for some default size +.IR SZ . +.P +.nf +.BI "bool_t xdr_accepted_reply(XDR *" xdrs ", struct accepted_reply *" ar ); +.fi +.IP +Used for encoding RPC reply messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.P +.nf +.BI "bool_t xdr_authunix_parms(XDR *" xdrs ", struct authunix_parms *" aupp ); +.fi +.IP +Used for describing UNIX credentials. +This routine is useful for users +who wish to generate these credentials without using the RPC +authentication package. +.P +.nf +.BI "void xdr_callhdr(XDR *" xdrs ", struct rpc_msg *" chdr ); +.fi +.IP +Used for describing RPC call header messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.P +.nf +.BI "bool_t xdr_callmsg(XDR *" xdrs ", struct rpc_msg *" cmsg ); +.fi +.IP +Used for describing RPC call messages. +This routine is useful for users who wish to generate RPC-style +messages without using the RPC package. +.P +.nf +.BI "bool_t xdr_opaque_auth(XDR *" xdrs ", struct opaque_auth *" ap ); +.fi +.IP +Used for describing RPC authentication information messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.P +.nf +.BI "bool_t xdr_pmap(XDR *" xdrs ", struct pmap *" regs ); +.fi +.IP +Used for describing parameters to various +.B portmap +procedures, externally. +This routine is useful for users who wish to generate +these parameters without using the +.B pmap +interface. +.P +.nf +.BI "bool_t xdr_pmaplist(XDR *" xdrs ", struct pmaplist **" rp ); +.fi +.IP +Used for describing a list of port mappings, externally. +This routine is useful for users who wish to generate +these parameters without using the +.B pmap +interface. +.P +.nf +.BI "bool_t xdr_rejected_reply(XDR *" xdrs ", struct rejected_reply *" rr ); +.fi +.IP +Used for describing RPC reply messages. +This routine is useful for users who wish to generate +RPC-style messages without using the RPC package. +.P +.nf +.BI "bool_t xdr_replymsg(XDR *" xdrs ", struct rpc_msg *" rmsg ); +.fi +.IP +Used for describing RPC reply messages. +This routine is useful for users who wish to generate +RPC style messages without using the RPC package. +.P +.nf +.BI "void xprt_register(SVCXPRT *" xprt ); +.fi +.IP +After RPC service transport handles are created, +they should register themselves with the RPC service package. +This routine modifies the global variable +.IR svc_fds . +Service implementors usually do not need this routine. +.P +.nf +.BI "void xprt_unregister(SVCXPRT *" xprt ); +.fi +.IP +Before an RPC service transport handle is destroyed, +it should unregister itself with the RPC service package. +This routine modifies the global variable +.IR svc_fds . +Service implementors usually do not need this routine. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR auth_destroy (), +.BR authnone_create (), +.BR authunix_create (), +.BR authunix_create_default (), +.BR callrpc (), +.BR clnt_broadcast (), +.BR clnt_call (), +.BR clnt_destroy (), +.BR clnt_create (), +.BR clnt_control (), +.BR clnt_freeres (), +.BR clnt_geterr (), +.BR clnt_pcreateerror (), +.BR clnt_perrno (), +.BR clnt_perror (), +.BR clnt_spcreateerror (), +.BR clnt_sperrno (), +.BR clnt_sperror (), +.BR clntraw_create (), +.BR clnttcp_create (), +.BR clntudp_create (), +.BR clntudp_bufcreate (), +.BR get_myaddress (), +.BR pmap_getmaps (), +.BR pmap_getport (), +.BR pmap_rmtcall (), +.BR pmap_set (), +.BR pmap_unset (), +.BR registerrpc (), +.BR svc_destroy (), +.BR svc_freeargs (), +.BR svc_getargs (), +.BR svc_getcaller (), +.BR svc_getreqset (), +.BR svc_getreq (), +.BR svc_register (), +.BR svc_run (), +.BR svc_sendreply (), +.BR svc_unregister (), +.BR svcerr_auth (), +.BR svcerr_decode (), +.BR svcerr_noproc (), +.BR svcerr_noprog (), +.BR svcerr_progvers (), +.BR svcerr_systemerr (), +.BR svcerr_weakauth (), +.BR svcfd_create (), +.BR svcraw_create (), +.BR svctcp_create (), +.BR svcudp_bufcreate (), +.BR svcudp_create (), +.BR xdr_accepted_reply (), +.BR xdr_authunix_parms (), +.BR xdr_callhdr (), +.BR xdr_callmsg (), +.BR xdr_opaque_auth (), +.BR xdr_pmap (), +.BR xdr_pmaplist (), +.BR xdr_rejected_reply (), +.BR xdr_replymsg (), +.BR xprt_register (), +.BR xprt_unregister () +T} Thread safety MT-Safe +.TE +.SH SEE ALSO +.\" We don't have an rpc_secure.3 page in the set at the moment -- MTK, 19 Sep 05 +.\" .BR rpc_secure (3), +.BR xdr (3) +.P +The following manuals: +.RS +Remote Procedure Calls: Protocol Specification +.br +Remote Procedure Call Programming Guide +.br +rpcgen Programming Guide +.br +.RE +.P +.IR "RPC: Remote Procedure Call Protocol Specification" , +RFC\ 1050, Sun Microsystems, Inc., +USC-ISI. diff --git a/man/man3/rpmatch.3 b/man/man3/rpmatch.3 new file mode 100644 index 0000000..5739b82 --- /dev/null +++ b/man/man3/rpmatch.3 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright (C) 2006 Justin Pryzby +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" %%%LICENSE_END +.\" +.\" References: +.\" glibc manual and source +.\" +.\" 2006-05-19, mtk, various edits and example program +.\" +.TH rpmatch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rpmatch \- determine if the answer to a question is affirmative or negative +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int rpmatch(const char *" response ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR rpmatch (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +.BR rpmatch () +handles a user response to yes or no questions, with +support for internationalization. +.P +.I response +should be a null-terminated string containing a +user-supplied response, perhaps obtained with +.BR fgets (3) +or +.BR getline (3). +.P +The user's language preference is taken into account per the +environment variables +.BR LANG , +.BR LC_MESSAGES , +and +.BR LC_ALL , +if the program has called +.BR setlocale (3) +to effect their changes. +.P +Regardless of the locale, responses matching +.B \[ha][Yy] +are always accepted as affirmative, and those matching +.B \[ha][Nn] +are always accepted as negative. +.SH RETURN VALUE +After examining +.IR response , +.BR rpmatch () +returns 0 for a recognized negative response ("no"), 1 +for a recognized positive response ("yes"), and \-1 when the value +of +.I response +is unrecognized. +.SH ERRORS +A return value of \-1 may indicate either an invalid input, or some +other error. +It is incorrect to only test if the return value is nonzero. +.P +.BR rpmatch () +can fail for any of the reasons that +.BR regcomp (3) +or +.BR regexec (3) +can fail; the cause of the error +is not available from +.I errno +or anywhere else, but indicates a +failure of the regex engine (but this case is indistinguishable from +that of an unrecognized value of +.IR response ). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rpmatch () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +None. +.SH HISTORY +GNU, FreeBSD, AIX. +.SH BUGS +The +.BR YESEXPR " and " NOEXPR +of some locales (including "C") only inspect the first character of the +.IR response . +This can mean that "yno" et al. resolve to +.BR 1 . +This is an unfortunate historical side-effect which should be fixed in time +with proper localisation, and should not deter from +.BR rpmatch () +being the proper way to distinguish between binary answers. +.SH EXAMPLES +The following program displays the results when +.BR rpmatch () +is applied to the string given in the program's command-line argument. +.P +.\" SRC BEGIN (rpmatch.c) +.EX +#define _DEFAULT_SOURCE +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + if (argc != 2 || strcmp(argv[1], "\-\-help") == 0) { + fprintf(stderr, "%s response\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + setlocale(LC_ALL, ""); + printf("rpmatch() returns: %d\en", rpmatch(argv[1])); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fgets (3), +.BR getline (3), +.BR nl_langinfo (3), +.BR regcomp (3), +.BR setlocale (3) diff --git a/man/man3/rresvport.3 b/man/man3/rresvport.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/rresvport.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/rresvport_af.3 b/man/man3/rresvport_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/rresvport_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/rtime.3 b/man/man3/rtime.3 new file mode 100644 index 0000000..f116831 --- /dev/null +++ b/man/man3/rtime.3 @@ -0,0 +1,152 @@ +'\" t +.\" Copyright 2003 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Modified 2003-04-04 Walter Harms +.\" +.\" +.\" Slightly polished, aeb, 2003-04-06 +.\" +.TH rtime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rtime \- get time from a remote machine +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int rtime(struct sockaddr_in *" addrp ", struct rpc_timeval *" timep , +.BI " struct rpc_timeval *" timeout ); +.fi +.SH DESCRIPTION +This function uses the Time Server Protocol as described in +RFC\ 868 to obtain the time from a remote machine. +.P +The Time Server Protocol gives the time in seconds since +00:00:00 UTC, 1 Jan 1900, +and this function subtracts the appropriate constant in order to +convert the result to seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.P +When +.I timeout +is non-NULL, the udp/time socket (port 37) is used. +Otherwise, the tcp/time socket (port 37) is used. +.SH RETURN VALUE +On success, 0 is returned, and the obtained 32-bit time value is stored in +.IR timep\->tv_sec . +In case of error \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +All errors for underlying functions +.RB ( sendto (2), +.BR poll (2), +.BR recvfrom (2), +.BR connect (2), +.BR read (2)) +can occur. +Moreover: +.TP +.B EIO +The number of returned bytes is not 4. +.TP +.B ETIMEDOUT +The waiting time as defined in timeout has expired. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR rtime () +T} Thread safety MT-Safe +.TE +.SH NOTES +Only IPv4 is supported. +.P +Some +.I in.timed +versions support only TCP. +Try the example program with +.I use_tcp +set to 1. +.\" .P +.\" Libc5 uses the prototype +.\" .P +.\" .nf +.\" int rtime(struct sockaddr_in *, struct timeval *, struct timeval *); +.\" .fi +.\" .P +.\" and requires +.\" .I +.\" instead of +.\" .IR . +.SH BUGS +.BR rtime () +in glibc 2.2.5 and earlier does not work properly on 64-bit machines. +.SH EXAMPLES +This example requires that port 37 is up and open. +You may check +that the time entry within +.I /etc/inetd.conf +is not commented out. +.P +The program connects to a computer called "linux". +Using "localhost" does not work. +The result is the localtime of the computer "linux". +.P +.\" SRC BEGIN (rtime.c) +.EX +#include +#include +#include +#include +#include +#include +\& +#include +\& +static int use_tcp = 0; +static const char servername[] = "linux"; +\& +int +main(void) +{ + int ret; + time_t t; + struct hostent *hent; + struct rpc_timeval time1 = {0, 0}; + struct rpc_timeval timeout = {1, 0}; + struct sockaddr_in name; +\& + memset(&name, 0, sizeof(name)); + sethostent(1); + hent = gethostbyname(servername); + memcpy(&name.sin_addr, hent\->h_addr, hent\->h_length); +\& + ret = rtime(&name, &time1, use_tcp ? NULL : &timeout); + if (ret < 0) + perror("rtime error"); + else { + t = time1.tv_sec; + printf("%s\en", ctime(&t)); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.\" .BR netdate (1), +.BR ntpdate (1), +.\" .BR rdate (1), +.BR inetd (8) diff --git a/man/man3/rtnetlink.3 b/man/man3/rtnetlink.3 new file mode 100644 index 0000000..7eaef31 --- /dev/null +++ b/man/man3/rtnetlink.3 @@ -0,0 +1,122 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" $Id: rtnetlink.3,v 1.2 1999/05/18 10:35:10 freitag Exp $ +.\" +.TH rtnetlink 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rtnetlink \- macros to manipulate rtnetlink messages +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.P +.BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type \ +", NETLINK_ROUTE);" +.P +.BI "int RTA_OK(struct rtattr *" rta ", int " rtabuflen ); +.P +.BI "void *RTA_DATA(struct rtattr *" rta ); +.BI "unsigned int RTA_PAYLOAD(struct rtattr *" rta ); +.P +.BI "struct rtattr *RTA_NEXT(struct rtattr *" rta \ +", unsigned int " rtabuflen ); +.P +.BI "unsigned int RTA_LENGTH(unsigned int " length ); +.BI "unsigned int RTA_SPACE(unsigned int "length ); +.fi +.SH DESCRIPTION +All +.BR rtnetlink (7) +messages consist of a +.BR netlink (7) +message header and appended attributes. +The attributes should be manipulated only using the macros provided here. +.P +.BI RTA_OK( rta ", " attrlen ) +returns true if +.I rta +points to a valid routing attribute; +.I attrlen +is the running length of the attribute buffer. +When not true then you must assume there are no more attributes in the +message, even if +.I attrlen +is nonzero. +.P +.BI RTA_DATA( rta ) +returns a pointer to the start of this attribute's data. +.P +.BI RTA_PAYLOAD( rta ) +returns the length of this attribute's data. +.P +.BI RTA_NEXT( rta ", " attrlen ) +gets the next attribute after +.IR rta . +Calling this macro will update +.IR attrlen . +You should use +.B RTA_OK +to check the validity of the returned pointer. +.P +.BI RTA_LENGTH( len ) +returns the length which is required for +.I len +bytes of data plus the header. +.P +.BI RTA_SPACE( len ) +returns the amount of space which will be needed in a message with +.I len +bytes of data. +.SH STANDARDS +Linux. +.SH BUGS +This manual page is incomplete. +.SH EXAMPLES +.\" FIXME . ? would be better to use libnetlink in the EXAMPLE code here +Creating a rtnetlink message to set the MTU of a device: +.P +.in +4n +.EX +#include +\& +\&... +\& +struct { + struct nlmsghdr nh; + struct ifinfomsg if; + char attrbuf[512]; +} req; +\& +struct rtattr *rta; +unsigned int mtu = 1000; +\& +int rtnetlink_sk = socket(AF_NETLINK, SOCK_DGRAM, NETLINK_ROUTE); +\& +memset(&req, 0, sizeof(req)); +req.nh.nlmsg_len = NLMSG_LENGTH(sizeof(req.if)); +req.nh.nlmsg_flags = NLM_F_REQUEST; +req.nh.nlmsg_type = RTM_NEWLINK; +req.if.ifi_family = AF_UNSPEC; +req.if.ifi_index = INTERFACE_INDEX; +req.if.ifi_change = 0xffffffff; /* ??? */ +rta = (struct rtattr *)(((char *) &req) + + NLMSG_ALIGN(req.nh.nlmsg_len)); +rta\->rta_type = IFLA_MTU; +rta\->rta_len = RTA_LENGTH(sizeof(mtu)); +req.nh.nlmsg_len = NLMSG_ALIGN(req.nh.nlmsg_len) + + RTA_LENGTH(sizeof(mtu)); +memcpy(RTA_DATA(rta), &mtu, sizeof(mtu)); +send(rtnetlink_sk, &req, req.nh.nlmsg_len, 0); +.EE +.in +.SH SEE ALSO +.BR netlink (3), +.BR netlink (7), +.BR rtnetlink (7) diff --git a/man/man3/ruserok.3 b/man/man3/ruserok.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/ruserok.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/ruserok_af.3 b/man/man3/ruserok_af.3 new file mode 100644 index 0000000..b58efef --- /dev/null +++ b/man/man3/ruserok_af.3 @@ -0,0 +1 @@ +.so man3/rcmd.3 diff --git a/man/man3/scalb.3 b/man/man3/scalb.3 new file mode 100644 index 0000000..754530c --- /dev/null +++ b/man/man3/scalb.3 @@ -0,0 +1,196 @@ +'\" t +.\" Copyright 2004 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH scalb 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +scalb, scalbf, scalbl \- multiply floating-point number +by integral power of radix (OBSOLETE) +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] double scalb(double " x ", double " exp ); +.BI "[[deprecated]] float scalbf(float " x ", float " exp ); +.BI "[[deprecated]] long double scalbl(long double " x ", long double " exp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR scalb (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR scalbf (), +.BR scalbl (): +.nf + _XOPEN_SOURCE >= 600 + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions multiply their first argument +.I x +by +.B FLT_RADIX +(probably 2) +to the power of +.IR exp , +that is: +.P +.nf + x * FLT_RADIX ** exp +.fi +.P +The definition of +.B FLT_RADIX +can be obtained by including +.IR . +.\" not in /usr/include but in a gcc lib +.SH RETURN VALUE +On success, these functions return +.I x +* +.B FLT_RADIX +** +.IR exp . +.P +If +.I x +or +.I exp +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity (negative infinity), +and +.I exp +is not negative infinity, +positive infinity (negative infinity) is returned. +.P +If +.I x +is +0 (\-0), and +.I exp +is not positive infinity, +0 (\-0) is returned. +.P +If +.I x +is zero, and +.I exp +is positive infinity, +a domain error occurs, and +a NaN is returned. +.P +If +.I x +is an infinity, +and +.I exp +is negative infinity, +a domain error occurs, and +a NaN is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with a sign the same as +.IR x . +.P +If the result underflows, +a range error occurs, +and the functions return zero, with a sign the same as +.IR x . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is 0, and \fIexp\fP is positive infinity, \ +or \fIx\fP is positive infinity and \fIexp\fP is negative infinity \ +and the other argument is not a NaN +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Range error, overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR scalb (), +.BR scalbf (), +.BR scalbl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR scalb () +4.3BSD. +Obsolescent in POSIX.1-2001; +Removed in POSIX.1-2008, +recommending the use of +.BR scalbln (3), +.BR scalblnf (3), +or +.BR scalblnl (3) +instead. +.\" Looking at header files: scalbf() is present on the +.\" BSDs, Tru64, HP-UX 11, Irix 6.5; scalbl() is on HP-UX 11 and Tru64. +.SH BUGS +Before glibc 2.20, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6803 +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6804 +these functions did not set +.I errno +for domain and range errors. +.SH SEE ALSO +.BR ldexp (3), +.BR scalbln (3) diff --git a/man/man3/scalbf.3 b/man/man3/scalbf.3 new file mode 100644 index 0000000..5a33fb8 --- /dev/null +++ b/man/man3/scalbf.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man/man3/scalbl.3 b/man/man3/scalbl.3 new file mode 100644 index 0000000..5a33fb8 --- /dev/null +++ b/man/man3/scalbl.3 @@ -0,0 +1 @@ +.so man3/scalb.3 diff --git a/man/man3/scalbln.3 b/man/man3/scalbln.3 new file mode 100644 index 0000000..a7b8f9f --- /dev/null +++ b/man/man3/scalbln.3 @@ -0,0 +1,174 @@ +'\" t +.\" Copyright 2004 Andries Brouwer . +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH scalbln 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl \- +multiply floating-point number by integral power of radix +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double scalbln(double " x ", long " exp ); +.BI "float scalblnf(float " x ", long " exp ); +.BI "long double scalblnl(long double " x ", long " exp ); +.P +.BI "double scalbn(double " x ", int " exp ); +.BI "float scalbnf(float " x ", int " exp ); +.BI "long double scalbnl(long double " x ", int " exp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR scalbln (), +.BR scalblnf (), +.BR scalblnl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE +.fi +.P +.BR scalbn (), +.BR scalbnf (), +.BR scalbnl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions multiply their first argument +.I x +by +.B FLT_RADIX +(probably 2) +to the power of +.IR exp , +that is: +.P +.nf + x * FLT_RADIX ** exp +.fi +.P +The definition of +.B FLT_RADIX +can be obtained by including +.IR . +.\" not in /usr/include but in a gcc lib +.SH RETURN VALUE +On success, these functions return +.I x +* +.B FLT_RADIX +** +.IR exp . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with a sign the same as +.IR x . +.P +If the result underflows, +a range error occurs, +and the functions return zero, with a sign the same as +.IR x . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error, overflow +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.TP +Range error, underflow +.I errno +is set to +.BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR scalbn (), +.BR scalbnf (), +.BR scalbnl (), +.BR scalbln (), +.BR scalblnf (), +.BR scalblnl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH HISTORY +These functions differ from the obsolete functions described in +.BR scalb (3) +in the type of their second argument. +The functions described on this page have a second argument +of an integral type, while those in +.BR scalb (3) +have a second argument of type +.IR double . +.SH NOTES +If +.B FLT_RADIX +equals 2 (which is usual), then +.BR scalbn () +is equivalent to +.BR ldexp (3). +.SH BUGS +Before glibc 2.20, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6803 +these functions did not set +.I errno +for range errors. +.SH SEE ALSO +.BR ldexp (3), +.BR scalb (3) diff --git a/man/man3/scalblnf.3 b/man/man3/scalblnf.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man/man3/scalblnf.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man/man3/scalblnl.3 b/man/man3/scalblnl.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man/man3/scalblnl.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man/man3/scalbn.3 b/man/man3/scalbn.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man/man3/scalbn.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man/man3/scalbnf.3 b/man/man3/scalbnf.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man/man3/scalbnf.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man/man3/scalbnl.3 b/man/man3/scalbnl.3 new file mode 100644 index 0000000..58d82f2 --- /dev/null +++ b/man/man3/scalbnl.3 @@ -0,0 +1 @@ +.so man3/scalbln.3 diff --git a/man/man3/scandir.3 b/man/man3/scandir.3 new file mode 100644 index 0000000..dff2c6b --- /dev/null +++ b/man/man3/scandir.3 @@ -0,0 +1,310 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:26:16 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Thu Apr 11 17:11:33 1996 by Andries Brouwer (aeb@cwi.nl): +.\" Corrected type of compar routines, as suggested by +.\" Miguel Barreiro (enano@avalon.yaix.es). Added example. +.\" Modified Sun Sep 24 20:15:46 2000 by aeb, following Petter Reinholdtsen. +.\" Modified 2001-12-26 by aeb, following Joey. Added versionsort. +.\" +.\" The pieces on scandirat(3) were copyright and licensed as follows. +.\" +.\" Copyright (c) 2012, Mark R. Bannister +.\" based on text in mkfifoat.3 Copyright (c) 2006, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH scandir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +scandir, scandirat, alphasort, versionsort \- scan +a directory for matching entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int scandir(const char *restrict " dirp , +.BI " struct dirent ***restrict " namelist , +.BI " int (*" filter ")(const struct dirent *)," +.BI " int (*" compar ")(const struct dirent **," +.B " const struct dirent **));" +.P +.BI "int alphasort(const struct dirent **" a ", const struct dirent **" b ); +.BI "int versionsort(const struct dirent **" a ", const struct dirent **" b ); +.P +.BR "#include " " /* Definition of AT_* constants */" +.B #include +.P +.BI "int scandirat(int " dirfd ", const char *restrict " dirp , +.BI " struct dirent ***restrict " namelist , +.BI " int (*" filter ")(const struct dirent *)," +.BI " int (*" compar ")(const struct dirent **," +.B " const struct dirent **));" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR scandir (), +.BR alphasort (): +.nf + /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR versionsort (): +.nf + _GNU_SOURCE +.fi +.P +.BR scandirat (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR scandir () +function scans the directory \fIdirp\fP, calling +\fIfilter\fP() on each directory entry. +Entries for which +\fIfilter\fP() returns nonzero are stored in strings allocated via +.BR malloc (3), +sorted using +.BR qsort (3) +with the comparison +function \fIcompar\fP(), and collected in array \fInamelist\fP +which is allocated via +.BR malloc (3). +If \fIfilter\fP is NULL, all entries are selected. +.P +The +.BR alphasort () +and +.BR versionsort () +functions can be used as the comparison function +.IR compar (). +The former sorts directory entries using +.BR strcoll (3), +the latter using +.BR strverscmp (3) +on the strings \fI(*a)\->d_name\fP and \fI(*b)\->d_name\fP. +.SS scandirat() +The +.BR scandirat () +function operates in exactly the same way as +.BR scandir (), +except for the differences described here. +.P +If the pathname given in +.I dirp +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR scandir () +for a relative pathname). +.P +If +.I dirp +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I dirp +is interpreted relative to the current working +directory of the calling process (like +.BR scandir ()). +.P +If +.I dirp +is absolute, then +.I dirfd +is ignored. +.P +See +.BR openat (2) +for an explanation of the need for +.BR scandirat (). +.SH RETURN VALUE +The +.BR scandir () +function returns the number of directory entries +selected. +On error, \-1 is returned, with +.I errno +set to indicate the error. +.P +The +.BR alphasort () +and +.BR versionsort () +functions return an integer less than, equal to, +or greater than zero if the first argument is considered to be +respectively less than, equal to, or greater than the second. +.SH ERRORS +.TP +.B EBADF +.RB ( scandirat ()) +.I dirp +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B ENOENT +The path in \fIdirp\fR does not exist. +.TP +.B ENOMEM +Insufficient memory to complete the operation. +.TP +.B ENOTDIR +The path in \fIdirp\fR is not a directory. +.TP +.B ENOTDIR +.RB ( scandirat ()) +.I dirp +is a relative pathname and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR scandir (), +.BR scandirat () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR alphasort (), +.BR versionsort () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +.TP +.BR alphasort () +.TQ +.BR scandir () +POSIX.1-2008. +.TP +.BR versionsort () +.TQ +.BR scandirat () +GNU. +.SH HISTORY +.TP +.BR alphasort () +.TQ +.BR scandir () +4.3BSD, POSIX.1-2008. +.TP +.BR versionsort () +glibc 2.1. +.TP +.BR scandirat () +glibc 2.15. +.\" .P +.\" The functions +.\" .BR scandir () +.\" and +.\" .BR alphasort () +.\" are from 4.3BSD, and have been available under Linux since libc4. +.\" Libc4 and libc5 use the more precise prototype +.\" .sp +.\" .nf +.\" int alphasort(const struct dirent ** a, +.\" const struct dirent **b); +.\" .fi +.\" .sp +.\" but glibc 2.0 returns to the imprecise BSD prototype. +.SH NOTES +Since glibc 2.1, +.BR alphasort () +calls +.BR strcoll (3); +earlier it used +.BR strcmp (3). +.P +Before glibc 2.10, the two arguments of +.BR alphasort () +and +.BR versionsort () +were typed as +.IR "const void\ *" . +When +.BR alphasort () +was standardized in POSIX.1-2008, +the argument type was specified as the type-safe +.IR "const struct dirent\ **", +and glibc 2.10 changed the definition of +.BR alphasort () +(and the nonstandard +.BR versionsort ()) +to match the standard. +.SH EXAMPLES +The program below prints a list of the files in the current directory +in reverse order. +.\" +.SS Program source +\& +.\" SRC BEGIN (scandir.c) +.EX +#define _DEFAULT_SOURCE +#include +#include +#include +\& +int +main(void) +{ + struct dirent **namelist; + int n; +\& + n = scandir(".", &namelist, NULL, alphasort); + if (n == \-1) { + perror("scandir"); + exit(EXIT_FAILURE); + } +\& + while (n\-\-) { + printf("%s\en", namelist[n]\->d_name); + free(namelist[n]); + } + free(namelist); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR closedir (3), +.BR fnmatch (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR seekdir (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strverscmp (3), +.BR telldir (3) diff --git a/man/man3/scandirat.3 b/man/man3/scandirat.3 new file mode 100644 index 0000000..7e757c7 --- /dev/null +++ b/man/man3/scandirat.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man/man3/scanf.3 b/man/man3/scanf.3 new file mode 100644 index 0000000..3855e77 --- /dev/null +++ b/man/man3/scanf.3 @@ -0,0 +1,159 @@ +'\" t +.\" Copyright 2022 Alejandro Colomar +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH scanf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +scanf, fscanf, vscanf, vfscanf \- input FILE format conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int scanf(const char *restrict " format ", ...);" +.BI "int fscanf(FILE *restrict " stream , +.BI " const char *restrict " format ", ...);" +.P +.B #include +.P +.BI "int vscanf(const char *restrict " format ", va_list " ap ); +.BI "int vfscanf(FILE *restrict " stream , +.BI " const char *restrict " format ", va_list " ap ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR vscanf (), +.BR vfscanf (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR scanf () +family of functions scans formatted input like +.BR sscanf (3), +but read from a +.IR FILE . +It is very difficult to use these functions correctly, +and it is preferable to read entire lines with +.BR fgets (3) +or +.BR getline (3) +and parse them later with +.BR sscanf (3) +or more specialized functions such as +.BR strtol (3). +.P +The +.BR scanf () +function reads input from the standard input stream +.I stdin +and +.BR fscanf () +reads input from the stream pointer +.IR stream . +.P +The +.BR vfscanf () +function is analogous to +.BR vfprintf (3) +and reads input from the stream pointer +.I stream +using a variable argument list of pointers (see +.BR stdarg (3). +The +.BR vscanf () +function is analogous to +.BR vprintf (3) +and reads from the standard input. +.SH RETURN VALUE +On success, these functions return the number of input items +successfully matched and assigned; +this can be fewer than provided for, +or even zero, in the event of an early matching failure. +.P +The value +.B EOF +is returned if the end of input is reached before either the first +successful conversion or a matching failure occurs. +.B EOF +is also returned if a read error occurs, +in which case the error indicator for the stream (see +.BR ferror (3)) +is set, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The file descriptor underlying +.I stream +is marked nonblocking, and the read operation would block. +.TP +.B EBADF +The file descriptor underlying +.I stream +is invalid, or not open for reading. +.TP +.B EILSEQ +Input byte sequence does not form a valid character. +.TP +.B EINTR +The read operation was interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +Not enough arguments; or +.I format +is NULL. +.TP +.B ENOMEM +Out of memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR scanf (), +.BR fscanf (), +.BR vscanf (), +.BR vfscanf () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH CAVEATS +These functions make it difficult to +distinguish newlines from other white space, +This is especially problematic with line-buffered input, +like the standard input stream. +.P +These functions can't report errors after the last +non-suppressed conversion specification. +.SH BUGS +It is impossible to accurately know +how many characters these functions have consumed from the input stream, +since they only report the number of successful conversions. +For example, +if the input is "123\en\ a", +.I scanf(\[dq]%d\ %d\[dq], &a, &b) +will consume the digits, the newline, and the space, but not the letter a. +This makes it difficult to recover from invalid input. +.SH SEE ALSO +.BR fgets (3), +.BR getline (3), +.BR sscanf (3) diff --git a/man/man3/sched_getcpu.3 b/man/man3/sched_getcpu.3 new file mode 100644 index 0000000..a1c6c67 --- /dev/null +++ b/man/man3/sched_getcpu.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sched_getcpu 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sched_getcpu \- determine CPU on which the calling thread is running +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B int sched_getcpu(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sched_getcpu (): +.nf + Since glibc 2.14: + _GNU_SOURCE + Before glibc 2.14: + _BSD_SOURCE || _SVID_SOURCE + /* _GNU_SOURCE also suffices */ +.fi +.SH DESCRIPTION +.BR sched_getcpu () +returns the number of the CPU +on which the calling thread is currently executing. +.SH RETURN VALUE +On success, +.BR sched_getcpu () +returns a nonnegative CPU number. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B ENOSYS +This kernel does not implement +.BR getcpu (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sched_getcpu () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.6. +.SH NOTES +The call +.P +.in +4n +.EX +cpu = sched_getcpu(); +.EE +.in +.P +is equivalent to the following +.BR getcpu (2) +call: +.P +.in +4n +.EX +int c, s; +s = getcpu(&c, NULL); +cpu = (s == \-1) ? s : c; +.EE +.in +.SH SEE ALSO +.BR getcpu (2), +.BR sched (7) diff --git a/man/man3/secure_getenv.3 b/man/man3/secure_getenv.3 new file mode 100644 index 0000000..5142bef --- /dev/null +++ b/man/man3/secure_getenv.3 @@ -0,0 +1 @@ +.so man3/getenv.3 diff --git a/man/man3/seed48.3 b/man/man3/seed48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/seed48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/seed48_r.3 b/man/man3/seed48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/seed48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/seekdir.3 b/man/man3/seekdir.3 new file mode 100644 index 0000000..a053f5b --- /dev/null +++ b/man/man3/seekdir.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:25:21 1993 by Rik Faith (faith@cs.unc.edu) +.\" +.TH seekdir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +seekdir \- set the position of the next readdir() call in the directory +stream. +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void seekdir(DIR *" dirp ", long " loc ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR seekdir (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR seekdir () +function sets the location in the directory stream +from which the next +.BR readdir (2) +call will start. +The +.I loc +argument should be a value returned by a previous call to +.BR telldir (3). +.SH RETURN VALUE +The +.BR seekdir () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR seekdir () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.SH CAVEATS +Up to glibc 2.1.1, the type of the +.I loc +argument was +.IR off_t . +POSIX.1-2001 specifies +.IR long , +and this is the type used since glibc 2.1.2. +See +.BR telldir (3) +for information on why you should be careful in making any +assumptions about the value in this argument. +.SH SEE ALSO +.BR lseek (2), +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR telldir (3) diff --git a/man/man3/sem_close.3 b/man/man3/sem_close.3 new file mode 100644 index 0000000..46331ac --- /dev/null +++ b/man/man3/sem_close.3 @@ -0,0 +1,63 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_close 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_close \- close a named semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sem_close(sem_t *" sem ); +.fi +.SH DESCRIPTION +.BR sem_close () +closes the named semaphore referred to by +.IR sem , +allowing any resources that the system has allocated to +the calling process for this semaphore to be freed. +.SH RETURN VALUE +On success +.BR sem_close () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_close () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +All open named semaphores are automatically closed on process +termination, or upon +.BR execve (2). +.SH SEE ALSO +.BR sem_getvalue (3), +.BR sem_open (3), +.BR sem_post (3), +.BR sem_unlink (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_destroy.3 b/man/man3/sem_destroy.3 new file mode 100644 index 0000000..6675537 --- /dev/null +++ b/man/man3/sem_destroy.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_destroy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_destroy \- destroy an unnamed semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sem_destroy(sem_t *" sem ); +.fi +.SH DESCRIPTION +.BR sem_destroy () +destroys the unnamed semaphore at the address pointed to by +.IR sem . +.P +Only a semaphore that has been initialized by +.BR sem_init (3) +should be destroyed using +.BR sem_destroy (). +.P +Destroying a semaphore that other processes or threads are +currently blocked on (in +.BR sem_wait (3)) +produces undefined behavior. +.P +Using a semaphore that has been destroyed produces undefined results, +until the semaphore has been reinitialized using +.BR sem_init (3). +.SH RETURN VALUE +.BR sem_destroy () +returns 0 on success; +on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_destroy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +An unnamed semaphore should be destroyed with +.BR sem_destroy () +before the memory in which it is located is deallocated. +Failure to do this can result in resource leaks on some implementations. +.\" But not on NPTL, where sem_destroy () is a no-op.. +.SH SEE ALSO +.BR sem_init (3), +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_getvalue.3 b/man/man3/sem_getvalue.3 new file mode 100644 index 0000000..bfadd47 --- /dev/null +++ b/man/man3/sem_getvalue.3 @@ -0,0 +1,74 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_getvalue 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_getvalue \- get the value of a semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sem_getvalue(sem_t *restrict " sem ", int *restrict " sval ); +.fi +.SH DESCRIPTION +.BR sem_getvalue () +places the current value of the semaphore pointed to +.I sem +into the integer pointed to by +.IR sval . +.P +If one or more processes or threads are blocked +waiting to lock the semaphore with +.BR sem_wait (3), +POSIX.1 permits two possibilities for the value returned in +.IR sval : +either 0 is returned; +or a negative number whose absolute value is the count +of the number of processes and threads currently blocked in +.BR sem_wait (3). +Linux adopts the former behavior. +.SH RETURN VALUE +.BR sem_getvalue () +returns 0 on success; +on error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +(The glibc implementation currently does not check whether +.I sem +is valid.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_getvalue () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The value of the semaphore may already have changed by the time +.BR sem_getvalue () +returns. +.SH SEE ALSO +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_init.3 b/man/man3/sem_init.3 new file mode 100644 index 0000000..8ea6b64 --- /dev/null +++ b/man/man3/sem_init.3 @@ -0,0 +1,108 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_init 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_init \- initialize an unnamed semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sem_init(sem_t *" sem ", int " pshared ", unsigned int " value ); +.fi +.SH DESCRIPTION +.BR sem_init () +initializes the unnamed semaphore at the address pointed to by +.IR sem . +The +.I value +argument specifies the initial value for the semaphore. +.P +The +.I pshared +argument indicates whether this semaphore is to be shared +between the threads of a process, or between processes. +.P +If +.I pshared +has the value 0, +then the semaphore is shared between the threads of a process, +and should be located at some address that is visible to all threads +(e.g., a global variable, or a variable allocated dynamically on +the heap). +.P +If +.I pshared +is nonzero, then the semaphore is shared between processes, +and should be located in a region of shared memory (see +.BR shm_open (3), +.BR mmap (2), +and +.BR shmget (2)). +(Since a child created by +.BR fork (2) +inherits its parent's memory mappings, it can also access the semaphore.) +Any process that can access the shared memory region +can operate on the semaphore using +.BR sem_post (3), +.BR sem_wait (3), +and so on. +.P +Initializing a semaphore that has already been initialized +results in undefined behavior. +.SH RETURN VALUE +.BR sem_init () +returns 0 on success; +on error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I value +exceeds +.BR SEM_VALUE_MAX . +.TP +.B ENOSYS +.I pshared +is nonzero, +but the system does not support process-shared semaphores (see +.BR sem_overview (7)). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_init () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Bizarrely, POSIX.1-2001 does not specify the value that should +be returned by a successful call to +.BR sem_init (). +POSIX.1-2008 rectifies this, specifying the zero return on success. +.SH EXAMPLES +See +.BR shm_open (3) +and +.BR sem_wait (3). +.SH SEE ALSO +.BR sem_destroy (3), +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_open.3 b/man/man3/sem_open.3 new file mode 100644 index 0000000..0f29dcf --- /dev/null +++ b/man/man3/sem_open.3 @@ -0,0 +1,175 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_open 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_open \- initialize and open a named semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.BR "#include " " /* For O_* constants */" +.BR "#include " " /* For mode constants */" +.B #include +.P +.BI "sem_t *sem_open(const char *" name ", int " oflag ); +.BI "sem_t *sem_open(const char *" name ", int " oflag , +.BI " mode_t " mode ", unsigned int " value ); +.fi +.SH DESCRIPTION +.BR sem_open () +creates a new POSIX semaphore or opens an existing semaphore. +The semaphore is identified by +.IR name . +For details of the construction of +.IR name , +see +.BR sem_overview (7). +.P +The +.I oflag +argument specifies flags that control the operation of the call. +(Definitions of the flags values can be obtained by including +.IR .) +If +.B O_CREAT +is specified in +.IR oflag , +then the semaphore is created if +it does not already exist. +The owner (user ID) of the semaphore is set to the effective +user ID of the calling process. +The group ownership (group ID) is set to the effective group ID +of the calling process. +.\" In reality the filesystem IDs are used on Linux. +If both +.B O_CREAT +and +.B O_EXCL +are specified in +.IR oflag , +then an error is returned if a semaphore with the given +.I name +already exists. +.P +If +.B O_CREAT +is specified in +.IR oflag , +then two additional arguments must be supplied. +The +.I mode +argument specifies the permissions to be placed on the new semaphore, +as for +.BR open (2). +(Symbolic definitions for the permissions bits can be obtained by including +.IR .) +The permissions settings are masked against the process umask. +Both read and write permission should be granted to each class of +user that will access the semaphore. +The +.I value +argument specifies the initial value for the new semaphore. +If +.B O_CREAT +is specified, and a semaphore with the given +.I name +already exists, then +.I mode +and +.I value +are ignored. +.SH RETURN VALUE +On success, +.BR sem_open () +returns the address of the new semaphore; +this address is used when calling other semaphore-related functions. +On error, +.BR sem_open () +returns +.BR SEM_FAILED , +with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The semaphore exists, but the caller does not have permission to +open it. +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified in +.IR oflag , +but a semaphore with this +.I name +already exists. +.TP +.B EINVAL +.I value +was greater than +.BR SEM_VALUE_MAX . +.TP +.B EINVAL +.I name +consists of just "/", followed by no other characters. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +The +.B O_CREAT +flag was not specified in +.I oflag +and no semaphore with this +.I name +exists; +or, +.\" this error can occur if we have a name of the (nonportable) form +.\" /dir/name, and the directory /dev/shm/dir does not exist. +.B O_CREAT +was specified, but +.I name +wasn't well formed. +.TP +.B ENOMEM +Insufficient memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_open () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR sem_close (3), +.BR sem_getvalue (3), +.BR sem_post (3), +.BR sem_unlink (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_post.3 b/man/man3/sem_post.3 new file mode 100644 index 0000000..eb23ef5 --- /dev/null +++ b/man/man3/sem_post.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_post 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_post \- unlock a semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sem_post(sem_t *" sem ); +.fi +.SH DESCRIPTION +.BR sem_post () +increments (unlocks) the semaphore pointed to by +.IR sem . +If the semaphore's value consequently becomes greater than zero, +then another process or thread blocked in a +.BR sem_wait (3) +call will be woken up and proceed to lock the semaphore. +.SH RETURN VALUE +.BR sem_post () +returns 0 on success; +on error, the value of the semaphore is left unchanged, +\-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.TP +.B EOVERFLOW +.\" Added in POSIX.1-2008 TC1 (Austin Interpretation 213) +The maximum allowable value for a semaphore would be exceeded. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_post () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +.BR sem_post () +is async-signal-safe: +it may be safely called within a signal handler. +.SH EXAMPLES +See +.BR sem_wait (3) +and +.BR shm_open (3). +.SH SEE ALSO +.BR sem_getvalue (3), +.BR sem_wait (3), +.BR sem_overview (7), +.BR signal\-safety (7) diff --git a/man/man3/sem_timedwait.3 b/man/man3/sem_timedwait.3 new file mode 100644 index 0000000..c7b43fa --- /dev/null +++ b/man/man3/sem_timedwait.3 @@ -0,0 +1 @@ +.so man3/sem_wait.3 diff --git a/man/man3/sem_trywait.3 b/man/man3/sem_trywait.3 new file mode 100644 index 0000000..c7b43fa --- /dev/null +++ b/man/man3/sem_trywait.3 @@ -0,0 +1 @@ +.so man3/sem_wait.3 diff --git a/man/man3/sem_unlink.3 b/man/man3/sem_unlink.3 new file mode 100644 index 0000000..c061332 --- /dev/null +++ b/man/man3/sem_unlink.3 @@ -0,0 +1,66 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_unlink 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_unlink \- remove a named semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sem_unlink(const char *" name ); +.fi +.SH DESCRIPTION +.BR sem_unlink () +removes the named semaphore referred to by +.IR name . +The semaphore name is removed immediately. +The semaphore is destroyed once all other processes that have +the semaphore open close it. +.SH RETURN VALUE +On success +.BR sem_unlink () +returns 0; on error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The caller does not have permission to unlink this semaphore. +.TP +.B ENAMETOOLONG +.I name +was too long. +.TP +.B ENOENT +There is no semaphore with the given +.IR name . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_unlink () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR sem_getvalue (3), +.BR sem_open (3), +.BR sem_post (3), +.BR sem_wait (3), +.BR sem_overview (7) diff --git a/man/man3/sem_wait.3 b/man/man3/sem_wait.3 new file mode 100644 index 0000000..f09f697 --- /dev/null +++ b/man/man3/sem_wait.3 @@ -0,0 +1,251 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_wait 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_wait, sem_timedwait, sem_trywait \- lock a semaphore +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sem_wait(sem_t *" sem ); +.BI "int sem_trywait(sem_t *" sem ); +.BI "int sem_timedwait(sem_t *restrict " sem , +.BI " const struct timespec *restrict " abs_timeout ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sem_timedwait (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR sem_wait () +decrements (locks) the semaphore pointed to by +.IR sem . +If the semaphore's value is greater than zero, +then the decrement proceeds, and the function returns, immediately. +If the semaphore currently has the value zero, +then the call blocks until either it becomes possible to perform +the decrement (i.e., the semaphore value rises above zero), +or a signal handler interrupts the call. +.P +.BR sem_trywait () +is the same as +.BR sem_wait (), +except that if the decrement cannot be immediately performed, +then call returns an error +.RI ( errno +set to +.BR EAGAIN ) +instead of blocking. +.P +.BR sem_timedwait () +is the same as +.BR sem_wait (), +except that +.I abs_timeout +specifies a limit on the amount of time that the call +should block if the decrement cannot be immediately performed. +The +.I abs_timeout +argument points to a +.BR timespec (3) +structure that specifies an absolute timeout +in seconds and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.P +If the timeout has already expired by the time of the call, +and the semaphore could not be locked immediately, +then +.BR sem_timedwait () +fails with a timeout error +.RI ( errno +set to +.BR ETIMEDOUT ). +.P +If the operation can be performed immediately, then +.BR sem_timedwait () +never fails with a timeout error, regardless of the value of +.IR abs_timeout . +Furthermore, the validity of +.I abs_timeout +is not checked in this case. +.SH RETURN VALUE +All of these functions return 0 on success; +on error, the value of the semaphore is left unchanged, +\-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +.RB ( sem_trywait ()) +The operation could not be performed without blocking (i.e., the +semaphore currently has the value zero). +.TP +.B EINTR +The call was interrupted by a signal handler; see +.BR signal (7). +.TP +.B EINVAL +.I sem +is not a valid semaphore. +.TP +.B EINVAL +.RB ( sem_timedwait ()) +The value of +.I abs_timeout.tv_nsecs +is less than 0, or greater than or equal to 1000 million. +.TP +.B ETIMEDOUT +.RB ( sem_timedwait ()) +The call timed out before the semaphore could be locked. +.\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition +.\" was detected", but this does not occur on Linux(?). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sem_wait (), +.BR sem_trywait (), +.BR sem_timedwait () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The (somewhat trivial) program shown below operates on an +unnamed semaphore. +The program expects two command-line arguments. +The first argument specifies a seconds value that is used to +set an alarm timer to generate a +.B SIGALRM +signal. +This handler performs a +.BR sem_post (3) +to increment the semaphore that is being waited on in +.I main() +using +.BR sem_timedwait (). +The second command-line argument specifies the length +of the timeout, in seconds, for +.BR sem_timedwait (). +The following shows what happens on two different runs of the program: +.P +.in +4n +.EX +.RB "$" " ./a.out 2 3" +About to call sem_timedwait() +sem_post() from handler +sem_timedwait() succeeded +.RB "$" " ./a.out 2 1" +About to call sem_timedwait() +sem_timedwait() timed out +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (sem_wait.c) +.EX +#include +#include +#include +#include +#include +#include +#include +\& +#include +\& +sem_t sem; +\& +#define handle_error(msg) \e + do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +static void +handler(int sig) +{ + write(STDOUT_FILENO, "sem_post() from handler\en", 24); + if (sem_post(&sem) == \-1) { + write(STDERR_FILENO, "sem_post() failed\en", 18); + _exit(EXIT_FAILURE); + } +} +\& +int +main(int argc, char *argv[]) +{ + struct sigaction sa; + struct timespec ts; + int s; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + if (sem_init(&sem, 0, 0) == \-1) + handle_error("sem_init"); +\& + /* Establish SIGALRM handler; set alarm timer using argv[1]. */ +\& + sa.sa_handler = handler; + sigemptyset(&sa.sa_mask); + sa.sa_flags = 0; + if (sigaction(SIGALRM, &sa, NULL) == \-1) + handle_error("sigaction"); +\& + alarm(atoi(argv[1])); +\& + /* Calculate relative interval as current time plus + number of seconds given argv[2]. */ +\& + if (clock_gettime(CLOCK_REALTIME, &ts) == \-1) + handle_error("clock_gettime"); +\& + ts.tv_sec += atoi(argv[2]); +\& + printf("%s() about to call sem_timedwait()\en", __func__); + while ((s = sem_timedwait(&sem, &ts)) == \-1 && errno == EINTR) + continue; /* Restart if interrupted by handler. */ +\& + /* Check what happened. */ +\& + if (s == \-1) { + if (errno == ETIMEDOUT) + printf("sem_timedwait() timed out\en"); + else + perror("sem_timedwait"); + } else + printf("sem_timedwait() succeeded\en"); +\& + exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR clock_gettime (2), +.BR sem_getvalue (3), +.BR sem_post (3), +.BR timespec (3), +.BR sem_overview (7), +.BR time (7) diff --git a/man/man3/setaliasent.3 b/man/man3/setaliasent.3 new file mode 100644 index 0000000..c82b647 --- /dev/null +++ b/man/man3/setaliasent.3 @@ -0,0 +1,184 @@ +'\" t +.\" Copyright 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Polished a bit, added a little, aeb +.\" +.TH setaliasent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setaliasent, endaliasent, getaliasent, getaliasent_r, +getaliasbyname, getaliasbyname_r \- read an alias entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B "void setaliasent(void);" +.B "void endaliasent(void);" +.P +.B "struct aliasent *getaliasent(void);" +.BI "int getaliasent_r(struct aliasent *restrict " result , +.BI " char " buffer "[restrict ." buflen "], \ +size_t " buflen , +.BI " struct aliasent **restrict " res ); +.P +.BI "struct aliasent *getaliasbyname(const char *" name ); +.BI "int getaliasbyname_r(const char *restrict " name , +.BI " struct aliasent *restrict " result , +.BI " char " buffer "[restrict ." buflen "], \ +size_t " buflen , +.BI " struct aliasent **restrict " res ); +.fi +.SH DESCRIPTION +One of the databases available with the Name Service Switch (NSS) +is the aliases database, that contains mail aliases. +(To find out which databases are supported, try +.IR "getent \-\-help" .) +Six functions are provided to access the aliases database. +.P +The +.BR getaliasent () +function returns a pointer to a structure containing +the group information from the aliases database. +The first time it is called it returns the first entry; +thereafter, it returns successive entries. +.P +The +.BR setaliasent () +function rewinds the file pointer to the beginning of the +aliases database. +.P +The +.BR endaliasent () +function closes the aliases database. +.P +.BR getaliasent_r () +is the reentrant version of the previous function. +The requested structure +is stored via the first argument but the programmer needs to fill the other +arguments also. +Not providing enough space causes the function to fail. +.P +The function +.BR getaliasbyname () +takes the name argument and searches the aliases database. +The entry is returned as a pointer to a +.IR "struct aliasent" . +.P +.BR getaliasbyname_r () +is the reentrant version of the previous function. +The requested structure +is stored via the second argument but the programmer needs to fill the other +arguments also. +Not providing enough space causes the function to fail. +.P +The +.I "struct aliasent" +is defined in +.IR : +.P +.in +4n +.EX +struct aliasent { + char *alias_name; /* alias name */ + size_t alias_members_len; + char **alias_members; /* alias name list */ + int alias_local; +}; +.EE +.in +.SH RETURN VALUE +The functions +.BR getaliasent_r () +and +.BR getaliasbyname_r () +return a nonzero value on error. +.SH FILES +The default alias database is the file +.IR /etc/aliases . +This can be changed in the +.I /etc/nsswitch.conf +file. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setaliasent (), +.BR endaliasent (), +.BR getaliasent_r (), +.BR getaliasbyname_r () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR getaliasent (), +.BR getaliasbyname () +T} Thread safety MT-Unsafe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +The NeXT system has similar routines: +.P +.in +4n +.EX +#include +\& +void alias_setent(void); +void alias_endent(void); +alias_ent *alias_getent(void); +alias_ent *alias_getbyname(char *name); +.EE +.in +.SH EXAMPLES +The following example compiles with +.IR "gcc example.c \-o example" . +It will dump all names in the alias database. +.P +.\" SRC BEGIN (setaliasent.c) +.EX +#include +#include +#include +#include +\& +int +main(void) +{ + struct aliasent *al; +\& + setaliasent(); + for (;;) { + al = getaliasent(); + if (al == NULL) + break; + printf("Name: %s\en", al\->alias_name); + } + if (errno) { + perror("reading alias"); + exit(EXIT_FAILURE); + } + endaliasent(); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getgrent (3), +.BR getpwent (3), +.BR getspent (3), +.BR aliases (5) +.\" +.\" /etc/sendmail/aliases +.\" Yellow Pages +.\" newaliases, postalias diff --git a/man/man3/setbuf.3 b/man/man3/setbuf.3 new file mode 100644 index 0000000..38400e4 --- /dev/null +++ b/man/man3/setbuf.3 @@ -0,0 +1,227 @@ +'\" t +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)setbuf.3 6.10 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 14:55:24 1993, faith@cs.unc.edu +.\" Added section to BUGS, Sun Mar 12 22:28:33 MET 1995, +.\" Thomas.Koenig@ciw.uni-karlsruhe.de +.\" Correction, Sun, 11 Apr 1999 15:55:18, +.\" Martin Vicente +.\" Correction, 2000-03-03, Andreas Jaeger +.\" Added return value for setvbuf, aeb, +.\" +.TH setbuf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int setvbuf(FILE *restrict " stream ", char " buf "[restrict ." size ], +.BI " int " mode ", size_t " size ); +.P +.BI "void setbuf(FILE *restrict " stream ", char *restrict " buf ); +.BI "void setbuffer(FILE *restrict " stream ", char " buf "[restrict ." size ], +.BI " size_t " size ); +.BI "void setlinebuf(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setbuffer (), +.BR setlinebuf (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The three types of buffering available are unbuffered, block buffered, and +line buffered. +When an output stream is unbuffered, information appears on +the destination file or terminal as soon as written; when it is block +buffered, many characters are saved up and written as a block; when it is +line buffered, characters are saved up until a newline is output or input is +read from any stream attached to a terminal device (typically \fIstdin\fP). +The function +.BR fflush (3) +may be used to force the block out early. +(See +.BR fclose (3).) +.P +Normally all files are block buffered. +If a stream refers to a terminal (as +.I stdout +normally does), it is line buffered. +The standard error stream +.I stderr +is always unbuffered by default. +.P +The +.BR setvbuf () +function may be used on any open stream to change its buffer. +The +.I mode +argument must be one of the following three macros: +.RS +.TP +.B _IONBF +unbuffered +.TP +.B _IOLBF +line buffered +.TP +.B _IOFBF +fully buffered +.RE +.P +Except for unbuffered files, the +.I buf +argument should point to a buffer at least +.I size +bytes long; this buffer will be used instead of the current buffer. +If the argument +.I buf +is NULL, +only the mode is affected; a new buffer will be allocated on the next read +or write operation. +The +.BR setvbuf () +function may be used only after opening a stream and before any other +operations have been performed on it. +.P +The other three calls are, in effect, simply aliases for calls to +.BR setvbuf (). +The +.BR setbuf () +function is exactly equivalent to the call +.P +.in +4n +setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); +.in +.P +The +.BR setbuffer () +function is the same, except that the size of the buffer is up to the +caller, rather than being determined by the default +.BR BUFSIZ . +The +.BR setlinebuf () +function is exactly equivalent to the call: +.P +.in +4n +setvbuf(stream, NULL, _IOLBF, 0); +.in +.SH RETURN VALUE +The function +.BR setvbuf () +returns 0 on success. +It returns nonzero on failure +.RI ( mode +is invalid or the request cannot be honored). +It may set +.I errno +on failure. +.P +The other functions do not return a value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setbuf (), +.BR setbuffer (), +.BR setlinebuf (), +.BR setvbuf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR setbuf () +.TQ +.BR setvbuf () +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR setbuf () +.TQ +.BR setvbuf () +C89, POSIX.1-2001. +.SH CAVEATS +POSIX notes +.\" https://www.austingroupbugs.net/view.php?id=397#c799 +.\" 0000397: setbuf and errno +that the value of +.I errno +is unspecified after a call to +.BR setbuf () +and further notes that, since the value of +.I errno +is not required to be unchanged after a successful call to +.BR setbuf (), +applications should instead use +.BR setvbuf () +in order to detect errors. +.SH BUGS +.\" The +.\" .BR setbuffer () +.\" and +.\" .BR setlinebuf () +.\" functions are not portable to versions of BSD before 4.2BSD, and +.\" are available under Linux since libc 4.5.21. +.\" On 4.2BSD and 4.3BSD systems, +.\" .BR setbuf () +.\" always uses a suboptimal buffer size and should be avoided. +.\".P +You must make sure that the space that +.I buf +points to still exists by the time +.I stream +is closed, which also happens at program termination. +For example, the following is invalid: +.P +.\" SRC BEGIN (setbuf.c) +.EX +#include +\& +int +main(void) +{ + char buf[BUFSIZ]; +\& + setbuf(stdout, buf); + printf("Hello, world!\en"); + return 0; +} +.EE +.\" SRC END +.SH SEE ALSO +.BR stdbuf (1), +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR fread (3), +.BR malloc (3), +.BR printf (3), +.BR puts (3) diff --git a/man/man3/setbuffer.3 b/man/man3/setbuffer.3 new file mode 100644 index 0000000..dc02d9e --- /dev/null +++ b/man/man3/setbuffer.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man/man3/setcontext.3 b/man/man3/setcontext.3 new file mode 100644 index 0000000..b01818d --- /dev/null +++ b/man/man3/setcontext.3 @@ -0,0 +1 @@ +.so man3/getcontext.3 diff --git a/man/man3/setenv.3 b/man/man3/setenv.3 new file mode 100644 index 0000000..d6f9683 --- /dev/null +++ b/man/man3/setenv.3 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2004, 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:20:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 9 Jun 2004, Michael Kerrisk +.\" Changed unsetenv() prototype; added EINVAL error +.\" Noted nonstandard behavior of setenv() if name contains '=' +.\" 2005-08-12, mtk, glibc 2.3.4 fixed the "name contains '='" bug +.\" +.TH setenv 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setenv \- change or add an environment variable +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int setenv(const char *" name ", const char *" value ", int " overwrite ); +.BI "int unsetenv(const char *" name ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setenv (), +.BR unsetenv (): +.nf + _POSIX_C_SOURCE >= 200112L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR setenv () +function adds the variable +.I name +to the +environment with the value +.IR value , +if +.I name +does not +already exist. +If +.I name +does exist in the environment, then +its value is changed to +.I value +if +.I overwrite +is nonzero; +if +.I overwrite +is zero, then the value of +.I name +is not changed (and +.BR setenv () +returns a success status). +This function makes copies of the strings pointed to by +.I name +and +.I value +(by contrast with +.BR putenv (3)). +.P +The +.BR unsetenv () +function deletes the variable +.I name +from +the environment. +If +.I name +does not exist in the environment, +then the function succeeds, and the environment is unchanged. +.SH RETURN VALUE +.BR setenv () +and +.BR unsetenv () +functions return zero on success, +or \-1 on error, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I name +is NULL, points to a string of length 0, +or contains an \[aq]=\[aq] character. +.TP +.B ENOMEM +Insufficient memory to add a new variable to the environment. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setenv (), +.BR unsetenv () +T} Thread safety MT-Unsafe const:env +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.P +Prior to glibc 2.2.2, +.BR unsetenv () +was prototyped +as returning +.IR void ; +more recent glibc versions follow the +POSIX.1-compliant prototype shown in the SYNOPSIS. +.SH CAVEATS +POSIX.1 does not require +.BR setenv () +or +.BR unsetenv () +to be reentrant. +.SH BUGS +POSIX.1 specifies that if +.I name +contains an \[aq]=\[aq] character, then +.BR setenv () +should fail with the error +.BR EINVAL ; +however, versions of glibc before glibc 2.3.4 allowed an \[aq]=\[aq] sign in +.IR name . +.SH SEE ALSO +.BR clearenv (3), +.BR getenv (3), +.BR putenv (3), +.BR environ (7) diff --git a/man/man3/setfsent.3 b/man/man3/setfsent.3 new file mode 100644 index 0000000..1e6a3eb --- /dev/null +++ b/man/man3/setfsent.3 @@ -0,0 +1 @@ +.so man3/getfsent.3 diff --git a/man/man3/setgrent.3 b/man/man3/setgrent.3 new file mode 100644 index 0000000..bde736f --- /dev/null +++ b/man/man3/setgrent.3 @@ -0,0 +1 @@ +.so man3/getgrent.3 diff --git a/man/man3/sethostent.3 b/man/man3/sethostent.3 new file mode 100644 index 0000000..7d0fb4b --- /dev/null +++ b/man/man3/sethostent.3 @@ -0,0 +1 @@ +.so man3/gethostbyname.3 diff --git a/man/man3/sethostid.3 b/man/man3/sethostid.3 new file mode 100644 index 0000000..3210db0 --- /dev/null +++ b/man/man3/sethostid.3 @@ -0,0 +1 @@ +.so man3/gethostid.3 diff --git a/man/man3/setjmp.3 b/man/man3/setjmp.3 new file mode 100644 index 0000000..b42e0d2 --- /dev/null +++ b/man/man3/setjmp.3 @@ -0,0 +1,332 @@ +'\" t +.\" Copyright (C) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH setjmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setjmp, sigsetjmp, longjmp, siglongjmp \- performing a nonlocal goto +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int setjmp(jmp_buf " env ); +.BI "int sigsetjmp(sigjmp_buf " env ", int " savesigs ); +.P +.BI "[[noreturn]] void longjmp(jmp_buf " env ", int " val ); +.BI "[[noreturn]] void siglongjmp(sigjmp_buf " env ", int " val ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setjmp (): +see NOTES. +.P +.BR sigsetjmp (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The functions described on this page are used for performing "nonlocal gotos": +transferring execution from one function to a predetermined location +in another function. +The +.BR setjmp () +function dynamically establishes the target to which control +will later be transferred, and +.BR longjmp () +performs the transfer of execution. +.P +The +.BR setjmp () +function saves various information about the calling environment +(typically, the stack pointer, the instruction pointer, +possibly the values of other registers and the signal mask) +in the buffer +.I env +for later use by +.BR longjmp (). +In this case, +.BR setjmp () +returns 0. +.P +The +.BR longjmp () +function uses the information saved in +.I env +to transfer control back to the point where +.BR setjmp () +was called and to restore ("rewind") the stack to its state at the time of the +.BR setjmp () +call. +In addition, and depending on the implementation (see NOTES), +the values of some other registers and the process signal mask +may be restored to their state at the time of the +.BR setjmp () +call. +.P +Following a successful +.BR longjmp (), +execution continues as if +.BR setjmp () +had returned for a second time. +This "fake" return can be distinguished from a true +.BR setjmp () +call because the "fake" return returns the value provided in +.IR val . +If the programmer mistakenly passes the value 0 in +.IR val , +the "fake" return will instead return 1. +.SS sigsetjmp() and siglongjmp() +.BR sigsetjmp () +and +.BR siglongjmp () +also perform nonlocal gotos, but provide predictable handling of +the process signal mask. +.P +If, and only if, the +.I savesigs +argument provided to +.BR sigsetjmp () +is nonzero, the process's current signal mask is saved in +.I env +and will be restored if a +.BR siglongjmp () +is later performed with this +.IR env . +.SH RETURN VALUE +.BR setjmp () +and +.BR sigsetjmp () +return 0 when called directly; +on the "fake" return that occurs after +.BR longjmp () +or +.BR siglongjmp (), +the nonzero value specified in +.I val +is returned. +.P +The +.BR longjmp () +or +.BR siglongjmp () +functions do not return. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setjmp (), +.BR sigsetjmp () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR longjmp (), +.BR siglongjmp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR setjmp () +.TQ +.BR longjmp () +C11, POSIX.1-2008. +.TP +.BR sigsetjmp () +.TQ +.BR siglongjmp () +POSIX.1-2008. +.SH HISTORY +.TP +.BR setjmp () +.TQ +.BR longjmp () +POSIX.1-2001, C89. +.TP +.BR sigsetjmp () +.TQ +.BR siglongjmp () +POSIX.1-2001. +.P +POSIX does not specify whether +.BR setjmp () +will save the signal mask +(to be later restored during +.BR longjmp ()). +In System V it will not. +In 4.3BSD it will, and there +is a function +.BR _setjmp () +that will not. +The behavior under Linux depends on the glibc version +and the setting of feature test macros. +Before glibc 2.19, +.BR setjmp () +follows the System V behavior by default, +but the BSD behavior is provided if the +.B _BSD_SOURCE +feature test macro is explicitly defined +.\" so that _FAVOR_BSD is triggered +and none of +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.\" .BR _XOPEN_SOURCE_EXTENDED , +.BR _GNU_SOURCE , +or +.B _SVID_SOURCE +is defined. +Since glibc 2.19, +.I +exposes only the System V version of +.BR setjmp (). +Programs that need the BSD semantics should replace calls to +.BR setjmp () +with calls to +.BR sigsetjmp () +with a nonzero +.I savesigs +argument. +.SH NOTES +.BR setjmp () +and +.BR longjmp () +can be useful for dealing with errors inside deeply nested function calls +or to allow a signal handler to pass control to +a specific point in the program, +rather than returning to the point where the handler interrupted +the main program. +In the latter case, +if you want to portably save and restore signal masks, use +.BR sigsetjmp () +and +.BR siglongjmp (). +See also the discussion of program readability below. +.SH CAVEATS +The compiler may optimize variables into registers, and +.BR longjmp () +may restore the values of other registers in addition to the +stack pointer and program counter. +Consequently, the values of automatic variables are unspecified +after a call to +.BR longjmp () +if they meet all the following criteria: +.IP \[bu] 3 +they are local to the function that made the corresponding +.BR setjmp () +call; +.IP \[bu] +their values are changed between the calls to +.BR setjmp () +and +.BR longjmp (); +and +.IP \[bu] +they are not declared as +.IR volatile . +.P +Analogous remarks apply for +.BR siglongjmp (). +.\" +.SS Nonlocal gotos and program readability +While it can be abused, +the traditional C "goto" statement at least has the benefit that lexical cues +(the goto statement and the target label) +allow the programmer to easily perceive the flow of control. +Nonlocal gotos provide no such cues: multiple +.BR setjmp () +calls might employ the same +.I jmp_buf +variable so that the content of the variable may change +over the lifetime of the application. +Consequently, the programmer may be forced to perform detailed +reading of the code to determine the dynamic target of a particular +.BR longjmp () +call. +(To make the programmer's life easier, each +.BR setjmp () +call should employ a unique +.I jmp_buf +variable.) +.P +Adding further difficulty, the +.BR setjmp () +and +.BR longjmp () +calls may not even be in the same source code module. +.P +In summary, nonlocal gotos can make programs harder to understand +and maintain, and an alternative should be used if possible. +.\" +.SS Undefined Behavior +If the function which called +.BR setjmp () +returns before +.BR longjmp () +is called, the behavior is undefined. +Some kind of subtle or unsubtle chaos is sure to result. +.P +If, in a multithreaded program, a +.BR longjmp () +call employs an +.I env +buffer that was initialized by a call to +.BR setjmp () +in a different thread, the behavior is undefined. +.\" +.\" The following statement appeared in versions up to POSIX.1-2008 TC1, +.\" but is set to be removed in POSIX.1-2008 TC2: +.\" +.\" According to POSIX.1, if a +.\" .BR longjmp () +.\" call is performed from a nested signal handler +.\" (i.e., from a handler that was invoked in response to a signal that was +.\" generated while another signal was already in the process of being +.\" handled), the behavior is undefined. +.P +POSIX.1-2008 Technical Corrigendum 2 adds +.\" http://austingroupbugs.net/view.php?id=516#c1195 +.BR longjmp () +and +.BR siglongjmp () +to the list of async-signal-safe functions. +However, the standard recommends avoiding the use of these functions +from signal handlers and goes on to point out that +if these functions are called from a signal handler that interrupted +a call to a non-async-signal-safe function (or some equivalent, +such as the steps equivalent to +.BR exit (3) +that occur upon a return from the initial call to +.IR main ()), +the behavior is undefined if the program subsequently makes a call to +a non-async-signal-safe function. +The only way of avoiding undefined behavior is to ensure one of the following: +.IP \[bu] 3 +After long jumping from the signal handler, +the program does not call any non-async-signal-safe functions +and does not return from the initial call to +.IR main (). +.IP \[bu] +Any signal whose handler performs a long jump must be blocked during +.I every +call to a non-async-signal-safe function and +no non-async-signal-safe functions are called after +returning from the initial call to +.IR main (). +.SH SEE ALSO +.BR signal (7), +.BR signal\-safety (7) diff --git a/man/man3/setkey.3 b/man/man3/setkey.3 new file mode 100644 index 0000000..e34c9e9 --- /dev/null +++ b/man/man3/setkey.3 @@ -0,0 +1 @@ +.so man3/encrypt.3 diff --git a/man/man3/setkey_r.3 b/man/man3/setkey_r.3 new file mode 100644 index 0000000..e34c9e9 --- /dev/null +++ b/man/man3/setkey_r.3 @@ -0,0 +1 @@ +.so man3/encrypt.3 diff --git a/man/man3/setlinebuf.3 b/man/man3/setlinebuf.3 new file mode 100644 index 0000000..dc02d9e --- /dev/null +++ b/man/man3/setlinebuf.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man/man3/setlocale.3 b/man/man3/setlocale.3 new file mode 100644 index 0000000..fe01130 --- /dev/null +++ b/man/man3/setlocale.3 @@ -0,0 +1,248 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 1999 by Bruno Haible (haible@clisp.cons.org) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 18:20:12 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Jul 15 16:49:10 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun Jul 4 14:52:16 1999 by Bruno Haible (haible@clisp.cons.org) +.\" Modified Tue Aug 24 17:11:01 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Tue Feb 6 03:31:55 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH setlocale 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setlocale \- set the current locale +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *setlocale(int " category ", const char *" locale ); +.fi +.SH DESCRIPTION +The +.BR setlocale () +function is used to set or query the program's current locale. +.P +If +.I locale +is not NULL, +the program's current locale is modified according to the arguments. +The argument +.I category +determines which parts of the program's current locale should be modified. +.TS +lB lB +lB lx. +Category Governs +LC_ALL All of the locale +LC_ADDRESS T{ +Formatting of addresses and +geography-related items (*) +T} +LC_COLLATE String collation +LC_CTYPE Character classification +LC_IDENTIFICATION T{ +Metadata describing the locale (*) +T} +LC_MEASUREMENT T{ +Settings related to measurements +(metric versus US customary) (*) +T} +LC_MESSAGES T{ +Localizable natural-language messages +T} +LC_MONETARY T{ +Formatting of monetary values +T} +LC_NAME T{ +Formatting of salutations for persons (*) +T} +LC_NUMERIC T{ +Formatting of nonmonetary numeric values +T} +LC_PAPER T{ +Settings related to the standard paper size (*) +T} +LC_TELEPHONE T{ +Formats to be used with telephone services (*) +T} +LC_TIME T{ +Formatting of date and time values +T} +.TE +.P +The categories marked with an asterisk in the above table +are GNU extensions. +For further information on these locale categories, see +.BR locale (7). +.P +The argument +.I locale +is a pointer to a character string containing the +required setting of +.IR category . +Such a string is either a well-known constant like "C" or "da_DK" +(see below), or an opaque string that was returned by another call of +.BR setlocale (). +.P +If +.I locale +is an empty string, +.BR \[dq]\[dq] , +each part of the locale that should be modified is set according to the +environment variables. +The details are implementation-dependent. +For glibc, first (regardless of +.IR category ), +the environment variable +.B LC_ALL +is inspected, +next the environment variable with the same name as the category +(see the table above), +and finally the environment variable +.BR LANG . +The first existing environment variable is used. +If its value is not a valid locale specification, the locale +is unchanged, and +.BR setlocale () +returns NULL. +.P +The locale +.B \[dq]C\[dq] +or +.B \[dq]POSIX\[dq] +is a portable locale; +it exists on all conforming systems. +.P +A locale name is typically of the form +.IR language "[_" territory "][." codeset "][@" modifier "]," +where +.I language +is an ISO\~639 language code, +.I territory +is an ISO\~3166 country code, and +.I codeset +is a character set or encoding identifier like +.B "ISO\-8859\-1" +or +.BR "UTF\-8" . +For a list of all supported locales, try "locale \-a" (see +.BR locale (1)). +.P +If +.I locale +is NULL, the current locale is only queried, not modified. +.P +On startup of the main program, the portable +.B \[dq]C\[dq] +locale is selected as default. +A program may be made portable to all locales by calling: +.P +.in +4n +.EX +setlocale(LC_ALL, ""); +.EE +.in +.P +after program initialization, and then: +.IP \[bu] 3 +using the values returned from a +.BR localeconv (3) +call for locale-dependent information; +.IP \[bu] +using the multibyte and wide character functions for text processing if +.BR "MB_CUR_MAX > 1" ; +.IP \[bu] +using +.BR strcoll (3) +and +.BR strxfrm (3) +to compare strings; and +.IP \[bu] +using +.BR wcscoll (3) +and +.BR wcsxfrm (3) +to compare wide-character strings. +.SH RETURN VALUE +A successful call to +.BR setlocale () +returns an opaque string that corresponds to the locale set. +This string may be allocated in static storage. +The string returned is such that a subsequent call with that string +and its associated category will restore that part of the process's +locale. +The return value is NULL if the request cannot be honored. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setlocale () +T} Thread safety MT-Unsafe const:locale env +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SS Categories +.TP +.B LC_ALL +.TQ +.B LC_COLLATE +.TQ +.B LC_CTYPE +.TQ +.B LC_MONETARY +.TQ +.B LC_NUMERIC +.TQ +.B LC_TIME +C11, POSIX.1-2008. +.TP +.B LC_MESSAGES +POSIX.1-2008. +.TP +Others: +GNU. +.SH HISTORY +POSIX.1-2001, C89. +.SS Categories +.TP +.B LC_ALL +.TQ +.B LC_COLLATE +.TQ +.B LC_CTYPE +.TQ +.B LC_MONETARY +.TQ +.B LC_NUMERIC +.TQ +.B LC_TIME +C89, POSIX.1-2001. +.TP +.B LC_MESSAGES +POSIX.1-2001. +.TP +Others: +GNU. +.SH SEE ALSO +.BR locale (1), +.BR localedef (1), +.BR isalpha (3), +.BR localeconv (3), +.BR nl_langinfo (3), +.BR rpmatch (3), +.BR strcoll (3), +.BR strftime (3), +.BR charsets (7), +.BR locale (7) diff --git a/man/man3/setlogmask.3 b/man/man3/setlogmask.3 new file mode 100644 index 0000000..c4a5ddb --- /dev/null +++ b/man/man3/setlogmask.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH setlogmask 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setlogmask \- set log priority mask +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int setlogmask(int " mask ); +.fi +.SH DESCRIPTION +A process has a log priority mask that determines which calls to +.BR syslog (3) +may be logged. +All other calls will be ignored. +Logging is enabled for the priorities that have the corresponding +bit set in +.IR mask . +The initial mask is such that logging is enabled for all priorities. +.P +The +.BR setlogmask () +function sets this logmask for the calling process, +and returns the previous mask. +If the +.I mask +argument is +.BR 0 , +the current logmask is not modified. +.P +The eight priorities are +.BR LOG_EMERG , +.BR LOG_ALERT , +.BR LOG_CRIT , +.BR LOG_ERR , +.BR LOG_WARNING , +.BR LOG_NOTICE , +.BR LOG_INFO , +and +.BR LOG_DEBUG . +The bit corresponding to a priority +.I p +is +.IR LOG_MASK(p) . +Some systems also provide a macro +.I LOG_UPTO(p) +for the mask +of all priorities in the above list up to and including +.IR p . +.SH RETURN VALUE +This function returns the previous log priority mask. +.SH ERRORS +None. +.\" .SH NOTES +.\" The glibc logmask handling was broken before glibc 2.1.1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setlogmask () +T} Thread safety MT-Unsafe race:LogMask +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.\" Note that the description in POSIX.1-2001 is flawed. +.P +.BR LOG_UPTO () +will be included in the next release of the POSIX specification (Issue 8). +.\" FIXME . https://www.austingroupbugs.net/view.php?id=1033 +.SH SEE ALSO +.BR closelog (3), +.BR openlog (3), +.BR syslog (3) diff --git a/man/man3/setmntent.3 b/man/man3/setmntent.3 new file mode 100644 index 0000000..3c2bb35 --- /dev/null +++ b/man/man3/setmntent.3 @@ -0,0 +1 @@ +.so man3/getmntent.3 diff --git a/man/man3/setnetent.3 b/man/man3/setnetent.3 new file mode 100644 index 0000000..70f5670 --- /dev/null +++ b/man/man3/setnetent.3 @@ -0,0 +1 @@ +.so man3/getnetent.3 diff --git a/man/man3/setnetgrent.3 b/man/man3/setnetgrent.3 new file mode 100644 index 0000000..b47d4d7 --- /dev/null +++ b/man/man3/setnetgrent.3 @@ -0,0 +1,170 @@ +'\" t +.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" based on glibc infopages +.\" polished - aeb +.\" +.TH setnetgrent 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +setnetgrent, endnetgrent, getnetgrent, getnetgrent_r, innetgr \- +handle network group entries +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int setnetgrent(const char *" netgroup ); +.B "void endnetgrent(void);" +.P +.BI "int getnetgrent(char **restrict " host , +.BI " char **restrict " user ", char **restrict " domain ); +.BI "int getnetgrent_r(char **restrict " host , +.BI " char **restrict " user ", char **restrict " domain , +.BI " char " buf "[restrict ." buflen "], size_t " buflen ); +.P +.BI "int innetgr(const char *" netgroup ", const char *" host , +.BI " const char *" user ", const char *" domain ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR \%setnetgrent (), +.BR \%endnetgrent (), +.BR \%getnetgrent (), +.BR \%getnetgrent_r (), +.BR \%innetgr (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.I netgroup +is a SunOS invention. +A netgroup database is a list of string triples +.RI ( hostname ", " username ", " domainname ) +or other netgroup names. +Any of the elements in a triple can be empty, +which means that anything matches. +The functions described here allow access to the netgroup databases. +The file +.I /etc/nsswitch.conf +defines what database is searched. +.P +The +.BR setnetgrent () +call defines the netgroup that will be searched by subsequent +.BR getnetgrent () +calls. +The +.BR getnetgrent () +function retrieves the next netgroup entry, and returns pointers in +.IR host , +.IR user , +.IR domain . +A null pointer means that the corresponding entry matches any string. +The pointers are valid only as long as there is no call to other +netgroup-related functions. +To avoid this problem you can use the GNU function +.BR getnetgrent_r () +that stores the strings in the supplied buffer. +To free all allocated buffers use +.BR endnetgrent (). +.P +In most cases you want to check only if the triplet +.RI ( hostname ", " username ", " domainname ) +is a member of a netgroup. +The function +.BR innetgr () +can be used for this without calling the above three functions. +Again, a null pointer is a wildcard and matches any string. +The function is thread-safe. +.SH RETURN VALUE +These functions return 1 on success and 0 for failure. +.SH FILES +.I /etc/netgroup +.br +.I /etc/nsswitch.conf +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setnetgrent (), +.BR getnetgrent_r (), +.BR innetgr () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netgrent +locale +T} +T{ +.na +.nh +.BR endnetgrent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netgrent +T} +T{ +.na +.nh +.BR getnetgrent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:netgrent +race:netgrentbuf locale +T} +.TE +.P +In the above table, +.I netgrent +in +.I race:netgrent +signifies that if any of the functions +.BR setnetgrent (), +.BR getnetgrent_r (), +.BR innetgr (), +.BR getnetgrent (), +or +.BR endnetgrent () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +In the BSD implementation, +.BR setnetgrent () +returns void. +.SH STANDARDS +None. +.SH HISTORY +.BR setnetgrent (), +.BR endnetgrent (), +.BR getnetgrent (), +and +.BR innetgr () +are available on most UNIX systems. +.BR getnetgrent_r () +is not widely available on other systems. +.\" getnetgrent_r() is on Solaris 8 and AIX 5.1, but not the BSDs. +.SH SEE ALSO +.BR sethostent (3), +.BR setprotoent (3), +.BR setservent (3) diff --git a/man/man3/setprotoent.3 b/man/man3/setprotoent.3 new file mode 100644 index 0000000..f8cb4bb --- /dev/null +++ b/man/man3/setprotoent.3 @@ -0,0 +1 @@ +.so man3/getprotoent.3 diff --git a/man/man3/setpwent.3 b/man/man3/setpwent.3 new file mode 100644 index 0000000..f2d121b --- /dev/null +++ b/man/man3/setpwent.3 @@ -0,0 +1 @@ +.so man3/getpwent.3 diff --git a/man/man3/setrpcent.3 b/man/man3/setrpcent.3 new file mode 100644 index 0000000..923085e --- /dev/null +++ b/man/man3/setrpcent.3 @@ -0,0 +1 @@ +.so man3/getrpcent.3 diff --git a/man/man3/setservent.3 b/man/man3/setservent.3 new file mode 100644 index 0000000..eaafb1c --- /dev/null +++ b/man/man3/setservent.3 @@ -0,0 +1 @@ +.so man3/getservent.3 diff --git a/man/man3/setspent.3 b/man/man3/setspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/setspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/setstate.3 b/man/man3/setstate.3 new file mode 100644 index 0000000..6e34104 --- /dev/null +++ b/man/man3/setstate.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man/man3/setstate_r.3 b/man/man3/setstate_r.3 new file mode 100644 index 0000000..b01937f --- /dev/null +++ b/man/man3/setstate_r.3 @@ -0,0 +1 @@ +.so man3/random_r.3 diff --git a/man/man3/setttyent.3 b/man/man3/setttyent.3 new file mode 100644 index 0000000..1cd11e3 --- /dev/null +++ b/man/man3/setttyent.3 @@ -0,0 +1 @@ +.so man3/getttyent.3 diff --git a/man/man3/setusershell.3 b/man/man3/setusershell.3 new file mode 100644 index 0000000..718ed12 --- /dev/null +++ b/man/man3/setusershell.3 @@ -0,0 +1 @@ +.so man3/getusershell.3 diff --git a/man/man3/setutent.3 b/man/man3/setutent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/setutent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/setutxent.3 b/man/man3/setutxent.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/setutxent.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/setvbuf.3 b/man/man3/setvbuf.3 new file mode 100644 index 0000000..dc02d9e --- /dev/null +++ b/man/man3/setvbuf.3 @@ -0,0 +1 @@ +.so man3/setbuf.3 diff --git a/man/man3/sgetspent.3 b/man/man3/sgetspent.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/sgetspent.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/sgetspent_r.3 b/man/man3/sgetspent_r.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/sgetspent_r.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/shm_open.3 b/man/man3/shm_open.3 new file mode 100644 index 0000000..257e460 --- /dev/null +++ b/man/man3/shm_open.3 @@ -0,0 +1,521 @@ +'\" t +.\" Copyright (C) 2002, 2020 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH shm_open 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +shm_open, shm_unlink \- create/open or unlink POSIX shared memory objects +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include +.BR "#include " " /* For mode constants */" +.BR "#include " " /* For O_* constants */" +.P +.BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode ); +.BI "int shm_unlink(const char *" name ); +.fi +.SH DESCRIPTION +.BR shm_open () +creates and opens a new, or opens an existing, POSIX shared memory object. +A POSIX shared memory object is in effect a handle which can +be used by unrelated processes to +.BR mmap (2) +the same region of shared memory. +The +.BR shm_unlink () +function performs the converse operation, +removing an object previously created by +.BR shm_open (). +.P +The operation of +.BR shm_open () +is analogous to that of +.BR open (2). +.I name +specifies the shared memory object to be created or opened. +For portable use, +a shared memory object should be identified by a name of the form +.IR /somename ; +that is, a null-terminated string of up to +.B NAME_MAX +(i.e., 255) characters consisting of an initial slash, +.\" glibc allows the initial slash to be omitted, and makes +.\" multiple initial slashes equivalent to a single slash. +.\" This differs from the implementation of POSIX message queues. +followed by one or more characters, none of which are slashes. +.\" glibc allows subdirectory components in the name, in which +.\" case the subdirectory must exist under /dev/shm, and allow the +.\" required permissions if a user wants to create a shared memory +.\" object in that subdirectory. +.P +.I oflag +is a bit mask created by ORing together exactly one of +.B O_RDONLY +or +.B O_RDWR +and any of the other flags listed here: +.TP +.B O_RDONLY +Open the object for read access. +A shared memory object opened in this way can be +.BR mmap (2)ed +only for read +.RB ( PROT_READ ) +access. +.TP +.B O_RDWR +Open the object for read-write access. +.TP +.B O_CREAT +Create the shared memory object if it does not exist. +The user and group ownership of the object are taken +from the corresponding effective IDs of the calling process, +.\" In truth it is actually the filesystem IDs on Linux, but these +.\" are nearly always the same as the effective IDs. (MTK, Jul 05) +and the object's +permission bits are set according to the low-order 9 bits of +.IR mode , +except that those bits set in the process file mode +creation mask (see +.BR umask (2)) +are cleared for the new object. +A set of macro constants which can be used to define +.I mode +is listed in +.BR open (2). +(Symbolic definitions of these constants can be obtained by including +.IR .) +.IP +A new shared memory object initially has zero length\[em]the size of the +object can be set using +.BR ftruncate (2). +The newly allocated bytes of a shared memory +object are automatically initialized to 0. +.TP +.B O_EXCL +If +.B O_CREAT +was also specified, and a shared memory object with the given +.I name +already exists, return an error. +The check for the existence of the object, and its creation if it +does not exist, are performed atomically. +.TP +.B O_TRUNC +If the shared memory object already exists, truncate it to zero bytes. +.P +Definitions of these flag values can be obtained by including +.IR . +.P +On successful completion +.BR shm_open () +returns a new file descriptor referring to the shared memory object. +This file descriptor is guaranteed to be the lowest-numbered file descriptor +not previously opened within the process. +The +.B FD_CLOEXEC +flag (see +.BR fcntl (2)) +is set for the file descriptor. +.P +The file descriptor is normally used in subsequent calls +to +.BR ftruncate (2) +(for a newly created object) and +.BR mmap (2). +After a call to +.BR mmap (2) +the file descriptor may be closed without affecting the memory mapping. +.P +The operation +of +.BR shm_unlink () +is analogous to +.BR unlink (2): +it removes a shared memory object name, and, once all processes +have unmapped the object, deallocates and +destroys the contents of the associated memory region. +After a successful +.BR shm_unlink (), +attempts to +.BR shm_open () +an object with the same +.I name +fail (unless +.B O_CREAT +was specified, in which case a new, distinct object is created). +.SH RETURN VALUE +On success, +.BR shm_open () +returns a file descriptor (a nonnegative integer). +On success, +.BR shm_unlink () +returns 0. +On failure, both functions return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EACCES +Permission to +.BR shm_unlink () +the shared memory object was denied. +.TP +.B EACCES +Permission was denied to +.BR shm_open () +.I name +in the specified +.IR mode , +or +.B O_TRUNC +was specified and the caller does not have write permission on the object. +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified to +.BR shm_open () +and the shared memory object specified by +.I name +already exists. +.TP +.B EINVAL +The +.I name +argument to +.BR shm_open () +was invalid. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +The length of +.I name +exceeds +.BR PATH_MAX . +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +An attempt was made to +.BR shm_open () +a +.I name +that did not exist, and +.B O_CREAT +was not specified. +.TP +.B ENOENT +An attempt was to made to +.BR shm_unlink () +a +.I name +that does not exist. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR shm_open (), +.BR shm_unlink () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +POSIX leaves the behavior of the combination of +.B O_RDONLY +and +.B O_TRUNC +unspecified. +On Linux, this will successfully truncate an existing +shared memory object\[em]this may not be so on other UNIX systems. +.P +The POSIX shared memory object implementation on Linux makes use +of a dedicated +.BR tmpfs (5) +filesystem that is normally mounted under +.IR /dev/shm . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.P +POSIX.1-2001 says that the group ownership of a newly created shared +memory object is set to either the calling process's effective group ID +or "a system default group ID". +POSIX.1-2008 says that the group ownership +may be set to either the calling process's effective group ID +or, if the object is visible in the filesystem, +the group ID of the parent directory. +.SH EXAMPLES +The programs below employ POSIX shared memory and POSIX unnamed semaphores +to exchange a piece of data. +The "bounce" program (which must be run first) raises the case +of a string that is placed into the shared memory by the "send" program. +Once the data has been modified, the "send" program then prints +the contents of the modified shared memory. +An example execution of the two programs is the following: +.P +.in +4n +.EX +$ \fB./pshm_ucase_bounce /myshm &\fP +[1] 270171 +$ \fB./pshm_ucase_send /myshm hello\fP +HELLO +.EE +.in +.P +Further detail about these programs is provided below. +.\" +.SS Program source: pshm_ucase.h +The following header file is included by both programs below. +Its primary purpose is to define a structure that will be imposed +on the memory object that is shared between the two programs. +.P +.in +4n +.\" SRC BEGIN (pshm_ucase.h) +.EX +#ifndef PSHM_UCASE_H +#define PSHM_UCASE_H +\& +#include +#include +#include +#include +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +#define BUF_SIZE 1024 /* Maximum size for exchanged string */ +\& +/* Define a structure that will be imposed on the shared + memory object */ +\& +struct shmbuf { + sem_t sem1; /* POSIX unnamed semaphore */ + sem_t sem2; /* POSIX unnamed semaphore */ + size_t cnt; /* Number of bytes used in \[aq]buf\[aq] */ + char buf[BUF_SIZE]; /* Data being transferred */ +}; +\& +#endif // include guard +.EE +.\" SRC END +.in +.\" +.SS Program source: pshm_ucase_bounce.c +The "bounce" program creates a new shared memory object with the name +given in its command-line argument and sizes the object to +match the size of the +.I shmbuf +structure defined in the header file. +It then maps the object into the process's address space, +and initializes two POSIX semaphores inside the object to 0. +.P +After the "send" program has posted the first of the semaphores, +the "bounce" program upper cases the data that has been placed +in the memory by the "send" program and then posts the second semaphore +to tell the "send" program that it may now access the shared memory. +.P +.in +4n +.\" SRC BEGIN (pshm_ucase_bounce.c) +.EX +/* pshm_ucase_bounce.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include +#include +#include +#include +#include +#include +\& +#include "pshm_ucase.h" +\& +int +main(int argc, char *argv[]) +{ + int fd; + char *shmpath; + struct shmbuf *shmp; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s /shm\-path\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + shmpath = argv[1]; +\& + /* Create shared memory object and set its size to the size + of our structure. */ +\& + fd = shm_open(shmpath, O_CREAT | O_EXCL | O_RDWR, 0600); + if (fd == \-1) + errExit("shm_open"); +\& + if (ftruncate(fd, sizeof(struct shmbuf)) == \-1) + errExit("ftruncate"); +\& + /* Map the object into the caller\[aq]s address space. */ +\& + shmp = mmap(NULL, sizeof(*shmp), PROT_READ | PROT_WRITE, + MAP_SHARED, fd, 0); + if (shmp == MAP_FAILED) + errExit("mmap"); +\& + /* Initialize semaphores as process\-shared, with value 0. */ +\& + if (sem_init(&shmp\->sem1, 1, 0) == \-1) + errExit("sem_init\-sem1"); + if (sem_init(&shmp\->sem2, 1, 0) == \-1) + errExit("sem_init\-sem2"); +\& + /* Wait for \[aq]sem1\[aq] to be posted by peer before touching + shared memory. */ +\& + if (sem_wait(&shmp\->sem1) == \-1) + errExit("sem_wait"); +\& + /* Convert data in shared memory into upper case. */ +\& + for (size_t j = 0; j < shmp\->cnt; j++) + shmp\->buf[j] = toupper((unsigned char) shmp\->buf[j]); +\& + /* Post \[aq]sem2\[aq] to tell the peer that it can now + access the modified data in shared memory. */ +\& + if (sem_post(&shmp\->sem2) == \-1) + errExit("sem_post"); +\& + /* Unlink the shared memory object. Even if the peer process + is still using the object, this is okay. The object will + be removed only after all open references are closed. */ +\& + shm_unlink(shmpath); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.\" +.SS Program source: pshm_ucase_send.c +The "send" program takes two command-line arguments: +the pathname of a shared memory object previously created by the "bounce" +program and a string that is to be copied into that object. +.P +The program opens the shared memory object +and maps the object into its address space. +It then copies the data specified in its second argument +into the shared memory, +and posts the first semaphore, +which tells the "bounce" program that it can now access that data. +After the "bounce" program posts the second semaphore, +the "send" program prints the contents of the shared memory +on standard output. +.P +.in +4n +.\" SRC BEGIN (pshm_ucase_send.c) +.EX +/* pshm_ucase_send.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include +#include +#include +#include +#include +#include +#include +\& +#include "pshm_ucase.h" +\& +int +main(int argc, char *argv[]) +{ + int fd; + char *shmpath, *string; + size_t len; + struct shmbuf *shmp; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s /shm\-path string\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + shmpath = argv[1]; + string = argv[2]; + len = strlen(string); +\& + if (len > BUF_SIZE) { + fprintf(stderr, "String is too long\en"); + exit(EXIT_FAILURE); + } +\& + /* Open the existing shared memory object and map it + into the caller\[aq]s address space. */ +\& + fd = shm_open(shmpath, O_RDWR, 0); + if (fd == \-1) + errExit("shm_open"); +\& + shmp = mmap(NULL, sizeof(*shmp), PROT_READ | PROT_WRITE, + MAP_SHARED, fd, 0); + if (shmp == MAP_FAILED) + errExit("mmap"); +\& + /* Copy data into the shared memory object. */ +\& + shmp\->cnt = len; + memcpy(&shmp\->buf, string, len); +\& + /* Tell peer that it can now access shared memory. */ +\& + if (sem_post(&shmp\->sem1) == \-1) + errExit("sem_post"); +\& + /* Wait until peer says that it has finished accessing + the shared memory. */ +\& + if (sem_wait(&shmp\->sem2) == \-1) + errExit("sem_wait"); +\& + /* Write modified data in shared memory to standard output. */ +\& + write(STDOUT_FILENO, &shmp\->buf, len); + write(STDOUT_FILENO, "\en", 1); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR close (2), +.BR fchmod (2), +.BR fchown (2), +.BR fcntl (2), +.BR fstat (2), +.BR ftruncate (2), +.BR memfd_create (2), +.BR mmap (2), +.BR open (2), +.BR umask (2), +.BR shm_overview (7) diff --git a/man/man3/shm_unlink.3 b/man/man3/shm_unlink.3 new file mode 100644 index 0000000..74f2986 --- /dev/null +++ b/man/man3/shm_unlink.3 @@ -0,0 +1 @@ +.so man3/shm_open.3 diff --git a/man/man3/sigabbrev_np.3 b/man/man3/sigabbrev_np.3 new file mode 100644 index 0000000..f64f756 --- /dev/null +++ b/man/man3/sigabbrev_np.3 @@ -0,0 +1 @@ +.so man3/strsignal.3 diff --git a/man/man3/sigaddset.3 b/man/man3/sigaddset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigaddset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigandset.3 b/man/man3/sigandset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigandset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigblock.3 b/man/man3/sigblock.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man/man3/sigblock.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man/man3/sigdelset.3 b/man/man3/sigdelset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigdelset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigdescr_np.3 b/man/man3/sigdescr_np.3 new file mode 100644 index 0000000..f64f756 --- /dev/null +++ b/man/man3/sigdescr_np.3 @@ -0,0 +1 @@ +.so man3/strsignal.3 diff --git a/man/man3/sigemptyset.3 b/man/man3/sigemptyset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigemptyset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigfillset.3 b/man/man3/sigfillset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigfillset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/siggetmask.3 b/man/man3/siggetmask.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man/man3/siggetmask.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man/man3/sighold.3 b/man/man3/sighold.3 new file mode 100644 index 0000000..c4e1d3c --- /dev/null +++ b/man/man3/sighold.3 @@ -0,0 +1 @@ +.so man3/sigset.3 diff --git a/man/man3/sigignore.3 b/man/man3/sigignore.3 new file mode 100644 index 0000000..c4e1d3c --- /dev/null +++ b/man/man3/sigignore.3 @@ -0,0 +1 @@ +.so man3/sigset.3 diff --git a/man/man3/siginterrupt.3 b/man/man3/siginterrupt.3 new file mode 100644 index 0000000..82c17e2 --- /dev/null +++ b/man/man3/siginterrupt.3 @@ -0,0 +1,98 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:40:51 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Apr 14 16:20:34 1996 by Andries Brouwer (aeb@cwi.nl) +.TH siginterrupt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +siginterrupt \- allow signals to interrupt system calls +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int siginterrupt(int " sig ", int " flag ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR siginterrupt (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR siginterrupt () +function changes the restart behavior when +a system call is interrupted by the signal \fIsig\fP. +If the \fIflag\fP +argument is false (0), then system calls will be restarted if interrupted +by the specified signal \fIsig\fP. +This is the default behavior in Linux. +.P +If the \fIflag\fP argument is true (1) and no data has been transferred, +then a system call interrupted by the signal \fIsig\fP will return \-1 +and \fIerrno\fP will be set to +.BR EINTR . +.P +If the \fIflag\fP argument is true (1) and data transfer has started, +then the system call will be interrupted and will return the actual +amount of data transferred. +.SH RETURN VALUE +The +.BR siginterrupt () +function returns 0 on success. +It returns \-1 if the +signal number +.I sig +is invalid, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The specified signal number is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR siginterrupt () +T} Thread safety T{ +.na +.nh +MT-Unsafe const:sigintr +T} +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +4.3BSD, POSIX.1-2001. +Obsolete in POSIX.1-2008, +recommending the use of +.BR sigaction (2) +with the +.B SA_RESTART +flag instead. +.SH SEE ALSO +.BR signal (2) diff --git a/man/man3/sigisemptyset.3 b/man/man3/sigisemptyset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigisemptyset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigismember.3 b/man/man3/sigismember.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigismember.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/siglongjmp.3 b/man/man3/siglongjmp.3 new file mode 100644 index 0000000..7cf497f --- /dev/null +++ b/man/man3/siglongjmp.3 @@ -0,0 +1 @@ +.so man3/setjmp.3 diff --git a/man/man3/sigmask.3 b/man/man3/sigmask.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man/man3/sigmask.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man/man3/signbit.3 b/man/man3/signbit.3 new file mode 100644 index 0000000..8c39fc0 --- /dev/null +++ b/man/man3/signbit.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on glibc infopages, copyright Free Software Foundation +.\" +.TH signbit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +signbit \- test sign of a real floating-point number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int signbit(" x ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR signbit (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR signbit () +is a generic macro which can work on all real floating-point types. +It returns a nonzero value if the value of +.I x +has its sign bit set. +.P +This is not the same as +.IR "x < 0.0" , +because IEEE 754 floating point allows zero to be signed. +The comparison +.I \-0.0\~<\~0.0 +is false, but +.I signbit(\-0.0) +will return a nonzero value. +.P +NaNs and infinities have a sign bit. +.SH RETURN VALUE +The +.BR signbit () +macro returns nonzero if the sign of +.I x +is negative; otherwise it returns zero. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR signbit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.P +This function is defined in IEC 559 (and the appendix with +recommended functions in IEEE 754/IEEE 854). +.SH SEE ALSO +.BR copysign (3) diff --git a/man/man3/signgam.3 b/man/man3/signgam.3 new file mode 100644 index 0000000..be0ed98 --- /dev/null +++ b/man/man3/signgam.3 @@ -0,0 +1 @@ +.so man3/lgamma.3 diff --git a/man/man3/significand.3 b/man/man3/significand.3 new file mode 100644 index 0000000..1966d24 --- /dev/null +++ b/man/man3/significand.3 @@ -0,0 +1,78 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" heavily based on glibc infopages, copyright Free Software Foundation +.\" +.TH significand 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +significand, significandf, significandl \- +get mantissa of floating-point number +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double significand(double " x ); +.BI "float significandf(float " x ); +.BI "long double significandl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR significand (), +.BR significandf (), +.BR significandl (): +.nf + /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the mantissa of +.I x +scaled to the range +.RB [ 1 ,\~ FLT_RADIX ). +They are equivalent to +.P +.in +4n +.EX +scalb(x, (double) \-ilogb(x)) +.EE +.in +.P +This function exists mainly for use in certain standardized tests +for IEEE 754 conformance. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR significand (), +.BR significandf (), +.BR significandl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.TP +.BR significand () +BSD. +.SH HISTORY +.TP +.BR significand () +BSD. +.SH SEE ALSO +.BR ilogb (3), +.BR scalb (3) diff --git a/man/man3/significandf.3 b/man/man3/significandf.3 new file mode 100644 index 0000000..4ae39f5 --- /dev/null +++ b/man/man3/significandf.3 @@ -0,0 +1 @@ +.so man3/significand.3 diff --git a/man/man3/significandl.3 b/man/man3/significandl.3 new file mode 100644 index 0000000..4ae39f5 --- /dev/null +++ b/man/man3/significandl.3 @@ -0,0 +1 @@ +.so man3/significand.3 diff --git a/man/man3/sigorset.3 b/man/man3/sigorset.3 new file mode 100644 index 0000000..c730781 --- /dev/null +++ b/man/man3/sigorset.3 @@ -0,0 +1 @@ +.so man3/sigsetops.3 diff --git a/man/man3/sigpause.3 b/man/man3/sigpause.3 new file mode 100644 index 0000000..bd93593 --- /dev/null +++ b/man/man3/sigpause.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigpause 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigpause \- atomically release blocked signals and wait for interrupt +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int sigpause(int " sigmask "); /* BSD (but see NOTES) */" +.P +.BI "[[deprecated]] int sigpause(int " sig "); /* POSIX.1 / SysV / UNIX 95 */" +.fi +.SH DESCRIPTION +Don't use this function. +Use +.BR sigsuspend (2) +instead. +.P +The function +.BR sigpause () +is designed to wait for some signal. +It changes the process's signal mask (set of blocked signals), +and then waits for a signal to arrive. +Upon arrival of a signal, the original signal mask is restored. +.SH RETURN VALUE +If +.BR sigpause () +returns, it was interrupted by a signal and the return value is \-1 +with +.I errno +set to +.BR EINTR . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigpause () +T} Thread safety MT-Safe +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" marking in glibc manual is more detailed: +.\" +.\" sigpause: MT-Unsafe race:sigprocmask/!bsd!linux +.\" +.\" glibc manual says /!linux!bsd indicate the preceding marker only applies +.\" when the underlying kernel is neither Linux nor a BSD kernel. +.\" So, it is safe in Linux kernel. +.SH VERSIONS +On Linux, this routine is a system call only on the Sparc (sparc64) +architecture. +.P +.\" Libc4 and libc5 know only about the BSD version. +.\" +glibc uses the BSD version if the +.B _BSD_SOURCE +feature test macro is defined and none of +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.BR _GNU_SOURCE , +or +.B _SVID_SOURCE +is defined. +Otherwise, the System V version is used, +and feature test macros must be defined as follows to obtain the declaration: +.IP \[bu] 3 +Since glibc 2.26: +_XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) +.IP \[bu] +glibc 2.25 and earlier: _XOPEN_SOURCE +.P +Since glibc 2.19, only the System V version is exposed by +.IR ; +applications that formerly used the BSD +.BR sigpause () +should be amended to use +.BR sigsuspend (2). +.\" +.\" For the BSD version, one usually uses a zero +.\" .I sigmask +.\" to indicate that no signals are to be blocked. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +Obsoleted in POSIX.1-2008. +.P +The classical BSD version of this function appeared in 4.2BSD. +It sets the process's signal mask to +.IR sigmask . +UNIX 95 standardized the incompatible System V version of +this function, which removes only the specified signal +.I sig +from the process's signal mask. +.\" __xpg_sigpause: UNIX 95, spec 1170, SVID, SVr4, XPG +The unfortunate situation with two incompatible functions with the +same name was solved by the +.BR \%sigsuspend (2) +function, that takes a +.I "sigset_t\ *" +argument (instead of an +.IR int ). +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR sigblock (3), +.BR sigvec (3), +.BR feature_test_macros (7) diff --git a/man/man3/sigqueue.3 b/man/man3/sigqueue.3 new file mode 100644 index 0000000..341d942 --- /dev/null +++ b/man/man3/sigqueue.3 @@ -0,0 +1,162 @@ +'\" t +.\" Copyright (c) 2002 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" added note on self-signaling, aeb, 2002-06-07 +.\" added note on CAP_KILL, mtk, 2004-06-16 +.\" +.TH sigqueue 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigqueue \- queue a signal and data to a process +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sigqueue(pid_t " pid ", int " sig ", const union sigval " value ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigqueue (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +.BR sigqueue () +sends the signal specified in +.I sig +to the process whose PID is given in +.IR pid . +The permissions required to send a signal are the same as for +.BR kill (2). +As with +.BR kill (2), +the null signal (0) can be used to check if a process with a given +PID exists. +.P +The +.I value +argument is used to specify an accompanying item of data (either an integer +or a pointer value) to be sent with the signal, and has the following type: +.P +.in +4n +.EX +union sigval { + int sival_int; + void *sival_ptr; +}; +.EE +.in +.P +If the receiving process has installed a handler for this signal using the +.B SA_SIGINFO +flag to +.BR sigaction (2), +then it can obtain this data via the +.I si_value +field of the +.I siginfo_t +structure passed as the second argument to the handler. +Furthermore, the +.I si_code +field of that structure will be set to +.BR SI_QUEUE . +.SH RETURN VALUE +On success, +.BR sigqueue () +returns 0, indicating that the signal was successfully +queued to the receiving process. +Otherwise, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +The limit of signals which may be queued has been reached. +(See +.BR signal (7) +for further information.) +.TP +.B EINVAL +.I sig +was invalid. +.TP +.B EPERM +The process does not have permission to send the signal +to the receiving process. +For the required permissions, see +.BR kill (2). +.TP +.B ESRCH +No process has a PID matching +.IR pid . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigqueue () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS C library/kernel differences +On Linux, +.BR sigqueue () +is implemented using the +.BR rt_sigqueueinfo (2) +system call. +The system call differs in its third argument, which is the +.I siginfo_t +structure that will be supplied to the receiving process's +signal handler or returned by the receiving process's +.BR sigtimedwait (2) +call. +Inside the glibc +.BR sigqueue () +wrapper, this argument, +.IR uinfo , +is initialized as follows: +.P +.in +4n +.EX +uinfo.si_signo = sig; /* Argument supplied to sigqueue() */ +uinfo.si_code = SI_QUEUE; +uinfo.si_pid = getpid(); /* Process ID of sender */ +uinfo.si_uid = getuid(); /* Real UID of sender */ +uinfo.si_value = val; /* Argument supplied to sigqueue() */ +.EE +.in +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +Linux 2.2. +POSIX.1-2001. +.SH NOTES +If this function results in the sending of a signal to the process +that invoked it, and that signal was not blocked by the calling thread, +and no other threads were willing to handle this signal (either by +having it unblocked, or by waiting for it using +.BR sigwait (3)), +then at least some signal must be delivered to this thread before this +function returns. +.SH SEE ALSO +.BR kill (2), +.BR rt_sigqueueinfo (2), +.BR sigaction (2), +.BR signal (2), +.BR pthread_sigqueue (3), +.BR sigwait (3), +.BR signal (7) diff --git a/man/man3/sigrelse.3 b/man/man3/sigrelse.3 new file mode 100644 index 0000000..c4e1d3c --- /dev/null +++ b/man/man3/sigrelse.3 @@ -0,0 +1 @@ +.so man3/sigset.3 diff --git a/man/man3/sigset.3 b/man/man3/sigset.3 new file mode 100644 index 0000000..195b5fe --- /dev/null +++ b/man/man3/sigset.3 @@ -0,0 +1,265 @@ +'\" t +.\" Copyright (c) 2005 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigset 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigset, sighold, sigrelse, sigignore \- System V signal API +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B typedef void (*sighandler_t)(int); +.P +.BI "[[deprecated]] sighandler_t sigset(int " sig ", sighandler_t " disp ); +.P +.BI "[[deprecated]] int sighold(int " sig ); +.BI "[[deprecated]] int sigrelse(int " sig ); +.BI "[[deprecated]] int sigignore(int " sig ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigset (), +.BR sighold (), +.BR sigrelse (), +.BR sigignore (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +These functions are provided in glibc as a compatibility interface +for programs that make use of the historical System V signal API. +This API is obsolete: new applications should use the POSIX signal API +.RB ( sigaction (2), +.BR sigprocmask (2), +etc.) +.P +The +.BR sigset () +function modifies the disposition of the signal +.IR sig . +The +.I disp +argument can be the address of a signal handler function, +or one of the following constants: +.TP +.B SIG_DFL +Reset the disposition of +.I sig +to the default. +.TP +.B SIG_IGN +Ignore +.IR sig . +.TP +.B SIG_HOLD +Add +.I sig +to the process's signal mask, but leave the disposition of +.I sig +unchanged. +.P +If +.I disp +specifies the address of a signal handler, then +.I sig +is added to the process's signal mask during execution of the handler. +.P +If +.I disp +was specified as a value other than +.BR SIG_HOLD , +then +.I sig +is removed from the process's signal mask. +.P +The dispositions for +.B SIGKILL +and +.B SIGSTOP +cannot be changed. +.P +The +.BR sighold () +function adds +.I sig +to the calling process's signal mask. +.P +The +.BR sigrelse () +function removes +.I sig +from the calling process's signal mask. +.P +The +.BR sigignore () +function sets the disposition of +.I sig +to +.BR SIG_IGN . +.SH RETURN VALUE +On success, +.BR sigset () +returns +.B SIG_HOLD +if +.I sig +was blocked before the call, +or the signal's previous disposition +if it was not blocked before the call. +On error, +.BR sigset () +returns \-1, with +.I errno +set to indicate the error. +(But see BUGS below.) +.P +The +.BR sighold (), +.BR sigrelse (), +and +.BR sigignore () +functions return 0 on success; on error, these functions return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +For +.BR sigset () +see the ERRORS under +.BR sigaction (2) +and +.BR sigprocmask (2). +.P +For +.BR sighold () +and +.BR sigrelse () +see the ERRORS under +.BR sigprocmask (2). +.P +For +.BR sigignore (), +see the errors under +.BR sigaction (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigset (), +.BR sighold (), +.BR sigrelse (), +.BR sigignore () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.TP +.I sighandler_t +GNU. +POSIX.1 uses the same type but without a +.IR typedef . +.SH HISTORY +glibc 2.1. +SVr4, POSIX.1-2001. +POSIX.1-2008 marks these functions +as obsolete, recommending the use of +.BR sigaction (2), +.BR sigprocmask (2), +.BR pthread_sigmask (3), +and +.BR sigsuspend (2) +instead. +.SH NOTES +The +.BR sigset () +function provides reliable signal handling semantics (as when calling +.BR sigaction (2) +with +.I sa_mask +equal to 0). +.P +On System V, the +.BR signal () +function provides unreliable semantics (as when calling +.BR sigaction (2) +with +.I sa_mask +equal to +.IR "SA_RESETHAND | SA_NODEFER" ). +On BSD, +.BR signal () +provides reliable semantics. +POSIX.1-2001 leaves these aspects of +.BR signal () +unspecified. +See +.BR signal (2) +for further details. +.P +In order to wait for a signal, +BSD and System V both provided a function named +.BR sigpause (3), +but this function has a different argument on the two systems. +See +.BR sigpause (3) +for details. +.SH BUGS +Before glibc 2.2, +.BR sigset () +did not unblock +.I sig +if +.I disp +was specified as a value other than +.BR SIG_HOLD . +.P +Before glibc 2.5, +.BR sigset () +does not correctly return the previous disposition of the signal +in two cases. +First, if +.I disp +is specified as +.BR SIG_HOLD , +then a successful +.BR sigset () +always returns +.BR SIG_HOLD . +Instead, it should return the previous disposition of the signal +(unless the signal was blocked, in which case +.B SIG_HOLD +should be returned). +Second, if the signal is currently blocked, then +the return value of a successful +.BR sigset () +should be +.BR SIG_HOLD . +Instead, the previous disposition of the signal is returned. +These problems have been fixed since glibc 2.5. +.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1951 +.SH SEE ALSO +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR raise (3), +.BR sigpause (3), +.BR sigvec (3), +.BR signal (7) diff --git a/man/man3/sigsetjmp.3 b/man/man3/sigsetjmp.3 new file mode 100644 index 0000000..7cf497f --- /dev/null +++ b/man/man3/sigsetjmp.3 @@ -0,0 +1 @@ +.so man3/setjmp.3 diff --git a/man/man3/sigsetmask.3 b/man/man3/sigsetmask.3 new file mode 100644 index 0000000..5582b11 --- /dev/null +++ b/man/man3/sigsetmask.3 @@ -0,0 +1 @@ +.so man3/sigvec.3 diff --git a/man/man3/sigsetops.3 b/man/man3/sigsetops.3 new file mode 100644 index 0000000..fd1ea9a --- /dev/null +++ b/man/man3/sigsetops.3 @@ -0,0 +1,190 @@ +'\" t +.\" Copyright (c) 1994 Mike Battersby +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by aeb, 960721 +.\" 2005-11-21, mtk, added descriptions of sigisemptyset(), sigandset(), +.\" and sigorset() +.\" 2007-10-26 mdw added wording that a sigset_t must be initialized +.\" prior to use +.\" +.TH SIGSETOPS 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigemptyset, sigfillset, sigaddset, sigdelset, sigismember \- POSIX +signal set operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sigemptyset(sigset_t *" set ); +.BI "int sigfillset(sigset_t *" set ); +.P +.BI "int sigaddset(sigset_t *" set ", int " signum ); +.BI "int sigdelset(sigset_t *" set ", int " signum ); +.P +.BI "int sigismember(const sigset_t *" set ", int " signum ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigemptyset (), +.BR sigfillset (), +.BR sigaddset (), +.BR sigdelset (), +.BR sigismember (): +.nf + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +These functions allow the manipulation of POSIX signal sets. +.P +.BR sigemptyset () +initializes the signal set given by +.I set +to empty, with all signals excluded from the set. +.P +.BR sigfillset () +initializes +.I set +to full, including all signals. +.P +.BR sigaddset () +and +.BR sigdelset () +add and delete respectively signal +.I signum +from +.IR set . +.P +.BR sigismember () +tests whether +.I signum +is a member of +.IR set . +.P +Objects of type +.I sigset_t +must be initialized by a call to either +.BR sigemptyset () +or +.BR sigfillset () +before being passed to the functions +.BR sigaddset (), +.BR sigdelset (), +and +.BR sigismember () +or the additional glibc functions described below +.RB ( sigisemptyset (), +.BR sigandset (), +and +.BR sigorset ()). +The results are undefined if this is not done. +.SH RETURN VALUE +.BR sigemptyset (), +.BR sigfillset (), +.BR sigaddset (), +and +.BR sigdelset () +return 0 on success and \-1 on error. +.P +.BR sigismember () +returns 1 if +.I signum +is a member of +.IR set , +0 if +.I signum +is not a member, and \-1 on error. +.P +On error, these functions set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I signum +is not a valid signal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigemptyset (), +.BR sigfillset (), +.BR sigaddset (), +.BR sigdelset (), +.BR sigismember (), +.BR sigisemptyset (), +.BR sigorset (), +.BR sigandset () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.SS GNU +If the +.B _GNU_SOURCE +feature test macro is defined, then \fI\fP +exposes three other functions for manipulating signal +sets: +.P +.nf +.BI "int sigisemptyset(const sigset_t *" set ); +.BI "int sigorset(sigset_t *" dest ", const sigset_t *" left , +.BI " const sigset_t *" right ); +.BI "int sigandset(sigset_t *" dest ", const sigset_t *" left , +.BI " const sigset_t *" right ); +.fi +.P +.BR sigisemptyset () +returns 1 if +.I set +contains no signals, and 0 otherwise. +.P +.BR sigorset () +places the union of the sets +.I left +and +.I right +in +.IR dest . +.BR sigandset () +places the intersection of the sets +.I left +and +.I right +in +.IR dest . +Both functions return 0 on success, and \-1 on failure. +.P +These functions are nonstandard (a few other systems provide similar +functions) and their use should be avoided in portable applications. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +When creating a filled signal set, the glibc +.BR sigfillset () +function does not include the two real-time signals used internally +by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH SEE ALSO +.BR sigaction (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigsuspend (2) diff --git a/man/man3/sigstack.3 b/man/man3/sigstack.3 new file mode 100644 index 0000000..bf85961 --- /dev/null +++ b/man/man3/sigstack.3 @@ -0,0 +1,3 @@ +.so man2/sigaltstack.2 +.\" No new programs should use sigstack(3). +.\" sigaltstack(2) briefly discusses sigstack(3), so point the user there. diff --git a/man/man3/sigvec.3 b/man/man3/sigvec.3 new file mode 100644 index 0000000..31f5ef4 --- /dev/null +++ b/man/man3/sigvec.3 @@ -0,0 +1,282 @@ +'\" t +.\" Copyright (c) 2005 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigvec 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigvec, sigblock, sigsetmask, siggetmask, sigmask \- BSD signal API +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int sigvec(int " sig ", const struct sigvec *" vec , +.BI " struct sigvec *" ovec ); +.P +.BI "[[deprecated]] int sigmask(int " signum ); +.P +.BI "[[deprecated]] int sigblock(int " mask ); +.BI "[[deprecated]] int sigsetmask(int " mask ); +.B [[deprecated]] int siggetmask(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +These functions are provided in glibc as a compatibility interface +for programs that make use of the historical BSD signal API. +This API is obsolete: new applications should use the POSIX signal API +.RB ( sigaction (2), +.BR sigprocmask (2), +etc.). +.P +The +.BR sigvec () +function sets and/or gets the disposition of the signal +.I sig +(like the POSIX +.BR sigaction (2)). +If +.I vec +is not NULL, it points to a +.I sigvec +structure that defines the new disposition for +.IR sig . +If +.I ovec +is not NULL, it points to a +.I sigvec +structure that is used to return the previous disposition of +.IR sig . +To obtain the current disposition of +.I sig +without changing it, specify NULL for +.IR vec , +and a non-null pointer for +.IR ovec . +.P +The dispositions for +.B SIGKILL +and +.B SIGSTOP +cannot be changed. +.P +The +.I sigvec +structure has the following form: +.P +.in +4n +.EX +struct sigvec { + void (*sv_handler)(int); /* Signal disposition */ + int sv_mask; /* Signals to be blocked in handler */ + int sv_flags; /* Flags */ +}; +.EE +.in +.P +The +.I sv_handler +field specifies the disposition of the signal, and is either: +the address of a signal handler function; +.BR SIG_DFL , +meaning the default disposition applies for the signal; or +.BR SIG_IGN , +meaning that the signal is ignored. +.P +If +.I sv_handler +specifies the address of a signal handler, then +.I sv_mask +specifies a mask of signals that are to be blocked while +the handler is executing. +In addition, the signal for which the handler is invoked is +also blocked. +Attempts to block +.B SIGKILL +or +.B SIGSTOP +are silently ignored. +.P +If +.I sv_handler +specifies the address of a signal handler, then the +.I sv_flags +field specifies flags controlling what happens when the handler is called. +This field may contain zero or more of the following flags: +.TP +.B SV_INTERRUPT +If the signal handler interrupts a blocking system call, +then upon return from the handler the system call is not restarted: +instead it fails with the error +.BR EINTR . +If this flag is not specified, then system calls are restarted +by default. +.TP +.B SV_RESETHAND +Reset the disposition of the signal to the default +before calling the signal handler. +If this flag is not specified, then the handler remains established +until explicitly removed by a later call to +.BR sigvec () +or until the process performs an +.BR execve (2). +.TP +.B SV_ONSTACK +Handle the signal on the alternate signal stack +(historically established under BSD using the obsolete +.BR sigstack () +function; the POSIX replacement is +.BR sigaltstack (2)). +.P +The +.BR sigmask () +macro constructs and returns a "signal mask" for +.IR signum . +For example, we can initialize the +.I vec.sv_mask +field given to +.BR sigvec () +using code such as the following: +.P +.in +4n +.EX +vec.sv_mask = sigmask(SIGQUIT) | sigmask(SIGABRT); + /* Block SIGQUIT and SIGABRT during + handler execution */ +.EE +.in +.P +The +.BR sigblock () +function adds the signals in +.I mask +to the process's signal mask +(like POSIX +.IR sigprocmask(SIG_BLOCK) ), +and returns the process's previous signal mask. +Attempts to block +.B SIGKILL +or +.B SIGSTOP +are silently ignored. +.P +The +.BR sigsetmask () +function sets the process's signal mask to the value given in +.I mask +(like POSIX +.IR sigprocmask(SIG_SETMASK) ), +and returns the process's previous signal mask. +.P +The +.BR siggetmask () +function returns the process's current signal mask. +This call is equivalent to +.IR sigblock(0) . +.SH RETURN VALUE +The +.BR sigvec () +function returns 0 on success; on error, it returns \-1 and sets +.I errno +to indicate the error. +.P +The +.BR sigblock () +and +.BR sigsetmask () +functions return the previous signal mask. +.P +The +.BR sigmask () +macro returns the signal mask for +.IR signum . +.SH ERRORS +See the ERRORS under +.BR sigaction (2) +and +.BR sigprocmask (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigvec (), +.BR sigmask (), +.BR sigblock (), +.BR sigsetmask (), +.BR siggetmask () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +.TP +.BR sigvec () +.TQ +.BR sigblock () +.TQ +.BR sigmask () +.TQ +.BR sigsetmask () +4.3BSD. +.TP +.BR siggetmask () +Unclear origin. +.TP +.BR sigvec () +Removed in glibc 2.21. +.SH NOTES +On 4.3BSD, the +.BR signal () +function provided reliable semantics (as when calling +.BR sigvec () +with +.I vec.sv_mask +equal to 0). +On System V, +.BR signal () +provides unreliable semantics. +POSIX.1 leaves these aspects of +.BR signal () +unspecified. +See +.BR signal (2) +for further details. +.P +In order to wait for a signal, +BSD and System V both provided a function named +.BR sigpause (3), +but this function has a different argument on the two systems. +See +.BR sigpause (3) +for details. +.SH SEE ALSO +.BR kill (2), +.BR pause (2), +.BR sigaction (2), +.BR signal (2), +.BR sigprocmask (2), +.BR raise (3), +.BR sigpause (3), +.BR sigset (3), +.BR signal (7) diff --git a/man/man3/sigwait.3 b/man/man3/sigwait.3 new file mode 100644 index 0000000..f79c917 --- /dev/null +++ b/man/man3/sigwait.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigwait 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigwait \- wait for a signal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sigwait(const sigset_t *restrict " set ", int *restrict " sig ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigwait (): +.nf + Since glibc 2.26: + _POSIX_C_SOURCE >= 199506L + glibc 2.25 and earlier: + _POSIX_C_SOURCE +.fi +.SH DESCRIPTION +The +.BR sigwait () +function suspends execution of the calling thread until +one of the signals specified in the signal set +.I set +becomes pending. +For a signal to become pending, +it must first be blocked with +.BR sigprocmask (2). +The function accepts the signal +(removes it from the pending list of signals), +and returns the signal number in +.IR sig . +.P +The operation of +.BR sigwait () +is the same as +.BR sigwaitinfo (2), +except that: +.IP \[bu] 3 +.BR sigwait () +returns only the signal number, rather than a +.I siginfo_t +structure describing the signal. +.IP \[bu] +The return values of the two functions are different. +.SH RETURN VALUE +On success, +.BR sigwait () +returns 0. +On error, it returns a positive error number (listed in ERRORS). +.SH ERRORS +.TP +.B EINVAL +.\" Does not occur for glibc. +.I set +contains an invalid signal number. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sigwait () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +.BR sigwait () +is implemented using +.BR sigtimedwait (2); +consult its +.BR NOTES . +.P +The glibc implementation of +.BR sigwait () +silently ignores attempts to wait for the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +See +.BR pthread_sigmask (3). +.SH SEE ALSO +.BR sigaction (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigsuspend (2), +.BR sigwaitinfo (2), +.BR sigsetops (3), +.BR signal (7) diff --git a/man/man3/simpleq.3 b/man/man3/simpleq.3 new file mode 100644 index 0000000..fbb71f0 --- /dev/null +++ b/man/man3/simpleq.3 @@ -0,0 +1 @@ +.so man3/stailq.3 diff --git a/man/man3/sin.3 b/man/man3/sin.3 new file mode 100644 index 0000000..7d90bee --- /dev/null +++ b/man/man3/sin.3 @@ -0,0 +1,122 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH sin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sin, sinf, sinl \- sine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double sin(double " x ); +.BI "float sinf(float " x ); +.BI "long double sinl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sinf (), +.BR sinl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the sine of +.IR x , +where +.I x +is +given in radians. +.SH RETURN VALUE +On success, these functions return the sine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.\" +.\" POSIX.1 allows an optional range error for subnormal x +.\" glibc 2.8 doesn't do this +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sin (), +.BR sinf (), +.BR sinl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +Before glibc 2.10, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6781 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cos (3), +.BR csin (3), +.BR sincos (3), +.BR tan (3) diff --git a/man/man3/sincos.3 b/man/man3/sincos.3 new file mode 100644 index 0000000..69769f1 --- /dev/null +++ b/man/man3/sincos.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH sincos 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sincos, sincosf, sincosl \- calculate sin and cos simultaneously +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "void sincos(double " x ", double *" sin ", double *" cos ); +.BI "void sincosf(float " x ", float *" sin ", float *" cos ); +.BI "void sincosl(long double " x ", long double *" sin ", long double *" cos ); +.fi +.SH DESCRIPTION +Several applications need sine and cosine of the same angle +.IR x . +These functions compute both at the same time, and store the results in +.I *sin +and +.IR *cos . +Using this function can be more efficient than two separate calls to +.BR sin (3) +and +.BR cos (3). +.P +If +.I x +is a NaN, +a NaN is returned in +.I *sin +and +.IR *cos . +.P +If +.I x +is positive infinity or negative infinity, +a domain error occurs, and +a NaN is returned in +.I *sin +and +.IR *cos . +.SH RETURN VALUE +These functions return +.IR void . +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sincos (), +.BR sincosf (), +.BR sincosl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH HISTORY +glibc 2.1. +.SH NOTES +To see the performance advantage of +.BR sincos (), +it may be necessary to disable +.BR gcc (1) +built-in optimizations, using flags such as: +.P +.in +4n +.EX +cc \-O \-lm \-fno\-builtin prog.c +.EE +.in +.SH BUGS +Before glibc 2.22, the glibc implementation did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=15467 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR cos (3), +.BR sin (3), +.BR tan (3) diff --git a/man/man3/sincosf.3 b/man/man3/sincosf.3 new file mode 100644 index 0000000..9faef65 --- /dev/null +++ b/man/man3/sincosf.3 @@ -0,0 +1 @@ +.so man3/sincos.3 diff --git a/man/man3/sincosl.3 b/man/man3/sincosl.3 new file mode 100644 index 0000000..9faef65 --- /dev/null +++ b/man/man3/sincosl.3 @@ -0,0 +1 @@ +.so man3/sincos.3 diff --git a/man/man3/sinf.3 b/man/man3/sinf.3 new file mode 100644 index 0000000..eab51f4 --- /dev/null +++ b/man/man3/sinf.3 @@ -0,0 +1 @@ +.so man3/sin.3 diff --git a/man/man3/sinh.3 b/man/man3/sinh.3 new file mode 100644 index 0000000..a80a95f --- /dev/null +++ b/man/man3/sinh.3 @@ -0,0 +1,129 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1996-06-08 by aeb +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH sinh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sinh, sinhf, sinhl \- hyperbolic sine function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double sinh(double " x ); +.BI "float sinhf(float " x ); +.BI "long double sinhl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sinhf (), +.BR sinhl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the hyperbolic sine of +.IR x , +which +is defined mathematically as: +.P +.nf + sinh(x) = (exp(x) \- exp(\-x)) / 2 +.fi +.SH RETURN VALUE +On success, these functions return the hyperbolic sine of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is positive infinity (negative infinity), +positive infinity (negative infinity) is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the same sign as +.IR x . +.\" +.\" POSIX.1-2001 documents an optional range error (underflow) +.\" for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sinh (), +.BR sinhf (), +.BR sinhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR cosh (3), +.BR csinh (3), +.BR tanh (3) diff --git a/man/man3/sinhf.3 b/man/man3/sinhf.3 new file mode 100644 index 0000000..dc3ce94 --- /dev/null +++ b/man/man3/sinhf.3 @@ -0,0 +1 @@ +.so man3/sinh.3 diff --git a/man/man3/sinhl.3 b/man/man3/sinhl.3 new file mode 100644 index 0000000..dc3ce94 --- /dev/null +++ b/man/man3/sinhl.3 @@ -0,0 +1 @@ +.so man3/sinh.3 diff --git a/man/man3/sinl.3 b/man/man3/sinl.3 new file mode 100644 index 0000000..eab51f4 --- /dev/null +++ b/man/man3/sinl.3 @@ -0,0 +1 @@ +.so man3/sin.3 diff --git a/man/man3/sleep.3 b/man/man3/sleep.3 new file mode 100644 index 0000000..8d3effc --- /dev/null +++ b/man/man3/sleep.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 18:16:02 1993 by Rik Faith (faith@cs.unc.edu) +.TH sleep 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sleep \- sleep for a specified number of seconds +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "unsigned int sleep(unsigned int " "seconds" ); +.fi +.SH DESCRIPTION +.BR sleep () +causes the calling thread to sleep either until +the number of real-time seconds specified in +.I seconds +have elapsed or until a signal arrives which is not ignored. +.SH RETURN VALUE +Zero if the requested time has elapsed, +or the number of seconds left to sleep, +if the call was interrupted by a signal handler. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sleep () +T} Thread safety MT-Unsafe sig:SIGCHLD/linux +.TE +.SH VERSIONS +On Linux, +.BR sleep () +is implemented via +.BR nanosleep (2). +See the +.BR nanosleep (2) +man page for a discussion of the clock used. +.P +On some systems, +.BR sleep () +may be implemented using +.BR alarm (2) +and +.B SIGALRM +(POSIX.1 permits this); +mixing calls to +.BR alarm (2) +and +.BR sleep () +is a bad idea. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH CAVEATS +Using +.BR longjmp (3) +from a signal handler or modifying the handling of +.B SIGALRM +while sleeping will cause undefined results. +.SH SEE ALSO +.BR sleep (1), +.BR alarm (2), +.BR nanosleep (2), +.BR signal (2), +.BR signal (7) diff --git a/man/man3/slist.3 b/man/man3/slist.3 new file mode 100644 index 0000000..ecdfe5c --- /dev/null +++ b/man/man3/slist.3 @@ -0,0 +1,319 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH SLIST 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +SLIST_EMPTY, +SLIST_ENTRY, +SLIST_FIRST, +SLIST_FOREACH, +.\"SLIST_FOREACH_FROM, +.\"SLIST_FOREACH_FROM_SAFE, +.\"SLIST_FOREACH_SAFE, +SLIST_HEAD, +SLIST_HEAD_INITIALIZER, +SLIST_INIT, +SLIST_INSERT_AFTER, +SLIST_INSERT_HEAD, +SLIST_NEXT, +SLIST_REMOVE, +.\"SLIST_REMOVE_AFTER, +SLIST_REMOVE_HEAD +.\"SLIST_SWAP +\- implementation of a singly linked list +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B SLIST_ENTRY(TYPE); +.P +.B SLIST_HEAD(HEADNAME, TYPE); +.BI "SLIST_HEAD SLIST_HEAD_INITIALIZER(SLIST_HEAD " head ); +.BI "void SLIST_INIT(SLIST_HEAD *" head ); +.P +.BI "int SLIST_EMPTY(SLIST_HEAD *" head ); +.P +.BI "void SLIST_INSERT_HEAD(SLIST_HEAD *" head , +.BI " struct TYPE *" elm ", SLIST_ENTRY " NAME ); +.BI "void SLIST_INSERT_AFTER(struct TYPE *" listelm , +.BI " struct TYPE *" elm ", SLIST_ENTRY " NAME ); +.P +.BI "struct TYPE *SLIST_FIRST(SLIST_HEAD *" head ); +.BI "struct TYPE *SLIST_NEXT(struct TYPE *" elm ", SLIST_ENTRY " NAME ); +.P +.BI "SLIST_FOREACH(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ); +.\" .BI "SLIST_FOREACH_FROM(struct TYPE *" var ", SLIST_HEAD *" head , +.\" .BI " SLIST_ENTRY " NAME ); +.\" .P +.\" .BI "SLIST_FOREACH_SAFE(struct TYPE *" var ", SLIST_HEAD *" head , +.\" .BI " SLIST_ENTRY " NAME ", struct TYPE *" temp_var ); +.\" .BI "SLIST_FOREACH_FROM_SAFE(struct TYPE *" var ", SLIST_HEAD *" head , +.\" .BI " SLIST_ENTRY " NAME ", struct TYPE *" temp_var ); +.P +.BI "void SLIST_REMOVE(SLIST_HEAD *" head ", struct TYPE *" elm , +.BI " SLIST_ENTRY " NAME ); +.BI "void SLIST_REMOVE_HEAD(SLIST_HEAD *" head , +.BI " SLIST_ENTRY " NAME ); +.\" .BI "void SLIST_REMOVE_AFTER(struct TYPE *" elm , +.\" .BI " SLIST_ENTRY " NAME ); +.\" .P +.\" .BI "void SLIST_SWAP(SLIST_HEAD *" head1 ", SLIST_HEAD *" head2 , +.\" .BI " SLIST_ENTRY " NAME ); +.fi +.SH DESCRIPTION +These macros define and operate on singly linked lists. +.P +In the macro definitions, +.I TYPE +is the name of a user-defined structure, +that must contain a field of type +.IR SLIST_ENTRY , +named +.IR NAME . +The argument +.I HEADNAME +is the name of a user-defined structure +that must be declared using the macro +.BR SLIST_HEAD (). +.SS Creation +A singly linked list is headed by a structure defined by the +.BR SLIST_HEAD () +macro. +This structure contains a single pointer to the first element on the list. +The elements are singly linked +for minimum space and pointer manipulation overhead +at the expense of O(n) removal for arbitrary elements. +New elements can be added to the list +after an existing element +or at the head of the list. +An +.I SLIST_HEAD +structure is declared as follows: +.P +.in +4 +.EX +SLIST_HEAD(HEADNAME, TYPE) head; +.EE +.in +.P +where +.I struct HEADNAME +is the structure to be defined, and +.I struct TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.P +.in +4 +.EX +struct HEADNAME *headp; +.EE +.in +.P +(The names +.I head +and +.I headp +are user selectable.) +.P +.BR SLIST_ENTRY () +declares a structure that connects the elements in +the list. +.P +.BR SLIST_HEAD_INITIALIZER () +evaluates to an initializer for the list +.IR head . +.P +.BR SLIST_INIT () +initializes the list referenced by +.IR head . +.P +.BR SLIST_EMPTY () +evaluates to true if there are no elements in the list. +.SS Insertion +.BR SLIST_INSERT_HEAD () +inserts the new element +.I elm +at the head of the list. +.P +.BR SLIST_INSERT_AFTER () +inserts the new element +.I elm +after the element +.IR listelm . +.SS Traversal +.BR SLIST_FIRST () +returns the first element in the list, or NULL if the list is empty. +.P +.BR SLIST_NEXT () +returns the next element in the list. +.P +.BR SLIST_FOREACH () +traverses the list referenced by +.I head +in the forward direction, +assigning each element in turn to +.IR var . +.\" .P +.\" .BR SLIST_FOREACH_FROM () +.\" behaves identically to +.\" .BR SLIST_FOREACH () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found SLIST element and begins the loop at +.\" .I var +.\" instead of the first element in the SLIST referenced by +.\" .IR head . +.\" .Pp +.\" .BR SLIST_FOREACH_SAFE () +.\" traverses the list referenced by +.\" .I head +.\" in the forward direction, assigning each element in +.\" turn to +.\" .IR var . +.\" However, unlike +.\" .BR SLIST_FOREACH () +.\" here it is permitted to both remove +.\" .I var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .P +.\" .BR SLIST_FOREACH_FROM_SAFE () +.\" behaves identically to +.\" .BR SLIST_FOREACH_SAFE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found SLIST element and begins the loop at +.\" .I var +.\" instead of the first element in the SLIST referenced by +.\" .IR head . +.SS Removal +.BR SLIST_REMOVE () +removes the element +.I elm +from the list. +.P +.BR SLIST_REMOVE_HEAD () +removes the element +.I elm +from the head of the list. +For optimum efficiency, +elements being removed from the head of the list +should explicitly use this macro instead of the generic +.BR SLIST_REMOVE (). +.\" .P +.\" .BR SLIST_REMOVE_AFTER () +.\" removes the element after +.\" .I elm +.\" from the list. +.\" Unlike +.\" .IR SLIST_REMOVE , +.\" this macro does not traverse the entire list. +.\" .SS Other features +.\" .BR SLIST_SWAP () +.\" swaps the contents of +.\" .I head1 +.\" and +.\" .IR head2 . +.SH RETURN VALUE +.BR SLIST_EMPTY () +returns nonzero if the list is empty, +and zero if the list contains at least one entry. +.P +.BR SLIST_FIRST (), +and +.BR SLIST_NEXT () +return a pointer to the first or next +.I TYPE +structure, respectively. +.P +.BR SLIST_HEAD_INITIALIZER () +returns an initializer that can be assigned to the list +.IR head . +.SH STANDARDS +BSD. +.SH HISTORY +4.4BSD. +.SH BUGS +.BR SLIST_FOREACH () +doesn't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +.BR SLIST_FOREACH_SAFE (), +which is present on the BSDs but is not present in glibc, +fixes this limitation by allowing +.I var +to safely be removed from the list and freed from within the loop +without interfering with the traversal. +.SH EXAMPLES +.\" SRC BEGIN (slist.c) +.EX +#include +#include +#include +#include +\& +struct entry { + int data; + SLIST_ENTRY(entry) entries; /* Singly linked list */ +}; +\& +SLIST_HEAD(slisthead, entry); +\& +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct slisthead head; /* Singly linked list + head */ +\& + SLIST_INIT(&head); /* Initialize the queue */ +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the head */ + SLIST_INSERT_HEAD(&head, n1, entries); +\& + n2 = malloc(sizeof(struct entry)); /* Insert after */ + SLIST_INSERT_AFTER(n1, n2, entries); +\& + SLIST_REMOVE(&head, n2, entry, entries);/* Deletion */ + free(n2); +\& + n3 = SLIST_FIRST(&head); + SLIST_REMOVE_HEAD(&head, entries); /* Deletion from the head */ + free(n3); +\& + for (unsigned int i = 0; i < 5; i++) { + n1 = malloc(sizeof(struct entry)); + SLIST_INSERT_HEAD(&head, n1, entries); + n1\->data = i; + } +\& + /* Forward traversal */ + SLIST_FOREACH(np, &head, entries) + printf("%i\en", np\->data); +\& + while (!SLIST_EMPTY(&head)) { /* List deletion */ + n1 = SLIST_FIRST(&head); + SLIST_REMOVE_HEAD(&head, entries); + free(n1); + } + SLIST_INIT(&head); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR insque (3), +.BR queue (7) diff --git a/man/man3/snprintf.3 b/man/man3/snprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/snprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/sockatmark.3 b/man/man3/sockatmark.3 new file mode 100644 index 0000000..62d1ba1 --- /dev/null +++ b/man/man3/sockatmark.3 @@ -0,0 +1,138 @@ +'\" t +.\" Copyright (c) 2006, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sockatmark 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sockatmark \- determine whether socket is at out-of-band mark +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sockatmark(int " sockfd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sockatmark (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +.BR sockatmark () +returns a value indicating whether or not the socket referred +to by the file descriptor +.I sockfd +is at the out-of-band mark. +If the socket is at the mark, then 1 is returned; +if the socket is not at the mark, 0 is returned. +This function does not remove the out-of-band mark. +.SH RETURN VALUE +A successful call to +.BR sockatmark () +returns 1 if the socket is at the out-of-band mark, or 0 if it is not. +On error, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I sockfd +is not a valid file descriptor. +.TP +.B EINVAL +.\" POSIX.1 says ENOTTY for this case +.I sockfd +is not a file descriptor to which +.BR sockatmark () +can be applied. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sockatmark () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2.4. +POSIX.1-2001. +.SH NOTES +If +.BR sockatmark () +returns 1, then the out-of-band data can be read using the +.B MSG_OOB +flag of +.BR recv (2). +.P +Out-of-band data is supported only on some stream socket protocols. +.P +.BR sockatmark () +can safely be called from a handler for the +.B SIGURG +signal. +.P +.BR sockatmark () +is implemented using the +.B SIOCATMARK +.BR ioctl (2) +operation. +.SH BUGS +Prior to glibc 2.4, +.BR sockatmark () +did not work. +.SH EXAMPLES +The following code can be used after receipt of a +.B SIGURG +signal to read (and discard) all data up to the mark, +and then read the byte of data at the mark: +.P +.EX + char buf[BUF_LEN]; + char oobdata; + int atmark, s; +\& + for (;;) { + atmark = sockatmark(sockfd); + if (atmark == \-1) { + perror("sockatmark"); + break; + } +\& + if (atmark) + break; +\& + s = read(sockfd, buf, BUF_LEN); + if (s == \-1) + perror("read"); + if (s <= 0) + break; + } +\& + if (atmark == 1) { + if (recv(sockfd, &oobdata, 1, MSG_OOB) == \-1) { + perror("recv"); + ... + } + } +.EE +.SH SEE ALSO +.BR fcntl (2), +.BR recv (2), +.BR send (2), +.BR tcp (7) diff --git a/man/man3/sprintf.3 b/man/man3/sprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/sprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/sqrt.3 b/man/man3/sqrt.3 new file mode 100644 index 0000000..6f012ab --- /dev/null +++ b/man/man3/sqrt.3 @@ -0,0 +1,109 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.TH sqrt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sqrt, sqrtf, sqrtl \- square root function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double sqrt(double " x ); +.BI "float sqrtf(float " x ); +.BI "long double sqrtl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sqrtf (), +.BR sqrtl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the nonnegative square root of +.IR x . +.SH RETURN VALUE +On success, these functions return the square root of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is positive infinity, positive infinity is returned. +.P +If +.I x +is less than \-0, +a domain error occurs, +and a NaN is returned. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP less than \-0 +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sqrt (), +.BR sqrtf (), +.BR sqrtl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR cbrt (3), +.BR csqrt (3), +.BR hypot (3) diff --git a/man/man3/sqrtf.3 b/man/man3/sqrtf.3 new file mode 100644 index 0000000..81258bb --- /dev/null +++ b/man/man3/sqrtf.3 @@ -0,0 +1 @@ +.so man3/sqrt.3 diff --git a/man/man3/sqrtl.3 b/man/man3/sqrtl.3 new file mode 100644 index 0000000..81258bb --- /dev/null +++ b/man/man3/sqrtl.3 @@ -0,0 +1 @@ +.so man3/sqrt.3 diff --git a/man/man3/srand.3 b/man/man3/srand.3 new file mode 100644 index 0000000..b007c2f --- /dev/null +++ b/man/man3/srand.3 @@ -0,0 +1 @@ +.so man3/rand.3 diff --git a/man/man3/srand48.3 b/man/man3/srand48.3 new file mode 100644 index 0000000..3133f7d --- /dev/null +++ b/man/man3/srand48.3 @@ -0,0 +1 @@ +.so man3/drand48.3 diff --git a/man/man3/srand48_r.3 b/man/man3/srand48_r.3 new file mode 100644 index 0000000..81e9d8e --- /dev/null +++ b/man/man3/srand48_r.3 @@ -0,0 +1 @@ +.so man3/drand48_r.3 diff --git a/man/man3/srandom.3 b/man/man3/srandom.3 new file mode 100644 index 0000000..6e34104 --- /dev/null +++ b/man/man3/srandom.3 @@ -0,0 +1 @@ +.so man3/random.3 diff --git a/man/man3/srandom_r.3 b/man/man3/srandom_r.3 new file mode 100644 index 0000000..b01937f --- /dev/null +++ b/man/man3/srandom_r.3 @@ -0,0 +1 @@ +.so man3/random_r.3 diff --git a/man/man3/sscanf.3 b/man/man3/sscanf.3 new file mode 100644 index 0000000..46eef25 --- /dev/null +++ b/man/man3/sscanf.3 @@ -0,0 +1,730 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)scanf.3 6.14 (Berkeley) 1/8/93 +.\" +.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu +.\" modified to resemble the GNU libio setup used in the Linux libc +.\" used in versions 4.x (x>4) and 5 Helmut.Geyer@iwr.uni-heidelberg.de +.\" Modified, aeb, 970121 +.\" 2005-07-14, mtk, added description of %n$ form; various text +.\" incorporated from the GNU C library documentation ((C) The +.\" Free Software Foundation); other parts substantially rewritten. +.\" +.\" 2008-06-23, mtk +.\" Add ERRORS section. +.\" Document the 'a' and 'm' modifiers for dynamic string allocation. +.\" +.TH sscanf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sscanf, vsscanf \- input string format conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int sscanf(const char *restrict " str , +.BI " const char *restrict " format ", ...);" +.P +.B #include +.P +.BI "int vsscanf(const char *restrict " str , +.BI " const char *restrict " format ", va_list " ap ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR vsscanf (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR sscanf () +family of functions scans formatted input according to +.I format +as described below. +This format may contain +.IR "conversion specifications" ; +the results from such conversions, if any, +are stored in the locations pointed to by the +.I pointer +arguments that follow +.IR format . +Each +.I pointer +argument must be of a type that is appropriate for the value returned +by the corresponding conversion specification. +.P +If the number of conversion specifications in +.I format +exceeds the number of +.I pointer +arguments, the results are undefined. +If the number of +.I pointer +arguments exceeds the number of conversion specifications, then the excess +.I pointer +arguments are evaluated, but are otherwise ignored. +.P +.BR sscanf () +These functions +read their input from the string pointed to by +.IR str . +.P +The +.BR vsscanf () +function is analogous to +.BR vsprintf (3). +.P +The +.I format +string consists of a sequence of +.I directives +which describe how to process the sequence of input characters. +If processing of a directive fails, no further input is read, and +.BR sscanf () +returns. +A "failure" can be either of the following: +.IR "input failure" , +meaning that input characters were unavailable, or +.IR "matching failure" , +meaning that the input was inappropriate (see below). +.P +A directive is one of the following: +.TP +\[bu] +A sequence of white-space characters (space, tab, newline, etc.; see +.BR isspace (3)). +This directive matches any amount of white space, +including none, in the input. +.TP +\[bu] +An ordinary character (i.e., one other than white space or \[aq]%\[aq]). +This character must exactly match the next character of input. +.TP +\[bu] +A conversion specification, +which commences with a \[aq]%\[aq] (percent) character. +A sequence of characters from the input is converted according to +this specification, and the result is placed in the corresponding +.I pointer +argument. +If the next item of input does not match the conversion specification, +the conversion fails\[em]this is a +.IR "matching failure" . +.P +Each +.I conversion specification +in +.I format +begins with either the character \[aq]%\[aq] or the character sequence +"\fB%\fP\fIn\fP\fB$\fP" +(see below for the distinction) followed by: +.TP +\[bu] +An optional \[aq]*\[aq] assignment-suppression character: +.BR sscanf () +reads input as directed by the conversion specification, +but discards the input. +No corresponding +.I pointer +argument is required, and this specification is not +included in the count of successful assignments returned by +.BR scanf (). +.TP +\[bu] +For decimal conversions, an optional quote character (\[aq]). +This specifies that the input number may include thousands' +separators as defined by the +.B LC_NUMERIC +category of the current locale. +(See +.BR setlocale (3).) +The quote character may precede or follow the \[aq]*\[aq] +assignment-suppression character. +.TP +\[bu] +An optional \[aq]m\[aq] character. +This is used with string conversions +.RI ( %s , +.IR %c , +.IR %[ ), +and relieves the caller of the +need to allocate a corresponding buffer to hold the input: instead, +.BR sscanf () +allocates a buffer of sufficient size, +and assigns the address of this buffer to the corresponding +.I pointer +argument, which should be a pointer to a +.I "char\ *" +variable (this variable does not need to be initialized before the call). +The caller should subsequently +.BR free (3) +this buffer when it is no longer required. +.TP +\[bu] +An optional decimal integer which specifies the +.IR "maximum field width" . +Reading of characters stops either when this maximum is reached or +when a nonmatching character is found, whichever happens first. +Most conversions discard initial white space characters (the exceptions +are noted below), +and these discarded characters don't count toward the maximum field width. +String input conversions store a terminating null byte (\[aq]\e0\[aq]) +to mark the end of the input; +the maximum field width does not include this terminator. +.TP +\[bu] +An optional +.IR "type modifier character" . +For example, the +.B l +type modifier is used with integer conversions such as +.B %d +to specify that the corresponding +.I pointer +argument refers to a +.I "long" +rather than a pointer to an +.IR int . +.TP +\[bu] +A +.I "conversion specifier" +that specifies the type of input conversion to be performed. +.P +The conversion specifications in +.I format +are of two forms, either beginning with \[aq]%\[aq] or beginning with +"\fB%\fP\fIn\fP\fB$\fP". +The two forms should not be mixed in the same +.I format +string, except that a string containing +"\fB%\fP\fIn\fP\fB$\fP" +specifications can include +.B %% +and +.BR %* . +If +.I format +contains \[aq]%\[aq] +specifications, then these correspond in order with successive +.I pointer +arguments. +In the +"\fB%\fP\fIn\fP\fB$\fP" +form (which is specified in POSIX.1-2001, but not C99), +.I n +is a decimal integer that specifies that the converted input should +be placed in the location referred to by the +.IR n -th +.I pointer +argument following +.IR format . +.SS Conversions +The following +.I "type modifier characters" +can appear in a conversion specification: +.TP +.B h +Indicates that the conversion will be one of +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP +and the next pointer is a pointer to a +.I short +or +.I unsigned short +(rather than +.IR int ). +.TP +.B hh +As for +.BR h , +but the next pointer is a pointer to a +.I signed char +or +.IR "unsigned char" . +.TP +.B j +As for +.BR h , +but the next pointer is a pointer to an +.I intmax_t +or a +.IR uintmax_t . +This modifier was introduced in C99. +.TP +.B l +Indicates either that the conversion will be one of +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, \fBX\fP, or \fBn\fP +and the next pointer is a pointer to a +.I long +or +.I unsigned long +(rather than +.IR int ), +or that the conversion will be one of +\fBe\fP, \fBf\fP, or \fBg\fP +and the next pointer is a pointer to +.I double +(rather than +.IR float ). +If used with +.B %c +or +.BR %s , +the corresponding parameter is considered +as a pointer to a wide character or wide-character string respectively. +.\" This use of l was introduced in Amendment 1 to ISO C90. +.TP +.B ll +(ell-ell) +Indicates that the conversion will be one of +.BR b , +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.B n +and the next pointer is a pointer to a +.I long long +or +.I unsigned long long +(rather than +.IR int ). +.TP +.B L +Indicates that the conversion will be either +\fBe\fP, \fBf\fP, or \fBg\fP +and the next pointer is a pointer to +.I "long double" +or +(as a GNU extension) +the conversion will be +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, or \fBx\fP +and the next pointer is a pointer to +.IR "long long" . +.\" MTK, Jul 05: The following is no longer true for modern +.\" ANSI C (i.e., C99): +.\" (Note that long long is not an +.\" ANSI C +.\" type. Any program using this will not be portable to all +.\" architectures). +.TP +.B q +equivalent to +.BR L . +This specifier does not exist in ANSI C. +.TP +.B t +As for +.BR h , +but the next pointer is a pointer to a +.IR ptrdiff_t . +This modifier was introduced in C99. +.TP +.B z +As for +.BR h , +but the next pointer is a pointer to a +.IR size_t . +This modifier was introduced in C99. +.P +The following +.I "conversion specifiers" +are available: +.TP +.B % +Matches a literal \[aq]%\[aq]. +That is, +.B %\&% +in the format string matches a +single input \[aq]%\[aq] character. +No conversion is done (but initial white space characters are discarded), +and assignment does not occur. +.TP +.B d +Matches an optionally signed decimal integer; +the next pointer must be a pointer to +.IR int . +.\" .TP +.\" .B D +.\" Equivalent to +.\" .IR ld ; +.\" this exists only for backward compatibility. +.\" (Note: thus only in libc4 +.\" In libc5 and glibc the +.\" .B %D +.\" is silently ignored, causing old programs to fail mysteriously.) +.TP +.B i +Matches an optionally signed integer; the next pointer must be a pointer to +.IR int . +The integer is read in base 16 if it begins with +.I 0x +or +.IR 0X , +in base 8 if it begins with +.IR 0 , +and in base 10 otherwise. +Only characters that correspond to the base are used. +.TP +.B o +Matches an unsigned octal integer; the next pointer must be a pointer to +.IR "unsigned int" . +.TP +.B u +Matches an unsigned decimal integer; the next pointer must be a +pointer to +.IR "unsigned int" . +.TP +.B x +Matches an unsigned hexadecimal integer +(that may optionally begin with a prefix of +.I 0x +or +.IR 0X , +which is discarded); the next pointer must +be a pointer to +.IR "unsigned int" . +.TP +.B X +Equivalent to +.BR x . +.TP +.B f +Matches an optionally signed floating-point number; the next pointer must +be a pointer to +.IR float . +.TP +.B e +Equivalent to +.BR f . +.TP +.B g +Equivalent to +.BR f . +.TP +.B E +Equivalent to +.BR f . +.TP +.B a +(C99) Equivalent to +.BR f . +.TP +.B s +Matches a sequence of non-white-space characters; +the next pointer must be a pointer to the initial element of a +character array that is long enough to hold the input sequence and +the terminating null byte (\[aq]\e0\[aq]), which is added automatically. +The input string stops at white space or at the maximum field +width, whichever occurs first. +.TP +.B c +Matches a sequence of characters whose length is specified by the +.I maximum field width +(default 1); the next pointer must be a pointer to +.IR char , +and there must be enough room for all the characters +(no terminating null byte is added). +The usual skip of leading white space is suppressed. +To skip white space first, use an explicit space in the format. +.TP +.B \&[ +Matches a nonempty sequence of characters from the specified set of +accepted characters; the next pointer must be a pointer to +.IR char , +and there must be enough room for all the characters in the string, plus a +terminating null byte. +The usual skip of leading white space is suppressed. +The string is to be made up of characters in (or not in) a particular set; +the set is defined by the characters between the open bracket +.B [ +character and a close bracket +.B ] +character. +The set +.I excludes +those characters if the first character after the open bracket is a +circumflex +.RB ( \[ha] ). +To include a close bracket in the set, make it the first character after +the open bracket or the circumflex; any other position will end the set. +The hyphen character +.B \- +is also special; when placed between two other characters, it adds all +intervening characters to the set. +To include a hyphen, make it the last +character before the final close bracket. +For instance, +.B [\[ha]]0\-9\-] +means +the set "everything except close bracket, zero through nine, and hyphen". +The string ends with the appearance of a character not in the (or, with a +circumflex, in) set or when the field width runs out. +.TP +.B p +Matches a pointer value (as printed by +.B %p +in +.BR printf (3)); +the next pointer must be a pointer to a pointer to +.IR void . +.TP +.B n +Nothing is expected; instead, the number of characters consumed thus far +from the input is stored through the next pointer, which must be a pointer +to +.IR int , +or variant whose size matches the (optionally) +supplied integer length modifier. +This is +.I not +a conversion and does +.I not +increase the count returned by the function. +The assignment can be suppressed with the +.B * +assignment-suppression character, but the effect on the +return value is undefined. +Therefore +.B %*n +conversions should not be used. +.SH RETURN VALUE +On success, these functions return the number of input items +successfully matched and assigned; +this can be fewer than provided for, +or even zero, in the event of an early matching failure. +.P +The value +.B EOF +is returned if the end of input is reached before either the first +successful conversion or a matching failure occurs. +.SH ERRORS +.TP +.B EILSEQ +Input byte sequence does not form a valid character. +.TP +.B EINVAL +Not enough arguments; or +.I format +is NULL. +.TP +.B ENOMEM +Out of memory. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sscanf (), +.BR vsscanf () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.P +The +.B q +specifier is the 4.4BSD notation for +.IR "long long" , +while +.B ll +or the usage of +.B L +in integer conversions is the GNU notation. +.P +The Linux version of these functions is based on the +.I GNU +.I libio +library. +Take a look at the +.I info +documentation of +.I GNU +.I libc (glibc-1.08) +for a more concise description. +.SH NOTES +.SS The 'a' assignment-allocation modifier +Originally, the GNU C library supported dynamic allocation for string inputs +(as a nonstandard extension) via the +.B a +character. +(This feature is present at least as far back as glibc 2.0.) +Thus, one could write the following to have +.BR sscanf () +allocate a buffer for a string, +with a pointer to that buffer being returned in +.IR *buf : +.P +.in +4n +.EX +char *buf; +sscanf(str, "%as", &buf); +.EE +.in +.P +The use of the letter +.B a +for this purpose was problematic, since +.B a +is also specified by the ISO C standard as a synonym for +.B f +(floating-point input). +POSIX.1-2008 instead specifies the +.B m +modifier for assignment allocation (as documented in DESCRIPTION, above). +.P +Note that the +.B a +modifier is not available if the program is compiled with +.I gcc\~\-std=c99 +or +.I gcc\~\-D_ISOC99_SOURCE +(unless +.B _GNU_SOURCE +is also specified), in which case the +.B a +is interpreted as a specifier for floating-point numbers (see above). +.P +Support for the +.B m +modifier was added to glibc 2.7, +and new programs should use that modifier instead of +.BR a . +.P +As well as being standardized by POSIX, the +.B m +modifier has the following further advantages over +the use of +.BR a : +.IP \[bu] 3 +It may also be applied to +.B %c +conversion specifiers (e.g., +.BR %3mc ). +.IP \[bu] +It avoids ambiguity with respect to the +.B %a +floating-point conversion specifier (and is unaffected by +.I gcc\~\-std=c99 +etc.). +.SH BUGS +.SS Numeric conversion specifiers +Use of the numeric conversion specifiers produces Undefined Behavior +for invalid input. +See +.UR https://port70.net/\:%7Ensz/\:c/\:c11/\:n1570.html\:#7.21.6.2p10 +C11 7.21.6.2/10 +.UE . +This is a bug in the ISO C standard, +and not an inherent design issue with the API. +However, +current implementations are not safe from that bug, +so it is not recommended to use them. +Instead, +programs should use functions such as +.BR strtol (3) +to parse numeric input. +Alternatively, +mitigate it by specifying a maximum field width. +.SS Nonstandard modifiers +These functions are fully C99 conformant, but provide the +additional modifiers +.B q +and +.B a +as well as an additional behavior of the +.B L +and +.B ll +modifiers. +The latter may be considered to be a bug, as it changes the +behavior of modifiers defined in C99. +.P +Some combinations of the type modifiers and conversion +specifiers defined by C99 do not make sense +(e.g., +.BR "%Ld" ). +While they may have a well-defined behavior on Linux, this need not +to be so on other architectures. +Therefore it usually is better to use +modifiers that are not defined by C99 at all, that is, use +.B q +instead of +.B L +in combination with +\fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, and \fBX\fP +conversions or +.BR ll . +.P +The usage of +.B q +is not the same as on 4.4BSD, +as it may be used in float conversions equivalently to +.BR L . +.SH EXAMPLES +To use the dynamic allocation conversion specifier, specify +.B m +as a length modifier (thus +.B %ms +or +\fB%m[\fP\fIrange\fP\fB]\fP). +The caller must +.BR free (3) +the returned string, as in the following example: +.P +.in +4n +.EX +char *p; +int n; +\& +errno = 0; +n = sscanf(str, "%m[a\-z]", &p); +if (n == 1) { + printf("read: %s\en", p); + free(p); +} else if (errno != 0) { + perror("sscanf"); +} else { + fprintf(stderr, "No matching characters\en"); +} +.EE +.in +.P +As shown in the above example, it is necessary to call +.BR free (3) +only if the +.BR sscanf () +call successfully read a string. +.SH SEE ALSO +.BR getc (3), +.BR printf (3), +.BR setlocale (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man/man3/ssignal.3 b/man/man3/ssignal.3 new file mode 100644 index 0000000..047cab2 --- /dev/null +++ b/man/man3/ssignal.3 @@ -0,0 +1 @@ +.so man3/gsignal.3 diff --git a/man/man3/stailq.3 b/man/man3/stailq.3 new file mode 100644 index 0000000..2441dcf --- /dev/null +++ b/man/man3/stailq.3 @@ -0,0 +1,377 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH STAILQ 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +.\"SIMPLEQ_CONCAT, +SIMPLEQ_EMPTY, +SIMPLEQ_ENTRY, +SIMPLEQ_FIRST, +SIMPLEQ_FOREACH, +.\"SIMPLEQ_FOREACH_FROM, +.\"SIMPLEQ_FOREACH_FROM_SAFE, +.\"SIMPLEQ_FOREACH_SAFE, +SIMPLEQ_HEAD, +SIMPLEQ_HEAD_INITIALIZER, +SIMPLEQ_INIT, +SIMPLEQ_INSERT_AFTER, +SIMPLEQ_INSERT_HEAD, +SIMPLEQ_INSERT_TAIL, +.\"SIMPLEQ_LAST, +SIMPLEQ_NEXT, +SIMPLEQ_REMOVE, +.\"SIMPLEQ_REMOVE_AFTER, +SIMPLEQ_REMOVE_HEAD, +.\"SIMPLEQ_SWAP, +STAILQ_CONCAT, +STAILQ_EMPTY, +STAILQ_ENTRY, +STAILQ_FIRST, +STAILQ_FOREACH, +.\"STAILQ_FOREACH_FROM, +.\"STAILQ_FOREACH_FROM_SAFE, +.\"STAILQ_FOREACH_SAFE, +STAILQ_HEAD, +STAILQ_HEAD_INITIALIZER, +STAILQ_INIT, +STAILQ_INSERT_AFTER, +STAILQ_INSERT_HEAD, +STAILQ_INSERT_TAIL, +.\"STAILQ_LAST, +STAILQ_NEXT, +STAILQ_REMOVE, +.\"STAILQ_REMOVE_AFTER, +STAILQ_REMOVE_HEAD, +.\"STAILQ_SWAP +\- implementation of a singly linked tail queue +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B STAILQ_ENTRY(TYPE); +.P +.B STAILQ_HEAD(HEADNAME, TYPE); +.BI "STAILQ_HEAD STAILQ_HEAD_INITIALIZER(STAILQ_HEAD " head ); +.BI "void STAILQ_INIT(STAILQ_HEAD *" head ); +.P +.BI "int STAILQ_EMPTY(STAILQ_HEAD *" head ); +.P +.BI "void STAILQ_INSERT_HEAD(STAILQ_HEAD *" head , +.BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME ); +.BI "void STAILQ_INSERT_TAIL(STAILQ_HEAD *" head , +.BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME ); +.BI "void STAILQ_INSERT_AFTER(STAILQ_HEAD *" head ", struct TYPE *" listelm , +.BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME ); +.P +.BI "struct TYPE *STAILQ_FIRST(STAILQ_HEAD *" head ); +.\" .BI "struct TYPE *STAILQ_LAST(STAILQ_HEAD *" head ", struct TYPE *" elm , +.\" .BI " STAILQ_ENTRY " NAME ); +.BI "struct TYPE *STAILQ_NEXT(struct TYPE *" elm ", STAILQ_ENTRY " NAME ); +.P +.BI "STAILQ_FOREACH(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ); +.\" .BI "STAILQ_FOREACH_FROM(struct TYPE *" var ", STAILQ_HEAD *" head , +.\" .BI " STAILQ_ENTRY " NAME ); +.\" .P +.\" .BI "STAILQ_FOREACH_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head , +.\" .BI " STAILQ_ENTRY " NAME ", struct TYPE *" temp_var ); +.\" .BI "STAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head , +.\" .BI " STAILQ_ENTRY " NAME ", struct TYPE *" temp_var ); +.P +.BI "void STAILQ_REMOVE(STAILQ_HEAD *" head ", struct TYPE *" elm ", TYPE," +.BI " STAILQ_ENTRY " NAME ); +.BI "void STAILQ_REMOVE_HEAD(STAILQ_HEAD *" head , +.BI " STAILQ_ENTRY " NAME ); +.\" .BI "void STAILQ_REMOVE_AFTER(STAILQ_HEAD *" head ", struct TYPE *" elm , +.\" .BI " STAILQ_ENTRY " NAME ); +.P +.BI "void STAILQ_CONCAT(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 ); +.\" .BI "void STAILQ_SWAP(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 , +.\" .BI " STAILQ_ENTRY " NAME ); +.fi +.IR Note : +Identical macros prefixed with SIMPLEQ instead of STAILQ exist; see NOTES. +.SH DESCRIPTION +These macros define and operate on singly linked tail queues. +.P +In the macro definitions, +.I TYPE +is the name of a user-defined structure, +that must contain a field of type +.IR STAILQ_ENTRY , +named +.IR NAME . +The argument +.I HEADNAME +is the name of a user-defined structure that must be declared +using the macro +.BR STAILQ_HEAD (). +.SS Creation +A singly linked tail queue is headed by a structure defined by the +.BR STAILQ_HEAD () +macro. +This structure contains a pair of pointers, +one to the first element in the tail queue and the other to +the last element in the tail queue. +The elements are singly linked for minimum space and pointer +manipulation overhead at the expense of O(n) removal for arbitrary elements. +New elements can be added to the tail queue after an existing element, +at the head of the tail queue, or at the end of the tail queue. +A +.I STAILQ_HEAD +structure is declared as follows: +.P +.in +4 +.EX +STAILQ_HEAD(HEADNAME, TYPE) head; +.EE +.in +.P +where +.I struct HEADNAME +is the structure to be defined, and +.I struct TYPE +is the type of the elements to be linked into the tail queue. +A pointer to the head of the tail queue can later be declared as: +.P +.in +4 +.EX +struct HEADNAME *headp; +.EE +.in +.P +(The names +.I head +and +.I headp +are user selectable.) +.P +.BR STAILQ_ENTRY () +declares a structure that connects the elements in the tail queue. +.P +.BR STAILQ_HEAD_INITIALIZER () +evaluates to an initializer for the tail queue +.IR head . +.P +.BR STAILQ_INIT () +initializes the tail queue referenced by +.IR head . +.P +.BR STAILQ_EMPTY () +evaluates to true if there are no items on the tail queue. +.SS Insertion +.BR STAILQ_INSERT_HEAD () +inserts the new element +.I elm +at the head of the tail queue. +.P +.BR STAILQ_INSERT_TAIL () +inserts the new element +.I elm +at the end of the tail queue. +.P +.BR STAILQ_INSERT_AFTER () +inserts the new element +.I elm +after the element +.IR listelm . +.SS Traversal +.BR STAILQ_FIRST () +returns the first item on the tail queue or NULL if the tail queue is empty. +.\" .P +.\" .BR STAILQ_LAST () +.\" returns the last item on the tail queue. +.\" If the tail queue is empty the return value is NULL . +.P +.BR STAILQ_NEXT () +returns the next item on the tail queue, or NULL this item is the last. +.P +.BR STAILQ_FOREACH () +traverses the tail queue referenced by +.I head +in the forward direction, +assigning each element in turn to +.IR var . +.\" .P +.\" .BR STAILQ_FOREACH_FROM () +.\" behaves identically to +.\" .BR STAILQ_FOREACH () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found STAILQ element and begins the loop at +.\" .I var +.\" instead of the first element in the STAILQ referenced by +.\" .IR head . +.\" .P +.\" .BR STAILQ_FOREACH_SAFE () +.\" traverses the tail queue referenced by +.\" .I head +.\" in the forward direction, assigning each element +.\" in turn to +.\" .IR var . +.\" However, unlike +.\" .BR STAILQ_FOREACH () +.\" here it is permitted to both remove +.\" .I var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .P +.\" .BR STAILQ_FOREACH_FROM_SAFE () +.\" behaves identically to +.\" .BR STAILQ_FOREACH_SAFE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found STAILQ element and begins the loop at +.\" .I var +.\" instead of the first element in the STAILQ referenced by +.\" .IR head . +.SS Removal +.BR STAILQ_REMOVE () +removes the element +.I elm +from the tail queue. +.P +.BR STAILQ_REMOVE_HEAD () +removes the element at the head of the tail queue. +For optimum efficiency, +elements being removed from the head of the tail queue should +use this macro explicitly rather than the generic +.BR STAILQ_REMOVE () +macro. +.\" .P +.\" .BR STAILQ_REMOVE_AFTER () +.\" removes the element after +.\" .I elm +.\" from the tail queue. +.\" Unlike +.\" .BR STAILQ_REMOVE (), +.\" this macro does not traverse the entire tail queue. +.SS Other features +.BR STAILQ_CONCAT () +concatenates the tail queue headed by +.I head2 +onto the end of the one headed by +.I head1 +removing all entries from the former. +.\" .P +.\" .BR STAILQ_SWAP () +.\" swaps the contents of +.\" .I head1 +.\" and +.\" .IR head2 . +.SH RETURN VALUE +.BR STAILQ_EMPTY () +returns nonzero if the queue is empty, +and zero if the queue contains at least one entry. +.P +.BR STAILQ_FIRST (), +and +.BR STAILQ_NEXT () +return a pointer to the first or next +.I TYPE +structure, respectively. +.P +.BR STAILQ_HEAD_INITIALIZER () +returns an initializer that can be assigned to the queue +.IR head . +.SH VERSIONS +Some BSDs provide SIMPLEQ instead of STAILQ. +They are identical, but for historical reasons +they were named differently on different BSDs. +STAILQ originated on FreeBSD, and SIMPLEQ originated on NetBSD. +For compatibility reasons, some systems provide both sets of macros. +glibc provides both STAILQ and SIMPLEQ, +which are identical except for a missing SIMPLEQ equivalent to +.BR STAILQ_CONCAT (). +.SH BUGS +.BR STAILQ_FOREACH () +doesn't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +.BR STAILQ_FOREACH_SAFE (), +which is present on the BSDs but is not present in glibc, +fixes this limitation by allowing +.I var +to safely be removed from the list and freed from within the loop +without interfering with the traversal. +.SH STANDARDS +BSD. +.SH HISTORY +4.4BSD. +.SH EXAMPLES +.\" SRC BEGIN (stailq.c) +.EX +#include +#include +#include +#include +\& +struct entry { + int data; + STAILQ_ENTRY(entry) entries; /* Singly linked tail queue */ +}; +\& +STAILQ_HEAD(stailhead, entry); +\& +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct stailhead head; /* Singly linked tail queue + head */ +\& + STAILQ_INIT(&head); /* Initialize the queue */ +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the head */ + STAILQ_INSERT_HEAD(&head, n1, entries); +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the tail */ + STAILQ_INSERT_TAIL(&head, n1, entries); +\& + n2 = malloc(sizeof(struct entry)); /* Insert after */ + STAILQ_INSERT_AFTER(&head, n1, n2, entries); +\& + STAILQ_REMOVE(&head, n2, entry, entries); /* Deletion */ + free(n2); +\& + n3 = STAILQ_FIRST(&head); + STAILQ_REMOVE_HEAD(&head, entries); /* Deletion from the head */ + free(n3); +\& + n1 = STAILQ_FIRST(&head); + n1\->data = 0; + for (unsigned int i = 1; i < 5; i++) { + n1 = malloc(sizeof(struct entry)); + STAILQ_INSERT_HEAD(&head, n1, entries); + n1\->data = i; + } + /* Forward traversal */ + STAILQ_FOREACH(np, &head, entries) + printf("%i\en", np\->data); + /* TailQ deletion */ + n1 = STAILQ_FIRST(&head); + while (n1 != NULL) { + n2 = STAILQ_NEXT(n1, entries); + free(n1); + n1 = n2; + } + STAILQ_INIT(&head); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR insque (3), +.BR queue (7) diff --git a/man/man3/static_assert.3 b/man/man3/static_assert.3 new file mode 100644 index 0000000..ee83779 --- /dev/null +++ b/man/man3/static_assert.3 @@ -0,0 +1,119 @@ +.\" Copyright (c) 2022 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH static_assert 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +static_assert, _Static_assert \- fail compilation if assertion is false +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void static_assert(scalar " constant-expression ", const char *" msg ); +.P +/* Since C23: */ +.BI "void static_assert(scalar " constant-expression ); +.fi +.SH DESCRIPTION +This macro is similar to +.BR \%assert (3), +but it works at compile time, +generating a compilation error (with an optional message) +when the input is false (i.e., compares equal to zero). +.P +If the input is nonzero, +no code is emitted. +.P +.I msg +must be a string literal. +Since C23, this argument is optional. +.P +There's a keyword, +.BR \%_Static_assert (), +that behaves identically, +and can be used without including +.IR . +.SH RETURN VALUE +No value is returned. +.SH VERSIONS +In C11, +the second argument +.RI ( msg ) +was mandatory; +since C23, +it can be omitted. +.SH STANDARDS +C11 and later. +.SH EXAMPLES +.BR static_assert () +can't be used in some places, +like for example at global scope. +For that, +a macro +.BR \%must_be () +can be written in terms of +.BR \%static_assert (). +The following program uses the macro to get the size of an array safely. +.P +.in +4n +.\" SRC BEGIN (must_be.c) +.EX +#include +#include +#include +#include +#include +#include +\& +/* + * This macro behaves like static_assert(), failing to + * compile if its argument is not true. However, it always + * returns 0, which allows using it everywhere an expression + * can be used. + */ +#define must_be(e) \e +( \e + 0 * (int) sizeof( \e + struct { \e + static_assert(e); \e + int ISO_C_forbids_a_struct_with_no_members; \e + } \e + ) \e +) +\& +#define is_same_type(a, b) \e + __builtin_types_compatible_p(typeof(a), typeof(b)) +\& +#define is_array(arr) (!is_same_type((arr), &*(arr))) +#define must_be_array(arr) must_be(is_array(arr)) +\& +#define sizeof_array(arr) (sizeof(arr) + must_be_array(arr)) +#define nitems(arr) (sizeof((arr)) / sizeof((arr)[0]) \e + + must_be_array(arr)) +\& +int foo[10]; +int8_t bar[sizeof_array(foo)]; +\& +int +main(void) +{ + for (size_t i = 0; i < nitems(foo); i++) { + foo[i] = i; + } +\& + memcpy(bar, foo, sizeof_array(bar)); +\& + for (size_t i = 0; i < nitems(bar); i++) { + printf("%d,", bar[i]); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR assert (3) diff --git a/man/man3/statvfs.3 b/man/man3/statvfs.3 new file mode 100644 index 0000000..15b4f86 --- /dev/null +++ b/man/man3/statvfs.3 @@ -0,0 +1,256 @@ +'\" t +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" The pathconf note is from Walter Harms +.\" This is not a system call on Linux +.\" +.\" Modified 2004-06-23 by Michael Kerrisk +.\" +.TH statvfs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +statvfs, fstatvfs \- get filesystem statistics +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int statvfs(const char *restrict " path \ +", struct statvfs *restrict " buf ); +.BI "int fstatvfs(int " fd ", struct statvfs *" buf ); +.fi +.SH DESCRIPTION +The function +.BR statvfs () +returns information about a mounted filesystem. +.I path +is the pathname of any file within the mounted filesystem. +.I buf +is a pointer to a +.I statvfs +structure defined approximately as follows: +.P +.in +4n +.EX +struct statvfs { + unsigned long f_bsize; /* Filesystem block size */ + unsigned long f_frsize; /* Fragment size */ + fsblkcnt_t f_blocks; /* Size of fs in f_frsize units */ + fsblkcnt_t f_bfree; /* Number of free blocks */ + fsblkcnt_t f_bavail; /* Number of free blocks for + unprivileged users */ + fsfilcnt_t f_files; /* Number of inodes */ + fsfilcnt_t f_ffree; /* Number of free inodes */ + fsfilcnt_t f_favail; /* Number of free inodes for + unprivileged users */ + unsigned long f_fsid; /* Filesystem ID */ + unsigned long f_flag; /* Mount flags */ + unsigned long f_namemax; /* Maximum filename length */ +}; +.EE +.in +.P +Here the types +.I fsblkcnt_t +and +.I fsfilcnt_t +are defined in +.IR . +Both used to be +.IR "unsigned long" . +.P +The field +.I f_flag +is a bit mask indicating various options that were employed +when mounting this filesystem. +It contains zero or more of the following flags: +.\" XXX Keep this list in sync with statfs(2) +.TP +.B ST_MANDLOCK +Mandatory locking is permitted on the filesystem (see +.BR fcntl (2)). +.TP +.B ST_NOATIME +Do not update access times; see +.BR mount (2). +.TP +.B ST_NODEV +Disallow access to device special files on this filesystem. +.TP +.B ST_NODIRATIME +Do not update directory access times; see +.BR mount (2). +.TP +.B ST_NOEXEC +Execution of programs is disallowed on this filesystem. +.TP +.B ST_NOSUID +The set-user-ID and set-group-ID bits are ignored by +.BR exec (3) +for executable files on this filesystem +.TP +.B ST_RDONLY +This filesystem is mounted read-only. +.TP +.B ST_RELATIME +Update atime relative to mtime/ctime; see +.BR mount (2). +.TP +.B ST_SYNCHRONOUS +Writes are synched to the filesystem immediately (see the description of +.B O_SYNC +in +.BR open (2)). +.P +It is unspecified whether all members of the returned struct +have meaningful values on all filesystems. +.P +.BR fstatvfs () +returns the same information about an open file referenced by descriptor +.IR fd . +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +.RB ( statvfs ()) +Search permission is denied for a component of the path prefix of +.IR path . +(See also +.BR path_resolution (7).) +.TP +.B EBADF +.RB ( fstatvfs ()) +.I fd +is not a valid open file descriptor. +.TP +.B EFAULT +.I Buf +or +.I path +points to an invalid address. +.TP +.B EINTR +This call was interrupted by a signal; see +.BR signal (7). +.TP +.B EIO +An I/O error occurred while reading from the filesystem. +.TP +.B ELOOP +.RB ( statvfs ()) +Too many symbolic links were encountered in translating +.IR path . +.TP +.B ENAMETOOLONG +.RB ( statvfs ()) +.I path +is too long. +.TP +.B ENOENT +.RB ( statvfs ()) +The file referred to by +.I path +does not exist. +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOSYS +The filesystem does not support this call. +.TP +.B ENOTDIR +.RB ( statvfs ()) +A component of the path prefix of +.I path +is not a directory. +.TP +.B EOVERFLOW +Some values were too large to be represented in the returned struct. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR statvfs (), +.BR fstatvfs () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Only the +.B ST_NOSUID +and +.B ST_RDONLY +flags of the +.I f_flag +field are specified in POSIX.1. +To obtain definitions of the remaining flags, one must define +.BR _GNU_SOURCE . +.SH NOTES +The Linux kernel has system calls +.BR statfs (2) +and +.BR fstatfs (2) +to support this library call. +.P +The glibc implementations of +.P +.in +4n +.EX +pathconf(path, _PC_REC_XFER_ALIGN); +pathconf(path, _PC_ALLOC_SIZE_MIN); +pathconf(path, _PC_REC_MIN_XFER_SIZE); +.EE +.in +.P +respectively use the +.IR f_frsize , +.IR f_frsize , +and +.I f_bsize +fields returned by a call to +.BR statvfs () +with the argument +.IR path . +.P +Under Linux, +.I f_favail +is always the same as +.IR f_ffree , +and there's no way for a filesystem to report otherwise. +This is not an issue, +since no filesystems with an inode root reservation exist. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Before glibc 2.13, +.\" glibc commit 3cdaa6adb113a088fdfb87aa6d7747557eccc58d +.BR statvfs () +populated the bits of the +.I f_flag +field by scanning the mount options shown in +.IR /proc/mounts . +However, starting with Linux 2.6.36, the underlying +.BR statfs (2) +system call provides the necessary information via the +.I f_flags +field, and since glibc 2.13, the +.BR statvfs () +function will use information from that field rather than scanning +.IR /proc/mounts . +.SH SEE ALSO +.BR statfs (2) diff --git a/man/man3/stdarg.3 b/man/man3/stdarg.3 new file mode 100644 index 0000000..40f6cc9 --- /dev/null +++ b/man/man3/stdarg.3 @@ -0,0 +1,297 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)stdarg.3 6.8 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 15:11:11 1993, faith@cs.unc.edu +.\" Additions, 2001-10-14, aeb +.\" +.TH stdarg 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stdarg, va_start, va_arg, va_end, va_copy \- variable argument lists +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void va_start(va_list " ap ", " last ); +.IB type " va_arg(va_list " ap ", " type ); +.BI "void va_end(va_list " ap ); +.BI "void va_copy(va_list " dest ", va_list " src ); +.fi +.SH DESCRIPTION +A function may be called with a varying number of arguments of varying +types. +The include file +.I +declares a type +.I va_list +and defines three macros for stepping through a list of arguments whose +number and types are not known to the called function. +.P +The called function must declare an object of type +.I va_list +which is used by the macros +.BR va_start (), +.BR va_arg (), +and +.BR va_end (). +.SS va_start() +The +.BR va_start () +macro initializes +.I ap +for subsequent use by +.BR va_arg () +and +.BR va_end (), +and must be called first. +.P +The argument +.I last +is the name of the last argument before the variable argument list, that is, +the last argument of which the calling function knows the type. +.P +Because the address of this argument may be used in the +.BR va_start () +macro, it should not be declared as a register variable, +or as a function or an array type. +.SS va_arg() +The +.BR va_arg () +macro expands to an expression that has the type and value of the next +argument in the call. +The argument +.I ap +is the +.I va_list +.I ap +initialized by +.BR va_start (). +Each call to +.BR va_arg () +modifies +.I ap +so that the next call returns the next argument. +The argument +.I type +is a type name specified so that the type of a pointer to an object that +has the specified type can be obtained simply by adding a * to +.IR type . +.P +The first use of the +.BR va_arg () +macro after that of the +.BR va_start () +macro returns the argument after +.IR last . +Successive invocations return the values of the remaining arguments. +.P +If there is no next argument, or if +.I type +is not compatible with the type of the actual next argument (as promoted +according to the default argument promotions), random errors will occur. +.P +If +.I ap +is passed to a function that uses +.BI va_arg( ap , type ), +then the value of +.I ap +is undefined after the return of that function. +.SS va_end() +Each invocation of +.BR va_start () +must be matched by a corresponding invocation of +.BR va_end () +in the same function. +After the call +.BI va_end( ap ) +the variable +.I ap +is undefined. +Multiple traversals of the list, each +bracketed by +.BR va_start () +and +.BR va_end () +are possible. +.BR va_end () +may be a macro or a function. +.SS va_copy() +The +.BR va_copy () +macro copies the (previously initialized) variable argument list +.I src +to +.IR dest . +The behavior is as if +.BR va_start () +were applied to +.I dest +with the same +.I last +argument, followed by the same number of +.BR va_arg () +invocations that was used to reach the current state of +.IR src . +.P +.\" Proposal from clive@demon.net, 1997-02-28 +An obvious implementation would have a +.I va_list +be a pointer to the stack frame of the variadic function. +In such a setup (by far the most common) there seems +nothing against an assignment +.P +.in +4n +.EX +va_list aq = ap; +.EE +.in +.P +Unfortunately, there are also systems that make it an +array of pointers (of length 1), and there one needs +.P +.in +4n +.EX +va_list aq; +*aq = *ap; +.EE +.in +.P +Finally, on systems where arguments are passed in registers, +it may be necessary for +.BR va_start () +to allocate memory, store the arguments there, and also +an indication of which argument is next, so that +.BR va_arg () +can step through the list. +Now +.BR va_end () +can free the allocated memory again. +To accommodate this situation, C99 adds a macro +.BR va_copy (), +so that the above assignment can be replaced by +.P +.in +4n +.EX +va_list aq; +va_copy(aq, ap); +\&... +va_end(aq); +.EE +.in +.P +Each invocation of +.BR va_copy () +must be matched by a corresponding invocation of +.BR va_end () +in the same function. +Some systems that do not supply +.BR va_copy () +have +.B __va_copy +instead, since that was the name used in the draft proposal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR va_start (), +.BR va_end (), +.BR va_copy () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR va_arg () +T} Thread safety MT-Safe race:ap +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR va_start () +.TQ +.BR va_arg () +.TQ +.BR va_end () +C89, POSIX.1-2001. +.TP +.BR va_copy () +C99, POSIX.1-2001. +.SH CAVEATS +Unlike the historical +.B varargs +macros, the +.B stdarg +macros do not permit programmers to code a function with no fixed +arguments. +This problem generates work mainly when converting +.B varargs +code to +.B stdarg +code, but it also creates difficulties for variadic functions that wish to +pass all of their arguments on to a function that takes a +.I va_list +argument, such as +.BR vfprintf (3). +.SH EXAMPLES +The function +.I foo +takes a string of format characters and prints out the argument associated +with each format character based on the type. +.P +.EX +#include +#include +\& +void +foo(char *fmt, ...) /* \[aq]...\[aq] is C syntax for a variadic function */ +\& +{ + va_list ap; + int d; + char c; + char *s; +\& + va_start(ap, fmt); + while (*fmt) + switch (*fmt++) { + case \[aq]s\[aq]: /* string */ + s = va_arg(ap, char *); + printf("string %s\en", s); + break; + case \[aq]d\[aq]: /* int */ + d = va_arg(ap, int); + printf("int %d\en", d); + break; + case \[aq]c\[aq]: /* char */ + /* need a cast here since va_arg only + takes fully promoted types */ + c = (char) va_arg(ap, int); + printf("char %c\en", c); + break; + } + va_end(ap); +} +.EE +.SH SEE ALSO +.BR vprintf (3), +.BR vscanf (3), +.BR vsyslog (3) diff --git a/man/man3/stderr.3 b/man/man3/stderr.3 new file mode 100644 index 0000000..752ae27 --- /dev/null +++ b/man/man3/stderr.3 @@ -0,0 +1 @@ +.so man3/stdin.3 diff --git a/man/man3/stdin.3 b/man/man3/stdin.3 new file mode 100644 index 0000000..7ffbc9a --- /dev/null +++ b/man/man3/stdin.3 @@ -0,0 +1,160 @@ +.\" From dholland@burgundy.eecs.harvard.edu Tue Mar 24 18:08:15 1998 +.\" +.\" This man page was written in 1998 by David A. Holland +.\" Polished a bit by aeb. +.\" +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" Placed in the Public Domain. +.\" %%%LICENSE_END +.\" +.\" 2005-06-16 mtk, mentioned freopen() +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH stdin 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stdin, stdout, stderr \- standard I/O streams +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "extern FILE *" stdin ; +.BI "extern FILE *" stdout ; +.BI "extern FILE *" stderr ; +.fi +.SH DESCRIPTION +Under normal circumstances every UNIX program has three streams opened +for it when it starts up, one for input, one for output, and one for +printing diagnostic or error messages. +These are typically attached to +the user's terminal (see +.BR tty (4)) +but might instead refer to files or other devices, depending on what +the parent process chose to set up. +(See also the "Redirection" section of +.BR sh (1).) +.P +The input stream is referred to as "standard input"; the output stream is +referred to as "standard output"; and the error stream is referred to +as "standard error". +These terms are abbreviated to form the symbols +used to refer to these files, namely +.IR stdin , +.IR stdout , +and +.IR stderr . +.P +Each of these symbols is a +.BR stdio (3) +macro of type pointer to +.IR FILE , +and can be used with functions like +.BR fprintf (3) +or +.BR fread (3). +.P +Since +.IR FILE s +are a buffering wrapper around UNIX file descriptors, the +same underlying files may also be accessed using the raw UNIX file +interface, that is, the functions like +.BR read (2) +and +.BR lseek (2). +.P +On program startup, the integer file descriptors +associated with the streams +.IR stdin , +.IR stdout , +and +.I stderr +are 0, 1, and 2, respectively. +The preprocessor symbols +.BR STDIN_FILENO , +.BR STDOUT_FILENO , +and +.B STDERR_FILENO +are defined with these values in +.IR . +(Applying +.BR freopen (3) +to one of these streams can change the file descriptor number +associated with the stream.) +.P +Note that mixing use of +.IR FILE s +and raw file descriptors can produce +unexpected results and should generally be avoided. +(For the masochistic among you: POSIX.1, section 8.2.3, describes +in detail how this interaction is supposed to work.) +A general rule is that file descriptors are handled in the kernel, +while stdio is just a library. +This means for example, that after an +.BR exec (3), +the child inherits all open file descriptors, but all old streams +have become inaccessible. +.P +Since the symbols +.IR stdin , +.IR stdout , +and +.I stderr +are specified to be macros, assigning to them is nonportable. +The standard streams can be made to refer to different files +with help of the library function +.BR freopen (3), +specially introduced to make it possible to reassign +.IR stdin , +.IR stdout , +and +.IR stderr . +The standard streams are closed by a call to +.BR exit (3) +and by normal program termination. +.SH STANDARDS +C11, POSIX.1-2008. +.P +The standards also stipulate that these three +streams shall be open at program startup. +.SH HISTORY +C89, POSIX.1-2001. +.SH NOTES +The stream +.I stderr +is unbuffered. +The stream +.I stdout +is line-buffered when it points to a terminal. +Partial lines will not +appear until +.BR fflush (3) +or +.BR exit (3) +is called, or a newline is printed. +This can produce unexpected +results, especially with debugging output. +The buffering mode of the standard streams (or any other stream) +can be changed using the +.BR setbuf (3) +or +.BR setvbuf (3) +call. +Note that in case +.I stdin +is associated with a terminal, there may also be input buffering +in the terminal driver, entirely unrelated to stdio buffering. +(Indeed, normally terminal input is line buffered in the kernel.) +This kernel input handling can be modified using calls like +.BR tcsetattr (3); +see also +.BR stty (1), +and +.BR termios (3). +.SH SEE ALSO +.BR csh (1), +.BR sh (1), +.BR open (2), +.BR fopen (3), +.BR stdio (3) diff --git a/man/man3/stdio.3 b/man/man3/stdio.3 new file mode 100644 index 0000000..45a8727 --- /dev/null +++ b/man/man3/stdio.3 @@ -0,0 +1,353 @@ +'\" t +.\" Copyright (c) 1990, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)stdio.3 6.5 (Berkeley) 5/6/91 +.\" +.\" Converted for Linux, Mon Nov 29 16:07:22 1993, faith@cs.unc.edu +.\" Modified, 2001-12-26, aeb +.\" +.TH stdio 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stdio \- standard input/output library functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "FILE *" stdin ; +.BI "FILE *" stdout ; +.BI "FILE *" stderr ; +.fi +.SH DESCRIPTION +The standard I/O library provides a simple and efficient buffered stream +I/O interface. +Input and output is mapped into logical data streams and the +physical I/O characteristics are concealed. +The functions and macros are +listed below; more information is available from the individual man pages. +.P +A stream is associated with an external file (which may be a physical +device) by +.I opening +a file, which may involve creating a new file. +Creating an existing file +causes its former contents to be discarded. +If a file can support positioning requests (such as a disk file, +as opposed to a terminal), then a +.I file position indicator +associated with the stream is positioned at the start of the file (byte +zero), unless the file is opened with append mode. +If append mode is used, +it is unspecified whether the position indicator will be placed at the +start or the end of the file. +The position indicator is maintained by +subsequent reads, writes, and positioning requests. +All input occurs as if the characters were read by successive calls to the +.BR fgetc (3) +function; all output takes place as if all characters were written by +successive calls to the +.BR fputc (3) +function. +.P +A file is disassociated from a stream by +.I closing +the file. +Output streams are flushed (any unwritten buffer contents are +transferred to the host environment) before the stream is disassociated from +the file. +The value of a pointer to a +.I FILE +object is indeterminate after a file is closed (garbage). +.P +A file may be subsequently reopened, by the same or another program +execution, and its contents reclaimed or modified (if it can be +repositioned at the start). +If the main function returns to its original +caller, or the +.BR exit (3) +function is called, all open files are closed (hence all output streams are +flushed) before program termination. +Other methods of program termination, +such as +.BR abort (3) +do not bother about closing files properly. +.P +At program startup, three text streams are predefined and need not be +opened explicitly: +.I standard input +(for reading conventional input), +.I standard output +(for writing conventional output), and +.I standard error +(for writing diagnostic output). +These streams are abbreviated +.IR stdin , +.IR stdout , +and +.IR stderr . +When opened, the standard error stream is not fully buffered; the standard +input and output streams are fully buffered if and only if the streams do +not refer to an interactive device. +.P +Output streams that refer to terminal devices are always line buffered by +default; pending output to such streams is written automatically whenever +an input stream that refers to a terminal device is read. +In cases where a +large amount of computation is done after printing part of a line on an +output terminal, it is necessary to +.BR fflush (3) +the standard output before going off and computing so that the output will +appear. +.P +The +.I stdio +library is a part of the library +.B libc +and routines are automatically loaded as needed by +.BR cc (1). +The +SYNOPSIS +sections of the following manual pages indicate which include files are to +be used, what the compiler declaration for the function looks like and +which external variables are of interest. +.P +The following are defined as macros; these names may not be reused without +first removing their current definitions with +.BR #undef : +.BR BUFSIZ , +.BR EOF , +.BR FILENAME_MAX , +.BR FOPEN_MAX , +.BR L_cuserid , +.BR L_ctermid , +.BR L_tmpnam , +.BR NULL , +.BR SEEK_END , +.BR SEEK_SET , +.BR SEEK_CUR , +.BR TMP_MAX , +.BR clearerr , +.BR feof , +.BR ferror , +.BR fileno , +.\" Not on Linux: .BR fropen , +.\" Not on Linux: .BR fwopen , +.BR getc , +.BR getchar , +.BR putc , +.BR putchar , +.BR stderr , +.BR stdin , +.BR stdout . +Function versions of the macro functions +.BR feof , +.BR ferror , +.BR clearerr , +.BR fileno , +.BR getc , +.BR getchar , +.BR putc , +and +.B putchar +exist and will be used if the macros definitions are explicitly removed. +.SS List of functions +.TS +; +lb lbx +l l. +Function Description +_ +\fBclearerr\fP(3) T{ +check and reset stream status +T} +\fBfclose\fP(3) T{ +close a stream +T} +\fBfdopen\fP(3) T{ +stream open functions +T} +\fBfeof\fP(3) T{ +check and reset stream status +T} +\fBferror\fP(3) T{ +check and reset stream status +T} +\fBfflush\fP(3) T{ +flush a stream +T} +\fBfgetc\fP(3) T{ +get next character or word from input stream +T} +\fBfgetpos\fP(3) T{ +reposition a stream +T} +\fBfgets\fP(3) T{ +get a line from a stream +T} +\fBfileno\fP(3) T{ +return the integer descriptor of the argument stream +T} +\fBfmemopen\fP(3) T{ +open memory as stream +T} +\fBfopen\fP(3) T{ +stream open functions +T} +\fBfopencookie\fP(3) T{ +open a custom stream +T} +\fBfprintf\fP(3) T{ +formatted output conversion +T} +\fBfpurge\fP(3) T{ +flush a stream +T} +\fBfputc\fP(3) T{ +output a character or word to a stream +T} +\fBfputs\fP(3) T{ +output a line to a stream +T} +\fBfread\fP(3) T{ +binary stream input/output +T} +\fBfreopen\fP(3) T{ +stream open functions +T} +\fBfscanf\fP(3) T{ +input format conversion +T} +\fBfseek\fP(3) T{ +reposition a stream +T} +\fBfsetpos\fP(3) T{ +reposition a stream +T} +\fBftell\fP(3) T{ +reposition a stream +T} +\fBfwrite\fP(3) T{ +binary stream input/output +T} +\fBgetc\fP(3) T{ +get next character or word from input stream +T} +\fBgetchar\fP(3) T{ +get next character or word from input stream +T} +\fBgets\fP(3) T{ +get a line from a stream +T} +\fBgetw\fP(3) T{ +get next character or word from input stream +T} +\fBmktemp\fP(3) T{ +make temporary filename (unique) +T} +\fBopen_memstream\fP(3) T{ +open a dynamic memory buffer stream +T} +\fBopen_wmemstream\fP(3) T{ +open a dynamic memory buffer stream +T} +\fBperror\fP(3) T{ +system error messages +T} +\fBprintf\fP(3) T{ +formatted output conversion +T} +\fBputc\fP(3) T{ +output a character or word to a stream +T} +\fBputchar\fP(3) T{ +output a character or word to a stream +T} +\fBputs\fP(3) T{ +output a line to a stream +T} +\fBputw\fP(3) T{ +output a character or word to a stream +T} +\fBremove\fP(3) T{ +remove directory entry +T} +\fBrewind\fP(3) T{ +reposition a stream +T} +\fBscanf\fP(3) T{ +input format conversion +T} +\fBsetbuf\fP(3) T{ +stream buffering operations +T} +\fBsetbuffer\fP(3) T{ +stream buffering operations +T} +\fBsetlinebuf\fP(3) T{ +stream buffering operations +T} +\fBsetvbuf\fP(3) T{ +stream buffering operations +T} +\fBsprintf\fP(3) T{ +formatted output conversion +T} +\fBsscanf\fP(3) T{ +input format conversion +T} +\fBstrerror\fP(3) T{ +system error messages +T} +\fBsys_errlist\fP(3) T{ +system error messages +T} +\fBsys_nerr\fP(3) T{ +system error messages +T} +\fBtempnam\fP(3) T{ +temporary file routines +T} +\fBtmpfile\fP(3) T{ +temporary file routines +T} +\fBtmpnam\fP(3) T{ +temporary file routines +T} +\fBungetc\fP(3) T{ +un-get character from input stream +T} +\fBvfprintf\fP(3) T{ +formatted output conversion +T} +\fBvfscanf\fP(3) T{ +input format conversion +T} +\fBvprintf\fP(3) T{ +formatted output conversion +T} +\fBvscanf\fP(3) T{ +input format conversion +T} +\fBvsprintf\fP(3) T{ +formatted output conversion +T} +\fBvsscanf\fP(3) T{ +input format conversion +T} +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH SEE ALSO +.BR close (2), +.BR open (2), +.BR read (2), +.BR write (2), +.BR stdout (3), +.BR unlocked_stdio (3) diff --git a/man/man3/stdio_ext.3 b/man/man3/stdio_ext.3 new file mode 100644 index 0000000..ed0203c --- /dev/null +++ b/man/man3/stdio_ext.3 @@ -0,0 +1,137 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH stdio_ext 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +__fbufsize, __flbf, __fpending, __fpurge, __freadable, +__freading, __fsetlocking, __fwritable, __fwriting, _flushlbf \- +interfaces to stdio FILE structure +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "size_t __fbufsize(FILE *" stream ); +.BI "size_t __fpending(FILE *" stream ); +.BI "int __flbf(FILE *" stream ); +.BI "int __freadable(FILE *" stream ); +.BI "int __fwritable(FILE *" stream ); +.BI "int __freading(FILE *" stream ); +.BI "int __fwriting(FILE *" stream ); +.BI "int __fsetlocking(FILE *" stream ", int " type ); +.B "void _flushlbf(void);" +.BI "void __fpurge(FILE *" stream ); +.fi +.SH DESCRIPTION +Solaris introduced routines to allow portable access to the +internals of the +.I FILE +structure, and glibc also implemented these. +.P +The +.BR __fbufsize () +function returns the size of the buffer currently used +by the given stream. +.P +The +.BR __fpending () +function returns the number of bytes in the output buffer. +For wide-oriented streams the unit is wide characters. +This function is undefined on buffers in reading mode, +or opened read-only. +.P +The +.BR __flbf () +function returns a nonzero value if the stream is line-buffered, +and zero otherwise. +.P +The +.BR __freadable () +function returns a nonzero value if the stream allows reading, +and zero otherwise. +.P +The +.BR __fwritable () +function returns a nonzero value if the stream allows writing, +and zero otherwise. +.P +The +.BR __freading () +function returns a nonzero value if the stream is read-only, or +if the last operation on the stream was a read operation, +and zero otherwise. +.P +The +.BR __fwriting () +function returns a nonzero value if the stream is write-only (or +append-only), or if the last operation on the stream was a write +operation, and zero otherwise. +.P +The +.BR __fsetlocking () +function can be used to select the desired type of locking on the stream. +It returns the current type. +The +.I type +argument can take the following three values: +.TP +.B FSETLOCKING_INTERNAL +Perform implicit locking around every operation on the given stream +(except for the *_unlocked ones). +This is the default. +.TP +.B FSETLOCKING_BYCALLER +The caller will take care of the locking (possibly using +.BR flockfile (3) +in case there is more than one thread), and the stdio routines +will not do locking until the state is reset to +.BR FSETLOCKING_INTERNAL . +.TP +.B FSETLOCKING_QUERY +Don't change the type of locking. +(Only return it.) +.P +The +.BR _flushlbf () +function flushes all line-buffered streams. +(Presumably so that +output to a terminal is forced out, say before reading keyboard input.) +.P +The +.BR __fpurge () +function discards the contents of the stream's buffer. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR __fbufsize (), +.BR __fpending (), +.BR __fpurge (), +.BR __fsetlocking () +T} Thread safety MT-Safe race:stream +T{ +.na +.nh +.BR __flbf (), +.BR __freadable (), +.BR __freading (), +.BR __fwritable (), +.BR __fwriting (), +.BR _flushlbf () +T} Thread safety MT-Safe +.TE +.SH SEE ALSO +.BR flockfile (3), +.BR fpurge (3) diff --git a/man/man3/stdout.3 b/man/man3/stdout.3 new file mode 100644 index 0000000..752ae27 --- /dev/null +++ b/man/man3/stdout.3 @@ -0,0 +1 @@ +.so man3/stdin.3 diff --git a/man/man3/stpcpy.3 b/man/man3/stpcpy.3 new file mode 100644 index 0000000..ff7476a --- /dev/null +++ b/man/man3/stpcpy.3 @@ -0,0 +1 @@ +.so man3/strcpy.3 diff --git a/man/man3/stpncpy.3 b/man/man3/stpncpy.3 new file mode 100644 index 0000000..3e45f79 --- /dev/null +++ b/man/man3/stpncpy.3 @@ -0,0 +1,178 @@ +'\" t +.\" Copyright 2022 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH stpncpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stpncpy, strncpy +\- +fill a fixed-size buffer with non-null bytes from a string, +padding with null bytes as needed +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *strncpy(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.BI "char *stpncpy(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR stpncpy (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +These functions copy non-null bytes from the string pointed to by +.I src +into the array pointed to by +.IR dst . +If the source has too few non-null bytes to fill the destination, +the functions pad the destination with trailing null bytes. +If the destination buffer, +limited by its size, +isn't large enough to hold the copy, +the resulting character sequence is truncated. +For the difference between the two functions, see RETURN VALUE. +.P +An implementation of these functions might be: +.P +.in +4n +.EX +char * +strncpy(char *restrict dst, const char *restrict src, size_t dsize) +{ + stpncpy(dst, src, dsize); + return dst; +} +\& +char * +stpncpy(char *restrict dst, const char *restrict src, size_t dsize) +{ + size_t dlen; +\& + dlen = strnlen(src, dsize); + return memset(mempcpy(dst, src, dlen), 0, dsize \- dlen); +} +.EE +.in +.SH RETURN VALUE +.TP +.BR strncpy () +returns +.IR dst . +.TP +.BR stpncpy () +returns a pointer to +one after the last character in the destination character sequence. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR stpncpy (), +.BR strncpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR strncpy () +C11, POSIX.1-2008. +.TP +.BR stpncpy () +POSIX.1-2008. +.SH HISTORY +.TP +.BR strncpy () +C89, POSIX.1-2001, SVr4, 4.3BSD. +.TP +.BR stpncpy () +glibc 1.07. +POSIX.1-2008. +.SH CAVEATS +The name of these functions is confusing. +These functions produce a null-padded character sequence, +not a string (see +.BR string_copying (7)). +For example: +.P +.in +4n +.EX +strncpy(buf, "1", 5); // { \[aq]1\[aq], 0, 0, 0, 0 } +strncpy(buf, "1234", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], 0 } +strncpy(buf, "12345", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], \[aq]5\[aq] } +strncpy(buf, "123456", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], \[aq]5\[aq] } +.EE +.in +.P +It's impossible to distinguish truncation by the result of the call, +from a character sequence that just fits the destination buffer; +truncation should be detected by +comparing the length of the input string +with the size of the destination buffer. +.P +If you're going to use this function in chained calls, +it would be useful to develop a similar function that accepts +a pointer to the end (one after the last element) of the destination buffer +instead of its size. +.SH EXAMPLES +.\" SRC BEGIN (stpncpy.c) +.EX +#include +#include +#include +#include +\& +int +main(void) +{ + char *p; + char buf1[20]; + char buf2[20]; + size_t len; +\& + if (sizeof(buf2) < strlen("Hello world!")) + errx("strncpy: truncating character sequence"); + strncpy(buf2, "Hello world!", sizeof(buf2)); + len = strnlen(buf2, sizeof(buf2)); +\& + printf("[len = %zu]: ", len); + fwrite(buf2, 1, len, stdout); + putchar(\[aq]\en\[aq]); +\& + if (sizeof(buf1) < strlen("Hello world!")) + errx("stpncpy: truncating character sequence"); + p = stpncpy(buf1, "Hello world!", sizeof(buf1)); + len = p \- buf1; +\& + printf("[len = %zu]: ", len); + fwrite(buf1, 1, len, stdout); + putchar(\[aq]\en\[aq]); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR wcpncpy (3), +.BR string_copying (7) diff --git a/man/man3/strcasecmp.3 b/man/man3/strcasecmp.3 new file mode 100644 index 0000000..647f211 --- /dev/null +++ b/man/man3/strcasecmp.3 @@ -0,0 +1,112 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:12:45 1993 by Rik Faith (faith@cs.unc.edu) +.TH strcasecmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strcasecmp, strncasecmp \- compare two strings ignoring case +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int strcasecmp(const char *" s1 ", const char *" s2 ); +.BI "int strncasecmp(const char " s1 [. n "], const char " s2 [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strcasecmp () +function performs a byte-by-byte comparison of the strings +.I s1 +and +.IR s2 , +ignoring the case of the characters. +It returns an integer +less than, equal to, or greater than zero if +.I s1 +is found, +respectively, to be less than, to match, or be greater than +.IR s2 . +.P +The +.BR strncasecmp () +function is similar, except that it compares +no more than +.I n +bytes of +.I s1 +and +.IR s2 . +.SH RETURN VALUE +The +.BR strcasecmp () +and +.BR strncasecmp () +functions return +an integer less than, equal to, or greater than zero if +.I s1 +is, after ignoring case, found to be +less than, to match, or be greater than +.IR s2 , +respectively. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strcasecmp (), +.BR strncasecmp () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +4.4BSD, POSIX.1-2001. +.P +The +.BR strcasecmp () +and +.BR strncasecmp () +functions first appeared in 4.4BSD, where they were declared in +.IR . +Thus, for reasons of historical compatibility, the glibc +.I +header file also declares these functions, if the +.B _DEFAULT_SOURCE +(or, in glibc 2.19 and earlier, +.BR _BSD_SOURCE ) +feature test macro is defined. +.P +The POSIX.1-2008 standard says of these functions: +.P +.RS +When the +.B LC_CTYPE +category of the locale being used is from the POSIX locale, +these functions shall behave as if the strings had been converted +to lowercase and then a byte comparison performed. +Otherwise, the results are unspecified. +.RE +.SH SEE ALSO +.BR memcmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR string (3), +.BR strncmp (3), +.BR wcscasecmp (3), +.BR wcsncasecmp (3) diff --git a/man/man3/strcasestr.3 b/man/man3/strcasestr.3 new file mode 100644 index 0000000..2feb2c5 --- /dev/null +++ b/man/man3/strcasestr.3 @@ -0,0 +1 @@ +.so man3/strstr.3 diff --git a/man/man3/strcat.3 b/man/man3/strcat.3 new file mode 100644 index 0000000..ff7476a --- /dev/null +++ b/man/man3/strcat.3 @@ -0,0 +1 @@ +.so man3/strcpy.3 diff --git a/man/man3/strchr.3 b/man/man3/strchr.3 new file mode 100644 index 0000000..3abb02e --- /dev/null +++ b/man/man3/strchr.3 @@ -0,0 +1,131 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Mon Apr 12 12:51:24 1993, David Metcalfe +.\" 2006-05-19, Justin Pryzby +.\" Document strchrnul(3). +.\" +.TH strchr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strchr, strrchr, strchrnul \- locate character in string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *strchr(const char *" s ", int " c ); +.BI "char *strrchr(const char *" s ", int " c ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "char *strchrnul(const char *" s ", int " c ); +.fi +.SH DESCRIPTION +The +.BR strchr () +function returns a pointer to the first occurrence +of the character +.I c +in the string +.IR s . +.P +The +.BR strrchr () +function returns a pointer to the last occurrence +of the character +.I c +in the string +.IR s . +.P +The +.BR strchrnul () +function is like +.BR strchr () +except that if +.I c +is not found in +.IR s , +then it returns a pointer to the null byte +at the end of +.IR s , +rather than NULL. +.P +Here "character" means "byte"; these functions do not work with +wide or multibyte characters. +.SH RETURN VALUE +The +.BR strchr () +and +.BR strrchr () +functions return a pointer to +the matched character or NULL if the character is not found. +The terminating null byte is considered part of the string, +so that if +.I c +is specified as \[aq]\e0\[aq], +these functions return a pointer to the terminator. +.P +The +.BR strchrnul () +function returns a pointer to the matched character, +or a pointer to the null byte at the end of +.I s +(i.e., +.IR "s+strlen(s)" ) +if the character is not found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strchr (), +.BR strrchr (), +.BR strchrnul () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR strchr () +.TQ +.BR strrchr () +C11, POSIX.1-2008. +.TP +.BR strchrnul () +GNU. +.SH HISTORY +.TP +.BR strchr () +.TQ +.BR strrchr () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR strchrnul () +glibc 2.1.1, +FreeBSD 10, +NetBSD 8. +.SH SEE ALSO +.BR memchr (3), +.BR string (3), +.BR strlen (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR wcschr (3), +.BR wcsrchr (3) diff --git a/man/man3/strchrnul.3 b/man/man3/strchrnul.3 new file mode 100644 index 0000000..322b7a8 --- /dev/null +++ b/man/man3/strchrnul.3 @@ -0,0 +1 @@ +.so man3/strchr.3 diff --git a/man/man3/strcmp.3 b/man/man3/strcmp.3 new file mode 100644 index 0000000..ba9eefb --- /dev/null +++ b/man/man3/strcmp.3 @@ -0,0 +1,208 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2020 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:08:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-08-31, aeb +.\" +.TH strcmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strcmp, strncmp \- compare two strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int strcmp(const char *" s1 ", const char *" s2 ); +.BI "int strncmp(const char " s1 [. n "], const char " s2 [. n "], size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strcmp () +function compares the two strings +.I s1 +and +.IR s2 . +The locale is not taken into account (for a locale-aware comparison, see +.BR strcoll (3)). +The comparison is done using unsigned characters. +.P +.BR strcmp () +returns an integer indicating the result of the comparison, as follows: +.IP \[bu] 3 +0, if the +.I s1 +and +.I s2 +are equal; +.IP \[bu] +a negative value if +.I s1 +is less than +.IR s2 ; +.IP \[bu] +a positive value if +.I s1 +is greater than +.IR s2 . +.P +The +.BR strncmp () +function is similar, except it compares +only the first (at most) +.I n +bytes of +.I s1 +and +.IR s2 . +.SH RETURN VALUE +The +.BR strcmp () +and +.BR strncmp () +functions return an integer +less than, equal to, or greater than zero if +.I s1 +(or the first +.I n +bytes thereof) is found, respectively, to be less than, to +match, or be greater than +.IR s2 . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strcmp (), +.BR strncmp () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +POSIX.1 specifies only that: +.RS +.P +The sign of a nonzero return value shall be determined by the sign +of the difference between the values of the first pair of bytes +(both interpreted as type +.IR "unsigned char" ) +that differ in the strings being compared. +.RE +.P +In glibc, as in most other implementations, +the return value is the arithmetic result of subtracting +the last compared byte in +.I s2 +from the last compared byte in +.IR s1 . +(If the two characters are equal, this difference is 0.) +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH EXAMPLES +The program below can be used to demonstrate the operation of +.BR strcmp () +(when given two arguments) and +.BR strncmp () +(when given three arguments). +First, some examples using +.BR strcmp (): +.P +.in +4n +.EX +$ \fB./string_comp ABC ABC\fP + and are equal +$ \fB./string_comp ABC AB\fP # \[aq]C\[aq] is ASCII 67; \[aq]C\[aq] \- \[aq]\e0\[aq] = 67 + is greater than (67) +$ \fB./string_comp ABA ABZ\fP # \[aq]A\[aq] is ASCII 65; \[aq]Z\[aq] is ASCII 90 + is less than (\-25) +$ \fB./string_comp ABJ ABC\fP + is greater than (7) +$ .\fB/string_comp $\[aq]\e201\[aq] A\fP # 0201 \- 0101 = 0100 (or 64 decimal) + is greater than (64) +.EE +.in +.P +The last example uses +.BR bash (1)-specific +syntax to produce a string containing an 8-bit ASCII code; +the result demonstrates that the string comparison uses unsigned +characters. +.P +And then some examples using +.BR strncmp (): +.P +.in +4n +.EX +$ \fB./string_comp ABC AB 3\fP + is greater than (67) +$ \fB./string_comp ABC AB 2\fP + and are equal in the first 2 bytes +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (string_comp.c) +.EX +/* string_comp.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int res; +\& + if (argc < 3) { + fprintf(stderr, "Usage: %s []\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + if (argc == 3) + res = strcmp(argv[1], argv[2]); + else + res = strncmp(argv[1], argv[2], atoi(argv[3])); +\& + if (res == 0) { + printf(" and are equal"); + if (argc > 3) + printf(" in the first %d bytes\en", atoi(argv[3])); + printf("\en"); + } else if (res < 0) { + printf(" is less than (%d)\en", res); + } else { + printf(" is greater than (%d)\en", res); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR memcmp (3), +.BR strcasecmp (3), +.BR strcoll (3), +.BR string (3), +.BR strncasecmp (3), +.BR strverscmp (3), +.BR wcscmp (3), +.BR wcsncmp (3), +.BR ascii (7) diff --git a/man/man3/strcoll.3 b/man/man3/strcoll.3 new file mode 100644 index 0000000..8b19cfc --- /dev/null +++ b/man/man3/strcoll.3 @@ -0,0 +1,86 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:40:44 1993 by Rik Faith (faith@cs.unc.edu) +.TH strcoll 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strcoll \- compare two strings using the current locale +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int strcoll(const char *" s1 ", const char *" s2 ); +.fi +.SH DESCRIPTION +The +.BR strcoll () +function compares the two strings +.I s1 +and +.IR s2 . +It returns an integer less than, equal to, or greater +than zero if +.I s1 +is found, respectively, to be less than, +to match, or be greater than +.IR s2 . +The comparison is based on +strings interpreted as appropriate for the program's current locale +for category +.BR LC_COLLATE . +(See +.BR setlocale (3).) +.SH RETURN VALUE +The +.BR strcoll () +function returns an integer less than, equal to, +or greater than zero if +.I s1 +is found, respectively, to be less +than, to match, or be greater than +.IR s2 , +when both are interpreted +as appropriate for the current locale. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strcoll () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH NOTES +In the +.I "POSIX" +or +.I "C" +locales +.BR strcoll () +is equivalent to +.BR strcmp (3). +.SH SEE ALSO +.BR memcmp (3), +.BR setlocale (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR string (3), +.BR strxfrm (3) diff --git a/man/man3/strcpy.3 b/man/man3/strcpy.3 new file mode 100644 index 0000000..a14e8cf --- /dev/null +++ b/man/man3/strcpy.3 @@ -0,0 +1,204 @@ +'\" t +.\" Copyright 2022 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH strcpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stpcpy, strcpy, strcat \- copy or catenate a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *stpcpy(char *restrict " dst ", const char *restrict " src ); +.BI "char *strcpy(char *restrict " dst ", const char *restrict " src ); +.BI "char *strcat(char *restrict " dst ", const char *restrict " src ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR stpcpy (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +.TP +.BR stpcpy () +.TQ +.BR strcpy () +These functions copy the string pointed to by +.IR src , +into a string +at the buffer pointed to by +.IR dst . +The programmer is responsible for allocating a destination buffer large enough, +that is, +.IR "strlen(src) + 1" . +For the difference between the two functions, see RETURN VALUE. +.TP +.BR strcat () +This function catenates the string pointed to by +.IR src , +after the string pointed to by +.I dst +(overwriting its terminating null byte). +The programmer is responsible for allocating a destination buffer large enough, +that is, +.IR "strlen(dst) + strlen(src) + 1" . +.P +An implementation of these functions might be: +.P +.in +4n +.EX +char * +stpcpy(char *restrict dst, const char *restrict src) +{ + char *p; +\& + p = mempcpy(dst, src, strlen(src)); + *p = \[aq]\e0\[aq]; +\& + return p; +} +\& +char * +strcpy(char *restrict dst, const char *restrict src) +{ + stpcpy(dst, src); + return dst; +} +\& +char * +strcat(char *restrict dst, const char *restrict src) +{ + stpcpy(dst + strlen(dst), src); + return dst; +} +.EE +.in +.SH RETURN VALUE +.TP +.BR stpcpy () +This function returns +a pointer to the terminating null byte of the copied string. +.TP +.BR strcpy () +.TQ +.BR strcat () +These functions return +.IR dst . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR stpcpy (), +.BR strcpy (), +.BR strcat () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR stpcpy () +POSIX.1-2008. +.TP +.BR strcpy () +.TQ +.BR strcat () +C11, POSIX.1-2008. +.SH STANDARDS +.TP +.BR stpcpy () +POSIX.1-2008. +.TP +.BR strcpy () +.TQ +.BR strcat () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH CAVEATS +The strings +.I src +and +.I dst +may not overlap. +.P +If the destination buffer is not large enough, +the behavior is undefined. +See +.B _FORTIFY_SOURCE +in +.BR feature_test_macros (7). +.P +.BR strcat () +can be very inefficient. +Read about +.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ +Shlemiel the painter +.UE . +.SH EXAMPLES +.\" SRC BEGIN (strcpy.c) +.EX +#include +#include +#include +#include +\& +int +main(void) +{ + char *p; + char *buf1; + char *buf2; + size_t len, maxsize; +\& + maxsize = strlen("Hello ") + strlen("world") + strlen("!") + 1; + buf1 = malloc(sizeof(*buf1) * maxsize); + if (buf1 == NULL) + err(EXIT_FAILURE, "malloc()"); + buf2 = malloc(sizeof(*buf2) * maxsize); + if (buf2 == NULL) + err(EXIT_FAILURE, "malloc()"); +\& + p = buf1; + p = stpcpy(p, "Hello "); + p = stpcpy(p, "world"); + p = stpcpy(p, "!"); + len = p \- buf1; +\& + printf("[len = %zu]: ", len); + puts(buf1); // "Hello world!" + free(buf1); +\& + strcpy(buf2, "Hello "); + strcat(buf2, "world"); + strcat(buf2, "!"); + len = strlen(buf2); +\& + printf("[len = %zu]: ", len); + puts(buf2); // "Hello world!" + free(buf2); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR strdup (3), +.BR string (3), +.BR wcscpy (3), +.BR string_copying (7) diff --git a/man/man3/strcspn.3 b/man/man3/strcspn.3 new file mode 100644 index 0000000..26284f2 --- /dev/null +++ b/man/man3/strcspn.3 @@ -0,0 +1 @@ +.so man3/strspn.3 diff --git a/man/man3/strdup.3 b/man/man3/strdup.3 new file mode 100644 index 0000000..530ffb9 --- /dev/null +++ b/man/man3/strdup.3 @@ -0,0 +1,145 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:34 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Wed Oct 17 01:12:26 2001 by John Levon +.TH strdup 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strdup, strndup, strdupa, strndupa \- duplicate a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *strdup(const char *" s ); +.P +.BI "char *strndup(const char " s [. n "], size_t " n ); +.BI "char *strdupa(const char *" s ); +.BI "char *strndupa(const char " s [. n "], size_t " n ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strdup (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR strndup (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.P +.BR strdupa (), +.BR strndupa (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR strdup () +function returns a pointer to a new string which +is a duplicate of the string +.IR s . +Memory for the new string is +obtained with +.BR malloc (3), +and can be freed with +.BR free (3). +.P +The +.BR strndup () +function is similar, but copies at most +.I n +bytes. +If +.I s +is longer than +.IR n , +only +.I n +bytes are copied, and a terminating null byte (\[aq]\e0\[aq]) is added. +.P +.BR strdupa () +and +.BR strndupa () +are similar, but use +.BR alloca (3) +to allocate the buffer. +.SH RETURN VALUE +On success, the +.BR strdup () +function returns a pointer to the duplicated +string. +It returns NULL if insufficient memory was available, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory available to allocate duplicate string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strdup (), +.BR strndup (), +.BR strdupa (), +.BR strndupa () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR strdup () +.TQ +.BR strndup () +POSIX.1-2008. +.TP +.BR strdupa () +.TQ +.BR strndupa () +GNU. +.SH HISTORY +.TP +.BR strdup () +SVr4, 4.3BSD-Reno, POSIX.1-2001. +.TP +.BR strndup () +POSIX.1-2008. +.TP +.BR strdupa () +.TQ +.BR strndupa () +GNU. +.SH SEE ALSO +.BR alloca (3), +.BR calloc (3), +.BR free (3), +.BR malloc (3), +.BR realloc (3), +.BR string (3), +.BR wcsdup (3) diff --git a/man/man3/strdupa.3 b/man/man3/strdupa.3 new file mode 100644 index 0000000..2dd8f88 --- /dev/null +++ b/man/man3/strdupa.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man/man3/strerror.3 b/man/man3/strerror.3 new file mode 100644 index 0000000..62a99c6 --- /dev/null +++ b/man/man3/strerror.3 @@ -0,0 +1,324 @@ +'\" t +.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2005, 2014, 2020 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:05:30 1993 by Rik Faith +.\" Modified Fri Feb 16 14:25:17 1996 by Andries Brouwer +.\" Modified Sun Jul 21 20:55:44 1996 by Andries Brouwer +.\" Modified Mon Oct 15 21:16:25 2001 by John Levon +.\" Modified Tue Oct 16 00:04:43 2001 by Andries Brouwer +.\" Modified Fri Jun 20 03:04:30 2003 by Andries Brouwer +.\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description +.\" Addition of extra material on portability and standards. +.\" +.TH strerror 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l \- +return string describing error number +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *strerror(int " errnum ); +.BI "const char *strerrorname_np(int " errnum ); +.BI "const char *strerrordesc_np(int " errnum ); +.P +.BI "int strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen ); + /* XSI-compliant */ +.P +.BI "char *strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen ); + /* GNU-specific */ +.P +.BI "char *strerror_l(int " errnum ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strerrorname_np (), +.BR strerrordesc_np (): +.nf + _GNU_SOURCE +.fi +.P +.BR strerror_r (): +.nf + The XSI-compliant version is provided if: + (_POSIX_C_SOURCE >= 200112L) && ! _GNU_SOURCE + Otherwise, the GNU-specific version is provided. +.fi +.SH DESCRIPTION +The +.BR strerror () +function returns a pointer to a string that describes the error +code passed in the argument +.IR errnum , +possibly using the +.B LC_MESSAGES +part of the current locale to select the appropriate language. +(For example, if +.I errnum +is +.BR EINVAL , +the returned description will be "Invalid argument".) +This string must not be modified by the application, +and the returned pointer will be invalidated on a subsequent call to +.BR strerror () +or +.BR strerror_l (), +or if the thread that obtained the string exits. +No other library function, including +.BR perror (3), +will modify this string. +.P +Like +.BR strerror (), +the +.BR strerrordesc_np () +function returns a pointer to a string that describes the error +code passed in the argument +.IR errnum , +with the difference that the returned string is not translated +according to the current locale. +.P +The +.BR strerrorname_np () +function returns a pointer to a string containing the name of the error +code passed in the argument +.IR errnum . +For example, given +.B EPERM +as an argument, this function returns a pointer to the string "EPERM". +Given +.B 0 +as an argument, +this function returns a pointer to the string "0". +.\" +.SS strerror_r() +.BR strerror_r () +is like +.BR strerror (), +but might use the supplied buffer +.I buf +instead of allocating one internally. +This function is available in two versions: +an XSI-compliant version specified in POSIX.1-2001 +(available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13), +and a GNU-specific version (available since glibc 2.0). +The XSI-compliant version is provided with the feature test macros +settings shown in the SYNOPSIS; +otherwise the GNU-specific version is provided. +If no feature test macros are explicitly defined, +then (since glibc 2.4) +.B _POSIX_C_SOURCE +is defined by default with the value +200112L, so that the XSI-compliant version of +.BR strerror_r () +is provided by default. +.P +The XSI-compliant +.BR strerror_r () +is preferred for portable applications. +It returns the error string in the user-supplied buffer +.I buf +of length +.IR buflen . +.P +The GNU-specific +.BR strerror_r () +returns a pointer to a string containing the error message. +This may be either a pointer to a string that the function stores in +.IR buf , +or a pointer to some (immutable) static string +(in which case +.I buf +is unused). +If the function stores a string in +.IR buf , +then at most +.I buflen +bytes are stored (the string may be truncated if +.I buflen +is too small and +.I errnum +is unknown). +The string always includes a terminating null byte (\[aq]\e0\[aq]). +.\" +.SS strerror_l() +.BR strerror_l () +is like +.BR strerror (), +but maps +.I errnum +to a locale-dependent error message in the locale specified by +.IR locale . +The behavior of +.BR strerror_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +or is not a valid locale object handle. +.SH RETURN VALUE +The +.BR strerror (), +.BR strerror_l (), +and the GNU-specific +.BR strerror_r () +functions return +the appropriate error description string, +or an "Unknown error nnn" message if the error number is unknown. +.P +On success, +.BR strerrorname_np () +and +.BR strerrordesc_np () +return the appropriate error description string. +If +.I errnum +is an invalid error number, these functions return NULL. +.P +The XSI-compliant +.BR strerror_r () +function returns 0 on success. +On error, +a (positive) error number is returned (since glibc 2.13), +or \-1 is returned and +.I errno +is set to indicate the error (before glibc 2.13). +.P +POSIX.1-2001 and POSIX.1-2008 require that a successful call to +.BR strerror () +or +.BR strerror_l () +shall leave +.I errno +unchanged, and note that, +since no function return value is reserved to indicate an error, +an application that wishes to check for errors should initialize +.I errno +to zero before the call, +and then check +.I errno +after the call. +.SH ERRORS +.TP +.B EINVAL +The value of +.I errnum +is not a valid error number. +.TP +.B ERANGE +Insufficient storage was supplied to contain the error description string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strerror () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +T{ +.na +.nh +.BR strerrorname_np (), +.BR strerrordesc_np () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR strerror_r (), +.BR strerror_l () +T} Thread safety MT-Safe +.TE +.P +Before glibc 2.32, +.BR strerror () +is not MT-Safe. +.SH STANDARDS +.TP +.BR strerror () +C11, POSIX.1-2008. +.TP +.BR strerror_r () +.\" FIXME . for later review when Issue 8 is one day released... +.\" A future POSIX.1 may remove strerror_r() +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=508 +.TQ +.BR strerror_l () +POSIX.1-2008. +.TP +.BR strerrorname_np () +.TQ +.BR strerrordesc_np () +GNU. +.P +POSIX.1-2001 permits +.BR strerror () +to set +.I errno +if the call encounters an error, but does not specify what +value should be returned as the function result in the event of an error. +On some systems, +.\" e.g., Solaris 8, HP-UX 11 +.BR strerror () +returns NULL if the error number is unknown. +On other systems, +.\" e.g., FreeBSD 5.4, Tru64 5.1B +.BR strerror () +returns a string something like "Error nnn occurred" and sets +.I errno +to +.B EINVAL +if the error number is unknown. +C99 and POSIX.1-2008 require the return value to be non-NULL. +.SH HISTORY +.TP +.BR strerror () +POSIX.1-2001, C89. +.TP +.BR strerror_r () +POSIX.1-2001. +.TP +.BR strerror_l () +glibc 2.6. +POSIX.1-2008. +.TP +.BR strerrorname_np () +.TQ +.BR strerrordesc_np () +glibc 2.32. +.SH NOTES +.BR strerrorname_np () +and +.BR strerrordesc_np () +are thread-safe and async-signal-safe. +.SH SEE ALSO +.BR err (3), +.BR errno (3), +.BR error (3), +.BR perror (3), +.BR strsignal (3), +.BR locale (7), +.BR signal-safety (7) diff --git a/man/man3/strerror_l.3 b/man/man3/strerror_l.3 new file mode 100644 index 0000000..649dd6d --- /dev/null +++ b/man/man3/strerror_l.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man/man3/strerror_r.3 b/man/man3/strerror_r.3 new file mode 100644 index 0000000..649dd6d --- /dev/null +++ b/man/man3/strerror_r.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man/man3/strerrordesc_np.3 b/man/man3/strerrordesc_np.3 new file mode 100644 index 0000000..649dd6d --- /dev/null +++ b/man/man3/strerrordesc_np.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man/man3/strerrorname_np.3 b/man/man3/strerrorname_np.3 new file mode 100644 index 0000000..649dd6d --- /dev/null +++ b/man/man3/strerrorname_np.3 @@ -0,0 +1 @@ +.so man3/strerror.3 diff --git a/man/man3/strfmon.3 b/man/man3/strfmon.3 new file mode 100644 index 0000000..c3a9cb2 --- /dev/null +++ b/man/man3/strfmon.3 @@ -0,0 +1,209 @@ +'\" t +.\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH strfmon 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strfmon, strfmon_l \- convert monetary value to a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t strfmon(char " s "[restrict ." max "], size_t " max , +.BI " const char *restrict " format ", ...);" +.BI "ssize_t strfmon_l(char " s "[restrict ." max "], size_t " max ", \ +locale_t " locale , +.BI " const char *restrict " format ", ...);" +.fi +.SH DESCRIPTION +The +.BR strfmon () +function formats the specified monetary amount +according to the current locale +and format specification +.I format +and places the +result in the character array +.I s +of size +.IR max . +.P +The +.BR strfmon_l () +function performs the same task, +but uses +the locale specified by +.IR locale . +The behavior of +.BR strfmon_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.P +Ordinary characters in +.I format +are copied to +.I s +without conversion. +Conversion specifiers are introduced by a \[aq]%\[aq] +character. +Immediately following it there can be zero or more +of the following flags: +.TP +.BI = f +The single-byte character +.I f +is used as the numeric fill character (to be used with +a left precision, see below). +When not specified, the space character is used. +.TP +.B \[ha] +Do not use any grouping characters that might be defined +for the current locale. +By default, grouping is enabled. +.TP +.BR ( " or " + +The ( flag indicates that negative amounts should be enclosed between +parentheses. +The + flag indicates that signs should be handled +in the default way, that is, amounts are preceded by the locale's +sign indication, for example, nothing for positive, "\-" for negative. +.TP +.B ! +Omit the currency symbol. +.TP +.B \- +Left justify all fields. +The default is right justification. +.P +Next, there may be a field width: a decimal digit string specifying +a minimum field width in bytes. +The default is 0. +A result smaller than this width is padded with spaces +(on the left, unless the left-justify flag was given). +.P +Next, there may be a left precision of the form "#" followed by +a decimal digit string. +If the number of digits left of the +radix character is smaller than this, the representation is +padded on the left with the numeric fill character. +Grouping characters are not counted in this field width. +.P +Next, there may be a right precision of the form "." followed by +a decimal digit string. +The amount being formatted is rounded to +the specified number of digits prior to formatting. +The default is specified in the +.I frac_digits +and +.I int_frac_digits +items of the current locale. +If the right precision is 0, no radix character is printed. +(The radix character here is determined by +.BR LC_MONETARY , +and may differ from that specified by +.BR LC_NUMERIC .) +.P +Finally, the conversion specification must be ended with a +conversion character. +The three conversion characters are +.TP +.B % +(In this case, the entire specification must be exactly "%%".) +Put a \[aq]%\[aq] character in the result string. +.TP +.B i +One argument of type +.I double +is converted using the locale's international currency format. +.TP +.B n +One argument of type +.I double +is converted using the locale's national currency format. +.SH RETURN VALUE +The +.BR strfmon () +function returns the number of characters placed +in the array +.IR s , +not including the terminating null byte, +provided the string, including the terminating null byte, fits. +Otherwise, it sets +.I errno +to +.BR E2BIG , +returns \-1, and the contents of the array is undefined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strfmon () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR strfmon_l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH EXAMPLES +The call +.P +.in +4n +.EX +strfmon(buf, sizeof(buf), "[%\[ha]=*#6n] [%=*#6i]", + 1234.567, 1234.567); +.EE +.in +.P +outputs +.P +.in +4n +.EX +[€ **1234,57] [EUR **1 234,57] +.EE +.in +.P +in the +.I nl_NL +locale. +The +.IR de_DE , +.IR de_CH , +.IR en_AU , +and +.I en_GB +locales yield +.P +.in +4n +.EX +[ **1234,57 €] [ **1.234,57 EUR] +[ Fr. **1234.57] [ CHF **1\[aq]234.57] +[ $**1234.57] [ AUD**1,234.57] +[ £**1234.57] [ GBP**1,234.57] +.EE +.in +.SH SEE ALSO +.BR duplocale (3), +.BR setlocale (3), +.BR sprintf (3), +.BR locale (7) diff --git a/man/man3/strfmon_l.3 b/man/man3/strfmon_l.3 new file mode 100644 index 0000000..cdbc310 --- /dev/null +++ b/man/man3/strfmon_l.3 @@ -0,0 +1 @@ +.so man3/strfmon.3 diff --git a/man/man3/strfromd.3 b/man/man3/strfromd.3 new file mode 100644 index 0000000..74bc736 --- /dev/null +++ b/man/man3/strfromd.3 @@ -0,0 +1,231 @@ +'\" t +.\" Copyright (c) 2016, IBM Corporation. +.\" Written by Wainer dos Santos Moschetta +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" glibc 2.25 source code and manual. +.\" C99 standard document. +.\" ISO/IEC TS 18661-1 technical specification. +.\" snprintf and other man.3 pages. +.\" +.TH strfromd 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strfromd, strfromf, strfroml \- convert a floating-point value into +a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int strfromd(char " str "[restrict ." n "], size_t " n , +.BI " const char *restrict " format ", double " fp ");" +.BI "int strfromf(char " str "[restrict ." n "], size_t " n , +.BI " const char *restrict " format ", float "fp ");" +.BI "int strfroml(char " str "[restrict ." n "], size_t " n , +.BI " const char *restrict " format ", long double " fp ");" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strfromd (), +.BR strfromf (), +.BR strfroml (): +.nf + __STDC_WANT_IEC_60559_BFP_EXT__ +.fi +.SH DESCRIPTION +These functions convert a floating-point value, +.IR fp , +into a string of characters, +.IR str , +with a configurable +.I format +string. +At most +.I n +characters are stored into +.IR str . +.P +The terminating null byte ('\e0') is written if and only if +.I n +is sufficiently large, otherwise the written string is truncated at +.I n +characters. +.P +The +.BR strfromd (), +.BR strfromf (), +and +.BR strfroml () +functions are equivalent to +.P +.in +4n +.EX +snprintf(str, n, format, fp); +.EE +.in +.P +except for the +.I format +string. +.SS Format of the format string +The +.I format +string must start with the character \[aq]%\[aq]. +This is followed by an optional precision which starts with the period +character (.), followed by an optional decimal integer. +If no integer is specified after the period character, +a precision of zero is used. +Finally, the format string should have one of the conversion specifiers +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G . +.P +The conversion specifier is applied based on the floating-point type +indicated by the function suffix. +Therefore, unlike +.BR snprintf (), +the format string does not have a length modifier character. +See +.BR snprintf (3) +for a detailed description of these conversion specifiers. +.P +The implementation conforms to the C99 standard on conversion of NaN and +infinity values: +.P +.RS +If +.I fp +is a NaN, +NaN, or \-NaN, and +.B f +(or +.BR a , +.BR e , +.BR g ) +is the conversion specifier, the conversion is to "nan", "nan", or "\-nan", +respectively. +If +.B F +(or +.BR A , +.BR E , +.BR G ) +is the conversion specifier, the conversion is to "NAN" or "\-NAN". +.P +Likewise if +.I fp +is infinity, it is converted to [\-]inf or [\-]INF. +.RE +.P +A malformed +.I format +string results in undefined behavior. +.SH RETURN VALUE +The +.BR strfromd (), +.BR strfromf (), +and +.BR strfroml () +functions return the number of characters that would have been written in +.I str +if +.I n +had enough space, +not counting the terminating null byte. +Thus, a return value of +.I n +or greater means that the output was truncated. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7) +and the +.B POSIX Safety Concepts +section in GNU C Library manual. +.P +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strfromd (), +.BR strfromf (), +.BR strfroml () +T} Thread safety MT-Safe locale +\^ Async-signal safety AS-Unsafe heap +\^ Async-cancel safety AC-Unsafe mem +.TE +.P +Note: these attributes are preliminary. +.SH STANDARDS +ISO/IEC TS 18661-1. +.SH VERSIONS +.TP +.BR strfromd () +.TQ +.BR strfromf () +.TQ +.BR strfroml () +glibc 2.25. +.SH NOTES +These functions take account of the +.B LC_NUMERIC +category of the current locale. +.SH EXAMPLES +To convert the value 12.1 as a float type to a string using decimal +notation, resulting in "12.100000": +.P +.in +4n +.EX +#define __STDC_WANT_IEC_60559_BFP_EXT__ +#include +int ssize = 10; +char s[ssize]; +strfromf(s, ssize, "%f", 12.1); +.EE +.in +.P +To convert the value 12.3456 as a float type to a string using +decimal notation with two digits of precision, resulting in "12.35": +.P +.in +4n +.EX +#define __STDC_WANT_IEC_60559_BFP_EXT__ +#include +int ssize = 10; +char s[ssize]; +strfromf(s, ssize, "%.2f", 12.3456); +.EE +.in +.P +To convert the value 12.345e19 as a double type to a string using +scientific notation with zero digits of precision, resulting in "1E+20": +.P +.in +4n +.EX +#define __STDC_WANT_IEC_60559_BFP_EXT__ +#include +int ssize = 10; +char s[ssize]; +strfromd(s, ssize, "%.E", 12.345e19); +.EE +.in +.SH SEE ALSO +.BR atof (3), +.BR snprintf (3), +.BR strtod (3) diff --git a/man/man3/strfromf.3 b/man/man3/strfromf.3 new file mode 100644 index 0000000..d20099d --- /dev/null +++ b/man/man3/strfromf.3 @@ -0,0 +1 @@ +.so man3/strfromd.3 diff --git a/man/man3/strfroml.3 b/man/man3/strfroml.3 new file mode 100644 index 0000000..d20099d --- /dev/null +++ b/man/man3/strfroml.3 @@ -0,0 +1 @@ +.so man3/strfromd.3 diff --git a/man/man3/strfry.3 b/man/man3/strfry.3 new file mode 100644 index 0000000..2f7daec --- /dev/null +++ b/man/man3/strfry.3 @@ -0,0 +1,55 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:39:43 1993 by Rik Faith (faith@cs.unc.edu) +.TH strfry 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strfry \- randomize a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "char *strfry(char *" string ); +.fi +.SH DESCRIPTION +The +.BR strfry () +function randomizes the contents of +.I string +by randomly swapping characters in the string. +The result is an anagram of +.IR string . +.SH RETURN VALUE +The +.BR strfry () +functions returns a pointer to the randomized +string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strfry () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +GNU. +.SH SEE ALSO +.BR memfrob (3), +.BR string (3) diff --git a/man/man3/strftime.3 b/man/man3/strftime.3 new file mode 100644 index 0000000..e94a3ef --- /dev/null +++ b/man/man3/strftime.3 @@ -0,0 +1,777 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" GNU texinfo documentation on glibc date/time functions. +.\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith (faith@cs.unc.edu) +.\" Applied fix by Wolfgang Franke, aeb, 961011 +.\" Corrected return value, aeb, 970307 +.\" Added Single UNIX Spec conversions and %z, aeb/esr, 990329. +.\" 2005-11-22 mtk, added glibc Notes covering optional 'flag' and +.\" 'width' components of conversion specifications. +.\" +.TH strftime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strftime \- format date and time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t strftime(char " s "[restrict ." max "], size_t " max , +.BI " const char *restrict " format , +.BI " const struct tm *restrict " tm ); +.P +.BI "size_t strftime_l(char " s "[restrict ." max "], size_t " max , +.BI " const char *restrict " format , +.BI " const struct tm *restrict " tm , +.BI " locale_t " locale ); +.fi +.SH DESCRIPTION +The +.BR strftime () +function formats the broken-down time +.I tm +according to the format specification +.I format +and places the +result in the character array +.I s +of size +.IR max . +The broken-down time structure +.I tm +is defined in +.IR . +See also +.BR ctime (3). +.\" FIXME . POSIX says: Local timezone information is used as though +.\" strftime() called tzset(). But this doesn't appear to be the case +.P +The format specification is a null-terminated string and may contain +special character sequences called +.IR "conversion specifications", +each of which is introduced by a \[aq]%\[aq] character and terminated by +some other character known as a +.IR "conversion specifier character". +All other character sequences are +.IR "ordinary character sequences". +.P +The characters of ordinary character sequences (including the null byte) +are copied verbatim from +.I format +to +.IR s . +However, the characters +of conversion specifications are replaced as shown in the list below. +In this list, the field(s) employed from the +.I tm +structure are also shown. +.TP +.B %a +The abbreviated name of the day of the week according to the current locale. +(Calculated from +.IR tm_wday .) +(The specific names used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.BR ABDAY_ { 1 \[en] 7 } +as an argument.) +.TP +.B %A +The full name of the day of the week according to the current locale. +(Calculated from +.IR tm_wday .) +(The specific names used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.BR DAY_ { 1 \[en] 7 } +as an argument.) +.TP +.B %b +The abbreviated month name according to the current locale. +(Calculated from +.IR tm_mon .) +(The specific names used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.BR ABMON_ { 1 \[en] 12 } +as an argument.) +.TP +.B %B +The full month name according to the current locale. +(Calculated from +.IR tm_mon .) +(The specific names used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.BR MON_ { 1 \[en] 12 } +as an argument.) +.TP +.B %c +The preferred date and time representation for the current locale. +(The specific format used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.B D_T_FMT +as an argument for the +.B %c +conversion specification, and with +.B ERA_D_T_FMT +for the +.B %Ec +conversion specification.) +(In the POSIX locale this is equivalent to +.BR "%a %b %e %H:%M:%S %Y" .) +.TP +.B %C +The century number (year/100) as a 2-digit integer. (SU) +(The +.B %EC +conversion specification corresponds to the name of the era.) +(Calculated from +.IR tm_year .) +.TP +.B %d +The day of the month as a decimal number (range 01 to 31). +(Calculated from +.IR tm_mday .) +.TP +.B %D +Equivalent to +.BR %m/%d/%y . +(Yecch\[em]for Americans only. +Americans should note that in other countries +.B %d/%m/%y +is rather common. +This means that in international context this format is +ambiguous and should not be used.) (SU) +.TP +.B %e +Like +.BR %d , +the day of the month as a decimal number, but a leading +zero is replaced by a space. (SU) +(Calculated from +.IR tm_mday .) +.TP +.B %E +Modifier: use alternative ("era-based") format, see below. (SU) +.TP +.B %F +Equivalent to +.B %Y\-%m\-%d +(the ISO\~8601 date format). (C99) +.TP +.B %G +The ISO\~8601 week-based year (see NOTES) with century as a decimal number. +The 4-digit year corresponding to the ISO week number (see +.BR %V ). +This has the same format and value as +.BR %Y , +except that if the ISO week number belongs to the previous or next year, +that year is used instead. (TZ) +(Calculated from +.IR tm_year , +.IR tm_yday , +and +.IR tm_wday .) +.TP +.B %g +Like +.BR %G , +but without century, that is, with a 2-digit year (00\[en]99). (TZ) +(Calculated from +.IR tm_year , +.IR tm_yday , +and +.IR tm_wday .) +.TP +.B %h +Equivalent to +.BR %b . +(SU) +.TP +.B %H +The hour as a decimal number using a 24-hour clock (range 00 to 23). +(Calculated from +.IR tm_hour .) +.TP +.B %I +The hour as a decimal number using a 12-hour clock (range 01 to 12). +(Calculated from +.IR tm_hour .) +.TP +.B %j +The day of the year as a decimal number (range 001 to 366). +(Calculated from +.IR tm_yday .) +.TP +.B %k +The hour (24-hour clock) as a decimal number (range 0 to 23); +single digits are preceded by a blank. +(See also +.BR %H .) +(Calculated from +.IR tm_hour .) +(TZ) +.TP +.B %l +The hour (12-hour clock) as a decimal number (range 1 to 12); +single digits are preceded by a blank. +(See also +.BR %I .) +(Calculated from +.IR tm_hour .) +(TZ) +.TP +.B %m +The month as a decimal number (range 01 to 12). +(Calculated from +.IR tm_mon .) +.TP +.B %M +The minute as a decimal number (range 00 to 59). +(Calculated from +.IR tm_min .) +.TP +.B %n +A newline character. (SU) +.TP +.B %O +Modifier: use alternative numeric symbols, see below. (SU) +.TP +.B %p +Either "AM" or "PM" according to the given time value, or the +corresponding strings for the current locale. +Noon is treated as "PM" and midnight as "AM". +(Calculated from +.IR tm_hour .) +(The specific string representations used for "AM" and "PM" +in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.BR AM_STR " and " PM_STR , +respectively.) +.TP +.B %P +Like +.B %p +but in lowercase: "am" or "pm" or a corresponding +string for the current locale. +(Calculated from +.IR tm_hour .) +(GNU) +.TP +.B %r +The time in a.m. or p.m. notation. +(SU) +(The specific format used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.B T_FMT_AMPM +as an argument.) +(In the POSIX locale this is equivalent to +.BR "%I:%M:%S %p" .) +.TP +.B %R +The time in 24-hour notation +.RB ( %H:%M ). +(SU) +For a version including the seconds, see +.B %T +below. +.TP +.B %s +The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ) +(Calculated from +.IR mktime(tm) .) +.TP +.B %S +The second as a decimal number (range 00 to 60). +(The range is up to 60 to allow for occasional leap seconds.) +(Calculated from +.IR tm_sec .) +.TP +.B %t +A tab character. (SU) +.TP +.B %T +The time in 24-hour notation +.RB ( %H:%M:%S ). +(SU) +.TP +.B %u +The day of the week as a decimal, range 1 to 7, Monday being 1. +See also +.BR %w . +(Calculated from +.IR tm_wday .) +(SU) +.TP +.B %U +The week number of the current year as a decimal number, +range 00 to 53, starting with the first Sunday as the first day +of week 01. +See also +.B %V +and +.BR %W . +(Calculated from +.I tm_yday +and +.IR tm_wday .) +.TP +.B %V +The ISO\~8601 week number (see NOTES) of the current year as a decimal number, +range 01 to 53, where week 1 is the first week that has at least +4 days in the new year. +See also +.B %U +and +.BR %W . +(Calculated from +.IR tm_year , +.IR tm_yday , +and +.IR tm_wday .) +(SU) +.TP +.B %w +The day of the week as a decimal, range 0 to 6, Sunday being 0. +See also +.BR %u . +(Calculated from +.IR tm_wday .) +.TP +.B %W +The week number of the current year as a decimal number, +range 00 to 53, starting with the first Monday as the first day of week 01. +(Calculated from +.I tm_yday +and +.IR tm_wday .) +.TP +.B %x +The preferred date representation for the current locale without the time. +(The specific format used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.B D_FMT +as an argument for the +.B %x +conversion specification, and with +.B ERA_D_FMT +for the +.B %Ex +conversion specification.) +(In the POSIX locale this is equivalent to +.BR %m/%d/%y .) +.TP +.B %X +The preferred time representation for the current locale without the date. +(The specific format used in the current locale can be obtained by calling +.BR nl_langinfo (3) +with +.B T_FMT +as an argument for the +.B %X +conversion specification, and with +.B ERA_T_FMT +for the +.B %EX +conversion specification.) +(In the POSIX locale this is equivalent to +.BR %H:%M:%S .) +.TP +.B %y +The year as a decimal number without a century (range 00 to 99). +(The +.B %Ey +conversion specification corresponds to the year since the beginning of the era +denoted by the +.B %EC +conversion specification.) +(Calculated from +.IR tm_year ) +.TP +.B %Y +The year as a decimal number including the century. +(The +.B %EY +conversion specification corresponds to +the full alternative year representation.) +(Calculated from +.IR tm_year ) +.TP +.B %z +The +.I +hhmm +or +.I \-hhmm +numeric timezone (that is, the hour and minute offset from UTC). (SU) +.TP +.B %Z +The timezone name or abbreviation. +.TP +.B %+ +.\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to +.\" their man pages) +The date and time in +.BR date (1) +format. (TZ) +(Not supported in glibc2.) +.TP +.B %% +A literal \[aq]%\[aq] character. +.P +Some conversion specifications can be modified by preceding the +conversion specifier character by the +.B E +or +.B O +.I modifier +to indicate that an alternative format should be used. +If the alternative format or specification does not exist for +the current locale, the behavior will be as if the unmodified +conversion specification were used. (SU) +The Single UNIX Specification mentions +.BR %Ec , +.BR %EC , +.BR %Ex , +.BR %EX , +.BR %Ey , +.BR %EY , +.BR %Od , +.BR %Oe , +.BR %OH , +.BR %OI , +.BR %Om , +.BR %OM , +.BR %OS , +.BR %Ou , +.BR %OU , +.BR %OV , +.BR %Ow , +.BR %OW , +.BR %Oy , +where the effect of the +.B O +modifier is to use +alternative numeric symbols (say, roman numerals), and that of the +.B E +modifier is to use a locale-dependent alternative representation. +The rules governing date representation with the +.B E +modifier can be obtained by supplying +.B ERA +as an argument to a +.BR nl_langinfo (3). +One example of such alternative forms is the Japanese era calendar scheme in the +.B ja_JP +glibc locale. +.P +.BR strftime_l () +is equivalent to +.BR strftime (), +except it uses the specified +.I locale +instead of the current locale. +The behaviour is undefined if +.I locale +is invalid or +.BR LC_GLOBAL_LOCALE . +.SH RETURN VALUE +Provided that the result string, +including the terminating null byte, does not exceed +.I max +bytes, +.BR strftime () +returns the number of bytes (excluding the terminating null byte) +placed in the array +.IR s . +If the length of the result string (including the terminating null byte) +would exceed +.I max +bytes, then +.BR strftime () +returns 0, and the contents of the array are undefined. +.\" (This behavior applies since at least libc 4.4.4; +.\" very old versions of libc, such as libc 4.4.1, +.\" would return +.\" .I max +.\" if the array was too small.) +.P +Note that the return value 0 does not necessarily indicate an error. +For example, in many locales +.B %p +yields an empty string. +An empty +.I format +string will likewise yield an empty string. +.SH ENVIRONMENT +The environment variables +.B TZ +and +.B LC_TIME +are used. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strftime (), +.BR strftime_l () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +.TP +.BR strftime () +C11, POSIX.1-2008. +.TP +.BR strftime_l () +POSIX.1-2008. +.SH HISTORY +.TP +.BR strftime () +SVr4, C89. +.\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details +.\" in the standards changed across versions. Investigate and +.\" write up. +.TP +.BR strftime_l () +POSIX.1-2008. +.P +There are strict inclusions between the set of conversions +given in ANSI C (unmarked), those given in the Single UNIX Specification +(marked SU), those given in Olson's timezone package (marked TZ), +and those given in glibc (marked GNU), except that +.B %+ +is not supported in glibc2. +On the other hand glibc2 has several more extensions. +POSIX.1 only refers to ANSI C; POSIX.2 describes under +.BR date (1) +several extensions that could apply to +.BR strftime () +as well. +The +.B %F +conversion is in C99 and POSIX.1-2001. +.P +In SUSv2, the +.B %S +specifier allowed a range of 00 to 61, +to allow for the theoretical possibility of a minute that +included a double leap second +(there never has been such a minute). +.SH NOTES +.SS ISO\~8601 week dates +.BR %G , +.BR %g , +and +.B %V +yield values calculated from the week-based year defined by the +ISO\~8601 standard. +In this system, weeks start on a Monday, and are numbered from 01, +for the first week, up to 52 or 53, for the last week. +Week 1 is the first week where four or more days fall within the +new year (or, synonymously, week 01 is: +the first week of the year that contains a Thursday; +or, the week that has 4 January in it). +When three or fewer days of the first calendar week of the new year fall +within that year, +then the ISO\~8601 week-based system counts those days as part of week 52 +or 53 of the preceding year. +For example, 1 January 2010 is a Friday, +meaning that just three days of that calendar week fall in 2010. +Thus, the ISO\~8601 week-based system considers these days to be part of +week 53 +.RB ( %V ) +of the year 2009 +.RB ( %G ); +week 01 of ISO\~8601 year 2010 starts on Monday, 4 January 2010. +Similarly, the first two days of January 2011 are considered to be part +of week 52 of the year 2010. +.SS glibc notes +glibc provides some extensions for conversion specifications. +(These extensions are not specified in POSIX.1-2001, but a few other +systems provide similar features.) +.\" HP-UX and Tru64 also have features like this. +Between the \[aq]%\[aq] character and the conversion specifier character, +an optional +.I flag +and field +.I width +may be specified. +(These precede the +.B E +or +.B O +modifiers, if present.) +.P +The following flag characters are permitted: +.TP +.B _ +(underscore) +Pad a numeric result string with spaces. +.TP +.B \- +(dash) +Do not pad a numeric result string. +.TP +.B 0 +Pad a numeric result string with zeros even if the conversion +specifier character uses space-padding by default. +.TP +.B \[ha] +Convert alphabetic characters in result string to uppercase. +.TP +.B # +Swap the case of the result string. +(This flag works only with certain conversion specifier characters, +and of these, it is only really useful with +.BR %Z .) +.P +An optional decimal width specifier may follow the (possibly absent) flag. +If the natural size of the field is smaller than this width, +then the result string is padded (on the left) to the specified width. +.SH BUGS +If the output string would exceed +.I max +bytes, +.I errno +is +.I not +set. +This makes it impossible to distinguish this error case from cases where the +.I format +string legitimately produces a zero-length output string. +POSIX.1-2001 +does +.I not +specify any +.I errno +settings for +.BR strftime (). +.P +Some buggy versions of +.BR gcc (1) +complain about the use of +.BR %c : +.IR "warning: \`%c\[aq] yields only last 2 digits of year in some locales" . +Of course programmers are encouraged to use +.BR %c , +as it gives the preferred date and time representation. +One meets all kinds of strange obfuscations +to circumvent this +.BR gcc (1) +problem. +A relatively clean one is to add an +intermediate function +.P +.in +4n +.EX +size_t +my_strftime(char *s, size_t max, const char *fmt, + const struct tm *tm) +{ + return strftime(s, max, fmt, tm); +} +.EE +.in +.P +Nowadays, +.BR gcc (1) +provides the +.I \-Wno\-format\-y2k +option to prevent the warning, +so that the above workaround is no longer required. +.SH EXAMPLES +.B RFC\~2822-compliant date format +(with an English locale for %a and %b) +.P +.in +4n +.EX +"%a,\ %d\ %b\ %Y\ %T\ %z" +.EE +.in +.P +.B RFC\~822-compliant date format +(with an English locale for %a and %b) +.P +.in +4n +.EX +"%a,\ %d\ %b\ %y\ %T\ %z" +.EE +.in +.SS Example program +The program below can be used to experiment with +.BR strftime (). +.P +Some examples of the result string produced by the glibc implementation of +.BR strftime () +are as follows: +.P +.in +4n +.EX +.RB "$" " ./a.out \[aq]%m\[aq]" +Result string is "11" +.RB "$" " ./a.out \[aq]%5m\[aq]" +Result string is "00011" +.RB "$" " ./a.out \[aq]%_5m\[aq]" +Result string is " 11" +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strftime.c) +.EX +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + char outstr[200]; + time_t t; + struct tm *tmp; +\& + t = time(NULL); + tmp = localtime(&t); + if (tmp == NULL) { + perror("localtime"); + exit(EXIT_FAILURE); + } +\& + if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) { + fprintf(stderr, "strftime returned 0"); + exit(EXIT_FAILURE); + } +\& + printf("Result string is \e"%s\e"\en", outstr); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR date (1), +.BR time (2), +.BR ctime (3), +.BR nl_langinfo (3), +.BR setlocale (3), +.BR sprintf (3), +.BR strptime (3) diff --git a/man/man3/strftime_l.3 b/man/man3/strftime_l.3 new file mode 100644 index 0000000..02e797a --- /dev/null +++ b/man/man3/strftime_l.3 @@ -0,0 +1 @@ +.so man3/strftime.3 diff --git a/man/man3/string.3 b/man/man3/string.3 new file mode 100644 index 0000000..c7069b6 --- /dev/null +++ b/man/man3/string.3 @@ -0,0 +1,217 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:54:31 1993, Rik Faith (faith@cs.unc.edu) +.TH string 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stpcpy, strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, +strdup, strfry, strlen, strncat, strncmp, strncpy, strncasecmp, strpbrk, +strrchr, strsep, strspn, strstr, strtok, strxfrm, index, rindex +\- string operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.B #include +.TP +.BI "int strcasecmp(const char *" s1 ", const char *" s2 ); +Compare the strings +.I s1 +and +.I s2 +ignoring case. +.TP +.BI "int strncasecmp(const char " s1 [. n "], const char " s2 [. n "], \ +size_t " n ); +Compare the first +.I n +bytes of the strings +.I s1 +and +.I s2 +ignoring case. +.TP +.BI "char *index(const char *" s ", int " c ); +Identical to +.BR strchr (3). +.TP +.BI "char *rindex(const char *" s ", int " c ); +Identical to +.BR strrchr (3). +.TP +.B #include +.TP +.BI "char *stpcpy(char *restrict " dest ", const char *restrict " src ); +Copy a string from +.I src +to +.IR dest , +returning a pointer to the end of the resulting string at +.IR dest . +.TP +.BI "char *strcat(char *restrict " dest ", const char *restrict " src ); +Append the string +.I src +to the string +.IR dest , +returning a pointer +.IR dest . +.TP +.BI "char *strchr(const char *" s ", int " c ); +Return a pointer to the first occurrence of the character +.I c +in the string +.IR s . +.TP +.BI "int strcmp(const char *" s1 ", const char *" s2 ); +Compare the strings +.I s1 +with +.IR s2 . +.TP +.BI "int strcoll(const char *" s1 ", const char *" s2 ); +Compare the strings +.I s1 +with +.I s2 +using the current locale. +.TP +.BI "char *strcpy(char *restrict " dest ", const char *restrict " src ); +Copy the string +.I src +to +.IR dest , +returning a pointer to the start of +.IR dest . +.TP +.BI "size_t strcspn(const char *" s ", const char *" reject ); +Calculate the length of the initial segment of the string +.I s +which does not contain any of bytes in the string +.IR reject , +.TP +.BI "char *strdup(const char *" s ); +Return a duplicate of the string +.I s +in memory allocated using +.BR malloc (3). +.TP +.BI "char *strfry(char *" string ); +Randomly swap the characters in +.IR string . +.TP +.BI "size_t strlen(const char *" s ); +Return the length of the string +.IR s . +.TP +.nf +.BI "char *strncat(char " dest "[restrict strlen(." dest ") + ." n " + 1]," +.BI " const char " src "[restrict ." n ], +.BI " size_t " n ); +.fi +Append at most +.I n +bytes from the unterminated string +.I src +to the string +.IR dest , +returning a pointer to +.IR dest . +.TP +.BI "int strncmp(const char " s1 [. n "], const char " s2 [. n "], size_t " n ); +Compare at most +.I n +bytes of the strings +.I s1 +and +.IR s2 . +.TP +.BI "char *strpbrk(const char *" s ", const char *" accept ); +Return a pointer to the first occurrence in the string +.I s +of one of the bytes in the string +.IR accept . +.TP +.BI "char *strrchr(const char *" s ", int " c ); +Return a pointer to the last occurrence of the character +.I c +in the string +.IR s . +.TP +.BI "char *strsep(char **restrict " stringp ", const char *restrict " delim ); +Extract the initial token in +.I stringp +that is delimited by one of the bytes in +.IR delim . +.TP +.BI "size_t strspn(const char *" s ", const char *" accept ); +Calculate the length of the starting segment in the string +.I s +that consists entirely of bytes in +.IR accept . +.TP +.BI "char *strstr(const char *" haystack ", const char *" needle ); +Find the first occurrence of the substring +.I needle +in the string +.IR haystack , +returning a pointer to the found substring. +.TP +.BI "char *strtok(char *restrict " s ", const char *restrict " delim ); +Extract tokens from the string +.I s +that are delimited by one of the bytes in +.IR delim . +.TP +.nf +.BI "size_t strxfrm(char " dest "[restrict ." n "], \ +const char " src "[restrict ." n ], +.BI " size_t " n ); +.fi +Transforms +.I src +to the current locale and copies the first +.I n +bytes to +.IR dest . +.TP +.nf +.BI "char *strncpy(char " dest "[restrict ." n "], \ +const char " src "[restrict ." n ], +.BI " size_t " n ); +.fi +Fill a fixed-size buffer with leading non-null bytes from a source array, +padding with null bytes as needed. +.SH DESCRIPTION +The string functions perform operations on null-terminated +strings. +See the individual man pages for descriptions of each function. +.SH SEE ALSO +.BR bstring (3), +.BR stpcpy (3), +.BR strcasecmp (3), +.BR strcat (3), +.BR strchr (3), +.BR strcmp (3), +.BR strcoll (3), +.BR strcpy (3), +.BR strcspn (3), +.BR strdup (3), +.BR strfry (3), +.BR strlen (3), +.BR strncasecmp (3), +.BR strncat (3), +.BR strncmp (3), +.BR strncpy (3), +.BR strpbrk (3), +.BR strrchr (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR strxfrm (3) diff --git a/man/man3/strlen.3 b/man/man3/strlen.3 new file mode 100644 index 0000000..69aa2e8 --- /dev/null +++ b/man/man3/strlen.3 @@ -0,0 +1,61 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:02:26 1993 by Rik Faith (faith@cs.unc.edu) +.TH strlen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strlen \- calculate the length of a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t strlen(const char *" s ); +.fi +.SH DESCRIPTION +The +.BR strlen () +function calculates the length of the string pointed to by +.IR s , +excluding the terminating null byte (\[aq]\e0\[aq]). +.SH RETURN VALUE +The +.BR strlen () +function returns the number of bytes in the string pointed to by +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strlen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH NOTES +In cases where the input buffer may not contain +a terminating null byte, +.BR strnlen (3) +should be used instead. +.SH SEE ALSO +.BR string (3), +.BR strnlen (3), +.BR wcslen (3), +.BR wcsnlen (3) diff --git a/man/man3/strncasecmp.3 b/man/man3/strncasecmp.3 new file mode 100644 index 0000000..fd3b671 --- /dev/null +++ b/man/man3/strncasecmp.3 @@ -0,0 +1 @@ +.so man3/strcasecmp.3 diff --git a/man/man3/strncat.3 b/man/man3/strncat.3 new file mode 100644 index 0000000..275e8d0 --- /dev/null +++ b/man/man3/strncat.3 @@ -0,0 +1,132 @@ +'\" t +.\" Copyright 2022 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH strncat 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strncat +\- +append non-null bytes from a source array to a string, +and null-terminate the result +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." ssize ], +.BI " size_t " ssize ); +.fi +.SH DESCRIPTION +This function appends at most +.I ssize +non-null bytes from the array pointed to by +.IR src , +followed by a null character, +to the end of the string pointed to by +.IR dst . +.I dst +must point to a string contained in a buffer that is large enough, +that is, the buffer size must be at least +.IR "strlen(dst) + strnlen(src, ssize) + 1" . +.P +An implementation of this function might be: +.P +.in +4n +.EX +char * +strncat(char *restrict dst, const char *restrict src, size_t ssize) +{ + #define strnul(s) (s + strlen(s)) +\& + stpcpy(mempcpy(strnul(dst), src, strnlen(src, ssize)), ""); + return dst; +} +.EE +.in +.SH RETURN VALUE +.BR strncat () +returns +.IR dst . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strncat () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH CAVEATS +The name of this function is confusing; +it has no relation to +.BR strncpy (3). +.P +If the destination buffer does not already contain a string, +or is not large enough, +the behavior is undefined. +See +.B _FORTIFY_SOURCE +in +.BR feature_test_macros (7). +.SH BUGS +This function can be very inefficient. +Read about +.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ +Shlemiel the painter +.UE . +.SH EXAMPLES +.\" SRC BEGIN (strncat.c) +.EX +#include +#include +#include +#include +\& +#define nitems(arr) (sizeof((arr)) / sizeof((arr)[0])) +\& +int +main(void) +{ + size_t n; +\& + // Null-padded fixed-size character sequences + char pre[4] = "pre."; + char new_post[50] = ".foo.bar"; +\& + // Strings + char post[] = ".post"; + char src[] = "some_long_body.post"; + char *dest; +\& + n = nitems(pre) + strlen(src) \- strlen(post) + nitems(new_post) + 1; + dest = malloc(sizeof(*dest) * n); + if (dest == NULL) + err(EXIT_FAILURE, "malloc()"); +\& + dest[0] = \[aq]\e0\[aq]; // There's no 'cpy' function to this 'cat'. + strncat(dest, pre, nitems(pre)); + strncat(dest, src, strlen(src) \- strlen(post)); + strncat(dest, new_post, nitems(new_post)); +\& + puts(dest); // "pre.some_long_body.foo.bar" + free(dest); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR string (3), +.BR string_copying (7) diff --git a/man/man3/strncmp.3 b/man/man3/strncmp.3 new file mode 100644 index 0000000..1007f43 --- /dev/null +++ b/man/man3/strncmp.3 @@ -0,0 +1 @@ +.so man3/strcmp.3 diff --git a/man/man3/strncpy.3 b/man/man3/strncpy.3 new file mode 100644 index 0000000..4710b02 --- /dev/null +++ b/man/man3/strncpy.3 @@ -0,0 +1 @@ +.so man3/stpncpy.3 diff --git a/man/man3/strndup.3 b/man/man3/strndup.3 new file mode 100644 index 0000000..2dd8f88 --- /dev/null +++ b/man/man3/strndup.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man/man3/strndupa.3 b/man/man3/strndupa.3 new file mode 100644 index 0000000..2dd8f88 --- /dev/null +++ b/man/man3/strndupa.3 @@ -0,0 +1 @@ +.so man3/strdup.3 diff --git a/man/man3/strnlen.3 b/man/man3/strnlen.3 new file mode 100644 index 0000000..147f9aa --- /dev/null +++ b/man/man3/strnlen.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" +.TH strnlen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strnlen \- determine the length of a fixed-size string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t strnlen(const char " s [. maxlen "], size_t " maxlen ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strnlen (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR strnlen () +function returns the number of bytes in the string +pointed to by +.IR s , +excluding the terminating null byte (\[aq]\e0\[aq]), +but at most +.IR maxlen . +In doing this, +.BR strnlen () +looks only at the first +.I maxlen +characters in the string pointed to by +.I s +and never beyond +.IR s[maxlen\-1] . +.SH RETURN VALUE +The +.BR strnlen () +function returns +.IR strlen(s) , +if that is less than +.IR maxlen , +or +.I maxlen +if there is no null terminating (\[aq]\e0\[aq]) among the first +.I maxlen +characters pointed to by +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strnlen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2008. +.SH SEE ALSO +.BR strlen (3) diff --git a/man/man3/strpbrk.3 b/man/man3/strpbrk.3 new file mode 100644 index 0000000..2ad85af --- /dev/null +++ b/man/man3/strpbrk.3 @@ -0,0 +1,66 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:01:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH strpbrk 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strpbrk \- search a string for any of a set of bytes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *strpbrk(const char *" s ", const char *" accept ); +.fi +.SH DESCRIPTION +The +.BR strpbrk () +function locates the first occurrence in the +string +.I s +of any of the bytes in the string +.IR accept . +.SH RETURN VALUE +The +.BR strpbrk () +function returns a pointer to the byte in +.I s +that matches one of the bytes in +.IR accept , +or NULL +if no such byte is found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strpbrk () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR memchr (3), +.BR strchr (3), +.BR string (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3), +.BR wcspbrk (3) diff --git a/man/man3/strptime.3 b/man/man3/strptime.3 new file mode 100644 index 0000000..ba6c383 --- /dev/null +++ b/man/man3/strptime.3 @@ -0,0 +1,413 @@ +'\" t +.\" Copyright 1993 Mitchum DSouza +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified, jmv@lucifer.dorms.spbu.ru, 1999-11-08 +.\" Modified, aeb, 2000-04-07 +.\" Updated from glibc docs, C. Scott Ananian, 2001-08-25 +.\" Modified, aeb, 2001-08-31 +.\" Modified, wharms 2001-11-12, remark on white space and example +.\" +.TH strptime 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strptime \- convert a string representation of time to a time tm structure +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "char *strptime(const char *restrict " s ", const char *restrict " format , +.BI " struct tm *restrict " tm ); +.fi +.SH DESCRIPTION +The +.BR strptime () +function is the converse of +.BR strftime (3); +it converts the character string pointed to by +.I s +to values which are stored in the +"broken-down time" +structure pointed to by +.IR tm , +using the format specified by +.IR format . +.P +The broken-down time structure +.I tm +is described in +.BR tm (3type). +.P +The +.I format +argument +is a character string that consists of field descriptors and text characters, +reminiscent of +.BR scanf (3). +Each field descriptor consists of a +.B % +character followed by another character that specifies the replacement +for the field descriptor. +All other characters in the +.I format +string must have a matching character in the input string, +except for whitespace, which matches zero or more +whitespace characters in the input string. +There should be white\%space or other alphanumeric characters +between any two field descriptors. +.P +The +.BR strptime () +function processes the input string from left +to right. +Each of the three possible input elements (whitespace, +literal, or format) are handled one after the other. +If the input cannot be matched to the format string, the function stops. +The remainder of the format and input strings are not processed. +.P +The supported input field descriptors are listed below. +In case a text string (such as the name of a day of the week or a month name) +is to be matched, the comparison is case insensitive. +In case a number is to be matched, leading zeros are +permitted but not required. +.TP +.B %% +The +.B % +character. +.TP +.BR %a " or " %A +The name of the day of the week according to the current locale, +in abbreviated form or the full name. +.TP +.BR %b " or " %B " or " %h +The month name according to the current locale, +in abbreviated form or the full name. +.TP +.B %c +The date and time representation for the current locale. +.TP +.B %C +The century number (0\[en]99). +.TP +.BR %d " or " %e +The day of month (1\[en]31). +.TP +.B %D +Equivalent to +.BR %m/%d/%y . +(This is the American style date, very confusing +to non-Americans, especially since +.B %d/%m/%y +is widely used in Europe. +The ISO\~8601 standard format is +.BR %Y\-%m\-%d .) +.TP +.B %H +The hour (0\[en]23). +.TP +.B %I +The hour on a 12-hour clock (1\[en]12). +.TP +.B %j +The day number in the year (1\[en]366). +.TP +.B %m +The month number (1\[en]12). +.TP +.B %M +The minute (0\[en]59). +.TP +.B %n +Arbitrary whitespace. +.TP +.B %p +The locale's equivalent of AM or PM. +(Note: there may be none.) +.TP +.B %r +The 12-hour clock time (using the locale's AM or PM). +In the POSIX locale equivalent to +.BR "%I:%M:%S %p" . +If +.I t_fmt_ampm +is empty in the +.B LC_TIME +part of the current locale, +then the behavior is undefined. +.TP +.B %R +Equivalent to +.BR %H:%M . +.TP +.B %S +The second (0\[en]60; 60 may occur for leap seconds; +earlier also 61 was allowed). +.TP +.B %t +Arbitrary whitespace. +.TP +.B %T +Equivalent to +.BR %H:%M:%S . +.TP +.B %U +The week number with Sunday the first day of the week (0\[en]53). +The first Sunday of January is the first day of week 1. +.TP +.B %w +The ordinal number of the day of the week (0\[en]6), with Sunday = 0. +.TP +.B %W +The week number with Monday the first day of the week (0\[en]53). +The first Monday of January is the first day of week 1. +.TP +.B %x +The date, using the locale's date format. +.TP +.B %X +The time, using the locale's time format. +.TP +.B %y +The year within century (0\[en]99). +When a century is not otherwise specified, values in the range 69\[en]99 refer +to years in the twentieth century (1969\[en]1999); values in the +range 00\[en]68 refer to years in the twenty-first century (2000\[en]2068). +.TP +.B %Y +The year, including century (for example, 1991). +.P +Some field descriptors can be modified by the E or O modifier characters +to indicate that an alternative format or specification should be used. +If the +alternative format or specification does not exist in the current locale, the +unmodified field descriptor is used. +.P +The E modifier specifies that the input string may contain +alternative locale-dependent versions of the date and time representation: +.TP +.B %Ec +The locale's alternative date and time representation. +.TP +.B %EC +The name of the base year (period) in the locale's alternative representation. +.TP +.B %Ex +The locale's alternative date representation. +.TP +.B %EX +The locale's alternative time representation. +.TP +.B %Ey +The offset from +.B %EC +(year only) in the locale's alternative representation. +.TP +.B %EY +The full alternative year representation. +.P +The O modifier specifies that the numerical input may be in an +alternative locale-dependent format: +.TP +.BR %Od " or " %Oe +The day of the month using the locale's alternative numeric symbols; +leading zeros are permitted but not required. +.TP +.B %OH +The hour (24-hour clock) using the locale's alternative numeric symbols. +.TP +.B %OI +The hour (12-hour clock) using the locale's alternative numeric symbols. +.TP +.B %Om +The month using the locale's alternative numeric symbols. +.TP +.B %OM +The minutes using the locale's alternative numeric symbols. +.TP +.B %OS +The seconds using the locale's alternative numeric symbols. +.TP +.B %OU +The week number of the year (Sunday as the first day of the week) +using the locale's alternative numeric symbols. +.TP +.B %Ow +The ordinal number of the day of the week (Sunday=0), +using the locale's alternative numeric symbols. +.TP +.B %OW +The week number of the year (Monday as the first day of the week) +using the locale's alternative numeric symbols. +.TP +.B %Oy +The year (offset from +.BR %C ) +using the locale's alternative numeric symbols. +.SH RETURN VALUE +The return value of the function is a pointer to the first character +not processed in this function call. +In case the input string +contains more characters than required by the format string, the return +value points right after the last consumed input character. +In case the whole input string is consumed, +the return value points to the null byte at the end of the string. +If +.BR strptime () +fails to match all +of the format string and therefore an error occurred, the function +returns NULL. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strptime () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SUSv2. +.SH NOTES +In principle, this function does not initialize +.I tm +but +stores only the values specified. +This means that +.I tm +should be initialized before the call. +Details differ a bit between different UNIX systems. +The glibc implementation does not touch those fields which are not +explicitly specified, except that it recomputes the +.I tm_wday +and +.I tm_yday +field if any of the year, month, or day elements changed. +.\" .P +.\" This function is available since libc 4.6.8. +.\" Linux libc4 and libc5 includes define the prototype unconditionally; +.\" glibc2 includes provide a prototype only when +.\" .B _XOPEN_SOURCE +.\" or +.\" .B _GNU_SOURCE +.\" are defined. +.\" .P +.\" Before libc 5.4.13 whitespace +.\" (and the \[aq]n\[aq] and \[aq]t\[aq] specifications) was not handled, +.\" no \[aq]E\[aq] and \[aq]O\[aq] locale modifier characters were accepted, +.\" and the \[aq]C\[aq] specification was a synonym for the \[aq]c\[aq] specification. +.P +The \[aq]y\[aq] (year in century) specification is taken to specify a year +.\" in the 20th century by libc4 and libc5. +.\" It is taken to be a year +in the range 1950\[en]2049 by glibc 2.0. +It is taken to be a year in +1969\[en]2068 since glibc 2.1. +.\" In libc4 and libc5 the code for %I is broken (fixed in glibc; +.\" %OI was fixed in glibc 2.2.4). +.SS glibc notes +For reasons of symmetry, glibc tries to support for +.BR strptime () +the same format characters as for +.BR strftime (3). +(In most cases, the corresponding fields are parsed, but no field in +.I tm +is changed.) +This leads to +.TP +.B %F +Equivalent to +.BR %Y\-%m\-%d , +the ISO\~8601 date format. +.TP +.B %g +The year corresponding to the ISO week number, but without the century +(0\[en]99). +.TP +.B %G +The year corresponding to the ISO week number. +(For example, 1991.) +.TP +.B %u +The day of the week as a decimal number (1\[en]7, where Monday = 1). +.TP +.B %V +The ISO\~8601:1988 week number as a decimal number (1\[en]53). +If the week (starting on Monday) containing 1 January has four or more days +in the new year, then it is considered week 1. +Otherwise, it is the last week +of the previous year, and the next week is week 1. +.TP +.B %z +An RFC-822/ISO\~8601 standard timezone specification. +.TP +.B %Z +The timezone name. +.P +Similarly, because of GNU extensions to +.BR strftime (3), +.B %k +is accepted as a synonym for +.BR %H , +and +.B %l +should be accepted +as a synonym for +.BR %I , +and +.B %P +is accepted as a synonym for +.BR %p . +Finally +.TP +.B %s +The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +Leap seconds are not counted unless leap second support is available. +.P +The glibc implementation does not require whitespace between +two field descriptors. +.SH EXAMPLES +The following example demonstrates the use of +.BR strptime () +and +.BR strftime (3). +.P +.\" SRC BEGIN (strptime.c) +.EX +#define _XOPEN_SOURCE +#include +#include +#include +#include +\& +int +main(void) +{ + struct tm tm; + char buf[255]; +\& + memset(&tm, 0, sizeof(tm)); + strptime("2001\-11\-12 18:31:01", "%Y\-%m\-%d %H:%M:%S", &tm); + strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm); + puts(buf); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR time (2), +.BR getdate (3), +.BR scanf (3), +.BR setlocale (3), +.BR strftime (3) diff --git a/man/man3/strrchr.3 b/man/man3/strrchr.3 new file mode 100644 index 0000000..322b7a8 --- /dev/null +++ b/man/man3/strrchr.3 @@ -0,0 +1 @@ +.so man3/strchr.3 diff --git a/man/man3/strsep.3 b/man/man3/strsep.3 new file mode 100644 index 0000000..a3f0153 --- /dev/null +++ b/man/man3/strsep.3 @@ -0,0 +1,162 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 18:00:10 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Jan 20 12:04:18 1997 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Tue Jan 23 20:23:07 2001 by Andries Brouwer (aeb@cwi.nl) +.\" +.TH strsep 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strsep \- extract token from string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *strsep(char **restrict " stringp ", const char *restrict " delim ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strsep (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +If +.I *stringp +is NULL, the +.BR strsep () +function returns NULL +and does nothing else. +Otherwise, this function finds the first token +in the string +.I *stringp +that is delimited by one of the bytes in the string +.IR delim . +This token is terminated by overwriting the delimiter +with a null byte (\[aq]\e0\[aq]), +and +.I *stringp +is updated to point past the token. +In case no delimiter was found, the token is taken to be +the entire string +.IR *stringp , +and +.I *stringp +is made NULL. +.SH RETURN VALUE +The +.BR strsep () +function returns a pointer to the token, +that is, it returns the original value of +.IR *stringp . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strsep () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.4BSD. +.P +The +.BR strsep () +function was introduced as a replacement for +.BR strtok (3), +since the latter cannot handle empty fields. +However, +.BR strtok (3) +conforms to C89/C99 and hence is more portable. +.SH BUGS +Be cautious when using this function. +If you do use it, note that: +.IP \[bu] 3 +This function modifies its first argument. +.IP \[bu] +This function cannot be used on constant strings. +.IP \[bu] +The identity of the delimiting character is lost. +.SH EXAMPLES +The program below is a port of the one found in +.BR strtok (3), +which, however, doesn't discard multiple delimiters or empty tokens: +.P +.in +4n +.EX +.RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]" +1: a/bbb///cc + \-\-> a + \-\-> bbb + \-\-> + \-\-> + \-\-> cc +2: xxx + \-\-> xxx +3: yyy + \-\-> yyy +4: + \-\-> +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strsep.c) +.EX +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + char *token, *subtoken; +\& + if (argc != 4) { + fprintf(stderr, "Usage: %s string delim subdelim\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + for (unsigned int j = 1; (token = strsep(&argv[1], argv[2])); j++) { + printf("%u: %s\en", j, token); +\& + while ((subtoken = strsep(&token, argv[3]))) + printf("\et \-\-> %s\en", subtoken); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR memchr (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strspn (3), +.BR strstr (3), +.BR strtok (3) diff --git a/man/man3/strsignal.3 b/man/man3/strsignal.3 new file mode 100644 index 0000000..168cde4 --- /dev/null +++ b/man/man3/strsignal.3 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright (C) 2020 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:59:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH strsignal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strsignal, sigabbrev_np, sigdescr_np, sys_siglist \- +return string describing signal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *strsignal(int " sig ); +.BI "const char *sigdescr_np(int " sig ); +.BI "const char *sigabbrev_np(int " sig ); +.P +.BI "[[deprecated]] extern const char *const " sys_siglist []; +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR sigabbrev_np (), +.BR sigdescr_np (): +.nf + _GNU_SOURCE +.fi +.P +.BR strsignal (): +.nf + From glibc 2.10 to glibc 2.31: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.P +.IR sys_siglist : +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR strsignal () +function returns a string describing the signal +number passed in the argument +.IR sig . +The string can be used only until the next call to +.BR strsignal (). +The string returned by +.BR strsignal () +is localized according to the +.B LC_MESSAGES +category in the current locale. +.P +The +.BR sigdescr_np () +function returns a string describing the signal +number passed in the argument +.IR sig . +Unlike +.BR strsignal () +this string is not influenced by the current locale. +.P +The +.BR sigabbrev_np () +function returns the abbreviated name of the signal, +.IR sig . +For example, given the value +.BR SIGINT , +it returns the string "INT". +.P +The (deprecated) array +.I sys_siglist +holds the signal description strings +indexed by signal number. +The +.BR strsignal () +or the +.BR sigdescr_np () +function should be used instead of this array; see also VERSIONS. +.SH RETURN VALUE +The +.BR strsignal () +function returns the appropriate description +string, or an unknown signal message if the signal number is invalid. +On some systems (but not on Linux), NULL may instead be +returned for an invalid signal number. +.P +The +.BR sigdescr_np () +and +.BR sigabbrev_np () +functions return the appropriate description string. +The returned string is statically allocated and valid for +the lifetime of the program. +These functions return NULL for an invalid signal number. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strsignal () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:strsignal locale +T} +T{ +.na +.nh +.BR sigdescr_np (), +.BR sigabbrev_np () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR strsignal () +POSIX.1-2008. +.TP +.BR sigdescr_np () +.TQ +.BR sigabbrev_np () +GNU. +.TP +.I sys_siglist +None. +.\" glibc commit b1ccfc061feee9ce616444ded8e1cd5acf9fa97f +.SH HISTORY +.TP +.BR strsignal () +POSIX.1-2008. +Solaris, BSD. +.TP +.BR sigdescr_np () +.TQ +.BR sigabbrev_np () +glibc 2.32. +.TP +.I sys_siglist +Removed in glibc 2.32. +.SH NOTES +.BR sigdescr_np () +and +.BR sigabbrev_np () +are thread-safe and async-signal-safe. +.SH SEE ALSO +.BR psignal (3), +.BR strerror (3) diff --git a/man/man3/strspn.3 b/man/man3/strspn.3 new file mode 100644 index 0000000..c1739c5 --- /dev/null +++ b/man/man3/strspn.3 @@ -0,0 +1,85 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:57:50 1993 by Rik Faith (faith@cs.unc.edu) +.TH strspn 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strspn, strcspn \- get length of a prefix substring +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t strspn(const char *" s ", const char *" accept ); +.BI "size_t strcspn(const char *" s ", const char *" reject ); +.fi +.SH DESCRIPTION +The +.BR strspn () +function calculates the length (in bytes) of the initial +segment of +.I s +which consists entirely of bytes in +.IR accept . +.P +The +.BR strcspn () +function calculates the length of the initial +segment of +.I s +which consists entirely of bytes not in +.IR reject . +.SH RETURN VALUE +The +.BR strspn () +function returns the number of bytes in +the initial segment of +.I s +which consist only of bytes +from +.IR accept . +.P +The +.BR strcspn () +function returns the number of bytes in +the initial segment of +.I s +which are not in the string +.IR reject . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strspn (), +.BR strcspn () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR memchr (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strstr (3), +.BR strtok (3), +.BR wcscspn (3), +.BR wcsspn (3) diff --git a/man/man3/strstr.3 b/man/man3/strstr.3 new file mode 100644 index 0000000..c62469d --- /dev/null +++ b/man/man3/strstr.3 @@ -0,0 +1,98 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:56:43 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added history, aeb, 980113. +.\" 2005-05-05 mtk: added strcasestr() +.\" +.TH strstr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strstr, strcasestr \- locate a substring +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *strstr(const char *" haystack ", const char *" needle ); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "char *strcasestr(const char *" haystack ", const char *" needle ); +.fi +.SH DESCRIPTION +The +.BR strstr () +function finds the first occurrence of the substring +.I needle +in the string +.IR haystack . +The terminating null bytes (\[aq]\e0\[aq]) are not compared. +.P +The +.BR strcasestr () +function is like +.BR strstr (), +but ignores the case of both arguments. +.SH RETURN VALUE +These functions return a pointer to the beginning of the +located substring, or NULL if the substring is not found. +.P +If +.I needle +is the empty string, +the return value is always +.I haystack +itself. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strstr () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR strcasestr () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +.TP +.BR strstr () +C11, POSIX.1-2008. +.TP +.BR strcasestr () +GNU. +.SH HISTORY +.TP +.BR strstr () +POSIX.1-2001, C89. +.TP +.BR strcasestr () +GNU. +.SH SEE ALSO +.BR memchr (3), +.BR memmem (3), +.BR strcasecmp (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strtok (3), +.BR wcsstr (3) diff --git a/man/man3/strtod.3 b/man/man3/strtod.3 new file mode 100644 index 0000000..c1b36cc --- /dev/null +++ b/man/man3/strtod.3 @@ -0,0 +1,205 @@ +'\" t +.\" Copyright (c) 1990, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)strtod.3 5.3 (Berkeley) 6/29/91 +.\" +.\" Modified Sun Aug 21 17:16:22 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat May 04 19:34:31 MET DST 1996 by Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de) +.\" Added strof, strtold, aeb, 2001-06-07 +.\" +.TH strtod 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtod, strtof, strtold \- convert ASCII string to floating-point number +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double strtod(const char *restrict " nptr ", char **restrict " endptr ); +.BI "float strtof(const char *restrict " nptr ", char **restrict " endptr ); +.BI "long double strtold(const char *restrict " nptr \ +", char **restrict " endptr ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strtof (), +.BR strtold (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR strtod (), +.BR strtof (), +and +.BR strtold () +functions convert the initial portion of the string pointed to by +.I nptr +to +.IR double , +.IR float , +and +.I long double +representation, respectively. +.P +The expected form of the (initial portion of the) string is +optional leading white space as recognized by +.BR isspace (3), +an optional plus (\[aq]+\[aq]) or minus sign (\[aq]\-\[aq]) and then either +(i) a decimal number, or (ii) a hexadecimal number, +or (iii) an infinity, or (iv) a NAN (not-a-number). +.P +A +.I "decimal number" +consists of a nonempty sequence of decimal digits +possibly containing a radix character (decimal point, locale-dependent, +usually \[aq].\[aq]), optionally followed by a decimal exponent. +A decimal exponent consists of an \[aq]E\[aq] or \[aq]e\[aq], followed by an +optional plus or minus sign, followed by a nonempty sequence of +decimal digits, and indicates multiplication by a power of 10. +.P +A +.I "hexadecimal number" +consists of a "0x" or "0X" followed by a nonempty sequence of +hexadecimal digits possibly containing a radix character, +optionally followed by a binary exponent. +A binary exponent +consists of a \[aq]P\[aq] or \[aq]p\[aq], followed by an optional +plus or minus sign, followed by a nonempty sequence of +decimal digits, and indicates multiplication by a power of 2. +At least one of radix character and binary exponent must be present. +.P +An +.I infinity +is either "INF" or "INFINITY", disregarding case. +.P +A +.I NAN +is "NAN" (disregarding case) optionally followed by a string, +.IR (n-char-sequence) , +where +.I n-char-sequence +specifies in an implementation-dependent +way the type of NAN (see NOTES). +.SH RETURN VALUE +These functions return the converted value, if any. +.P +If +.I endptr +is not NULL, +a pointer to the character after the last character used in the conversion +is stored in the location referenced by +.IR endptr . +.P +If no conversion is performed, zero is returned and (unless +.I endptr +is null) the value of +.I nptr +is stored in the location referenced by +.IR endptr . +.P +If the correct value would cause overflow, plus or minus +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.B HUGE_VALL +is returned (according to the return type and sign of the value), +and +.B ERANGE +is stored in +.IR errno . +.P +If the correct value would cause underflow, +a value with magnitude no larger than +.BR DBL_MIN , +.BR FLT_MIN , +or +.B LDBL_MIN +is returned and +.B ERANGE +is stored in +.IR errno . +.SH ERRORS +.TP +.B ERANGE +Overflow or underflow occurred. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtod (), +.BR strtof (), +.BR strtold () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +In the glibc implementation, the +.I n-char-sequence +that optionally follows "NAN" +is interpreted as an integer number +(with an optional '0' or '0x' prefix to select base 8 or 16) +that is to be placed in the +mantissa component of the returned value. +.\" From glibc 2.8's stdlib/strtod_l.c: +.\" We expect it to be a number which is put in the +.\" mantissa of the number. +.\" It looks as though at least FreeBSD (according to the manual) does +.\" something similar. +.\" C11 says: "An implementation may use the n-char sequence to determine +.\" extra information to be represented in the NaN's significant." +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR strtod () +C89, POSIX.1-2001. +.TP +.BR strtof () +.TQ +.BR strtold () +C99, POSIX.1-2001. +.SH NOTES +Since +0 can legitimately be returned +on both success and failure, the calling program should set +.I errno +to 0 before the call, +and then determine if an error occurred by checking whether +.I errno +has a nonzero value after the call. +.SH EXAMPLES +See the example on the +.BR strtol (3) +manual page; +the use of the functions described in this manual page is similar. +.SH SEE ALSO +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR nan (3), +.BR nanf (3), +.BR nanl (3), +.BR strfromd (3), +.BR strtol (3), +.BR strtoul (3) diff --git a/man/man3/strtof.3 b/man/man3/strtof.3 new file mode 100644 index 0000000..ac3e4a5 --- /dev/null +++ b/man/man3/strtof.3 @@ -0,0 +1 @@ +.so man3/strtod.3 diff --git a/man/man3/strtoimax.3 b/man/man3/strtoimax.3 new file mode 100644 index 0000000..54799d5 --- /dev/null +++ b/man/man3/strtoimax.3 @@ -0,0 +1,68 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH strtoimax 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtoimax, strtoumax \- convert string to integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "intmax_t strtoimax(const char *restrict " nptr ", char **restrict " endptr , +.BI " int " base ); +.BI "uintmax_t strtoumax(const char *restrict " nptr ", char **restrict " endptr , +.BI " int " base ); +.fi +.SH DESCRIPTION +These functions are just like +.BR strtol (3) +and +.BR strtoul (3), +except that they return a value of type +.I intmax_t +and +.IR uintmax_t , +respectively. +.SH RETURN VALUE +On success, the converted value is returned. +If nothing was found to convert, zero is returned. +On overflow or underflow +.B INTMAX_MAX +or +.B INTMAX_MIN +or +.B UINTMAX_MAX +is returned, and +.I errno +is set to +.BR ERANGE . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtoimax (), +.BR strtoumax () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR imaxabs (3), +.BR imaxdiv (3), +.BR strtol (3), +.BR strtoul (3), +.BR wcstoimax (3) diff --git a/man/man3/strtok.3 b/man/man3/strtok.3 new file mode 100644 index 0000000..efd56de --- /dev/null +++ b/man/man3/strtok.3 @@ -0,0 +1,288 @@ +'\" t +.\" Copyright (C) 2005, 2013 Michael Kerrisk +.\" a few fragments from an earlier (1996) version by +.\" Andries Brouwer (aeb@cwi.nl) remain. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Rewritten old page, 960210, aeb@cwi.nl +.\" Updated, added strtok_r. 2000-02-13 Nicolás Lichtmaier +.\" 2005-11-17, mtk: Substantial parts rewritten +.\" 2013-05-19, mtk: added much further detail on the operation of strtok() +.\" +.TH strtok 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtok, strtok_r \- extract tokens from strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *strtok(char *restrict " str ", const char *restrict " delim ); +.BI "char *strtok_r(char *restrict " str ", const char *restrict " delim , +.BI " char **restrict " saveptr ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strtok_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR strtok () +function breaks a string into a sequence of zero or more nonempty tokens. +On the first call to +.BR strtok (), +the string to be parsed should be +specified in +.IR str . +In each subsequent call that should parse the same string, +.I str +must be NULL. +.P +The +.I delim +argument specifies a set of bytes that +delimit the tokens in the parsed string. +The caller may specify different strings in +.I delim +in successive +calls that parse the same string. +.P +Each call to +.BR strtok () +returns a pointer to a +null-terminated string containing the next token. +This string does not include the delimiting byte. +If no more tokens are found, +.BR strtok () +returns NULL. +.P +A sequence of calls to +.BR strtok () +that operate on the same string maintains a pointer +that determines the point from which to start searching for the next token. +The first call to +.BR strtok () +sets this pointer to point to the first byte of the string. +The start of the next token is determined by scanning forward +for the next nondelimiter byte in +.IR str . +If such a byte is found, it is taken as the start of the next token. +If no such byte is found, +then there are no more tokens, and +.BR strtok () +returns NULL. +(A string that is empty or that contains only delimiters +will thus cause +.BR strtok () +to return NULL on the first call.) +.P +The end of each token is found by scanning forward until either +the next delimiter byte is found or until the +terminating null byte (\[aq]\e0\[aq]) is encountered. +If a delimiter byte is found, it is overwritten with +a null byte to terminate the current token, and +.BR strtok () +saves a pointer to the following byte; +that pointer will be used as the starting point +when searching for the next token. +In this case, +.BR strtok () +returns a pointer to the start of the found token. +.P +From the above description, +it follows that a sequence of two or more contiguous delimiter bytes in +the parsed string is considered to be a single delimiter, and that +delimiter bytes at the start or end of the string are ignored. +Put another way: the tokens returned by +.BR strtok () +are always nonempty strings. +Thus, for example, given the string "\fIaaa;;bbb,\fP", +successive calls to +.BR strtok () +that specify the delimiter string "\fI;,\fP" +would return the strings "\fIaaa\fP" and "\fIbbb\fP", +and then a null pointer. +.P +The +.BR strtok_r () +function is a reentrant version of +.BR strtok (). +The +.I saveptr +argument is a pointer to a +.I char\~* +variable that is used internally by +.BR strtok_r () +in order to maintain context between successive calls that parse the +same string. +.P +On the first call to +.BR strtok_r (), +.I str +should point to the string to be parsed, and the value of +.I *saveptr +is ignored (but see NOTES). +In subsequent calls, +.I str +should be NULL, and +.I saveptr +(and the buffer that it points to) +should be unchanged since the previous call. +.P +Different strings may be parsed concurrently using sequences of calls to +.BR strtok_r () +that specify different +.I saveptr +arguments. +.SH RETURN VALUE +The +.BR strtok () +and +.BR strtok_r () +functions return a pointer to +the next token, or NULL if there are no more tokens. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtok () +T} Thread safety MT-Unsafe race:strtok +T{ +.na +.nh +.BR strtok_r () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +On some implementations, +.\" Tru64, according to its manual page +.I *saveptr +is required to be NULL on the first call to +.BR strtok_r () +that is being used to parse +.IR str . +.SH STANDARDS +.TP +.BR strtok () +C11, POSIX.1-2008. +.TP +.BR strtok_r () +POSIX.1-2008. +.SH HISTORY +.TP +.BR strtok () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR strtok_r () +POSIX.1-2001. +.SH BUGS +Be cautious when using these functions. +If you do use them, note that: +.IP \[bu] 3 +These functions modify their first argument. +.IP \[bu] +These functions cannot be used on constant strings. +.IP \[bu] +The identity of the delimiting byte is lost. +.IP \[bu] +The +.BR strtok () +function uses a static buffer while parsing, so it's not thread safe. +Use +.BR strtok_r () +if this matters to you. +.SH EXAMPLES +The program below uses nested loops that employ +.BR strtok_r () +to break a string into a two-level hierarchy of tokens. +The first command-line argument specifies the string to be parsed. +The second argument specifies the delimiter byte(s) +to be used to separate that string into "major" tokens. +The third argument specifies the delimiter byte(s) +to be used to separate the "major" tokens into subtokens. +.P +An example of the output produced by this program is the following: +.P +.in +4n +.EX +.RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]" +1: a/bbb///cc + \-\-> a + \-\-> bbb + \-\-> cc +2: xxx + \-\-> xxx +3: yyy + \-\-> yyy +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strtok.c) +.EX +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + char *str1, *str2, *token, *subtoken; + char *saveptr1, *saveptr2; + int j; +\& + if (argc != 4) { + fprintf(stderr, "Usage: %s string delim subdelim\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) { + token = strtok_r(str1, argv[2], &saveptr1); + if (token == NULL) + break; + printf("%d: %s\en", j, token); +\& + for (str2 = token; ; str2 = NULL) { + subtoken = strtok_r(str2, argv[3], &saveptr2); + if (subtoken == NULL) + break; + printf("\et \-\-> %s\en", subtoken); + } + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.P +Another example program using +.BR strtok () +can be found in +.BR getaddrinfo_a (3). +.SH SEE ALSO +.BR memchr (3), +.BR strchr (3), +.BR string (3), +.BR strpbrk (3), +.BR strsep (3), +.BR strspn (3), +.BR strstr (3), +.BR wcstok (3) diff --git a/man/man3/strtok_r.3 b/man/man3/strtok_r.3 new file mode 100644 index 0000000..19095a0 --- /dev/null +++ b/man/man3/strtok_r.3 @@ -0,0 +1 @@ +.so man3/strtok.3 diff --git a/man/man3/strtol.3 b/man/man3/strtol.3 new file mode 100644 index 0000000..c001265 --- /dev/null +++ b/man/man3/strtol.3 @@ -0,0 +1,321 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:53:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Added correction due to nsd@bbc.com (Nick Duffek) - aeb, 950610 +.TH strtol 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtol, strtoll, strtoq \- convert a string to a long integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long strtol(const char *restrict " nptr , +.BI " char **restrict " endptr ", int " base ); +.BI "long long strtoll(const char *restrict " nptr , +.BI " char **restrict " endptr ", int " base ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strtoll (): +.nf + _ISOC99_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR strtol () +function converts the initial part of the string +in +.I nptr +to a long integer value according to the given +.IR base , +which must be between 2 and 36 inclusive, or be the special value 0. +.P +The string may begin with an arbitrary amount of white space (as +determined by +.BR isspace (3)) +followed by a single optional \[aq]+\[aq] or \[aq]\-\[aq] sign. +If +.I base +is zero or 16, the string may then include a +"0x" or "0X" prefix, and the number will be read in base 16; otherwise, a +zero +.I base +is taken as 10 (decimal) unless the next character +is \[aq]0\[aq], in which case it is taken as 8 (octal). +.P +The remainder of the string is converted to a +.I long +value +in the obvious manner, stopping at the first character which is not a +valid digit in the given base. +(In bases above 10, the letter \[aq]A\[aq] in +either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so +forth, with \[aq]Z\[aq] representing 35.) +.P +If +.I endptr +is not NULL, +and the +.I base +is supported, +.BR strtol () +stores the address of the +first invalid character in +.IR *endptr . +If there were no digits at +all, +.BR strtol () +stores the original value of +.I nptr +in +.I *endptr +(and returns 0). +In particular, if +.I *nptr +is not \[aq]\e0\[aq] but +.I **endptr +is \[aq]\e0\[aq] on return, the entire string is valid. +.P +The +.BR strtoll () +function works just like the +.BR strtol () +function but returns a +.I long long +integer value. +.SH RETURN VALUE +The +.BR strtol () +function returns the result of the conversion, +unless the value would underflow or overflow. +If an underflow occurs, +.BR strtol () +returns +.BR LONG_MIN . +If an overflow occurs, +.BR strtol () +returns +.BR LONG_MAX . +In both cases, +.I errno +is set to +.BR ERANGE . +Precisely the same holds for +.BR strtoll () +(with +.B LLONG_MIN +and +.B LLONG_MAX +instead of +.B LONG_MIN +and +.BR LONG_MAX ). +.SH ERRORS +This function does not modify +.I errno +on success. +.TP +.B EINVAL +(not in C99) +The given +.I base +contains an unsupported value. +.TP +.B ERANGE +The resulting value was out of range. +.P +The implementation may also set +.I errno +to +.B EINVAL +in case +no conversion was performed (no digits seen, and 0 returned). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtol (), +.BR strtoll (), +.BR strtoq () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR strtol () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR strtoll () +POSIX.1-2001, C99. +.SH NOTES +Since +.BR strtol () +can legitimately return 0, +.BR LONG_MAX , +or +.B LONG_MIN +.RB ( LLONG_MAX +or +.B LLONG_MIN +for +.BR strtoll ()) +on both success and failure, the calling program should set +.I errno +to 0 before the call, +and then determine if an error occurred by checking whether +.I errno == ERANGE +after the call. +.P +According to POSIX.1, +in locales other than "C" and "POSIX", +these functions may accept other, +implementation-defined numeric strings. +.P +BSD also has +.P +.in +4n +.EX +.BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base ); +.EE +.in +.P +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.BR strtoll () +or to +.BR strtol (). +.SH CAVEATS +If the +.I base +needs to be tested, +it should be tested in a call where the string is known to succeed. +Otherwise, it's impossible to portably differentiate the errors. +.P +.in +4n +.EX +errno = 0; +strtol("0", NULL, base); +if (errno == EINVAL) + goto unsupported_base; +.EE +.in +.SH EXAMPLES +The program shown below demonstrates the use of +.BR strtol (). +The first command-line argument specifies a string from which +.BR strtol () +should parse a number. +The second (optional) argument specifies the base to be used for +the conversion. +(This argument is converted to numeric form using +.BR atoi (3), +a function that performs no error checking and +has a simpler interface than +.BR strtol ().) +Some examples of the results produced by this program are the following: +.P +.in +4n +.EX +.RB "$" " ./a.out 123" +strtol() returned 123 +.RB "$" " ./a.out \[aq] 123\[aq]" +strtol() returned 123 +.RB "$" " ./a.out 123abc" +strtol() returned 123 +Further characters after number: "abc" +.RB "$" " ./a.out 123abc 55" +strtol: Invalid argument +.RB "$" " ./a.out \[aq]\[aq]" +No digits were found +.RB "$" " ./a.out 4000000000" +strtol: Numerical result out of range +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strtol.c) +.EX +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int base; + char *endptr, *str; + long val; +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s str [base]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + str = argv[1]; + base = (argc > 2) ? atoi(argv[2]) : 0; +\& + errno = 0; /* To distinguish success/failure after call */ + strtol("0", NULL, base); + if (errno == EINVAL) { + perror("strtol"); + exit(EXIT_FAILURE); + } +\& + errno = 0; /* To distinguish success/failure after call */ + val = strtol(str, &endptr, base); +\& + /* Check for various possible errors. */ +\& + if (errno == ERANGE) { + perror("strtol"); + exit(EXIT_FAILURE); + } +\& + if (endptr == str) { + fprintf(stderr, "No digits were found\en"); + exit(EXIT_FAILURE); + } +\& + /* If we got here, strtol() successfully parsed a number. */ +\& + printf("strtol() returned %ld\en", val); +\& + if (*endptr != \[aq]\e0\[aq]) /* Not necessarily an error... */ + printf("Further characters after number: \e"%s\e"\en", endptr); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtoimax (3), +.BR strtoul (3) diff --git a/man/man3/strtold.3 b/man/man3/strtold.3 new file mode 100644 index 0000000..ac3e4a5 --- /dev/null +++ b/man/man3/strtold.3 @@ -0,0 +1 @@ +.so man3/strtod.3 diff --git a/man/man3/strtoll.3 b/man/man3/strtoll.3 new file mode 100644 index 0000000..d090393 --- /dev/null +++ b/man/man3/strtoll.3 @@ -0,0 +1 @@ +.so man3/strtol.3 diff --git a/man/man3/strtoq.3 b/man/man3/strtoq.3 new file mode 100644 index 0000000..d090393 --- /dev/null +++ b/man/man3/strtoq.3 @@ -0,0 +1 @@ +.so man3/strtol.3 diff --git a/man/man3/strtoul.3 b/man/man3/strtoul.3 new file mode 100644 index 0000000..dd9d2c1 --- /dev/null +++ b/man/man3/strtoul.3 @@ -0,0 +1,224 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:54:03 1993 by Rik Faith (faith@cs.unc.edu) +.\" Fixed typo, aeb, 950823 +.\" 2002-02-22, joey, mihtjel: Added strtoull() +.\" +.TH strtoul 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtoul, strtoull, strtouq \- convert a string to an unsigned long integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "unsigned long strtoul(const char *restrict " nptr , +.BI " char **restrict " endptr ", int " base ); +.BI "unsigned long long strtoull(const char *restrict " nptr , +.BI " char **restrict " endptr ", int " base ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR strtoull (): +.nf + _ISOC99_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR strtoul () +function converts the initial part of the string +in +.I nptr +to an +.I "unsigned long" +value according to the +given +.IR base , +which must be between 2 and 36 inclusive, or be +the special value 0. +.P +The string may begin with an arbitrary amount of white space (as +determined by +.BR isspace (3)) +followed by a single optional \[aq]+\[aq] or \[aq]\-\[aq] +sign. +If +.I base +is zero or 16, the string may then include a +"0x" prefix, and the number will be read in base 16; otherwise, a +zero +.I base +is taken as 10 (decimal) unless the next character +is \[aq]0\[aq], in which case it is taken as 8 (octal). +.P +The remainder of the string is converted to an +.I "unsigned long" +value in the obvious manner, +stopping at the first character which is not a +valid digit in the given base. +(In bases above 10, the letter \[aq]A\[aq] in +either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so +forth, with \[aq]Z\[aq] representing 35.) +.P +If +.I endptr +is not NULL, +and the +.I base +is supported, +.BR strtoul () +stores the address of the +first invalid character in +.IR *endptr . +If there were no digits at +all, +.BR strtoul () +stores the original value of +.I nptr +in +.I *endptr +(and returns 0). +In particular, if +.I *nptr +is not \[aq]\e0\[aq] but +.I **endptr +is \[aq]\e0\[aq] on return, the entire string is valid. +.P +The +.BR strtoull () +function works just like the +.BR strtoul () +function but returns an +.I "unsigned long long" +value. +.SH RETURN VALUE +The +.BR strtoul () +function returns either the result of the conversion +or, if there was a leading minus sign, the negation of the result of the +conversion represented as an unsigned value, +unless the original (nonnegated) value would overflow; in +the latter case, +.BR strtoul () +returns +.B ULONG_MAX +and sets +.I errno +to +.BR ERANGE . +Precisely the same holds for +.BR strtoull () +(with +.B ULLONG_MAX +instead of +.BR ULONG_MAX ). +.SH ERRORS +This function does not modify +.I errno +on success. +.TP +.B EINVAL +(not in C99) +The given +.I base +contains an unsupported value. +.TP +.B ERANGE +The resulting value was out of range. +.P +The implementation may also set +.I errno +to +.B EINVAL +in case +no conversion was performed (no digits seen, and 0 returned). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtoul (), +.BR strtoull (), +.BR strtouq () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR strtoul () +POSIX.1-2001, C89, SVr4. +.TP +.BR strtoull () +POSIX.1-2001, C99. +.SH NOTES +Since +.BR strtoul () +can legitimately return 0 or +.B ULONG_MAX +.RB ( ULLONG_MAX +for +.BR strtoull ()) +on both success and failure, the calling program should set +.I errno +to 0 before the call, +and then determine if an error occurred by checking whether +.I errno +has a nonzero value after the call. +.P +In locales other than the "C" locale, other strings may be accepted. +(For example, the thousands separator of the current locale may be +supported.) +.P +BSD also has +.P +.in +4n +.EX +.BI "u_quad_t strtouq(const char *" nptr ", char **" endptr ", int " base ); +.EE +.in +.P +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.BR strtoull () +or to +.BR strtoul (). +.P +Negative values are considered valid input and are +silently converted to the equivalent +.I "unsigned long" +value. +.SH EXAMPLES +See the example on the +.BR strtol (3) +manual page; +the use of the functions described in this manual page is similar. +.SH SEE ALSO +.BR a64l (3), +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoumax (3) diff --git a/man/man3/strtoull.3 b/man/man3/strtoull.3 new file mode 100644 index 0000000..3340a83 --- /dev/null +++ b/man/man3/strtoull.3 @@ -0,0 +1 @@ +.so man3/strtoul.3 diff --git a/man/man3/strtoumax.3 b/man/man3/strtoumax.3 new file mode 100644 index 0000000..753be84 --- /dev/null +++ b/man/man3/strtoumax.3 @@ -0,0 +1 @@ +.so man3/strtoimax.3 diff --git a/man/man3/strtouq.3 b/man/man3/strtouq.3 new file mode 100644 index 0000000..3340a83 --- /dev/null +++ b/man/man3/strtouq.3 @@ -0,0 +1 @@ +.so man3/strtoul.3 diff --git a/man/man3/strverscmp.3 b/man/man3/strverscmp.3 new file mode 100644 index 0000000..9e3cc39 --- /dev/null +++ b/man/man3/strverscmp.3 @@ -0,0 +1,146 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH strverscmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strverscmp \- compare two version strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int strverscmp(const char *" s1 ", const char *" s2 ); +.fi +.SH DESCRIPTION +Often one has files +.IR jan1 ", " jan2 ", ..., " jan9 ", " jan10 ", ..." +and it feels wrong when +.BR ls (1) +orders them +.IR jan1 ", " jan10 ", ..., " jan2 ", ..., " jan9 . +.\" classical solution: "rename jan jan0 jan?" +In order to rectify this, GNU introduced the +.I \-v +option to +.BR ls (1), +which is implemented using +.BR versionsort (3), +which again uses +.BR strverscmp (). +.P +Thus, the task of +.BR strverscmp () +is to compare two strings and find the "right" order, while +.BR strcmp (3) +finds only the lexicographic order. +This function does not use +the locale category +.BR LC_COLLATE , +so is meant mostly for situations +where the strings are expected to be in ASCII. +.P +What this function does is the following. +If both strings are equal, return 0. +Otherwise, find the position +between two bytes with the property that before it both strings are equal, +while directly after it there is a difference. +Find the largest consecutive digit strings containing (or starting at, +or ending at) this position. +If one or both of these is empty, +then return what +.BR strcmp (3) +would have returned (numerical ordering of byte values). +Otherwise, compare both digit strings numerically, where digit strings with +one or more leading zeros are interpreted as if they have a decimal point +in front (so that in particular digit strings with more leading zeros +come before digit strings with fewer leading zeros). +Thus, the ordering is +.IR 000 ", " 00 ", " 01 ", " 010 ", " 09 ", " 0 ", " 1 ", " 9 ", " 10 . +.SH RETURN VALUE +The +.BR strverscmp () +function returns an integer +less than, equal to, or greater than zero if +.I s1 +is found, respectively, to be earlier than, equal to, +or later than +.IR s2 . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strverscmp () +T} Thread safety MT-Safe +.TE +.\" FIXME: The marking is different from that in the glibc manual, +.\" which has: +.\" +.\" strverscmp: MT-Safe locale +.\" +.\" glibc manual says strverscmp should have marking locale because it calls +.\" isdigit() multiple times and isdigit() uses locale variable. +.\" But isdigit() has two implementations. With different compiling conditions, +.\" we may call isdigit() in macro, then strverscmp() should not have locale +.\" problem. +.SH STANDARDS +GNU. +.SH EXAMPLES +The program below can be used to demonstrate the behavior of +.BR strverscmp (). +It uses +.BR strverscmp () +to compare the two strings given as its command-line arguments. +An example of its use is the following: +.P +.in +4n +.EX +$ \fB./a.out jan1 jan10\fP +jan1 < jan10 +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (strverscmp.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ + int res; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + res = strverscmp(argv[1], argv[2]); +\& + printf("%s %s %s\en", argv[1], + (res < 0) ? "<" : (res == 0) ? "==" : ">", argv[2]); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR rename (1), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3) diff --git a/man/man3/strxfrm.3 b/man/man3/strxfrm.3 new file mode 100644 index 0000000..8fb9097 --- /dev/null +++ b/man/man3/strxfrm.3 @@ -0,0 +1,86 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:41:28 1993 by Rik Faith (faith@cs.unc.edu) +.TH strxfrm 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strxfrm \- string transformation +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t strxfrm(char " dest "[restrict ." n "], \ +const char " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR strxfrm () +function transforms the +.I src +string into a +form such that the result of +.BR strcmp (3) +on two strings that have +been transformed with +.BR strxfrm () +is the same as the result of +.BR strcoll (3) +on the two strings before their transformation. +The first +.I n +bytes of the transformed string are placed in +.IR dest . +The transformation is based on the program's current +locale for category +.BR LC_COLLATE . +(See +.BR setlocale (3)). +.SH RETURN VALUE +The +.BR strxfrm () +function returns the number of bytes required to +store the transformed string in +.I dest +excluding the +terminating null byte (\[aq]\e0\[aq]). +If the value returned is +.I n +or more, the +contents of +.I dest +are indeterminate. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strxfrm () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH SEE ALSO +.BR memcmp (3), +.BR setlocale (3), +.BR strcasecmp (3), +.BR strcmp (3), +.BR strcoll (3), +.BR string (3) diff --git a/man/man3/svc_destroy.3 b/man/man3/svc_destroy.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_destroy.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_freeargs.3 b/man/man3/svc_freeargs.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_freeargs.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_getargs.3 b/man/man3/svc_getargs.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_getargs.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_getcaller.3 b/man/man3/svc_getcaller.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_getcaller.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_getreq.3 b/man/man3/svc_getreq.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_getreq.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_getreqset.3 b/man/man3/svc_getreqset.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_getreqset.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_register.3 b/man/man3/svc_register.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_register.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_run.3 b/man/man3/svc_run.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_run.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_sendreply.3 b/man/man3/svc_sendreply.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_sendreply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svc_unregister.3 b/man/man3/svc_unregister.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svc_unregister.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_auth.3 b/man/man3/svcerr_auth.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_auth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_decode.3 b/man/man3/svcerr_decode.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_decode.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_noproc.3 b/man/man3/svcerr_noproc.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_noproc.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_noprog.3 b/man/man3/svcerr_noprog.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_noprog.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_progvers.3 b/man/man3/svcerr_progvers.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_progvers.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_systemerr.3 b/man/man3/svcerr_systemerr.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_systemerr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcerr_weakauth.3 b/man/man3/svcerr_weakauth.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcerr_weakauth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcfd_create.3 b/man/man3/svcfd_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcfd_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcraw_create.3 b/man/man3/svcraw_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcraw_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svctcp_create.3 b/man/man3/svctcp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svctcp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcudp_bufcreate.3 b/man/man3/svcudp_bufcreate.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcudp_bufcreate.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/svcudp_create.3 b/man/man3/svcudp_create.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/svcudp_create.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/swab.3 b/man/man3/swab.3 new file mode 100644 index 0000000..b263846 --- /dev/null +++ b/man/man3/swab.3 @@ -0,0 +1,76 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:52:15 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-12-15, aeb +.TH swab 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +swab \- swap adjacent bytes +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "void swab(const void " from "[restrict ." n "], void " to "[restrict ." n ], +.BI " ssize_t " n ); +.fi +.SH DESCRIPTION +The +.BR swab () +function copies +.I n +bytes from the array pointed +to by +.I from +to the array pointed to by +.IR to , +exchanging +adjacent even and odd bytes. +This function is used to exchange data +between machines that have different low/high byte ordering. +.P +This function does nothing when +.I n +is negative. +When +.I n +is positive and odd, it handles +.I n\-1 +bytes +as above, and does something unspecified with the last byte. +(In other words, +.I n +should be even.) +.SH RETURN VALUE +The +.BR swab () +function returns no value. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR swab () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR bstring (3) diff --git a/man/man3/swapcontext.3 b/man/man3/swapcontext.3 new file mode 100644 index 0000000..cdccd64 --- /dev/null +++ b/man/man3/swapcontext.3 @@ -0,0 +1 @@ +.so man3/makecontext.3 diff --git a/man/man3/swprintf.3 b/man/man3/swprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man/man3/swprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man/man3/sys_errlist.3 b/man/man3/sys_errlist.3 new file mode 100644 index 0000000..837f1a1 --- /dev/null +++ b/man/man3/sys_errlist.3 @@ -0,0 +1 @@ +.so man3/perror.3 diff --git a/man/man3/sys_nerr.3 b/man/man3/sys_nerr.3 new file mode 100644 index 0000000..837f1a1 --- /dev/null +++ b/man/man3/sys_nerr.3 @@ -0,0 +1 @@ +.so man3/perror.3 diff --git a/man/man3/sys_siglist.3 b/man/man3/sys_siglist.3 new file mode 100644 index 0000000..f64f756 --- /dev/null +++ b/man/man3/sys_siglist.3 @@ -0,0 +1 @@ +.so man3/strsignal.3 diff --git a/man/man3/sysconf.3 b/man/man3/sysconf.3 new file mode 100644 index 0000000..2c269fd --- /dev/null +++ b/man/man3/sysconf.3 @@ -0,0 +1,390 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 17:51:42 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Tue Aug 17 11:42:20 1999 by Ariel Scolnicov (ariels@compugen.co.il) +.TH sysconf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sysconf \- get configuration information at run time +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long sysconf(int " "name" ); +.fi +.SH DESCRIPTION +POSIX allows an application to test at compile or run time +whether certain options are supported, or what the value is +of certain configurable constants or limits. +.P +At compile time this is done by including +.I +and/or +.I +and testing the value of certain macros. +.P +At run time, one can ask for numerical values using the present function +.BR sysconf (). +One can ask for numerical values that may depend +on the filesystem in which a file resides using +.BR fpathconf (3) +and +.BR pathconf (3). +One can ask for string values using +.BR confstr (3). +.P +The values obtained from these functions are system configuration constants. +They do not change during the lifetime of a process. +.\" except that sysconf(_SC_OPEN_MAX) may change answer after a call +.\" to setrlimit( ) which changes the RLIMIT_NOFILE soft limit +.P +For options, typically, there is a constant +.B _POSIX_FOO +that may be defined in +.IR . +If it is undefined, one should ask at run time. +If it is defined to \-1, then the option is not supported. +If it is defined to 0, then relevant functions and headers exist, +but one has to ask at run time what degree of support is available. +If it is defined to a value other than \-1 or 0, then the option is +supported. +Usually the value (such as 200112L) indicates the year and month +of the POSIX revision describing the option. +glibc uses the value 1 +to indicate support as long as the POSIX revision has not been published yet. +.\" and 999 to indicate support for options no longer present in the latest +.\" standard. (?) +The +.BR sysconf () +argument will be +.BR _SC_FOO . +For a list of options, see +.BR posixoptions (7). +.P +For variables or limits, typically, there is a constant +.BR _FOO , +maybe defined in +.IR , +or +.BR _POSIX_FOO , +maybe defined in +.IR . +The constant will not be defined if the limit is unspecified. +If the constant is defined, it gives a guaranteed value, and +a greater value might actually be supported. +If an application wants to take advantage of values which may change +between systems, a call to +.BR sysconf () +can be made. +The +.BR sysconf () +argument will be +.BR _SC_FOO . +.SS POSIX.1 variables +We give the name of the variable, the name of the +.BR sysconf () +argument used to inquire about its value, +and a short description. +.P +First, the POSIX.1 compatible values. +.\" [for the moment: only the things that are unconditionally present] +.\" .TP +.\" .BR AIO_LISTIO_MAX " - " _SC_AIO_LISTIO_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" Maximum number of I/O operations in a single list I/O call. +.\" Must not be less than _POSIX_AIO_LISTIO_MAX. +.\" .TP +.\" .BR AIO_MAX " - " _SC_AIO_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" Maximum number of outstanding asynchronous I/O operations. +.\" Must not be less than _POSIX_AIO_MAX. +.\" .TP +.\" .BR AIO_PRIO_DELTA_MAX " - " _SC_AIO_PRIO_DELTA_MAX +.\" (if _POSIX_ASYNCHRONOUS_IO) +.\" The maximum amount by which a process can decrease its +.\" asynchronous I/O priority level from its own scheduling priority. +.\" Must be nonnegative. +.TP +.BR ARG_MAX " - " _SC_ARG_MAX +The maximum length of the arguments to the +.BR exec (3) +family of functions. +Must not be less than +.B _POSIX_ARG_MAX +(4096). +.TP +.BR CHILD_MAX " - " _SC_CHILD_MAX +The maximum number of simultaneous processes per user ID. +Must not be less than +.B _POSIX_CHILD_MAX +(25). +.TP +.BR HOST_NAME_MAX " - " _SC_HOST_NAME_MAX +Maximum length of a hostname, not including the terminating null byte, +as returned by +.BR gethostname (2). +Must not be less than +.B _POSIX_HOST_NAME_MAX +(255). +.TP +.BR LOGIN_NAME_MAX " - " _SC_LOGIN_NAME_MAX +Maximum length of a login name, including the terminating null byte. +Must not be less than +.B _POSIX_LOGIN_NAME_MAX +(9). +.TP +.BR NGROUPS_MAX " - " _SC_NGROUPS_MAX +Maximum number of supplementary group IDs. +.TP +.BR "" "clock ticks - " _SC_CLK_TCK +The number of clock ticks per second. +The corresponding variable is obsolete. +It was of course called +.BR CLK_TCK . +(Note: the macro +.B CLOCKS_PER_SEC +does not give information: it must equal 1000000.) +.TP +.BR OPEN_MAX " - " _SC_OPEN_MAX +The maximum number of files that a process can have open at any time. +Must not be less than +.B _POSIX_OPEN_MAX +(20). +.TP +.BR PAGESIZE " - " _SC_PAGESIZE +Size of a page in bytes. +Must not be less than 1. +.TP +.BR PAGE_SIZE " - " _SC_PAGE_SIZE +A synonym for +.BR PAGESIZE / _SC_PAGESIZE . +(Both +.B PAGESIZE +and +.B PAGE_SIZE +are specified in POSIX.) +.TP +.BR RE_DUP_MAX " - " _SC_RE_DUP_MAX +The number of repeated occurrences of a BRE permitted by +.BR regexec (3) +and +.BR regcomp (3). +Must not be less than +.B _POSIX2_RE_DUP_MAX +(255). +.TP +.BR STREAM_MAX " - " _SC_STREAM_MAX +The maximum number of streams that a process can have open at any +time. +If defined, it has the same value as the standard C macro +.BR FOPEN_MAX . +Must not be less than +.B _POSIX_STREAM_MAX +(8). +.TP +.BR SYMLOOP_MAX " - " _SC_SYMLOOP_MAX +The maximum number of symbolic links seen in a pathname before resolution +returns +.BR ELOOP . +Must not be less than +.B _POSIX_SYMLOOP_MAX +(8). +.TP +.BR TTY_NAME_MAX " - " _SC_TTY_NAME_MAX +The maximum length of terminal device name, +including the terminating null byte. +Must not be less than +.B _POSIX_TTY_NAME_MAX +(9). +.TP +.BR TZNAME_MAX " - " _SC_TZNAME_MAX +The maximum number of bytes in a timezone name. +Must not be less than +.B _POSIX_TZNAME_MAX +(6). +.TP +.BR _POSIX_VERSION " - " _SC_VERSION +indicates the year and month the POSIX.1 standard was approved in the +format +.BR YYYYMML ; +the value +.B 199009L +indicates the Sept. 1990 revision. +.SS POSIX.2 variables +Next, the POSIX.2 values, giving limits for utilities. +.TP +.BR BC_BASE_MAX " - " _SC_BC_BASE_MAX +indicates the maximum +.I obase +value accepted by the +.BR bc (1) +utility. +.TP +.BR BC_DIM_MAX " - " _SC_BC_DIM_MAX +indicates the maximum value of elements permitted in an array by +.BR bc (1). +.TP +.BR BC_SCALE_MAX " - " _SC_BC_SCALE_MAX +indicates the maximum +.I scale +value allowed by +.BR bc (1). +.TP +.BR BC_STRING_MAX " - " _SC_BC_STRING_MAX +indicates the maximum length of a string accepted by +.BR bc (1). +.TP +.BR COLL_WEIGHTS_MAX " - " _SC_COLL_WEIGHTS_MAX +indicates the maximum numbers of weights that can be assigned to an +entry of the +.B LC_COLLATE order +keyword in the locale definition file. +.TP +.BR EXPR_NEST_MAX " - " _SC_EXPR_NEST_MAX +is the maximum number of expressions which can be nested within +parentheses by +.BR expr (1). +.TP +.BR LINE_MAX " - " _SC_LINE_MAX +The maximum length of a utility's input line, either from +standard input or from a file. +This includes space for a trailing +newline. +.TP +.BR RE_DUP_MAX " - " _SC_RE_DUP_MAX +The maximum number of repeated occurrences of a regular expression when +the interval notation +.B \e{m,n\e} +is used. +.TP +.BR POSIX2_VERSION " - " _SC_2_VERSION +indicates the version of the POSIX.2 standard in the format of +YYYYMML. +.TP +.BR POSIX2_C_DEV " - " _SC_2_C_DEV +indicates whether the POSIX.2 C language development facilities are +supported. +.TP +.BR POSIX2_FORT_DEV " - " _SC_2_FORT_DEV +indicates whether the POSIX.2 FORTRAN development utilities are +supported. +.TP +.BR POSIX2_FORT_RUN " - " _SC_2_FORT_RUN +indicates whether the POSIX.2 FORTRAN run-time utilities are supported. +.TP +.BR _POSIX2_LOCALEDEF " - " _SC_2_LOCALEDEF +indicates whether the POSIX.2 creation of locales via +.BR localedef (1) +is supported. +.TP +.BR POSIX2_SW_DEV " - " _SC_2_SW_DEV +indicates whether the POSIX.2 software development utilities option is +supported. +.P +These values also exist, but may not be standard. +.TP +.BR "" " - " _SC_PHYS_PAGES +The number of pages of physical memory. +Note that it is possible +for the product of this value and the value of +.B _SC_PAGESIZE +to overflow. +.TP +.BR "" " - " _SC_AVPHYS_PAGES +The number of currently available pages of physical memory. +.TP +.BR "" " - " _SC_NPROCESSORS_CONF +The number of processors configured. +See also +.BR get_nprocs_conf (3). +.TP +.BR "" " - " _SC_NPROCESSORS_ONLN +The number of processors currently online (available). +See also +.BR get_nprocs_conf (3). +.SH RETURN VALUE +The return value of +.BR sysconf () +is one of the following: +.IP \[bu] 3 +On error, \-1 is returned and +.I errno +is set to indicate the error +(for example, +.BR EINVAL , +indicating that +.I name +is invalid). +.IP \[bu] +If +.I name +corresponds to a maximum or minimum limit, and that limit is indeterminate, +\-1 is returned and +.I errno +is not changed. +(To distinguish an indeterminate limit from an error, set +.I errno +to zero before the call, and then check whether +.I errno +is nonzero when \-1 is returned.) +.IP \[bu] +If +.I name +corresponds to an option, +a positive value is returned if the option is supported, +and \-1 is returned if the option is not supported. +.IP \[bu] +Otherwise, +the current value of the option or limit is returned. +This value will not be more restrictive than +the corresponding value that was described to the application in +.I +or +.I +when the application was compiled. +.SH ERRORS +.TP +.B EINVAL +.I name +is invalid. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sysconf () +T} Thread safety MT-Safe env +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +It is difficult to use +.B ARG_MAX +because it is not specified how much of the argument space for +.BR exec (3) +is consumed by the user's environment variables. +.P +Some returned values may be huge; they are not suitable for allocating +memory. +.SH SEE ALSO +.BR bc (1), +.BR expr (1), +.BR getconf (1), +.BR locale (1), +.BR confstr (3), +.BR fpathconf (3), +.BR pathconf (3), +.BR posixoptions (7) diff --git a/man/man3/syslog.3 b/man/man3/syslog.3 new file mode 100644 index 0000000..e6b885b --- /dev/null +++ b/man/man3/syslog.3 @@ -0,0 +1,359 @@ +'\" t +.\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com) +.\" and Copyright 2001, 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Updated 1999.12.19 by Karl M. Hegbloom +.\" +.\" Updated 13 Oct 2001, Michael Kerrisk +.\" Added description of vsyslog +.\" Added descriptions of LOG_ODELAY and LOG_NOWAIT +.\" Added brief description of facility and option arguments +.\" Added CONFORMING TO section +.\" 2001-10-13, aeb, minor changes +.\" Modified 13 Dec 2001, Martin Schulze +.\" Modified 3 Jan 2002, Michael Kerrisk +.\" +.TH syslog 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +closelog, openlog, syslog, vsyslog \- send messages to the system logger +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void openlog(const char *" ident ", int " option ", int " facility ); +.BI "void syslog(int " priority ", const char *" format ", ...);" +.B "void closelog(void);" +.P +.BI "void vsyslog(int " priority ", const char *" format ", va_list " ap ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR vsyslog (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +.SS openlog() +.BR openlog () +opens a connection to the system logger for a program. +.P +The string pointed to by +.I ident +is prepended to every message, and is typically set to the program name. +If +.I ident +is NULL, the program name is used. +(POSIX.1-2008 does not specify the behavior when +.I ident +is NULL.) +.P +The +.I option +argument specifies flags which control the operation of +.BR openlog () +and subsequent calls to +.BR syslog (). +The +.I facility +argument establishes a default to be used if +none is specified in subsequent calls to +.BR syslog (). +The values that may be specified for +.I option +and +.I facility +are described below. +.P +The use of +.BR openlog () +is optional; it will automatically be called by +.BR syslog () +if necessary, in which case +.I ident +will default to NULL. +.\" +.SS syslog() and vsyslog() +.BR syslog () +generates a log message, which will be distributed by +.BR syslogd (8). +.P +The +.I priority +argument is formed by ORing together a +.I facility +value and a +.I level +value (described below). +If no +.I facility +value is ORed into +.IR priority , +then the default value set by +.BR openlog () +is used, or, if there was no preceding +.BR openlog () +call, a default of +.B LOG_USER +is employed. +.P +The remaining arguments are a +.IR format , +as in +.BR printf (3), +and any arguments required by the +.IR format , +except that the two-character sequence +.B %m +will be replaced by +the error message string +.IR strerror ( errno ). +The format string need not include a terminating newline character. +.P +The function +.BR vsyslog () +performs the same task as +.BR syslog () +with the difference that it takes a set of arguments which have +been obtained using the +.BR stdarg (3) +variable argument list macros. +.\" +.SS closelog() +.BR closelog () +closes the file descriptor being used to write to the system logger. +The use of +.BR closelog () +is optional. +.\" +.SS Values for \fIoption\fP +The +.I option +argument to +.BR openlog () +is a bit mask constructed by ORing together any of the following values: +.TP 15 +.B LOG_CONS +Write directly to the system console if there is an error while sending to +the system logger. +.TP +.B LOG_NDELAY +Open the connection immediately (normally, the connection is opened when +the first message is logged). +This may be useful, for example, if a subsequent +.BR chroot (2) +would make the pathname used internally by the logging facility unreachable. +.TP +.B LOG_NOWAIT +Don't wait for child processes that may have been created while logging +the message. +(The GNU C library does not create a child process, so this +option has no effect on Linux.) +.TP +.B LOG_ODELAY +The converse of +.BR LOG_NDELAY ; +opening of the connection is delayed until +.BR syslog () +is called. +(This is the default, and need not be specified.) +.TP +.B LOG_PERROR +(Not in POSIX.1-2001 or POSIX.1-2008.) +Also log the message to +.IR stderr . +.TP +.B LOG_PID +Include the caller's PID with each message. +.\" +.SS Values for \fIfacility\fP +The +.I facility +argument is used to specify what type of program is logging the message. +This lets the configuration file specify that messages from different +facilities will be handled differently. +.TP 15 +.B LOG_AUTH +security/authorization messages +.TP +.B LOG_AUTHPRIV +security/authorization messages (private) +.TP +.B LOG_CRON +clock daemon +.RB ( cron " and " at ) +.TP +.B LOG_DAEMON +system daemons without separate facility value +.TP +.B LOG_FTP +ftp daemon +.TP +.B LOG_KERN +kernel messages (these can't be generated from user processes) +.\" LOG_KERN has the value 0; if used as a facility, zero translates to: +.\" "use the default facility". +.TP +.BR LOG_LOCAL0 " through " LOG_LOCAL7 +reserved for local use +.TP +.B LOG_LPR +line printer subsystem +.TP +.B LOG_MAIL +mail subsystem +.TP +.B LOG_NEWS +USENET news subsystem +.TP +.B LOG_SYSLOG +messages generated internally by +.BR syslogd (8) +.TP +.BR LOG_USER " (default)" +generic user-level messages +.TP +.B LOG_UUCP +UUCP subsystem +.\" +.SS Values for \fIlevel\fP +This determines the importance of the message. +The levels are, in order of decreasing importance: +.TP 15 +.B LOG_EMERG +system is unusable +.TP +.B LOG_ALERT +action must be taken immediately +.TP +.B LOG_CRIT +critical conditions +.TP +.B LOG_ERR +error conditions +.TP +.B LOG_WARNING +warning conditions +.TP +.B LOG_NOTICE +normal, but significant, condition +.TP +.B LOG_INFO +informational message +.TP +.B LOG_DEBUG +debug-level message +.P +The function +.BR setlogmask (3) +can be used to restrict logging to specified levels only. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR openlog (), +.BR closelog () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR syslog (), +.BR vsyslog () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +.TP +.BR syslog () +.TQ +.BR openlog () +.TQ +.BR closelog () +POSIX.1-2008. +.TP +.BR vsyslog () +None. +.SH HISTORY +.TP +.BR syslog () +4.2BSD, SUSv2, POSIX.1-2001. +.TP +.BR openlog () +.TQ +.BR closelog () +4.3BSD, SUSv2, POSIX.1-2001. +.\" .SH HISTORY +.\" 4.3BSD documents +.\" .BR setlogmask (). +.TP +.BR vsyslog () +4.3BSD-Reno. +.\" Of course early v* functions used the +.\" .I +.\" mechanism, which is not compatible with +.\" .IR . +.P +POSIX.1-2001 specifies only the +.B LOG_USER +and +.B LOG_LOCAL* +values for +.IR facility . +However, with the exception of +.B LOG_AUTHPRIV +and +.BR LOG_FTP , +the other +.I facility +values appear on most UNIX systems. +.P +The +.B LOG_PERROR +value for +.I option +is not specified by POSIX.1-2001 or POSIX.1-2008, but is available +in most versions of UNIX. +.SH NOTES +The argument +.I ident +in the call of +.BR openlog () +is probably stored as-is. +Thus, if the string it points to +is changed, +.BR syslog () +may start prepending the changed string, and if the string +it points to ceases to exist, the results are undefined. +Most portable is to use a string constant. +.P +Never pass a string with user-supplied data as a format, +use the following instead: +.P +.in +4n +.EX +syslog(priority, "%s", string); +.EE +.in +.SH SEE ALSO +.BR journalctl (1), +.BR logger (1), +.BR setlogmask (3), +.BR syslog.conf (5), +.BR syslogd (8) diff --git a/man/man3/system.3 b/man/man3/system.3 new file mode 100644 index 0000000..8a00ba8 --- /dev/null +++ b/man/man3/system.3 @@ -0,0 +1,269 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (c) 2014 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 17:51:15 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 11 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 14 May 2001, 23 Sep 2001 by aeb +.\" 2004-12-20, mtk +.\" +.TH system 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +system \- execute a shell command +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int system(const char *" "command" ); +.fi +.SH DESCRIPTION +The +.BR system () +library function behaves as if it used +.BR fork (2) +to create a child process that executed the shell command specified in +.I command +using +.BR execl (3) +as follows: +.P +.in +4n +.EX +execl("/bin/sh", "sh", "\-c", command, (char *) NULL); +.EE +.in +.P +.BR system () +returns after the command has been completed. +.P +During execution of the command, +.B SIGCHLD +will be blocked, and +.B SIGINT +and +.B SIGQUIT +will be ignored, in the process that calls +.BR system (). +(These signals will be handled according to their defaults inside +the child process that executes +.IR command .) +.P +If +.I command +is NULL, then +.BR system () +returns a status indicating whether a shell is available on the system. +.SH RETURN VALUE +The return value of +.BR system () +is one of the following: +.IP \[bu] 3 +If +.I command +is NULL, then a nonzero value if a shell is available, +or 0 if no shell is available. +.IP \[bu] +If a child process could not be created, +or its status could not be retrieved, +the return value is \-1 and +.I errno +is set to indicate the error. +.IP \[bu] +If a shell could not be executed in the child process, +then the return value is as though the child shell terminated by calling +.BR _exit (2) +with the status 127. +.IP \[bu] +If all system calls succeed, +then the return value is the termination status of the child shell +used to execute +.IR command . +(The termination status of a shell is the termination status of +the last command it executes.) +.P +In the last two cases, +the return value is a "wait status" that can be examined using +the macros described in +.BR waitpid (2). +(i.e., +.BR WIFEXITED (), +.BR WEXITSTATUS (), +and so on). +.P +.BR system () +does not affect the wait status of any other children. +.SH ERRORS +.BR system () +can fail with any of the same errors as +.BR fork (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR system () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89. +.SH NOTES +.BR system () +provides simplicity and convenience: +it handles all of the details of calling +.BR fork (2), +.BR execl (3), +and +.BR waitpid (2), +as well as the necessary manipulations of signals; +in addition, +the shell performs the usual substitutions and I/O redirections for +.IR command . +The main cost of +.BR system () +is inefficiency: +additional system calls are required to create the process that +runs the shell and to execute the shell. +.P +If the +.B _XOPEN_SOURCE +feature test macro is defined +(before including +.I any +header files), +then the macros described in +.BR waitpid (2) +.RB ( WEXITSTATUS (), +etc.) are made available when including +.IR . +.P +As mentioned, +.BR system () +ignores +.B SIGINT +and +.BR SIGQUIT . +This may make programs that call it +from a loop uninterruptible, unless they take care themselves +to check the exit status of the child. +For example: +.P +.in +4n +.EX +while (something) { + int ret = system("foo"); +\& + if (WIFSIGNALED(ret) && + (WTERMSIG(ret) == SIGINT || WTERMSIG(ret) == SIGQUIT)) + break; +} +.EE +.in +.P +According to POSIX.1, it is unspecified whether handlers registered using +.BR pthread_atfork (3) +are called during the execution of +.BR system (). +In the glibc implementation, such handlers are not called. +.P +Before glibc 2.1.3, the check for the availability of +.I /bin/sh +was not actually performed if +.I command +was NULL; instead it was always assumed to be available, and +.BR system () +always returned 1 in this case. +Since glibc 2.1.3, this check is performed because, even though +POSIX.1-2001 requires a conforming implementation to provide +a shell, that shell may not be available or executable if +the calling program has previously called +.BR chroot (2) +(which is not specified by POSIX.1-2001). +.P +It is possible for the shell command to terminate with a status of 127, +which yields a +.BR system () +return value that is indistinguishable from the case +where a shell could not be executed in the child process. +.\" +.SS Caveats +Do not use +.BR system () +from a privileged program +(a set-user-ID or set-group-ID program, or a program with capabilities) +because strange values for some environment variables +might be used to subvert system integrity. +For example, +.B PATH +could be manipulated so that an arbitrary program +is executed with privilege. +Use the +.BR exec (3) +family of functions instead, but not +.BR execlp (3) +or +.BR execvp (3) +(which also use the +.B PATH +environment variable to search for an executable). +.P +.BR system () +will not, in fact, work properly from programs with set-user-ID or +set-group-ID privileges on systems on which +.I /bin/sh +is bash version 2: as a security measure, bash 2 drops privileges on startup. +(Debian uses a different shell, +.BR dash (1), +which does not do this when invoked as +.BR sh .) +.P +Any user input that is employed as part of +.I command +should be +.I carefully +sanitized, to ensure that unexpected shell commands or command options +are not executed. +Such risks are especially grave when using +.BR system () +from a privileged program. +.SH BUGS +.\" [BUG 211029](https://bugzilla.kernel.org/show_bug.cgi?id=211029) +.\" [glibc bug](https://sourceware.org/bugzilla/show_bug.cgi?id=27143) +.\" [POSIX bug](https://www.austingroupbugs.net/view.php?id=1440) +If the command name starts with a hyphen, +.BR sh (1) +interprets the command name as an option, +and the behavior is undefined. +(See the +.B \-c +option to +.BR sh (1).) +To work around this problem, +prepend the command with a space as in the following call: +.P +.in +4n +.EX + system(" \-unfortunate\-command\-name"); +.EE +.in +.SH SEE ALSO +.BR sh (1), +.BR execve (2), +.BR fork (2), +.BR sigaction (2), +.BR sigprocmask (2), +.BR wait (2), +.BR exec (3), +.BR signal (7) diff --git a/man/man3/sysv_signal.3 b/man/man3/sysv_signal.3 new file mode 100644 index 0000000..fcdfa6b --- /dev/null +++ b/man/man3/sysv_signal.3 @@ -0,0 +1,90 @@ +'\" t +.\" Copyright (c) 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sysv_signal 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sysv_signal \- signal handling with System V semantics +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.B typedef void (*sighandler_t)(int); +.P +.BI "sighandler_t sysv_signal(int " signum ", sighandler_t " handler ); +.fi +.SH DESCRIPTION +The +.BR sysv_signal () +function takes the same arguments, and performs the same task, as +.BR signal (2). +.P +However +.BR sysv_signal () +provides the System V unreliable signal semantics, that is: +a) the disposition of the signal is reset to the default +when the handler is invoked; +b) delivery of further instances of the signal is not blocked while +the signal handler is executing; and +c) if the handler interrupts (certain) blocking system calls, +then the system call is not automatically restarted. +.SH RETURN VALUE +The +.BR sysv_signal () +function returns the previous value of the signal handler, or +.B SIG_ERR +on error. +.SH ERRORS +As for +.BR signal (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR sysv_signal () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +Use of +.BR sysv_signal () +should be avoided; use +.BR sigaction (2) +instead. +.P +On older Linux systems, +.BR sysv_signal () +and +.BR signal (2) +were equivalent. +But on newer systems, +.BR signal (2) +provides reliable signal semantics; see +.BR signal (2) +for details. +.P +The use of +.I sighandler_t +is a GNU extension; +this type is defined only if +the +.B _GNU_SOURCE +feature test macro is defined. +.SH STANDARDS +None. +.SH SEE ALSO +.BR sigaction (2), +.BR signal (2), +.BR bsd_signal (3), +.BR signal (7) diff --git a/man/man3/tailq.3 b/man/man3/tailq.3 new file mode 100644 index 0000000..45899a6 --- /dev/null +++ b/man/man3/tailq.3 @@ -0,0 +1,397 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH TAILQ 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +TAILQ_CONCAT, +TAILQ_EMPTY, +TAILQ_ENTRY, +TAILQ_FIRST, +TAILQ_FOREACH, +.\"TAILQ_FOREACH_FROM, +.\"TAILQ_FOREACH_FROM_SAFE, +TAILQ_FOREACH_REVERSE, +.\"TAILQ_FOREACH_REVERSE_FROM, +.\"TAILQ_FOREACH_REVERSE_FROM_SAFE, +.\"TAILQ_FOREACH_REVERSE_SAFE, +.\"TAILQ_FOREACH_SAFE, +TAILQ_HEAD, +TAILQ_HEAD_INITIALIZER, +TAILQ_INIT, +TAILQ_INSERT_AFTER, +TAILQ_INSERT_BEFORE, +TAILQ_INSERT_HEAD, +TAILQ_INSERT_TAIL, +TAILQ_LAST, +TAILQ_NEXT, +TAILQ_PREV, +TAILQ_REMOVE +.\"TAILQ_SWAP +\- implementation of a doubly linked tail queue +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B TAILQ_ENTRY(TYPE); +.P +.B TAILQ_HEAD(HEADNAME, TYPE); +.BI "TAILQ_HEAD TAILQ_HEAD_INITIALIZER(TAILQ_HEAD " head ); +.BI "void TAILQ_INIT(TAILQ_HEAD *" head ); +.P +.BI "int TAILQ_EMPTY(TAILQ_HEAD *" head ); +.P +.BI "void TAILQ_INSERT_HEAD(TAILQ_HEAD *" head , +.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); +.BI "void TAILQ_INSERT_TAIL(TAILQ_HEAD *" head , +.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); +.BI "void TAILQ_INSERT_BEFORE(struct TYPE *" listelm , +.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); +.BI "void TAILQ_INSERT_AFTER(TAILQ_HEAD *" head ", struct TYPE *" listelm , +.BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); +.P +.BI "struct TYPE *TAILQ_FIRST(TAILQ_HEAD *" head ); +.BI "struct TYPE *TAILQ_LAST(TAILQ_HEAD *" head ", HEADNAME);" +.BI "struct TYPE *TAILQ_PREV(struct TYPE *" elm ", HEADNAME, TAILQ_ENTRY " NAME ); +.BI "struct TYPE *TAILQ_NEXT(struct TYPE *" elm ", TAILQ_ENTRY " NAME ); +.P +.BI "TAILQ_FOREACH(struct TYPE *" var ", TAILQ_HEAD *" head , +.BI " TAILQ_ENTRY " NAME ); +.\" .BI "TAILQ_FOREACH_FROM(struct TYPE *" var ", TAILQ_HEAD *" head , +.\" .BI " TAILQ_ENTRY " NAME ); +.BI "TAILQ_FOREACH_REVERSE(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME," +.BI " TAILQ_ENTRY " NAME ); +.\" .BI "TAILQ_FOREACH_REVERSE_FROM(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME," +.\" .BI " TAILQ_ENTRY " NAME ); +.\" .P +.\" .BI "TAILQ_FOREACH_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head , +.\" .BI " TAILQ_ENTRY " NAME , +.\" .BI " struct TYPE *" temp_var ); +.\" .BI "TAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head , +.\" .BI " TAILQ_ENTRY " NAME , +.\" .BI " struct TYPE *" temp_var ); +.\" .BI "TAILQ_FOREACH_REVERSE_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head , +.\" .BI " HEADNAME, TAILQ_ENTRY " NAME , +.\" .BI " struct TYPE *" temp_var ); +.\" .BI "TAILQ_FOREACH_REVERSE_FROM_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head , +.\" .BI " HEADNAME, TAILQ_ENTRY " NAME , +.\" .BI " struct TYPE *" temp_var ); +.P +.BI "void TAILQ_REMOVE(TAILQ_HEAD *" head ", struct TYPE *" elm , +.BI " TAILQ_ENTRY " NAME ); +.P +.BI "void TAILQ_CONCAT(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 , +.BI " TAILQ_ENTRY " NAME ); +.\" .BI "void TAILQ_SWAP(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 ", TYPE," +.\" .BI " TAILQ_ENTRY " NAME ); +.fi +.SH DESCRIPTION +These macros define and operate on doubly linked tail queues. +.P +In the macro definitions, +.I TYPE +is the name of a user defined structure, +that must contain a field of type +.IR TAILQ_ENTRY , +named +.IR NAME . +The argument +.I HEADNAME +is the name of a user defined structure that must be declared +using the macro +.BR TAILQ_HEAD (). +.SS Creation +A tail queue is headed by a structure defined by the +.BR TAILQ_HEAD () +macro. +This structure contains a pair of pointers, +one to the first element in the queue +and the other to the last element in the queue. +The elements are doubly linked +so that an arbitrary element can be removed without traversing the queue. +New elements can be added to the queue +after an existing element, +before an existing element, +at the head of the queue, +or at the end of the queue. +A +.I TAILQ_HEAD +structure is declared as follows: +.P +.in +4 +.EX +TAILQ_HEAD(HEADNAME, TYPE) head; +.EE +.in +.P +where +.I struct HEADNAME +is the structure to be defined, and +.I struct TYPE +is the type of the elements to be linked into the queue. +A pointer to the head of the queue can later be declared as: +.P +.in +4 +.EX +struct HEADNAME *headp; +.EE +.in +.P +(The names +.I head +and +.I headp +are user selectable.) +.P +.BR TAILQ_ENTRY () +declares a structure that connects the elements in the queue. +.P +.BR TAILQ_HEAD_INITIALIZER () +evaluates to an initializer for the queue +.IR head . +.P +.BR TAILQ_INIT () +initializes the queue referenced by +.P +.BR TAILQ_EMPTY () +evaluates to true if there are no items on the queue. +.IR head . +.SS Insertion +.BR TAILQ_INSERT_HEAD () +inserts the new element +.I elm +at the head of the queue. +.P +.BR TAILQ_INSERT_TAIL () +inserts the new element +.I elm +at the end of the queue. +.P +.BR TAILQ_INSERT_BEFORE () +inserts the new element +.I elm +before the element +.IR listelm . +.P +.BR TAILQ_INSERT_AFTER () +inserts the new element +.I elm +after the element +.IR listelm . +.SS Traversal +.BR TAILQ_FIRST () +returns the first item on the queue, or NULL if the queue is empty. +.P +.BR TAILQ_LAST () +returns the last item on the queue. +If the queue is empty the return value is NULL. +.P +.BR TAILQ_PREV () +returns the previous item on the queue, or NULL if this item is the first. +.P +.BR TAILQ_NEXT () +returns the next item on the queue, or NULL if this item is the last. +.P +.BR TAILQ_FOREACH () +traverses the queue referenced by +.I head +in the forward direction, +assigning each element in turn to +.IR var . +.I var +is set to NULL if the loop completes normally, +or if there were no elements. +.\" .P +.\" .BR TAILQ_FOREACH_FROM () +.\" behaves identically to +.\" .BR TAILQ_FOREACH () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found TAILQ element and begins the loop at +.\" .I var +.\" instead of the first element in the TAILQ referenced by +.\" .IR head . +.P +.BR TAILQ_FOREACH_REVERSE () +traverses the queue referenced by +.I head +in the reverse direction, +assigning each element in turn to +.IR var . +.\" .P +.\" .BR TAILQ_FOREACH_REVERSE_FROM () +.\" behaves identically to +.\" .BR TAILQ_FOREACH_REVERSE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found TAILQ element and begins the reverse loop at +.\" .I var +.\" instead of the last element in the TAILQ referenced by +.\" .IR head . +.\" .P +.\" .BR TAILQ_FOREACH_SAFE () +.\" and +.\" .BR TAILQ_FOREACH_REVERSE_SAFE () +.\" traverse the list referenced by +.\" .I head +.\" in the forward or reverse direction respectively, +.\" assigning each element in turn to +.\" .IR var . +.\" However, unlike their unsafe counterparts, +.\" .BR TAILQ_FOREACH () +.\" and +.\" .BR TAILQ_FOREACH_REVERSE () +.\" permit to both remove +.\" .I var +.\" as well as free it from within the loop safely without interfering with the +.\" traversal. +.\" .P +.\" .BR TAILQ_FOREACH_FROM_SAFE () +.\" behaves identically to +.\" .BR TAILQ_FOREACH_SAFE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found TAILQ element and begins the loop at +.\" .I var +.\" instead of the first element in the TAILQ referenced by +.\" .IR head . +.\" .P +.\" .BR TAILQ_FOREACH_REVERSE_FROM_SAFE () +.\" behaves identically to +.\" .BR TAILQ_FOREACH_REVERSE_SAFE () +.\" when +.\" .I var +.\" is NULL, else it treats +.\" .I var +.\" as a previously found TAILQ element and begins the reverse loop at +.\" .I var +.\" instead of the last element in the TAILQ referenced by +.\" .IR head . +.SS Removal +.BR TAILQ_REMOVE () +removes the element +.I elm +from the queue. +.SS Other features +.\" .BR TAILQ_SWAP () +.\" swaps the contents of +.\" .I head1 +.\" and +.\" .IR head2 . +.\" .P +.BR TAILQ_CONCAT () +concatenates the queue headed by +.I head2 +onto the end of the one headed by +.I head1 +removing all entries from the former. +.SH RETURN VALUE +.BR TAILQ_EMPTY () +returns nonzero if the queue is empty, +and zero if the queue contains at least one entry. +.P +.BR TAILQ_FIRST (), +.BR TAILQ_LAST (), +.BR TAILQ_PREV (), +and +.BR TAILQ_NEXT () +return a pointer to the first, last, previous, or next +.I TYPE +structure, respectively. +.P +.BR TAILQ_HEAD_INITIALIZER () +returns an initializer that can be assigned to the queue +.IR head . +.SH STANDARDS +BSD. +.SH HISTORY +4.4BSD. +.SH CAVEATS +.BR TAILQ_FOREACH () +and +.BR TAILQ_FOREACH_REVERSE () +don't allow +.I var +to be removed or freed within the loop, +as it would interfere with the traversal. +.BR TAILQ_FOREACH_SAFE () +and +.BR TAILQ_FOREACH_REVERSE_SAFE (), +which are present on the BSDs but are not present in glibc, +fix this limitation by allowing +.I var +to safely be removed from the list and freed from within the loop +without interfering with the traversal. +.SH EXAMPLES +.\" SRC BEGIN (tailq.c) +.EX +#include +#include +#include +#include +\& +struct entry { + int data; + TAILQ_ENTRY(entry) entries; /* Tail queue */ +}; +\& +TAILQ_HEAD(tailhead, entry); +\& +int +main(void) +{ + struct entry *n1, *n2, *n3, *np; + struct tailhead head; /* Tail queue head */ + int i; +\& + TAILQ_INIT(&head); /* Initialize the queue */ +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the head */ + TAILQ_INSERT_HEAD(&head, n1, entries); +\& + n1 = malloc(sizeof(struct entry)); /* Insert at the tail */ + TAILQ_INSERT_TAIL(&head, n1, entries); +\& + n2 = malloc(sizeof(struct entry)); /* Insert after */ + TAILQ_INSERT_AFTER(&head, n1, n2, entries); +\& + n3 = malloc(sizeof(struct entry)); /* Insert before */ + TAILQ_INSERT_BEFORE(n2, n3, entries); +\& + TAILQ_REMOVE(&head, n2, entries); /* Deletion */ + free(n2); + /* Forward traversal */ + i = 0; + TAILQ_FOREACH(np, &head, entries) + np\->data = i++; + /* Reverse traversal */ + TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries) + printf("%i\en", np\->data); + /* TailQ deletion */ + n1 = TAILQ_FIRST(&head); + while (n1 != NULL) { + n2 = TAILQ_NEXT(n1, entries); + free(n1); + n1 = n2; + } + TAILQ_INIT(&head); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR insque (3), +.BR queue (7) diff --git a/man/man3/tan.3 b/man/man3/tan.3 new file mode 100644 index 0000000..738a052 --- /dev/null +++ b/man/man3/tan.3 @@ -0,0 +1,146 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH tan 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tan, tanf, tanl \- tangent function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double tan(double " x ); +.BI "float tanf(float " x ); +.BI "long double tanl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tanf (), +.BR tanl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the tangent of +.IR x , +where +.I x +is +given in radians. +.SH RETURN VALUE +On success, these functions return the tangent of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity or negative infinity, +a domain error occurs, +and a NaN is returned. +.P +If the correct result would overflow, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the mathematically correct sign. +.\" I think overflow can't occur, because the closest floating-point +.\" representation of pi/2 is still not close enough to pi/2 to +.\" produce a large enough value to overflow. +.\" Testing certainly seems to bear this out. -- mtk, Jul 08 +.\" +.\" POSIX.1 allows an optional underflow error; +.\" glibc 2.8 doesn't do this +.\" POSIX.1 an optional range error for subnormal x; +.\" glibc 2.8 doesn't do this +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is an infinity +.I errno +is set to +.B EDOM +(but see BUGS). +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Range error: result overflow +.\" Unable to test this case, since the best approximation of +.\" pi/2 in double precision only yields a tan() value of 1.633e16. +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tan (), +.BR tanf (), +.BR tanl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH BUGS +Before glibc 2.10, the glibc implementation did not set +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6782 +.I errno +to +.B EDOM +when a domain error occurred. +.SH SEE ALSO +.BR acos (3), +.BR asin (3), +.BR atan (3), +.BR atan2 (3), +.BR cos (3), +.BR ctan (3), +.BR sin (3) diff --git a/man/man3/tanf.3 b/man/man3/tanf.3 new file mode 100644 index 0000000..58e5a16 --- /dev/null +++ b/man/man3/tanf.3 @@ -0,0 +1 @@ +.so man3/tan.3 diff --git a/man/man3/tanh.3 b/man/man3/tanh.3 new file mode 100644 index 0000000..08a7a29 --- /dev/null +++ b/man/man3/tanh.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-07-27 by Walter Harms +.\" (walter.harms@informatik.uni-oldenburg.de) +.\" +.TH tanh 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tanh, tanhf, tanhl \- hyperbolic tangent function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double tanh(double " x ); +.BI "float tanhf(float " x ); +.BI "long double tanhl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tanhf (), +.BR tanhl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +These functions return the hyperbolic tangent of +.IR x , +which +is defined mathematically as: +.P +.nf + tanh(x) = sinh(x) / cosh(x) +.fi +.SH RETURN VALUE +On success, these functions return the hyperbolic tangent of +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is +0 (\-0), +0 (\-0) is returned. +.P +If +.I x +is positive infinity (negative infinity), ++1 (\-1) is returned. +.\" +.\" POSIX.1-2001 documents an optional range error (underflow) +.\" for subnormal x; +.\" glibc 2.8 does not do this. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tanh (), +.BR tanhf (), +.BR tanhl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The variant returning +.I double +also conforms to +SVr4, 4.3BSD, C89. +.SH SEE ALSO +.BR acosh (3), +.BR asinh (3), +.BR atanh (3), +.BR cosh (3), +.BR ctanh (3), +.BR sinh (3) diff --git a/man/man3/tanhf.3 b/man/man3/tanhf.3 new file mode 100644 index 0000000..3556edb --- /dev/null +++ b/man/man3/tanhf.3 @@ -0,0 +1 @@ +.so man3/tanh.3 diff --git a/man/man3/tanhl.3 b/man/man3/tanhl.3 new file mode 100644 index 0000000..3556edb --- /dev/null +++ b/man/man3/tanhl.3 @@ -0,0 +1 @@ +.so man3/tanh.3 diff --git a/man/man3/tanl.3 b/man/man3/tanl.3 new file mode 100644 index 0000000..58e5a16 --- /dev/null +++ b/man/man3/tanl.3 @@ -0,0 +1 @@ +.so man3/tan.3 diff --git a/man/man3/tcdrain.3 b/man/man3/tcdrain.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcdrain.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcflow.3 b/man/man3/tcflow.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcflow.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcflush.3 b/man/man3/tcflush.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcflush.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcgetattr.3 b/man/man3/tcgetattr.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcgetattr.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcgetpgrp.3 b/man/man3/tcgetpgrp.3 new file mode 100644 index 0000000..b29c9ab --- /dev/null +++ b/man/man3/tcgetpgrp.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tcgetpgrp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tcgetpgrp, tcsetpgrp \- get and set terminal foreground process group +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "pid_t tcgetpgrp(int " fd ); +.BI "int tcsetpgrp(int " fd ", pid_t " pgrp ); +.fi +.SH DESCRIPTION +The function +.BR tcgetpgrp () +returns the process group ID of the foreground process group on the +terminal associated to +.IR fd , +which must be the controlling terminal of the calling process. +.\" The process itself may be a background process. +.P +The function +.BR tcsetpgrp () +makes the process group with process group ID +.I pgrp +the foreground process group on the terminal associated to +.IR fd , +which must be the controlling terminal of the calling process, +and still be associated with its session. +Moreover, +.I pgrp +must be a (nonempty) process group belonging to +the same session as the calling process. +.P +If +.BR tcsetpgrp () +is called by a member of a background process group in its session, +and the calling process is not blocking or ignoring +.BR SIGTTOU , +a +.B SIGTTOU +signal is sent to all members of this background process group. +.SH RETURN VALUE +When +.I fd +refers to the controlling terminal of the calling process, +the function +.BR tcgetpgrp () +will return the foreground process group ID of that terminal +if there is one, and some value larger than 1 that is not +presently a process group ID otherwise. +When +.I fd +does not refer to the controlling terminal of the calling process, +\-1 is returned, and +.I errno +is set to indicate the error. +.P +When successful, +.BR tcsetpgrp () +returns 0. +Otherwise, it returns \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EINVAL +.I pgrp +has an unsupported value. +.TP +.B ENOTTY +The calling process does not have a controlling terminal, or +it has one but it is not described by +.IR fd , +or, for +.BR tcsetpgrp (), +this controlling terminal is no longer associated with the session +of the calling process. +.TP +.B EPERM +.I pgrp +has a supported value, but is not the process group ID of a +process in the same session as the calling process. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tcgetpgrp (), +.BR tcsetpgrp () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +These functions are implemented via the +.B TIOCGPGRP +and +.B TIOCSPGRP +ioctls. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +The ioctls appeared in 4.2BSD. +The functions are POSIX inventions. +.SH SEE ALSO +.BR setpgid (2), +.BR setsid (2), +.BR credentials (7) diff --git a/man/man3/tcgetsid.3 b/man/man3/tcgetsid.3 new file mode 100644 index 0000000..a8925f7 --- /dev/null +++ b/man/man3/tcgetsid.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tcgetsid 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tcgetsid \- get session ID +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE 500" " /* See feature_test_macros(7) */" +.B "#include " +.P +.BI "pid_t tcgetsid(int " fd ); +.fi +.SH DESCRIPTION +The function +.BR tcgetsid () +returns the session ID of the current session that has the +terminal associated to +.I fd +as controlling terminal. +This terminal must be the controlling terminal of the calling process. +.SH RETURN VALUE +When +.I fd +refers to the controlling terminal of our session, +the function +.BR tcgetsid () +will return the session ID of this session. +Otherwise, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B ENOTTY +The calling process does not have a controlling terminal, or +it has one but it is not described by +.IR fd . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tcgetsid () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.P +This function is implemented via the +.B TIOCGSID +.BR ioctl (2), +present +since Linux 2.1.71. +.SH SEE ALSO +.BR getsid (2) diff --git a/man/man3/tcsendbreak.3 b/man/man3/tcsendbreak.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcsendbreak.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcsetattr.3 b/man/man3/tcsetattr.3 new file mode 100644 index 0000000..eb47249 --- /dev/null +++ b/man/man3/tcsetattr.3 @@ -0,0 +1 @@ +.so man3/termios.3 diff --git a/man/man3/tcsetpgrp.3 b/man/man3/tcsetpgrp.3 new file mode 100644 index 0000000..1a8b360 --- /dev/null +++ b/man/man3/tcsetpgrp.3 @@ -0,0 +1 @@ +.so man3/tcgetpgrp.3 diff --git a/man/man3/tdelete.3 b/man/man3/tdelete.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man/man3/tdelete.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man/man3/tdestroy.3 b/man/man3/tdestroy.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man/man3/tdestroy.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man/man3/telldir.3 b/man/man3/telldir.3 new file mode 100644 index 0000000..90ae1f3 --- /dev/null +++ b/man/man3/telldir.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:48:42 1993 by Rik Faith (faith@cs.unc.edu) +.TH telldir 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +telldir \- return current location in directory stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "long telldir(DIR *" dirp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR telldir (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR telldir () +function returns the current location associated with +the directory stream \fIdirp\fP. +.SH RETURN VALUE +On success, the +.BR telldir () +function returns the current location +in the directory stream. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +Invalid directory stream descriptor \fIdirp\fP. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR telldir () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.3BSD. +.P +Up to glibc 2.1.1, the return type of +.BR telldir () +was +.IR off_t . +POSIX.1-2001 specifies +.IR long , +and this is the type used since glibc 2.1.2. +.P +In early filesystems, the value returned by +.BR telldir () +was a simple file offset within a directory. +Modern filesystems use tree or hash structures, rather than flat tables, +to represent directories. +On such filesystems, the value returned by +.BR telldir () +(and used internally by +.BR readdir (3)) +is a "cookie" that is used by the implementation +to derive a position within a directory. +.\" https://lwn.net/Articles/544298/ +Application programs should treat this strictly as an opaque value, making +.I no +assumptions about its contents. +.SH SEE ALSO +.BR closedir (3), +.BR opendir (3), +.BR readdir (3), +.BR rewinddir (3), +.BR scandir (3), +.BR seekdir (3) diff --git a/man/man3/tempnam.3 b/man/man3/tempnam.3 new file mode 100644 index 0000000..3f9baca --- /dev/null +++ b/man/man3/tempnam.3 @@ -0,0 +1,175 @@ +'\" t +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tempnam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tempnam \- create a name for a temporary file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *tempnam(const char *" dir ", const char *" pfx ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tempnam (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +.I "Never use this function." +Use +.BR mkstemp (3) +or +.BR tmpfile (3) +instead. +.P +The +.BR tempnam () +function returns a pointer to a string that is a valid filename, +and such that a file with this name did not exist when +.BR tempnam () +checked. +The filename suffix of the pathname generated will start with +.I pfx +in case +.I pfx +is a non-NULL string of at most five bytes. +The directory prefix part of the pathname generated is required to +be "appropriate" (often that at least implies writable). +.P +Attempts to find an appropriate directory go through the following +steps: +.TP 3 +a) +In case the environment variable +.B TMPDIR +exists and +contains the name of an appropriate directory, that is used. +.TP +b) +Otherwise, if the +.I dir +argument is non-NULL and appropriate, it is used. +.TP +c) +Otherwise, +.I P_tmpdir +(as defined in +.IR ) +is used when appropriate. +.TP +d) +Finally an implementation-defined directory may be used. +.P +The string returned by +.BR tempnam () +is allocated using +.BR malloc (3) +and hence should be freed by +.BR free (3). +.SH RETURN VALUE +On success, the +.BR tempnam () +function returns a pointer to a unique temporary filename. +It returns NULL if a unique name cannot be generated, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Allocation of storage failed. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tempnam () +T} Thread safety MT-Safe env +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, 4.3BSD, POSIX.1-2001. +Obsoleted in POSIX.1-2008. +.SH NOTES +Although +.BR tempnam () +generates names that are difficult to guess, +it is nevertheless possible that between the time that +.BR tempnam () +returns a pathname, and the time that the program opens it, +another program might create that pathname using +.BR open (2), +or create it as a symbolic link. +This can lead to security holes. +To avoid such possibilities, use the +.BR open (2) +.B O_EXCL +flag to open the pathname. +Or better yet, use +.BR mkstemp (3) +or +.BR tmpfile (3). +.P +SUSv2 does not mention the use of +.BR TMPDIR ; +glibc will use it only +when the program is not set-user-ID. +On SVr4, the directory used under \fBd)\fP is +.I /tmp +(and this is what glibc does). +.P +Because it dynamically allocates memory used to return the pathname, +.BR tempnam () +is reentrant, and thus thread safe, unlike +.BR tmpnam (3). +.P +The +.BR tempnam () +function generates a different string each time it is called, +up to +.B TMP_MAX +(defined in +.IR ) +times. +If it is called more than +.B TMP_MAX +times, +the behavior is implementation defined. +.P +.BR tempnam () +uses at most the first five bytes from +.IR pfx . +.P +The glibc implementation of +.BR tempnam () +fails with the error +.B EEXIST +upon failure to find a unique name. +.SH BUGS +The precise meaning of "appropriate" is undefined; +it is unspecified how accessibility of a directory is determined. +.SH SEE ALSO +.BR mkstemp (3), +.BR mktemp (3), +.BR tmpfile (3), +.BR tmpnam (3) diff --git a/man/man3/termios.3 b/man/man3/termios.3 new file mode 100644 index 0000000..932cfb4 --- /dev/null +++ b/man/man3/termios.3 @@ -0,0 +1,1235 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" Copyright (c) 2006-2015, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-02-25 by Jim Van Zandt +.\" Modified 1995-09-02 by Jim Van Zandt +.\" moved to man3, aeb, 950919 +.\" Modified 2001-09-22 by Michael Kerrisk +.\" Modified 2001-12-17, aeb +.\" Modified 2004-10-31, aeb +.\" 2006-12-28, mtk: +.\" Added .SS headers to give some structure to this page; and a +.\" small amount of reordering. +.\" Added a section on canonical and noncanonical mode. +.\" Enhanced the discussion of "raw" mode for cfmakeraw(). +.\" Document CMSPAR. +.\" +.TH termios 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, +cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \- +get and set terminal attributes, line control, get and set baud rate +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int tcgetattr(int " fd ", struct termios *" termios_p ); +.BI "int tcsetattr(int " fd ", int " optional_actions , +.BI " const struct termios *" termios_p ); +.P +.BI "int tcsendbreak(int " fd ", int " duration ); +.BI "int tcdrain(int " fd ); +.BI "int tcflush(int " fd ", int " queue_selector ); +.BI "int tcflow(int " fd ", int " action ); +.P +.BI "void cfmakeraw(struct termios *" termios_p ); +.P +.BI "speed_t cfgetispeed(const struct termios *" termios_p ); +.BI "speed_t cfgetospeed(const struct termios *" termios_p ); +.P +.BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed ); +.BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed ); +.BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR cfsetspeed (), +.BR cfmakeraw (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The termios functions describe a general terminal interface that is +provided to control asynchronous communications ports. +.SS The termios structure +Many of the functions described here have a \fItermios_p\fP argument +that is a pointer to a \fItermios\fP structure. +This structure contains at least the following members: +.P +.in +4n +.EX +tcflag_t c_iflag; /* input modes */ +tcflag_t c_oflag; /* output modes */ +tcflag_t c_cflag; /* control modes */ +tcflag_t c_lflag; /* local modes */ +cc_t c_cc[NCCS]; /* special characters */ +.EE +.in +.P +The values that may be assigned to these fields are described below. +In the case of the first four bit-mask fields, +the definitions of some of the associated flags that may be set are +exposed only if a specific feature test macro (see +.BR feature_test_macros (7)) +is defined, as noted in brackets ("[]"). +.P +In the descriptions below, "not in POSIX" means that the +value is not specified in POSIX.1-2001, +and "XSI" means that the value is specified in POSIX.1-2001 +as part of the XSI extension. +.P +\fIc_iflag\fP flag constants: +.TP +.B IGNBRK +Ignore BREAK condition on input. +.TP +.B BRKINT +If \fBIGNBRK\fP is set, a BREAK is ignored. +If it is not set +but \fBBRKINT\fP is set, then a BREAK causes the input and output +queues to be flushed, and if the terminal is the controlling +terminal of a foreground process group, it will cause a +\fBSIGINT\fP to be sent to this foreground process group. +When neither \fBIGNBRK\fP nor \fBBRKINT\fP are set, a BREAK +reads as a null byte (\[aq]\e0\[aq]), except when \fBPARMRK\fP is set, +in which case it reads as the sequence \e377 \e0 \e0. +.TP +.B IGNPAR +Ignore framing errors and parity errors. +.TP +.B PARMRK +If this bit is set, input bytes with parity or framing errors are +marked when passed to the program. +This bit is meaningful only when +\fBINPCK\fP is set and \fBIGNPAR\fP is not set. +The way erroneous bytes are marked is with two preceding bytes, +\e377 and \e0. +Thus, the program actually reads three bytes for one +erroneous byte received from the terminal. +If a valid byte has the value \e377, +and \fBISTRIP\fP (see below) is not set, +the program might confuse it with the prefix that marks a +parity error. +Therefore, a valid byte \e377 is passed to the program as two +bytes, \e377 \e377, in this case. +.IP +If neither \fBIGNPAR\fP nor \fBPARMRK\fP +is set, read a character with a parity error or framing error +as \e0. +.TP +.B INPCK +Enable input parity checking. +.TP +.B ISTRIP +Strip off eighth bit. +.TP +.B INLCR +Translate NL to CR on input. +.TP +.B IGNCR +Ignore carriage return on input. +.TP +.B ICRNL +Translate carriage return to newline on input (unless \fBIGNCR\fP is set). +.TP +.B IUCLC +(not in POSIX) Map uppercase characters to lowercase on input. +.TP +.B IXON +Enable XON/XOFF flow control on output. +.TP +.B IXANY +(XSI) Typing any character will restart stopped output. +(The default is to allow just the START character to restart output.) +.TP +.B IXOFF +Enable XON/XOFF flow control on input. +.TP +.B IMAXBEL +(not in POSIX) Ring bell when input queue is full. +Linux does not implement this bit, and acts as if it is always set. +.TP +.BR IUTF8 " (since Linux 2.6.4)" +(not in POSIX) Input is UTF8; +this allows character-erase to be correctly performed in cooked mode. +.P +.I c_oflag +flag constants: +.TP +.B OPOST +Enable implementation-defined output processing. +.TP +.B OLCUC +(not in POSIX) Map lowercase characters to uppercase on output. +.TP +.B ONLCR +(XSI) Map NL to CR-NL on output. +.TP +.B OCRNL +Map CR to NL on output. +.TP +.B ONOCR +Don't output CR at column 0. +.TP +.B ONLRET +The NL character is assumed to do the carriage-return function; +the kernel's idea of the current column is set to 0 +after both NL and CR. +.TP +.B OFILL +Send fill characters for a delay, rather than using a timed delay. +.TP +.B OFDEL +Fill character is ASCII DEL (0177). +If unset, fill character is ASCII NUL (\[aq]\e0\[aq]). +(Not implemented on Linux.) +.TP +.B NLDLY +Newline delay mask. +Values are \fBNL0\fP and \fBNL1\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B CRDLY +Carriage return delay mask. +Values are \fBCR0\fP, \fBCR1\fP, \fBCR2\fP, or \fBCR3\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B TABDLY +Horizontal tab delay mask. +Values are \fBTAB0\fP, \fBTAB1\fP, \fBTAB2\fP, \fBTAB3\fP (or \fBXTABS\fP, +but see the +.B BUGS +section). +A value of TAB3, that is, XTABS, expands tabs to spaces +(with tab stops every eight columns). +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B BSDLY +Backspace delay mask. +Values are \fBBS0\fP or \fBBS1\fP. +(Has never been implemented.) +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B VTDLY +Vertical tab delay mask. +Values are \fBVT0\fP or \fBVT1\fP. +.TP +.B FFDLY +Form feed delay mask. +Values are \fBFF0\fP or \fBFF1\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.P +\fIc_cflag\fP flag constants: +.TP +.B CBAUD +(not in POSIX) Baud speed mask (4+1 bits). +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B CBAUDEX +(not in POSIX) Extra baud speed mask (1 bit), included in +.BR CBAUD . +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.IP +(POSIX says that the baud speed is stored in the +.I termios +structure without specifying where precisely, and provides +.BR cfgetispeed () +and +.BR cfsetispeed () +for getting at it. +Some systems use bits selected by +.B CBAUD +in +.IR c_cflag , +other systems use separate fields, for example, +.I sg_ispeed +and +.IR sg_ospeed .) +.TP +.B CSIZE +Character size mask. +Values are \fBCS5\fP, \fBCS6\fP, \fBCS7\fP, or \fBCS8\fP. +.TP +.B CSTOPB +Set two stop bits, rather than one. +.TP +.B CREAD +Enable receiver. +.TP +.B PARENB +Enable parity generation on output and parity checking for input. +.TP +.B PARODD +If set, then parity for input and output is odd; +otherwise even parity is used. +.TP +.B HUPCL +Lower modem control lines after last process closes the device (hang up). +.TP +.B CLOCAL +Ignore modem control lines. +.TP +.B LOBLK +(not in POSIX) Block output from a noncurrent shell layer. +For use by \fBshl\fP (shell layers). +(Not implemented on Linux.) +.TP +.B CIBAUD +(not in POSIX) Mask for input speeds. +The values for the +.B CIBAUD +bits are +the same as the values for the +.B CBAUD +bits, shifted left +.B IBSHIFT +bits. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +(Not implemented in glibc, supported on Linux via +.BR TCGET * +and +.BR TCSET * +ioctls; see +.BR ioctl_tty (2)) +.TP +.B CMSPAR +(not in POSIX) +Use "stick" (mark/space) parity (supported on certain serial +devices): if +.B PARODD +is set, the parity bit is always 1; if +.B PARODD +is not set, then the parity bit is always 0. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B CRTSCTS +(not in POSIX) Enable RTS/CTS (hardware) flow control. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.P +\fIc_lflag\fP flag constants: +.TP +.B ISIG +When any of the characters INTR, QUIT, SUSP, or DSUSP are received, +generate the corresponding signal. +.TP +.B ICANON +Enable canonical mode (described below). +.TP +.B XCASE +(not in POSIX; not supported under Linux) +If \fBICANON\fP is also set, terminal is uppercase only. +Input is converted to lowercase, except for characters preceded by \e. +On output, uppercase characters are preceded by \e and lowercase +characters are converted to uppercase. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.\" glibc is probably now wrong to allow +.\" Define +.\" .B _XOPEN_SOURCE +.\" to expose +.\" .BR XCASE . +.TP +.B ECHO +Echo input characters. +.TP +.B ECHOE +If \fBICANON\fP is also set, the ERASE character erases the preceding +input character, and WERASE erases the preceding word. +.TP +.B ECHOK +If \fBICANON\fP is also set, the KILL character erases the current line. +.TP +.B ECHONL +If \fBICANON\fP is also set, echo the NL character even if ECHO is not set. +.TP +.B ECHOCTL +(not in POSIX) If \fBECHO\fP is also set, +terminal special characters other than +TAB, NL, START, and STOP are echoed as \fB\[ha]X\fP, +where X is the character with +ASCII code 0x40 greater than the special character. +For example, character +0x08 (BS) is echoed as \fB\[ha]H\fP. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B ECHOPRT +(not in POSIX) If \fBICANON\fP and \fBECHO\fP are also set, characters +are printed as they are being erased. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B ECHOKE +(not in POSIX) If \fBICANON\fP is also set, KILL is echoed by erasing +each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B DEFECHO +(not in POSIX) Echo only when a process is reading. +(Not implemented on Linux.) +.TP +.B FLUSHO +(not in POSIX; not supported under Linux) +Output is being flushed. +This flag is toggled by typing +the DISCARD character. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B NOFLSH +Disable flushing the input and output queues when generating signals for the +INT, QUIT, and SUSP characters. +.\" Stevens lets SUSP only flush the input queue +.TP +.B TOSTOP +Send the +.B SIGTTOU +signal to the process group of a background process +which tries to write to its controlling terminal. +.TP +.B PENDIN +(not in POSIX; not supported under Linux) +All characters in the input queue are reprinted when +the next character is read. +.RB ( bash (1) +handles typeahead this way.) +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B IEXTEN +Enable implementation-defined input processing. +This flag, as well as \fBICANON\fP must be enabled for the +special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted, +and for the \fBIUCLC\fP flag to be effective. +.P +The \fIc_cc\fP array defines the terminal special characters. +The symbolic indices (initial values) and meaning are: +.TP +.B VDISCARD +(not in POSIX; not supported under Linux; 017, SI, Ctrl-O) +Toggle: start/stop discarding pending output. +Recognized when +.B IEXTEN +is set, and then not passed as input. +.TP +.B VDSUSP +(not in POSIX; not supported under Linux; 031, EM, Ctrl-Y) +Delayed suspend character (DSUSP): +send +.B SIGTSTP +signal when the character is read by the user program. +Recognized when +.B IEXTEN +and +.B ISIG +are set, and the system supports +job control, and then not passed as input. +.TP +.B VEOF +(004, EOT, Ctrl-D) +End-of-file character (EOF). +More precisely: this character causes the pending tty buffer to be sent +to the waiting user program without waiting for end-of-line. +If it is the first character of the line, the +.BR read (2) +in the user program returns 0, which signifies end-of-file. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VEOL +(0, NUL) +Additional end-of-line character (EOL). +Recognized when +.B ICANON +is set. +.TP +.B VEOL2 +(not in POSIX; 0, NUL) +Yet another end-of-line character (EOL2). +Recognized when +.B ICANON +is set. +.TP +.B VERASE +(0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) +Erase character (ERASE). +This erases the previous not-yet-erased character, +but does not erase past EOF or beginning-of-line. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VINTR +(003, ETX, Ctrl-C, or also 0177, DEL, rubout) +Interrupt character (INTR). +Send a +.B SIGINT +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VKILL +(025, NAK, Ctrl-U, or Ctrl-X, or also @) +Kill character (KILL). +This erases the input since the last EOF or beginning-of-line. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VLNEXT +(not in POSIX; 026, SYN, Ctrl-V) +Literal next (LNEXT). +Quotes the next input character, depriving it of +a possible special meaning. +Recognized when +.B IEXTEN +is set, and then not passed as input. +.TP +.B VMIN +Minimum number of characters for noncanonical read (MIN). +.TP +.B VQUIT +(034, FS, Ctrl-\e) +Quit character (QUIT). +Send +.B SIGQUIT +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VREPRINT +(not in POSIX; 022, DC2, Ctrl-R) +Reprint unread characters (REPRINT). +Recognized when +.B ICANON +and +.B IEXTEN +are set, and then not passed as input. +.TP +.B VSTART +(021, DC1, Ctrl-Q) +Start character (START). +Restarts output stopped by the Stop character. +Recognized when +.B IXON +is set, and then not passed as input. +.TP +.B VSTATUS +(not in POSIX; not supported under Linux; +status request: 024, DC4, Ctrl-T). +Status character (STATUS). +Display status information at terminal, +including state of foreground process and amount of CPU time it has consumed. +Also sends a +.B SIGINFO +signal (not supported on Linux) to the foreground process group. +.TP +.B VSTOP +(023, DC3, Ctrl-S) +Stop character (STOP). +Stop output until Start character typed. +Recognized when +.B IXON +is set, and then not passed as input. +.TP +.B VSUSP +(032, SUB, Ctrl-Z) +Suspend character (SUSP). +Send +.B SIGTSTP +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VSWTCH +(not in POSIX; not supported under Linux; 0, NUL) +Switch character (SWTCH). +Used in System V to switch shells in +.IR "shell layers" , +a predecessor to shell job control. +.TP +.B VTIME +Timeout in deciseconds for noncanonical read (TIME). +.TP +.B VWERASE +(not in POSIX; 027, ETB, Ctrl-W) +Word erase (WERASE). +Recognized when +.B ICANON +and +.B IEXTEN +are set, and then not passed as input. +.P +An individual terminal special character can be disabled by setting +the value of the corresponding +.I c_cc +element to +.BR _POSIX_VDISABLE . +.P +The above symbolic subscript values are all different, except that +.BR VTIME , +.B VMIN +may have the same value as +.BR VEOL , +.BR VEOF , +respectively. +In noncanonical mode the special character meaning is replaced +by the timeout meaning. +For an explanation of +.B VMIN +and +.BR VTIME , +see the description of +noncanonical mode below. +.SS Retrieving and changing terminal settings +.BR tcgetattr () +gets the parameters associated with the object referred by \fIfd\fP and +stores them in the \fItermios\fP structure referenced by +\fItermios_p\fP. +This function may be invoked from a background process; +however, the terminal attributes may be subsequently changed by a +foreground process. +.P +.BR tcsetattr () +sets the parameters associated with the terminal (unless support is +required from the underlying hardware that is not available) from the +\fItermios\fP structure referred to by \fItermios_p\fP. +\fIoptional_actions\fP specifies when the changes take effect: +.TP +.B TCSANOW +the change occurs immediately. +.TP +.B TCSADRAIN +the change occurs after all output written to +.I fd +has been transmitted. +This option should be used when changing +parameters that affect output. +.TP +.B TCSAFLUSH +the change occurs after all output written to the object referred by +.I fd +has been transmitted, and all input that has been received but not read +will be discarded before the change is made. +.SS Canonical and noncanonical mode +The setting of the +.B ICANON +canon flag in +.I c_lflag +determines whether the terminal is operating in canonical mode +.RB ( ICANON +set) or +noncanonical mode +.RB ( ICANON +unset). +By default, +.B ICANON +is set. +.P +In canonical mode: +.IP \[bu] 3 +Input is made available line by line. +An input line is available when one of the line delimiters +is typed (NL, EOL, EOL2; or EOF at the start of line). +Except in the case of EOF, the line delimiter is included +in the buffer returned by +.BR read (2). +.IP \[bu] +Line editing is enabled (ERASE, KILL; +and if the +.B IEXTEN +flag is set: WERASE, REPRINT, LNEXT). +A +.BR read (2) +returns at most one line of input; if the +.BR read (2) +requested fewer bytes than are available in the current line of input, +then only as many bytes as requested are read, +and the remaining characters will be available for a future +.BR read (2). +.IP \[bu] +The maximum line length is 4096 chars +(including the terminating newline character); +lines longer than 4096 chars are truncated. +After 4095 characters, input processing (e.g., +.B ISIG +and +.B ECHO* +processing) continues, but any input data after 4095 characters up to +(but not including) any terminating newline is discarded. +This ensures that the terminal can always receive +more input until at least one line can be read. +.P +In noncanonical mode input is available immediately (without +the user having to type a line-delimiter character), +no input processing is performed, +and line editing is disabled. +The read buffer will only accept 4095 chars; this provides the +necessary space for a newline char if the input mode is switched +to canonical. +The settings of MIN +.RI ( c_cc[VMIN] ) +and TIME +.RI ( c_cc[VTIME] ) +determine the circumstances in which a +.BR read (2) +completes; there are four distinct cases: +.TP +MIN == 0, TIME == 0 (polling read) +If data is available, +.BR read (2) +returns immediately, with the lesser of the number of bytes +available, or the number of bytes requested. +If no data is available, +.BR read (2) +returns 0. +.TP +MIN > 0, TIME == 0 (blocking read) +.BR read (2) +blocks until MIN bytes are available, +and returns up to the number of bytes requested. +.TP +MIN == 0, TIME > 0 (read with timeout) +TIME specifies the limit for a timer in tenths of a second. +The timer is started when +.BR read (2) +is called. +.BR read (2) +returns either when at least one byte of data is available, +or when the timer expires. +If the timer expires without any input becoming available, +.BR read (2) +returns 0. +If data is already available at the time of the call to +.BR read (2), +the call behaves as though the data was received immediately after the call. +.TP +MIN > 0, TIME > 0 (read with interbyte timeout) +TIME specifies the limit for a timer in tenths of a second. +Once an initial byte of input becomes available, +the timer is restarted after each further byte is received. +.BR read (2) +returns when any of the following conditions is met: +.RS +.IP \[bu] 3 +MIN bytes have been received. +.IP \[bu] +The interbyte timer expires. +.IP \[bu] +The number of bytes requested by +.BR read (2) +has been received. +(POSIX does not specify this termination condition, +and on some other implementations +.\" e.g., Solaris +.BR read (2) +does not return in this case.) +.RE +.IP +Because the timer is started only after the initial byte +becomes available, at least one byte will be read. +If data is already available at the time of the call to +.BR read (2), +the call behaves as though the data was received immediately after the call. +.P +POSIX +.\" POSIX.1-2008 XBD 11.1.7 +does not specify whether the setting of the +.B O_NONBLOCK +file status flag takes precedence over the MIN and TIME settings. +If +.B O_NONBLOCK +is set, a +.BR read (2) +in noncanonical mode may return immediately, +regardless of the setting of MIN or TIME. +Furthermore, if no data is available, +POSIX permits a +.BR read (2) +in noncanonical mode to return either 0, or \-1 with +.I errno +set to +.BR EAGAIN . +.SS Raw mode +.BR cfmakeraw () +sets the terminal to something like the +"raw" mode of the old Version 7 terminal driver: +input is available character by character, +echoing is disabled, and all special processing of +terminal input and output characters is disabled. +The terminal attributes are set as follows: +.P +.in +4n +.EX +termios_p\->c_iflag &= \[ti](IGNBRK | BRKINT | PARMRK | ISTRIP + | INLCR | IGNCR | ICRNL | IXON); +termios_p\->c_oflag &= \[ti]OPOST; +termios_p\->c_lflag &= \[ti](ECHO | ECHONL | ICANON | ISIG | IEXTEN); +termios_p\->c_cflag &= \[ti](CSIZE | PARENB); +termios_p\->c_cflag |= CS8; +.EE +.in +.\" +.SS Line control +.BR tcsendbreak () +transmits a continuous stream of zero-valued bits for a specific +duration, if the terminal is using asynchronous serial data +transmission. +If \fIduration\fP is zero, it transmits zero-valued bits +for at least 0.25 seconds, and not more than 0.5 seconds. +If \fIduration\fP is not zero, it sends zero-valued bits for some +implementation-defined length of time. +.P +If the terminal is not using asynchronous serial data transmission, +.BR tcsendbreak () +returns without taking any action. +.P +.BR tcdrain () +waits until all output written to the object referred to by +.I fd +has been transmitted. +.P +.BR tcflush () +discards data written to the object referred to by +.I fd +but not transmitted, or data received but not read, depending on the +value of +.IR queue_selector : +.TP +.B TCIFLUSH +flushes data received but not read. +.TP +.B TCOFLUSH +flushes data written but not transmitted. +.TP +.B TCIOFLUSH +flushes both data received but not read, and data written but not +transmitted. +.P +.BR tcflow () +suspends transmission or reception of data on the object referred to by +.IR fd , +depending on the value of +.IR action : +.TP +.B TCOOFF +suspends output. +.TP +.B TCOON +restarts suspended output. +.TP +.B TCIOFF +transmits a STOP character, which stops the terminal device from +transmitting data to the system. +.TP +.B TCION +transmits a START character, which starts the terminal device +transmitting data to the system. +.P +The default on open of a terminal file is that neither its input nor its +output is suspended. +.SS Line speed +The baud rate functions are provided for getting and setting the values +of the input and output baud rates in the \fItermios\fP structure. +The new values do not take effect +until +.BR tcsetattr () +is successfully called. +.P +Setting the speed to \fBB0\fP instructs the modem to "hang up". +The actual bit rate corresponding to \fBB38400\fP may be altered with +.BR setserial (8). +.P +The input and output baud rates are stored in the \fItermios\fP +structure. +.P +.BR cfgetospeed () +returns the output baud rate stored in the \fItermios\fP structure +pointed to by +.IR termios_p . +.P +.BR cfsetospeed () +sets the output baud rate stored in the \fItermios\fP structure pointed +to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: +.RS +.TP +.B B0 +.TQ +.B B50 +.TQ +.B B75 +.TQ +.B B110 +.TQ +.B B134 +.TQ +.B B150 +.TQ +.B B200 +.TQ +.B B300 +.TQ +.B B600 +.TQ +.B B1200 +.TQ +.B B1800 +.TQ +.B B2400 +.TQ +.B B4800 +.TQ +.B B9600 +.TQ +.B B19200 +.TQ +.B B38400 +.TQ +.B B57600 +.TQ +.B B115200 +.TQ +.B B230400 +.TQ +.B B460800 +.TQ +.B B500000 +.TQ +.B B576000 +.TQ +.B B921600 +.TQ +.B B1000000 +.TQ +.B B1152000 +.TQ +.B B1500000 +.TQ +.B B2000000 +.RE +.P +These constants are additionally supported on the SPARC architecture: +.RS +.TP +.B B76800 +.TQ +.B B153600 +.TQ +.B B307200 +.TQ +.B B614400 +.RE +.P +These constants are additionally supported on non-SPARC architectures: +.RS +.TP +.B B2500000 +.TQ +.B B3000000 +.TQ +.B B3500000 +.TQ +.B B4000000 +.RE +.P +Due to differences between architectures, portable applications should check +if a particular +.BI B nnn +constant is defined prior to using it. +.P +The zero baud rate, +.BR B0 , +is used to terminate the connection. +If +.B B0 +is specified, the modem control lines shall no longer be asserted. +Normally, this will disconnect the line. +.B CBAUDEX +is a mask +for the speeds beyond those defined in POSIX.1 (57600 and above). +Thus, +.BR B57600 " & " CBAUDEX +is nonzero. +.P +Setting the baud rate to a value other than those defined by +.BI B nnn +constants is possible via the +.B TCSETS2 +ioctl; see +.BR ioctl_tty (2). +.P +.BR cfgetispeed () +returns the input baud rate stored in the +.I termios +structure. +.P +.BR cfsetispeed () +sets the input baud rate stored in the +.I termios +structure to +.IR speed , +which must be specified as one of the +.BI B nnn +constants listed above for +.BR cfsetospeed (). +If the input baud rate is set to the literal constant +.B 0 +(not the symbolic constant +.BR B0 ), +the input baud rate will be +equal to the output baud rate. +.P +.BR cfsetspeed () +is a 4.4BSD extension. +It takes the same arguments as +.BR cfsetispeed (), +and sets both input and output speed. +.SH RETURN VALUE +.BR cfgetispeed () +returns the input baud rate stored in the +\fItermios\fP +structure. +.P +.BR cfgetospeed () +returns the output baud rate stored in the \fItermios\fP structure. +.P +All other functions return: +.TP +.B 0 +on success. +.TP +.B \-1 +on failure and set +.I errno +to indicate the error. +.P +Note that +.BR tcsetattr () +returns success if \fIany\fP of the requested changes could be +successfully carried out. +Therefore, when making multiple changes +it may be necessary to follow this call with a further call to +.BR tcgetattr () +to check that all changes have been performed successfully. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tcgetattr (), +.BR tcsetattr (), +.BR tcdrain (), +.BR tcflush (), +.BR tcflow (), +.BR tcsendbreak (), +.BR cfmakeraw (), +.BR cfgetispeed (), +.BR cfgetospeed (), +.BR cfsetispeed (), +.BR cfsetospeed (), +.BR cfsetspeed () +T} Thread safety MT-Safe +.TE +.\" FIXME: The markings are different from that in the glibc manual. +.\" markings in glibc manual are more detailed: +.\" +.\" tcsendbreak: MT-Unsafe race:tcattr(filedes)/bsd +.\" tcflow: MT-Unsafe race:tcattr(filedes)/bsd +.\" +.\" glibc manual says /bsd indicate the preceding marker only applies +.\" when the underlying kernel is a BSD kernel. +.\" So, it is safety in Linux kernel. +.SH STANDARDS +.TP +.BR tcgetattr () +.TQ +.BR tcsetattr () +.TQ +.BR tcsendbreak () +.TQ +.BR tcdrain () +.TQ +.BR tcflush () +.TQ +.BR tcflow () +.TQ +.BR cfgetispeed () +.TQ +.BR cfgetospeed () +.TQ +.BR cfsetispeed () +.TQ +.BR cfsetospeed () +POSIX.1-2008. +.TP +.BR cfmakeraw () +.TQ +.BR cfsetspeed () +BSD. +.SH HISTORY +.TP +.BR tcgetattr () +.TQ +.BR tcsetattr () +.TQ +.BR tcsendbreak () +.TQ +.BR tcdrain () +.TQ +.BR tcflush () +.TQ +.BR tcflow () +.TQ +.BR cfgetispeed () +.TQ +.BR cfgetospeed () +.TQ +.BR cfsetispeed () +.TQ +.BR cfsetospeed () +POSIX.1-2001. +.TP +.BR cfmakeraw () +.TQ +.BR cfsetspeed () +BSD. +.SH NOTES +UNIX\ V7 and several later systems have a list of baud rates +where after the values +.B B0 +through +.B B9600 +one finds the two constants +.BR EXTA , +.B EXTB +("External A" and "External B"). +Many systems extend the list with much higher baud rates. +.P +The effect of a nonzero \fIduration\fP with +.BR tcsendbreak () +varies. +SunOS specifies a break of +.I "duration\ *\ N" +seconds, where \fIN\fP is at least 0.25, and not more than 0.5. +Linux, AIX, DU, Tru64 send a break of +.I duration +milliseconds. +FreeBSD and NetBSD and HP-UX and MacOS ignore the value of +.IR duration . +Under Solaris and UnixWare, +.BR tcsendbreak () +with nonzero +.I duration +behaves like +.BR tcdrain (). +.\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0. +.\" libc4.7.6, libc5, glibc for unix: duration in ms. +.\" glibc for bsd: duration in us +.\" glibc for sunos4: ignore duration +.SH BUGS +.\" kernel 77e5bff1640432f28794a00800955e646dcd7455 +.\" glibc 573963e32ffac46d9891970ddebde2ac3212c5c0 +On the Alpha architecture before Linux 4.16 (and glibc before glibc 2.28), the +.B XTABS +value was different from +.B TAB3 +and it was ignored by the +.B N_TTY +line discipline code of the terminal driver as a result +(because as it wasn't part of the +.B TABDLY +mask). +.SH SEE ALSO +.BR reset (1), +.BR setterm (1), +.BR stty (1), +.BR tput (1), +.BR tset (1), +.BR tty (1), +.BR ioctl_console (2), +.BR ioctl_tty (2), +.BR cc_t (3type), +.BR speed_t (3type), +.BR tcflag_t (3type), +.BR setserial (8) diff --git a/man/man3/tfind.3 b/man/man3/tfind.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man/man3/tfind.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man/man3/tgamma.3 b/man/man3/tgamma.3 new file mode 100644 index 0000000..01d86a9 --- /dev/null +++ b/man/man3/tgamma.3 @@ -0,0 +1,216 @@ +'\" t +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on glibc infopages +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" Modified 2004-11-15, fixed error noted by Fabian Kreutz +.\" +.\" +.TH tgamma 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tgamma, tgammaf, tgammal \- true gamma function +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double tgamma(double " x ); +.BI "float tgammaf(float " x ); +.BI "long double tgammal(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tgamma (), +.BR tgammaf (), +.BR tgammal (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions calculate the Gamma function of +.IR x . +.P +The Gamma function is defined by +.P +.RS +Gamma(x) = integral from 0 to infinity of t\[ha](x\-1) e\[ha]\-t dt +.RE +.P +It is defined for every real number except for nonpositive integers. +For nonnegative integral +.I m +one has +.P +.RS +Gamma(m+1) = m! +.RE +.P +and, more generally, for all +.IR x : +.P +.RS +Gamma(x+1) = x * Gamma(x) +.RE +.P +Furthermore, the following is valid for all values of +.I x +outside the poles: +.P +.RS +Gamma(x) * Gamma(1 \- x) = PI / sin(PI * x) +.RE +.SH RETURN VALUE +On success, these functions return Gamma(x). +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is positive infinity, positive infinity is returned. +.P +If +.I x +is a negative integer, or is negative infinity, +a domain error occurs, +and a NaN is returned. +.P +If the result overflows, +a range error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the correct mathematical sign. +.P +If the result underflows, +a range error occurs, +and the functions return 0, with the correct mathematical sign. +.P +If +.I x +is \-0 or +0, +a pole error occurs, +and the functions return +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +respectively, with the same sign as the 0. +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is a negative integer, or negative infinity +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised (but see BUGS). +.TP +Pole error: \fIx\fP is +0 or \-0 +.I errno +is set to +.BR ERANGE . +A divide-by-zero floating-point exception +.RB ( FE_DIVBYZERO ) +is raised. +.TP +Range error: result overflow +.I errno +is set to +.BR ERANGE . +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.P +glibc also gives the following error which is not specified +in C99 or POSIX.1-2001. +.TP +Range error: result underflow +.\" e.g., tgamma(-172.5) on glibc 2.8/x86-32 +.\" .I errno +.\" is set to +.\" .BR ERANGE . +An underflow floating-point exception +.RB ( FE_UNDERFLOW ) +is raised, and +.I errno +is set to +.BR ERANGE . +.\" glibc (as at 2.8) also supports an inexact +.\" exception for various cases. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tgamma (), +.BR tgammaf (), +.BR tgammal () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH NOTES +This function had to be called "true gamma function" +since there is already a function +.BR gamma (3) +that returns something else (see +.BR gamma (3) +for details). +.SH BUGS +Before glibc 2.18, the glibc implementation of these functions did not set +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6809 +.I errno +to +.B EDOM +when +.I x +is negative infinity. +.P +Before glibc 2.19, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6810 +the glibc implementation of these functions did not set +.I errno +to +.B ERANGE +on an underflow range error. +.P +.\" +In glibc versions 2.3.3 and earlier, +an argument of +0 or \-0 incorrectly produced a domain error +.RI ( errno +set to +.B EDOM +and an +.B FE_INVALID +exception raised), rather than a pole error. +.SH SEE ALSO +.BR gamma (3), +.BR lgamma (3) diff --git a/man/man3/tgammaf.3 b/man/man3/tgammaf.3 new file mode 100644 index 0000000..4a0248a --- /dev/null +++ b/man/man3/tgammaf.3 @@ -0,0 +1 @@ +.so man3/tgamma.3 diff --git a/man/man3/tgammal.3 b/man/man3/tgammal.3 new file mode 100644 index 0000000..4a0248a --- /dev/null +++ b/man/man3/tgammal.3 @@ -0,0 +1 @@ +.so man3/tgamma.3 diff --git a/man/man3/timegm.3 b/man/man3/timegm.3 new file mode 100644 index 0000000..7395d99 --- /dev/null +++ b/man/man3/timegm.3 @@ -0,0 +1,92 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH timegm 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timegm, timelocal \- inverses of gmtime and localtime +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] time_t timelocal(struct tm *" tm ); +.BI "time_t timegm(struct tm *" tm ); +.P +.fi +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR timelocal (), +.BR timegm (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR timelocal () +and +.BR timegm () +are the inverses of +.BR localtime (3) +and +.BR gmtime (3). +Both functions take a broken-down time and convert it to calendar time +(seconds since the Epoch, 1970-01-01 00:00:00 +0000, UTC). +The difference between the two functions is that +.BR timelocal () +takes the local timezone into account when doing the conversion, while +.BR timegm () +takes the input value to be Coordinated Universal Time (UTC). +.SH RETURN VALUE +On success, +these functions return the calendar time (seconds since the Epoch), +expressed as a value of type +.IR time_t . +On error, they return the value +.I (time_t)\ \-1 +and set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EOVERFLOW +The result cannot be represented. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR timelocal (), +.BR timegm () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +BSD. +.SH HISTORY +GNU, BSD. +.P +The +.BR timelocal () +function is equivalent to the POSIX standard function +.BR mktime (3). +There is no reason to ever use it. +.SH SEE ALSO +.BR gmtime (3), +.BR localtime (3), +.BR mktime (3), +.BR tzset (3) diff --git a/man/man3/timelocal.3 b/man/man3/timelocal.3 new file mode 100644 index 0000000..45d4c09 --- /dev/null +++ b/man/man3/timelocal.3 @@ -0,0 +1 @@ +.so man3/timegm.3 diff --git a/man/man3/timeradd.3 b/man/man3/timeradd.3 new file mode 100644 index 0000000..89002ec --- /dev/null +++ b/man/man3/timeradd.3 @@ -0,0 +1,143 @@ +.\" Copyright (c) 2007 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-07-31, mtk, Created +.\" +.TH timeradd 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timeradd, timersub, timercmp, timerclear, timerisset \- timeval operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void timeradd(struct timeval *" a ", struct timeval *" b , +.BI " struct timeval *" res ); +.BI "void timersub(struct timeval *" a ", struct timeval *" b , +.BI " struct timeval *" res ); +.P +.BI "void timerclear(struct timeval *" tvp ); +.BI "int timerisset(struct timeval *" tvp ); +.P +.BI "int timercmp(struct timeval *" a ", struct timeval *" b ", " CMP ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The macros are provided to operate on +.I timeval +structures, defined in +.I +as: +.P +.in +4n +.EX +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* microseconds */ +}; +.EE +.in +.P +.BR timeradd () +adds the time values in +.I a +and +.IR b , +and places the sum in the +.I timeval +pointed to by +.IR res . +The result is normalized such that +.I res\->tv_usec +has a value in the range 0 to 999,999. +.P +.BR timersub () +subtracts the time value in +.I b +from the time value in +.IR a , +and places the result in the +.I timeval +pointed to by +.IR res . +The result is normalized such that +.I res\->tv_usec +has a value in the range 0 to 999,999. +.P +.BR timerclear () +zeros out the +.I timeval +structure pointed to by +.IR tvp , +so that it represents the Epoch: 1970-01-01 00:00:00 +0000 (UTC). +.P +.BR timerisset () +returns true (nonzero) if either field of the +.I timeval +structure pointed to by +.I tvp +contains a nonzero value. +.P +.BR timercmp () +compares the timer values in +.I a +and +.I b +using the comparison operator +.IR CMP , +and returns true (nonzero) or false (0) depending on +the result of the comparison. +Some systems (but not Linux/glibc), +have a broken +.BR timercmp () +implementation, +.\" HP-UX, Tru64, Irix have a definition like: +.\"#define timercmp(tvp, uvp, cmp) \ +.\" ((tvp)->tv_sec cmp (uvp)->tv_sec || \ +.\" (tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec) +in which +.I CMP +of +.IR >= , +.IR <= , +and +.I == +do not work; +portable applications can instead use +.P +.in +4n +.EX +!timercmp(..., <) +!timercmp(..., >) +!timercmp(..., !=) +.EE +.in +.SH RETURN VALUE +.BR timerisset () +and +.BR timercmp () +return true (nonzero) or false (0). +.SH ERRORS +No errors are defined. +.SH STANDARDS +None. +.SH HISTORY +BSD. +.SH SEE ALSO +.BR gettimeofday (2), +.BR time (7) diff --git a/man/man3/timerclear.3 b/man/man3/timerclear.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man/man3/timerclear.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man/man3/timercmp.3 b/man/man3/timercmp.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man/man3/timercmp.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man/man3/timerisset.3 b/man/man3/timerisset.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man/man3/timerisset.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man/man3/timersub.3 b/man/man3/timersub.3 new file mode 100644 index 0000000..8e977c9 --- /dev/null +++ b/man/man3/timersub.3 @@ -0,0 +1 @@ +.so man3/timeradd.3 diff --git a/man/man3/timezone.3 b/man/man3/timezone.3 new file mode 100644 index 0000000..8090763 --- /dev/null +++ b/man/man3/timezone.3 @@ -0,0 +1 @@ +.so man3/tzset.3 diff --git a/man/man3/tmpfile.3 b/man/man3/tmpfile.3 new file mode 100644 index 0000000..21d934b --- /dev/null +++ b/man/man3/tmpfile.3 @@ -0,0 +1,103 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 17:46:57 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-11-17, aeb +.TH tmpfile 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tmpfile \- create a temporary file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B FILE *tmpfile(void); +.fi +.SH DESCRIPTION +The +.BR tmpfile () +function opens a unique temporary file +in binary read/write (w+b) mode. +The file will be automatically deleted when it is closed or the +program terminates. +.SH RETURN VALUE +The +.BR tmpfile () +function returns a stream descriptor, or NULL if +a unique filename cannot be generated or the unique file cannot be +opened. +In the latter case, +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Search permission denied for directory in file's path prefix. +.TP +.B EEXIST +Unable to generate a unique filename. +.TP +.B EINTR +The call was interrupted by a signal; see +.BR signal (7). +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOSPC +There was no room in the directory to add the new filename. +.TP +.B EROFS +Read-only filesystem. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tmpfile () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The standard does not specify the directory that +.BR tmpfile () +will use. +glibc will try the path prefix +.I P_tmpdir +defined +in +.IR , +and if that fails, then the directory +.IR /tmp . +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD, SUSv2. +.SH NOTES +POSIX.1-2001 specifies: +an error message may be written to +.I stdout +if the stream +cannot be opened. +.SH SEE ALSO +.BR exit (3), +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpnam (3) diff --git a/man/man3/tmpnam.3 b/man/man3/tmpnam.3 new file mode 100644 index 0000000..25161d6 --- /dev/null +++ b/man/man3/tmpnam.3 @@ -0,0 +1,168 @@ +'\" t +.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2003-11-15, aeb, added tmpnam_r +.\" +.TH tmpnam 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tmpnam, tmpnam_r \- create a name for a temporary file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] char *tmpnam(char *" s ); +.BI "[[deprecated]] char *tmpnam_r(char *" s ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tmpnam_r () +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + Up to and including glibc 2.19: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +.B Note: +avoid using these functions; use +.BR mkstemp (3) +or +.BR tmpfile (3) +instead. +.P +The +.BR tmpnam () +function returns a pointer to a string that is a valid filename, +and such that a file with this name did not exist at some point +in time, so that naive programmers may think it +a suitable name for a temporary file. +If the argument +.I s +is NULL, this name is generated in an internal static buffer +and may be overwritten by the next call to +.BR tmpnam (). +If +.I s +is not NULL, the name is copied to the character array (of length +at least +.IR L_tmpnam ) +pointed to by +.I s +and the value +.I s +is returned in case of success. +.P +The created pathname has a directory prefix +.IR P_tmpdir . +(Both +.I L_tmpnam +and +.I P_tmpdir +are defined in +.IR , +just like the +.B TMP_MAX +mentioned below.) +.P +The +.BR tmpnam_r () +function performs the same task as +.BR tmpnam (), +but returns NULL (to indicate an error) if +.I s +is NULL. +.SH RETURN VALUE +These functions return a pointer to a unique temporary +filename, or NULL if a unique name cannot be generated. +.SH ERRORS +No errors are defined. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tmpnam () +T} Thread safety MT-Unsafe race:tmpnam/!s +T{ +.na +.nh +.BR tmpnam_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR tmpnam () +C11, POSIX.1-2008. +.TP +.BR tmpnam_r () +None. +.SH HISTORY +.TP +.BR tmpnam () +SVr4, 4.3BSD, C89, POSIX.1-2001. +Obsolete in POSIX.1-2008. +.TP +.BR tmpnam_r () +Solaris. +.SH NOTES +The +.BR tmpnam () +function generates a different string each time it is called, +up to +.B TMP_MAX +times. +If it is called more than +.B TMP_MAX +times, +the behavior is implementation defined. +.P +Although these functions generate names that are difficult to guess, +it is nevertheless possible that between the time that +the pathname is returned and the time that the program opens it, +another program might create that pathname using +.BR open (2), +or create it as a symbolic link. +This can lead to security holes. +To avoid such possibilities, use the +.BR open (2) +.B O_EXCL +flag to open the pathname. +Or better yet, use +.BR mkstemp (3) +or +.BR tmpfile (3). +.P +Portable applications that use threads cannot call +.BR tmpnam () +with a NULL argument if either +.B _POSIX_THREADS +or +.B _POSIX_THREAD_SAFE_FUNCTIONS +is defined. +.SH BUGS +Never use these functions. +Use +.BR mkstemp (3) +or +.BR tmpfile (3) +instead. +.SH SEE ALSO +.BR mkstemp (3), +.BR mktemp (3), +.BR tempnam (3), +.BR tmpfile (3) diff --git a/man/man3/tmpnam_r.3 b/man/man3/tmpnam_r.3 new file mode 100644 index 0000000..c1bd6dc --- /dev/null +++ b/man/man3/tmpnam_r.3 @@ -0,0 +1 @@ +.so man3/tmpnam.3 diff --git a/man/man3/toascii.3 b/man/man3/toascii.3 new file mode 100644 index 0000000..e2e574a --- /dev/null +++ b/man/man3/toascii.3 @@ -0,0 +1,68 @@ +'\" t +.\" Copyright (c) 1995 by Jim Van Zandt +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Added BUGS section, aeb, 950919 +.\" +.TH toascii 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +toascii \- convert character to ASCII +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] int toascii(int " c ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR toascii (): +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +.BR toascii () +converts +.I c +to a 7-bit +.I "unsigned char" +value that fits into the ASCII character set, by clearing the +high-order bits. +.SH RETURN VALUE +The value returned is that of the converted character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR toascii () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, BSD, POSIX.1-2001. +Obsolete in POSIX.1-2008, +noting that it cannot be used portably in a localized application. +.SH BUGS +Many people will be unhappy if you use this function. +This function will convert accented letters into random characters. +.SH SEE ALSO +.BR isascii (3), +.BR tolower (3), +.BR toupper (3) diff --git a/man/man3/tolower.3 b/man/man3/tolower.3 new file mode 100644 index 0000000..033f16e --- /dev/null +++ b/man/man3/tolower.3 @@ -0,0 +1 @@ +.so man3/toupper.3 diff --git a/man/man3/tolower_l.3 b/man/man3/tolower_l.3 new file mode 100644 index 0000000..033f16e --- /dev/null +++ b/man/man3/tolower_l.3 @@ -0,0 +1 @@ +.so man3/toupper.3 diff --git a/man/man3/toupper.3 b/man/man3/toupper.3 new file mode 100644 index 0000000..c2ab04a --- /dev/null +++ b/man/man3/toupper.3 @@ -0,0 +1,185 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 17:45:39 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2000-02-13 by Nicolás Lichtmaier +.TH toupper 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int toupper(int " "c" ); +.BI "int tolower(int " "c" ); +.P +.BI "int toupper_l(int " c ", locale_t " locale ); +.BI "int tolower_l(int " c ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR toupper_l (), +.BR tolower_l (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +These functions convert lowercase letters to uppercase, and vice versa. +.P +If +.I c +is a lowercase letter, +.BR toupper () +returns its uppercase equivalent, +if an uppercase representation exists in the current locale. +Otherwise, it returns +.IR c . +The +.BR toupper_l () +function performs the same task, +but uses the locale referred to by the locale handle +.IR locale . +.P +If +.I c +is an uppercase letter, +.BR tolower () +returns its lowercase equivalent, +if a lowercase representation exists in the current locale. +Otherwise, it returns +.IR c . +The +.BR tolower_l () +function performs the same task, +but uses the locale referred to by the locale handle +.IR locale . +.P +If +.I c +is neither an +.I "unsigned char" +value nor +.BR EOF , +the behavior of these functions +is undefined. +.P +The behavior of +.BR toupper_l () +and +.BR tolower_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.SH RETURN VALUE +The value returned is that of the converted letter, or +.I c +if the conversion was not possible. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR toupper (), +.BR tolower (), +.BR toupper_l (), +.BR tolower_l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR toupper () +.TQ +.BR tolower () +C11, POSIX.1-2008. +.TP +.BR toupper_l () +.TQ +.BR tolower_l () +POSIX.1-2008. +.SH HISTORY +.TP +.BR toupper () +.TQ +.BR tolower () +C89, 4.3BSD, POSIX.1-2001. +.TP +.BR toupper_l () +.TQ +.BR tolower_l () +POSIX.1-2008. +.SH NOTES +The standards require that the argument +.I c +for these functions is either +.B EOF +or a value that is representable in the type +.IR "unsigned char" . +If the argument +.I c +is of type +.IR char , +it must be cast to +.IR "unsigned char" , +as in the following example: +.P +.in +4n +.EX +char c; +\&... +res = toupper((unsigned char) c); +.EE +.in +.P +This is necessary because +.I char +may be the equivalent +.IR "signed char" , +in which case a byte where the top bit is set would be sign extended when +converting to +.IR int , +yielding a value that is outside the range of +.IR "unsigned char" . +.P +The details of what constitutes an uppercase or lowercase letter depend +on the locale. +For example, the default +.B \[dq]C\[dq] +locale does not know about umlauts, so no conversion is done for them. +.P +In some non-English locales, there are lowercase letters with no +corresponding uppercase equivalent; +.\" FIXME One day the statement about "sharp s" needs to be reworked, +.\" since there is nowadays a capital "sharp s" that has a codepoint +.\" in Unicode 5.0; see https://en.wikipedia.org/wiki/Capital_%E1%BA%9E +the German sharp s is one example. +.SH SEE ALSO +.BR isalpha (3), +.BR newlocale (3), +.BR setlocale (3), +.BR towlower (3), +.BR towupper (3), +.BR uselocale (3), +.BR locale (7) diff --git a/man/man3/toupper_l.3 b/man/man3/toupper_l.3 new file mode 100644 index 0000000..033f16e --- /dev/null +++ b/man/man3/toupper_l.3 @@ -0,0 +1 @@ +.so man3/toupper.3 diff --git a/man/man3/towctrans.3 b/man/man3/towctrans.3 new file mode 100644 index 0000000..e18baa6 --- /dev/null +++ b/man/man3/towctrans.3 @@ -0,0 +1,82 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH towctrans 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +towctrans \- wide-character transliteration +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wint_t towctrans(wint_t " wc ", wctrans_t " desc ); +.fi +.SH DESCRIPTION +If +.I wc +is a wide character, then the +.BR towctrans () +function +translates it according to the transliteration descriptor +.IR desc . +If +.I wc +is +.BR WEOF , +.B WEOF +is returned. +.P +.I desc +must be a transliteration descriptor returned by +the +.BR wctrans (3) +function. +.SH RETURN VALUE +The +.BR towctrans () +function returns the translated wide character, +or +.B WEOF +if +.I wc +is +.BR WEOF . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR towctrans () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR towctrans () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR towlower (3), +.BR towupper (3), +.BR wctrans (3) diff --git a/man/man3/towlower.3 b/man/man3/towlower.3 new file mode 100644 index 0000000..a136a59 --- /dev/null +++ b/man/man3/towlower.3 @@ -0,0 +1,131 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" and Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH towlower 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +towlower, towlower_l \- convert a wide character to lowercase +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wint_t towlower(wint_t " wc ); +.BI "wint_t towlower_l(wint_t " wc ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR towlower_l (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR towlower () +function is the wide-character equivalent of the +.BR tolower (3) +function. +If +.I wc +is an uppercase wide character, +and there exists a lowercase equivalent in the current locale, +it returns the lowercase equivalent of +.IR wc . +In all other cases, +.I wc +is returned unchanged. +.P +The +.BR towlower_l () +function performs the same task, +but performs the conversion based on the character type information in +the locale specified by +.IR locale . +The behavior of +.BR towlower_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.P +The argument +.I wc +must be representable as a +.I wchar_t +and be a valid character in the locale or be the value +.BR WEOF . +.SH RETURN VALUE +If +.I wc +was convertible to lowercase, +.BR towlower () +returns its lowercase equivalent; +otherwise it returns +.IR wc . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR towlower () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR towlower_l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR towlower () +C11, POSIX.1-2008 (XSI). +.TP +.BR towlower_l () +POSIX.1-2008. +.SH STANDARDS +.TP +.BR towlower () +C99, POSIX.1-2001 (XSI). +Obsolete in POSIX.1-2008 (XSI). +.TP +.BR towlower_l () +glibc 2.3. +POSIX.1-2008. +.SH NOTES +The behavior of these functions depends on the +.B LC_CTYPE +category of the locale. +.P +These functions are not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower, and title case. +.SH SEE ALSO +.BR iswlower (3), +.BR towctrans (3), +.BR towupper (3), +.BR locale (7) diff --git a/man/man3/towlower_l.3 b/man/man3/towlower_l.3 new file mode 100644 index 0000000..6135f86 --- /dev/null +++ b/man/man3/towlower_l.3 @@ -0,0 +1 @@ +.so man3/towlower.3 diff --git a/man/man3/towupper.3 b/man/man3/towupper.3 new file mode 100644 index 0000000..5d4fbf4 --- /dev/null +++ b/man/man3/towupper.3 @@ -0,0 +1,130 @@ +'\" t +.\" and Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH towupper 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +towupper, towupper_l \- convert a wide character to uppercase +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wint_t towupper(wint_t " wc ); +.BI "wint_t towupper_l(wint_t " wc ", locale_t " locale ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR towupper_l (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR towupper () +function is the wide-character equivalent of the +.BR toupper (3) +function. +If +.I wc +is a lowercase wide character, +and there exists an uppercase equivalent in the current locale, +it returns the uppercase equivalent of +.IR wc . +In all other cases, +.I wc +is returned unchanged. +.P +The +.BR towupper_l () +function performs the same task, +but performs the conversion based on the character type information in +the locale specified by +.IR locale . +The behavior of +.BR towupper_l () +is undefined if +.I locale +is the special locale object +.B LC_GLOBAL_LOCALE +(see +.BR duplocale (3)) +or is not a valid locale object handle. +.P +The argument +.I wc +must be representable as a +.I wchar_t +and be a valid character in the locale or be the value +.BR WEOF . +.SH RETURN VALUE +If +.I wc +was convertible to uppercase, +.BR towupper () +returns its uppercase equivalent; +otherwise it returns +.IR wc . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR towupper () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR towupper_l () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR towupper () +C11, POSIX.1-2008 (XSI). +.TP +.BR towupper_l () +POSIX.1-2008. +.SH HISTORY +.TP +.BR towupper () +C99, POSIX.1-2001 (XSI). +Obsolete in POSIX.1-2008 (XSI). +.TP +.BR towupper_l () +POSIX.1-2008. +glibc 2.3. +.SH NOTES +The behavior of these functions depends on the +.B LC_CTYPE +category of the locale. +.P +These functions are not very appropriate for dealing with Unicode characters, +because Unicode knows about three cases: upper, lower, and title case. +.SH SEE ALSO +.BR iswupper (3), +.BR towctrans (3), +.BR towlower (3), +.BR locale (7) diff --git a/man/man3/towupper_l.3 b/man/man3/towupper_l.3 new file mode 100644 index 0000000..a0b0e89 --- /dev/null +++ b/man/man3/towupper_l.3 @@ -0,0 +1 @@ +.so man3/towupper.3 diff --git a/man/man3/trunc.3 b/man/man3/trunc.3 new file mode 100644 index 0000000..17e5f14 --- /dev/null +++ b/man/man3/trunc.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH trunc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +trunc, truncf, truncl \- round to integer, toward zero +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double trunc(double " x ); +.BI "float truncf(float " x ); +.BI "long double truncl(long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR trunc (), +.BR truncf (), +.BR truncl (): +.nf + _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +These functions round +.I x +to the nearest integer value that is not larger in magnitude than +.IR x . +.SH RETURN VALUE +These functions return the rounded integer value, in floating format. +.P +If +.I x +is integral, infinite, or NaN, +.I x +itself is returned. +.SH ERRORS +No errors occur. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR trunc (), +.BR truncf (), +.BR truncl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +glibc 2.1. +C99, POSIX.1-2001. +.SH NOTES +The integral value returned by these functions may be too large +to store in an integer type +.RI ( int , +.IR long , +etc.). +To avoid an overflow, which will produce undefined results, +an application should perform a range check on the returned value +before assigning it to an integer type. +.SH SEE ALSO +.BR ceil (3), +.BR floor (3), +.BR lrint (3), +.BR nearbyint (3), +.BR rint (3), +.BR round (3) diff --git a/man/man3/truncf.3 b/man/man3/truncf.3 new file mode 100644 index 0000000..b859341 --- /dev/null +++ b/man/man3/truncf.3 @@ -0,0 +1 @@ +.so man3/trunc.3 diff --git a/man/man3/truncl.3 b/man/man3/truncl.3 new file mode 100644 index 0000000..b859341 --- /dev/null +++ b/man/man3/truncl.3 @@ -0,0 +1 @@ +.so man3/trunc.3 diff --git a/man/man3/tsearch.3 b/man/man3/tsearch.3 new file mode 100644 index 0000000..c4aaf18 --- /dev/null +++ b/man/man3/tsearch.3 @@ -0,0 +1,356 @@ +'\" t +.\" Copyright 1995 by Jim Van Zandt +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tsearch 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tsearch, tfind, tdelete, twalk, twalk_r, tdestroy \- manage a binary search tree +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B typedef enum { preorder, postorder, endorder, leaf } VISIT; +.P +.BI "void *tsearch(const void *" key ", void **" rootp , +.BI " int (*" compar ")(const void *, const void *));" +.BI "void *tfind(const void *" key ", void *const *" rootp , +.BI " int (*" compar ")(const void *, const void *));" +.BI "void *tdelete(const void *restrict " key ", void **restrict " rootp , +.BI " int (*" compar ")(const void *, const void *));" +.BI "void twalk(const void *" root , +.BI " void (*" action ")(const void *" nodep ", VISIT " which , +.BI " int " depth )); +.P +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "void twalk_r(const void *" root , +.BI " void (*" action ")(const void *" nodep ", VISIT " which , +.BI " void *" closure ), +.BI " void *" closure ); +.BI "void tdestroy(void *" root ", void (*" free_node ")(void *" nodep )); +.fi +.SH DESCRIPTION +.BR tsearch (), +.BR tfind (), +.BR twalk (), +and +.BR tdelete () +manage a +binary search tree. +They are generalized from Knuth (6.2.2) Algorithm T. +The first field in each node of the tree is a pointer to the +corresponding data item. +(The calling program must store the actual data.) +.I compar +points to a comparison routine, which takes +pointers to two items. +It should return an integer which is negative, +zero, or positive, depending on whether the first item is less than, +equal to, or greater than the second. +.P +.BR tsearch () +searches the tree for an item. +.I key +points to the item to be searched for. +.I rootp +points to a variable which points to the root of the tree. +If the tree is empty, +then the variable that +.I rootp +points to should be set to NULL. +If the item is found in the tree, then +.BR tsearch () +returns a pointer +to the corresponding tree node. +(In other words, +.BR tsearch () +returns a pointer to a pointer to the data item.) +If the item is not found, then +.BR tsearch () +adds it, and returns a +pointer to the corresponding tree node. +.P +.BR tfind () +is like +.BR tsearch (), +except that if the item is not +found, then +.BR tfind () +returns NULL. +.P +.BR tdelete () +deletes an item from the tree. +Its arguments are the same as for +.BR tsearch (). +.P +.BR twalk () +performs depth-first, left-to-right traversal of a binary +tree. +.I root +points to the starting node for the traversal. +If that node is not the root, then only part of the tree will be visited. +.BR twalk () +calls the user function +.I action +each time a node is +visited (that is, three times for an internal node, and once for a +leaf). +.IR action , +in turn, takes three arguments. +The first argument is a pointer to the node being visited. +The structure of the node is unspecified, +but it is possible to cast the pointer to a pointer-to-pointer-to-element +in order to access the element stored within the node. +The application must not modify the structure pointed to by this argument. +The second argument is an integer which +takes one of the values +.BR preorder , +.BR postorder , +or +.B endorder +depending on whether this is the first, second, or +third visit to the internal node, +or the value +.B leaf +if this is the single visit to a leaf node. +(These symbols are defined in +.IR .) +The third argument is the depth of the node; +the root node has depth zero. +.P +(More commonly, +.BR preorder , +.BR postorder , +and +.B endorder +are known as +.BR preorder , +.BR inorder , +and +.BR postorder : +before visiting the children, after the first and before the second, +and after visiting the children. +Thus, the choice of name +.B post\%order +is rather confusing.) +.P +.BR twalk_r () +is similar to +.BR twalk (), +but instead of the +.I depth +argument, the +.I closure +argument pointer is passed to each invocation of the action callback, +unchanged. +This pointer can be used to pass information to and from +the callback function in a thread-safe fashion, without resorting +to global variables. +.P +.BR tdestroy () +removes the whole tree pointed to by +.IR root , +freeing all resources allocated by the +.BR tsearch () +function. +For the data in each tree node the function +.I free_node +is called. +The pointer to the data is passed as the argument to the function. +If no such work is necessary, +.I free_node +must point to a function +doing nothing. +.SH RETURN VALUE +.BR tsearch () +returns a pointer to a matching node in the tree, or to +the newly added node, or NULL if there was insufficient memory +to add the item. +.BR tfind () +returns a pointer to the node, or +NULL if no match is found. +If there are multiple items that match the key, +the item whose node is returned is unspecified. +.P +.BR tdelete () +returns a pointer to the parent of the node deleted, or +NULL if the item was not found. +If the deleted node was the root node, +.BR tdelete () +returns a dangling pointer that must not be accessed. +.P +.BR tsearch (), +.BR tfind (), +and +.BR tdelete () +also +return NULL if +.I rootp +was NULL on entry. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tsearch (), +.BR tfind (), +.BR tdelete () +T} Thread safety MT-Safe race:rootp +T{ +.na +.nh +.BR twalk () +T} Thread safety MT-Safe race:root +T{ +.na +.nh +.BR twalk_r () +T} Thread safety MT-Safe race:root +T{ +.na +.nh +.BR tdestroy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR tsearch () +.TQ +.BR tfind () +.TQ +.BR tdelete () +.TQ +.BR twalk () +POSIX.1-2008. +.TP +.BR tdestroy () +.TQ +.BR twalk_r () +GNU. +.SH HISTORY +.TP +.BR tsearch () +.TQ +.BR tfind () +.TQ +.BR tdelete () +.TQ +.BR twalk () +POSIX.1-2001, POSIX.1-2008, SVr4. +.TP +.BR twalk_r () +glibc 2.30. +.SH NOTES +.BR twalk () +takes a pointer to the root, while the other functions +take a pointer to a variable which points to the root. +.P +.BR tdelete () +frees the memory required for the node in the tree. +The user is responsible for freeing the memory for the corresponding +data. +.P +The example program depends on the fact that +.BR twalk () +makes no +further reference to a node after calling the user function with +argument "endorder" or "leaf". +This works with the GNU library +implementation, but is not in the System V documentation. +.SH EXAMPLES +The following program inserts twelve random numbers into a binary +tree, where duplicate numbers are collapsed, then prints the numbers +in order. +.P +.\" SRC BEGIN (tsearch.c) +.EX +#define _GNU_SOURCE /* Expose declaration of tdestroy() */ +#include +#include +#include +#include +#include +\& +static void *root = NULL; +\& +static void * +xmalloc(size_t n) +{ + void *p; +\& + p = malloc(n); + if (p) + return p; + fprintf(stderr, "insufficient memory\en"); + exit(EXIT_FAILURE); +} +\& +static int +compare(const void *pa, const void *pb) +{ + if (*(int *) pa < *(int *) pb) + return \-1; + if (*(int *) pa > *(int *) pb) + return 1; + return 0; +} +\& +static void +action(const void *nodep, VISIT which, int depth) +{ + int *datap; +\& + switch (which) { + case preorder: + break; + case postorder: + datap = *(int **) nodep; + printf("%6d\en", *datap); + break; + case endorder: + break; + case leaf: + datap = *(int **) nodep; + printf("%6d\en", *datap); + break; + } +} +\& +int +main(void) +{ + int *ptr; + int **val; +\& + srand(time(NULL)); + for (unsigned int i = 0; i < 12; i++) { + ptr = xmalloc(sizeof(*ptr)); + *ptr = rand() & 0xff; + val = tsearch(ptr, &root, compare); + if (val == NULL) + exit(EXIT_FAILURE); + if (*val != ptr) + free(ptr); + } + twalk(root, action); + tdestroy(root, free); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR bsearch (3), +.BR hsearch (3), +.BR lsearch (3), +.BR qsort (3) diff --git a/man/man3/ttyname.3 b/man/man3/ttyname.3 new file mode 100644 index 0000000..92ee3be --- /dev/null +++ b/man/man3/ttyname.3 @@ -0,0 +1,111 @@ +'\" t +.\" Copyright (c) 1995 Jim Van Zandt +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 2001-12-13, Martin Schulze +.\" Added ttyname_r, aeb, 2002-07-20 +.\" +.TH ttyname 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ttyname, ttyname_r \- return name of a terminal +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "char *ttyname(int " fd ); +.BI "int ttyname_r(int " fd ", char " buf [. buflen "], size_t " buflen ); +.fi +.SH DESCRIPTION +The function +.BR ttyname () +returns a pointer to the null-terminated pathname of the terminal device +that is open on the file descriptor \fIfd\fP, or NULL on error +(for example, if \fIfd\fP is not connected to a terminal). +The return value may point to static data, possibly overwritten by the +next call. +The function +.BR ttyname_r () +stores this pathname in the buffer +.I buf +of length +.IR buflen . +.SH RETURN VALUE +The function +.BR ttyname () +returns a pointer to a pathname on success. +On error, NULL is returned, and +.I errno +is set to indicate the error. +The function +.BR ttyname_r () +returns 0 on success, and an error number upon error. +.SH ERRORS +.TP +.B EBADF +Bad file descriptor. +.TP +.\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23 +.B ENODEV +.I fd +refers to a slave pseudoterminal device +but the corresponding pathname could not be found (see NOTES). +.TP +.B ENOTTY +.I fd +does not refer to a terminal device. +.TP +.B ERANGE +.RB ( ttyname_r ()) +.I buflen +was too small to allow storing the pathname. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ttyname () +T} Thread safety MT-Unsafe race:ttyname +T{ +.na +.nh +.BR ttyname_r () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, 4.2BSD. +.SH NOTES +A process that keeps a file descriptor that refers to a +.BR pts (4) +device open when switching to another mount namespace that uses a different +.I /dev/ptmx +instance may still accidentally find that a device path of the same name +for that file descriptor exists. +However, this device path refers to a different device and thus +can't be used to access the device that the file descriptor refers to. +Calling +.BR ttyname () +or +.BR ttyname_r () +on the file descriptor in the new mount namespace will cause these +functions to return NULL and set +.I errno +to +.BR ENODEV . +.SH SEE ALSO +.BR tty (1), +.BR fstat (2), +.BR ctermid (3), +.BR isatty (3), +.BR pts (4) diff --git a/man/man3/ttyname_r.3 b/man/man3/ttyname_r.3 new file mode 100644 index 0000000..aaa18ee --- /dev/null +++ b/man/man3/ttyname_r.3 @@ -0,0 +1 @@ +.so man3/ttyname.3 diff --git a/man/man3/ttyslot.3 b/man/man3/ttyslot.3 new file mode 100644 index 0000000..0548ea4 --- /dev/null +++ b/man/man3/ttyslot.3 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright (C) 2002 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This replaces an earlier man page written by Walter Harms +.\" . +.\" +.TH ttyslot 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ttyslot \- find the slot of the current user's terminal in some file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* See NOTES */" +.P +.B "int ttyslot(void);" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ttyslot (): +.nf + Since glibc 2.24: + _DEFAULT_SOURCE + From glibc 2.20 to glibc 2.23: + _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) + glibc 2.19 and earlier: + _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.fi +.SH DESCRIPTION +The legacy function +.BR ttyslot () +returns the index of the current user's entry in some file. +.P +Now "What file?" you ask. +Well, let's first look at some history. +.SS Ancient history +There used to be a file +.I /etc/ttys +in UNIX\ V6, that was read by the +.BR init (1) +program to find out what to do with each terminal line. +Each line consisted of three characters. +The first character was either \[aq]0\[aq] or \[aq]1\[aq], +where \[aq]0\[aq] meant "ignore". +The second character denoted the terminal: \[aq]8\[aq] stood for "/dev/tty8". +The third character was an argument to +.BR getty (8) +indicating the sequence of line speeds to try (\[aq]\-\[aq] was: start trying +110 baud). +Thus a typical line was "18\-". +A hang on some line was solved by changing the \[aq]1\[aq] to a \[aq]0\[aq], +signaling init, changing back again, and signaling init again. +.P +In UNIX\ V7 the format was changed: here the second character +was the argument to +.BR getty (8) +indicating the sequence of line speeds to try (\[aq]0\[aq] was: cycle through +300-1200-150-110 baud; \[aq]4\[aq] was for the on-line console DECwriter) +while the rest of the line contained the name of the tty. +Thus a typical line was "14console". +.P +Later systems have more elaborate syntax. +System V-like systems have +.I /etc/inittab +instead. +.SS Ancient history (2) +On the other hand, there is the file +.I /etc/utmp +listing the people currently logged in. +It is maintained by +.BR login (1). +It has a fixed size, and the appropriate index in the file was +determined by +.BR login (1) +using the +.BR ttyslot () +call to find the number of the line in +.I /etc/ttys +(counting from 1). +.SS The semantics of ttyslot +Thus, the function +.BR ttyslot () +returns the index of the controlling terminal of the calling process +in the file +.IR /etc/ttys , +and that is (usually) the same as the index of the entry for the +current user in the file +.IR /etc/utmp . +BSD still has the +.I /etc/ttys +file, but System V-like systems do not, and hence cannot refer to it. +Thus, on such systems the documentation says that +.BR ttyslot () +returns the current user's index in the user accounting data base. +.SH RETURN VALUE +If successful, this function returns the slot number. +On error (e.g., if none of the file descriptors 0, 1, or 2 is +associated with a terminal that occurs in this data base) +it returns 0 on UNIX\ V6 and V7 and BSD-like systems, +but \-1 on System V-like systems. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ttyslot () +T} Thread safety MT-Unsafe +.TE +.SH VERSIONS +The utmp file is found in various places on various systems, such as +.IR /etc/utmp , +.IR /var/adm/utmp , +.IR /var/run/utmp . +.SH STANDARDS +None. +.SH HISTORY +SUSv1; marked as LEGACY in SUSv2; removed in POSIX.1-2001. +SUSv2 requires \-1 on error. +.P +The glibc2 implementation of this function reads the file +.BR _PATH_TTYS , +defined in +.I +as "/etc/ttys". +It returns 0 on error. +Since Linux systems do not usually have "/etc/ttys", it will +always return 0. +.P +On BSD-like systems and Linux, the declaration of +.BR ttyslot () +is provided by +.IR . +On System V-like systems, the declaration is provided by +.IR . +Since glibc 2.24, +.I +also provides the declaration with the following +feature test macro definitions: +.P +.in +4n +.EX +(_XOPEN_SOURCE >= 500 || + (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)) + && ! (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600) +.EE +.in +.P +Minix also has +.IR fttyslot ( fd ). +.\" .SH HISTORY +.\" .BR ttyslot () +.\" appeared in UNIX V7. +.SH SEE ALSO +.BR getttyent (3), +.BR ttyname (3), +.BR utmp (5) diff --git a/man/man3/twalk.3 b/man/man3/twalk.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man/man3/twalk.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man/man3/twalk_r.3 b/man/man3/twalk_r.3 new file mode 100644 index 0000000..72f1251 --- /dev/null +++ b/man/man3/twalk_r.3 @@ -0,0 +1 @@ +.so man3/tsearch.3 diff --git a/man/man3/tzname.3 b/man/man3/tzname.3 new file mode 100644 index 0000000..8090763 --- /dev/null +++ b/man/man3/tzname.3 @@ -0,0 +1 @@ +.so man3/tzset.3 diff --git a/man/man3/tzset.3 b/man/man3/tzset.3 new file mode 100644 index 0000000..bb7ad9f --- /dev/null +++ b/man/man3/tzset.3 @@ -0,0 +1,244 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 11:01:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-11-13, aeb +.\" Modified 2004-12-01 mtk and Martin Schulze +.\" +.TH tzset 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tzset, tzname, timezone, daylight \- initialize time conversion information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B void tzset(void); +.P +.BI "extern char *" tzname [2]; +.BI "extern long " timezone ; +.BI "extern int " daylight ; +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR tzset (): +.nf + _POSIX_C_SOURCE +.fi +.P +.IR tzname : +.nf + _POSIX_C_SOURCE +.fi +.P +.IR timezone , +.IR daylight : +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR tzset () +function initializes the \fItzname\fP variable from the +.B TZ +environment variable. +This function is automatically called by the +other time conversion functions that depend on the timezone. +In a System-V-like environment, it will also set the variables \fItimezone\fP +(seconds West of UTC) and \fIdaylight\fP (to 0 if this timezone does not +have any daylight saving time rules, or to nonzero if there is a time, +past, present, or future when daylight saving time applies). +.P +If the +.B TZ +variable does not appear in the environment, the system timezone is used. +The system timezone is configured by copying, or linking, a file in the +.BR tzfile (5) +format to +.IR /etc/localtime . +A timezone database of these files may be located in the system +timezone directory (see the \fBFILES\fP section below). +.P +If the +.B TZ +variable does appear in the environment, but its value is empty, +or its value cannot be interpreted using any of the formats specified +below, then Coordinated Universal Time (UTC) is used. +.P +The value of +.B TZ +can be one of two formats. +The first format is a string of characters that directly represent the +timezone to be used: +.P +.in +4n +.EX +.IR "std offset" [ dst [ offset ][, start [ /time ], end [ /time ]]] +.EE +.in +.P +There are no spaces in the specification. +The \fIstd\fP string specifies an abbreviation for the timezone and must be +three or more alphabetic characters. +When enclosed between the less-than (<) and greater-than (>) signs, the +character set is expanded to include the plus (+) sign, the minus (\-) +sign, and digits. +The \fIoffset\fP string immediately +follows \fIstd\fP and specifies the time value to be added to the local +time to get Coordinated Universal Time (UTC). +The \fIoffset\fP is positive +if the local timezone is west of the Prime Meridian and negative if it is +east. +The hour must be between 0 and 24, and the minutes and seconds 00 and 59: +.P +.in +4n +.EX +.RI [ + | \- ] hh [ :mm [ :ss ]] +.EE +.in +.P +The \fIdst\fP string and \fIoffset\fP specify the name and offset for the +corresponding daylight saving timezone. +If the offset is omitted, +it defaults to one hour ahead of standard time. +.P +The \fIstart\fP field specifies when daylight saving time goes into +effect and the \fIend\fP field specifies when the change is made back to +standard time. +These fields may have the following formats: +.TP +J\fIn\fP +This specifies the Julian day with \fIn\fP between 1 and 365. +Leap days are not counted. +In this format, February 29 can't be represented; +February 28 is day 59, and March 1 is always day 60. +.TP +.I n +This specifies the zero-based Julian day with \fIn\fP between 0 and 365. +February 29 is counted in leap years. +.TP +M\fIm\fP.\fIw\fP.\fId\fP +This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP +(1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12). +Week 1 is +the first week in which day \fId\fP occurs and week 5 is the last week +in which day \fId\fP occurs. +Day 0 is a Sunday. +.P +The \fItime\fP fields specify when, in the local time currently in effect, +the change to the other time occurs. +If omitted, the default is 02:00:00. +.P +Here is an example for New Zealand, +where the standard time (NZST) is 12 hours ahead of UTC, +and daylight saving time (NZDT), 13 hours ahead of UTC, +runs from the first Sunday in October to the third Sunday in March, +and the changeovers happen at the default time of 02:00:00: +.P +.in +4n +.EX +TZ="NZST\-12:00:00NZDT\-13:00:00,M10.1.0,M3.3.0" +.EE +.in +.P +The second format specifies that the timezone information should be read +from a file: +.P +.in +4n +.EX +:[filespec] +.EE +.in +.P +If the file specification \fIfilespec\fP is omitted, or its value cannot +be interpreted, then Coordinated Universal Time (UTC) is used. +If \fIfilespec\fP is given, it specifies another +.BR tzfile (5)-format +file to read the timezone information from. +If \fIfilespec\fP does not begin with a \[aq]/\[aq], the file specification is +relative to the system timezone directory. +If the colon is omitted each +of the above \fBTZ\fP formats will be tried. +.P +Here's an example, once more for New Zealand: +.P +.in +4n +.EX +TZ=":Pacific/Auckland" +.EE +.in +.SH ENVIRONMENT +.TP +.B TZ +If this variable is set its value takes precedence over the system +configured timezone. +.TP +.B TZDIR +If this variable is set its value takes precedence over the system +configured timezone database directory path. +.SH FILES +.TP +.I /etc/localtime +The system timezone file. +.TP +.I /usr/share/zoneinfo/ +The system timezone database directory. +.TP +.I /usr/share/zoneinfo/posixrules +When a TZ string includes a dst timezone without anything following it, +then this file is used for the start/end rules. +It is in the +.BR tzfile (5) +format. +By default, the zoneinfo Makefile hard links it to the +.IR America/New_York " tzfile." +.P +Above are the current standard file locations, but they are +configurable when glibc is compiled. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tzset () +T} Thread safety MT-Safe env locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.P +4.3BSD had a function +.BI "char *timezone(" zone ", " dst ) +that returned the +name of the timezone corresponding to its first argument (minutes +West of UTC). +If the second argument was 0, the standard name was used, +otherwise the daylight saving time version. +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR time (2), +.BR ctime (3), +.BR getenv (3), +.BR tzfile (5) diff --git a/man/man3/ualarm.3 b/man/man3/ualarm.3 new file mode 100644 index 0000000..66359dd --- /dev/null +++ b/man/man3/ualarm.3 @@ -0,0 +1,140 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ualarm 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ualarm \- schedule signal after given number of microseconds +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR ualarm (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +The +.BR ualarm () +function causes the signal +.B SIGALRM +to be sent to the invoking process after (not less than) +.I usecs +microseconds. +The delay may be lengthened slightly by any system activity +or by the time spent processing the call or by the +granularity of system timers. +.P +Unless caught or ignored, the +.B SIGALRM +signal will terminate the process. +.P +If the +.I interval +argument is nonzero, further +.B SIGALRM +signals will be sent every +.I interval +microseconds after the first. +.SH RETURN VALUE +This function returns the number of microseconds remaining for +any alarm that was previously set, or 0 if no alarm was pending. +.SH ERRORS +.TP +.B EINTR +Interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +\fIusecs\fP or \fIinterval\fP is not smaller than 1000000. +(On systems where that is considered an error.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ualarm () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD, POSIX.1-2001. +POSIX.1-2001 marks it as obsolete. +Removed in POSIX.1-2008. +.P +4.3BSD, SUSv2, and POSIX do not define any errors. +.P +POSIX.1-2001 does not specify what happens if the +.I usecs +argument is 0. +.\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD! +On Linux (and probably most other systems), +the effect is to cancel any pending alarm. +.P +The type +.I useconds_t +is an unsigned integer type capable of holding integers +in the range [0,1000000]. +On the original BSD implementation, and in glibc before glibc 2.1, +the arguments to +.BR ualarm () +were instead typed as +.IR "unsigned int" . +Programs will be more portable if they never mention +.I useconds_t +explicitly. +.P +The interaction of this function with +other timer functions such as +.BR alarm (2), +.BR sleep (3), +.BR nanosleep (2), +.BR setitimer (2), +.BR timer_create (2), +.BR timer_delete (2), +.BR timer_getoverrun (2), +.BR timer_gettime (2), +.BR timer_settime (2), +.BR usleep (3) +is unspecified. +.P +This function is obsolete. +Use +.BR setitimer (2) +or POSIX interval timers +.RB ( timer_create (2), +etc.) +instead. +.SH SEE ALSO +.BR alarm (2), +.BR getitimer (2), +.BR nanosleep (2), +.BR select (2), +.BR setitimer (2), +.BR usleep (3), +.BR time (7) diff --git a/man/man3/ulckpwdf.3 b/man/man3/ulckpwdf.3 new file mode 100644 index 0000000..142c5a5 --- /dev/null +++ b/man/man3/ulckpwdf.3 @@ -0,0 +1 @@ +.so man3/getspnam.3 diff --git a/man/man3/ulimit.3 b/man/man3/ulimit.3 new file mode 100644 index 0000000..b143761 --- /dev/null +++ b/man/man3/ulimit.3 @@ -0,0 +1,87 @@ +'\" t +.\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Moved to man3, aeb, 980612 +.\" +.TH ulimit 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ulimit \- get and set user limits +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "[[deprecated]] long ulimit(int " cmd ", long " newlimit ); +.fi +.SH DESCRIPTION +Warning: this routine is obsolete. +Use +.BR getrlimit (2), +.BR setrlimit (2), +and +.BR sysconf (3) +instead. +For the shell command +.BR ulimit , +see +.BR bash (1). +.P +The +.BR ulimit () +call will get or set some limit for the calling process. +The +.I cmd +argument can have one of the following values. +.TP +.B UL_GETFSIZE +Return the limit on the size of a file, in units of 512 bytes. +.TP +.B UL_SETFSIZE +Set the limit on the size of a file. +.TP +.B 3 +(Not implemented for Linux.) +Return the maximum possible address of the data segment. +.TP +.B 4 +(Implemented but no symbolic constant provided.) +Return the maximum number of files that the calling process can open. +.SH RETURN VALUE +On success, +.BR ulimit () +returns a nonnegative value. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EPERM +An unprivileged process tried to increase a limit. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ulimit () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +SVr4, POSIX.1-2001. +POSIX.1-2008 marks it as obsolete. +.SH SEE ALSO +.BR bash (1), +.BR getrlimit (2), +.BR setrlimit (2), +.BR sysconf (3) diff --git a/man/man3/undocumented.3 b/man/man3/undocumented.3 new file mode 100644 index 0000000..09d85e5 --- /dev/null +++ b/man/man3/undocumented.3 @@ -0,0 +1,164 @@ +.\" Copyright 1995 Jim Van Zandt +.\" From jrv@vanzandt.mv.com Mon Sep 4 21:11:50 1995 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 1996-11-08, meem@sherilyn.wustl.edu, corrections +.\" 2004-10-31, aeb, changed maintainer address, updated list +.\" 2015-04-20, william@tuffbizz.com, updated list +.\" +.TH undocumented 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +undocumented \- undocumented library functions +.SH SYNOPSIS +.nf +Undocumented library functions +.fi +.SH DESCRIPTION +This man page mentions those library functions which are implemented in +the standard libraries but not yet documented in man pages. +.SS Solicitation +If you have information about these functions, +please look in the source code, write a man page (using a style +similar to that of the other Linux section 3 man pages), and send it to +.B mtk.manpages@gmail.com +for inclusion in the next man page release. +.SS The list +.BR authdes_create (3), +.BR authdes_getucred (3), +.BR authdes_pk_create (3), +.\" .BR chflags (3), +.BR clntunix_create (3), +.BR creat64 (3), +.BR dn_skipname (3), +.\" .BR fattach (3), +.\" .BR fchflags (3), +.\" .BR fclean (3), +.BR fcrypt (3), +.\" .BR fdetach (3), +.BR fp_nquery (3), +.BR fp_query (3), +.BR fp_resstat (3), +.BR freading (3), +.BR freopen64 (3), +.BR fseeko64 (3), +.BR ftello64 (3), +.BR ftw64 (3), +.BR fwscanf (3), +.BR get_avphys_pages (3), +.BR getdirentries64 (3), +.BR getmsg (3), +.BR getnetname (3), +.BR get_phys_pages (3), +.BR getpublickey (3), +.BR getsecretkey (3), +.BR h_errlist (3), +.BR host2netname (3), +.BR hostalias (3), +.BR inet_nsap_addr (3), +.BR inet_nsap_ntoa (3), +.BR init_des (3), +.BR libc_nls_init (3), +.BR mstats (3), +.BR netname2host (3), +.BR netname2user (3), +.BR nlist (3), +.BR obstack_free (3), +.\" .BR obstack stuff (3), +.BR parse_printf_format (3), +.BR p_cdname (3), +.BR p_cdnname (3), +.BR p_class (3), +.BR p_fqname (3), +.BR p_option (3), +.BR p_query (3), +.BR printf_size (3), +.BR printf_size_info (3), +.BR p_rr (3), +.BR p_time (3), +.BR p_type (3), +.BR putlong (3), +.BR putshort (3), +.BR re_compile_fastmap (3), +.BR re_compile_pattern (3), +.BR register_printf_function (3), +.BR re_match (3), +.BR re_match_2 (3), +.BR re_rx_search (3), +.BR re_search (3), +.BR re_search_2 (3), +.BR re_set_registers (3), +.BR re_set_syntax (3), +.BR res_send_setqhook (3), +.BR res_send_setrhook (3), +.BR ruserpass (3), +.BR setfileno (3), +.BR sethostfile (3), +.BR svc_exit (3), +.BR svcudp_enablecache (3), +.BR tell (3), +.BR thrd_create (3), +.BR thrd_current (3), +.BR thrd_equal (3), +.BR thrd_sleep (3), +.BR thrd_yield (3), +.BR tr_break (3), +.BR tzsetwall (3), +.BR ufc_dofinalperm (3), +.BR ufc_doit (3), +.BR user2netname (3), +.BR wcschrnul (3), +.BR wcsftime (3), +.BR wscanf (3), +.BR xdr_authdes_cred (3), +.BR xdr_authdes_verf (3), +.BR xdr_cryptkeyarg (3), +.BR xdr_cryptkeyres (3), +.BR xdr_datum (3), +.BR xdr_des_block (3), +.BR xdr_domainname (3), +.BR xdr_getcredres (3), +.BR xdr_keybuf (3), +.BR xdr_keystatus (3), +.BR xdr_mapname (3), +.BR xdr_netnamestr (3), +.BR xdr_netobj (3), +.BR xdr_passwd (3), +.BR xdr_peername (3), +.BR xdr_rmtcall_args (3), +.BR xdr_rmtcallres (3), +.BR xdr_unixcred (3), +.BR xdr_yp_buf (3), +.BR xdr_yp_inaddr (3), +.BR xdr_ypbind_binding (3), +.BR xdr_ypbind_resp (3), +.BR xdr_ypbind_resptype (3), +.BR xdr_ypbind_setdom (3), +.BR xdr_ypdelete_args (3), +.BR xdr_ypmaplist (3), +.BR xdr_ypmaplist_str (3), +.BR xdr_yppasswd (3), +.BR xdr_ypreq_key (3), +.BR xdr_ypreq_nokey (3), +.BR xdr_ypresp_all (3), +.BR xdr_ypresp_all_seq (3), +.BR xdr_ypresp_key_val (3), +.BR xdr_ypresp_maplist (3), +.BR xdr_ypresp_master (3), +.BR xdr_ypresp_order (3), +.BR xdr_ypresp_val (3), +.BR xdr_ypstat (3), +.BR xdr_ypupdate_args (3), +.BR yp_all (3), +.BR yp_bind (3), +.BR yperr_string (3), +.BR yp_first (3), +.BR yp_get_default_domain (3), +.BR yp_maplist (3), +.BR yp_master (3), +.BR yp_match (3), +.BR yp_next (3), +.BR yp_order (3), +.BR ypprot_err (3), +.BR yp_unbind (3), +.BR yp_update (3) diff --git a/man/man3/ungetc.3 b/man/man3/ungetc.3 new file mode 100644 index 0000000..2f6585a --- /dev/null +++ b/man/man3/ungetc.3 @@ -0,0 +1 @@ +.so man3/fgetc.3 diff --git a/man/man3/ungetwc.3 b/man/man3/ungetwc.3 new file mode 100644 index 0000000..8892e31 --- /dev/null +++ b/man/man3/ungetwc.3 @@ -0,0 +1,102 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH ungetwc 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ungetwc \- push back a wide character onto a FILE stream +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wint_t ungetwc(wint_t " wc ", FILE *" stream ); +.fi +.SH DESCRIPTION +The +.BR ungetwc () +function is the wide-character equivalent of the +.BR ungetc (3) +function. +It pushes back a wide character onto +.I stream +and returns it. +.P +If +.I wc +is +.BR WEOF , +it returns +.BR WEOF . +If +.I wc +is an invalid wide character, +it sets +.I errno +to +.B EILSEQ +and returns +.BR WEOF . +.P +If +.I wc +is a valid wide character, it is pushed back onto the stream +and thus becomes available for future wide-character read operations. +The file-position indicator is decremented by one or more. +The end-of-file +indicator is cleared. +The backing storage of the file is not affected. +.P +Note: +.I wc +need not be the last wide-character read from the stream; +it can be any other valid wide character. +.P +If the implementation supports multiple push-back operations in a row, the +pushed-back wide characters will be read in reverse order; however, only one +level of push-back is guaranteed. +.SH RETURN VALUE +The +.BR ungetwc () +function returns +.I wc +when successful, or +.B WEOF +upon +failure. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR ungetwc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR ungetwc () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR fgetwc (3) diff --git a/man/man3/unlocked_stdio.3 b/man/man3/unlocked_stdio.3 new file mode 100644 index 0000000..d0c1650 --- /dev/null +++ b/man/man3/unlocked_stdio.3 @@ -0,0 +1,202 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH unlocked_stdio 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +getc_unlocked, getchar_unlocked, putc_unlocked, +putchar_unlocked \- nonlocking stdio functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int getc_unlocked(FILE *" stream ); +.B "int getchar_unlocked(void);" +.BI "int putc_unlocked(int " c ", FILE *" stream ); +.BI "int putchar_unlocked(int " c ); +.P +.BI "void clearerr_unlocked(FILE *" stream ); +.BI "int feof_unlocked(FILE *" stream ); +.BI "int ferror_unlocked(FILE *" stream ); +.BI "int fileno_unlocked(FILE *" stream ); +.BI "int fflush_unlocked(FILE *_Nullable " stream ); +.P +.BI "int fgetc_unlocked(FILE *" stream ); +.BI "int fputc_unlocked(int " c ", FILE *" stream ); +.P +.BI "size_t fread_unlocked(void " ptr "[restrict ." size " * ." n ], +.BI " size_t " size ", size_t " n , +.BI " FILE *restrict " stream ); +.BI "size_t fwrite_unlocked(const void " ptr "[restrict ." size " * ." n ], +.BI " size_t " size ", size_t " n , +.BI " FILE *restrict " stream ); +.P +.BI "char *fgets_unlocked(char " s "[restrict ." n "], int " n \ +", FILE *restrict " stream ); +.BI "int fputs_unlocked(const char *restrict " s ", FILE *restrict " stream ); +.P +.B #include +.P +.BI "wint_t getwc_unlocked(FILE *" stream ); +.B "wint_t getwchar_unlocked(void);" +.BI "wint_t fgetwc_unlocked(FILE *" stream ); +.P +.BI "wint_t fputwc_unlocked(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwc_unlocked(wchar_t " wc ", FILE *" stream ); +.BI "wint_t putwchar_unlocked(wchar_t " wc ); +.P +.BI "wchar_t *fgetws_unlocked(wchar_t " ws "[restrict ." n "], int " n , +.BI " FILE *restrict " stream ); +.BI "int fputws_unlocked(const wchar_t *restrict " ws , +.BI " FILE *restrict " stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR \%getc_unlocked (), +.BR \%getchar_unlocked (), +.BR \%putc_unlocked (), +.BR \%putchar_unlocked (): +.nf + /* glibc >= 2.24: */ _POSIX_C_SOURCE >= 199309L + || /* glibc <= 2.23: */ _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR \%clearerr_unlocked (), +.BR \%feof_unlocked (), +.BR \%ferror_unlocked (), +.BR \%fileno_unlocked (), +.BR \%fflush_unlocked (), +.BR \%fgetc_unlocked (), +.BR \%fputc_unlocked (), +.BR \%fread_unlocked (), +.BR \%fwrite_unlocked (): +.nf + /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR \%fgets_unlocked (), +.BR \%fputs_unlocked (), +.BR \%getwc_unlocked (), +.BR \%getwchar_unlocked (), +.BR \%fgetwc_unlocked (), +.BR \%fputwc_unlocked (), +.BR \%putwchar_unlocked (), +.BR \%fgetws_unlocked (), +.BR \%fputws_unlocked (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +Each of these functions has the same behavior as its counterpart +without the "_unlocked" suffix, except that they do not use locking +(they do not set locks themselves, and do not test for the presence +of locks set by others) and hence are thread-unsafe. +See +.BR flockfile (3). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getc_unlocked (), +.BR putc_unlocked (), +.BR clearerr_unlocked (), +.BR fflush_unlocked (), +.BR fgetc_unlocked (), +.BR fputc_unlocked (), +.BR fread_unlocked (), +.BR fwrite_unlocked (), +.BR fgets_unlocked (), +.BR fputs_unlocked (), +.BR getwc_unlocked (), +.BR fgetwc_unlocked (), +.BR fputwc_unlocked (), +.BR putwc_unlocked (), +.BR fgetws_unlocked (), +.BR fputws_unlocked () +T} Thread safety T{ +.na +.nh +MT-Safe race:stream +T} +T{ +.na +.nh +.BR getchar_unlocked (), +.BR getwchar_unlocked () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:stdin +T} +T{ +.na +.nh +.BR putchar_unlocked (), +.BR putwchar_unlocked () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:stdout +T} +T{ +.na +.nh +.BR feof_unlocked (), +.BR ferror_unlocked (), +.BR fileno_unlocked () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR getc_unlocked () +.TQ +.BR getchar_unlocked () +.TQ +.BR putc_unlocked () +.TQ +.BR putchar_unlocked () +POSIX.1-2008. +.TP +Others: +None. +.SH HISTORY +.TP +.BR getc_unlocked () +.TQ +.BR getchar_unlocked () +.TQ +.BR putc_unlocked () +.TQ +.BR putchar_unlocked () +POSIX.1-2001. +.\" E.g., in HP-UX 10.0. In HP-UX 10.30 they are called obsolescent, and +.\" moved to a compatibility library. +.\" Available in HP-UX 10.0: clearerr_unlocked, fclose_unlocked, +.\" feof_unlocked, ferror_unlocked, fflush_unlocked, fgets_unlocked, +.\" fgetwc_unlocked, fgetws_unlocked, fileno_unlocked, fputs_unlocked, +.\" fputwc_unlocked, fputws_unlocked, fread_unlocked, fseek_unlocked, +.\" ftell_unlocked, fwrite_unlocked, getc_unlocked, getchar_unlocked, +.\" getw_unlocked, getwc_unlocked, getwchar_unlocked, putc_unlocked, +.\" putchar_unlocked, puts_unlocked, putws_unlocked, putw_unlocked, +.\" putwc_unlocked, putwchar_unlocked, rewind_unlocked, setvbuf_unlocked, +.\" ungetc_unlocked, ungetwc_unlocked. +.SH SEE ALSO +.BR flockfile (3), +.BR stdio (3) diff --git a/man/man3/unlockpt.3 b/man/man3/unlockpt.3 new file mode 100644 index 0000000..ccdbf4f --- /dev/null +++ b/man/man3/unlockpt.3 @@ -0,0 +1,84 @@ +'\" t +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. - aeb +.\" %%%LICENSE_END +.\" +.TH unlockpt 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +unlockpt \- unlock a pseudoterminal master/slave pair +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #define _XOPEN_SOURCE +.B #include +.P +.BI "int unlockpt(int " fd ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR unlockpt (): +.nf + Since glibc 2.24: + _XOPEN_SOURCE >= 500 +.\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) + glibc 2.23 and earlier: + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +The +.BR unlockpt () +function unlocks the slave pseudoterminal device +corresponding to the master pseudoterminal referred to by the file descriptor +.IR fd . +.P +.BR unlockpt () +should be called before opening the slave side of a pseudoterminal. +.SH RETURN VALUE +When successful, +.BR unlockpt () +returns 0. +Otherwise, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EBADF +The +.I fd +argument is not a file descriptor open for writing. +.TP +.B EINVAL +The +.I fd +argument is not associated with a master pseudoterminal. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR unlockpt () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +POSIX.1-2001. +.SH SEE ALSO +.BR grantpt (3), +.BR posix_openpt (3), +.BR ptsname (3), +.BR pts (4), +.BR pty (7) diff --git a/man/man3/unsetenv.3 b/man/man3/unsetenv.3 new file mode 100644 index 0000000..19ec56c --- /dev/null +++ b/man/man3/unsetenv.3 @@ -0,0 +1 @@ +.so man3/setenv.3 diff --git a/man/man3/updwtmp.3 b/man/man3/updwtmp.3 new file mode 100644 index 0000000..7a2c8f9 --- /dev/null +++ b/man/man3/updwtmp.3 @@ -0,0 +1,81 @@ +'\" t +.\" Copyright 1997 Nicolás Lichtmaier +.\" Created Wed Jul 2 23:27:34 ART 1997 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Added info on availability, aeb, 971207 +.\" Added -lutil remark, 030718 +.\" 2008-07-02, mtk, document updwtmpx() +.\" +.TH updwtmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +updwtmp, logwtmp \- append an entry to the wtmp file +.SH LIBRARY +System utilities library +.RI ( libutil ", " \-lutil ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "void updwtmp(const char *" wtmp_file ", const struct utmp *" ut ); +.BI "void logwtmp(const char *" line ", const char *" name \ +", const char *" host ); +.fi +.SH DESCRIPTION +.BR updwtmp () +appends the utmp structure +.I ut +to the wtmp file. +.P +.BR logwtmp () +constructs a utmp structure using +.IR line ", " name ", " host , +current time, and current process ID. +Then it calls +.BR updwtmp () +to append the structure to the wtmp file. +.SH FILES +.TP +.I /var/log/wtmp +database of past user logins +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR updwtmp (), +.BR logwtmp () +T} Thread safety MT-Unsafe sig:ALRM timer +.TE +.SH VERSIONS +For consistency with the other "utmpx" functions (see +.BR getutxent (3)), +glibc provides (since glibc 2.1): +.P +.in +4n +.EX +.BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */" +.B #include +.BI "void updwtmpx (const char *" wtmpx_file ", const struct utmpx *" utx ); +.EE +.in +.P +This function performs the same task as +.BR updwtmp (), +but differs in that it takes a +.I utmpx +structure as its last argument. +.SH STANDARDS +None. +.SH HISTORY +Solaris, NetBSD. +.SH SEE ALSO +.BR getutxent (3), +.BR wtmp (5) diff --git a/man/man3/updwtmpx.3 b/man/man3/updwtmpx.3 new file mode 100644 index 0000000..0dc4dea --- /dev/null +++ b/man/man3/updwtmpx.3 @@ -0,0 +1 @@ +.so man3/updwtmp.3 diff --git a/man/man3/uselocale.3 b/man/man3/uselocale.3 new file mode 100644 index 0000000..0856b9d --- /dev/null +++ b/man/man3/uselocale.3 @@ -0,0 +1,102 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH uselocale 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +uselocale \- set/get the locale for the calling thread +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "locale_t uselocale(locale_t " newloc ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR uselocale (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR uselocale () +function sets the current locale for the calling thread, +and returns the thread's previously current locale. +After a successful call to +.BR uselocale (), +any calls by this thread to functions that depend on the locale +will operate as though the locale has been set to +.IR newloc . +.P +The +.I newloc +argument can have one of the following values: +.TP +A handle returned by a call to \fBnewlocale\fP(3) or \fBduplocale\fP(3) +The calling thread's current locale is set to the specified locale. +.TP +The special locale object handle \fBLC_GLOBAL_LOCALE\fP +The calling thread's current locale is set to the global locale determined by +.BR setlocale (3). +.TP +.I "(locale_t) 0" +The calling thread's current locale is left unchanged +(and the current locale is returned as the function result). +.SH RETURN VALUE +On success, +.BR uselocale () +returns the locale handle that was set by the previous call to +.BR uselocale () +in this thread, or +.B LC_GLOBAL_LOCALE +if there was no such previous call. +On error, it returns +.IR "(locale_t)\ 0" , +and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I newloc +does not refer to a valid locale object. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3. +POSIX.1-2008. +.SH NOTES +Unlike +.BR setlocale (3), +.BR uselocale () +does not allow selective replacement of individual locale categories. +To employ a locale that differs in only a few categories from the current +locale, use calls to +.BR duplocale (3) +and +.BR newlocale (3) +to obtain a locale object equivalent to the current locale and +modify the desired categories in that object. +.SH EXAMPLES +See +.BR newlocale (3) +and +.BR duplocale (3). +.SH SEE ALSO +.BR locale (1), +.BR duplocale (3), +.BR freelocale (3), +.BR newlocale (3), +.BR setlocale (3), +.BR locale (5), +.BR locale (7) diff --git a/man/man3/usleep.3 b/man/man3/usleep.3 new file mode 100644 index 0000000..fef133e --- /dev/null +++ b/man/man3/usleep.3 @@ -0,0 +1,123 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2001-04-01 by aeb +.\" Modified 2003-07-23 by aeb +.\" +.TH usleep 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +usleep \- suspend execution for microsecond intervals +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int usleep(useconds_t " usec ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR usleep (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +The +.BR usleep () +function suspends execution of the calling thread for +(at least) \fIusec\fP microseconds. +The sleep may be lengthened slightly +by any system activity or by the time spent processing the call or by the +granularity of system timers. +.SH RETURN VALUE +The +.BR usleep () +function returns 0 on success. +On error, \-1 is returned, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EINTR +Interrupted by a signal; see +.BR signal (7). +.TP +.B EINVAL +\fIusec\fP is greater than or equal to 1000000. +(On systems where that is considered an error.) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR usleep () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD, POSIX.1-2001. +POSIX.1-2001 declares it obsolete, suggesting +.BR nanosleep (2) +instead. +Removed in POSIX.1-2008. +.P +On the original BSD implementation, +and before glibc 2.2.2, the return type of this function is +.IR void . +The POSIX version returns +.IR int , +and this is also the prototype used since glibc 2.2.2. +.P +Only the +.B EINVAL +error return is documented by SUSv2 and POSIX.1-2001. +.SH CAVEATS +The interaction of this function with the +.B SIGALRM +signal, and with other timer functions such as +.BR alarm (2), +.BR sleep (3), +.BR nanosleep (2), +.BR setitimer (2), +.BR timer_create (2), +.BR timer_delete (2), +.BR timer_getoverrun (2), +.BR timer_gettime (2), +.BR timer_settime (2), +.BR ualarm (3) +is unspecified. +.SH SEE ALSO +.BR alarm (2), +.BR getitimer (2), +.BR nanosleep (2), +.BR select (2), +.BR setitimer (2), +.BR sleep (3), +.BR ualarm (3), +.BR useconds_t (3type), +.BR time (7) diff --git a/man/man3/utmpname.3 b/man/man3/utmpname.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/utmpname.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/utmpxname.3 b/man/man3/utmpxname.3 new file mode 100644 index 0000000..29c36b7 --- /dev/null +++ b/man/man3/utmpxname.3 @@ -0,0 +1 @@ +.so man3/getutent.3 diff --git a/man/man3/va_arg.3 b/man/man3/va_arg.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man/man3/va_arg.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man/man3/va_copy.3 b/man/man3/va_copy.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man/man3/va_copy.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man/man3/va_end.3 b/man/man3/va_end.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man/man3/va_end.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man/man3/va_start.3 b/man/man3/va_start.3 new file mode 100644 index 0000000..c419248 --- /dev/null +++ b/man/man3/va_start.3 @@ -0,0 +1 @@ +.so man3/stdarg.3 diff --git a/man/man3/valloc.3 b/man/man3/valloc.3 new file mode 100644 index 0000000..791d4c8 --- /dev/null +++ b/man/man3/valloc.3 @@ -0,0 +1 @@ +.so man3/posix_memalign.3 diff --git a/man/man3/vasprintf.3 b/man/man3/vasprintf.3 new file mode 100644 index 0000000..5a8753a --- /dev/null +++ b/man/man3/vasprintf.3 @@ -0,0 +1 @@ +.so man3/asprintf.3 diff --git a/man/man3/vdprintf.3 b/man/man3/vdprintf.3 new file mode 100644 index 0000000..fa36f35 --- /dev/null +++ b/man/man3/vdprintf.3 @@ -0,0 +1 @@ +.so man3/dprintf.3 diff --git a/man/man3/verr.3 b/man/man3/verr.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/verr.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/verrx.3 b/man/man3/verrx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/verrx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/versionsort.3 b/man/man3/versionsort.3 new file mode 100644 index 0000000..7e757c7 --- /dev/null +++ b/man/man3/versionsort.3 @@ -0,0 +1 @@ +.so man3/scandir.3 diff --git a/man/man3/vfprintf.3 b/man/man3/vfprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/vfprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/vfscanf.3 b/man/man3/vfscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man/man3/vfscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man/man3/vfwprintf.3 b/man/man3/vfwprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man/man3/vfwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man/man3/vlimit.3 b/man/man3/vlimit.3 new file mode 100644 index 0000000..58a817b --- /dev/null +++ b/man/man3/vlimit.3 @@ -0,0 +1,3 @@ +.so man2/getrlimit.2 +.\" No new programs should use vlimit(3). +.\" getrlimit(2) briefly discusses vlimit(3), so point the user there. diff --git a/man/man3/vprintf.3 b/man/man3/vprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/vprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/vscanf.3 b/man/man3/vscanf.3 new file mode 100644 index 0000000..9fd424b --- /dev/null +++ b/man/man3/vscanf.3 @@ -0,0 +1 @@ +.so man3/scanf.3 diff --git a/man/man3/vsnprintf.3 b/man/man3/vsnprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/vsnprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/vsprintf.3 b/man/man3/vsprintf.3 new file mode 100644 index 0000000..975530d --- /dev/null +++ b/man/man3/vsprintf.3 @@ -0,0 +1 @@ +.so man3/printf.3 diff --git a/man/man3/vsscanf.3 b/man/man3/vsscanf.3 new file mode 100644 index 0000000..8f5ebc1 --- /dev/null +++ b/man/man3/vsscanf.3 @@ -0,0 +1 @@ +.so man3/sscanf.3 diff --git a/man/man3/vswprintf.3 b/man/man3/vswprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man/man3/vswprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man/man3/vsyslog.3 b/man/man3/vsyslog.3 new file mode 100644 index 0000000..ec352b2 --- /dev/null +++ b/man/man3/vsyslog.3 @@ -0,0 +1 @@ +.so man3/syslog.3 diff --git a/man/man3/vtimes.3 b/man/man3/vtimes.3 new file mode 100644 index 0000000..4097ab7 --- /dev/null +++ b/man/man3/vtimes.3 @@ -0,0 +1,3 @@ +.so man2/getrusage.2 +.\" No new programs should use vtimes(3). +.\" getrusage(2) briefly discusses vtimes(3), so point the user there. diff --git a/man/man3/vwarn.3 b/man/man3/vwarn.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/vwarn.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/vwarnx.3 b/man/man3/vwarnx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/vwarnx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/vwprintf.3 b/man/man3/vwprintf.3 new file mode 100644 index 0000000..56ec968 --- /dev/null +++ b/man/man3/vwprintf.3 @@ -0,0 +1 @@ +.so man3/wprintf.3 diff --git a/man/man3/warn.3 b/man/man3/warn.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/warn.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/warnx.3 b/man/man3/warnx.3 new file mode 100644 index 0000000..3ee2e49 --- /dev/null +++ b/man/man3/warnx.3 @@ -0,0 +1 @@ +.so man3/err.3 diff --git a/man/man3/wcpcpy.3 b/man/man3/wcpcpy.3 new file mode 100644 index 0000000..8d80953 --- /dev/null +++ b/man/man3/wcpcpy.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcpcpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcpcpy \- copy a wide-character string, returning a pointer to its end +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcpcpy(wchar_t *restrict " dest \ +", const wchar_t *restrict " src ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcpcpy (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcpcpy () +function is the wide-character equivalent of the +.BR stpcpy (3) +function. +It copies the wide-character string pointed to by +.IR src , +including the terminating null wide character (L\[aq]\e0\[aq]), +to the array pointed to by +.IR dest . +.P +The strings may not overlap. +.P +The programmer must ensure that there +is room for at least +.I wcslen(src)+1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcpcpy () +returns a pointer to the end of the wide-character string +.IR dest , +that is, a pointer to the terminating null wide character. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcpcpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH SEE ALSO +.BR strcpy (3), +.BR wcscpy (3) diff --git a/man/man3/wcpncpy.3 b/man/man3/wcpncpy.3 new file mode 100644 index 0000000..b63d3d0 --- /dev/null +++ b/man/man3/wcpncpy.3 @@ -0,0 +1,106 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcpncpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcpncpy \- copy a fixed-size string of wide characters, +returning a pointer to its end +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcpncpy(wchar_t " dest "[restrict ." n ], +.BI " const wchar_t " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcpncpy (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcpncpy () +function is the wide-character equivalent +of the +.BR stpncpy (3) +function. +It copies at most +.I n +wide characters from the wide-character +string pointed to by +.IR src , +including the terminating null wide (L\[aq]\e0\[aq]), +to the array pointed to by +.IR dest . +Exactly +.I n +wide characters are +written at +.IR dest . +If the length +.I wcslen(src) +is smaller than +.IR n , +the remaining wide characters in the array pointed to +by +.I dest +are filled with L\[aq]\e0\[aq] characters. +If the length +.I wcslen(src) +is greater than or equal +to +.IR n , +the string pointed to by +.I dest +will +not be L\[aq]\e0\[aq] terminated. +.P +The strings may not overlap. +.P +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wcpncpy () +returns a pointer to the last wide character written, that is, +.IR dest + n \-1. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcpncpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH SEE ALSO +.BR stpncpy (3), +.BR wcsncpy (3) diff --git a/man/man3/wcrtomb.3 b/man/man3/wcrtomb.3 new file mode 100644 index 0000000..9e96b92 --- /dev/null +++ b/man/man3/wcrtomb.3 @@ -0,0 +1,144 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcrtomb 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcrtomb \- convert a wide character to a multibyte sequence +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t wcrtomb(char *restrict " s ", wchar_t " wc \ +", mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +The main case for this function is when +.I s +is +not NULL and +.I wc +is not a null wide character (L\[aq]\e0\[aq]). +In this case, the +.BR wcrtomb () +function +converts the wide character +.I wc +to its multibyte representation and stores it +at the beginning of the character +array pointed to by +.IR s . +It updates the shift state +.IR *ps , +and +returns the length of said multibyte representation, +that is, the number of bytes +written at +.IR s . +.P +A different case is when +.I s +is not NULL, +but +.I wc +is a null wide character (L\[aq]\e0\[aq]). +In this case, the +.BR wcrtomb () +function stores at +the character array pointed to by +.I s +the shift sequence needed to +bring +.I *ps +back to the initial state, +followed by a \[aq]\e0\[aq] byte. +It updates the shift state +.I *ps +(i.e., brings +it into the initial state), +and returns the length of the shift sequence plus +one, that is, the number of bytes written at +.IR s . +.P +A third case is when +.I s +is NULL. +In this case, +.I wc +is ignored, +and the function effectively returns +.P +.in +4n +.EX +wcrtomb(buf, L\[aq]\e0\[aq], ps) +.EE +.in +.P +where +.I buf +is an internal anonymous buffer. +.P +In all of the above cases, if +.I ps +is NULL, a static anonymous +state known only to the +.BR wcrtomb () +function is used instead. +.SH RETURN VALUE +The +.BR wcrtomb () +function returns the number of +bytes that have been or would +have been written to the byte array at +.IR s . +If +.I wc +can not be +represented as a multibyte sequence (according to the current locale), +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcrtomb () +T} Thread safety MT-Unsafe race:wcrtomb/!ps +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wcrtomb () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR mbsinit (3), +.BR wcsrtombs (3) diff --git a/man/man3/wcscasecmp.3 b/man/man3/wcscasecmp.3 new file mode 100644 index 0000000..b9d4c21 --- /dev/null +++ b/man/man3/wcscasecmp.3 @@ -0,0 +1,99 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcscasecmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcscasecmp \- compare two wide-character strings, ignoring case +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int wcscasecmp(const wchar_t *" s1 ", const wchar_t *" s2 ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcscasecmp (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcscasecmp () +function is the wide-character equivalent of the +.BR strcasecmp (3) +function. +It compares the wide-character string pointed to +by +.I s1 +and the wide-character string pointed to by +.IR s2 , +ignoring +case differences +.RB ( towupper (3), +.BR towlower (3)). +.SH RETURN VALUE +The +.BR wcscasecmp () +function returns zero if the wide-character strings at +.I s1 +and +.I s2 +are equal except for case distinctions. +It returns a +positive integer if +.I s1 +is greater than +.IR s2 , +ignoring case. +It +returns a negative integer if +.I s1 +is smaller +than +.IR s2 , +ignoring case. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcscasecmp () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +.SH NOTES +The behavior of +.BR wcscasecmp () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR strcasecmp (3), +.BR wcscmp (3) diff --git a/man/man3/wcscat.3 b/man/man3/wcscat.3 new file mode 100644 index 0000000..5aecad3 --- /dev/null +++ b/man/man3/wcscat.3 @@ -0,0 +1,70 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcscat 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcscat \- concatenate two wide-character strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcscat(wchar_t *restrict " dest \ +", const wchar_t *restrict " src ); +.fi +.SH DESCRIPTION +The +.BR wcscat () +function is the wide-character equivalent +of the +.BR strcat (3) +function. +It copies the wide-character string pointed to by +.IR src , +including the terminating null wide character (L\[aq]\e0\[aq]), +to the end of the wide-character string pointed to by +.IR dest . +.P +The strings may not overlap. +.P +The programmer must ensure that there is room for at least +.IR wcslen(dest) + wcslen(src) +1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcscat () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcscat () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strcat (3), +.BR wcpcpy (3), +.BR wcscpy (3), +.BR wcsncat (3) diff --git a/man/man3/wcschr.3 b/man/man3/wcschr.3 new file mode 100644 index 0000000..8b05e14 --- /dev/null +++ b/man/man3/wcschr.3 @@ -0,0 +1,69 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcschr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcschr \- search a wide character in a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcschr(const wchar_t *" wcs ", wchar_t " wc ); +.fi +.SH DESCRIPTION +The +.BR wcschr () +function is the wide-character equivalent +of the +.BR strchr (3) +function. +It searches the first occurrence of +.I wc +in the wide-character +string pointed to by +.IR wcs . +.SH RETURN VALUE +The +.BR wcschr () +function returns a pointer to the first occurrence of +.I wc +in the wide-character string pointed to by +.IR wcs , +or NULL if +.I wc +does not occur in the string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcschr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strchr (3), +.BR wcspbrk (3), +.BR wcsrchr (3), +.BR wcsstr (3), +.BR wmemchr (3) diff --git a/man/man3/wcscmp.3 b/man/man3/wcscmp.3 new file mode 100644 index 0000000..06c1f56 --- /dev/null +++ b/man/man3/wcscmp.3 @@ -0,0 +1,79 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcscmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcscmp \- compare two wide-character strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int wcscmp(const wchar_t *" s1 ", const wchar_t *" s2 ); +.fi +.SH DESCRIPTION +The +.BR wcscmp () +function is the wide-character equivalent +of the +.BR strcmp (3) +function. +It compares the wide-character string pointed to by +.I s1 +and the +wide-character string pointed to by +.IR s2 . +.SH RETURN VALUE +The +.BR wcscmp () +function returns zero if the wide-character strings at +.I s1 +and +.I s2 +are equal. +It returns an integer greater than zero if +at the first differing position +.IR i , +the corresponding wide-character +.I s1[i] +is greater than +.IR s2[i] . +It returns an integer less than zero if +at the first differing position +.IR i , +the corresponding wide-character +.I s1[i] +is less than +.IR s2[i] . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcscmp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strcmp (3), +.BR wcscasecmp (3), +.BR wmemcmp (3) diff --git a/man/man3/wcscpy.3 b/man/man3/wcscpy.3 new file mode 100644 index 0000000..5607bd7 --- /dev/null +++ b/man/man3/wcscpy.3 @@ -0,0 +1,72 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcscpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcscpy \- copy a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcscpy(wchar_t *restrict " dest \ +", const wchar_t *restrict " src ); +.fi +.SH DESCRIPTION +The +.BR wcscpy () +function is the wide-character equivalent +of the +.BR strcpy (3) +function. +It copies the wide-character string pointed to by +.IR src , +including the terminating null wide character (L\[aq]\e0\[aq]), +to the array pointed to by +.IR dest . +.P +The strings may not overlap. +.P +The programmer must ensure that there is +room for at least +.I wcslen(src)+1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcscpy () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcscpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strcpy (3), +.BR wcpcpy (3), +.BR wcscat (3), +.BR wcsdup (3), +.BR wmemcpy (3) diff --git a/man/man3/wcscspn.3 b/man/man3/wcscspn.3 new file mode 100644 index 0000000..ddffa22 --- /dev/null +++ b/man/man3/wcscspn.3 @@ -0,0 +1,81 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcscspn 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcscspn \- search a wide-character string for any of a set of wide characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t wcscspn(const wchar_t *" wcs ", const wchar_t *" reject ); +.fi +.SH DESCRIPTION +The +.BR wcscspn () +function is the wide-character equivalent +of the +.BR strcspn (3) +function. +It determines the length of the longest initial segment of +.I wcs +which consists entirely of wide-characters not listed in +.IR reject . +In +other words, it searches for the first occurrence in the wide-character +string +.I wcs +of any of the characters in the wide-character string +.IR reject . +.SH RETURN VALUE +The +.BR wcscspn () +function returns the number of +wide characters in the longest +initial segment of +.I wcs +which consists entirely of wide-characters not +listed in +.IR reject . +In other words, it returns the position of the first +occurrence in the wide-character string +.I wcs +of any of the characters in +the wide-character string +.IR reject , +or +.I wcslen(wcs) +if there is none. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcscspn () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strcspn (3), +.BR wcspbrk (3), +.BR wcsspn (3) diff --git a/man/man3/wcsdup.3 b/man/man3/wcsdup.3 new file mode 100644 index 0000000..41131a1 --- /dev/null +++ b/man/man3/wcsdup.3 @@ -0,0 +1,83 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcsdup 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsdup \- duplicate a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcsdup(const wchar_t *" s ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcsdup (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcsdup () +function is the wide-character equivalent +of the +.BR strdup (3) +function. +It allocates and returns a new wide-character string whose initial +contents is a duplicate of the wide-character string pointed to by +.IR s . +.P +Memory for the new wide-character string is +obtained with +.BR malloc (3), +and should be freed with +.BR free (3). +.SH RETURN VALUE +On success, +.BR wcsdup () +returns a pointer to the new wide-character string. +On error, it returns NULL, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory available to allocate duplicate string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsdup () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +libc5, glibc 2.0. +.SH SEE ALSO +.BR strdup (3), +.BR wcscpy (3) diff --git a/man/man3/wcslen.3 b/man/man3/wcslen.3 new file mode 100644 index 0000000..4e96b94 --- /dev/null +++ b/man/man3/wcslen.3 @@ -0,0 +1,65 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcslen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcslen \- determine the length of a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t wcslen(const wchar_t *" s ); +.fi +.SH DESCRIPTION +The +.BR wcslen () +function is the wide-character equivalent +of the +.BR strlen (3) +function. +It determines the length of the wide-character string pointed to +by +.IR s , +excluding the terminating null wide character (L\[aq]\e0\[aq]). +.SH RETURN VALUE +The +.BR wcslen () +function returns the +number of wide characters in +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcslen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +In cases where the input buffer may not contain +a terminating null wide character, +.BR wcsnlen (3) +should be used instead. +.SH SEE ALSO +.BR strlen (3) diff --git a/man/man3/wcsncasecmp.3 b/man/man3/wcsncasecmp.3 new file mode 100644 index 0000000..dde8ec1 --- /dev/null +++ b/man/man3/wcsncasecmp.3 @@ -0,0 +1,105 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcsncasecmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsncasecmp \- compare two fixed-size wide-character strings, ignoring case +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int wcsncasecmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], s\ +ize_t " n ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcsncasecmp (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcsncasecmp () +function is the wide-character equivalent of the +.BR strncasecmp (3) +function. +It compares the wide-character string pointed to +by +.I s1 +and the wide-character string +pointed to by +.IR s2 , +but at most +.I n +wide characters from each string, ignoring case differences +.RB ( towupper (3), +.BR towlower (3)). +.SH RETURN VALUE +The +.BR wcsncasecmp () +function returns zero +if the wide-character strings at +.I s1 +and +.IR s2 , +truncated to at most length +.IR n , +are equal except +for case distinctions. +It returns a positive integer if truncated +.I s1 +is +greater than truncated +.IR s2 , +ignoring case. +It returns a negative integer +if truncated +.I s1 +is smaller than truncated +.IR s2 , +ignoring case. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsncasecmp () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +.SH NOTES +The behavior of +.BR wcsncasecmp () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR strncasecmp (3), +.BR wcsncmp (3) diff --git a/man/man3/wcsncat.3 b/man/man3/wcsncat.3 new file mode 100644 index 0000000..77181d2 --- /dev/null +++ b/man/man3/wcsncat.3 @@ -0,0 +1,72 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsncat 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsncat \- concatenate two wide-character strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcsncat(wchar_t " dest "[restrict ." n ], +.BI " const wchar_t " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcsncat () +function is the wide-character equivalent of the +.BR strncat (3) +function. +It copies at most +.I n +wide characters from the wide-character +string pointed to by +.I src +to the end of the wide-character string pointed +to by +.IR dest , +and adds a terminating null wide character (L\[aq]\e0\[aq]). +.P +The strings may not overlap. +.P +The programmer must ensure that there is room for at least +.IR wcslen(dest) + n +1 +wide characters at +.IR dest . +.SH RETURN VALUE +.BR wcsncat () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsncat () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strncat (3), +.BR wcscat (3) diff --git a/man/man3/wcsncmp.3 b/man/man3/wcsncmp.3 new file mode 100644 index 0000000..2768894 --- /dev/null +++ b/man/man3/wcsncmp.3 @@ -0,0 +1,93 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsncmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsncmp \- compare two fixed-size wide-character strings +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int wcsncmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcsncmp () +function is the wide-character equivalent of the +.BR strncmp (3) +function. +It compares the wide-character string pointed to by +.I s1 +and the +wide-character string pointed to by +.IR s2 , +but at most +.I n +wide +characters from each string. +In each string, the comparison extends only up +to the first occurrence of a null wide character (L\[aq]\e0\[aq]), if any. +.SH RETURN VALUE +The +.BR wcsncmp () +function returns zero if the wide-character strings at +.I s1 +and +.IR s2 , +truncated to at most length +.IR n , +are equal. +It returns an integer greater than zero if at the first differing position +.I i +.RI ( i +< +.IR n ), +the corresponding wide-character +.I s1[i] +is +greater than +.IR s2[i] . +It returns an integer less than zero if at the first +differing position +.I i +.RI ( i +< +.IR n ), +the corresponding +wide-character +.I s1[i] +is less than +.IR s2[i] . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsncmp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strncmp (3), +.BR wcsncasecmp (3) diff --git a/man/man3/wcsncpy.3 b/man/man3/wcsncpy.3 new file mode 100644 index 0000000..841f356 --- /dev/null +++ b/man/man3/wcsncpy.3 @@ -0,0 +1,89 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsncpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsncpy \- copy a fixed-size string of wide characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcsncpy(wchar_t " dest "[restrict ." n ], +.BI " const wchar_t " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcsncpy () +function is the wide-character equivalent of the +.BR strncpy (3) +function. +It copies at most +.I n +wide characters from the wide-character +string pointed to by +.IR src , +including the terminating null wide character (L\[aq]\e0\[aq]), +to the array pointed to by +.IR dest . +Exactly +.I n +wide characters are +written at +.IR dest . +If the length \fIwcslen(src)\fP is smaller than +.IR n , +the remaining wide characters in the array +pointed to by +.I dest +are filled +with null wide characters. +If the length \fIwcslen(src)\fP is greater than or equal +to +.IR n , +the string pointed to by +.I dest +will not be terminated by a null wide character. +.P +The strings may not overlap. +.P +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wcsncpy () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsncpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strncpy (3) diff --git a/man/man3/wcsnlen.3 b/man/man3/wcsnlen.3 new file mode 100644 index 0000000..e2c4116 --- /dev/null +++ b/man/man3/wcsnlen.3 @@ -0,0 +1,91 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcsnlen 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsnlen \- determine the length of a fixed-size wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t wcsnlen(const wchar_t " s [. maxlen "], size_t " maxlen ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcsnlen (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcsnlen () +function is the wide-character equivalent +of the +.BR strnlen (3) +function. +It returns the number of wide-characters in the string pointed to by +.IR s , +not including the terminating null wide character (L\[aq]\e0\[aq]), +but at most +.I maxlen +wide characters (note: this parameter is not a byte count). +In doing this, +.BR wcsnlen () +looks at only the first +.I maxlen +wide characters at +.I s +and never beyond +.IR s[maxlen\-1] . +.SH RETURN VALUE +The +.BR wcsnlen () +function returns +.IR wcslen(s) , +if that is less than +.IR maxlen , +or +.I maxlen +if there is no null wide character among the +first +.I maxlen +wide characters pointed to by +.IR s . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsnlen () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.1. +.SH SEE ALSO +.BR strnlen (3), +.BR wcslen (3) diff --git a/man/man3/wcsnrtombs.3 b/man/man3/wcsnrtombs.3 new file mode 100644 index 0000000..1ef6581 --- /dev/null +++ b/man/man3/wcsnrtombs.3 @@ -0,0 +1,189 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcsnrtombs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsnrtombs \- convert a wide-character string to a multibyte string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t wcsnrtombs(char " dest "[restrict ." len "], \ +const wchar_t **restrict " src , +.BI " size_t " nwc ", size_t " len ", \ +mbstate_t *restrict " ps ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wcsnrtombs (): +.nf + Since glibc 2.10: + _POSIX_C_SOURCE >= 200809L + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR wcsnrtombs () +function is like the +.BR wcsrtombs (3) +function, +except that the number of wide characters to be converted, +starting at +.IR *src , +is limited to +.IR nwc . +.P +If +.I dest +is not NULL, +the +.BR wcsnrtombs () +function converts +at most +.I nwc +wide characters from +the wide-character string +.I *src +to a multibyte string starting at +.IR dest . +At most +.I len +bytes are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.IR "wcrtomb(dest, *src, ps)" , +as long as this call succeeds, +and then incrementing +.I dest +by the +number of bytes written and +.I *src +by one. +The conversion can stop for three reasons: +.IP \[bu] 3 +A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). +In this case, +.I *src +is left pointing to the invalid wide character, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP \[bu] +.I nwc +wide characters have been +converted without encountering a null wide character (L\[aq]\e0\[aq]), +or the length limit forces a stop. +In this case, +.I *src +is left pointing +to the next wide character to be converted, and the number of bytes written +to +.I dest +is returned. +.IP \[bu] +The wide-character string has been completely converted, including the +terminating null wide character (which has the side effect of bringing back +.I *ps +to the initial state). +In this case, +.I *src +is set to NULL, and the number +of bytes written to +.IR dest , +excluding the terminating null byte (\[aq]\e0\[aq]), is +returned. +.P +If +.I dest +is NULL, +.I len +is ignored, +and the conversion proceeds as above, +except that the converted bytes are not written out to memory, and that +no destination length limit exists. +.P +In both of the above cases, +if +.I ps +is NULL, a static anonymous +state known only to the +.BR wcsnrtombs () +function is used instead. +.P +The programmer must ensure that there is room for at least +.I len +bytes +at +.IR dest . +.SH RETURN VALUE +The +.BR wcsnrtombs () +function returns +the number of bytes that make up the +converted part of multibyte sequence, +not including the terminating null byte. +If a wide character was encountered which +could not be converted, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsnrtombs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:wcsnrtombs/!ps +T} +.TE +.SH STANDARDS +POSIX.1-2008. +.SH NOTES +The behavior of +.BR wcsnrtombs () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbsinit (3), +.BR wcsrtombs (3) diff --git a/man/man3/wcspbrk.3 b/man/man3/wcspbrk.3 new file mode 100644 index 0000000..2b3286e --- /dev/null +++ b/man/man3/wcspbrk.3 @@ -0,0 +1,69 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcspbrk 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcspbrk \- search a wide-character string for any of a set of wide characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcspbrk(const wchar_t *" wcs ", const wchar_t *" accept ); +.fi +.SH DESCRIPTION +The +.BR wcspbrk () +function is the wide-character equivalent +of the +.BR strpbrk (3) +function. +It searches for the first occurrence in the wide-character +string pointed to by +.I wcs +of any of the +characters in the wide-character +string pointed to by +.IR accept . +.SH RETURN VALUE +The +.BR wcspbrk () +function returns a pointer to the first occurrence in +.I wcs +of any of the characters listed in +.IR accept . +If +.I wcs +contains none of these characters, NULL is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcspbrk () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strpbrk (3), +.BR wcschr (3), +.BR wcscspn (3) diff --git a/man/man3/wcsrchr.3 b/man/man3/wcsrchr.3 new file mode 100644 index 0000000..05b0e38 --- /dev/null +++ b/man/man3/wcsrchr.3 @@ -0,0 +1,66 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsrchr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsrchr \- search a wide character in a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcsrchr(const wchar_t *" wcs ", wchar_t " wc ); +.fi +.SH DESCRIPTION +The +.BR wcsrchr () +function is the wide-character equivalent +of the +.BR strrchr (3) +function. +It searches the last occurrence of +.I wc +in the wide-character +string pointed to by +.IR wcs . +.SH RETURN VALUE +The +.BR wcsrchr () +function returns a pointer to the last occurrence of +.I wc +in the wide-character string pointed to by +.IR wcs , +or NULL if +.I wc +does not occur in the string. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsrchr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strrchr (3), +.BR wcschr (3) diff --git a/man/man3/wcsrtombs.3 b/man/man3/wcsrtombs.3 new file mode 100644 index 0000000..9235dfb --- /dev/null +++ b/man/man3/wcsrtombs.3 @@ -0,0 +1,164 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsrtombs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsrtombs \- convert a wide-character string to a multibyte string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t wcsrtombs(char " dest "[restrict ." len "], \ +const wchar_t **restrict " src , +.BI " size_t " len ", mbstate_t *restrict " ps ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, +the +.BR wcsrtombs () +function converts +the wide-character string +.I *src +to a multibyte string starting at +.IR dest . +At most +.I len +bytes are written to +.IR dest . +The shift state +.I *ps +is updated. +The conversion is effectively performed by repeatedly +calling +.IR "wcrtomb(dest, *src, ps)" , +as long as this call succeeds, +and then incrementing +.I dest +by the +number of bytes written and +.I *src +by one. +The conversion can stop for three reasons: +.IP \[bu] 3 +A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). +In this case, +.I *src +is left pointing to the invalid wide character, +.I (size_t)\ \-1 +is returned, +and +.I errno +is set to +.BR EILSEQ . +.IP \[bu] +The length limit forces a stop. +In this case, +.I *src +is left pointing +to the next wide character to be converted, +and the number of bytes written to +.I dest +is returned. +.IP \[bu] +The wide-character string has been completely converted, including the +terminating null wide character (L\[aq]\e0\[aq]), +which has the side effect of bringing back +.I *ps +to the initial state. +In this case, +.I *src +is set to NULL, and the number +of bytes written to +.IR dest , +excluding the terminating null byte (\[aq]\e0\[aq]), +is returned. +.P +If +.I dest +is NULL, +.I len +is ignored, +and the conversion proceeds as above, except that the converted bytes +are not written out to memory, and that +no length limit exists. +.P +In both of the above cases, +if +.I ps +is NULL, a static anonymous +state known only to the +.BR wcsrtombs () +function is used instead. +.P +The programmer must ensure that there is room for at least +.I len +bytes +at +.IR dest . +.SH RETURN VALUE +The +.BR wcsrtombs () +function returns +the number of bytes that make up the +converted part of multibyte sequence, +not including the terminating null byte. +If a wide character was encountered +which could not be converted, +.I (size_t)\ \-1 +is returned, and +.I errno +set to +.BR EILSEQ . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsrtombs () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:wcsrtombs/!ps +T} +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wcsrtombs () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +Passing NULL as +.I ps +is not multithread safe. +.SH SEE ALSO +.BR iconv (3), +.BR mbsinit (3), +.BR wcrtomb (3), +.BR wcsnrtombs (3), +.BR wcstombs (3) diff --git a/man/man3/wcsspn.3 b/man/man3/wcsspn.3 new file mode 100644 index 0000000..1a66e09 --- /dev/null +++ b/man/man3/wcsspn.3 @@ -0,0 +1,78 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsspn 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsspn \- get length of a prefix wide-character substring +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t wcsspn(const wchar_t *" wcs ", const wchar_t *" accept ); +.fi +.SH DESCRIPTION +The +.BR wcsspn () +function is the wide-character equivalent of the +.BR strspn (3) +function. +It determines the length of the longest initial segment of +.I wcs +which consists entirely of wide-characters listed in +.IR accept . +In other +words, it searches for the first occurrence in the wide-character string +.I wcs +of a wide-character not contained in the wide-character string +.IR accept . +.SH RETURN VALUE +The +.BR wcsspn () +function returns the number of +wide characters in the longest +initial segment of +.I wcs +which consists entirely of wide-characters listed +in +.IR accept . +In other words, it returns the position of the first +occurrence in the wide-character string +.I wcs +of a wide-character not +contained in the wide-character string +.IR accept , +or +.I wcslen(wcs) +if there is none. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsspn () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strspn (3), +.BR wcscspn (3) diff --git a/man/man3/wcsstr.3 b/man/man3/wcsstr.3 new file mode 100644 index 0000000..95e9359 --- /dev/null +++ b/man/man3/wcsstr.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcsstr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcsstr \- locate a substring in a wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcsstr(const wchar_t *" haystack ", const wchar_t *" needle ); +.fi +.SH DESCRIPTION +The +.BR wcsstr () +function is the wide-character equivalent of the +.BR strstr (3) +function. +It searches for the first occurrence of the wide-character string +.I needle +(without its terminating null wide character (L\[aq]\e0\[aq])) +as a substring in the wide-character string +.IR haystack . +.SH RETURN VALUE +The +.BR wcsstr () +function returns a pointer to the first occurrence of +.I needle +in +.IR haystack . +It returns NULL if +.I needle +does not occur +as a substring in +.IR haystack . +.P +Note the special case: +If +.I needle +is the empty wide-character string, +the return value is always +.I haystack +itself. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcsstr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR strstr (3), +.BR wcschr (3) diff --git a/man/man3/wcstoimax.3 b/man/man3/wcstoimax.3 new file mode 100644 index 0000000..ebd8691 --- /dev/null +++ b/man/man3/wcstoimax.3 @@ -0,0 +1,58 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH wcstoimax 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcstoimax, wcstoumax \- convert wide-character string to integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "intmax_t wcstoimax(const wchar_t *restrict " nptr , +.BI " wchar_t **restrict " endptr ", int " base ); +.BI "uintmax_t wcstoumax(const wchar_t *restrict " nptr , +.BI " wchar_t **restrict " endptr ", int " base ); +.fi +.SH DESCRIPTION +These functions are just like +.BR wcstol (3) +and +.BR wcstoul (3), +except that they return a value of type +.I intmax_t +and +.IR uintmax_t , +respectively. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcstoimax (), +.BR wcstoumax () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR imaxabs (3), +.BR imaxdiv (3), +.BR strtoimax (3), +.BR strtoumax (3), +.\" FIXME . the pages referred to by the following xrefs are not yet written +.BR wcstol (3), +.BR wcstoul (3) diff --git a/man/man3/wcstok.3 b/man/man3/wcstok.3 new file mode 100644 index 0000000..f2d19c8 --- /dev/null +++ b/man/man3/wcstok.3 @@ -0,0 +1,117 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcstok 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcstok \- split wide-character string into tokens +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wcstok(wchar_t *restrict " wcs \ +", const wchar_t *restrict " delim , +.BI " wchar_t **restrict " ptr ); +.fi +.SH DESCRIPTION +The +.BR wcstok () +function is the wide-character equivalent of the +.BR strtok (3) +function, +with an added argument to make it multithread-safe. +It can be used +to split a wide-character string +.I wcs +into tokens, where a token is +defined as a substring not containing any wide-characters from +.IR delim . +.P +The search starts at +.IR wcs , +if +.I wcs +is not NULL, +or at +.IR *ptr , +if +.I wcs +is NULL. +First, any delimiter wide-characters are skipped, that is, the +pointer is advanced beyond any wide-characters which occur in +.IR delim . +If the end of the wide-character string is now +reached, +.BR wcstok () +returns NULL, to indicate that no tokens +were found, and stores an appropriate value in +.IR *ptr , +so that subsequent calls to +.BR wcstok () +will continue to return NULL. +Otherwise, the +.BR wcstok () +function recognizes the beginning of a token +and returns a pointer to it, but before doing that, it zero-terminates the +token by replacing the next wide-character which occurs in +.I delim +with +a null wide character (L\[aq]\e0\[aq]), +and it updates +.I *ptr +so that subsequent calls will +continue searching after the end of recognized token. +.SH RETURN VALUE +The +.BR wcstok () +function returns a pointer to the next token, +or NULL if no further token was found. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcstok () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The original +.I wcs +wide-character string is destructively modified during +the operation. +.SH EXAMPLES +The following code loops over the tokens contained in a wide-character string. +.P +.EX +wchar_t *wcs = ...; +wchar_t *token; +wchar_t *state; +for (token = wcstok(wcs, L" \et\en", &state); + token != NULL; + token = wcstok(NULL, L" \et\en", &state)) { + ... +} +.EE +.SH SEE ALSO +.BR strtok (3), +.BR wcschr (3) diff --git a/man/man3/wcstombs.3 b/man/man3/wcstombs.3 new file mode 100644 index 0000000..4d3ef56 --- /dev/null +++ b/man/man3/wcstombs.3 @@ -0,0 +1,125 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wcstombs 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcstombs \- convert a wide-character string to a multibyte string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "size_t wcstombs(char " dest "[restrict ." n "], \ +const wchar_t *restrict " src , +.BI " size_t " n ); +.fi +.SH DESCRIPTION +If +.I dest +is not NULL, the +.BR wcstombs () +function converts +the wide-character string +.I src +to a multibyte string starting at +.IR dest . +At most +.I n +bytes are written to +.IR dest . +The sequence of characters placed in +.I dest +begins in the initial shift state. +The conversion can stop for three reasons: +.IP \[bu] 3 +A wide character has been encountered that can not be represented as a +multibyte sequence (according to the current locale). +In this case, +.I (size_t)\ \-1 +is returned. +.IP \[bu] +The length limit forces a stop. +In this case, the number of bytes written to +.I dest +is returned, but the shift state at this point is lost. +.IP \[bu] +The wide-character string has been completely converted, including the +terminating null wide character (L\[aq]\e0\[aq]). +In this case, the conversion ends in the initial shift state. +The number of bytes written to +.IR dest , +excluding the terminating null byte (\[aq]\e0\[aq]), is returned. +.P +The programmer must ensure that there is room for at least +.I n +bytes +at +.IR dest . +.P +If +.I dest +is NULL, +.I n +is ignored, and the conversion proceeds as +above, except that the converted bytes are not written out to memory, +and no length limit exists. +.P +In order to avoid the case 2 above, the programmer should make sure +.I n +is greater than or equal to +.IR "wcstombs(NULL,src,0)+1" . +.SH RETURN VALUE +The +.BR wcstombs () +function returns the number of bytes that make up the +converted part of a multibyte sequence, +not including the terminating null byte. +If a wide character was encountered which could not be +converted, +.I (size_t)\ \-1 +is returned. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcstombs () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +The function +.BR wcsrtombs (3) +provides a better interface to the same functionality. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wcstombs () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR mblen (3), +.BR mbstowcs (3), +.BR mbtowc (3), +.BR wcsrtombs (3), +.BR wctomb (3) diff --git a/man/man3/wcstoumax.3 b/man/man3/wcstoumax.3 new file mode 100644 index 0000000..f3aa5d2 --- /dev/null +++ b/man/man3/wcstoumax.3 @@ -0,0 +1 @@ +.so man3/wcstoimax.3 diff --git a/man/man3/wcswidth.3 b/man/man3/wcswidth.3 new file mode 100644 index 0000000..b46fc52 --- /dev/null +++ b/man/man3/wcswidth.3 @@ -0,0 +1,73 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcswidth 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcswidth \- determine columns needed for a fixed-size wide-character string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int wcswidth(const wchar_t *" s ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wcswidth () +function returns the +number of columns needed to represent +the wide-character string pointed to by +.IR s , +but at most +.I n +wide +characters. +If a nonprintable wide character occurs among these characters, +\-1 is returned. +.SH RETURN VALUE +The +.BR wcswidth () +function +returns the number of column positions for the +wide-character string +.IR s , +truncated to at most length +.IR n . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcswidth () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The behavior of +.BR wcswidth () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswprint (3), +.BR wcwidth (3) diff --git a/man/man3/wctob.3 b/man/man3/wctob.3 new file mode 100644 index 0000000..b95ef37 --- /dev/null +++ b/man/man3/wctob.3 @@ -0,0 +1,86 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wctob 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wctob \- try to represent a wide character as a single byte +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int wctob(wint_t " c ); +.fi +.SH DESCRIPTION +The +.BR wctob () +function tests whether +the multibyte representation of the +wide character +.IR c , +starting in the initial state, consists of a single +byte. +If so, it is returned as an +.IR "unsigned char" . +.P +Never use this function. +It cannot help you in writing internationalized +programs. +Internationalized programs must never distinguish single-byte and +multibyte characters. +.SH RETURN VALUE +The +.BR wctob () +function returns the single-byte representation of +.IR c , +if it exists, or +.B EOF +otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wctob () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wctob () +depends on the +.B LC_CTYPE +category of the +current locale. +.P +This function should never be used. +Internationalized programs must never +distinguish single-byte and multibyte characters. +Use either +.BR wctomb (3) +or the thread-safe +.BR wcrtomb (3) +instead. +.SH SEE ALSO +.BR btowc (3), +.BR wcrtomb (3), +.BR wctomb (3) diff --git a/man/man3/wctomb.3 b/man/man3/wctomb.3 new file mode 100644 index 0000000..33a688a --- /dev/null +++ b/man/man3/wctomb.3 @@ -0,0 +1,119 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wctomb 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wctomb \- convert a wide character to a multibyte sequence +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int wctomb(char *" s ", wchar_t " wc ); +.fi +.SH DESCRIPTION +If +.I s +is not NULL, +the +.BR wctomb () +function converts the wide character +.I wc +to its multibyte representation and stores it at the beginning of +the character array pointed to by +.IR s . +It updates the shift state, which +is stored in a static anonymous variable +known only to the +.BR wctomb () +function, +and returns the length of said multibyte representation, +that is, the number of +bytes written at +.IR s . +.P +The programmer must ensure that there is +room for at least +.B MB_CUR_MAX +bytes at +.IR s . +.P +If +.I s +is NULL, the +.BR wctomb () +function +.\" The Dinkumware doc and the Single UNIX specification say this, but +.\" glibc doesn't implement this. +resets the shift state, known only to this function, +to the initial state, and +returns nonzero if the encoding has nontrivial shift state, +or zero if the encoding is stateless. +.SH RETURN VALUE +If +.I s +is not NULL, the +.BR wctomb () +function +returns the number of bytes +that have been written to the byte array at +.IR s . +If +.I wc +can not be +represented as a multibyte sequence (according +to the current locale), \-1 is returned. +.P +If +.I s +is NULL, the +.BR wctomb () +function returns nonzero if the +encoding has nontrivial shift state, or zero if the encoding is stateless. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wctomb () +T} Thread safety MT-Unsafe race +.TE +.SH VERSIONS +The function +.BR wcrtomb (3) +provides +a better interface to the same functionality. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wctomb () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR MB_CUR_MAX (3), +.BR mblen (3), +.BR mbstowcs (3), +.BR mbtowc (3), +.BR wcrtomb (3), +.BR wcstombs (3) diff --git a/man/man3/wctrans.3 b/man/man3/wctrans.3 new file mode 100644 index 0000000..92a2409 --- /dev/null +++ b/man/man3/wctrans.3 @@ -0,0 +1,88 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wctrans 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wctrans \- wide-character translation mapping +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wctrans_t wctrans(const char *" name ); +.fi +.SH DESCRIPTION +The +.I wctrans_t +type represents a mapping +which can map a wide character to +another wide character. +Its nature is implementation-dependent, but the special +value +.I (wctrans_t)\ 0 +denotes an invalid mapping. +Nonzero +.I wctrans_t +values can be passed to the +.BR towctrans (3) +function to actually perform +the wide-character mapping. +.P +The +.BR wctrans () +function returns a mapping, given by its name. +The set of +valid names depends on the +.B LC_CTYPE +category of the current locale, but the +following names are valid in all locales. +.P +.nf + "tolower" \- realizes the \fBtolower\fP(3) mapping + "toupper" \- realizes the \fBtoupper\fP(3) mapping +.fi +.SH RETURN VALUE +The +.BR wctrans () +function returns a mapping descriptor if the +.I name +is valid. +Otherwise, it returns +.IR "(wctrans_t)\ 0" . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wctrans () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wctrans () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR towctrans (3) diff --git a/man/man3/wctype.3 b/man/man3/wctype.3 new file mode 100644 index 0000000..cf6ce26 --- /dev/null +++ b/man/man3/wctype.3 @@ -0,0 +1,100 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wctype 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wctype \- wide-character classification +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wctype_t wctype(const char *" name ); +.fi +.SH DESCRIPTION +The +.I wctype_t +type represents a property which a wide character may or +may not have. +In other words, it represents a class of wide characters. +This type's nature is implementation-dependent, but the special value +.I "(wctype_t) 0" +denotes an invalid property. +Nonzero +.I wctype_t +values +can be passed to the +.BR iswctype (3) +function +to actually test whether a given +wide character has the property. +.P +The +.BR wctype () +function returns a property, given by its name. +The set of +valid names depends on the +.B LC_CTYPE +category of the current locale, but the +following names are valid in all locales. +.P +.nf + "alnum" \- realizes the \fBisalnum\fP(3) classification function + "alpha" \- realizes the \fBisalpha\fP(3) classification function + "blank" \- realizes the \fBisblank\fP(3) classification function + "cntrl" \- realizes the \fBiscntrl\fP(3) classification function + "digit" \- realizes the \fBisdigit\fP(3) classification function + "graph" \- realizes the \fBisgraph\fP(3) classification function + "lower" \- realizes the \fBislower\fP(3) classification function + "print" \- realizes the \fBisprint\fP(3) classification function + "punct" \- realizes the \fBispunct\fP(3) classification function + "space" \- realizes the \fBisspace\fP(3) classification function + "upper" \- realizes the \fBisupper\fP(3) classification function + "xdigit" \- realizes the \fBisxdigit\fP(3) classification function +.fi +.SH RETURN VALUE +The +.BR wctype () +function returns a property descriptor +if the +.I name +is valid. +Otherwise, it returns +.IR "(wctype_t) 0" . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wctype () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wctype () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswctype (3) diff --git a/man/man3/wcwidth.3 b/man/man3/wcwidth.3 new file mode 100644 index 0000000..5aaba2b --- /dev/null +++ b/man/man3/wcwidth.3 @@ -0,0 +1,77 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wcwidth 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wcwidth \- determine columns needed for a wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BI "int wcwidth(wchar_t " c ); +.fi +.SH DESCRIPTION +The +.BR wcwidth () +function returns the number of columns +needed to represent the wide character +.IR c . +If +.I c +is a printable wide character, the value +is at least 0. +If +.I c +is null wide character (L\[aq]\e0\[aq]), the value is 0. +Otherwise, \-1 is returned. +.SH RETURN VALUE +The +.BR wcwidth () +function returns the number of +column positions for +.IR c . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wcwidth () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Note that before glibc 2.2.5, glibc used the prototype +.P +.nf +.BI "int wcwidth(wint_t " c ); +.fi +.SH NOTES +The behavior of +.BR wcwidth () +depends on the +.B LC_CTYPE +category of the +current locale. +.SH SEE ALSO +.BR iswprint (3), +.BR wcswidth (3) diff --git a/man/man3/wmemchr.3 b/man/man3/wmemchr.3 new file mode 100644 index 0000000..d4cf541 --- /dev/null +++ b/man/man3/wmemchr.3 @@ -0,0 +1,70 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wmemchr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wmemchr \- search a wide character in a wide-character array +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wmemchr(const wchar_t " s [. n "], wchar_t " c ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemchr () +function is the wide-character equivalent of the +.BR memchr (3) +function. +It searches the +.I n +wide characters starting at +.I s +for +the first occurrence of the wide character +.IR c . +.SH RETURN VALUE +The +.BR wmemchr () +function returns a pointer to the first occurrence of +.I c +among the +.I n +wide characters starting at +.IR s , +or NULL if +.I c +does +not occur among these. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wmemchr () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR memchr (3), +.BR wcschr (3) diff --git a/man/man3/wmemcmp.3 b/man/man3/wmemcmp.3 new file mode 100644 index 0000000..f89e8a1 --- /dev/null +++ b/man/man3/wmemcmp.3 @@ -0,0 +1,90 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" +.TH wmemcmp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wmemcmp \- compare two arrays of wide-characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int wmemcmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemcmp () +function is the wide-character equivalent of the +.BR memcmp (3) +function. +It compares the +.I n +wide-characters starting at +.I s1 +and the +.I n +wide-characters starting at +.IR s2 . +.SH RETURN VALUE +The +.BR wmemcmp () +function returns +zero if the wide-character arrays of size +.I n +at +.I s1 +and +.I s2 +are equal. +It returns an integer greater than +zero if at the first differing position +.I i +.RI ( i " <" +.IR n ), +the +corresponding wide-character +.I s1[i] +is greater than +.IR s2[i] . +It returns an integer less than zero if +at the first differing position +.I i +.RI ( i +< +.IR n ), +the corresponding +wide-character +.I s1[i] +is less than +.IR s2[i] . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wmemcmp () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR memcmp (3), +.BR wcscmp (3) diff --git a/man/man3/wmemcpy.3 b/man/man3/wmemcpy.3 new file mode 100644 index 0000000..808a6ae --- /dev/null +++ b/man/man3/wmemcpy.3 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wmemcpy 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wmemcpy \- copy an array of wide-characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wmemcpy(wchar_t " dest "[restrict ." n ], +.BI " const wchar_t " src "[restrict ." n ], +.BI " size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemcpy () +function is the wide-character equivalent of the +.BR memcpy (3) +function. +It copies +.I n +wide characters from the array starting at +.I src +to the array starting at +.IR dest . +.P +The arrays may not overlap; use +.BR wmemmove (3) +to copy between overlapping +arrays. +.P +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wmemcpy () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wmemcpy () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR memcpy (3), +.BR wcscpy (3), +.BR wmemmove (3), +.BR wmempcpy (3) diff --git a/man/man3/wmemmove.3 b/man/man3/wmemmove.3 new file mode 100644 index 0000000..aff1bea --- /dev/null +++ b/man/man3/wmemmove.3 @@ -0,0 +1,70 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wmemmove 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wmemmove \- copy an array of wide-characters +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wmemmove(wchar_t " dest [. n "], const wchar_t " src [. n "], \ +size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemmove () +function is the wide-character equivalent of the +.BR memmove (3) +function. +It copies +.I n +wide characters from the array +starting at +.I src +to the array starting at +.IR dest . +The arrays may +overlap. +.P +The programmer must ensure that there is room for at least +.I n +wide +characters at +.IR dest . +.SH RETURN VALUE +.BR wmemmove () +returns +.IR dest . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wmemmove () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR memmove (3), +.BR wmemcpy (3) diff --git a/man/man3/wmempcpy.3 b/man/man3/wmempcpy.3 new file mode 100644 index 0000000..26750cb --- /dev/null +++ b/man/man3/wmempcpy.3 @@ -0,0 +1 @@ +.so man3/mempcpy.3 diff --git a/man/man3/wmemset.3 b/man/man3/wmemset.3 new file mode 100644 index 0000000..b4c4cb2 --- /dev/null +++ b/man/man3/wmemset.3 @@ -0,0 +1,61 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wmemset 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wmemset \- fill an array of wide-characters with a constant wide character +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "wchar_t *wmemset(wchar_t " wcs [. n "], wchar_t " wc ", size_t " n ); +.fi +.SH DESCRIPTION +The +.BR wmemset () +function is the wide-character equivalent of the +.BR memset (3) +function. +It fills the array of +.I n +wide-characters starting at +.I wcs +with +.I n +copies of the wide character +.IR wc . +.SH RETURN VALUE +.BR wmemset () +returns +.IR wcs . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wmemset () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH SEE ALSO +.BR memset (3) diff --git a/man/man3/wordexp.3 b/man/man3/wordexp.3 new file mode 100644 index 0000000..945befc --- /dev/null +++ b/man/man3/wordexp.3 @@ -0,0 +1,245 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH wordexp 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wordexp, wordfree \- perform word expansion like a posix-shell +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "int wordexp(const char *restrict " s ", wordexp_t *restrict " p \ +", int " flags ); +.BI "void wordfree(wordexp_t *" p ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR wordexp (), +.BR wordfree (): +.nf + _XOPEN_SOURCE +.fi +.SH DESCRIPTION +The function +.BR wordexp () +performs a shell-like expansion of the string +.I s +and returns the result in the structure pointed to by +.IR p . +The data type +.I wordexp_t +is a structure that at least has the fields +.IR we_wordc , +.IR we_wordv , +and +.IR we_offs . +The field +.I we_wordc +is a +.I size_t +that gives the number of words in the expansion of +.IR s . +The field +.I we_wordv +is a +.I "char\ **" +that points to the array of words found. +The field +.I we_offs +of type +.I size_t +is sometimes (depending on +.IR flags , +see below) used to indicate the number of initial elements in the +.I we_wordv +array that should be filled with NULLs. +.P +The function +.BR wordfree () +frees the allocated memory again. +More precisely, it does not free +its argument, but it frees the array +.I we_wordv +and the strings that points to. +.SS The string argument +Since the expansion is the same as the expansion by the shell (see +.BR sh (1)) +of the parameters to a command, the string +.I s +must not contain characters that would be illegal in shell command +parameters. +In particular, there must not be any unescaped +newline or |, &, ;, <, >, (, ), {, } characters +outside a command substitution or parameter substitution context. +.P +If the argument +.I s +contains a word that starts with an unquoted comment character #, +then it is unspecified whether that word and all following words +are ignored, or the # is treated as a non-comment character. +.SS The expansion +The expansion done consists of the following stages: +tilde expansion (replacing \[ti]user by user's home directory), +variable substitution (replacing $FOO by the value of the environment +variable FOO), command substitution (replacing $(command) or \`command\` +by the output of command), arithmetic expansion, field splitting, +wildcard expansion, quote removal. +.P +The result of expansion of special parameters +($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified. +.P +Field splitting is done using the environment variable $IFS. +If it is not set, the field separators are space, tab, and newline. +.SS The output array +The array +.I we_wordv +contains the words found, followed by a NULL. +.SS The flags argument +The +.I flag +argument is a bitwise inclusive OR of the following values: +.TP +.B WRDE_APPEND +Append the words found to the array resulting from a previous call. +.TP +.B WRDE_DOOFFS +Insert +.I we_offs +initial NULLs in the array +.IR we_wordv . +(These are not counted in the returned +.IR we_wordc .) +.TP +.B WRDE_NOCMD +Don't do command substitution. +.TP +.B WRDE_REUSE +The argument +.I p +resulted from a previous call to +.BR wordexp (), +and +.BR wordfree () +was not called. +Reuse the allocated storage. +.TP +.B WRDE_SHOWERR +Normally during command substitution +.I stderr +is redirected to +.IR /dev/null . +This flag specifies that +.I stderr +is not to be redirected. +.TP +.B WRDE_UNDEF +Consider it an error if an undefined shell variable is expanded. +.SH RETURN VALUE +On success, +.BR wordexp () +returns 0. +On failure, +.BR wordexp () +returns one of the following nonzero values: +.TP +.B WRDE_BADCHAR +Illegal occurrence of newline or one of |, &, ;, <, >, (, ), {, }. +.TP +.B WRDE_BADVAL +An undefined shell variable was referenced, and the +.B WRDE_UNDEF +flag +told us to consider this an error. +.TP +.B WRDE_CMDSUB +Command substitution requested, but the +.B WRDE_NOCMD +flag told us to consider this an error. +.TP +.B WRDE_NOSPACE +Out of memory. +.TP +.B WRDE_SYNTAX +Shell syntax error, such as unbalanced parentheses or +unmatched quotes. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wordexp () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:utent const:env +env sig:ALRM timer locale +T} +T{ +.na +.nh +.BR wordfree () +T} Thread safety MT-Safe +.TE +.P +In the above table, +.I utent +in +.I race:utent +signifies that if any of the functions +.BR setutent (3), +.BR getutent (3), +or +.BR endutent (3) +are used in parallel in different threads of a program, +then data races could occur. +.BR wordexp () +calls those functions, +so we use race:utent to remind users. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +glibc 2.1. +.SH EXAMPLES +The output of the following example program +is approximately that of "ls [a-c]*.c". +.P +.\" SRC BEGIN (wordexp.c) +.EX +#include +#include +#include +\& +int +main(void) +{ + wordexp_t p; + char **w; +\& + wordexp("[a\-c]*.c", &p, 0); + w = p.we_wordv; + for (size_t i = 0; i < p.we_wordc; i++) + printf("%s\en", w[i]); + wordfree(&p); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR fnmatch (3), +.BR glob (3) diff --git a/man/man3/wordfree.3 b/man/man3/wordfree.3 new file mode 100644 index 0000000..f0035e0 --- /dev/null +++ b/man/man3/wordfree.3 @@ -0,0 +1 @@ +.so man3/wordexp.3 diff --git a/man/man3/wprintf.3 b/man/man3/wprintf.3 new file mode 100644 index 0000000..6aaf3b4 --- /dev/null +++ b/man/man3/wprintf.3 @@ -0,0 +1,273 @@ +'\" t +.\" Copyright (c) Bruno Haible +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH wprintf 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted +wide-character output conversion +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.BI "int wprintf(const wchar_t *restrict " format ", ...);" +.BI "int fwprintf(FILE *restrict " stream , +.BI " const wchar_t *restrict " format ", ...);" +.BI "int swprintf(wchar_t " wcs "[restrict ." maxlen "], size_t " maxlen , +.BI " const wchar_t *restrict " format ", ...);" +.P +.BI "int vwprintf(const wchar_t *restrict " format ", va_list " args ); +.BI "int vfwprintf(FILE *restrict " stream , +.BI " const wchar_t *restrict " format ", va_list " args ); +.BI "int vswprintf(wchar_t " wcs "[restrict ." maxlen "], size_t " maxlen , +.BI " const wchar_t *restrict " format ", va_list " args ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +All functions shown above: +.\" .BR wprintf (), +.\" .BR fwprintf (), +.\" .BR swprintf (), +.\" .BR vwprintf (), +.\" .BR vfwprintf (), +.\" .BR vswprintf (): +.nf + _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE + || _POSIX_C_SOURCE >= 200112L +.fi +.SH DESCRIPTION +The +.BR wprintf () +family of functions is +the wide-character equivalent of the +.BR printf (3) +family of functions. +It performs formatted output of wide +characters. +.P +The +.BR wprintf () +and +.BR vwprintf () +functions +perform wide-character output to +.IR stdout . +.I stdout +must not be byte oriented; see +.BR fwide (3) +for more information. +.P +The +.BR fwprintf () +and +.BR vfwprintf () +functions +perform wide-character output to +.IR stream . +.I stream +must not be byte oriented; see +.BR fwide (3) +for more information. +.P +The +.BR swprintf () +and +.BR vswprintf () +functions +perform wide-character output +to an array of wide characters. +The programmer must ensure that there is +room for at least +.I maxlen +wide +characters at +.IR wcs . +.P +These functions are like +the +.BR printf (3), +.BR vprintf (3), +.BR fprintf (3), +.BR vfprintf (3), +.BR sprintf (3), +.BR vsprintf (3) +functions except for the +following differences: +.TP +.B \[bu] +The +.I format +string is a wide-character string. +.TP +.B \[bu] +The output consists of wide characters, not bytes. +.TP +.B \[bu] +.BR swprintf () +and +.BR vswprintf () +take a +.I maxlen +argument, +.BR sprintf (3) +and +.BR vsprintf (3) +do not. +.RB ( snprintf (3) +and +.BR vsnprintf (3) +take a +.I maxlen +argument, but these functions do not return \-1 upon +buffer overflow on Linux.) +.P +The treatment of the conversion characters +.B c +and +.B s +is different: +.TP +.B c +If no +.B l +modifier is present, the +.I int +argument is converted to a wide character by a call to the +.BR btowc (3) +function, and the resulting wide character is written. +If an +.B l +modifier is present, the +.I wint_t +(wide character) argument is written. +.TP +.B s +If no +.B l +modifier is present: the +.I "const\ char\ *" +argument is expected to be a pointer to an array of character type +(pointer to a string) containing a multibyte character sequence beginning +in the initial shift state. +Characters from the array are converted to +wide characters (each by a call to the +.BR mbrtowc (3) +function with a conversion state starting in the initial state before +the first byte). +The resulting wide characters are written up to +(but not including) the terminating null wide character (L\[aq]\e0\[aq]). +If a precision is +specified, no more wide characters than the number specified are written. +Note that the precision determines the number of +.I wide characters +written, not the number of +.I bytes +or +.IR "screen positions" . +The array must contain a terminating null byte (\[aq]\e0\[aq]), +unless a precision is given +and it is so small that the number of converted wide characters reaches it +before the end of the array is reached. +If an +.B l +modifier is present: the +.I "const\ wchar_t\ *" +argument is expected to be a pointer to an array of wide characters. +Wide characters from the array are written up to (but not including) a +terminating null wide character. +If a precision is specified, no more than +the number specified are written. +The array must contain a terminating null +wide character, unless a precision is given and it is smaller than or equal +to the number of wide characters in the array. +.SH RETURN VALUE +The functions return the number of wide characters written, excluding the +terminating null wide character in +case of the functions +.BR swprintf () +and +.BR vswprintf (). +They return \-1 when an error occurs. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR wprintf (), +.BR fwprintf (), +.BR swprintf (), +.BR vwprintf (), +.BR vfwprintf (), +.BR vswprintf () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C99. +.SH NOTES +The behavior of +.BR wprintf () +et al. depends +on the +.B LC_CTYPE +category of the +current locale. +.P +If the +.I format +string contains non-ASCII wide characters, the program +will work correctly only if the +.B LC_CTYPE +category of the current locale at +run time is the same as the +.B LC_CTYPE +category of the current locale at +compile time. +This is because the +.I wchar_t +representation is platform- and locale-dependent. +(The glibc represents +wide characters using their Unicode (ISO/IEC 10646) code point, but other +platforms don't do this. +Also, the use of C99 universal character names +of the form \eunnnn does not solve this problem.) +Therefore, in +internationalized programs, the +.I format +string should consist of ASCII +wide characters only, or should be constructed at run time in an +internationalized way (e.g., using +.BR gettext (3) +or +.BR iconv (3), +followed by +.BR mbstowcs (3)). +.SH SEE ALSO +.BR fprintf (3), +.BR fputwc (3), +.BR fwide (3), +.BR printf (3), +.BR snprintf (3) +.\" .BR wscanf (3) diff --git a/man/man3/xcrypt.3 b/man/man3/xcrypt.3 new file mode 100644 index 0000000..d00642a --- /dev/null +++ b/man/man3/xcrypt.3 @@ -0,0 +1,95 @@ +'\" t +.\" Copyright 2003 walter harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" this is the 3rd type of interface for cryptographic routines +.\" 1. encrypt() expects a bit field +.\" 2. cbc_crypt() byte values +.\" 3. xencrypt() a hexstring +.\" to bad to be true :( +.\" +.TH XCRYPT 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +xencrypt, xdecrypt, passwd2des \- RFS password encryption +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B "#include " +.P +.BI "void passwd2des(char " *passwd ", char *" key ");" +.P +.BI "int xencrypt(char *" secret ", char *" passwd ");" +.BI "int xdecrypt(char *" secret ", char *" passwd ");" +.fi +.SH DESCRIPTION +.BR WARNING : +Do not use these functions in new code. +They do not achieve any type of acceptable cryptographic security guarantees. +.P +The function +.BR passwd2des () +takes a character string +.I passwd +of arbitrary length and fills a character array +.I key +of length 8. +The array +.I key +is suitable for use as DES key. +It has odd parity set in bit 0 of each byte. +Both other functions described here use this function to turn their +argument +.I passwd +into a DES key. +.P +The +.BR xencrypt () +function takes the ASCII character string +.I secret +given in hex, +.\" (over the alphabet 0123456789abcdefABCDEF), +which must have a length that is a multiple of 16, +encrypts it using the DES key derived from +.I passwd +by +.BR passwd2des (), +and outputs the result again in +.I secret +as a hex string +.\" (over the alphabet 0123456789abcdef) +of the same length. +.P +The +.BR xdecrypt () +function performs the converse operation. +.SH RETURN VALUE +The functions +.BR xencrypt () +and +.BR xdecrypt () +return 1 on success and 0 on error. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR passwd2des (), +.BR xencrypt (), +.BR xdecrypt () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +These functions are available since glibc 2.1. +.SH BUGS +The prototypes are missing from the abovementioned include file. +.SH SEE ALSO +.BR cbc_crypt (3) diff --git a/man/man3/xdecrypt.3 b/man/man3/xdecrypt.3 new file mode 100644 index 0000000..01b6ce6 --- /dev/null +++ b/man/man3/xdecrypt.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man/man3/xdr.3 b/man/man3/xdr.3 new file mode 100644 index 0000000..9aa20c4 --- /dev/null +++ b/man/man3/xdr.3 @@ -0,0 +1,609 @@ +'\" t +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)xdr.3n 2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI +.\" +.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax +.\" +.TH xdr 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +xdr \- library routines for external data representation +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS AND DESCRIPTION +These routines allow C programmers to describe +arbitrary data structures in a machine-independent fashion. +Data for remote procedure calls are transmitted using these +routines. +.P +The prototypes below are declared in +.I +and make use of the following types: +.P +.RS 4 +.EX +.BI "typedef int " bool_t ; +.P +.BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *,...);" +.EE +.RE +.P +For the declaration of the +.I XDR +type, see +.IR . +.P +.nf +.BI "bool_t xdr_array(XDR *" xdrs ", char **" arrp ", unsigned int *" sizep , +.BI " unsigned int " maxsize ", unsigned int " elsize , +.BI " xdrproc_t " elproc ); +.fi +.IP +A filter primitive that translates between variable-length arrays +and their corresponding external representations. +The argument +.I arrp +is the address of the pointer to the array, while +.I sizep +is the address of the element count of the array; +this element count cannot exceed +.IR maxsize . +The argument +.I elsize +is the +.I sizeof +each of the array's elements, and +.I elproc +is an XDR filter that translates between +the array elements' C form, and their external +representation. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_bool(XDR *" xdrs ", bool_t *" bp ); +.fi +.IP +A filter primitive that translates between booleans (C +integers) +and their external representations. +When encoding data, this +filter produces values of either one or zero. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_bytes(XDR *" xdrs ", char **" sp ", unsigned int *" sizep , +.BI " unsigned int " maxsize ); +.fi +.IP +A filter primitive that translates between counted byte +strings and their external representations. +The argument +.I sp +is the address of the string pointer. +The length of the +string is located at address +.IR sizep ; +strings cannot be longer than +.IR maxsize . +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_char(XDR *" xdrs ", char *" cp ); +.fi +.IP +A filter primitive that translates between C characters +and their external representations. +This routine returns one if it succeeds, zero otherwise. +Note: encoded characters are not packed, and occupy 4 bytes each. +For arrays of characters, it is worthwhile to +consider +.BR xdr_bytes (), +.BR xdr_opaque (), +or +.BR xdr_string (). +.P +.nf +.BI "void xdr_destroy(XDR *" xdrs ); +.fi +.IP +A macro that invokes the destroy routine associated with the XDR stream, +.IR xdrs . +Destruction usually involves freeing private data structures +associated with the stream. +Using +.I xdrs +after invoking +.BR xdr_destroy () +is undefined. +.P +.nf +.BI "bool_t xdr_double(XDR *" xdrs ", double *" dp ); +.fi +.IP +A filter primitive that translates between C +.I double +precision numbers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_enum(XDR *" xdrs ", enum_t *" ep ); +.fi +.IP +A filter primitive that translates between C +.IR enum s +(actually integers) and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_float(XDR *" xdrs ", float *" fp ); +.fi +.IP +A filter primitive that translates between C +.IR float s +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "void xdr_free(xdrproc_t " proc ", char *" objp ); +.fi +.IP +Generic freeing routine. +The first argument is the XDR routine for the object being freed. +The second argument is a pointer to the object itself. +Note: the pointer passed to this routine is +.I not +freed, but what it points to +.I is +freed (recursively). +.P +.nf +.BI "unsigned int xdr_getpos(XDR *" xdrs ); +.fi +.IP +A macro that invokes the get-position routine +associated with the XDR stream, +.IR xdrs . +The routine returns an unsigned integer, +which indicates the position of the XDR byte stream. +A desirable feature of XDR +streams is that simple arithmetic works with this number, +although the XDR stream instances need not guarantee this. +.P +.nf +.BI "long *xdr_inline(XDR *" xdrs ", int " len ); +.fi +.IP +A macro that invokes the inline routine associated with the XDR stream, +.IR xdrs . +The routine returns a pointer +to a contiguous piece of the stream's buffer; +.I len +is the byte length of the desired buffer. +Note: pointer is cast to +.IR "long\ *" . +.IP +Warning: +.BR xdr_inline () +may return NULL (0) +if it cannot allocate a contiguous piece of a buffer. +Therefore the behavior may vary among stream instances; +it exists for the sake of efficiency. +.P +.nf +.BI "bool_t xdr_int(XDR *" xdrs ", int *" ip ); +.fi +.IP +A filter primitive that translates between C integers +and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_long(XDR *" xdrs ", long *" lp ); +.fi +.IP +A filter primitive that translates between C +.I long +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "void xdrmem_create(XDR *" xdrs ", char *" addr ", unsigned int " size , +.BI " enum xdr_op " op ); +.fi +.IP +This routine initializes the XDR stream object pointed to by +.IR xdrs . +The stream's data is written to, or read from, +a chunk of memory at location +.I addr +whose length is no more than +.I size +bytes long. +The +.I op +determines the direction of the XDR stream (either +.BR XDR_ENCODE , +.BR XDR_DECODE , +or +.BR XDR_FREE ). +.P +.nf +.BI "bool_t xdr_opaque(XDR *" xdrs ", char *" cp ", unsigned int " cnt ); +.fi +.IP +A filter primitive that translates between fixed size opaque data +and its external representation. +The argument +.I cp +is the address of the opaque object, and +.I cnt +is its size in bytes. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_pointer(XDR *" xdrs ", char **" objpp , +.BI " unsigned int " objsize ", xdrproc_t " xdrobj ); +.fi +.IP +Like +.BR xdr_reference () +except that it serializes null pointers, whereas +.BR xdr_reference () +does not. +Thus, +.BR xdr_pointer () +can represent +recursive data structures, such as binary trees or +linked lists. +.P +.nf +.BI "void xdrrec_create(XDR *" xdrs ", unsigned int " sendsize , +.BI " unsigned int " recvsize ", char *" handle , +.BI " int (*" readit ")(char *, char *, int)," +.BI " int (*" writeit ")(char *, char *, int));" +.fi +.IP +This routine initializes the XDR stream object pointed to by +.IR xdrs . +The stream's data is written to a buffer of size +.IR sendsize ; +a value of zero indicates the system should use a suitable default. +The stream's data is read from a buffer of size +.IR recvsize ; +it too can be set to a suitable default by passing a zero value. +When a stream's output buffer is full, +.I writeit +is called. +Similarly, when a stream's input buffer is empty, +.I readit +is called. +The behavior of these two routines is similar to +the system calls +.BR read (2) +and +.BR write (2), +except that +.I handle +is passed to the former routines as the first argument. +Note: the XDR stream's +.I op +field must be set by the caller. +.IP +Warning: to read from an XDR stream created by this API, +you'll need to call +.BR xdrrec_skiprecord () +first before calling any other XDR APIs. +This inserts additional bytes in the stream to provide +record boundary information. +Also, XDR streams created with different +.B xdr*_create +APIs are not compatible for the same reason. +.P +.nf +.BI "bool_t xdrrec_endofrecord(XDR *" xdrs ", int " sendnow ); +.fi +.IP +This routine can be invoked only on streams created by +.BR xdrrec_create (). +The data in the output buffer is marked as a completed record, +and the output buffer is optionally written out if +.I sendnow +is nonzero. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdrrec_eof(XDR *" xdrs ); +.fi +.IP +This routine can be invoked only on streams created by +.BR xdrrec_create (). +After consuming the rest of the current record in the stream, +this routine returns one if the stream has no more input, +zero otherwise. +.P +.nf +.BI "bool_t xdrrec_skiprecord(XDR *" xdrs ); +.fi +.IP +This routine can be invoked only on +streams created by +.BR xdrrec_create (). +It tells the XDR implementation that the rest of the current record +in the stream's input buffer should be discarded. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_reference(XDR *" xdrs ", char **" pp ", unsigned int " size , +.BI " xdrproc_t " proc ); +.fi +.IP +A primitive that provides pointer chasing within structures. +The argument +.I pp +is the address of the pointer; +.I size +is the +.I sizeof +the structure that +.I *pp +points to; and +.I proc +is an XDR procedure that filters the structure +between its C form and its external representation. +This routine returns one if it succeeds, zero otherwise. +.IP +Warning: this routine does not understand null pointers. +Use +.BR xdr_pointer () +instead. +.P +.nf +.BI "xdr_setpos(XDR *" xdrs ", unsigned int " pos ); +.fi +.IP +A macro that invokes the set position routine associated with +the XDR stream +.IR xdrs . +The argument +.I pos +is a position value obtained from +.BR xdr_getpos (). +This routine returns one if the XDR stream could be repositioned, +and zero otherwise. +.IP +Warning: it is difficult to reposition some types of XDR +streams, so this routine may fail with one +type of stream and succeed with another. +.P +.nf +.BI "bool_t xdr_short(XDR *" xdrs ", short *" sp ); +.fi +.IP +A filter primitive that translates between C +.I short +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "void xdrstdio_create(XDR *" xdrs ", FILE *" file ", enum xdr_op " op ); +.fi +.IP +This routine initializes the XDR stream object pointed to by +.IR xdrs . +The XDR stream data is written to, or read from, the +.I stdio +stream +.IR file . +The argument +.I op +determines the direction of the XDR stream (either +.BR XDR_ENCODE , +.BR XDR_DECODE , +or +.BR XDR_FREE ). +.IP +Warning: the destroy routine associated with such XDR streams calls +.BR fflush (3) +on the +.I file +stream, but never +.BR fclose (3). +.P +.nf +.BI "bool_t xdr_string(XDR *" xdrs ", char **" sp ", unsigned int " maxsize ); +.fi +.IP +A filter primitive that translates between C strings and +their corresponding external representations. +Strings cannot be longer than +.IR maxsize . +Note: +.I sp +is the address of the string's pointer. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_u_char(XDR *" xdrs ", unsigned char *" ucp ); +.fi +.IP +A filter primitive that translates between +.I unsigned +C characters and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned int *" up ); +.fi +.IP +A filter primitive that translates between C +.I unsigned +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_u_long(XDR *" xdrs ", unsigned long *" ulp ); +.fi +.IP +A filter primitive that translates between C +.I "unsigned long" +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_u_short(XDR *" xdrs ", unsigned short *" usp ); +.fi +.IP +A filter primitive that translates between C +.I "unsigned short" +integers and their external representations. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_union(XDR *" xdrs ", enum_t *" dscmp ", char *" unp , +.BI " const struct xdr_discrim *" choices , +.BI " xdrproc_t " defaultarm "); /* may equal NULL */" +.fi +.IP +A filter primitive that translates between a discriminated C +.I union +and its corresponding external representation. +It first +translates the discriminant of the union located at +.IR dscmp . +This discriminant is always an +.IR enum_t . +Next the union located at +.I unp +is translated. +The argument +.I choices +is a pointer to an array of +.BR xdr_discrim () +structures. +Each structure contains an ordered pair of +.RI [ value , proc ]. +If the union's discriminant is equal to the associated +.IR value , +then the +.I proc +is called to translate the union. +The end of the +.BR xdr_discrim () +structure array is denoted by a routine of value NULL. +If the discriminant is not found in the +.I choices +array, then the +.I defaultarm +procedure is called (if it is not NULL). +Returns one if it succeeds, zero otherwise. +.P +.nf +.BI "bool_t xdr_vector(XDR *" xdrs ", char *" arrp ", unsigned int " size , +.BI " unsigned int " elsize ", xdrproc_t " elproc ); +.fi +.IP +A filter primitive that translates between fixed-length arrays +and their corresponding external representations. +The argument +.I arrp +is the address of the pointer to the array, while +.I size +is the element count of the array. +The argument +.I elsize +is the +.I sizeof +each of the array's elements, and +.I elproc +is an XDR filter that translates between +the array elements' C form, and their external +representation. +This routine returns one if it succeeds, zero otherwise. +.P +.nf +.B bool_t xdr_void(void); +.fi +.IP +This routine always returns one. +It may be passed to RPC routines that require a function argument, +where nothing is to be done. +.P +.nf +.BI "bool_t xdr_wrapstring(XDR *" xdrs ", char **" sp ); +.fi +.IP +A primitive that calls +.B "xdr_string(xdrs, sp,MAXUN.UNSIGNED );" +where +.B MAXUN.UNSIGNED +is the maximum value of an unsigned integer. +.BR xdr_wrapstring () +is handy because the RPC package passes a maximum of two XDR +routines as arguments, and +.BR xdr_string (), +one of the most frequently used primitives, requires three. +Returns one if it succeeds, zero otherwise. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR xdr_array (), +.BR xdr_bool (), +.BR xdr_bytes (), +.BR xdr_char (), +.BR xdr_destroy (), +.BR xdr_double (), +.BR xdr_enum (), +.BR xdr_float (), +.BR xdr_free (), +.BR xdr_getpos (), +.BR xdr_inline (), +.BR xdr_int (), +.BR xdr_long (), +.BR xdrmem_create (), +.BR xdr_opaque (), +.BR xdr_pointer (), +.BR xdrrec_create (), +.BR xdrrec_eof (), +.BR xdrrec_endofrecord (), +.BR xdrrec_skiprecord (), +.BR xdr_reference (), +.BR xdr_setpos (), +.BR xdr_short (), +.BR xdrstdio_create (), +.BR xdr_string (), +.BR xdr_u_char (), +.BR xdr_u_int (), +.BR xdr_u_long (), +.BR xdr_u_short (), +.BR xdr_union (), +.BR xdr_vector (), +.BR xdr_void (), +.BR xdr_wrapstring () +T} Thread safety MT-Safe +.TE +.SH SEE ALSO +.BR rpc (3) +.P +The following manuals: +.RS +eXternal Data Representation Standard: Protocol Specification +.br +eXternal Data Representation: Sun Technical Notes +.br +.IR "XDR: External Data Representation Standard" , +RFC\ 1014, Sun Microsystems, Inc., +USC-ISI. +.RE diff --git a/man/man3/xdr_accepted_reply.3 b/man/man3/xdr_accepted_reply.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_accepted_reply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_array.3 b/man/man3/xdr_array.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_array.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_authunix_parms.3 b/man/man3/xdr_authunix_parms.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_authunix_parms.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_bool.3 b/man/man3/xdr_bool.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_bool.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_bytes.3 b/man/man3/xdr_bytes.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_bytes.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_callhdr.3 b/man/man3/xdr_callhdr.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_callhdr.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_callmsg.3 b/man/man3/xdr_callmsg.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_callmsg.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_char.3 b/man/man3/xdr_char.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_char.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_destroy.3 b/man/man3/xdr_destroy.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_destroy.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_double.3 b/man/man3/xdr_double.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_double.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_enum.3 b/man/man3/xdr_enum.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_enum.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_float.3 b/man/man3/xdr_float.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_float.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_free.3 b/man/man3/xdr_free.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_free.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_getpos.3 b/man/man3/xdr_getpos.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_getpos.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_inline.3 b/man/man3/xdr_inline.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_inline.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_int.3 b/man/man3/xdr_int.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_int.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_long.3 b/man/man3/xdr_long.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_long.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_opaque.3 b/man/man3/xdr_opaque.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_opaque.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_opaque_auth.3 b/man/man3/xdr_opaque_auth.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_opaque_auth.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_pmap.3 b/man/man3/xdr_pmap.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_pmap.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_pmaplist.3 b/man/man3/xdr_pmaplist.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_pmaplist.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_pointer.3 b/man/man3/xdr_pointer.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_pointer.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_reference.3 b/man/man3/xdr_reference.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_reference.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_rejected_reply.3 b/man/man3/xdr_rejected_reply.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_rejected_reply.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_replymsg.3 b/man/man3/xdr_replymsg.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xdr_replymsg.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xdr_setpos.3 b/man/man3/xdr_setpos.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_setpos.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_short.3 b/man/man3/xdr_short.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_short.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_string.3 b/man/man3/xdr_string.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_string.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_u_char.3 b/man/man3/xdr_u_char.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_u_char.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_u_int.3 b/man/man3/xdr_u_int.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_u_int.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_u_long.3 b/man/man3/xdr_u_long.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_u_long.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_u_short.3 b/man/man3/xdr_u_short.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_u_short.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_union.3 b/man/man3/xdr_union.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_union.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_vector.3 b/man/man3/xdr_vector.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_vector.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_void.3 b/man/man3/xdr_void.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_void.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdr_wrapstring.3 b/man/man3/xdr_wrapstring.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdr_wrapstring.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrmem_create.3 b/man/man3/xdrmem_create.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrmem_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrrec_create.3 b/man/man3/xdrrec_create.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrrec_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrrec_endofrecord.3 b/man/man3/xdrrec_endofrecord.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrrec_endofrecord.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrrec_eof.3 b/man/man3/xdrrec_eof.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrrec_eof.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrrec_skiprecord.3 b/man/man3/xdrrec_skiprecord.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrrec_skiprecord.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xdrstdio_create.3 b/man/man3/xdrstdio_create.3 new file mode 100644 index 0000000..7ff092d --- /dev/null +++ b/man/man3/xdrstdio_create.3 @@ -0,0 +1 @@ +.so man3/xdr.3 diff --git a/man/man3/xencrypt.3 b/man/man3/xencrypt.3 new file mode 100644 index 0000000..01b6ce6 --- /dev/null +++ b/man/man3/xencrypt.3 @@ -0,0 +1 @@ +.so man3/xcrypt.3 diff --git a/man/man3/xprt_register.3 b/man/man3/xprt_register.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xprt_register.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/xprt_unregister.3 b/man/man3/xprt_unregister.3 new file mode 100644 index 0000000..b184711 --- /dev/null +++ b/man/man3/xprt_unregister.3 @@ -0,0 +1 @@ +.so man3/rpc.3 diff --git a/man/man3/y0.3 b/man/man3/y0.3 new file mode 100644 index 0000000..af9628f --- /dev/null +++ b/man/man3/y0.3 @@ -0,0 +1,276 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sat Jul 24 19:08:17 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2002-08-25, aeb +.\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB +.\" 2008-07-24, mtk, created this page, based on material from j0.3. +.\" +.TH y0 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +y0, y0f, y0l, y1, y1f, y1l, yn, ynf, ynl \- +Bessel functions of the second kind +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "double y0(double " x ); +.BI "double y1(double " x ); +.BI "double yn(int " n ", double " x ); +.P +.BI "float y0f(float " x ); +.BI "float y1f(float " x ); +.BI "float ynf(int " n ", float " x ); +.P +.BI "long double y0l(long double " x ); +.BI "long double y1l(long double " x ); +.BI "long double ynl(int " n ", long double " x ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR y0 (), +.BR y1 (), +.BR yn (): +.nf + _XOPEN_SOURCE + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.P +.BR y0f (), +.BR y0l (), +.BR y1f (), +.BR y1l (), +.BR ynf (), +.BR ynl (): +.nf + _XOPEN_SOURCE >= 600 + || (_ISOC99_SOURCE && _XOPEN_SOURCE) + || /* Since glibc 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR y0 () +and +.BR y1 () +functions return Bessel functions of +.I x +of the second kind of orders 0 and 1, respectively. +The +.BR yn () +function +returns the Bessel function of +.I x +of the second kind of order +.IR n . +.P +The value of +.I x +must be positive. +.P +The +.BR y0f (), +.BR y1f (), +and +.BR ynf () +functions are versions that take and return +.I float +values. +The +.BR y0l (), +.BR y1l (), +and +.BR ynl () +functions are versions that take and return +.I "long double" +values. +.SH RETURN VALUE +On success, these functions return the appropriate +Bessel value of the second kind for +.IR x . +.P +If +.I x +is a NaN, a NaN is returned. +.P +If +.I x +is negative, +a domain error occurs, +and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +(POSIX.1-2001 also allows a NaN return for this case.) +.P +If +.I x +is 0.0, +a pole error occurs, +and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +.P +If the result underflows, +a range error occurs, +and the functions return 0.0 +.P +If the result overflows, +a range error occurs, +and the functions return +.RB \- HUGE_VAL , +.RB \- HUGE_VALF , +or +.RB \- HUGE_VALL , +respectively. +(POSIX.1-2001 also allows a 0.0 return for this case.) +.SH ERRORS +See +.BR math_error (7) +for information on how to determine whether an error has occurred +when calling these functions. +.P +The following errors can occur: +.TP +Domain error: \fIx\fP is negative +.I errno +is set to +.BR EDOM . +An invalid floating-point exception +.RB ( FE_INVALID ) +is raised. +.TP +Pole error: \fIx\fP is 0.0 +.\" Before POSIX.1-2001 TC2, this was (inconsistently) specified +.\" as a range error. +.I errno +is set to +.B ERANGE +and an +.B FE_DIVBYZERO +exception is raised +(but see BUGS). +.TP +Range error: result underflow +.\" e.g., y0(1e33) on glibc 2.8/x86-32 +.I errno +is set to +.BR ERANGE . +No +.B FE_UNDERFLOW +exception is returned by +.\" This is intended behavior +.\" See https://www.sourceware.org/bugzilla/show_bug.cgi?id=6806 +.BR fetestexcept (3) +for this case. +.TP +Range error: result overflow +.\" e.g., yn(10, 1e-40) on glibc 2.8/x86-32 +.I errno +is set to +.B ERANGE +(but see BUGS). +An overflow floating-point exception +.RB ( FE_OVERFLOW ) +is raised. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR y0 (), +.BR y0f (), +.BR y0l () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR y1 (), +.BR y1f (), +.BR y1l () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR yn (), +.BR ynf (), +.BR ynl () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR y0 () +.TQ +.BR y1 () +.TQ +.BR yn () +POSIX.1-2008. +.TP +Others: +BSD. +.SH HISTORY +.TP +.BR y0 () +.TQ +.BR y1 () +.TQ +.BR yn () +SVr4, 4.3BSD, +POSIX.1-2001. +.TP +Others: +BSD. +.SH BUGS +Before glibc 2.19, +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6807 +these functions misdiagnosed pole errors: +.I errno +was set to +.BR EDOM , +instead of +.B ERANGE +and no +.B FE_DIVBYZERO +exception was raised. +.P +Before glibc 2.17, +.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6808 +did not set +.I errno +for "range error: result underflow". +.P +In glibc 2.3.2 and earlier, +.\" Actually, 2.3.2 is the earliest test result I have; so yet +.\" to confirm if this error occurs only in glibc 2.3.2. +these functions do not raise an invalid floating-point exception +.RB ( FE_INVALID ) +when a domain error occurs. +.SH SEE ALSO +.BR j0 (3) diff --git a/man/man3/y0f.3 b/man/man3/y0f.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/y0f.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/y0l.3 b/man/man3/y0l.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/y0l.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/y1.3 b/man/man3/y1.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/y1.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/y1f.3 b/man/man3/y1f.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/y1f.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/y1l.3 b/man/man3/y1l.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/y1l.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/yn.3 b/man/man3/yn.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/yn.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/ynf.3 b/man/man3/ynf.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/ynf.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3/ynl.3 b/man/man3/ynl.3 new file mode 100644 index 0000000..88b3c99 --- /dev/null +++ b/man/man3/ynl.3 @@ -0,0 +1 @@ +.so man3/y0.3 diff --git a/man/man3const/EOF.3const b/man/man3const/EOF.3const new file mode 100644 index 0000000..61a244f --- /dev/null +++ b/man/man3const/EOF.3const @@ -0,0 +1,42 @@ +.\" Copyright (c) 2022 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH EOF 3const 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +EOF \- end of file or error indicator +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR "#define EOF " "/* ... */" +.fi +.SH DESCRIPTION +.B EOF +represents the end of an input file, or an error indication. +It is a negative value, of type +.IR int . +.P +.B EOF +is not a character +(it can't be represented by +.IR "unsigned char" ). +It is instead a sentinel value outside of the valid range for valid characters. +.SH CONFORMING TO +C99 and later; +POSIX.1-2001 and later. +.SH CAVEATS +Programs can't pass this value to an output function +to "write" the end of a file. +That would likely result in undefined behavior. +Instead, +closing the writing stream or file descriptor +that refers to such file +is the way to signal the end of that file. +.SH SEE ALSO +.BR feof (3), +.BR fgetc (3) diff --git a/man/man3const/EXIT_FAILURE.3const b/man/man3const/EXIT_FAILURE.3const new file mode 100644 index 0000000..ba0d62d --- /dev/null +++ b/man/man3const/EXIT_FAILURE.3const @@ -0,0 +1 @@ +.so man3const/EXIT_SUCCESS.3const diff --git a/man/man3const/EXIT_SUCCESS.3const b/man/man3const/EXIT_SUCCESS.3const new file mode 100644 index 0000000..29228ee --- /dev/null +++ b/man/man3const/EXIT_SUCCESS.3const @@ -0,0 +1,61 @@ +.\" Copyright (c) 2022 by Thomas Voss +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH EXIT_SUCCESS 3const 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +EXIT_SUCCESS, EXIT_FAILURE \- termination status constants +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR "#define EXIT_SUCCESS " 0 +.BR "#define EXIT_FAILURE " "/* nonzero */" +.fi +.SH DESCRIPTION +.B EXIT_SUCCESS +and +.B EXIT_FAILURE +represent a successful and unsuccessful exit status respectively, +and can be used as arguments to the +.BR exit (3) +function. +.SH CONFORMING TO +C99 and later; +POSIX.1-2001 and later. +.SH EXAMPLES +.\" SRC BEGIN (EXIT_SUCCESS.c) +.EX +#include +#include +\& +int +main(int argc, char *argv[]) +{ + FILE *fp; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \en", argv[0]); + exit(EXIT_FAILURE); + } +\& + fp = fopen(argv[1], "r"); + if (fp == NULL) { + perror(argv[1]); + exit(EXIT_FAILURE); + } +\& + /* Other code omitted */ +\& + fclose(fp); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR exit (3), +.BR sysexits.h (3head) diff --git a/man/man3const/NULL.3const b/man/man3const/NULL.3const new file mode 100644 index 0000000..c9cdc37 --- /dev/null +++ b/man/man3const/NULL.3const @@ -0,0 +1,74 @@ +.\" Copyright (c) 2022 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH NULL 3const 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +NULL \- null pointer constant +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.B "#define NULL ((void *) 0)" +.fi +.SH DESCRIPTION +.B NULL +represents a null pointer constant, +that is, a pointer that does not point to anything. +.SH CONFORMING TO +C99 and later; +POSIX.1-2001 and later. +.SH NOTES +The following headers also provide +.BR NULL : +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.SH CAVEATS +It is undefined behavior to dereference a null pointer, +and that usually causes a segmentation fault in practice. +.P +It is also undefined behavior to perform pointer arithmetic on it. +.P +.I NULL \- NULL +is undefined behavior, according to ISO C, but is defined to be 0 in C++. +.P +To avoid confusing human readers of the code, +do not compare pointer variables to +.BR 0 , +and do not assign +.B 0 +to them. +Instead, always use +.BR NULL . +.P +.B NULL +shouldn't be confused with +.BR NUL , +which is an +.BR ascii (7) +character, +represented in C as +.BR \[aq]\e0\[aq] . +.SH BUGS +When it is necessary to set a pointer variable to a null pointer, +it is not enough to use +.BR memset (3) +to zero the pointer +(this is usually done when zeroing a struct that contains pointers), +since ISO C and POSIX don't guarantee that a bit pattern of all 0s +represent a null pointer. +See the EXAMPLES section in +.BR getaddrinfo (3) +for an example program that does this correctly. +.SH SEE ALSO +.BR void (3type) diff --git a/man/man3const/PA_CHAR.3const b/man/man3const/PA_CHAR.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_CHAR.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_DOUBLE.3const b/man/man3const/PA_DOUBLE.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_DOUBLE.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_FLAG_LONG.3const b/man/man3const/PA_FLAG_LONG.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_FLAG_LONG.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_FLAG_LONG_DOUBLE.3const b/man/man3const/PA_FLAG_LONG_DOUBLE.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_FLAG_LONG_DOUBLE.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_FLAG_LONG_LONG.3const b/man/man3const/PA_FLAG_LONG_LONG.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_FLAG_LONG_LONG.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_FLAG_PTR.3const b/man/man3const/PA_FLAG_PTR.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_FLAG_PTR.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_FLAG_SHORT.3const b/man/man3const/PA_FLAG_SHORT.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_FLAG_SHORT.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_FLOAT.3const b/man/man3const/PA_FLOAT.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_FLOAT.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_INT.3const b/man/man3const/PA_INT.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_INT.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_LAST.3const b/man/man3const/PA_LAST.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_LAST.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_POINTER.3const b/man/man3const/PA_POINTER.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_POINTER.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_STRING.3const b/man/man3const/PA_STRING.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_STRING.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_WCHAR.3const b/man/man3const/PA_WCHAR.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_WCHAR.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3const/PA_WSTRING.3const b/man/man3const/PA_WSTRING.3const new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3const/PA_WSTRING.3const @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3head/printf.h.3head b/man/man3head/printf.h.3head new file mode 100644 index 0000000..6d809d2 --- /dev/null +++ b/man/man3head/printf.h.3head @@ -0,0 +1,582 @@ +.\" Copyright (C) 2022 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH printf.h 3head 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +printf.h, +\%register_printf_specifier, +\%register_printf_modifier, +\%register_printf_type, +\%printf_function, +\%printf_arginfo_size_function, +\%printf_va_arg_function, +\%printf_info, +\%PA_INT, +\%PA_CHAR, +\%PA_WCHAR, +\%PA_STRING, +\%PA_WSTRING, +\%PA_POINTER, +\%PA_FLOAT, +\%PA_DOUBLE, +\%PA_LAST, +\%PA_FLAG_LONG_LONG, +\%PA_FLAG_LONG_DOUBLE, +\%PA_FLAG_LONG, +\%PA_FLAG_SHORT, +\%PA_FLAG_PTR +\- define custom behavior for printf-like functions +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int register_printf_specifier(int " spec ", printf_function " func , +.BI " printf_arginfo_size_function " arginfo ); +.BI "int register_printf_modifier(const wchar_t *" str ); +.BI "int register_printf_type(printf_va_arg_function " fct ); +.fi +.SS Callbacks +.nf +.BI "typedef int printf_function(FILE *" stream ", const struct printf_info *" info , +.BI " const void *const " args []); +.BI "typedef int printf_arginfo_size_function(const struct printf_info *" info , +.BI " size_t " n ", int " argtypes [ n "], int " size [ n ]); +.BI "typedef void printf_va_arg_function(void *" mem ", va_list *" ap ); +.fi +.SS Types +.EX +.B struct printf_info { +.BR " int prec; " "// Precision" +.BR " int width; " "// Width" +.BR " wchar_t spec; " "// Format letter" +.BR " unsigned int is_long_double:1;" "// " L " or " ll " flag" +.BR " unsigned int is_short:1; " "// " h " flag" +.BR " unsigned int is_long:1; " "// " l " flag" +.BR " unsigned int alt:1; " "// " # " flag" +.BR " unsigned int space:1; " "// Space flag" +.BR " unsigned int left:1; " "// " - " flag" +.BR " unsigned int showsign:1; " "// " + " flag" +.BR " unsigned int group:1; " "// " \[aq] " flag" +.BR " unsigned int extra:1; " "// For special use" +.BR " unsigned int is_char:1; " "// " hh " flag" +.BR " unsigned int wide:1; " "// True for wide character streams" +.BR " unsigned int i18n:1; " "// " I " flag" +.BR " unsigned int is_binary128:1; " "/* Floating-point argument is" +.BR " " " ABI-compatible with" +.BR " " " IEC 60559 binary128 */" +.BR " unsigned short user; " "// Bits for user-installed modifiers" +.BR " wchar_t pad; " "// Padding character" +.B }; +.EE +.SS Constants +.EX +.BR "#define PA_FLAG_LONG_LONG " "/* ... */" +.BR "#define PA_FLAG_LONG_DOUBLE " "/* ... */" +.BR "#define PA_FLAG_LONG " "/* ... */" +.BR "#define PA_FLAG_SHORT " "/* ... */" +.BR "#define PA_FLAG_PTR " "/* ... */" +.EE +.SH DESCRIPTION +These functions serve to extend and/or modify the behavior of the +.BR printf (3) +family of functions. +.SS register_printf_specifier() +This function registers a custom conversion specifier for the +.BR printf (3) +family of functions. +.TP +.I spec +The character which will be used as a conversion specifier in the format string. +.TP +.I func +Callback function that will be executed by the +.BR printf (3) +family of functions +to format the input arguments into the output +.IR stream . +.RS +.TP +.I stream +Output stream where the formatted output should be printed. +This stream transparently represents the output, +even in the case of functions that write to a string. +.TP +.I info +Structure that holds context information, +including the modifiers specified in the format string. +This holds the same contents as in +.IR arginfo . +.TP +.I args +Array of pointers to the arguments to the +.BR printf (3)\c +-like function. +.RE +.TP +.I arginfo +Callback function that will be executed by the +.BR printf (3) +family of functions +to know how many arguments should be parsed for the custom specifier +and also their types. +.RS +.TP +.I info +Structure that holds context information, +including the modifiers specified in the format string. +This holds the same contents as in +.IR func . +.TP +.I n +Number of arguments remaining to be parsed. +.TP +.I argtypes +This array should be set to +define the type of each of the arguments that will be parsed. +Each element in the array represents one of the arguments to be parsed, +in the same order that they are passed to the +.BR printf (3)\c +-like function. +Each element should be set to a base type +.RB ( PA_ *) +from the enum above, +or a custom one, +and optionally ORed with an appropriate length modifier +.RB ( PA_FLAG_ *). +.RS +.P +The type is determined by using one of the following constants: +.TP +.B PA_INT +.IR int . +.TP +.B PA_CHAR +.IR int , +cast to +.IR char . +.TP +.B PA_WCHAR +.IR wchar_t . +.TP +.B PA_STRING +.IR "const char\~*" , +a \(aq\e0\(aq-terminated string. +.TP +.B PA_WSTRING +.IR "const wchar_t\~*" , +a wide character L\(aq\e0\(aq-terminated string. +.TP +.B PA_POINTER +.IR void\~* . +.TP +.B PA_FLOAT +.IR float . +.TP +.B PA_DOUBLE +.IR double . +.TP +.B PA_LAST +TODO. +.RE +.TP +.I size +For user-defined types, +the size of the type (in bytes) should also be specified through this array. +Otherwise, leave it unused. +.RE +.P +.I arginfo +is called before +.IR func , +and prepares some information needed to call +.IR func . +.SS register_printf_modifier() +TODO +.SS register_printf_type() +TODO +.SH RETURN VALUE +.BR \%register_printf_specifier (), +.BR \%register_printf_modifier (), +and +.BR \%register_printf_type () +return zero on success, or \-1 on error. +.SS Callbacks +The callback of type +.I printf_function +should return the number of characters written, +or \-1 on error. +.P +The callback of type +.I \%printf_arginfo_size_function +should return the number of arguments to be parsed by this specifier. +It also passes information about the type of those arguments +to the caller through +.IR argtypes . +On error, it should return \-1. +.SH ERRORS +.TP +.B EINVAL +The specifier was not a valid character. +.SH STANDARDS +GNU. +.SH HISTORY +.BR \%register_printf_function (3) +is an older function similar to +.BR \%register_printf_specifier (), +and is now deprecated. +That function can't handle user-defined types. +.P +.BR \%register_printf_specifier () +supersedes +.BR \%register_printf_function (3). +.SH EXAMPLES +The following example program registers the 'b' and 'B' specifiers +to print integers in binary format, +mirroring rules for other unsigned conversion specifiers like 'x' and 'u'. +This can be used to print in binary prior to C23. +.P +.\" SRC BEGIN (register_printf_specifier.c) +.EX +/* This code is in the public domain */ +\& +#include +#include +#include +#include +#include +#include +#include +#include +\& +#include +\& +#define GROUP_SEP \[aq]\e\[aq]\[aq] +\& +struct Printf_Pad { + char ch; + size_t len; +}; +\& +static int b_printf(FILE *stream, const struct printf_info *info, + const void *const args[]); +static int b_arginf_sz(const struct printf_info *info, + size_t n, int argtypes[n], int size[n]); +\& +static uintmax_t b_value(const struct printf_info *info, + const void *arg); +static size_t b_bin_repr(char bin[UINTMAX_WIDTH], + const struct printf_info *info, const void *arg); +static size_t b_bin_len(const struct printf_info *info, + ptrdiff_t min_len); +static size_t b_pad_len(const struct printf_info *info, + ptrdiff_t bin_len); +static ssize_t b_print_prefix(FILE *stream, + const struct printf_info *info); +static ssize_t b_pad_zeros(FILE *stream, const struct printf_info *info, + ptrdiff_t min_len); +static ssize_t b_print_number(FILE *stream, + const struct printf_info *info, + const char bin[UINTMAX_WIDTH], + size_t min_len, size_t bin_len); +static char pad_ch(const struct printf_info *info); +static ssize_t pad_spaces(FILE *stream, size_t pad_len); +\& +int +main(void) +{ + if (register_printf_specifier(\[aq]b\[aq], b_printf, b_arginf_sz) == \-1) + err(EXIT_FAILURE, "register_printf_specifier(\[aq]b\[aq], ...)"); + if (register_printf_specifier(\[aq]B\[aq], b_printf, b_arginf_sz) == \-1) + err(EXIT_FAILURE, "register_printf_specifier(\[aq]B\[aq], ...)"); +\& + printf("....----....----....----....----\en"); + printf("%llb;\en", 0x5Ellu); + printf("%lB;\en", 0x5Elu); + printf("%b;\en", 0x5Eu); + printf("%hB;\en", 0x5Eu); + printf("%hhb;\en", 0x5Eu); + printf("%jb;\en", (uintmax_t)0x5E); + printf("%zb;\en", (size_t)0x5E); + printf("....----....----....----....----\en"); + printf("%#b;\en", 0x5Eu); + printf("%#B;\en", 0x5Eu); + printf("....----....----....----....----\en"); + printf("%10b;\en", 0x5Eu); + printf("%010b;\en", 0x5Eu); + printf("%.10b;\en", 0x5Eu); + printf("....----....----....----....----\en"); + printf("%\-10B;\en", 0x5Eu); + printf("....----....----....----....----\en"); + printf("%\[aq]B;\en", 0x5Eu); + printf("....----....----....----....----\en"); + printf("....----....----....----....----\en"); + printf("%#16.12b;\en", 0xAB); + printf("%\-#\[aq]20.12b;\en", 0xAB); + printf("%#\[aq]020B;\en", 0xAB); + printf("....----....----....----....----\en"); + printf("%#020B;\en", 0xAB); + printf("%\[aq]020B;\en", 0xAB); + printf("%020B;\en", 0xAB); + printf("....----....----....----....----\en"); + printf("%#021B;\en", 0xAB); + printf("%\[aq]021B;\en", 0xAB); + printf("%021B;\en", 0xAB); + printf("....----....----....----....----\en"); + printf("%#022B;\en", 0xAB); + printf("%\[aq]022B;\en", 0xAB); + printf("%022B;\en", 0xAB); + printf("....----....----....----....----\en"); + printf("%#023B;\en", 0xAB); + printf("%\[aq]023B;\en", 0xAB); + printf("%023B;\en", 0xAB); + printf("....----....----....----....----\en"); + printf("%\-#\[aq]19.11b;\en", 0xAB); + printf("%#\[aq]019B;\en", 0xAB); + printf("%#019B;\en", 0xAB); + printf("....----....----....----....----\en"); + printf("%\[aq]019B;\en", 0xAB); + printf("%019B;\en", 0xAB); + printf("%#016b;\en", 0xAB); + printf("....----....----....----....----\en"); +\& + return 0; +} +\& +static int +b_printf(FILE *stream, const struct printf_info *info, + const void *const args[]) +{ + char bin[UINTMAX_WIDTH]; + size_t min_len, bin_len; + ssize_t len, tmp; + struct Printf_Pad pad = {0}; +\& + len = 0; +\& + min_len = b_bin_repr(bin, info, args[0]); + bin_len = b_bin_len(info, min_len); +\& + pad.ch = pad_ch(info); + if (pad.ch == \[aq] \[aq]) + pad.len = b_pad_len(info, bin_len); +\& + /* Padding with \[aq] \[aq] (right aligned) */ + if ((pad.ch == \[aq] \[aq]) && !info->left) { + tmp = pad_spaces(stream, pad.len); + if (tmp == EOF) + return EOF; + len += tmp; + } +\& + /* "0b"/"0B" prefix */ + if (info->alt) { + tmp = b_print_prefix(stream, info); + if (tmp == EOF) + return EOF; + len += tmp; + } +\& + /* Padding with \[aq]0\[aq] */ + if (pad.ch == \[aq]0\[aq]) { + tmp = b_pad_zeros(stream, info, min_len); + if (tmp == EOF) + return EOF; + len += tmp; + } +\& + /* Print number (including leading 0s to fill precision) */ + tmp = b_print_number(stream, info, bin, min_len, bin_len); + if (tmp == EOF) + return EOF; + len += tmp; +\& + /* Padding with \[aq] \[aq] (left aligned) */ + if (info\->left) { + tmp = pad_spaces(stream, pad.len); + if (tmp == EOF) + return EOF; + len += tmp; + } +\& + return len; +} +\& +static int +b_arginf_sz(const struct printf_info *info, size_t n, int argtypes[n], + [[maybe_unused]] int size[n]) +{ + if (n < 1) + return \-1; +\& + if (info\->is_long_double) + argtypes[0] = PA_INT | PA_FLAG_LONG_LONG; + else if (info\->is_long) + argtypes[0] = PA_INT | PA_FLAG_LONG; + else + argtypes[0] = PA_INT; +\& + return 1; +} +\& +static uintmax_t +b_value(const struct printf_info *info, const void *arg) +{ + if (info\->is_long_double) + return *(const unsigned long long *)arg; + if (info\->is_long) + return *(const unsigned long *)arg; +\& + /* short and char are both promoted to int */ + return *(const unsigned int *)arg; +} +\& +static size_t +b_bin_repr(char bin[UINTMAX_WIDTH], + const struct printf_info *info, const void *arg) +{ + size_t min_len; + uintmax_t val; +\& + val = b_value(info, arg); +\& + bin[0] = \[aq]0\[aq]; + for (min_len = 0; val; min_len++) { + bin[min_len] = \[aq]0\[aq] + (val % 2); + val >>= 1; + } +\& + return MAX(min_len, 1); +} +\& +static size_t +b_bin_len(const struct printf_info *info, ptrdiff_t min_len) +{ + return MAX(info\->prec, min_len); +} +\& +static size_t +b_pad_len(const struct printf_info *info, ptrdiff_t bin_len) +{ + ptrdiff_t pad_len; +\& + pad_len = info\->width \- bin_len; + if (info\->alt) + pad_len \-= 2; + if (info\->group) + pad_len \-= (bin_len \- 1) / 4; +\& + return MAX(pad_len, 0); +} +\& +static ssize_t +b_print_prefix(FILE *stream, const struct printf_info *info) +{ + ssize_t len; +\& + len = 0; + if (fputc(\[aq]0\[aq], stream) == EOF) + return EOF; + len++; + if (fputc(info\->spec, stream) == EOF) + return EOF; + len++; +\& + return len; +} +\& +static ssize_t +b_pad_zeros(FILE *stream, const struct printf_info *info, + ptrdiff_t min_len) +{ + ssize_t len; + ptrdiff_t tmp; +\& + len = 0; + tmp = info\->width \- (info\->alt * 2); + if (info\->group) + tmp \-= tmp / 5 \- !(tmp % 5); + for (ptrdiff_t i = tmp \- 1; i > min_len \- 1; i\-\-) { + if (fputc(\[aq]0\[aq], stream) == EOF) + return EOF; + len++; +\& + if (!info\->group || (i % 4)) + continue; + if (fputc(GROUP_SEP, stream) == EOF) + return EOF; + len++; + } +\& + return len; +} +\& +static ssize_t +b_print_number(FILE *stream, const struct printf_info *info, + const char bin[UINTMAX_WIDTH], + size_t min_len, size_t bin_len) +{ + ssize_t len; +\& + len = 0; +\& + /* Print leading zeros to fill precision */ + for (size_t i = bin_len \- 1; i > min_len \- 1; i\-\-) { + if (fputc(\[aq]0\[aq], stream) == EOF) + return EOF; + len++; +\& + if (!info\->group || (i % 4)) + continue; + if (fputc(GROUP_SEP, stream) == EOF) + return EOF; + len++; + } +\& + /* Print number */ + for (size_t i = min_len \- 1; i < min_len; i\-\-) { + if (fputc(bin[i], stream) == EOF) + return EOF; + len++; +\& + if (!info\->group || (i % 4) || !i) + continue; + if (fputc(GROUP_SEP, stream) == EOF) + return EOF; + len++; + } +\& + return len; +} +\& +static char +pad_ch(const struct printf_info *info) +{ + if ((info\->prec != \-1) || (info\->pad == \[aq] \[aq]) || info\->left) + return \[aq] \[aq]; + return \[aq]0\[aq]; +} +\& +static ssize_t +pad_spaces(FILE *stream, size_t pad_len) +{ + ssize_t len; +\& + len = 0; + for (size_t i = pad_len - 1; i < pad_len; i\-\-) { + if (fputc(\[aq] \[aq], stream) == EOF) + return EOF; + len++; + } +\& + return len; +} +.EE +.\" SRC END +.SH SEE ALSO +.BR asprintf (3), +.BR printf (3), +.BR wprintf (3) diff --git a/man/man3head/sysexits.h.3head b/man/man3head/sysexits.h.3head new file mode 100644 index 0000000..93cd3f0 --- /dev/null +++ b/man/man3head/sysexits.h.3head @@ -0,0 +1,200 @@ +'\" t +.\" Copyright (c) 1996 Joerg Wunsch +.\" Copyright (c) 2022 Alejandro Colomar +.\" +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Rewritten for the Linux man-pages by Alejandro Colomar +.\" +.TH sysexits.h 3head 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sysexits.h \- exit codes for programs +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.fi +.TS +lB2 lB2 l1 lX. +#define EX_OK 0 /* T{ +successful termination */ +T} +.P +#define EX__BASE 64 /* T{ +base value for error messages */ +T} +.P +#define EX_USAGE 64 /* T{ +command line usage error */ +T} +#define EX_DATAERR 65 /* T{ +data format error */ +T} +#define EX_NOINPUT 66 /* T{ +cannot open input */ +T} +#define EX_NOUSER 67 /* T{ +addressee unknown */ +T} +#define EX_NOHOST 68 /* T{ +host name unknown */ +T} +#define EX_UNAVAILABLE 69 /* T{ +service unavailable */ +T} +#define EX_SOFTWARE 70 /* T{ +internal software error */ +T} +#define EX_OSERR 71 /* T{ +system error (e.g., can't fork) */ +T} +#define EX_OSFILE 72 /* T{ +critical OS file missing */ +T} +#define EX_CANTCREAT 73 /* T{ +can't create (user) output file */ +T} +#define EX_IOERR 74 /* T{ +input/output error */ +T} +#define EX_TEMPFAIL 75 /* T{ +temp failure; user is invited to retry */ +T} +#define EX_PROTOCOL 76 /* T{ +remote error in protocol */ +T} +#define EX_NOPERM 77 /* T{ +permission denied */ +T} +#define EX_CONFIG 78 /* T{ +configuration error */ +T} +.P +.T& +lB2 l2 l1 lX. +#define EX__MAX ... /* T{ +maximum listed value */ +T} +.TE +.SH DESCRIPTION +A few programs exit with the following error codes. +.P +The successful exit is always indicated by a status of +.BR 0 , +or +.B EX_OK +(equivalent to +.B EXIT_SUCCESS +from +.IR ). +Error numbers begin at +.B EX__BASE +to reduce the possibility of clashing with other exit statuses +that random programs may already return. +The meaning of the code is approximately as follows: +.TP +.B EX_USAGE +The command was used incorrectly, +e.g., +with the wrong number of arguments, +a bad flag, +bad syntax in a parameter, +or whatever. +.TP +.B EX_DATAERR +The input data was incorrect in some way. +This should only be used for user's data and not system files. +.TP +.B EX_NOINPUT +An input file (not a system file) did not exist or was not readable. +This could also include errors like "No message" to a mailer +(if it cared to catch it). +.TP +.B EX_NOUSER +The user specified did not exist. +This might be used for mail addresses or remote logins. +.TP +.B EX_NOHOST +The host specified did not exist. +This is used in mail addresses or network requests. +.TP +.B EX_UNAVAILABLE +A service is unavailable. +This can occur if a support program or file does not exist. +This can also be used as a catch-all message +when something you wanted to do doesn't work, but you don't know why. +.TP +.B EX_SOFTWARE +An internal software error has been detected. +This should be limited to non-operating system related errors if possible. +.TP +.B EX_OSERR +An operating system error has been detected. +This is intended to be used for such things as +"cannot fork", +"cannot create pipe", +or the like. +It includes things like +.BR getuid (2) +returning a user that does not exist in the +.BR passwd (5) +file. +.TP +.B EX_OSFILE +Some system file +(e.g., +.IR /etc/passwd , +.IR /etc/utmp , +etc.) +does not exist, +cannot be opened, +or has some sort of error (e.g., syntax error). +.TP +.B EX_CANTCREAT +A (user specified) output file cannot be created. +.TP +.B EX_IOERR +An error occurred while doing I/O on some file. +.TP +.B EX_TEMPFAIL +Temporary failure, +indicating something that is not really an error. +For example that a mailer could not create a connection, +and the request should be reattempted later. +.TP +.B EX_PROTOCOL +The remote system returned something that +was "not possible" during a protocol exchange. +.TP +.B EX_OSFILE +You did not have sufficient permission to perform the operation. +This is not intended for file system problems, +which should use +.B EX_NOINPUT +or +.BR EX_CANTCREAT , +but rather for higher level permissions. +.TP +.B EX_CONFIG +Something was found in an unconfigured or misconfigured state. +.P +The numerical values corresponding to the symbolical ones +are given in parenthesis for easy reference. +.SH STANDARDS +BSD. +.SH HISTORY +The +.I +file appeared in 4.0BSD for use by the deliverymail utility, +later renamed to +.BR sendmail (8). +.SH CAVEATS +The choice of an appropriate exit value is often ambiguous. +.SH SEE ALSO +.BR err (3), +.BR error (3), +.BR exit (3) diff --git a/man/man3type/FILE.3type b/man/man3type/FILE.3type new file mode 100644 index 0000000..3bd1df1 --- /dev/null +++ b/man/man3type/FILE.3type @@ -0,0 +1,36 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH FILE 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +FILE \- input/output stream +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " FILE; +.fi +.SH DESCRIPTION +An object type used for streams. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH NOTES +The following header also provides this type: +.IR . +.SH SEE ALSO +.BR fclose (3), +.BR flockfile (3), +.BR fopen (3), +.BR fprintf (3), +.BR fread (3), +.BR fscanf (3), +.BR stdin (3), +.BR stdio (3) diff --git a/man/man3type/aiocb.3type b/man/man3type/aiocb.3type new file mode 100644 index 0000000..5ae2078 --- /dev/null +++ b/man/man3type/aiocb.3type @@ -0,0 +1,42 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH aiocb 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aiocb \- asynchronous I/O control block +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.B struct aiocb { +.BR " int aio_fildes;" " /* File descriptor */" +.BR " off_t aio_offset;" " /* File offset */" +.BR " volatile void *aio_buf;" " /* Location of buffer */" +.BR " size_t aio_nbytes;" " /* Length of transfer */" +.BR " int aio_reqprio;" " /* Request priority offset */" +.BR " struct sigevent aio_sigevent;" " /* Signal number and value */" +.BR " int aio_lio_opcode;" " /* Operation to be performed */" +.B }; +.EE +.SH DESCRIPTION +For further information about this structure, see +.BR aio (7). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_fsync (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_suspend (3), +.BR aio_write (3), +.BR lio_listio (3) diff --git a/man/man3type/blkcnt_t.3type b/man/man3type/blkcnt_t.3type new file mode 100644 index 0000000..c0d4cde --- /dev/null +++ b/man/man3type/blkcnt_t.3type @@ -0,0 +1,30 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH blkcnt_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +blkcnt_t \- file block counts +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " blkcnt_t; +.fi +.SH DESCRIPTION +Used for file block counts. +It is a signed integer type. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The following header also provides this type: +.IR . +.SH SEE ALSO +.BR stat (3type) diff --git a/man/man3type/blksize_t.3type b/man/man3type/blksize_t.3type new file mode 100644 index 0000000..92bc6ea --- /dev/null +++ b/man/man3type/blksize_t.3type @@ -0,0 +1,30 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH blksize_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +blksize_t \- file block sizes +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " blksize_t; +.fi +.SH DESCRIPTION +Used for file block sizes. +It is a signed integer type. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The following header also provides this type: +.IR . +.SH SEE ALSO +.BR stat (3type) diff --git a/man/man3type/cc_t.3type b/man/man3type/cc_t.3type new file mode 100644 index 0000000..369e353 --- /dev/null +++ b/man/man3type/cc_t.3type @@ -0,0 +1,35 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH cc_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cc_t, speed_t, tcflag_t \- terminal special characters, baud rates, modes +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " cc_t; +.BR typedef " /* ... */ " speed_t; +.BR typedef " /* ... */ " tcflag_t; +.fi +.SH DESCRIPTION +.I cc_t +is used for terminal special characters, +.I speed_t +for baud rates, and +.I tcflag_t +for modes. +.P +All are unsigned integer types. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR termios (3) diff --git a/man/man3type/clock_t.3type b/man/man3type/clock_t.3type new file mode 100644 index 0000000..04f176c --- /dev/null +++ b/man/man3type/clock_t.3type @@ -0,0 +1,37 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH clock_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clock_t \- system time +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " clock_t; +.fi +.SH DESCRIPTION +Used for system time in clock ticks or +.B CLOCKS_PER_SEC +(defined in +.IR ). +According to POSIX, +it is an integer type or a real-floating type. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH NOTES +The following headers also provide this type: +.I +and +.IR . +.SH SEE ALSO +.BR times (2), +.BR clock (3) diff --git a/man/man3type/clockid_t.3type b/man/man3type/clockid_t.3type new file mode 100644 index 0000000..5a3a916 --- /dev/null +++ b/man/man3type/clockid_t.3type @@ -0,0 +1,28 @@ +.TH clockid_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +clockid_t \- clock ID for the clock and timer functions +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " clockid_t; +.fi +.SH DESCRIPTION +Used for clock ID type in the clock and timer functions. +It is defined as an arithmetic type. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The following header also provides this type: +.IR . +.SH SEE ALSO +.BR clock_adjtime (2), +.BR clock_getres (2), +.BR clock_nanosleep (2), +.BR timer_create (2), +.BR clock_getcpuclockid (3) diff --git a/man/man3type/dev_t.3type b/man/man3type/dev_t.3type new file mode 100644 index 0000000..79636e1 --- /dev/null +++ b/man/man3type/dev_t.3type @@ -0,0 +1,33 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH dev_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dev_t \- device ID +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " dev_t; +.fi +.SH DESCRIPTION +Used for device IDs. +It is an integer type. +For further details of this type, see +.BR makedev (3). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The following header also provides this type: +.IR . +.SH SEE ALSO +.BR mknod (2), +.BR stat (3type) diff --git a/man/man3type/div_t.3type b/man/man3type/div_t.3type new file mode 100644 index 0000000..b8ac75b --- /dev/null +++ b/man/man3type/div_t.3type @@ -0,0 +1,59 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH div_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +div_t, ldiv_t, lldiv_t, imaxdiv_t \- +quotient and remainder of an integer division +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.B typedef struct { +.BR " int quot;" " /* Quotient */" +.BR " int rem;" " /* Remainder */" +.B } div_t; +.P +.B typedef struct { +.BR " long quot;" " /* Quotient */" +.BR " long rem;" " /* Remainder */" +.B } ldiv_t; +.P +.B typedef struct { +.BR " long long quot;" " /* Quotient */" +.BR " long long rem;" " /* Remainder */" +.B } lldiv_t; +.P +.B #include +.P +.B typedef struct { +.BR " intmax_t quot;" " /* Quotient */" +.BR " intmax_t rem;" " /* Remainder */" +.B } imaxdiv_t; +.EE +.SH DESCRIPTION +.RI [[ l ] l ] div_t +is the type of the value returned by the +.RB [[ l ] l ]\c +.BR div (3) +function. +.P +.I imaxdiv_t +is the type of the value returned by the +.BR imaxdiv (3) +function. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH SEE ALSO +.BR div (3), +.BR imaxdiv (3), +.BR ldiv (3), +.BR lldiv (3) diff --git a/man/man3type/double_t.3type b/man/man3type/double_t.3type new file mode 100644 index 0000000..d23cb61 --- /dev/null +++ b/man/man3type/double_t.3type @@ -0,0 +1,56 @@ +'\" t +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH double_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +float_t, double_t \- most efficient floating types +.SH LIBRARY +Math library +.RI ( libm ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " float_t; +.BR typedef " /* ... */ " double_t; +.fi +.SH DESCRIPTION +The implementation's most efficient floating types at least as wide as +.I float +and +.I double +respectively. +Their type depends on the value of the macro +.B FLT_EVAL_METHOD +(defined in +.IR ): +.P +.TS +lB rI rI. +FLT_EVAL_METHOD float_t double_t +.T& +n rI rI. +_ +0 float double +1 double double +2 long double long double +.TE +.P +For other values of +.BR FLT_EVAL_METHOD , +the types of +.I float_t +and +.I double_t +are implementation-defined. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH SEE ALSO +.BR float.h (0p), +.BR math.h (0p) diff --git a/man/man3type/epoll_data.3type b/man/man3type/epoll_data.3type new file mode 100644 index 0000000..033a55f --- /dev/null +++ b/man/man3type/epoll_data.3type @@ -0,0 +1 @@ +.so man3type/epoll_event.3type diff --git a/man/man3type/epoll_data_t.3type b/man/man3type/epoll_data_t.3type new file mode 100644 index 0000000..033a55f --- /dev/null +++ b/man/man3type/epoll_data_t.3type @@ -0,0 +1 @@ +.so man3type/epoll_event.3type diff --git a/man/man3type/epoll_event.3type b/man/man3type/epoll_event.3type new file mode 100644 index 0000000..e629d91 --- /dev/null +++ b/man/man3type/epoll_event.3type @@ -0,0 +1,55 @@ +.\" Copyright (c) 2022 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH epoll_event 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +epoll_event, epoll_data, epoll_data_t +\- epoll event +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.B struct epoll_event { +.BR " uint32_t events;" " /* Epoll events */" +.BR " epoll_data_t data;" " /* User data variable */" +.B }; +.P +.B union epoll_data { +.B " void *ptr;" +.B " int fd;" +.B " uint32_t u32;" +.B " uint64_t u64;" +.B }; +.P +.B "typedef union epoll_data epoll_data_t;" +.EE +.SH DESCRIPTION +The +.I epoll_event +structure specifies data that the kernel should save and +return when the corresponding file descriptor becomes ready. +.SH VERSIONS +.SS C library/kernel differences +The Linux kernel headers also provide this type, +with a slightly different definition: +.P +.in +4n +.EX +#include +\& +struct epoll_event { + __poll_t events; + __u64 data; +}; +.EE +.in +.SH STANDARDS +Linux. +.SH SEE ALSO +.BR epoll_wait (2), +.BR epoll_ctl (2) diff --git a/man/man3type/fenv_t.3type b/man/man3type/fenv_t.3type new file mode 100644 index 0000000..87c2fb3 --- /dev/null +++ b/man/man3type/fenv_t.3type @@ -0,0 +1,35 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH fenv_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fenv_t, fexcept_t \- floating-point environment +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " fenv_t; +.BR typedef " /* ... */ " fexcept_t; +.fi +.SH DESCRIPTION +.I fenv_t +represents the entire floating-point environment, +including control modes and status flags. +.P +.I fexcept_t +represents the floating-point status flags collectively. +.P +For further details see +.BR fenv (3). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH SEE ALSO +.BR fenv (3) diff --git a/man/man3type/fexcept_t.3type b/man/man3type/fexcept_t.3type new file mode 100644 index 0000000..5bedba0 --- /dev/null +++ b/man/man3type/fexcept_t.3type @@ -0,0 +1 @@ +.so man3type/fenv_t.3type diff --git a/man/man3type/float_t.3type b/man/man3type/float_t.3type new file mode 100644 index 0000000..104734c --- /dev/null +++ b/man/man3type/float_t.3type @@ -0,0 +1 @@ +.so man3type/double_t.3type diff --git a/man/man3type/gid_t.3type b/man/man3type/gid_t.3type new file mode 100644 index 0000000..52bae74 --- /dev/null +++ b/man/man3type/gid_t.3type @@ -0,0 +1 @@ +.so man3type/id_t.3type diff --git a/man/man3type/id_t.3type b/man/man3type/id_t.3type new file mode 100644 index 0000000..945bb22 --- /dev/null +++ b/man/man3type/id_t.3type @@ -0,0 +1,110 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH id_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pid_t, uid_t, gid_t, id_t \- process/user/group identifier +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " pid_t; +.BR typedef " /* ... */ " uid_t; +.BR typedef " /* ... */ " gid_t; +.BR typedef " /* ... */ " id_t; +.fi +.SH DESCRIPTION +.I pid_t +is a type used for storing process IDs, process group IDs, and session IDs. +It is a signed integer type. +.P +.I uid_t +is a type used to hold user IDs. +It is an integer type. +.P +.I gid_t +is a type used to hold group IDs. +It is an integer type. +.P +.I id_t +is a type used to hold a general identifier. +It is an integer type that can be used to contain a +.IR pid_t , +.IR uid_t , +or +.IR gid_t . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The following headers also provide +.IR pid_t : +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.P +The following headers also provide +.IR uid_t : +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.P +The following headers also provide +.IR gid_t : +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.P +The following header also provides +.IR id_t : +.IR . +.SH SEE ALSO +.BR chown (2), +.BR fork (2), +.BR getegid (2), +.BR geteuid (2), +.BR getgid (2), +.BR getgroups (2), +.BR getpgid (2), +.BR getpid (2), +.BR getppid (2), +.BR getpriority (2), +.BR getpwnam (3), +.BR getresgid (2), +.BR getresuid (2), +.BR getsid (2), +.BR gettid (2), +.BR getuid (2), +.BR kill (2), +.BR pidfd_open (2), +.BR sched_setscheduler (2), +.BR waitid (2), +.BR getgrnam (3), +.BR sigqueue (3), +.BR credentials (7) diff --git a/man/man3type/imaxdiv_t.3type b/man/man3type/imaxdiv_t.3type new file mode 100644 index 0000000..3ab8f34 --- /dev/null +++ b/man/man3type/imaxdiv_t.3type @@ -0,0 +1 @@ +.so man3type/div_t.3type diff --git a/man/man3type/in6_addr.3type b/man/man3type/in6_addr.3type new file mode 100644 index 0000000..39e914c --- /dev/null +++ b/man/man3type/in6_addr.3type @@ -0,0 +1 @@ +.so man3type/sockaddr.3type diff --git a/man/man3type/in_addr.3type b/man/man3type/in_addr.3type new file mode 100644 index 0000000..39e914c --- /dev/null +++ b/man/man3type/in_addr.3type @@ -0,0 +1 @@ +.so man3type/sockaddr.3type diff --git a/man/man3type/in_addr_t.3type b/man/man3type/in_addr_t.3type new file mode 100644 index 0000000..39e914c --- /dev/null +++ b/man/man3type/in_addr_t.3type @@ -0,0 +1 @@ +.so man3type/sockaddr.3type diff --git a/man/man3type/in_port_t.3type b/man/man3type/in_port_t.3type new file mode 100644 index 0000000..39e914c --- /dev/null +++ b/man/man3type/in_port_t.3type @@ -0,0 +1 @@ +.so man3type/sockaddr.3type diff --git a/man/man3type/int16_t.3type b/man/man3type/int16_t.3type new file mode 100644 index 0000000..a0d1a82 --- /dev/null +++ b/man/man3type/int16_t.3type @@ -0,0 +1 @@ +.so man3type/intN_t.3type diff --git a/man/man3type/int32_t.3type b/man/man3type/int32_t.3type new file mode 100644 index 0000000..a0d1a82 --- /dev/null +++ b/man/man3type/int32_t.3type @@ -0,0 +1 @@ +.so man3type/intN_t.3type diff --git a/man/man3type/int64_t.3type b/man/man3type/int64_t.3type new file mode 100644 index 0000000..a0d1a82 --- /dev/null +++ b/man/man3type/int64_t.3type @@ -0,0 +1 @@ +.so man3type/intN_t.3type diff --git a/man/man3type/int8_t.3type b/man/man3type/int8_t.3type new file mode 100644 index 0000000..a0d1a82 --- /dev/null +++ b/man/man3type/int8_t.3type @@ -0,0 +1 @@ +.so man3type/intN_t.3type diff --git a/man/man3type/intN_t.3type b/man/man3type/intN_t.3type new file mode 100644 index 0000000..b103f5d --- /dev/null +++ b/man/man3type/intN_t.3type @@ -0,0 +1,177 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH intN_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intN_t, int8_t, int16_t, int32_t, int64_t, +uintN_t, uint8_t, uint16_t, uint32_t, uint64_t +\- fixed-width basic integer types +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " int8_t; +.BR typedef " /* ... */ " int16_t; +.BR typedef " /* ... */ " int32_t; +.BR typedef " /* ... */ " int64_t; +.P +.BR typedef " /* ... */ " uint8_t; +.BR typedef " /* ... */ " uint16_t; +.BR typedef " /* ... */ " uint32_t; +.BR typedef " /* ... */ " uint64_t; +.P +.B "#define INT8_WIDTH 8" +.B "#define INT16_WIDTH 16" +.B "#define INT32_WIDTH 32" +.B "#define INT64_WIDTH 64" +.P +.B "#define UINT8_WIDTH 8" +.B "#define UINT16_WIDTH 16" +.B "#define UINT32_WIDTH 32" +.B "#define UINT64_WIDTH 64" +.P +.BR "#define INT8_MAX " "/* 2**(INT8_WIDTH - 1) - 1 */" +.BR "#define INT16_MAX " "/* 2**(INT16_WIDTH - 1) - 1 */" +.BR "#define INT32_MAX " "/* 2**(INT32_WIDTH - 1) - 1 */" +.BR "#define INT64_MAX " "/* 2**(INT64_WIDTH - 1) - 1 */" +.P +.BR "#define INT8_MIN " "/* - 2**(INT8_WIDTH - 1) */" +.BR "#define INT16_MIN " "/* - 2**(INT16_WIDTH - 1) */" +.BR "#define INT32_MIN " "/* - 2**(INT32_WIDTH - 1) */" +.BR "#define INT64_MIN " "/* - 2**(INT64_WIDTH - 1) */" +.P +.BR "#define UINT8_MAX " "/* 2**INT8_WIDTH - 1 */" +.BR "#define UINT16_MAX " "/* 2**INT16_WIDTH - 1 */" +.BR "#define UINT32_MAX " "/* 2**INT32_WIDTH - 1 */" +.BR "#define UINT64_MAX " "/* 2**INT64_WIDTH - 1 */" +.P +.BI "#define INT8_C(" c ") " c " ## " "\fR/* ... */\fP" +.BI "#define INT16_C(" c ") " c " ## " "\fR/* ... */\fP" +.BI "#define INT32_C(" c ") " c " ## " "\fR/* ... */\fP" +.BI "#define INT64_C(" c ") " c " ## " "\fR/* ... */\fP" +.P +.BI "#define UINT8_C(" c ") " c " ## " "\fR/* ... */\fP" +.BI "#define UINT16_C(" c ") " c " ## " "\fR/* ... */\fP" +.BI "#define UINT32_C(" c ") " c " ## " "\fR/* ... */\fP" +.BI "#define UINT64_C(" c ") " c " ## " "\fR/* ... */\fP" +.fi +.SH DESCRIPTION +.IR int N _t +are +signed integer types +of a fixed width of exactly N bits, +.I N +being the value specified in its type name. +They are be capable of storing values in the range +.RB [ INT \fIN\fP _MIN , +.BR INT \fIN\fP _MAX ], +substituting +.I N +by the appropriate number. +.P +.IR uint N _t +are +unsigned integer types +of a fixed width of exactly N bits, +N being the value specified in its type name. +They are capable of storing values in the range +.RB [ 0 , +.BR UINT \fIN\fP _MAX ], +substituting +.I N +by the appropriate number. +.P +According to POSIX, +.RI [ u ] int8_t , +.RI [ u ] int16_t , +and +.RI [ u ] int32_t +are required; +.RI [ u ] int64_t +are only required in implementations that provide integer types with width 64; +and all other types of this form are optional. +.P +The macros +.RB [ U ] INT \fIN\fP _WIDTH +expand to the width in bits of these types +.RI ( N ). +.P +The macros +.RB [ U ] INT \fIN\fP _MAX +expand to the maximum value that these types can hold. +.P +The macros +.BI INT N _MIN +expand to the minimum value that these types can hold. +.P +The macros +.RB [ U ] INT \fIN\fP _C () +expand their argument to an integer constant of type +.RI [ u ] int N _t . +.P +The length modifiers for the +.RI [ u ] int N _t +types for the +.BR printf (3) +family of functions +are expanded by macros of the forms +.BR PRId \fIN\fP, +.BR PRIi \fIN\fP, +.BR PRIu \fIN\fP, +and +.BI PRIx N +(defined in +.IR ); +resulting for example in +.B %"PRId64" +or +.B %"PRIi64" +for printing +.I int64_t +values. +The length modifiers for the +.RI [ u ] int N _t +types for the +.BR scanf (3) +family of functions +are expanded by macros of the forms +.BR SCNd \fIN\fP, +.BR SCNi \fIN\fP, +.BR SCNu \fIN\fP, +and +.BI SCNx N, +(defined in +.IR ); +resulting for example in +.B %"SCNu8" +or +.B %"SCNx8" +for scanning +.I uint8_t +values. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The +.RB [ U ] INT \fIN\fP _WIDTH +macros were added in C23. +.SH NOTES +The following header also provides these types: +.IR . +.I +also provides +.I uint16_t +and +.IR uint32_t . +.SH SEE ALSO +.BR intmax_t (3type), +.BR intptr_t (3type), +.BR printf (3) diff --git a/man/man3type/intmax_t.3type b/man/man3type/intmax_t.3type new file mode 100644 index 0000000..fed4e43 --- /dev/null +++ b/man/man3type/intmax_t.3type @@ -0,0 +1,97 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH intmax_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intmax_t, uintmax_t \- greatest-width basic integer types +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " intmax_t; +.BR typedef " /* ... */ " uintmax_t; +.P +.BR "#define INTMAX_WIDTH " "/* ... */" +.B "#define UINTMAX_WIDTH INTMAX_WIDTH" +.P +.BR "#define INTMAX_MAX " "/* 2**(INTMAX_WIDTH - 1) - 1 */" +.BR "#define INTMAX_MIN " "/* - 2**(INTMAX_WIDTH - 1) */" +.BR "#define UINTMAX_MAX " "/* 2**UINTMAX_WIDTH - 1 */" +.P +.BI "#define INTMAX_C(" c ) " c " ## " \fR/* ... */\fP" +.BI "#define UINTMAX_C(" c ) " c " ## " \fR/* ... */\fP" +.fi +.SH DESCRIPTION +.I intmax_t +is a signed integer type +capable of representing any value of any basic signed integer type +supported by the implementation. +It is capable of storing values in the range +.RB [ INTMAX_MIN , +.BR INTMAX_MAX ]. +.P +.I uintmax_t +is an unsigned integer type +capable of representing any value of any basic unsigned integer type +supported by the implementation. +It is capable of storing values in the range +.RB [ 0 , +.BR UINTMAX_MAX ]. +.P +The macros +.RB [ U ] INTMAX_WIDTH +expand to the width in bits of these types. +.P +The macros +.RB [ U ] INTMAX_MAX +expand to the maximum value that these types can hold. +.P +The macro +.B INTMAX_MIN +expands to the minimum value that +.I intmax_t +can hold. +.P +The macros +.RB [ U ] INTMAX_C () +expand their argument to an integer constant of type +.RI [ u ] intmax_t . +.P +The length modifier for +.RI [ u ] intmax_t +for the +.BR printf (3) +and the +.BR scanf (3) +families of functions is +.BR j ; +resulting commonly in +.BR %jd , +.BR %ji , +.BR %ju , +or +.B %jx +for printing +.RI [ u ] intmax_t +values. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +The following header also provides these types: +.IR . +.SH BUGS +These types may not be as large as extended integer types, such as +.I __int128 +.SH SEE ALSO +.BR int64_t (3type), +.BR intptr_t (3type), +.BR printf (3), +.BR strtoimax (3) diff --git a/man/man3type/intptr_t.3type b/man/man3type/intptr_t.3type new file mode 100644 index 0000000..44e2adc --- /dev/null +++ b/man/man3type/intptr_t.3type @@ -0,0 +1,107 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH intptr_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intptr_t, uintptr_t \- integer types wide enough to hold pointers +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " intptr_t; +.BR typedef " /* ... */ " uintptr_t; +.P +.BR "#define INTPTR_WIDTH" " /* ... */" +.B #define UINTPTR_WIDTH INTPTR_WIDTH +.P +.BR "#define INTPTR_MAX" " /* 2**(INTPTR_WIDTH \- 1) \- 1 */" +.BR "#define INTPTR_MIN" " /* \- 2**(INTPTR_WIDTH \- 1) */" +.BR "#define UINTPTR_MAX" " /* 2**UINTPTR_WIDTH \- 1 */" +.fi +.SH DESCRIPTION +.I intptr_t +is a signed integer type +such that any valid +.RI ( "void *" ) +value can be converted to this type and then converted back. +It is capable of storing values in the range +.RB [ INTPTR_MIN , +.BR INTPTR_MAX ]. +.P +.I uintptr_t +is an unsigned integer type +such that any valid +.RI ( "void *" ) +value can be converted to this type and then converted back. +It is capable of storing values in the range +.RB [ 0 , +.BR INTPTR_MAX ]. +.P +The macros +.RB [ U ] INTPTR_WIDTH +expand to the width in bits of these types. +.P +The macros +.RB [ U ] INTPTR_MAX +expand to the maximum value that these types can hold. +.P +The macro +.B INTPTR_MIN +expands to the minimum value that +.I intptr_t +can hold. +.P +The length modifiers for the +.RI [ u ] intptr_t +types +for the +.BR printf (3) +family of functions +are expanded by the macros +.BR PRIdPTR , +.BR PRIiPTR , +and +.B PRIuPTR +(defined in +.IR ); +resulting commonly in +.B %"PRIdPTR" +or +.B %"PRIiPTR" +for printing +.I intptr_t +values. +The length modifiers for the +.IR [ u ] intptr_t +types +for the +.BR scanf (3) +family of functions +are expanded by the macros +.BR SCNdPTR , +.BR SCNiPTR , +and +.B SCNuPTR +(defined in +.IR ); +resulting commonly in +.B %"SCNuPTR" +for scanning +.I uintptr_t +values. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH NOTES +The following header also provides these types: +.IR . +.SH SEE ALSO +.BR intmax_t (3type), +.BR void (3) diff --git a/man/man3type/iovec.3type b/man/man3type/iovec.3type new file mode 100644 index 0000000..b385b34 --- /dev/null +++ b/man/man3type/iovec.3type @@ -0,0 +1,49 @@ +.\" Copyright (c) 2022 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH iovec 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iovec \- Vector I/O data structure +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.B struct iovec { +.BR " void *iov_base;" " /* Starting address */" +.BR " size_t iov_len;" " /* Size of the memory pointed to by "\c +.IR iov_base ". */" +.B }; +.EE +.SH DESCRIPTION +Describes a region of memory, beginning at +.I iov_base +address and with the size of +.I iov_len +bytes. +System calls use arrays of this structure, +where each element of the array represents a memory region, +and the whole array represents a vector of memory regions. +The maximum number of +.I iovec +structures in that array +is limited by +.B IOV_MAX +(defined in +.IR , +or accessible via the call +.IR sysconf(_SC_IOV_MAX) ). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The following header also provides this type: +.IR . +.SH SEE ALSO +.BR process_madvise (2), +.BR readv (2) diff --git a/man/man3type/itimerspec.3type b/man/man3type/itimerspec.3type new file mode 100644 index 0000000..8f43d7b --- /dev/null +++ b/man/man3type/itimerspec.3type @@ -0,0 +1,32 @@ +.\" Copyright (c) 2022 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH itimerspec 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +itimerspec \- interval for a timer with nanosecond precision +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.B struct itimerspec { +.BR " struct timespec it_interval;" " /* Interval for periodic timer */" +.BR " struct timespec it_value;" " /* Initial expiration */" +.B }; +.EE +.SH DESCRIPTION +Describes the initial expiration of a timer, +and its interval, +in seconds and nanoseconds. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR timerfd_create (2), +.BR timer_settime (2), +.BR timespec (3type) diff --git a/man/man3type/lconv.3type b/man/man3type/lconv.3type new file mode 100644 index 0000000..18597aa --- /dev/null +++ b/man/man3type/lconv.3type @@ -0,0 +1,56 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH lconv 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lconv \- numeric formatting information +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.BR "struct lconv {" " /* Values in the \[dq]C\[dq] locale: */" +.BR " char *decimal_point;" " /* \[dq].\[dq] */" +.BR " char *thousands_sep;" " /* \[dq]\[dq] */" +.BR " char *grouping;" " /* \[dq]\[dq] */" +.BR " char *mon_decimal_point;" " /* \[dq]\[dq] */" +.BR " char *mon_thousands_sep;" " /* \[dq]\[dq] */" +.BR " char *mon_grouping;" " /* \[dq]\[dq] */" +.BR " char *positive_sign;" " /* \[dq]\[dq] */" +.BR " char *negative_sign;" " /* \[dq]\[dq] */" +.BR " char *currency_symbol;" " /* \[dq]\[dq] */" +.BR " char frac_digits;" " /* CHAR_MAX */" +.BR " char p_cs_precedes;" " /* CHAR_MAX */" +.BR " char n_cs_precedes;" " /* CHAR_MAX */" +.BR " char p_sep_by_space;" " /* CHAR_MAX */" +.BR " char n_sep_by_space;" " /* CHAR_MAX */" +.BR " char p_sign_posn;" " /* CHAR_MAX */" +.BR " char n_sign_posn;" " /* CHAR_MAX */" +.BR " char *int_curr_symbol;" " /* \[dq]\[dq] */" +.BR " char int_frac_digits;" " /* CHAR_MAX */" +.BR " char int_p_cs_precedes;" " /* CHAR_MAX */" +.BR " char int_n_cs_precedes;" " /* CHAR_MAX */" +.BR " char int_p_sep_by_space;" " /* CHAR_MAX */" +.BR " char int_n_sep_by_space;" " /* CHAR_MAX */" +.BR " char int_p_sign_posn;" " /* CHAR_MAX */" +.BR " char int_n_sign_posn;" " /* CHAR_MAX */" +.B }; +.EE +.SH DESCRIPTION +Contains members related to the formatting of numeric values. +In the "C" locale, its members have the values +shown in the comments above. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH SEE ALSO +.BR setlocale (3), +.BR localeconv (3), +.BR charsets (7), +.BR locale (7) diff --git a/man/man3type/ldiv_t.3type b/man/man3type/ldiv_t.3type new file mode 100644 index 0000000..3ab8f34 --- /dev/null +++ b/man/man3type/ldiv_t.3type @@ -0,0 +1 @@ +.so man3type/div_t.3type diff --git a/man/man3type/lldiv_t.3type b/man/man3type/lldiv_t.3type new file mode 100644 index 0000000..3ab8f34 --- /dev/null +++ b/man/man3type/lldiv_t.3type @@ -0,0 +1 @@ +.so man3type/div_t.3type diff --git a/man/man3type/locale_t.3type b/man/man3type/locale_t.3type new file mode 100644 index 0000000..9eca4b8 --- /dev/null +++ b/man/man3type/locale_t.3type @@ -0,0 +1,43 @@ +.\" Copyright (c) 2024 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH locale_t 3type 2024-05-03 "Linux man-pages (unreleased)" +.SH NAME +locale_t +\- +locale object +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " locale_t; +.fi +.SH DESCRIPTION +.I locale_t +is a type used for storing a locale object. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2008. +.SH NOTES +The following headers also provide this type: +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR . +.SH SEE ALSO +.BR duplocale (3), +.BR freelocale (3), +.BR newlocale (3), +.BR setlocale (3), +.BR uselocale (3), +.BR locale (5), +.BR locale (7) diff --git a/man/man3type/loff_t.3type b/man/man3type/loff_t.3type new file mode 100644 index 0000000..e59af3f --- /dev/null +++ b/man/man3type/loff_t.3type @@ -0,0 +1 @@ +.so man3type/off_t.3type diff --git a/man/man3type/mbstate_t.3type b/man/man3type/mbstate_t.3type new file mode 100644 index 0000000..2b7555d --- /dev/null +++ b/man/man3type/mbstate_t.3type @@ -0,0 +1,84 @@ +.\" Copyright, Bruno Haible +.\" Copyright 2024, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" References consulted: +.\" GNU glibc-2 source code and manual +.\" Dinkumware C library reference http://www.dinkumware.com/ +.\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html +.\" ISO/IEC 9899:1999 +.\" +.TH mbstate_t 3type 2024-05-03 "Linux man-pages (unreleased)" +.SH NAME +mbstate_t +\- +multi-byte-character conversion state +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " mbstate_t; +.fi +.SH DESCRIPTION +Character conversion between the multibyte representation and the wide +character representation uses conversion state, of type +.IR mbstate_t . +Conversion of a string uses a finite-state machine; when it is interrupted +after the complete conversion of a number of characters, it may need to +save a state for processing the remaining characters. +Such a conversion +state is needed for the sake of encodings such as ISO/IEC\~2022 and UTF-7. +.P +The initial state is the state at the beginning of conversion of a string. +There are two kinds of state: the one used by multibyte to wide character +conversion functions, such as +.BR mbsrtowcs (3), +and the one used by wide +character to multibyte conversion functions, such as +.BR wcsrtombs (3), +but they both fit in a +.IR mbstate_t , +and they both have the same +representation for an initial state. +.P +For 8-bit encodings, all states are equivalent to the initial state. +For multibyte encodings like UTF-8, EUC-*, BIG5, or SJIS, the wide character +to multibyte conversion functions never produce non-initial states, but the +multibyte to wide-character conversion functions like +.BR mbrtowc (3) +do +produce non-initial states when interrupted in the middle of a character. +.P +One possible way to create an +.I mbstate_t +in initial state is to set it to zero: +.P +.in +4n +.EX +mbstate_t state; +memset(&state, 0, sizeof(state)); +.EE +.in +.P +On Linux, the following works as well, but might generate compiler warnings: +.P +.in +4n +.EX +mbstate_t state = { 0 }; +.EE +.in +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.SH SEE ALSO +.BR mbrlen (3), +.BR mbrtowc (3), +.BR mbsinit (3), +.BR mbsrtowcs (3), +.BR wcrtomb (3), +.BR wcsrtombs (3) diff --git a/man/man3type/mode_t.3type b/man/man3type/mode_t.3type new file mode 100644 index 0000000..6f66aac --- /dev/null +++ b/man/man3type/mode_t.3type @@ -0,0 +1,40 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH mode_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mode_t \- file attributes +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " mode_t; +.fi +.SH DESCRIPTION +Used for some file attributes (e.g., file mode). +It is an integer type. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The following headers also provide this type: +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.SH SEE ALSO +.BR chmod (2), +.BR mkdir (2), +.BR open (2), +.BR umask (2), +.BR stat (3type) diff --git a/man/man3type/off64_t.3type b/man/man3type/off64_t.3type new file mode 100644 index 0000000..e59af3f --- /dev/null +++ b/man/man3type/off64_t.3type @@ -0,0 +1 @@ +.so man3type/off_t.3type diff --git a/man/man3type/off_t.3type b/man/man3type/off_t.3type new file mode 100644 index 0000000..da23eb5 --- /dev/null +++ b/man/man3type/off_t.3type @@ -0,0 +1,92 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH off_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +off_t, off64_t, loff_t \- file sizes +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " off_t; +.P +.B #define _LARGEFILE64_SOURCE +.B #include +.P +.BR typedef " /* ... */ " off64_t; +.P +.B #define _GNU_SOURCE +.B #include +.P +.BR typedef " /* ... */ " loff_t; +.fi +.SH DESCRIPTION +.I off_t +is used for describing file sizes. +It is a signed integer type. +.P +.I off64_t +is a 64-bit version of the type, +used in glibc. +.P +.I loff_t +is a 64-bit version of the type, +introduced by the Linux kernel. +.SH STANDARDS +.TP +.I off_t +POSIX.1-2008. +.TP +.I off64_t +GNU and some BSDs. +.TP +.I loff_t +Linux. +.SH VERSIONS +.TP +.I off_t +POSIX.1-2001. +.P +.I +and +.I +define +.I off_t +since POSIX.1-2008. +.SH NOTES +On some architectures, +the width of +.I off_t +can be controlled with the feature test macro +.BR _FILE_OFFSET_BITS . +.P +The following headers also provide +.IR off_t : +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.SH SEE ALSO +.BR copy_file_range (2), +.BR llseek (2), +.BR lseek (2), +.BR mmap (2), +.BR posix_fadvise (2), +.BR pread (2), +.BR readahead (2), +.BR sync_file_range (2), +.BR truncate (2), +.BR fseeko (3), +.BR lockf (3), +.BR lseek64 (3), +.BR posix_fallocate (3), +.BR feature_test_macros (7) diff --git a/man/man3type/pid_t.3type b/man/man3type/pid_t.3type new file mode 100644 index 0000000..52bae74 --- /dev/null +++ b/man/man3type/pid_t.3type @@ -0,0 +1 @@ +.so man3type/id_t.3type diff --git a/man/man3type/printf_arginfo_size_function.3type b/man/man3type/printf_arginfo_size_function.3type new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3type/printf_arginfo_size_function.3type @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3type/printf_function.3type b/man/man3type/printf_function.3type new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3type/printf_function.3type @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3type/printf_info.3type b/man/man3type/printf_info.3type new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3type/printf_info.3type @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3type/printf_va_arg_function.3type b/man/man3type/printf_va_arg_function.3type new file mode 100644 index 0000000..ad10bad --- /dev/null +++ b/man/man3type/printf_va_arg_function.3type @@ -0,0 +1 @@ +.so man3head/printf.h.3head diff --git a/man/man3type/ptrdiff_t.3type b/man/man3type/ptrdiff_t.3type new file mode 100644 index 0000000..49d82a9 --- /dev/null +++ b/man/man3type/ptrdiff_t.3type @@ -0,0 +1,47 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH ptrdiff_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ptrdiff_t \- count of elements or array index +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " ptrdiff_t; +.fi +.SH DESCRIPTION +Used for a count of elements, or an array index. +It is the result of subtracting two pointers. +It is a signed integer type +capable of storing values in the range +.RB [ PTRDIFF_MIN , +.BR PTRDIFF_MAX ]. +.P +The length modifier for +.I ptrdiff_t +for the +.BR printf (3) +and the +.BR scanf (3) +families of functions is +.BR t , +resulting commonly in +.B %td +or +.B %ti +for printing +.I ptrdiff_t +values. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH SEE ALSO +.BR size_t (3type) diff --git a/man/man3type/regex_t.3type b/man/man3type/regex_t.3type new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3type/regex_t.3type @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3type/regmatch_t.3type b/man/man3type/regmatch_t.3type new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3type/regmatch_t.3type @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3type/regoff_t.3type b/man/man3type/regoff_t.3type new file mode 100644 index 0000000..c0daaf0 --- /dev/null +++ b/man/man3type/regoff_t.3type @@ -0,0 +1 @@ +.so man3/regex.3 diff --git a/man/man3type/sa_family_t.3type b/man/man3type/sa_family_t.3type new file mode 100644 index 0000000..39e914c --- /dev/null +++ b/man/man3type/sa_family_t.3type @@ -0,0 +1 @@ +.so man3type/sockaddr.3type diff --git a/man/man3type/sigevent.3type b/man/man3type/sigevent.3type new file mode 100644 index 0000000..373bf6d --- /dev/null +++ b/man/man3type/sigevent.3type @@ -0,0 +1,142 @@ +.\" Copyright (c) 2006, 2010, 2020, Michael Kerrisk +.\" Copyright (C) 2009 Petr Baudis +.\" Copyright (c) 2020-2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigevent 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sigevent, sigval \- structure for notification from asynchronous routines +.SH SYNOPSIS +.EX +.B #include +.P +.B struct sigevent { +.BR " int sigev_notify;" " /* Notification type */" +.BR " int sigev_signo;" " /* Signal number */" +.BR " union sigval sigev_value;" " /* Data passed with notification */" +\& +.B " void (*sigev_notify_function)(union sigval);" +.BR " " " /* Notification function" +.BR " " " (SIGEV_THREAD) */" +.B " pthread_attr_t *sigev_notify_attributes;" +.BR " " " /* Notification attributes */" +\& +.BR " " "/* Linux only: */" +.B " pid_t sigev_notify_thread_id;" +.BR " " " /* ID of thread to signal" +.BR " " " (SIGEV_THREAD_ID) */" +.B }; +.P +.BR "union sigval {" " /* Data passed with notification */" +.BR " int sival_int;" " /* Integer value */" +.BR " void *sival_ptr;" " /* Pointer value */" +.B }; +.EE +.SH DESCRIPTION +.SS sigevent +The +.I sigevent +structure is used by various APIs +to describe the way a process is to be notified about an event +(e.g., completion of an asynchronous request, expiration of a timer, +or the arrival of a message). +.P +The definition shown in the SYNOPSIS is approximate: +some of the fields in the +.I sigevent +structure may be defined as part of a union. +Programs should employ only those fields relevant +to the value specified in +.IR sigev_notify . +.P +The +.I sigev_notify +field specifies how notification is to be performed. +This field can have one of the following values: +.TP +.B SIGEV_NONE +A "null" notification: don't do anything when the event occurs. +.TP +.B SIGEV_SIGNAL +Notify the process by sending the signal specified in +.IR sigev_signo . +.IP +If the signal is caught with a signal handler that was registered using the +.BR sigaction (2) +.B SA_SIGINFO +flag, then the following fields are set in the +.I siginfo_t +structure that is passed as the second argument of the handler: +.RS +.TP 10 +.I si_code +This field is set to a value that depends on the API +delivering the notification. +.TP +.I si_signo +This field is set to the signal number (i.e., the same value as in +.IR sigev_signo ). +.TP +.I si_value +This field is set to the value specified in +.IR sigev_value . +.RE +.IP +Depending on the API, other fields may also be set in the +.I siginfo_t +structure. +.IP +The same information is also available if the signal is accepted using +.BR sigwaitinfo (2). +.TP +.B SIGEV_THREAD +Notify the process by invoking +.I sigev_notify_function +"as if" it were the start function of a new thread. +(Among the implementation possibilities here are that +each timer notification could result in the creation of a new thread, +or that a single thread is created to receive all notifications.) +The function is invoked with +.I sigev_value +as its sole argument. +If +.I sigev_notify_attributes +is not NULL, it should point to a +.I pthread_attr_t +structure that defines attributes for the new thread (see +.BR pthread_attr_init (3)). +.TP +.BR SIGEV_THREAD_ID " (Linux-specific)" +.\" | SIGEV_SIGNAL vs not? +Currently used only by POSIX timers; see +.BR timer_create (2). +.SS sigval +Data passed with a signal. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +.I +and +.I +define +.I sigevent +since POSIX.1-2008. +.SH NOTES +The following headers also provide +.IR sigevent : +.IR , +.IR , +and +.IR . +.SH SEE ALSO +.BR timer_create (2), +.BR getaddrinfo_a (3), +.BR lio_listio (3), +.BR mq_notify (3), +.BR pthread_sigqueue (3), +.BR sigqueue (3), +.BR aiocb (3type), +.BR siginfo_t (3type) diff --git a/man/man3type/siginfo_t.3type b/man/man3type/siginfo_t.3type new file mode 100644 index 0000000..db50c0f --- /dev/null +++ b/man/man3type/siginfo_t.3type @@ -0,0 +1 @@ +.so man7/system_data_types.7 diff --git a/man/man3type/sigset_t.3type b/man/man3type/sigset_t.3type new file mode 100644 index 0000000..db50c0f --- /dev/null +++ b/man/man3type/sigset_t.3type @@ -0,0 +1 @@ +.so man7/system_data_types.7 diff --git a/man/man3type/sigval.3type b/man/man3type/sigval.3type new file mode 100644 index 0000000..b43f1bb --- /dev/null +++ b/man/man3type/sigval.3type @@ -0,0 +1 @@ +.so man3type/sigevent.3type diff --git a/man/man3type/size_t.3type b/man/man3type/size_t.3type new file mode 100644 index 0000000..96aa146 --- /dev/null +++ b/man/man3type/size_t.3type @@ -0,0 +1,181 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH size_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +size_t, ssize_t \- count of bytes +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " size_t; +.P +.B #include +.P +.BR typedef " /* ... */ " ssize_t; +.fi +.SH DESCRIPTION +.TP +.I size_t +Used for a count of bytes. +It is the result of the +.IR sizeof () +operator. +It is an unsigned integer type +capable of storing values in the range +.RB [ 0 , +.BR SIZE_MAX ]. +.TP +.I ssize_t +Used for a count of bytes or an error indication. +It is a signed integer type +capable of storing values at least in the range +.RB [ \-1 , +.BR SSIZE_MAX ]. +.SS Use with printf(3) and scanf(3) +.TP +.I size_t +The length modifier for +.I size_t +for the +.BR printf (3) +and the +.BR scanf (3) +families of functions is +.BR z , +resulting commonly in +.B %zu +or +.B %zx +for printing +.I size_t +values. +.TP +.I ssize_t +glibc and most other implementations provide a length modifier for +.I ssize_t +for the +.BR printf (3) +and the +.BR scanf (3) +families of functions, +which is +.BR z ; +resulting commonly in +.B %zd +or +.B %zi +for printing +.I ssize_t +values. +Although +.B z +works for +.I ssize_t +on most implementations, +portable POSIX programs should avoid using it\[em]for example, +by converting the value to +.I intmax_t +and using its length modifier +.RB ( j ). +.SH STANDARDS +.TP +.I size_t +C11, POSIX.1-2008. +.TP +.I ssize_t +POSIX.1-2008. +.PD +.SH HISTORY +.TP +.I size_t +C89, POSIX.1-2001. +.TP +.I ssize_t +POSIX.1-2001. +.P +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.I +define +.I size_t +since POSIX.1-2008. +.P +.IR , +.IR , +and +.I +define +.I ssize_t +since POSIX.1-2008. +.SH NOTES +.TP +.I size_t +The following headers also provide +.IR size_t : +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.TP +.I ssize_t +The following headers also provide +.IR ssize_t : +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.SH SEE ALSO +.BR read (2), +.BR readlink (2), +.BR readv (2), +.BR recv (2), +.BR send (2), +.BR write (2), +.BR fread (3), +.BR fwrite (3), +.BR memcmp (3), +.BR memcpy (3), +.BR memset (3), +.BR offsetof (3), +.BR ptrdiff_t (3type) diff --git a/man/man3type/sockaddr.3type b/man/man3type/sockaddr.3type new file mode 100644 index 0000000..751095d --- /dev/null +++ b/man/man3type/sockaddr.3type @@ -0,0 +1,154 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH sockaddr 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sockaddr, sockaddr_storage, sockaddr_in, sockaddr_in6, sockaddr_un, socklen_t, +in_addr, in6_addr, in_addr_t, in_port_t, +\- socket address +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.B struct sockaddr { +.BR " sa_family_t sa_family;" " /* Address family */" +.BR " char sa_data[];" " /* Socket address */" +.B }; +.P +.B struct sockaddr_storage { +.BR " sa_family_t ss_family;" " /* Address family */" +.B }; +.P +.BR typedef " /* ... */ " socklen_t; +.BR typedef " /* ... */ " sa_family_t; +.P +.EE +.SS Internet domain sockets +.EX +.B #include +.P +.B struct sockaddr_in { +.BR " sa_family_t sin_family;" " /* " AF_INET " */" +.BR " in_port_t sin_port;" " /* Port number */" +.BR " struct in_addr sin_addr;" " /* IPv4 address */" +.B }; +.P +.B struct sockaddr_in6 { +.BR " sa_family_t sin6_family;" " /* " AF_INET6 " */" +.BR " in_port_t sin6_port;" " /* Port number */" +.BR " uint32_t sin6_flowinfo;" " /* IPv6 flow info */" +.BR " struct in6_addr sin6_addr;" " /* IPv6 address */" +.BR " uint32_t sin6_scope_id;" " /* Set of interfaces for a scope */" +.B }; +.P +.B struct in_addr { +.B " in_addr_t s_addr;" +.B }; +.P +.B struct in6_addr { +.B " uint8_t s6_addr[16];" +.B }; +.P +.B typedef uint32_t in_addr_t; +.B typedef uint16_t in_port_t; +.EE +.SS UNIX domain sockets +.EX +.B #include +.P +.B struct sockaddr_un { +.BR " sa_family_t sun_family;" " /* Address family */" +.BR " char sun_path[];" " /* Socket pathname */" +.B }; +.EE +.SH DESCRIPTION +.TP +.I sockaddr +Describes a socket address. +.TP +.I sockaddr_storage +A structure at least as large as any other +.IR sockaddr_ * +address structures. +It's aligned so that a pointer to it can be cast +as a pointer to other +.IR sockaddr_ * +structures and used to access its fields. +.TP +.I socklen_t +Describes the length of a socket address. +This is an integer type of at least 32 bits. +.TP +.I sa_family_t +Describes a socket's protocol family. +This is an unsigned integer type. +.SS Internet domain sockets +.TP +.I sockaddr_in +Describes an IPv4 Internet domain socket address. +The +.I sin_port +and +.I sin_addr +members are stored in network byte order. +.TP +.I sockaddr_in6 +Describes an IPv6 Internet domain socket address. +The +.I sin6_addr.s6_addr +array is used to contain a 128-bit IPv6 address, +stored in network byte order. +.SS UNIX domain sockets +.TP +.I sockaddr_un +Describes a UNIX domain socket address. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +.I socklen_t +was invented by POSIX. +See also +.BR accept (2). +.P +These structures were invented before modern ISO C strict-aliasing rules. +If aliasing rules are applied strictly, +these structures would be extremely difficult to use +without invoking Undefined Behavior. +POSIX Issue 8 will fix this by requiring that implementations +make sure that these structures +can be safely used as they were designed. +.SH NOTES +.I socklen_t +is also defined in +.IR . +.P +.I sa_family_t +is also defined in +.I +and +.IR . +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR connect (2), +.BR getpeername (2), +.BR getsockname (2), +.BR getsockopt (2), +.BR sendto (2), +.BR setsockopt (2), +.BR socket (2), +.BR socketpair (2), +.BR getaddrinfo (3), +.BR gethostbyaddr (3), +.BR getnameinfo (3), +.BR htonl (3), +.BR ipv6 (7), +.BR socket (7) diff --git a/man/man3type/sockaddr_in.3type b/man/man3type/sockaddr_in.3type new file mode 100644 index 0000000..39e914c --- /dev/null +++ b/man/man3type/sockaddr_in.3type @@ -0,0 +1 @@ +.so man3type/sockaddr.3type diff --git a/man/man3type/sockaddr_in6.3type b/man/man3type/sockaddr_in6.3type new file mode 100644 index 0000000..39e914c --- /dev/null +++ b/man/man3type/sockaddr_in6.3type @@ -0,0 +1 @@ +.so man3type/sockaddr.3type diff --git a/man/man3type/sockaddr_storage.3type b/man/man3type/sockaddr_storage.3type new file mode 100644 index 0000000..39e914c --- /dev/null +++ b/man/man3type/sockaddr_storage.3type @@ -0,0 +1 @@ +.so man3type/sockaddr.3type diff --git a/man/man3type/sockaddr_un.3type b/man/man3type/sockaddr_un.3type new file mode 100644 index 0000000..39e914c --- /dev/null +++ b/man/man3type/sockaddr_un.3type @@ -0,0 +1 @@ +.so man3type/sockaddr.3type diff --git a/man/man3type/socklen_t.3type b/man/man3type/socklen_t.3type new file mode 100644 index 0000000..39e914c --- /dev/null +++ b/man/man3type/socklen_t.3type @@ -0,0 +1 @@ +.so man3type/sockaddr.3type diff --git a/man/man3type/speed_t.3type b/man/man3type/speed_t.3type new file mode 100644 index 0000000..26cfd01 --- /dev/null +++ b/man/man3type/speed_t.3type @@ -0,0 +1 @@ +.so man3type/cc_t.3type diff --git a/man/man3type/ssize_t.3type b/man/man3type/ssize_t.3type new file mode 100644 index 0000000..c8d4408 --- /dev/null +++ b/man/man3type/ssize_t.3type @@ -0,0 +1 @@ +.so man3type/size_t.3type diff --git a/man/man3type/stat.3type b/man/man3type/stat.3type new file mode 100644 index 0000000..d1dccf1 --- /dev/null +++ b/man/man3type/stat.3type @@ -0,0 +1,162 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH stat 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +stat \- file status +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.B struct stat { +.BR " dev_t st_dev;" " /* ID of device containing file */" +.BR " ino_t st_ino;" " /* Inode number */" +.BR " mode_t st_mode;" " /* File type and mode */" +.BR " nlink_t st_nlink;" " /* Number of hard links */" +.BR " uid_t st_uid;" " /* User ID of owner */" +.BR " gid_t st_gid;" " /* Group ID of owner */" +.BR " dev_t st_rdev;" " /* Device ID (if special file) */" +.BR " off_t st_size;" " /* Total size, in bytes */" +.BR " blksize_t st_blksize;" " /* Block size for filesystem I/O */" +.BR " blkcnt_t st_blocks;" " /* Number of 512 B blocks allocated */" +\& + /* Since POSIX.1-2008, this structure supports nanosecond + precision for the following timestamp fields. + For the details before POSIX.1-2008, see VERSIONS. */ +\& +.BR " struct timespec st_atim;" " /* Time of last access */" +.BR " struct timespec st_mtim;" " /* Time of last modification */" +.BR " struct timespec st_ctim;" " /* Time of last status change */" +\& +.BR "#define st_atime st_atim.tv_sec" " /* Backward compatibility */" +.B "#define st_mtime st_mtim.tv_sec" +.B "#define st_ctime st_ctim.tv_sec" +.B }; +.EE +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.IR st_atim , +.IR st_mtim , +.IR st_ctim : +.nf + Since glibc 2.12: + _POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700 + glibc 2.19 and earlier: + _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +Describes information about a file. +.P +The fields are as follows: +.TP +.I st_dev +This field describes the device on which this file resides. +(The +.BR major (3) +and +.BR minor (3) +macros may be useful to decompose the device ID in this field.) +.TP +.I st_ino +This field contains the file's inode number. +.TP +.I st_mode +This field contains the file type and mode. +See +.BR inode (7) +for further information. +.TP +.I st_nlink +This field contains the number of hard links to the file. +.TP +.I st_uid +This field contains the user ID of the owner of the file. +.TP +.I st_gid +This field contains the ID of the group owner of the file. +.TP +.I st_rdev +This field describes the device that this file (inode) represents. +.TP +.I st_size +This field gives the size of the file (if it is a regular +file or a symbolic link) in bytes. +The size of a symbolic link is the length of the pathname +it contains, without a terminating null byte. +.TP +.I st_blksize +This field gives the "preferred" block size for efficient filesystem I/O. +.TP +.I st_blocks +This field indicates the number of blocks allocated to the file, +in 512-byte units. +(This may be smaller than +.IR st_size /512 +when the file has holes.) +.TP +.I st_atime +This is the time of the last access of file data. +.TP +.I st_mtime +This is the time of last modification of file data. +.TP +.I st_ctime +This is the file's last status change timestamp +(time of last change to the inode). +.P +For further information on the above fields, see +.BR inode (7). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +Old kernels and old standards did not support nanosecond timestamp fields. +Instead, there were three timestamp +.RI fields\[em] st_atime , +.IR st_mtime , +and +.IR st_ctime \[em]typed +as +.I time_t +that recorded timestamps with one-second precision. +.P +Since Linux 2.5.48, the +.I stat +structure supports nanosecond resolution for the three file timestamp fields. +The nanosecond components of each timestamp are available +via names of the form +.IR st_atim.tv_nsec , +if suitable test macros are defined. +Nanosecond timestamps were standardized in POSIX.1-2008, +and, starting with glibc 2.12, +glibc exposes the nanosecond component names if +.B _POSIX_C_SOURCE +is defined with the value 200809L or greater, or +.B _XOPEN_SOURCE +is defined with the value 700 or greater. +Up to and including glibc 2.19, +the definitions of the nanoseconds components are also defined if +.B _BSD_SOURCE +or +.B _SVID_SOURCE +is defined. +If none of the aforementioned macros are defined, +then the nanosecond values are exposed with names of the form +.IR st_atimensec . +.SH NOTES +The following header also provides this type: +.IR . +.SH SEE ALSO +.BR stat (2), +.BR inode (7) diff --git a/man/man3type/suseconds_t.3type b/man/man3type/suseconds_t.3type new file mode 100644 index 0000000..7f430e1 --- /dev/null +++ b/man/man3type/suseconds_t.3type @@ -0,0 +1 @@ +.so man3type/time_t.3type diff --git a/man/man3type/tcflag_t.3type b/man/man3type/tcflag_t.3type new file mode 100644 index 0000000..26cfd01 --- /dev/null +++ b/man/man3type/tcflag_t.3type @@ -0,0 +1 @@ +.so man3type/cc_t.3type diff --git a/man/man3type/time_t.3type b/man/man3type/time_t.3type new file mode 100644 index 0000000..9635745 --- /dev/null +++ b/man/man3type/time_t.3type @@ -0,0 +1,111 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH time_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +time_t, suseconds_t, useconds_t \- integer time +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " time_t; +.P +.B #include +.P +.BR typedef " /* ... */ " suseconds_t; +.BR typedef " /* ... */ " useconds_t; +.fi +.SH DESCRIPTION +.TP +.I time_t +Used for time in seconds. +According to POSIX, +it is an integer type. +.\" In POSIX.1-2001, the type was specified as being either an integer +.\" type or a real-floating type. However, existing implementations +.\" used an integer type, and POSIX.1-2008 tightened the specification +.\" to reflect this. +.TP +.I suseconds_t +Used for time in microseconds. +It is a signed integer type +capable of storing values at least in the range +.RB [ \-1 , +.BR 1000000 ]. +.TP +.I useconds_t +Used for time in microseconds. +It is an unsigned integer type +capable of storing values at least in the range +.RB [ 0 , +.BR 1000000 ]. +.SH STANDARDS +.TP +.I time_t +C11, POSIX.1-2008. +.TP +.I suseconds_t +.TQ +.I useconds_t +POSIX.1-2008. +.PD +.SH HISTORY +.TP +.I time_t +C89, POSIX.1-2001. +.TP +.I suseconds_t +.TQ +.I useconds_t +POSIX.1-2001. +.P +.I +defines +.I time_t +since POSIX.1-2008. +.P +POSIX.1-2001 defined +.I useconds_t +in +.I +too. +.SH NOTES +On some architectures, +the width of +.I time_t +can be controlled with the feature test macro +.BR _TIME_BITS . +See +.BR feature_test_macros (7). +.P +The following headers also provide +.IR time_t : +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.P +The following headers also provide +.IR suseconds_t : +.I +and +.IR . +.SH SEE ALSO +.BR stime (2), +.BR time (2), +.BR ctime (3), +.BR difftime (3), +.BR usleep (3), +.BR timeval (3type) diff --git a/man/man3type/timer_t.3type b/man/man3type/timer_t.3type new file mode 100644 index 0000000..8f38f5b --- /dev/null +++ b/man/man3type/timer_t.3type @@ -0,0 +1,34 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH timer_t 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timer_t \- timer ID +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " timer_t; +.fi +.SH DESCRIPTION +Used for timer ID returned by +.BR timer_create (2). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The following header also provides +.IR timer_t : +.IR . +.SH SEE ALSO +.BR timer_create (2), +.BR timer_delete (2), +.BR timer_getoverrun (2), +.BR timer_settime (2) diff --git a/man/man3type/timespec.3type b/man/man3type/timespec.3type new file mode 100644 index 0000000..f607441 --- /dev/null +++ b/man/man3type/timespec.3type @@ -0,0 +1,60 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH timespec 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timespec \- time in seconds and nanoseconds +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.B struct timespec { +.BR " time_t tv_sec;" " /* Seconds */" +.RB " /* ... */" " tv_nsec;" \ +" /* Nanoseconds [" 0 ", " 999\[aq]999\[aq]999 "] */" +.B }; +.EE +.SH DESCRIPTION +Describes times in seconds and nanoseconds. +.P +.I tv_nsec +is of an implementation-defined signed type +capable of holding the specified range. +Under glibc, this is usually +.IR long , +and +.I long long +on X32. +It can be safely down-cast to any concrete 32-bit integer type for processing. +.SH VERSIONS +Prior to C23, +.I tv_nsec +was +.IR long . +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The following headers also provide this type: +.IR , +.IR , +.IR , +.IR , +.IR , +and +.IR . +.SH SEE ALSO +.BR clock_gettime (2), +.BR clock_nanosleep (2), +.BR nanosleep (2), +.BR timerfd_gettime (2), +.BR timer_gettime (2), +.BR time_t (3type), +.BR timeval (3type) diff --git a/man/man3type/timeval.3type b/man/man3type/timeval.3type new file mode 100644 index 0000000..ab47f08 --- /dev/null +++ b/man/man3type/timeval.3type @@ -0,0 +1,43 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH timeval 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +timeval \- time in seconds and microseconds +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.B struct timeval { +.BR " time_t tv_sec;" " /* Seconds */" +.BR " suseconds_t tv_usec;" " /* Microseconds */" +.B }; +.EE +.SH DESCRIPTION +Describes times in seconds and microseconds. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The following headers also provide this type: +.IR , +.IR , +and +.IR . +.SH SEE ALSO +.BR gettimeofday (2), +.BR select (2), +.BR utimes (2), +.BR adjtime (3), +.BR futimes (3), +.BR timeradd (3), +.BR suseconds_t (3type), +.BR time_t (3type), +.BR timespec (3type) diff --git a/man/man3type/tm.3type b/man/man3type/tm.3type new file mode 100644 index 0000000..9b646c9 --- /dev/null +++ b/man/man3type/tm.3type @@ -0,0 +1,112 @@ +.\" Copyright (c) 2022 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH tm 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tm \- broken-down time +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.EX +.B #include +.P +.B struct tm { +.BR " int tm_sec;" " /* Seconds [" 0 ", " 60 "] */" +.BR " int tm_min;" " /* Minutes [" 0 ", " 59 "] */" +.BR " int tm_hour;" " /* Hour [" 0 ", " 23 "] */" +.BR " int tm_mday;" " /* Day of the month [" 1 ", " 31 "] */" +.BR " int tm_mon;" \ +" /* Month [" 0 ", " 11 "] (January = " 0 ") */" +.BR " int tm_year;" " /* Year minus " 1900 " */" +.BR " int tm_wday;" \ +" /* Day of the week [" 0 ", " 6 "] (Sunday = " 0 ") */" +.BR " int tm_yday;" \ +" /* Day of the year [" 0 ", " 365 "] (Jan/01 = " 0 ") */" +.BR " int tm_isdst;" " /* Daylight savings flag */" +.P +.BR " long tm_gmtoff;" " /* Seconds East of UTC */" +.BR " const char *tm_zone;" " /* Timezone abbreviation */" +.B }; +.EE +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.IR tm_gmtoff , +.IR tm_zone : +.nf +.\" Guarded with __USE_MISC: + Since glibc 2.20: + _DEFAULT_SOURCE + glibc 2.20 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +Describes time, broken down into distinct components. +.P +.I tm_isdst +describes whether daylight saving time is in effect at the time described. +The value is positive if daylight saving time is in effect, +zero if it is not, +and negative if the information is not available. +.P +.I tm_gmtoff +is the difference, in seconds, +of the timezone represented by this broken-down time and UTC +(this is the additive inverse of +.BR timezone (3)). +.P +.I tm_zone +is the equivalent of +.BR tzname (3) +for the timezone represented by this broken-down time. +.SH VERSIONS +In C90, +.I tm_sec +could represent values in the range +.RB [ 0 ", " 61 ], +which could represent a double leap second. +UTC doesn't permit double leap seconds, +so it was limited to +.B 60 +in C99. +.P +.BR timezone (3), +as a variable, is an XSI extension: some systems provide the V7-compatible +.\" FreeBSD +.BR timezone (3) +function. +The +.I tm_gmtoff +field provides an alternative (with the opposite sign) for those systems. +.P +.I tm_zone +points to static storage and may be overridden on subsequent calls to +.BR localtime (3) +and similar functions (however, this never happens under glibc). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.P +.I tm_gmtoff +and +.I tm_zone +originate from 4.3BSD-Tahoe (where +.I tm_zone +is a +.IR "char *" ). +.SH NOTES +.I tm_sec +can represent a leap second with the value +.BR 60 . +.SH SEE ALSO +.BR ctime (3), +.BR strftime (3), +.BR strptime (3), +.BR time (7) diff --git a/man/man3type/uid_t.3type b/man/man3type/uid_t.3type new file mode 100644 index 0000000..52bae74 --- /dev/null +++ b/man/man3type/uid_t.3type @@ -0,0 +1 @@ +.so man3type/id_t.3type diff --git a/man/man3type/uint16_t.3type b/man/man3type/uint16_t.3type new file mode 100644 index 0000000..a0d1a82 --- /dev/null +++ b/man/man3type/uint16_t.3type @@ -0,0 +1 @@ +.so man3type/intN_t.3type diff --git a/man/man3type/uint32_t.3type b/man/man3type/uint32_t.3type new file mode 100644 index 0000000..a0d1a82 --- /dev/null +++ b/man/man3type/uint32_t.3type @@ -0,0 +1 @@ +.so man3type/intN_t.3type diff --git a/man/man3type/uint64_t.3type b/man/man3type/uint64_t.3type new file mode 100644 index 0000000..a0d1a82 --- /dev/null +++ b/man/man3type/uint64_t.3type @@ -0,0 +1 @@ +.so man3type/intN_t.3type diff --git a/man/man3type/uint8_t.3type b/man/man3type/uint8_t.3type new file mode 100644 index 0000000..a0d1a82 --- /dev/null +++ b/man/man3type/uint8_t.3type @@ -0,0 +1 @@ +.so man3type/intN_t.3type diff --git a/man/man3type/uintN_t.3type b/man/man3type/uintN_t.3type new file mode 100644 index 0000000..a0d1a82 --- /dev/null +++ b/man/man3type/uintN_t.3type @@ -0,0 +1 @@ +.so man3type/intN_t.3type diff --git a/man/man3type/uintmax_t.3type b/man/man3type/uintmax_t.3type new file mode 100644 index 0000000..497d4ac --- /dev/null +++ b/man/man3type/uintmax_t.3type @@ -0,0 +1 @@ +.so man3type/intmax_t.3type diff --git a/man/man3type/uintptr_t.3type b/man/man3type/uintptr_t.3type new file mode 100644 index 0000000..6a55bc9 --- /dev/null +++ b/man/man3type/uintptr_t.3type @@ -0,0 +1 @@ +.so man3type/intptr_t.3type diff --git a/man/man3type/useconds_t.3type b/man/man3type/useconds_t.3type new file mode 100644 index 0000000..7f430e1 --- /dev/null +++ b/man/man3type/useconds_t.3type @@ -0,0 +1 @@ +.so man3type/time_t.3type diff --git a/man/man3type/va_list.3type b/man/man3type/va_list.3type new file mode 100644 index 0000000..175fdab --- /dev/null +++ b/man/man3type/va_list.3type @@ -0,0 +1,44 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH va_list 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +va_list \- variable argument list +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " va_list; +.fi +.SH DESCRIPTION +Used by functions with a varying number of arguments of varying types. +The function must declare an object of type +.I va_list +which is used by the macros +.BR va_start (3), +.BR va_arg (3), +.BR va_copy (3), +and +.BR va_end (3) +to traverse the list of arguments. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH NOTES +The following headers also provide +.IR va_list : +.I +and +.IR . +.SH SEE ALSO +.BR va_start (3), +.BR va_arg (3), +.BR va_copy (3), +.BR va_end (3) diff --git a/man/man3type/void.3type b/man/man3type/void.3type new file mode 100644 index 0000000..d4af096 --- /dev/null +++ b/man/man3type/void.3type @@ -0,0 +1,76 @@ +.\" Copyright (c) 2020-2022 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH void 3type 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +void \- abstract type +.SH SYNOPSIS +.nf +.B void * +.fi +.SH DESCRIPTION +A pointer to any object type may be converted to a pointer to +.I void +and back. +POSIX further requires that any pointer, +including pointers to functions, +may be converted to a pointer to +.I void +and back. +.P +Conversions from and to any other pointer type are done implicitly, +not requiring casts at all. +Note that this feature prevents any kind of type checking: +the programmer should be careful not to convert a +.I void * +value to a type incompatible to that of the underlying data, +because that would result in undefined behavior. +.P +This type is useful in function parameters and return value +to allow passing values of any type. +The function will typically use some mechanism to know +the real type of the data being passed via a pointer to +.IR void . +.P +A value of this type can't be dereferenced, +as it would give a value of type +.IR void , +which is not possible. +Likewise, pointer arithmetic is not possible with this type. +However, in GNU C, pointer arithmetic is allowed +as an extension to the standard; +this is done by treating the size of a +.I void +or of a function as 1. +A consequence of this is that +.I sizeof +is also allowed on +.I void +and on function types, and returns 1. +.SS Use with printf(3) and scanf(3) +The conversion specifier for +.I void * +for the +.BR printf (3) +and the +.BR scanf (3) +families of functions is +.BR p . +.SH VERSIONS +The POSIX requirement about compatibility between +.I void * +and function pointers was added in +POSIX.1-2008 Technical Corrigendum 1 (2013). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C89, POSIX.1-2001. +.SH SEE ALSO +.BR malloc (3), +.BR memcmp (3), +.BR memcpy (3), +.BR memset (3), +.BR intptr_t (3type) diff --git a/man/man3type/wchar_t.3type b/man/man3type/wchar_t.3type new file mode 100644 index 0000000..5b527b0 --- /dev/null +++ b/man/man3type/wchar_t.3type @@ -0,0 +1,48 @@ +.\" Copyright (c) 2024 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH wchar_t 3type 2024-05-03 "Linux man-pages (unreleased)" +.SH NAME +wchar_t +\- +wide-character type +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " wchar_t; +.P +.B #include +.P +.BR "#define WCHAR_WIDTH " "/* ... */" +.BR "#define WCHAR_MAX " "/* ... */" +.BR "#define WCHAR_MIN " "/* ... */" +.fi +.SH DESCRIPTION +.I wchar_t +is a type used for storing a wide character. +It is an integer type. +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The +.B WCHAR_WIDTH +macro was added in C23. +.SH NOTES +The following headers also provide this type: +.IR , +.IR , +.IR , +.IR . +.P +The following header also provides these macros: +.IR . +.SH SEE ALSO +.BR wint_t (3type), +.BR fputwc (3) diff --git a/man/man3type/wint_t.3type b/man/man3type/wint_t.3type new file mode 100644 index 0000000..991b863 --- /dev/null +++ b/man/man3type/wint_t.3type @@ -0,0 +1,56 @@ +.\" Copyright (c) 2024 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH wint_t 3type 2024-05-03 "Linux man-pages (unreleased)" +.SH NAME +wint_t, +WEOF +\- +integer type capable of storing any wchar_t of WEOF +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include +.P +.BR typedef " /* ... */ " wint_t; +.P +.BR "#define WEOF " "/* ... */" +.P +.B #include +.P +.BR "#define WINT_WIDTH " "/* ... */" +.BR "#define WINT_MAX " "/* ... */" +.BR "#define WINT_MIN " "/* ... */" +.fi +.SH DESCRIPTION +.I wint_t +is a type used in functions that work with wide characters. +It is capable of storing any valid wchar_t or WEOF. +It is an integer type. +.P +.B WEOF +is used by wide-character functions +to indicate the end of an input file +or an error. +It is of type +.IR wint_t . +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +C99, POSIX.1-2001. +.P +The +.B WINT_WIDTH +macro was added in C23. +.SH NOTES +The following header also provides +.I wint_t +and +.BR WEOF : +.IR . +.SH SEE ALSO +.BR wchar_t (3type), +.BR fputwc (3) diff --git a/man/man4/cciss.4 b/man/man4/cciss.4 new file mode 100644 index 0000000..aea84d3 --- /dev/null +++ b/man/man4/cciss.4 @@ -0,0 +1,385 @@ +'\" t +.\" Copyright (C) 2011, Hewlett-Packard Development Company, L.P. +.\" Written by Stephen M. Cameron +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.\" shorthand for double quote that works everywhere. +.ds q \N'34' +.TH cciss 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cciss \- HP Smart Array block driver +.SH SYNOPSIS +.nf +modprobe cciss [ cciss_allow_hpsa=1 ] +.fi +.SH DESCRIPTION +.\" commit 253d2464df446456c0bba5ed4137a7be0b278aa8 +.BR Note : +This obsolete driver was removed in Linux 4.14, +as it is superseded by the +.BR hpsa (4) +driver in newer kernels. +.P +.B cciss +is a block driver for older HP Smart Array RAID controllers. +.SS Options +.IR "cciss_allow_hpsa=1" : +This option prevents the +.B cciss +driver from attempting to drive any controllers that the +.BR hpsa (4) +driver is capable of controlling, which is to say, the +.B cciss +driver is restricted by this option to the following controllers: +.P +.nf + Smart Array 5300 + Smart Array 5i + Smart Array 532 + Smart Array 5312 + Smart Array 641 + Smart Array 642 + Smart Array 6400 + Smart Array 6400 EM + Smart Array 6i + Smart Array P600 + Smart Array P400i + Smart Array E200i + Smart Array E200 + Smart Array E200i + Smart Array E200i + Smart Array E200i + Smart Array E500 +.fi +.SS Supported hardware +The +.B cciss +driver supports the following Smart Array boards: +.P +.nf + Smart Array 5300 + Smart Array 5i + Smart Array 532 + Smart Array 5312 + Smart Array 641 + Smart Array 642 + Smart Array 6400 + Smart Array 6400 U320 Expansion Module + Smart Array 6i + Smart Array P600 + Smart Array P800 + Smart Array E400 + Smart Array P400i + Smart Array E200 + Smart Array E200i + Smart Array E500 + Smart Array P700m + Smart Array P212 + Smart Array P410 + Smart Array P410i + Smart Array P411 + Smart Array P812 + Smart Array P712m + Smart Array P711m +.fi +.SS Configuration details +To configure HP Smart Array controllers, +use the HP Array Configuration Utility +(either +.BR hpacuxe (8) +or +.BR hpacucli (8)) +or the Offline ROM-based Configuration Utility (ORCA) +run from the Smart Array's option ROM at boot time. +.SH FILES +.SS Device nodes +The device naming scheme is as follows: +.P +Major numbers: +.IP +.TS +r r. +104 cciss0 +105 cciss1 +106 cciss2 +105 cciss3 +108 cciss4 +109 cciss5 +110 cciss6 +111 cciss7 +.TE +.P +Minor numbers: +.P +.EX + b7 b6 b5 b4 b3 b2 b1 b0 + |\-\-\-\-+\-\-\-\-| |\-\-\-\-+\-\-\-\-| + | | + | +\-\-\-\-\-\-\-\- Partition ID (0=wholedev, 1\-15 partition) + | + +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- Logical Volume number +.EE +.P +The device naming scheme is: +.TS +li l. +/dev/cciss/c0d0 Controller 0, disk 0, whole device +/dev/cciss/c0d0p1 Controller 0, disk 0, partition 1 +/dev/cciss/c0d0p2 Controller 0, disk 0, partition 2 +/dev/cciss/c0d0p3 Controller 0, disk 0, partition 3 +\& +/dev/cciss/c1d1 Controller 1, disk 1, whole device +/dev/cciss/c1d1p1 Controller 1, disk 1, partition 1 +/dev/cciss/c1d1p2 Controller 1, disk 1, partition 2 +/dev/cciss/c1d1p3 Controller 1, disk 1, partition 3 +.TE +.SS Files in /proc +The files +.I /proc/driver/cciss/cciss[0\-9]+ +contain information about +the configuration of each controller. +For example: +.P +.in +4n +.EX +$ \fBcd /proc/driver/cciss\fP +$ \fBls \-l\fP +total 0 +-rw\-r\-\-r\-\- 1 root root 0 2010\-09\-10 10:38 cciss0 +-rw\-r\-\-r\-\- 1 root root 0 2010\-09\-10 10:38 cciss1 +-rw\-r\-\-r\-\- 1 root root 0 2010\-09\-10 10:38 cciss2 +$ \fBcat cciss2\fP +cciss2: HP Smart Array P800 Controller +Board ID: 0x3223103c +Firmware Version: 7.14 +IRQ: 16 +Logical drives: 1 +Current Q depth: 0 +Current # commands on controller: 0 +Max Q depth since init: 1 +Max # commands on controller since init: 2 +Max SG entries since init: 32 +Sequential access devices: 0 +\& +cciss/c2d0: 36.38GB RAID 0 +.EE +.in +.\" +.SS Files in /sys +.TP +.IR /sys/bus/pci/devices/ dev /cciss X /c X d Y /model +Displays the SCSI INQUIRY page 0 model for logical drive +.I Y +of controller +.IR X . +.TP +.IR /sys/bus/pci/devices/ dev /cciss X /c X d Y /rev +Displays the SCSI INQUIRY page 0 revision for logical drive +.I Y +of controller +.IR X . +.TP +.IR /sys/bus/pci/devices/ dev /cciss X /c X d Y /unique_id +Displays the SCSI INQUIRY page 83 serial number for logical drive +.I Y +of controller +.IR X . +.TP +.IR /sys/bus/pci/devices/ dev /cciss X /c X d Y /vendor +Displays the SCSI INQUIRY page 0 vendor for logical drive +.I Y +of controller +.IR X . +.TP +.IR /sys/bus/pci/devices/ dev /cciss X /c X d Y /block:cciss!c X d Y +A symbolic link to +.IR /sys/block/cciss!c X d Y. +.TP +.IR /sys/bus/pci/devices/ dev /cciss X /rescan +When this file is written to, the driver rescans the controller +to discover any new, removed, or modified logical drives. +.TP +.IR /sys/bus/pci/devices/ dev /cciss X /resettable +A value of 1 displayed in this file indicates that +the "reset_devices=1" kernel parameter (used by +.BR kdump ) +is honored by this controller. +A value of 0 indicates that the +"reset_devices=1" kernel parameter will not be honored. +Some models of Smart Array are not able to honor this parameter. +.TP +.IR /sys/bus/pci/devices/ dev /cciss X /c X d Y /lunid +Displays the 8-byte LUN ID used to address logical drive +.I Y +of controller +.IR X . +.TP +.IR /sys/bus/pci/devices/ dev /cciss X /c X d Y /raid_level +Displays the RAID level of logical drive +.I Y +of controller +.IR X . +.TP +.IR /sys/bus/pci/devices/ dev /cciss X /c X d Y /usage_count +Displays the usage count (number of opens) of logical drive +.I Y +of controller +.IR X . +.SS SCSI tape drive and medium changer support +SCSI sequential access devices and medium changer devices are supported and +appropriate device nodes are automatically created (e.g., +.IR /dev/st0 , +.IR /dev/st1 , +etc.; see +.BR st (4) +for more details.) +You must enable "SCSI tape drive support for Smart Array 5xxx" and +"SCSI support" in your kernel configuration to be able to use SCSI +tape drives with your Smart Array 5xxx controller. +.P +Additionally, note that the driver will not engage the SCSI core at +init time. +The driver must be directed to dynamically engage the SCSI core via the +.I /proc +filesystem entry, +which the "block" side of the driver creates as +.I /proc/driver/cciss/cciss* +at run time. +This is because at driver init time, +the SCSI core may not yet be initialized (because the driver is a block +driver) and attempting to register it with the SCSI core in such a case +would cause a hang. +This is best done via an initialization script +(typically in +.IR /etc/init.d , +but could vary depending on distribution). +For example: +.P +.in +4n +.EX +for x in /proc/driver/cciss/cciss[0\-9]* +do + echo "engage scsi" > $x +done +.EE +.in +.P +Once the SCSI core is engaged by the driver, it cannot be disengaged +(except by unloading the driver, if it happens to be linked as a module.) +.P +Note also that if no sequential access devices or medium changers are +detected, the SCSI core will not be engaged by the action of the above +script. +.SS Hot plug support for SCSI tape drives +Hot plugging of SCSI tape drives is supported, with some caveats. +The +.B cciss +driver must be informed that changes to the SCSI bus +have been made. +This may be done via the +.I /proc +filesystem. +For example: +.IP +echo "rescan" > /proc/scsi/cciss0/1 +.P +This causes the driver to: +.RS +.IP (1) 5 +query the adapter about changes to the +physical SCSI buses and/or fiber channel arbitrated loop, and +.IP (2) +make note of any new or removed sequential access devices +or medium changers. +.RE +.P +The driver will output messages indicating which +devices have been added or removed and the controller, bus, target, and +lun used to address each device. +The driver then notifies the SCSI midlayer +of these changes. +.P +Note that the naming convention of the +.I /proc +filesystem entries +contains a number in addition to the driver name +(e.g., "cciss0" +instead of just "cciss", which you might expect). +.P +Note: +.I Only +sequential access devices and medium changers are presented +as SCSI devices to the SCSI midlayer by the +.B cciss +driver. +Specifically, physical SCSI disk drives are +.I not +presented to the SCSI midlayer. +The only disk devices that are presented to the kernel are logical +drives that the array controller constructs from regions on +the physical drives. +The logical drives are presented to the block layer +(not to the SCSI midlayer). +It is important for the driver to prevent the kernel from accessing the +physical drives directly, since these drives are used by the array +controller to construct the logical drives. +.SS SCSI error handling for tape drives and medium changers +The Linux SCSI midlayer provides an error-handling protocol that +is initiated whenever a SCSI command fails to complete within a +certain amount of time (which can vary depending on the command). +The +.B cciss +driver participates in this protocol to some extent. +The normal protocol is a four-step process: +.IP (1) 5 +First, the device is told to abort the command. +.IP (2) +If that doesn't work, the device is reset. +.IP (3) +If that doesn't work, the SCSI bus is reset. +.IP (4) +If that doesn't work, the host bus adapter is reset. +.P +The +.B cciss +driver is a block +driver as well as a SCSI driver and only the tape drives and medium +changers are presented to the SCSI midlayer. +Furthermore, unlike more +straightforward SCSI drivers, disk I/O continues through the block +side during the SCSI error-recovery process. +Therefore, the +.B cciss +driver implements only the first two of these actions, +aborting the command, and resetting the device. +Note also that most tape drives will not oblige +in aborting commands, and sometimes it appears they will not even +obey a reset command, though in most circumstances they will. +If the command cannot be aborted and the device cannot be +reset, the device will be set offline. +.P +In the event that the error-handling code is triggered and a tape drive is +successfully reset or the tardy command is successfully aborted, the +tape drive may still not allow I/O to continue until some command +is issued that positions the tape to a known position. +Typically you must rewind the tape (by issuing +.I "mt \-f /dev/st0 rewind" +for example) before I/O can proceed again to a tape drive that was reset. +.SH SEE ALSO +.BR hpsa (4), +.BR cciss_vol_status (8), +.BR hpacucli (8), +.BR hpacuxe (8) +.P +.UR http://cciss.sf.net +.UE , +and +.I Documentation/blockdev/cciss.txt +and +.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss +in the Linux kernel source tree +.\" .SH AUTHORS +.\" Don Brace, Steve Cameron, Chase Maupin, Mike Miller, Michael Ni, +.\" Charles White, Francis Wiran +.\" and probably some other people. diff --git a/man/man4/console_codes.4 b/man/man4/console_codes.4 new file mode 100644 index 0000000..2fa7715 --- /dev/null +++ b/man/man4/console_codes.4 @@ -0,0 +1,811 @@ +'\" t +.\" Copyright (c) 1996 Andries Brouwer , Mon Oct 31 22:13:04 1996 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" This is combined from many sources. +.\" For Linux, the definitive source is of course console.c. +.\" About vt100-like escape sequences in general there are +.\" the ISO/IEC 6429 and ISO/IEC 2022 norms, the descriptions of +.\" an actual vt100, and the xterm docs (ctlseqs.ms). +.\" Substantial portions of this text are derived from a write-up +.\" by Eric S. Raymond . +.\" +.\" Tiny correction, aeb, 961107. +.\" +.\" 2006-05-27, Several corrections - Thomas E. Dickey +.\" +.TH console_codes 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +console_codes \- Linux console escape and control sequences +.SH DESCRIPTION +The Linux console implements a large subset of +the VT102 and ECMA-48 / ISO/IEC\~6429 / ANSI X3.64 terminal controls, +plus certain private-mode sequences +for changing the color palette, character-set mapping, and so on. +In the tabular descriptions below, the second column gives ECMA-48 or DEC +mnemonics (the latter if prefixed with DEC) for the given function. +Sequences without a mnemonic are neither ECMA-48 nor VT102. +.P +After all the normal output processing has been done, and a +stream of characters arrives at the console driver for actual +printing, the first thing that happens is a translation from +the code used for processing to the code used for printing. +.P +If the console is in UTF-8 mode, then the incoming bytes are +first assembled into 16-bit Unicode codes. +Otherwise, each byte is transformed according to the current mapping table +(which translates it to a Unicode value). +See the \fBCharacter Sets\fP section below for discussion. +.P +In the normal case, the Unicode value is converted to a font index, +and this is stored in video memory, so that the corresponding glyph +(as found in video ROM) appears on the screen. +Note that the use of Unicode (and the design of the PC hardware) +allows us to use 512 different glyphs simultaneously. +.P +If the current Unicode value is a control character, or we are +currently processing an escape sequence, the value will treated +specially. +Instead of being turned into a font index and rendered as +a glyph, it may trigger cursor movement or other control functions. +See the \fBLinux Console Controls\fP section below for discussion. +.P +It is generally not good practice to hard-wire terminal controls into +programs. +Linux supports a +.BR terminfo (5) +database of terminal capabilities. +Rather than emitting console escape sequences by hand, you will almost +always want to use a terminfo-aware screen library or utility such as +.BR ncurses (3), +.BR tput (1), +or +.BR reset (1). +.SS Linux console controls +This section describes all the control characters and escape sequences +that invoke special functions (i.e., anything other than writing a +glyph at the current cursor location) on the Linux console. +.P +.B "Control characters" +.P +A character is a control character if (before transformation +according to the mapping table) it has one of the 14 codes +00 (NUL), 07 (BEL), 08 (BS), 09 (HT), 0a (LF), 0b (VT), +0c (FF), 0d (CR), 0e (SO), 0f (SI), 18 (CAN), 1a (SUB), +1b (ESC), 7f (DEL). +One can set a "display control characters" mode (see below), +and allow 07, 09, 0b, 18, 1a, 7f to be displayed as glyphs. +On the other hand, in UTF-8 mode all codes 00\[en]1f are regarded +as control characters, regardless of any "display control characters" +mode. +.P +If we have a control character, it is acted upon immediately +and then discarded (even in the middle of an escape sequence) +and the escape sequence continues with the next character. +(However, ESC starts a new escape sequence, possibly aborting a previous +unfinished one, and CAN and SUB abort any escape sequence.) +The recognized control characters are BEL, BS, HT, LF, VT, FF, +CR, SO, SI, CAN, SUB, ESC, DEL, CSI. +They do what one would expect: +.TP +BEL (0x07, \fB\[ha]G\fP) +beeps; +.TP +BS (0x08, \fB\[ha]H\fP) +backspaces one column +(but not past the beginning of the line); +.TP +HT (0x09, \fB\[ha]I\fP) +goes to the next tab stop or to the end of the line +if there is no earlier tab stop; +.TP +LF (0x0A, \fB\[ha]J\fP) +.TQ +VT (0x0B, \fB\[ha]K\fP) +.TQ +FF (0x0C, \fB\[ha]L\fP) +all give a linefeed, +and if LF/NL (new-line mode) is set also a carriage return; +.TP +CR (0x0D, \fB\[ha]M\fP) +gives a carriage return; +.TP +SO (0x0E, \fB\[ha]N\fP) +activates the G1 character set; +.TP +SI (0x0F, \fB\[ha]O\fP) +activates the G0 character set; +.TP +CAN (0x18, \fB\[ha]X\fP) +.TQ +SUB (0x1A, \fB\[ha]Z\fP) +abort escape sequences; +.TP +ESC (0x1B, \fB\[ha][\fP) +starts an escape sequence; +.TP +DEL (0x7F) +is ignored; +.TP +CSI (0x9B) +is equivalent to ESC [. +.P +.B "ESC- but not CSI-sequences" +.ad l +.TS +l l lx. +ESC c RIS Reset. +ESC D IND Linefeed. +ESC E NEL Newline. +ESC H HTS Set tab stop at current column. +ESC M RI Reverse linefeed. +ESC Z DECID T{ +DEC private identification. The kernel +returns the string ESC [ ? 6 c, claiming +that it is a VT102. +T} +ESC 7 DECSC T{ +Save current state (cursor coordinates, +attributes, character sets pointed at by G0, G1). +T} +ESC 8 DECRC T{ +Restore state most recently saved by ESC 7. +T} +ESC % Start sequence selecting character set +ESC % @ \0\0\0Select default (ISO/IEC\~646 / ISO/IEC\~8859-1) +ESC % G \0\0\0Select UTF-8 +ESC % 8 \0\0\0Select UTF-8 (obsolete) +ESC # 8 DECALN T{ +DEC screen alignment test \- fill screen with E's. +T} +ESC ( T{ +Start sequence defining G0 character set +(followed by one of B, 0, U, K, as below) +T} +ESC ( B T{ +Select default (ISO/IEC\~8859-1 mapping). +T} +ESC ( 0 T{ +Select VT100 graphics mapping. +T} +ESC ( U T{ +Select null mapping \- straight to character ROM. +T} +ESC ( K T{ +Select user mapping \- the map that is loaded by the utility \fBmapscrn\fP(8). +T} +ESC ) T{ +Start sequence defining G1 (followed by one of B, 0, U, K, as above). +T} +ESC > DECPNM Set numeric keypad mode +ESC = DECPAM Set application keypad mode +ESC ] OSC T{ +Operating System Command prefix. +T} +ESC ] R Reset palette. +ESC ] P T{ +Set palette, with parameter given in 7 hexadecimal digits \fInrrggbb\fP after +the final P. Here \fIn\fP is the color (0\[en]15), and \fIrrggbb\fP indicates +the red/green/blue values (0\[en]255). +T} +.TE +.ad +.P +.B "ECMA-48 CSI sequences" +.P +CSI (or ESC [) is followed by a sequence of parameters, +at most NPAR (16), that are decimal numbers separated by +semicolons. +An empty or absent parameter is taken to be 0. +The sequence of parameters may be preceded by a single question mark. +.P +However, after CSI [ (or ESC [ [) a single character is read +and this entire sequence is ignored. +(The idea is to ignore an echoed function key.) +.P +The action of a CSI sequence is determined by its final character. +.ad l +.TS +l l lx. +@ ICH T{ +Insert the indicated # of blank characters. +T} +A CUU T{ +Move cursor up the indicated # of rows. +T} +B CUD T{ +Move cursor down the indicated # of rows. +T} +C CUF T{ +Move cursor right the indicated # of columns. +T} +D CUB T{ +Move cursor left the indicated # of columns. +T} +E CNL T{ +Move cursor down the indicated # of rows, to column 1. +T} +F CPL T{ +Move cursor up the indicated # of rows, to column 1. +T} +G CHA T{ +Move cursor to indicated column in current row. +T} +H CUP T{ +Move cursor to the indicated row, column (origin at 1,1). +T} +J ED T{ +Erase display (default: from cursor to end of display). +T} + T{ +ESC [ 1 J: erase from start to cursor. +T} + T{ +ESC [ 2 J: erase whole display. +T} + T{ +ESC [ 3 J: erase whole display including scroll-back +buffer (since Linux 3.0). +T} +.\" ESC [ 3 J: commit f8df13e0a901fe55631fed66562369b4dba40f8b +K EL T{ +Erase line (default: from cursor to end of line). +T} + T{ +ESC [ 1 K: erase from start of line to cursor. +T} + T{ +ESC [ 2 K: erase whole line. +T} +L IL T{ +Insert the indicated # of blank lines. +T} +M DL T{ +Delete the indicated # of lines. +T} +P DCH T{ +Delete the indicated # of characters on current line. +T} +X ECH T{ +Erase the indicated # of characters on current line. +T} +a HPR T{ +Move cursor right the indicated # of columns. +T} +c DA T{ +Answer ESC [ ? 6 c: "I am a VT102". +T} +d VPA T{ +Move cursor to the indicated row, current column. +T} +e VPR T{ +Move cursor down the indicated # of rows. +T} +f HVP T{ +Move cursor to the indicated row, column. +T} +g TBC T{ +Without parameter: clear tab stop at current position. +T} + T{ +ESC [ 3 g: delete all tab stops. +T} +h SM Set Mode (see below). +l RM Reset Mode (see below). +m SGR Set attributes (see below). +n DSR Status report (see below). +q DECLL Set keyboard LEDs. + ESC [ 0 q: clear all LEDs + ESC [ 1 q: set Scroll Lock LED + ESC [ 2 q: set Num Lock LED + ESC [ 3 q: set Caps Lock LED +r DECSTBM T{ +Set scrolling region; parameters are top and bottom row. +T} +s ? Save cursor location. +u ? Restore cursor location. +\` HPA T{ +Move cursor to indicated column in current row. +T} +.TE +.ad +.P +.B ECMA-48 Select Graphic Rendition +.P +The ECMA-48 SGR sequence ESC [ \fIparameters\fP m sets display +attributes. +Several attributes can be set in the same sequence, separated by +semicolons. +An empty parameter (between semicolons or string initiator or +terminator) is interpreted as a zero. +.ad l +.TS +l lx. +param result +0 T{ +reset all attributes to their defaults +T} +1 set bold +2 T{ +set half-bright (simulated with color on a color display) +T} +3 set italic (since Linux 2.6.22; simulated with color on a color display) +4 T{ +set underscore (simulated with color on a color display) +(the colors used to simulate dim or underline are set +using ESC ] ...) +T} +5 set blink +7 set reverse video +10 T{ +reset selected mapping, display control flag, +and toggle meta flag (ECMA-48 says "primary font"). +T} +11 T{ +select null mapping, set display control flag, +reset toggle meta flag (ECMA-48 says "first alternate font"). +T} +12 T{ +select null mapping, set display control flag, +set toggle meta flag (ECMA-48 says "second alternate font"). +The toggle meta flag +causes the high bit of a byte to be toggled +before the mapping table translation is done. +T} +21 T{ +set underline; before Linux 4.17, this value +set normal intensity (as is done in many other terminals) +T} +22 set normal intensity +23 italic off (since Linux 2.6.22) +24 underline off +25 blink off +27 reverse video off +30 set black foreground +31 set red foreground +32 set green foreground +33 set brown foreground +34 set blue foreground +35 set magenta foreground +36 set cyan foreground +37 set white foreground +38 T{ +256/24-bit foreground color follows, shoehorned into 16 basic colors +(before Linux 3.16: set underscore on, set default foreground color) +T} +39 T{ +set default foreground color +(before Linux 3.16: set underscore off, set default foreground color) +T} +40 set black background +41 set red background +42 set green background +43 set brown background +44 set blue background +45 set magenta background +46 set cyan background +47 set white background +48 T{ +256/24-bit background color follows, shoehorned into 8 basic colors +T} +49 set default background color +90..97 T{ +set foreground to bright versions of 30..37 +T} +100..107 T{ +set background, same as 40..47 (bright not supported) +T} +.TE +.ad +.P +Commands 38 and 48 require further arguments: +.TS +l lx. +;5;x T{ +256 color: values 0..15 are IBGR (black, red, green, ... white), +16..231 a 6x6x6 color cube, 232..255 a grayscale ramp +T} +;2;r;g;b T{ +24-bit color, r/g/b components are in the range 0..255 +T} +.TE +.P +.B ECMA-48 Mode Switches +.TP +ESC [ 3 h +DECCRM (default off): Display control chars. +.TP +ESC [ 4 h +DECIM (default off): Set insert mode. +.TP +ESC [ 20 h +LF/NL (default off): Automatically follow echo of LF, VT, or FF with CR. +.\" +.P +.B ECMA-48 Status Report Commands +.\" +.TP +ESC [ 5 n +Device status report (DSR): Answer is ESC [ 0 n (Terminal OK). +.TP +ESC [ 6 n +Cursor position report (CPR): Answer is ESC [ \fIy\fP ; \fIx\fP R, +where \fIx,y\fP is the cursor location. +.\" +.P +.B DEC Private Mode (DECSET/DECRST) sequences +.P +.\" +These are not described in ECMA-48. +We list the Set Mode sequences; +the Reset Mode sequences are obtained by replacing the final \[aq]h\[aq] +by \[aq]l\[aq]. +.TP +ESC [ ? 1 h +DECCKM (default off): When set, the cursor keys send an ESC O prefix, +rather than ESC [. +.TP +ESC [ ? 3 h +DECCOLM (default off = 80 columns): 80/132 col mode switch. +The driver sources note that this alone does not suffice; some user-mode +utility such as +.BR resizecons (8) +has to change the hardware registers on the console video card. +.TP +ESC [ ? 5 h +DECSCNM (default off): Set reverse-video mode. +.TP +ESC [ ? 6 h +DECOM (default off): When set, cursor addressing is relative to +the upper left corner of the scrolling region. +.TP +ESC [ ? 7 h +DECAWM (default on): Set autowrap on. +In this mode, a graphic +character emitted after column 80 (or column 132 of DECCOLM is on) +forces a wrap to the beginning of the following line first. +.TP +ESC [ ? 8 h +DECARM (default on): Set keyboard autorepeat on. +.TP +ESC [ ? 9 h +X10 Mouse Reporting (default off): Set reporting mode to 1 (or reset to +0)\[em]see below. +.TP +ESC [ ? 25 h +DECTECM (default on): Make cursor visible. +.TP +ESC [ ? 1000 h +X11 Mouse Reporting (default off): Set reporting mode to 2 (or reset +to 0)\[em]see below. +.\" +.P +.B Linux Console Private CSI Sequences +.P +.\" +The following sequences are neither ECMA-48 nor native VT102. +They are native to the Linux console driver. +Colors are in SGR parameters: +0 = black, 1 = red, 2 = green, 3 = brown, 4 = blue, 5 = magenta, 6 = +cyan, 7 = white; 8\[en]15 = bright versions of 0\[en]7. +.TS +l lx. +ESC [ 1 ; \fIn\fP ] T{ +Set color \fIn\fP as the underline color. +T} +ESC [ 2 ; \fIn\fP ] T{ +Set color \fIn\fP as the dim color. +T} +ESC [ 8 ] T{ +Make the current color pair the default attributes. +T} +ESC [ 9 ; \fIn\fP ] T{ +Set screen blank timeout to \fIn\fP minutes. +T} +ESC [ 10 ; \fIn\fP ] T{ +Set bell frequency in Hz. +T} +ESC [ 11 ; \fIn\fP ] T{ +Set bell duration in msec. +T} +ESC [ 12 ; \fIn\fP ] T{ +Bring specified console to the front. +T} +ESC [ 13 ] T{ +Unblank the screen. +T} +ESC [ 14 ; \fIn\fP ] T{ +Set the VESA powerdown interval in minutes. +T} +ESC [ 15 ] T{ +Bring the previous console to the front +(since Linux 2.6.0). +T} +ESC [ 16 ; \fIn\fP ] T{ +Set the cursor blink interval in milliseconds +(since Linux 4.2). +T} +.\" commit bd63364caa8df38bad2b25b11b2a1b849475cce5 +.TE +.SS Character sets +The kernel knows about 4 translations of bytes into console-screen +symbols. +The four tables are: a) Latin1 \-> PC, +b) VT100 graphics \-> PC, c) PC \-> PC, d) user-defined. +.P +There are two character sets, called G0 and G1, and one of them +is the current character set. +(Initially G0.) +Typing \fB\[ha]N\fP causes G1 to become current, +\fB\[ha]O\fP causes G0 to become current. +.P +These variables G0 and G1 point at a translation table, and can be +changed by the user. +Initially they point at tables a) and b), respectively. +The sequences ESC ( B and ESC ( 0 and ESC ( U and ESC ( K cause G0 to +point at translation table a), b), c), and d), respectively. +The sequences ESC ) B and ESC ) 0 and ESC ) U and ESC ) K cause G1 to +point at translation table a), b), c), and d), respectively. +.P +The sequence ESC c causes a terminal reset, which is what you want if the +screen is all garbled. +The oft-advised "echo \[ha]V\[ha]O" will make only G0 current, +but there is no guarantee that G0 points at table a). +In some distributions there is a program +.BR reset (1) +that just does "echo \[ha][c". +If your terminfo entry for the console is correct +(and has an entry rs1=\eEc), then "tput reset" will also work. +.P +The user-defined mapping table can be set using +.BR mapscrn (8). +The result of the mapping is that if a symbol c is printed, the symbol +s = map[c] is sent to the video memory. +The bitmap that corresponds to +s is found in the character ROM, and can be changed using +.BR setfont (8). +.SS Mouse tracking +The mouse tracking facility is intended to return +.BR xterm (1)-compatible +mouse status reports. +Because the console driver has no way to know +the device or type of the mouse, these reports are returned in the +console input stream only when the virtual terminal driver receives +a mouse update ioctl. +These ioctls must be generated by a mouse-aware +user-mode application such as the +.BR gpm (8) +daemon. +.P +The mouse tracking escape sequences generated by +\fBxterm\fP(1) encode numeric parameters in a single character as +\fIvalue\fP+040. +For example, \[aq]!\[aq] is 1. +The screen coordinate system is 1-based. +.P +The X10 compatibility mode sends an escape sequence on button press +encoding the location and the mouse button pressed. +It is enabled by sending ESC [ ? 9 h and disabled with ESC [ ? 9 l. +On button press, \fBxterm\fP(1) sends +ESC [ M \fIbxy\fP (6 characters). +Here \fIb\fP is button\-1, +and \fIx\fP and \fIy\fP are the x and y coordinates of the mouse +when the button was pressed. +This is the same code the kernel also produces. +.P +Normal tracking mode (not implemented in Linux 2.0.24) sends an escape +sequence on both button press and release. +Modifier information is also sent. +It is enabled by sending ESC [ ? 1000 h and disabled with +ESC [ ? 1000 l. +On button press or release, \fBxterm\fP(1) sends ESC [ M +\fIbxy\fP. +The low two bits of \fIb\fP encode button information: +0=MB1 pressed, 1=MB2 pressed, 2=MB3 pressed, 3=release. +The upper bits encode what modifiers were down when the button was +pressed and are added together: 4=Shift, 8=Meta, 16=Control. +Again \fIx\fP and +\fIy\fP are the x and y coordinates of the mouse event. +The upper left corner is (1,1). +.SS Comparisons with other terminals +Many different terminal types are described, like the Linux console, +as being "VT100-compatible". +Here we discuss differences between the +Linux console and the two most important others, the DEC VT102 and +.BR xterm (1). +.\" +.P +.B Control-character handling +.P +The VT102 also recognized the following control characters: +.TP +NUL (0x00) +was ignored; +.TP +ENQ (0x05) +triggered an answerback message; +.TP +DC1 (0x11, \fB\[ha]Q\fP, XON) +resumed transmission; +.TP +DC3 (0x13, \fB\[ha]S\fP, XOFF) +caused VT100 to ignore (and stop transmitting) +all codes except XOFF and XON. +.P +VT100-like DC1/DC3 processing may be enabled by the terminal driver. +.P +The +.BR xterm (1) +program (in VT100 mode) recognizes the control characters +BEL, BS, HT, LF, VT, FF, CR, SO, SI, ESC. +.\" +.P +.B Escape sequences +.P +VT100 console sequences not implemented on the Linux console: +.TS +l l l. +ESC N SS2 T{ +Single shift 2. (Select G2 character set for the next character only.) +T} +ESC O SS3 T{ +Single shift 3. (Select G3 character set for the next character only.) +T} +ESC P DCS T{ +Device control string (ended by ESC \e) +T} +ESC X SOS Start of string. +ESC \[ha] PM Privacy message (ended by ESC \e) +ESC \e ST String terminator +ESC * ... Designate G2 character set +ESC + ... Designate G3 character set +.TE +.P +The program +.BR xterm (1) +(in VT100 mode) recognizes ESC c, ESC # 8, ESC >, ESC =, +ESC D, ESC E, ESC H, ESC M, ESC N, ESC O, ESC P ... ESC \e, +ESC Z (it answers ESC [ ? 1 ; 2 c, "I am a VT100 with +advanced video option") +and ESC \[ha] ... ESC \e with the same meanings as indicated above. +It accepts ESC (, ESC ), ESC *, ESC + followed by 0, A, B for +the DEC special character and line drawing set, UK, and US-ASCII, +respectively. +.P +The user can configure \fBxterm\fP(1) to respond to VT220-specific +control sequences, and it will identify itself as a VT52, VT100, and +up depending on the way it is configured and initialized. +.P +It accepts ESC ] (OSC) for the setting of certain resources. +In addition to the ECMA-48 string terminator (ST), +\fBxterm\fP(1) accepts a BEL to terminate an OSC string. +These are a few of the OSC control sequences recognized by \fBxterm\fP(1): +.TS +l l. +ESC ] 0 ; \fItxt\fP ST T{ +Set icon name and window title to \fItxt\fP. +T} +ESC ] 1 ; \fItxt\fP ST Set icon name to \fItxt\fP. +ESC ] 2 ; \fItxt\fP ST Set window title to \fItxt\fP. +ESC ] 4 ; \fInum\fP; \fItxt\fP ST Set ANSI color \fInum\fP to \fItxt\fP. +ESC ] 10 ; \fItxt\fP ST Set dynamic text color to \fItxt\fP. +ESC ] 4 6 ; \fIname\fP ST T{ +Change log file to \fIname\fP (normally disabled by a compile-time option). +T} +ESC ] 5 0 ; \fIfn\fP ST Set font to \fIfn\fP. +.TE +.P +It recognizes the following with slightly modified meaning +(saving more state, behaving closer to VT100/VT220): +.TS +l l l. +ESC 7 DECSC Save cursor +ESC 8 DECRC Restore cursor +.TE +.P +It also recognizes +.TS +l l lx. +ESC F T{ +Cursor to lower left corner of screen (if enabled +by \fBxterm\fP(1)'s \fBhpLowerleftBugCompat\fP resource). +T} +ESC l Memory lock (per HP terminals). + Locks memory above the cursor. +ESC m Memory unlock (per HP terminals). +ESC n LS2 Invoke the G2 character set. +ESC o LS3 Invoke the G3 character set. +ESC | LS3R Invoke the G3 character set as GR. +ESC } LS2R Invoke the G2 character set as GR. +ESC \[ti] LS1R Invoke the G1 character set as GR. +.TE +.P +It also recognizes ESC % and provides a more complete UTF-8 +implementation than Linux console. +.\" +.P +.B CSI Sequences +.P +Old versions of \fBxterm\fP(1), for example, from X11R5, +interpret the blink SGR as a bold SGR. +Later versions which implemented ANSI colors, for example, +XFree86 3.1.2A in 1995, improved this by allowing +the blink attribute to be displayed as a color. +Modern versions of xterm implement blink SGR as blinking text +and still allow colored text as an alternate rendering of SGRs. +Stock X11R6 versions did not recognize the color-setting SGRs until +the X11R6.8 release, which incorporated XFree86 xterm. +All ECMA-48 CSI sequences recognized by Linux are also recognized by +.IR xterm , +however \fBxterm\fP(1) implements several ECMA-48 and DEC control sequences +not recognized by Linux. +.P +The \fBxterm\fP(1) +program recognizes all of the DEC Private Mode sequences listed +above, but none of the Linux private-mode sequences. +For discussion of \fBxterm\fP(1)'s +own private-mode sequences, refer to the +\fIXterm Control Sequences\fP +document by +Edward Moy, +Stephen Gildea, +and Thomas E.\& Dickey +available with the X distribution. +That document, though terse, is much longer than this manual page. +For a chronological overview, +.P +.RS +.UR http://invisible\-island.net\:/xterm\:/xterm.log.html +.UE +.RE +.P +details changes to xterm. +.P +The \fIvttest\fP program +.P +.RS +.UR http://invisible\-island.net\:/vttest/ +.UE +.RE +.P +demonstrates many of these control sequences. +The \fBxterm\fP(1) source distribution also contains sample +scripts which exercise other features. +.SH NOTES +ESC 8 (DECRC) is not able to restore the character set changed with +ESC %. +.SH BUGS +In Linux 2.0.23, CSI is broken, and NUL is not ignored inside +escape sequences. +.P +Some older kernel versions (after Linux 2.0) interpret 8-bit control +sequences. +These "C1 controls" use codes between 128 and 159 to replace +ESC [, ESC ] and similar two-byte control sequence initiators. +There are fragments of that in modern kernels (either overlooked or +broken by changes to support UTF-8), +but the implementation is incomplete and should be regarded +as unreliable. +.P +Linux "private mode" sequences do not follow the rules in ECMA-48 +for private mode control sequences. +In particular, those ending with ] do not use a standard terminating +character. +The OSC (set palette) sequence is a greater problem, +since \fBxterm\fP(1) may interpret this as a control sequence +which requires a string terminator (ST). +Unlike the \fBsetterm\fP(1) sequences which will be ignored (since +they are invalid control sequences), the palette sequence will make +\fBxterm\fP(1) appear to hang (though pressing the return-key +will fix that). +To accommodate applications which have been hardcoded to use Linux +control sequences, +set the \fBxterm\fP(1) resource \fBbrokenLinuxOSC\fP to true. +.P +An older version of this document implied that Linux recognizes the +ECMA-48 control sequence for invisible text. +It is ignored. +.SH SEE ALSO +.BR ioctl_console (2), +.BR charsets (7) diff --git a/man/man4/console_ioctl.4 b/man/man4/console_ioctl.4 new file mode 100644 index 0000000..5dfc68d --- /dev/null +++ b/man/man4/console_ioctl.4 @@ -0,0 +1,2 @@ +.so man2/ioctl_console.2 +.\" Link for old name of this page diff --git a/man/man4/cpuid.4 b/man/man4/cpuid.4 new file mode 100644 index 0000000..a09d87a --- /dev/null +++ b/man/man4/cpuid.4 @@ -0,0 +1,83 @@ +.\" Copyright (c) 2009 Intel Corporation, Author Andi Kleen +.\" Description based on comments in arch/x86/kernel/cpuid.c +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH cpuid 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cpuid \- x86 CPUID access device +.SH DESCRIPTION +CPUID provides an interface for querying information about the x86 CPU. +.P +This device is accessed by +.BR lseek (2) +or +.BR pread (2) +to the appropriate CPUID level and reading in chunks of 16 bytes. +A larger read size means multiple reads of consecutive levels. +.P +The lower 32 bits of the file position is used as the incoming +.IR %eax , +and the upper 32 bits of the file position as the incoming +.IR %ecx , +the latter is intended for "counting" +.I eax +levels like +.IR eax=4 . +.P +This driver uses +.IR /dev/cpu/CPUNUM/cpuid , +where +.I CPUNUM +is the minor number, +and on an SMP box will direct the access to CPU +.I CPUNUM +as listed in +.IR /proc/cpuinfo . +.P +This file is protected so that it can be read only by the user +.IR root , +or members of the group +.IR root . +.SH NOTES +The CPUID instruction can be directly executed by a program +using inline assembler. +However this device allows convenient +access to all CPUs without changing process affinity. +.P +Most of the information in +.I cpuid +is reported by the kernel in cooked form either in +.I /proc/cpuinfo +or through subdirectories in +.IR /sys/devices/system/cpu . +Direct CPUID access through this device should only +be used in exceptional cases. +.P +The +.I cpuid +driver is not auto-loaded. +On modular kernels you might need to use the following command +to load it explicitly before use: +.P +.in +4n +.EX +$ modprobe cpuid +.EE +.in +.P +There is no support for CPUID functions that require additional +input registers. +.P +Early i486 CPUs do not support the CPUID instruction; +.\" arch/x86/kernel/cpuid.c cpuid_open() +opening this device for those CPUs fails with EIO. +.SH SEE ALSO +.BR cpuid (1) +.P +Intel Corporation, Intel 64 and IA-32 Architectures +Software Developer's Manual Volume 2A: +Instruction Set Reference, A-M, 3-180 CPUID reference. +.P +Intel Corporation, Intel Processor Identification and +the CPUID Instruction, Application note 485. diff --git a/man/man4/dsp56k.4 b/man/man4/dsp56k.4 new file mode 100644 index 0000000..f0aed35 --- /dev/null +++ b/man/man4/dsp56k.4 @@ -0,0 +1,107 @@ +.\" Copyright (c) 2000 lars brinkhoff +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, Thu Jan 27 19:16:19 CET 2000, lars@nocrew.org +.\" +.TH dsp56k 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dsp56k \- DSP56001 interface device +.SH SYNOPSIS +.nf +.B #include +.P +.BI "ssize_t read(int " fd ", void *" data ", size_t " length ); +.BI "ssize_t write(int " fd ", void *" data ", size_t " length ); +.P +.BI "int ioctl(int " fd ", DSP56K_UPLOAD, struct dsp56k_upload *" program ); +.BI "int ioctl(int " fd ", DSP56K_SET_TX_WSIZE, int " wsize ); +.BI "int ioctl(int " fd ", DSP56K_SET_RX_WSIZE, int " wsize ); +.BI "int ioctl(int " fd ", DSP56K_HOST_FLAGS, struct dsp56k_host_flags *" flags ); +.BI "int ioctl(int " fd ", DSP56K_HOST_CMD, int " cmd ); +.fi +.SH CONFIGURATION +The +.I dsp56k +device is a character device with major number 55 and minor +number 0. +.SH DESCRIPTION +The Motorola DSP56001 is a fully programmable 24-bit digital signal +processor found in Atari Falcon030-compatible computers. +The \fIdsp56k\fP special file is used to control the DSP56001, and +to send and receive data using the bidirectional handshaked host +port. +.P +To send a data stream to the signal processor, use +.BR write (2) +to the +device, and +.BR read (2) +to receive processed data. +The data can be sent or +received in 8, 16, 24, or 32-bit quantities on the host side, but will +always be seen as 24-bit quantities in the DSP56001. +.P +The following +.BR ioctl (2) +calls are used to control the +\fIdsp56k\fP device: +.TP +.B DSP56K_UPLOAD +resets the DSP56001 and uploads a program. +The third +.BR ioctl (2) +argument must be a pointer to a \fIstruct dsp56k_upload\fP with members +\fIbin\fP pointing to a DSP56001 binary program, and \fIlen\fP set to +the length of the program, counted in 24-bit words. +.TP +.B DSP56K_SET_TX_WSIZE +sets the transmit word size. +Allowed values are in the range 1 to 4, +and is the number of bytes that will be sent at a time to the +DSP56001. +These data quantities will either be padded with bytes containing zero, +or truncated to fit the native 24-bit data format of the +DSP56001. +.TP +.B DSP56K_SET_RX_WSIZE +sets the receive word size. +Allowed values are in the range 1 to 4, +and is the number of bytes that will be received at a time from the DSP56001. +These data quantities will either truncated, +or padded with a null byte (\[aq]\e0\[aq]), +to fit the native 24-bit data format of the DSP56001. +.TP +.B DSP56K_HOST_FLAGS +read and write the host flags. +The host flags are four +general-purpose bits that can be read by both the hosting computer and +the DSP56001. +Bits 0 and 1 can be written by the host, and bits 2 and +3 can be written by the DSP56001. +.IP +To access the host flags, the third +.BR ioctl (2) +argument must be a pointer +to a \fIstruct dsp56k_host_flags\fP. +If bit 0 or 1 is set in the +\fIdir\fP member, the corresponding bit in \fIout\fP will be written +to the host flags. +The state of all host flags will be returned in +the lower four bits of the \fIstatus\fP member. +.TP +.B DSP56K_HOST_CMD +sends a host command. +Allowed values are in the range 0 to 31, and is a +user-defined command handled by the program running in the DSP56001. +.SH FILES +.I /dev/dsp56k +.\" .SH AUTHORS +.\" Fredrik Noring , lars brinkhoff , +.\" Tomas Berndtsson . +.SH SEE ALSO +.IR linux/include/asm\-m68k/dsp56k.h , +.IR linux/drivers/char/dsp56k.c , +.UR http://dsp56k.nocrew.org/ +.UE , +DSP56000/DSP56001 Digital Signal Processor User's Manual diff --git a/man/man4/fd.4 b/man/man4/fd.4 new file mode 100644 index 0000000..2dbcaf0 --- /dev/null +++ b/man/man4/fd.4 @@ -0,0 +1,232 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de) +.\" and 1994,1995 Alain Knaff (Alain.Knaff@imag.fr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, Sun Feb 26 15:00:02 1995, faith@cs.unc.edu +.\" +.TH fd 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fd \- floppy disk device +.SH CONFIGURATION +Floppy drives are block devices with major number 2. +Typically they +are owned by +root:floppy +(i.e., user root, group floppy) and have +either mode 0660 (access checking via group membership) or mode 0666 +(everybody has access). +The minor +numbers encode the device type, drive number, and controller number. +For each device type (that is, combination of density and track count) +there is a base minor number. +To this base number, add the drive's +number on its controller and 128 if the drive is on the secondary +controller. +In the following device tables, \fIn\fP represents the +drive number. +.P +\fBWarning: if you use formats with more tracks +than supported by your drive, you may cause it mechanical damage.\fP +Trying once if more tracks than the usual 40/80 are supported should not +damage it, but no warranty is given for that. +If you are not sure, don't create device +entries for those formats, so as to prevent their usage. +.P +Drive-independent device files which automatically detect the media +format and capacity: +.TS +l c +l c. +Name Base + minor # +_ +\fBfd\fP\fIn\fP 0 +.TE +.P +5.25 inch double-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBd360\fP 360 40 9 2 4 +.TE +.P +5.25 inch high-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBh360\fP 360 40 9 2 20 +\fBfd\fP\fIn\fP\fBh410\fP 410 41 10 2 48 +\fBfd\fP\fIn\fP\fBh420\fP 420 42 10 2 64 +\fBfd\fP\fIn\fP\fBh720\fP 720 80 9 2 24 +\fBfd\fP\fIn\fP\fBh880\fP 880 80 11 2 80 +\fBfd\fP\fIn\fP\fBh1200\fP 1200 80 15 2 8 +\fBfd\fP\fIn\fP\fBh1440\fP 1440 80 18 2 40 +\fBfd\fP\fIn\fP\fBh1476\fP 1476 82 18 2 56 +\fBfd\fP\fIn\fP\fBh1494\fP 1494 83 18 2 72 +\fBfd\fP\fIn\fP\fBh1600\fP 1600 80 20 2 92 +.TE +.P +3.5 inch double-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBu360\fP 360 80 9 1 12 +\fBfd\fP\fIn\fP\fBu720\fP 720 80 9 2 16 +\fBfd\fP\fIn\fP\fBu800\fP 800 80 10 2 120 +\fBfd\fP\fIn\fP\fBu1040\fP 1040 80 13 2 84 +\fBfd\fP\fIn\fP\fBu1120\fP 1120 80 14 2 88 +.TE +.P +3.5 inch high-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBu360\fP 360 40 9 2 12 +\fBfd\fP\fIn\fP\fBu720\fP 720 80 9 2 16 +\fBfd\fP\fIn\fP\fBu820\fP 820 82 10 2 52 +\fBfd\fP\fIn\fP\fBu830\fP 830 83 10 2 68 +\fBfd\fP\fIn\fP\fBu1440\fP 1440 80 18 2 28 +\fBfd\fP\fIn\fP\fBu1600\fP 1600 80 20 2 124 +\fBfd\fP\fIn\fP\fBu1680\fP 1680 80 21 2 44 +\fBfd\fP\fIn\fP\fBu1722\fP 1722 82 21 2 60 +\fBfd\fP\fIn\fP\fBu1743\fP 1743 83 21 2 76 +\fBfd\fP\fIn\fP\fBu1760\fP 1760 80 22 2 96 +\fBfd\fP\fIn\fP\fBu1840\fP 1840 80 23 2 116 +\fBfd\fP\fIn\fP\fBu1920\fP 1920 80 24 2 100 +.TE +.P +3.5 inch extra-density device files: +.TS +lw(1i) l l l l c +lw(1i) c c c c c. +Name Capacity Cyl. Sect. Heads Base + KiB minor # +_ +\fBfd\fP\fIn\fP\fBu2880\fP 2880 80 36 2 32 +\fBfd\fP\fIn\fP\fBCompaQ\fP 2880 80 36 2 36 +\fBfd\fP\fIn\fP\fBu3200\fP 3200 80 40 2 104 +\fBfd\fP\fIn\fP\fBu3520\fP 3520 80 44 2 108 +\fBfd\fP\fIn\fP\fBu3840\fP 3840 80 48 2 112 +.TE +.SH DESCRIPTION +\fBfd\fP special files access the floppy disk drives in raw mode. +The following +.BR ioctl (2) +calls are supported by \fBfd\fP devices: +.TP +.B FDCLRPRM +clears the media information of a drive (geometry of disk in drive). +.TP +.B FDSETPRM +sets the media information of a drive. +The media information will be +lost when the media is changed. +.TP +.B FDDEFPRM +sets the media information of a drive (geometry of disk in drive). +The media information will not be lost when the media is changed. +This will disable autodetection. +In order to reenable autodetection, you +have to issue an \fBFDCLRPRM\fP. +.TP +.B FDGETDRVTYP +returns the type of a drive (name parameter). +For formats which work +in several drive types, \fBFDGETDRVTYP\fP returns a name which is +appropriate for the oldest drive type which supports this format. +.TP +.B FDFLUSH +invalidates the buffer cache for the given drive. +.TP +.B FDSETMAXERRS +sets the error thresholds for reporting errors, aborting the operation, +recalibrating, resetting, and reading sector by sector. +.TP +.B FDSETMAXERRS +gets the current error thresholds. +.TP +.B FDGETDRVTYP +gets the internal name of the drive. +.TP +.B FDWERRORCLR +clears the write error statistics. +.TP +.B FDWERRORGET +reads the write error statistics. +These include the total number of +write errors, the location and disk of the first write error, and the +location and disk of the last write error. +Disks are identified by a +generation number which is incremented at (almost) each disk change. +.TP +.B FDTWADDLE +Switch the drive motor off for a few microseconds. +This might be +needed in order to access a disk whose sectors are too close together. +.TP +.B FDSETDRVPRM +sets various drive parameters. +.TP +.B FDGETDRVPRM +reads these parameters back. +.TP +.B FDGETDRVSTAT +gets the cached drive state (disk changed, write protected et al.) +.TP +.B FDPOLLDRVSTAT +polls the drive and return its state. +.TP +.B FDGETFDCSTAT +gets the floppy controller state. +.TP +.B FDRESET +resets the floppy controller under certain conditions. +.TP +.B FDRAWCMD +sends a raw command to the floppy controller. +.P +For more precise information, consult also the \fI\fP and +\fI\fP include files, as well as the +.BR floppycontrol (1) +manual page. +.SH FILES +.I /dev/fd* +.SH NOTES +The various formats permit reading and writing many types of disks. +However, if a floppy is formatted with an inter-sector gap that is too small, +performance may drop, +to the point of needing a few seconds to access an entire track. +To prevent this, use interleaved formats. +.P +It is not possible to +read floppies which are formatted using GCR (group code recording), +which is used by Apple II and Macintosh computers (800k disks). +.P +Reading floppies which are hard sectored (one hole per sector, with +the index hole being a little skewed) is not supported. +This used to be common with older 8-inch floppies. +.\" .SH AUTHORS +.\" Alain Knaff (Alain.Knaff@imag.fr), David Niemi +.\" (niemidc@clark.net), Bill Broadhurst (bbroad@netcom.com). +.SH SEE ALSO +.BR chown (1), +.BR floppycontrol (1), +.BR getfdprm (1), +.BR mknod (1), +.BR superformat (1), +.BR mount (8), +.BR setfdprm (8) diff --git a/man/man4/full.4 b/man/man4/full.4 new file mode 100644 index 0000000..c9ccadd --- /dev/null +++ b/man/man4/full.4 @@ -0,0 +1,46 @@ +.\" This man-page is Copyright (C) 1997 John S. Kallal +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" correction, aeb, 970825 +.TH full 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +full \- always full device +.SH CONFIGURATION +If your system does not have +.I /dev/full +created already, it +can be created with the following commands: +.P +.in +4n +.EX +mknod \-m 666 /dev/full c 1 7 +chown root:root /dev/full +.EE +.in +.SH DESCRIPTION +The file +.I /dev/full +has major device number 1 +and minor device number 7. +.P +Writes to the +.I /dev/full +device fail with an +.B ENOSPC +error. +This can be used to test how a program handles disk-full errors. +.P +Reads from the +.I /dev/full +device will return \e0 characters. +.P +Seeks on +.I /dev/full +will always succeed. +.SH FILES +.I /dev/full +.SH SEE ALSO +.BR mknod (1), +.BR null (4), +.BR zero (4) diff --git a/man/man4/fuse.4 b/man/man4/fuse.4 new file mode 100644 index 0000000..d159d02 --- /dev/null +++ b/man/man4/fuse.4 @@ -0,0 +1,535 @@ +.\" Copyright (c) 2016 Julia Computing Inc, Keno Fischer +.\" Description based on include/uapi/fuse.h and code in fs/fuse +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH fuse 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fuse \- Filesystem in Userspace (FUSE) device +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +This device is the primary interface between the FUSE filesystem driver +and a user-space process wishing to provide the filesystem (referred to +in the rest of this manual page as the +.IR "filesystem daemon" ). +This manual page is intended for those +interested in understanding the kernel interface itself. +Those implementing a FUSE filesystem may wish to make use of +a user-space library such as +.I libfuse +that abstracts away the low-level interface. +.P +At its core, FUSE is a simple client-server protocol, in which the Linux +kernel is the client and the daemon is the server. +After obtaining a file descriptor for this device, the daemon may +.BR read (2) +requests from that file descriptor and is expected to +.BR write (2) +back its replies. +It is important to note that a file descriptor is +associated with a unique FUSE filesystem. +In particular, opening a second copy of this device, +will not allow access to resources created +through the first file descriptor (and vice versa). +.\" +.SS The basic protocol +Every message that is read by the daemon begins with a header described by +the following structure: +.P +.in +4n +.EX +struct fuse_in_header { + uint32_t len; /* Total length of the data, + including this header */ + uint32_t opcode; /* The kind of operation (see below) */ + uint64_t unique; /* A unique identifier for this request */ + uint64_t nodeid; /* ID of the filesystem object + being operated on */ + uint32_t uid; /* UID of the requesting process */ + uint32_t gid; /* GID of the requesting process */ + uint32_t pid; /* PID of the requesting process */ + uint32_t padding; +}; +.EE +.in +.P +The header is followed by a variable-length data portion +(which may be empty) specific to the requested operation +(the requested operation is indicated by +.IR opcode ). +.P +The daemon should then process the request and if applicable send +a reply (almost all operations require a reply; if they do not, +this is documented below), by performing a +.BR write (2) +to the file descriptor. +All replies must start with the following header: +.P +.in +4n +.EX +struct fuse_out_header { + uint32_t len; /* Total length of data written to + the file descriptor */ + int32_t error; /* Any error that occurred (0 if none) */ + uint64_t unique; /* The value from the + corresponding request */ +}; +.EE +.in +.P +This header is also followed by (potentially empty) variable-sized +data depending on the executed request. +However, if the reply is an error reply (i.e., +.I error +is set), +then no further payload data should be sent, independent of the request. +.\" +.SS Exchanged messages +This section should contain documentation for each of the messages +in the protocol. +This manual page is currently incomplete, +so not all messages are documented. +For each message, first the struct sent by the kernel is given, +followed by a description of the semantics of the message. +.TP +.B FUSE_INIT +.IP +.in +4n +.EX +struct fuse_init_in { + uint32_t major; + uint32_t minor; + uint32_t max_readahead; /* Since protocol v7.6 */ + uint32_t flags; /* Since protocol v7.6 */ +}; +.EE +.in +.IP +This is the first request sent by the kernel to the daemon. +It is used to negotiate the protocol version and other filesystem parameters. +Note that the protocol version may affect the layout of any structure +in the protocol (including this structure). +The daemon must thus remember the negotiated version +and flags for each session. +As of the writing of this man page, +the highest supported kernel protocol version is +.IR 7.26 . +.IP +Users should be aware that the descriptions in this manual page +may be incomplete or incorrect for older or more recent protocol versions. +.IP +The reply for this request has the following format: +.IP +.in +4n +.EX +struct fuse_init_out { + uint32_t major; + uint32_t minor; + uint32_t max_readahead; /* Since v7.6 */ + uint32_t flags; /* Since v7.6; some flags bits + were introduced later */ + uint16_t max_background; /* Since v7.13 */ + uint16_t congestion_threshold; /* Since v7.13 */ + uint32_t max_write; /* Since v7.5 */ + uint32_t time_gran; /* Since v7.6 */ + uint32_t unused[9]; +}; +.EE +.in +.IP +If the major version supported by the kernel is larger than that supported +by the daemon, the reply shall consist of only +.I uint32_t major +(following the usual header), +indicating the largest major version supported by the daemon. +The kernel will then issue a new +.B FUSE_INIT +request conforming to the older version. +In the reverse case, the daemon should +quietly fall back to the kernel's major version. +.IP +The negotiated minor version is considered to be the minimum +of the minor versions provided by the daemon and the kernel and +both parties should use the protocol corresponding to said minor version. +.TP +.B FUSE_GETATTR +.IP +.in +4n +.EX +struct fuse_getattr_in { + uint32_t getattr_flags; + uint32_t dummy; + uint64_t fh; /* Set only if + (getattr_flags & FUSE_GETATTR_FH) +}; +.EE +.in +.IP +The requested operation is to compute the attributes to be returned +by +.BR stat (2) +and similar operations for the given filesystem object. +The object for which the attributes should be computed is indicated +either by +.I header\->nodeid +or, if the +.B FUSE_GETATTR_FH +flag is set, by the file handle +.IR fh . +The latter case of operation is analogous to +.BR fstat (2). +.IP +For performance reasons, these attributes may be cached in the kernel for +a specified duration of time. +While the cache timeout has not been exceeded, +the attributes will be served from the cache and will not cause additional +.B FUSE_GETATTR +requests. +.IP +The computed attributes and the requested +cache timeout should then be returned in the following structure: +.IP +.in +4n +.EX +struct fuse_attr_out { + /* Attribute cache duration (seconds + nanoseconds) */ + uint64_t attr_valid; + uint32_t attr_valid_nsec; + uint32_t dummy; + struct fuse_attr { + uint64_t ino; + uint64_t size; + uint64_t blocks; + uint64_t atime; + uint64_t mtime; + uint64_t ctime; + uint32_t atimensec; + uint32_t mtimensec; + uint32_t ctimensec; + uint32_t mode; + uint32_t nlink; + uint32_t uid; + uint32_t gid; + uint32_t rdev; + uint32_t blksize; + uint32_t padding; + } attr; +}; +.EE +.in +.TP +.B FUSE_ACCESS +.IP +.in +4n +.EX +struct fuse_access_in { + uint32_t mask; + uint32_t padding; +}; +.EE +.in +.IP +If the +.I default_permissions +mount options is not used, this request may be used for permissions checking. +No reply data is expected, but errors may be indicated +as usual by setting the +.I error +field in the reply header (in particular, access denied errors +may be indicated by returning +.BR \-EACCES ). +.TP +.BR FUSE_OPEN " and " FUSE_OPENDIR +.in +4n +.EX +struct fuse_open_in { + uint32_t flags; /* The flags that were passed + to the open(2) */ + uint32_t unused; +}; +.EE +.in +.IP +The requested operation is to open the node indicated by +.IR header\->nodeid . +The exact semantics of what this means will depend on the +filesystem being implemented. +However, at the very least the +filesystem should validate that the requested +.I flags +are valid for the indicated resource and then send a reply with the +following format: +.IP +.in +4n +.EX +struct fuse_open_out { + uint64_t fh; + uint32_t open_flags; + uint32_t padding; +}; +.EE +.in +.IP +The +.I fh +field is an opaque identifier that the kernel will use to refer +to this resource +The +.I open_flags +field is a bit mask of any number of the flags +that indicate properties of this file handle to the kernel: +.RS 7 +.TP 18 +.B FOPEN_DIRECT_IO +Bypass page cache for this open file. +.TP +.B FOPEN_KEEP_CACHE +Don't invalidate the data cache on open. +.TP +.B FOPEN_NONSEEKABLE +The file is not seekable. +.RE +.TP +.BR FUSE_READ " and " FUSE_READDIR +.IP +.in +4n +.EX +struct fuse_read_in { + uint64_t fh; + uint64_t offset; + uint32_t size; + uint32_t read_flags; + uint64_t lock_owner; + uint32_t flags; + uint32_t padding; +}; +.EE +.in +.IP +The requested action is to read up to +.I size +bytes of the file or directory, starting at +.IR offset . +The bytes should be returned directly following the usual reply header. +.TP +.B FUSE_INTERRUPT +.in +4n +.EX +struct fuse_interrupt_in { + uint64_t unique; +}; +.EE +.in +.IP +The requested action is to cancel the pending operation indicated by +.IR unique . +This request requires no response. +However, receipt of this message does +not by itself cancel the indicated operation. +The kernel will still expect a reply to said operation (e.g., an +.I EINTR +error or a short read). +At most one +.B FUSE_INTERRUPT +request will be issued for a given operation. +After issuing said operation, +the kernel will wait uninterruptibly for completion of the indicated request. +.TP +.B FUSE_LOOKUP +Directly following the header is a filename to be looked up in the directory +indicated by +.IR header\->nodeid . +The expected reply is of the form: +.IP +.in +4n +.EX +struct fuse_entry_out { + uint64_t nodeid; /* Inode ID */ + uint64_t generation; /* Inode generation */ + uint64_t entry_valid; + uint64_t attr_valid; + uint32_t entry_valid_nsec; + uint32_t attr_valid_nsec; + struct fuse_attr attr; +}; +.EE +.in +.IP +The combination of +.I nodeid +and +.I generation +must be unique for the filesystem's lifetime. +.IP +The interpretation of timeouts and +.I attr +is as for +.BR FUSE_GETATTR . +.TP +.B FUSE_FLUSH +.in +4n +.EX +struct fuse_flush_in { + uint64_t fh; + uint32_t unused; + uint32_t padding; + uint64_t lock_owner; +}; +.EE +.in +.IP +The requested action is to flush any pending changes to the indicated +file handle. +No reply data is expected. +However, an empty reply message +still needs to be issued once the flush operation is complete. +.TP +.BR FUSE_RELEASE " and " FUSE_RELEASEDIR +.in +4n +.EX +struct fuse_release_in { + uint64_t fh; + uint32_t flags; + uint32_t release_flags; + uint64_t lock_owner; +}; +.EE +.in +.IP +These are the converse of +.B FUSE_OPEN +and +.B FUSE_OPENDIR +respectively. +The daemon may now free any resources associated with the +file handle +.I fh +as the kernel will no longer refer to it. +There is no reply data associated with this request, +but a reply still needs to be issued once the request has +been completely processed. +.TP +.B FUSE_STATFS +This operation implements +.BR statfs (2) +for this filesystem. +There is no input data associated with this request. +The expected reply data has the following structure: +.IP +.in +4n +.EX +struct fuse_kstatfs { + uint64_t blocks; + uint64_t bfree; + uint64_t bavail; + uint64_t files; + uint64_t ffree; + uint32_t bsize; + uint32_t namelen; + uint32_t frsize; + uint32_t padding; + uint32_t spare[6]; +}; +\& +struct fuse_statfs_out { + struct fuse_kstatfs st; +}; +.EE +.in +.IP +For the interpretation of these fields, see +.BR statfs (2). +.SH ERRORS +.TP +.B E2BIG +Returned from +.BR read (2) +operations when the kernel's request is too large for the provided buffer +and the request was +.BR FUSE_SETXATTR . +.TP +.B EINVAL +Returned from +.BR write (2) +if validation of the reply failed. +Not all mistakes in replies will be caught by this validation. +However, basic mistakes, such as short replies or an incorrect +.I unique +value, are detected. +.TP +.B EIO +Returned from +.BR read (2) +operations when the kernel's request is too large for the provided buffer. +.IP +.IR Note : +There are various ways in which incorrect use of these interfaces can cause +operations on the provided filesystem's files and directories to fail with +.BR EIO . +Among the possible incorrect uses are: +.RS +.IP \[bu] 3 +changing +.I mode & S_IFMT +for an inode that has previously been reported to the kernel; or +.IP \[bu] +giving replies to the kernel that are shorter than what the kernel expected. +.RE +.TP +.B ENODEV +Returned from +.BR read (2) +and +.BR write (2) +if the FUSE filesystem was unmounted. +.TP +.B EPERM +Returned from operations on a +.I /dev/fuse +file descriptor that has not been mounted. +.SH STANDARDS +Linux. +.SH NOTES +The following messages are not yet documented in this manual page: +.P +.\" FIXME: Document the following. +.in +4n +.EX +.B FUSE_BATCH_FORGET +.B FUSE_BMAP +.B FUSE_CREATE +.B FUSE_DESTROY +.B FUSE_FALLOCATE +.B FUSE_FORGET +.B FUSE_FSYNC +.B FUSE_FSYNCDIR +.B FUSE_GETLK +.B FUSE_GETXATTR +.B FUSE_IOCTL +.B FUSE_LINK +.B FUSE_LISTXATTR +.B FUSE_LSEEK +.B FUSE_MKDIR +.B FUSE_MKNOD +.B FUSE_NOTIFY_REPLY +.B FUSE_POLL +.B FUSE_READDIRPLUS +.B FUSE_READLINK +.B FUSE_REMOVEXATTR +.B FUSE_RENAME +.B FUSE_RENAME2 +.B FUSE_RMDIR +.B FUSE_SETATTR +.B FUSE_SETLK +.B FUSE_SETLKW +.B FUSE_SYMLINK +.B FUSE_UNLINK +.B FUSE_WRITE +.EE +.in +.SH SEE ALSO +.BR fusermount (1), +.BR mount.fuse (8) diff --git a/man/man4/hd.4 b/man/man4/hd.4 new file mode 100644 index 0000000..4d11bd9 --- /dev/null +++ b/man/man4/hd.4 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 16:56:20 1993 by Rik Faith +.\" Modified Mon Oct 21 21:38:51 1996 by Eric S. Raymond +.\" (and some more by aeb) +.\" +.TH hd 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +hd \- MFM/IDE hard disk devices +.SH DESCRIPTION +The +.B hd* +devices are block devices to access MFM/IDE hard disk drives +in raw mode. +The master drive on the primary IDE controller (major device +number 3) is +.BR hda ; +the slave drive is +.BR hdb . +The master drive of the second controller (major device number 22) +is +.B hdc +and the slave is +.BR hdd . +.P +General IDE block device names have the form +.BI hd X\c +, or +.BI hd XP\c +, where +.I X +is a letter denoting the physical drive, and +.I P +is a number denoting the partition on that physical drive. +The first form, +.BI hd X\c +, is used to address the whole drive. +Partition numbers are assigned in the order the partitions +are discovered, and only nonempty, nonextended partitions +get a number. +However, partition numbers 1\[en]4 are given to the +four partitions described in the MBR (the "primary" partitions), +regardless of whether they are unused or extended. +Thus, the first logical partition will be +.BI hd X 5\c +\&. +Both DOS-type partitioning and BSD-disklabel partitioning are supported. +You can have at most 63 partitions on an IDE disk. +.P +For example, +.I /dev/hda +refers to all of the first IDE drive in the system; and +.I /dev/hdb3 +refers to the third DOS "primary" partition on the second one. +.P +They are typically created by: +.P +.in +4n +.EX +mknod \-m 660 /dev/hda b 3 0 +mknod \-m 660 /dev/hda1 b 3 1 +mknod \-m 660 /dev/hda2 b 3 2 +\&... +mknod \-m 660 /dev/hda8 b 3 8 +mknod \-m 660 /dev/hdb b 3 64 +mknod \-m 660 /dev/hdb1 b 3 65 +mknod \-m 660 /dev/hdb2 b 3 66 +\&... +mknod \-m 660 /dev/hdb8 b 3 72 +chown root:disk /dev/hd* +.EE +.in +.SH FILES +.I /dev/hd* +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR sd (4), +.BR mount (8) diff --git a/man/man4/hpsa.4 b/man/man4/hpsa.4 new file mode 100644 index 0000000..e4fc5c1 --- /dev/null +++ b/man/man4/hpsa.4 @@ -0,0 +1,240 @@ +.\" Copyright (C) 2011, Hewlett-Packard Development Company, L.P. +.\" Written by Stephen M. Cameron +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.\" shorthand for double quote that works everywhere. +.ds q \N'34' +.TH hpsa 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +hpsa \- HP Smart Array SCSI driver +.SH SYNOPSIS +.nf +modprobe hpsa [ hpsa_allow_any=1 ] +.fi +.SH DESCRIPTION +.B hpsa +is a SCSI driver for HP Smart Array RAID controllers. +.SS Options +.IR "hpsa_allow_any=1" : +This option allows the driver to attempt to operate on +any HP Smart Array hardware RAID controller, +even if it is not explicitly known to the driver. +This allows newer hardware to work with older drivers. +Typically this is used to allow installation of +operating systems from media that predates the +RAID controller, though it may also be used to enable +.B hpsa +to drive older controllers that would normally be handled by the +.BR cciss (4) +driver. +These older boards have not been tested and are +not supported with +.BR hpsa , +and +.BR cciss (4) +should still be used for these. +.SS Supported hardware +The +.B hpsa +driver supports the following Smart Array boards: +.P +.nf + Smart Array P700M + Smart Array P212 + Smart Array P410 + Smart Array P410i + Smart Array P411 + Smart Array P812 + Smart Array P712m + Smart Array P711m + StorageWorks P1210m +.fi +.P +.\" commit 135ae6edeb51979d0998daf1357f149a7d6ebb08 +Since Linux 4.14, the following Smart Array boards are also supported: +.P +.nf + Smart Array 5300 + Smart Array 5312 + Smart Array 532 + Smart Array 5i + Smart Array 6400 + Smart Array 6400 EM + Smart Array 641 + Smart Array 642 + Smart Array 6i + Smart Array E200 + Smart Array E200i + Smart Array E200i + Smart Array E200i + Smart Array E200i + Smart Array E500 + Smart Array P400 + Smart Array P400i + Smart Array P600 + Smart Array P700m + Smart Array P800 +.fi +.SS Configuration details +To configure HP Smart Array controllers, +use the HP Array Configuration Utility (either +.BR hpacuxe (8) +or +.BR hpacucli (8)) +or the Offline ROM-based Configuration Utility (ORCA) +run from the Smart Array's option ROM at boot time. +.SH FILES +.SS Device nodes +Logical drives are accessed via the SCSI disk driver +.RB ( sd (4)), +tape drives via the SCSI tape driver +.RB ( st (4)), +and +the RAID controller via the SCSI generic driver +.RB ( sg (4)), +with device nodes named +.IR /dev/sd* , +.IR /dev/st* , +and +.IR /dev/sg* , +respectively. +.SS HPSA-specific host attribute files in /sys +.TP +.I /sys/class/scsi_host/host*/rescan +This is a write-only attribute. +Writing to this attribute will cause the driver to scan for +new, changed, or removed devices (e.g., hot-plugged tape drives, +or newly configured or deleted logical drives, etc.) +and notify the SCSI midlayer of any changes detected. +Normally a rescan is triggered automatically +by HP's Array Configuration Utility (either the GUI or the +command-line variety); +thus, for logical drive changes, the user should not +normally have to use this attribute. +This attribute may be useful when hot plugging devices like tape drives, +or entire storage boxes containing preconfigured logical drives. +.TP +.I /sys/class/scsi_host/host*/firmware_revision +This attribute contains the firmware version of the Smart Array. +.IP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_host/host4\fP +# \fBcat firmware_revision\fP +7.14 +.EE +.in +.\" +.SS HPSA-specific disk attribute files in /sys +.TP +.I /sys/class/scsi_disk/c:b:t:l/device/unique_id +This attribute contains a 32 hex-digit unique ID for each logical drive. +.IP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_disk/4:0:0:0/device\fP +# \fBcat unique_id\fP +600508B1001044395355323037570F77 +.EE +.in +.TP +.I /sys/class/scsi_disk/c:b:t:l/device/raid_level +This attribute contains the RAID level of each logical drive. +.IP +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_disk/4:0:0:0/device\fP +# \fBcat raid_level\fP +RAID 0 +.EE +.in +.TP +.I /sys/class/scsi_disk/c:b:t:l/device/lunid +This attribute contains the 16 hex-digit (8 byte) LUN ID +by which a logical drive or physical device can be addressed. +.IR c : b : t : l +are the controller, bus, target, and lun of the device. +.P +For example: +.IP +.in +4n +.EX +# \fBcd /sys/class/scsi_disk/4:0:0:0/device\fP +# \fBcat lunid\fP +0x0000004000000000 +.EE +.in +.\" +.SS Supported ioctl() operations +For compatibility with applications written for the +.BR cciss (4) +driver, many, but +not all of the ioctls supported by the +.BR cciss (4) +driver are also supported by the +.B hpsa +driver. +The data structures used by these ioctls are described in +the Linux kernel source file +.IR include/linux/cciss_ioctl.h . +.TP +.B CCISS_DEREGDISK +.TQ +.B CCISS_REGNEWDISK +.TQ +.B CCISS_REGNEWD +These three ioctls all do exactly the same thing, +which is to cause the driver to rescan for new devices. +This does exactly the same thing as writing to the +hpsa-specific host "rescan" attribute. +.TP +.B CCISS_GETPCIINFO +Returns PCI domain, bus, device, and function and "board ID" (PCI subsystem ID). +.TP +.B CCISS_GETDRIVVER +Returns driver version in three bytes encoded as: +.IP +.in +4n +.EX +(major_version << 16) | (minor_version << 8) | + (subminor_version) +.EE +.in +.TP +.B CCISS_PASSTHRU +.TQ +.B CCISS_BIG_PASSTHRU +Allows "BMIC" and "CISS" commands to be passed through to the Smart Array. +These are used extensively by the HP Array Configuration Utility, +SNMP storage agents, and so on. +See +.I cciss_vol_status +at +.UR http://cciss.sf.net +.UE +for some examples. +.SH SEE ALSO +.BR cciss (4), +.BR sd (4), +.BR st (4), +.BR cciss_vol_status (8), +.BR hpacucli (8), +.BR hpacuxe (8) +.P +.UR http://cciss.sf.net +.UE , +and +.I Documentation/scsi/hpsa.txt +and +.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss +in the Linux kernel source tree +.\" .SH AUTHORS +.\" Don Brace, Steve Cameron, Tom Lawler, Mike Miller, Scott Teel +.\" and probably some other people. diff --git a/man/man4/initrd.4 b/man/man4/initrd.4 new file mode 100644 index 0000000..099aeb3 --- /dev/null +++ b/man/man4/initrd.4 @@ -0,0 +1,479 @@ +.\" This man-page is Copyright (C) 1997 John S. Kallal +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" If the you wish to distribute versions of this work under other +.\" conditions than the above, please contact the author(s) at the following +.\" for permission: +.\" +.\" John S. Kallal - +.\" email: +.\" mail: 518 Kerfoot Farm RD, Wilmington, DE 19803-2444, USA +.\" phone: (302)654-5478 +.\" +.\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $ +.TH initrd 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +initrd \- boot loader initialized RAM disk +.SH CONFIGURATION +.I /dev/initrd +is a read-only block device assigned +major number 1 and minor number 250. +Typically +.I /dev/initrd +is owned by +root:disk +with mode 0400 (read access by root only). +If the Linux system does not have +.I /dev/initrd +already created, it can be created with the following commands: +.P +.in +4n +.EX +mknod \-m 400 /dev/initrd b 1 250 +chown root:disk /dev/initrd +.EE +.in +.P +Also, support for both "RAM disk" and "Initial RAM disk" +(e.g., +.B CONFIG_BLK_DEV_RAM=y +and +.BR CONFIG_BLK_DEV_INITRD=y ) +must be compiled directly into the Linux kernel to use +.IR /dev/initrd . +When using +.IR /dev/initrd , +the RAM disk driver cannot be loaded as a module. +.\" +.\" +.\" +.SH DESCRIPTION +The special file +.I /dev/initrd +is a read-only block device. +This device is a RAM disk that is initialized (e.g., loaded) +by the boot loader before the kernel is started. +The kernel then can use +.IR /dev/initrd "'s" +contents for a two-phase system boot-up. +.P +In the first boot-up phase, the kernel starts up +and mounts an initial root filesystem from the contents of +.I /dev/initrd +(e.g., RAM disk initialized by the boot loader). +In the second phase, additional drivers or other modules +are loaded from the initial root device's contents. +After loading the additional modules, a new root filesystem +(i.e., the normal root filesystem) is mounted from a +different device. +.\" +.\" +.\" +.SS Boot-up operation +When booting up with +.BR initrd , +the system boots as follows: +.IP (1) 5 +The boot loader loads the kernel program and +.IR /dev/initrd 's +contents into memory. +.IP (2) +On kernel startup, +the kernel uncompresses and copies the contents of the device +.I /dev/initrd +onto device +.I /dev/ram0 +and then frees the memory used by +.IR /dev/initrd . +.IP (3) +The kernel then read-write mounts the device +.I /dev/ram0 +as the initial root filesystem. +.IP (4) +If the indicated normal root filesystem is also the initial +root filesystem (e.g., +.IR /dev/ram0 ) +then the kernel skips to the last step for the usual boot sequence. +.IP (5) +If the executable file +.I /linuxrc +is present in the initial root filesystem, +.I /linuxrc +is executed with UID 0. +(The file +.I /linuxrc +must have executable permission. +The file +.I /linuxrc +can be any valid executable, including a shell script.) +.IP (6) +If +.I /linuxrc +is not executed or when +.I /linuxrc +terminates, the normal root filesystem is mounted. +(If +.I /linuxrc +exits with any filesystems mounted on the initial root +filesystem, then the behavior of the kernel is +.BR UNSPECIFIED . +See the NOTES section for the current kernel behavior.) +.IP (7) +If the normal root filesystem has a directory +.IR /initrd , +the device +.I /dev/ram0 +is moved from +.I / +to +.IR /initrd . +Otherwise, if the directory +.I /initrd +does not exist, the device +.I /dev/ram0 +is unmounted. +(When moved from +.I / +to +.IR /initrd , +.I /dev/ram0 +is not unmounted and therefore processes can remain running from +.IR /dev/ram0 . +If directory +.I /initrd +does not exist on the normal root filesystem +and any processes remain running from +.I /dev/ram0 +when +.I /linuxrc +exits, the behavior of the kernel is +.BR UNSPECIFIED . +See the NOTES section for the current kernel behavior.) +.IP (8) +The usual boot sequence (e.g., invocation of +.IR /sbin/init ) +is performed on the normal root filesystem. +.\" +.\" +.\" +.SS Options +The following boot loader options, when used with +.BR initrd , +affect the kernel's boot-up operation: +.TP +.BI initrd= "filename" +Specifies the file to load as the contents of +.IR /dev/initrd . +For +.B LOADLIN +this is a command-line option. +For +.B LILO +you have to use this command in the +.B LILO +configuration file +.IR /etc/lilo.config . +The filename specified with this +option will typically be a gzipped filesystem image. +.TP +.B noinitrd +This boot option disables the two-phase boot-up operation. +The kernel performs the usual boot sequence as if +.I /dev/initrd +was not initialized. +With this option, any contents of +.I /dev/initrd +loaded into memory by the boot loader contents are preserved. +This option permits the contents of +.I /dev/initrd +to be any data and need not be limited to a filesystem image. +However, device +.I /dev/initrd +is read-only and can be read only one time after system startup. +.TP +.BI root= "device-name" +Specifies the device to be used as the normal root filesystem. +For +.B LOADLIN +this is a command-line option. +For +.B LILO +this is a boot time option or +can be used as an option line in the +.B LILO +configuration file +.IR /etc/lilo.config . +The device specified by this option must be a mountable +device having a suitable root filesystem. +.\" +.\" +.\" +.SS Changing the normal root filesystem +By default, +the kernel's settings +(e.g., set in the kernel file with +.BR rdev (8) +or compiled into the kernel file), +or the boot loader option setting +is used for the normal root filesystems. +For an NFS-mounted normal root filesystem, one has to use the +.B nfs_root_name +and +.B nfs_root_addrs +boot options to give the NFS settings. +For more information on NFS-mounted root see the kernel documentation file +.I Documentation/filesystems/nfs/nfsroot.txt +.\" commit dc7a08166f3a5f23e79e839a8a88849bd3397c32 +(or +.I Documentation/filesystems/nfsroot.txt +before Linux 2.6.33). +For more information on setting the root filesystem see also the +.B LILO +and +.B LOADLIN +documentation. +.P +It is also possible for the +.I /linuxrc +executable to change the normal root device. +For +.I /linuxrc +to change the normal root device, +.I /proc +must be mounted. +After mounting +.IR /proc , +.I /linuxrc +changes the normal root device by writing into the proc files +.IR /proc/sys/kernel/real\-root\-dev , +.IR /proc/sys/kernel/nfs\-root\-name , +and +.IR /proc/sys/kernel/nfs\-root\-addrs . +For a physical root device, the root device is changed by having +.I /linuxrc +write the new root filesystem device number into +.IR /proc/sys/kernel/real\-root\-dev . +For an NFS root filesystem, the root device is changed by having +.I /linuxrc +write the NFS setting into files +.I /proc/sys/kernel/nfs\-root\-name +and +.I /proc/sys/kernel/nfs\-root\-addrs +and then writing 0xff (e.g., the pseudo-NFS-device number) into file +.IR /proc/sys/kernel/real\-root\-dev . +For example, the following shell command line would change +the normal root device to +.IR /dev/hdb1 : +.P +.in +4n +.EX +echo 0x365 >/proc/sys/kernel/real\-root\-dev +.EE +.in +.P +For an NFS example, the following shell command lines would change the +normal root device to the NFS directory +.I /var/nfsroot +on a local networked NFS server with IP number 193.8.232.7 for a system with +IP number 193.8.232.2 and named "idefix": +.P +.in +4n +.EX +echo /var/nfsroot >/proc/sys/kernel/nfs\-root\-name +echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \e + >/proc/sys/kernel/nfs\-root\-addrs +echo 255 >/proc/sys/kernel/real\-root\-dev +.EE +.in +.P +.BR Note : +The use of +.I /proc/sys/kernel/real\-root\-dev +to change the root filesystem is obsolete. +See the Linux kernel source file +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10) +as well as +.BR pivot_root (2) +and +.BR pivot_root (8) +for information on the modern method of changing the root filesystem. +.\" FIXME . Should this manual page describe the pivot_root mechanism? +.\" +.\" +.\" +.SS Usage +The main motivation for implementing +.B initrd +was to allow for modular kernel configuration at system installation. +.P +A possible system installation scenario is as follows: +.IP (1) 5 +The loader program boots from floppy or other media with a minimal kernel +(e.g., support for +.IR /dev/ram , +.IR /dev/initrd , +and the ext2 filesystem) and loads +.I /dev/initrd +with a gzipped version of the initial filesystem. +.IP (2) +The executable +.I /linuxrc +determines what is needed to (1) mount the normal root filesystem +(i.e., device type, device drivers, filesystem) and (2) the +distribution media (e.g., CD-ROM, network, tape, ...). +This can be done by asking the user, by auto-probing, +or by using a hybrid approach. +.IP (3) +The executable +.I /linuxrc +loads the necessary modules from the initial root filesystem. +.IP (4) +The executable +.I /linuxrc +creates and populates the root filesystem. +(At this stage the normal root filesystem does not have to be a +completed system yet.) +.IP (5) +The executable +.I /linuxrc +sets +.IR /proc/sys/kernel/real\-root\-dev , +unmounts +.IR /proc , +the normal root filesystem and any other filesystems +it has mounted, and then terminates. +.IP (6) +The kernel then mounts the normal root filesystem. +.IP (7) +Now that the filesystem is accessible and intact, +the boot loader can be installed. +.IP (8) +The boot loader is configured to load into +.I /dev/initrd +a filesystem with the set of modules that was used to bring up the system. +(e.g., device +.I /dev/ram0 +can be modified, then unmounted, and finally, the image is written from +.I /dev/ram0 +to a file.) +.IP (9) +The system is now bootable and additional installation tasks can be +performed. +.P +The key role of +.I /dev/initrd +in the above is to reuse the configuration data during normal system operation +without requiring initial kernel selection, a large generic kernel or, +recompiling the kernel. +.P +A second scenario is for installations where Linux runs on systems with +different hardware configurations in a single administrative network. +In such cases, it may be desirable to use only a small set of kernels +(ideally only one) and to keep the system-specific part of configuration +information as small as possible. +In this case, create a common file +with all needed modules. +Then, only the +.I /linuxrc +file or a file executed by +.I /linuxrc +would be different. +.P +A third scenario is more convenient recovery disks. +Because information like the location of the root filesystem +partition is not needed at boot time, the system loaded from +.I /dev/initrd +can use a dialog and/or auto-detection followed by a +possible sanity check. +.P +Last but not least, Linux distributions on CD-ROM may use +.B initrd +for easy installation from the CD-ROM. +The distribution can use +.B LOADLIN +to directly load +.I /dev/initrd +from CD-ROM without the need of any floppies. +The distribution could also use a +.B LILO +boot floppy and then bootstrap a bigger RAM disk via +.I /dev/initrd +from the CD-ROM. +.\" +.\" +.\" +.SH FILES +.I /dev/initrd +.br +.I /dev/ram0 +.br +.I /linuxrc +.br +.I /initrd +.\" +.\" +.\" +.SH NOTES +.IP \[bu] 3 +With the current kernel, any filesystems that remain mounted when +.I /dev/ram0 +is moved from +.I / +to +.I /initrd +continue to be accessible. +However, the +.I /proc/mounts +entries are not updated. +.IP \[bu] +With the current kernel, if directory +.I /initrd +does not exist, then +.I /dev/ram0 +will +.B not +be fully unmounted if +.I /dev/ram0 +is used by any process or has any filesystem mounted on it. +If +.I /dev/ram0 +is +.B not +fully unmounted, then +.I /dev/ram0 +will remain in memory. +.IP \[bu] +Users of +.I /dev/initrd +should not depend on the behavior given in the above notes. +The behavior may change in future versions of the Linux kernel. +.\" +.\" +.\" +.\" .SH AUTHORS +.\" The kernel code for device +.\" .BR initrd +.\" was written by Werner Almesberger and +.\" Hans Lermen . +.\" The code for +.\" .BR initrd +.\" was added to the baseline Linux kernel in development version 1.3.73. +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR ram (4), +.BR freeramdisk (8), +.BR rdev (8) +.P +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10) +in the Linux kernel source tree, the LILO documentation, +the LOADLIN documentation, the SYSLINUX documentation diff --git a/man/man4/intro.4 b/man/man4/intro.4 new file mode 100644 index 0000000..5c65b06 --- /dev/null +++ b/man/man4/intro.4 @@ -0,0 +1,22 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 16:57:14 1993 by Rik Faith (faith@cs.unc.edu) +.TH intro 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intro \- introduction to special files +.SH DESCRIPTION +Section 4 of the manual describes special files (devices). +.SH FILES +/dev/* \[em] device files +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR mknod (1), +.BR mknod (2), +.BR standards (7) diff --git a/man/man4/kmem.4 b/man/man4/kmem.4 new file mode 100644 index 0000000..d4c1762 --- /dev/null +++ b/man/man4/kmem.4 @@ -0,0 +1 @@ +.so man4/mem.4 diff --git a/man/man4/lirc.4 b/man/man4/lirc.4 new file mode 100644 index 0000000..3660bcd --- /dev/null +++ b/man/man4/lirc.4 @@ -0,0 +1,423 @@ +.\" Copyright (c) 2015-2016, Alec Leamas +.\" Copyright (c) 2018, Sean Young +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH lirc 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lirc \- lirc devices +.SH DESCRIPTION +The +.I /dev/lirc* +character devices provide a low-level +bidirectional interface to infra-red (IR) remotes. +Most of these devices can receive, and some can send. +When receiving or sending data, the driver works in two different modes +depending on the underlying hardware. +.P +Some hardware (typically TV-cards) decodes the IR signal internally +and provides decoded button presses as scancode values. +Drivers for this kind of hardware work in +.B LIRC_MODE_SCANCODE +mode. +Such hardware usually does not support sending IR signals. +Furthermore, such hardware can only decode a limited set of IR protocols, +usually only the protocol of the specific remote which is +bundled with, for example, a TV-card. +.P +Other hardware provides a stream of pulse/space durations. +Such drivers work in +.B LIRC_MODE_MODE2 +mode. +Such hardware can be used with (almost) any kind of remote. +This type of hardware can also be used in +.B LIRC_MODE_SCANCODE +mode, in which case the kernel IR decoders will decode the IR. +These decoders can be written in extended BPF (see +.BR bpf (2)) +and attached to the +.B lirc +device. +Sometimes, this kind of hardware also supports +sending IR data. +.P +The \fBLIRC_GET_FEATURES\fR ioctl (see below) allows probing for whether +receiving and sending is supported, and in which modes, amongst other +features. +.\" +.SS Reading input with the LIRC_MODE_MODE2 mode +In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by +.BR read (2) +provides 32-bit values representing a space or a pulse duration. +The time of the duration (microseconds) is encoded in the lower 24 bits. +Pulse (also known as flash) +indicates a duration of infrared light being detected, +and space (also known as gap) indicates a duration with no infrared. +If the duration of space exceeds the inactivity timeout, +a special timeout package is delivered, +which marks the end of a message. +The upper 8 bits indicate the type of package: +.TP 4 +.B LIRC_MODE2_SPACE +Value reflects a space duration (microseconds). +.TP 4 +.B LIRC_MODE2_PULSE +Value reflects a pulse duration (microseconds). +.TP 4 +.B LIRC_MODE2_FREQUENCY +Value reflects a frequency (Hz); see the +.B LIRC_SET_MEASURE_CARRIER_MODE +ioctl. +.TP 4 +.B LIRC_MODE2_TIMEOUT +Value reflects a space duration (microseconds). +The package reflects a timeout; see the +.B LIRC_SET_REC_TIMEOUT_REPORTS +ioctl. +.\" +.TP 4 +.B LIRC_MODE2_OVERFLOW +The IR receiver encountered an overflow, +and as a result data is missing +(since Linux 5.18). +.SS Reading input with the LIRC_MODE_SCANCODE mode +In the \fBLIRC_MODE_SCANCODE\fR +mode, the data returned by +.BR read (2) +reflects decoded button presses, in the struct \fIlirc_scancode\fR. +The scancode is stored in the \fIscancode\fR field, and the IR protocol +is stored in \fIrc_proto\fR. +This field has one the values of the \fIenum rc_proto\fR. +.\" +.SS Writing output with the LIRC_MODE_PULSE mode +The data written to the character device using +.BR write (2) +is a pulse/space sequence of integer values. +Pulses and spaces are only marked implicitly by their position. +The data must start and end with a pulse, thus it must always include +an odd number of samples. +The +.BR write (2) +function blocks until the data has been transmitted by the +hardware. +If more data is provided than the hardware can send, the +.BR write (2) +call fails with the error +.BR EINVAL . +.SS Writing output with the LIRC_MODE_SCANCODE mode +The data written to the character devices must be a single struct +\fIlirc_scancode\fR. +The \fIscancode\fR and \fIrc_proto\fR fields must +filled in, all other fields must be 0. +The kernel IR encoders will +convert the scancode to pulses and spaces. +The protocol or scancode is invalid, or the +.B lirc +device cannot transmit. +.SH IOCTL COMMANDS +.nf +#include /* But see BUGS */ +\& +int ioctl(int fd, int cmd, int *val); +.fi +.P +The following +.BR ioctl (2) +operations are provided by the +.B lirc +character device to probe or change specific +.B lirc +hardware settings. +.SS Always Supported Commands +\fI/dev/lirc*\fR devices always support the following commands: +.TP 4 +.BR LIRC_GET_FEATURES " (\fIvoid\fP)" +Returns a bit mask of combined features bits; see FEATURES. +.P +If a device returns an error code for +.BR LIRC_GET_FEATURES , +it is safe to assume it is not a +.B lirc +device. +.\" +.SS Optional Commands +Some +.B lirc +devices support the commands listed below. +Unless otherwise stated, these fail with the error \fBENOTTY\fR if the +operation isn't supported, or with the error \fBEINVAL\fR if the operation +failed, or invalid arguments were provided. +If a driver does not announce support of certain features, invoking +the corresponding ioctls will fail with the error +.BR ENOTTY . +.TP +.BR LIRC_GET_REC_MODE " (\fIvoid\fP)" +If the +.B lirc +device has no receiver, this operation fails with the error +.BR ENOTTY . +Otherwise, it returns the receive mode, which will be one of: +.RS +.TP +.B LIRC_MODE_MODE2 +The driver returns a sequence of pulse/space durations. +.TP +.B LIRC_MODE_SCANCODE +The driver returns struct +.I lirc_scancode +values, each of which represents +a decoded button press. +.RE +.TP +.BR LIRC_SET_REC_MODE " (\fIint\fP)" +Set the receive mode. +.I val +is either +.B LIRC_MODE_SCANCODE +or +.BR LIRC_MODE_MODE2 . +If the +.B lirc +device has no receiver, this operation fails with the error +.B ENOTTY. +.TP +.BR LIRC_GET_SEND_MODE " (\fIvoid\fP)" +Return the send mode. +.B LIRC_MODE_PULSE +or +.B LIRC_MODE_SCANCODE +is supported. +If the +.B lirc +device cannot send, this operation fails with the error +.B ENOTTY. +.TP +.BR LIRC_SET_SEND_MODE " (\fIint\fP)" +Set the send mode. +.I val +is either +.B LIRC_MODE_SCANCODE +or +.BR LIRC_MODE_PULSE . +If the +.B lirc +device cannot send, this operation fails with the error +.BR ENOTTY . +.TP +.BR LIRC_SET_SEND_CARRIER " (\fIint\fP)" +Set the modulation frequency. +The argument is the frequency (Hz). +.TP +.BR LIRC_SET_SEND_DUTY_CYCLE " (\fIint\fP)" +Set the carrier duty cycle. +.I val +is a number in the range [0,100] which +describes the pulse width as a percentage of the total cycle. +Currently, no special meaning is defined for 0 or 100, but the values +are reserved for future use. +.TP +.BI LIRC_GET_MIN_TIMEOUT( void ) +.TQ +.BI LIRC_GET_MAX_TIMEOUT( void ) +Some devices have internal timers that can be used to detect when +there has been no IR activity for a long time. +This can help +.BR lircd (8) +in detecting that an IR signal is finished and can speed up the +decoding process. +These operations +return integer values with the minimum/maximum timeout that can be +set (microseconds). +Some devices have a fixed timeout. +For such drivers, +.B LIRC_GET_MIN_TIMEOUT +and +.B LIRC_GET_MAX_TIMEOUT +will fail with the error +.BR ENOTTY . +.TP +.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" +Set the integer value for IR inactivity timeout (microseconds). +To be accepted, the value must be within the limits defined by +.B LIRC_GET_MIN_TIMEOUT +and +.BR LIRC_GET_MAX_TIMEOUT . +A value of 0 (if supported by the hardware) disables all hardware +timeouts and data should be reported as soon as possible. +If the exact value cannot be set, then the next possible value +.I greater +than the given value should be set. +.TP +.BR LIRC_GET_REC_TIMEOUT " (\fIvoid\fP)" +Return the current inactivity timeout (microseconds). +Available since Linux 4.18. +.TP +.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)" +Enable +.RI ( val +is 1) or disable +.RI ( val +is 0) timeout packages in +.BR LIRC_MODE_MODE2 . +The behavior of this operation has varied across kernel versions: +.RS +.IP \[bu] 3 +Since Linux 5.17: +timeout packages are always enabled and this ioctl is a no-op. +.IP \[bu] +Since Linux 4.16: +timeout packages are enabled by default. +Each time the +.B lirc +device is opened, the +.B LIRC_SET_REC_TIMEOUT +operation can be used to disable (and, if desired, to later re-enable) +the timeout on the file descriptor. +.IP \[bu] +In Linux 4.15 and earlier: +timeout packages are disabled by default, and enabling them (via +.BR LIRC_SET_REC_TIMEOUT ) +on any file descriptor associated with the +.B lirc +device has the effect of enabling timeouts for all file descriptors +referring to that device (until timeouts are disabled again). +.RE +.TP +.BR LIRC_SET_REC_CARRIER " (\fIint\fP)" +Set the upper bound of the receive carrier frequency (Hz). +See +.BR LIRC_SET_REC_CARRIER_RANGE . +.TP +.BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)" +Sets the lower bound of the receive carrier frequency (Hz). +For this to take affect, first set the lower bound using the +.B LIRC_SET_REC_CARRIER_RANGE +ioctl, and then the upper bound using the +.B LIRC_SET_REC_CARRIER +ioctl. +.TP +.BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)" +Enable +.RI ( val +is 1) or disable +.RI ( val +is 0) the measure mode. +If enabled, from the next key press on, the driver will send +.B LIRC_MODE2_FREQUENCY +packets. +By default, this should be turned off. +.TP +.BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)" +Return the driver resolution (microseconds). +.TP +.BR LIRC_SET_TRANSMITTER_MASK " (\fIint\fP)" +Enable the set of transmitters specified in +.IR val , +which contains a bit mask where each enabled transmitter is a 1. +The first transmitter is encoded by the least significant bit, and so on. +When an invalid bit mask is given, for example a bit is set even +though the device does not have so many transmitters, +this operation returns the +number of available transmitters and does nothing otherwise. +.TP +.BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)" +Some devices are equipped with a special wide band receiver which is +intended to be used to learn the output of an existing remote. +This ioctl can be used to enable +.RI ( val +equals 1) or disable +.RI ( val +equals 0) this functionality. +This might be useful for devices that otherwise have narrow band +receivers that prevent them to be used with certain remotes. +Wide band receivers may also be more precise. +On the other hand, their disadvantage usually is reduced range of +reception. +.IP +Note: wide band receiver may be implicitly enabled if you enable +carrier reports. +In that case, it will be disabled as soon as you disable carrier reports. +Trying to disable a wide band receiver while carrier reports are active +will do nothing. +.\" +.SH FEATURES +the +.B LIRC_GET_FEATURES +ioctl returns a bit mask describing features of the driver. +The following bits may be returned in the mask: +.TP +.B LIRC_CAN_REC_MODE2 +The driver is capable of receiving using +.BR LIRC_MODE_MODE2 . +.TP +.B LIRC_CAN_REC_SCANCODE +The driver is capable of receiving using +.BR LIRC_MODE_SCANCODE . +.TP +.B LIRC_CAN_SET_SEND_CARRIER +The driver supports changing the modulation frequency using +.BR LIRC_SET_SEND_CARRIER . +.TP +.B LIRC_CAN_SET_SEND_DUTY_CYCLE +The driver supports changing the duty cycle using +.BR LIRC_SET_SEND_DUTY_CYCLE . +.TP +.B LIRC_CAN_SET_TRANSMITTER_MASK +The driver supports changing the active transmitter(s) using +.BR LIRC_SET_TRANSMITTER_MASK . +.TP +.B LIRC_CAN_SET_REC_CARRIER +The driver supports setting the receive carrier frequency using +.BR LIRC_SET_REC_CARRIER . +Any +.B lirc +device since the drivers were merged in Linux 2.6.36 +must have +.B LIRC_CAN_SET_REC_CARRIER_RANGE +set if +.B LIRC_CAN_SET_REC_CARRIER +feature is set. +.TP +.B LIRC_CAN_SET_REC_CARRIER_RANGE +The driver supports +.BR LIRC_SET_REC_CARRIER_RANGE . +The lower bound of the carrier must first be set using the +.B LIRC_SET_REC_CARRIER_RANGE +ioctl, before using the +.B LIRC_SET_REC_CARRIER +ioctl to set the upper bound. +.TP +.B LIRC_CAN_GET_REC_RESOLUTION +The driver supports +.BR LIRC_GET_REC_RESOLUTION . +.TP +.B LIRC_CAN_SET_REC_TIMEOUT +The driver supports +.BR LIRC_SET_REC_TIMEOUT . +.TP +.B LIRC_CAN_MEASURE_CARRIER +The driver supports measuring of the modulation frequency using +.BR LIRC_SET_MEASURE_CARRIER_MODE . +.TP +.B LIRC_CAN_USE_WIDEBAND_RECEIVER +The driver supports learning mode using +.BR LIRC_SET_WIDEBAND_RECEIVER . +.TP +.B LIRC_CAN_SEND_PULSE +The driver supports sending using +.B LIRC_MODE_PULSE +or +.B LIRC_MODE_SCANCODE +.\" +.SH BUGS +Using these devices requires the kernel source header file +.IR lirc.h . +This file is not available before Linux 4.6. +Users of older kernels could use the file bundled in +.UR http://www.lirc.org +.UE . +.\" +.SH SEE ALSO +\fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2) +.P +.UR https://www.kernel.org/\:doc/\:html/\:latest/\:userspace\-api/\:media/\:rc/\:lirc\-dev.html +.UE diff --git a/man/man4/loop-control.4 b/man/man4/loop-control.4 new file mode 100644 index 0000000..251e652 --- /dev/null +++ b/man/man4/loop-control.4 @@ -0,0 +1 @@ +.so man4/loop.4 diff --git a/man/man4/loop.4 b/man/man4/loop.4 new file mode 100644 index 0000000..19c1127 --- /dev/null +++ b/man/man4/loop.4 @@ -0,0 +1,361 @@ +.\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) +.\" and Copyright 2015 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH loop 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +loop, loop-control \- loop devices +.SH SYNOPSIS +.nf +#include +.fi +.SH DESCRIPTION +The loop device is a block device that maps its data blocks not to a +physical device such as a hard disk or optical disk drive, +but to the blocks of +a regular file in a filesystem or to another block device. +This can be useful for example to provide a block device for a filesystem +image stored in a file, so that it can be mounted with the +.BR mount (8) +command. +You could do +.P +.in +4n +.EX +$ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP +$ \fBsudo losetup /dev/loop4 file.img\fP +$ \fBsudo mkfs \-t ext4 /dev/loop4\fP +$ \fBsudo mkdir /myloopdev\fP +$ \fBsudo mount /dev/loop4 /myloopdev\fP +.EE +.in +.P +See +.BR losetup (8) +for another example. +.P +A transfer function can be specified for each loop device for +encryption and decryption purposes. +.P +The following +.BR ioctl (2) +operations are provided by the loop block device: +.TP +.B LOOP_SET_FD +Associate the loop device with the open file whose file descriptor is +passed as the (third) +.BR ioctl (2) +argument. +.TP +.B LOOP_CLR_FD +Disassociate the loop device from any file descriptor. +.TP +.B LOOP_SET_STATUS +Set the status of the loop device using the (third) +.BR ioctl (2) +argument. +This argument is a pointer to a +.I loop_info +structure, defined in +.I +as: +.IP +.in +4n +.EX +struct loop_info { + int lo_number; /* ioctl r/o */ + dev_t lo_device; /* ioctl r/o */ + unsigned long lo_inode; /* ioctl r/o */ + dev_t lo_rdevice; /* ioctl r/o */ + int lo_offset; + int lo_encrypt_type; + int lo_encrypt_key_size; /* ioctl w/o */ + int lo_flags; /* ioctl r/w (r/o before + Linux 2.6.25) */ + char lo_name[LO_NAME_SIZE]; + unsigned char lo_encrypt_key[LO_KEY_SIZE]; + /* ioctl w/o */ + unsigned long lo_init[2]; + char reserved[4]; +}; +.EE +.in +.IP +The encryption type +.RI ( lo_encrypt_type ) +should be one of +.BR LO_CRYPT_NONE , +.BR LO_CRYPT_XOR , +.BR LO_CRYPT_DES , +.BR LO_CRYPT_FISH2 , +.BR LO_CRYPT_BLOW , +.BR LO_CRYPT_CAST128 , +.BR LO_CRYPT_IDEA , +.BR LO_CRYPT_DUMMY , +.BR LO_CRYPT_SKIPJACK , +or (since Linux 2.6.0) +.BR LO_CRYPT_CRYPTOAPI . +.IP +The +.I lo_flags +field is a bit mask that can include zero or more of the following: +.RS +.TP +.B LO_FLAGS_READ_ONLY +The loopback device is read-only. +.TP +.BR LO_FLAGS_AUTOCLEAR " (since Linux 2.6.25)" +.\" commit 96c5865559cee0f9cbc5173f3c949f6ce3525581 +The loopback device will autodestruct on last close. +.TP +.BR LO_FLAGS_PARTSCAN " (since Linux 3.2)" +.\" commit e03c8dd14915fabc101aa495828d58598dc5af98 +Allow automatic partition scanning. +.TP +.BR LO_FLAGS_DIRECT_IO " (since Linux 4.10)" +.\" commit 2e5ab5f379f96a6207c45be40c357ebb1beb8ef3 +Use direct I/O mode to access the backing file. +.RE +.IP +The only +.I lo_flags +that can be modified by +.B LOOP_SET_STATUS +are +.B LO_FLAGS_AUTOCLEAR +and +.BR LO_FLAGS_PARTSCAN . +.TP +.B LOOP_GET_STATUS +Get the status of the loop device. +The (third) +.BR ioctl (2) +argument must be a pointer to a +.IR "struct loop_info" . +.TP +.BR LOOP_CHANGE_FD " (since Linux 2.6.5)" +Switch the backing store of the loop device to the new file identified +file descriptor specified in the (third) +.BR ioctl (2) +argument, which is an integer. +This operation is possible only if the loop device is read-only and +the new backing store is the same size and type as the old backing store. +.TP +.BR LOOP_SET_CAPACITY " (since Linux 2.6.30)" +.\" commit 53d6660836f233df66490707365ab177e5fb2bb4 +Resize a live loop device. +One can change the size of the underlying backing store and then use this +operation so that the loop driver learns about the new size. +This operation takes no argument. +.TP +.BR LOOP_SET_DIRECT_IO " (since Linux 4.10)" +.\" commit ab1cb278bc7027663adbfb0b81404f8398437e11 +Set DIRECT I/O mode on the loop device, so that +it can be used to open backing file. +The (third) +.BR ioctl (2) +argument is an unsigned long value. +A nonzero represents direct I/O mode. +.TP +.BR LOOP_SET_BLOCK_SIZE " (since Linux 4.14)" +.\" commit 89e4fdecb51cf5535867026274bc97de9480ade5 +Set the block size of the loop device. +The (third) +.BR ioctl (2) +argument is an unsigned long value. +This value must be a power of two in the range +[512,pagesize]; +otherwise, an +.B EINVAL +error results. +.TP +.BR LOOP_CONFIGURE " (since Linux 5.8)" +.\" commit 3448914e8cc550ba792d4ccc74471d1ca4293aae +Setup and configure all loop device parameters in a single step using +the (third) +.BR ioctl (2) +argument. +This argument is a pointer to a +.I loop_config +structure, defined in +.I +as: +.IP +.in +4n +.EX +struct loop_config { + __u32 fd; + __u32 block_size; + struct loop_info64 info; + __u64 __reserved[8]; +}; +.EE +.in +.IP +In addition to doing what +.B LOOP_SET_STATUS +can do, +.B LOOP_CONFIGURE +can also be used to do the following: +.RS +.IP \[bu] 3 +set the correct block size immediately by setting +.IR loop_config.block_size ; +.IP \[bu] +explicitly request direct I/O mode by setting +.B LO_FLAGS_DIRECT_IO +in +.IR loop_config.info.lo_flags ; +and +.IP \[bu] +explicitly request read-only mode by setting +.B LO_FLAGS_READ_ONLY +in +.IR loop_config.info.lo_flags . +.RE +.P +Since Linux 2.6, there are two new +.BR ioctl (2) +operations: +.TP +.B LOOP_SET_STATUS64 +.TQ +.B LOOP_GET_STATUS64 +These are similar to +.BR LOOP_SET_STATUS " and " LOOP_GET_STATUS +described above but use the +.I loop_info64 +structure, +which has some additional fields and a larger range for some other fields: +.IP +.in +4n +.EX +struct loop_info64 { + uint64_t lo_device; /* ioctl r/o */ + uint64_t lo_inode; /* ioctl r/o */ + uint64_t lo_rdevice; /* ioctl r/o */ + uint64_t lo_offset; + uint64_t lo_sizelimit; /* bytes, 0 == max available */ + uint32_t lo_number; /* ioctl r/o */ + uint32_t lo_encrypt_type; + uint32_t lo_encrypt_key_size; /* ioctl w/o */ + uint32_t lo_flags; i /* ioctl r/w (r/o before + Linux 2.6.25) */ + uint8_t lo_file_name[LO_NAME_SIZE]; + uint8_t lo_crypt_name[LO_NAME_SIZE]; + uint8_t lo_encrypt_key[LO_KEY_SIZE]; /* ioctl w/o */ + uint64_t lo_init[2]; +}; +.EE +.in +.SS /dev/loop-control +Since Linux 3.1, +.\" commit 770fe30a46a12b6fb6b63fbe1737654d28e84844 +the kernel provides the +.I /dev/loop\-control +device, which permits an application to dynamically find a free device, +and to add and remove loop devices from the system. +To perform these operations, one first opens +.I /dev/loop\-control +and then employs one of the following +.BR ioctl (2) +operations: +.TP +.B LOOP_CTL_GET_FREE +Allocate or find a free loop device for use. +On success, the device number is returned as the result of the call. +This operation takes no argument. +.TP +.B LOOP_CTL_ADD +Add the new loop device whose device number is specified +as a long integer in the third +.BR ioctl (2) +argument. +On success, the device index is returned as the result of the call. +If the device is already allocated, the call fails with the error +.BR EEXIST . +.TP +.B LOOP_CTL_REMOVE +Remove the loop device whose device number is specified +as a long integer in the third +.BR ioctl (2) +argument. +On success, the device number is returned as the result of the call. +If the device is in use, the call fails with the error +.BR EBUSY . +.SH FILES +.TP +.I /dev/loop* +The loop block special device files. +.SH EXAMPLES +The program below uses the +.I /dev/loop\-control +device to find a free loop device, opens the loop device, +opens a file to be used as the underlying storage for the device, +and then associates the loop device with the backing store. +The following shell session demonstrates the use of the program: +.P +.in +4n +.EX +$ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP +10+0 records in +10+0 records out +10485760 bytes (10 MB) copied, 0.00609385 s, 1.7 GB/s +$ \fBsudo ./mnt_loop file.img\fP +loopname = /dev/loop5 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + int loopctlfd, loopfd, backingfile; + long devnr; + char loopname[4096]; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s backing\-file\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + loopctlfd = open("/dev/loop\-control", O_RDWR); + if (loopctlfd == \-1) + errExit("open: /dev/loop\-control"); +\& + devnr = ioctl(loopctlfd, LOOP_CTL_GET_FREE); + if (devnr == \-1) + errExit("ioctl\-LOOP_CTL_GET_FREE"); +\& + sprintf(loopname, "/dev/loop%ld", devnr); + printf("loopname = %s\en", loopname); +\& + loopfd = open(loopname, O_RDWR); + if (loopfd == \-1) + errExit("open: loopname"); +\& + backingfile = open(argv[1], O_RDWR); + if (backingfile == \-1) + errExit("open: backing\-file"); +\& + if (ioctl(loopfd, LOOP_SET_FD, backingfile) == \-1) + errExit("ioctl\-LOOP_SET_FD"); +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR losetup (8), +.BR mount (8) diff --git a/man/man4/lp.4 b/man/man4/lp.4 new file mode 100644 index 0000000..8b3e722 --- /dev/null +++ b/man/man4/lp.4 @@ -0,0 +1,137 @@ +'\" t +.\" Copyright (c) Michael Haardt (michael@cantor.informatik.rwth-aachen.de), +.\" Sun Jan 15 19:16:33 1995 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, Sun Feb 26 15:02:58 1995, faith@cs.unc.edu +.TH lp 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +lp \- line printer devices +.SH SYNOPSIS +.nf +.B #include +.fi +.SH CONFIGURATION +\fBlp\fP[0\[en]2] are character devices for the parallel line printers; +they have major number 6 and minor number 0\[en]2. +The minor numbers +correspond to the printer port base addresses 0x03bc, 0x0378, and 0x0278. +Usually they have mode 220 and are owned by user +.I root +and group +.IR lp . +You can use printer ports either with polling or with interrupts. +Interrupts are recommended when high traffic is expected, for example, +for laser printers. +For typical dot matrix printers, polling will usually be enough. +The default is polling. +.SH DESCRIPTION +The following +.BR ioctl (2) +calls are supported: +.TP +.BR "int ioctl(int " fd ", LPTIME, int " arg ) +Sets the amount of time that the driver sleeps before rechecking the printer +when the printer's buffer appears to be filled to +.IR arg . +If you have a fast printer, decrease this number; +if you have a slow printer, then increase it. +This is in hundredths of a second, the default 2 +being 0.02 seconds. +It influences only the polling driver. +.TP +.BR "int ioctl(int " fd ", LPCHAR, int " arg ) +Sets the maximum number of busy-wait iterations which the polling driver does +while waiting for the printer to get ready for receiving a character to +.IR arg . +If printing is too slow, increase this number; if the +system gets too slow, decrease this number. +The default is 1000. +It influences only the polling driver. +.TP +.BR "int ioctl(int " fd ", LPABORT, int " arg ) +If +.I arg +is 0, the printer driver will retry on errors, otherwise +it will abort. +The default is 0. +.TP +.BR "int ioctl(int " fd ", LPABORTOPEN, int " arg ) +If +.I arg +is 0, +.BR open (2) +will be aborted on error, otherwise error will be ignored. +The default is to ignore it. +.TP +.BR "int ioctl(int " fd ", LPCAREFUL, int " arg ) +If +.I arg +is 0, then the out-of-paper, offline, and error signals are +required to be false on all writes, otherwise they are ignored. +The default is to ignore them. +.TP +.BR "int ioctl(int " fd ", LPWAIT, int " arg ) +Sets the number of busy waiting iterations to wait before strobing the +printer to accept a just-written character, and the number of iterations to +wait before turning the strobe off again, +to +.IR arg . +The specification says this time should be 0.5 +microseconds, but experience has shown the delay caused by the code is +already enough. +For that reason, the default value is 0. +.\" FIXME . Actually, since Linux 2.2, the default is 1 +This is used for both the polling and the interrupt driver. +.TP +.BR "int ioctl(int " fd ", LPSETIRQ, int " arg ) +This +.BR ioctl (2) +requires superuser privileges. +It takes an +.I int +containing the new IRQ as argument. +As a side effect, the printer will be reset. +When +.I arg +is 0, the polling driver will be used, which is also default. +.TP +.BR "int ioctl(int " fd ", LPGETIRQ, int *" arg ) +Stores the currently used IRQ in +.IR arg . +.TP +.BR "int ioctl(int " fd ", LPGETSTATUS, int *" arg ) +Stores the value of the status port in +.IR arg . +The bits have the following meaning: +.TS +l l. +LP_PBUSY inverted busy input, active high +LP_PACK unchanged acknowledge input, active low +LP_POUTPA unchanged out-of-paper input, active high +LP_PSELECD unchanged selected input, active high +LP_PERRORP unchanged error input, active low +.TE +.IP +Refer to your printer manual for the meaning of the signals. +Note that undocumented bits may also be set, depending on your printer. +.TP +.BR "int ioctl(int " fd ", LPRESET)" +Resets the printer. +No argument is used. +.SH FILES +.I /dev/lp* +.\" .SH AUTHORS +.\" The printer driver was originally written by Jim Weigand and Linus +.\" Torvalds. +.\" It was further improved by Michael K.\& Johnson. +.\" The interrupt code was written by Nigel Gamble. +.\" Alan Cox modularized it. +.\" LPCAREFUL, LPABORT, LPGETSTATUS were added by Chris Metcalf. +.SH SEE ALSO +.BR chmod (1), +.BR chown (1), +.BR mknod (1), +.BR lpcntl (8), +.BR tunelp (8) diff --git a/man/man4/mem.4 b/man/man4/mem.4 new file mode 100644 index 0000000..22b6b3c --- /dev/null +++ b/man/man4/mem.4 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 16:59:10 1993 by Rik Faith (faith@cs.unc.edu) +.TH mem 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mem, kmem, port \- system memory, kernel memory and system ports +.SH DESCRIPTION +.I /dev/mem +is a character device file +that is an image of the main memory of the computer. +It may be used, for example, to examine (and even patch) the system. +.P +Byte addresses in +.I /dev/mem +are interpreted as physical memory addresses. +References to nonexistent locations cause errors to be returned. +.P +Examining and patching is likely to lead to unexpected results +when read-only or write-only bits are present. +.P +Since Linux 2.6.26, and depending on the architecture, the +.B CONFIG_STRICT_DEVMEM +kernel configuration option limits the areas +which can be accessed through this file. +For example: on x86, RAM access is not allowed but accessing +memory-mapped PCI regions is. +.P +It is typically created by: +.P +.in +4n +.EX +mknod \-m 660 /dev/mem c 1 1 +chown root:kmem /dev/mem +.EE +.in +.P +The file +.I /dev/kmem +is the same as +.IR /dev/mem , +except that the kernel virtual memory +rather than physical memory is accessed. +Since Linux 2.6.26, this file is available only if the +.B CONFIG_DEVKMEM +kernel configuration option is enabled. +.P +It is typically created by: +.P +.in +4n +.EX +mknod \-m 640 /dev/kmem c 1 2 +chown root:kmem /dev/kmem +.EE +.in +.P +.I /dev/port +is similar to +.IR /dev/mem , +but the I/O ports are accessed. +.P +It is typically created by: +.P +.in +4n +.EX +mknod \-m 660 /dev/port c 1 4 +chown root:kmem /dev/port +.EE +.in +.SH FILES +.I /dev/mem +.br +.I /dev/kmem +.br +.I /dev/port +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR ioperm (2) diff --git a/man/man4/mouse.4 b/man/man4/mouse.4 new file mode 100644 index 0000000..3435423 --- /dev/null +++ b/man/man4/mouse.4 @@ -0,0 +1,171 @@ +'\" t +.\" This manpage is Copyright (C) 1996 Michael Haardt. +.\" Updates Nov 1998, Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH mouse 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mouse \- serial mouse interface +.SH CONFIGURATION +Serial mice are connected to a serial RS232/V24 dialout line, see +.BR ttyS (4) +for a description. +.SH DESCRIPTION +.SS Introduction +The pinout of the usual 9 pin plug as used for serial mice is: +.P +.TS +center; +r c l. +pin name used for +2 RX Data +3 TX \-12 V, Imax = 10 mA +4 DTR +12 V, Imax = 10 mA +7 RTS +12 V, Imax = 10 mA +5 GND Ground +.TE +.P +This is the specification, in fact 9 V suffices with most mice. +.P +The mouse driver can recognize a mouse by dropping RTS to low and raising +it again. +About 14 ms later the mouse will send 0x4D (\[aq]M\[aq]) on the data line. +After a further 63 ms, a Microsoft-compatible 3-button mouse will send +0x33 (\[aq]3\[aq]). +.P +The relative mouse movement is sent as +.I dx +(positive means right) +and +.I dy +(positive means down). +Various mice can operate at different speeds. +To select speeds, cycle through the +speeds 9600, 4800, 2400, and 1200 bit/s, each time writing the two characters +from the table below and waiting 0.1 seconds. +The following table shows available speeds and the strings that select them: +.P +.TS +center; +l l. +bit/s string +9600 *q +4800 *p +2400 *o +1200 *n +.TE +.P +The first byte of a data packet can be used for synchronization purposes. +.SS Microsoft protocol +The +.B Microsoft +protocol uses 1 start bit, 7 data bits, no parity +and one stop bit at the speed of 1200 bits/sec. +Data is sent to RxD in 3-byte packets. +The +.I dx +and +.I dy +movements are sent as +two's-complement, +.I lb +.RI ( rb ) +are set when the left (right) +button is pressed: +.P +.TS +center; +r c c c c c c c. +byte d6 d5 d4 d3 d2 d1 d0 +1 1 lb rb dy7 dy6 dx7 dx6 +2 0 dx5 dx4 dx3 dx2 dx1 dx0 +3 0 dy5 dy4 dy3 dy2 dy1 dy0 +.TE +.SS 3-button Microsoft protocol +Original Microsoft mice only have two buttons. +However, there are some +three button mice which also use the Microsoft protocol. +Pressing or +releasing the middle button is reported by sending a packet with zero +movement and no buttons pressed. +(Thus, unlike for the other two buttons, the status of the middle +button is not reported in each packet.) +.SS Logitech protocol +Logitech serial 3-button mice use a different extension of the +Microsoft protocol: when the middle button is up, the above 3-byte +packet is sent. +When the middle button is down a 4-byte packet is +sent, where the 4th byte has value 0x20 (or at least has the 0x20 +bit set). +In particular, a press of the middle button is reported +as 0,0,0,0x20 when no other buttons are down. +.SS Mousesystems protocol +The +.B Mousesystems +protocol uses 1 start bit, 8 data bits, no parity, +and two stop bits at the speed of 1200 bits/sec. +Data is sent to RxD in +5-byte packets. +.I dx +is sent as the sum of the two two's-complement +values, +.I dy +is send as negated sum of the two two's-complement +values. +.I lb +.RI ( mb , +.IR rb ) +are cleared when the left (middle, +right) button is pressed: +.P +.TS +center; +r c c c c c c c c. +byte d7 d6 d5 d4 d3 d2 d1 d0 +1 1 0 0 0 0 lb mb rb +2 0 dxa6 dxa5 dxa4 dxa3 dxa2 dxa1 dxa0 +3 0 dya6 dya5 dya4 dya3 dya2 dya1 dya0 +4 0 dxb6 dxb5 dxb4 dxb3 dxb2 dxb1 dxb0 +5 0 dyb6 dyb5 dyb4 dyb3 dyb2 dyb1 dyb0 +.TE +.P +Bytes 4 and 5 describe the change that occurred since bytes 2 and 3 +were transmitted. +.SS Sun protocol +The +.B Sun +protocol is the 3-byte version of the above 5-byte +Mousesystems protocol: the last two bytes are not sent. +.SS MM protocol +The +.B MM +protocol uses 1 start bit, 8 data bits, odd parity, and one +stop bit at the speed of 1200 bits/sec. +Data is sent to RxD in 3-byte +packets. +.I dx +and +.I dy +are sent as single signed values, the +sign bit indicating a negative value. +.I lb +.RI ( mb , +.IR rb ) +are +set when the left (middle, right) button is pressed: +.P +.TS +center; +r c c c c c c c c. +byte d7 d6 d5 d4 d3 d2 d1 d0 +1 1 0 0 dxs dys lb mb rb +2 0 dx6 dx5 dx4 dx3 dx2 dx1 dx0 +3 0 dy6 dy5 dy4 dy3 dy2 dy1 dy0 +.TE +.SH FILES +.TP +.I /dev/mouse +A commonly used symbolic link pointing to a mouse device. +.SH SEE ALSO +.BR ttyS (4), +.BR gpm (8) diff --git a/man/man4/msr.4 b/man/man4/msr.4 new file mode 100644 index 0000000..ef5b2b3 --- /dev/null +++ b/man/man4/msr.4 @@ -0,0 +1,42 @@ +.\" Copyright (c) 2009 Intel Corporation, Author Andi Kleen +.\" Some sentences copied from comments in arch/x86/kernel/msr.c +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH msr 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +msr \- x86 CPU MSR access device +.SH DESCRIPTION +.I /dev/cpu/CPUNUM/msr +provides an interface to read and write the model-specific +registers (MSRs) of an x86 CPU. +.I CPUNUM +is the number of the CPU to access as listed in +.IR /proc/cpuinfo . +.P +The register access is done by opening the file and seeking +to the MSR number as offset in the file, and then +reading or writing in chunks of 8 bytes. +An I/O transfer of more than 8 bytes means multiple reads or writes +of the same register. +.P +This file is protected so that it can be read and written only by the user +.IR root , +or members of the group +.IR root . +.SH NOTES +The +.I msr +driver is not auto-loaded. +On modular kernels you might need to use the following command +to load it explicitly before use: +.P +.in +4n +.EX +$ modprobe msr +.EE +.in +.SH SEE ALSO +Intel Corporation Intel 64 and IA-32 Architectures +Software Developer's Manual Volume 3B Appendix B, +for an overview of the Intel CPU MSRs. diff --git a/man/man4/null.4 b/man/man4/null.4 new file mode 100644 index 0000000..f9c718e --- /dev/null +++ b/man/man4/null.4 @@ -0,0 +1,52 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:00:12 1993 by Rik Faith (faith@cs.unc.edu) +.TH null 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +null, zero \- data sink +.SH DESCRIPTION +Data written to the +.I /dev/null +and +.I /dev/zero +special files is discarded. +.P +Reads from +.I /dev/null +always return end of file (i.e., +.BR read (2) +returns 0), whereas reads from +.I /dev/zero +always return bytes containing zero (\[aq]\e0\[aq] characters). +.P +These devices are typically created by: +.P +.in +4n +.EX +mknod \-m 666 /dev/null c 1 3 +mknod \-m 666 /dev/zero c 1 5 +chown root:root /dev/null /dev/zero +.EE +.in +.SH FILES +.I /dev/null +.br +.I /dev/zero +.SH NOTES +If these devices are not writable and readable for all users, many +programs will act strangely. +.P +Since Linux 2.6.31, +.\" commit 2b83868723d090078ac0e2120e06a1cc94dbaef0 +reads from +.I /dev/zero +are interruptible by signals. +(This change was made to help with bad latencies for large reads from +.IR /dev/zero .) +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR full (4) diff --git a/man/man4/port.4 b/man/man4/port.4 new file mode 100644 index 0000000..d4c1762 --- /dev/null +++ b/man/man4/port.4 @@ -0,0 +1 @@ +.so man4/mem.4 diff --git a/man/man4/ptmx.4 b/man/man4/ptmx.4 new file mode 100644 index 0000000..b50d4e7 --- /dev/null +++ b/man/man4/ptmx.4 @@ -0,0 +1 @@ +.so man4/pts.4 diff --git a/man/man4/pts.4 b/man/man4/pts.4 new file mode 100644 index 0000000..0ed004d --- /dev/null +++ b/man/man4/pts.4 @@ -0,0 +1,75 @@ +.\" This man page was written by Jeremy Phelps . +.\" Notes added - aeb +.\" +.\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE) +.\" Redistribute and revise at will. +.\" %%%LICENSE_END +.\" +.TH pts 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ptmx, pts \- pseudoterminal master and slave +.SH DESCRIPTION +The file +.I /dev/ptmx +(the pseudoterminal multiplexor device) +is a character file with major number 5 and +minor number 2, usually with mode 0666 and ownership root:root. +It is used to create a pseudoterminal master and slave pair. +.P +When a process opens +.IR /dev/ptmx , +it gets a file +descriptor for a pseudoterminal master +and a pseudoterminal slave device is created in the +.I /dev/pts +directory. +Each file descriptor obtained by opening +.I /dev/ptmx +is an independent pseudoterminal master with its own associated slave, +whose path can +be found by passing the file descriptor to +.BR ptsname (3). +.P +Before opening the pseudoterminal slave, you must pass the master's file +descriptor to +.BR grantpt (3) +and +.BR unlockpt (3). +.P +Once both the pseudoterminal master and slave are open, the slave provides +processes with an interface that is identical to that of a real terminal. +.P +Data written to the slave is presented on the master file descriptor as input. +Data written to the master is presented to the slave as input. +.P +In practice, pseudoterminals are used for implementing terminal emulators +such as +.BR xterm (1), +in which data read from the pseudoterminal master is interpreted by the +application in the same way +a real terminal would interpret the data, and for implementing remote-login +programs such as +.BR sshd (8), +in which data read from the pseudoterminal master is sent across the network +to a client program that is connected to a terminal or terminal emulator. +.P +Pseudoterminals can also be used to send input to programs that normally +refuse to read input from pipes (such as +.BR su (1), +and +.BR passwd (1)). +.SH FILES +.IR /dev/ptmx , +.I /dev/pts/* +.SH NOTES +The Linux support for the above (known as UNIX 98 pseudoterminal naming) +is done using the +.I devpts +filesystem, which should be mounted on +.IR /dev/pts . +.SH SEE ALSO +.BR getpt (3), +.BR grantpt (3), +.BR ptsname (3), +.BR unlockpt (3), +.BR pty (7) diff --git a/man/man4/ram.4 b/man/man4/ram.4 new file mode 100644 index 0000000..1b59a50 --- /dev/null +++ b/man/man4/ram.4 @@ -0,0 +1,28 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:01:11 1993 by Rik Faith (faith@cs.unc.edu) +.TH ram 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ram \- ram disk device +.SH DESCRIPTION +The +.I ram +device is a block device to access the ram disk in raw mode. +.P +It is typically created by: +.P +.in +4n +.EX +mknod \-m 660 /dev/ram b 1 1 +chown root:disk /dev/ram +.EE +.in +.SH FILES +.I /dev/ram +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR mount (8) diff --git a/man/man4/random.4 b/man/man4/random.4 new file mode 100644 index 0000000..78fe128 --- /dev/null +++ b/man/man4/random.4 @@ -0,0 +1,349 @@ +.\" Copyright (c) 1997 John S. Kallal (kallal@voicenet.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Some changes by tytso and aeb. +.\" +.\" 2004-12-16, John V. Belmonte/mtk, Updated init and quit scripts +.\" 2004-04-08, AEB, Improved description of read from /dev/urandom +.\" 2008-06-20, George Spelvin , +.\" Matt Mackall +.\" +.TH random 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +random, urandom \- kernel random number source devices +.SH SYNOPSIS +.nf +#include +.P +.BI "int ioctl(" fd ", RND" request ", " param ");" +.fi +.SH DESCRIPTION +The character special files \fI/dev/random\fP and +\fI/dev/urandom\fP (present since Linux 1.3.30) +provide an interface to the kernel's random number generator. +The file +.I /dev/random +has major device number 1 and minor device number 8. +The file +.I /dev/urandom +has major device number 1 and minor device number 9. +.P +The random number generator gathers environmental noise +from device drivers and other sources into an entropy pool. +The generator also keeps an estimate of the +number of bits of noise in the entropy pool. +From this entropy pool, random numbers are created. +.P +Linux 3.17 and later provides the simpler and safer +.BR getrandom (2) +interface which requires no special files; +see the +.BR getrandom (2) +manual page for details. +.P +When read, the +.I /dev/urandom +device returns random bytes using a pseudorandom +number generator seeded from the entropy pool. +Reads from this device do not block (i.e., the CPU is not yielded), +but can incur an appreciable delay when requesting large amounts of data. +.P +When read during early boot time, +.I /dev/urandom +may return data prior to the entropy pool being initialized. +.\" This is a real problem; see +.\" commit 9b4d008787f864f17d008c9c15bbe8a0f7e2fc24 +If this is of concern in your application, use +.BR getrandom (2) +or \fI/dev/random\fP instead. +.P +The \fI/dev/random\fP device is a legacy interface which dates back to +a time where the cryptographic primitives used in the implementation +of \fI/dev/urandom\fP were not widely trusted. +It will return random bytes only within the estimated number of +bits of fresh noise in the entropy pool, blocking if necessary. +\fI/dev/random\fP is suitable for applications that need +high quality randomness, and can afford indeterminate delays. +.P +When the entropy pool is empty, reads from \fI/dev/random\fP will block +until additional environmental noise is gathered. +Since Linux 5.6, the +.B O_NONBLOCK +flag is ignored as +.I /dev/random +will no longer block except during early boot process. +In earlier versions, if +.BR open (2) +is called for +.I /dev/random +with the +.B O_NONBLOCK +flag, a subsequent +.BR read (2) +will not block if the requested number of bytes is not available. +Instead, the available bytes are returned. +If no byte is available, +.BR read (2) +will return \-1 and +.I errno +will be set to +.BR EAGAIN . +.P +The +.B O_NONBLOCK +flag has no effect when opening +.IR /dev/urandom . +When calling +.BR read (2) +for the device +.IR /dev/urandom , +reads of up to 256 bytes will return as many bytes as are requested +and will not be interrupted by a signal handler. +Reads with a buffer over this limit may return less than the +requested number of bytes or fail with the error +.BR EINTR , +if interrupted by a signal handler. +.P +Since Linux 3.16, +.\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc +a +.BR read (2) +from +.I /dev/urandom +will return at most 32\ MB. +A +.BR read (2) +from +.I /dev/random +will return at most 512 bytes +.\" SEC_XFER_SIZE in drivers/char/random.c +(340 bytes before Linux 2.6.12). +.P +Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the +entropy pool with the data written, but this will not result in a +higher entropy count. +This means that it will impact the contents +read from both files, but it will not make reads from +\fI/dev/random\fP faster. +.SS Usage +The +.I /dev/random +interface is considered a legacy interface, and +.I /dev/urandom +is preferred and sufficient in all use cases, with the exception of +applications which require randomness during early boot time; for +these applications, +.BR getrandom (2) +must be used instead, +because it will block until the entropy pool is initialized. +.P +If a seed file is saved across reboots as recommended below, +the output is +cryptographically secure against attackers without local root access as +soon as it is reloaded in the boot sequence, and perfectly adequate for +network encryption session keys. +(All major Linux distributions have saved the seed file across reboots +since 2000 at least.) +Since reads from +.I /dev/random +may block, users will usually want to open it in nonblocking mode +(or perform a read with timeout), +and provide some sort of user notification if the desired +entropy is not immediately available. +.\" +.SS Configuration +If your system does not have +\fI/dev/random\fP and \fI/dev/urandom\fP created already, they +can be created with the following commands: +.P +.in +4n +.EX +mknod \-m 666 /dev/random c 1 8 +mknod \-m 666 /dev/urandom c 1 9 +chown root:root /dev/random /dev/urandom +.EE +.in +.P +When a Linux system starts up without much operator interaction, +the entropy pool may be in a fairly predictable state. +This reduces the actual amount of noise in the entropy pool +below the estimate. +In order to counteract this effect, it helps to carry +entropy pool information across shut-downs and start-ups. +To do this, add the lines to an appropriate script +which is run during the Linux system start-up sequence: +.P +.in +4n +.EX +echo "Initializing random number generator..." +random_seed=/var/run/random\-seed +# Carry a random seed from start\-up to start\-up +# Load and then save the whole entropy pool +if [ \-f $random_seed ]; then + cat $random_seed >/dev/urandom +else + touch $random_seed +fi +chmod 600 $random_seed +poolfile=/proc/sys/kernel/random/poolsize +[ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 +bytes=$(expr $bits / 8) +dd if=/dev/urandom of=$random_seed count=1 bs=$bytes +.EE +.in +.P +Also, add the following lines in an appropriate script which is +run during the Linux system shutdown: +.P +.in +4n +.EX +# Carry a random seed from shut\-down to start\-up +# Save the whole entropy pool +echo "Saving random seed..." +random_seed=/var/run/random\-seed +touch $random_seed +chmod 600 $random_seed +poolfile=/proc/sys/kernel/random/poolsize +[ \-r $poolfile ] && bits=$(cat $poolfile) || bits=4096 +bytes=$(expr $bits / 8) +dd if=/dev/urandom of=$random_seed count=1 bs=$bytes +.EE +.in +.P +In the above examples, we assume Linux 2.6.0 or later, where +.I /proc/sys/kernel/random/poolsize +returns the size of the entropy pool in bits (see below). +.\" +.SS /proc interfaces +The files in the directory +.I /proc/sys/kernel/random +(present since Linux 2.3.16) provide additional information about the +.I /dev/random +device: +.TP +.I entropy_avail +This read-only file gives the available entropy, in bits. +This will be a number in the range 0 to 4096. +.TP +.I poolsize +This file +gives the size of the entropy pool. +The semantics of this file vary across kernel versions: +.RS +.TP +Linux 2.4: +This file gives the size of the entropy pool in +.IR bytes . +Normally, this file will have the value 512, but it is writable, +and can be changed to any value for which an algorithm is available. +The choices are 32, 64, 128, 256, 512, 1024, or 2048. +.TP +Linux 2.6 and later: +This file is read-only, and gives the size of the entropy pool in +.IR bits . +It contains the value 4096. +.RE +.TP +.I read_wakeup_threshold +This file +contains the number of bits of entropy required for waking up processes +that sleep waiting for entropy from +.IR /dev/random . +The default is 64. +.TP +.I write_wakeup_threshold +This file +contains the number of bits of entropy below which we wake up +processes that do a +.BR select (2) +or +.BR poll (2) +for write access to +.IR /dev/random . +These values can be changed by writing to the files. +.TP +.IR uuid " and " boot_id +These read-only files +contain random strings like 6fd5a44b\-35f4\-4ad4\-a9b9\-6b9be13e1fe9. +The former is generated afresh for each read, the latter was +generated once. +.\" +.SS ioctl(2) interface +The following +.BR ioctl (2) +requests are defined on file descriptors connected to either \fI/dev/random\fP +or \fI/dev/urandom\fP. +All requests performed will interact with the input +entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP. +The +.B CAP_SYS_ADMIN +capability is required for all requests except +.BR RNDGETENTCNT . +.TP +.B RNDGETENTCNT +Retrieve the entropy count of the input pool, the contents will be the same +as the +.I entropy_avail +file under proc. +The result will be stored in the int pointed to by the argument. +.TP +.B RNDADDTOENTCNT +Increment or decrement the entropy count of the input pool +by the value pointed to by the argument. +.TP +.B RNDGETPOOL +Removed in Linux 2.6.9. +.TP +.B RNDADDENTROPY +Add some additional entropy to the input pool, +incrementing the entropy count. +This differs from writing to \fI/dev/random\fP or \fI/dev/urandom\fP, +which only adds some +data but does not increment the entropy count. +The following structure is used: +.IP +.in +4n +.EX +struct rand_pool_info { + int entropy_count; + int buf_size; + __u32 buf[0]; +}; +.EE +.in +.IP +Here +.I entropy_count +is the value added to (or subtracted from) the entropy count, and +.I buf +is the buffer of size +.I buf_size +which gets added to the entropy pool. +.TP +.B RNDZAPENTCNT +.TQ +.B RNDCLEARPOOL +Zero the entropy count of all pools and add some system data (such as +wall clock) to the pools. +.SH FILES +.I /dev/random +.br +.I /dev/urandom +.SH NOTES +For an overview and comparison of the various interfaces that +can be used to obtain randomness, see +.BR random (7). +.SH BUGS +During early boot time, reads from +.I /dev/urandom +may return data prior to the entropy pool being initialized. +.\" .SH AUTHOR +.\" The kernel's random number generator was written by +.\" Theodore Ts'o (tytso@athena.mit.edu). +.SH SEE ALSO +.BR mknod (1), +.BR getrandom (2), +.BR random (7) +.P +RFC\ 1750, "Randomness Recommendations for Security" diff --git a/man/man4/rtc.4 b/man/man4/rtc.4 new file mode 100644 index 0000000..f720086 --- /dev/null +++ b/man/man4/rtc.4 @@ -0,0 +1,347 @@ +.\" rtc.4 +.\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" $Id: rtc.4,v 1.4 2005/12/05 17:19:49 urs Exp $ +.\" +.\" 2006-02-08 Various additions by mtk +.\" 2006-11-26 cleanup, cover the generic rtc framework; David Brownell +.\" +.TH rtc 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rtc \- real-time clock +.SH SYNOPSIS +.nf +#include +.P +.BI "int ioctl(" fd ", RTC_" request ", " param ");" +.fi +.SH DESCRIPTION +This is the interface to drivers for real-time clocks (RTCs). +.P +Most computers have one or more hardware clocks which record the +current "wall clock" time. +These are called "Real Time Clocks" (RTCs). +One of these usually has battery backup power so that it tracks the time +even while the computer is turned off. +RTCs often provide alarms and other interrupts. +.P +All i386 PCs, and ACPI-based systems, have an RTC that is compatible with +the Motorola MC146818 chip on the original PC/AT. +Today such an RTC is usually integrated into the mainboard's chipset +(south bridge), and uses a replaceable coin-sized backup battery. +.P +Non-PC systems, such as embedded systems built around system-on-chip +processors, use other implementations. +They usually won't offer the same functionality as the RTC from a PC/AT. +.SS RTC vs system clock +RTCs should not be confused with the system clock, which is +a software clock maintained by the kernel and used to implement +.BR gettimeofday (2) +and +.BR time (2), +as well as setting timestamps on files, and so on. +The system clock reports seconds and microseconds since a start point, +defined to be the POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC). +(One common implementation counts timer interrupts, once +per "jiffy", at a frequency of 100, 250, or 1000 Hz.) +That is, it is supposed to report wall clock time, which RTCs also do. +.P +A key difference between an RTC and the system clock is that RTCs +run even when the system is in a low power state (including "off"), +and the system clock can't. +Until it is initialized, the system clock can only report time since +system boot ... not since the POSIX Epoch. +So at boot time, and after resuming from a system low power state, the +system clock will often be set to the current wall clock time using an RTC. +Systems without an RTC need to set the system clock using another clock, +maybe across the network or by entering that data manually. +.SS RTC functionality +RTCs can be read and written with +.BR hwclock (8), +or directly with the +.BR ioctl (2) +requests listed below. +.P +Besides tracking the date and time, many RTCs can also generate +interrupts +.IP \[bu] 3 +on every clock update (i.e., once per second); +.IP \[bu] +at periodic intervals with a frequency that can be set to +any power-of-2 multiple in the range 2 Hz to 8192 Hz; +.IP \[bu] +on reaching a previously specified alarm time. +.P +Each of those interrupt sources can be enabled or disabled separately. +On many systems, the alarm interrupt can be configured as a system wakeup +event, which can resume the system from a low power state such as +Suspend-to-RAM (STR, called S3 in ACPI systems), +Hibernation (called S4 in ACPI systems), +or even "off" (called S5 in ACPI systems). +On some systems, the battery backed RTC can't issue +interrupts, but another one can. +.P +The +.I /dev/rtc +(or +.IR /dev/rtc0 , +.IR /dev/rtc1 , +etc.) +device can be opened only once (until it is closed) and it is read-only. +On +.BR read (2) +and +.BR select (2) +the calling process is blocked until the next interrupt from that RTC +is received. +Following the interrupt, the process can read a long integer, of which +the least significant byte contains a bit mask encoding +the types of interrupt that occurred, +while the remaining 3 bytes contain the number of interrupts since the +last +.BR read (2). +.SS ioctl(2) interface +The following +.BR ioctl (2) +requests are defined on file descriptors connected to RTC devices: +.TP +.B RTC_RD_TIME +Returns this RTC's time in the following structure: +.IP +.in +4n +.EX +struct rtc_time { + int tm_sec; + int tm_min; + int tm_hour; + int tm_mday; + int tm_mon; + int tm_year; + int tm_wday; /* unused */ + int tm_yday; /* unused */ + int tm_isdst; /* unused */ +}; +.EE +.in +.IP +The fields in this structure have the same meaning and ranges as for the +.I tm +structure described in +.BR gmtime (3). +A pointer to this structure should be passed as the third +.BR ioctl (2) +argument. +.TP +.B RTC_SET_TIME +Sets this RTC's time to the time specified by the +.I rtc_time +structure pointed to by the third +.BR ioctl (2) +argument. +To set the +RTC's time the process must be privileged (i.e., have the +.B CAP_SYS_TIME +capability). +.TP +.B RTC_ALM_READ +.TQ +.B RTC_ALM_SET +Read and set the alarm time, for RTCs that support alarms. +The alarm interrupt must be separately enabled or disabled using the +.BR RTC_AIE_ON ", " RTC_AIE_OFF +requests. +The third +.BR ioctl (2) +argument is a pointer to an +.I rtc_time +structure. +Only the +.IR tm_sec , +.IR tm_min , +and +.I tm_hour +fields of this structure are used. +.TP +.B RTC_IRQP_READ +.TQ +.B RTC_IRQP_SET +Read and set the frequency for periodic interrupts, +for RTCs that support periodic interrupts. +The periodic interrupt must be separately enabled or disabled using the +.BR RTC_PIE_ON ", " RTC_PIE_OFF +requests. +The third +.BR ioctl (2) +argument is an +.I "unsigned long\ *" +or an +.IR "unsigned long" , +respectively. +The value is the frequency in interrupts per second. +The set of allowable frequencies is the multiples of two +in the range 2 to 8192. +Only a privileged process (i.e., one having the +.B CAP_SYS_RESOURCE +capability) can set frequencies above the value specified in +.IR /proc/sys/dev/rtc/max\-user\-freq . +(This file contains the value 64 by default.) +.TP +.B RTC_AIE_ON +.TQ +.B RTC_AIE_OFF +Enable or disable the alarm interrupt, for RTCs that support alarms. +The third +.BR ioctl (2) +argument is ignored. +.TP +.B RTC_UIE_ON +.TQ +.B RTC_UIE_OFF +Enable or disable the interrupt on every clock update, +for RTCs that support this once-per-second interrupt. +The third +.BR ioctl (2) +argument is ignored. +.TP +.B RTC_PIE_ON +.TQ +.B RTC_PIE_OFF +Enable or disable the periodic interrupt, +for RTCs that support these periodic interrupts. +The third +.BR ioctl (2) +argument is ignored. +Only a privileged process (i.e., one having the +.B CAP_SYS_RESOURCE +capability) can enable the periodic interrupt if the frequency is +currently set above the value specified in +.IR /proc/sys/dev/rtc/max\-user\-freq . +.TP +.B RTC_EPOCH_READ +.TQ +.B RTC_EPOCH_SET +Many RTCs encode the year in an 8-bit register which is either +interpreted as an 8-bit binary number or as a BCD number. +In both cases, +the number is interpreted relative to this RTC's Epoch. +The RTC's Epoch is +initialized to 1900 on most systems but on Alpha and MIPS it might +also be initialized to 1952, 1980, or 2000, depending on the value of +an RTC register for the year. +With some RTCs, +these operations can be used to read or to set the RTC's Epoch, +respectively. +The third +.BR ioctl (2) +argument is an +.I "unsigned long\ *" +or an +.IR "unsigned long" , +respectively, and the value returned (or assigned) is the Epoch. +To set the RTC's Epoch the process must be privileged (i.e., have the +.B CAP_SYS_TIME +capability). +.TP +.B RTC_WKALM_RD +.TQ +.B RTC_WKALM_SET +Some RTCs support a more powerful alarm interface, using these ioctls +to read or write the RTC's alarm time (respectively) with this structure: +.P +.RS +.in +4n +.EX +struct rtc_wkalrm { + unsigned char enabled; + unsigned char pending; + struct rtc_time time; +}; +.EE +.in +.RE +.IP +The +.I enabled +flag is used to enable or disable the alarm interrupt, +or to read its current status; when using these calls, +.BR RTC_AIE_ON " and " RTC_AIE_OFF +are not used. +The +.I pending +flag is used by +.B RTC_WKALM_RD +to report a pending interrupt +(so it's mostly useless on Linux, except when talking +to the RTC managed by EFI firmware). +The +.I time +field is as used with +.B RTC_ALM_READ +and +.B RTC_ALM_SET +except that the +.IR tm_mday , +.IR tm_mon , +and +.I tm_year +fields are also valid. +A pointer to this structure should be passed as the third +.BR ioctl (2) +argument. +.SH FILES +.TP +.I /dev/rtc +.TQ +.I /dev/rtc0 +.TQ +.I /dev/rtc1 +.TQ +\&.\|.\|. +RTC special character device files. +.TP +.I /proc/driver/rtc +status of the (first) RTC. +.SH NOTES +When the kernel's system time is synchronized with an external +reference using +.BR adjtimex (2) +it will update a designated RTC periodically every 11 minutes. +To do so, the kernel has to briefly turn off periodic interrupts; +this might affect programs using that RTC. +.P +An RTC's Epoch has nothing to do with the POSIX Epoch which is +used only for the system clock. +.P +If the year according to the RTC's Epoch and the year register is +less than 1970 it is assumed to be 100 years later, that is, between 2000 +and 2069. +.P +Some RTCs support "wildcard" values in alarm fields, to support +scenarios like periodic alarms at fifteen minutes after every hour, +or on the first day of each month. +Such usage is nonportable; +portable user-space code expects only a single alarm interrupt, and +will either disable or reinitialize the alarm after receiving it. +.P +Some RTCs support periodic interrupts with periods that are multiples +of a second rather than fractions of a second; +multiple alarms; +programmable output clock signals; +nonvolatile memory; +and other hardware +capabilities that are not currently exposed by this API. +.SH SEE ALSO +.BR date (1), +.BR adjtimex (2), +.BR gettimeofday (2), +.BR settimeofday (2), +.BR stime (2), +.BR time (2), +.BR gmtime (3), +.BR time (7), +.BR hwclock (8) +.P +.I Documentation/rtc.txt +in the Linux kernel source tree diff --git a/man/man4/sd.4 b/man/man4/sd.4 new file mode 100644 index 0000000..62fc270 --- /dev/null +++ b/man/man4/sd.4 @@ -0,0 +1,117 @@ +.\" sd.4 +.\" Copyright 1992 Rickard E. Faith (faith@cs.unc.edu) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sd 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sd \- driver for SCSI disk drives +.SH SYNOPSIS +.nf +.BR "#include " "/* for HDIO_GETGEO */" +.BR "#include " "/* for BLKGETSIZE and BLKRRPART */" +.fi +.SH CONFIGURATION +The block device name has the following form: +.BI sd lp, +where +.I l +is a letter denoting the physical drive, and +.I p +is a number denoting the partition on that physical drive. +Often, the partition number, +.IR p , +will be left off when the device corresponds to the whole drive. +.P +SCSI disks have a major device number of 8, and a minor device number of +the form (16 * +.IR drive_number ") + " partition_number , +where +.I drive_number +is the number of the physical drive in order of detection, and +.I partition_number +is as follows: +.IP \[bu] 3 +partition 0 is the whole drive +.IP \[bu] +partitions 1\[en]4 are the DOS "primary" partitions +.IP \[bu] +partitions 5\[en]8 are the DOS "extended" (or "logical") partitions +.P +For example, +.I /dev/sda +will have major 8, minor 0, and will refer to all of the first SCSI drive +in the system; and +.I /dev/sdb3 +will have major 8, minor 19, and will refer to the third DOS "primary" +partition on the second SCSI drive in the system. +.P +At this time, only block devices are provided. +Raw devices have not yet been implemented. +.SH DESCRIPTION +The following +.IR ioctl s +are provided: +.TP +.B HDIO_GETGEO +Returns the BIOS disk parameters in the following structure: +.P +.in +4n +.EX +struct hd_geometry { + unsigned char heads; + unsigned char sectors; + unsigned short cylinders; + unsigned long start; +}; +.EE +.in +.IP +A pointer to this structure is passed as the +.BR ioctl (2) +parameter. +.IP +The information returned in the parameter is the disk geometry of the drive +.I "as understood by DOS!" +This geometry is +.I not +the physical geometry of the drive. +It is used when constructing the +drive's partition table, however, and is needed for convenient operation +of +.BR fdisk (1), +.BR efdisk (1), +and +.BR lilo (1). +If the geometry information is not available, zero will be returned for all +of the parameters. +.TP +.B BLKGETSIZE +Returns the device size in sectors. +The +.BR ioctl (2) +parameter should be a pointer to a +.IR long . +.TP +.B BLKRRPART +Forces a reread of the SCSI disk partition tables. +No parameter is needed. +.IP +The SCSI +.BR ioctl (2) +operations are also supported. +If the +.BR ioctl (2) +parameter is required, and it is NULL, then +.BR ioctl (2) +fails with the error +.BR EINVAL . +.SH FILES +.TP +.I /dev/sd[a\-h] +the whole device +.TP +.I /dev/sd[a\-h][0\-8] +individual block partitions +.\".SH SEE ALSO +.\".BR scsi (4) diff --git a/man/man4/sk98lin.4 b/man/man4/sk98lin.4 new file mode 100644 index 0000000..69b9612 --- /dev/null +++ b/man/man4/sk98lin.4 @@ -0,0 +1,580 @@ +'\" t +.\" (C)Copyright 1999-2003 Marvell(R) -- linux@syskonnect.de +.\" sk98lin.4 1.1 2003/12/17 10:03:18 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" This manpage can be viewed using `groff -Tascii -man sk98lin.4 | less` +.\" +.TH sk98lin 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sk98lin \- Marvell/SysKonnect Gigabit Ethernet driver v6.21 +.SH SYNOPSIS +.B insmod sk98lin.o +.RB [ Speed_A=\c +.IR i,j,... ] +.RB [ Speed_B=\c +.IR i,j,... ] +.RB [ AutoNeg_A=\c +.IR i,j,... ] +.RB [ AutoNeg_B=\c +.IR i,j,... ] +.RB [ DupCap_A=\c +.IR i,j,... ] +.RB [ DupCap_B=\c +.IR i,j,... ] +.RB [ FlowCtrl_A=\c +.IR i,j,... ] +.RB [ FlowCtrl_B=\c +.IR i,j,... ] +.RB [ Role_A=\c +.IR i,j,... ] +.RB [ Role_B=\c +.IR i,j,... ] +.RB [ ConType=\c +.IR i,j,... ] +.RB [ Moderation=\c +.IR i,j,... ] +.RB [ IntsPerSec=\c +.IR i,j,... ] +.RB [ PrefPort=\c +.IR i,j,... ] +.RB [ RlmtMode=\c +.IR i,j,... ] +.SH DESCRIPTION +.ad l +.hy 0 +.BR Note : +This obsolete driver was removed in Linux 2.6.26. +.P +.B sk98lin +is the Gigabit Ethernet driver for +Marvell and SysKonnect network adapter cards. +It supports SysKonnect SK-98xx/SK-95xx +compliant Gigabit Ethernet Adapter and +any Yukon compliant chipset. +.P +When loading the driver using insmod, +parameters for the network adapter cards +might be stated as a sequence of comma separated commands. +If for instance two network adapters are installed and AutoNegotiation on +Port A of the first adapter should be ON, +but on the Port A of the second adapter switched OFF, one must enter: +.P +.in +4n +.EX +insmod sk98lin.o AutoNeg_A=On,Off +.EE +.in +.P +After +.B sk98lin +is bound to one or more adapter cards and the +.I /proc +filesystem is mounted on your system, a dedicated statistics file +will be created in the folder +.I /proc/net/sk98lin +for all ports of the installed network adapter cards. +Those files are named +.IR eth[x] , +where +.I x +is the number of the interface that has been assigned to a +dedicated port by the system. +.P +If loading is finished, any desired IP address can be +assigned to the respective +.I eth[x] +interface using the +.BR ifconfig (8) +command. +This causes the adapter to connect to the Ethernet and to display a status +message on the console saying "ethx: network connection up using port y" +followed by the configured or detected connection parameters. +.P +The +.B sk98lin +also supports large frames (also called jumbo frames). +Using jumbo frames can improve throughput tremendously when +transferring large amounts of data. +To enable large frames, the MTU (maximum transfer unit) size +for an interface is to be set to a high value. +The default MTU size is 1500 and can be changed up to 9000 (bytes). +Setting the MTU size can be done when assigning the IP address +to the interface or later by using the +.BR ifconfig (8) +command with the mtu parameter. +If for instance eth0 needs an IP +address and a large frame MTU size, +the following two commands might be used: +.P +.in +4n +.EX +ifconfig eth0 10.1.1.1 +ifconfig eth0 mtu 9000 +.EE +.in +.P +Those two commands might even be combined into one: +.P +.in +4n +.EX +ifconfig eth0 10.1.1.1 mtu 9000 +.EE +.in +.P +Note that large frames can be used only if permitted by +your network infrastructure. +This means, that any switch being used in your Ethernet must +also support large frames. +Quite some switches support large frames, +but need to be configured to do so. +Most of the times, their default setting is to support only +standard frames with an MTU size of 1500 (bytes). +In addition to the switches inside the network, +all network adapters that are to be used must also be +enabled regarding jumbo frames. +If an adapter is not set to receive large frames, it will simply drop them. +.P +Switching back to the standard Ethernet frame size can be done by using the +.BR ifconfig (8) +command again: +.P +.in +4n +.EX +ifconfig eth0 mtu 1500 +.EE +.in +.P +The Marvell/SysKonnect Gigabit Ethernet driver for Linux is able to +support VLAN and Link Aggregation according to +IEEE standards 802.1, 802.1q, and 802.3ad. +Those features are available only after installation of open source modules +which can be found on the Internet: +.P +.IR VLAN : +.UR http://www.candelatech.com\:/\[ti]greear\:/vlan.html +.UE +.br +.I Link +.IR Aggregation : +.UR http://www.st.rim.or.jp\:/\[ti]yumo +.UE +.P +Note that Marvell/SysKonnect does not offer any support for these +open source modules and does not take the responsibility for any +kind of failures or problems arising when using these modules. +.SS Parameters +.TP +.BI Speed_A= i,j,... +This parameter is used to set the speed capabilities of port A of an +adapter card. +It is valid only for Yukon copper adapters. +Possible values are: +.IR 10 , +.IR 100 , +.IR 1000 , +or +.IR Auto ; +.I Auto +is the default. +Usually, the speed is negotiated between the two ports +during link establishment. +If this fails, +a port can be forced to a specific setting with this parameter. +.TP +.BI Speed_B= i,j,... +This parameter is used to set the speed capabilities of port B of +an adapter card. +It is valid only for Yukon copper adapters. +Possible values are: +.IR 10 , +.IR 100 , +.IR 1000 , +or +.IR Auto ; +.I Auto +is the default. +Usually, the speed is negotiated between the two ports during link +establishment. +If this fails, +a port can be forced to a specific setting with this parameter. +.TP +.BI AutoNeg_A= i,j,... +Enables or disables the use of autonegotiation of port A of an adapter card. +Possible values are: +.IR On , +.IR Off , +or +.IR Sense ; +.I On +is the default. +The +.I Sense +mode automatically detects whether the link partner supports +auto-negotiation or not. +.TP +.BI AutoNeg_B= i,j,... +Enables or disables the use of autonegotiation of port B of an adapter card. +Possible values are: +.IR On , +.IR Off , +or +.IR Sense ; +.I On +is the default. +The +.I Sense +mode automatically detects whether the link partner supports +auto-negotiation or not. +.TP +.BI DupCap_A= i,j,... +This parameter indicates the duplex mode to be used for port A +of an adapter card. +Possible values are: +.IR Half , +.IR Full , +or +.IR Both ; +.I Both +is the default. +This parameter is relevant only if AutoNeg_A of port A is not set to +.IR Sense . +If AutoNeg_A is set to +.IR On , +all three values of DupCap_A ( +.IR Half , +.IR Full , +or +.IR Both ) +might be stated. +If AutoNeg_A is set to +.IR Off , +only DupCap_A values +.I Full +and +.I Half +are allowed. +This DupCap_A parameter is useful if your link partner does not +support all possible duplex combinations. +.TP +.BI DupCap_B= i,j,... +This parameter indicates the duplex mode to be used for port B +of an adapter card. +Possible values are: +.IR Half , +.IR Full , +or +.IR Both ; +.I Both +is the default. +This parameter is relevant only if AutoNeg_B of port B is not set to +.IR Sense . +If AutoNeg_B is set to +.IR On , +all three values of DupCap_B ( +.IR Half , +.IR Full , +or +.IR Both ) +might be stated. +If AutoNeg_B is set to +.IR Off , +only DupCap_B values +.I Full +and +.I Half +are allowed. +This DupCap_B parameter is useful if your link partner does not +support all possible duplex combinations. +.TP +.BI FlowCtrl_A= i,j,... +This parameter can be used to set the flow control capabilities the +port reports during auto-negotiation. +Possible values are: +.IR Sym , +.IR SymOrRem , +.IR LocSend , +or +.IR None ; +.I SymOrRem +is the default. +The different modes have the following meaning: +.RS +.TP +.IR Sym " = Symmetric" +Both link partners are allowed to send PAUSE frames. +.TP +.IR SymOrRem " = SymmetricOrRemote" +Both or only remote partner are allowed to send PAUSE frames. +.TP +.IR LocSend " = LocalSend" +Only local link partner is allowed to send PAUSE frames. +.TP +.IR None " = None" +No link partner is allowed to send PAUSE frames. +.RE +.IP +Note that this parameter is ignored if AutoNeg_A is set to +.IR Off . +.TP +.BI FlowCtrl_B= i,j,... +This parameter can be used to set the flow control capabilities the +port reports during auto-negotiation. +Possible values are: +.IR Sym , +.IR SymOrRem , +.IR LocSend , +or +.IR None ; +.I SymOrRem +is the default. +The different modes have the following meaning: +.RS +.TP +.IR Sym " = Symmetric" +Both link partners are allowed to send PAUSE frames. +.TP +.IR SymOrRem " = SymmetricOrRemote" +Both or only remote partner are allowed to send PAUSE frames. +.TP +.IR LocSend " = LocalSend" +Only local link partner is allowed to send PAUSE frames. +.TP +.IR None " = None" +No link partner is allowed to send PAUSE frames. +.RE +.IP +Note that this parameter is ignored if AutoNeg_B is set to +.IR Off . +.TP +.BI Role_A= i,j,... +This parameter is valid only for 1000Base-T adapter cards. +For two 1000Base-T ports to communicate, +one must take the role of the master (providing timing information), +while the other must be the slave. +Possible values are: +.IR Auto , +.IR Master , +or +.IR Slave ; +.I Auto +is the default. +Usually, the role of a port is negotiated between two ports during +link establishment, but if that fails the port A of an adapter card +can be forced to a specific setting with this parameter. +.TP +.BI Role_B= i,j,... +This parameter is valid only for 1000Base-T adapter cards. +For two 1000Base-T ports to communicate, one must take +the role of the master (providing timing information), +while the other must be the slave. +Possible values are: +.IR Auto , +.IR Master , +or +.IR Slave ; +.I Auto +is the default. +Usually, the role of a port is negotiated between +two ports during link establishment, but if that fails +the port B of an adapter card can be forced to a +specific setting with this parameter. +.TP +.BI ConType= i,j,... +This parameter is a combination of all five per-port parameters +within one single parameter. +This simplifies the configuration of both ports of an adapter card. +The different values of this variable reflect the +most meaningful combinations of port parameters. +Possible values and their corresponding combination of per-port parameters: +.IP +.TS +lb lb lb lb lb lb +l l l l l l. +ConType DupCap AutoNeg FlowCtrl Role Speed +\fIAuto\fP Both On SymOrRem Auto Auto +\fI100FD\fP Full Off None Auto 100 +\fI100HD\fP Half Off None Auto 100 +\fI10FD\fP Full Off None Auto 10 +\fI10HD\fP Half Off None Auto 10 +.TE +.IP +Stating any other port parameter together with this +.I ConType +parameter will result in a merged configuration of those settings. +This is due to +the fact, that the per-port parameters (e.g., +.IR Speed_A ) +have a higher priority than the combined variable +.IR ConType . +.TP +.BI Moderation= i,j,... +Interrupt moderation is employed to limit the maximum number of interrupts +the driver has to serve. +That is, one or more interrupts (which indicate any transmit or +receive packet to be processed) are queued until the driver processes them. +When queued interrupts are to be served, is determined by the +.I IntsPerSec +parameter, which is explained later below. +Possible moderation modes are: +.IR None , +.IR Static , +or +.IR Dynamic ; +.I None +is the default. +The different modes have the following meaning: +.IP +.I None +No interrupt moderation is applied on the adapter card. +Therefore, each transmit or receive interrupt is served immediately +as soon as it appears on the interrupt line of the adapter card. +.IP +.I Static +Interrupt moderation is applied on the adapter card. +All transmit and receive interrupts are queued until +a complete moderation interval ends. +If such a moderation interval ends, all queued interrupts +are processed in one big bunch without any delay. +The term +.I Static +reflects the fact, that interrupt moderation is always enabled, +regardless how much network load is currently passing via a +particular interface. +In addition, the duration of the moderation interval has a fixed +length that never changes while the driver is operational. +.IP +.I Dynamic +Interrupt moderation might be applied on the adapter card, +depending on the load of the system. +If the driver detects that the system load is too high, +the driver tries to shield the system against too much network +load by enabling interrupt moderation. +If\[em]at a later time\[em]the CPU utilization decreases +again (or if the network load is negligible), the interrupt +moderation will automatically be disabled. +.IP +Interrupt moderation should be used when the driver has to +handle one or more interfaces with a high network load, +which\[em]as a consequence\[em]leads also to a high CPU utilization. +When moderation is applied in such high network load situations, +CPU load might be reduced by 20\[en]30% on slow computers. +.IP +Note that the drawback of using interrupt moderation is an increase of +the round-trip-time (RTT), due to the queuing and serving of +interrupts at dedicated moderation times. +.TP +.BI IntsPerSec= i,j,... +This parameter determines the length of any interrupt moderation interval. +Assuming that static interrupt moderation is to be used, an +.I IntsPerSec +parameter value of 2000 will lead to an interrupt moderation interval of +500 microseconds. +Possible values for this parameter are in the range of +30...40000 (interrupts per second). +The default value is 2000. +.IP +This parameter is used only if either static or dynamic interrupt moderation +is enabled on a network adapter card. +This parameter is ignored if no moderation is applied. +.IP +Note that the duration of the moderation interval is to be chosen with care. +At first glance, selecting a very long duration (e.g., only 100 interrupts per +second) seems to be meaningful, but the increase of packet-processing delay +is tremendous. +On the other hand, selecting a very short moderation time might +compensate the use of any moderation being applied. +.TP +.BI PrefPort= i,j,... +This parameter is used to force the preferred port to +A or B (on dual-port network adapters). +The preferred port is the one that is used if both ports A and B are +detected as fully functional. +Possible values are: +.I A +or +.IR B ; +.I A +is the default. +.TP +.BI RlmtMode= i,j,... +RLMT monitors the status of the port. +If the link of the active port fails, +RLMT switches immediately to the standby link. +The virtual link is maintained as long as at least one "physical" link is up. +This parameters states how RLMT should monitor both ports. +Possible values are: +.IR CheckLinkState , +.IR CheckLocalPort , +.IR CheckSeg , +or +.IR DualNet ; +.I CheckLinkState +is the default. +The different modes have the following meaning: +.IP +.I CheckLinkState +Check link state only: RLMT uses the link state reported by the adapter +hardware for each individual port to determine whether a port can be used +for all network traffic or not. +.IP +.I CheckLocalPort +In this mode, RLMT monitors the network path between the two +ports of an adapter by regularly exchanging packets between them. +This mode requires a network configuration in which the +two ports are able to "see" each other (i.e., there +must not be any router between the ports). +.IP +.I CheckSeg +Check local port and segmentation: +This mode supports the same functions as the CheckLocalPort +mode and additionally checks network segmentation between the ports. +Therefore, this mode is to be used only if Gigabit Ethernet +switches are installed on the network that have been +configured to use the Spanning Tree protocol. +.IP +.I DualNet +In this mode, ports A and B are used as separate devices. +If you have a dual port adapter, port A will be configured as +.I eth[x] +and port B as +.IR eth[x+1] . +Both ports can be used independently with distinct IP addresses. +The preferred port setting is not used. +RLMT is turned off. +.IP +Note that RLMT modes +.I CheckLocalPort +and +.I CheckLinkState +are designed to operate in configurations where a +network path between the ports on one adapter exists. +Moreover, they are not designed to work where adapters are +connected back-to-back. +.SH FILES +.TP +.I /proc/net/sk98lin/eth[x] +The statistics file of a particular interface of an adapter card. +It contains generic information about the adapter card plus a detailed +summary of all transmit and receive counters. +.TP +.I /usr/src/linux/Documentation/networking/sk98lin.txt +This is the +.I README +file of the +.I sk98lin +driver. +It contains a detailed installation HOWTO and describes all parameters +of the driver. +It denotes also common problems and provides the solution to them. +.SH BUGS +Report any bugs to linux@syskonnect.de +.\" .SH AUTHORS +.\" Ralph Roesler \[em] rroesler@syskonnect.de +.\" .br +.\" Mirko Lindner \[em] mlindner@syskonnect.de +.SH SEE ALSO +.BR ifconfig (8), +.BR insmod (8), +.BR modprobe (8) diff --git a/man/man4/smartpqi.4 b/man/man4/smartpqi.4 new file mode 100644 index 0000000..97a5809 --- /dev/null +++ b/man/man4/smartpqi.4 @@ -0,0 +1,496 @@ +'\" t +.\" Copyright (C) 2019-2023, Microchip Technology Inc. and its subsidiaries +.\" Copyright (C) 2016-2018, Microsemi Corporation +.\" Copyright (C) 2016, PMC-Sierra, Inc. +.\" Written by Kevin Barnett +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.TH smartpqi 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +smartpqi \- Microchip Smart Storage SCSI driver +.SH SYNOPSIS +.SY "modprobe smartpqi" +.RB [ disable_device_id_wildcards= { 0 | 1 }] +.RB [ disable_heartbeat= { 0 | 1 }] +.RB [ disable_ctrl_shutdown= { 0 | 1 }] +.RB [ lockup_action= { none | reboot | panic }] +.RB [ expose_ld_first= { 0 | 1 }] +.RB [ hide_vsep= { 0 | 1 }] +.RB [ disable_managed_interrupts= { 0 | 1 }] +.RB [ ctrl_ready_timeout= { 0 |[ 30 , 1800 ]}] +.YS +.SH DESCRIPTION +.B smartpqi +is a SCSI driver for Microchip Smart Storage controllers. +.SS Supported \f[BI]ioctl\fP\/() operations +For compatibility with applications written for the +.BR cciss (4) +and +.BR hpsa (4) +drivers, many, but not all of the +.BR ioctl (2) +operations supported by the +.B hpsa +driver are also supported by the +.B smartpqi +driver. +The data structures used by these operations +are described in the Linux kernel source file +.IR include/linux/cciss_ioctl.h . +.TP +.B CCISS_DEREGDISK +.TQ +.B CCISS_REGNEWDISK +.TQ +.B CCISS_REGNEWD +These operations +all do exactly the same thing, which is to cause the driver to re-scan +for new devices. +This does exactly the same thing as writing to the +.BR smartpqi -specific +host +.I rescan +attribute. +.TP +.B CCISS_GETPCIINFO +This operation returns the PCI domain, bus, +device, and function and "board ID" (PCI subsystem ID). +.TP +.B CCISS_GETDRIVVER +This operation returns the driver version in four bytes, encoded as: +.IP +.in +4n +.EX +(major_version << 28) | (minor_version << 24) | + (release << 16) | revision +.EE +.in +.TP +.B CCISS_PASSTHRU +Allows BMIC and CISS commands to be passed through to the controller. +.SS Boot options +.TP +.BR disable_device_id_wildcards= { 0 | 1 } +Disables support for device ID wildcards. +The default value is 0 (wildcards are enabled). +.TP +.BR disable_heartbeat= { 0 | 1 } +Disables support for the controller's heartbeat check. +This parameter is used for debugging purposes. +The default value is 0 (the controller's heartbeat check is enabled). +.TP +.BR disable_ctrl_shutdown= { 0 | 1 } +Disables support for shutting down the controller in the +event of a controller lockup. +The default value is 0 (controller will be shut down). +.TP +.BR lockup_action= { none | reboot | panic } +Specifies the action the driver takes when a controller +lockup is detected. +The default action is +.BR none . +.TS +l l +--- +l l. +parameter action +\fBnone\fP take controller offline only +\fBreboot\fP reboot the system +\fBpanic\fP panic the system +.TE +.TP +.BR expose_ld_first= { 0 | 1 } +This option exposes logical devices to the OS before physical devices. +The default value is 0 (physical devices exposed first). +.TP +.BR hide_vsep= { 0 | 1 } +This option disables exposure of the virtual SEP to the OS. +The default value is 0 (virtual SEP is exposed). +.TP +.BR disable_managed_interrupts= { 0 | 1 } +Disables driver utilization of Linux kernel managed interrupts for controllers. +The managed interrupts feature automatically distributes interrupts +to all available CPUs and assigns SMP affinity. +The default value is 0 (managed interrupts enabled). +.TP +.BR ctrl_ready_timeout= { 0 |[ 30 , 1800 ]} +This option specifies the timeout in seconds for the driver to wait +for the controller to be ready. +The valid range is 0 or +.RB [ 30 ", " 1800 ]. +The default value is 0, +which causes the driver to use a timeout of 180 seconds. +.SH FILES +.SS Device nodes +Disk drives are accessed via the SCSI disk driver +.RI ( sd ), +tape drives via the SCSI tape driver +.RI ( st ), +and the RAID controller via the SCSI generic driver +.RI ( sg ), +with device nodes named +.IR /dev/sd *, +.IR /dev/st *, +and +.IR /dev/sg *, +respectively. +.SS SmartPQI-specific host attribute files in \f[BI]/sys\fP +.TP +.IR /sys/class/scsi_host/host * /rescan +The host +.I rescan +attribute is a write-only attribute. +Writing to this attribute will cause the driver to scan for new, +changed, or removed devices (e.g., hot-plugged tape drives, or newly +configured or deleted logical volumes) and notify the SCSI mid-layer of +any changes detected. +Usually this action is triggered automatically by configuration +changes, so the user should not normally have to write to this file. +Doing so may be useful when hot-plugging devices such as tape drives or +entire storage boxes containing pre-configured logical volumes. +.TP +.IR /sys/class/scsi_host/host * /lockup_action +The host +.I lockup_action +attribute is a read/write attribute. +This attribute will cause the driver to perform a specific action in the +unlikely event that a controller lockup has been detected. +See +.B OPTIONS +above +for an explanation of the +.I lockup_action +values. +.TP +.IR /sys/class/scsi_host/host * /driver_version +The +.I driver_version +attribute is read-only. +This attribute contains the smartpqi driver version. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/driver_version +1.1.2\-126 +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /firmware_version +The +.I firmware_version +attribute is read-only. +This attribute contains the controller firmware version. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/firmware_version +1.29\-112 +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /model +The +.I model +attribute is read-only. +This attribute contains the product identification string of the controller. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/model +1100\-16i +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /serial_number +The +.I serial_number +attribute is read-only. +This attribute contains the unique identification number of the controller. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/serial_number +6A316373777 +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /vendor +The +.I vendor +attribute is read-only. +This attribute contains the vendor identification string of the controller. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_host/host1/vendor +Adaptec +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /enable_stream_detection +The +.I enable_stream_detection +attribute is read-write. +This attribute enables/disables stream detection in the driver. +Enabling stream detection can improve sequential write performance +for ioaccel-enabled volumes. +See the +.B ssd_smart_path_enabled +disk attribute section for details on ioaccel-enabled volumes. +The default value is 1 (stream detection enabled). +.IP +Enable example: +.IP +.in +4n +.EX +$ \c +.B echo 1 > /sys/class/scsi_host/host1/enable_stream_detection +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /enable_r5_writes +The +.I enable_r5_writes +attribute is read-write. +This attribute enables/disables RAID 5 write operations +for ioaccel-enabled volumes. +Enabling can improve sequential write performance. +See the +.B ssd_smart_path_enabled +disk attribute section for details on ioaccel-enabled volumes. +The default value is 1 (RAID 5 writes enabled). +.IP +Enable example: +.IP +.in +4n +.EX +$ \c +.B echo 1 > /sys/class/scsi_host/host1/enable_r5_writes +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /enable_r6_writes +The +.I enable_r6_writes +attribute is read-write. +This attribute enables/disables RAID 6 write operations +for ioaccel-enabled volumes. +Enabling can improve sequential write performance. +See the +.B ssd_smart_path_enabled +disk attribute section for details on ioaccel-enabled volumes. +The default value is 1 (RAID 6 writes enabled). +.IP +Enable example: +.IP +.in +4n +.EX +$ \c +.B echo 1 > /sys/class/scsi_host/host1/enable_r6_writes +.EE +.in +.SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP +In the file specifications below, +.I c +stands for the number of the appropriate SCSI controller, +.I b +is the bus number, +.I t +the target number, and +.I l +is the logical unit number (LUN). +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/raid_level +The +.I raid_level +attribute is read-only. +This attribute contains the RAID level of the logical volume. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/4:0:0:0/device/raid_level +RAID 0 +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/sas_address +The +.I sas_address +attribute is read-only. +This attribute contains the SAS address of the device. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/1:0:3:0/device/sas_address +0x5001173d028543a2 +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/ssd_smart_path_enabled +The +.I ssd_smart_path_enabled +attribute is read-only. +This attribute is for ioaccel-enabled volumes. +(Ioaccel is an alternative driver submission path that allows the +driver to send I/O requests directly to backend SCSI devices, +bypassing the controller firmware. +This results in an increase in performance. +This method is used for HBA disks and for logical volumes comprised of SSDs.) +Contains 1 if ioaccel is enabled for the volume and 0 otherwise. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/1:0:3:0/device/ssd_smart_path_enabled +0 +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/lunid +The +.I lunid +attribute is read-only. +This attribute contains the SCSI LUN ID for the device. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/13:1:0:3/device/lunid +0x0300004000000000 +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/unique_id +The +.I unique_id +attribute is read-only. +This attribute contains a 16-byte ID +that uniquely identifies the device within the controller. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/13:1:0:3/device/unique_id +600508B1001C6D4723A8E98D704FDB94 +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/path_info +The +.I path_info +attribute is read-only. +This attribute contains the +.IR c : b : t : l +of the device +along with the device type +and whether the device is Active or Inactive. +If the device is an HBA device, +.I path_info +will also display the PORT, BOX, and BAY the device is plugged into. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/13:1:0:3/device/path_info +[13:1:0:3] Direct-Access Active +\& +$ \c +.B cat /sys/class/scsi_disk/12:0:9:0/device/path_info +[12:0:9:0] Direct-Access PORT: C1 BOX: 1 BAY: 14 Inactive +[12:0:9:0] Direct-Access PORT: C0 BOX: 1 BAY: 14 Active +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/raid_bypass_cnt +The +.I raid_bypass_cnt +attribute is read-only. +This attribute contains the number of I/O requests +that have gone through the ioaccel path +for ioaccel-enabled volumes. +See the +.B ssd_smart_path_enabled +disk attribute section for details on ioaccel-enabled volumes. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/13:1:0:3/device/raid_bypass_cnt +0x300 +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/sas_ncq_prio_enable +The +.I sas_ncq_prio_enable +attribute is read/write. +This attribute enables SATA NCQ priority support. +This attribute works only when device has NCQ support +and controller firmware can handle IO with NCQ priority attribute. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B echo 1 > /sys/class/scsi_disk/13:1:0:3/device/sas_ncq_prio_enable +.EE +.in +.SH VERSIONS +The +.B smartpqi +driver was added in Linux 4.9. +.SH NOTES +.SS Configuration +To configure a Microchip Smart Storage controller, +refer to the User Guide for the controller, +which can be found by searching for the specific controller at +.UR https://www.microchip.com/design-centers/storage +.UE . +.SH HISTORY +.I /sys/class/scsi_host/host*/version +was replaced by two sysfs entries: +.IP +.I /sys/class/scsi_host/host*/driver_version +.IP +.I /sys/class/scsi_host/host*/firmware_version +.SH SEE ALSO +.BR cciss (4), +.BR hpsa (4), +.BR sd (4), +.BR st (4), +.BR sg (4) +.P +.I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss +in the Linux kernel source tree. diff --git a/man/man4/st.4 b/man/man4/st.4 new file mode 100644 index 0000000..2186e64 --- /dev/null +++ b/man/man4/st.4 @@ -0,0 +1,950 @@ +.\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com) +.\" Copyright 1999-2005 Kai Mäkisara (Kai.Makisara@kolumbus.fi) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH st 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +st \- SCSI tape device +.SH SYNOPSIS +.nf +.B #include +.P +.BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);" +.BI "int ioctl(int " fd ", MTIOCTOP, (struct mtop *)" mt_cmd ); +.BI "int ioctl(int " fd ", MTIOCGET, (struct mtget *)" mt_status ); +.BI "int ioctl(int " fd ", MTIOCPOS, (struct mtpos *)" mt_pos ); +.fi +.SH DESCRIPTION +The +.B st +driver provides the interface to a variety of SCSI tape devices. +Currently, the driver takes control of all detected devices of type +\[lq]sequential-access\[rq]. +The +.B st +driver uses major device number 9. +.P +Each device uses eight minor device numbers. +The lowermost five bits +in the minor numbers are assigned sequentially in the order of +detection. +In the 2.6 kernel, the bits above the eight lowermost bits are +concatenated to the five lowermost bits to form the tape number. +The minor numbers can be grouped into +two sets of four numbers: the principal (auto-rewind) minor device numbers, +.IR n , +and the \[lq]no-rewind\[rq] device numbers, +.RI ( n " + 128)." +Devices opened using the principal device number will be sent a +.B REWIND +command when they are closed. +Devices opened using the \[lq]no-rewind\[rq] device number will not. +(Note that using an auto-rewind device for positioning the tape with, +for instance, mt does not lead to the desired result: the tape is +rewound after the mt command and the next command starts from the +beginning of the tape). +.P +Within each group, four minor numbers are available to define +devices with different characteristics (block size, compression, +density, etc.) +When the system starts up, only the first device is available. +The other three are activated when the default +characteristics are defined (see below). +(By changing compile-time +constants, it is possible to change the balance between the maximum +number of tape drives and the number of minor numbers for each +drive. +The default allocation allows control of 32 tape drives. +For instance, it is possible to control up to 64 tape drives +with two minor numbers for different options.) +.P +Devices are typically created by: +.P +.in +4n +.EX +mknod \-m 666 /dev/st0 c 9 0 +mknod \-m 666 /dev/st0l c 9 32 +mknod \-m 666 /dev/st0m c 9 64 +mknod \-m 666 /dev/st0a c 9 96 +mknod \-m 666 /dev/nst0 c 9 128 +mknod \-m 666 /dev/nst0l c 9 160 +mknod \-m 666 /dev/nst0m c 9 192 +mknod \-m 666 /dev/nst0a c 9 224 +.EE +.in +.P +There is no corresponding block device. +.P +The driver uses an internal buffer that has to be large enough to hold +at least one tape block. +Before Linux 2.1.121, the buffer is +allocated as one contiguous block. +This limits the block size to the +largest contiguous block of memory the kernel allocator can provide. +The limit is currently 128\ kB for 32-bit architectures and +256\ kB for 64-bit architectures. +In newer kernels the driver +allocates the buffer in several parts if necessary. +By default, the +maximum number of parts is 16. +This means that the maximum block size +is very large (2\ MB if allocation of 16 blocks of 128\ kB succeeds). +.P +The driver's internal buffer size is determined by a compile-time +constant which can be overridden with a kernel startup option. +In addition to this, the driver tries to allocate a larger temporary +buffer at run time if necessary. +However, run-time allocation of large +contiguous blocks of memory may fail and it is advisable not to rely +too much on dynamic buffer allocation before Linux 2.1.121 +(this applies also to demand-loading the driver with kerneld or kmod). +.P +The driver does not specifically support any tape drive brand or +model. +After system start-up the tape device options are defined by +the drive firmware. +For example, if the drive firmware selects fixed-block mode, +the tape device uses fixed-block mode. +The options can +be changed with explicit +.BR ioctl (2) +calls and remain in effect when the device is closed and reopened. +Setting the options affects both the auto-rewind and the nonrewind +device. +.P +Different options can be specified for the different devices within +the subgroup of four. +The options take effect when the device is +opened. +For example, the system administrator can define +one device that writes in fixed-block mode with a certain block size, +and one which writes in variable-block mode (if the drive supports +both modes). +.P +The driver supports +.B tape partitions +if they are supported by the drive. +(Note that the tape partitions +have nothing to do with disk partitions. +A partitioned tape can be +seen as several logical tapes within one medium.) +Partition support has to be enabled with an +.BR ioctl (2). +The tape +location is preserved within each partition across partition changes. +The partition used for subsequent tape operations is +selected with an +.BR ioctl (2). +The partition switch is executed together with +the next tape operation in order to avoid unnecessary tape +movement. +The maximum number of partitions on a tape is defined by a +compile-time constant (originally four). +The driver contains an +.BR ioctl (2) +that can format a tape with either one or two partitions. +.P +Device +.I /dev/tape +is usually created as a hard or soft link to the default tape device +on the system. +.P +Starting from Linux 2.6.2, the driver exports in the sysfs directory +.I /sys/class/scsi_tape +the attached devices and some parameters assigned to the devices. +.SS Data transfer +The driver supports operation in both fixed-block mode and +variable-block mode (if supported by the drive). +In fixed-block mode the drive +writes blocks of the specified size and the block size is not +dependent on the byte counts of the write system calls. +In variable-block mode one tape block is written for each write call +and the byte +count determines the size of the corresponding tape block. +Note that +the blocks on the tape don't contain any information about the +writing mode: when reading, the only important thing is to use +commands that accept the block sizes on the tape. +.P +In variable-block mode the read byte count does not have to match +the tape block size exactly. +If the byte count is larger than the +next block on tape, the driver returns the data and the function +returns the actual block size. +If the block size is larger than the +byte count, an error is returned. +.P +In fixed-block mode the read byte counts can be arbitrary if +buffering is enabled, or a multiple of the tape block size if +buffering is disabled. +Before Linux 2.1.121 allow writes with +arbitrary byte count if buffering is enabled. +In all other cases +(before Linux 2.1.121 with buffering disabled or newer kernel) the +write byte count must be a multiple of the tape block size. +.P +In Linux 2.6, the driver tries to use direct transfers between the user +buffer and the device. +If this is not possible, the driver's internal buffer +is used. +The reasons for not using direct transfers include improper alignment +of the user buffer (default is 512 bytes but this can be changed by the HBA +driver), one or more pages of the user buffer not reachable by the +SCSI adapter, and so on. +.P +A filemark is automatically written to tape if the last tape operation +before close was a write. +.P +When a filemark is encountered while reading, the following +happens. +If there are data remaining in the buffer when the filemark +is found, the buffered data is returned. +The next read returns zero +bytes. +The following read returns data from the next file. +The end of +recorded data is signaled by returning zero bytes for two consecutive +read calls. +The third read returns an error. +.SS Ioctls +The driver supports three +.BR ioctl (2) +requests. +Requests not recognized by the +.B st +driver are passed to the +.B SCSI +driver. +The definitions below are from +.IR /usr/include/linux/mtio.h : +.SS MTIOCTOP \[em] perform a tape operation +This request takes an argument of type +.IR "(struct mtop\ *)" . +Not all drives support all operations. +The driver returns an +.B EIO +error if the drive rejects an operation. +.P +.in +4n +.EX +/* Structure for MTIOCTOP \- mag tape op command: */ +struct mtop { + short mt_op; /* operations defined below */ + int mt_count; /* how many of them */ +}; +.EE +.in +.P +Magnetic tape operations for normal tape use: +.TP +.B MTBSF +Backward space over +.I mt_count +filemarks. +.TP +.B MTBSFM +Backward space over +.I mt_count +filemarks. +Reposition the tape to the EOT side of the last filemark. +.TP +.B MTBSR +Backward space over +.I mt_count +records (tape blocks). +.TP +.B MTBSS +Backward space over +.I mt_count +setmarks. +.TP +.B MTCOMPRESSION +Enable compression of tape data within the drive if +.I mt_count +is nonzero and disable compression if +.I mt_count +is zero. +This command uses the MODE page 15 supported by most DATs. +.TP +.B MTEOM +Go to the end of the recorded media (for appending files). +.TP +.B MTERASE +Erase tape. +With Linux 2.6, short erase (mark tape empty) is performed if the +argument is zero. +Otherwise, long erase (erase all) is done. +.TP +.B MTFSF +Forward space over +.I mt_count +filemarks. +.TP +.B MTFSFM +Forward space over +.I mt_count +filemarks. +Reposition the tape to the BOT side of the last filemark. +.TP +.B MTFSR +Forward space over +.I mt_count +records (tape blocks). +.TP +.B MTFSS +Forward space over +.I mt_count +setmarks. +.TP +.B MTLOAD +Execute the SCSI load command. +A special case is available for some HP +autoloaders. +If +.I mt_count +is the constant +.B MT_ST_HPLOADER_OFFSET +plus a number, the number is +sent to the drive to control the autoloader. +.TP +.B MTLOCK +Lock the tape drive door. +.TP +.B MTMKPART +Format the tape into one or two partitions. +If +.I mt_count +is positive, it gives the size of partition 1 and partition +0 contains the rest of the tape. +If +.I mt_count +is zero, the tape is formatted into one partition. +From Linux 4.6, +.\" commit 8038e6456a3e6f5c4759e0d73c4f9165b90c93e7 +a negative +.I mt_count +specifies the size of partition 0 and +the rest of the tape contains partition 1. +The physical ordering of partitions depends on the drive. +This command is not allowed for a drive unless the partition support +is enabled for the drive (see +.B MT_ST_CAN_PARTITIONS +below). +.TP +.B MTNOP +No op\[em]flushes the driver's buffer as a side effect. +Should be used before reading status with +.BR MTIOCGET . +.TP +.B MTOFFL +Rewind and put the drive off line. +.TP +.B MTRESET +Reset drive. +.TP +.B MTRETEN +Re-tension tape. +.TP +.B MTREW +Rewind. +.TP +.B MTSEEK +Seek to the tape block number specified in +.IR mt_count . +This operation requires either a SCSI-2 drive that supports the +.B LOCATE +command (device-specific address) +or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive +Viper, Wangtek, ...). +The block number should be one that was previously returned by +.B MTIOCPOS +if device-specific addresses are used. +.TP +.B MTSETBLK +Set the drive's block length to the value specified in +.IR mt_count . +A block length of zero sets the drive to variable block size mode. +.TP +.B MTSETDENSITY +Set the tape density to the code in +.IR mt_count . +The density codes supported by a drive can be found from the drive +documentation. +.TP +.B MTSETPART +The active partition is switched to +.IR mt_count . +The partitions are numbered from zero. +This command is not allowed for +a drive unless the partition support is enabled for the drive (see +.B MT_ST_CAN_PARTITIONS +below). +.TP +.B MTUNLOAD +Execute the SCSI unload command (does not eject the tape). +.TP +.B MTUNLOCK +Unlock the tape drive door. +.TP +.B MTWEOF +Write +.I mt_count +filemarks. +.TP +.B MTWSM +Write +.I mt_count +setmarks. +.P +Magnetic tape operations for setting of device options (by the superuser): +.TP +.B MTSETDRVBUFFER +Set various drive and driver options according to bits encoded in +.IR mt_count . +These consist of the drive's buffering mode, a set of Boolean driver +options, the buffer write threshold, defaults for the block size and +density, and timeouts (only since Linux 2.1). +A single operation can affect only one item in the list below (the +Booleans counted as one item.) +.IP +A value having zeros in the high-order 4 bits will be used to set the +drive's buffering mode. +The buffering modes are: +.RS +.TP +.B 0 +The drive will not report +.B GOOD +status on write commands until the data +blocks are actually written to the medium. +.TP +.B 1 +The drive may report +.B GOOD +status on write commands as soon as all the +data has been transferred to the drive's internal buffer. +.TP +.B 2 +The drive may report +.B GOOD +status on write commands as soon as (a) all +the data has been transferred to the drive's internal buffer, and +(b) all buffered data from different initiators has been successfully +written to the medium. +.RE +.IP +To control the write threshold the value in +.I mt_count +must include the constant +.B MT_ST_WRITE_THRESHOLD +bitwise ORed with a block count in the low 28 bits. +The block count refers to 1024-byte blocks, not the physical block +size on the tape. +The threshold cannot exceed the driver's internal buffer size (see +DESCRIPTION, above). +.IP +To set and clear the Boolean options +the value in +.I mt_count +must include one of the constants +.BR MT_ST_BOOLEANS , +.BR MT_ST_SETBOOLEANS , +.BR MT_ST_CLEARBOOLEANS , +or +.B MT_ST_DEFBOOLEANS +bitwise ORed with +whatever combination of the following options is desired. +Using +.B MT_ST_BOOLEANS +the options can be set to the values +defined in the corresponding bits. +With +.B MT_ST_SETBOOLEANS +the options can be selectively set and with +.B MT_ST_DEFBOOLEANS +selectively cleared. +.IP +The default options for a tape device are set with +.BR MT_ST_DEFBOOLEANS . +A nonactive tape device (e.g., device with +minor 32 or 160) is activated when the default options for it are +defined the first time. +An activated device inherits from the device +activated at start-up the options not set explicitly. +.IP +The Boolean options are: +.RS +.TP +.BR MT_ST_BUFFER_WRITES " (Default: true)" +Buffer all write operations in fixed-block mode. +If this option is false and the drive uses a fixed block size, then +all write operations must be for a multiple of the block size. +This option must be set false to write reliable multivolume archives. +.TP +.BR MT_ST_ASYNC_WRITES " (Default: true)" +When this option is true, write operations return immediately without +waiting for the data to be transferred to the drive if the data fits +into the driver's buffer. +The write threshold determines how full the buffer must be before a +new SCSI write command is issued. +Any errors reported by the drive will be held until the next +operation. +This option must be set false to write reliable multivolume archives. +.TP +.BR MT_ST_READ_AHEAD " (Default: true)" +This option causes the driver to provide read buffering and +read-ahead in fixed-block mode. +If this option is false and the drive uses a fixed block size, then +all read operations must be for a multiple of the block size. +.TP +.BR MT_ST_TWO_FM " (Default: false)" +This option modifies the driver behavior when a file is closed. +The normal action is to write a single filemark. +If the option is true, the driver will write two filemarks and +backspace over the second one. +.IP +Note: +This option should not be set true for QIC tape drives since they are +unable to overwrite a filemark. +These drives detect the end of recorded data by testing for blank tape +rather than two consecutive filemarks. +Most other current drives also +detect the end of recorded data and using two filemarks is usually +necessary only when interchanging tapes with some other systems. +.TP +.BR MT_ST_DEBUGGING " (Default: false)" +This option turns on various debugging messages from the driver +(effective only if the driver was compiled with +.B DEBUG +defined nonzero). +.TP +.BR MT_ST_FAST_EOM " (Default: false)" +This option causes the +.B MTEOM +operation to be sent directly to the +drive, potentially speeding up the operation but causing the driver to +lose track of the current file number normally returned by the +.B MTIOCGET +request. +If +.B MT_ST_FAST_EOM +is false, the driver will respond to an +.B MTEOM +request by forward spacing over files. +.TP +.BR MT_ST_AUTO_LOCK " (Default: false)" +When this option is true, the drive door is locked when the device file is +opened and unlocked when it is closed. +.TP +.BR MT_ST_DEF_WRITES " (Default: false)" +The tape options (block size, mode, compression, etc.) may change +when changing from one device linked to a drive to another device +linked to the same drive depending on how the devices are +defined. +This option defines when the changes are enforced by the +driver using SCSI-commands and when the drives auto-detection +capabilities are relied upon. +If this option is false, the driver +sends the SCSI-commands immediately when the device is changed. +If the +option is true, the SCSI-commands are not sent until a write is +requested. +In this case, the drive firmware is allowed to detect the +tape structure when reading and the SCSI-commands are used only to +make sure that a tape is written according to the correct specification. +.TP +.BR MT_ST_CAN_BSR " (Default: false)" +When read-ahead is used, the tape must sometimes be spaced backward to the +correct position when the device is closed and the SCSI command to +space backward over records is used for this purpose. +Some older +drives can't process this command reliably and this option can be used +to instruct the driver not to use the command. +The end result is that, +with read-ahead and fixed-block mode, the tape may not be correctly +positioned within a file when the device is closed. +With Linux 2.6, the +default is true for drives supporting SCSI-3. +.TP +.BR MT_ST_NO_BLKLIMS " (Default: false)" +Some drives don't accept the +.B "READ BLOCK LIMITS" +SCSI command. +If this is used, the driver does not use the command. +The drawback is +that the driver can't check before sending commands if the selected +block size is acceptable to the drive. +.TP +.BR MT_ST_CAN_PARTITIONS " (Default: false)" +This option enables support for several partitions within a +tape. +The option applies to all devices linked to a drive. +.TP +.BR MT_ST_SCSI2LOGICAL " (Default: false)" +This option instructs the driver to use the logical block addresses +defined in the SCSI-2 standard when performing the seek and tell +operations (both with +.B MTSEEK +and +.B MTIOCPOS +commands and when changing tape +partition). +Otherwise, the device-specific addresses are used. +It is highly advisable to set this option if the drive supports the +logical addresses because they count also filemarks. +There are some +drives that support only the logical block addresses. +.TP +.BR MT_ST_SYSV " (Default: false)" +When this option is enabled, the tape devices use the System V +semantics. +Otherwise, the BSD semantics are used. +The most important +difference between the semantics is what happens when a device used +for reading is closed: in System V semantics the tape is spaced forward +past the next filemark if this has not happened while using the +device. +In BSD semantics the tape position is not changed. +.TP +.BR MT_NO_WAIT " (Default: false)" +Enables immediate mode (i.e., don't wait for the command to finish) for some +commands (e.g., rewind). +.P +An example: +.P +.in +4n +.EX +struct mtop mt_cmd; +mt_cmd.mt_op = MTSETDRVBUFFER; +mt_cmd.mt_count = MT_ST_BOOLEANS | + MT_ST_BUFFER_WRITES | MT_ST_ASYNC_WRITES; +ioctl(fd, MTIOCTOP, mt_cmd); +.EE +.in +.P +The default block size for a device can be set with +.B MT_ST_DEF_BLKSIZE +and the default density code can be set with +.BR MT_ST_DEFDENSITY . +The values for the parameters are or'ed +with the operation code. +.P +With Linux 2.1.x and later, the timeout values can be set with the +subcommand +.B MT_ST_SET_TIMEOUT +ORed with the timeout in seconds. +The long timeout (used for rewinds and other commands +that may take a long time) can be set with +.BR MT_ST_SET_LONG_TIMEOUT . +The kernel defaults are very long to +make sure that a successful command is not timed out with any +drive. +Because of this, the driver may seem stuck even if it is only +waiting for the timeout. +These commands can be used to set more +practical values for a specific drive. +The timeouts set for one device +apply for all devices linked to the same drive. +.P +Starting from Linux 2.4.19 and Linux 2.5.43, the driver supports a status +bit which indicates whether the drive requests cleaning. +The method used by the +drive to return cleaning information is set using the +.B MT_ST_SEL_CLN +subcommand. +If the value is zero, the cleaning +bit is always zero. +If the value is one, the TapeAlert data defined +in the SCSI-3 standard is used (not yet implemented). +Values 2\[en]17 are +reserved. +If the lowest eight bits are >= 18, bits from the extended +sense data are used. +The bits 9\[en]16 specify a mask to select the bits +to look at and the bits 17\[en]23 specify the bit pattern to look for. +If the bit pattern is zero, one or more bits under the mask indicate +the cleaning request. +If the pattern is nonzero, the pattern must match +the masked sense data byte. +.RE +.SS MTIOCGET \[em] get status +This request takes an argument of type +.IR "(struct mtget\ *)" . +.P +.in +4n +.EX +/* structure for MTIOCGET \- mag tape get status command */ +struct mtget { + long mt_type; + long mt_resid; + /* the following registers are device dependent */ + long mt_dsreg; + long mt_gstat; + long mt_erreg; + /* The next two fields are not always used */ + daddr_t mt_fileno; + daddr_t mt_blkno; +}; +.EE +.in +.TP +\fImt_type\fP +The header file defines many values for +.IR mt_type , +but the current driver reports only the generic types +.B MT_ISSCSI1 +(Generic SCSI-1 tape) +and +.B MT_ISSCSI2 +(Generic SCSI-2 tape). +.TP +\fImt_resid\fP +contains the current tape partition number. +.TP +\fImt_dsreg\fP +reports the drive's current settings for block size (in the low 24 +bits) and density (in the high 8 bits). +These fields are defined by +.BR MT_ST_BLKSIZE_SHIFT , +.BR MT_ST_BLKSIZE_MASK , +.BR MT_ST_DENSITY_SHIFT , +and +.BR MT_ST_DENSITY_MASK . +.TP +\fImt_gstat\fP +reports generic (device independent) status information. +The header file defines macros for testing these status bits: +.RS +.TP +\fBGMT_EOF\fP(\fIx\fP) +The tape is positioned just after a filemark +(always false after an +.B MTSEEK +operation). +.TP +\fBGMT_BOT\fP(\fIx\fP) +The tape is positioned at the beginning of the first file (always false +after an +.B MTSEEK +operation). +.TP +\fBGMT_EOT\fP(\fIx\fP) +A tape operation has reached the physical End Of Tape. +.TP +\fBGMT_SM\fP(\fIx\fP) +The tape is currently positioned at a setmark +(always false after an +.B MTSEEK +operation). +.TP +\fBGMT_EOD\fP(\fIx\fP) +The tape is positioned at the end of recorded data. +.TP +\fBGMT_WR_PROT\fP(\fIx\fP) +The drive is write-protected. +For some drives this can also mean that the drive does not support +writing on the current medium type. +.TP +\fBGMT_ONLINE\fP(\fIx\fP) +The last +.BR open (2) +found the drive with a tape in place and ready for operation. +.TP +\fBGMT_D_6250\fP(\fIx\fP) +.TQ +\fBGMT_D_1600\fP(\fIx\fP) +.TQ +\fBGMT_D_800\fP(\fIx\fP) +This \[lq]generic\[rq] status information reports the current +density setting for 9-track \(12" tape drives only. +.TP +\fBGMT_DR_OPEN\fP(\fIx\fP) +The drive does not have a tape in place. +.TP +\fBGMT_IM_REP_EN\fP(\fIx\fP) +Immediate report mode. +This bit is set if there are no guarantees that +the data has been physically written to the tape when the write call +returns. +It is set zero only when the driver does not buffer data and +the drive is set not to buffer data. +.TP +\fBGMT_CLN\fP(\fIx\fP) +The drive has requested cleaning. +Implemented since Linux 2.4.19 and Linux 2.5.43. +.RE +.TP +\fImt_erreg\fP +The only field defined in +.I mt_erreg +is the recovered error count in the low 16 bits (as defined by +.B MT_ST_SOFTERR_SHIFT +and +.BR MT_ST_SOFTERR_MASK ). +Due to inconsistencies in the way drives report recovered errors, this +count is often not maintained (most drives do not by default report +soft errors but this can be changed with a SCSI MODE SELECT command). +.TP +\fImt_fileno\fP +reports the current file number (zero-based). +This value is set to \-1 when the file number is unknown (e.g., after +.B MTBSS +or +.BR MTSEEK ). +.TP +\fImt_blkno\fP +reports the block number (zero-based) within the current file. +This value is set to \-1 when the block number is unknown (e.g., after +.BR MTBSF , +.BR MTBSS , +or +.BR MTSEEK ). +.SS MTIOCPOS \[em] get tape position +This request takes an argument of type +.I "(struct mtpos\ *)" +and reports the drive's notion of the current tape block number, +which is not the same as +.I mt_blkno +returned by +.BR MTIOCGET . +This drive must be a SCSI-2 drive that supports the +.B "READ POSITION" +command (device-specific address) +or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive +Viper, Wangtek, ... ). +.P +.in +4n +.EX +/* structure for MTIOCPOS \- mag tape get position command */ +struct mtpos { + long mt_blkno; /* current block number */ +}; +.EE +.in +.SH RETURN VALUE +.TP +.B EACCES +An attempt was made to write or erase a write-protected tape. +(This error is not detected during +.BR open (2).) +.TP +.B EBUSY +The device is already in use or the driver was unable to allocate a +buffer. +.TP +.B EFAULT +The command parameters point to memory not belonging to the calling +process. +.TP +.B EINVAL +An +.BR ioctl (2) +had an invalid argument, or a requested block size was invalid. +.TP +.B EIO +The requested operation could not be completed. +.TP +.B ENOMEM +The byte count in +.BR read (2) +is smaller than the next physical block on the tape. +(Before Linux 2.2.18 and Linux 2.4.0 the extra bytes have been +.\" Precisely: Linux 2.6.0-test6 +silently ignored.) +.TP +.B ENOSPC +A write operation could not be completed because the tape reached +end-of-medium. +.TP +.B ENOSYS +Unknown +.BR ioctl (2). +.TP +.B ENXIO +During opening, the tape device does not exist. +.TP +.B EOVERFLOW +An attempt was made to read or write a variable-length block that is +larger than the driver's internal buffer. +.TP +.B EROFS +Open is attempted with +.B O_WRONLY +or +.B O_RDWR +when the tape in the drive is write-protected. +.SH FILES +.TP +.I /dev/st* +the auto-rewind SCSI tape devices +.TP +.I /dev/nst* +the nonrewind SCSI tape devices +.\" .SH AUTHOR +.\" The driver has been written by Kai M\(:akisara (Kai.Makisara@metla.fi) +.\" starting from a driver written by Dwayne Forsyth. +.\" Several other +.\" people have also contributed to the driver. +.SH NOTES +.IP \[bu] 3 +When exchanging data between systems, both systems have to agree on +the physical tape block size. +The parameters of a drive after startup +are often not the ones most operating systems use with these +devices. +Most systems use drives in variable-block mode if the drive +supports that mode. +This applies to most modern drives, including +DATs, 8mm helical scan drives, DLTs, etc. +It may be advisable to use +these drives in variable-block mode also in Linux (i.e., use +.B MTSETBLK +or +.B MTSETDEFBLK +at system startup to set the mode), at least when +exchanging data with a foreign system. +The drawback of +this is that a fairly large tape block size has to be used to get +acceptable data transfer rates on the SCSI bus. +.IP \[bu] +Many programs (e.g., +.BR tar (1)) +allow the user to specify the blocking +factor on the command line. +Note that this determines the physical block +size on tape only in variable-block mode. +.IP \[bu] +In order to use SCSI tape drives, the basic SCSI driver, +a SCSI-adapter driver and the SCSI tape driver must be either +configured into the kernel or loaded as modules. +If the SCSI-tape +driver is not present, the drive is recognized but the tape support +described in this page is not available. +.IP \[bu] +The driver writes error messages to the console/log. +The SENSE +codes written into some messages are automatically translated to text +if verbose SCSI messages are enabled in kernel configuration. +.IP \[bu] +The driver's internal buffering allows good throughput in fixed-block +mode also with small +.BR read (2) +and +.BR write (2) +byte counts. +With direct transfers +this is not possible and may cause a surprise when moving to the 2.6 +kernel. +The solution is to tell the software to use larger transfers (often +telling it to use larger blocks). +If this is not possible, direct transfers can be disabled. +.SH SEE ALSO +.BR mt (1) +.P +The file +.I drivers/scsi/README.st +or +.I Documentation/scsi/st.txt +(kernel >= 2.6) in the Linux kernel source tree contains +the most recent information about the driver and its configuration +possibilities diff --git a/man/man4/tty.4 b/man/man4/tty.4 new file mode 100644 index 0000000..60e48c5 --- /dev/null +++ b/man/man4/tty.4 @@ -0,0 +1,67 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 2003-04-07 by Michael Kerrisk +.\" +.TH tty 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tty \- controlling terminal +.SH DESCRIPTION +The file +.I /dev/tty +is a character file with major number 5 and +minor number 0, usually with mode 0666 and ownership root:tty. +It is a synonym for the controlling terminal of a process, if any. +.P +In addition to the +.BR ioctl (2) +requests supported by the device that +.B tty +refers to, the +.BR ioctl (2) +request +.B TIOCNOTTY +is supported. +.SS TIOCNOTTY +Detach the calling process from its controlling terminal. +.P +If the process is the session leader, +then +.B SIGHUP +and +.B SIGCONT +signals are sent to the foreground process group +and all processes in the current session lose their controlling tty. +.P +This +.BR ioctl (2) +call works only on file descriptors connected +to +.IR /dev/tty . +It is used by daemon processes when they are invoked +by a user at a terminal. +The process attempts to open +.IR /dev/tty . +If the open succeeds, it +detaches itself from the terminal by using +.BR TIOCNOTTY , +while if the +open fails, it is obviously not attached to a terminal and does not need +to detach itself. +.SH FILES +.I /dev/tty +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR ioctl (2), +.BR ioctl_console (2), +.BR ioctl_tty (2), +.BR termios (3), +.BR ttyS (4), +.BR vcs (4), +.BR pty (7), +.BR agetty (8), +.BR mingetty (8) diff --git a/man/man4/ttyS.4 b/man/man4/ttyS.4 new file mode 100644 index 0000000..ccf263d --- /dev/null +++ b/man/man4/ttyS.4 @@ -0,0 +1,33 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:03:24 1993 by Rik Faith (faith@cs.unc.edu) +.TH ttyS 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ttyS \- serial terminal lines +.SH DESCRIPTION +.B ttyS[0\-3] +are character devices for the serial terminal lines. +.P +They are typically created by: +.P +.in +4n +.EX +mknod \-m 660 /dev/ttyS0 c 4 64 # base address 0x3f8 +mknod \-m 660 /dev/ttyS1 c 4 65 # base address 0x2f8 +mknod \-m 660 /dev/ttyS2 c 4 66 # base address 0x3e8 +mknod \-m 660 /dev/ttyS3 c 4 67 # base address 0x2e8 +chown root:tty /dev/ttyS[0\-3] +.EE +.in +.SH FILES +.I /dev/ttyS[0\-3] +.SH SEE ALSO +.BR chown (1), +.BR mknod (1), +.BR tty (4), +.BR agetty (8), +.BR mingetty (8), +.BR setserial (8) diff --git a/man/man4/tty_ioctl.4 b/man/man4/tty_ioctl.4 new file mode 100644 index 0000000..fc4736e --- /dev/null +++ b/man/man4/tty_ioctl.4 @@ -0,0 +1,2 @@ +.so man2/ioctl_tty.2 +.\" Link for old name of this page diff --git a/man/man4/urandom.4 b/man/man4/urandom.4 new file mode 100644 index 0000000..b95979f --- /dev/null +++ b/man/man4/urandom.4 @@ -0,0 +1 @@ +.so man4/random.4 diff --git a/man/man4/vcs.4 b/man/man4/vcs.4 new file mode 100644 index 0000000..2b6a3e3 --- /dev/null +++ b/man/man4/vcs.4 @@ -0,0 +1,172 @@ +.\" Copyright (c) 1995 James R. Van Zandt +.\" Sat Feb 18 09:11:07 EST 1995 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, Sun Feb 26 15:08:05 1995, faith@cs.unc.edu +.\" 2007-12-17, Samuel Thibault : +.\" document the VT_GETHIFONTMASK ioctl +.\" " +.TH vcs 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +vcs, vcsa \- virtual console memory +.SH DESCRIPTION +.I /dev/vcs0 +is a character device with major number 7 and minor number +0, usually with mode 0644 and ownership root:tty. +It refers to the memory of the currently +displayed virtual console terminal. +.P +.I /dev/vcs[1\-63] +are character devices for virtual console +terminals, they have major number 7 and minor number 1 to 63, usually +mode 0644 and ownership root:tty. +.I /dev/vcsa[0\-63] +are the same, but +using +.IR "unsigned short" s +(in host byte order) that include attributes, +and prefixed with four bytes giving the screen +dimensions and cursor position: +.IR lines , +.IR columns , +.IR x , +.IR y . +.RI ( x += +.I y += 0 at the top left corner of the screen.) +.P +When a 512-character font is loaded, +the 9th bit position can be fetched by applying the +.BR ioctl (2) +.B VT_GETHIFONTMASK +operation +(available since Linux 2.6.18) +on +.IR /dev/tty[1\-63] ; +the value is returned in the +.I "unsigned short" +pointed to by the third +.BR ioctl (2) +argument. +.P +These devices replace the screendump +.BR ioctl (2) +operations of +.BR ioctl_console (2), +so the system +administrator can control access using filesystem permissions. +.P +The devices for the first eight virtual consoles may be created by: +.P +.in +4n +.EX +for x in 0 1 2 3 4 5 6 7 8; do + mknod \-m 644 /dev/vcs$x c 7 $x; + mknod \-m 644 /dev/vcsa$x c 7 $[$x+128]; +done +chown root:tty /dev/vcs* +.EE +.in +.P +No +.BR ioctl (2) +requests are supported. +.SH FILES +.I /dev/vcs[0\-63] +.br +.I /dev/vcsa[0\-63] +.\" .SH AUTHOR +.\" Andries Brouwer +.SH VERSIONS +Introduced with Linux 1.1.92. +.SH EXAMPLES +You may do a screendump on vt3 by switching to vt1 and typing +.P +.in +4n +.EX +cat /dev/vcs3 >foo +.EE +.in +.P +Note that the output does not contain +newline characters, so some processing may be required, like +in +.P +.in +4n +.EX +fold \-w 81 /dev/vcs3 | lpr +.EE +.in +.P +or (horrors) +.P +.in +4n +.EX +setterm \-dump 3 \-file /proc/self/fd/1 +.EE +.in +.P +The +.I /dev/vcsa0 +device is used for Braille support. +.P +This program displays the character and screen attributes under the +cursor of the second virtual console, then changes the background color +there: +.P +.EX +#include +#include +#include +#include +#include +#include +\& +int +main(void) +{ + int fd; + char *device = "/dev/vcsa2"; + char *console = "/dev/tty2"; + struct {unsigned char lines, cols, x, y;} scrn; + unsigned short s; + unsigned short mask; + unsigned char attrib; + int ch; +\& + fd = open(console, O_RDWR); + if (fd < 0) { + perror(console); + exit(EXIT_FAILURE); + } + if (ioctl(fd, VT_GETHIFONTMASK, &mask) < 0) { + perror("VT_GETHIFONTMASK"); + exit(EXIT_FAILURE); + } + (void) close(fd); + fd = open(device, O_RDWR); + if (fd < 0) { + perror(device); + exit(EXIT_FAILURE); + } + (void) read(fd, &scrn, 4); + (void) lseek(fd, 4 + 2*(scrn.y*scrn.cols + scrn.x), SEEK_SET); + (void) read(fd, &s, 2); + ch = s & 0xff; + if (s & mask) + ch |= 0x100; + attrib = ((s & \[ti]mask) >> 8); + printf("ch=%#03x attrib=%#02x\en", ch, attrib); + s \[ha]= 0x1000; + (void) lseek(fd, \-2, SEEK_CUR); + (void) write(fd, &s, 2); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR ioctl_console (2), +.BR tty (4), +.BR ttyS (4), +.BR gpm (8) diff --git a/man/man4/vcsa.4 b/man/man4/vcsa.4 new file mode 100644 index 0000000..ffe8d9b --- /dev/null +++ b/man/man4/vcsa.4 @@ -0,0 +1 @@ +.so man4/vcs.4 diff --git a/man/man4/veth.4 b/man/man4/veth.4 new file mode 100644 index 0000000..9bdc672 --- /dev/null +++ b/man/man4/veth.4 @@ -0,0 +1,86 @@ +.\" Copyright (c) 2012 Tomáš Pospíšek (tpo_deb@sourcepole.ch), +.\" Fri, 03 Nov 2012 22:35:33 +0100 +.\" and Copyright (c) 2012 Eric W. Biederman +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" +.TH veth 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +veth \- Virtual Ethernet Device +.SH DESCRIPTION +The +.B veth +devices are virtual Ethernet devices. +They can act as tunnels between network namespaces to create +a bridge to a physical network device in another namespace, +but can also be used as standalone network devices. +.P +.B veth +devices are always created in interconnected pairs. +A pair can be created using the command: +.P +.in +4n +.EX +# ip link add type veth peer name +.EE +.in +.P +In the above, +.I p1-name +and +.I p2-name +are the names assigned to the two connected end points. +.P +Packets transmitted on one device in the pair are immediately received on +the other device. +When either device is down, the link state of the pair is down. +.P +.B veth +device pairs are useful for combining the network +facilities of the kernel together in interesting ways. +A particularly interesting use case is to place one end of a +.B veth +pair in one network namespace and the other end in another network namespace, +thus allowing communication between network namespaces. +To do this, one can provide the +.B netns +parameter when creating the interfaces: +.P +.in +4n +.EX +# ip link add netns type veth peer netns +.EE +.in +.P +or, for an existing +.B veth +pair, move one side to the other namespace: +.P +.in +4n +.EX +# ip link set netns +.EE +.in +.P +.BR ethtool (8) +can be used to find the peer of a +.B veth +network interface, using commands something like: +.P +.in +4n +.EX +# \fBip link add ve_A type veth peer name ve_B\fP # Create veth pair +# \fBethtool \-S ve_A\fP # Discover interface index of peer +NIC statistics: + peer_ifindex: 16 +# \fBip link | grep \[aq]\[ha]16:\[aq]\fP # Look up interface +16: ve_B@ve_A: mtu 1500 qdisc ... +.EE +.in +.SH "SEE ALSO" +.BR clone (2), +.BR network_namespaces (7), +.BR ip (8), +.BR ip\-link (8), +.BR ip\-netns (8) diff --git a/man/man4/wavelan.4 b/man/man4/wavelan.4 new file mode 100644 index 0000000..39834d4 --- /dev/null +++ b/man/man4/wavelan.4 @@ -0,0 +1,142 @@ +.\" From jt@hplb.hpl.hp.com Thu Dec 19 18:31:49 1996 +.\" From: Jean Tourrilhes +.\" Address: HP Labs, Filton Road, Stoke Gifford, Bristol BS12 6QZ, U.K. +.\" Jean II - HPLB - '96 +.\" wavelan.c.4 +.\" +.\" Provenance of this page is unclear. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH wavelan 4 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +wavelan \- AT&T GIS WaveLAN ISA device driver +.SH SYNOPSIS +.nf +.BI "insmod wavelan_cs.o [io=" B,B.. "] [ irq=" I,I.. "] [name=" N,N.. ] +.fi +.SH DESCRIPTION +.I This driver is obsolete: +it was removed in Linux 2.6.35. +.P +.B wavelan +is the low-level device driver for the NCR / AT&T / Lucent +.B WaveLAN ISA +and Digital (DEC) +.B RoamAbout DS +wireless ethernet adapter. +This driver is available as a module or +might be compiled in the kernel. +This driver supports multiple cards +in both forms (up to 4) and allocates the next available ethernet +device (eth0..eth#) for each card found, unless a device name is +explicitly specified (see below). +This device name will be reported +in the kernel log file with the MAC address, NWID, and frequency used +by the card. +.SS Parameters +This section applies to the module form (parameters passed on the +.BR insmod (8) +command line). +If the driver is included in the kernel, use the +.I ether=IRQ,IO,NAME +syntax on the kernel command line. +.TP +.B io +Specify the list of base addresses where to search for wavelan cards +(setting by dip switch on the card). +If you don't specify any io +address, the driver will scan 0x390 and 0x3E0 addresses, which might +conflict with other hardware... +.TP +.B irq +Set the list of IRQs that each wavelan card should use (the value is +saved in permanent storage for future use). +.TP +.B name +Set the list of names to be used for each wavelan card device (name +used by +.BR ifconfig (8)). +.SS Wireless extensions +Use +.BR iwconfig (8) +to manipulate wireless extensions. +.SS NWID (or domain) +Set the network ID +.RI [ 0 +to +.IR FFFF ] +or disable it +.RI [ off ]. +As the NWID is stored in the card Permanent Storage Area, it will be +reused at any further invocation of the driver. +.SS Frequency & channels +For the 2.4\ GHz 2.00 Hardware, you are able to set the frequency by +specifying one of the 10 defined channels +.RI ( 2.412, +.I 2.422, 2.425, 2.4305, 2.432, 2.442, 2.452, 2.460, 2.462 +or +.IR 2.484 ) +or directly as a numeric value. +The frequency is changed immediately and +permanently. +Frequency availability depends on the regulations... +.SS Statistics spy +Set a list of MAC addresses in the driver (up to 8) and get the last +quality of link for each of those (see +.BR iwspy (8)). +.SS /proc/net/wireless +.I status +is the status reported by the modem. +.I Link quality +reports the quality of the modulation on the air (direct sequence +spread spectrum) [max = 16]. +.I Level +and +.I Noise +refer to the signal level and noise level [max = 64]. +The +.I crypt discarded packet +and +.I misc discarded packet +counters are not implemented. +.SS Private ioctl +You may use +.BR iwpriv (8) +to manipulate private ioctls. +.SS Quality and level threshold +Enables you to define the quality and level threshold used by the +modem (packet below that level are discarded). +.SS Histogram +This functionality makes it possible to set a number of +signal level intervals and +to count the number of packets received in each of those defined +intervals. +This distribution might be used to calculate the mean value +and standard deviation of the signal level. +.SS Specific notes +This driver fails to detect some +.B non-NCR/AT&T/Lucent +Wavelan cards. +If this happens for you, you must look in the source code on +how to add your card to the detection routine. +.P +Some of the mentioned features are optional. +You may enable or disable +them by changing flags in the driver header and recompile. +.\" .SH AUTHOR +.\" Bruce Janson \[em] bruce@cs.usyd.edu.au +.\" .br +.\" Jean Tourrilhes \[em] jt@hplb.hpl.hp.com +.\" .br +.\" (and others; see source code for details) +.\" +.\" SEE ALSO part +.\" +.SH SEE ALSO +.BR wavelan_cs (4), +.BR ifconfig (8), +.BR insmod (8), +.BR iwconfig (8), +.BR iwpriv (8), +.BR iwspy (8) diff --git a/man/man4/zero.4 b/man/man4/zero.4 new file mode 100644 index 0000000..15a39be --- /dev/null +++ b/man/man4/zero.4 @@ -0,0 +1 @@ +.so man4/null.4 diff --git a/man/man5/acct.5 b/man/man5/acct.5 new file mode 100644 index 0000000..7a4cb52 --- /dev/null +++ b/man/man5/acct.5 @@ -0,0 +1,161 @@ +.\" Copyright (C) 2008, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH acct 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +acct \- process accounting file +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +If the kernel is built with the process accounting option enabled +.RB ( CONFIG_BSD_PROCESS_ACCT ), +then calling +.BR acct (2) +starts process accounting, for example: +.P +.in +4n +acct("/var/log/pacct"); +.in +.P +When process accounting is enabled, the kernel writes a record +to the accounting file as each process on the system terminates. +This record contains information about the terminated process, +and is defined in +.I +as follows: +.P +.in +4n +.EX +#define ACCT_COMM 16 +\& +typedef u_int16_t comp_t; +\& +struct acct { + char ac_flag; /* Accounting flags */ + u_int16_t ac_uid; /* Accounting user ID */ + u_int16_t ac_gid; /* Accounting group ID */ + u_int16_t ac_tty; /* Controlling terminal */ + u_int32_t ac_btime; /* Process creation time + (seconds since the Epoch) */ + comp_t ac_utime; /* User CPU time */ + comp_t ac_stime; /* System CPU time */ + comp_t ac_etime; /* Elapsed time */ + comp_t ac_mem; /* Average memory usage (kB) */ + comp_t ac_io; /* Characters transferred (unused) */ + comp_t ac_rw; /* Blocks read or written (unused) */ + comp_t ac_minflt; /* Minor page faults */ + comp_t ac_majflt; /* Major page faults */ + comp_t ac_swaps; /* Number of swaps (unused) */ + u_int32_t ac_exitcode; /* Process termination status + (see wait(2)) */ + char ac_comm[ACCT_COMM+1]; + /* Command name (basename of last + executed command; null\-terminated) */ + char ac_pad[\fIX\fP]; /* padding bytes */ +}; +\& +enum { /* Bits that may be set in ac_flag field */ + AFORK = 0x01, /* Has executed fork, but no exec */ + ASU = 0x02, /* Used superuser privileges */ + ACORE = 0x08, /* Dumped core */ + AXSIG = 0x10 /* Killed by a signal */ +}; +.EE +.in +.P +The +.I comp_t +data type is a floating-point value consisting of a 3-bit, base-8 exponent, +and a 13-bit mantissa. +A value, +.IR c , +of this type can be converted to a (long) integer as follows: +.P +.nf + v = (c & 0x1fff) << (((c >> 13) & 0x7) * 3); +.fi +.P +The +.IR ac_utime , +.IR ac_stime , +and +.I ac_etime +fields measure time in "clock ticks"; divide these values by +.I sysconf(_SC_CLK_TCK) +to convert them to seconds. +.SS Version 3 accounting file format +Since Linux 2.6.8, +an optional alternative version of the accounting file can be produced +if the +.B CONFIG_BSD_PROCESS_ACCT_V3 +option is set when building the kernel. +With this option is set, +the records written to the accounting file contain additional fields, +and the width of +.I c_uid +and +.I ac_gid +fields is widened from 16 to 32 bits +(in line with the increased size of UID and GIDs in Linux 2.4 and later). +The records are defined as follows: +.P +.in +4n +.EX +struct acct_v3 { + char ac_flag; /* Flags */ + char ac_version; /* Always set to ACCT_VERSION (3) */ + u_int16_t ac_tty; /* Controlling terminal */ + u_int32_t ac_exitcode; /* Process termination status */ + u_int32_t ac_uid; /* Real user ID */ + u_int32_t ac_gid; /* Real group ID */ + u_int32_t ac_pid; /* Process ID */ + u_int32_t ac_ppid; /* Parent process ID */ + u_int32_t ac_btime; /* Process creation time */ + float ac_etime; /* Elapsed time */ + comp_t ac_utime; /* User CPU time */ + comp_t ac_stime; /* System time */ + comp_t ac_mem; /* Average memory usage (kB) */ + comp_t ac_io; /* Characters transferred (unused) */ + comp_t ac_rw; /* Blocks read or written + (unused) */ + comp_t ac_minflt; /* Minor page faults */ + comp_t ac_majflt; /* Major page faults */ + comp_t ac_swaps; /* Number of swaps (unused) */ + char ac_comm[ACCT_COMM]; /* Command name */ +}; +.EE +.in +.SH VERSIONS +Although it is present on most systems, it is not standardized, +and the details vary somewhat between systems. +.SH STANDARDS +None. +.SH HISTORY +glibc 2.6. +.P +Process accounting originated on BSD. +.SH NOTES +Records in the accounting file are ordered by termination time of +the process. +.P +Up to and including Linux 2.6.9, +a separate accounting record is written for each thread created using +the NPTL threading library; +since Linux 2.6.10, +a single accounting record is written for the entire process +on termination of the last thread in the process. +.P +The +.I /proc/sys/kernel/acct +file, described in +.BR proc (5), +defines settings that control the behavior of process accounting +when disk space runs low. +.SH SEE ALSO +.BR lastcomm (1), +.BR acct (2), +.BR accton (8), +.BR sa (8) diff --git a/man/man5/charmap.5 b/man/man5/charmap.5 new file mode 100644 index 0000000..47d038d --- /dev/null +++ b/man/man5/charmap.5 @@ -0,0 +1,105 @@ +.\" Copyright (C) 1994 Jochen Hein (Hein@Student.TU-Clausthal.de) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH charmap 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +charmap \- character set description file +.SH DESCRIPTION +A character set description (charmap) defines all available characters +and their encodings in a character set. +.BR localedef (1) +can use charmaps to create locale variants for different character sets. +.SS Syntax +The charmap file starts with a header that may consist of the +following keywords: +.TP +.RI < code_set_name > +is followed by the name of the character map. +.TP +.RI < comment_char > +is followed by a character that will be used as the comment character +for the rest of the file. +It defaults to the number sign (#). +.TP +.RI < escape_char > +is followed by a character that should be used as the escape character +for the rest of the file to mark characters that should be interpreted +in a special way. +It defaults to the backslash (\e). +.TP +.RI < mb_cur_max > +is followed by the maximum number of bytes for a character. +The default value is 1. +.TP +.RI < mb_cur_min > +is followed by the minimum number of bytes for a character. +This value must be less than or equal than +.RI < mb_cur_max >. +If not specified, it defaults to +.RI < mb_cur_max >. +.P +The character set definition section starts with the keyword +.I CHARMAP +in the first column. +.P +The following lines may have one of the two following forms to +define the character set: +.TP +.RI < character >\ byte-sequence\ comment +This form defines exactly one character and its byte sequence, +.I comment +being optional. +.TP +.RI < character >..< character >\ byte-sequence\ comment +This form defines a character range and its byte sequence, +.I comment +being optional. +.P +The character set definition section ends with the string +.IR "END CHARMAP" . +.P +The character set definition section may optionally be followed by a +section to define widths of characters. +.P +The +.I WIDTH_DEFAULT +keyword can be used to define the default width for all characters +not explicitly listed. +The default character width is 1. +.P +The width section for individual characters starts with the keyword +.I WIDTH +in the first column. +.P +The following lines may have one of the two following forms to +define the widths of the characters: +.TP +.RI < character >\ width +This form defines the width of exactly one character. +.TP +.RI < character >...< character >\ width +This form defines the width for all the characters in the range. +.P +The width definition section ends with the string +.IR "END WIDTH" . +.SH FILES +.TP +.I /usr/share/i18n/charmaps +Usual default character map path. +.SH STANDARDS +POSIX.2. +.SH EXAMPLES +The Euro sign is defined as follows in the +.I UTF\-8 +charmap: +.P +.nf + /xe2/x82/xac EURO SIGN +.fi +.SH SEE ALSO +.BR iconv (1), +.BR locale (1), +.BR localedef (1), +.BR locale (5), +.BR charsets (7) diff --git a/man/man5/core.5 b/man/man5/core.5 new file mode 100644 index 0000000..c24f6f9 --- /dev/null +++ b/man/man5/core.5 @@ -0,0 +1,684 @@ +.\" Copyright (c) 2006, 2008 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH core 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +core \- core dump file +.SH DESCRIPTION +The default action of certain signals is to cause a process to terminate +and produce a +.IR "core dump file" , +a file containing an image of the process's memory at +the time of termination. +This image can be used in a debugger (e.g., +.BR gdb (1)) +to inspect the state of the program at the time that it terminated. +A list of the signals which cause a process to dump core can be found in +.BR signal (7). +.P +A process can set its soft +.B RLIMIT_CORE +resource limit to place an upper limit on the size of the core dump file +that will be produced if it receives a "core dump" signal; see +.BR getrlimit (2) +for details. +.P +There are various circumstances in which a core dump file is +not produced: +.IP \[bu] 3 +The process does not have permission to write the core file. +(By default, the core file is called +.I core +or +.IR core.pid , +where +.I pid +is the ID of the process that dumped core, +and is created in the current working directory. +See below for details on naming.) +Writing the core file fails if the directory in which +it is to be created is not writable, +or if a file with the same name exists and +is not writable +or is not a regular file +(e.g., it is a directory or a symbolic link). +.IP \[bu] +A (writable, regular) file with the same name as would be used for the +core dump already exists, but there is more than one hard link to that +file. +.IP \[bu] +The filesystem where the core dump file would be created is full; +or has run out of inodes; or is mounted read-only; +or the user has reached their quota for the filesystem. +.IP \[bu] +The directory in which the core dump file is to be created does +not exist. +.IP \[bu] +The +.B RLIMIT_CORE +(core file size) or +.B RLIMIT_FSIZE +(file size) resource limits for the process are set to zero; see +.BR getrlimit (2) +and the documentation of the shell's +.I ulimit +command +.RI ( limit +in +.BR csh (1)). +However, +.B RLIMIT_CORE +will be ignored if the system is configured to pipe core dumps to a program. +.IP \[bu] +The binary being executed by the process does not have read +permission enabled. +(This is a security measure to +ensure that an executable whose contents are not readable +does not produce a\[em]possibly readable\[em]core dump containing +an image of the executable.) +.IP \[bu] +The process is executing a set-user-ID (set-group-ID) program +that is owned by a user (group) other than the real user (group) +ID of the process, +or the process is executing a program that has file capabilities (see +.BR capabilities (7)). +(However, see the description of the +.BR prctl (2) +.B PR_SET_DUMPABLE +operation, and the description of the +.I /proc/sys/fs/suid_dumpable +.\" FIXME . Perhaps relocate discussion of /proc/sys/fs/suid_dumpable +.\" and PR_SET_DUMPABLE to this page? +file in +.BR proc (5).) +.IP \[bu] +.I /proc/sys/kernel/core_pattern +is empty and +.I /proc/sys/kernel/core_uses_pid +contains the value 0. +(These files are described below.) +Note that if +.I /proc/sys/kernel/core_pattern +is empty and +.I /proc/sys/kernel/core_uses_pid +contains the value 1, +core dump files will have names of the form +.IR .pid , +and such files are hidden unless one uses the +.BR ls (1) +.I \-a +option. +.IP \[bu] +(Since Linux 3.7) +.\" commit 046d662f481830e652ac34cd112249adde16452a +The kernel was configured without the +.B CONFIG_COREDUMP +option. +.P +In addition, +a core dump may exclude part of the address space of the process if the +.BR madvise (2) +.B MADV_DONTDUMP +flag was employed. +.P +On systems that employ +.BR systemd (1) +as the +.I init +framework, core dumps may instead be placed in a location determined by +.BR systemd (1). +See below for further details. +.\" +.SS Naming of core dump files +By default, a core dump file is named +.IR core , +but the +.I /proc/sys/kernel/core_pattern +file (since Linux 2.6 and 2.4.21) +can be set to define a template that is used to name core dump files. +The template can contain % specifiers which are substituted +by the following values when a core file is created: +.P +.RS 4 +.PD 0 +.TP 4 +%% +A single % character. +.TP +%c +Core file size soft resource limit of crashing process (since Linux 2.6.24). +.TP +%d +.\" Added in git commit 12a2b4b2241e318b4f6df31228e4272d2c2968a1 +Dump mode\[em]same as value returned by +.BR prctl (2) +.B PR_GET_DUMPABLE +(since Linux 3.7). +.TP +%e +The process or thread's +.I comm +value, which typically is the same as the executable filename +(without path prefix, and truncated to a maximum of 15 characters), +but may have been modified to be something different; +see the discussion of +.IR /proc/ pid /comm +and +.IR /proc/ pid /task/ tid /comm +in +.BR proc (5). +.TP +%E +Pathname of executable, +with slashes (\[aq]/\[aq]) replaced by exclamation marks (\[aq]!\[aq]) +(since Linux 3.0). +.TP +%g +Numeric real GID of dumped process. +.TP +%h +Hostname (same as \fInodename\fP returned by \fBuname\fP(2)). +.TP +%i +TID of thread that triggered core dump, +as seen in the PID namespace in which the thread resides +.\" commit b03023ecbdb76c1dec86b41ed80b123c22783220 +(since Linux 3.18). +.TP +%I +TID of thread that triggered core dump, as seen in the initial PID namespace +.\" commit b03023ecbdb76c1dec86b41ed80b123c22783220 +(since Linux 3.18). +.TP +%p +PID of dumped process, +as seen in the PID namespace in which the process resides. +.TP +%P +.\" Added in git commit 65aafb1e7484b7434a0c1d4c593191ebe5776a2f +PID of dumped process, as seen in the initial PID namespace +(since Linux 3.12). +.TP +%s +Number of signal causing dump. +.TP +%t +Time of dump, expressed as seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.TP +%u +Numeric real UID of dumped process. +.PD +.RE +.P +A single % at the end of the template is dropped from the +core filename, as is the combination of a % followed by any +character other than those listed above. +All other characters in the template become a literal +part of the core filename. +The template may include \[aq]/\[aq] characters, which are interpreted +as delimiters for directory names. +The maximum size of the resulting core filename is 128 bytes (64 bytes +before Linux 2.6.19). +The default value in this file is "core". +For backward compatibility, if +.I /proc/sys/kernel/core_pattern +does not include +.I %p +and +.I /proc/sys/kernel/core_uses_pid +(see below) +is nonzero, then .PID will be appended to the core filename. +.P +Paths are interpreted according to the settings that are active for the +crashing process. +That means the crashing process's mount namespace (see +.BR mount_namespaces (7)), +its current working directory (found via +.BR getcwd (2)), +and its root directory (see +.BR chroot (2)). +.P +Since Linux 2.4, Linux has also provided +a more primitive method of controlling +the name of the core dump file. +If the +.I /proc/sys/kernel/core_uses_pid +file contains the value 0, then a core dump file is simply named +.IR core . +If this file contains a nonzero value, then the core dump file includes +the process ID in a name of the form +.IR core.PID . +.P +Since Linux 3.6, +.\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 +if +.I /proc/sys/fs/suid_dumpable +is set to 2 ("suidsafe"), the pattern must be either an absolute pathname +(starting with a leading \[aq]/\[aq] character) or a pipe, as defined below. +.SS Piping core dumps to a program +Since Linux 2.6.19, Linux supports an alternate syntax for the +.I /proc/sys/kernel/core_pattern +file. +If the first character of this file is a pipe symbol (\fB|\fP), +then the remainder of the line is interpreted as the command-line for +a user-space program (or script) that is to be executed. +.P +Since Linux 5.3.0, +.\" commit 315c69261dd3fa12dbc830d4fa00d1fad98d3b03 +the pipe template is split on spaces into an argument list +.I before +the template parameters are expanded. +In earlier kernels, the template parameters are expanded first and +the resulting string is split on spaces into an argument list. +This means that in earlier kernels executable names added by the +.I %e +and +.I %E +template parameters could get split into multiple arguments. +So the core dump handler needs to put the executable names as the last +argument and ensure it joins all parts of the executable name using spaces. +Executable names with multiple spaces in them are not correctly represented +in earlier kernels, +meaning that the core dump handler needs to use mechanisms to find +the executable name. +.P +Instead of being written to a file, the core dump is given as +standard input to the program. +Note the following points: +.IP \[bu] 3 +The program must be specified using an absolute pathname (or a +pathname relative to the root directory, \fI/\fP), +and must immediately follow the '|' character. +.IP \[bu] +The command-line arguments can include any of +the % specifiers listed above. +For example, to pass the PID of the process that is being dumped, specify +.I %p +in an argument. +.IP \[bu] +The process created to run the program runs as user and group +.IR root . +.IP \[bu] +Running as +.I root +does not confer any exceptional security bypasses. +Namely, LSMs (e.g., SELinux) are still active and may prevent the handler +from accessing details about the crashed process via +.IR /proc/ pid. +.IP \[bu] +The program pathname is interpreted with respect to the initial mount namespace +as it is always executed there. +It is not affected by the settings +(e.g., root directory, mount namespace, current working directory) +of the crashing process. +.IP \[bu] +The process runs in the initial namespaces +(PID, mount, user, and so on) +and not in the namespaces of the crashing process. +One can utilize specifiers such as +.I %P +to find the right +.IR /proc/ pid +directory and probe/enter the crashing process's namespaces if needed. +.IP \[bu] +The process starts with its current working directory +as the root directory. +If desired, it is possible change to the working directory of +the dumping process by employing the value provided by the +.I %P +specifier to change to the location of the dumping process via +.IR /proc/ pid /cwd . +.IP \[bu] +Command-line arguments can be supplied to the +program (since Linux 2.6.24), +delimited by white space (up to a total line length of 128 bytes). +.IP \[bu] +The +.B RLIMIT_CORE +limit is not enforced for core dumps that are piped to a program +via this mechanism. +.\" +.SS /proc/sys/kernel/core_pipe_limit +When collecting core dumps via a pipe to a user-space program, +it can be useful for the collecting program to gather data about +the crashing process from that process's +.IR /proc/ pid +directory. +In order to do this safely, +the kernel must wait for the program collecting the core dump to exit, +so as not to remove the crashing process's +.IR /proc/ pid +files prematurely. +This in turn creates the +possibility that a misbehaving collecting program can block +the reaping of a crashed process by simply never exiting. +.P +Since Linux 2.6.32, +.\" commit a293980c2e261bd5b0d2a77340dd04f684caff58 +the +.I /proc/sys/kernel/core_pipe_limit +can be used to defend against this possibility. +The value in this file defines how many concurrent crashing +processes may be piped to user-space programs in parallel. +If this value is exceeded, then those crashing processes above this value +are noted in the kernel log and their core dumps are skipped. +.P +A value of 0 in this file is special. +It indicates that unlimited processes may be captured in parallel, +but that no waiting will take place (i.e., the collecting +program is not guaranteed access to +.IR /proc/ ). +The default value for this file is 0. +.\" +.SS Controlling which mappings are written to the core dump +Since Linux 2.6.23, the Linux-specific +.IR /proc/ pid /coredump_filter +file can be used to control which memory segments are written to the +core dump file in the event that a core dump is performed for the +process with the corresponding process ID. +.P +The value in the file is a bit mask of memory mapping types (see +.BR mmap (2)). +If a bit is set in the mask, then memory mappings of the +corresponding type are dumped; otherwise they are not dumped. +The bits in this file have the following meanings: +.P +.PD 0 +.RS 4 +.TP +bit 0 +Dump anonymous private mappings. +.TP +bit 1 +Dump anonymous shared mappings. +.TP +bit 2 +Dump file-backed private mappings. +.TP +bit 3 +Dump file-backed shared mappings. +.\" file-backed shared mappings of course also update the underlying +.\" mapped file. +.TP +bit 4 (since Linux 2.6.24) +Dump ELF headers. +.TP +bit 5 (since Linux 2.6.28) +Dump private huge pages. +.TP +bit 6 (since Linux 2.6.28) +Dump shared huge pages. +.TP +bit 7 (since Linux 4.4) +.\" commit ab27a8d04b32b6ee8c30c14c4afd1058e8addc82 +Dump private DAX pages. +.TP +bit 8 (since Linux 4.4) +.\" commit ab27a8d04b32b6ee8c30c14c4afd1058e8addc82 +Dump shared DAX pages. +.RE +.PD +.P +By default, the following bits are set: 0, 1, 4 (if the +.B CONFIG_CORE_DUMP_DEFAULT_ELF_HEADERS +kernel configuration option is enabled), and 5. +This default can be modified at boot time using the +.I coredump_filter +boot option. +.P +The value of this file is displayed in hexadecimal. +(The default value is thus displayed as 33.) +.P +Memory-mapped I/O pages such as frame buffer are never dumped, and +virtual DSO +.RB ( vdso (7)) +pages are always dumped, regardless of the +.I coredump_filter +value. +.P +A child process created via +.BR fork (2) +inherits its parent's +.I coredump_filter +value; +the +.I coredump_filter +value is preserved across an +.BR execve (2). +.P +It can be useful to set +.I coredump_filter +in the parent shell before running a program, for example: +.P +.in +4n +.EX +.RB "$" " echo 0x7 > /proc/self/coredump_filter" +.RB "$" " ./some_program" +.EE +.in +.P +This file is provided only if the kernel was built with the +.B CONFIG_ELF_CORE +configuration option. +.\" +.SS Core dumps and systemd +On systems using the +.BR systemd (1) +.I init +framework, core dumps may be placed in a location determined by +.BR systemd (1). +To do this, +.BR systemd (1) +employs the +.I core_pattern +feature that allows piping core dumps to a program. +One can verify this by checking whether core dumps are being piped to the +.BR systemd\-coredump (8) +program: +.P +.in +4n +.EX +$ \fBcat /proc/sys/kernel/core_pattern\fP +|/usr/lib/systemd/systemd\-coredump %P %u %g %s %t %c %e +.EE +.in +.P +In this case, core dumps will be placed in the location configured for +.BR systemd\-coredump (8), +typically as +.BR lz4 (1) +compressed files in the directory +.IR /var/lib/systemd/coredump/ . +One can list the core dumps that have been recorded by +.BR systemd\-coredump (8) +using +.BR coredumpctl (1): +.P +.EX +$ \fBcoredumpctl list | tail \-5\fP +Wed 2017\-10\-11 22:25:30 CEST 2748 1000 1000 3 present /usr/bin/sleep +Thu 2017\-10\-12 06:29:10 CEST 2716 1000 1000 3 present /usr/bin/sleep +Thu 2017\-10\-12 06:30:50 CEST 2767 1000 1000 3 present /usr/bin/sleep +Thu 2017\-10\-12 06:37:40 CEST 2918 1000 1000 3 present /usr/bin/cat +Thu 2017\-10\-12 08:13:07 CEST 2955 1000 1000 3 present /usr/bin/cat +.EE +.P +The information shown for each core dump includes the date and time +of the dump, the PID, UID, and GID of the dumping process, +the signal number that caused the core dump, +and the pathname of the executable that was being run by the dumped process. +Various options to +.BR coredumpctl (1) +allow a specified coredump file to be pulled from the +.BR systemd (1) +location into a specified file. +For example, to extract the core dump for PID 2955 shown above to a file named +.I core +in the current directory, one could use: +.P +.in +4n +.EX +$ \fBcoredumpctl dump 2955 \-o core\fP +.EE +.in +.P +For more extensive details, see the +.BR coredumpctl (1) +manual page. +.P +To (persistently) disable the +.BR systemd (1) +mechanism that archives core dumps, restoring to something more like +traditional Linux behavior, one can set an override for the +.BR systemd (1) +mechanism, using something like: +.P +.in +4n +.EX +# \fBecho "kernel.core_pattern=core.%p" > \e\fP +\fB /etc/sysctl.d/50\-coredump.conf\fP +# \fB/lib/systemd/systemd\-sysctl\fP +.EE +.in +.P +It is also possible to temporarily (i.e., until the next reboot) change the +.I core_pattern +setting using a command such as the following +(which causes the names of core dump files to include the executable name +as well as the number of the signal which triggered the core dump): +.P +.in +4n +.EX +# \fBsysctl \-w kernel.core_pattern="%e\-%s.core"\fP +.EE +.in +.\" +.SH NOTES +The +.BR gdb (1) +.I gcore +command can be used to obtain a core dump of a running process. +.P +In Linux versions up to and including 2.6.27, +.\" Changed with commit 6409324b385f3f63a03645b4422e3be67348d922 +if a multithreaded process (or, more precisely, a process that +shares its memory with another process by being created with the +.B CLONE_VM +flag of +.BR clone (2)) +dumps core, then the process ID is always appended to the core filename, +unless the process ID was already included elsewhere in the +filename via a +.I %p +specification in +.IR /proc/sys/kernel/core_pattern . +(This is primarily useful when employing the obsolete +LinuxThreads implementation, +where each thread of a process has a different PID.) +.\" Always including the PID in the name of the core file made +.\" sense for LinuxThreads, where each thread had a unique PID, +.\" but doesn't seem to serve any purpose with NPTL, where all the +.\" threads in a process share the same PID (as POSIX.1 requires). +.\" Probably the behavior is maintained so that applications using +.\" LinuxThreads continue appending the PID (the kernel has no easy +.\" way of telling which threading implementation the user-space +.\" application is using). -- mtk, April 2006 +.SH EXAMPLES +The program below can be used to demonstrate the use of the +pipe syntax in the +.I /proc/sys/kernel/core_pattern +file. +The following shell session demonstrates the use of this program +(compiled to create an executable named +.IR core_pattern_pipe_test ): +.P +.in +4n +.EX +.RB "$" " cc \-o core_pattern_pipe_test core_pattern_pipe_test.c" +.RB "$" " su" +Password: +.RB "#" " echo \[dq]|$PWD/core_pattern_pipe_test %p \ +UID=%u GID=%g sig=%s\[dq] > \e" +.B " /proc/sys/kernel/core_pattern" +.RB "#" " exit" +.RB "$" " sleep 100" +.BR "\[ha]\e" " # type control\-backslash" +Quit (core dumped) +.RB "$" " cat core.info" +argc=5 +argc[0]= +argc[1]=<20575> +argc[2]= +argc[3]= +argc[4]= +Total bytes in core dump: 282624 +.EE +.in +.SS Program source +\& +.EX +/* core_pattern_pipe_test.c */ +\& +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +\& +#define BUF_SIZE 1024 +\& +int +main(int argc, char *argv[]) +{ + ssize_t nread, tot; + char buf[BUF_SIZE]; + FILE *fp; + char cwd[PATH_MAX]; +\& + /* Change our current working directory to that of the + crashing process. */ +\& + snprintf(cwd, PATH_MAX, "/proc/%s/cwd", argv[1]); + chdir(cwd); +\& + /* Write output to file "core.info" in that directory. */ +\& + fp = fopen("core.info", "w+"); + if (fp == NULL) + exit(EXIT_FAILURE); +\& + /* Display command\-line arguments given to core_pattern + pipe program. */ +\& + fprintf(fp, "argc=%d\en", argc); + for (size_t j = 0; j < argc; j++) + fprintf(fp, "argc[%zu]=<%s>\en", j, argv[j]); +\& + /* Count bytes in standard input (the core dump). */ +\& + tot = 0; + while ((nread = read(STDIN_FILENO, buf, BUF_SIZE)) > 0) + tot += nread; + fprintf(fp, "Total bytes in core dump: %zd\en", tot); +\& + fclose(fp); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR bash (1), +.BR coredumpctl (1), +.BR gdb (1), +.BR getrlimit (2), +.BR mmap (2), +.BR prctl (2), +.BR sigaction (2), +.BR elf (5), +.BR proc (5), +.BR pthreads (7), +.BR signal (7), +.BR systemd\-coredump (8) diff --git a/man/man5/dir_colors.5 b/man/man5/dir_colors.5 new file mode 100644 index 0000000..4719690 --- /dev/null +++ b/man/man5/dir_colors.5 @@ -0,0 +1,406 @@ +'\" t +.\" Copyright (c) 2001 Martin Schulze +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH dir_colors 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +dir_colors \- configuration file for dircolors(1) +.SH DESCRIPTION +The program +.BR ls (1) +uses the environment variable +.B LS_COLORS +to determine the colors in which the filenames are to be displayed. +This environment variable is usually set by a command like +.P +.RS +eval \`dircolors some_path/dir_colors\` +.RE +.P +found in a system default shell initialization file, like +.I /etc/profile +or +.IR /etc/csh.cshrc . +(See also +.BR dircolors (1).) +Usually, the file used here is +.I /etc/DIR_COLORS +and can be overridden by a +.I .dir_colors +file in one's home directory. +.P +This configuration file consists of several statements, one per line. +Anything right of a hash mark (#) is treated as a comment, if the +hash mark is at the beginning of a line or is preceded by at least one +whitespace. +Blank lines are ignored. +.P +The +.I global +section of the file consists of any statement before the first +.B TERM +statement. +Any statement in the global section of the file is +considered valid for all terminal types. +Following the global section +is one or more +.I terminal-specific +sections, preceded by one or more +.B TERM +statements which specify the terminal types (as given by the +.B TERM +environment variable) the following declarations apply to. +It is always possible to override a global declaration by a subsequent +terminal-specific one. +.P +The following statements are recognized; case is insignificant: +.TP +.B TERM \fIterminal-type\fR +Starts a terminal-specific section and specifies which terminal it +applies to. +Multiple +.B TERM +statements can be used to create a section which applies for several +terminal types. +.TP +.B COLOR yes|all|no|none|tty +(Slackware only; ignored by GNU +.BR dircolors (1).) +Specifies that colorization should always be enabled (\fIyes\fR or +\fIall\fR), never enabled (\fIno\fR or \fInone\fR), or enabled only if +the output is a terminal (\fItty\fR). +The default is \fIno\fR. +.TP +.B EIGHTBIT yes|no +(Slackware only; ignored by GNU +.BR dircolors (1).) +Specifies that eight-bit ISO/IEC\~8859 characters should be enabled by +default. +For compatibility reasons, this can also be specified as 1 for +\fIyes\fR or 0 for \fIno\fR. +The default is \fIno\fR. +.TP +.B OPTIONS \fIoptions\fR +(Slackware only; ignored by GNU +.BR dircolors (1).) +Adds command-line options to the default +.B ls +command line. +The options can be any valid +.B ls +command-line options, and should include the leading minus sign. +Note that +.B dircolors +does not verify the validity of these options. +.TP +.B NORMAL \fIcolor-sequence\fR +Specifies the color used for normal (nonfilename) text. +.IP +Synonym: +.BR NORM . +.TP +.B FILE \fIcolor-sequence\fR +Specifies the color used for a regular file. +.TP +.B DIR \fIcolor-sequence\fR +Specifies the color used for directories. +.TP +.B LINK \fIcolor-sequence\fR +Specifies the color used for a symbolic link. +.IP +Synonyms: +.BR LNK , +.BR SYMLINK . +.TP +.B ORPHAN \fIcolor-sequence\fR +Specifies the color used for an orphaned symbolic link (one which +points to a nonexistent file). +If this is unspecified, +.B ls +will use the +.B LINK +color instead. +.TP +.B MISSING \fIcolor-sequence\fR +Specifies the color used for a missing file (a nonexistent file which +nevertheless has a symbolic link pointing to it). +If this is unspecified, +.B ls +will use the +.B FILE +color instead. +.TP +.B FIFO \fIcolor-sequence\fR +Specifies the color used for a FIFO (named pipe). +.IP +Synonym: +.BR PIPE . +.TP +.B SOCK \fIcolor-sequence\fR +Specifies the color used for a socket. +.TP +.B DOOR \fIcolor-sequence\fR +(Supported since fileutils 4.1) +Specifies the color used for a door (Solaris 2.5 and later). +.TP +.B BLK \fIcolor-sequence\fR +Specifies the color used for a block device special file. +.IP +Synonym: +.BR BLOCK . +.TP +.B CHR \fIcolor-sequence\fR +Specifies the color used for a character device special file. +.IP +Synonym: +.BR CHAR . +.TP +.B EXEC \fIcolor-sequence\fR +Specifies the color used for a file with the executable attribute set. +.TP +.B SUID \fIcolor-sequence\fR +Specifies the color used for a file with the set-user-ID attribute set. +.IP +Synonym: +.BR SETUID . +.TP +.B SGID \fIcolor-sequence\fR +Specifies the color used for a file with the set-group-ID attribute set. +.IP +Synonym: +.BR SETGID . +.TP +.B STICKY \fIcolor-sequence\fR +Specifies the color used for a directory with the sticky attribute set. +.TP +.B STICKY_OTHER_WRITABLE \fIcolor-sequence\fR +Specifies the color used for +an other-writable directory with the executable attribute set. +.IP +Synonym: +.BR OWT . +.TP +.B OTHER_WRITABLE \fIcolor-sequence\fR +Specifies the color used for +an other-writable directory without the executable attribute set. +.IP +Synonym: +.BR OWR . +.TP +.B LEFTCODE \fIcolor-sequence\fR +Specifies the +.I "left code" +for non-ISO/IEC\~6429 terminals (see below). +.IP +Synonym: +.BR LEFT . +.TP +.B RIGHTCODE \fIcolor-sequence\fR +Specifies the +.I "right code" +for non-ISO/IEC\~6429 terminals (see below). +.IP +Synonym: +.BR RIGHT . +.TP +.B ENDCODE \fIcolor-sequence\fR +Specifies the +.I "end code" +for non-ISO/IEC\~6429 terminals (see below). +.IP +Synonym: +.BR END . +.TP +.BI * "extension color-sequence" +Specifies the color used for any file that ends in \fIextension\fR. +.TP +.BI . "extension color-sequence" +Same as \fB*\fR.\fIextension\fR. +Specifies the color used for any file that +ends in .\fIextension\fR. +Note that the period is included in the +extension, which makes it impossible to specify an extension not +starting with a period, such as +.B \[ti] +for +.B emacs +backup files. +This form should be considered obsolete. +.SS ISO/IEC\~6429 (ANSI) color sequences +Most color-capable ASCII terminals today use ISO/IEC\~6429 (ANSI) color sequences, +and many common terminals without color capability, including +.B xterm +and the widely used and cloned DEC VT100, will recognize ISO/IEC\~6429 color +codes and harmlessly eliminate them from the output or emulate them. +.B ls +uses ISO/IEC\~6429 codes by default, assuming colorization is enabled. +.P +ISO/IEC\~6429 color sequences are composed of sequences of numbers +separated by semicolons. +The most common codes are: +.RS +.TS +l l. + 0 to restore default color + 1 for brighter colors + 4 for underlined text + 5 for flashing text +30 for black foreground +31 for red foreground +32 for green foreground +33 for yellow (or brown) foreground +34 for blue foreground +35 for purple foreground +36 for cyan foreground +37 for white (or gray) foreground +40 for black background +41 for red background +42 for green background +43 for yellow (or brown) background +44 for blue background +45 for purple background +46 for cyan background +47 for white (or gray) background +.TE +.RE +.P +Not all commands will work on all systems or display devices. +.P +.B ls +uses the following defaults: +.TS +lb l l. +NORMAL 0 Normal (nonfilename) text +FILE 0 Regular file +DIR 32 Directory +LINK 36 Symbolic link +ORPHAN undefined Orphaned symbolic link +MISSING undefined Missing file +FIFO 31 Named pipe (FIFO) +SOCK 33 Socket +BLK 44;37 Block device +CHR 44;37 Character device +EXEC 35 Executable file +.TE +.P +A few terminal programs do not recognize the default +properly. +If all text gets colorized after you do a directory +listing, change the +.B NORMAL +and +.B FILE +codes to the numerical codes for your normal foreground and background +colors. +.SS Other terminal types (advanced configuration) +If you have a color-capable (or otherwise highlighting) terminal (or +printer!) which uses a different set of codes, you can still generate +a suitable setup. +To do so, you will have to use the +.BR LEFTCODE , +.BR RIGHTCODE , +and +.B ENDCODE +definitions. +.P +When writing out a filename, +.B ls +generates the following output sequence: +.B LEFTCODE +.I typecode +.B RIGHTCODE +.I filename +.BR ENDCODE , +where the +.I typecode +is the color sequence that depends on the type or name of file. +If the +.B ENDCODE +is undefined, the sequence +.B "LEFTCODE NORMAL RIGHTCODE" +will be used instead. +The purpose of the left- and rightcodes is +merely to reduce the amount of typing necessary (and to hide ugly +escape codes away from the user). +If they are not appropriate for +your terminal, you can eliminate them by specifying the respective +keyword on a line by itself. +.P +.B NOTE: +If the +.B ENDCODE +is defined in the global section of the setup file, it +.I cannot +be undefined in a terminal-specific section of the file. +This means any +.B NORMAL +definition will have no effect. +A different +.B ENDCODE +can, however, be specified, which would have the same effect. +.SS Escape sequences +To specify control- or blank characters in the color sequences or +filename extensions, either C-style \e-escaped notation or +.BR stty \-style +\[ha]-notation can be used. +The C-style notation +includes the following characters: +.RS +.TS +lb l. +\ea Bell (ASCII 7) +\eb Backspace (ASCII 8) +\ee Escape (ASCII 27) +\ef Form feed (ASCII 12) +\en Newline (ASCII 10) +\er Carriage Return (ASCII 13) +\et Tab (ASCII 9) +\ev Vertical Tab (ASCII 11) +\e? Delete (ASCII 127) +\e\fInnn Any character (octal notation) +\ex\fInnn Any character (hexadecimal notation) +\e_ Space +\e\e Backslash (\e) +\e\[ha] Caret (\[ha]) +\e# Hash mark (#) +.TE +.RE +.P +Note that escapes are necessary to enter a space, backslash, +caret, or any control character anywhere in the string, as well as a +hash mark as the first character. +.SH FILES +.TP +.I /etc/DIR_COLORS +System-wide configuration file. +.TP +.I \[ti]/.dir_colors +Per-user configuration file. +.P +This page describes the +.B dir_colors +file format as used in the fileutils-4.1 package; +other versions may differ slightly. +.SH NOTES +The default +.B LEFTCODE +and +.B RIGHTCODE +definitions, which are used by ISO/IEC\~6429 terminals are: +.RS +.TS +lb l. +LEFTCODE \ee[ +RIGHTCODE m +.TE +.RE +.P +The default +.B ENDCODE +is undefined. +.SH SEE ALSO +.BR dircolors (1), +.BR ls (1), +.BR stty (1), +.BR xterm (1) diff --git a/man/man5/elf.5 b/man/man5/elf.5 new file mode 100644 index 0000000..f520b1a --- /dev/null +++ b/man/man5/elf.5 @@ -0,0 +1,2213 @@ +.\" $OpenBSD: elf.5,v 1.12 2003/10/27 20:23:58 jmc Exp $ +.\"Copyright (c) 1999 Jeroen Ruigrok van der Werven +.\"All rights reserved. +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\"Redistribution and use in source and binary forms, with or without +.\"modification, are permitted provided that the following conditions +.\"are met: +.\"1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\"2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\"THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\"ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\"IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\"ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\"FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\"DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\"OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\"HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\"LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\"OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\"SUCH DAMAGE. +.\" %%%LICENSE_END +.\" +.\" $FreeBSD: src/share/man/man5/elf.5,v 1.21 2001/10/01 16:09:23 ru Exp $ +.\" +.\" Slightly adapted - aeb, 2004-01-01 +.\" 2005-07-15, Mike Frysinger , various fixes +.\" 2007-10-11, Mike Frysinger , various fixes +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH ELF 5 2024-05-08 "Linux man-pages (unreleased)" +.SH NAME +elf \- format of Executable and Linking Format (ELF) files +.SH SYNOPSIS +.nf +.\" .B #include +.B #include +.fi +.SH DESCRIPTION +The header file +.I +defines the format of ELF executable binary files. +Amongst these files are +normal executable files, relocatable object files, core files, and shared +objects. +.P +An executable file using the ELF file format consists of an ELF header, +followed by a program header table or a section header table, or both. +The ELF header is always at offset zero of the file. +The program header +table and the section header table's offset in the file are defined in the +ELF header. +The two tables describe the rest of the particularities of +the file. +.P +.\" Applications which wish to process ELF binary files for their native +.\" architecture only should include +.\" .I +.\" in their source code. +.\" These applications should need to refer to +.\" all the types and structures by their generic names +.\" "Elf_xxx" +.\" and to the macros by +.\" ELF_xxx". +.\" Applications written this way can be compiled on any architecture, +.\" regardless of whether the host is 32-bit or 64-bit. +.\" .P +.\" Should an application need to process ELF files of an unknown +.\" architecture, then the application needs to explicitly use either +.\" "Elf32_xxx" +.\" or +.\" "Elf64_xxx" +.\" type and structure names. +.\" Likewise, the macros need to be identified by +.\" "ELF32_xxx" +.\" or +.\" "ELF64_xxx". +.\" .P +This header file describes the above mentioned headers as C structures +and also includes structures for dynamic sections, relocation sections and +symbol tables. +.\" +.SS Basic types +The following types are used for N-bit architectures (N=32,64, +.I ElfN +stands for +.I Elf32 +or +.IR Elf64 , +.I uintN_t +stands for +.I uint32_t +or +.IR uint64_t ): +.P +.in +4n +.EX +ElfN_Addr Unsigned program address, uintN_t +ElfN_Off Unsigned file offset, uintN_t +ElfN_Section Unsigned section index, uint16_t +ElfN_Versym Unsigned version symbol information, uint16_t +Elf_Byte unsigned char +ElfN_Half uint16_t +ElfN_Sword int32_t +ElfN_Word uint32_t +ElfN_Sxword int64_t +ElfN_Xword uint64_t +.\" Elf32_Size Unsigned object size +.EE +.in +.P +(Note: the *BSD terminology is a bit different. +There, +.I Elf64_Half +is +twice as large as +.IR Elf32_Half , +and +.I Elf64Quarter +is used for +.IR uint16_t . +In order to avoid confusion these types are replaced by explicit ones +in the below.) +.P +All data structures that the file format defines follow the +"natural" +size and alignment guidelines for the relevant class. +If necessary, +data structures contain explicit padding to ensure 4-byte alignment +for 4-byte objects, to force structure sizes to a multiple of 4, and so on. +.\" +.SS ELF header (Ehdr) +The ELF header is described by the type +.I Elf32_Ehdr +or +.IR Elf64_Ehdr : +.P +.in +4n +.EX +#define EI_NIDENT 16 +\& +typedef struct { + unsigned char e_ident[EI_NIDENT]; + uint16_t e_type; + uint16_t e_machine; + uint32_t e_version; + ElfN_Addr e_entry; + ElfN_Off e_phoff; + ElfN_Off e_shoff; + uint32_t e_flags; + uint16_t e_ehsize; + uint16_t e_phentsize; + uint16_t e_phnum; + uint16_t e_shentsize; + uint16_t e_shnum; + uint16_t e_shstrndx; +} ElfN_Ehdr; +.EE +.in +.P +The fields have the following meanings: +.\" +.\" +.TP +.I e_ident +This array of bytes specifies how to interpret the file, +independent of the processor or the file's remaining contents. +Within this array everything is named by macros, which start with +the prefix +.B EI_ +and may contain values which start with the prefix +.BR ELF . +The following macros are defined: +.RS +.TP +.B EI_MAG0 +The first byte of the magic number. +It must be filled with +.BR ELFMAG0 . +(0: 0x7f) +.TP +.B EI_MAG1 +The second byte of the magic number. +It must be filled with +.BR ELFMAG1 . +(1: \[aq]E\[aq]) +.TP +.B EI_MAG2 +The third byte of the magic number. +It must be filled with +.BR ELFMAG2 . +(2: \[aq]L\[aq]) +.TP +.B EI_MAG3 +The fourth byte of the magic number. +It must be filled with +.BR ELFMAG3 . +(3: \[aq]F\[aq]) +.TP +.B EI_CLASS +The fifth byte identifies the architecture for this binary: +.RS +.TP 14 +.PD 0 +.B ELFCLASSNONE +This class is invalid. +.TP +.B ELFCLASS32 +This defines the 32-bit architecture. +It supports machines with files +and virtual address spaces up to 4 Gigabytes. +.TP +.B ELFCLASS64 +This defines the 64-bit architecture. +.PD +.RE +.TP +.B EI_DATA +The sixth byte specifies the data encoding of the processor-specific +data in the file. +Currently, these encodings are supported: +.RS 9 +.TP 14 +.PD 0 +.B ELFDATANONE +Unknown data format. +.TP +.B ELFDATA2LSB +Two's complement, little-endian. +.TP +.B ELFDATA2MSB +Two's complement, big-endian. +.PD +.RE +.TP +.B EI_VERSION +The seventh byte is the version number of the ELF specification: +.IP +.PD 0 +.RS +.TP 14 +.B EV_NONE +Invalid version. +.TP +.B EV_CURRENT +Current version. +.PD +.RE +.\".El +.TP +.B EI_OSABI +The eighth byte identifies the operating system +and ABI to which the object is targeted. +Some fields in other ELF structures have flags +and values that have platform-specific meanings; +the interpretation of those fields is determined by the value of this byte. +For example: +.RS +.TP 21 +.PD 0 +.B ELFOSABI_NONE +Same as ELFOSABI_SYSV +.\" 0 +.TP +.B ELFOSABI_SYSV +UNIX System V ABI +.\" 0 +.\" synonym: ELFOSABI_NONE +.TP +.B ELFOSABI_HPUX +HP-UX ABI +.\" 1 +.TP +.B ELFOSABI_NETBSD +NetBSD ABI +.\" 2 +.TP +.B ELFOSABI_LINUX +Linux ABI +.\" 3 +.\" .TP +.\" .BR ELFOSABI_HURD +.\" Hurd ABI +.\" 4 +.\" .TP +.\" .BR ELFOSABI_86OPEN +.\" 86Open Common IA32 ABI +.\" 5 +.TP +.B ELFOSABI_SOLARIS +Solaris ABI +.\" 6 +.\" .TP +.\" .BR ELFOSABI_MONTEREY +.\" Monterey project ABI +.\" Now replaced by +.\" ELFOSABI_AIX +.\" 7 +.TP +.B ELFOSABI_IRIX +IRIX ABI +.\" 8 +.TP +.B ELFOSABI_FREEBSD +FreeBSD ABI +.\" 9 +.TP +.B ELFOSABI_TRU64 +TRU64 UNIX ABI +.\" 10 +.\" ELFOSABI_MODESTO +.\" 11 +.\" ELFOSABI_OPENBSD +.\" 12 +.TP +.B ELFOSABI_ARM +ARM architecture ABI +.\" 97 +.TP +.B ELFOSABI_STANDALONE +Stand-alone (embedded) ABI +.\" 255 +.PD +.RE +.TP +.B EI_ABIVERSION +The ninth byte identifies the version of the ABI +to which the object is targeted. +This field is used to distinguish among incompatible versions of an ABI. +The interpretation of this version number +is dependent on the ABI identified by the +.B EI_OSABI +field. +Applications conforming to this specification use the value 0. +.TP +.B EI_PAD +Start of padding. +These bytes are reserved and set to zero. +Programs +which read them should ignore them. +The value for +.B EI_PAD +will change in +the future if currently unused bytes are given meanings. +.\" As reported by Yuri Kozlov and confirmed by Mike Frysinger, EI_BRAND is +.\" not in GABI (http://www.sco.com/developers/gabi/latest/ch4.eheader.html) +.\" It looks to be a BSDism +.\" .TP +.\" .BR EI_BRAND +.\" Start of architecture identification. +.TP +.B EI_NIDENT +The size of the +.I e_ident +array. +.RE +.TP +.I e_type +This member of the structure identifies the object file type: +.RS +.TP 16 +.PD 0 +.B ET_NONE +An unknown type. +.TP +.B ET_REL +A relocatable file. +.TP +.B ET_EXEC +An executable file. +.TP +.B ET_DYN +A shared object. +.TP +.B ET_CORE +A core file. +.PD +.RE +.TP +.I e_machine +This member specifies the required architecture for an individual file. +For example: +.RS +.TP 16 +.PD 0 +.B EM_NONE +An unknown machine +.\" 0 +.TP +.B EM_M32 +AT&T WE 32100 +.\" 1 +.TP +.B EM_SPARC +Sun Microsystems SPARC +.\" 2 +.TP +.B EM_386 +Intel 80386 +.\" 3 +.TP +.B EM_68K +Motorola 68000 +.\" 4 +.TP +.B EM_88K +Motorola 88000 +.\" 5 +.\" .TP +.\" .BR EM_486 +.\" Intel 80486 +.\" 6 +.TP +.B EM_860 +Intel 80860 +.\" 7 +.TP +.B EM_MIPS +MIPS RS3000 (big-endian only) +.\" 8 +.\" EM_S370 +.\" 9 +.\" .TP +.\" .BR EM_MIPS_RS4_BE +.\" MIPS RS4000 (big-endian only). Deprecated +.\" 10 +.\" EM_MIPS_RS3_LE (MIPS R3000 little-endian) +.\" 10 +.TP +.B EM_PARISC +HP/PA +.\" 15 +.TP +.B EM_SPARC32PLUS +SPARC with enhanced instruction set +.\" 18 +.TP +.B EM_PPC +PowerPC +.\" 20 +.TP +.B EM_PPC64 +PowerPC 64-bit +.\" 21 +.TP +.B EM_S390 +IBM S/390 +.\" 22 +.TP +.B EM_ARM +Advanced RISC Machines +.\" 40 +.TP +.B EM_SH +Renesas SuperH +.\" 42 +.TP +.B EM_SPARCV9 +SPARC v9 64-bit +.\" 43 +.TP +.B EM_IA_64 +Intel Itanium +.\" 50 +.TP +.B EM_X86_64 +AMD x86-64 +.\" 62 +.TP +.B EM_VAX +DEC Vax +.\" 75 +.\" EM_CRIS +.\" 76 +.\" .TP +.\" .BR EM_ALPHA +.\" Compaq [DEC] Alpha +.\" .TP +.\" .BR EM_ALPHA_EXP +.\" Compaq [DEC] Alpha with enhanced instruction set +.PD +.RE +.TP +.I e_version +This member identifies the file version: +.RS +.TP 16 +.PD 0 +.B EV_NONE +Invalid version +.TP +.B EV_CURRENT +Current version +.PD +.RE +.TP +.I e_entry +This member gives the virtual address to which the system first transfers +control, thus starting the process. +If the file has no associated entry +point, this member holds zero. +.TP +.I e_phoff +This member holds the program header table's file offset in bytes. +If +the file has no program header table, this member holds zero. +.TP +.I e_shoff +This member holds the section header table's file offset in bytes. +If the +file has no section header table, this member holds zero. +.TP +.I e_flags +This member holds processor-specific flags associated with the file. +Flag names take the form EF_`machine_flag'. +Currently, no flags have been defined. +.TP +.I e_ehsize +This member holds the ELF header's size in bytes. +.TP +.I e_phentsize +This member holds the size in bytes of one entry in the file's +program header table; all entries are the same size. +.TP +.I e_phnum +This member holds the number of entries in the program header +table. +Thus the product of +.I e_phentsize +and +.I e_phnum +gives the table's size +in bytes. +If a file has no program header, +.I e_phnum +holds the value zero. +.IP +If the number of entries in the program header table is +larger than or equal to +.\" This is a Linux extension, added in Linux 2.6.34. +.B PN_XNUM +(0xffff), this member holds +.B PN_XNUM +(0xffff) and the real number of entries in the program header table is held +in the +.I sh_info +member of the initial entry in section header table. +Otherwise, the +.I sh_info +member of the initial entry contains the value zero. +.RS +.TP +.B PN_XNUM +This is defined as 0xffff, the largest number +.I e_phnum +can have, specifying where the actual number of program headers is assigned. +.PD +.RE +.TP +.I e_shentsize +This member holds a sections header's size in bytes. +A section header is one +entry in the section header table; all entries are the same size. +.TP +.I e_shnum +This member holds the number of entries in the section header table. +Thus +the product of +.I e_shentsize +and +.I e_shnum +gives the section header table's size in bytes. +If a file has no section +header table, +.I e_shnum +holds the value of zero. +.IP +If the number of entries in the section header table is +larger than or equal to +.B SHN_LORESERVE +(0xff00), +.I e_shnum +holds the value zero and the real number of entries in the section header +table is held in the +.I sh_size +member of the initial entry in section header table. +Otherwise, the +.I sh_size +member of the initial entry in the section header table holds +the value zero. +.TP +.I e_shstrndx +This member holds the section header table index of the entry associated +with the section name string table. +If the file has no section name string +table, this member holds the value +.BR SHN_UNDEF . +.IP +If the index of section name string table section is +larger than or equal to +.B SHN_LORESERVE +(0xff00), this member holds +.B SHN_XINDEX +(0xffff) and the real index of the section name string table section +is held in the +.I sh_link +member of the initial entry in section header table. +Otherwise, the +.I sh_link +member of the initial entry in section header table contains the value zero. +.\" +.SS Program header (Phdr) +An executable or shared object file's program header table is an array of +structures, each describing a segment or other information the system needs +to prepare the program for execution. +An object file +.I segment +contains one or more +.IR sections . +Program headers are meaningful only for executable and shared object files. +A file specifies its own program header size with the ELF header's +.I e_phentsize +and +.I e_phnum +members. +The ELF program header is described by the type +.I Elf32_Phdr +or +.I Elf64_Phdr +depending on the architecture: +.P +.in +4n +.EX +typedef struct { + uint32_t p_type; + Elf32_Off p_offset; + Elf32_Addr p_vaddr; + Elf32_Addr p_paddr; + uint32_t p_filesz; + uint32_t p_memsz; + uint32_t p_flags; + uint32_t p_align; +} Elf32_Phdr; +.EE +.in +.P +.in +4n +.EX +typedef struct { + uint32_t p_type; + uint32_t p_flags; + Elf64_Off p_offset; + Elf64_Addr p_vaddr; + Elf64_Addr p_paddr; + uint64_t p_filesz; + uint64_t p_memsz; + uint64_t p_align; +} Elf64_Phdr; +.EE +.in +.P +The main difference between the 32-bit and the 64-bit program header lies +in the location of the +.I p_flags +member in the total struct. +.TP +.I p_type +This member of the structure indicates what kind of segment this array +element describes or how to interpret the array element's information. +.RS 10 +.TP +.B PT_NULL +The array element is unused and the other members' values are undefined. +This lets the program header have ignored entries. +.TP +.B PT_LOAD +The array element specifies a loadable segment, described by +.I p_filesz +and +.IR p_memsz . +The bytes from the file are mapped to the beginning of the memory +segment. +If the segment's memory size +.I p_memsz +is larger than the file size +.IR p_filesz , +the +"extra" +bytes are defined to hold the value 0 and to follow the segment's +initialized area. +The file size may not be larger than the memory size. +Loadable segment entries in the program header table appear in ascending +order, sorted on the +.I p_vaddr +member. +.TP +.B PT_DYNAMIC +The array element specifies dynamic linking information. +.TP +.B PT_INTERP +The array element specifies the location and size of a null-terminated +pathname to invoke as an interpreter. +This segment type is meaningful +only for executable files (though it may occur for shared objects). +However it may not occur more than once in a file. +If it is present, it must precede any loadable segment entry. +.TP +.B PT_NOTE +The array element specifies the location of notes (ElfN_Nhdr). +.TP +.B PT_SHLIB +This segment type is reserved but has unspecified semantics. +Programs that +contain an array element of this type do not conform to the ABI. +.TP +.B PT_PHDR +The array element, if present, +specifies the location and size of the program header table itself, +both in the file and in the memory image of the program. +This segment type may not occur more than once in a file. +Moreover, it may +occur only if the program header table is part of the memory image of the +program. +If it is present, it must precede any loadable segment entry. +.TP +.B PT_LOPROC +.TQ +.B PT_HIPROC +Values in the inclusive range +.RB [ PT_LOPROC , +.BR PT_HIPROC ] +are reserved for processor-specific semantics. +.TP +.B PT_GNU_STACK +GNU extension which is used by the Linux kernel to control the state of the +stack via the flags set in the +.I p_flags +member. +.RE +.TP +.I p_offset +This member holds the offset from the beginning of the file at which +the first byte of the segment resides. +.TP +.I p_vaddr +This member holds the virtual address at which the first byte of the +segment resides in memory. +.TP +.I p_paddr +On systems for which physical addressing is relevant, this member is +reserved for the segment's physical address. +Under +BSD +this member is +not used and must be zero. +.TP +.I p_filesz +This member holds the number of bytes in the file image of the segment. +It may be zero. +.TP +.I p_memsz +This member holds the number of bytes in the memory image of the segment. +It may be zero. +.TP +.I p_flags +This member holds a bit mask of flags relevant to the segment: +.RS +.TP +.PD 0 +.B PF_X +An executable segment. +.TP +.B PF_W +A writable segment. +.TP +.B PF_R +A readable segment. +.PD +.RE +.IP +A text segment commonly has the flags +.B PF_X +and +.BR PF_R . +A data segment commonly has +.B PF_W +and +.BR PF_R . +.TP +.I p_align +This member holds the value to which the segments are aligned in memory +and in the file. +Loadable process segments must have congruent values for +.I p_vaddr +and +.IR p_offset , +modulo the page size. +Values of zero and one mean no alignment is required. +Otherwise, +.I p_align +should be a positive, integral power of two, and +.I p_vaddr +should equal +.IR p_offset , +modulo +.IR p_align . +.\" +.SS Section header (Shdr) +A file's section header table lets one locate all the file's sections. +The +section header table is an array of +.I Elf32_Shdr +or +.I Elf64_Shdr +structures. +The +ELF header's +.I e_shoff +member gives the byte offset from the beginning of the file to the section +header table. +.I e_shnum +holds the number of entries the section header table contains. +.I e_shentsize +holds the size in bytes of each entry. +.P +A section header table index is a subscript into this array. +Some section +header table indices are reserved: +the initial entry and the indices between +.B SHN_LORESERVE +and +.BR SHN_HIRESERVE . +The initial entry is used in ELF extensions for +.IR e_phnum , +.IR e_shnum , +and +.IR e_shstrndx ; +in other cases, each field in the initial entry is set to zero. +An object file does not have sections for +these special indices: +.TP +.B SHN_UNDEF +This value marks an undefined, missing, irrelevant, +or otherwise meaningless section reference. +.TP +.B SHN_LORESERVE +This value specifies the lower bound of the range of reserved indices. +.TP +.B SHN_LOPROC +.TQ +.B SHN_HIPROC +Values greater in the inclusive range +.RB [ SHN_LOPROC , +.BR SHN_HIPROC ] +are reserved for processor-specific semantics. +.TP +.B SHN_ABS +This value specifies the absolute value for the corresponding reference. +For +example, a symbol defined relative to section number +.B SHN_ABS +has an absolute value and is not affected by relocation. +.TP +.B SHN_COMMON +Symbols defined relative to this section are common symbols, +such as FORTRAN COMMON or unallocated C external variables. +.TP +.B SHN_HIRESERVE +This value specifies the upper bound of the range of reserved indices. +The +system reserves indices between +.B SHN_LORESERVE +and +.BR SHN_HIRESERVE , +inclusive. +The section header table does not contain entries for the +reserved indices. +.P +The section header has the following structure: +.P +.in +4n +.EX +typedef struct { + uint32_t sh_name; + uint32_t sh_type; + uint32_t sh_flags; + Elf32_Addr sh_addr; + Elf32_Off sh_offset; + uint32_t sh_size; + uint32_t sh_link; + uint32_t sh_info; + uint32_t sh_addralign; + uint32_t sh_entsize; +} Elf32_Shdr; +.EE +.in +.P +.in +4n +.EX +typedef struct { + uint32_t sh_name; + uint32_t sh_type; + uint64_t sh_flags; + Elf64_Addr sh_addr; + Elf64_Off sh_offset; + uint64_t sh_size; + uint32_t sh_link; + uint32_t sh_info; + uint64_t sh_addralign; + uint64_t sh_entsize; +} Elf64_Shdr; +.EE +.in +.P +No real differences exist between the 32-bit and 64-bit section headers. +.TP +.I sh_name +This member specifies the name of the section. +Its value is an index +into the section header string table section, giving the location of +a null-terminated string. +.TP +.I sh_type +This member categorizes the section's contents and semantics. +.RS +.TP +.B SHT_NULL +This value marks the section header as inactive. +It does not +have an associated section. +Other members of the section header +have undefined values. +.TP +.B SHT_PROGBITS +This section holds information defined by the program, whose +format and meaning are determined solely by the program. +.TP +.B SHT_SYMTAB +This section holds a symbol table. +Typically, +.B SHT_SYMTAB +provides symbols for link editing, though it may also be used +for dynamic linking. +As a complete symbol table, it may contain +many symbols unnecessary for dynamic linking. +An object file can +also contain a +.B SHT_DYNSYM +section. +.TP +.B SHT_STRTAB +This section holds a string table. +An object file may have multiple +string table sections. +.TP +.B SHT_RELA +This section holds relocation entries with explicit addends, such +as type +.I Elf32_Rela +for the 32-bit class of object files. +An object may have multiple +relocation sections. +.TP +.B SHT_HASH +This section holds a symbol hash table. +An object participating in +dynamic linking must contain a symbol hash table. +An object file may +have only one hash table. +.TP +.B SHT_DYNAMIC +This section holds information for dynamic linking. +An object file may +have only one dynamic section. +.TP +.B SHT_NOTE +This section holds notes (ElfN_Nhdr). +.TP +.B SHT_NOBITS +A section of this type occupies no space in the file but otherwise +resembles +.BR SHT_PROGBITS . +Although this section contains no bytes, the +.I sh_offset +member contains the conceptual file offset. +.TP +.B SHT_REL +This section holds relocation offsets without explicit addends, such +as type +.I Elf32_Rel +for the 32-bit class of object files. +An object file may have multiple +relocation sections. +.TP +.B SHT_SHLIB +This section is reserved but has unspecified semantics. +.TP +.B SHT_DYNSYM +This section holds a minimal set of dynamic linking symbols. +An +object file can also contain a +.B SHT_SYMTAB +section. +.TP +.B SHT_LOPROC +.TQ +.B SHT_HIPROC +Values in the inclusive range +.RB [ SHT_LOPROC , +.BR SHT_HIPROC ] +are reserved for processor-specific semantics. +.TP +.B SHT_LOUSER +This value specifies the lower bound of the range of indices reserved for +application programs. +.TP +.B SHT_HIUSER +This value specifies the upper bound of the range of indices reserved for +application programs. +Section types between +.B SHT_LOUSER +and +.B SHT_HIUSER +may be used by the application, without conflicting with current or future +system-defined section types. +.RE +.TP +.I sh_flags +Sections support one-bit flags that describe miscellaneous attributes. +If a flag bit is set in +.IR sh_flags , +the attribute is +"on" +for the section. +Otherwise, the attribute is +"off" +or does not apply. +Undefined attributes are set to zero. +.RS +.TP +.B SHF_WRITE +This section contains data that should be writable during process +execution. +.TP +.B SHF_ALLOC +This section occupies memory during process execution. +Some control +sections do not reside in the memory image of an object file. +This +attribute is off for those sections. +.TP +.B SHF_EXECINSTR +This section contains executable machine instructions. +.TP +.B SHF_MASKPROC +All bits included in this mask are reserved for processor-specific +semantics. +.RE +.TP +.I sh_addr +If this section appears in the memory image of a process, this member +holds the address at which the section's first byte should reside. +Otherwise, the member contains zero. +.TP +.I sh_offset +This member's value holds the byte offset from the beginning of the file +to the first byte in the section. +One section type, +.BR SHT_NOBITS , +occupies no space in the file, and its +.I sh_offset +member locates the conceptual placement in the file. +.TP +.I sh_size +This member holds the section's size in bytes. +Unless the section type +is +.BR SHT_NOBITS , +the section occupies +.I sh_size +bytes in the file. +A section of type +.B SHT_NOBITS +may have a nonzero size, but it occupies no space in the file. +.TP +.I sh_link +This member holds a section header table index link, whose interpretation +depends on the section type. +.TP +.I sh_info +This member holds extra information, whose interpretation depends on the +section type. +.TP +.I sh_addralign +Some sections have address alignment constraints. +If a section holds a +doubleword, the system must ensure doubleword alignment for the entire +section. +That is, the value of +.I sh_addr +must be congruent to zero, modulo the value of +.IR sh_addralign . +Only zero and positive integral powers of two are allowed. +The value 0 or 1 means that the section has no alignment constraints. +.TP +.I sh_entsize +Some sections hold a table of fixed-sized entries, such as a symbol table. +For such a section, this member gives the size in bytes for each entry. +This member contains zero if the section does not hold a table of +fixed-size entries. +.P +Various sections hold program and control information: +.TP +.I .bss +This section holds uninitialized data that contributes to the program's +memory image. +By definition, the system initializes the data with zeros +when the program begins to run. +This section is of type +.BR SHT_NOBITS . +The attribute types are +.B SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.I .comment +This section holds version control information. +This section is of type +.BR SHT_PROGBITS . +No attribute types are used. +.TP +.I .ctors +This section holds initialized pointers to the C++ constructor functions. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.B SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.I .data +This section holds initialized data that contribute to the program's +memory image. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.B SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.I .data1 +This section holds initialized data that contribute to the program's +memory image. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.B SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.I .debug +This section holds information for symbolic debugging. +The contents +are unspecified. +This section is of type +.BR SHT_PROGBITS . +No attribute types are used. +.TP +.I .dtors +This section holds initialized pointers to the C++ destructor functions. +This section is of type +.BR SHT_PROGBITS . +The attribute types are +.B SHF_ALLOC +and +.BR SHF_WRITE . +.TP +.I .dynamic +This section holds dynamic linking information. +The section's attributes +will include the +.B SHF_ALLOC +bit. +Whether the +.B SHF_WRITE +bit is set is processor-specific. +This section is of type +.BR SHT_DYNAMIC . +See the attributes above. +.TP +.I .dynstr +This section holds strings needed for dynamic linking, most commonly +the strings that represent the names associated with symbol table entries. +This section is of type +.BR SHT_STRTAB . +The attribute type used is +.BR SHF_ALLOC . +.TP +.I .dynsym +This section holds the dynamic linking symbol table. +This section is of type +.BR SHT_DYNSYM . +The attribute used is +.BR SHF_ALLOC . +.TP +.I .fini +This section holds executable instructions that contribute to the process +termination code. +When a program exits normally the system arranges to +execute the code in this section. +This section is of type +.BR SHT_PROGBITS . +The attributes used are +.B SHF_ALLOC +and +.BR SHF_EXECINSTR . +.TP +.I .gnu.version +This section holds the version symbol table, an array of +.I ElfN_Half +elements. +This section is of type +.BR SHT_GNU_versym . +The attribute type used is +.BR SHF_ALLOC . +.TP +.I .gnu.version_d +This section holds the version symbol definitions, a table of +.I ElfN_Verdef +structures. +This section is of type +.BR SHT_GNU_verdef . +The attribute type used is +.BR SHF_ALLOC . +.TP +.I .gnu.version_r +This section holds the version symbol needed elements, a table of +.I ElfN_Verneed +structures. +This section is of +type +.BR SHT_GNU_versym . +The attribute type used is +.BR SHF_ALLOC . +.TP +.I .got +This section holds the global offset table. +This section is of type +.BR SHT_PROGBITS . +The attributes are processor-specific. +.TP +.I .hash +This section holds a symbol hash table. +This section is of type +.BR SHT_HASH . +The attribute used is +.BR SHF_ALLOC . +.TP +.I .init +This section holds executable instructions that contribute to the process +initialization code. +When a program starts to run the system arranges to execute +the code in this section before calling the main program entry point. +This section is of type +.BR SHT_PROGBITS . +The attributes used are +.B SHF_ALLOC +and +.BR SHF_EXECINSTR . +.TP +.I .interp +This section holds the pathname of a program interpreter. +If the file has +a loadable segment that includes the section, the section's attributes will +include the +.B SHF_ALLOC +bit. +Otherwise, that bit will be off. +This section is of type +.BR SHT_PROGBITS . +.TP +.I .line +This section holds line number information for symbolic debugging, +which describes the correspondence between the program source and +the machine code. +The contents are unspecified. +This section is of type +.BR SHT_PROGBITS . +No attribute types are used. +.TP +.I .note +This section holds various notes. +This section is of type +.BR SHT_NOTE . +No attribute types are used. +.TP +.I .note.ABI\-tag +This section is used to declare the expected run-time ABI of the ELF image. +It may include the operating system name and its run-time versions. +This section is of type +.BR SHT_NOTE . +The only attribute used is +.BR SHF_ALLOC . +.TP +.I .note.gnu.build\-id +This section is used to hold an ID that uniquely identifies +the contents of the ELF image. +Different files with the same build ID should contain the same executable +content. +See the +.B \-\-build\-id +option to the GNU linker (\fBld\fR (1)) for more details. +This section is of type +.BR SHT_NOTE . +The only attribute used is +.BR SHF_ALLOC . +.TP +.I .note.GNU\-stack +This section is used in Linux object files for declaring stack attributes. +This section is of type +.BR SHT_PROGBITS . +The only attribute used is +.BR SHF_EXECINSTR . +This indicates to the GNU linker that the object file requires an +executable stack. +.TP +.I .note.openbsd.ident +OpenBSD native executables usually contain this section +to identify themselves so the kernel can bypass any compatibility +ELF binary emulation tests when loading the file. +.TP +.I .plt +This section holds the procedure linkage table. +This section is of type +.BR SHT_PROGBITS . +The attributes are processor-specific. +.TP +.I .relNAME +This section holds relocation information as described below. +If the file +has a loadable segment that includes relocation, the section's attributes +will include the +.B SHF_ALLOC +bit. +Otherwise, the bit will be off. +By convention, +"NAME" +is supplied by the section to which the relocations apply. +Thus a relocation +section for +.B .text +normally would have the name +.BR .rel.text . +This section is of type +.BR SHT_REL . +.TP +.I .relaNAME +This section holds relocation information as described below. +If the file +has a loadable segment that includes relocation, the section's attributes +will include the +.B SHF_ALLOC +bit. +Otherwise, the bit will be off. +By convention, +"NAME" +is supplied by the section to which the relocations apply. +Thus a relocation +section for +.B .text +normally would have the name +.BR .rela.text . +This section is of type +.BR SHT_RELA . +.TP +.I .rodata +This section holds read-only data that typically contributes to a +nonwritable segment in the process image. +This section is of type +.BR SHT_PROGBITS . +The attribute used is +.BR SHF_ALLOC . +.TP +.I .rodata1 +This section holds read-only data that typically contributes to a +nonwritable segment in the process image. +This section is of type +.BR SHT_PROGBITS . +The attribute used is +.BR SHF_ALLOC . +.TP +.I .shstrtab +This section holds section names. +This section is of type +.BR SHT_STRTAB . +No attribute types are used. +.TP +.I .strtab +This section holds strings, most commonly the strings that represent the +names associated with symbol table entries. +If the file has a loadable +segment that includes the symbol string table, the section's attributes +will include the +.B SHF_ALLOC +bit. +Otherwise, the bit will be off. +This section is of type +.BR SHT_STRTAB . +.TP +.I .symtab +This section holds a symbol table. +If the file has a loadable segment +that includes the symbol table, the section's attributes will include +the +.B SHF_ALLOC +bit. +Otherwise, the bit will be off. +This section is of type +.BR SHT_SYMTAB . +.TP +.I .text +This section holds the +"text", +or executable instructions, of a program. +This section is of type +.BR SHT_PROGBITS . +The attributes used are +.B SHF_ALLOC +and +.BR SHF_EXECINSTR . +.\" +.SS String and symbol tables +String table sections hold null-terminated character sequences, commonly +called strings. +The object file uses these strings to represent symbol +and section names. +One references a string as an index into the string +table section. +The first byte, which is index zero, is defined to hold +a null byte (\[aq]\e0\[aq]). +Similarly, a string table's last byte is defined to +hold a null byte, ensuring null termination for all strings. +.P +An object file's symbol table holds information needed to locate and +relocate a program's symbolic definitions and references. +A symbol table +index is a subscript into this array. +.P +.in +4n +.EX +typedef struct { + uint32_t st_name; + Elf32_Addr st_value; + uint32_t st_size; + unsigned char st_info; + unsigned char st_other; + uint16_t st_shndx; +} Elf32_Sym; +.EE +.in +.P +.in +4n +.EX +typedef struct { + uint32_t st_name; + unsigned char st_info; + unsigned char st_other; + uint16_t st_shndx; + Elf64_Addr st_value; + uint64_t st_size; +} Elf64_Sym; +.EE +.in +.P +The 32-bit and 64-bit versions have the same members, just in a different +order. +.TP +.I st_name +This member holds an index into the object file's symbol string table, +which holds character representations of the symbol names. +If the value +is nonzero, it represents a string table index that gives the symbol +name. +Otherwise, the symbol has no name. +.TP +.I st_value +This member gives the value of the associated symbol. +.TP +.I st_size +Many symbols have associated sizes. +This member holds zero if the symbol +has no size or an unknown size. +.TP +.I st_info +This member specifies the symbol's type and binding attributes: +.RS +.TP +.B STT_NOTYPE +The symbol's type is not defined. +.TP +.B STT_OBJECT +The symbol is associated with a data object. +.TP +.B STT_FUNC +The symbol is associated with a function or other executable code. +.TP +.B STT_SECTION +The symbol is associated with a section. +Symbol table entries of +this type exist primarily for relocation and normally have +.B STB_LOCAL +bindings. +.TP +.B STT_FILE +By convention, the symbol's name gives the name of the source file +associated with the object file. +A file symbol has +.B STB_LOCAL +bindings, its section index is +.BR SHN_ABS , +and it precedes the other +.B STB_LOCAL +symbols of the file, if it is present. +.TP +.B STT_LOPROC +.TQ +.B STT_HIPROC +Values in the inclusive range +.RB [ STT_LOPROC , +.BR STT_HIPROC ] +are reserved for processor-specific semantics. +.TP +.B STB_LOCAL +Local symbols are not visible outside the object file containing their +definition. +Local symbols of the same name may exist in multiple files +without interfering with each other. +.TP +.B STB_GLOBAL +Global symbols are visible to all object files being combined. +One file's +definition of a global symbol will satisfy another file's undefined +reference to the same symbol. +.TP +.B STB_WEAK +Weak symbols resemble global symbols, but their definitions have lower +precedence. +.TP +.B STB_LOPROC +.TQ +.B STB_HIPROC +Values in the inclusive range +.RB [ STB_LOPROC , +.BR STB_HIPROC ] +are reserved for processor-specific semantics. +.RE +.IP +There are macros for packing and unpacking the binding and type fields: +.RS +.TP +.BI ELF32_ST_BIND( info ) +.TQ +.BI ELF64_ST_BIND( info ) +Extract a binding from an +.I st_info +value. +.TP +.BI ELF32_ST_TYPE( info ) +.TQ +.BI ELF64_ST_TYPE( info ) +Extract a type from an +.I st_info +value. +.TP +.BI ELF32_ST_INFO( bind ", " type ) +.TQ +.BI ELF64_ST_INFO( bind ", " type ) +Convert a binding and a type into an +.I st_info +value. +.RE +.TP +.I st_other +This member defines the symbol visibility. +.RS +.TP +.PD 0 +.B STV_DEFAULT +Default symbol visibility rules. +Global and weak symbols are available to other modules; +references in the local module can be interposed +by definitions in other modules. +.TP +.B STV_INTERNAL +Processor-specific hidden class. +.TP +.B STV_HIDDEN +Symbol is unavailable to other modules; +references in the local module always resolve to the local symbol +(i.e., the symbol can't be interposed by definitions in other modules). +.TP +.B STV_PROTECTED +Symbol is available to other modules, +but references in the local module always resolve to the local symbol. +.PD +.P +There are macros for extracting the visibility type: +.P +.BR ELF32_ST_VISIBILITY (other) +or +.BR ELF64_ST_VISIBILITY (other) +.RE +.TP +.I st_shndx +Every symbol table entry is +"defined" +in relation to some section. +This member holds the relevant section +header table index. +.\" +.SS Relocation entries (Rel & Rela) +Relocation is the process of connecting symbolic references with +symbolic definitions. +Relocatable files must have information that +describes how to modify their section contents, thus allowing executable +and shared object files to hold the right information for a process's +program image. +Relocation entries are these data. +.P +Relocation structures that do not need an addend: +.P +.in +4n +.EX +typedef struct { + Elf32_Addr r_offset; + uint32_t r_info; +} Elf32_Rel; +.EE +.in +.P +.in +4n +.EX +typedef struct { + Elf64_Addr r_offset; + uint64_t r_info; +} Elf64_Rel; +.EE +.in +.P +Relocation structures that need an addend: +.P +.in +4n +.EX +typedef struct { + Elf32_Addr r_offset; + uint32_t r_info; + int32_t r_addend; +} Elf32_Rela; +.EE +.in +.P +.in +4n +.EX +typedef struct { + Elf64_Addr r_offset; + uint64_t r_info; + int64_t r_addend; +} Elf64_Rela; +.EE +.in +.TP +.I r_offset +This member gives the location at which to apply the relocation action. +For a relocatable file, the value is the byte offset from the beginning +of the section to the storage unit affected by the relocation. +For an +executable file or shared object, the value is the virtual address of +the storage unit affected by the relocation. +.TP +.I r_info +This member gives both the symbol table index with respect to which the +relocation must be made and the type of relocation to apply. +Relocation +types are processor-specific. +When the text refers to a relocation +entry's relocation type or symbol table index, it means the result of +applying +.B ELF[32|64]_R_TYPE +or +.BR ELF[32|64]_R_SYM , +respectively, to the entry's +.I r_info +member. +.TP +.I r_addend +This member specifies a constant addend used to compute the value to be +stored into the relocatable field. +.\" +.SS Dynamic tags (Dyn) +The +.I .dynamic +section contains a series of structures that hold relevant +dynamic linking information. +The +.I d_tag +member controls the interpretation +of +.IR d_un . +.P +.in +4n +.EX +typedef struct { + Elf32_Sword d_tag; + union { + Elf32_Word d_val; + Elf32_Addr d_ptr; + } d_un; +} Elf32_Dyn; +extern Elf32_Dyn _DYNAMIC[]; +.EE +.in +.P +.in +4n +.EX +typedef struct { + Elf64_Sxword d_tag; + union { + Elf64_Xword d_val; + Elf64_Addr d_ptr; + } d_un; +} Elf64_Dyn; +extern Elf64_Dyn _DYNAMIC[]; +.EE +.in +.TP +.I d_tag +This member may have any of the following values: +.RS +.TP 12 +.B DT_NULL +Marks end of dynamic section +.TP +.B DT_NEEDED +String table offset to name of a needed library +.TP +.B DT_PLTRELSZ +Size in bytes of PLT relocation entries +.TP +.B DT_PLTGOT +Address of PLT and/or GOT +.TP +.B DT_HASH +Address of symbol hash table +.TP +.B DT_STRTAB +Address of string table +.TP +.B DT_SYMTAB +Address of symbol table +.TP +.B DT_RELA +Address of Rela relocation table +.TP +.B DT_RELASZ +Size in bytes of the Rela relocation table +.TP +.B DT_RELAENT +Size in bytes of a Rela relocation table entry +.TP +.B DT_STRSZ +Size in bytes of string table +.TP +.B DT_SYMENT +Size in bytes of a symbol table entry +.TP +.B DT_INIT +Address of the initialization function +.TP +.B DT_FINI +Address of the termination function +.TP +.B DT_SONAME +String table offset to name of shared object +.TP +.B DT_RPATH +String table offset to search path for direct and indirect library dependencies +.TP +.B DT_SYMBOLIC +Alert linker to search this shared object before the executable for symbols +.TP +.B DT_REL +Address of Rel relocation table +.TP +.B DT_RELSZ +Size in bytes of Rel relocation table +.TP +.B DT_RELENT +Size in bytes of a Rel table entry +.TP +.B DT_PLTREL +Type of relocation entry to which the PLT refers (Rela or Rel) +.TP +.B DT_DEBUG +Undefined use for debugging +.TP +.B DT_TEXTREL +Absence of this entry indicates that no relocation entries should +apply to a nonwritable segment +.TP +.B DT_JMPREL +Address of relocation entries associated solely with the PLT +.TP +.B DT_BIND_NOW +Instruct dynamic linker to process all relocations before +transferring control to the executable +.TP +.B DT_RUNPATH +String table offset to search path for direct library dependencies +.TP +.B DT_LOPROC +.TQ +.B DT_HIPROC +Values in the inclusive range +.RB [ DT_LOPROC , +.BR DT_HIPROC ] +are reserved for processor-specific semantics +.RE +.TP +.I d_val +This member represents integer values with various interpretations. +.TP +.I d_ptr +This member represents program virtual addresses. +When interpreting +these addresses, the actual address should be computed based on the +original file value and memory base address. +Files do not contain +relocation entries to fixup these addresses. +.TP +.I _DYNAMIC +Array containing all the dynamic structures in the +.I .dynamic +section. +This is automatically populated by the linker. +.\" GABI ELF Reference for Note Sections: +.\" http://www.sco.com/developers/gabi/latest/ch5.pheader.html#note_section +.\" +.\" Note that it implies the sizes and alignments of notes depend on the ELF +.\" size (e.g. 32-bit ELFs have three 4-byte words and use 4-byte alignment +.\" while 64-bit ELFs use 8-byte words & alignment), but that is not the case +.\" in the real world. Notes always have three 4-byte words as can be seen +.\" in the source links below (remember that Elf64_Word is a 32-bit quantity). +.\" glibc: https://sourceware.org/git/?p=glibc.git;a=blob;f=elf/elf.h;h=9e59b3275917549af0cebe1f2de9ded3b7b10bf2#l1173 +.\" binutils: https://sourceware.org/git/?p=binutils-gdb.git;a=blob;f=binutils/readelf.c;h=274ddd17266aef6e4ad1f67af8a13a21500ff2af#l15943 +.\" Linux: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/elf.h?h=v4.8#n422 +.\" Solaris: https://docs.oracle.com/cd/E23824_01/html/819-0690/chapter6-18048.html +.\" FreeBSD: https://svnweb.freebsd.org/base/head/sys/sys/elf_common.h?revision=303677&view=markup#l33 +.\" NetBSD: https://www.netbsd.org/docs/kernel/elf-notes.html +.\" OpenBSD: https://github.com/openbsd/src/blob/master/sys/sys/exec_elf.h#L533 +.\" +.SS Notes (Nhdr) +ELF notes allow for appending arbitrary information for the system to use. +They are largely used by core files +.RI ( e_type +of +.BR ET_CORE ), +but many projects define their own set of extensions. +For example, +the GNU tool chain uses ELF notes to pass information from +the linker to the C library. +.P +Note sections contain a series of notes (see the +.I struct +definitions below). +Each note is followed by the name field (whose length is defined in +\fIn_namesz\fR) and then by the descriptor field (whose length is defined in +\fIn_descsz\fR) and whose starting address has a 4 byte alignment. +Neither field is defined in the note struct due to their arbitrary lengths. +.P +An example for parsing out two consecutive notes should clarify their layout +in memory: +.P +.in +4n +.EX +void *memory, *name, *desc; +Elf64_Nhdr *note, *next_note; +\& +/* The buffer is pointing to the start of the section/segment. */ +note = memory; +\& +/* If the name is defined, it follows the note. */ +name = note\->n_namesz == 0 ? NULL : memory + sizeof(*note); +\& +/* If the descriptor is defined, it follows the name + (with alignment). */ +\& +desc = note\->n_descsz == 0 ? NULL : + memory + sizeof(*note) + ALIGN_UP(note\->n_namesz, 4); +\& +/* The next note follows both (with alignment). */ +next_note = memory + sizeof(*note) + + ALIGN_UP(note\->n_namesz, 4) + + ALIGN_UP(note\->n_descsz, 4); +.EE +.in +.P +Keep in mind that the interpretation of +.I n_type +depends on the namespace defined by the +.I n_namesz +field. +If the +.I n_namesz +field is not set (e.g., is 0), then there are two sets of notes: +one for core files and one for all other ELF types. +If the namespace is unknown, then tools will usually fallback to these sets +of notes as well. +.P +.in +4n +.EX +typedef struct { + Elf32_Word n_namesz; + Elf32_Word n_descsz; + Elf32_Word n_type; +} Elf32_Nhdr; +.EE +.in +.P +.in +4n +.EX +typedef struct { + Elf64_Word n_namesz; + Elf64_Word n_descsz; + Elf64_Word n_type; +} Elf64_Nhdr; +.EE +.in +.TP +.I n_namesz +The length of the name field in bytes. +The contents will immediately follow this note in memory. +The name is null terminated. +For example, if the name is "GNU", then +.I n_namesz +will be set to 4. +.TP +.I n_descsz +The length of the descriptor field in bytes. +The contents will immediately follow the name field in memory. +.TP +.I n_type +Depending on the value of the name field, this member may have any of the +following values: +.RS +.TP 5 +.B Core files (e_type = ET_CORE) +Notes used by all core files. +These are highly operating system or architecture specific and often require +close coordination with kernels, C libraries, and debuggers. +These are used when the namespace is the default (i.e., +.I n_namesz +will be set to 0), or a fallback when the namespace is unknown. +.RS +.TP 21 +.PD 0 +.B NT_PRSTATUS +prstatus struct +.TP +.B NT_FPREGSET +fpregset struct +.TP +.B NT_PRPSINFO +prpsinfo struct +.TP +.B NT_PRXREG +prxregset struct +.TP +.B NT_TASKSTRUCT +task structure +.TP +.B NT_PLATFORM +String from sysinfo(SI_PLATFORM) +.TP +.B NT_AUXV +auxv array +.TP +.B NT_GWINDOWS +gwindows struct +.TP +.B NT_ASRS +asrset struct +.TP +.B NT_PSTATUS +pstatus struct +.TP +.B NT_PSINFO +psinfo struct +.TP +.B NT_PRCRED +prcred struct +.TP +.B NT_UTSNAME +utsname struct +.TP +.B NT_LWPSTATUS +lwpstatus struct +.TP +.B NT_LWPSINFO +lwpinfo struct +.TP +.B NT_PRFPXREG +fprxregset struct +.TP +.B NT_SIGINFO +siginfo_t (size might increase over time) +.TP +.B NT_FILE +Contains information about mapped files +.TP +.B NT_PRXFPREG +user_fxsr_struct +.TP +.B NT_PPC_VMX +PowerPC Altivec/VMX registers +.TP +.B NT_PPC_SPE +PowerPC SPE/EVR registers +.TP +.B NT_PPC_VSX +PowerPC VSX registers +.TP +.B NT_386_TLS +i386 TLS slots (struct user_desc) +.TP +.B NT_386_IOPERM +x86 io permission bitmap (1=deny) +.TP +.B NT_X86_XSTATE +x86 extended state using xsave +.TP +.B NT_S390_HIGH_GPRS +s390 upper register halves +.TP +.B NT_S390_TIMER +s390 timer register +.TP +.B NT_S390_TODCMP +s390 time-of-day (TOD) clock comparator register +.TP +.B NT_S390_TODPREG +s390 time-of-day (TOD) programmable register +.TP +.B NT_S390_CTRS +s390 control registers +.TP +.B NT_S390_PREFIX +s390 prefix register +.TP +.B NT_S390_LAST_BREAK +s390 breaking event address +.TP +.B NT_S390_SYSTEM_CALL +s390 system call restart data +.TP +.B NT_S390_TDB +s390 transaction diagnostic block +.TP +.B NT_ARM_VFP +ARM VFP/NEON registers +.TP +.B NT_ARM_TLS +ARM TLS register +.TP +.B NT_ARM_HW_BREAK +ARM hardware breakpoint registers +.TP +.B NT_ARM_HW_WATCH +ARM hardware watchpoint registers +.TP +.B NT_ARM_SYSTEM_CALL +ARM system call number +.PD +.RE +.TP +.B n_name = GNU +Extensions used by the GNU tool chain. +.RS +.TP +.B NT_GNU_ABI_TAG +Operating system (OS) ABI information. +The desc field will be 4 words: +.IP +.PD 0 +.RS +.IP [0] 5 +OS descriptor +(\fBELF_NOTE_OS_LINUX\fR, \fBELF_NOTE_OS_GNU\fR, and so on)` +.IP [1] +major version of the ABI +.IP [2] +minor version of the ABI +.IP [3] +subminor version of the ABI +.RE +.PD +.TP +.B NT_GNU_HWCAP +Synthetic hwcap information. +The desc field begins with two words: +.IP +.PD 0 +.RS +.IP [0] 5 +number of entries +.IP [1] +bit mask of enabled entries +.RE +.PD +.IP +Then follow variable-length entries, one byte followed by a null-terminated +hwcap name string. +The byte gives the bit number to test if enabled, (1U << bit) & bit mask. +.TP +.B NT_GNU_BUILD_ID +Unique build ID as generated by the GNU +.BR ld (1) +.B \-\-build\-id +option. +The desc consists of any nonzero number of bytes. +.TP +.B NT_GNU_GOLD_VERSION +The desc contains the GNU Gold linker version used. +.RE +.TP +.B Default/unknown namespace (e_type != ET_CORE) +These are used when the namespace is the default (i.e., +.I n_namesz +will be set to 0), or a fallback when the namespace is unknown. +.RS +.TP 12 +.PD 0 +.B NT_VERSION +A version string of some sort. +.TP +.B NT_ARCH +Architecture information. +.PD +.RE +.RE +.SH NOTES +.\" OpenBSD +.\" ELF support first appeared in +.\" OpenBSD 1.2, +.\" although not all supported platforms use it as the native +.\" binary file format. +ELF first appeared in +System V. +The ELF format is an adopted standard. +.P +The extensions for +.IR e_phnum , +.IR e_shnum , +and +.I e_shstrndx +respectively are +Linux extensions. +Sun, BSD, and AMD64 also support them; for further information, +look under SEE ALSO. +.\" .SH AUTHORS +.\" The original version of this manual page was written by +.\" .An Jeroen Ruigrok van der Werven +.\" .Aq asmodai@FreeBSD.org +.\" with inspiration from BSDi's +.\" .Bsx +.\" .Nm elf +.\" man page. +.SH SEE ALSO +.BR as (1), +.BR elfedit (1), +.BR gdb (1), +.BR ld (1), +.BR nm (1), +.BR objcopy (1), +.BR objdump (1), +.BR patchelf (1), +.BR readelf (1), +.BR size (1), +.BR strings (1), +.BR strip (1), +.BR execve (2), +.BR dl_iterate_phdr (3), +.BR core (5), +.BR ld.so (8) +.P +Hewlett-Packard, +.IR "Elf-64 Object File Format" . +.P +Santa Cruz Operation, +.IR "System V Application Binary Interface" . +.P +UNIX System Laboratories, +"Object Files", +.IR "Executable and Linking Format (ELF)" . +.P +Sun Microsystems, +.IR "Linker and Libraries Guide" . +.P +AMD64 ABI Draft, +.IR "System V Application Binary Interface AMD64 Architecture Processor Supplement" . diff --git a/man/man5/erofs.5 b/man/man5/erofs.5 new file mode 100644 index 0000000..1211333 --- /dev/null +++ b/man/man5/erofs.5 @@ -0,0 +1,97 @@ +.\" Copyright (c) 2016 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH erofs 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +erofs \- the Enhanced Read-Only File System +.SH DESCRIPTION +.B erofs +is a create-once read-only filesystem, +with support for compression and a multi-device backing store. +.P +There are two inode formats: +.IP \[bu] 3 +32-byte compact with 16-bit UID/GID, +32-bit file size, +and no file times +.PD 0 +.IP \[bu] +64-byte extended with 32-bit UID/GID, +64-bit file size, +and a modification time +.RI ( st_mtim ). +.PD +.\" See fs/erofs/super.c:shmem_parse_options for options it supports. +.SS Mount options +.TP +.B user_xattr +.TQ +.B nouser_xattr +Controls whether +.I user +extended attributes are exposed. +Defaults to yes. +.TP +.B acl +.TQ +.B noacl +Controls whether POSIX +.BR acl (5)s +are exposed. +Defaults to yes. +.TP +.BR cache_strategy = disabled | readahead | readaround +Cache allocation for compressed files: +never, if reading from start of file, regardless of position. +Defaults to +.BR readaround . +.TP +.B dax +.TQ +.BR dax = always | never +Direct Access control. +If +.B always +and the source device supports DAX, uncompressed non-inlined files +will be read directly, without going through the page cache. +.B dax +is a synonym for +.BR always . +Defaults to unset, which is equivalent to +.BR never . +.TP +.BR device = \fIblobdev\fP +Add extra device holding some of the data. +Must be given as many times and in the same order as +.B \-\-blobdev +was to +.BR mkfs.erofs (1). +.\" Nominally there's a device_table feature and it somehow scans(?) for them, +.\" cf. super.c:erofs_scan_devices(), but I haven't gotten it to work +.TP +.BR domain_id = \fIdid\fP +.TQ +.BR fsid = \fIid\fP +Control CacheFiles on-demand read support. +To be documented. +.SH VERSIONS +.B erofs +images are versioned through the use of feature flags; +these are listed in the +.B \-E +section of +.BR mkfs.erofs (1), +.SH CONFIGURATION +Linux must be configured with the +.B CONFIG_EROFS_FS +option to mount EROFS filesystems. +There are sub-configuration items that restrict the availability +of some of the parameters above. +.SH SEE ALSO +.BR mkfs.erofs (1), +.BR fsck.erofs (1), +.BR dump.erofs (1) +.P +.I Documentation/filesystems/erofs.txt +in the Linux source. diff --git a/man/man5/filesystems.5 b/man/man5/filesystems.5 new file mode 100644 index 0000000..42b17ae --- /dev/null +++ b/man/man5/filesystems.5 @@ -0,0 +1,227 @@ +.\" Copyright 1996 Daniel Quinlan (Daniel.Quinlan@linux.org) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2007-12-14 mtk Added Reiserfs, XFS, JFS. +.\" +.TH filesystems 5 2024-05-02 "Linux man-pages (unreleased)" +.nh +.SH NAME +filesystems \- Linux filesystem types: ext, ext2, ext3, ext4, hpfs, iso9660, +JFS, minix, msdos, ncpfs nfs, ntfs, proc, Reiserfs, smb, sysv, umsdos, vfat, +XFS, xiafs +.SH DESCRIPTION +When, as is customary, the +.B proc +filesystem is mounted on +.IR /proc , +you can find in the file +.I /proc/filesystems +which filesystems your kernel currently supports; +see +.BR proc (5) +for more details. +There is also a legacy +.BR sysfs (2) +system call (whose availability is controlled by the +.\" commit: 6af9f7bf3c399e0ab1eee048e13572c6d4e15fe9 +.B CONFIG_SYSFS_SYSCALL +kernel build configuration option since Linux 3.15) +that enables enumeration of the currently available filesystem types +regardless of +.I /proc +availability and/or sanity. +.P +If you need a currently unsupported filesystem, insert the corresponding +kernel module or recompile the kernel. +.P +In order to use a filesystem, you have to +.I mount +it; see +.BR mount (2) +and +.BR mount (8). +.P +The following list provides a +short description of the available or historically available +filesystems in the Linux kernel. +See the kernel documentation for a comprehensive +description of all options and limitations. +.TP +.B erofs +is the Enhanced Read-Only File System, stable since Linux 5.4. +.\" commit 47e4937a4a7ca4184fd282791dfee76c6799966a moves it out of staging +See +.BR erofs (5). +.TP +.B ext +is an elaborate extension of the +.B minix +filesystem. +It has been completely superseded by the second version +of the extended filesystem +.RB ( ext2 ) +and has been removed from the kernel (in Linux 2.1.21). +.TP +.B ext2 +is a disk filesystem that was used by Linux for fixed disks +as well as removable media. +The second extended filesystem was designed as an extension of the +extended filesystem +.RB ( ext ). +See +.BR ext2 (5). +.TP +.B ext3 +is a journaling version of the +.B ext2 +filesystem. +It is easy to +switch back and forth between +.B ext2 +and +.BR ext3 . +See +.BR ext3 (5). +.TP +.B ext4 +is a set of upgrades to +.B ext3 +including substantial performance and +reliability enhancements, +plus large increases in volume, file, and directory size limits. +See +.BR ext4 (5). +.TP +.B hpfs +is the High Performance Filesystem, used in OS/2. +This filesystem is +read-only under Linux due to the lack of available documentation. +.TP +.B iso9660 +is a CD-ROM filesystem type conforming to the ISO/IEC\~9660 standard. +.RS +.TP +.B "High Sierra" +Linux supports High Sierra, the precursor to the ISO/IEC\~9660 standard for +CD-ROM filesystems. +It is automatically recognized within the +.B iso9660 +filesystem support under Linux. +.TP +.B "Rock Ridge" +Linux also supports the System Use Sharing Protocol records specified +by the Rock Ridge Interchange Protocol. +They are used to further describe the files in the +.B iso9660 +filesystem to a UNIX host, and provide information such as long +filenames, UID/GID, POSIX permissions, and devices. +It is automatically recognized within the +.B iso9660 +filesystem support under Linux. +.RE +.TP +.B JFS +is a journaling filesystem, developed by IBM, +that was integrated into Linux 2.4.24. +.TP +.B minix +is the filesystem used in the Minix operating system, the first to run +under Linux. +It has a number of shortcomings, including a 64\ MB partition size +limit, short filenames, and a single timestamp. +It remains useful for floppies and RAM disks. +.TP +.B msdos +is the filesystem used by DOS, Windows, and some OS/2 computers. +.B msdos +filenames can be no longer than 8 characters, followed by an +optional period and 3 character extension. +.TP +.B ncpfs +is a network filesystem that supports the NCP protocol, +used by Novell NetWare. +It was removed from the kernel in Linux 4.17. +.IP +To use +.BR ncpfs , +you need special programs, which can be found at +.UR ftp://ftp.gwdg.de\:/pub\:/linux\:/misc\:/ncpfs +.UE . +.TP +.B nfs +is the network filesystem used to access disks located on remote computers. +.TP +.B ntfs +is the filesystem native to Microsoft Windows NT, +supporting features like ACLs, journaling, encryption, and so on. +.TP +.B proc +is a pseudo filesystem which is used as an interface to kernel data +structures rather than reading and interpreting +.IR /dev/kmem . +In particular, its files do not take disk space. +See +.BR proc (5). +.TP +.B Reiserfs +is a journaling filesystem, designed by Hans Reiser, +that was integrated into Linux 2.4.1. +.TP +.B smb +is a network filesystem that supports the SMB protocol, used by +Windows. +See +.UR https://www.samba.org\:/samba\:/smbfs/ +.UE . +.TP +.B sysv +is an implementation of the System V/Coherent filesystem for Linux. +It implements all of Xenix FS, System V/386 FS, and Coherent FS. +.TP +.B umsdos +is an extended DOS filesystem used by Linux. +It adds capability for +long filenames, UID/GID, POSIX permissions, and special files +(devices, named pipes, etc.) under the DOS filesystem, without +sacrificing compatibility with DOS. +.TP +.B tmpfs +is a filesystem whose contents reside in virtual memory. +Since the files on such filesystems typically reside in RAM, +file access is extremely fast. +See +.BR tmpfs (5). +.TP +.B vfat +is an extended FAT filesystem used by Microsoft Windows95 and Windows NT. +.B vfat +adds the capability to use long filenames under the MSDOS filesystem. +.TP +.B XFS +is a journaling filesystem, developed by SGI, +that was integrated into Linux 2.4.20. +.TP +.B xiafs +was designed and implemented to be a stable, safe filesystem by +extending the Minix filesystem code. +It provides the basic most +requested features without undue complexity. +The +.B xiafs +filesystem is no longer actively developed or maintained. +It was removed from the kernel in Linux 2.1.21. +.SH SEE ALSO +.BR fuse (4), +.BR btrfs (5), +.BR ext2 (5), +.BR ext3 (5), +.BR ext4 (5), +.BR nfs (5), +.BR proc (5), +.BR sysfs (5), +.BR tmpfs (5), +.BR xfs (5), +.BR fsck (8), +.BR mkfs (8), +.BR mount (8) diff --git a/man/man5/fs.5 b/man/man5/fs.5 new file mode 100644 index 0000000..3ec300c --- /dev/null +++ b/man/man5/fs.5 @@ -0,0 +1 @@ +.so man5/filesystems.5 diff --git a/man/man5/ftpusers.5 b/man/man5/ftpusers.5 new file mode 100644 index 0000000..38d57b0 --- /dev/null +++ b/man/man5/ftpusers.5 @@ -0,0 +1,42 @@ +.\" Copyright (c) 2000 Christoph J. Thompson +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ftpusers 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ftpusers \- list of users that may not log in via the FTP daemon +.SH DESCRIPTION +The text file +.B ftpusers +contains a list of users that may not log in using the +File Transfer Protocol (FTP) server daemon. +This file is used not merely for +system administration purposes but also for improving security within a TCP/IP +networked environment. +.P +The +.B ftpusers +file will typically contain a list of the users that +either have no business using ftp or have too many privileges to be allowed +to log in through the FTP server daemon. +Such users usually include root, daemon, bin, uucp, and news. +.P +If your FTP server daemon doesn't use +.BR ftpusers , +then it is suggested that you read its documentation to find out how to +block access for certain users. +Washington University FTP server Daemon +(wuftpd) and Professional FTP Daemon (proftpd) are known to make use of +.BR ftpusers . +.SS Format +The format of +.B ftpusers +is very simple. +There is one account name (or username) per line. +Lines starting with a # are ignored. +.SH FILES +.I /etc/ftpusers +.SH SEE ALSO +.BR passwd (5), +.BR proftpd (8), +.BR wuftpd (8) diff --git a/man/man5/gai.conf.5 b/man/man5/gai.conf.5 new file mode 100644 index 0000000..a69e845 --- /dev/null +++ b/man/man5/gai.conf.5 @@ -0,0 +1,89 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All rights reserved. +.\" Author: Ulrich Drepper +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.TH gai.conf 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +gai.conf \- getaddrinfo(3) configuration file +.SH DESCRIPTION +A call to +.BR getaddrinfo (3) +might return multiple answers. +According to RFC\ 3484 these answers must be sorted so that +the answer with the highest success rate is first in the list. +The RFC provides an algorithm for the sorting. +The static rules are not always adequate, though. +For this reason, +the RFC also requires that system administrators should have the possibility +to dynamically change the sorting. +For the glibc implementation, this can be achieved with the +.I /etc/gai.conf +file. +.P +Each line in the configuration file consists of a keyword and its parameters. +White spaces in any place are ignored. +Lines starting with \[aq]#\[aq] are comments and are ignored. +.P +The keywords currently recognized are: +.TP +\fBlabel\fR \fInetmask\fR \fIprecedence\fR +The value is added to the label table used in the RFC\ 3484 sorting. +If any \fBlabel\fR definition is present in the configuration file, +the default table is not used. +All the label definitions +of the default table which are to be maintained have to be duplicated. +Following the keyword, +the line has to contain a network mask and a precedence value. +.TP +\fBprecedence\fR \fInetmask\fR \fIprecedence\fR +This keyword is similar to \fBlabel\fR, but instead the value is added +to the precedence table as specified in RFC\ 3484. +Once again, the +presence of a single \fBprecedence\fR line in the configuration file +causes the default table to not be used. +.TP +\fBreload\fR <\fByes\fR|\fBno\fR> +This keyword controls whether a process checks whether the configuration +file has been changed since the last time it was read. +If the value is +"\fByes\fR", the file is reread. +This might cause problems in multithreaded +applications and is generally a bad idea. +The default is "\fBno\fR". +.TP +\fBscopev4\fR \fImask\fR \fIvalue\fR +Add another rule to the RFC\ 3484 scope table for IPv4 address. +By default, the scope IDs described in section 3.2 in RFC\ 3438 are used. +Changing these defaults should hardly ever be necessary. +.SH FILES +\fI/etc/gai.conf\fR +.SH VERSIONS +The +.I gai.conf +.\" Added in 2006 +file is supported since glibc 2.5. +.SH EXAMPLES +The default table according to RFC\ 3484 would be specified with the +following configuration file: +.P +.in +4n +.EX +label ::1/128 0 +label ::/0 1 +label 2002::/16 2 +label ::/96 3 +label ::ffff:0:0/96 4 +precedence ::1/128 50 +precedence ::/0 40 +precedence 2002::/16 30 +precedence ::/96 20 +precedence ::ffff:0:0/96 10 +.EE +.in +.\" .SH AUTHOR +.\" Ulrich Drepper +.\" +.SH SEE ALSO +.BR getaddrinfo (3), +RFC\ 3484 diff --git a/man/man5/group.5 b/man/man5/group.5 new file mode 100644 index 0000000..fdf79e0 --- /dev/null +++ b/man/man5/group.5 @@ -0,0 +1,55 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:06:03 1993 by Rik Faith (faith@cs.unc.edu) +.TH group 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +group \- user group file +.SH DESCRIPTION +The +.I /etc/group +file is a text file that defines the groups on the system. +There is one entry per line, with the following format: +.P +.in +4n +.EX +group_name:password:GID:user_list +.EE +.in +.P +The fields are as follows: +.TP +.I group_name +the name of the group. +.TP +.I password +the (encrypted) group password. +If this field is empty, no password is needed. +.TP +.I GID +the numeric group ID. +.TP +.I user_list +a list of the usernames that are members of this group, separated by commas. +.SH FILES +.I /etc/group +.SH BUGS +As the 4.2BSD +.BR initgroups (3) +man page says: no one seems to keep +.I /etc/group +up-to-date. +.SH SEE ALSO +.BR chgrp (1), +.BR gpasswd (1), +.BR groups (1), +.BR login (1), +.BR newgrp (1), +.BR sg (1), +.BR getgrent (3), +.BR getgrnam (3), +.BR gshadow (5), +.BR passwd (5), +.BR vigr (8) diff --git a/man/man5/host.conf.5 b/man/man5/host.conf.5 new file mode 100644 index 0000000..822ad49 --- /dev/null +++ b/man/man5/host.conf.5 @@ -0,0 +1,204 @@ +.\" Copyright (c) 1997 Martin Schulze (joey@infodrom.north.de) +.\" Much of the text is copied from the manpage of resolv+(8). +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2003-08-23 Martin Schulze Updated according to glibc 2.3.2 +.TH host.conf 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +host.conf \- resolver configuration file +.SH DESCRIPTION +The file +.I /etc/host.conf +contains configuration information specific to the resolver library. +It should contain one configuration keyword per line, followed by +appropriate configuration information. +The following keywords are recognized: +.TP +.I trim +This keyword may be listed more than once. +Each time it should be +followed by a list of domains, separated by colons (\[aq]:\[aq]), semicolons +(\[aq];\[aq]) or commas (\[aq],\[aq]), with the leading dot. +When set, the +resolver library will automatically trim the given domain name from the +end of any hostname resolved via DNS. +This is intended for use with +local hosts and domains. +(Related note: +.I trim +will not affect hostnames gathered via NIS or the +.BR hosts (5) +file. +Care should be taken to +ensure that the first hostname for each entry in the hosts file is +fully qualified or unqualified, as appropriate for the local +installation.) +.TP +.I multi +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolver library will return all valid addresses for a host that +appears in the +.I /etc/hosts +file, +instead of only the first. +This is +.I off +by default, as it may cause a substantial performance loss at sites +with large hosts files. +.TP +.I reorder +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolver library +will attempt to reorder host addresses so that local addresses +(i.e., on the same subnet) are listed first when a +.BR gethostbyname (3) +is performed. +Reordering is done for all lookup methods. +The default value is +.IR off . +.SH ENVIRONMENT +The following environment variables can be used to allow users to +override the behavior which is configured in +.IR /etc/host.conf : +.TP +.B RESOLV_HOST_CONF +If set, this variable points to a file that should be read instead of +.IR /etc/host.conf . +.TP +.B RESOLV_MULTI +Overrides the +.I multi +command. +.TP +.B RESOLV_REORDER +Overrides the +.I reorder +command. +.TP +.B RESOLV_ADD_TRIM_DOMAINS +A list of domains, +separated by +colons (\[aq]:\[aq]), semicolons (\[aq];\[aq]), or commas (\[aq],\[aq]), +with the leading dot, +which will be added to the list of domains that should be trimmed. +.TP +.B RESOLV_OVERRIDE_TRIM_DOMAINS +A list of domains, +separated by +colons (\[aq]:\[aq]), semicolons (\[aq];\[aq]), or commas (\[aq],\[aq]), +with the leading dot, +which will replace the list of domains that should be trimmed. +Overrides the +.I trim +command. +.SH FILES +.TP +.I /etc/host.conf +Resolver configuration file +.TP +.I /etc/resolv.conf +Resolver configuration file +.TP +.I /etc/hosts +Local hosts database +.SH NOTES +The following differences exist compared to the original implementation. +A new command +.I spoof +and a new environment variable +.B RESOLV_SPOOF_CHECK +can take arguments like +.IR off ", " nowarn ", and " warn . +Line comments can appear anywhere and not only at the beginning of a line. +.SS Historical +The +.BR nsswitch.conf (5) +file is the modern way of controlling the order of host lookups. +.P +In glibc 2.4 and earlier, the following keyword is recognized: +.TP +.I order +This keyword specifies how host lookups are to be performed. +It should be followed by one or more lookup methods, separated by commas. +Valid methods are +.IR bind ", " hosts ", and " nis . +.TP +.B RESOLV_SERV_ORDER +Overrides the +.I order +command. +.P +.\" commit 7d68cdaa4f748e87ee921f587ee2d483db624b3d +Since glibc 2.0.7, and up through glibc 2.24, +the following keywords and environment variable +have been recognized but never implemented: +.TP +.I nospoof +Valid values are +.IR on " and " off . +If set to +.IR on , +the resolver library will attempt to prevent hostname spoofing to +enhance the security of +.BR rlogin " and " rsh . +It works as follows: after performing a host address lookup, +the resolver library will perform a hostname lookup for that address. +If the two hostnames +do not match, the query fails. +The default value is +.IR off . +.TP +.I spoofalert +Valid values are +.IR on " and " off . +If this option is set to +.I on +and the +.I nospoof +option is also set, +the resolver library will log a warning of the error via the +syslog facility. +The default value is +.IR off . +.TP +.I spoof +Valid values are +.IR off ", " nowarn ", and " warn . +If this option is set to +.IR off , +spoofed addresses are permitted and no warnings will be emitted +via the syslog facility. +If this option is set to +.IR warn , +the resolver library will attempt to prevent hostname spoofing to +enhance the security and log a warning of the error via the syslog +facility. +If this option is set to +.IR nowarn , +the resolver library will attempt to prevent hostname spoofing to +enhance the security but not emit warnings via the syslog facility. +Setting this option to anything else is equal to setting it to +.IR nowarn . +.TP +.B RESOLV_SPOOF_CHECK +Overrides the +.IR nospoof ", " spoofalert ", and " spoof +commands in the same way as the +.I spoof +command is parsed. +Valid values are +.IR off ", " nowarn ", and " warn . +.SH SEE ALSO +.BR gethostbyname (3), +.BR hosts (5), +.BR nsswitch.conf (5), +.BR resolv.conf (5), +.BR hostname (7), +.BR named (8) diff --git a/man/man5/hosts.5 b/man/man5/hosts.5 new file mode 100644 index 0000000..bab4455 --- /dev/null +++ b/man/man5/hosts.5 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2000 Manoj Srivastava +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Minor polishing, aeb +.\" Modified, 2002-06-16, Mike Coleman +.\" +.TH hosts 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +hosts \- static table lookup for hostnames +.SH SYNOPSIS +.nf +.B /etc/hosts +.fi +.SH DESCRIPTION +This manual page describes the format of the +.I /etc/hosts +file. +This file is a simple text file that associates IP addresses +with hostnames, one line per IP address. +For each host a single +line should be present with the following information: +.RS +.P +IP_address canonical_hostname [aliases...] +.RE +.P +The IP address can conform to either IPv4 or IPv6. +Fields of the entry are separated by any number of blanks and/or +tab characters. +Text from a "#" character until the end of the line is +a comment, and is ignored. +Host names may contain only alphanumeric +characters, minus signs ("\-"), and periods ("."). +They must begin with an +alphabetic character and end with an alphanumeric character. +Optional aliases provide for name changes, alternate spellings, +shorter hostnames, or generic hostnames (for example, +.IR localhost ). +If required, a host may have two separate entries in this file; +one for each version of the Internet Protocol (IPv4 and IPv6). +.P +The Berkeley Internet Name Domain (BIND) Server implements the +Internet name server for UNIX systems. +It augments or replaces the +.I /etc/hosts +file or hostname lookup, and frees a host from relying on +.I /etc/hosts +being up to date and complete. +.P +In modern systems, even though the host table has been superseded by +DNS, it is still widely used for: +.TP +.B bootstrapping +Most systems have a small host table containing the name and address +information for important hosts on the local network. +This is useful +when DNS is not running, for example during system bootup. +.TP +.B NIS +Sites that use NIS use the host table as input to the NIS host +database. +Even though NIS can be used with DNS, most NIS sites still +use the host table with an entry for all local hosts as a backup. +.TP +.B isolated nodes +Very small sites that are isolated from the network use the host table +instead of DNS. +If the local information rarely changes, and the +network is not connected to the Internet, DNS offers little +advantage. +.SH FILES +.I /etc/hosts +.SH NOTES +Modifications to this file normally take effect immediately, +except in cases where the file is cached by applications. +.SS Historical notes +RFC\ 952 gave the original format for the host table, though it has +since changed. +.P +Before the advent of DNS, the host table was the only way of resolving +hostnames on the fledgling Internet. +Indeed, this file could be +created from the official host data base maintained at the Network +Information Control Center (NIC), though local changes were often +required to bring it up to date regarding unofficial aliases and/or +unknown hosts. +The NIC no longer maintains the hosts.txt files, +though looking around at the time of writing (circa 2000), there are +historical hosts.txt files on the WWW. +I just found three, from 92, +94, and 95. +.SH EXAMPLES +.EX +# The following lines are desirable for IPv4 capable hosts +127.0.0.1 localhost +\& +# 127.0.1.1 is often used for the FQDN of the machine +127.0.1.1 thishost.example.org thishost +192.168.1.10 foo.example.org foo +192.168.1.13 bar.example.org bar +146.82.138.7 master.debian.org master +209.237.226.90 www.opensource.org +\& +# The following lines are desirable for IPv6 capable hosts +::1 localhost ip6\-localhost ip6\-loopback +ff02::1 ip6\-allnodes +ff02::2 ip6\-allrouters +.EE +.SH SEE ALSO +.BR hostname (1), +.BR resolver (3), +.BR host.conf (5), +.BR resolv.conf (5), +.BR resolver (5), +.BR hostname (7), +.BR named (8) +.P +Internet RFC\ 952 +.\" .SH AUTHOR +.\" This manual page was written by Manoj Srivastava , +.\" for the Debian GNU/Linux system. diff --git a/man/man5/hosts.equiv.5 b/man/man5/hosts.equiv.5 new file mode 100644 index 0000000..718ec15 --- /dev/null +++ b/man/man5/hosts.equiv.5 @@ -0,0 +1,212 @@ +.\" Copyright (c) 1995 Peter Tobias +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.TH hosts.equiv 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +hosts.equiv \- list of hosts and users that are granted "trusted" +.B r +command access to your system +.SH DESCRIPTION +The file +.I /etc/hosts.equiv +allows or denies hosts and users to use +the \fBr\fP-commands (e.g., +.BR rlogin , +.BR rsh , +or +.BR rcp ) +without +supplying a password. +.P +The file uses the following format: +.TP +\fI+|[\-]hostname|+@netgroup|\-@netgroup\fP \fI[+|[\-]username|+@netgroup|\-@netgroup]\fP +.P +The +.I hostname +is the name of a host which is logically equivalent +to the local host. +Users logged into that host are allowed to access +like-named user accounts on the local host without supplying a password. +The +.I hostname +may be (optionally) preceded by a plus (+) sign. +If the plus sign is used alone, it allows any host to access your system. +You can explicitly deny access to a host by preceding the +.I hostname +by a minus (\-) sign. +Users from that host must always supply additional credentials, +including possibly a password. +For security reasons you should always +use the FQDN of the hostname and not the short hostname. +.P +The +.I username +entry grants a specific user access to all user +accounts (except root) without supplying a password. +That means the +user is NOT restricted to like-named accounts. +The +.I username +may +be (optionally) preceded by a plus (+) sign. +You can also explicitly +deny access to a specific user by preceding the +.I username +with +a minus (\-) sign. +This says that the user is not trusted no matter +what other entries for that host exist. +.P +Netgroups can be specified by preceding the netgroup by an @ sign. +.P +Be extremely careful when using the plus (+) sign. +A simple typographical +error could result in a standalone plus sign. +A standalone plus sign is +a wildcard character that means "any host"! +.SH FILES +.I /etc/hosts.equiv +.SH NOTES +Some systems will honor the contents of this file only when it has owner +root and no write permission for anybody else. +Some exceptionally +paranoid systems even require that there be no other hard links to the file. +.P +Modern systems use the Pluggable Authentication Modules library (PAM). +With PAM a standalone plus sign is considered a wildcard +character which means "any host" only when the word +.I promiscuous +is added to the auth component line in your PAM file for +the particular service +.RB "(e.g., " rlogin ). +.SH EXAMPLES +Below are some example +.I /etc/host.equiv +or +.I \[ti]/.rhosts +files. +.P +Allow any user to log in from any host: +.P +.in +4n +.EX ++ +.EE +.in +.P +Allow any user from +.I host +with a matching local account to log in: +.P +.in +4n +.EX +host +.EE +.in +.P +Note: the use of +.I +host +is never a valid syntax, +including attempting to specify that any user from the host is allowed. +.P +Allow any user from +.I host +to log in: +.P +.in +4n +.EX +host + +.EE +.in +.P +Note: this is distinct from the previous example +since it does not require a matching local account. +.P +Allow +.I user +from +.I host +to log in as any non-root user: +.P +.in +4n +.EX +host user +.EE +.in +.P +Allow all users with matching local accounts from +.I host +to log in except for +.IR baduser : +.P +.in +4n +.EX +host \-baduser +host +.EE +.in +.P +Deny all users from +.IR host : +.P +.in +4n +.EX +\-host +.EE +.in +.P +Note: the use of +.I "\-host\ \-user" +is never a valid syntax, +including attempting to specify that a particular user from the host +is not trusted. +.P +Allow all users with matching local accounts on all hosts in a +.IR netgroup : +.P +.in +4n +.EX ++@netgroup +.EE +.in +.P +Disallow all users on all hosts in a +.IR netgroup : +.P +.in +4n +.EX +\-@netgroup +.EE +.in +.P +Allow all users in a +.I netgroup +to log in from +.I host +as any non-root user: +.P +.in +4n +.EX +host +@netgroup +.EE +.in +.P +Allow all users with matching local accounts on all hosts in a +.I netgroup +except +.IR baduser : +.P +.in +4n +.EX ++@netgroup \-baduser ++@netgroup +.EE +.in +.P +Note: the deny statements must always precede the allow statements because +the file is processed sequentially until the first matching rule is found. +.SH SEE ALSO +.BR rhosts (5), +.BR rlogind (8), +.BR rshd (8) diff --git a/man/man5/intro.5 b/man/man5/intro.5 new file mode 100644 index 0000000..71ec35e --- /dev/null +++ b/man/man5/intro.5 @@ -0,0 +1,23 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:06:52 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jan 14 00:34:09 1996 by Andries Brouwer (aeb@cwi.nl) +.TH intro 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intro \- introduction to file formats and filesystems +.SH DESCRIPTION +Section 5 of the manual describes various file formats, +as well as the corresponding C structures, if any. +.P +In addition, +this section contains a number of pages that document various filesystems. +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR standards (7) diff --git a/man/man5/issue.5 b/man/man5/issue.5 new file mode 100644 index 0000000..019e5f7 --- /dev/null +++ b/man/man5/issue.5 @@ -0,0 +1,24 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 11:06:22 1993 by Rik Faith +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.TH issue 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +issue \- prelogin message and identification file +.SH DESCRIPTION +.I /etc/issue +is a text file which contains a message or +system identification to be printed before the login prompt. +It may contain various \fB@\fP\fIchar\fP and \fB\e\fP\fIchar\fP +sequences, if supported by the +.BR getty -type +program employed on the system. +.SH FILES +.I /etc/issue +.SH SEE ALSO +.BR motd (5), +.BR agetty (8), +.BR mingetty (8) diff --git a/man/man5/locale.5 b/man/man5/locale.5 new file mode 100644 index 0000000..f3da0c5 --- /dev/null +++ b/man/man5/locale.5 @@ -0,0 +1,1316 @@ +.\" Copyright (C) 1994 Jochen Hein (Hein@Student.TU-Clausthal.de) +.\" Copyright (C) 2008 Petr Baudis (pasky@suse.cz) +.\" Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2008-06-17 Petr Baudis +.\" LC_TIME: Describe first_weekday and first_workday +.\" +.TH locale 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +locale \- describes a locale definition file +.SH DESCRIPTION +The +.B locale +definition file contains all the information that the +.BR localedef (1) +command needs to convert it into the binary locale database. +.P +The definition files consist of sections which each describe a +locale category in detail. +See +.BR locale (7) +for additional details for these categories. +.SS Syntax +The locale definition file starts with a header that may consist +of the following keywords: +.TP +.I escape_char +is followed by a character that should be used as the +escape-character for the rest of the file to mark characters that +should be interpreted in a special way. +It defaults to the backslash (\e). +.TP +.I comment_char +is followed by a character that will be used as the +comment-character for the rest of the file. +It defaults to the number sign (#). +.P +The locale definition has one part for each locale category. +Each part can be copied from another existing locale or +can be defined from scratch. +If the category should be copied, +the only valid keyword in the definition is +.I copy +followed by the name of the locale in double quotes which should be +copied. +The exceptions for this rule are +.B LC_COLLATE +and +.B LC_CTYPE +where a +.I copy +statement can be followed by locale-specific rules and selected overrides. +.P +When defining a locale or a category from scratch, an existing system- +provided locale definition file should be used as a reference to follow +common glibc conventions. +.SS Locale category sections +The following category sections are defined by POSIX: +.IP \[bu] 3 +.B LC_CTYPE +.IP \[bu] +.B LC_COLLATE +.IP \[bu] +.B LC_MESSAGES +.IP \[bu] +.B LC_MONETARY +.IP \[bu] +.B LC_NUMERIC +.IP \[bu] +.B LC_TIME +.P +In addition, since glibc 2.2, +the GNU C library supports the following nonstandard categories: +.IP \[bu] 3 +.B LC_ADDRESS +.IP \[bu] +.B LC_IDENTIFICATION +.IP \[bu] +.B LC_MEASUREMENT +.IP \[bu] +.B LC_NAME +.IP \[bu] +.B LC_PAPER +.IP \[bu] +.B LC_TELEPHONE +.P +See +.BR locale (7) +for a more detailed description of each category. +.SS LC_ADDRESS +The definition starts with the string +.I LC_ADDRESS +in the first column. +.P +The following keywords are allowed: +.TP +.I postal_fmt +followed by a string containing field descriptors that define +the format used for postal addresses in the locale. +The following field descriptors are recognized: +.RS +.TP +%n +Person's name, possibly constructed with the +.B LC_NAME +.I name_fmt +keyword (since glibc 2.24). +.TP 4 +%a +Care of person, or organization. +.TP +%f +Firm name. +.TP +%d +Department name. +.TP +%b +Building name. +.TP +%s +Street or block (e.g., Japanese) name. +.TP +%h +House number or designation. +.TP +%N +Insert an end-of-line if the previous descriptor's value was not an empty +string; otherwise ignore. +.TP +%t +Insert a space if the previous descriptor's value was not an empty string; +otherwise ignore. +.TP +%r +Room number, door designation. +.TP +%e +Floor number. +.TP +%C +Country designation, from the +.I country_post +keyword. +.TP +%l +Local township within town or city (since glibc 2.24). +.TP +%z +Zip number, postal code. +.TP +%T +Town, city. +.TP +%S +State, province, or prefecture. +.TP +%c +Country, as taken from data record. +.P +Each field descriptor may have an \[aq]R\[aq] after +the \[aq]%\[aq] to specify that the +information is taken from a Romanized version string of the +entity. +.RE +.TP +.I country_name +followed by the country name in the language of the current document +(e.g., "Deutschland" for the +.B de_DE +locale). +.TP +.I country_post +followed by the abbreviation of the country (see CERT_MAILCODES). +.TP +.I country_ab2 +followed by the two-letter abbreviation of the country (ISO\~3166). +.TP +.I country_ab3 +followed by the three-letter abbreviation of the country (ISO\~3166). +.TP +.I country_num +followed by the numeric country code (ISO\~3166). +.TP +.I country_car +followed by the international license plate country code. +.TP +.I country_isbn +followed by the ISBN code (for books). +.TP +.I lang_name +followed by the language name in the language of the current document. +.TP +.I lang_ab +followed by the two-letter abbreviation of the language (ISO\~639). +.TP +.I lang_term +followed by the three-letter abbreviation of the language (ISO\~639-2/T). +.TP +.I lang_lib +followed by the three-letter abbreviation of the language for library +use (ISO\~639-2/B). +Applications should in general prefer +.I lang_term +over +.IR lang_lib . +.P +The +.B LC_ADDRESS +definition ends with the string +.IR "END LC_ADDRESS" . +.SS LC_CTYPE +The definition starts with the string +.I LC_CTYPE +in the first column. +.P +The following keywords are allowed: +.TP +.I upper +followed by a list of uppercase letters. +The letters +.B A +through +.B Z +are included automatically. +Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. +.TP +.I lower +followed by a list of lowercase letters. +The letters +.B a +through +.B z +are included automatically. +Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. +.TP +.I alpha +followed by a list of letters. +All character specified as either +.B upper +or +.B lower +are automatically included. +Characters also specified as +.BR cntrl , +.BR digit , +.BR punct , +or +.B space +are not allowed. +.TP +.I digit +followed by the characters classified as numeric digits. +Only the +digits +.B 0 +through +.B 9 +are allowed. +They are included by default in this class. +.TP +.I space +followed by a list of characters defined as white-space +characters. +Characters also specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR graph , +or +.B xdigit +are not allowed. +The characters +.BR , +.BR , +.BR , +.BR , +.BR , +and +.B +are automatically included. +.TP +.I cntrl +followed by a list of control characters. +Characters also specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR punct , +.BR graph , +.BR print , +or +.B xdigit +are not allowed. +.TP +.I punct +followed by a list of punctuation characters. +Characters also +specified as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR cntrl , +.BR xdigit , +or the +.B +character are not allowed. +.TP +.I graph +followed by a list of printable characters, not including the +.B +character. +The characters defined as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR xdigit , +and +.B punct +are automatically included. +Characters also specified as +.B cntrl +are not allowed. +.TP +.I print +followed by a list of printable characters, including the +.B +character. +The characters defined as +.BR upper , +.BR lower , +.BR alpha , +.BR digit , +.BR xdigit , +.BR punct , +and the +.B +character are automatically included. +Characters also specified as +.B cntrl +are not allowed. +.TP +.I xdigit +followed by a list of characters classified as hexadecimal +digits. +The decimal digits must be included followed by one or +more set of six characters in ascending order. +The following +characters are included by default: +.B 0 +through +.BR 9 , +.B a +through +.BR f , +.B A +through +.BR F . +.TP +.I blank +followed by a list of characters classified as +.BR blank . +The characters +.B +and +.B +are automatically included. +.TP +.I charclass +followed by a list of locale-specific character class names +which are then to be defined in the locale. +.TP +.I toupper +followed by a list of mappings from lowercase to uppercase +letters. +Each mapping is a pair of a lowercase and an uppercase letter +separated with a +.B , +and enclosed in parentheses. +.TP +.I tolower +followed by a list of mappings from uppercase to lowercase +letters. +If the keyword tolower is not present, the reverse of the +toupper list is used. +.TP +.I map totitle +followed by a list of mapping pairs of +characters and letters +to be used in titles (headings). +.TP +.I class +followed by a locale-specific character class definition, +starting with the class name followed by the characters +belonging to the class. +.TP +.I charconv +followed by a list of locale-specific character mapping names +which are then to be defined in the locale. +.TP +.I outdigit +followed by a list of alternate output digits for the locale. +.TP +.I map to_inpunct +followed by a list of mapping pairs of +alternate digits and separators +for input digits for the locale. +.TP +.I map to_outpunct +followed by a list of mapping pairs of +alternate separators +for output for the locale. +.TP +.I translit_start +marks the start of the transliteration rules section. +The section can contain the +.I include +keyword in the beginning followed by +locale-specific rules and overrides. +Any rule specified in the locale file +will override any rule +copied or included from other files. +In case of duplicate rule definitions in the locale file, +only the first rule is used. +.IP +A transliteration rule consist of a character to be transliterated +followed by a list of transliteration targets separated by semicolons. +The first target which can be presented in the target character set +is used, if none of them can be used the +.I default_missing +character will be used instead. +.TP +.I include +in the transliteration rules section includes +a transliteration rule file +(and optionally a repertoire map file). +.TP +.I default_missing +in the transliteration rules section +defines the default character to be used for +transliteration where none of the targets cannot be presented +in the target character set. +.TP +.I translit_end +marks the end of the transliteration rules. +.P +The +.B LC_CTYPE +definition ends with the string +.IR "END LC_CTYPE" . +.SS LC_COLLATE +Note that glibc does not support all POSIX-defined options, +only the options described below are supported (as of glibc 2.23). +.P +The definition starts with the string +.I LC_COLLATE +in the first column. +.P +The following keywords are allowed: +.TP +.I coll_weight_max +followed by the number representing used collation levels. +This keyword is recognized but ignored by glibc. +.TP +.I collating\-element +followed by the definition of a collating-element symbol +representing a multicharacter collating element. +.TP +.I collating\-symbol +followed by the definition of a collating symbol +that can be used in collation order statements. +.TP +.I define +followed by +.B string +to be evaluated in an +.I ifdef +.B string +/ +.I else +/ +.I endif +construct. +.TP +.I reorder\-after +followed by a redefinition of a collation rule. +.TP +.I reorder\-end +marks the end of the redefinition of a collation rule. +.TP +.I reorder\-sections\-after +followed by a script name to reorder listed scripts after. +.TP +.I reorder\-sections\-end +marks the end of the reordering of sections. +.TP +.I script +followed by a declaration of a script. +.TP +.I symbol\-equivalence +followed by a collating-symbol to be equivalent to another defined +collating-symbol. +.P +The collation rule definition starts with a line: +.TP +.I order_start +followed by a list of keywords chosen from +.BR forward , +.BR backward , +or +.BR position . +The order definition consists of lines that describe the collation +order and is terminated with the keyword +.IR order_end . +.P +The +.B LC_COLLATE +definition ends with the string +.IR "END LC_COLLATE" . +.SS LC_IDENTIFICATION +The definition starts with the string +.I LC_IDENTIFICATION +in the first column. +.P +The following keywords are allowed: +.TP +.I title +followed by the title of the locale document +(e.g., "Maori language locale for New Zealand"). +.TP +.I source +followed by the name of the organization that maintains this document. +.TP +.I address +followed by the address of the organization that maintains this document. +.TP +.I contact +followed by the name of the contact person at +the organization that maintains this document. +.TP +.I email +followed by the email address of the person or +organization that maintains this document. +.TP +.I tel +followed by the telephone number (in international format) +of the organization that maintains this document. +As of glibc 2.24, this keyword is deprecated in favor of +other contact methods. +.TP +.I fax +followed by the fax number (in international format) +of the organization that maintains this document. +As of glibc 2.24, this keyword is deprecated in favor of +other contact methods. +.TP +.I language +followed by the name of the language to which this document applies. +.TP +.I territory +followed by the name of the country/geographic extent +to which this document applies. +.TP +.I audience +followed by a description of the audience for which this document is +intended. +.TP +.I application +followed by a description of any special application +for which this document is intended. +.TP +.I abbreviation +followed by the short name for provider of the source of this document. +.TP +.I revision +followed by the revision number of this document. +.TP +.I date +followed by the revision date of this document. +.P +In addition, for each of the categories defined by the document, +there should be a line starting with the keyword +.IR category , +followed by: +.IP (1) 5 +a string that identifies this locale category definition, +.IP (2) +a semicolon, and +.IP (3) +one of the +.B LC_* +identifiers. +.P +The +.B LC_IDENTIFICATION +definition ends with the string +.IR "END LC_IDENTIFICATION" . +.SS LC_MESSAGES +The definition starts with the string +.I LC_MESSAGES +in the first column. +.P +The following keywords are allowed: +.TP +.I yesexpr +followed by a regular expression that describes possible +yes-responses. +.TP +.I noexpr +followed by a regular expression that describes possible +no-responses. +.TP +.I yesstr +followed by the output string corresponding to "yes". +.TP +.I nostr +followed by the output string corresponding to "no". +.P +The +.B LC_MESSAGES +definition ends with the string +.IR "END LC_MESSAGES" . +.SS LC_MEASUREMENT +The definition starts with the string +.I LC_MEASUREMENT +in the first column. +.P +The following keywords are allowed: +.TP +.I measurement +followed by number identifying the standard used for measurement. +The following values are recognized: +.RS +.TP 4 +.B 1 +Metric. +.TP +.B 2 +US customary measurements. +.RE +.P +The +.B LC_MEASUREMENT +definition ends with the string +.IR "END LC_MEASUREMENT" . +.SS LC_MONETARY +The definition starts with the string +.I LC_MONETARY +in the first column. +.P +The following keywords are allowed: +.TP +.I int_curr_symbol +followed by the international currency symbol. +This must be a +4-character string containing the international currency symbol as +defined by the ISO\~4217 standard (three characters) followed by a +separator. +.TP +.I currency_symbol +followed by the local currency symbol. +.TP +.I mon_decimal_point +followed by the single-character string that will be used as the +decimal delimiter when formatting monetary quantities. +.TP +.I mon_thousands_sep +followed by the single-character string that will be used as a group +separator when formatting monetary quantities. +.TP +.I mon_grouping +followed by a sequence of integers separated by semicolons that +describe the formatting of monetary quantities. +See +.I grouping +below for details. +.TP +.I positive_sign +followed by a string that is used to indicate a positive sign for +monetary quantities. +.TP +.I negative_sign +followed by a string that is used to indicate a negative sign for +monetary quantities. +.TP +.I int_frac_digits +followed by the number of fractional digits that should be used when +formatting with the +.IR int_curr_symbol . +.TP +.I frac_digits +followed by the number of fractional digits that should be used when +formatting with the +.IR currency_symbol . +.TP +.I p_cs_precedes +followed by an integer that indicates the placement of +.I currency_symbol +for a nonnegative formatted monetary quantity: +.RS +.TP 4 +.B 0 +the symbol succeeds the value. +.TP +.B 1 +the symbol precedes the value. +.RE +.TP +.I p_sep_by_space +followed by an integer that indicates the separation of +.IR currency_symbol , +the sign string, and the value for a nonnegative formatted monetary quantity. +The following values are recognized: +.RS +.TP 4 +.B 0 +No space separates the currency symbol and the value. +.TP +.B 1 +If the currency symbol and the sign string are adjacent, +a space separates them from the value; +otherwise a space separates the currency symbol and the value. +.TP +.B 2 +If the currency symbol and the sign string are adjacent, +a space separates them from the value; +otherwise a space separates the sign string and the value. +.RE +.TP +.I n_cs_precedes +followed by an integer that indicates the placement of +.I currency_symbol +for a negative formatted monetary quantity. +The same values are recognized as for +.IR p_cs_precedes . +.TP +.I n_sep_by_space +followed by an integer that indicates the separation of +.IR currency_symbol , +the sign string, and the value for a negative formatted monetary quantity. +The same values are recognized as for +.IR p_sep_by_space . +.TP +.I p_sign_posn +followed by an integer that indicates where the +.I positive_sign +should be placed for a nonnegative monetary quantity: +.RS +.TP 4 +.B 0 +Parentheses enclose the quantity and the +.I currency_symbol +or +.IR int_curr_symbol . +.TP +.B 1 +The sign string precedes the quantity and the +.I currency_symbol +or the +.IR int_curr_symbol . +.TP +.B 2 +The sign string succeeds the quantity and the +.I currency_symbol +or the +.IR int_curr_symbol . +.TP +.B 3 +The sign string precedes the +.I currency_symbol +or the +.IR int_curr_symbol . +.TP +.B 4 +The sign string succeeds the +.I currency_symbol +or the +.IR int_curr_symbol . +.RE +.TP +.I n_sign_posn +followed by an integer that indicates where the +.I negative_sign +should be placed for a negative monetary quantity. +The same values are recognized as for +.IR p_sign_posn . +.TP +.I int_p_cs_precedes +followed by an integer that indicates the placement of +.I int_curr_symbol +for a nonnegative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_cs_precedes . +.TP +.I int_n_cs_precedes +followed by an integer that indicates the placement of +.I int_curr_symbol +for a negative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_cs_precedes . +.TP +.I int_p_sep_by_space +followed by an integer that indicates the separation of +.IR int_curr_symbol , +the sign string, +and the value for a nonnegative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sep_by_space . +.TP +.I int_n_sep_by_space +followed by an integer that indicates the separation of +.IR int_curr_symbol , +the sign string, +and the value for a negative internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sep_by_space . +.TP +.I int_p_sign_posn +followed by an integer that indicates where the +.I positive_sign +should be placed for a nonnegative +internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sign_posn . +.TP +.I int_n_sign_posn +followed by an integer that indicates where the +.I negative_sign +should be placed for a negative +internationally formatted monetary quantity. +The same values are recognized as for +.IR p_sign_posn . +.P +The +.B LC_MONETARY +definition ends with the string +.IR "END LC_MONETARY" . +.SS LC_NAME +The definition starts with the string +.I LC_NAME +in the first column. +.P +Various keywords are allowed, but only +.I name_fmt +is mandatory. +Other keywords are needed only if there is common convention to +use the corresponding salutation in this locale. +The allowed keywords are as follows: +.TP +.I name_fmt +followed by a string containing field descriptors that define +the format used for names in the locale. +The following field descriptors are recognized: +.RS +.TP 4 +%f +Family name(s). +.TP +%F +Family names in uppercase. +.TP +%g +First given name. +.TP +%G +First given initial. +.TP +%l +First given name with Latin letters. +.TP +%o +Other shorter name. +.TP +%m +Additional given name(s). +.TP +%M +Initials for additional given name(s). +.TP +%p +Profession. +.TP +%s +Salutation, such as "Doctor". +.TP +%S +Abbreviated salutation, such as "Mr." or "Dr.". +.TP +%d +Salutation, using the FDCC-sets conventions. +.\" 1 for the name_gen +.\" In glibc 2.19, %d1 is used in only: +.\" /home/mtk/ARCHIVE/GLIBC/glibc-2.19/localedata/locales/bem_ZM +.\" /home/mtk/ARCHIVE/GLIBC/glibc-2.19/localedata/locales/zh_HK +.\" In glibc 2.19, %d[2-5] appear to be not used at all +.\" 2 for name_mr +.\" 3 for name_mrs +.\" 4 for name_miss +.\" 5 for name_ms +.TP +%t +If the preceding field descriptor resulted in an empty string, +then the empty string, otherwise a space character. +.RE +.TP +.I name_gen +followed by the general salutation for any gender. +.TP +.I name_mr +followed by the salutation for men. +.TP +.I name_mrs +followed by the salutation for married women. +.TP +.I name_miss +followed by the salutation for unmarried women. +.TP +.I name_ms +followed by the salutation valid for all women. +.P +The +.B LC_NAME +definition ends with the string +.IR "END LC_NAME" . +.SS LC_NUMERIC +The definition starts with the string +.I LC_NUMERIC +in the first column. +.P +The following keywords are allowed: +.TP +.I decimal_point +followed by the single-character string that will be used as the +decimal delimiter when formatting numeric quantities. +.TP +.I thousands_sep +followed by the single-character string that will be used as a group +separator when formatting numeric quantities. +.TP +.I grouping +followed by a sequence of integers separated by semicolons +that describe the formatting of numeric quantities. +.IP +Each integer specifies the number of digits in a group. +The first integer defines the size of the group immediately +to the left of the decimal delimiter. +Subsequent integers define succeeding groups to the +left of the previous group. +If the last integer is not \-1, then the size of the previous group +(if any) is repeatedly used for the remainder of the digits. +If the last integer is \-1, then no further grouping is performed. +.P +The +.B LC_NUMERIC +definition ends with the string +.IR "END LC_NUMERIC" . +.SS LC_PAPER +The definition starts with the string +.I LC_PAPER +in the first column. +.P +The following keywords are allowed: +.TP +.I height +followed by the height, in millimeters, of the standard paper format. +.TP +.I width +followed by the width, in millimeters, of the standard paper format. +.P +The +.B LC_PAPER +definition ends with the string +.IR "END LC_PAPER" . +.SS LC_TELEPHONE +The definition starts with the string +.I LC_TELEPHONE +in the first column. +.P +The following keywords are allowed: +.TP +.I tel_int_fmt +followed by a string that contains field descriptors that identify +the format used to dial international numbers. +The following field descriptors are recognized: +.RS +.TP 4 +%a +Area code without nationwide prefix (the prefix is often "00"). +.TP +%A +Area code including nationwide prefix. +.TP +%l +Local number (within area code). +.TP +%e +Extension (to local number). +.TP +%c +Country code. +.TP +%C +Alternate carrier service code used for dialing abroad. +.TP +%t +If the preceding field descriptor resulted in an empty string, +then the empty string, otherwise a space character. +.RE +.TP +.I tel_dom_fmt +followed by a string that contains field descriptors that identify +the format used to dial domestic numbers. +The recognized field descriptors are the same as for +.IR tel_int_fmt . +.TP +.I int_select +followed by the prefix used to call international phone numbers. +.TP +.I int_prefix +followed by the prefix used from other countries to dial this country. +.P +The +.B LC_TELEPHONE +definition ends with the string +.IR "END LC_TELEPHONE" . +.SS LC_TIME +The definition starts with the string +.I LC_TIME +in the first column. +.P +The following keywords are allowed: +.TP +.I abday +followed by a list of abbreviated names of the days of the week. +The list starts with the first day of the week +as specified by +.I week +(Sunday by default). +See NOTES. +.TP +.I day +followed by a list of names of the days of the week. +The list starts with the first day of the week +as specified by +.I week +(Sunday by default). +See NOTES. +.TP +.I abmon +followed by a list of abbreviated month names. +.TP +.I mon +followed by a list of month names. +.TP +.I d_t_fmt +followed by the appropriate date and time format +(for syntax, see +.BR strftime (3)). +.TP +.I d_fmt +followed by the appropriate date format +(for syntax, see +.BR strftime (3)). +.TP +.I t_fmt +followed by the appropriate time format +(for syntax, see +.BR strftime (3)). +.TP +.I am_pm +followed by the appropriate representation of the +.B am +and +.B pm +strings. +This should be left empty for locales not using AM/PM convention. +.TP +.I t_fmt_ampm +followed by the appropriate time format +(for syntax, see +.BR strftime (3)) +when using 12h clock format. +This should be left empty for locales not using AM/PM convention. +.TP +.I era +followed by semicolon-separated strings that define how years are +counted and displayed for each era in the locale. +Each string has the following format: +.RS +.P +.IR direction ":" offset ":" start_date ":" end_date ":" era_name ":" era_format +.P +The fields are to be defined as follows: +.TP 4 +.I direction +Either +.B + +or +.BR \- . +.B + +means the years closer to +.I start_date +have lower numbers than years closer to +.IR end_date . +.B \- +means the opposite. +.TP +.I offset +The number of the year closest to +.I start_date +in the era, corresponding to the +.I %Ey +descriptor (see +.BR strptime (3)). +.TP +.I start_date +The start of the era in the form of +.IR yyyy/mm/dd . +Years prior AD 1 are represented as negative numbers. +.TP +.I end_date +The end of the era in the form of +.IR yyyy/mm/dd , +or one of the two special values of +.B \-* +or +.BR +* . +.B \-* +means the ending date is the beginning of time. +.B +* +means the ending date is the end of time. +.TP +.I era_name +The name of the era corresponding to the +.I %EC +descriptor (see +.BR strptime (3)). +.TP +.I era_format +The format of the year in the era corresponding to the +.I %EY +descriptor (see +.BR strptime (3)). +.RE +.TP +.I era_d_fmt +followed by the format of the date in alternative era notation, +corresponding to the +.I %Ex +descriptor (see +.BR strptime (3)). +.TP +.I era_t_fmt +followed by the format of the time in alternative era notation, +corresponding to the +.I %EX +descriptor (see +.BR strptime (3)). +.TP +.I era_d_t_fmt +followed by the format of the date and time in alternative era notation, +corresponding to the +.I %Ec +descriptor (see +.BR strptime (3)). +.TP +.I alt_digits +followed by the alternative digits used for date and time in the locale. +.TP +.I week +followed by a list of three values separated by semicolons: +The number of days in a week (by default 7), +a date of beginning of the week (by default corresponds to Sunday), +and the minimal length of the first week in year (by default 4). +Regarding the start of the week, +.B 19971130 +shall be used for Sunday and +.B 19971201 +shall be used for Monday. +See NOTES. +.TP +.IR first_weekday " (since glibc 2.2)" +followed by the number of the day from the +.I day +list to be shown as the first day of the week in calendar applications. +The default value of +.B 1 +corresponds to either Sunday or Monday depending +on the value of the second +.I week +list item. +See NOTES. +.TP +.IR first_workday " (since glibc 2.2)" +followed by the number of the first working day from the +.I day +list. +The default value is +.BR 2 . +See NOTES. +.TP +.I cal_direction +followed by a number value that indicates the direction for the +display of calendar dates, as follows: +.RS +.TP 4 +.B 1 +Left-right from top. +.TP +.B 2 +Top-down from left. +.TP +.B 3 +Right-left from top. +.RE +.TP +.I date_fmt +followed by the appropriate date representation for +.BR date (1) +(for syntax, see +.BR strftime (3)). +.P +The +.B LC_TIME +definition ends with the string +.IR "END LC_TIME" . +.SH FILES +.TP +.I /usr/lib/locale/locale\-archive +Usual default locale archive location. +.TP +.I /usr/share/i18n/locales +Usual default path for locale definition files. +.SH STANDARDS +POSIX.2. +.SH NOTES +The collective GNU C library community wisdom regarding +.IR abday , +.IR day , +.IR week , +.IR first_weekday , +and +.I first_workday +states at +https://sourceware.org/glibc/wiki/Locales +the following: +.IP \[bu] 3 +The value of the second +.I week +list item specifies the base of the +.I abday +and +.I day +lists. +.IP \[bu] +.I first_weekday +specifies the offset of the first day-of-week in the +.I abday +and +.I day +lists. +.IP \[bu] +For compatibility reasons, all glibc locales should set the value of the +second +.I week +list item to +.B 19971130 +(Sunday) and base the +.I abday +and +.I day +lists appropriately, and set +.I first_weekday +and +.I first_workday +to +.B 1 +or +.BR 2 , +depending on whether the week and work week actually starts on Sunday or +Monday for the locale. +.\" .SH AUTHOR +.\" Jochen Hein (Hein@Student.TU-Clausthal.de) +.SH SEE ALSO +.BR iconv (1), +.BR locale (1), +.BR localedef (1), +.BR localeconv (3), +.BR newlocale (3), +.BR setlocale (3), +.BR strftime (3), +.BR strptime (3), +.BR uselocale (3), +.BR charmap (5), +.BR charsets (7), +.BR locale (7), +.BR unicode (7), +.BR utf\-8 (7) diff --git a/man/man5/motd.5 b/man/man5/motd.5 new file mode 100644 index 0000000..9de8eea --- /dev/null +++ b/man/man5/motd.5 @@ -0,0 +1,25 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:08:16 1993 by Rik Faith +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.TH motd 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +motd \- message of the day +.SH DESCRIPTION +The contents of +.I /etc/motd +are displayed by +.BR login (1) +after a successful login but just before it executes the login shell. +.P +The abbreviation "motd" stands for "message of the day", and this file +has been traditionally used for exactly that (it requires much less disk +space than mail to all users). +.SH FILES +.I /etc/motd +.SH SEE ALSO +.BR login (1), +.BR issue (5) diff --git a/man/man5/networks.5 b/man/man5/networks.5 new file mode 100644 index 0000000..0aa2893 --- /dev/null +++ b/man/man5/networks.5 @@ -0,0 +1,60 @@ +.\" Copyright (c) 2001 Martin Schulze +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2008-09-04, mtk, taken from Debian downstream, with a few light edits +.\" +.TH networks 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +networks \- network name information +.SH DESCRIPTION +The file +.I /etc/networks +is a plain ASCII file that describes known DARPA networks and symbolic +names for these networks. +Each line represents a network and has the following structure: +.P +.RS +.I name number aliases .\|.\|. +.RE +.P +where the fields are delimited by spaces or tabs. +Empty lines are ignored. +The hash character (\fB#\fP) indicates the start of a comment: +this character, and the remaining characters up to +the end of the current line, +are ignored by library functions that process the file. +.P +The field descriptions are: +.TP +.I name +The symbolic name for the network. +Network names can contain any printable characters except +white-space characters or the comment character. +.TP +.I number +The official number for this network in numbers-and-dots notation (see +.BR inet (3)). +The trailing ".0" (for the host component of the network address) +may be omitted. +.TP +.I aliases +Optional aliases for the network. +.P +This file is read by the +.BR route (8) +and +.BR netstat (8) +utilities. +Only Class A, B, or C networks are supported, partitioned networks +(i.e., network/26 or network/28) are not supported by this file. +.SH FILES +.TP +.I /etc/networks +The networks definition file. +.SH SEE ALSO +.BR getnetbyaddr (3), +.BR getnetbyname (3), +.BR getnetent (3), +.BR netstat (8), +.BR route (8) diff --git a/man/man5/nologin.5 b/man/man5/nologin.5 new file mode 100644 index 0000000..6e83b76 --- /dev/null +++ b/man/man5/nologin.5 @@ -0,0 +1,22 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 11:06:34 1993 by Rik Faith (faith@cs.unc.edu) +.\" Corrected Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond (esr@thyrsus.com) +.TH nologin 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nologin \- prevent unprivileged users from logging into the system +.SH DESCRIPTION +If the file \fI/etc/nologin\fP exists and is readable, +.BR login (1) +will allow access only to root. +Other users will +be shown the contents of this file and their logins will be refused. +This provides a simple way of temporarily disabling all unprivileged logins. +.SH FILES +.I /etc/nologin +.SH SEE ALSO +.BR login (1), +.BR shutdown (8) diff --git a/man/man5/nscd.conf.5 b/man/man5/nscd.conf.5 new file mode 100644 index 0000000..0121e84 --- /dev/null +++ b/man/man5/nscd.conf.5 @@ -0,0 +1,342 @@ +.\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk +.\" Updates: Greg Banks Copyright (c) 2021 Microsoft Corp. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH nscd.conf 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nscd.conf \- name service cache daemon configuration file +.SH DESCRIPTION +The file +.I /etc/nscd.conf +is read from +.BR nscd (8) +at startup. +Each line specifies either an attribute and a value, or an +attribute, service, and a value. +Fields are separated either by SPACE +or TAB characters. +A \[aq]#\[aq] (number sign) indicates the beginning of a +comment; following characters, up to the end of the line, +are not interpreted by nscd. +.P +Valid services are \fIpasswd\fP, \fIgroup\fP, \fIhosts\fP, \fIservices\fP, +or \fInetgroup\fP. +.P +.B logfile +.I debug-file-name +.RS +Specifies name of the file to which debug info should be written. +.RE +.P +.B debug\-level +.I value +.RS +Sets the desired debug level. +0 hides debug info. +1 shows general debug info. +2 additionally shows data in cache dumps. +3 (and above) shows all debug info. +The default is 0. +.RE +.P +.B threads +.I number +.RS +This is the initial number of threads that are started to wait for +requests. +At least five threads will always be created. +The number of threads may increase dynamically up to +.B max\-threads +in response to demand from clients, +but never decreases. +.RE +.P +.B max\-threads +.I number +.RS +Specifies the maximum number of threads. +The default is 32. +.RE +.P +.B server\-user +.I user +.RS +If this option is set, nscd will run as this user and not as root. +If a separate cache for every user is used (\-S parameter), this +option is ignored. +.RE +.P +.B stat\-user +.I user +.RS +Specifies the user who is allowed to request statistics. +.RE +.P +.B reload\-count +unlimited | +.I number +.RS +Sets a limit on the number of times a cached entry +gets reloaded without being used +before it gets removed. +The limit can take values ranging from 0 to 254; +values 255 or higher behave the same as +.BR unlimited . +Limit values can be specified in either decimal +or hexadecimal with a "0x" prefix. +The special value +.B unlimited +is case-insensitive. +The default limit is 5. +A limit of 0 turns off the reloading feature. +See NOTES below for further discussion of reloading. +.RE +.P +.B paranoia +.I +.RS +Enabling paranoia mode causes nscd to restart itself periodically. +The default is no. +.RE +.P +.B restart\-interval +.I time +.RS +Sets the restart interval to +.I time +seconds +if periodic restart is enabled by enabling +.B paranoia +mode. +The default is 3600. +.RE +.P +.B enable\-cache +.I service +.I +.RS +Enables or disables the specified +.I service +cache. +The default is no. +.RE +.P +.B positive\-time\-to\-live +.I service +.I value +.RS +Sets the TTL (time-to-live) for positive entries (successful queries) +in the specified cache for +.IR service . +.I Value +is in seconds. +Larger values increase cache hit rates and reduce mean +response times, but increase problems with cache coherence. +Note that for some name services (including specifically DNS) +the TTL returned from the name service is used and +this attribute is ignored. +.RE +.P +.B negative\-time\-to\-live +.I service +.I value +.RS +Sets the TTL (time-to-live) for negative entries (unsuccessful queries) +in the specified cache for +.IR service . +.I Value +is in seconds. +Can result in significant performance improvements if there +are several files owned by UIDs (user IDs) not in system databases (for +example untarring the Linux kernel sources as root); should be kept small +to reduce cache coherency problems. +.RE +.P +.B suggested\-size +.I service +.I value +.RS +This is the internal hash table size, +.I value +should remain a prime number for optimum efficiency. +The default is 211. +.RE +.P +.B check\-files +.I service +.I +.RS +Enables or disables checking the file belonging to the specified +.I service +for changes. +The files are +.IR /etc/passwd , +.IR /etc/group , +.IR /etc/hosts , +.IR /etc/resolv.conf , +.IR /etc/services , +and +.IR /etc/netgroup . +The default is yes. +.RE +.P +.B persistent +.I service +.I +.RS +Keep the content of the cache for +.I service +over server restarts; useful when +.B paranoia +mode is set. +The default is no. +.RE +.P +.B shared +.I service +.I +.RS +The memory mapping of the nscd databases for +.I service +is shared with the clients so +that they can directly search in them instead of having to ask the +daemon over the socket each time a lookup is performed. +The default is no. +Note that a cache miss will still result in +asking the daemon over the socket. +.RE +.P +.B max\-db\-size +.I service +.I bytes +.RS +The maximum allowable size, in bytes, of the database files for the +.IR service . +The default is 33554432. +.RE +.P +.B auto\-propagate +.I service +.I +.RS +When set to +.I no +for +.I passwd +or +.I group +service, then the +.I .byname +requests are not added to +.I passwd.byuid +or +.I group.bygid +cache. +This can help with tables containing multiple records for the same ID. +The default is yes. +This option is valid only for services +.I passwd +and +.IR group . +.RE +.SH NOTES +The default values stated in this manual page originate +from the source code of +.BR nscd (8) +and are used if not overridden in the configuration file. +The default values used in the configuration file of +your distribution might differ. +.SS Reloading +.BR nscd (8) +has a feature called reloading, +whose behavior can be surprising. +.P +Reloading is enabled when the +.B reload-count +attribute has a non-zero value. +The default value in the source code enables reloading, +although your distribution may differ. +.P +When reloading is enabled, +positive cached entries (the results of successful queries) +do not simply expire when their TTL is up. +Instead, at the expiry time, +.B nscd +will "reload", +i.e., +re-issue to the name service the same query that created the cached entry, +to get a new value to cache. +Depending on +.I /etc/nsswitch.conf +this may mean that a DNS, LDAP, or NIS request is made. +If the new query is successful, +reloading will repeat when the new value would expire, +until +.B reload-count +reloads have happened for the entry, +and only then will it actually be removed from the cache. +A request from a client which hits the entry will +reset the reload counter on the entry. +Purging the cache using +.I nscd\~-i +overrides the reload logic and removes the entry. +.P +Reloading has the effect of extending cache entry TTLs +without compromising on cache coherency, +at the cost of additional load on the backing name service. +Whether this is a good idea on your system depends on +details of your applications' behavior, +your name service, +and the effective TTL values of your cache entries. +Note that for some name services +(for example, DNS), +the effective TTL is the value returned from the name service and +.I not +the value of the +.B positive\-time\-to\-live +attribute. +.P +Please consider the following advice carefully: +.IP \[bu] 3 +If your application will make a second request for the same name, +after more than 1 TTL but before +.B reload\-count +TTLs, +and is sensitive to the latency of a cache miss, +then reloading may be a good idea for you. +.IP \[bu] +If your name service is configured to return very short TTLs, +and your applications only make requests rarely under normal circumstances, +then reloading may result in additional load on your backing name service +without any benefit to applications, +which is probably a bad idea for you. +.IP \[bu] +If your name service capacity is limited, +reloading may have the surprising effect of +increasing load on your name service instead of reducing it, +and may be a bad idea for you. +.IP \[bu] +Setting +.B reload\-count +to +.B unlimited +is almost never a good idea, +as it will result in a cache that never expires entries +and puts never-ending additional load on the backing name service. +.P +Some distributions have an init script for +.BR nscd (8) +with a +.I reload +command which uses +.I nscd\~-i +to purge the cache. +That use of the word "reload" is entirely different +from the "reloading" described here. +.SH SEE ALSO +.BR nscd (8) +.\" .SH AUTHOR +.\" .B nscd +.\" was written by Thorsten Kukuk and Ulrich Drepper. diff --git a/man/man5/nss.5 b/man/man5/nss.5 new file mode 100644 index 0000000..258cc11 --- /dev/null +++ b/man/man5/nss.5 @@ -0,0 +1,101 @@ +.\" Copyright (C) 2006 Red Hat, Inc. All rights reserved. +.\" Author: Ulrich Drepper +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.TH nss 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nss \- Name Service Switch configuration file +.SH DESCRIPTION +Each call to a function which retrieves data from a system database +like the password or group database is handled by the Name Service +Switch implementation in the GNU C library. +The various services +provided are implemented by independent modules, each of which +naturally varies widely from the other. +.P +The default implementations coming with the GNU C library are by +default conservative and do not use unsafe data. +This might be very costly in some situations, especially when the databases +are large. +Some modules allow the system administrator to request +taking shortcuts if these are known to be safe. +It is then the system administrator's responsibility to ensure the assumption +is correct. +.P +There are other modules where the implementation changed over time. +If an implementation used to sacrifice speed for memory consumption, +it might create problems if the preference is switched. +.P +The +.I /etc/default/nss +file contains a number of variable assignments. +Each variable controls the behavior of one or more +NSS modules. +White spaces are ignored. +Lines beginning with \[aq]#\[aq] +are treated as comments. +.P +The variables currently recognized are: +.TP +\fBNETID_AUTHORITATIVE =\fR \fITRUE\fR|\fIFALSE\fR +If set to TRUE, the NIS backend for the +.BR initgroups (3) +function will accept the information +from the +.I netid.byname +NIS map as authoritative. +This can speed up the function significantly if the +.I group.byname +map is large. +The content of the +.I netid.byname +map is used \fBas is\fR. +The system administrator has to make sure it is correctly generated. +.TP +\fBSERVICES_AUTHORITATIVE =\fR \fITRUE\fR|\fIFALSE\fR +If set to TRUE, the NIS backend for the +.BR getservbyname (3) +and +.BR getservbyname_r (3) +functions will assume that the +.I services.byservicename +NIS map exists and is authoritative, particularly +that it contains both keys with /proto and without /proto for both +primary service names and service aliases. +The system administrator has to make sure it is correctly generated. +.TP +\fBSETENT_BATCH_READ =\fR \fITRUE\fR|\fIFALSE\fR +If set to TRUE, the NIS backend for the +.BR setpwent (3) +and +.BR setgrent (3) +functions will read the entire database at once and then +hand out the requests one by one from memory with every corresponding +.BR getpwent (3) +or +.BR getgrent (3) +call respectively. +Otherwise, each +.BR getpwent (3) +or +.BR getgrent (3) +call might result in a network communication with the server to get +the next entry. +.SH FILES +\fI/etc/default/nss\fR +.SH EXAMPLES +The default configuration corresponds to the following configuration file: +.P +.in +4n +.EX +NETID_AUTHORITATIVE=FALSE +SERVICES_AUTHORITATIVE=FALSE +SETENT_BATCH_READ=FALSE +.EE +.in +.\" .SH AUTHOR +.\" Ulrich Drepper +.\" +.SH SEE ALSO +\fInsswitch.conf\fR diff --git a/man/man5/nsswitch.conf.5 b/man/man5/nsswitch.conf.5 new file mode 100644 index 0000000..b394cf4 --- /dev/null +++ b/man/man5/nsswitch.conf.5 @@ -0,0 +1,427 @@ +.\" Copyright (c) 1998, 1999 Thorsten Kukuk (kukuk@vt.uni-paderborn.de) +.\" Copyright (c) 2011, Mark R. Bannister +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH nsswitch.conf 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nsswitch.conf \- Name Service Switch configuration file +.SH DESCRIPTION +The Name Service Switch (NSS) configuration file, +.IR /etc/nsswitch.conf , +is used by the GNU C Library and certain other applications to determine +the sources from which to obtain name-service information in +a range of categories, +and in what order. +Each category of information is identified by a database name. +.P +The file is plain ASCII text, with columns separated by spaces or tab +characters. +The first column specifies the database name. +The remaining columns describe the order of sources to query and a +limited set of actions that can be performed by lookup result. +.P +The following databases are understood by the GNU C Library: +.TP 12 +.B aliases +Mail aliases, used by +.BR getaliasent (3) +and related functions. +.TP +.B ethers +Ethernet numbers. +.TP +.B group +Groups of users, used by +.BR getgrent (3) +and related functions. +.TP +.B hosts +Host names and numbers, used by +.BR gethostbyname (3) +and related functions. +.TP +.B initgroups +Supplementary group access list, used by +.BR getgrouplist (3) +function. +.TP +.B netgroup +Network-wide list of hosts and users, used for access rules. +C libraries before glibc 2.1 supported netgroups only over NIS. +.TP +.B networks +Network names and numbers, used by +.BR getnetent (3) +and related functions. +.TP +.B passwd +User passwords, used by +.BR getpwent (3) +and related functions. +.TP +.B protocols +Network protocols, used by +.BR getprotoent (3) +and related functions. +.TP +.B publickey +Public and secret keys for Secure_RPC used by NFS and NIS+. +.TP +.B rpc +Remote procedure call names and numbers, used by +.BR getrpcbyname (3) +and related functions. +.TP +.B services +Network services, used by +.BR getservent (3) +and related functions. +.TP +.B shadow +Shadow user passwords, used by +.BR getspnam (3) +and related functions. +.P +The GNU C Library ignores databases with unknown names. +Some applications use this to implement special handling for their own +databases. +For example, +.BR sudo (8) +consults the +.B sudoers +database. +Delegation of subordinate user/group IDs +can be configured using the +.B subid +database. +Refer to +.BR subuid (5) +and +.BR subgid (5) +for more details. +.P +Here is an example +.I /etc/nsswitch.conf +file: +.P +.in +4n +.EX +passwd: compat +group: compat +shadow: compat +\& +hosts: dns [!UNAVAIL=return] files +networks: nis [NOTFOUND=return] files +ethers: nis [NOTFOUND=return] files +protocols: nis [NOTFOUND=return] files +rpc: nis [NOTFOUND=return] files +services: nis [NOTFOUND=return] files +.EE +.in +.P +The first column is the database name. +The remaining columns specify: +.IP \[bu] 3 +One or more service specifications, for example, "files", "db", or "nis". +The order of the services on the line determines the order in which +those services will be queried, in turn, until a result is found. +.IP \[bu] +Optional actions to perform if a particular result is obtained +from the preceding service, for example, "[NOTFOUND=return]". +.P +The service specifications supported on your system depend on the +presence of shared libraries, and are therefore extensible. +Libraries called +.IB /lib/libnss_SERVICE.so. X +will provide the named +.IR SERVICE . +On a standard installation, you can use +"files", "db", "nis", and "nisplus". +For the +.B hosts +database, you can additionally specify "dns". +For the +.BR passwd , +.BR group , +and +.B shadow +databases, you can additionally specify +"compat" (see +.B "Compatibility mode" +below). +The version number +.B X +may be 1 for glibc 2.0, or 2 for glibc 2.1 and later. +On systems with additional libraries installed, you may have access to +further services such as "hesiod", "ldap", "winbind", and "wins". +.P +An action may also be specified following a service specification. +The action modifies the behavior following a result obtained +from the preceding data source. +Action items take the general form: +.P +.RS 4 +.RI [ STATUS = ACTION ] +.br +.RI [! STATUS = ACTION ] +.RE +.P +where +.P +.RS 4 +.I STATUS +=> +.B success +| +.B notfound +| +.B unavail +| +.B tryagain +.br +.I ACTION +=> +.B return +| +.B continue +| +.B merge +.RE +.P +The ! negates the test, matching all possible results except the +one specified. +The case of the keywords is not significant. +.P +The +.I STATUS +value is matched against the result of the lookup function called by +the preceding service specification, and can be one of: +.RS 4 +.TP 12 +.B success +No error occurred and the requested entry is returned. +The default action for this condition is "return". +.TP +.B notfound +The lookup succeeded, but the requested entry was not found. +The default action for this condition is "continue". +.TP +.B unavail +The service is permanently unavailable. +This can mean either that the +required file cannot be read, or, for network services, that the server +is not available or does not allow queries. +The default action for this condition is "continue". +.TP +.B tryagain +The service is temporarily unavailable. +This could mean a file is +locked or a server currently cannot accept more connections. +The default action for this condition is "continue". +.RE +.P +The +.I ACTION +value can be one of: +.RS 4 +.TP 12 +.B return +Return a result now. +Do not call any further lookup functions. +However, for compatibility reasons, if this is the selected action for the +.B group +database and the +.B notfound +status, and the configuration file does not contain the +.B initgroups +line, the next lookup function is always called, +without affecting the search result. +.TP +.B continue +Call the next lookup function. +.TP +.B merge +.I [SUCCESS=merge] +is used between two database entries. +When a group is located in the first of the two group entries, +processing will continue on to the next one. +If the group is also found in the next entry (and the group name and GID +are an exact match), the member list of the second entry will be added +to the group object to be returned. +Available since glibc 2.24. +Note that merging will not be done for +.BR getgrent (3) +nor will duplicate members be pruned when they occur in both entries +being merged. +.RE +.SS Compatibility mode (compat) +The NSS "compat" service is similar to "files" except that it +additionally permits special entries in corresponding files +for granting users or members of netgroups access to the system. +The following entries are valid in this mode: +.RS 4 +.P +For +.B passwd +and +.B shadow +databases: +.RS 4 +.TP 12 +.BI + user +Include the specified +.I user +from the NIS passwd/shadow map. +.TP +.BI +@ netgroup +Include all users in the given +.IR netgroup . +.TP +.BI \- user +Exclude the specified +.I user +from the NIS passwd/shadow map. +.TP +.BI \-@ netgroup +Exclude all users in the given +.IR netgroup . +.TP +.B + +Include every user, except previously excluded ones, from the +NIS passwd/shadow map. +.RE +.P +For +.B group +database: +.RS 4 +.TP 12 +.BI + group +Include the specified +.I group +from the NIS group map. +.TP +.BI \- group +Exclude the specified +.I group +from the NIS group map. +.TP +.B + +Include every group, except previously excluded ones, from the +NIS group map. +.RE +.RE +.P +By default, the source is "nis", but this may be +overridden by specifying any NSS service except "compat" itself +as the source for the pseudo-databases +.BR passwd_compat , +.BR group_compat , +and +.BR shadow_compat . +.SH FILES +A service named +.I SERVICE +is implemented by a shared object library named +.IB libnss_SERVICE.so. X +that resides in +.IR /lib . +.RS 4 +.TP 25 +.PD 0 +.I /etc/nsswitch.conf +NSS configuration file. +.TP +.IB /lib/libnss_compat.so. X +implements "compat" source. +.TP +.IB /lib/libnss_db.so. X +implements "db" source. +.TP +.IB /lib/libnss_dns.so. X +implements "dns" source. +.TP +.IB /lib/libnss_files.so. X +implements "files" source. +.TP +.IB /lib/libnss_hesiod.so. X +implements "hesiod" source. +.TP +.IB /lib/libnss_nis.so. X +implements "nis" source. +.TP +.IB /lib/libnss_nisplus.so. X +implements "nisplus" source. +.PD +.RE +.P +The following files are read when "files" source is specified +for respective databases: +.RS 4 +.TP 12 +.PD 0 +.B aliases +.I /etc/aliases +.TP +.B ethers +.I /etc/ethers +.TP +.B group +.I /etc/group +.TP +.B hosts +.I /etc/hosts +.TP +.B initgroups +.I /etc/group +.TP +.B netgroup +.I /etc/netgroup +.TP +.B networks +.I /etc/networks +.TP +.B passwd +.I /etc/passwd +.TP +.B protocols +.I /etc/protocols +.TP +.B publickey +.I /etc/publickey +.TP +.B rpc +.I /etc/rpc +.TP +.B services +.I /etc/services +.TP +.B shadow +.I /etc/shadow +.PD +.RE +.SH NOTES +Starting with glibc 2.33, +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=12459 +.B nsswitch.conf +is automatically reloaded if the file is changed. +In earlier versions, the entire file was read only once within each process. +If the file was later changed, +the process would continue using the old configuration. +.P +Traditionally, there was only a single source for service information, +often in the form of a single configuration +file (e.g., \fI/etc/passwd\fP). +However, as other name services, such as the Network Information +Service (NIS) and the Domain Name Service (DNS), became popular, +a method was needed +that would be more flexible than fixed search orders coded into +the C library. +The Name Service Switch mechanism, +which was based on the mechanism used by +Sun Microsystems in the Solaris 2 C library, +introduced a cleaner solution to the problem. +.SH SEE ALSO +.BR getent (1), +.BR nss (5) diff --git a/man/man5/passwd.5 b/man/man5/passwd.5 new file mode 100644 index 0000000..cd46fdf --- /dev/null +++ b/man/man5/passwd.5 @@ -0,0 +1,160 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 10:46:28 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Aug 21 18:12:27 1994 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jun 18 01:53:57 1995 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Jan 5 20:24:40 MET 1998 by Michael Haardt +.\" (michael@cantor.informatik.rwth-aachen.de) +.TH passwd 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +passwd \- password file +.SH DESCRIPTION +The +.I /etc/passwd +file is a text file that describes user login accounts for the system. +It should have read permission allowed for all users (many utilities, like +.BR ls (1) +use it to map user IDs to usernames), but write access only for the +superuser. +.P +In the good old days there was no great problem with this general +read permission. +Everybody could read the encrypted passwords, but the +hardware was too slow to crack a well-chosen password, and moreover the +basic assumption used to be that of a friendly user-community. +These days many people run some version of the shadow password suite, where +.I /etc/passwd +has an \[aq]x\[aq] character in the password field, +and the encrypted passwords are in +.IR /etc/shadow , +which is readable by the superuser only. +.P +If the encrypted password, whether in +.I /etc/passwd +or in +.IR /etc/shadow , +is an empty string, login is allowed without even asking for a password. +Note that this functionality may be intentionally disabled in applications, +or configurable (for example using the +.RB \[dq] nullok \[dq] +or +.RB \[dq] nonull \[dq] +arguments to +.BR pam_unix (8)). +.P +If the encrypted password in +.I /etc/passwd +is "\fI*NP*\fP" (without the quotes), +the shadow record should be obtained from an NIS+ server. +.P +Regardless of whether shadow passwords are used, many system administrators +use an asterisk (*) in the encrypted password field to make sure +that this user can not authenticate themself using a +password. +(But see NOTES below.) +.P +If you create a new login, first put an asterisk (*) in the password field, +then use +.BR passwd (1) +to set it. +.P +Each line of the file describes a single user, +and contains seven colon-separated fields: +.P +.in +4n +.EX +name:password:UID:GID:GECOS:directory:shell +.EE +.in +.P +The field are as follows: +.TP 12 +.I name +This is the user's login name. +It should not contain capital letters. +.TP +.I password +This is either the encrypted user password, +an asterisk (*), or the letter \[aq]x\[aq]. +(See +.BR pwconv (8) +for an explanation of \[aq]x\[aq].) +.TP +.I UID +The privileged +.I root +login account (superuser) has the user ID 0. +.TP +.I GID +This is the numeric primary group ID for this user. +(Additional groups for the user are defined in the system group file; see +.BR group (5)). +.TP +.I GECOS +This field (sometimes called the "comment field") +is optional and used only for informational purposes. +Usually, it contains the full username. +Some programs (for example, +.BR finger (1)) +display information from this field. +.IP +GECOS stands for "General Electric Comprehensive Operating System", +which was renamed to GCOS when +GE's large systems division was sold to Honeywell. +Dennis Ritchie has reported: "Sometimes we sent printer output or +batch jobs to the GCOS machine. +The gcos field in the password file was a place to stash the +information for the $IDENTcard. +Not elegant." +.TP +.I directory +This is the user's home directory: +the initial directory where the user is placed after logging in. +The value in this field is used to set the +.B HOME +environment variable. +.TP +.I shell +This is the program to run at login (if empty, use +.IR /bin/sh ). +If set to a nonexistent executable, the user will be unable to login +through +.BR login (1). +The value in this field is used to set the +.B SHELL +environment variable. +.SH FILES +.I /etc/passwd +.SH NOTES +If you want to create user groups, there must be an entry in +.IR /etc/group , +or no group will exist. +.P +If the encrypted password is set to an asterisk (*), the user will be unable +to login using +.BR login (1), +but may still login using +.BR rlogin (1), +run existing processes and initiate new ones through +.BR rsh (1), +.BR cron (8), +.BR at (1), +or mail filters, etc. +Trying to lock an account by simply changing the +shell field yields the same result and additionally allows the use of +.BR su (1). +.SH SEE ALSO +.BR chfn (1), +.BR chsh (1), +.BR login (1), +.BR passwd (1), +.BR su (1), +.BR crypt (3), +.BR getpwent (3), +.BR getpwnam (3), +.BR group (5), +.BR shadow (5), +.BR vipw (8) diff --git a/man/man5/proc.5 b/man/man5/proc.5 new file mode 100644 index 0000000..bbdf162 --- /dev/null +++ b/man/man5/proc.5 @@ -0,0 +1,266 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc 5 2024-05-19 "Linux man-pages (unreleased)" +.SH NAME +proc \- process information, system information, and sysctl pseudo-filesystem +.SH DESCRIPTION +The +.B proc +filesystem is a pseudo-filesystem which provides an interface to +kernel data structures. +It is commonly mounted at +.IR /proc . +Typically, it is mounted automatically by the system, +but it can also be mounted manually using a command such as: +.P +.in +4n +.EX +mount \-t proc proc /proc +.EE +.in +.P +Most of the files in the +.B proc +filesystem are read-only, +but some files are writable, allowing kernel variables to be changed. +.\" +.SS Mount options +The +.B proc +filesystem supports the following mount options: +.TP +.BR hidepid "=\fIn\fP (since Linux 3.3)" +.\" commit 0499680a42141d86417a8fbaa8c8db806bea1201 +This option controls who can access the information in +.IR /proc/ pid +directories. +The argument, +.IR n , +is one of the following values: +.RS +.TP 4 +0 +Everybody may access all +.IR /proc/ pid +directories. +This is the traditional behavior, +and the default if this mount option is not specified. +.TP +1 +Users may not access files and subdirectories inside any +.IR /proc/ pid +directories but their own (the +.IR /proc/ pid +directories themselves remain visible). +Sensitive files such as +.IR /proc/ pid /cmdline +and +.IR /proc/ pid /status +are now protected against other users. +This makes it impossible to learn whether any user is running a +specific program +(so long as the program doesn't otherwise reveal itself by its behavior). +.\" As an additional bonus, since +.\" .IR /proc/[pid]/cmdline +.\" is inaccessible for other users, +.\" poorly written programs passing sensitive information via +.\" program arguments are now protected against local eavesdroppers. +.TP +2 +As for mode 1, but in addition the +.IR /proc/ pid +directories belonging to other users become invisible. +This means that +.IR /proc/ pid +entries can no longer be used to discover the PIDs on the system. +This doesn't hide the fact that a process with a specific PID value exists +(it can be learned by other means, for example, by "kill \-0 $PID"), +but it hides a process's UID and GID, +which could otherwise be learned by employing +.BR stat (2) +on a +.IR /proc/ pid +directory. +This greatly complicates an attacker's task of gathering +information about running processes (e.g., discovering whether +some daemon is running with elevated privileges, +whether another user is running some sensitive program, +whether other users are running any program at all, and so on). +.TP +.BR gid "=\fIgid\fP (since Linux 3.3)" +.\" commit 0499680a42141d86417a8fbaa8c8db806bea1201 +Specifies the ID of a group whose members are authorized to +learn process information otherwise prohibited by +.B hidepid +(i.e., users in this group behave as though +.I /proc +was mounted with +.IR hidepid=0 ). +This group should be used instead of approaches such as putting +nonroot users into the +.BR sudoers (5) +file. +.RE +.TP +.BR subset = pid " (since Linux 5.8)" +.\" commit 6814ef2d992af09451bbeda4770daa204461329e +Show only the specified subset of procfs, +hiding all top level files and directories in the procfs +that are not related to tasks. +.SS Overview +Underneath +.IR /proc , +there are the following general groups of files and subdirectories: +.TP +.IR /proc/ "pid subdirectories" +Each one of these subdirectories contains files and subdirectories +exposing information about the process with the corresponding process ID. +.IP +Underneath each of the +.IR /proc/ pid +directories, a +.I task +subdirectory contains subdirectories of the form +.IR task/ tid, +which contain corresponding information about each of the threads +in the process, where +.I tid +is the kernel thread ID of the thread. +.IP +The +.IR /proc/ pid +subdirectories are visible when iterating through +.I /proc +with +.BR getdents (2) +(and thus are visible when one uses +.BR ls (1) +to view the contents of +.IR /proc ). +.TP +.IR /proc/ "tid subdirectories" +Each one of these subdirectories contains files and subdirectories +exposing information about the thread with the corresponding thread ID. +The contents of these directories are the same as the corresponding +.IR /proc/ pid /task/ tid +directories. +.IP +The +.IR /proc/ tid +subdirectories are +.I not +visible when iterating through +.I /proc +with +.BR getdents (2) +(and thus are +.I not +visible when one uses +.BR ls (1) +to view the contents of +.IR /proc ). +.TP +.I /proc/self +When a process accesses this magic symbolic link, +it resolves to the process's own +.IR /proc/ pid +directory. +.TP +.I /proc/thread\-self +When a thread accesses this magic symbolic link, +it resolves to the process's own +.IR /proc/self/task/ tid +directory. +.TP +.I /proc/[a\-z]* +Various other files and subdirectories under +.I /proc +expose system-wide information. +.P +All of the above are described in more detail in separate manpages +whose names start with +.BR proc_ . +.\" +.\" .SH FILES +.\" FIXME Describe /proc/[pid]/sessionid +.\" commit 1e0bd7550ea9cf474b1ad4c6ff5729a507f75fdc +.\" CONFIG_AUDITSYSCALL +.\" Added in Linux 2.6.25; read-only; only readable by real UID +.\" +.\" FIXME Describe /proc/[pid]/sched +.\" Added in Linux 2.6.23 +.\" CONFIG_SCHED_DEBUG, and additional fields if CONFIG_SCHEDSTATS +.\" Displays various scheduling parameters +.\" This file can be written, to reset stats +.\" The set of fields exposed by this file have changed +.\" significantly over time. +.\" commit 43ae34cb4cd650d1eb4460a8253a8e747ba052ac +.\" +.\" FIXME Describe /proc/[pid]/schedstats and +.\" /proc/[pid]/task/[tid]/schedstats +.\" Added in Linux 2.6.9 +.\" CONFIG_SCHEDSTATS +.\" FIXME Document /proc/sched_debug (since Linux 2.6.23) +.\" See also /proc/[pid]/sched +.\" FIXME 2.6.13 seems to have /proc/vmcore implemented; document this +.\" See Documentation/kdump/kdump.txt +.\" commit 666bfddbe8b8fd4fd44617d6c55193d5ac7edb29 +.\" Needs CONFIG_VMCORE +.\" +.SH NOTES +Many files contain strings (e.g., the environment and command line) +that are in the internal format, +with subfields terminated by null bytes (\[aq]\e0\[aq]). +When inspecting such files, you may find that the results are more readable +if you use a command of the following form to display them: +.P +.in +4n +.EX +.RB "$" " cat \fIfile\fP | tr \[aq]\e000\[aq] \[aq]\en\[aq]" +.EE +.in +.\" .SH ACKNOWLEDGEMENTS +.\" The material on /proc/sys/fs and /proc/sys/kernel is closely based on +.\" kernel source documentation files written by Rik van Riel. +.SH SEE ALSO +.BR cat (1), +.BR dmesg (1), +.BR find (1), +.BR free (1), +.BR htop (1), +.BR init (1), +.BR ps (1), +.BR pstree (1), +.BR tr (1), +.BR uptime (1), +.BR chroot (2), +.BR mmap (2), +.BR readlink (2), +.BR syslog (2), +.BR slabinfo (5), +.BR sysfs (5), +.BR hier (7), +.BR namespaces (7), +.BR time (7), +.BR arp (8), +.BR hdparm (8), +.BR ifconfig (8), +.BR lsmod (8), +.BR lspci (8), +.BR mount (8), +.BR netstat (8), +.BR procinfo (8), +.BR route (8), +.BR sysctl (8) +.P +The Linux kernel source files: +.IR Documentation/filesystems/proc.rst , +.IR Documentation/admin\-guide/sysctl/fs.rst , +.IR Documentation/admin\-guide/sysctl/kernel.rst , +.IR Documentation/admin\-guide/sysctl/net.rst , +and +.IR Documentation/admin\-guide/sysctl/vm.rst . diff --git a/man/man5/proc_apm.5 b/man/man5/proc_apm.5 new file mode 100644 index 0000000..295d69e --- /dev/null +++ b/man/man5/proc_apm.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_apm 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/apm \- advanced power management +.SH DESCRIPTION +.TP +.I /proc/apm +Advanced power management version and battery information when +.B CONFIG_APM +is defined at kernel compilation time. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_buddyinfo.5 b/man/man5/proc_buddyinfo.5 new file mode 100644 index 0000000..0ee9519 --- /dev/null +++ b/man/man5/proc_buddyinfo.5 @@ -0,0 +1,58 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_buddyinfo 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/buddyinfo \- memory fragmentation +.SH DESCRIPTION +.TP +.I /proc/buddyinfo +This file contains information which is used for diagnosing memory +fragmentation issues. +Each line starts with the identification of the node and the name +of the zone which together identify a memory region. +This is then +followed by the count of available chunks of a certain order in +which these zones are split. +The size in bytes of a certain order is given by the formula: +.IP +.in +4n +.EX +(2\[ha]order)\ *\ PAGE_SIZE +.EE +.in +.IP +The binary buddy allocator algorithm inside the kernel will split +one chunk into two chunks of a smaller order (thus with half the +size) or combine two contiguous chunks into one larger chunk of +a higher order (thus with double the size) to satisfy allocation +requests and to counter memory fragmentation. +The order matches the column number, when starting to count at zero. +.IP +For example on an x86-64 system: +.RS -12 +.EX +Node 0, zone DMA 1 1 1 0 2 1 1 0 1 1 3 +Node 0, zone DMA32 65 47 4 81 52 28 13 10 5 1 404 +Node 0, zone Normal 216 55 189 101 84 38 37 27 5 3 587 +.EE +.RE +.IP +In this example, there is one node containing three zones and there +are 11 different chunk sizes. +If the page size is 4 kilobytes, then the first zone called +.I DMA +(on x86 the first 16 megabyte of memory) has 1 chunk of 4 kilobytes +(order 0) available and has 3 chunks of 4 megabytes (order 10) available. +.IP +If the memory is heavily fragmented, the counters for higher +order chunks will be zero and allocation of large contiguous areas +will fail. +.IP +Further information about the zones can be found in +.IR /proc/zoneinfo . +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_bus.5 b/man/man5/proc_bus.5 new file mode 100644 index 0000000..92c27af --- /dev/null +++ b/man/man5/proc_bus.5 @@ -0,0 +1,35 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_bus 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/bus/ \- installed buses +.SH DESCRIPTION +.TP +.I /proc/bus/ +Contains subdirectories for installed buses. +.TP +.I /proc/bus/pccard/ +Subdirectory for PCMCIA devices when +.B CONFIG_PCMCIA +is set at kernel compilation time. +.TP +.I /proc/bus/pccard/drivers +.TP +.I /proc/bus/pci/ +Contains various bus subdirectories and pseudo-files containing +information about PCI buses, installed devices, and device +drivers. +Some of these files are not ASCII. +.TP +.I /proc/bus/pci/devices +Information about PCI devices. +They may be accessed through +.BR lspci (8) +and +.BR setpci (8). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_cgroups.5 b/man/man5/proc_cgroups.5 new file mode 100644 index 0000000..b0e6925 --- /dev/null +++ b/man/man5/proc_cgroups.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_cgroups 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/cgroups \- control groups +.SH DESCRIPTION +.TP +.IR /proc/cgroups " (since Linux 2.6.24)" +See +.BR cgroups (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_cmdline.5 b/man/man5/proc_cmdline.5 new file mode 100644 index 0000000..d9e55df --- /dev/null +++ b/man/man5/proc_cmdline.5 @@ -0,0 +1,22 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_cmdline 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/cmdline \- kernel boot arguments +.SH DESCRIPTION +.TP +.I /proc/cmdline +Arguments passed to the Linux kernel at boot time. +Often done via a boot manager such as +.BR lilo (8) +or +.BR grub (8). +Any arguments embedded in the kernel image or initramfs via +.B CONFIG_BOOT_CONFIG +will also be displayed. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_config.gz.5 b/man/man5/proc_config.gz.5 new file mode 100644 index 0000000..97c8241 --- /dev/null +++ b/man/man5/proc_config.gz.5 @@ -0,0 +1,40 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_config.gz 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/config.gz \- kernel build configuration +.SH DESCRIPTION +.TP +.IR /proc/config.gz " (since Linux 2.6)" +This file exposes the configuration options that were used +to build the currently running kernel, +in the same format as they would be shown in the +.I .config +file that resulted when configuring the kernel (using +.IR "make xconfig" , +.IR "make config" , +or similar). +The file contents are compressed; view or search them using +.BR zcat (1) +and +.BR zgrep (1). +As long as no changes have been made to the following file, +the contents of +.I /proc/config.gz +are the same as those provided by: +.IP +.in +4n +.EX +cat /lib/modules/$(uname \-r)/build/.config +.EE +.in +.IP +.I /proc/config.gz +is provided only if the kernel is configured with +.BR CONFIG_IKCONFIG_PROC . +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_cpuinfo.5 b/man/man5/proc_cpuinfo.5 new file mode 100644 index 0000000..8950294 --- /dev/null +++ b/man/man5/proc_cpuinfo.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_cpuinfo 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/cpuinfo \- CPU and system architecture information +.SH DESCRIPTION +.TP +.I /proc/cpuinfo +This is a collection of CPU and system architecture dependent items, +for each supported architecture a different list. +Two common entries are \fIprocessor\fP which gives CPU number and +\fIbogomips\fP; a system constant that is calculated +during kernel initialization. +SMP machines have information for +each CPU. +The +.BR lscpu (1) +command gathers its information from this file. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_crypto.5 b/man/man5/proc_crypto.5 new file mode 100644 index 0000000..2b9ed19 --- /dev/null +++ b/man/man5/proc_crypto.5 @@ -0,0 +1,26 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_crypto 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/crypto \- ciphers provided by kernel crypto API +.SH DESCRIPTION +.TP +.I /proc/crypto +A list of the ciphers provided by the kernel crypto API. +For details, see the kernel +.I "Linux Kernel Crypto API" +documentation available under the kernel source directory +.I Documentation/crypto/ +.\" commit 3b72c814a8e8cd638e1ba0da4dfce501e9dff5af +(or +.I Documentation/DocBook +before Linux 4.10; +the documentation can be built using a command such as +.I make htmldocs +in the root directory of the kernel source tree). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_devices.5 b/man/man5/proc_devices.5 new file mode 100644 index 0000000..3944337 --- /dev/null +++ b/man/man5/proc_devices.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_devices 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/devices \- major numbers and device groups +.SH DESCRIPTION +.TP +.I /proc/devices +Text listing of major numbers and device groups. +This can be used by MAKEDEV scripts for consistency with the kernel. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_diskstats.5 b/man/man5/proc_diskstats.5 new file mode 100644 index 0000000..e0af610 --- /dev/null +++ b/man/man5/proc_diskstats.5 @@ -0,0 +1,21 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_diskstats 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/diskstats \- disk I/O statistics +.SH DESCRIPTION +.TP +.IR /proc/diskstats " (since Linux 2.5.69)" +This file contains disk I/O statistics for each disk device. +See the Linux kernel source file +.I Documentation/admin\-guide/iostats.rst +(or +.I Documentation/iostats.txt +before Linux 5.3) +for further information. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_dma.5 b/man/man5/proc_dma.5 new file mode 100644 index 0000000..e769c31 --- /dev/null +++ b/man/man5/proc_dma.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_dma 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/dma \- ISA DMA channels +.SH DESCRIPTION +.TP +.I /proc/dma +This is a list of the registered \fIISA\fP DMA (direct memory access) +channels in use. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_driver.5 b/man/man5/proc_driver.5 new file mode 100644 index 0000000..f400eaf --- /dev/null +++ b/man/man5/proc_driver.5 @@ -0,0 +1,15 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_driver 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/driver/ \- empty dir +.SH DESCRIPTION +.TP +.I /proc/driver/ +Empty subdirectory. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_execdomains.5 b/man/man5/proc_execdomains.5 new file mode 100644 index 0000000..2178c1b --- /dev/null +++ b/man/man5/proc_execdomains.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_execdomains 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/execdomains \- ABI personalities (obsolete) +.SH DESCRIPTION +.TP +.I /proc/execdomains +Used to list ABI personalities before Linux 4.1; +now contains a constant string for userspace compatibility. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_fb.5 b/man/man5/proc_fb.5 new file mode 100644 index 0000000..13d28e5 --- /dev/null +++ b/man/man5/proc_fb.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_fb 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/fb \- frame buffer +.SH DESCRIPTION +.TP +.I /proc/fb +Frame buffer information when +.B CONFIG_FB +is defined during kernel compilation. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_filesystems.5 b/man/man5/proc_filesystems.5 new file mode 100644 index 0000000..ca035fe --- /dev/null +++ b/man/man5/proc_filesystems.5 @@ -0,0 +1,33 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.\" FIXME cross check against Documentation/filesystems/proc.txt +.\" to see what information could be imported from that file +.\" into this file. +.\" +.TH proc_filesystems 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/filesystems \- supported filesystems +.SH DESCRIPTION +.TP +.I /proc/filesystems +A text listing of the filesystems which are supported by the kernel, +namely filesystems which were compiled into the kernel or whose kernel +modules are currently loaded. +(See also +.BR filesystems (5).) +If a filesystem is marked with "nodev", +this means that it does not require a block device to be mounted +(e.g., virtual filesystem, network filesystem). +.IP +Incidentally, this file may be used by +.BR mount (8) +when no filesystem is specified and it didn't manage to determine the +filesystem type. +Then filesystems contained in this file are tried +(excepted those that are marked with "nodev"). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_fs.5 b/man/man5/proc_fs.5 new file mode 100644 index 0000000..ccf2310 --- /dev/null +++ b/man/man5/proc_fs.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_fs 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/fs/ \- mounted filesystems +.SH DESCRIPTION +.TP +.I /proc/fs/ +.\" FIXME Much more needs to be said about /proc/fs +.\" +Contains subdirectories that in turn contain files +with information about (certain) mounted filesystems. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_ide.5 b/man/man5/proc_ide.5 new file mode 100644 index 0000000..e78a652 --- /dev/null +++ b/man/man5/proc_ide.5 @@ -0,0 +1,37 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_ide 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/ide/ \- IDE channels and attached devices +.SH DESCRIPTION +.TP +.I /proc/ide +This directory +exists on systems with the IDE bus. +There are directories for each IDE channel and attached device. +Files include: +.IP +.in +4n +.EX +cache buffer size in KB +capacity number of sectors +driver driver version +geometry physical and logical geometry +identify in hexadecimal +media media type +model manufacturer\[aq]s model number +settings drive settings +smart_thresholds IDE disk management thresholds (in hex) +smart_values IDE disk management values (in hex) +.EE +.in +.IP +The +.BR hdparm (8) +utility provides access to this information in a friendly format. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_interrupts.5 b/man/man5/proc_interrupts.5 new file mode 100644 index 0000000..8e46baa --- /dev/null +++ b/man/man5/proc_interrupts.5 @@ -0,0 +1,22 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_interrupts 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/interrupts \- number of interrupts +.SH DESCRIPTION +.TP +.I /proc/interrupts +This is used to record the number of interrupts per CPU per IO device. +Since Linux 2.6.24, +for the i386 and x86-64 architectures, at least, this also includes +interrupts internal to the system (that is, not associated with a device +as such), such as NMI (nonmaskable interrupt), LOC (local timer interrupt), +and for SMP systems, TLB (TLB flush interrupt), RES (rescheduling +interrupt), CAL (remote function call interrupt), and possibly others. +Very easy to read formatting, done in ASCII. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_iomem.5 b/man/man5/proc_iomem.5 new file mode 100644 index 0000000..573e592 --- /dev/null +++ b/man/man5/proc_iomem.5 @@ -0,0 +1,15 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_iomem 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/iomem \- I/O memory map +.SH DESCRIPTION +.TP +.I /proc/iomem +I/O memory map in Linux 2.4. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_ioports.5 b/man/man5/proc_ioports.5 new file mode 100644 index 0000000..3f9d6b6 --- /dev/null +++ b/man/man5/proc_ioports.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_ioports 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/ioports \- I/O port regions +.SH DESCRIPTION +.TP +.I /proc/ioports +This is a list of currently registered Input-Output port regions that +are in use. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_kallsyms.5 b/man/man5/proc_kallsyms.5 new file mode 100644 index 0000000..f2c6f11 --- /dev/null +++ b/man/man5/proc_kallsyms.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kallsyms 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/kallsyms \- kernel exported symbols +.SH DESCRIPTION +.TP +.IR /proc/kallsyms " (since Linux 2.5.71)" +This holds the kernel exported symbol definitions used by the +.BR modules (X) +tools to dynamically link and bind loadable modules. +In Linux 2.5.47 and earlier, a similar file with slightly different syntax +was named +.IR ksyms . +.SH HISTORY +.TP +.IR /proc/ksyms " (Linux 1.1.23\[en]2.5.47)" +See +.IR /proc/kallsyms . +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_kcore.5 b/man/man5/proc_kcore.5 new file mode 100644 index 0000000..4f882dd --- /dev/null +++ b/man/man5/proc_kcore.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kcore 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/kcore \- physical memory +.SH DESCRIPTION +.TP +.I /proc/kcore +This file represents the physical memory of the system and is stored +in the ELF core file format. +With this pseudo-file, and an unstripped +kernel +.RI ( /usr/src/linux/vmlinux ) +binary, GDB can be used to +examine the current state of any kernel data structures. +.IP +The total length of the file is the size of physical memory (RAM) plus +4\ KiB. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_key-users.5 b/man/man5/proc_key-users.5 new file mode 100644 index 0000000..7f88ac3 --- /dev/null +++ b/man/man5/proc_key-users.5 @@ -0,0 +1 @@ +.so man5/proc_keys.5 diff --git a/man/man5/proc_keys.5 b/man/man5/proc_keys.5 new file mode 100644 index 0000000..1722b6d --- /dev/null +++ b/man/man5/proc_keys.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_keys 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/keys, /proc/key\-users \- in-kernel key management +.SH DESCRIPTION +.TP +.IR /proc/keys " (since Linux 2.6.10)" +See +.BR keyrings (7). +.TP +.IR /proc/key\-users " (since Linux 2.6.10)" +See +.BR keyrings (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_kmsg.5 b/man/man5/proc_kmsg.5 new file mode 100644 index 0000000..3e488e3 --- /dev/null +++ b/man/man5/proc_kmsg.5 @@ -0,0 +1,28 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kmsg 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/kmsg \- kernel messages +.SH DESCRIPTION +.TP +.I /proc/kmsg +This file can be used instead of the +.BR syslog (2) +system call to read kernel messages. +A process must have superuser +privileges to read this file, and only one process should read this +file. +This file should not be read if a syslog process is running +which uses the +.BR syslog (2) +system call facility to log kernel messages. +.IP +Information in this file is retrieved with the +.BR dmesg (1) +program. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_kpagecgroup.5 b/man/man5/proc_kpagecgroup.5 new file mode 100644 index 0000000..1bb9cd9 --- /dev/null +++ b/man/man5/proc_kpagecgroup.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kpagecgroup 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/kpagecgroup \- memory cgroups +.SH DESCRIPTION +.TP +.IR /proc/kpagecgroup " (since Linux 4.3)" +.\" commit 80ae2fdceba8313b0433f899bdd9c6c463291a17 +This file contains a 64-bit inode number of +the memory cgroup each page is charged to, +indexed by page frame number (see the discussion of +.IR /proc/ pid /pagemap ). +.IP +The +.I /proc/kpagecgroup +file is present only if the +.B CONFIG_MEMCG +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_kpagecount.5 b/man/man5/proc_kpagecount.5 new file mode 100644 index 0000000..81b9792 --- /dev/null +++ b/man/man5/proc_kpagecount.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kpagecount 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/kpagecount \- count of mappings of physical pages +.SH DESCRIPTION +.TP +.IR /proc/kpagecount " (since Linux 2.6.25)" +This file contains a 64-bit count of the number of +times each physical page frame is mapped, +indexed by page frame number (see the discussion of +.IR /proc/ pid /pagemap ). +.IP +The +.I /proc/kpagecount +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_kpageflags.5 b/man/man5/proc_kpageflags.5 new file mode 100644 index 0000000..e525c6e --- /dev/null +++ b/man/man5/proc_kpageflags.5 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kpageflags 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/kpageflags \- physical pages frame masks +.SH DESCRIPTION +.TP +.IR /proc/kpageflags " (since Linux 2.6.25)" +This file contains 64-bit masks corresponding to each physical page frame; +it is indexed by page frame number (see the discussion of +.IR /proc/ pid /pagemap ). +The bits are as follows: +.RS +.IP +.TS +r l l l. +0 - KPF_LOCKED +1 - KPF_ERROR +2 - KPF_REFERENCED +3 - KPF_UPTODATE +4 - KPF_DIRTY +5 - KPF_LRU +6 - KPF_ACTIVE +7 - KPF_SLAB +8 - KPF_WRITEBACK +9 - KPF_RECLAIM +10 - KPF_BUDDY +11 - KPF_MMAP (since Linux 2.6.31) +12 - KPF_ANON (since Linux 2.6.31) +13 - KPF_SWAPCACHE (since Linux 2.6.31) +14 - KPF_SWAPBACKED (since Linux 2.6.31) +15 - KPF_COMPOUND_HEAD (since Linux 2.6.31) +16 - KPF_COMPOUND_TAIL (since Linux 2.6.31) +17 - KPF_HUGE (since Linux 2.6.31) +18 - KPF_UNEVICTABLE (since Linux 2.6.31) +19 - KPF_HWPOISON (since Linux 2.6.31) +20 - KPF_NOPAGE (since Linux 2.6.31) +21 - KPF_KSM (since Linux 2.6.32) +22 - KPF_THP (since Linux 3.4) +23 - KPF_BALLOON (since Linux 3.18) +.\" KPF_BALLOON: commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +24 - KPF_ZERO_PAGE (since Linux 4.0) +.\" KPF_ZERO_PAGE: commit 56873f43abdcd574b25105867a990f067747b2f4 +25 - KPF_IDLE (since Linux 4.3) +.\" KPF_IDLE: commit f074a8f49eb87cde95ac9d040ad5e7ea4f029738 +26 - KPF_PGTABLE (since Linux 4.18) +.\" KPF_PGTABLE: commit 1d40a5ea01d53251c23c7be541d3f4a656cfc537 +.TE +.RE +.IP +For further details on the meanings of these bits, +see the kernel source file +.IR Documentation/admin\-guide/mm/pagemap.rst . +Before Linux 2.6.29, +.\" commit ad3bdefe877afb47480418fdb05ecd42842de65e +.\" commit e07a4b9217d1e97d2f3a62b6b070efdc61212110 +.BR KPF_WRITEBACK , +.BR KPF_RECLAIM , +.BR KPF_BUDDY , +and +.B KPF_LOCKED +did not report correctly. +.IP +The +.I /proc/kpageflags +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_ksyms.5 b/man/man5/proc_ksyms.5 new file mode 100644 index 0000000..e4fc2a1 --- /dev/null +++ b/man/man5/proc_ksyms.5 @@ -0,0 +1 @@ +.so man5/proc_kallsyms.5 diff --git a/man/man5/proc_loadavg.5 b/man/man5/proc_loadavg.5 new file mode 100644 index 0000000..6bc3eb2 --- /dev/null +++ b/man/man5/proc_loadavg.5 @@ -0,0 +1,27 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_loadavg 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/loadavg \- load average +.SH DESCRIPTION +.TP +.I /proc/loadavg +The first three fields in this file are load average figures +giving the number of jobs in the run queue (state R) +or waiting for disk I/O (state D) averaged over 1, 5, and 15 minutes. +They are the same as the load average numbers given by +.BR uptime (1) +and other programs. +The fourth field consists of two numbers separated by a slash (/). +The first of these is the number of currently runnable kernel +scheduling entities (processes, threads). +The value after the slash is the number of kernel scheduling entities +that currently exist on the system. +The fifth field is the PID of the process that was most +recently created on the system. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_locks.5 b/man/man5/proc_locks.5 new file mode 100644 index 0000000..9af488d --- /dev/null +++ b/man/man5/proc_locks.5 @@ -0,0 +1,122 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_locks 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/locks \- current file locks and leases +.SH DESCRIPTION +.TP +.I /proc/locks +This file shows current file locks +(\c +.BR flock (2) +and +.BR fcntl (2)) +and leases +(\c +.BR fcntl (2)). +.IP +An example of the content shown in this file is the following: +.IP +.in +4n +.EX +1: POSIX ADVISORY READ 5433 08:01:7864448 128 128 +2: FLOCK ADVISORY WRITE 2001 08:01:7864554 0 EOF +3: FLOCK ADVISORY WRITE 1568 00:2f:32388 0 EOF +4: POSIX ADVISORY WRITE 699 00:16:28457 0 EOF +5: POSIX ADVISORY WRITE 764 00:16:21448 0 0 +6: POSIX ADVISORY READ 3548 08:01:7867240 1 1 +7: POSIX ADVISORY READ 3548 08:01:7865567 1826 2335 +8: OFDLCK ADVISORY WRITE \-1 08:01:8713209 128 191 +.EE +.in +.IP +The fields shown in each line are as follows: +.RS +.IP [1] 5 +The ordinal position of the lock in the list. +.IP [2] +The lock type. +Values that may appear here include: +.RS +.TP +.B FLOCK +This is a BSD file lock created using +.BR flock (2). +.TP +.B OFDLCK +This is an open file description (OFD) lock created using +.BR fcntl (2). +.TP +.B POSIX +This is a POSIX byte-range lock created using +.BR fcntl (2). +.RE +.IP [3] +Among the strings that can appear here are the following: +.RS +.TP +.B ADVISORY +This is an advisory lock. +.TP +.B MANDATORY +This is a mandatory lock. +.RE +.IP [4] +The type of lock. +Values that can appear here are: +.RS +.TP +.B READ +This is a POSIX or OFD read lock, or a BSD shared lock. +.TP +.B WRITE +This is a POSIX or OFD write lock, or a BSD exclusive lock. +.RE +.IP [5] +The PID of the process that owns the lock. +.IP +Because OFD locks are not owned by a single process +(since multiple processes may have file descriptors that +refer to the same open file description), +the value \-1 is displayed in this field for OFD locks. +(Before Linux 4.14, +.\" commit 9d5b86ac13c573795525ecac6ed2db39ab23e2a8 +a bug meant that the PID of the process that +initially acquired the lock was displayed instead of the value \-1.) +.IP [6] +Three colon-separated subfields that identify the major and minor device +ID of the device containing the filesystem where the locked file resides, +followed by the inode number of the locked file. +.IP [7] +The byte offset of the first byte of the lock. +For BSD locks, this value is always 0. +.IP [8] +The byte offset of the last byte of the lock. +.B EOF +in this field means that the lock extends to the end of the file. +For BSD locks, the value shown is always +.IR EOF . +.RE +.IP +Since Linux 4.9, +.\" commit d67fd44f697dff293d7cdc29af929241b669affe +the list of locks shown in +.I /proc/locks +is filtered to show just the locks for the processes in the PID +namespace (see +.BR pid_namespaces (7)) +for which the +.I /proc +filesystem was mounted. +(In the initial PID namespace, +there is no filtering of the records shown in this file.) +.IP +The +.BR lslocks (8) +command provides a bit more information about each lock. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_malloc.5 b/man/man5/proc_malloc.5 new file mode 100644 index 0000000..b8ebc4a --- /dev/null +++ b/man/man5/proc_malloc.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_malloc 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/malloc \- debug malloc (obsolete) +.SH DESCRIPTION +.TP +.IR /proc/malloc " (only up to and including Linux 2.2)" +.\" It looks like this only ever did something back in 1.0 days +This file is present only if +.B CONFIG_DEBUG_MALLOC +was defined during compilation. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_meminfo.5 b/man/man5/proc_meminfo.5 new file mode 100644 index 0000000..b344155 --- /dev/null +++ b/man/man5/proc_meminfo.5 @@ -0,0 +1,327 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_meminfo 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/meminfo \- memory usage +.SH DESCRIPTION +.TP +.I /proc/meminfo +This file reports statistics about memory usage on the system. +It is used by +.BR free (1) +to report the amount of free and used memory (both physical and swap) +on the system as well as the shared memory and buffers used by the +kernel. +Each line of the file consists of a parameter name, followed by a colon, +the value of the parameter, and an option unit of measurement (e.g., "kB"). +The list below describes the parameter names and +the format specifier required to read the field value. +Except as noted below, +all of the fields have been present since at least Linux 2.6.0. +Some fields are displayed only if the kernel was configured +with various options; those dependencies are noted in the list. +.RS +.TP +.IR MemTotal " %lu" +Total usable RAM (i.e., physical RAM minus a few reserved +bits and the kernel binary code). +.TP +.IR MemFree " %lu" +The sum of +.IR LowFree + HighFree . +.TP +.IR MemAvailable " %lu (since Linux 3.14)" +An estimate of how much memory is available for starting new +applications, without swapping. +.TP +.IR Buffers " %lu" +Relatively temporary storage for raw disk blocks that +shouldn't get tremendously large (20 MB or so). +.TP +.IR Cached " %lu" +In-memory cache for files read from the disk (the page cache). +Doesn't include +.IR SwapCached . +.TP +.IR SwapCached " %lu" +Memory that once was swapped out, is swapped back in but +still also is in the swap file. +(If memory pressure is high, these pages +don't need to be swapped out again because they are already +in the swap file. +This saves I/O.) +.TP +.IR Active " %lu" +Memory that has been used more recently and usually not +reclaimed unless absolutely necessary. +.TP +.IR Inactive " %lu" +Memory which has been less recently used. +It is more eligible to be reclaimed for other purposes. +.TP +.IR Active(anon) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Inactive(anon) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Active(file) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Inactive(file) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Unevictable " %lu (since Linux 2.6.28)" +(From Linux 2.6.28 to Linux 2.6.30, +\fBCONFIG_UNEVICTABLE_LRU\fP was required.) +[To be documented.] +.TP +.IR Mlocked " %lu (since Linux 2.6.28)" +(From Linux 2.6.28 to Linux 2.6.30, +\fBCONFIG_UNEVICTABLE_LRU\fP was required.) +[To be documented.] +.TP +.IR HighTotal " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Total amount of highmem. +Highmem is all memory above \[ti]860 MB of physical memory. +Highmem areas are for use by user-space programs, +or for the page cache. +The kernel must use tricks to access +this memory, making it slower to access than lowmem. +.TP +.IR HighFree " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Amount of free highmem. +.TP +.IR LowTotal " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Total amount of lowmem. +Lowmem is memory which can be used for everything that +highmem can be used for, but it is also available for the +kernel's use for its own data structures. +Among many other things, +it is where everything from +.I Slab +is allocated. +Bad things happen when you're out of lowmem. +.TP +.IR LowFree " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Amount of free lowmem. +.TP +.IR MmapCopy " %lu (since Linux 2.6.29)" +.RB ( CONFIG_MMU +is required.) +[To be documented.] +.TP +.IR SwapTotal " %lu" +Total amount of swap space available. +.TP +.IR SwapFree " %lu" +Amount of swap space that is currently unused. +.TP +.IR Dirty " %lu" +Memory which is waiting to get written back to the disk. +.TP +.IR Writeback " %lu" +Memory which is actively being written back to the disk. +.TP +.IR AnonPages " %lu (since Linux 2.6.18)" +Non-file backed pages mapped into user-space page tables. +.TP +.IR Mapped " %lu" +Files which have been mapped into memory (with +.BR mmap (2)), +such as libraries. +.TP +.IR Shmem " %lu (since Linux 2.6.32)" +Amount of memory consumed in +.BR tmpfs (5) +filesystems. +.TP +.IR KReclaimable " %lu (since Linux 4.20)" +Kernel allocations that the kernel will attempt to reclaim +under memory pressure. +Includes +.I SReclaimable +(below), and other direct allocations with a shrinker. +.TP +.IR Slab " %lu" +In-kernel data structures cache. +(See +.BR slabinfo (5).) +.TP +.IR SReclaimable " %lu (since Linux 2.6.19)" +Part of +.IR Slab , +that might be reclaimed, such as caches. +.TP +.IR SUnreclaim " %lu (since Linux 2.6.19)" +Part of +.IR Slab , +that cannot be reclaimed on memory pressure. +.TP +.IR KernelStack " %lu (since Linux 2.6.32)" +Amount of memory allocated to kernel stacks. +.TP +.IR PageTables " %lu (since Linux 2.6.18)" +Amount of memory dedicated to the lowest level of page tables. +.TP +.IR Quicklists " %lu (since Linux 2.6.27)" +(\fBCONFIG_QUICKLIST\fP is required.) +[To be documented.] +.TP +.IR NFS_Unstable " %lu (since Linux 2.6.18)" +NFS pages sent to the server, but not yet committed to stable storage. +.TP +.IR Bounce " %lu (since Linux 2.6.18)" +Memory used for block device "bounce buffers". +.TP +.IR WritebackTmp " %lu (since Linux 2.6.26)" +Memory used by FUSE for temporary writeback buffers. +.TP +.IR CommitLimit " %lu (since Linux 2.6.10)" +This is the total amount of memory currently available to +be allocated on the system, expressed in kilobytes. +This limit is adhered to +only if strict overcommit accounting is enabled (mode 2 in +.IR /proc/sys/vm/overcommit_memory ). +The limit is calculated according to the formula described under +.IR /proc/sys/vm/overcommit_memory . +For further details, see the kernel source file +.IR Documentation/vm/overcommit\-accounting.rst . +.TP +.IR Committed_AS " %lu" +The amount of memory presently allocated on the system. +The committed memory is a sum of all of the memory which +has been allocated by processes, even if it has not been +"used" by them as of yet. +A process which allocates 1 GB of memory (using +.BR malloc (3) +or similar), but touches only 300 MB of that memory will show up +as using only 300 MB of memory even if it has the address space +allocated for the entire 1 GB. +.IP +This 1 GB is memory which has been "committed" to by the VM +and can be used at any time by the allocating application. +With strict overcommit enabled on the system (mode 2 in +.IR /proc/sys/vm/overcommit_memory ), +allocations which would exceed the +.I CommitLimit +will not be permitted. +This is useful if one needs to guarantee that processes will not +fail due to lack of memory once that memory has been successfully allocated. +.TP +.IR VmallocTotal " %lu" +Total size of vmalloc memory area. +.TP +.IR VmallocUsed " %lu" +Amount of vmalloc area which is used. +Since Linux 4.4, +.\" commit a5ad88ce8c7fae7ddc72ee49a11a75aa837788e0 +this field is no longer calculated, and is hard coded as 0. +See +.IR /proc/vmallocinfo . +.TP +.IR VmallocChunk " %lu" +Largest contiguous block of vmalloc area which is free. +Since Linux 4.4, +.\" commit a5ad88ce8c7fae7ddc72ee49a11a75aa837788e0 +this field is no longer calculated and is hard coded as 0. +See +.IR /proc/vmallocinfo . +.TP +.IR HardwareCorrupted " %lu (since Linux 2.6.32)" +(\fBCONFIG_MEMORY_FAILURE\fP is required.) +[To be documented.] +.TP +.IR LazyFree " %lu (since Linux 4.12)" +Shows the amount of memory marked by +.BR madvise (2) +.BR MADV_FREE . +.TP +.IR AnonHugePages " %lu (since Linux 2.6.38)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Non-file backed huge pages mapped into user-space page tables. +.TP +.IR ShmemHugePages " %lu (since Linux 4.8)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Memory used by shared memory (shmem) and +.BR tmpfs (5) +allocated with huge pages. +.TP +.IR ShmemPmdMapped " %lu (since Linux 4.8)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Shared memory mapped into user space with huge pages. +.TP +.IR CmaTotal " %lu (since Linux 3.1)" +Total CMA (Contiguous Memory Allocator) pages. +(\fBCONFIG_CMA\fP is required.) +.TP +.IR CmaFree " %lu (since Linux 3.1)" +Free CMA (Contiguous Memory Allocator) pages. +(\fBCONFIG_CMA\fP is required.) +.TP +.IR HugePages_Total " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The size of the pool of huge pages. +.TP +.IR HugePages_Free " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The number of huge pages in the pool that are not yet allocated. +.TP +.IR HugePages_Rsvd " %lu (since Linux 2.6.17)" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +This is the number of huge pages for +which a commitment to allocate from the pool has been made, +but no allocation has yet been made. +These reserved huge pages +guarantee that an application will be able to allocate a +huge page from the pool of huge pages at fault time. +.TP +.IR HugePages_Surp " %lu (since Linux 2.6.24)" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +This is the number of huge pages in +the pool above the value in +.IR /proc/sys/vm/nr_hugepages . +The maximum number of surplus huge pages is controlled by +.IR /proc/sys/vm/nr_overcommit_hugepages . +.TP +.IR Hugepagesize " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The size of huge pages. +.TP +.IR DirectMap4k " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 4 kB pages. +(x86.) +.TP +.IR DirectMap4M " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 4 MB pages. +(x86 with +.B CONFIG_X86_64 +or +.B CONFIG_X86_PAE +enabled.) +.TP +.IR DirectMap2M " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 2 MB pages. +(x86 with neither +.B CONFIG_X86_64 +nor +.B CONFIG_X86_PAE +enabled.) +.TP +.IR DirectMap1G " %lu (since Linux 2.6.27)" +(x86 with +.B CONFIG_X86_64 +and +.B CONFIG_X86_DIRECT_GBPAGES +enabled.) +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_modules.5 b/man/man5/proc_modules.5 new file mode 100644 index 0000000..d5d7236 --- /dev/null +++ b/man/man5/proc_modules.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_modules 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/modules \- loaded modules +.SH DESCRIPTION +.TP +.I /proc/modules +A text list of the modules that have been loaded by the system. +See also +.BR lsmod (8). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_mounts.5 b/man/man5/proc_mounts.5 new file mode 100644 index 0000000..7da5a66 --- /dev/null +++ b/man/man5/proc_mounts.5 @@ -0,0 +1 @@ +.so man5/proc_pid_mounts.5 diff --git a/man/man5/proc_mtrr.5 b/man/man5/proc_mtrr.5 new file mode 100644 index 0000000..b80ff38 --- /dev/null +++ b/man/man5/proc_mtrr.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_mtrr 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/mtrr \- memory type range registers +.SH DESCRIPTION +.TP +.I /proc/mtrr +Memory Type Range Registers. +See the Linux kernel source file +.I Documentation/x86/mtrr.rst +(or +.I Documentation/x86/mtrr.txt +.\" commit 7225e75144b9718cbbe1820d9c011c809d5773fd +before Linux 5.2, or +.I Documentation/mtrr.txt +before Linux 2.6.28) +for details. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_net.5 b/man/man5/proc_net.5 new file mode 100644 index 0000000..85a0dbd --- /dev/null +++ b/man/man5/proc_net.5 @@ -0,0 +1 @@ +.so man5/proc_pid_net.5 diff --git a/man/man5/proc_partitions.5 b/man/man5/proc_partitions.5 new file mode 100644 index 0000000..7fbe965 --- /dev/null +++ b/man/man5/proc_partitions.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_partitions 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/partitions \- major and minor numbers of partitions +.SH DESCRIPTION +.TP +.I /proc/partitions +Contains the major and minor numbers of each partition as well as the number +of 1024-byte blocks and the partition name. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pci.5 b/man/man5/proc_pci.5 new file mode 100644 index 0000000..3b60c62 --- /dev/null +++ b/man/man5/proc_pci.5 @@ -0,0 +1,28 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pci 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pci \- PCI devices +.SH DESCRIPTION +.TP +.I /proc/pci +This is a listing of all PCI devices found during kernel initialization +and their configuration. +.IP +This file has been deprecated in favor of a new +.I /proc +interface for PCI +.RI ( /proc/bus/pci ). +It became optional in Linux 2.2 (available with +.B CONFIG_PCI_OLD_PROC +set at kernel compilation). +It became once more nonoptionally enabled in Linux 2.4. +Next, it was deprecated in Linux 2.6 (still available with +.B CONFIG_PCI_LEGACY_PROC +set), and finally removed altogether since Linux 2.6.17. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid.5 b/man/man5/proc_pid.5 new file mode 100644 index 0000000..6d1f679 --- /dev/null +++ b/man/man5/proc_pid.5 @@ -0,0 +1,73 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/, /proc/self/ \- process information +.SH DESCRIPTION +.TP +.IR /proc/ pid / +There is a numerical subdirectory for each running process; the +subdirectory is named by the process ID. +Each +.IR /proc/ pid +subdirectory contains the pseudo-files and directories described below. +.IP +The files inside each +.IR /proc/ pid +directory are normally owned by the effective user and +effective group ID of the process. +However, as a security measure, the ownership is made +.I root:root +if the process's "dumpable" attribute is set to a value other than 1. +.IP +Before Linux 4.11, +.\" commit 68eb94f16227336a5773b83ecfa8290f1d6b78ce +.I root:root +meant the "global" root user ID and group ID +(i.e., UID 0 and GID 0 in the initial user namespace). +Since Linux 4.11, +if the process is in a noninitial user namespace that has a +valid mapping for user (group) ID 0 inside the namespace, then +the user (group) ownership of the files under +.IR /proc/ pid +is instead made the same as the root user (group) ID of the namespace. +This means that inside a container, +things work as expected for the container "root" user. +.IP +The process's "dumpable" attribute may change for the following reasons: +.RS +.IP \[bu] 3 +The attribute was explicitly set via the +.BR prctl (2) +.B PR_SET_DUMPABLE +operation. +.IP \[bu] +The attribute was reset to the value in the file +.I /proc/sys/fs/suid_dumpable +(described below), for the reasons described in +.BR prctl (2). +.RE +.IP +Resetting the "dumpable" attribute to 1 reverts the ownership of the +.IR /proc/ pid /* +files to the process's effective UID and GID. +Note, however, that if the effective UID or GID is subsequently modified, +then the "dumpable" attribute may be reset, as described in +.BR prctl (2). +Therefore, it may be desirable to reset the "dumpable" attribute +.I after +making any desired changes to the process's effective UID or GID. +.TP +.I /proc/self/ +This directory refers to the process accessing the +.I /proc +filesystem, +and is identical to the +.I /proc +directory named by the process ID of the same process. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_attr.5 b/man/man5/proc_pid_attr.5 new file mode 100644 index 0000000..7963e0e --- /dev/null +++ b/man/man5/proc_pid_attr.5 @@ -0,0 +1,137 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_attr 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/attr/ \- security-related attributes +.SH DESCRIPTION +.TP +.IR /proc/ pid /attr/ +.\" https://lwn.net/Articles/28222/ +.\" From: Stephen Smalley +.\" To: LKML and others +.\" Subject: [RFC][PATCH] Process Attribute API for Security Modules +.\" Date: 08 Apr 2003 16:17:52 -0400 +.\" +.\" http://www.nsa.gov/research/_files/selinux/papers/module/x362.shtml +.\" +The files in this directory provide an API for security modules. +The contents of this directory are files that can be read and written +in order to set security-related attributes. +This directory was added to support SELinux, +but the intention was that the API be general enough to support +other security modules. +For the purpose of explanation, +examples of how SELinux uses these files are provided below. +.IP +This directory is present only if the kernel was configured with +.BR CONFIG_SECURITY . +.TP +.IR /proc/ pid /attr/current " (since Linux 2.6.0)" +The contents of this file represent the current +security attributes of the process. +.IP +In SELinux, this file is used to get the security context of a process. +Prior to Linux 2.6.11, this file could not be used to set the security +context (a write was always denied), since SELinux limited process security +transitions to +.BR execve (2) +(see the description of +.IR /proc/ pid /attr/exec , +below). +Since Linux 2.6.11, SELinux lifted this restriction and began supporting +"set" operations via writes to this node if authorized by policy, +although use of this operation is only suitable for applications that are +trusted to maintain any desired separation between the old and new security +contexts. +.IP +Prior to Linux 2.6.28, SELinux did not allow threads within a +multithreaded process to set their security context via this node +as it would yield an inconsistency among the security contexts of the +threads sharing the same memory space. +Since Linux 2.6.28, SELinux lifted +this restriction and began supporting "set" operations for threads within +a multithreaded process if the new security context is bounded by the old +security context, where the bounded relation is defined in policy and +guarantees that the new security context has a subset of the permissions +of the old security context. +.IP +Other security modules may choose to support "set" operations via +writes to this node. +.TP +.IR /proc/ pid /attr/exec " (since Linux 2.6.0)" +This file represents the attributes to assign to the +process upon a subsequent +.BR execve (2). +.IP +In SELinux, +this is needed to support role/domain transitions, and +.BR execve (2) +is the preferred point to make such transitions because it offers better +control over the initialization of the process in the new security label +and the inheritance of state. +In SELinux, this attribute is reset on +.BR execve (2) +so that the new program reverts to the default behavior for any +.BR execve (2) +calls that it may make. +In SELinux, a process can set +only its own +.IR /proc/ pid /attr/exec +attribute. +.TP +.IR /proc/ pid /attr/fscreate " (since Linux 2.6.0)" +This file represents the attributes to assign to files +created by subsequent calls to +.BR open (2), +.BR mkdir (2), +.BR symlink (2), +and +.BR mknod (2) +.IP +SELinux employs this file to support creation of a file +(using the aforementioned system calls) +in a secure state, +so that there is no risk of inappropriate access being obtained +between the time of creation and the time that attributes are set. +In SELinux, this attribute is reset on +.BR execve (2), +so that the new program reverts to the default behavior for +any file creation calls it may make, but the attribute will persist +across multiple file creation calls within a program unless it is +explicitly reset. +In SELinux, a process can set only its own +.IR /proc/ pid /attr/fscreate +attribute. +.TP +.IR /proc/ pid /attr/keycreate " (since Linux 2.6.18)" +.\" commit 4eb582cf1fbd7b9e5f466e3718a59c957e75254e +If a process writes a security context into this file, +all subsequently created keys +.RB ( add_key (2)) +will be labeled with this context. +For further information, see the kernel source file +.I Documentation/security/keys/core.rst +(or file +.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 +.I Documentation/security/keys.txt +between Linux 3.0 and Linux 4.13, or +.\" commit d410fa4ef99112386de5f218dd7df7b4fca910b4 +.I Documentation/keys.txt +before Linux 3.0). +.TP +.IR /proc/ pid /attr/prev " (since Linux 2.6.0)" +This file contains the security context of the process before the last +.BR execve (2); +that is, the previous value of +.IR /proc/ pid /attr/current . +.TP +.IR /proc/ pid /attr/socketcreate " (since Linux 2.6.18)" +.\" commit 42c3e03ef6b298813557cdb997bd6db619cd65a2 +If a process writes a security context into this file, +all subsequently created sockets will be labeled with this context. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_autogroup.5 b/man/man5/proc_pid_autogroup.5 new file mode 100644 index 0000000..4c22b97 --- /dev/null +++ b/man/man5/proc_pid_autogroup.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_autogroup 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +proc_pid_autogroup \- group tasks for the scheduler +.SH DESCRIPTION +.TP +.IR /proc/ pid /autogroup " (since Linux 2.6.38)" +.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a +See +.BR sched (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_auxv.5 b/man/man5/proc_pid_auxv.5 new file mode 100644 index 0000000..8edccda --- /dev/null +++ b/man/man5/proc_pid_auxv.5 @@ -0,0 +1,27 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_auxv 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/auxv \- exec(3) information +.SH DESCRIPTION +.TP +.IR /proc/ pid /auxv " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test7 +This contains the contents of the ELF interpreter information passed +to the process at exec time. +The format is one \fIunsigned long\fP ID +plus one \fIunsigned long\fP value for each entry. +The last entry contains two zeros. +See also +.BR getauxval (3). +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_cgroup.5 b/man/man5/proc_pid_cgroup.5 new file mode 100644 index 0000000..3da0d7a --- /dev/null +++ b/man/man5/proc_pid_cgroup.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cgroup 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/cgroup \- control group +.SH DESCRIPTION +.TP +.IR /proc/ pid /cgroup " (since Linux 2.6.24)" +See +.BR cgroups (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_clear_refs.5 b/man/man5/proc_pid_clear_refs.5 new file mode 100644 index 0000000..48a5522 --- /dev/null +++ b/man/man5/proc_pid_clear_refs.5 @@ -0,0 +1,87 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_clear_refs 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/clear_refs \- reset the PG_Referenced and ACCESSED/YOUNG bits +.SH DESCRIPTION +.TP +.IR /proc/ pid /clear_refs " (since Linux 2.6.22)" +.\" commit b813e931b4c8235bb42e301096ea97dbdee3e8fe (2.6.22) +.\" commit 398499d5f3613c47f2143b8c54a04efb5d7a6da9 (2.6.32) +.\" commit 040fa02077de01c7e08fa75be6125e4ca5636011 (3.11) +.\" +.\" "Clears page referenced bits shown in smaps output" +.\" write-only, writable only by the owner of the process +.IP +This is a write-only file, writable only by owner of the process. +.IP +The following values may be written to the file: +.RS +.TP +1 (since Linux 2.6.22) +.\" Internally: CLEAR_REFS_ALL +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all the pages associated with the process. +(Before Linux 2.6.32, writing any nonzero value to this file +had this effect.) +.TP +2 (since Linux 2.6.32) +.\" Internally: CLEAR_REFS_ANON +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all anonymous pages associated with the process. +.TP +3 (since Linux 2.6.32) +.\" Internally: CLEAR_REFS_MAPPED +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all file-mapped pages associated with the process. +.RE +.IP +Clearing the PG_Referenced and ACCESSED/YOUNG bits provides a method +to measure approximately how much memory a process is using. +One first inspects the values in the "Referenced" fields +for the VMAs shown in +.IR /proc/ pid /smaps +to get an idea of the memory footprint of the +process. +One then clears the PG_Referenced and ACCESSED/YOUNG bits +and, after some measured time interval, +once again inspects the values in the "Referenced" fields +to get an idea of the change in memory footprint of the +process during the measured interval. +If one is interested only in inspecting the selected mapping types, +then the value 2 or 3 can be used instead of 1. +.IP +Further values can be written to affect different properties: +.RS +.TP +4 (since Linux 3.11) +Clear the soft-dirty bit for all the pages associated with the process. +.\" Internally: CLEAR_REFS_SOFT_DIRTY +This is used (in conjunction with +.IR /proc/ pid /pagemap ) +by the check-point restore system to discover which pages of a process +have been dirtied since the file +.IR /proc/ pid /clear_refs +was written to. +.TP +5 (since Linux 4.0) +.\" Internally: CLEAR_REFS_MM_HIWATER_RSS +Reset the peak resident set size ("high water mark") to the process's +current resident set size value. +.RE +.IP +Writing any value to +.IR /proc/ pid /clear_refs +other than those listed above has no effect. +.IP +The +.IR /proc/ pid /clear_refs +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_cmdline.5 b/man/man5/proc_pid_cmdline.5 new file mode 100644 index 0000000..9388e10 --- /dev/null +++ b/man/man5/proc_pid_cmdline.5 @@ -0,0 +1,49 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cmdline 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/cmdline \- command line +.SH DESCRIPTION +.TP +.IR /proc/ pid /cmdline +This read-only file holds the complete command line for the process, +unless the process is a zombie. +.\" In Linux 2.3.26, this also used to be true if the process was swapped out. +In the latter case, there is nothing in this file: +that is, a read on this file will return 0 characters. +.IP +For processes which are still running, +the command-line arguments appear in this file +in the same layout as they do in process memory: +If the process is well-behaved, +it is a set of strings separated by null bytes (\[aq]\e0\[aq]), +with a further null byte after the last string. +.IP +This is the common case, +but processes have the freedom to +override the memory region and +break assumptions about the contents or format of the +.IR /proc/ pid /cmdline +file. +.IP +If, after an +.BR execve (2), +the process modifies its +.I argv +strings, those changes will show up here. +This is not the same thing as modifying the +.I argv +array. +.IP +Furthermore, a process may change the memory location that this file refers via +.BR prctl (2) +operations such as +.BR PR_SET_MM_ARG_START . +.IP +Think of this file as the command line that the process wants you to see. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_comm.5 b/man/man5/proc_pid_comm.5 new file mode 100644 index 0000000..f936ed6 --- /dev/null +++ b/man/man5/proc_pid_comm.5 @@ -0,0 +1,49 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_comm 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/comm \- command name +.SH DESCRIPTION +.TP +.IR /proc/ pid /comm " (since Linux 2.6.33)" +.\" commit 4614a696bd1c3a9af3a08f0e5874830a85b889d4 +This file exposes the process's +.I comm +value\[em]that is, the command name associated with the process. +Different threads in the same process may have different +.I comm +values, accessible via +.IR /proc/ pid /task/ tid /comm . +A thread may modify its +.I comm +value, or that of any of other thread in the same thread group (see +the discussion of +.B CLONE_THREAD +in +.BR clone (2)), +by writing to the file +.IR /proc/self/task/ tid /comm . +Strings longer than +.B TASK_COMM_LEN +(16) characters (including the terminating null byte) are silently truncated. +.IP +This file provides a superset of the +.BR prctl (2) +.B PR_SET_NAME +and +.B PR_GET_NAME +operations, and is employed by +.BR pthread_setname_np (3) +when used to rename threads other than the caller. +The value in this file is used for the +.I %e +specifier in +.IR /proc/sys/kernel/core_pattern ; +see +.BR core (5). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_coredump_filter.5 b/man/man5/proc_pid_coredump_filter.5 new file mode 100644 index 0000000..770fb99 --- /dev/null +++ b/man/man5/proc_pid_coredump_filter.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_coredump_filter 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/coredump_filter \- core dump filter +.SH DESCRIPTION +.TP +.IR /proc/ pid /coredump_filter " (since Linux 2.6.23)" +See +.BR core (5). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_cpuset.5 b/man/man5/proc_pid_cpuset.5 new file mode 100644 index 0000000..380a0a9 --- /dev/null +++ b/man/man5/proc_pid_cpuset.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cpuset 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/cpuset \- CPU affinity sets +.SH DESCRIPTION +.TP +.IR /proc/ pid /cpuset " (since Linux 2.6.12)" +.\" and/proc/[pid]/task/[tid]/cpuset +See +.BR cpuset (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_cwd.5 b/man/man5/proc_pid_cwd.5 new file mode 100644 index 0000000..027176b --- /dev/null +++ b/man/man5/proc_pid_cwd.5 @@ -0,0 +1,36 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cwd 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/cwd \- symbolic link to current working directory +.SH DESCRIPTION +.TP +.IR /proc/ pid /cwd +This is a symbolic link to the current working directory of the process. +To find out the current working directory of process 20, +for instance, you can do this: +.IP +.in +4n +.EX +.RB "$" " cd /proc/20/cwd; pwd \-P" +.EE +.in +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_environ.5 b/man/man5/proc_pid_environ.5 new file mode 100644 index 0000000..efbb1a8 --- /dev/null +++ b/man/man5/proc_pid_environ.5 @@ -0,0 +1,48 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_environ 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/environ \- initial environment +.SH DESCRIPTION +.TP +.IR /proc/ pid /environ +This file contains the initial environment that was set +when the currently executing program was started via +.BR execve (2). +The entries are separated by null bytes (\[aq]\e0\[aq]), +and there may be a null byte at the end. +Thus, to print out the environment of process 1, you would do: +.IP +.in +4n +.EX +.RB "$" " cat /proc/1/environ | tr \[aq]\e000\[aq] \[aq]\en\[aq]" +.EE +.in +.IP +If, after an +.BR execve (2), +the process modifies its environment +(e.g., by calling functions such as +.BR putenv (3) +or modifying the +.BR environ (7) +variable directly), +this file will +.I not +reflect those changes. +.IP +Furthermore, a process may change the memory location that this file refers via +.BR prctl (2) +operations such as +.BR PR_SET_MM_ENV_START . +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_exe.5 b/man/man5/proc_pid_exe.5 new file mode 100644 index 0000000..dec2c90 --- /dev/null +++ b/man/man5/proc_pid_exe.5 @@ -0,0 +1,59 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_exe 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/exe \- symbolic link to program pathname +.SH DESCRIPTION +.TP +.IR /proc/ pid /exe +Under Linux 2.2 and later, this file is a symbolic link +containing the actual pathname of the executed command. +This symbolic link can be dereferenced normally; attempting to open +it will open the executable. +You can even type +.IR /proc/ pid /exe +to run another copy of the same executable that is being run by +process +.IR pid . +If the pathname has been unlinked, the symbolic link will contain the +string \[aq]\ (deleted)\[aq] appended to the original pathname. +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Under Linux 2.0 and earlier, +.IR /proc/ pid /exe +is a pointer to the binary which was executed, +and appears as a symbolic link. +A +.BR readlink (2) +call on this file under Linux 2.0 returns a string in the format: +.IP +.in +4n +.EX +[device]:inode +.EE +.in +.IP +For example, [0301]:1502 would be inode 1502 on device major 03 (IDE, +MFM, etc. drives) minor 01 (first partition on the first drive). +.IP +.BR find (1) +with the +.I \-inum +option can be used to locate the file. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_fd.5 b/man/man5/proc_pid_fd.5 new file mode 100644 index 0000000..a765b21 --- /dev/null +++ b/man/man5/proc_pid_fd.5 @@ -0,0 +1,161 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_fd 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/fd/ \- file descriptors +.SH DESCRIPTION +.TP +.IR /proc/ pid /fd/ +This is a subdirectory containing one entry for each file which the +process has open, named by its file descriptor, and which is a +symbolic link to the actual file. +Thus, 0 is standard input, 1 standard output, 2 standard error, and so on. +.IP +For file descriptors for pipes and sockets, +the entries will be symbolic links whose content is the +file type with the inode. +A +.BR readlink (2) +call on this file returns a string in the format: +.IP +.in +4n +.EX +type:[inode] +.EE +.in +.IP +For example, +.I socket:[2248868] +will be a socket and its inode is 2248868. +For sockets, that inode can be used to find more information +in one of the files under +.IR /proc/net/ . +.IP +For file descriptors that have no corresponding inode +(e.g., file descriptors produced by +.BR bpf (2), +.BR epoll_create (2), +.BR eventfd (2), +.BR inotify_init (2), +.BR perf_event_open (2), +.BR signalfd (2), +.BR timerfd_create (2), +and +.BR userfaultfd (2)), +the entry will be a symbolic link with contents of the form +.IP +.in +4n +.EX +.RI anon_inode: file-type +.EE +.in +.IP +In many cases (but not all), the +.I file-type +is surrounded by square brackets. +.IP +For example, an epoll file descriptor will have a symbolic link +whose content is the string +.IR "anon_inode:[eventpoll]" . +.IP +.\"The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this directory +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Programs that take a filename as a command-line argument, +but don't take input from standard input if no argument is supplied, +and programs that write to a file named as a command-line argument, +but don't send their output to standard output +if no argument is supplied, can nevertheless be made to use +standard input or standard output by using +.IR /proc/ pid /fd +files as command-line arguments. +For example, assuming that +.I \-i +is the flag designating an input file and +.I \-o +is the flag designating an output file: +.IP +.in +4n +.EX +.RB "$" " foobar \-i /proc/self/fd/0 \-o /proc/self/fd/1 ..." +.EE +.in +.IP +and you have a working filter. +.\" The following is not true in my tests (MTK): +.\" Note that this will not work for +.\" programs that seek on their files, as the files in the fd directory +.\" are not seekable. +.IP +.I /proc/self/fd/N +is approximately the same as +.I /dev/fd/N +in some UNIX and UNIX-like systems. +Most Linux MAKEDEV scripts symbolically link +.I /dev/fd +to +.IR /proc/self/fd , +in fact. +.IP +Most systems provide symbolic links +.IR /dev/stdin , +.IR /dev/stdout , +and +.IR /dev/stderr , +which respectively link to the files +.IR 0 , +.IR 1 , +and +.I 2 +in +.IR /proc/self/fd . +Thus the example command above could be written as: +.IP +.in +4n +.EX +.RB "$" " foobar \-i /dev/stdin \-o /dev/stdout ..." +.EE +.in +.IP +Permission to dereference or read +.RB ( readlink (2)) +the symbolic links in this directory is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Note that for file descriptors referring to inodes +(pipes and sockets, see above), +those inodes still have permission bits and ownership information +distinct from those of the +.IR /proc/ pid /fd +entry, +and that the owner may differ from the user and group IDs of the process. +An unprivileged process may lack permissions to open them, as in this example: +.IP +.in +4n +.EX +.RB "$" " echo test | sudo \-u nobody cat" +test +.RB "$" " echo test | sudo \-u nobody cat /proc/self/fd/0" +cat: /proc/self/fd/0: Permission denied +.EE +.in +.IP +File descriptor 0 refers to the pipe created by the shell +and owned by that shell's user, which is not +.IR nobody , +so +.B cat +does not have permission +to create a new file descriptor to read from that inode, +even though it can still read from its existing file descriptor 0. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_fdinfo.5 b/man/man5/proc_pid_fdinfo.5 new file mode 100644 index 0000000..3f5b370 --- /dev/null +++ b/man/man5/proc_pid_fdinfo.5 @@ -0,0 +1,300 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_fdinfo 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/fdinfo/ \- information about file descriptors +.SH DESCRIPTION +.TP +.IR /proc/ pid /fdinfo/ " (since Linux 2.6.22)" +This is a subdirectory containing one entry for each file which the +process has open, named by its file descriptor. +The files in this directory are readable only by the owner of the process. +The contents of each file can be read to obtain information +about the corresponding file descriptor. +The content depends on the type of file referred to by the +corresponding file descriptor. +.IP +For regular files and directories, we see something like: +.IP +.in +4n +.EX +.RB "$" " cat /proc/12015/fdinfo/4" +pos: 1000 +flags: 01002002 +mnt_id: 21 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.I pos +This is a decimal number showing the file offset. +.TP +.I flags +This is an octal number that displays the +file access mode and file status flags (see +.BR open (2)). +If the close-on-exec file descriptor flag is set, then +.I flags +will also include the value +.BR O_CLOEXEC . +.IP +Before Linux 3.1, +.\" commit 1117f72ea0217ba0cc19f05adbbd8b9a397f5ab7 +this field incorrectly displayed the setting of +.B O_CLOEXEC +at the time the file was opened, +rather than the current setting of the close-on-exec flag. +.TP +.I +.I mnt_id +This field, present since Linux 3.15, +.\" commit 49d063cb353265c3af701bab215ac438ca7df36d +is the ID of the mount containing this file. +See the description of +.IR /proc/ pid /mountinfo . +.RE +.IP +For eventfd file descriptors (see +.BR eventfd (2)), +we see (since Linux 3.8) +.\" commit cbac5542d48127b546a23d816380a7926eee1c25 +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +eventfd\-count: 40 +.EE +.in +.IP +.I eventfd\-count +is the current value of the eventfd counter, in hexadecimal. +.IP +For epoll file descriptors (see +.BR epoll (7)), +we see (since Linux 3.8) +.\" commit 138d22b58696c506799f8de759804083ff9effae +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +tfd: 9 events: 19 data: 74253d2500000009 +tfd: 7 events: 19 data: 74253d2500000007 +.EE +.in +.IP +Each of the lines beginning +.I tfd +describes one of the file descriptors being monitored via +the epoll file descriptor (see +.BR epoll_ctl (2) +for some details). +The +.I tfd +field is the number of the file descriptor. +The +.I events +field is a hexadecimal mask of the events being monitored for this file +descriptor. +The +.I data +field is the data value associated with this file descriptor. +.IP +For signalfd file descriptors (see +.BR signalfd (2)), +we see (since Linux 3.8) +.\" commit 138d22b58696c506799f8de759804083ff9effae +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +sigmask: 0000000000000006 +.EE +.in +.IP +.I sigmask +is the hexadecimal mask of signals that are accepted via this +signalfd file descriptor. +(In this example, bits 2 and 3 are set, corresponding to the signals +.B SIGINT +and +.BR SIGQUIT ; +see +.BR signal (7).) +.IP +For inotify file descriptors (see +.BR inotify (7)), +we see (since Linux 3.8) +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 00 +mnt_id: 11 +inotify wd:2 ino:7ef82a sdev:800001 mask:800afff ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:2af87e00220ffd73 +inotify wd:1 ino:192627 sdev:800001 mask:800afff ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:27261900802dfd73 +.EE +.in +.IP +Each of the lines beginning with "inotify" displays information about +one file or directory that is being monitored. +The fields in this line are as follows: +.RS +.TP +.I wd +A watch descriptor number (in decimal). +.TP +.I ino +The inode number of the target file (in hexadecimal). +.TP +.I sdev +The ID of the device where the target file resides (in hexadecimal). +.TP +.I mask +The mask of events being monitored for the target file (in hexadecimal). +.RE +.IP +If the kernel was built with exportfs support, the path to the target +file is exposed as a file handle, via three hexadecimal fields: +.IR fhandle\-bytes , +.IR fhandle\-type , +and +.IR f_handle . +.IP +For fanotify file descriptors (see +.BR fanotify (7)), +we see (since Linux 3.8) +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 11 +fanotify flags:0 event\-flags:88002 +fanotify ino:19264f sdev:800001 mflags:0 mask:1 ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:4f261900a82dfd73 +.EE +.in +.IP +The fourth line displays information defined when the fanotify group +was created via +.BR fanotify_init (2): +.RS +.TP +.I flags +The +.I flags +argument given to +.BR fanotify_init (2) +(expressed in hexadecimal). +.TP +.I event\-flags +The +.I event_f_flags +argument given to +.BR fanotify_init (2) +(expressed in hexadecimal). +.RE +.IP +Each additional line shown in the file contains information +about one of the marks in the fanotify group. +Most of these fields are as for inotify, except: +.RS +.TP +.I mflags +The flags associated with the mark +(expressed in hexadecimal). +.TP +.I mask +The events mask for this mark +(expressed in hexadecimal). +.TP +.I ignored_mask +The mask of events that are ignored for this mark +(expressed in hexadecimal). +.RE +.IP +For details on these fields, see +.BR fanotify_mark (2). +.IP +For timerfd file descriptors (see +.BR timerfd (2)), +we see (since Linux 3.17) +.\" commit af9c4957cf212ad9cf0bee34c95cb11de5426e85 +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02004002 +mnt_id: 13 +clockid: 0 +ticks: 0 +settime flags: 03 +it_value: (7695568592, 640020877) +it_interval: (0, 0) +.EE +.in +.RS +.TP +.I clockid +This is the numeric value of the clock ID +(corresponding to one of the +.B CLOCK_* +constants defined via +.IR ) +that is used to mark the progress of the timer (in this example, 0 is +.BR CLOCK_REALTIME ). +.TP +.I ticks +This is the number of timer expirations that have occurred, +(i.e., the value that +.BR read (2) +on it would return). +.TP +.I settime flags +This field lists the flags with which the timerfd was last armed (see +.BR timerfd_settime (2)), +in octal +(in this example, both +.B TFD_TIMER_ABSTIME +and +.B TFD_TIMER_CANCEL_ON_SET +are set). +.TP +.I it_value +This field contains the amount of time until the timer will next expire, +expressed in seconds and nanoseconds. +This is always expressed as a relative value, +regardless of whether the timer was created using the +.B TFD_TIMER_ABSTIME +flag. +.TP +.I it_interval +This field contains the interval of the timer, +in seconds and nanoseconds. +(The +.I it_value +and +.I it_interval +fields contain the values that +.BR timerfd_gettime (2) +on this file descriptor would return.) +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_gid_map.5 b/man/man5/proc_pid_gid_map.5 new file mode 100644 index 0000000..4637389 --- /dev/null +++ b/man/man5/proc_pid_gid_map.5 @@ -0,0 +1 @@ +.so man5/proc_pid_uid_map.5 diff --git a/man/man5/proc_pid_io.5 b/man/man5/proc_pid_io.5 new file mode 100644 index 0000000..493c7b8 --- /dev/null +++ b/man/man5/proc_pid_io.5 @@ -0,0 +1,100 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_io 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/io \- I/O statistics +.SH DESCRIPTION +.TP +.IR /proc/ pid /io " (since Linux 2.6.20)" +.\" commit 7c3ab7381e79dfc7db14a67c6f4f3285664e1ec2 +This file contains I/O statistics +for the process and its waited-for children, +for example: +.IP +.in +4n +.EX +.RB "#" " cat /proc/3828/io" +rchar: 323934931 +wchar: 323929600 +syscr: 632687 +syscw: 632675 +read_bytes: 0 +write_bytes: 323932160 +cancelled_write_bytes: 0 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.IR rchar ": characters read" +The number of bytes +returned by successful +.BR read (2) +and similar system calls. +.TP +.IR wchar ": characters written" +The number of bytes +returned by successful +.BR write (2) +and similar system calls. +.TP +.IR syscr ": read syscalls" +The number of "file read" system calls\[em]those from the +.BR read (2) +family, +.BR sendfile (2), +.BR copy_file_range (2), +and +.BR ioctl (2) +.BR BTRFS_IOC_ENCODED_READ [ _32 ] +(including when invoked by the kernel as part of other syscalls). +.TP +.IR syscw ": write syscalls" +The number of "file write" system calls\[em]those from the +.BR write (2) +family, +.BR sendfile (2), +.BR copy_file_range (2), +and +.BR ioctl (2) +.BR BTRFS_IOC_ENCODED_WRITE [ _32 ] +(including when invoked by the kernel as part of other syscalls). +.TP +.IR read_bytes ": bytes read" +The number of bytes really fetched from the storage layer. +This is accurate for block-backed filesystems. +.TP +.IR write_bytes ": bytes written" +The number of bytes really sent to the storage layer. +.TP +.IR cancelled_write_bytes : +The above statistics fail to account for truncation: +if a process writes 1 MB to a regular file and then removes it, +said 1 MB will not be written, but +.I will +have nevertheless been accounted as a 1 MB write. +This field represents the number of bytes "saved" from I/O writeback. +This can yield to having done negative I/O +if caches dirtied by another process are truncated. +.I cancelled_write_bytes +applies to I/O already accounted-for in +.IR write_bytes . +.RE +.IP +Permission to access this file is governed by +.BR ptrace (2) +access mode +.BR PTRACE_MODE_READ_FSCREDS . +.SH CAVEATS +These counters are not atomic: +on systems where 64-bit integer operations may tear, +a counter could be updated simultaneously with a read, +yielding an incorrect intermediate value. +.SH SEE ALSO +.BR getrusage (2), +.BR proc (5) diff --git a/man/man5/proc_pid_limits.5 b/man/man5/proc_pid_limits.5 new file mode 100644 index 0000000..f8f6012 --- /dev/null +++ b/man/man5/proc_pid_limits.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_oid_limits 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/limits \- resource limits +.SH DESCRIPTION +.TP +.IR /proc/ pid /limits " (since Linux 2.6.24)" +This file displays the soft limit, hard limit, and units of measurement +for each of the process's resource limits (see +.BR getrlimit (2)). +Up to and including Linux 2.6.35, +this file is protected to allow reading only by the real UID of the process. +Since Linux 2.6.36, +.\" commit 3036e7b490bf7878c6dae952eec5fb87b1106589 +this file is readable by all users on the system. +.\" FIXME Describe /proc/[pid]/loginuid +.\" Added in Linux 2.6.11; updating requires CAP_AUDIT_CONTROL +.\" CONFIG_AUDITSYSCALL +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_map_files.5 b/man/man5/proc_pid_map_files.5 new file mode 100644 index 0000000..27e46ff --- /dev/null +++ b/man/man5/proc_pid_map_files.5 @@ -0,0 +1,72 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_map_files 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/map_files/ \- memory-mapped files +.SH DESCRIPTION +.TP +.IR /proc/ pid /map_files/ " (since Linux 3.3)" +.\" commit 640708a2cff7f81e246243b0073c66e6ece7e53e +This subdirectory contains entries corresponding to memory-mapped +files (see +.BR mmap (2)). +Entries are named by memory region start and end +address pair (expressed as hexadecimal numbers), +and are symbolic links to the mapped files themselves. +Here is an example, +with the output wrapped and reformatted to fit on an 80-column display: +.IP +.in +4n +.EX +.RB "#" " ls \-l /proc/self/map_files/" +lr\-\-\-\-\-\-\-\-. 1 root root 64 Apr 16 21:31 + 3252e00000\-3252e20000 \-> /usr/lib64/ld\-2.15.so +\&... +.EE +.in +.IP +Although these entries are present for memory regions that were +mapped with the +.B MAP_FILE +flag, the way anonymous shared memory (regions created with the +.B MAP_ANON | MAP_SHARED +flags) +is implemented in Linux +means that such regions also appear on this directory. +Here is an example where the target file is the deleted +.I /dev/zero +one: +.IP +.in +4n +.EX +lrw\-\-\-\-\-\-\-. 1 root root 64 Apr 16 21:33 + 7fc075d2f000\-7fc075e6f000 \-> /dev/zero (deleted) +.EE +.in +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Until Linux 4.3, +.\" commit bdb4d100afe9818aebd1d98ced575c5ef143456c +this directory appeared only if the +.B CONFIG_CHECKPOINT_RESTORE +kernel configuration option was enabled. +.IP +Capabilities are required to read the contents of the symbolic links in +this directory: before Linux 5.9, the reading process requires +.B CAP_SYS_ADMIN +in the initial user namespace; +since Linux 5.9, the reading process must have either +.B CAP_SYS_ADMIN +or +.B CAP_CHECKPOINT_RESTORE +in the initial (i.e. root) user namespace. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_maps.5 b/man/man5/proc_pid_maps.5 new file mode 100644 index 0000000..1d54b4d --- /dev/null +++ b/man/man5/proc_pid_maps.5 @@ -0,0 +1,156 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_maps 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/maps \- mapped memory regions +.SH DESCRIPTION +.TP +.IR /proc/ pid /maps +A file containing the currently mapped memory regions and their access +permissions. +See +.BR mmap (2) +for some further information about memory mappings. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +The format of the file is: +.IP +.in +4n +.EX +.I "address perms offset dev inode pathname" +00400000\-00452000 r\-xp 00000000 08:02 173521 /usr/bin/dbus\-daemon +00651000\-00652000 r\-\-p 00051000 08:02 173521 /usr/bin/dbus\-daemon +00652000\-00655000 rw\-p 00052000 08:02 173521 /usr/bin/dbus\-daemon +00e03000\-00e24000 rw\-p 00000000 00:00 0 [heap] +00e24000\-011f7000 rw\-p 00000000 00:00 0 [heap] +\&... +35b1800000\-35b1820000 r\-xp 00000000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a1f000\-35b1a20000 r\-\-p 0001f000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a20000\-35b1a21000 rw\-p 00020000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a21000\-35b1a22000 rw\-p 00000000 00:00 0 +35b1c00000\-35b1dac000 r\-xp 00000000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1dac000\-35b1fac000 \-\-\-p 001ac000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1fac000\-35b1fb0000 r\-\-p 001ac000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1fb0000\-35b1fb2000 rw\-p 001b0000 08:02 135870 /usr/lib64/libc\-2.15.so +\&... +f2c6ff8c000\-7f2c7078c000 rw\-p 00000000 00:00 0 [stack:986] +\&... +7fffb2c0d000\-7fffb2c2e000 rw\-p 00000000 00:00 0 [stack] +7fffb2d48000\-7fffb2d49000 r\-xp 00000000 00:00 0 [vdso] +.EE +.in +.IP +The +.I address +field is the address space in the process that the mapping occupies. +The +.I perms +field is a set of permissions: +.IP +.in +4n +.EX +r = read +w = write +x = execute +s = shared +p = private (copy on write) +.EE +.in +.IP +The +.I offset +field is the offset into the file/whatever; +.I dev +is the device +(major:minor); +.I inode +is the inode on that device. +0 indicates that no inode is associated with the memory region, +as would be the case with BSS (uninitialized data). +.IP +The +.I pathname +field will usually be the file that is backing the mapping. +For ELF files, +you can easily coordinate with the +.I offset +field by looking at the +Offset field in the ELF program headers +.RI ( "readelf\ \-l" ). +.IP +There are additional helpful pseudo-paths: +.RS +.TP +.I [stack] +The initial process's (also known as the main thread's) stack. +.TP +.IR [stack: tid ] " (from Linux 3.4 to Linux 4.4)" +.\" commit b76437579d1344b612cf1851ae610c636cec7db0 (added) +.\" commit 65376df582174ffcec9e6471bf5b0dd79ba05e4a (removed) +A thread's stack (where the +.I tid +is a thread ID). +It corresponds to the +.IR /proc/ pid /task/ tid / +path. +This field was removed in Linux 4.5, since providing this information +for a process with large numbers of threads is expensive. +.TP +.I [vdso] +The virtual dynamically linked shared object. +See +.BR vdso (7). +.TP +.I [heap] +The process's heap. +.TP +.IR [anon: name ] " (since Linux 5.17)" +.\" Commit 9a10064f5625d5572c3626c1516e0bebc6c9fe9b +A named private anonymous mapping. +Set with +.BR prctl (2) +.BR PR_SET_VMA_ANON_NAME . +.TP +.IR [anon_shmem: name ] " (since Linux 6.2)" +.\" Commit d09e8ca6cb93bb4b97517a18fbbf7eccb0e9ff43 +A named shared anonymous mapping. +Set with +.BR prctl (2) +.BR PR_SET_VMA_ANON_NAME . +.in +.RE +.IP +If the +.I pathname +field is blank, +this is an anonymous mapping as obtained via +.BR mmap (2). +There is no easy way to coordinate this back to a process's source, +short of running it through +.BR gdb (1), +.BR strace (1), +or similar. +.IP +.I pathname +is shown unescaped except for newline characters, which are replaced +with an octal escape sequence. +As a result, it is not possible to determine whether the original +pathname contained a newline character or the literal +.I \e012 +character sequence. +.IP +If the mapping is file-backed and the file has been deleted, the string +" (deleted)" is appended to the pathname. +Note that this is ambiguous too. +.IP +Under Linux 2.0, there is no field giving pathname. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_mem.5 b/man/man5/proc_pid_mem.5 new file mode 100644 index 0000000..bde814d --- /dev/null +++ b/man/man5/proc_pid_mem.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mem 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/mem \- memory +.SH DESCRIPTION +.TP +.IR /proc/ pid /mem +This file can be used to access the pages of a process's memory through +.BR open (2), +.BR read (2), +and +.BR lseek (2). +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_mountinfo.5 b/man/man5/proc_pid_mountinfo.5 new file mode 100644 index 0000000..c43e0e6 --- /dev/null +++ b/man/man5/proc_pid_mountinfo.5 @@ -0,0 +1,124 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mountinfo 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/mountinfo \- mount information +.SH DESCRIPTION +.TP +.IR /proc/ pid /mountinfo " (since Linux 2.6.26)" +.\" This info adapted from Documentation/filesystems/proc.txt +.\" commit 2d4d4864ac08caff5c204a752bd004eed4f08760 +This file contains information about mounts +in the process's mount namespace (see +.BR mount_namespaces (7)). +It supplies various information +(e.g., propagation state, root of mount for bind mounts, +identifier for each mount and its parent) that is missing from the (older) +.IR /proc/ pid /mounts +file, and fixes various other problems with that file +(e.g., nonextensibility, +failure to distinguish per-mount versus per-superblock options). +.IP +The file contains lines of the form: +.IP +.EX +36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 \- ext3 /dev/root rw,errors=continue +(1)(2)(3) (4) (5) (6) (7) (8) (9) (10) (11) +.EE +.IP +The numbers in parentheses are labels for the descriptions below: +.RS 7 +.TP 5 +(1) +mount ID: a unique ID for the mount (may be reused after +.BR umount (2)). +.TP +(2) +parent ID: the ID of the parent mount +(or of self for the root of this mount namespace's mount tree). +.IP +If a new mount is stacked on top of a previous existing mount +(so that it hides the existing mount) at pathname P, +then the parent of the new mount is the previous mount at that location. +Thus, when looking at all the mounts stacked at a particular location, +the top-most mount is the one that is not the parent +of any other mount at the same location. +(Note, however, that this top-most mount will be accessible only if +the longest path subprefix of P that is a mount point +is not itself hidden by a stacked mount.) +.IP +If the parent mount lies outside the process's root directory (see +.BR chroot (2)), +the ID shown here won't have a corresponding record in +.I mountinfo +whose mount ID (field 1) matches this parent mount ID +(because mounts that lie outside the process's root directory +are not shown in +.IR mountinfo ). +As a special case of this point, +the process's root mount may have a parent mount +(for the initramfs filesystem) that lies +.\" Miklos Szeredi, Nov 2017: The hidden one is the initramfs, I believe +.\" mtk: In the initial mount namespace, this hidden ID has the value 0 +outside the process's root directory, +and an entry for that mount will not appear in +.IR mountinfo . +.TP +(3) +major:minor: the value of +.I st_dev +for files on this filesystem (see +.BR stat (2)). +.TP +(4) +root: the pathname of the directory in the filesystem +which forms the root of this mount. +.TP +(5) +mount point: the pathname of the mount point relative +to the process's root directory. +.TP +(6) +mount options: per-mount options (see +.BR mount (2)). +.TP +(7) +optional fields: zero or more fields of the form "tag[:value]"; see below. +.TP +(8) +separator: the end of the optional fields is marked by a single hyphen. +.TP +(9) +filesystem type: the filesystem type in the form "type[.subtype]". +.TP +(10) +mount source: filesystem-specific information or "none". +.TP +(11) +super options: per-superblock options (see +.BR mount (2)). +.RE +.IP +Currently, the possible optional fields are +.IR shared , +.IR master , +.IR propagate_from , +and +.IR unbindable . +See +.BR mount_namespaces (7) +for a description of these fields. +Parsers should ignore all unrecognized optional fields. +.IP +For more information on mount propagation see +.I Documentation/filesystems/sharedsubtree.rst +(or +.I Documentation/filesystems/sharedsubtree.txt +before Linux 5.8) +in the Linux kernel source tree. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_mounts.5 b/man/man5/proc_pid_mounts.5 new file mode 100644 index 0000000..be31873 --- /dev/null +++ b/man/man5/proc_pid_mounts.5 @@ -0,0 +1,49 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mounts 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/mounts \- mounted filesystems +.SH DESCRIPTION +.TP +.IR /proc/ pid /mounts " (since Linux 2.4.19)" +This file lists all the filesystems currently mounted in the +process's mount namespace (see +.BR mount_namespaces (7)). +The format of this file is documented in +.BR fstab (5). +.IP +Since Linux 2.6.15, this file is pollable: +after opening the file for reading, a change in this file +(i.e., a filesystem mount or unmount) causes +.BR select (2) +to mark the file descriptor as having an exceptional condition, and +.BR poll (2) +and +.BR epoll_wait (2) +mark the file as having a priority event +.RB ( POLLPRI ). +(Before Linux 2.6.30, +a change in this file was indicated by the file descriptor +being marked as readable for +.BR select (2), +and being marked as having an error condition for +.BR poll (2) +and +.BR epoll_wait (2).) +.TP +.I /proc/mounts +Before Linux 2.4.19, this file was a list +of all the filesystems currently mounted on the system. +With the introduction of per-process mount namespaces in Linux 2.4.19 (see +.BR mount_namespaces (7)), +this file became a link to +.IR /proc/self/mounts , +which lists the mounts of the process's own mount namespace. +The format of this file is documented in +.BR fstab (5). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_mountstats.5 b/man/man5/proc_pid_mountstats.5 new file mode 100644 index 0000000..7cebb4b --- /dev/null +++ b/man/man5/proc_pid_mountstats.5 @@ -0,0 +1,46 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mountstats 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/mountstats \- mount statistics +.SH DESCRIPTION +.TP +.IR /proc/ pid /mountstats " (since Linux 2.6.17)" +This file exports information (statistics, configuration information) +about the mounts in the process's mount namespace (see +.BR mount_namespaces (7)). +Lines in this file have the form: +.IP +.in +4n +.EX +device /dev/sda7 mounted on /home with fstype ext3 [stats] +( 1 ) ( 2 ) (3 ) ( 4 ) +.EE +.in +.IP +The fields in each line are: +.RS 7 +.TP 5 +(1) +The name of the mounted device +(or "nodevice" if there is no corresponding device). +.TP +(2) +The mount point within the filesystem tree. +.TP +(3) +The filesystem type. +.TP +(4) +Optional statistics and configuration information. +Currently (as at Linux 2.6.26), only NFS filesystems export +information via this field. +.RE +.IP +This file is readable only by the owner of the process. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_net.5 b/man/man5/proc_pid_net.5 new file mode 100644 index 0000000..bc5ceb3 --- /dev/null +++ b/man/man5/proc_pid_net.5 @@ -0,0 +1,298 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Alan Cox +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_net 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/net/, /proc/net/ \- network layer information +.SH DESCRIPTION +.TP +.IR /proc/ pid /net/ " (since Linux 2.6.25)" +See the description of +.IR /proc/net . +.TP +.I /proc/net/ +This directory contains various files and subdirectories containing +information about the networking layer. +The files contain ASCII structures and are, +therefore, readable with +.BR cat (1). +However, the standard +.BR netstat (8) +suite provides much cleaner access to these files. +.IP +With the advent of network namespaces, +various information relating to the network stack is virtualized (see +.BR network_namespaces (7)). +Thus, since Linux 2.6.25, +.\" commit e9720acd728a46cb40daa52c99a979f7c4ff195c +.I /proc/net +is a symbolic link to the directory +.IR /proc/self/net , +which contains the same files and directories as listed below. +However, these files and directories now expose information +for the network namespace of which the process is a member. +.TP +.I /proc/net/arp +This holds an ASCII readable dump of the kernel ARP table used for +address resolutions. +It will show both dynamically learned and preprogrammed ARP entries. +The format is: +.IP +.in +4n +.EX +IP address HW type Flags HW address Mask Device +192.168.0.50 0x1 0x2 00:50:BF:25:68:F3 * eth0 +192.168.0.250 0x1 0xc 00:00:00:00:00:00 * eth0 +.EE +.in +.IP +Here "IP address" is the IPv4 address of the machine and the "HW type" +is the hardware type of the address from RFC\ 826. +The flags are the internal +flags of the ARP structure (as defined in +.IR /usr/include/linux/if_arp.h ) +and +the "HW address" is the data link layer mapping for that IP address if +it is known. +.TP +.I /proc/net/dev +The dev pseudo-file contains network device status information. +This gives +the number of received and sent packets, the number of errors and +collisions +and other basic statistics. +These are used by the +.BR ifconfig (8) +program to report device status. +The format is: +.IP +.EX +Inter\-| Receive | Transmit + face |bytes packets errs drop fifo frame compressed multicast|bytes packets errs drop fifo colls carrier compressed + lo: 2776770 11307 0 0 0 0 0 0 2776770 11307 0 0 0 0 0 0 + eth0: 1215645 2751 0 0 0 0 0 0 1782404 4324 0 0 0 427 0 0 + ppp0: 1622270 5552 1 0 0 0 0 0 354130 5669 0 0 0 0 0 0 + tap0: 7714 81 0 0 0 0 0 0 7714 81 0 0 0 0 0 0 +.EE +.\" .TP +.\" .I /proc/net/ipx +.\" No information. +.\" .TP +.\" .I /proc/net/ipx_route +.\" No information. +.TP +.I /proc/net/dev_mcast +Defined in +.IR /usr/src/linux/net/core/dev_mcast.c : +.IP +.in +4n +.EX +indx interface_name dmi_u dmi_g dmi_address +2 eth0 1 0 01005e000001 +3 eth1 1 0 01005e000001 +4 eth2 1 0 01005e000001 +.EE +.in +.TP +.I /proc/net/igmp +Internet Group Management Protocol. +Defined in +.IR /usr/src/linux/net/core/igmp.c . +.TP +.I /proc/net/rarp +This file uses the same format as the +.I arp +file and contains the current reverse mapping database used to provide +.BR rarp (8) +reverse address lookup services. +If RARP is not configured into the +kernel, +this file will not be present. +.TP +.I /proc/net/raw +Holds a dump of the RAW socket table. +Much of the information is not of +use +apart from debugging. +The "sl" value is the kernel hash slot for the +socket, +the "local_address" is the local address and protocol number pair. +\&"St" is +the internal status of the socket. +The "tx_queue" and "rx_queue" are the +outgoing and incoming data queue in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields are not used by RAW. +The "uid" +field holds the effective UID of the creator of the socket. +.\" .TP +.\" .I /proc/net/route +.\" No information, but looks similar to +.\" .BR route (8). +.TP +.I /proc/net/snmp +This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP +management +information bases for an SNMP agent. +.TP +.I /proc/net/tcp +Holds a dump of the TCP socket table. +Much of the information is not +of use apart from debugging. +The "sl" value is the kernel hash slot +for the socket, the "local_address" is the local address and port number pair. +The "rem_address" is the remote address and port number pair +(if connected). +\&"St" is the internal status of the socket. +The "tx_queue" and "rx_queue" are the +outgoing and incoming data queue in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields hold internal information of +the kernel socket state and are useful only for debugging. +The "uid" +field holds the effective UID of the creator of the socket. +.TP +.I /proc/net/udp +Holds a dump of the UDP socket table. +Much of the information is not of +use apart from debugging. +The "sl" value is the kernel hash slot for the +socket, the "local_address" is the local address and port number pair. +The "rem_address" is the remote address and port number pair +(if connected). +"St" is the internal status of the socket. +The "tx_queue" and "rx_queue" are the outgoing and incoming data queue +in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields +are not used by UDP. +The "uid" +field holds the effective UID of the creator of the socket. +The format is: +.IP +.EX +sl local_address rem_address st tx_queue rx_queue tr rexmits tm\->when uid + 1: 01642C89:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 0 + 1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 0 + 1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 +.EE +.TP +.I /proc/net/unix +Lists the UNIX domain sockets present within the system and their +status. +The format is: +.IP +.EX +Num RefCount Protocol Flags Type St Inode Path + 0: 00000002 00000000 00000000 0001 03 42 + 1: 00000001 00000000 00010000 0001 01 1948 /dev/printer +.EE +.IP +The fields are as follows: +.RS +.TP 10 +.IR Num : +the kernel table slot number. +.TP +.IR RefCount : +the number of users of the socket. +.TP +.IR Protocol : +currently always 0. +.TP +.IR Flags : +the internal kernel flags holding the status of the socket. +.TP +.IR Type : +the socket type. +For +.B SOCK_STREAM +sockets, this is 0001; for +.B SOCK_DGRAM +sockets, it is 0002; and for +.B SOCK_SEQPACKET +sockets, it is 0005. +.TP +.IR St : +the internal state of the socket. +.TP +.IR Inode : +the inode number of the socket. +.TP +.IR Path : +the bound pathname (if any) of the socket. +Sockets in the abstract namespace are included in the list, +and are shown with a +.I Path +that commences with the character '@'. +.RE +.TP +.I /proc/net/netfilter/nfnetlink_queue +This file contains information about netfilter user-space queueing, if used. +Each line represents a queue. +Queues that have not been subscribed to +by user space are not shown. +.IP +.in +4n +.EX + 1 4207 0 2 65535 0 0 0 1 + (1) (2) (3)(4) (5) (6) (7) (8) +.EE +.in +.IP +The fields in each line are: +.RS 7 +.TP 5 +(1) +The ID of the queue. +This matches what is specified in the +.B \-\-queue\-num +or +.B \-\-queue\-balance +options to the +.BR iptables (8) +NFQUEUE target. +See +.BR iptables\-extensions (8) +for more information. +.TP +(2) +The netlink port ID subscribed to the queue. +.TP +(3) +The number of packets currently queued and waiting to be processed by +the application. +.TP +(4) +The copy mode of the queue. +It is either 1 (metadata only) or 2 +(also copy payload data to user space). +.TP +(5) +Copy range; that is, how many bytes of packet payload should be copied to +user space at most. +.TP +(6) +queue dropped. +Number of packets that had to be dropped by the kernel because +too many packets are already waiting for user space to send back the mandatory +accept/drop verdicts. +.TP +(7) +queue user dropped. +Number of packets that were dropped within the netlink +subsystem. +Such drops usually happen when the corresponding socket buffer is +full; that is, user space is not able to read messages fast enough. +.TP +(8) +sequence number. +Every queued packet is associated with a (32-bit) +monotonically increasing sequence number. +This shows the ID of the most recent packet queued. +.RE +.IP +The last number exists only for compatibility reasons and is always 1. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_ns.5 b/man/man5/proc_pid_ns.5 new file mode 100644 index 0000000..954ea6f --- /dev/null +++ b/man/man5/proc_pid_ns.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_ns 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/ns/ \- namespaces +.SH DESCRIPTION +.TP +.IR /proc/ pid /ns/ " (since Linux 3.0)" +.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f +This is a subdirectory containing one entry for each namespace that +supports being manipulated by +.BR setns (2). +For more information, see +.BR namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_numa_maps.5 b/man/man5/proc_pid_numa_maps.5 new file mode 100644 index 0000000..b1baafb --- /dev/null +++ b/man/man5/proc_pid_numa_maps.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_numa_maps 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/numa_maps \- NUMA memory policy and allocation +.SH DESCRIPTION +.TP +.IR /proc/ pid /numa_maps " (since Linux 2.6.14)" +See +.BR numa (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_oom_adj.5 b/man/man5/proc_pid_oom_adj.5 new file mode 100644 index 0000000..5112044 --- /dev/null +++ b/man/man5/proc_pid_oom_adj.5 @@ -0,0 +1 @@ +.so man5/proc_pid_oom_score_adj.5 diff --git a/man/man5/proc_pid_oom_score.5 b/man/man5/proc_pid_oom_score.5 new file mode 100644 index 0000000..e187d28 --- /dev/null +++ b/man/man5/proc_pid_oom_score.5 @@ -0,0 +1,58 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_oom_score 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/oom_score \- OOM-killer score +.SH DESCRIPTION +.TP +.IR /proc/ pid /oom_score " (since Linux 2.6.11)" +.\" See mm/oom_kill.c::badness() before Linux 2.6.36 sources +.\" See mm/oom_kill.c::oom_badness() after Linux 2.6.36 +.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 +This file displays the current score that the kernel gives to +this process for the purpose of selecting a process +for the OOM-killer. +A higher score means that the process is more likely to be +selected by the OOM-killer. +The basis for this score is the amount of memory used by the process, +with increases (+) or decreases (\-) for factors including: +.\" See mm/oom_kill.c::badness() before Linux 2.6.36 sources +.\" See mm/oom_kill.c::oom_badness() after Linux 2.6.36 +.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 +.RS +.IP \[bu] 3 +whether the process is privileged (\-). +.\" More precisely, if it has CAP_SYS_ADMIN or (pre 2.6.36) CAP_SYS_RESOURCE +.RE +.IP +Before Linux 2.6.36 +the following factors were also used in the calculation of oom_score: +.RS +.IP \[bu] 3 +whether the process creates a lot of children using +.BR fork (2) +(+); +.IP \[bu] +whether the process has been running a long time, +or has used a lot of CPU time (\-); +.IP \[bu] +whether the process has a low nice value (i.e., > 0) (+); and +.IP \[bu] +whether the process is making direct hardware access (\-). +.\" More precisely, if it has CAP_SYS_RAWIO +.RE +.IP +The +.I oom_score +also reflects the adjustment specified by the +.I oom_score_adj +or +.I oom_adj +setting for the process. +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_oom_score_adj (5) diff --git a/man/man5/proc_pid_oom_score_adj.5 b/man/man5/proc_pid_oom_score_adj.5 new file mode 100644 index 0000000..82e4a66 --- /dev/null +++ b/man/man5/proc_pid_oom_score_adj.5 @@ -0,0 +1,117 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_oom_score_adj 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/oom_score_adj \- OOM-killer score adjustment +.SH DESCRIPTION +.TP +.IR /proc/ pid /oom_score_adj " (since Linux 2.6.36)" +.\" Text taken from Linux 3.7 Documentation/filesystems/proc.txt +This file can be used to adjust the badness heuristic used to select which +process gets killed in out-of-memory conditions. +.IP +The badness heuristic assigns a value to each candidate task ranging from 0 +(never kill) to 1000 (always kill) to determine which process is targeted. +The units are roughly a proportion along that range of +allowed memory the process may allocate from, +based on an estimation of its current memory and swap use. +For example, if a task is using all allowed memory, +its badness score will be 1000. +If it is using half of its allowed memory, its score will be 500. +.IP +There is an additional factor included in the badness score: root +processes are given 3% extra memory over other tasks. +.IP +The amount of "allowed" memory depends on the context +in which the OOM-killer was called. +If it is due to the memory assigned to the allocating task's cpuset +being exhausted, +the allowed memory represents the set of mems assigned to that +cpuset (see +.BR cpuset (7)). +If it is due to a mempolicy's node(s) being exhausted, +the allowed memory represents the set of mempolicy nodes. +If it is due to a memory limit (or swap limit) being reached, +the allowed memory is that configured limit. +Finally, if it is due to the entire system being out of memory, the +allowed memory represents all allocatable resources. +.IP +The value of +.I oom_score_adj +is added to the badness score before it +is used to determine which task to kill. +Acceptable values range from \-1000 +(OOM_SCORE_ADJ_MIN) to +1000 (OOM_SCORE_ADJ_MAX). +This allows user space to control the preference for OOM-killing, +ranging from always preferring a certain +task or completely disabling it from OOM-killing. +The lowest possible value, \-1000, is +equivalent to disabling OOM-killing entirely for that task, +since it will always report a badness score of 0. +.IP +Consequently, it is very simple for user space to define +the amount of memory to consider for each task. +Setting an +.I oom_score_adj +value of +500, for example, +is roughly equivalent to allowing the remainder of tasks sharing the +same system, cpuset, mempolicy, or memory controller resources +to use at least 50% more memory. +A value of \-500, on the other hand, would be roughly +equivalent to discounting 50% of the task's +allowed memory from being considered as scoring against the task. +.IP +For backward compatibility with previous kernels, +.IR /proc/ pid /oom_adj +can still be used to tune the badness score. +Its value is +scaled linearly with +.IR oom_score_adj . +.IP +Writing to +.IR /proc/ pid /oom_score_adj +or +.IR /proc/ pid /oom_adj +will change the other with its scaled value. +.IP +The +.BR choom (1) +program provides a command-line interface for adjusting the +.I oom_score_adj +value of a running process or a newly executed command. +.SH HISTORY +.TP +.IR /proc/ pid /oom_adj " (since Linux 2.6.11)" +This file can be used to adjust the score used to select which process +should be killed in an out-of-memory (OOM) situation. +The kernel uses this value for a bit-shift operation of the process's +.I oom_score +value: +valid values are in the range \-16 to +15, +plus the special value \-17, +which disables OOM-killing altogether for this process. +A positive score increases the likelihood of this +process being killed by the OOM-killer; +a negative score decreases the likelihood. +.IP +The default value for this file is 0; +a new process inherits its parent's +.I oom_adj +setting. +A process must be privileged +.RB ( CAP_SYS_RESOURCE ) +to update this file, +although a process can always increase its own +.I oom_adj +setting (since Linux 2.6.20). +.IP +Since Linux 2.6.36, use of this file is deprecated in favor of +.IR /proc/ pid /oom_score_adj , +and finally removed in Linux 3.7. +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_oom_score (5) diff --git a/man/man5/proc_pid_pagemap.5 b/man/man5/proc_pid_pagemap.5 new file mode 100644 index 0000000..87cb7e7 --- /dev/null +++ b/man/man5/proc_pid_pagemap.5 @@ -0,0 +1,77 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_pagemap 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/pagemap \- mapping of virtual pages +.SH DESCRIPTION +.TP +.IR /proc/ pid /pagemap " (since Linux 2.6.25)" +This file shows the mapping of each of the process's virtual pages +into physical page frames or swap area. +It contains one 64-bit value for each virtual page, +with the bits set as follows: +.RS +.TP +63 +If set, the page is present in RAM. +.TP +62 +If set, the page is in swap space +.TP +61 (since Linux 3.5) +The page is a file-mapped page or a shared anonymous page. +.TP +60\[en]58 (since Linux 3.11) +Zero +.\" Not quite true; see commit 541c237c0923f567c9c4cabb8a81635baadc713f +.TP +57 (since Linux 5.14) +If set, the page is write-protected through +.BR userfaultfd (2). +.TP +56 (since Linux 4.2) +.\" commit 77bb499bb60f4b79cca7d139c8041662860fcf87 +.\" commit 83b4b0bb635eee2b8e075062e4e008d1bc110ed7 +The page is exclusively mapped. +.TP +55 (since Linux 3.11) +PTE is soft-dirty +(see the kernel source file +.IR Documentation/admin\-guide/mm/soft\-dirty.rst ). +.TP +54\[en]0 +If the page is present in RAM (bit 63), then these bits +provide the page frame number, which can be used to index +.I /proc/kpageflags +and +.IR /proc/kpagecount . +If the page is present in swap (bit 62), +then bits 4\[en]0 give the swap type, and bits 54\[en]5 encode the swap offset. +.RE +.IP +Before Linux 3.11, bits 60\[en]55 were +used to encode the base-2 log of the page size. +.IP +To employ +.IR /proc/ pid /pagemap +efficiently, use +.IR /proc/ pid /maps +to determine which areas of memory are actually mapped and seek +to skip over unmapped regions. +.IP +The +.IR /proc/ pid /pagemap +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_personality.5 b/man/man5/proc_pid_personality.5 new file mode 100644 index 0000000..7e72688 --- /dev/null +++ b/man/man5/proc_pid_personality.5 @@ -0,0 +1,23 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_personality 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/personality \- execution domain +.SH DESCRIPTION +.TP +.IR /proc/ pid /personality " (since Linux 2.6.28)" +.\" commit 478307230810d7e2a753ed220db9066dfdf88718 +This read-only file exposes the process's execution domain, as set by +.BR personality (2). +The value is displayed in hexadecimal notation. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_projid_map.5 b/man/man5/proc_pid_projid_map.5 new file mode 100644 index 0000000..d8dafcc --- /dev/null +++ b/man/man5/proc_pid_projid_map.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_projid_map 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/projid_map \- project ID mappings +.SH DESCRIPTION +.TP +.IR /proc/ pid /projid_map " (since Linux 3.7)" +.\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_root.5 b/man/man5/proc_pid_root.5 new file mode 100644 index 0000000..84f361f --- /dev/null +++ b/man/man5/proc_pid_root.5 @@ -0,0 +1,75 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_root 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/root/ \- symbolic link to root directory +.SH DESCRIPTION +.TP +.IR /proc/ pid /root/ +UNIX and Linux support the idea of a per-process root of the +filesystem, set by the +.BR chroot (2) +system call. +This file is a symbolic link that points to the process's +root directory, and behaves in the same way as +.IR exe , +and +.IR fd/* . +.IP +Note however that this file is not merely a symbolic link. +It provides the same view of the filesystem (including namespaces and the +set of per-process mounts) as the process itself. +An example illustrates this point. +In one terminal, we start a shell in new user and mount namespaces, +and in that shell we create some new mounts: +.IP +.in +4n +.EX +$ \fBPS1=\[aq]sh1# \[aq] unshare \-Urnm\fP +sh1# \fBmount \-t tmpfs tmpfs /etc\fP # Mount empty tmpfs at /etc +sh1# \fBmount \-\-bind /usr /dev\fP # Mount /usr at /dev +sh1# \fBecho $$\fP +27123 +.EE +.in +.IP +In a second terminal window, in the initial mount namespace, +we look at the contents of the corresponding mounts in +the initial and new namespaces: +.IP +.in +4n +.EX +$ \fBPS1=\[aq]sh2# \[aq] sudo sh\fP +sh2# \fBls /etc | wc \-l\fP # In initial NS +309 +sh2# \fBls /proc/27123/root/etc | wc \-l\fP # /etc in other NS +0 # The empty tmpfs dir +sh2# \fBls /dev | wc \-l\fP # In initial NS +205 +sh2# \fBls /proc/27123/root/dev | wc \-l\fP # /dev in other NS +11 # Actually bind + # mounted to /usr +sh2# \fBls /usr | wc \-l\fP # /usr in initial NS +11 +.EE +.in +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of the +.IR /proc/ pid /root +symbolic link are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_seccomp.5 b/man/man5/proc_pid_seccomp.5 new file mode 100644 index 0000000..08864b7 --- /dev/null +++ b/man/man5/proc_pid_seccomp.5 @@ -0,0 +1,36 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_seccomp 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/seccomp \- secure computing mode +.SH DESCRIPTION +.TP +.IR /proc/ pid /seccomp " (Linux 2.6.12 to Linux 2.6.22)" +This file can be used to read and change the process's +secure computing (seccomp) mode setting. +It contains the value 0 if the process is not in seccomp mode, +and 1 if the process is in strict seccomp mode (see +.BR seccomp (2)). +Writing 1 to this file places the process irreversibly in strict seccomp mode. +(Further attempts to write to the file fail with the +.B EPERM +error.) +.IP +In Linux 2.6.23, +this file went away, to be replaced by the +.BR prctl (2) +.B PR_GET_SECCOMP +and +.B PR_SET_SECCOMP +operations (and later by +.BR seccomp (2) +and the +.I Seccomp +field in +.IR /proc/ pid /status ). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_setgroups.5 b/man/man5/proc_pid_setgroups.5 new file mode 100644 index 0000000..f912e42 --- /dev/null +++ b/man/man5/proc_pid_setgroups.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_setgroups 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/setgroups \- allow or deny setting groups +.SH DESCRIPTION +.TP +.IR /proc/ pid /setgroups " (since Linux 3.19)" +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_smaps.5 b/man/man5/proc_pid_smaps.5 new file mode 100644 index 0000000..0ebb543 --- /dev/null +++ b/man/man5/proc_pid_smaps.5 @@ -0,0 +1,129 @@ +'\" t +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_smaps 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/smaps \- XXX: What does 's' in "smaps" stand for? +.SH DESCRIPTION +.TP +.IR /proc/ pid /smaps " (since Linux 2.6.14)" +This file shows memory consumption for each of the process's mappings. +(The +.BR pmap (1) +command displays similar information, +in a form that may be easier for parsing.) +For each mapping there is a series of lines such as the following: +.IP +.in +4n +.EX +00400000\-0048a000 r\-xp 00000000 fd:03 960637 /bin/bash +Size: 552 kB +Rss: 460 kB +Pss: 100 kB +Shared_Clean: 452 kB +Shared_Dirty: 0 kB +Private_Clean: 8 kB +Private_Dirty: 0 kB +Referenced: 460 kB +Anonymous: 0 kB +AnonHugePages: 0 kB +ShmemHugePages: 0 kB +ShmemPmdMapped: 0 kB +Swap: 0 kB +KernelPageSize: 4 kB +MMUPageSize: 4 kB +Locked: 0 kB +ProtectionKey: 0 +VmFlags: rd ex mr mw me dw +.EE +.in +.IP +The first of these lines shows the same information as is displayed +for the mapping in +.IR /proc/ pid /maps . +The following lines show the size of the mapping, +the amount of the mapping that is currently resident in RAM ("Rss"), +the process's proportional share of this mapping ("Pss"), +the number of clean and dirty shared pages in the mapping, +and the number of clean and dirty private pages in the mapping. +"Referenced" indicates the amount of memory currently marked as +referenced or accessed. +"Anonymous" shows the amount of memory +that does not belong to any file. +"Swap" shows how much +would-be-anonymous memory is also used, but out on swap. +.IP +The "KernelPageSize" line (available since Linux 2.6.29) +is the page size used by the kernel to back the virtual memory area. +This matches the size used by the MMU in the majority of cases. +However, one counter-example occurs on PPC64 kernels +whereby a kernel using 64 kB as a base page size may still use 4 kB +pages for the MMU on older processors. +To distinguish the two attributes, the "MMUPageSize" line +(also available since Linux 2.6.29) +reports the page size used by the MMU. +.IP +The "Locked" indicates whether the mapping is locked in memory +or not. +.IP +The "ProtectionKey" line (available since Linux 4.9, on x86 only) +contains the memory protection key (see +.BR pkeys (7)) +associated with the virtual memory area. +This entry is present only if the kernel was built with the +.B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS +configuration option (since Linux 4.6). +.IP +The "VmFlags" line (available since Linux 3.8) +represents the kernel flags associated with the virtual memory area, +encoded using the following two-letter codes: +.RS +.IP +.TS +l l l. +rd - readable +wr - writable +ex - executable +sh - shared +mr - may read +mw - may write +me - may execute +ms - may share +gd - stack segment grows down +pf - pure PFN range +dw - disabled write to the mapped file +lo - pages are locked in memory +io - memory mapped I/O area +sr - sequential read advise provided +rr - random read advise provided +dc - do not copy area on fork +de - do not expand area on remapping +ac - area is accountable +nr - swap space is not reserved for the area +ht - area uses huge tlb pages +sf - perform synchronous page faults (since Linux 4.15) +nl - non-linear mapping (removed in Linux 4.0) +ar - architecture specific flag +wf - wipe on fork (since Linux 4.14) +dd - do not include area into core dump +sd - soft-dirty flag (since Linux 3.13) +mm - mixed map area +hg - huge page advise flag +nh - no-huge page advise flag +mg - mergeable advise flag +um - userfaultfd missing pages tracking (since Linux 4.3) +uw - userfaultfd wprotect pages tracking (since Linux 4.3) +.TE +.RE +.IP +The +.IR /proc/ pid /smaps +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_stack.5 b/man/man5/proc_pid_stack.5 new file mode 100644 index 0000000..75c6e7f --- /dev/null +++ b/man/man5/proc_pid_stack.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_stack 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/stack \- kernel stack +.SH DESCRIPTION +.TP +.IR /proc/ pid /stack " (since Linux 2.6.29)" +.\" 2ec220e27f5040aec1e88901c1b6ea3d135787ad +This file provides a symbolic trace of the function calls in this +process's kernel stack. +This file is provided only if the kernel was built with the +.B CONFIG_STACKTRACE +configuration option. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_stat.5 b/man/man5/proc_pid_stat.5 new file mode 100644 index 0000000..6cd2978 --- /dev/null +++ b/man/man5/proc_pid_stat.5 @@ -0,0 +1,380 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_stat 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/stat \- status information +.SH DESCRIPTION +.TP +.IR /proc/ pid /stat +Status information about the process. +This is used by +.BR ps (1). +It is defined in the kernel source file +.IR fs/proc/array.c "." +.IP +The fields, in order, with their proper +.BR scanf (3) +format specifiers, are listed below. +Whether or not certain of these fields display valid information is governed by +a ptrace access mode +.BR PTRACE_MODE_READ_FSCREDS " | " PTRACE_MODE_NOAUDIT +check (refer to +.BR ptrace (2)). +If the check denies access, then the field value is displayed as 0. +The affected fields are indicated with the marking [PT]. +.RS +.TP +(1) \fIpid\fP \ %d +.br +The process ID. +.TP +(2) \fIcomm\fP \ %s +The filename of the executable, in parentheses. +Strings longer than +.B TASK_COMM_LEN +(16) characters (including the terminating null byte) are silently truncated. +This is visible whether or not the executable is swapped out. +.TP +(3) \fIstate\fP \ %c +One of the following characters, indicating process state: +.RS +.TP +R +Running +.TP +S +Sleeping in an interruptible wait +.TP +D +Waiting in uninterruptible +disk sleep +.TP +Z +Zombie +.TP +T +Stopped (on a signal) or (before Linux 2.6.33) trace stopped +.TP +t +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Tracing stop (Linux 2.6.33 onward) +.TP +W +Paging (only before Linux 2.6.0) +.TP +X +Dead (from Linux 2.6.0 onward) +.TP +x +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Dead (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +K +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Wakekill (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +W +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Waking (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +P +.\" commit f2530dc71cf0822f90bb63ea4600caaef33a66bb +Parked (Linux 3.9 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +I +.\" commit 06eb61844d841d0032a9950ce7f8e783ee49c0d0 +Idle (Linux 4.14 onward) +.RE +.TP +(4) \fIppid\fP \ %d +The PID of the parent of this process. +.TP +(5) \fIpgrp\fP \ %d +The process group ID of the process. +.TP +(6) \fIsession\fP \ %d +The session ID of the process. +.TP +(7) \fItty_nr\fP \ %d +The controlling terminal of the process. +(The minor device number is contained in the combination of bits +31 to 20 and 7 to 0; +the major device number is in bits 15 to 8.) +.TP +(8) \fItpgid\fP \ %d +.\" This field and following, up to and including wchan added 0.99.1 +The ID of the foreground process group of the controlling +terminal of the process. +.TP +(9) \fIflags\fP \ %u +The kernel flags word of the process. +For bit meanings, +see the PF_* defines in the Linux kernel source file +.IR include/linux/sched.h . +Details depend on the kernel version. +.IP +The format for this field was %lu before Linux 2.6. +.TP +(10) \fIminflt\fP \ %lu +The number of minor faults the process has made which have not +required loading a memory page from disk. +.TP +(11) \fIcminflt\fP \ %lu +The number of minor faults that the process's +waited-for children have made. +.TP +(12) \fImajflt\fP \ %lu +The number of major faults the process has made which have +required loading a memory page from disk. +.TP +(13) \fIcmajflt\fP \ %lu +The number of major faults that the process's +waited-for children have made. +.TP +(14) \fIutime\fP \ %lu +Amount of time that this process has been scheduled in user mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +This includes guest time, \fIguest_time\fP +(time spent running a virtual CPU, see below), +so that applications that are not aware of the guest time field +do not lose that time from their calculations. +.TP +(15) \fIstime\fP \ %lu +Amount of time that this process has been scheduled in kernel mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(16) \fIcutime\fP \ %ld +Amount of time that this process's +waited-for children have been scheduled in user mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +(See also +.BR times (2).) +This includes guest time, \fIcguest_time\fP +(time spent running a virtual CPU, see below). +.TP +(17) \fIcstime\fP \ %ld +Amount of time that this process's +waited-for children have been scheduled in kernel mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(18) \fIpriority\fP \ %ld +(Explanation for Linux 2.6) +For processes running a real-time scheduling policy +.RI ( policy +below; see +.BR sched_setscheduler (2)), +this is the negated scheduling priority, minus one; +that is, a number in the range \-2 to \-100, +corresponding to real-time priorities 1 to 99. +For processes running under a non-real-time scheduling policy, +this is the raw nice value +.RB ( setpriority (2)) +as represented in the kernel. +The kernel stores nice values as numbers +in the range 0 (high) to 39 (low), +corresponding to the user-visible nice range of \-20 to 19. +.IP +Before Linux 2.6, this was a scaled value based on +the scheduler weighting given to this process. +.\" And back in Linux 1.2 days things were different again. +.TP +(19) \fInice\fP \ %ld +The nice value (see +.BR setpriority (2)), +a value in the range 19 (low priority) to \-20 (high priority). +.\" Back in Linux 1.2 days things were different. +.\" .TP +.\" \fIcounter\fP %ld +.\" The current maximum size in jiffies of the process's next timeslice, +.\" or what is currently left of its current timeslice, if it is the +.\" currently running process. +.\" .TP +.\" \fItimeout\fP %u +.\" The time in jiffies of the process's next timeout. +.\" timeout was removed sometime around 2.1/2.2 +.TP +(20) \fInum_threads\fP \ %ld +Number of threads in this process (since Linux 2.6). +Before Linux 2.6, this field was hard coded to 0 as a placeholder +for an earlier removed field. +.TP +(21) \fIitrealvalue\fP \ %ld +The time in jiffies before the next +.B SIGALRM +is sent to the process due to an interval timer. +Since Linux 2.6.17, this field is no longer maintained, +and is hard coded as 0. +.TP +(22) \fIstarttime\fP \ %llu +The time the process started after system boot. +Before Linux 2.6, this value was expressed in jiffies. +Since Linux 2.6, the value is expressed in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.IP +The format for this field was %lu before Linux 2.6. +.TP +(23) \fIvsize\fP \ %lu +Virtual memory size in bytes. +.TP +(24) \fIrss\fP \ %ld +Resident Set Size: number of pages the process has in real memory. +This is just the pages which +count toward text, data, or stack space. +This does not include pages +which have not been demand-loaded in, or which are swapped out. +This value is inaccurate; see +.IR /proc/ pid /statm +below. +.TP +(25) \fIrsslim\fP \ %lu +Current soft limit in bytes on the rss of the process; +see the description of +.B RLIMIT_RSS +in +.BR getrlimit (2). +.TP +(26) \fIstartcode\fP \ %lu \ [PT] +The address above which program text can run. +.TP +(27) \fIendcode\fP \ %lu \ [PT] +The address below which program text can run. +.TP +(28) \fIstartstack\fP \ %lu \ [PT] +The address of the start (i.e., bottom) of the stack. +.TP +(29) \fIkstkesp\fP \ %lu \ [PT] +The current value of ESP (stack pointer), as found in the +kernel stack page for the process. +.TP +(30) \fIkstkeip\fP \ %lu \ [PT] +The current EIP (instruction pointer). +.TP +(31) \fIsignal\fP \ %lu +The bitmap of pending signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(32) \fIblocked\fP \ %lu +The bitmap of blocked signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(33) \fIsigignore\fP \ %lu +The bitmap of ignored signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(34) \fIsigcatch\fP \ %lu +The bitmap of caught signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(35) \fIwchan\fP \ %lu \ [PT] +This is the "channel" in which the process is waiting. +It is the address of a location in the kernel where the process is sleeping. +The corresponding symbolic name can be found in +.IR /proc/ pid /wchan . +.TP +(36) \fInswap\fP \ %lu +.\" nswap was added in Linux 2.0 +Number of pages swapped (not maintained). +.TP +(37) \fIcnswap\fP \ %lu +.\" cnswap was added in Linux 2.0 +Cumulative \fInswap\fP for child processes (not maintained). +.TP +(38) \fIexit_signal\fP \ %d \ (since Linux 2.1.22) +Signal to be sent to parent when we die. +.TP +(39) \fIprocessor\fP \ %d \ (since Linux 2.2.8) +CPU number last executed on. +.TP +(40) \fIrt_priority\fP \ %u \ (since Linux 2.5.19) +Real-time scheduling priority, a number in the range 1 to 99 for +processes scheduled under a real-time policy, +or 0, for non-real-time processes (see +.BR sched_setscheduler (2)). +.TP +(41) \fIpolicy\fP \ %u \ (since Linux 2.5.19) +Scheduling policy (see +.BR sched_setscheduler (2)). +Decode using the SCHED_* constants in +.IR linux/sched.h . +.IP +The format for this field was %lu before Linux 2.6.22. +.TP +(42) \fIdelayacct_blkio_ticks\fP \ %llu \ (since Linux 2.6.18) +Aggregated block I/O delays, measured in clock ticks (centiseconds). +.TP +(43) \fIguest_time\fP \ %lu \ (since Linux 2.6.24) +Guest time of the process (time spent running a virtual CPU +for a guest operating system), measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(44) \fIcguest_time\fP \ %ld \ (since Linux 2.6.24) +Guest time of the process's children, measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(45) \fIstart_data\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address above which program initialized and +uninitialized (BSS) data are placed. +.TP +(46) \fIend_data\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address below which program initialized and +uninitialized (BSS) data are placed. +.TP +(47) \fIstart_brk\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address above which program heap can be expanded with +.BR brk (2). +.TP +(48) \fIarg_start\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address above which program command-line arguments +.RI ( argv ) +are placed. +.TP +(49) \fIarg_end\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address below program command-line arguments +.RI ( argv ) +are placed. +.TP +(50) \fIenv_start\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address above which program environment is placed. +.TP +(51) \fIenv_end\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address below which program environment is placed. +.TP +(52) \fIexit_code\fP \ %d \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +The thread's exit status in the form reported by +.BR waitpid (2). +.RE +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_status (5) diff --git a/man/man5/proc_pid_statm.5 b/man/man5/proc_pid_statm.5 new file mode 100644 index 0000000..5aeb72c --- /dev/null +++ b/man/man5/proc_pid_statm.5 @@ -0,0 +1,46 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_statm 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/statm \- memory usage information +.SH DESCRIPTION +.TP +.IR /proc/ pid /statm +Provides information about memory usage, measured in pages. +The columns are: +.IP +.in +4n +.EX +size (1) total program size + (same as VmSize in \fI/proc/\fPpid\fI/status\fP) +resident (2) resident set size + (inaccurate; same as VmRSS in \fI/proc/\fPpid\fI/status\fP) +shared (3) number of resident shared pages + (i.e., backed by a file) + (inaccurate; same as RssFile+RssShmem in + \fI/proc/\fPpid\fI/status\fP) +text (4) text (code) +.\" (not including libs; broken, includes data segment) +lib (5) library (unused since Linux 2.6; always 0) +data (6) data + stack +.\" (including libs; broken, includes library text) +dt (7) dirty pages (unused since Linux 2.6; always 0) +.EE +.in +.IP +.\" See SPLIT_RSS_COUNTING in the kernel. +.\" Inaccuracy is bounded by TASK_RSS_EVENTS_THRESH. +Some of these values are inaccurate because +of a kernel-internal scalability optimization. +If accurate values are required, use +.IR /proc/ pid /smaps +or +.IR /proc/ pid /smaps_rollup +instead, which are much slower but provide accurate, detailed information. +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_status (5) diff --git a/man/man5/proc_pid_status.5 b/man/man5/proc_pid_status.5 new file mode 100644 index 0000000..d9688a2 --- /dev/null +++ b/man/man5/proc_pid_status.5 @@ -0,0 +1,384 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_status 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/status \- memory usage and status information +.SH DESCRIPTION +.TP +.IR /proc/ pid /status +Provides much of the information in +.IR /proc/ pid /stat +and +.IR /proc/ pid /statm +in a format that's easier for humans to parse. +Here's an example: +.IP +.in +4n +.EX +.RB "$" " cat /proc/$$/status" +Name: bash +Umask: 0022 +State: S (sleeping) +Tgid: 17248 +Ngid: 0 +Pid: 17248 +PPid: 17200 +TracerPid: 0 +Uid: 1000 1000 1000 1000 +Gid: 100 100 100 100 +FDSize: 256 +Groups: 16 33 100 +NStgid: 17248 +NSpid: 17248 +NSpgid: 17248 +NSsid: 17200 +VmPeak: 131168 kB +VmSize: 131168 kB +VmLck: 0 kB +VmPin: 0 kB +VmHWM: 13484 kB +VmRSS: 13484 kB +RssAnon: 10264 kB +RssFile: 3220 kB +RssShmem: 0 kB +VmData: 10332 kB +VmStk: 136 kB +VmExe: 992 kB +VmLib: 2104 kB +VmPTE: 76 kB +VmPMD: 12 kB +VmSwap: 0 kB +HugetlbPages: 0 kB # 4.4 +CoreDumping: 0 # 4.15 +Threads: 1 +SigQ: 0/3067 +SigPnd: 0000000000000000 +ShdPnd: 0000000000000000 +SigBlk: 0000000000010000 +SigIgn: 0000000000384004 +SigCgt: 000000004b813efb +CapInh: 0000000000000000 +CapPrm: 0000000000000000 +CapEff: 0000000000000000 +CapBnd: ffffffffffffffff +CapAmb: 0000000000000000 +NoNewPrivs: 0 +Seccomp: 0 +Seccomp_filters: 0 +Speculation_Store_Bypass: vulnerable +Cpus_allowed: 00000001 +Cpus_allowed_list: 0 +Mems_allowed: 1 +Mems_allowed_list: 0 +voluntary_ctxt_switches: 150 +nonvoluntary_ctxt_switches: 545 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.I Name +Command run by this process. +Strings longer than +.B TASK_COMM_LEN +(16) characters (including the terminating null byte) are silently truncated. +.TP +.I Umask +Process umask, expressed in octal with a leading zero; see +.BR umask (2). +(Since Linux 4.7.) +.TP +.I State +Current state of the process. +One of +"R (running)", +"S (sleeping)", +"D (disk sleep)", +"T (stopped)", +"t (tracing stop)", +"Z (zombie)", +or +"X (dead)". +.TP +.I Tgid +Thread group ID (i.e., Process ID). +.TP +.I Ngid +NUMA group ID (0 if none; since Linux 3.13). +.TP +.I Pid +Thread ID (see +.BR gettid (2)). +.TP +.I PPid +PID of parent process. +.TP +.I TracerPid +PID of process tracing this process (0 if not being traced). +.TP +.I Uid +.TQ +.I Gid +Real, effective, saved set, and filesystem UIDs (GIDs). +.TP +.I FDSize +Number of file descriptor slots currently allocated. +.TP +.I Groups +Supplementary group list. +.TP +.I NStgid +Thread group ID (i.e., PID) in each of the PID namespaces of which +.I pid +is a member. +The leftmost entry shows the value with respect to the PID namespace +of the process that mounted this procfs (or the root namespace +if mounted by the kernel), +followed by the value in successively nested inner namespaces. +.\" commit e4bc33245124db69b74a6d853ac76c2976f472d5 +(Since Linux 4.1.) +.TP +.I NSpid +Thread ID in each of the PID namespaces of which +.I pid +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.TP +.I NSpgid +Process group ID in each of the PID namespaces of which +.I pid +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.TP +.I NSsid +descendant namespace session ID hierarchy +Session ID in each of the PID namespaces of which +.I pid +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.TP +.I VmPeak +Peak virtual memory size. +.TP +.I VmSize +Virtual memory size. +.TP +.I VmLck +Locked memory size (see +.BR mlock (2)). +.TP +.I VmPin +Pinned memory size +.\" commit bc3e53f682d93df677dbd5006a404722b3adfe18 +(since Linux 3.2). +These are pages that can't be moved because something needs to +directly access physical memory. +.TP +.I VmHWM +Peak resident set size ("high water mark"). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I VmRSS +Resident set size. +Note that the value here is the sum of +.IR RssAnon , +.IR RssFile , +and +.IR RssShmem . +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I RssAnon +Size of resident anonymous memory. +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I RssFile +Size of resident file mappings. +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I RssShmem +Size of resident shared memory (includes System V shared memory, +mappings from +.BR tmpfs (5), +and shared anonymous mappings). +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +.TP +.I VmData +.TQ +.I VmStk +.TQ +.I VmExe +Size of data, stack, and text segments. +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I VmLib +Shared library code size. +.TP +.I VmPTE +Page table entries size (since Linux 2.6.10). +.TP +.I VmPMD +.\" commit dc6c9a35b66b520cf67e05d8ca60ebecad3b0479 +Size of second-level page tables (added in Linux 4.0; removed in Linux 4.15). +.TP +.I VmSwap +.\" commit b084d4353ff99d824d3bc5a5c2c22c70b1fba722 +Swapped-out virtual memory size by anonymous private pages; +shmem swap usage is not included (since Linux 2.6.34). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I HugetlbPages +Size of hugetlb memory portions +.\" commit 5d317b2b6536592a9b51fe65faed43d65ca9158e +(since Linux 4.4). +.TP +.I CoreDumping +Contains the value 1 if the process is currently dumping core, +and 0 if it is not +.\" commit c643401218be0f4ab3522e0c0a63016596d6e9ca +(since Linux 4.15). +This information can be used by a monitoring process to avoid killing +a process that is currently dumping core, +which could result in a corrupted core dump file. +.TP +.I Threads +Number of threads in process containing this thread. +.TP +.I SigQ +This field contains two slash-separated numbers that relate to +queued signals for the real user ID of this process. +The first of these is the number of currently queued +signals for this real user ID, and the second is the +resource limit on the number of queued signals for this process +(see the description of +.B RLIMIT_SIGPENDING +in +.BR getrlimit (2)). +.TP +.I SigPnd +.TQ +.I ShdPnd +Mask (expressed in hexadecimal) +of signals pending for thread and for process as a whole (see +.BR pthreads (7) +and +.BR signal (7)). +.TP +.I SigBlk +.TQ +.I SigIgn +.TQ +.I SigCgt +Masks (expressed in hexadecimal) +indicating signals being blocked, ignored, and caught (see +.BR signal (7)). +.TP +.I CapInh +.TQ +.I CapPrm +.TQ +.I CapEff +Masks (expressed in hexadecimal) +of capabilities enabled in inheritable, permitted, and effective sets +(see +.BR capabilities (7)). +.TP +.I CapBnd +Capability bounding set, expressed in hexadecimal +(since Linux 2.6.26, see +.BR capabilities (7)). +.TP +.I CapAmb +Ambient capability set, expressed in hexadecimal +(since Linux 4.3, see +.BR capabilities (7)). +.TP +.I NoNewPrivs +.\" commit af884cd4a5ae62fcf5e321fecf0ec1014730353d +Value of the +.I no_new_privs +bit +(since Linux 4.10, see +.BR prctl (2)). +.TP +.I Seccomp +.\" commit 2f4b3bf6b2318cfaa177ec5a802f4d8d6afbd816 +Seccomp mode of the process +(since Linux 3.8, see +.BR seccomp (2)). +0 means +.BR SECCOMP_MODE_DISABLED ; +1 means +.BR SECCOMP_MODE_STRICT ; +2 means +.BR SECCOMP_MODE_FILTER . +This field is provided only if the kernel was built with the +.B CONFIG_SECCOMP +kernel configuration option enabled. +.TP +.I Seccomp_filters +.\" commit c818c03b661cd769e035e41673d5543ba2ebda64 +Number of seccomp filters attached to the process +(since Linux 5.9, see +.BR seccomp (2)). +.TP +.I Speculation_Store_Bypass +.\" commit fae1fa0fc6cca8beee3ab8ed71d54f9a78fa3f64 +Speculation flaw mitigation state +(since Linux 4.17, see +.BR prctl (2)). +.TP +.I Cpus_allowed +Hexadecimal mask of CPUs on which this process may run +(since Linux 2.6.24, see +.BR cpuset (7)). +.TP +.I Cpus_allowed_list +Same as previous, but in "list format" +(since Linux 2.6.26, see +.BR cpuset (7)). +.TP +.I Mems_allowed +Mask of memory nodes allowed to this process +(since Linux 2.6.24, see +.BR cpuset (7)). +.TP +.I Mems_allowed_list +Same as previous, but in "list format" +(since Linux 2.6.26, see +.BR cpuset (7)). +.TP +.I voluntary_ctxt_switches +.TQ +.I nonvoluntary_ctxt_switches +Number of voluntary and involuntary context switches (since Linux 2.6.23). +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_syscall.5 b/man/man5/proc_pid_syscall.5 new file mode 100644 index 0000000..21a464f --- /dev/null +++ b/man/man5/proc_pid_syscall.5 @@ -0,0 +1,33 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_syscall 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/syscall \- currently executed system call +.SH DESCRIPTION +.TP +.IR /proc/ pid /syscall " (since Linux 2.6.27)" +.\" commit ebcb67341fee34061430f3367f2e507e52ee051b +This file exposes the system call number and argument registers for the +system call currently being executed by the process, +followed by the values of the stack pointer and program counter registers. +The values of all six argument registers are exposed, +although most system calls use fewer registers. +.IP +If the process is blocked, but not in a system call, +then the file displays \-1 in place of the system call number, +followed by just the values of the stack pointer and program counter. +If process is not blocked, then the file contains just the string "running". +.IP +This file is present only if the kernel was configured with +.BR CONFIG_HAVE_ARCH_TRACEHOOK . +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_task.5 b/man/man5/proc_pid_task.5 new file mode 100644 index 0000000..0a50876 --- /dev/null +++ b/man/man5/proc_pid_task.5 @@ -0,0 +1,97 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_task 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/task/, /proc/tid/, /proc/thread\-self/ \- thread information +.SH DESCRIPTION +.TP +.IR /proc/ pid /task/ " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test6 +This is a directory that contains one subdirectory +for each thread in the process. +The name of each subdirectory is the numerical thread ID +.RI ( tid ) +of the thread (see +.BR gettid (2)). +.IP +Within each of these subdirectories, there is a set of +files with the same names and contents as under the +.IR /proc/ pid +directories. +For attributes that are shared by all threads, the contents for +each of the files under the +.IR task/ tid +subdirectories will be the same as in the corresponding +file in the parent +.IR /proc/ pid +directory +(e.g., in a multithreaded process, all of the +.IR task/ tid /cwd +files will have the same value as the +.IR /proc/ pid /cwd +file in the parent directory, since all of the threads in a process +share a working directory). +For attributes that are distinct for each thread, +the corresponding files under +.IR task/ tid +may have different values (e.g., various fields in each of the +.IR task/ tid /status +files may be different for each thread), +.\" in particular: "children" :/ +or they might not exist in +.IR /proc/ pid +at all. +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of the +.IR /proc/ pid /task +directory are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.TP +.IR /proc/ tid / +There is a numerical subdirectory for each running thread +that is not a thread group leader +(i.e., a thread whose thread ID is not the same as its process ID); +the subdirectory is named by the thread ID. +Each one of these subdirectories contains files and subdirectories +exposing information about the thread with the thread ID +.IR tid . +The contents of these directories are the same as the corresponding +.IR /proc/ pid /task/ tid +directories. +.IP +The +.IR /proc/ tid +subdirectories are +.I not +visible when iterating through +.I /proc +with +.BR getdents (2) +(and thus are +.I not +visible when one uses +.BR ls (1) +to view the contents of +.IR /proc ). +However, the pathnames of these directories are visible to +(i.e., usable as arguments in) +system calls that operate on pathnames. +.TP +.IR /proc/thread\-self/ " (since Linux 3.17)" +.\" commit 0097875bd41528922fb3bb5f348c53f17e00e2fd +This directory refers to the thread accessing the +.I /proc +filesystem, +and is identical to the +.IR /proc/self/task/ tid +directory named by the process thread ID +.RI ( tid ) +of the same thread. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_timers.5 b/man/man5/proc_pid_timers.5 new file mode 100644 index 0000000..fe996e2 --- /dev/null +++ b/man/man5/proc_pid_timers.5 @@ -0,0 +1,82 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_timers 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/timers \- POSIX timers +.SH DESCRIPTION +.TP +.IR /proc/ pid /timers " (since Linux 3.10)" +.\" commit 5ed67f05f66c41e39880a6d61358438a25f9fee5 +.\" commit 48f6a7a511ef8823fdff39afee0320092d43a8a0 +A list of the POSIX timers for this process. +Each timer is listed with a line that starts with the string "ID:". +For example: +.IP +.in +4n +.EX +ID: 1 +signal: 60/00007fff86e452a8 +notify: signal/pid.2634 +ClockID: 0 +ID: 0 +signal: 60/00007fff86e452a8 +notify: signal/pid.2634 +ClockID: 1 +.EE +.in +.IP +The lines shown for each timer have the following meanings: +.RS +.TP +.I ID +The ID for this timer. +This is not the same as the timer ID returned by +.BR timer_create (2); +rather, it is the same kernel-internal ID that is available via the +.I si_timerid +field of the +.I siginfo_t +structure (see +.BR sigaction (2)). +.TP +.I signal +This is the signal number that this timer uses to deliver notifications +followed by a slash, and then the +.I sigev_value +value supplied to the signal handler. +Valid only for timers that notify via a signal. +.TP +.I notify +The part before the slash specifies the mechanism +that this timer uses to deliver notifications, +and is one of "thread", "signal", or "none". +Immediately following the slash is either the string "tid" for timers +with +.B SIGEV_THREAD_ID +notification, or "pid" for timers that notify by other mechanisms. +Following the "." is the PID of the process +(or the kernel thread ID of the thread) that will be delivered +a signal if the timer delivers notifications via a signal. +.TP +.I ClockID +This field identifies the clock that the timer uses for measuring time. +For most clocks, this is a number that matches one of the user-space +.B CLOCK_* +constants exposed via +.IR . +.B CLOCK_PROCESS_CPUTIME_ID +timers display with a value of \-6 +in this field. +.B CLOCK_THREAD_CPUTIME_ID +timers display with a value of \-2 +in this field. +.RE +.IP +This file is available only when the kernel was configured with +.BR CONFIG_CHECKPOINT_RESTORE . +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_timerslack_ns.5 b/man/man5/proc_pid_timerslack_ns.5 new file mode 100644 index 0000000..89df9f5 --- /dev/null +++ b/man/man5/proc_pid_timerslack_ns.5 @@ -0,0 +1,41 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_timerslack_ns 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/timerslack_ns \- timer slack in nanoseconds +.SH DESCRIPTION +.TP +.IR /proc/ pid /timerslack_ns " (since Linux 4.6)" +.\" commit da8b44d5a9f8bf26da637b7336508ca534d6b319 +.\" commit 5de23d435e88996b1efe0e2cebe242074ce67c9e +This file exposes the process's "current" timer slack value, +expressed in nanoseconds. +The file is writable, +allowing the process's timer slack value to be changed. +Writing 0 to this file resets the "current" timer slack to the +"default" timer slack value. +For further details, see the discussion of +.B PR_SET_TIMERSLACK +in +.BR prctl (2). +.IP +Initially, +permission to access this file was governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check (see +.BR ptrace (2)). +However, this was subsequently deemed too strict a requirement +(and had the side effect that requiring a process to have the +.B CAP_SYS_PTRACE +capability would also allow it to view and change any process's memory). +Therefore, since Linux 4.9, +.\" commit 7abbaf94049914f074306d960b0f968ffe52e59f +only the (weaker) +.B CAP_SYS_NICE +capability is required to access this file. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_uid_map.5 b/man/man5/proc_pid_uid_map.5 new file mode 100644 index 0000000..eecbf6a --- /dev/null +++ b/man/man5/proc_pid_uid_map.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_uid_map 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/gid_map, /proc/pid/uid_map \- user and group ID mappings +.SH DESCRIPTION +.TP +.IR /proc/ pid /gid_map " (since Linux 3.5)" +See +.BR user_namespaces (7). +.TP +.IR /proc/ pid /uid_map " (since Linux 3.5)" +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_pid_wchan.5 b/man/man5/proc_pid_wchan.5 new file mode 100644 index 0000000..7b331b2 --- /dev/null +++ b/man/man5/proc_pid_wchan.5 @@ -0,0 +1,21 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_wchan 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/pid/wchan \- wait channel +.SH DESCRIPTION +.TP +.IR /proc/ pid /wchan " (since Linux 2.6.0)" +The symbolic name corresponding to the location +in the kernel where the process is sleeping. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_profile.5 b/man/man5/proc_profile.5 new file mode 100644 index 0000000..44adb24 --- /dev/null +++ b/man/man5/proc_profile.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_profile 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/profile \- kernel profiling +.SH DESCRIPTION +.TP +.IR /proc/profile " (since Linux 2.4)" +This file is present only if the kernel was booted with the +.I profile=1 +command-line option. +It exposes kernel profiling information in a binary format for use by +.BR readprofile (1). +Writing (e.g., an empty string) to this file resets the profiling counters; +on some architectures, +writing a binary integer "profiling multiplier" of size +.I sizeof(int) +sets the profiling interrupt frequency. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_scsi.5 b/man/man5/proc_scsi.5 new file mode 100644 index 0000000..947c412 --- /dev/null +++ b/man/man5/proc_scsi.5 @@ -0,0 +1,66 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Michael Neuffer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_scsi 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/scsi/ \- SCSI +.SH DESCRIPTION +.TP +.I /proc/scsi/ +A directory with the +.I scsi +mid-level pseudo-file and various SCSI low-level +driver directories, +which contain a file for each SCSI host in this system, all of +which give the status of some part of the SCSI IO subsystem. +These files contain ASCII structures and are, therefore, readable with +.BR cat (1). +.IP +You can also write to some of the files to reconfigure the subsystem or +switch certain features on or off. +.TP +.I /proc/scsi/scsi +This is a listing of all SCSI devices known to the kernel. +The listing is similar to the one seen during bootup. +scsi currently supports only the \fIadd\-single\-device\fP command which +allows root to add a hotplugged device to the list of known devices. +.IP +The command +.IP +.in +4n +.EX +echo \[aq]scsi add\-single\-device 1 0 5 0\[aq] > /proc/scsi/scsi +.EE +.in +.IP +will cause +host scsi1 to scan on SCSI channel 0 for a device on ID 5 LUN 0. +If there +is already a device known on this address or the address is invalid, an +error will be returned. +.TP +.IR /proc/scsi/ drivername / +\fIdrivername\fP can currently be NCR53c7xx, aha152x, aha1542, aha1740, +aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic, +scsi_debug, seagate, t128, u15\-24f, ultrastore, or wd7000. +These directories show up for all drivers that registered at least one +SCSI HBA. +Every directory contains one file per registered host. +Every host-file is named after the number the host was assigned during +initialization. +.IP +Reading these files will usually show driver and host configuration, +statistics, and so on. +.IP +Writing to these files allows different things on different hosts. +For example, with the \fIlatency\fP and \fInolatency\fP commands, +root can switch on and off command latency measurement code in the +eata_dma driver. +With the \fIlockup\fP and \fIunlock\fP commands, +root can control bus lockups simulated by the scsi_debug driver. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_self.5 b/man/man5/proc_self.5 new file mode 100644 index 0000000..fb01835 --- /dev/null +++ b/man/man5/proc_self.5 @@ -0,0 +1 @@ +.so man5/proc_pid.5 diff --git a/man/man5/proc_slabinfo.5 b/man/man5/proc_slabinfo.5 new file mode 100644 index 0000000..38b785d --- /dev/null +++ b/man/man5/proc_slabinfo.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_slabinfo 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/slabinfo \- kernel caches +.SH DESCRIPTION +.TP +.I /proc/slabinfo +Information about kernel caches. +See +.BR slabinfo (5) +for details. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_stat.5 b/man/man5/proc_stat.5 new file mode 100644 index 0000000..3fe4c6f --- /dev/null +++ b/man/man5/proc_stat.5 @@ -0,0 +1,140 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_stat 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/stat \- kernel system statistics +.SH DESCRIPTION +.TP +.I /proc/stat +kernel/system statistics. +Varies with architecture. +Common +entries include: +.RS +.TP +.I cpu 10132153 290696 3084719 46828483 16683 0 25195 0 175628 0 +.TQ +.I cpu0 1393280 32966 572056 13343292 6130 0 17875 0 23933 0 +The amount of time, measured in units of +USER_HZ (1/100ths of a second on most architectures, use +.I sysconf(_SC_CLK_TCK) +to obtain the right value), +.\" 1024 on Alpha and ia64 +that the system ("cpu" line) or the specific CPU ("cpu\fIN\fR" line) +spent in various states: +.RS +.TP +.I user +(1) Time spent in user mode. +.TP +.I nice +(2) Time spent in user mode with low priority (nice). +.TP +.I system +(3) Time spent in system mode. +.TP +.I idle +(4) Time spent in the idle task. +.\" FIXME . Actually, the following info about the /proc/stat 'cpu' field +.\" does not seem to be quite right (at least in Linux 2.6.12 or Linux 3.6): +.\" the idle time in /proc/uptime does not quite match this value +This value should be USER_HZ times the +second entry in the +.I /proc/uptime +pseudo-file. +.TP +.IR iowait " (since Linux 2.5.41)" +(5) Time waiting for I/O to complete. +This value is not reliable, for the following reasons: +.\" See kernel commit 9c240d757658a3ae9968dd309e674c61f07c7f48 +.RS +.IP \[bu] 3 +The CPU will not wait for I/O to complete; +iowait is the time that a task is waiting for I/O to complete. +When a CPU goes into idle state for outstanding task I/O, +another task will be scheduled on this CPU. +.IP \[bu] +On a multi-core CPU, +the task waiting for I/O to complete is not running on any CPU, +so the iowait of each CPU is difficult to calculate. +.IP \[bu] +The value in this field may +.I decrease +in certain conditions. +.RE +.TP +.IR irq " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test4 +(6) Time servicing interrupts. +.TP +.IR softirq " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test4 +(7) Time servicing softirqs. +.TP +.IR steal " (since Linux 2.6.11)" +(8) Stolen time, which is the time spent in other operating systems when +running in a virtualized environment +.TP +.IR guest " (since Linux 2.6.24)" +(9) Time spent running a virtual CPU for guest +operating systems under the control of the Linux kernel. +.\" See Changelog entry for 5e84cfde51cf303d368fcb48f22059f37b3872de +.TP +.IR guest_nice " (since Linux 2.6.33)" +.\" commit ce0e7b28fb75cb003cfc8d0238613aaf1c55e797 +(10) Time spent running a niced guest (virtual CPU for guest +operating systems under the control of the Linux kernel). +.RE +.TP +\fIpage 5741 1808\fP +The number of pages the system paged in and the number that were paged +out (from disk). +.TP +\fIswap 1 0\fP +The number of swap pages that have been brought in and out. +.TP +.\" FIXME . The following is not the full picture for the 'intr' of +.\" /proc/stat on 2.6: +\fIintr 1462898\fP +This line shows counts of interrupts serviced since boot time, +for each of the possible system interrupts. +The first column is the total of all interrupts serviced +including unnumbered architecture specific interrupts; +each subsequent column is the total for that particular numbered interrupt. +Unnumbered interrupts are not shown, only summed into the total. +.TP +\fIdisk_io: (2,0):(31,30,5764,1,2) (3,0):\fP... +(major,disk_idx):(noinfo, read_io_ops, blks_read, write_io_ops, blks_written) +.br +(Linux 2.4 only) +.TP +\fIctxt 115315\fP +The number of context switches that the system underwent. +.TP +\fIbtime 769041601\fP +boot time, in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.TP +\fIprocesses 86031\fP +Number of forks since boot. +.TP +\fIprocs_running 6\fP +Number of processes in runnable state. +(Linux 2.5.45 onward.) +.TP +\fIprocs_blocked 2\fP +Number of processes blocked waiting for I/O to complete. +(Linux 2.5.45 onward.) +.TP +.I softirq 229245889 94 60001584 13619 5175704 2471304 28 51212741 59130143 0 51240672 +.\" commit d3d64df21d3d0de675a0d3ffa7c10514f3644b30 +This line shows the number of softirq for all CPUs. +The first column is the total of all softirqs and +each subsequent column is the total for particular softirq. +(Linux 2.6.31 onward.) +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_swaps.5 b/man/man5/proc_swaps.5 new file mode 100644 index 0000000..356943c --- /dev/null +++ b/man/man5/proc_swaps.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_swaps 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/swaps \- swap areas +.SH DESCRIPTION +.TP +.I /proc/swaps +Swap areas in use. +See also +.BR swapon (8). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_sys.5 b/man/man5/proc_sys.5 new file mode 100644 index 0000000..fc5713a --- /dev/null +++ b/man/man5/proc_sys.5 @@ -0,0 +1,31 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/ \- system information, and sysctl pseudo-filesystem +.SH DESCRIPTION +.TP +.I /proc/sys/ +This directory (present since Linux 1.3.57) contains a number of files +and subdirectories corresponding to kernel variables. +These variables can be read and in some cases modified using +the \fI/proc\fP filesystem, and the (deprecated) +.BR sysctl (2) +system call. +.IP +String values may be terminated by either \[aq]\e0\[aq] or \[aq]\en\[aq]. +.IP +Integer and long values may be written either in decimal or in +hexadecimal notation (e.g., 0x3FFF). +When writing multiple integer or long values, these may be separated +by any of the following whitespace characters: +\[aq]\ \[aq], \[aq]\et\[aq], or \[aq]\en\[aq]. +Using other separators leads to the error +.BR EINVAL . +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_sys_abi.5 b/man/man5/proc_sys_abi.5 new file mode 100644 index 0000000..5969ac5 --- /dev/null +++ b/man/man5/proc_sys_abi.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_abi 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/abi/ \- application binary information +.SH DESCRIPTION +.TP +.IR /proc/sys/abi/ " (since Linux 2.4.10)" +This directory may contain files with application binary information. +.\" On some systems, it is not present. +See the Linux kernel source file +.I Documentation/sysctl/abi.rst +(or +.I Documentation/sysctl/abi.txt +before Linux 5.3) +for more information. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man/man5/proc_sys_debug.5 b/man/man5/proc_sys_debug.5 new file mode 100644 index 0000000..0facf71 --- /dev/null +++ b/man/man5/proc_sys_debug.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_debug 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/debug/ \- debug +.SH DESCRIPTION +.TP +.I /proc/sys/debug/ +This directory may be empty. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man/man5/proc_sys_dev.5 b/man/man5/proc_sys_dev.5 new file mode 100644 index 0000000..7ff1b58 --- /dev/null +++ b/man/man5/proc_sys_dev.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_dev 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/dev/ \- device-specific information +.SH DESCRIPTION +.TP +.I /proc/sys/dev/ +This directory contains device-specific information (e.g., +.IR dev/cdrom/info ). +On +some systems, it may be empty. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man/man5/proc_sys_fs.5 b/man/man5/proc_sys_fs.5 new file mode 100644 index 0000000..2ffdeb4 --- /dev/null +++ b/man/man5/proc_sys_fs.5 @@ -0,0 +1,471 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_fs 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/fs/ \- kernel variables related to filesystems +.SH DESCRIPTION +.TP +.I /proc/sys/fs/ +This directory contains the files and subdirectories for kernel variables +related to filesystems. +.TP +.IR /proc/sys/fs/aio\-max\-nr " and " /proc/sys/fs/aio\-nr " (since Linux 2.6.4)" +.I aio\-nr +is the running total of the number of events specified by +.BR io_setup (2) +calls for all currently active AIO contexts. +If +.I aio\-nr +reaches +.IR aio\-max\-nr , +then +.BR io_setup (2) +will fail with the error +.BR EAGAIN . +Raising +.I aio\-max\-nr +does not result in the preallocation or resizing +of any kernel data structures. +.TP +.I /proc/sys/fs/binfmt_misc +Documentation for files in this directory can be found +in the Linux kernel source in the file +.I Documentation/admin\-guide/binfmt\-misc.rst +(or in +.I Documentation/binfmt_misc.txt +on older kernels). +.TP +.IR /proc/sys/fs/dentry\-state " (since Linux 2.2)" +This file contains information about the status of the +directory cache (dcache). +The file contains six numbers, +.IR nr_dentry , +.IR nr_unused , +.I age_limit +(age in seconds), +.I want_pages +(pages requested by system) and two dummy values. +.RS +.IP \[bu] 3 +.I nr_dentry +is the number of allocated dentries (dcache entries). +This field is unused in Linux 2.2. +.IP \[bu] +.I nr_unused +is the number of unused dentries. +.IP \[bu] +.I age_limit +.\" looks like this is unused in Linux 2.2 to Linux 2.6 +is the age in seconds after which dcache entries +can be reclaimed when memory is short. +.IP \[bu] +.I want_pages +.\" looks like this is unused in Linux 2.2 to Linux 2.6 +is nonzero when the kernel has called shrink_dcache_pages() and the +dcache isn't pruned yet. +.RE +.TP +.I /proc/sys/fs/dir\-notify\-enable +This file can be used to disable or enable the +.I dnotify +interface described in +.BR fcntl (2) +on a system-wide basis. +A value of 0 in this file disables the interface, +and a value of 1 enables it. +.TP +.I /proc/sys/fs/dquot\-max +This file shows the maximum number of cached disk quota entries. +On some (2.4) systems, it is not present. +If the number of free cached disk quota entries is very low and +you have some awesome number of simultaneous system users, +you might want to raise the limit. +.TP +.I /proc/sys/fs/dquot\-nr +This file shows the number of allocated disk quota +entries and the number of free disk quota entries. +.TP +.IR /proc/sys/fs/epoll/ " (since Linux 2.6.28)" +This directory contains the file +.IR max_user_watches , +which can be used to limit the amount of kernel memory consumed by the +.I epoll +interface. +For further details, see +.BR epoll (7). +.TP +.I /proc/sys/fs/file\-max +This file defines +a system-wide limit on the number of open files for all processes. +System calls that fail when encountering this limit fail with the error +.BR ENFILE . +(See also +.BR setrlimit (2), +which can be used by a process to set the per-process limit, +.BR RLIMIT_NOFILE , +on the number of files it may open.) +If you get lots +of error messages in the kernel log about running out of file handles +(open file descriptions) +(look for "VFS: file\-max limit reached"), +try increasing this value: +.IP +.in +4n +.EX +echo 100000 > /proc/sys/fs/file\-max +.EE +.in +.IP +Privileged processes +.RB ( CAP_SYS_ADMIN ) +can override the +.I file\-max +limit. +.TP +.I /proc/sys/fs/file\-nr +This (read-only) file contains three numbers: +the number of allocated file handles +(i.e., the number of open file descriptions; see +.BR open (2)); +the number of free file handles; +and the maximum number of file handles (i.e., the same value as +.IR /proc/sys/fs/file\-max ). +If the number of allocated file handles is close to the +maximum, you should consider increasing the maximum. +Before Linux 2.6, +the kernel allocated file handles dynamically, +but it didn't free them again. +Instead the free file handles were kept in a list for reallocation; +the "free file handles" value indicates the size of that list. +A large number of free file handles indicates that there was +a past peak in the usage of open file handles. +Since Linux 2.6, the kernel does deallocate freed file handles, +and the "free file handles" value is always zero. +.TP +.IR /proc/sys/fs/inode\-max " (only present until Linux 2.2)" +This file contains the maximum number of in-memory inodes. +This value should be 3\[en]4 times larger +than the value in +.IR file\-max , +since \fIstdin\fP, \fIstdout\fP +and network sockets also need an inode to handle them. +When you regularly run out of inodes, you need to increase this value. +.IP +Starting with Linux 2.4, +there is no longer a static limit on the number of inodes, +and this file is removed. +.TP +.I /proc/sys/fs/inode\-nr +This file contains the first two values from +.IR inode\-state . +.TP +.I /proc/sys/fs/inode\-state +This file +contains seven numbers: +.IR nr_inodes , +.IR nr_free_inodes , +.IR preshrink , +and four dummy values (always zero). +.IP +.I nr_inodes +is the number of inodes the system has allocated. +.\" This can be slightly more than +.\" .I inode\-max +.\" because Linux allocates them one page full at a time. +.I nr_free_inodes +represents the number of free inodes. +.IP +.I preshrink +is nonzero when the +.I nr_inodes +> +.I inode\-max +and the system needs to prune the inode list instead of allocating more; +since Linux 2.4, this field is a dummy value (always zero). +.TP +.IR /proc/sys/fs/inotify/ " (since Linux 2.6.13)" +This directory contains files +.IR max_queued_events ", " max_user_instances ", and " max_user_watches , +that can be used to limit the amount of kernel memory consumed by the +.I inotify +interface. +For further details, see +.BR inotify (7). +.TP +.I /proc/sys/fs/lease\-break\-time +This file specifies the grace period that the kernel grants to a process +holding a file lease +.RB ( fcntl (2)) +after it has sent a signal to that process notifying it +that another process is waiting to open the file. +If the lease holder does not remove or downgrade the lease within +this grace period, the kernel forcibly breaks the lease. +.TP +.I /proc/sys/fs/leases\-enable +This file can be used to enable or disable file leases +.RB ( fcntl (2)) +on a system-wide basis. +If this file contains the value 0, leases are disabled. +A nonzero value enables leases. +.TP +.IR /proc/sys/fs/mount\-max " (since Linux 4.9)" +.\" commit d29216842a85c7970c536108e093963f02714498 +The value in this file specifies the maximum number of mounts that may exist +in a mount namespace. +The default value in this file is 100,000. +.TP +.IR /proc/sys/fs/mqueue/ " (since Linux 2.6.6)" +This directory contains files +.IR msg_max ", " msgsize_max ", and " queues_max , +controlling the resources used by POSIX message queues. +See +.BR mq_overview (7) +for details. +.TP +.IR /proc/sys/fs/nr_open " (since Linux 2.6.25)" +.\" commit 9cfe015aa424b3c003baba3841a60dd9b5ad319b +This file imposes a ceiling on the value to which the +.B RLIMIT_NOFILE +resource limit can be raised (see +.BR getrlimit (2)). +This ceiling is enforced for both unprivileged and privileged process. +The default value in this file is 1048576. +(Before Linux 2.6.25, the ceiling for +.B RLIMIT_NOFILE +was hard-coded to the same value.) +.TP +.IR /proc/sys/fs/overflowgid " and " /proc/sys/fs/overflowuid +These files +allow you to change the value of the fixed UID and GID. +The default is 65534. +Some filesystems support only 16-bit UIDs and GIDs, although in Linux +UIDs and GIDs are 32 bits. +When one of these filesystems is mounted +with writes enabled, any UID or GID that would exceed 65535 is translated +to the overflow value before being written to disk. +.TP +.IR /proc/sys/fs/pipe\-max\-size " (since Linux 2.6.35)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/pipe\-user\-pages\-hard " (since Linux 4.5)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/pipe\-user\-pages\-soft " (since Linux 4.5)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/protected_fifos " (since Linux 4.19)" +The value in this file is/can be set to one of the following: +.RS +.TP 4 +0 +Writing to FIFOs is unrestricted. +.TP +1 +Don't allow +.B O_CREAT +.BR open (2) +on FIFOs that the caller doesn't own in world-writable sticky directories, +unless the FIFO is owned by the owner of the directory. +.TP +2 +As for the value 1, +but the restriction also applies to group-writable sticky directories. +.RE +.IP +The intent of the above protections is to avoid unintentional writes to an +attacker-controlled FIFO when a program expected to create a regular file. +.TP +.IR /proc/sys/fs/protected_hardlinks " (since Linux 3.6)" +.\" commit 800179c9b8a1e796e441674776d11cd4c05d61d7 +When the value in this file is 0, +no restrictions are placed on the creation of hard links +(i.e., this is the historical behavior before Linux 3.6). +When the value in this file is 1, +a hard link can be created to a target file +only if one of the following conditions is true: +.RS +.IP \[bu] 3 +The calling process has the +.B CAP_FOWNER +capability in its user namespace +and the file UID has a mapping in the namespace. +.IP \[bu] +The filesystem UID of the process creating the link matches +the owner (UID) of the target file +(as described in +.BR credentials (7), +a process's filesystem UID is normally the same as its effective UID). +.IP \[bu] +All of the following conditions are true: +.RS 4 +.IP \[bu] 3 +the target is a regular file; +.IP \[bu] +the target file does not have its set-user-ID mode bit enabled; +.IP \[bu] +the target file does not have both its set-group-ID and +group-executable mode bits enabled; and +.IP \[bu] +the caller has permission to read and write the target file +(either via the file's permissions mask or because it has +suitable capabilities). +.RE +.RE +.IP +The default value in this file is 0. +Setting the value to 1 +prevents a longstanding class of security issues caused by +hard-link-based time-of-check, time-of-use races, +most commonly seen in world-writable directories such as +.IR /tmp . +The common method of exploiting this flaw +is to cross privilege boundaries when following a given hard link +(i.e., a root process follows a hard link created by another user). +Additionally, on systems without separated partitions, +this stops unauthorized users from "pinning" vulnerable set-user-ID and +set-group-ID files against being upgraded by +the administrator, or linking to special files. +.TP +.IR /proc/sys/fs/protected_regular " (since Linux 4.19)" +The value in this file is/can be set to one of the following: +.RS +.TP 4 +0 +Writing to regular files is unrestricted. +.TP +1 +Don't allow +.B O_CREAT +.BR open (2) +on regular files that the caller doesn't own in +world-writable sticky directories, +unless the regular file is owned by the owner of the directory. +.TP +2 +As for the value 1, +but the restriction also applies to group-writable sticky directories. +.RE +.IP +The intent of the above protections is similar to +.IR protected_fifos , +but allows an application to +avoid writes to an attacker-controlled regular file, +where the application expected to create one. +.TP +.IR /proc/sys/fs/protected_symlinks " (since Linux 3.6)" +.\" commit 800179c9b8a1e796e441674776d11cd4c05d61d7 +When the value in this file is 0, +no restrictions are placed on following symbolic links +(i.e., this is the historical behavior before Linux 3.6). +When the value in this file is 1, symbolic links are followed only +in the following circumstances: +.RS +.IP \[bu] 3 +the filesystem UID of the process following the link matches +the owner (UID) of the symbolic link +(as described in +.BR credentials (7), +a process's filesystem UID is normally the same as its effective UID); +.IP \[bu] +the link is not in a sticky world-writable directory; or +.IP \[bu] +the symbolic link and its parent directory have the same owner (UID) +.RE +.IP +A system call that fails to follow a symbolic link +because of the above restrictions returns the error +.B EACCES +in +.IR errno . +.IP +The default value in this file is 0. +Setting the value to 1 avoids a longstanding class of security issues +based on time-of-check, time-of-use races when accessing symbolic links. +.TP +.IR /proc/sys/fs/suid_dumpable " (since Linux 2.6.13)" +.\" The following is based on text from Documentation/sysctl/kernel.txt +The value in this file is assigned to a process's "dumpable" flag +in the circumstances described in +.BR prctl (2). +In effect, +the value in this file determines whether core dump files are +produced for set-user-ID or otherwise protected/tainted binaries. +The "dumpable" setting also affects the ownership of files in a process's +.IR /proc/ pid +directory, as described above. +.IP +Three different integer values can be specified: +.RS +.TP +\fI0\ (default)\fP +.\" In kernel source: SUID_DUMP_DISABLE +This provides the traditional (pre-Linux 2.6.13) behavior. +A core dump will not be produced for a process which has +changed credentials (by calling +.BR seteuid (2), +.BR setgid (2), +or similar, or by executing a set-user-ID or set-group-ID program) +or whose binary does not have read permission enabled. +.TP +\fI1\ ("debug")\fP +.\" In kernel source: SUID_DUMP_USER +All processes dump core when possible. +(Reasons why a process might nevertheless not dump core are described in +.BR core (5).) +The core dump is owned by the filesystem user ID of the dumping process +and no security is applied. +This is intended for system debugging situations only: +this mode is insecure because it allows unprivileged users to +examine the memory contents of privileged processes. +.TP +\fI2\ ("suidsafe")\fP +.\" In kernel source: SUID_DUMP_ROOT +Any binary which normally would not be dumped (see "0" above) +is dumped readable by root only. +This allows the user to remove the core dump file but not to read it. +For security reasons core dumps in this mode will not overwrite one +another or other files. +This mode is appropriate when administrators are +attempting to debug problems in a normal environment. +.IP +Additionally, since Linux 3.6, +.\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 +.I /proc/sys/kernel/core_pattern +must either be an absolute pathname +or a pipe command, as detailed in +.BR core (5). +Warnings will be written to the kernel log if +.I core_pattern +does not follow these rules, and no core dump will be produced. +.\" 54b501992dd2a839e94e76aa392c392b55080ce8 +.RE +.IP +For details of the effect of a process's "dumpable" setting +on ptrace access mode checking, see +.BR ptrace (2). +.TP +.I /proc/sys/fs/super\-max +This file +controls the maximum number of superblocks, and +thus the maximum number of mounted filesystems the kernel +can have. +You need increase only +.I super\-max +if you need to mount more filesystems than the current value in +.I super\-max +allows you to. +.TP +.I /proc/sys/fs/super\-nr +This file +contains the number of filesystems currently mounted. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man/man5/proc_sys_kernel.5 b/man/man5/proc_sys_kernel.5 new file mode 100644 index 0000000..a01964d --- /dev/null +++ b/man/man5/proc_sys_kernel.5 @@ -0,0 +1,691 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_kernel 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/kernel/ \- control a range of kernel parameters +.SH DESCRIPTION +.TP +.I /proc/sys/kernel/ +This directory contains files controlling a range of kernel parameters, +as described below. +.TP +.I /proc/sys/kernel/acct +This file +contains three numbers: +.IR highwater , +.IR lowwater , +and +.IR frequency . +If BSD-style process accounting is enabled, these values control +its behavior. +If free space on filesystem where the log lives goes below +.I lowwater +percent, accounting suspends. +If free space gets above +.I highwater +percent, accounting resumes. +.I frequency +determines +how often the kernel checks the amount of free space (value is in +seconds). +Default values are 4, 2, and 30. +That is, suspend accounting if 2% or less space is free; resume it +if 4% or more space is free; consider information about amount of free space +valid for 30 seconds. +.TP +.IR /proc/sys/kernel/auto_msgmni " (Linux 2.6.27 to Linux 3.18)" +.\" commit 9eefe520c814f6f62c5d36a2ddcd3fb99dfdb30e (introduces feature) +.\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973 (rendered redundant) +From Linux 2.6.27 to Linux 3.18, +this file was used to control recomputing of the value in +.I /proc/sys/kernel/msgmni +upon the addition or removal of memory or upon IPC namespace creation/removal. +Echoing "1" into this file enabled +.I msgmni +automatic recomputing (and triggered a recomputation of +.I msgmni +based on the current amount of available memory and number of IPC namespaces). +Echoing "0" disabled automatic recomputing. +(Automatic recomputing was also disabled if a value was explicitly assigned to +.IR /proc/sys/kernel/msgmni .) +The default value in +.I auto_msgmni +was 1. +.IP +Since Linux 3.19, the content of this file has no effect (because +.I msgmni +.\" FIXME Must document the 3.19 'msgmni' changes. +defaults to near the maximum value possible), +and reads from this file always return the value "0". +.TP +.IR /proc/sys/kernel/cap_last_cap " (since Linux 3.2)" +See +.BR capabilities (7). +.TP +.IR /proc/sys/kernel/cap\-bound " (from Linux 2.2 to Linux 2.6.24)" +This file holds the value of the kernel +.I "capability bounding set" +(expressed as a signed decimal number). +This set is ANDed against the capabilities permitted to a process +during +.BR execve (2). +Starting with Linux 2.6.25, +the system-wide capability bounding set disappeared, +and was replaced by a per-thread bounding set; see +.BR capabilities (7). +.TP +.I /proc/sys/kernel/core_pattern +See +.BR core (5). +.TP +.I /proc/sys/kernel/core_pipe_limit +See +.BR core (5). +.TP +.I /proc/sys/kernel/core_uses_pid +See +.BR core (5). +.TP +.I /proc/sys/kernel/ctrl\-alt\-del +This file +controls the handling of Ctrl-Alt-Del from the keyboard. +When the value in this file is 0, Ctrl-Alt-Del is trapped and +sent to the +.BR init (1) +program to handle a graceful restart. +When the value is greater than zero, Linux's reaction to a Vulcan +Nerve Pinch (tm) will be an immediate reboot, without even +syncing its dirty buffers. +Note: when a program (like dosemu) has the keyboard in "raw" +mode, the Ctrl-Alt-Del is intercepted by the program before it +ever reaches the kernel tty layer, and it's up to the program +to decide what to do with it. +.TP +.IR /proc/sys/kernel/dmesg_restrict " (since Linux 2.6.37)" +The value in this file determines who can see kernel syslog contents. +A value of 0 in this file imposes no restrictions. +If the value is 1, only privileged users can read the kernel syslog. +(See +.BR syslog (2) +for more details.) +Since Linux 3.4, +.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8 +only users with the +.B CAP_SYS_ADMIN +capability may change the value in this file. +.TP +.IR /proc/sys/kernel/domainname " and " /proc/sys/kernel/hostname +can be used to set the NIS/YP domainname and the +hostname of your box in exactly the same way as the commands +.BR domainname (1) +and +.BR hostname (1), +that is: +.IP +.in +4n +.EX +.RB "#" " echo \[aq]darkstar\[aq] > /proc/sys/kernel/hostname" +.RB "#" " echo \[aq]mydomain\[aq] > /proc/sys/kernel/domainname" +.EE +.in +.IP +has the same effect as +.IP +.in +4n +.EX +.RB "#" " hostname \[aq]darkstar\[aq]" +.RB "#" " domainname \[aq]mydomain\[aq]" +.EE +.in +.IP +Note, however, that the classic darkstar.frop.org has the +hostname "darkstar" and DNS (Internet Domain Name Server) +domainname "frop.org", not to be confused with the NIS (Network +Information Service) or YP (Yellow Pages) domainname. +These two +domain names are in general different. +For a detailed discussion +see the +.BR hostname (1) +man page. +.TP +.I /proc/sys/kernel/hotplug +This file +contains the pathname for the hotplug policy agent. +The default value in this file is +.IR /sbin/hotplug . +.TP +.\" Removed in commit 87f504e5c78b910b0c1d6ffb89bc95e492322c84 (tglx/history.git) +.IR /proc/sys/kernel/htab\-reclaim " (before Linux 2.4.9.2)" +(PowerPC only) If this file is set to a nonzero value, +the PowerPC htab +.\" removed in commit 1b483a6a7b2998e9c98ad985d7494b9b725bd228, before Linux 2.6.28 +(see kernel file +.IR Documentation/powerpc/ppc_htab.txt ) +is pruned +each time the system hits the idle loop. +.TP +.I /proc/sys/kernel/keys/ +This directory contains various files that define parameters and limits +for the key-management facility. +These files are described in +.BR keyrings (7). +.TP +.IR /proc/sys/kernel/kptr_restrict " (since Linux 2.6.38)" +.\" 455cd5ab305c90ffc422dd2e0fb634730942b257 +The value in this file determines whether kernel addresses are exposed via +.I /proc +files and other interfaces. +A value of 0 in this file imposes no restrictions. +If the value is 1, kernel pointers printed using the +.I %pK +format specifier will be replaced with zeros unless the user has the +.B CAP_SYSLOG +capability. +If the value is 2, kernel pointers printed using the +.I %pK +format specifier will be replaced with zeros regardless +of the user's capabilities. +The initial default value for this file was 1, +but the default was changed +.\" commit 411f05f123cbd7f8aa1edcae86970755a6e2a9d9 +to 0 in Linux 2.6.39. +Since Linux 3.4, +.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8 +only users with the +.B CAP_SYS_ADMIN +capability can change the value in this file. +.TP +.I /proc/sys/kernel/l2cr +(PowerPC only) This file +contains a flag that controls the L2 cache of G3 processor +boards. +If 0, the cache is disabled. +Enabled if nonzero. +.TP +.I /proc/sys/kernel/modprobe +This file contains the pathname for the kernel module loader. +The default value is +.IR /sbin/modprobe . +The file is present only if the kernel is built with the +.B CONFIG_MODULES +.RB ( CONFIG_KMOD +in Linux 2.6.26 and earlier) +option enabled. +It is described by the Linux kernel source file +.I Documentation/kmod.txt +(present only in Linux 2.4 and earlier). +.TP +.IR /proc/sys/kernel/modules_disabled " (since Linux 2.6.31)" +.\" 3d43321b7015387cfebbe26436d0e9d299162ea1 +.\" From Documentation/sysctl/kernel.txt +A toggle value indicating if modules are allowed to be loaded +in an otherwise modular kernel. +This toggle defaults to off (0), but can be set true (1). +Once true, modules can be neither loaded nor unloaded, +and the toggle cannot be set back to false. +The file is present only if the kernel is built with the +.B CONFIG_MODULES +option enabled. +.TP +.IR /proc/sys/kernel/msgmax " (since Linux 2.2)" +This file defines +a system-wide limit specifying the maximum number of bytes in +a single message written on a System V message queue. +.TP +.IR /proc/sys/kernel/msgmni " (since Linux 2.4)" +This file defines the system-wide limit on the number of +message queue identifiers. +See also +.IR /proc/sys/kernel/auto_msgmni . +.TP +.IR /proc/sys/kernel/msgmnb " (since Linux 2.2)" +This file defines a system-wide parameter used to initialize the +.I msg_qbytes +setting for subsequently created message queues. +The +.I msg_qbytes +setting specifies the maximum number of bytes that may be written to the +message queue. +.TP +.IR /proc/sys/kernel/ngroups_max " (since Linux 2.6.4)" +This is a read-only file that displays the upper limit on the +number of a process's group memberships. +.TP +.IR /proc/sys/kernel/ns_last_pid " (since Linux 3.3)" +See +.BR pid_namespaces (7). +.TP +.IR /proc/sys/kernel/ostype " and " /proc/sys/kernel/osrelease +These files +give substrings of +.IR /proc/version . +.TP +.IR /proc/sys/kernel/overflowgid " and " /proc/sys/kernel/overflowuid +These files duplicate the files +.I /proc/sys/fs/overflowgid +and +.IR /proc/sys/fs/overflowuid . +.TP +.I /proc/sys/kernel/panic +This file gives read/write access to the kernel variable +.IR panic_timeout . +If this is zero, the kernel will loop on a panic; if nonzero, +it indicates that the kernel should autoreboot after this number +of seconds. +When you use the +software watchdog device driver, the recommended setting is 60. +.TP +.IR /proc/sys/kernel/panic_on_oops " (since Linux 2.5.68)" +This file controls the kernel's behavior when an oops +or BUG is encountered. +If this file contains 0, then the system +tries to continue operation. +If it contains 1, then the system +delays a few seconds (to give klogd time to record the oops output) +and then panics. +If the +.I /proc/sys/kernel/panic +file is also nonzero, then the machine will be rebooted. +.TP +.IR /proc/sys/kernel/pid_max " (since Linux 2.5.34)" +This file specifies the value at which PIDs wrap around +(i.e., the value in this file is one greater than the maximum PID). +PIDs greater than this value are not allocated; +thus, the value in this file also acts as a system-wide limit +on the total number of processes and threads. +The default value for this file, 32768, +results in the same range of PIDs as on earlier kernels. +On 32-bit platforms, 32768 is the maximum value for +.IR pid_max . +On 64-bit systems, +.I pid_max +can be set to any value up to 2\[ha]22 +.RB ( PID_MAX_LIMIT , +approximately 4 million). +.\" Prior to Linux 2.6.10, pid_max could also be raised above 32768 on 32-bit +.\" platforms, but this broke /proc/[pid] +.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=109513010926152&w=2 +.TP +.IR /proc/sys/kernel/powersave\-nap " (PowerPC only)" +This file contains a flag. +If set, Linux-PPC will use the "nap" mode of +powersaving, +otherwise the "doze" mode will be used. +.TP +.I /proc/sys/kernel/printk +See +.BR syslog (2). +.TP +.IR /proc/sys/kernel/pty " (since Linux 2.6.4)" +This directory contains two files relating to the number of UNIX 98 +pseudoterminals (see +.BR pts (4)) +on the system. +.TP +.I /proc/sys/kernel/pty/max +This file defines the maximum number of pseudoterminals. +.\" FIXME Document /proc/sys/kernel/pty/reserve +.\" New in Linux 3.3 +.\" commit e9aba5158a80098447ff207a452a3418ae7ee386 +.TP +.I /proc/sys/kernel/pty/nr +This read-only file +indicates how many pseudoterminals are currently in use. +.TP +.I /proc/sys/kernel/random/ +This directory +contains various parameters controlling the operation of the file +.IR /dev/random . +See +.BR random (4) +for further information. +.TP +.IR /proc/sys/kernel/random/uuid " (since Linux 2.4)" +Each read from this read-only file returns a randomly generated 128-bit UUID, +as a string in the standard UUID format. +.TP +.IR /proc/sys/kernel/randomize_va_space " (since Linux 2.6.12)" +.\" Some further details can be found in Documentation/sysctl/kernel.txt +Select the address space layout randomization (ASLR) policy for the system +(on architectures that support ASLR). +Three values are supported for this file: +.RS +.TP +.B 0 +Turn ASLR off. +This is the default for architectures that don't support ASLR, +and when the kernel is booted with the +.I norandmaps +parameter. +.TP +.B 1 +Make the addresses of +.BR mmap (2) +allocations, the stack, and the VDSO page randomized. +Among other things, this means that shared libraries will be +loaded at randomized addresses. +The text segment of PIE-linked binaries will also be loaded +at a randomized address. +This value is the default if the kernel was configured with +.BR CONFIG_COMPAT_BRK . +.TP +.B 2 +(Since Linux 2.6.25) +.\" commit c1d171a002942ea2d93b4fbd0c9583c56fce0772 +Also support heap randomization. +This value is the default if the kernel was not configured with +.BR CONFIG_COMPAT_BRK . +.RE +.TP +.I /proc/sys/kernel/real\-root\-dev +This file is documented in the Linux kernel source file +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10). +.TP +.IR /proc/sys/kernel/reboot\-cmd " (Sparc only)" +This file seems to be a way to give an argument to the SPARC +ROM/Flash boot loader. +Maybe to tell it what to do after +rebooting? +.TP +.I /proc/sys/kernel/rtsig\-max +(Up to and including Linux 2.6.7; see +.BR setrlimit (2)) +This file can be used to tune the maximum number +of POSIX real-time (queued) signals that can be outstanding +in the system. +.TP +.I /proc/sys/kernel/rtsig\-nr +(Up to and including Linux 2.6.7.) +This file shows the number of POSIX real-time signals currently queued. +.TP +.IR /proc/ pid /sched_autogroup_enabled " (since Linux 2.6.38)" +.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/sched_child_runs_first " (since Linux 2.6.23)" +If this file contains the value zero, then, after a +.BR fork (2), +the parent is first scheduled on the CPU. +If the file contains a nonzero value, +then the child is scheduled first on the CPU. +(Of course, on a multiprocessor system, +the parent and the child might both immediately be scheduled on a CPU.) +.TP +.IR /proc/sys/kernel/sched_rr_timeslice_ms " (since Linux 3.9)" +See +.BR sched_rr_get_interval (2). +.TP +.IR /proc/sys/kernel/sched_rt_period_us " (since Linux 2.6.25)" +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/sched_rt_runtime_us " (since Linux 2.6.25)" +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/seccomp/ " (since Linux 4.14)" +.\" commit 8e5f1ad116df6b0de65eac458d5e7c318d1c05af +This directory provides additional seccomp information and +configuration. +See +.BR seccomp (2) +for further details. +.TP +.IR /proc/sys/kernel/sem " (since Linux 2.4)" +This file contains 4 numbers defining limits for System V IPC semaphores. +These fields are, in order: +.RS +.TP +SEMMSL +The maximum semaphores per semaphore set. +.TP +SEMMNS +A system-wide limit on the number of semaphores in all semaphore sets. +.TP +SEMOPM +The maximum number of operations that may be specified in a +.BR semop (2) +call. +.TP +SEMMNI +A system-wide limit on the maximum number of semaphore identifiers. +.RE +.TP +.I /proc/sys/kernel/sg\-big\-buff +This file +shows the size of the generic SCSI device (sg) buffer. +You can't tune it just yet, but you could change it at +compile time by editing +.I include/scsi/sg.h +and changing +the value of +.BR SG_BIG_BUFF . +However, there shouldn't be any reason to change this value. +.TP +.IR /proc/sys/kernel/shm_rmid_forced " (since Linux 3.1)" +.\" commit b34a6b1da371ed8af1221459a18c67970f7e3d53 +.\" See also Documentation/sysctl/kernel.txt +If this file is set to 1, all System V shared memory segments will +be marked for destruction as soon as the number of attached processes +falls to zero; +in other words, it is no longer possible to create shared memory segments +that exist independently of any attached process. +.IP +The effect is as though a +.BR shmctl (2) +.B IPC_RMID +is performed on all existing segments as well as all segments +created in the future (until this file is reset to 0). +Note that existing segments that are attached to no process will be +immediately destroyed when this file is set to 1. +Setting this option will also destroy segments that were created, +but never attached, +upon termination of the process that created the segment with +.BR shmget (2). +.IP +Setting this file to 1 provides a way of ensuring that +all System V shared memory segments are counted against the +resource usage and resource limits (see the description of +.B RLIMIT_AS +in +.BR getrlimit (2)) +of at least one process. +.IP +Because setting this file to 1 produces behavior that is nonstandard +and could also break existing applications, +the default value in this file is 0. +Set this file to 1 only if you have a good understanding +of the semantics of the applications using +System V shared memory on your system. +.TP +.IR /proc/sys/kernel/shmall " (since Linux 2.2)" +This file +contains the system-wide limit on the total number of pages of +System V shared memory. +.TP +.IR /proc/sys/kernel/shmmax " (since Linux 2.2)" +This file +can be used to query and set the run-time limit +on the maximum (System V IPC) shared memory segment size that can be +created. +Shared memory segments up to 1 GB are now supported in the +kernel. +This value defaults to +.BR SHMMAX . +.TP +.IR /proc/sys/kernel/shmmni " (since Linux 2.4)" +This file +specifies the system-wide maximum number of System V shared memory +segments that can be created. +.TP +.IR /proc/sys/kernel/sysctl_writes_strict " (since Linux 3.16)" +.\" commit f88083005ab319abba5d0b2e4e997558245493c8 +.\" commit 2ca9bb456ada8bcbdc8f77f8fc78207653bbaa92 +.\" commit f4aacea2f5d1a5f7e3154e967d70cf3f711bcd61 +.\" commit 24fe831c17ab8149413874f2fd4e5c8a41fcd294 +The value in this file determines how the file offset affects +the behavior of updating entries in files under +.IR /proc/sys . +The file has three possible values: +.RS +.TP 4 +\-1 +This provides legacy handling, with no printk warnings. +Each +.BR write (2) +must fully contain the value to be written, +and multiple writes on the same file descriptor +will overwrite the entire value, regardless of the file position. +.TP +0 +(default) This provides the same behavior as for \-1, +but printk warnings are written for processes that +perform writes when the file offset is not 0. +.TP +1 +Respect the file offset when writing strings into +.I /proc/sys +files. +Multiple writes will +.I append +to the value buffer. +Anything written beyond the maximum length +of the value buffer will be ignored. +Writes to numeric +.I /proc/sys +entries must always be at file offset 0 and the value must be +fully contained in the buffer provided to +.BR write (2). +.\" FIXME . +.\" With /proc/sys/kernel/sysctl_writes_strict==1, writes at an +.\" offset other than 0 do not generate an error. Instead, the +.\" write() succeeds, but the file is left unmodified. +.\" This is surprising. The behavior may change in the future. +.\" See thread.gmane.org/gmane.linux.man/9197 +.\" From: Michael Kerrisk (man-pages +.\" Subject: sysctl_writes_strict documentation + an oddity? +.\" Newsgroups: gmane.linux.man, gmane.linux.kernel +.\" Date: 2015-05-09 08:54:11 GMT +.RE +.TP +.I /proc/sys/kernel/sysrq +This file controls the functions allowed to be invoked by the SysRq key. +By default, +the file contains 1 meaning that every possible SysRq request is allowed +(in older kernel versions, SysRq was disabled by default, +and you were required to specifically enable it at run-time, +but this is not the case any more). +Possible values in this file are: +.RS +.TP 5 +0 +Disable sysrq completely +.TP +1 +Enable all functions of sysrq +.TP +> 1 +Bit mask of allowed sysrq functions, as follows: +.PD 0 +.RS +.TP 5 +\ \ 2 +Enable control of console logging level +.TP +\ \ 4 +Enable control of keyboard (SAK, unraw) +.TP +\ \ 8 +Enable debugging dumps of processes etc. +.TP +\ 16 +Enable sync command +.TP +\ 32 +Enable remount read-only +.TP +\ 64 +Enable signaling of processes (term, kill, oom-kill) +.TP +128 +Allow reboot/poweroff +.TP +256 +Allow nicing of all real-time tasks +.RE +.PD +.RE +.IP +This file is present only if the +.B CONFIG_MAGIC_SYSRQ +kernel configuration option is enabled. +For further details see the Linux kernel source file +.I Documentation/admin\-guide/sysrq.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/sysrq.txt +before Linux 4.10). +.TP +.I /proc/sys/kernel/version +This file contains a string such as: +.IP +.in +4n +.EX +#5 Wed Feb 25 21:49:24 MET 1998 +.EE +.in +.IP +The "#5" means that +this is the fifth kernel built from this source base and the +date following it indicates the time the kernel was built. +.TP +.IR /proc/sys/kernel/threads\-max " (since Linux 2.3.11)" +.\" The following is based on Documentation/sysctl/kernel.txt +This file specifies the system-wide limit on the number of +threads (tasks) that can be created on the system. +.IP +Since Linux 4.1, +.\" commit 230633d109e35b0a24277498e773edeb79b4a331 +the value that can be written to +.I threads\-max +is bounded. +The minimum value that can be written is 20. +The maximum value that can be written is given by the +constant +.B FUTEX_TID_MASK +(0x3fffffff). +If a value outside of this range is written to +.IR threads\-max , +the error +.B EINVAL +occurs. +.IP +The value written is checked against the available RAM pages. +If the thread structures would occupy too much (more than 1/8th) +of the available RAM pages, +.I threads\-max +is reduced accordingly. +.TP +.IR /proc/sys/kernel/yama/ptrace_scope " (since Linux 3.5)" +See +.BR ptrace (2). +.TP +.IR /proc/sys/kernel/zero\-paged " (PowerPC only)" +This file +contains a flag. +When enabled (nonzero), Linux-PPC will pre-zero pages in +the idle loop, possibly speeding up get_free_pages. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man/man5/proc_sys_net.5 b/man/man5/proc_sys_net.5 new file mode 100644 index 0000000..1c3d247 --- /dev/null +++ b/man/man5/proc_sys_net.5 @@ -0,0 +1,34 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_net 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/net/ \- networking +.SH DESCRIPTION +.TP +.I /proc/sys/net/ +This directory contains networking stuff. +Explanations for some of the files under this directory can be found in +.BR tcp (7) +and +.BR ip (7). +.TP +.I /proc/sys/net/core/bpf_jit_enable +See +.BR bpf (2). +.TP +.I /proc/sys/net/core/somaxconn +This file defines a ceiling value for the +.I backlog +argument of +.BR listen (2); +see the +.BR listen (2) +manual page for details. +.SH SEE ALSO +.BR proc (5), +.BR proc_net (5) diff --git a/man/man5/proc_sys_proc.5 b/man/man5/proc_sys_proc.5 new file mode 100644 index 0000000..ced2dcb --- /dev/null +++ b/man/man5/proc_sys_proc.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_proc 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/proc/ \- ??? +.SH DESCRIPTION +.TP +.I /proc/sys/proc/ +This directory may be empty. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man/man5/proc_sys_sunrpc.5 b/man/man5/proc_sys_sunrpc.5 new file mode 100644 index 0000000..8fc9647 --- /dev/null +++ b/man/man5/proc_sys_sunrpc.5 @@ -0,0 +1,19 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_sunrpc 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/sunrpc/ \- Sun remote procedure call for NFS +.SH DESCRIPTION +.TP +.I /proc/sys/sunrpc/ +This directory supports Sun remote procedure call for network filesystem +(NFS). +On some systems, it is not present. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man/man5/proc_sys_user.5 b/man/man5/proc_sys_user.5 new file mode 100644 index 0000000..82cf4a9 --- /dev/null +++ b/man/man5/proc_sys_user.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_user 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/user/ \- limits on the number of namespaces of various types +.SH DESCRIPTION +.TP +.IR /proc/sys/user/ " (since Linux 4.9)" +See +.BR namespaces (7). +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man/man5/proc_sys_vm.5 b/man/man5/proc_sys_vm.5 new file mode 100644 index 0000000..39f8598 --- /dev/null +++ b/man/man5/proc_sys_vm.5 @@ -0,0 +1,420 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_vm 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sys/vm/ \- virtual memory subsystem +.SH DESCRIPTION +.TP +.I /proc/sys/vm/ +This directory contains files for memory management tuning, buffer, and +cache management. +.TP +.IR /proc/sys/vm/admin_reserve_kbytes " (since Linux 3.10)" +.\" commit 4eeab4f5580d11bffedc697684b91b0bca0d5009 +This file defines the amount of free memory (in KiB) on the system that +should be reserved for users with the capability +.BR CAP_SYS_ADMIN . +.IP +The default value in this file is the minimum of [3% of free pages, 8MiB] +expressed as KiB. +The default is intended to provide enough for the superuser +to log in and kill a process, if necessary, +under the default overcommit 'guess' mode (i.e., 0 in +.IR /proc/sys/vm/overcommit_memory ). +.IP +Systems running in "overcommit never" mode (i.e., 2 in +.IR /proc/sys/vm/overcommit_memory ) +should increase the value in this file to account +for the full virtual memory size of the programs used to recover (e.g., +.BR login (1) +.BR ssh (1), +and +.BR top (1)) +Otherwise, the superuser may not be able to log in to recover the system. +For example, on x86-64 a suitable value is 131072 (128MiB reserved). +.IP +Changing the value in this file takes effect whenever +an application requests memory. +.TP +.IR /proc/sys/vm/compact_memory " (since Linux 2.6.35)" +When 1 is written to this file, all zones are compacted such that free +memory is available in contiguous blocks where possible. +The effect of this action can be seen by examining +.IR /proc/buddyinfo . +.IP +Present only if the kernel was configured with +.BR CONFIG_COMPACTION . +.TP +.IR /proc/sys/vm/drop_caches " (since Linux 2.6.16)" +Writing to this file causes the kernel to drop clean caches, dentries, and +inodes from memory, causing that memory to become free. +This can be useful for memory management testing and +performing reproducible filesystem benchmarks. +Because writing to this file causes the benefits of caching to be lost, +it can degrade overall system performance. +.IP +To free pagecache, use: +.IP +.in +4n +.EX +echo 1 > /proc/sys/vm/drop_caches +.EE +.in +.IP +To free dentries and inodes, use: +.IP +.in +4n +.EX +echo 2 > /proc/sys/vm/drop_caches +.EE +.in +.IP +To free pagecache, dentries, and inodes, use: +.IP +.in +4n +.EX +echo 3 > /proc/sys/vm/drop_caches +.EE +.in +.IP +Because writing to this file is a nondestructive operation and dirty objects +are not freeable, the +user should run +.BR sync (1) +first. +.TP +.IR /proc/sys/vm/sysctl_hugetlb_shm_group " (since Linux 2.6.7)" +This writable file contains a group ID that is allowed +to allocate memory using huge pages. +If a process has a filesystem group ID or any supplementary group ID that +matches this group ID, +then it can make huge-page allocations without holding the +.B CAP_IPC_LOCK +capability; see +.BR memfd_create (2), +.BR mmap (2), +and +.BR shmget (2). +.TP +.IR /proc/sys/vm/legacy_va_layout " (since Linux 2.6.9)" +.\" The following is from Documentation/filesystems/proc.txt +If nonzero, this disables the new 32-bit memory-mapping layout; +the kernel will use the legacy (2.4) layout for all processes. +.TP +.IR /proc/sys/vm/memory_failure_early_kill " (since Linux 2.6.32)" +.\" The following is based on the text in Documentation/sysctl/vm.txt +Control how to kill processes when an uncorrected memory error +(typically a 2-bit error in a memory module) +that cannot be handled by the kernel +is detected in the background by hardware. +In some cases (like the page still having a valid copy on disk), +the kernel will handle the failure +transparently without affecting any applications. +But if there is no other up-to-date copy of the data, +it will kill processes to prevent any data corruptions from propagating. +.IP +The file has one of the following values: +.RS +.TP +.B 1 +Kill all processes that have the corrupted-and-not-reloadable page mapped +as soon as the corruption is detected. +Note that this is not supported for a few types of pages, +such as kernel internally +allocated data or the swap cache, but works for the majority of user pages. +.TP +.B 0 +Unmap the corrupted page from all processes and kill a process +only if it tries to access the page. +.RE +.IP +The kill is performed using a +.B SIGBUS +signal with +.I si_code +set to +.BR BUS_MCEERR_AO . +Processes can handle this if they want to; see +.BR sigaction (2) +for more details. +.IP +This feature is active only on architectures/platforms with advanced machine +check handling and depends on the hardware capabilities. +.IP +Applications can override the +.I memory_failure_early_kill +setting individually with the +.BR prctl (2) +.B PR_MCE_KILL +operation. +.IP +Present only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.IR /proc/sys/vm/memory_failure_recovery " (since Linux 2.6.32)" +.\" The following is based on the text in Documentation/sysctl/vm.txt +Enable memory failure recovery (when supported by the platform). +.RS +.TP +.B 1 +Attempt recovery. +.TP +.B 0 +Always panic on a memory failure. +.RE +.IP +Present only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.IR /proc/sys/vm/oom_dump_tasks " (since Linux 2.6.25)" +.\" The following is from Documentation/sysctl/vm.txt +Enables a system-wide task dump (excluding kernel threads) to be +produced when the kernel performs an OOM-killing. +The dump includes the following information +for each task (thread, process): +thread ID, real user ID, thread group ID (process ID), +virtual memory size, resident set size, +the CPU that the task is scheduled on, +oom_adj score (see the description of +.IR /proc/ pid /oom_adj ), +and command name. +This is helpful to determine why the OOM-killer was invoked +and to identify the rogue task that caused it. +.IP +If this contains the value zero, this information is suppressed. +On very large systems with thousands of tasks, +it may not be feasible to dump the memory state information for each one. +Such systems should not be forced to incur a performance penalty in +OOM situations when the information may not be desired. +.IP +If this is set to nonzero, this information is shown whenever the +OOM-killer actually kills a memory-hogging task. +.IP +The default value is 0. +.TP +.IR /proc/sys/vm/oom_kill_allocating_task " (since Linux 2.6.24)" +.\" The following is from Documentation/sysctl/vm.txt +This enables or disables killing the OOM-triggering task in +out-of-memory situations. +.IP +If this is set to zero, the OOM-killer will scan through the entire +tasklist and select a task based on heuristics to kill. +This normally selects a rogue memory-hogging task that +frees up a large amount of memory when killed. +.IP +If this is set to nonzero, the OOM-killer simply kills the task that +triggered the out-of-memory condition. +This avoids a possibly expensive tasklist scan. +.IP +If +.I /proc/sys/vm/panic_on_oom +is nonzero, it takes precedence over whatever value is used in +.IR /proc/sys/vm/oom_kill_allocating_task . +.IP +The default value is 0. +.TP +.IR /proc/sys/vm/overcommit_kbytes " (since Linux 3.14)" +.\" commit 49f0ce5f92321cdcf741e35f385669a421013cb7 +This writable file provides an alternative to +.I /proc/sys/vm/overcommit_ratio +for controlling the +.I CommitLimit +when +.I /proc/sys/vm/overcommit_memory +has the value 2. +It allows the amount of memory overcommitting to be specified as +an absolute value (in kB), +rather than as a percentage, as is done with +.IR overcommit_ratio . +This allows for finer-grained control of +.I CommitLimit +on systems with extremely large memory sizes. +.IP +Only one of +.I overcommit_kbytes +or +.I overcommit_ratio +can have an effect: +if +.I overcommit_kbytes +has a nonzero value, then it is used to calculate +.IR CommitLimit , +otherwise +.I overcommit_ratio +is used. +Writing a value to either of these files causes the +value in the other file to be set to zero. +.TP +.I /proc/sys/vm/overcommit_memory +This file contains the kernel virtual memory accounting mode. +Values are: +.RS +.IP +0: heuristic overcommit (this is the default) +.br +1: always overcommit, never check +.br +2: always check, never overcommit +.RE +.IP +In mode 0, calls of +.BR mmap (2) +with +.B MAP_NORESERVE +are not checked, and the default check is very weak, +leading to the risk of getting a process "OOM-killed". +.IP +In mode 1, the kernel pretends there is always enough memory, +until memory actually runs out. +One use case for this mode is scientific computing applications +that employ large sparse arrays. +Before Linux 2.6.0, any nonzero value implies mode 1. +.IP +In mode 2 (available since Linux 2.6), the total virtual address space +that can be allocated +.RI ( CommitLimit +in +.IR /proc/meminfo ) +is calculated as +.IP +.in +4n +.EX +CommitLimit = (total_RAM \- total_huge_TLB) * + overcommit_ratio / 100 + total_swap +.EE +.in +.IP +where: +.RS +.IP \[bu] 3 +.I total_RAM +is the total amount of RAM on the system; +.IP \[bu] +.I total_huge_TLB +is the amount of memory set aside for huge pages; +.IP \[bu] +.I overcommit_ratio +is the value in +.IR /proc/sys/vm/overcommit_ratio ; +and +.IP \[bu] +.I total_swap +is the amount of swap space. +.RE +.IP +For example, on a system with 16 GB of physical RAM, 16 GB +of swap, no space dedicated to huge pages, and an +.I overcommit_ratio +of 50, this formula yields a +.I CommitLimit +of 24 GB. +.IP +Since Linux 3.14, if the value in +.I /proc/sys/vm/overcommit_kbytes +is nonzero, then +.I CommitLimit +is instead calculated as: +.IP +.in +4n +.EX +CommitLimit = overcommit_kbytes + total_swap +.EE +.in +.IP +See also the description of +.I /proc/sys/vm/admin_reserve_kbytes +and +.IR /proc/sys/vm/user_reserve_kbytes . +.TP +.IR /proc/sys/vm/overcommit_ratio " (since Linux 2.6.0)" +This writable file defines a percentage by which memory +can be overcommitted. +The default value in the file is 50. +See the description of +.IR /proc/sys/vm/overcommit_memory . +.TP +.IR /proc/sys/vm/panic_on_oom " (since Linux 2.6.18)" +.\" The following is adapted from Documentation/sysctl/vm.txt +This enables or disables a kernel panic in +an out-of-memory situation. +.IP +If this file is set to the value 0, +the kernel's OOM-killer will kill some rogue process. +Usually, the OOM-killer is able to kill a rogue process and the +system will survive. +.IP +If this file is set to the value 1, +then the kernel normally panics when out-of-memory happens. +However, if a process limits allocations to certain nodes +using memory policies +.RB ( mbind (2) +.BR MPOL_BIND ) +or cpusets +.RB ( cpuset (7)) +and those nodes reach memory exhaustion status, +one process may be killed by the OOM-killer. +No panic occurs in this case: +because other nodes' memory may be free, +this means the system as a whole may not have reached +an out-of-memory situation yet. +.IP +If this file is set to the value 2, +the kernel always panics when an out-of-memory condition occurs. +.IP +The default value is 0. +1 and 2 are for failover of clustering. +Select either according to your policy of failover. +.TP +.I /proc/sys/vm/swappiness +.\" The following is from Documentation/sysctl/vm.txt +The value in this file controls how aggressively the kernel will swap +memory pages. +Higher values increase aggressiveness, lower values +decrease aggressiveness. +The default value is 60. +.TP +.IR /proc/sys/vm/user_reserve_kbytes " (since Linux 3.10)" +.\" commit c9b1d0981fcce3d9976d7b7a56e4e0503bc610dd +Specifies an amount of memory (in KiB) to reserve for user processes. +This is intended to prevent a user from starting a single memory hogging +process, such that they cannot recover (kill the hog). +The value in this file has an effect only when +.I /proc/sys/vm/overcommit_memory +is set to 2 ("overcommit never" mode). +In this case, the system reserves an amount of memory that is the minimum +of [3% of current process size, +.IR user_reserve_kbytes ]. +.IP +The default value in this file is the minimum of [3% of free pages, 128MiB] +expressed as KiB. +.IP +If the value in this file is set to zero, +then a user will be allowed to allocate all free memory with a single process +(minus the amount reserved by +.IR /proc/sys/vm/admin_reserve_kbytes ). +Any subsequent attempts to execute a command will result in +"fork: Cannot allocate memory". +.IP +Changing the value in this file takes effect whenever +an application requests memory. +.TP +.IR /proc/sys/vm/unprivileged_userfaultfd " (since Linux 5.2)" +.\" cefdca0a86be517bc390fc4541e3674b8e7803b0 +This (writable) file exposes a flag that controls whether +unprivileged processes are allowed to employ +.BR userfaultfd (2). +If this file has the value 1, then unprivileged processes may use +.BR userfaultfd (2). +If this file has the value 0, then only processes that have the +.B CAP_SYS_PTRACE +capability may employ +.BR userfaultfd (2). +The default value in this file is 1. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man/man5/proc_sysrq-trigger.5 b/man/man5/proc_sysrq-trigger.5 new file mode 100644 index 0000000..2d42047 --- /dev/null +++ b/man/man5/proc_sysrq-trigger.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sysrq-trigger 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sysrq\-trigger \- SysRq function +.SH DESCRIPTION +.TP +.IR /proc/sysrq\-trigger " (since Linux 2.4.21)" +Writing a character to this file triggers the same SysRq function as +typing ALT-SysRq- (see the description of +.IR /proc/sys/kernel/sysrq ). +This file is normally writable only by +.IR root . +For further details see the Linux kernel source file +.I Documentation/admin\-guide/sysrq.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/sysrq.txt +before Linux 4.10). +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_sysvipc.5 b/man/man5/proc_sysvipc.5 new file mode 100644 index 0000000..567388d --- /dev/null +++ b/man/man5/proc_sysvipc.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sysvipc 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/sysvipc/ \- System V IPC +.SH DESCRIPTION +.TP +.I /proc/sysvipc/ +Subdirectory containing the pseudo-files +.IR msg ", " sem " and " shm "." +These files list the System V Interprocess Communication (IPC) objects +(respectively: message queues, semaphores, and shared memory) +that currently exist on the system, +providing similar information to that available via +.BR ipcs (1). +These files have headers and are formatted (one IPC object per line) +for easy understanding. +.BR sysvipc (7) +provides further background on the information shown by these files. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_thread-self.5 b/man/man5/proc_thread-self.5 new file mode 100644 index 0000000..2c760e9 --- /dev/null +++ b/man/man5/proc_thread-self.5 @@ -0,0 +1 @@ +.so man5/proc_pid_task.5 diff --git a/man/man5/proc_tid.5 b/man/man5/proc_tid.5 new file mode 100644 index 0000000..2c760e9 --- /dev/null +++ b/man/man5/proc_tid.5 @@ -0,0 +1 @@ +.so man5/proc_pid_task.5 diff --git a/man/man5/proc_tid_children.5 b/man/man5/proc_tid_children.5 new file mode 100644 index 0000000..0b40774 --- /dev/null +++ b/man/man5/proc_tid_children.5 @@ -0,0 +1,37 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_tid_children 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/tid/children \- child tasks +.SH DESCRIPTION +.TP +.IR /proc/ tid /children " (since Linux 3.5)" +.\" commit 818411616baf46ceba0cff6f05af3a9b294734f7 +A space-separated list of child tasks of this task. +Each child task is represented by its TID. +.IP +.\" see comments in get_children_pid() in fs/proc/array.c +This option is intended for use by the checkpoint-restore (CRIU) system, +and reliably provides a list of children only if all of the child processes +are stopped or frozen. +It does not work properly if children of the target task exit while +the file is being read! +Exiting children may cause non-exiting children to be omitted from the list. +This makes this interface even more unreliable than classic PID-based +approaches if the inspected task and its children aren't frozen, +and most code should probably not use this interface. +.IP +Until Linux 4.2, the presence of this file was governed by the +.B CONFIG_CHECKPOINT_RESTORE +kernel configuration option. +Since Linux 4.2, +.\" commit 2e13ba54a2682eea24918b87ad3edf70c2cf085b +it is governed by the +.B CONFIG_PROC_CHILDREN +option. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_timer_list.5 b/man/man5/proc_timer_list.5 new file mode 100644 index 0000000..8872391 --- /dev/null +++ b/man/man5/proc_timer_list.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_timer_list 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/timer_list \- pending timers +.SH DESCRIPTION +.TP +.IR /proc/timer_list " (since Linux 2.6.21)" +.\" commit 289f480af87e45f7a6de6ba9b4c061c2e259fe98 +This read-only file exposes a list of all currently pending +(high-resolution) timers, +all clock-event sources, and their parameters in a human-readable form. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_timer_stats.5 b/man/man5/proc_timer_stats.5 new file mode 100644 index 0000000..beb034a --- /dev/null +++ b/man/man5/proc_timer_stats.5 @@ -0,0 +1,117 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_timer_stats 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/timer_stats \- timer statistics +.SH DESCRIPTION +.TP +.IR /proc/timer_stats " (from Linux 2.6.21 until Linux 4.10)" +.\" commit 82f67cd9fca8c8762c15ba7ed0d5747588c1e221 +.\" Date: Fri Feb 16 01:28:13 2007 -0800 +.\" Text largely derived from Documentation/timers/timer_stats.txt +.\" removed in commit dfb4357da6ddbdf57d583ba64361c9d792b0e0b1 +.\" Date: Wed Feb 8 11:26:59 2017 -0800 +This is a debugging facility to make timer (ab)use in a Linux +system visible to kernel and user-space developers. +It can be used by kernel and user-space developers to verify that +their code does not make undue use of timers. +The goal is to avoid unnecessary wakeups, +thereby optimizing power consumption. +.IP +If enabled in the kernel +.RB ( CONFIG_TIMER_STATS ), +but not used, +it has almost zero run-time overhead and a relatively small +data-structure overhead. +Even if collection is enabled at run time, overhead is low: +all the locking is per-CPU and lookup is hashed. +.IP +The +.I /proc/timer_stats +file is used both to control sampling facility and to read out the +sampled information. +.IP +The +.I timer_stats +functionality is inactive on bootup. +A sampling period can be started using the following command: +.IP +.in +4n +.EX +# echo 1 > /proc/timer_stats +.EE +.in +.IP +The following command stops a sampling period: +.IP +.in +4n +.EX +# echo 0 > /proc/timer_stats +.EE +.in +.IP +The statistics can be retrieved by: +.IP +.in +4n +.EX +$ cat /proc/timer_stats +.EE +.in +.IP +While sampling is enabled, each readout from +.I /proc/timer_stats +will see +newly updated statistics. +Once sampling is disabled, the sampled information +is kept until a new sample period is started. +This allows multiple readouts. +.IP +Sample output from +.IR /proc/timer_stats : +.IP +.in +4n +.EX +.RB $ " cat /proc/timer_stats" +Timer Stats Version: v0.3 +Sample period: 1.764 s +Collection: active + 255, 0 swapper/3 hrtimer_start_range_ns (tick_sched_timer) + 71, 0 swapper/1 hrtimer_start_range_ns (tick_sched_timer) + 58, 0 swapper/0 hrtimer_start_range_ns (tick_sched_timer) + 4, 1694 gnome\-shell mod_delayed_work_on (delayed_work_timer_fn) + 17, 7 rcu_sched rcu_gp_kthread (process_timeout) +\&... + 1, 4911 kworker/u16:0 mod_delayed_work_on (delayed_work_timer_fn) + 1D, 2522 kworker/0:0 queue_delayed_work_on (delayed_work_timer_fn) +1029 total events, 583.333 events/sec +.EE +.in +.IP +The output columns are: +.RS +.IP [1] 5 +a count of the number of events, +optionally (since Linux 2.6.23) followed by the letter \[aq]D\[aq] +.\" commit c5c061b8f9726bc2c25e19dec227933a13d1e6b7 deferrable timers +if this is a deferrable timer; +.IP [2] +the PID of the process that initialized the timer; +.IP [3] +the name of the process that initialized the timer; +.IP [4] +the function where the timer was initialized; and +(in parentheses) +the callback function that is associated with the timer. +.RE +.IP +During the Linux 4.11 development cycle, +this file was removed because of security concerns, +as it exposes information across namespaces. +Furthermore, it is possible to obtain +the same information via in-kernel tracing facilities such as ftrace. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_tty.5 b/man/man5/proc_tty.5 new file mode 100644 index 0000000..ac9523d --- /dev/null +++ b/man/man5/proc_tty.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_tty 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/tty/ \- tty +.SH DESCRIPTION +.TP +.I /proc/tty/ +Subdirectory containing the pseudo-files and subdirectories for +tty drivers and line disciplines. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_uptime.5 b/man/man5/proc_uptime.5 new file mode 100644 index 0000000..6d223db --- /dev/null +++ b/man/man5/proc_uptime.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_uptime 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/uptime \- system uptime +.SH DESCRIPTION +.TP +.I /proc/uptime +This file contains two numbers (values in seconds): the uptime of the +system (including time spent in suspend) and the amount of time spent +in the idle process. +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_version.5 b/man/man5/proc_version.5 new file mode 100644 index 0000000..969fc32 --- /dev/null +++ b/man/man5/proc_version.5 @@ -0,0 +1,27 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_version 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/version \- kernel version +.SH DESCRIPTION +.TP +.I /proc/version +This string identifies the kernel version that is currently running. +It includes the contents of +.IR /proc/sys/kernel/ostype , +.IR /proc/sys/kernel/osrelease , +and +.IR /proc/sys/kernel/version . +For example: +.IP +.in +4n +.EX +Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994 +.EE +.in +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_vmstat.5 b/man/man5/proc_vmstat.5 new file mode 100644 index 0000000..71c71c5 --- /dev/null +++ b/man/man5/proc_vmstat.5 @@ -0,0 +1,702 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_vmstat 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/vmstat \- virtual memory statistics +.SH DESCRIPTION +.TP +.IR /proc/vmstat " (since Linux 2.6.0)" +This file displays various virtual memory statistics. +Each line of this file contains a single name-value pair, +delimited by white space. +Some lines are present only if the kernel was configured with +suitable options. +(In some cases, the options required for particular files have changed +across kernel versions, so they are not listed here. +Details can be found by consulting the kernel source code.) +The following fields may be present: +.\" FIXME We need explanations for each of the following fields... +.RS +.TP +.IR nr_free_pages " (since Linux 2.6.31)" +.\" commit d23ad42324cc4378132e51f2fc5c9ba6cbe75182 +.TP +.IR nr_alloc_batch " (since Linux 3.12)" +.\" commit 81c0a2bb515fd4daae8cab64352877480792b515 +.TP +.IR nr_inactive_anon " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_active_anon " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_inactive_file " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_active_file " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_unevictable " (since Linux 2.6.28)" +.\" commit 7b854121eb3e5ba0241882ff939e2c485228c9c5 +.TP +.IR nr_mlock " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.TP +.IR nr_anon_pages " (since Linux 2.6.18)" +.\" commit f3dbd34460ff54962d3e3244b6bcb7f5295356e6 +.TP +.IR nr_mapped " (since Linux 2.6.0)" +.TP +.IR nr_file_pages " (since Linux 2.6.18)" +.\" commit 347ce434d57da80fd5809c0c836f206a50999c26 +.TP +.IR nr_dirty " (since Linux 2.6.0)" +.TP +.IR nr_writeback " (since Linux 2.6.0)" +.TP +.IR nr_slab_reclaimable " (since Linux 2.6.19)" +.\" commit 972d1a7b140569084439a81265a0f15b74e924e0 +.\" Linux 2.6.0 had nr_slab +.TP +.IR nr_slab_unreclaimable " (since Linux 2.6.19)" +.\" commit 972d1a7b140569084439a81265a0f15b74e924e0 +.TP +.IR nr_page_table_pages " (since Linux 2.6.0)" +.TP +.IR nr_kernel_stack " (since Linux 2.6.32)" +.\" commit c6a7f5728a1db45d30df55a01adc130b4ab0327c +Amount of memory allocated to kernel stacks. +.TP +.IR nr_unstable " (since Linux 2.6.0)" +.TP +.IR nr_bounce " (since Linux 2.6.12)" +.\" commit edfbe2b0038723e5699ab22695ccd62b5542a5c1 +.TP +.IR nr_vmscan_write " (since Linux 2.6.19)" +.\" commit e129b5c23c2b471d47f1c5d2b8b193fc2034af43 +.TP +.IR nr_vmscan_immediate_reclaim " (since Linux 3.2)" +.\" commit 49ea7eb65e7c5060807fb9312b1ad4c3eab82e2c +.TP +.IR nr_writeback_temp " (since Linux 2.6.26)" +.\" commit fc3ba692a4d19019387c5acaea63131f9eab05dd +.TP +.IR nr_isolated_anon " (since Linux 2.6.32)" +.\" commit a731286de62294b63d8ceb3c5914ac52cc17e690 +.TP +.IR nr_isolated_file " (since Linux 2.6.32)" +.\" commit a731286de62294b63d8ceb3c5914ac52cc17e690 +.TP +.IR nr_shmem " (since Linux 2.6.32)" +.\" commit 4b02108ac1b3354a22b0d83c684797692efdc395 +Pages used by shmem and +.BR tmpfs (5). +.TP +.IR nr_dirtied " (since Linux 2.6.37)" +.\" commit ea941f0e2a8c02ae876cd73deb4e1557248f258c +.TP +.IR nr_written " (since Linux 2.6.37)" +.\" commit ea941f0e2a8c02ae876cd73deb4e1557248f258c +.TP +.IR nr_pages_scanned " (since Linux 3.17)" +.\" commit 0d5d823ab4e608ec7b52ac4410de4cb74bbe0edd +.TP +.IR numa_hit " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_miss " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_foreign " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_interleave " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_local " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_other " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR workingset_refault " (since Linux 3.15)" +.\" commit a528910e12ec7ee203095eb1711468a66b9b60b0 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR workingset_activate " (since Linux 3.15)" +.\" commit a528910e12ec7ee203095eb1711468a66b9b60b0 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR workingset_nodereclaim " (since Linux 3.15)" +.\" commit 449dd6984d0e47643c04c807f609dd56d48d5bcc +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_anon_transparent_hugepages " (since Linux 2.6.38)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_free_cma " (since Linux 3.7)" +.\" commit d1ce749a0db12202b711d1aba1d29e823034648d +Number of free CMA (Contiguous Memory Allocator) pages. +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_dirty_threshold " (since Linux 2.6.37)" +.\" commit 79da826aee6a10902ef411bc65864bd02102fa83 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_dirty_background_threshold " (since Linux 2.6.37)" +.\" commit 79da826aee6a10902ef411bc65864bd02102fa83 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgpgin " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgpgout " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pswpin " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pswpout " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_dma " (since Linux 2.6.5)" +.\" Linux 2.6.0 had pgalloc +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_high " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgalloc_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgfree " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgactivate " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgdeactivate " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgfault " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgmajfault " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_dma " (since Linux 2.6.5)" +.\" Linux 2.6.0 had pgrefill +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_high " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgrefill_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.\" Formerly there were +.\" pgsteal_high +.\" pgsteal_normal +.\" pgsteal_dma32 +.\" pgsteal_dma +.\" These were split out into pgsteal_kswapd* and pgsteal_direct* +.\" in commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.TP +.IR pgsteal_kswapd_dma " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Linux 2.6.0 had pgsteal +.\" Present only if the kernel was configured with +.\" .\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_dma32 " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_normal " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_high " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgsteal_kswapd_movable " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgsteal_direct_dma +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_dma32 " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_normal " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_high " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgsteal_direct_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_kswapd_dma +.\" Linux 2.6.0 had pgscan +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_kswapd_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_kswapd_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_kswapd_high +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgscan_kswapd_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_direct_dma +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_direct_normal +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_direct_high +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgscan_direct_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_throttle " (since Linux 3.6)" +.\" commit 68243e76ee343d63c6cf76978588a885951e2818 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR zone_reclaim_failed " (since linux 2.6.31)" +.\" commit 24cf72518c79cdcda486ed26074ff8151291cf65 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA . +.TP +.IR pginodesteal " (since linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR slabs_scanned " (since linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_inodesteal " (since linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_low_wmark_hit_quickly " (since Linux 2.6.33)" +.\" commit bb3ab596832b920c703d1aea1ce76d69c0f71fb7 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_high_wmark_hit_quickly " (since Linux 2.6.33)" +.\" commit bb3ab596832b920c703d1aea1ce76d69c0f71fb7 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pageoutrun " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR allocstall " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrotated " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR drop_pagecache " (since Linux 3.15)" +.\" commit 5509a5d27b971a90b940e148ca9ca53312e4fa7a +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR drop_slab " (since Linux 3.15)" +.\" commit 5509a5d27b971a90b940e148ca9ca53312e4fa7a +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR numa_pte_updates " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_huge_pte_updates " (since Linux 3.13)" +.\" commit 72403b4a0fbdf433c1fe0127e49864658f6f6468 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_hint_faults " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_hint_faults_local " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_pages_migrated " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR pgmigrate_success " (since Linux 3.8)" +.\" commit 5647bc293ab15f66a7b1cda850c5e9d162a6c7c2 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MIGRATION . +.TP +.IR pgmigrate_fail " (since Linux 3.8)" +.\" commit 5647bc293ab15f66a7b1cda850c5e9d162a6c7c2 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MIGRATION . +.TP +.IR compact_migrate_scanned " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Linux 3.8 dropped compact_blocks_moved, compact_pages_moved, and +.\" compact_pagemigrate_failed +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_free_scanned " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_isolated " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_stall " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_fail " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_success " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR htlb_buddy_alloc_success " (since Linux 2.6.26)" +.\" commit 3b1163006332302117b1b2acf226d4014ff46525 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HUGETLB_PAGE . +.TP +.IR htlb_buddy_alloc_fail " (since Linux 2.6.26)" +.\" commit 3b1163006332302117b1b2acf226d4014ff46525 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HUGETLB_PAGE . +.TP +.IR unevictable_pgs_culled " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_scanned " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_rescued " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_mlocked " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_munlocked " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_cleared " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_stranded " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.\" Linux 3.7 removed unevictable_pgs_mlockfreed +.TP +.IR thp_fault_alloc " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_fault_fallback " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_collapse_alloc " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_collapse_alloc_failed " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_split " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_zero_page_alloc " (since Linux 3.8)" +.\" commit d8a8e1f0da3d29d7268b3300c96a059d63901b76 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_zero_page_alloc_failed " (since Linux 3.8)" +.\" commit d8a8e1f0da3d29d7268b3300c96a059d63901b76 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR balloon_inflate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MEMORY_BALLOON . +.TP +.IR balloon_deflate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MEMORY_BALLOON . +.TP +.IR balloon_migrate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS , +.\" .BR CONFIG_MEMORY_BALLOON , +.\" and +.\" .BR CONFIG_BALLOON_COMPACTION . +.TP +.IR nr_tlb_remote_flush " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH +.\" and +.\" .BR CONFIG_SMP . +.TP +.IR nr_tlb_remote_flush_received " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH +.\" and +.\" .BR CONFIG_SMP . +.TP +.IR nr_tlb_local_flush_all " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH . +.TP +.IR nr_tlb_local_flush_one " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH . +.TP +.IR vmacache_find_calls " (since Linux 3.16)" +.\" commit 4f115147ff802267d0aa41e361c5aa5bd933d896 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.TP +.IR vmacache_find_hits " (since Linux 3.16)" +.\" commit 4f115147ff802267d0aa41e361c5aa5bd933d896 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.TP +.IR vmacache_full_flushes " (since Linux 3.19)" +.\" commit f5f302e21257ebb0c074bbafc37606c26d28cc3d +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/proc_zoneinfo.5 b/man/man5/proc_zoneinfo.5 new file mode 100644 index 0000000..86fe380 --- /dev/null +++ b/man/man5/proc_zoneinfo.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_zoneinfo 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +/proc/zoneinfo \- memory zones +.SH DESCRIPTION +.TP +.IR /proc/zoneinfo " (since Linux 2.6.13)" +This file displays information about memory zones. +This is useful for analyzing virtual memory behavior. +.\" FIXME more should be said about /proc/zoneinfo +.SH SEE ALSO +.BR proc (5) diff --git a/man/man5/procfs.5 b/man/man5/procfs.5 new file mode 100644 index 0000000..d8be74a --- /dev/null +++ b/man/man5/procfs.5 @@ -0,0 +1 @@ +.so man5/proc.5 diff --git a/man/man5/protocols.5 b/man/man5/protocols.5 new file mode 100644 index 0000000..41630c5 --- /dev/null +++ b/man/man5/protocols.5 @@ -0,0 +1,66 @@ +.\" Copyright (c) 1995 Martin Schulze +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1995-10-18 Martin Schulze +.\" * first released +.\" 2002-09-22 Seth W. Klein +.\" * protocol numbers are now assigned by the IANA +.\" +.TH protocols 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +protocols \- protocols definition file +.SH DESCRIPTION +This file is a plain ASCII file, describing the various DARPA internet +protocols that are available from the TCP/IP subsystem. +It should be +consulted instead of using the numbers in the ARPA include files, or, +even worse, just guessing them. +These numbers will occur in the +protocol field of any IP header. +.P +Keep this file untouched since changes would result in incorrect IP +packages. +Protocol numbers and names are specified by the IANA +(Internet Assigned Numbers Authority). +.\" .. by the DDN Network Information Center. +.P +Each line is of the following format: +.P +.RS +.I protocol number aliases .\|.\|. +.RE +.P +where the fields are delimited by spaces or tabs. +Empty lines are ignored. +If a line contains a hash mark (#), the hash mark and the part +of the line following it are ignored. +.P +The field descriptions are: +.TP +.I protocol +the native name for the protocol. +For example +.IR ip , +.IR tcp , +or +.IR udp . +.TP +.I number +the official number for this protocol as it will appear within the IP +header. +.TP +.I aliases +optional aliases for the protocol. +.P +This file might be distributed over a network using a network-wide +naming service like Yellow Pages/NIS or BIND/Hesiod. +.SH FILES +.TP +.I /etc/protocols +The protocols definition file. +.SH SEE ALSO +.BR getprotoent (3) +.P +.UR http://www.iana.org\:/assignments\:/protocol\-numbers +.UE diff --git a/man/man5/repertoiremap.5 b/man/man5/repertoiremap.5 new file mode 100644 index 0000000..d785c8d --- /dev/null +++ b/man/man5/repertoiremap.5 @@ -0,0 +1,58 @@ +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH repertoiremap 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +repertoiremap \- map symbolic character names to Unicode code points +.SH DESCRIPTION +A repertoire map defines mappings between symbolic character names +(mnemonics) and Unicode code points when compiling a locale with +.BR localedef (1). +Using a repertoire map is optional, it is needed only when symbolic +names are used instead of now preferred Unicode code points. +.SS Syntax +The repertoiremap file starts with a header that may consist of the +following keywords: +.TP +.I comment_char +is followed by a character that will be used as the +comment character for the rest of the file. +It defaults to the number sign (#). +.TP +.I escape_char +is followed by a character that should be used as the escape character +for the rest of the file to mark characters that should be interpreted +in a special way. +It defaults to the backslash (\e). +.P +The mapping section starts with the keyword +.I CHARIDS +in the first column. +.P +The mapping lines have the following form: +.TP +.I comment +This defines exactly one mapping, +.I comment +being optional. +.P +The mapping section ends with the string +.IR "END CHARIDS" . +.SH FILES +.TP +.I /usr/share/i18n/repertoiremaps +Usual default repertoire map path. +.SH STANDARDS +POSIX.2. +.SH NOTES +Repertoire maps are deprecated in favor of Unicode code points. +.SH EXAMPLES +A mnemonic for the Euro sign can be defined as follows: +.P +.nf + EURO SIGN +.fi +.SH SEE ALSO +.BR locale (1), +.BR localedef (1), +.BR charmap (5), +.BR locale (5) diff --git a/man/man5/resolv.conf.5 b/man/man5/resolv.conf.5 new file mode 100644 index 0000000..0f726a9 --- /dev/null +++ b/man/man5/resolv.conf.5 @@ -0,0 +1,406 @@ +.\" Copyright (c) 1986 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Redistribution and use in source and binary forms are permitted +.\" provided that the above copyright notice and this paragraph are +.\" duplicated in all such forms and that any documentation, +.\" advertising materials, and other materials related to such +.\" distribution and use acknowledge that the software was developed +.\" by the University of California, Berkeley. The name of the +.\" University may not be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %%%LICENSE_END +.\" +.\" @(#)resolver.5 5.9 (Berkeley) 12/14/89 +.\" $Id: resolver.5,v 8.6 1999/05/21 00:01:02 vixie Exp $ +.\" +.\" Added ndots remark by Bernhard R. Link - debian bug #182886 +.\" +.TH resolv.conf 5 2024-05-02 "Linux man-pages (unreleased)" +.UC 4 +.SH NAME +resolv.conf \- resolver configuration file +.SH SYNOPSIS +.nf +.B /etc/resolv.conf +.fi +.SH DESCRIPTION +The +.I resolver +is a set of routines in the C library +that provide access to the Internet Domain Name System (DNS). +The resolver configuration file contains information that is read +by the resolver routines the first time they are invoked by a process. +The file is designed to be human readable and contains a list of +keywords with values that provide various types of resolver information. +The configuration file is considered a trusted source of DNS information; +see the +.B trust-ad +option below for details. +.P +If this file does not exist, only the name server on the local machine +will be queried, and the search list contains the local domain name +determined from the hostname. +.P +The different configuration options are: +.TP +\fBnameserver\fP Name server IP address +Internet address of a name server that the resolver should query, +either an IPv4 address (in dot notation), +or an IPv6 address in colon (and possibly dot) notation as per RFC 2373. +Up to +.B MAXNS +(currently 3, see \fI\fP) name servers may be listed, +one per keyword. +If there are multiple servers, +the resolver library queries them in the order listed. +If no \fBnameserver\fP entries are present, +the default is to use the name server on the local machine. +(The algorithm used is to try a name server, and if the query times out, +try the next, until out of name servers, +then repeat trying all the name servers +until a maximum number of retries are made.) +.TP +\fBsearch\fP Search list for host-name lookup. +By default, the search list contains one entry, the local domain name. +It is determined from the local hostname returned by +.BR gethostname (2); +the local domain name is taken to be everything after the first +\[aq].\[aq]. +Finally, if the hostname does not contain a \[aq].\[aq], the +root domain is assumed as the local domain name. +.IP +This may be changed by listing the desired domain search path +following the \fIsearch\fP keyword with spaces or tabs separating +the names. +Resolver queries having fewer than +.I ndots +dots (default is 1) in them will be attempted using each component +of the search path in turn until a match is found. +For environments with multiple subdomains please read +.BI "options ndots:" n +below to avoid man-in-the-middle attacks and unnecessary +traffic for the root-dns-servers. +.\" When having a resolv.conv with a line +.\" search subdomain.domain.tld domain.tld +.\" and doing a hostlookup, for example by +.\" ping host.anothersubdomain +.\" it sends dns-requests for +.\" host.anothersubdomain. +.\" host.anothersubdomain.subdomain.domain.tld. +.\" host.anothersubdomain.domain.tld. +.\" thus not only causing unnecessary traffic for the root-dns-servers +.\" but broadcasting information to the outside and making man-in-the-middle +.\" attacks possible. +Note that this process may be slow and will generate a lot of network +traffic if the servers for the listed domains are not local, +and that queries will time out if no server is available +for one of the domains. +.IP +If there are multiple +.B search +directives, only the search list from the last instance is used. +.IP +In glibc 2.25 and earlier, the search list is limited to six domains +with a total of 256 characters. +Since glibc 2.26, +.\" glibc commit 3f853f22c87f0b671c0366eb290919719fa56c0e +the search list is unlimited. +.IP +The +.B domain +directive is an obsolete name for the +.B search +directive that handles one search list entry only. +.TP +\fBsortlist\fP +This option allows addresses returned by +.BR gethostbyname (3) +to be sorted. +A sortlist is specified by IP-address-netmask pairs. +The netmask is +optional and defaults to the natural netmask of the net. +The IP address +and optional network pairs are separated by slashes. +Up to 10 pairs may +be specified. +Here is an example: +.IP +.in +4n +sortlist 130.155.160.0/255.255.240.0 130.155.0.0 +.in +.TP +\fBoptions\fP +Options allows certain internal resolver variables to be modified. +The syntax is +.RS +.IP +\fBoptions\fP \fIoption\fP \fI...\fP +.P +where \fIoption\fP is one of the following: +.TP +\fBdebug\fP +.\" Since glibc 2.2? +Sets +.B RES_DEBUG +in +.I _res.options +(effective only if glibc was built with debug support; see +.BR resolver (3)). +.TP +.BI ndots: n +.\" Since glibc 2.2 +Sets a threshold for the number of dots which +must appear in a name given to +.BR res_query (3) +(see +.BR resolver (3)) +before an \fIinitial absolute query\fP will be made. +The default for +\fIn\fP is 1, meaning that if there are any dots in a name, the name +will be tried first as an absolute name before any \fIsearch list\fP +elements are appended to it. +The value for this option is silently capped to 15. +.TP +.BI timeout: n +.\" Since glibc 2.2 +Sets the amount of time the resolver will wait for a +response from a remote name server before retrying the +query via a different name server. +This may +.B not +be the total time taken by any resolver API call and there is no +guarantee that a single resolver API call maps to a single timeout. +Measured in seconds, +the default is +.B RES_TIMEOUT +(currently 5, see \fI\fP). +The value for this option is silently capped to 30. +.TP +.BI attempts: n +Sets the number of times the resolver will send a +query to its name servers before giving up and returning +an error to the calling application. +The default is +.B RES_DFLRETRY +(currently 2, see \fI\fP). +The value for this option is silently capped to 5. +.TP +.B rotate +.\" Since glibc 2.2 +Sets +.B RES_ROTATE +in +.IR _res.options , +which causes round-robin selection of name servers from among those listed. +This has the effect of spreading the query load among all listed servers, +rather than having all clients try the first listed server first every time. +.TP +.B no\-aaaa (since glibc 2.36) +.\" f282cdbe7f436c75864e5640a409a10485e9abb2 +Sets +.B RES_NOAAAA +in +.IR _res.options , +which suppresses AAAA queries made by the stub resolver, +including AAAA lookups triggered by NSS-based interfaces such as +.BR getaddrinfo (3). +Only DNS lookups are affected: IPv6 data in +.BR hosts (5) +is still used, +.BR getaddrinfo (3) +with +.B AI_PASSIVE +will still produce IPv6 addresses, +and configured IPv6 name servers are still used. +To produce correct Name Error (NXDOMAIN) results, +AAAA queries are translated to A queries. +This option is intended preliminary for diagnostic purposes, +to rule out that AAAA DNS queries have adverse impact. +It is incompatible with EDNS0 usage and DNSSEC validation by applications. +.TP +.B no\-check\-names +.\" since glibc 2.2 +Sets +.B RES_NOCHECKNAME +in +.IR _res.options , +which disables the modern BIND checking of incoming hostnames and +mail names for invalid characters such as underscore (_), non-ASCII, +or control characters. +.TP +.B inet6 +.\" Since glibc 2.2 +Sets +.B RES_USE_INET6 +in +.IR _res.options . +This has the effect of trying an AAAA query before an A query inside the +.BR gethostbyname (3) +function, and of mapping IPv4 responses in IPv6 "tunneled form" +if no AAAA records are found but an A record set exists. +Since glibc 2.25, +.\" b76e065991ec01299225d9da90a627ebe6c1ac97 +this option is deprecated; applications should use +.BR getaddrinfo (3), +rather than +.BR gethostbyname (3). +.TP +.BR ip6\-bytestring " (since glibc 2.3.4 to glibc 2.24)" +Sets +.B RES_USEBSTRING +in +.IR _res.options . +This causes reverse IPv6 lookups to be made using the bit-label format +described in RFC\ 2673; +if this option is not set (which is the default), then nibble format is used. +This option was removed in glibc 2.25, +since it relied on a backward-incompatible +DNS extension that was never deployed on the Internet. +.TP +.BR ip6\-dotint / no\-ip6\-dotint " (glibc 2.3.4 to glibc 2.24)" +Clear/set +.B RES_NOIP6DOTINT +in +.IR _res.options . +When this option is clear +.RB ( ip6\-dotint ), +reverse IPv6 lookups are made in the (deprecated) +.I ip6.int +zone; +when this option is set +.RB ( no\-ip6\-dotint ), +reverse IPv6 lookups are made in the +.I ip6.arpa +zone by default. +These options are available up to glibc 2.24, where +.B no\-ip6\-dotint +is the default. +Since +.B ip6\-dotint +support long ago ceased to be available on the Internet, +these options were removed in glibc 2.25. +.TP +.BR edns0 " (since glibc 2.6)" +Sets +.B RES_USE_EDNS0 +in +.IR _res.options . +This enables support for the DNS extensions described in RFC\ 2671. +.TP +.BR single\-request " (since glibc 2.10)" +Sets +.B RES_SNGLKUP +in +.IR _res.options . +By default, glibc performs IPv4 and IPv6 lookups in parallel since +glibc 2.9. +Some appliance DNS servers +cannot handle these queries properly and make the requests time out. +This option disables the behavior and makes glibc perform the IPv6 +and IPv4 requests sequentially (at the cost of some slowdown of the +resolving process). +.TP +.BR single\-request\-reopen " (since glibc 2.9)" +Sets +.B RES_SNGLKUPREOP +in +.IR _res.options . +The resolver uses the same socket for the A and AAAA requests. +Some hardware mistakenly sends back only one reply. +When that happens the client system will sit and wait for the second reply. +Turning this option on changes this behavior +so that if two requests from the same port are not handled correctly it will +close the socket and open a new one before sending the second request. +.TP +.BR no\-tld\-query " (since glibc 2.14)" +Sets +.B RES_NOTLDQUERY +in +.IR _res.options . +This option causes +.BR res_nsearch () +to not attempt to resolve an unqualified name +as if it were a top level domain (TLD). +This option can cause problems if the site has ``localhost'' as a TLD +rather than having localhost on one or more elements of the search list. +This option has no effect if neither RES_DEFNAMES or RES_DNSRCH is set. +.TP +.BR use\-vc " (since glibc 2.14)" +Sets +.B RES_USEVC +in +.IR _res.options . +This option forces the use of TCP for DNS resolutions. +.\" aef16cc8a4c670036d45590877d411a97f01e0cd +.TP +.BR no\-reload " (since glibc 2.26)" +Sets +.B RES_NORELOAD +in +.IR _res.options . +This option disables automatic reloading of a changed configuration file. +.TP +.BR trust\-ad " (since glibc 2.31)" +.\" 446997ff1433d33452b81dfa9e626b8dccf101a4 +Sets +.B RES_TRUSTAD +in +.IR _res.options . +This option controls the AD bit behavior of the stub resolver. +If a validating resolver sets the AD bit in a response, +it indicates that the data in the response was verified according +to the DNSSEC protocol. +In order to rely on the AD bit, the local system has to +trust both the DNSSEC-validating resolver and the network path to it, +which is why an explicit opt-in is required. +If the +.B trust\-ad +option is active, the stub resolver sets the AD bit in outgoing DNS +queries (to enable AD bit support), and preserves the AD bit in responses. +Without this option, the AD bit is not set in queries, +and it is always removed from responses before they are returned to the +application. +This means that applications can trust the AD bit in responses if the +.B trust\-ad +option has been set correctly. +.IP +In glibc 2.30 and earlier, +the AD is not set automatically in queries, +and is passed through unchanged to applications in responses. +.RE +.P +The \fIsearch\fP keyword of a system's \fIresolv.conf\fP file can be +overridden on a per-process basis by setting the environment variable +.B LOCALDOMAIN +to a space-separated list of search domains. +.P +The \fIoptions\fP keyword of a system's \fIresolv.conf\fP file can be +amended on a per-process basis by setting the environment variable +.B RES_OPTIONS +to a space-separated list of resolver options +as explained above under \fBoptions\fP. +.P +The keyword and value must appear on a single line, and the keyword +(e.g., \fBnameserver\fP) must start the line. +The value follows the keyword, separated by white space. +.P +Lines that contain a semicolon (;) or hash character (#) +in the first column are treated as comments. +.SH FILES +.IR /etc/resolv.conf , +.I +.SH SEE ALSO +.BR gethostbyname (3), +.BR resolver (3), +.BR host.conf (5), +.BR hosts (5), +.BR nsswitch.conf (5), +.BR hostname (7), +.BR named (8) +.P +Name Server Operations Guide for BIND diff --git a/man/man5/resolver.5 b/man/man5/resolver.5 new file mode 100644 index 0000000..86104b9 --- /dev/null +++ b/man/man5/resolver.5 @@ -0,0 +1 @@ +.so man5/resolv.conf.5 diff --git a/man/man5/rpc.5 b/man/man5/rpc.5 new file mode 100644 index 0000000..e96c39f --- /dev/null +++ b/man/man5/rpc.5 @@ -0,0 +1,83 @@ +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" +.\" %%%LICENSE_START(BSD_ONELINE_CDROM) +.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license) +.\" %%%LICENSE_END +.\" +.\" @(#)rpc.5 2.2 88/08/03 4.0 RPCSRC; from 1.4 87/11/27 SMI; +.TH rpc 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rpc \- RPC program number data base +.SH SYNOPSIS +.nf +.B /etc/rpc +.fi +.SH DESCRIPTION +The +.I rpc +file contains user readable names that +can be used in place of RPC program numbers. +Each line has the following information: +.P +.PD 0 +.IP \[bu] 3 +name of server for the RPC program +.IP \[bu] +RPC program number +.IP \[bu] +aliases +.PD +.P +Items are separated by any number of blanks and/or +tab characters. +A \[aq]#\[aq] indicates the beginning of a comment; characters from +the \[aq]#\[aq] to the end of the line are not interpreted by routines +which search the file. +.P +Here is an example of the +.I /etc/rpc +file from the Sun RPC Source distribution. +.P +.in +4n +.EX +# +# rpc 88/08/01 4.0 RPCSRC; from 1.12 88/02/07 SMI +# +portmapper 100000 portmap sunrpc +rstatd 100001 rstat rstat_svc rup perfmeter +rusersd 100002 rusers +nfs 100003 nfsprog +ypserv 100004 ypprog +mountd 100005 mount showmount +ypbind 100007 +walld 100008 rwall shutdown +yppasswdd 100009 yppasswd +etherstatd 100010 etherstat +rquotad 100011 rquotaprog quota rquota +sprayd 100012 spray +3270_mapper 100013 +rje_mapper 100014 +selection_svc 100015 selnsvc +database_svc 100016 +rexd 100017 rex +alis 100018 +sched 100019 +llockmgr 100020 +nlockmgr 100021 +x25.inr 100022 +statmon 100023 +status 100024 +bootparam 100026 +ypupdated 100028 ypupdate +keyserv 100029 keyserver +tfsd 100037 +nsed 100038 +nsemntd 100039 +.EE +.in +.SH FILES +.TP +.I /etc/rpc +RPC program number data base +.SH SEE ALSO +.BR getrpcent (3) diff --git a/man/man5/securetty.5 b/man/man5/securetty.5 new file mode 100644 index 0000000..1bd0dab --- /dev/null +++ b/man/man5/securetty.5 @@ -0,0 +1,35 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 11:06:27 1993 by Rik Faith (faith@cs.unc.edu) +.TH securetty 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +securetty \- list of terminals on which root is allowed to login +.SH DESCRIPTION +The file +.I /etc/securetty +contains the names of terminals +(one per line, without leading +.IR /dev/ ) +which are considered secure for the transmission of certain authentication +tokens. +.P +It is used by (some versions of) +.BR login (1) +to restrict the terminals +on which root is allowed to login. +See +.BR login.defs (5) +if you use the shadow suite. +.P +On PAM enabled systems, it is used for the same purpose by +.BR pam_securetty (8) +to restrict the terminals on which empty passwords are accepted. +.SH FILES +.I /etc/securetty +.SH SEE ALSO +.BR login (1), +.BR login.defs (5), +.BR pam_securetty (8) diff --git a/man/man5/services.5 b/man/man5/services.5 new file mode 100644 index 0000000..0d8f6c8 --- /dev/null +++ b/man/man5/services.5 @@ -0,0 +1,199 @@ +.\" This manpage is Copyright (C) 1996 Austin Donnelly , +.\" with additional material Copyright (c) 1995 Martin Schulze +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" This manpage was made by merging two independently written manpages, +.\" one written by Martin Schulze (18 Oct 95), the other written by +.\" Austin Donnelly, (9 Jan 96). +.\" +.\" Thu Jan 11 12:14:41 1996 Austin Donnelly +.\" * Merged two services(5) manpages +.\" +.TH services 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +services \- Internet network services list +.SH DESCRIPTION +.B services +is a plain ASCII file providing a mapping between human-friendly textual +names for internet services, and their underlying assigned port +numbers and protocol types. +Every networking program should look into +this file to get the port number (and protocol) for its service. +The C library routines +.BR getservent (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR setservent (3), +and +.BR endservent (3) +support querying this file from programs. +.P +Port numbers are assigned by the IANA (Internet Assigned Numbers +Authority), and their current policy is to assign both TCP and UDP +protocols when assigning a port number. +Therefore, most entries will +have two entries, even for TCP-only services. +.P +Port numbers below 1024 (so-called "low numbered" ports) can be +bound to only by root (see +.BR bind (2), +.BR tcp (7), +and +.BR udp (7)). +This is so clients connecting to low numbered ports can trust +that the service running on the port is the standard implementation, +and not a rogue service run by a user of the machine. +Well-known port numbers specified by the IANA are normally +located in this root-only space. +.P +The presence of an entry for a service in the +.B services +file does not necessarily mean that the service is currently running +on the machine. +See +.BR inetd.conf (5) +for the configuration of Internet services offered. +Note that not all +networking services are started by +.BR inetd (8), +and so won't appear in +.BR inetd.conf (5). +In particular, news (NNTP) and mail (SMTP) servers are often +initialized from the system boot scripts. +.P +The location of the +.B services +file is defined by +.B _PATH_SERVICES +in +.IR "." +This is usually set to +.IR /etc/services "." +.P +Each line describes one service, and is of the form: +.IP +\f2service-name\ \ \ port\f3/\f2protocol\ \ \ \f1[\f2aliases ...\f1] +.TP +where: +.TP +.I service-name +is the friendly name the service is known by and looked up under. +It is case sensitive. +Often, the client program is named after the +.IR service-name "." +.TP +.I port +is the port number (in decimal) to use for this service. +.TP +.I protocol +is the type of protocol to be used. +This field should match an entry +in the +.BR protocols (5) +file. +Typical values include +.B tcp +and +.BR udp . +.TP +.I aliases +is an optional space or tab separated list of other names for this +service. +Again, the names are case +sensitive. +.P +Either spaces or tabs may be used to separate the fields. +.P +Comments are started by the hash sign (#) and continue until the end +of the line. +Blank lines are skipped. +.P +The +.I service-name +should begin in the first column of the file, since leading spaces are +not stripped. +.I service-names +can be any printable characters excluding space and tab. +However, a conservative choice of characters should be used to minimize +compatibility problems. +For example, a\-z, 0\-9, and hyphen (\-) would seem a +sensible choice. +.P +Lines not matching this format should not be present in the +file. +(Currently, they are silently skipped by +.BR getservent (3), +.BR getservbyname (3), +and +.BR getservbyport (3). +However, this behavior should not be relied on.) +.P +.\" The following is not true as at glibc 2.8 (a line with a comma is +.\" ignored by getservent()); it's not clear if/when it was ever true. +.\" As a backward compatibility feature, the slash (/) between the +.\" .I port +.\" number and +.\" .I protocol +.\" name can in fact be either a slash or a comma (,). +.\" Use of the comma in +.\" modern installations is deprecated. +.\" +This file might be distributed over a network using a network-wide +naming service like Yellow Pages/NIS or BIND/Hesiod. +.P +A sample +.B services +file might look like this: +.P +.in +4n +.EX +netstat 15/tcp +qotd 17/tcp quote +msp 18/tcp # message send protocol +msp 18/udp # message send protocol +chargen 19/tcp ttytst source +chargen 19/udp ttytst source +ftp 21/tcp +# 22 \- unassigned +telnet 23/tcp +.EE +.in +.SH FILES +.TP +.I /etc/services +The Internet network services list +.TP +.I +Definition of +.B _PATH_SERVICES +.\" .SH BUGS +.\" It's not clear when/if the following was ever true; +.\" it isn't true for glibc 2.8: +.\" There is a maximum of 35 aliases, due to the way the +.\" .BR getservent (3) +.\" code is written. +.\" +.\" It's not clear when/if the following was ever true; +.\" it isn't true for glibc 2.8: +.\" Lines longer than +.\" .B BUFSIZ +.\" (currently 1024) characters will be ignored by +.\" .BR getservent (3), +.\" .BR getservbyname (3), +.\" and +.\" .BR getservbyport (3). +.\" However, this will also cause the next line to be mis-parsed. +.SH SEE ALSO +.BR listen (2), +.BR endservent (3), +.BR getservbyname (3), +.BR getservbyport (3), +.BR getservent (3), +.BR setservent (3), +.BR inetd.conf (5), +.BR protocols (5), +.BR inetd (8) +.P +Assigned Numbers RFC, most recently RFC\ 1700, (AKA STD0002). diff --git a/man/man5/shells.5 b/man/man5/shells.5 new file mode 100644 index 0000000..965b2a0 --- /dev/null +++ b/man/man5/shells.5 @@ -0,0 +1,40 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Thu May 20 20:45:48 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:11:07 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Nov 21 10:49:38 1993 by Michael Haardt +.\" Modified Sun Feb 26 15:09:15 1995 by Rik Faith (faith@cs.unc.edu) +.TH shells 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +shells \- pathnames of valid login shells +.SH DESCRIPTION +.I /etc/shells +is a text file which contains the full pathnames of valid login shells. +This file is consulted by +.BR chsh (1) +and available to be queried by other programs. +.P +Be aware that there are programs which consult this file to +find out if a user is a normal user; +for example, +FTP daemons traditionally +disallow access to users with shells not included in this file. +.SH FILES +.I /etc/shells +.SH EXAMPLES +.I /etc/shells +may contain the following paths: +.P +.in +4n +.EX +.I /bin/sh +.I /bin/bash +.I /bin/csh +.EE +.in +.SH SEE ALSO +.BR chsh (1), +.BR getusershell (3), +.BR pam_shells (8) diff --git a/man/man5/slabinfo.5 b/man/man5/slabinfo.5 new file mode 100644 index 0000000..0d5160f --- /dev/null +++ b/man/man5/slabinfo.5 @@ -0,0 +1,220 @@ +.\" Copyright (c) 2001 Andreas Dilger (adilger@turbolinux.com) +.\" and Copyright (c) 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH slabinfo 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +slabinfo \- kernel slab allocator statistics +.SH SYNOPSIS +.nf +.B cat /proc/slabinfo +.fi +.SH DESCRIPTION +Frequently used objects in the Linux kernel +(buffer heads, inodes, dentries, etc.) +have their own cache. +The file +.I /proc/slabinfo +gives statistics on these caches. +The following (edited) output shows an example of the +contents of this file: +.P +.EX +$ \fBsudo cat /proc/slabinfo\fP +slabinfo \- version: 2.1 +# name ... +sigqueue 100 100 160 25 1 : tunables 0 0 0 : slabdata 4 4 0 +sighand_cache 355 405 2112 15 8 : tunables 0 0 0 : slabdata 27 27 0 +kmalloc\-8192 96 96 8192 4 8 : tunables 0 0 0 : slabdata 24 24 0 +\&... +.EE +.P +The first line of output includes a version number, +which allows an application that is reading the file to handle changes +in the file format. +(See VERSIONS, below.) +The next line lists the names of the columns in the remaining lines. +.P +Each of the remaining lines displays information about a specified cache. +Following the cache name, +the output shown in each line shows three components for each cache: +.IP \[bu] 3 +statistics +.IP \[bu] +tunables +.IP \[bu] +slabdata +.P +The statistics are as follows: +.TP +.I active_objs +The number of objects that are currently active (i.e., in use). +.TP +.I num_objs +The total number of allocated objects +(i.e., objects that are both in use and not in use). +.TP +.I objsize +The size of objects in this slab, in bytes. +.TP +.I objperslab +The number of objects stored in each slab. +.TP +.I pagesperslab +The number of pages allocated for each slab. +.P +The +.I tunables +entries in each line show tunable parameters for the corresponding cache. +When using the default SLUB allocator, there are no tunables, the +.I /proc/slabinfo +file is not writable, and the value 0 is shown in these fields. +When using the older SLAB allocator, +the tunables for a particular cache can be set by writing +lines of the following form to +.IR /proc/slabinfo : +.P +.in +4n +.EX +# \fBecho \[aq]name limit batchcount sharedfactor\[aq] > /proc/slabinfo\fP +.EE +.in +.P +Here, +.I name +is the cache name, and +.IR limit , +.IR batchcount , +and +.I sharedfactor +are integers defining new values for the corresponding tunables. +The +.I limit +value should be a positive value, +.I batchcount +should be a positive value that is less than or equal to +.IR limit , +and +.I sharedfactor +should be nonnegative. +If any of the specified values is invalid, +the cache settings are left unchanged. +.P +The +.I tunables +entries in each line contain the following fields: +.TP +.I limit +The maximum number of objects that will be cached. +.\" https://lwn.net/Articles/56360/ +.\" This is the limit on the number of free objects that can be stored +.\" in the per-CPU free list for this slab cache. +.TP +.I batchcount +On SMP systems, this specifies the number of objects to transfer at one time +when refilling the available object list. +.\" https://lwn.net/Articles/56360/ +.\" On SMP systems, when we refill the available object list, instead +.\" of doing one object at a time, we do batch-count objects at a time. +.TP +.I sharedfactor +[To be documented] +.\" +.P +The +.I slabdata +entries in each line contain the following fields: +.TP +.I active_slabs +The number of active slabs. +.TP +.I nums_slabs +The total number of slabs. +.TP +.I sharedavail +[To be documented] +.P +Note that because of object alignment and slab cache overhead, +objects are not normally packed tightly into pages. +Pages with even one in-use object are considered in-use and cannot be +freed. +.P +Kernels configured with +.B CONFIG_DEBUG_SLAB +will also have additional statistics fields in each line, +and the first line of the file will contain the string "(statistics)". +The statistics field include : the high water mark of active +objects; the number of times objects have been allocated; +the number of times the cache has grown (new pages added +to this cache); the number of times the cache has been +reaped (unused pages removed from this cache); and the +number of times there was an error allocating new pages +to this cache. +.\" +.\" SMP systems will also have "(SMP)" in the first line of +.\" output, and will have two additional columns for each slab, +.\" reporting the slab allocation policy for the CPU-local +.\" cache (to reduce the need for inter-CPU synchronization +.\" when allocating objects from the cache). +.\" The first column is the per-CPU limit: the maximum number of objects that +.\" will be cached for each CPU. +.\" The second column is the +.\" batchcount: the maximum number of free objects in the +.\" global cache that will be transferred to the per-CPU cache +.\" if it is empty, or the number of objects to be returned +.\" to the global cache if the per-CPU cache is full. +.\" +.\" If both slab cache statistics and SMP are defined, there +.\" will be four additional columns, reporting the per-CPU +.\" cache statistics. +.\" The first two are the per-CPU cache +.\" allocation hit and miss counts: the number of times an +.\" object was or was not available in the per-CPU cache +.\" for allocation. +.\" The next two are the per-CPU cache free +.\" hit and miss counts: the number of times a freed object +.\" could or could not fit within the per-CPU cache limit, +.\" before flushing objects to the global cache. +.SH VERSIONS +The +.I /proc/slabinfo +file first appeared in Linux 2.1.23. +The file is versioned, +and over time there have been a number of versions with different layouts: +.TP +1.0 +Present throughout the Linux 2.2.x kernel series. +.TP +1.1 +Present in the Linux 2.4.x kernel series. +.\" First appeared in Linux 2.4.0-test3 +.TP +1.2 +A format that was briefly present in the Linux 2.5 development series. +.\" from Linux 2.5.45 to Linux 2.5.70 +.TP +2.0 +Present in Linux 2.6.x kernels up to and including Linux 2.6.9. +.\" First appeared in Linux 2.5.71 +.TP +2.1 +The current format, which first appeared in Linux 2.6.10. +.SH NOTES +Only root can read and (if the kernel was configured with +.BR CONFIG_SLAB ) +write the +.I /proc/slabinfo +file. +.P +The total amount of memory allocated to the SLAB/SLUB cache is shown in the +.I Slab +field of +.IR /proc/meminfo . +.SH SEE ALSO +.BR slabtop (1) +.P +The kernel source file +.I Documentation/vm/slub.txt +and +.IR tools/vm/slabinfo.c . diff --git a/man/man5/sysfs.5 b/man/man5/sysfs.5 new file mode 100644 index 0000000..33b0391 --- /dev/null +++ b/man/man5/sysfs.5 @@ -0,0 +1,275 @@ +.\" Copyright (c) 2017 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sysfs 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sysfs \- a filesystem for exporting kernel objects +.SH DESCRIPTION +The +.B sysfs +filesystem is a pseudo-filesystem which provides an interface to +kernel data structures. +(More precisely, the files and directories in +.B sysfs +provide a view of the +.I kobject +structures defined internally within the kernel.) +The files under +.B sysfs +provide information about devices, kernel modules, filesystems, +and other kernel components. +.P +The +.B sysfs +filesystem is commonly mounted at +.IR /sys . +Typically, it is mounted automatically by the system, +but it can also be mounted manually using a command such as: +.P +.in +4n +.EX +mount \-t sysfs sysfs /sys +.EE +.in +.P +Many of the files in the +.B sysfs +filesystem are read-only, +but some files are writable, allowing kernel variables to be changed. +To avoid redundancy, +symbolic links are heavily used to connect entries across the filesystem tree. +.\" +.SS Files and directories +The following list describes some of the files and directories under the +.I /sys +hierarchy. +.TP +.I /sys/block +This subdirectory contains one symbolic link for each block device +that has been discovered on the system. +The symbolic links point to corresponding directories under +.IR /sys/devices . +.TP +.I /sys/bus +This directory contains one subdirectory for each of the bus types +in the kernel. +Inside each of these directories are two subdirectories: +.RS +.TP +.I devices +This subdirectory contains symbolic links to entries in +.I /sys/devices +that correspond to the devices discovered on this bus. +.TP +.I drivers +This subdirectory contains one subdirectory for each device driver +that is loaded on this bus. +.RE +.TP +.I /sys/class +This subdirectory contains a single layer of further subdirectories +for each of the device classes that have been registered on the system +(e.g., terminals, network devices, block devices, graphics devices, +sound devices, and so on). +Inside each of these subdirectories are symbolic links for each of the +devices in this class. +These symbolic links refer to entries in the +.I /sys/devices +directory. +.TP +.I /sys/class/net +Each of the entries in this directory is a symbolic link +representing one of the real or virtual networking devices +that are visible in the network namespace of the process +that is accessing the directory. +Each of these symbolic links refers to entries in the +.I /sys/devices +directory. +.TP +.I /sys/dev +This directory contains two subdirectories +.I block/ +and +.IR char/ , +corresponding, respectively, +to the block and character devices on the system. +Inside each of these subdirectories are symbolic links with names of the form +.IR major-ID : minor-ID , +where the ID values correspond to the major and minor ID of a specific device. +Each symbolic link points to the +.B sysfs +directory for a device. +The symbolic links inside +.I /sys/dev +thus provide an easy way to look up the +.B sysfs +interface using the device IDs returned by a call to +.BR stat (2) +(or similar). +.IP +The following shell session shows an example from +.IR /sys/dev : +.IP +.in +4n +.EX +$ \fBstat \-c "%t %T" /dev/null\fP +1 3 +$ \fBreadlink /sys/dev/char/1\e:3\fP +\&../../devices/virtual/mem/null +$ \fBls \-Fd /sys/devices/virtual/mem/null\fP +/sys/devices/virtual/mem/null/ +$ \fBls \-d1 /sys/devices/virtual/mem/null/*\fP +/sys/devices/virtual/mem/null/dev +/sys/devices/virtual/mem/null/power/ +/sys/devices/virtual/mem/null/subsystem@ +/sys/devices/virtual/mem/null/uevent +.EE +.in +.TP +.I /sys/devices +This is a directory that contains a filesystem representation of +the kernel device tree, +which is a hierarchy of +.I device +structures within the kernel. +.TP +.I /sys/firmware +This subdirectory contains interfaces for viewing and manipulating +firmware-specific objects and attributes. +.TP +.I /sys/fs +This directory contains subdirectories for some filesystems. +A filesystem will have a subdirectory here only if it chose +to explicitly create the subdirectory. +.TP +.I /sys/fs/cgroup +This directory conventionally is used as a mount point for a +.BR tmpfs (5) +filesystem containing mount points for +.BR cgroups (7) +filesystems. +.TP +.I /sys/fs/smackfs +The directory contains configuration files for the SMACK LSM. +See the kernel source file +.IR Documentation/admin\-guide/LSM/Smack.rst . +.TP +.I /sys/hypervisor +[To be documented] +.TP +.I /sys/kernel +This subdirectory contains various files and subdirectories that provide +information about the running kernel. +.TP +.I /sys/kernel/cgroup/ +For information about the files in this directory, see +.BR cgroups (7). +.TP +.I /sys/kernel/debug/tracing +Mount point for the +.I tracefs +filesystem used by the kernel's +.I ftrace +facility. +(For information on +.IR ftrace , +see the kernel source file +.IR Documentation/trace/ftrace.txt .) +.TP +.I /sys/kernel/mm +This subdirectory contains various files and subdirectories that provide +information about the kernel's memory management subsystem. +.TP +.I /sys/kernel/mm/hugepages +This subdirectory contains one subdirectory for each of the +huge page sizes that the system supports. +The subdirectory name indicates the huge page size (e.g., +.IR hugepages\-2048kB ). +Within each of these subdirectories is a set of files +that can be used to view and (in some cases) change settings +associated with that huge page size. +For further information, see the kernel source file +.IR Documentation/admin\-guide/mm/hugetlbpage.rst . +.TP +.I /sys/module +This subdirectory contains one subdirectory +for each module that is loaded into the kernel. +The name of each directory is the name of the module. +In each of the subdirectories, there may be following files: +.RS +.TP +.I coresize +[to be documented] +.TP +.I initsize +[to be documented] +.TP +.I initstate +[to be documented] +.TP +.I refcnt +[to be documented] +.TP +.I srcversion +[to be documented] +.TP +.I taint +[to be documented] +.TP +.I uevent +[to be documented] +.TP +.I version +[to be documented] +.RE +.IP +In each of the subdirectories, there may be following subdirectories: +.RS +.TP +.I drivers +[To be documented] +.TP +.I holders +[To be documented] +.TP +.I notes +[To be documented] +.TP +.I parameters +This directory contains one file for each module parameter, +with each file containing the value of the corresponding parameter. +Some of these files are writable, allowing the +.TP +.I sections +This subdirectories contains files with information about module sections. +This information is mainly used for debugging. +.TP +.I +[To be documented] +.RE +.TP +.I /sys/power +[To be documented] +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.6.0. +.SH NOTES +This manual page is incomplete, possibly inaccurate, and is the kind +of thing that needs to be updated very often. +.SH SEE ALSO +.BR proc (5), +.BR udev (7) +.P +P.\& Mochel. (2005). +.IR "The sysfs filesystem" . +Proceedings of the 2005 Ottawa Linux Symposium. +.\" https://www.kernel.org/pub/linux/kernel/people/mochel/doc/papers/ols-2005/mochel.pdf +.P +The kernel source file +.I Documentation/filesystems/sysfs.txt +and various other files in +.I Documentation/ABI +and +.I Documentation/*/sysfs.txt diff --git a/man/man5/termcap.5 b/man/man5/termcap.5 new file mode 100644 index 0000000..633f2d1 --- /dev/null +++ b/man/man5/termcap.5 @@ -0,0 +1,466 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified formatting Sat Jul 24 17:13:38 1993, Rik Faith (faith@cs.unc.edu) +.\" Modified (extensions and corrections) +.\" Sun May 1 14:21:25 MET DST 1994 Michael Haardt +.\" If mistakes in the capabilities are found, please send a bug report to: +.\" michael@moria.de +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond (esr@thyrsus.com) +.TH termcap 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +termcap \- terminal capability database +.SH DESCRIPTION +The termcap database is an obsolete facility for describing the +capabilities of character-cell terminals and printers. +It is retained only for compatibility with old programs; +new programs should use the +.BR terminfo (5) +database and associated libraries. +.P +.I /etc/termcap +is an ASCII file (the database master) that lists the capabilities of +many different types of terminals. +Programs can read termcap to find +the particular escape codes needed to control the visual attributes of +the terminal actually in use. +(Other aspects of the terminal are +handled by +.BR stty (1).) +The termcap database is indexed on the +.B TERM +environment variable. +.P +Termcap entries must be defined on a single logical line, with \[aq]\e\[aq] +used to suppress the newline. +Fields are separated by \[aq]:\[aq]. +The first field of each entry starts at the left-hand margin, +and contains a list of names for the terminal, separated by \[aq]|\[aq]. +.P +The first subfield may (in BSD termcap entries from 4.3BSD and +earlier) contain a short name consisting of two characters. +This short name may consist of capital or small letters. +In 4.4BSD, termcap entries this field is omitted. +.P +The second subfield (first, in the newer 4.4BSD format) contains the +name used by the environment variable +.BR TERM . +It should be spelled in lowercase letters. +Selectable hardware capabilities should be marked +by appending a hyphen and a suffix to this name. +See below for an example. +Usual suffixes are w (more than 80 characters wide), am +(automatic margins), nam (no automatic margins), and rv (reverse video +display). +The third subfield contains a long and descriptive name for +this termcap entry. +.P +Subsequent fields contain the terminal capabilities; any continued +capability lines must be indented one tab from the left margin. +.P +Although there is no defined order, it is suggested to write first +boolean, then numeric, and then string capabilities, each sorted +alphabetically without looking at lower or upper spelling. +Capabilities of similar functions can be written in one line. +.P +Example for: +.nf +.P +Head line: vt|vt101|DEC VT 101 terminal in 80 character mode:\e +Head line: Vt|vt101-w|DEC VT 101 terminal in (wide) 132 character mode:\e +Boolean: :bs:\e +Numeric: :co#80:\e +String: :sr=\eE[H:\e +.fi +.SS Boolean capabilities +.nf +5i Printer will not echo on screen +am Automatic margins which means automatic line wrap +bs Control-H (8 dec.) performs a backspace +bw Backspace on left margin wraps to previous line and right margin +da Display retained above screen +db Display retained below screen +eo A space erases all characters at cursor position +es Escape sequences and special characters work in status line +gn Generic device +hc This is a hardcopy terminal +HC The cursor is hard to see when not on bottom line +hs Has a status line +hz Hazeltine bug, the terminal can not print tilde characters +in Terminal inserts null bytes, not spaces, to fill whitespace +km Terminal has a meta key +mi Cursor movement works in insert mode +ms Cursor movement works in standout/underline mode +NP No pad character +NR ti does not reverse te +nx No padding, must use XON/XOFF +os Terminal can overstrike +ul Terminal underlines although it can not overstrike +xb Beehive glitch, f1 sends ESCAPE, f2 sends \fB\[ha]C\fP +xn Newline/wraparound glitch +xo Terminal uses xon/xoff protocol +xs Text typed over standout text will be displayed in standout +xt Teleray glitch, destructive tabs and odd standout mode +.fi +.SS Numeric capabilities +.nf +co Number of columns +dB Delay in milliseconds for backspace on hardcopy terminals +dC Delay in milliseconds for carriage return on hardcopy terminals +dF Delay in milliseconds for form feed on hardcopy terminals +dN Delay in milliseconds for new line on hardcopy terminals +dT Delay in milliseconds for tabulator stop on hardcopy terminals +dV Delay in milliseconds for vertical tabulator stop on + hardcopy terminals +it Difference between tab positions +lh Height of soft labels +lm Lines of memory +lw Width of soft labels +li Number of lines +Nl Number of soft labels +pb Lowest baud rate which needs padding +sg Standout glitch +ug Underline glitch +vt virtual terminal number +ws Width of status line if different from screen width +.fi +.SS String capabilities +.nf +!1 shifted save key +!2 shifted suspend key +!3 shifted undo key +#1 shifted help key +#2 shifted home key +#3 shifted input key +#4 shifted cursor left key +%0 redo key +%1 help key +%2 mark key +%3 message key +%4 move key +%5 next-object key +%6 open key +%7 options key +%8 previous-object key +%9 print key +%a shifted message key +%b shifted move key +%c shifted next key +%d shifted options key +%e shifted previous key +%f shifted print key +%g shifted redo key +%h shifted replace key +%i shifted cursor right key +%j shifted resume key +&0 shifted cancel key +&1 reference key +&2 refresh key +&3 replace key +&4 restart key +&5 resume key +&6 save key +&7 suspend key +&8 undo key +&9 shifted begin key +*0 shifted find key +*1 shifted command key +*2 shifted copy key +*3 shifted create key +*4 shifted delete character +*5 shifted delete line +*6 select key +*7 shifted end key +*8 shifted clear line key +*9 shifted exit key +@0 find key +@1 begin key +@2 cancel key +@3 close key +@4 command key +@5 copy key +@6 create key +@7 end key +@8 enter/send key +@9 exit key +al Insert one line +AL Insert %1 lines +ac Pairs of block graphic characters to map alternate character set +ae End alternative character set +as Start alternative character set for block graphic characters +bc Backspace, if not \fB\[ha]H\fP +bl Audio bell +bt Move to previous tab stop +cb Clear from beginning of line to cursor +cc Dummy command character +cd Clear to end of screen +ce Clear to end of line +ch Move cursor horizontally only to column %1 +cl Clear screen and cursor home +cm Cursor move to row %1 and column %2 (on screen) +CM Move cursor to row %1 and column %2 (in memory) +cr Carriage return +cs Scroll region from line %1 to %2 +ct Clear tabs +cv Move cursor vertically only to line %1 +dc Delete one character +DC Delete %1 characters +dl Delete one line +DL Delete %1 lines +dm Begin delete mode +do Cursor down one line +DO Cursor down #1 lines +ds Disable status line +eA Enable alternate character set +ec Erase %1 characters starting at cursor +ed End delete mode +ei End insert mode +ff Formfeed character on hardcopy terminals +fs Return character to its position before going to status line +F1 The string sent by function key f11 +F2 The string sent by function key f12 +F3 The string sent by function key f13 +\&... \&... +F9 The string sent by function key f19 +FA The string sent by function key f20 +FB The string sent by function key f21 +\&... \&... +FZ The string sent by function key f45 +Fa The string sent by function key f46 +Fb The string sent by function key f47 +\&... \&... +Fr The string sent by function key f63 +hd Move cursor a half line down +ho Cursor home +hu Move cursor a half line up +i1 Initialization string 1 at login +i3 Initialization string 3 at login +is Initialization string 2 at login +ic Insert one character +IC Insert %1 characters +if Initialization file +im Begin insert mode +ip Insert pad time and needed special characters after insert +iP Initialization program +K1 upper left key on keypad +K2 center key on keypad +K3 upper right key on keypad +K4 bottom left key on keypad +K5 bottom right key on keypad +k0 Function key 0 +k1 Function key 1 +k2 Function key 2 +k3 Function key 3 +k4 Function key 4 +k5 Function key 5 +k6 Function key 6 +k7 Function key 7 +k8 Function key 8 +k9 Function key 9 +k; Function key 10 +ka Clear all tabs key +kA Insert line key +kb Backspace key +kB Back tab stop +kC Clear screen key +kd Cursor down key +kD Key for delete character under cursor +ke turn keypad off +kE Key for clear to end of line +kF Key for scrolling forward/down +kh Cursor home key +kH Cursor hown down key +kI Insert character/Insert mode key +kl Cursor left key +kL Key for delete line +kM Key for exit insert mode +kN Key for next page +kP Key for previous page +kr Cursor right key +kR Key for scrolling backward/up +ks Turn keypad on +kS Clear to end of screen key +kt Clear this tab key +kT Set tab here key +ku Cursor up key +l0 Label of zeroth function key, if not f0 +l1 Label of first function key, if not f1 +l2 Label of first function key, if not f2 +\&... \&... +la Label of tenth function key, if not f10 +le Cursor left one character +ll Move cursor to lower left corner +LE Cursor left %1 characters +LF Turn soft labels off +LO Turn soft labels on +mb Start blinking +MC Clear soft margins +md Start bold mode +me End all mode like so, us, mb, md, and mr +mh Start half bright mode +mk Dark mode (Characters invisible) +ML Set left soft margin +mm Put terminal in meta mode +mo Put terminal out of meta mode +mp Turn on protected attribute +mr Start reverse mode +MR Set right soft margin +nd Cursor right one character +nw Carriage return command +pc Padding character +pf Turn printer off +pk Program key %1 to send string %2 as if typed by user +pl Program key %1 to execute string %2 in local mode +pn Program soft label %1 to show string %2 +po Turn the printer on +pO Turn the printer on for %1 (<256) bytes +ps Print screen contents on printer +px Program key %1 to send string %2 to computer +r1 Reset string 1 to set terminal to sane modes +r2 Reset string 2 to set terminal to sane modes +r3 Reset string 3 to set terminal to sane modes +RA disable automatic margins +rc Restore saved cursor position +rf Reset string filename +RF Request for input from terminal +RI Cursor right %1 characters +rp Repeat character %1 for %2 times +rP Padding after character sent in replace mode +rs Reset string +RX Turn off XON/XOFF flow control +sa Set %1 %2 %3 %4 %5 %6 %7 %8 %9 attributes +SA enable automatic margins +sc Save cursor position +se End standout mode +sf Normal scroll one line +SF Normal scroll %1 lines +so Start standout mode +sr Reverse scroll +SR scroll back %1 lines +st Set tabulator stop in all rows at current column +SX Turn on XON/XOFF flow control +ta move to next hardware tab +tc Read in terminal description from another entry +te End program that uses cursor motion +ti Begin program that uses cursor motion +ts Move cursor to column %1 of status line +uc Underline character under cursor and move cursor right +ue End underlining +up Cursor up one line +UP Cursor up %1 lines +us Start underlining +vb Visible bell +ve Normal cursor visible +vi Cursor invisible +vs Standout cursor +wi Set window from line %1 to %2 and column %3 to %4 +XF XOFF character if not \fB\[ha]S\fP +.fi +.P +There are several ways of defining the control codes for string capabilities: +.P +Every normal character represents itself, +except \[aq]\[ha]\[aq], \[aq]\e\[aq], and \[aq]%\[aq]. +.P +A \fB\[ha]x\fP means Control-x. +Control-A equals 1 decimal. +.P +\ex means a special code. +x can be one of the following characters: +.RS +E Escape (27) +.br +n Linefeed (10) +.br +r Carriage return (13) +.br +t Tabulation (9) +.br +b Backspace (8) +.br +f Form feed (12) +.br +0 Null character. +A \exxx specifies the octal character xxx. +.RE +.TP +i +Increments parameters by one. +.TP +r +Single parameter capability +.TP ++ +Add value of next character to this parameter and do binary output +.TP +2 +Do ASCII output of this parameter with a field with of 2 +.TP +d +Do ASCII output of this parameter with a field with of 3 +.TP +% +Print a \[aq]%\[aq] +.P +If you use binary output, +then you should avoid the null character (\[aq]\e0\[aq]) +because it terminates the string. +You should reset tabulator expansion +if a tabulator can be the binary output of a parameter. +.TP +Warning: +The above metacharacters for parameters may be wrong: they document Minix +termcap which may not be compatible with Linux termcap. +.P +The block graphic characters can be specified by three string capabilities: +.TP +as +start the alternative charset +.TP +ae +end the alternative charset +.TP +ac +pairs of characters. +The first character is the name of the block graphic +symbol and the second characters is its definition. +.P +The following names are available: +.P +.nf ++ right arrow (>) +, left arrow (<) +\&. down arrow (v) +0 full square (#) +I lantern (#) +- upper arrow (\[ha]) +\&' rhombus (+) +a chess board (:) +f degree (') +g plus-minus (#) +h square (#) +j right bottom corner (+) +k right upper corner (+) +l left upper corner (+) +m left bottom corner (+) +n cross (+) +o upper horizontal line (-) +q middle horizontal line (-) +s bottom horizontal line (_) +t left tee (+) +u right tee (+) +v bottom tee (+) +w normal tee (+) +x vertical line (|) +\[ti] paragraph (???) +.fi +.P +The values in parentheses are suggested defaults which are used by the +.I curses +library, if the capabilities are missing. +.SH SEE ALSO +.BR ncurses (3), +.BR termcap (3), +.BR terminfo (5) diff --git a/man/man5/tmpfs.5 b/man/man5/tmpfs.5 new file mode 100644 index 0000000..51ea8f8 --- /dev/null +++ b/man/man5/tmpfs.5 @@ -0,0 +1,281 @@ +.\" Copyright (c) 2016 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH tmpfs 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tmpfs \- a virtual memory filesystem +.SH DESCRIPTION +The +.B tmpfs +facility allows the creation of filesystems whose contents reside +in virtual memory. +Since the files on such filesystems typically reside in RAM, +file access is extremely fast. +.P +The filesystem is automatically created when mounting +a filesystem with the type +.B tmpfs +via a command such as the following: +.P +.in +4n +.EX +$ sudo mount \-t tmpfs \-o size=10M tmpfs /mnt/mytmpfs +.EE +.in +.P +A +.B tmpfs +filesystem has the following properties: +.IP \[bu] 3 +The filesystem can employ swap space when physical memory pressure +demands it. +.IP \[bu] +The filesystem consumes only as much physical memory and swap space +as is required to store the current contents of the filesystem. +.IP \[bu] +During a remount operation +.RI ( "mount\ \-o\ remount" ), +the filesystem size can be changed +(without losing the existing contents of the filesystem). +.P +If a +.B tmpfs +filesystem is unmounted, its contents are discarded (lost). +.\" See mm/shmem.c:shmem_parse_options for options it supports. +.SS Mount options +The +.B tmpfs +filesystem supports the following mount options: +.TP +.BR size "=\fIbytes\fP" +Specify an upper limit on the size of the filesystem. +The size is given in bytes, and rounded up to entire pages. +The limit is removed if the size is +.BR 0 . +.IP +The size may have a +.BR k , +.BR m , +or +.B g +suffix for Ki, Mi, Gi (binary kilo (kibi), binary mega (mebi), and binary giga +(gibi)). +.IP +The size may also have a % suffix to limit this instance to a percentage of +physical RAM. +.IP +The default, when neither +.B size +nor +.B nr_blocks +is specified, is +.IR size=50% . +.TP +.BR nr_blocks "=\fIblocks\fP" +The same as +.BR size , +but in blocks of +.BR PAGE_CACHE_SIZE . +.IP +Blocks may be specified with +.BR k , +.BR m , +or +.B g +suffixes like +.BR size , +but not a % suffix. +.TP +.BR nr_inodes "=\fIinodes\fP" +The maximum number of inodes for this instance. +The default is half of the number of your physical RAM pages, or (on a +machine with highmem) the number of lowmem RAM pages, whichever is smaller. +The limit is removed if the number is +.BR 0 . +.IP +Inodes may be specified with +.BR k , +.BR m , +or +.B g +suffixes like +.BR size , +but not a % suffix. +.TP +.BR noswap "(since Linux 6.4)" +.\" commit 2c6efe9cf2d7841b75fe38ed1adbd41a90f51ba0 +Disables swap. +Remounts must respect the original settings. +By default swap is enabled. +.TP +.BR mode "=\fImode\fP" +Set initial permissions of the root directory. +.TP +.BR gid "=\fIgid\fP (since Linux 2.5.7)" +.\" Technically this is also in some version of Linux 2.4. +.\" commit 099445b489625b80b1d6687c9b6072dbeaca4096 +Set the initial group ID of the root directory. +.TP +.BR uid "=\fIuid\fP (since Linux 2.5.7)" +.\" Technically this is also in some version of Linux 2.4. +.\" commit 099445b489625b80b1d6687c9b6072dbeaca4096 +Set the initial user ID of the root directory. +.TP +.BR huge "=\fIhuge_option\fR (since Linux 4.7.0)" +.\" commit 5a6e75f8110c97e2a5488894d4e922187e6cb343 +Set the huge table memory allocation policy for all files in this instance (if +.B CONFIG_TRANSPARENT_HUGEPAGE +is enabled). +.IP +The +.I huge_option +value is one of the following: +.RS +.TP +.B never +Do not allocate huge pages. +This is the default. +.TP +.B always +Attempt to allocate huge pages every time a new page is needed. +.TP +.B within_size +Only allocate huge page if it will be fully within +.IR i_size . +Also respect +.BR fadvise (2) +and +.BR madvise (2) +hints +.TP +.B advise +Only allocate huge pages if requested with +.BR fadvise (2) +or +.BR madvise (2). +.TP +.B deny +For use in emergencies, to force the huge option off from all mounts. +.TP +.B force +Force the huge option on for all mounts; useful for testing. +.RE +.TP +.BR mpol "=\fImpol_option\fR (since Linux 2.6.15)" +.\" commit 7339ff8302fd70aabf5f1ae26e0c4905fa74a495 +Set the NUMA memory allocation policy for all files in this instance (if +.B CONFIG_NUMA +is enabled). +.IP +The +.I mpol_option +value is one of the following: +.RS +.TP +.B default +Use the process allocation policy (see +.BR set_mempolicy (2)). +.TP +.BR prefer ":\fInode\fP" +Preferably allocate memory from the given +.IR node . +.TP +.BR bind ":\fInodelist\fP" +Allocate memory only from nodes in +.IR nodelist . +.TP +.B interleave +Allocate from each node in turn. +.TP +.BR interleave ":\fInodelist\fP" +Allocate from each node of +.I in +turn. +.TP +.B local +Preferably allocate memory from the local node. +.RE +.IP +In the above, +.I nodelist +is a comma-separated list of decimal numbers and ranges +that specify NUMA nodes. +A range is a pair of hyphen-separated decimal numbers, +the smallest and largest node numbers in the range. +For example, +.IR mpol=bind:0\-3,5,7,9\-15 . +.SH VERSIONS +The +.B tmpfs +facility was added in Linux 2.4, as a successor to the older +.B ramfs +facility, which did not provide limit checking or +allow for the use of swap space. +.SH NOTES +In order for user-space tools and applications to create +.B tmpfs +filesystems, the kernel must be configured with the +.B CONFIG_TMPFS +option. +.P +The +.B tmpfs +filesystem supports extended attributes (see +.BR xattr (7)), +but +.I user +extended attributes are not permitted. +.P +An internal shared memory filesystem is used for +System V shared memory +.RB ( shmget (2)) +and shared anonymous mappings +.RB ( mmap (2) +with the +.B MAP_SHARED +and +.B MAP_ANONYMOUS +flags). +This filesystem is available regardless of whether +the kernel was configured with the +.B CONFIG_TMPFS +option. +.P +A +.B tmpfs +filesystem mounted at +.I /dev/shm +is used for the implementation of POSIX shared memory +.RB ( shm_overview (7)) +and POSIX semaphores +.RB ( sem_overview (7)). +.P +The amount of memory consumed by all +.B tmpfs +filesystems is shown in the +.I Shmem +field of +.I /proc/meminfo +and in the +.I shared +field displayed by +.BR free (1). +.P +The +.B tmpfs +facility was formerly called +.BR shmfs . +.SH SEE ALSO +.BR df (1), +.BR du (1), +.BR memfd_create (2), +.BR mmap (2), +.BR set_mempolicy (2), +.BR shm_open (3), +.BR mount (8) +.P +The kernel source files +.I Documentation/filesystems/tmpfs.txt +and +.IR Documentation/admin\-guide/mm/transhuge.rst . diff --git a/man/man5/ttytype.5 b/man/man5/ttytype.5 new file mode 100644 index 0000000..92dcf0f --- /dev/null +++ b/man/man5/ttytype.5 @@ -0,0 +1,56 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:17:50 1993 by Rik Faith +.\" Modified Thu Oct 19 21:25:21 MET 1995 by Martin Schulze +.\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond +.\" xk +.TH ttytype 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ttytype \- terminal device to default terminal type mapping +.SH DESCRIPTION +The +.I /etc/ttytype +file associates +.BR termcap (5) +and +.BR terminfo (5) +terminal type names +with tty lines. +Each line consists of a terminal type, followed by +whitespace, followed by a tty name (a device name without the +.I /dev/ +prefix). +.P +This association is used by the program +.BR tset (1) +to set the environment variable +.B TERM +to the default terminal name for +the user's current tty. +.P +This facility was designed for a traditional time-sharing environment +featuring character-cell terminals hardwired to a UNIX minicomputer. +It is little used on modern workstation and personal UNIX systems. +.SH FILES +.TP +.I /etc/ttytype +the tty definitions file. +.SH EXAMPLES +A typical +.I /etc/ttytype +is: +.P +.in +4n +.EX +con80x25 tty1 +vt320 ttys0 +.EE +.in +.SH SEE ALSO +.BR termcap (5), +.BR terminfo (5), +.BR agetty (8), +.BR mingetty (8) diff --git a/man/man5/tzfile.5 b/man/man5/tzfile.5 new file mode 100644 index 0000000..4aa3f6c --- /dev/null +++ b/man/man5/tzfile.5 @@ -0,0 +1,508 @@ +.\" This file is in the public domain, so clarified as of +.\" 1996-06-05 by Arthur David Olson. +.TH tzfile 5 "" "Time Zone Database" +.SH NAME +tzfile \- timezone information +.SH DESCRIPTION +.ie '\(lq'' .ds lq \&"\" +.el .ds lq \(lq\" +.ie '\(rq'' .ds rq \&"\" +.el .ds rq \(rq\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +.ie \n(.g .ds - \f(CR-\fP +.el .ds - \- +The timezone information files used by +.BR tzset (3) +are typically found under a directory with a name like +.IR /usr/share/zoneinfo . +These files use the format described in Internet RFC 8536. +Each file is a sequence of 8-bit bytes. +In a file, a binary integer is represented by a sequence of one or +more bytes in network order (bigendian, or high-order byte first), +with all bits significant, +a signed binary integer is represented using two's complement, +and a boolean is represented by a one-byte binary integer that is +either 0 (false) or 1 (true). +The format begins with a 44-byte header containing the following fields: +.RS 2 +.IP \(bu 3 +The magic four-byte ASCII sequence +.q "TZif" +identifies the file as a timezone information file. +.IP \(bu +A byte identifying the version of the file's format +(as of 2021, either an ASCII NUL, +.q "2", +.q "3", +or +.q "4" ). +.IP \(bu +Fifteen bytes containing zeros reserved for future use. +.IP \(bu +Six four-byte integer values, in the following order: +.RS +.TP 2 +.B tzh_ttisutcnt +The number of UT/local indicators stored in the file. +(UT is Universal Time.) +.TP +.B tzh_ttisstdcnt +The number of standard/wall indicators stored in the file. +.TP +.B tzh_leapcnt +The number of leap seconds for which data entries are stored in the file. +.TP +.B tzh_timecnt +The number of transition times for which data entries are stored +in the file. +.TP +.B tzh_typecnt +The number of local time types for which data entries are stored +in the file (must not be zero). +.TP +.B tzh_charcnt +The number of bytes of time zone abbreviation strings +stored in the file. +.RE +.RE +.PP +The above header is followed by the following fields, whose lengths +depend on the contents of the header: +.RS 2 +.IP \(bu 3 +.B tzh_timecnt +four-byte signed integer values sorted in ascending order. +These values are written in network byte order. +Each is used as a transition time (as returned by +.BR time (2)) +at which the rules for computing local time change. +.IP \(bu +.B tzh_timecnt +one-byte unsigned integer values; +each one but the last tells which of the different types of local time types +described in the file is associated with the time period +starting with the same-indexed transition time +and continuing up to but not including the next transition time. +(The last time type is present only for consistency checking with the +POSIX.1-2017-style TZ string described below.) +These values serve as indices into the next field. +.IP \(bu +.B tzh_typecnt +.B ttinfo +entries, each defined as follows: +.in +2 +.sp +.nf +.ta \w'\0\0\0\0'u +\w'unsigned char\0'u +struct ttinfo { + int32_t tt_utoff; + unsigned char tt_isdst; + unsigned char tt_desigidx; +}; +.in +.fi +.sp +Each structure is written as a four-byte signed integer value for +.BR tt_utoff , +in network byte order, followed by a one-byte boolean for +.B tt_isdst +and a one-byte value for +.BR tt_desigidx . +In each structure, +.B tt_utoff +gives the number of seconds to be added to UT, +.B tt_isdst +tells whether +.B tm_isdst +should be set by +.BR localtime (3) +and +.B tt_desigidx +serves as an index into the array of time zone abbreviation bytes +that follow the +.B ttinfo +entries in the file; if the designated string is "\*-00", the +.B ttinfo +entry is a placeholder indicating that local time is unspecified. +The +.B tt_utoff +value is never equal to \-2**31, to let 32-bit clients negate it without +overflow. +Also, in realistic applications +.B tt_utoff +is in the range [\-89999, 93599] (i.e., more than \-25 hours and less +than 26 hours); this allows easy support by implementations that +already support the POSIX-required range [\-24:59:59, 25:59:59]. +.IP \(bu +.B tzh_charcnt +bytes that represent time zone designations, +which are null-terminated byte strings, each indexed by the +.B tt_desigidx +values mentioned above. +The byte strings can overlap if one is a suffix of the other. +The encoding of these strings is not specified. +.IP \(bu +.B tzh_leapcnt +pairs of four-byte values, written in network byte order; +the first value of each pair gives the nonnegative time +(as returned by +.BR time (2)) +at which a leap second occurs or at which the leap second table expires; +the second is a signed integer specifying the correction, which is the +.I total +number of leap seconds to be applied during the time period +starting at the given time. +The pairs of values are sorted in strictly ascending order by time. +Each pair denotes one leap second, either positive or negative, +except that if the last pair has the same correction as the previous one, +the last pair denotes the leap second table's expiration time. +Each leap second is at the end of a UTC calendar month. +The first leap second has a nonnegative occurrence time, +and is a positive leap second if and only if its correction is positive; +the correction for each leap second after the first differs +from the previous leap second by either 1 for a positive leap second, +or \-1 for a negative leap second. +If the leap second table is empty, the leap-second correction is zero +for all timestamps; +otherwise, for timestamps before the first occurrence time, +the leap-second correction is zero if the first pair's correction is 1 or \-1, +and is unspecified otherwise (which can happen only in files +truncated at the start). +.IP \(bu +.B tzh_ttisstdcnt +standard/wall indicators, each stored as a one-byte boolean; +they tell whether the transition times associated with local time types +were specified as standard time or local (wall clock) time. +.IP \(bu +.B tzh_ttisutcnt +UT/local indicators, each stored as a one-byte boolean; +they tell whether the transition times associated with local time types +were specified as UT or local time. +If a UT/local indicator is set, the corresponding standard/wall indicator +must also be set. +.RE +.PP +The standard/wall and UT/local indicators were designed for +transforming a TZif file's transition times into transitions appropriate +for another time zone specified via +a POSIX.1-2017-style TZ string that lacks rules. +For example, when TZ="EET\*-2EEST" and there is no TZif file "EET\*-2EEST", +the idea was to adapt the transition times from a TZif file with the +well-known name "posixrules" that is present only for this purpose and +is a copy of the file "Europe/Brussels", a file with a different UT offset. +POSIX does not specify this obsolete transformational behavior, +the default rules are installation-dependent, and no implementation +is known to support this feature for timestamps past 2037, +so users desiring (say) Greek time should instead specify +TZ="Europe/Athens" for better historical coverage, falling back on +TZ="EET\*-2EEST,M3.5.0/3,M10.5.0/4" if POSIX conformance is required +and older timestamps need not be handled accurately. +.PP +The +.BR localtime (3) +function +normally uses the first +.B ttinfo +structure in the file +if either +.B tzh_timecnt +is zero or the time argument is less than the first transition time recorded +in the file. +.SS Version 2 format +For version-2-format timezone files, +the above header and data are followed by a second header and data, +identical in format except that +eight bytes are used for each transition time or leap second time. +(Leap second counts remain four bytes.) +After the second header and data comes a newline-enclosed string +in the style of the contents of a POSIX.1-2017 TZ environment variable, +for use in handling instants +after the last transition time stored in the file +or for all instants if the file has no transitions. +The TZ string is empty (i.e., nothing between the newlines) +if there is no POSIX.1-2017-style representation for such instants. +If nonempty, the TZ string must agree with the local time +type after the last transition time if present in the eight-byte data; +for example, given the string +.q "WET0WEST,M3.5.0/1,M10.5.0" +then if a last transition time is in July, the transition's local time +type must specify a daylight-saving time abbreviated +.q "WEST" +that is one hour east of UT. +Also, if there is at least one transition, time type 0 is associated +with the time period from the indefinite past up to but not including +the earliest transition time. +.SS Version 3 format +For version-3-format timezone files, the TZ string may +use two minor extensions to the POSIX.1-2017 TZ format, as described in +.BR newtzset (3). +First, the hours part of its transition times may be signed and range from +\-167 through 167 instead of the POSIX-required unsigned values +from 0 through 24. +Second, DST is in effect all year if it starts +January 1 at 00:00 and ends December 31 at 24:00 plus the difference +between daylight saving and standard time. +.SS Version 4 format +For version-4-format TZif files, +the first leap second record can have a correction that is neither ++1 nor \-1, to represent truncation of the TZif file at the start. +Also, if two or more leap second transitions are present and the last +entry's correction equals the previous one, the last entry +denotes the expiration of the leap second table instead of a leap second; +timestamps after this expiration are unreliable in that future +releases will likely add leap second entries after the expiration, and +the added leap seconds will change how post-expiration timestamps are treated. +.SS Interoperability considerations +Future changes to the format may append more data. +.PP +Version 1 files are considered a legacy format and +should not be generated, as they do not support transition +times after the year 2038. +Readers that understand only Version 1 must ignore +any data that extends beyond the calculated end of the version +1 data block. +.PP +Other than version 1, writers should generate +the lowest version number needed by a file's data. +For example, a writer should generate a version 4 file +only if its leap second table either expires or is truncated at the start. +Likewise, a writer not generating a version 4 file +should generate a version 3 file only if +TZ string extensions are necessary to accurately +model transition times. +.PP +The sequence of time changes defined by the version 1 +header and data block should be a contiguous sub-sequence +of the time changes defined by the version 2+ header and data +block, and by the footer. +This guideline helps obsolescent version 1 readers +agree with current readers about timestamps within the +contiguous sub-sequence. It also lets writers not +supporting obsolescent readers use a +.B tzh_timecnt +of zero +in the version 1 data block to save space. +.PP +When a TZif file contains a leap second table expiration +time, TZif readers should either refuse to process +post-expiration timestamps, or process them as if the expiration +time did not exist (possibly with an error indication). +.PP +Time zone designations should consist of at least three (3) +and no more than six (6) ASCII characters from the set of +alphanumerics, +.q "\*-", +and +.q "+". +This is for compatibility with POSIX requirements for +time zone abbreviations. +.PP +When reading a version 2 or higher file, readers +should ignore the version 1 header and data block except for +the purpose of skipping over them. +.PP +Readers should calculate the total lengths of the +headers and data blocks and check that they all fit within +the actual file size, as part of a validity check for the file. +.PP +When a positive leap second occurs, readers should append an extra +second to the local minute containing the second just before the leap +second. If this occurs when the UTC offset is not a multiple of 60 +seconds, the leap second occurs earlier than the last second of the +local minute and the minute's remaining local seconds are numbered +through 60 instead of the usual 59; the UTC offset is unaffected. +.SS Common interoperability issues +This section documents common problems in reading or writing TZif files. +Most of these are problems in generating TZif files for use by +older readers. +The goals of this section are: +.RS 2 +.IP \(bu 3 +to help TZif writers output files that avoid common +pitfalls in older or buggy TZif readers, +.IP \(bu +to help TZif readers avoid common pitfalls when reading +files generated by future TZif writers, and +.IP \(bu +to help any future specification authors see what sort of +problems arise when the TZif format is changed. +.RE +.PP +When new versions of the TZif format have been defined, a +design goal has been that a reader can successfully use a TZif +file even if the file is of a later TZif version than what the +reader was designed for. +When complete compatibility was not achieved, an attempt was +made to limit glitches to rarely used timestamps and allow +simple partial workarounds in writers designed to generate +new-version data useful even for older-version readers. +This section attempts to document these compatibility issues and +workarounds, as well as to document other common bugs in +readers. +.PP +Interoperability problems with TZif include the following: +.RS 2 +.IP \(bu 3 +Some readers examine only version 1 data. +As a partial workaround, a writer can output as much version 1 +data as possible. +However, a reader should ignore version 1 data, and should use +version 2+ data even if the reader's native timestamps have only +32 bits. +.IP \(bu +Some readers designed for version 2 might mishandle +timestamps after a version 3 or higher file's last transition, because +they cannot parse extensions to POSIX.1-2017 in the TZ-like string. +As a partial workaround, a writer can output more transitions +than necessary, so that only far-future timestamps are +mishandled by version 2 readers. +.IP \(bu +Some readers designed for version 2 do not support +permanent daylight saving time with transitions after 24:00 +\(en e.g., a TZ string +.q "EST5EDT,0/0,J365/25" +denoting permanent Eastern Daylight Time +(\-04). +As a workaround, a writer can substitute standard time +for two time zones east, e.g., +.q "XXX3EDT4,0/0,J365/23" +for a time zone with a never-used standard time (XXX, \-03) +and negative daylight saving time (EDT, \-04) all year. +Alternatively, +as a partial workaround a writer can substitute standard time +for the next time zone east \(en e.g., +.q "AST4" +for permanent +Atlantic Standard Time (\-04). +.IP \(bu +Some readers designed for version 2 or 3, and that require strict +conformance to RFC 8536, reject version 4 files whose leap second +tables are truncated at the start or that end in expiration times. +.IP \(bu +Some readers ignore the footer, and instead predict future +timestamps from the time type of the last transition. +As a partial workaround, a writer can output more transitions +than necessary. +.IP \(bu +Some readers do not use time type 0 for timestamps before +the first transition, in that they infer a time type using a +heuristic that does not always select time type 0. +As a partial workaround, a writer can output a dummy (no-op) +first transition at an early time. +.IP \(bu +Some readers mishandle timestamps before the first +transition that has a timestamp not less than \-2**31. +Readers that support only 32-bit timestamps are likely to be +more prone to this problem, for example, when they process +64-bit transitions only some of which are representable in 32 +bits. +As a partial workaround, a writer can output a dummy +transition at timestamp \-2**31. +.IP \(bu +Some readers mishandle a transition if its timestamp has +the minimum possible signed 64-bit value. +Timestamps less than \-2**59 are not recommended. +.IP \(bu +Some readers mishandle TZ strings that +contain +.q "<" +or +.q ">". +As a partial workaround, a writer can avoid using +.q "<" +or +.q ">" +for time zone abbreviations containing only alphabetic +characters. +.IP \(bu +Many readers mishandle time zone abbreviations that contain +non-ASCII characters. +These characters are not recommended. +.IP \(bu +Some readers may mishandle time zone abbreviations that +contain fewer than 3 or more than 6 characters, or that +contain ASCII characters other than alphanumerics, +.q "\*-", +and +.q "+". +These abbreviations are not recommended. +.IP \(bu +Some readers mishandle TZif files that specify +daylight-saving time UT offsets that are less than the UT +offsets for the corresponding standard time. +These readers do not support locations like Ireland, which +uses the equivalent of the TZ string +.q "IST\*-1GMT0,M10.5.0,M3.5.0/1", +observing standard time +(IST, +01) in summer and daylight saving time (GMT, +00) in winter. +As a partial workaround, a writer can output data for the +equivalent of the TZ string +.q "GMT0IST,M3.5.0/1,M10.5.0", +thus swapping standard and daylight saving time. +Although this workaround misidentifies which part of the year +uses daylight saving time, it records UT offsets and time zone +abbreviations correctly. +.IP \(bu +Some readers generate ambiguous timestamps for positive leap seconds +that occur when the UTC offset is not a multiple of 60 seconds. +For example, in a timezone with UTC offset +01:23:45 and with +a positive leap second 78796801 (1972-06-30 23:59:60 UTC), some readers will +map both 78796800 and 78796801 to 01:23:45 local time the next day +instead of mapping the latter to 01:23:46, and they will map 78796815 to +01:23:59 instead of to 01:23:60. +This has not yet been a practical problem, since no civil authority +has observed such UTC offsets since leap seconds were +introduced in 1972. +.RE +.PP +Some interoperability problems are reader bugs that +are listed here mostly as warnings to developers of readers. +.RS 2 +.IP \(bu 3 +Some readers do not support negative timestamps. +Developers of distributed applications should keep this +in mind if they need to deal with pre-1970 data. +.IP \(bu +Some readers mishandle timestamps before the first +transition that has a nonnegative timestamp. +Readers that do not support negative timestamps are likely to +be more prone to this problem. +.IP \(bu +Some readers mishandle time zone abbreviations like +.q "\*-08" +that contain +.q "+", +.q "\*-", +or digits. +.IP \(bu +Some readers mishandle UT offsets that are out of the +traditional range of \-12 through +12 hours, and so do not +support locations like Kiritimati that are outside this +range. +.IP \(bu +Some readers mishandle UT offsets in the range [\-3599, \-1] +seconds from UT, because they integer-divide the offset by +3600 to get 0 and then display the hour part as +.q "+00". +.IP \(bu +Some readers mishandle UT offsets that are not a multiple +of one hour, or of 15 minutes, or of 1 minute. +.RE +.SH SEE ALSO +.BR time (2), +.BR localtime (3), +.BR tzset (3), +.BR tzselect (8), +.BR zdump (8), +.BR zic (8). +.PP +Olson A, Eggert P, Murchison K. The Time Zone Information Format (TZif). +2019 Feb. +.UR https://\:datatracker.ietf.org/\:doc/\:html/\:rfc8536 +Internet RFC 8536 +.UE +.UR https://\:doi.org/\:10.17487/\:RFC8536 +doi:10.17487/RFC8536 +.UE . diff --git a/man/man5/utmp.5 b/man/man5/utmp.5 new file mode 100644 index 0000000..2f3c07e --- /dev/null +++ b/man/man5/utmp.5 @@ -0,0 +1,348 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@cantor.informatik.rwth-aachen.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1995-02-26 by Michael Haardt +.\" Modified 1996-07-20 by Michael Haardt +.\" Modified 1997-07-02 by Nicolás Lichtmaier +.\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne +.TH utmp 5 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +utmp, wtmp \- login records +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +The +.I utmp +file allows one to discover information about who is currently using the +system. +There may be more users currently using the system, because not +all programs use utmp logging. +.P +.B Warning: +.I utmp +must not be writable by the user class "other", +because many system programs (foolishly) +depend on its integrity. +You risk faked system logfiles and +modifications of system files if you leave +.I utmp +writable to any user other than the owner and group owner of the file. +.P +The file is a sequence of +.I utmp +structures, +declared as follows in +.I +(note that this is only one of several definitions +around; details depend on the version of libc): +.P +.in +4n +.EX +/* Values for ut_type field, below */ +\& +#define EMPTY 0 /* Record does not contain valid info + (formerly known as UT_UNKNOWN on Linux) */ +#define RUN_LVL 1 /* Change in system run\-level (see + \fBinit\fP(1)) */ +#define BOOT_TIME 2 /* Time of system boot (in \fIut_tv\fP) */ +#define NEW_TIME 3 /* Time after system clock change + (in \fIut_tv\fP) */ +#define OLD_TIME 4 /* Time before system clock change + (in \fIut_tv\fP) */ +#define INIT_PROCESS 5 /* Process spawned by \fBinit\fP(1) */ +#define LOGIN_PROCESS 6 /* Session leader process for user login */ +#define USER_PROCESS 7 /* Normal process */ +#define DEAD_PROCESS 8 /* Terminated process */ +#define ACCOUNTING 9 /* Not implemented */ +\& +#define UT_LINESIZE 32 +#define UT_NAMESIZE 32 +#define UT_HOSTSIZE 256 +\& +struct exit_status { /* Type for ut_exit, below */ + short e_termination; /* Process termination status */ + short e_exit; /* Process exit status */ +}; +\& +struct utmp { + short ut_type; /* Type of record */ + pid_t ut_pid; /* PID of login process */ + char ut_line[UT_LINESIZE]; /* Device name of tty \- "/dev/" */ + char ut_id[4]; /* Terminal name suffix, + or inittab(5) ID */ + char ut_user[UT_NAMESIZE]; /* Username */ + char ut_host[UT_HOSTSIZE]; /* Hostname for remote login, or + kernel version for run\-level + messages */ + struct exit_status ut_exit; /* Exit status of a process + marked as DEAD_PROCESS; not + used by Linux init(1) */ + /* The ut_session and ut_tv fields must be the same size when + compiled 32\- and 64\-bit. This allows data files and shared + memory to be shared between 32\- and 64\-bit applications. */ +#if __WORDSIZE == 64 && defined __WORDSIZE_COMPAT32 + int32_t ut_session; /* Session ID (\fBgetsid\fP(2)), + used for windowing */ + struct { + int32_t tv_sec; /* Seconds */ + int32_t tv_usec; /* Microseconds */ + } ut_tv; /* Time entry was made */ +#else + long ut_session; /* Session ID */ + struct timeval ut_tv; /* Time entry was made */ +#endif +\& + int32_t ut_addr_v6[4]; /* Internet address of remote + host; IPv4 address uses + just ut_addr_v6[0] */ + char __unused[20]; /* Reserved for future use */ +}; +\& +/* Backward compatibility hacks */ +#define ut_name ut_user +#ifndef _NO_UT_TIME +#define ut_time ut_tv.tv_sec +#endif +#define ut_xtime ut_tv.tv_sec +#define ut_addr ut_addr_v6[0] +.EE +.in +.P +This structure gives the name of the special file associated with the +user's terminal, the user's login name, and the time of login in the form +of +.BR time (2). +String fields are terminated by a null byte (\[aq]\e0\[aq]) +if they are shorter than the size +of the field. +.P +The first entries ever created result from +.BR init (1) +processing +.BR inittab (5). +Before an entry is processed, though, +.BR init (1) +cleans up utmp by setting \fIut_type\fP to \fBDEAD_PROCESS\fP, clearing +\fIut_user\fP, \fIut_host\fP, and \fIut_time\fP with null bytes for each +record which \fIut_type\fP is not \fBDEAD_PROCESS\fP or \fBRUN_LVL\fP +and where no process with PID \fIut_pid\fP exists. +If no empty record +with the needed \fIut_id\fP can be found, +.BR init (1) +creates a new one. +It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the +current values, and \fIut_type\fP to \fBINIT_PROCESS\fP. +.P +.BR mingetty (8) +(or +.BR agetty (8)) +locates the entry by the PID, changes \fIut_type\fP to +\fBLOGIN_PROCESS\fP, changes \fIut_time\fP, sets \fIut_line\fP, and waits +for connection to be established. +.BR login (1), +after a user has been +authenticated, changes \fIut_type\fP to \fBUSER_PROCESS\fP, changes +\fIut_time\fP, and sets \fIut_host\fP and \fIut_addr\fP. +Depending on +.BR mingetty (8) +(or +.BR agetty (8)) +and +.BR login (1), +records may be located by +\fIut_line\fP instead of the preferable \fIut_pid\fP. +.P +When +.BR init (1) +finds that a process has exited, it locates its utmp entry by +.IR ut_pid , +sets +.I ut_type +to +.BR DEAD_PROCESS , +and clears +.IR ut_user , +.IR ut_host , +and +.I ut_time +with null bytes. +.P +.BR xterm (1) +and other terminal emulators directly create a +\fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the +string that suffix part of the terminal name (the characters +following +.IR /dev/ [pt] ty ). +If they find a \fBDEAD_PROCESS\fP for this ID, +they recycle it, otherwise they create a new entry. +If they can, they +will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that +they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP +as well. +.P +.BR telnetd (8) +sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to +.BR login (1) +as usual. +After the telnet session ends, +.BR telnetd (8) +cleans up utmp in the described way. +.P +The \fIwtmp\fP file records all logins and logouts. +Its format is exactly like \fIutmp\fP except that a null username +indicates a logout +on the associated terminal. +Furthermore, the terminal name \fB\[ti]\fP +with username \fBshutdown\fP or \fBreboot\fP indicates a system +shutdown or reboot and the pair of terminal names \fB|\fP/\fB}\fP +logs the old/new system time when +.BR date (1) +changes it. +\fIwtmp\fP is maintained by +.BR login (1), +.BR init (1), +and some versions of +.BR getty (8) +(e.g., +.BR mingetty (8) +or +.BR agetty (8)). +None of these programs creates the file, so if it is +removed, record-keeping is turned off. +.SH FILES +.I /var/run/utmp +.br +.I /var/log/wtmp +.SH VERSIONS +POSIX.1 does not specify a +.I utmp +structure, but rather one named +.I utmpx +(as part of the XSI extension), +with specifications for the fields +.IR ut_type , +.IR ut_pid , +.IR ut_line , +.IR ut_id , +.IR ut_user , +and +.IR ut_tv . +POSIX.1 does not specify the lengths of the +.I ut_line +and +.I ut_user +fields. +.P +Linux defines the +.I utmpx +structure to be the same as the +.I utmp +structure. +.SH STANDARDS +Linux. +.SH HISTORY +Linux utmp entries conform neither to v7/BSD nor to System V; they are a +mix of the two. +.P +v7/BSD has fewer fields; most importantly it lacks +\fIut_type\fP, which causes native v7/BSD-like programs to display (for +example) dead or login entries. +Further, there is no configuration file +which allocates slots to sessions. +BSD does so because it lacks \fIut_id\fP fields. +.P +In Linux (as in System V), the \fIut_id\fP field of a +record will never change once it has been set, which reserves that slot +without needing a configuration file. +Clearing \fIut_id\fP may result +in race conditions leading to corrupted utmp entries and potential +security holes. +Clearing the abovementioned fields by filling them +with null bytes is not required by System V semantics, +but makes it possible to run +many programs which assume BSD semantics and which do not modify utmp. +Linux uses the BSD conventions for line contents, as documented above. +.P +.\" mtk: What is the referrent of "them" in the following sentence? +.\" System V only uses the type field to mark them and logs +.\" informative messages such as \fB"new time"\fP in the line field. +System V has no \fIut_host\fP or \fIut_addr_v6\fP fields. +.SH NOTES +Unlike various other +systems, where utmp logging can be disabled by removing the file, utmp +must always exist on Linux. +If you want to disable +.BR who (1), +then do not make utmp world readable. +.P +The file format is machine-dependent, so it is recommended that it be +processed only on the machine architecture where it was created. +.P +Note that on \fIbiarch\fP platforms, that is, systems which can run both +32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.), +\fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode. +The same goes for \fIut_session\fP and \fIut_time\fP if they are present. +This allows data files and shared memory to be shared between +32-bit and 64-bit applications. +This is achieved by changing the type of +.I ut_session +to +.IR int32_t , +and that of +.I ut_tv +to a struct with two +.I int32_t +fields +.I tv_sec +and +.IR tv_usec . +Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP, +then instead of the call: +.P +.in +4n +.EX +gettimeofday((struct timeval *) &ut.ut_tv, NULL); +.EE +.in +.P +the following method of setting this field is recommended: +.P +.in +4n +.EX +struct utmp ut; +struct timeval tv; +\& +gettimeofday(&tv, NULL); +ut.ut_tv.tv_sec = tv.tv_sec; +ut.ut_tv.tv_usec = tv.tv_usec; +.EE +.in +.\" .P +.\" Note that the \fIutmp\fP struct from libc5 has changed in libc6. +.\" Because of this, +.\" binaries using the old libc5 struct will corrupt +.\" .IR /var/run/utmp " and/or " /var/log/wtmp . +.\" .SH BUGS +.\" This man page is based on the libc5 one, things may work differently now. +.SH SEE ALSO +.BR ac (1), +.BR date (1), +.BR init (1), +.BR last (1), +.BR login (1), +.BR logname (1), +.BR lslogins (1), +.BR users (1), +.BR utmpdump (1), +.BR who (1), +.BR getutent (3), +.BR getutmp (3), +.BR login (3), +.BR logout (3), +.BR logwtmp (3), +.BR updwtmp (3) diff --git a/man/man5/utmpx.5 b/man/man5/utmpx.5 new file mode 100644 index 0000000..1fa9e5a --- /dev/null +++ b/man/man5/utmpx.5 @@ -0,0 +1 @@ +.so man5/utmp.5 diff --git a/man/man5/wtmp.5 b/man/man5/wtmp.5 new file mode 100644 index 0000000..1fa9e5a --- /dev/null +++ b/man/man5/wtmp.5 @@ -0,0 +1 @@ +.so man5/utmp.5 diff --git a/man/man6/intro.6 b/man/man6/intro.6 new file mode 100644 index 0000000..519c45c --- /dev/null +++ b/man/man6/intro.6 @@ -0,0 +1,17 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:19:57 1993 by Rik Faith (faith@cs.unc.edu) +.TH intro 6 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intro \- introduction to games +.SH DESCRIPTION +Section 6 of the manual describes the games and funny little programs +available on the system. +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! diff --git a/man/man7/address_families.7 b/man/man7/address_families.7 new file mode 100644 index 0000000..6dfd95a --- /dev/null +++ b/man/man7/address_families.7 @@ -0,0 +1,392 @@ +.\" Copyright (c) 2018 by Eugene Syromyatnikov , +.\" and Copyright (c) 2018 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH address_families 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +address_families \- socket address families (domains) +.SH SYNOPSIS +.nf +.BR "#include " " /* See NOTES */" +.B #include +.P +.BI "int socket(int " domain ", int " type ", int " protocol ); +.fi +.SH DESCRIPTION +The +.I domain +argument of the +.BR socket (2) +specifies a communication domain; this selects the protocol +family which will be used for communication. +These families are defined in +.IR . +The formats currently understood by the Linux kernel include: +.TP +.B AF_UNIX +.TQ +.B AF_LOCAL +Local communication. +For further information, see +.BR unix (7). +.TP +.B AF_INET +IPv4 Internet protocols. +For further information, see +.BR ip (7). +.TP +.B AF_AX25 +Amateur radio AX.25 protocol. +For further information, see +.BR ax25 (4). +.\" Part of ax25-tools +.TP +.B AF_IPX +IPX \- Novell protocols. +.TP +.B AF_APPLETALK +AppleTalk +For further information, see +.BR ddp (7). +.TP +.B AF_NETROM +AX.25 packet layer protocol. +For further information, see +.BR netrom (4), +.\" Part of ax25-tools package +.UR https://www.tldp.org/HOWTO/AX25-HOWTO/x61.html +.I The Packet Radio Protocols and Linux +.UE +and the +.IR AX.25 ", " NET/ROM ", and " "ROSE network programming" +chapters of the +.UR https://www.tldp.org/HOWTO/AX25-HOWTO/x2107.html +.I Linux Amateur Radio AX.25 HOWTO +.UE . +.TP +.B AF_BRIDGE +Can't be used for creating sockets; +mostly used for bridge links in +.BR rtnetlink (7) +protocol commands. +.TP +.B AF_ATMPVC +Access to raw ATM Permanent Virtual Circuits (PVCs). +For further information, see the +.UR https://www.tldp.org/HOWTO/text/ATM-Linux-HOWTO +.I ATM on Linux HOWTO +.UE . +.TP +.B AF_X25 +ITU-T X.25 / ISO/IEC\~8208 protocol. +For further information, see +.BR x25 (7). +.TP +.B AF_INET6 +IPv6 Internet protocols. +For further information, see +.BR ipv6 (7). +.TP +.B AF_ROSE +RATS (Radio Amateur Telecommunications Society). +Open Systems environment (ROSE) AX.25 packet layer protocol. +For further information, see the resources listed for +.BR AF_NETROM . +.TP +.B AF_DECnet +DECet protocol sockets. +See +.I Documentation/networking/decnet.txt +in the Linux kernel source tree for details. +.TP +.B AF_NETBEUI +Reserved for "802.2LLC project"; never used. +.TP +.B AF_SECURITY +This was a short-lived (between Linux 2.1.30 and 2.1.99pre2) protocol family +for firewall upcalls. +.TP +.B AF_KEY +Key management protocol, originally developed for usage with IPsec +(since Linux 2.1.38). +This has no relation to +.BR keyctl (2) +and the in-kernel key storage facility. +See +.UR https://tools.ietf.org/html/rfc2367 +RFC 2367 +.I PF_KEY Key Management API, Version 2 +.UE +for details. +.TP +.B AF_NETLINK +Kernel user interface device. +For further information, see +.BR netlink (7). +.TP +.B AF_PACKET +Low-level packet interface. +For further information, see +.BR packet (7). +.\" .TP +.\" .B AF_ASH +.\" Asynchronous Serial Host protocol (?) +.\" Notes from Eugene Syromyatnikov: +.\" I haven't found any concrete information about this one; +.\" it never was implemented in Linux, at least, judging by historical +.\" repos. There is also this file (and its variations): +.\" https://github.com/ecki/net-tools/blob/master/lib/ash.c +.\" ( https://github.com/ecki/net-tools/commits/master/lib/ash.c ) +.\" it mentions "NET-2 distribution" (BSD Net/2?), but, again, I failed +.\" to find any mentions of "ash" protocol there. +.\" (for the reference: +.\" ftp://pdp11.org.ru/pub/unix-archive/Distributions/UCB/Net2/net2.tar.gz ) +.\" Another source that mentions it is +.\" https://www.silabs.com/documents/public/user-guides/ug101-uart-gateway-protocol-reference.pdf +.\" https://www.silabs.com/documents/public/user-guides/ug115-ashv3-protocol-reference.pdf +.\" but I doubt that it's related, as former files use 64-byte addresses and +.\" "Hamming-encode of hops", and that's barely combines with a protocol +.\" that is mainly used over serial connection. +.TP +.B AF_ECONET +.\" commit: 349f29d841dbae854bd7367be7c250401f974f47 +Acorn Econet protocol (removed in Linux 3.5). +See the +.UR http://www.8bs.com/othrdnld/manuals/econet.shtml +Econet documentation +.UE +for details. +.TP +.B AF_ATMSVC +Access to ATM Switched Virtual Circuits (SVCs) +See the +.UR https://www.tldp.org/HOWTO/text/ATM-Linux-HOWTO +.I ATM on Linux HOWTO +.UE +for details. +.TP +.B AF_RDS +.\" commit: 639b321b4d8f4e412bfbb2a4a19bfebc1e68ace4 +Reliable Datagram Sockets (RDS) protocol (since Linux 2.6.30). +RDS over RDMA has no relation to +.B AF_SMC +or +.BR AF_XDP . +For further information, see +.\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds.7 +.\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds-rdma.7 +.BR rds (7), +.BR rds\-rdma (7), +and +.I Documentation/networking/rds.txt +in the Linux kernel source tree. +.TP +.B AF_IRDA +.\" commits: 1ca163afb6fd569b, d64c2a76123f0300 +Socket interface over IrDA +(moved to staging in Linux 4.14, removed in Linux 4.17). +.\" irda-utils: https://sourceforge.net/p/irda/code/HEAD/tree/tags/IRDAUTILS_0_9_18/irda-utils/man/irda.7.gz?format=raw +For further information, see +.BR irda (7). +.TP +.B AF_PPPOX +Generic PPP transport layer, for setting up L2 tunnels +(L2TP and PPPoE). +See +.I Documentation/networking/l2tp.txt +in the Linux kernel source tree for details. +.TP +.B AF_WANPIPE +.\" commits: ce0ecd594d78710422599918a608e96dd1ee6024 +Legacy protocol for wide area network (WAN) connectivity +that was used by Sangoma WAN cards (called "WANPIPE"); +removed in Linux 2.6.21. +.TP +.B AF_LLC +.\" linux-history commit: 34beb106cde7da233d4df35dd3d6cf4fee937caa +Logical link control (IEEE 802.2 LLC) protocol, upper part +of data link layer of ISO/OSI networking protocol stack +(since Linux 2.4); +has no relation to +.BR AF_PACKET . +See chapter +.I 13.5.3. Logical Link Control +in +.I Understanding Linux Kernel Internals +(O'Reilly Media, 2006) +and +.I IEEE Standards for Local Area Networks: Logical Link Control +(The Institute of Electronics and Electronics Engineers, Inc., +New York, New York, 1985) +for details. +See also +.UR https://wiki.linuxfoundation.org/networking/llc +some historical notes +.UE +regarding its development. +.TP +.B AF_IB +.\" commits: 8d36eb01da5d371f..ce117ffac2e93334 +InfiniBand native addressing (since Linux 3.11). +.TP +.B AF_MPLS +.\" commits: 0189197f441602acdca3f97750d392a895b778fd +Multiprotocol Label Switching (since Linux 4.1); +mostly used for configuring MPLS routing via +.BR netlink (7), +as it doesn't expose ability to create sockets to user space. +.TP +.B AF_CAN +.\" commits: 8dbde28d9711475a..5423dd67bd0108a1 +Controller Area Network automotive bus protocol (since Linux 2.6.25). +See +.I Documentation/networking/can.rst +in the Linux kernel source tree for details. +.TP +.B AF_TIPC +.\" commits: b97bf3fd8f6a16966d4f18983b2c40993ff937d4 +TIPC, "cluster domain sockets" protocol (since Linux 2.6.16). +See +.UR http://tipc.io/programming.html +.I TIPC Programmer's Guide +.UE +and the +.UR http://tipc.io/protocol.html +protocol description +.UE +for details. +.TP +.B AF_BLUETOOTH +.\" commits: 8d36eb01da5d371f..ce117ffac2e93334 +Bluetooth low-level socket protocol (since Linux 3.11). +See +.UR https://git.kernel.org\:/pub/scm\:/bluetooth/bluez.git\:/tree/doc/mgmt-api.txt +.I Bluetooth Management API overview +.UE +and +.UR https://people.csail.mit.edu/albert/bluez-intro/ +.I An Introduction to Bluetooth Programming +by Albert Huang +.UE +for details. +.TP +.B AF_IUCV +.\" commit: eac3731bd04c7131478722a3c148b78774553116 +IUCV (inter-user communication vehicle) z/VM protocol +for hypervisor-guest interaction (since Linux 2.6.21); +has no relation to +.B AF_VSOCK +and/or +.B AF_SMC +See +.UR https://www.ibm.com\:/support\:/knowledgecenter\:/en/SSB27U_6.4.0\:/com.ibm.zvm.v640.hcpb4\:/iucv.htm +.I IUCV protocol overview +.UE +for details. +.TP +.B AF_RXRPC +.\" commit: 17926a79320afa9b95df6b977b40cca6d8713cea +.\" http://people.redhat.com/~dhowells/rxrpc/ +.\" https://www.infradead.org/~dhowells/kafs/af_rxrpc_client.html +.\" http://workshop.openafs.org/afsbpw09/talks/thu_2/kafs.pdf +.\" http://pages.cs.wisc.edu/~remzi/OSTEP/dist-afs.pdf +.\" http://web.mit.edu/kolya/afs/rx/rx-spec +Rx, Andrew File System remote procedure call protocol +(since Linux 2.6.22). +See +.I Documentation/networking/rxrpc.txt +in the Linux kernel source tree for details. +.TP +.B AF_ISDN +.\" commit: 1b2b03f8e514e4f68e293846ba511a948b80243c +New "modular ISDN" driver interface protocol (since Linux 2.6.27). +See the +.UR http://www.misdn.eu/wiki/Main_Page/ +mISDN wiki +.UE +for details. +.TP +.B AF_PHONET +.\" commit: 4b07b3f69a8471cdc142c51461a331226fef248a +Nokia cellular modem IPC/RPC interface (since Linux 2.6.31). +See +.I Documentation/networking/phonet.txt +in the Linux kernel source tree for details. +.TP +.B AF_IEEE802154 +.\" commit: 9ec7671603573ede31207eb5b0b3e1aa211b2854 +IEEE 802.15.4 WPAN (wireless personal area network) raw packet protocol +(since Linux 2.6.31). +See +.I Documentation/networking/ieee802154.txt +in the Linux kernel source tree for details. +.TP +.B AF_CAIF +.\" commit: 529d6dad5bc69de14cdd24831e2a14264e93daa4 +.\" https://lwn.net/Articles/371017/ +.\" http://read.pudn.com/downloads157/doc/comm/698729/Misc/caif/Com%20CPU%20to%20Appl%20CPU%20Interface%20DESCRIPTION_LZN901%202002_revR1C.pdf +.\" http://read.pudn.com/downloads157/doc/comm/698729/Misc/caif/Com%20CPU%20to%20Appl%20CPU%20Interface%20PROTOCOL%20SPECIFICATION_LZN901%201708_revR1A.pdf +Ericsson's Communication CPU to Application CPU interface (CAIF) protocol +(since Linux 2.6.36). +See +.I Documentation/networking/caif/Linux\-CAIF.txt +in the Linux kernel source tree for details. +.TP +.B AF_ALG +Interface to kernel crypto API (since Linux 2.6.38). +See +.I Documentation/crypto/userspace\-if.rst +in the Linux kernel source tree for details. +.TP +.B AF_VSOCK +.\" commit: d021c344051af91f42c5ba9fdedc176740cbd238 +VMWare VSockets protocol for hypervisor-guest interaction (since Linux 3.9); +has no relation to +.B AF_IUCV +and +.BR AF_SMC . +For further information, see +.BR vsock (7). +.TP +.B AF_KCM +.\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314 +KCM (kernel connection multiplexer) interface (since Linux 4.6). +See +.I Documentation/networking/kcm.txt +in the Linux kernel source tree for details. +.TP +.B AF_QIPCRTR +.\" commit: bdabad3e363d825ddf9679dd431cca0b2c30f881 +Qualcomm IPC router interface protocol (since Linux 4.7). +.TP +.B AF_SMC +.\" commit: f3a3e248f3f7cd9a4bed334022704d7e7fc781bf +SMC-R (shared memory communications over RDMA) protocol (since Linux 4.11), +and SMC-D (shared memory communications, direct memory access) protocol +for intra-node z/VM quest interaction (since Linux 4.19); +has no relation to +.BR AF_RDS ", " AF_IUCV +or +.BR AF_VSOCK . +See +.UR https://tools.ietf.org/html/rfc7609 +RFC 7609 +.I IBM's Shared Memory Communications over RDMA (SMC-R) Protocol +.UE +for details regarding SMC-R. +See +.UR https://www-01.ibm.com\:/software/network\:/commserver\:/SMC-D/index.html +.I SMC-D Reference Information +.UE +for details regarding SMC-D. +.TP +.B AF_XDP +.\" commit: c0c77d8fb787cfe0c3fca689c2a30d1dad4eaba7 +XDP (express data path) interface (since Linux 4.18). +See +.I Documentation/networking/af_xdp.rst +in the Linux kernel source tree for details. +.SH SEE ALSO +.BR socket (2), +.BR socket (7) diff --git a/man/man7/aio.7 b/man/man7/aio.7 new file mode 100644 index 0000000..0b5c7c9 --- /dev/null +++ b/man/man7/aio.7 @@ -0,0 +1,446 @@ +.\" Copyright (c) 2010 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH AIO 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +aio \- POSIX asynchronous I/O overview +.SH DESCRIPTION +The POSIX asynchronous I/O (AIO) interface allows applications +to initiate one or more I/O operations that are performed +asynchronously (i.e., in the background). +The application can elect to be notified of completion of +the I/O operation in a variety of ways: +by delivery of a signal, by instantiation of a thread, +or no notification at all. +.P +The POSIX AIO interface consists of the following functions: +.TP +.BR aio_read (3) +Enqueue a read request. +This is the asynchronous analog of +.BR read (2). +.TP +.BR aio_write (3) +Enqueue a write request. +This is the asynchronous analog of +.BR write (2). +.TP +.BR aio_fsync (3) +Enqueue a sync request for the I/O operations on a file descriptor. +This is the asynchronous analog of +.BR fsync (2) +and +.BR fdatasync (2). +.TP +.BR aio_error (3) +Obtain the error status of an enqueued I/O request. +.TP +.BR aio_return (3) +Obtain the return status of a completed I/O request. +.TP +.BR aio_suspend (3) +Suspend the caller until one or more of a specified set of +I/O requests completes. +.TP +.BR aio_cancel (3) +Attempt to cancel outstanding I/O requests on a specified +file descriptor. +.TP +.BR lio_listio (3) +Enqueue multiple I/O requests using a single function call. +.P +The +.I aiocb +("asynchronous I/O control block") structure defines +parameters that control an I/O operation. +An argument of this type is employed with all of the functions listed above. +This structure has the following form: +.P +.in +4n +.EX +#include +\& +struct aiocb { + /* The order of these fields is implementation\-dependent */ +\& + int aio_fildes; /* File descriptor */ + off_t aio_offset; /* File offset */ + volatile void *aio_buf; /* Location of buffer */ + size_t aio_nbytes; /* Length of transfer */ + int aio_reqprio; /* Request priority */ + struct sigevent aio_sigevent; /* Notification method */ + int aio_lio_opcode; /* Operation to be performed; + lio_listio() only */ +\& + /* Various implementation\-internal fields not shown */ +}; +\& +/* Operation codes for \[aq]aio_lio_opcode\[aq]: */ +\& +enum { LIO_READ, LIO_WRITE, LIO_NOP }; +.EE +.in +.P +The fields of this structure are as follows: +.TP +.I aio_fildes +The file descriptor on which the I/O operation is to be performed. +.TP +.I aio_offset +This is the file offset at which the I/O operation is to be performed. +.TP +.I aio_buf +This is the buffer used to transfer data for a read or write operation. +.TP +.I aio_nbytes +This is the size of the buffer pointed to by +.IR aio_buf . +.TP +.I aio_reqprio +This field specifies a value that is subtracted +from the calling thread's real-time priority in order to +determine the priority for execution of this I/O request (see +.BR pthread_setschedparam (3)). +The specified value must be between 0 and the value returned by +.IR sysconf(_SC_AIO_PRIO_DELTA_MAX) . +This field is ignored for file synchronization operations. +.TP +.I aio_sigevent +This field is a structure that specifies how the caller is +to be notified when the asynchronous I/O operation completes. +Possible values for +.I aio_sigevent.sigev_notify +are +.BR SIGEV_NONE , +.BR SIGEV_SIGNAL , +and +.BR SIGEV_THREAD . +See +.BR sigevent (3type) +for further details. +.TP +.I aio_lio_opcode +The type of operation to be performed; used only for +.BR lio_listio (3). +.P +In addition to the standard functions listed above, +the GNU C library provides the following extension to the POSIX AIO API: +.TP +.BR aio_init (3) +Set parameters for tuning the behavior of the glibc POSIX AIO implementation. +.SH ERRORS +.TP +.B EINVAL +The +.I aio_reqprio +field of the +.I aiocb +structure was less than 0, +or was greater than the limit returned by the call +.IR sysconf(_SC_AIO_PRIO_DELTA_MAX) . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +glibc 2.1. +.SH NOTES +It is a good idea to zero out the control block buffer before use (see +.BR memset (3)). +The control block buffer and the buffer pointed to by +.I aio_buf +must not be changed while the I/O operation is in progress. +These buffers must remain valid until the I/O operation completes. +.P +Simultaneous asynchronous read or write operations using the same +.I aiocb +structure yield undefined results. +.P +The current Linux POSIX AIO implementation is provided in user space by glibc. +This has a number of limitations, most notably that maintaining multiple +threads to perform I/O operations is expensive and scales poorly. +Work has been in progress for some time on a kernel +state-machine-based implementation of asynchronous I/O +(see +.BR io_submit (2), +.BR io_setup (2), +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_getevents (2)), +but this implementation hasn't yet matured to the point where +the POSIX AIO implementation can be completely +reimplemented using the kernel system calls. +.\" http://lse.sourceforge.net/io/aio.html +.\" http://lse.sourceforge.net/io/aionotes.txt +.\" http://lwn.net/Articles/148755/ +.SH EXAMPLES +The program below opens each of the files named in its command-line +arguments and queues a request on the resulting file descriptor using +.BR aio_read (3). +The program then loops, +periodically monitoring each of the I/O operations +that is still in progress using +.BR aio_error (3). +Each of the I/O requests is set up to provide notification by delivery +of a signal. +After all I/O requests have completed, +the program retrieves their status using +.BR aio_return (3). +.P +The +.B SIGQUIT +signal (generated by typing control-\e) causes the program to request +cancelation of each of the outstanding requests using +.BR aio_cancel (3). +.P +Here is an example of what we might see when running this program. +In this example, the program queues two requests to standard input, +and these are satisfied by two lines of input containing +"abc" and "x". +.P +.in +4n +.EX +$ \fB./a.out /dev/stdin /dev/stdin\fP +opened /dev/stdin on descriptor 3 +opened /dev/stdin on descriptor 4 +aio_error(): + for request 0 (descriptor 3): In progress + for request 1 (descriptor 4): In progress +\fBabc\fP +I/O completion signal received +aio_error(): + for request 0 (descriptor 3): I/O succeeded + for request 1 (descriptor 4): In progress +aio_error(): + for request 1 (descriptor 4): In progress +\fBx\fP +I/O completion signal received +aio_error(): + for request 1 (descriptor 4): I/O succeeded +All I/O requests completed +aio_return(): + for request 0 (descriptor 3): 4 + for request 1 (descriptor 4): 2 +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include +#include +\& +#define BUF_SIZE 20 /* Size of buffers for read operations */ +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0) +\& +struct ioRequest { /* Application\-defined structure for tracking + I/O requests */ + int reqNum; + int status; + struct aiocb *aiocbp; +}; +\& +static volatile sig_atomic_t gotSIGQUIT = 0; + /* On delivery of SIGQUIT, we attempt to + cancel all outstanding I/O requests */ +\& +static void /* Handler for SIGQUIT */ +quitHandler(int sig) +{ + gotSIGQUIT = 1; +} +\& +#define IO_SIGNAL SIGUSR1 /* Signal used to notify I/O completion */ +\& +static void /* Handler for I/O completion signal */ +aioSigHandler(int sig, siginfo_t *si, void *ucontext) +{ + if (si\->si_code == SI_ASYNCIO) { + write(STDOUT_FILENO, "I/O completion signal received\en", 31); +\& + /* The corresponding ioRequest structure would be available as + struct ioRequest *ioReq = si\->si_value.sival_ptr; + and the file descriptor would then be available via + ioReq\->aiocbp\->aio_fildes */ + } +} +\& +int +main(int argc, char *argv[]) +{ + struct sigaction sa; + int s; + int numReqs; /* Total number of queued I/O requests */ + int openReqs; /* Number of I/O requests still in progress */ +\& + if (argc < 2) { + fprintf(stderr, "Usage: %s ...\en", + argv[0]); + exit(EXIT_FAILURE); + } +\& + numReqs = argc \- 1; +\& + /* Allocate our arrays. */ +\& + struct ioRequest *ioList = calloc(numReqs, sizeof(*ioList)); + if (ioList == NULL) + errExit("calloc"); +\& + struct aiocb *aiocbList = calloc(numReqs, sizeof(*aiocbList)); + if (aiocbList == NULL) + errExit("calloc"); +\& + /* Establish handlers for SIGQUIT and the I/O completion signal. */ +\& + sa.sa_flags = SA_RESTART; + sigemptyset(&sa.sa_mask); +\& + sa.sa_handler = quitHandler; + if (sigaction(SIGQUIT, &sa, NULL) == \-1) + errExit("sigaction"); +\& + sa.sa_flags = SA_RESTART | SA_SIGINFO; + sa.sa_sigaction = aioSigHandler; + if (sigaction(IO_SIGNAL, &sa, NULL) == \-1) + errExit("sigaction"); +\& + /* Open each file specified on the command line, and queue + a read request on the resulting file descriptor. */ +\& + for (size_t j = 0; j < numReqs; j++) { + ioList[j].reqNum = j; + ioList[j].status = EINPROGRESS; + ioList[j].aiocbp = &aiocbList[j]; +\& + ioList[j].aiocbp\->aio_fildes = open(argv[j + 1], O_RDONLY); + if (ioList[j].aiocbp\->aio_fildes == \-1) + errExit("open"); + printf("opened %s on descriptor %d\en", argv[j + 1], + ioList[j].aiocbp\->aio_fildes); +\& + ioList[j].aiocbp\->aio_buf = malloc(BUF_SIZE); + if (ioList[j].aiocbp\->aio_buf == NULL) + errExit("malloc"); +\& + ioList[j].aiocbp\->aio_nbytes = BUF_SIZE; + ioList[j].aiocbp\->aio_reqprio = 0; + ioList[j].aiocbp\->aio_offset = 0; + ioList[j].aiocbp\->aio_sigevent.sigev_notify = SIGEV_SIGNAL; + ioList[j].aiocbp\->aio_sigevent.sigev_signo = IO_SIGNAL; + ioList[j].aiocbp\->aio_sigevent.sigev_value.sival_ptr = + &ioList[j]; +\& + s = aio_read(ioList[j].aiocbp); + if (s == \-1) + errExit("aio_read"); + } +\& + openReqs = numReqs; +\& + /* Loop, monitoring status of I/O requests. */ +\& + while (openReqs > 0) { + sleep(3); /* Delay between each monitoring step */ +\& + if (gotSIGQUIT) { +\& + /* On receipt of SIGQUIT, attempt to cancel each of the + outstanding I/O requests, and display status returned + from the cancelation requests. */ +\& + printf("got SIGQUIT; canceling I/O requests: \en"); +\& + for (size_t j = 0; j < numReqs; j++) { + if (ioList[j].status == EINPROGRESS) { + printf(" Request %zu on descriptor %d:", j, + ioList[j].aiocbp\->aio_fildes); + s = aio_cancel(ioList[j].aiocbp\->aio_fildes, + ioList[j].aiocbp); + if (s == AIO_CANCELED) + printf("I/O canceled\en"); + else if (s == AIO_NOTCANCELED) + printf("I/O not canceled\en"); + else if (s == AIO_ALLDONE) + printf("I/O all done\en"); + else + perror("aio_cancel"); + } + } +\& + gotSIGQUIT = 0; + } +\& + /* Check the status of each I/O request that is still + in progress. */ +\& + printf("aio_error():\en"); + for (size_t j = 0; j < numReqs; j++) { + if (ioList[j].status == EINPROGRESS) { + printf(" for request %zu (descriptor %d): ", + j, ioList[j].aiocbp\->aio_fildes); + ioList[j].status = aio_error(ioList[j].aiocbp); +\& + switch (ioList[j].status) { + case 0: + printf("I/O succeeded\en"); + break; + case EINPROGRESS: + printf("In progress\en"); + break; + case ECANCELED: + printf("Canceled\en"); + break; + default: + perror("aio_error"); + break; + } +\& + if (ioList[j].status != EINPROGRESS) + openReqs\-\-; + } + } + } +\& + printf("All I/O requests completed\en"); +\& + /* Check status return of all I/O requests. */ +\& + printf("aio_return():\en"); + for (size_t j = 0; j < numReqs; j++) { + ssize_t s; +\& + s = aio_return(ioList[j].aiocbp); + printf(" for request %zu (descriptor %d): %zd\en", + j, ioList[j].aiocbp\->aio_fildes, s); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.nh +.BR io_cancel (2), +.BR io_destroy (2), +.BR io_getevents (2), +.BR io_setup (2), +.BR io_submit (2), +.BR aio_cancel (3), +.BR aio_error (3), +.BR aio_init (3), +.BR aio_read (3), +.BR aio_return (3), +.BR aio_write (3), +.BR lio_listio (3) +.P +"Asynchronous I/O Support in Linux 2.5", +Bhattacharya, Pratt, Pulavarty, and Morgan, +Proceedings of the Linux Symposium, 2003, +.UR https://www.kernel.org/doc/ols/2003/ols2003\-pages\-351\-366.pdf +.UE diff --git a/man/man7/armscii-8.7 b/man/man7/armscii-8.7 new file mode 100644 index 0000000..2219206 --- /dev/null +++ b/man/man7/armscii-8.7 @@ -0,0 +1,120 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ARMSCII-8 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +armscii-8 \- Armenian character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The Armenian Standard Code for Information Interchange, +8-bit coded character set. +.SS ArmSCII-8 characters +The following table displays the characters in ArmSCII-8 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +242 162 A2 և ARMENIAN SMALL LIGATURE ECH YIWN +243 163 A3 ։ ARMENIAN FULL STOP +244 164 A4 ) RIGHT PARENTHESIS +245 165 A5 ( LEFT PARENTHESIS +246 166 A6 » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +247 167 A7 « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +250 168 A8 — EM DASH +251 169 A9 . FULL STOP +252 170 AA ՝ ARMENIAN COMMA +253 171 AB , COMMA +254 172 AC - HYPHEN-MINUS +255 173 AD ֊ ARMENIAN HYPHEN +256 174 AE … HORIZONTAL ELLIPSIS +257 175 AF ՜ ARMENIAN EXCLAMATION MARK +260 176 B0 ՛ ARMENIAN EMPHASIS MARK +261 177 B1 ՞ ARMENIAN QUESTION MARK +262 178 B2 Ա ARMENIAN CAPITAL LETTER AYB +263 179 B3 ա ARMENIAN SMALL LETTER AYB +264 180 B4 Բ ARMENIAN CAPITAL LETTER BEN +265 181 B5 բ ARMENIAN SMALL LETTER BEN +266 182 B6 Գ ARMENIAN CAPITAL LETTER GIM +267 183 B7 գ ARMENIAN SMALL LETTER GIM +270 184 B8 Դ ARMENIAN CAPITAL LETTER DA +271 185 B9 դ ARMENIAN SMALL LETTER DA +272 186 BA Ե ARMENIAN CAPITAL LETTER ECH +273 187 BB ե ARMENIAN SMALL LETTER ECH +274 188 BC Զ ARMENIAN CAPITAL LETTER ZA +275 189 BD զ ARMENIAN SMALL LETTER ZA +276 190 BE Է ARMENIAN CAPITAL LETTER EH +277 191 BF է ARMENIAN SMALL LETTER EH +300 192 C0 Ը ARMENIAN CAPITAL LETTER ET +301 193 C1 ը ARMENIAN SMALL LETTER ET +302 194 C2 Թ ARMENIAN CAPITAL LETTER TO +303 195 C3 թ ARMENIAN SMALL LETTER TO +304 196 C4 Ժ ARMENIAN CAPITAL LETTER ZHE +305 197 C5 ժ ARMENIAN SMALL LETTER ZHE +306 198 C6 Ի ARMENIAN CAPITAL LETTER INI +307 199 C7 ի ARMENIAN SMALL LETTER INI +310 200 C8 Լ ARMENIAN CAPITAL LETTER LIWN +311 201 C9 լ ARMENIAN SMALL LETTER LIWN +312 202 CA Խ ARMENIAN CAPITAL LETTER XEH +313 203 CB խ ARMENIAN SMALL LETTER XEH +314 204 CC Ծ ARMENIAN CAPITAL LETTER CA +315 205 CD ծ ARMENIAN SMALL LETTER CA +316 206 CE Կ ARMENIAN CAPITAL LETTER KEN +317 207 CF կ ARMENIAN SMALL LETTER KEN +320 208 D0 Հ ARMENIAN CAPITAL LETTER HO +321 209 D1 հ ARMENIAN SMALL LETTER HO +322 210 D2 Ձ ARMENIAN CAPITAL LETTER JA +323 211 D3 ձ ARMENIAN SMALL LETTER JA +324 212 D4 Ղ ARMENIAN CAPITAL LETTER GHAD +325 213 D5 ղ ARMENIAN SMALL LETTER GHAD +326 214 D6 Ճ ARMENIAN CAPITAL LETTER CHEH +327 215 D7 ճ ARMENIAN SMALL LETTER CHEH +330 216 D8 Մ ARMENIAN CAPITAL LETTER MEN +331 217 D9 մ ARMENIAN SMALL LETTER MEN +332 218 DA Յ ARMENIAN CAPITAL LETTER YI +333 219 DB յ ARMENIAN SMALL LETTER YI +334 220 DC Ն ARMENIAN CAPITAL LETTER NOW +335 221 DD ն ARMENIAN SMALL LETTER NOW +336 222 DE Շ ARMENIAN CAPITAL LETTER SHA +337 223 DF շ ARMENIAN SMALL LETTER SHA +340 224 E0 Ո ARMENIAN CAPITAL LETTER VO +341 225 E1 ո ARMENIAN SMALL LETTER VO +342 226 E2 Չ ARMENIAN CAPITAL LETTER CHA +343 227 E3 չ ARMENIAN SMALL LETTER CHA +344 228 E4 Պ ARMENIAN CAPITAL LETTER PEH +345 229 E5 պ ARMENIAN SMALL LETTER PEH +346 230 E6 Ջ ARMENIAN CAPITAL LETTER JHEH +347 231 E7 ջ ARMENIAN SMALL LETTER JHEH +350 232 E8 Ռ ARMENIAN CAPITAL LETTER RA +351 233 E9 ռ ARMENIAN SMALL LETTER RA +352 234 EA Ս ARMENIAN CAPITAL LETTER SEH +353 235 EB ս ARMENIAN SMALL LETTER SEH +354 236 EC Վ ARMENIAN CAPITAL LETTER VEW +355 237 ED վ ARMENIAN SMALL LETTER VEW +356 238 EE Տ ARMENIAN CAPITAL LETTER TIWN +357 239 EF տ ARMENIAN SMALL LETTER TIWN +360 240 F0 Ր ARMENIAN CAPITAL LETTER REH +361 241 F1 ր ARMENIAN SMALL LETTER REH +362 242 F2 Ց ARMENIAN CAPITAL LETTER CO +363 243 F3 ց ARMENIAN SMALL LETTER CO +364 244 F4 Ւ ARMENIAN CAPITAL LETTER YIWN +365 245 F5 ւ ARMENIAN SMALL LETTER YIWN +366 246 F6 Փ ARMENIAN CAPITAL LETTER PIWR +367 247 F7 փ ARMENIAN SMALL LETTER PIWR +370 248 F8 Ք ARMENIAN CAPITAL LETTER KEH +371 249 F9 ք ARMENIAN SMALL LETTER KEH +372 250 FA Օ ARMENIAN CAPITAL LETTER OH +373 251 FB օ ARMENIAN SMALL LETTER OH +374 252 FC Ֆ ARMENIAN CAPITAL LETTER FEH +375 253 FD ֆ ARMENIAN SMALL LETTER FEH +376 254 FE ՚ ARMENIAN APOSTROPHE +.TE +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/arp.7 b/man/man7/arp.7 new file mode 100644 index 0000000..59f0813 --- /dev/null +++ b/man/man7/arp.7 @@ -0,0 +1,306 @@ +'\" t +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Matthew Wilcox . +.\" +.\" Modified June 1999 Andi Kleen +.\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $ +.\" +.TH arp 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +arp \- Linux ARP kernel module. +.SH DESCRIPTION +This kernel protocol module implements the Address Resolution +Protocol defined in RFC\ 826. +It is used to convert between Layer2 hardware addresses +and IPv4 protocol addresses on directly connected networks. +The user normally doesn't interact directly with this module except to +configure it; +instead it provides a service for other protocols in the kernel. +.P +A user process can receive ARP packets by using +.BR packet (7) +sockets. +There is also a mechanism for managing the ARP cache +in user-space by using +.BR netlink (7) +sockets. +The ARP table can also be controlled via +.BR ioctl (2) +on any +.B AF_INET +socket. +.P +The ARP module maintains a cache of mappings between hardware addresses +and protocol addresses. +The cache has a limited size so old and less +frequently used entries are garbage-collected. +Entries which are marked +as permanent are never deleted by the garbage-collector. +The cache can +be directly manipulated by the use of ioctls and its behavior can be +tuned by the +.I /proc +interfaces described below. +.P +When there is no positive feedback for an existing mapping after some +time (see the +.I /proc +interfaces below), a neighbor cache entry is considered stale. +Positive feedback can be gotten from a higher layer; for example from +a successful TCP ACK. +Other protocols can signal forward progress +using the +.B MSG_CONFIRM +flag to +.BR sendmsg (2). +When there is no forward progress, ARP tries to reprobe. +It first tries to ask a local arp daemon +.B app_solicit +times for an updated MAC address. +If that fails and an old MAC address is known, a unicast probe is sent +.B ucast_solicit +times. +If that fails too, it will broadcast a new ARP +request to the network. +Requests are sent only when there is data queued +for sending. +.P +Linux will automatically add a nonpermanent proxy arp entry when it +receives a request for an address it forwards to and proxy arp is +enabled on the receiving interface. +When there is a reject route for the target, no proxy arp entry is added. +.SS Ioctls +Three ioctls are available on all +.B AF_INET +sockets. +They take a pointer to a +.I struct arpreq +as their argument. +.P +.in +4n +.EX +struct arpreq { + struct sockaddr arp_pa; /* protocol address */ + struct sockaddr arp_ha; /* hardware address */ + int arp_flags; /* flags */ + struct sockaddr arp_netmask; /* netmask of protocol address */ + char arp_dev[16]; +}; +.EE +.in +.P +.BR SIOCSARP ", " SIOCDARP " and " SIOCGARP +respectively set, delete, and get an ARP mapping. +Setting and deleting ARP maps are privileged operations and may +be performed only by a process with the +.B CAP_NET_ADMIN +capability or an effective UID of 0. +.P +.I arp_pa +must be an +.B AF_INET +address and +.I arp_ha +must have the same type as the device which is specified in +.IR arp_dev . +.I arp_dev +is a zero-terminated string which names a device. +.RS +.TS +tab(:) allbox; +c s +l l. +\fIarp_flags\fR +flag:meaning +ATF_COM:Lookup complete +ATF_PERM:Permanent entry +ATF_PUBL:Publish entry +ATF_USETRAILERS:Trailers requested +ATF_NETMASK:Use a netmask +ATF_DONTPUB:Don't answer +.TE +.RE +.P +If the +.B ATF_NETMASK +flag is set, then +.I arp_netmask +should be valid. +Linux 2.2 does not support proxy network ARP entries, so this +should be set to 0xffffffff, or 0 to remove an existing proxy arp entry. +.B ATF_USETRAILERS +is obsolete and should not be used. +.SS /proc interfaces +ARP supports a range of +.I /proc +interfaces to configure parameters on a global or per-interface basis. +The interfaces can be accessed by reading or writing the +.I /proc/sys/net/ipv4/neigh/*/* +files. +Each interface in the system has its own directory in +.IR /proc/sys/net/ipv4/neigh/ . +The setting in the "default" directory is used for all newly created +devices. +Unless otherwise specified, time-related interfaces are specified +in seconds. +.TP +.IR anycast_delay " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of jiffies to delay before replying to a +IPv6 neighbor solicitation message. +Anycast support is not yet implemented. +Defaults to 1 second. +.TP +.IR app_solicit " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of probes to send to the user space ARP daemon via +netlink before dropping back to multicast probes (see +.IR mcast_solicit ). +Defaults to 0. +.TP +.IR base_reachable_time " (since Linux 2.2)" +.\" Precisely: 2.1.79 +Once a neighbor has been found, the entry is considered to be valid +for at least a random value between +.IR base_reachable_time "/2 and 3*" base_reachable_time /2. +An entry's validity will be extended if it receives positive feedback +from higher level protocols. +Defaults to 30 seconds. +This file is now obsolete in favor of +.IR base_reachable_time_ms . +.TP +.IR base_reachable_time_ms " (since Linux 2.6.12)" +As for +.IR base_reachable_time , +but measures time in milliseconds. +Defaults to 30000 milliseconds. +.TP +.IR delay_first_probe_time " (since Linux 2.2)" +.\" Precisely: 2.1.79 +Delay before first probe after it has been decided that a neighbor +is stale. +Defaults to 5 seconds. +.TP +.IR gc_interval " (since Linux 2.2)" +.\" Precisely: 2.1.79 +How frequently the garbage collector for neighbor entries +should attempt to run. +Defaults to 30 seconds. +.TP +.IR gc_stale_time " (since Linux 2.2)" +.\" Precisely: 2.1.79 +Determines how often to check for stale neighbor entries. +When a neighbor entry is considered stale, it is resolved again before +sending data to it. +Defaults to 60 seconds. +.TP +.IR gc_thresh1 " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The minimum number of entries to keep in the ARP cache. +The garbage collector will not run if there are fewer than +this number of entries in the cache. +Defaults to 128. +.TP +.IR gc_thresh2 " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The soft maximum number of entries to keep in the ARP cache. +The garbage collector will allow the number of entries to exceed +this for 5 seconds before collection will be performed. +Defaults to 512. +.TP +.IR gc_thresh3 " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The hard maximum number of entries to keep in the ARP cache. +The garbage collector will always run if there are more than +this number of entries in the cache. +Defaults to 1024. +.TP +.IR locktime " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The minimum number of jiffies to keep an ARP entry in the cache. +This prevents ARP cache thrashing if there is more than one potential +mapping (generally due to network misconfiguration). +Defaults to 1 second. +.TP +.IR mcast_solicit " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of attempts to resolve an address by +multicast/broadcast before marking the entry as unreachable. +Defaults to 3. +.TP +.IR proxy_delay " (since Linux 2.2)" +.\" Precisely: 2.1.79 +When an ARP request for a known proxy-ARP address is received, delay up to +.I proxy_delay +jiffies before replying. +This is used to prevent network flooding in some cases. +Defaults to 0.8 seconds. +.TP +.IR proxy_qlen " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of packets which may be queued to proxy-ARP addresses. +Defaults to 64. +.TP +.IR retrans_time " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The number of jiffies to delay before retransmitting a request. +Defaults to 1 second. +This file is now obsolete in favor of +.IR retrans_time_ms . +.TP +.IR retrans_time_ms " (since Linux 2.6.12)" +The number of milliseconds to delay before retransmitting a request. +Defaults to 1000 milliseconds. +.TP +.IR ucast_solicit " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of attempts to send unicast probes before asking +the ARP daemon (see +.IR app_solicit ). +Defaults to 3. +.TP +.IR unres_qlen " (since Linux 2.2)" +.\" Precisely: 2.1.79 +The maximum number of packets which may be queued for each unresolved +address by other network layers. +Defaults to 3. +.SH VERSIONS +The +.I struct arpreq +changed in Linux 2.0 to include the +.I arp_dev +member and the ioctl numbers changed at the same time. +Support for the old ioctls was dropped in Linux 2.2. +.P +Support for proxy arp entries for networks (netmask not equal 0xffffffff) +was dropped in Linux 2.2. +It is replaced by automatic proxy arp setup by +the kernel for all reachable hosts on other interfaces (when +forwarding and proxy arp is enabled for the interface). +.P +The +.I neigh/* +interfaces did not exist before Linux 2.2. +.SH BUGS +Some timer settings are specified in jiffies, which is architecture- +and kernel version-dependent; see +.BR time (7). +.P +There is no way to signal positive feedback from user space. +This means connection-oriented protocols implemented in user space +will generate excessive ARP traffic, because ndisc will regularly +reprobe the MAC address. +The same problem applies for some kernel protocols (e.g., NFS over UDP). +.P +This man page mashes together functionality that is IPv4-specific +with functionality that is shared between IPv4 and IPv6. +.SH SEE ALSO +.BR capabilities (7), +.BR ip (7), +.BR arpd (8) +.P +RFC\ 826 for a description of ARP. +RFC\ 2461 for a description of IPv6 neighbor discovery and the base +algorithms used. +Linux 2.2+ IPv4 ARP uses the IPv6 algorithms when applicable. diff --git a/man/man7/ascii.7 b/man/man7/ascii.7 new file mode 100644 index 0000000..420bcfc --- /dev/null +++ b/man/man7/ascii.7 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Created 1993-04-02 by Michael Haardt (michael@moria.de) +.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) +.\" Modified 1994-05-15 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" Modified 1994-11-22 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" Modified 1995-07-11 by Daniel Quinlan (quinlan@yggdrasil.com) +.\" Modified 1996-12-18 by Michael Haardt and aeb +.\" Modified 1999-05-31 by Dimitri Papadopoulos (dpo@club-internet.fr) +.\" Modified 1999-08-08 by Michael Haardt (michael@moria.de) +.\" Modified 2004-04-01 by aeb +.\" +.TH ascii 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ascii \- ASCII character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +ASCII is the American Standard Code for Information Interchange. +It is a 7-bit code. +Many 8-bit codes (e.g., ISO/IEC\~8859-1) contain ASCII as their lower half. +The international counterpart of ASCII is known as ISO/IEC\~646-IRV. +.P +The following table contains the 128 ASCII characters. +.P +C program \f(CW\[aq]\eX\[aq]\fP escapes are noted. +.P +.EX +.TS +l l l l | l l l l. +Oct Dec Hex Char Oct Dec Hex Char +_ +000 0 00 NUL \[aq]\e0\[aq] (null character) 100 64 40 @ +001 1 01 SOH (start of heading) 101 65 41 A +002 2 02 STX (start of text) 102 66 42 B +003 3 03 ETX (end of text) 103 67 43 C +004 4 04 EOT (end of transmission) 104 68 44 D +005 5 05 ENQ (enquiry) 105 69 45 E +006 6 06 ACK (acknowledge) 106 70 46 F +007 7 07 BEL \[aq]\ea\[aq] (bell) 107 71 47 G +010 8 08 BS \[aq]\eb\[aq] (backspace) 110 72 48 H +011 9 09 HT \[aq]\et\[aq] (horizontal tab) 111 73 49 I +012 10 0A LF \[aq]\en\[aq] (new line) 112 74 4A J +013 11 0B VT \[aq]\ev\[aq] (vertical tab) 113 75 4B K +014 12 0C FF \[aq]\ef\[aq] (form feed) 114 76 4C L +015 13 0D CR \[aq]\er\[aq] (carriage ret) 115 77 4D M +016 14 0E SO (shift out) 116 78 4E N +017 15 0F SI (shift in) 117 79 4F O +020 16 10 DLE (data link escape) 120 80 50 P +021 17 11 DC1 (device control 1) 121 81 51 Q +022 18 12 DC2 (device control 2) 122 82 52 R +023 19 13 DC3 (device control 3) 123 83 53 S +024 20 14 DC4 (device control 4) 124 84 54 T +025 21 15 NAK (negative ack.) 125 85 55 U +026 22 16 SYN (synchronous idle) 126 86 56 V +027 23 17 ETB (end of trans. blk) 127 87 57 W +030 24 18 CAN (cancel) 130 88 58 X +031 25 19 EM (end of medium) 131 89 59 Y +032 26 1A SUB (substitute) 132 90 5A Z +033 27 1B ESC (escape) 133 91 5B [ +034 28 1C FS (file separator) 134 92 5C \e \[aq]\e\e\[aq] +035 29 1D GS (group separator) 135 93 5D ] +036 30 1E RS (record separator) 136 94 5E \[ha] +037 31 1F US (unit separator) 137 95 5F \&_ +040 32 20 SPACE 140 96 60 \` +041 33 21 ! 141 97 61 a +042 34 22 " 142 98 62 b +043 35 23 # 143 99 63 c +044 36 24 $ 144 100 64 d +045 37 25 % 145 101 65 e +046 38 26 & 146 102 66 f +047 39 27 \[aq] 147 103 67 g +050 40 28 ( 150 104 68 h +051 41 29 ) 151 105 69 i +052 42 2A * 152 106 6A j +053 43 2B + 153 107 6B k +054 44 2C , 154 108 6C l +055 45 2D \- 155 109 6D m +056 46 2E . 156 110 6E n +057 47 2F / 157 111 6F o +060 48 30 0 160 112 70 p +061 49 31 1 161 113 71 q +062 50 32 2 162 114 72 r +063 51 33 3 163 115 73 s +064 52 34 4 164 116 74 t +065 53 35 5 165 117 75 u +066 54 36 6 166 118 76 v +067 55 37 7 167 119 77 w +070 56 38 8 170 120 78 x +071 57 39 9 171 121 79 y +072 58 3A : 172 122 7A z +073 59 3B ; 173 123 7B { +074 60 3C < 174 124 7C | +075 61 3D = 175 125 7D } +076 62 3E > 176 126 7E \[ti] +077 63 3F ? 177 127 7F DEL +.TE +.EE +.SS Tables +For convenience, below are more compact tables in hex and decimal. +.P +.EX + 2 3 4 5 6 7 30 40 50 60 70 80 90 100 110 120 + ------------- --------------------------------- +0: 0 @ P \` p 0: ( 2 < F P Z d n x +1: ! 1 A Q a q 1: ) 3 = G Q [ e o y +2: " 2 B R b r 2: * 4 > H R \e f p z +3: # 3 C S c s 3: ! + 5 ? I S ] g q { +4: $ 4 D T d t 4: " , 6 @ J T \[ha] h r | +5: % 5 E U e u 5: # \- 7 A K U _ i s } +6: & 6 F V f v 6: $ . 8 B L V \` j t \[ti] +7: \[aq] 7 G W g w 7: % / 9 C M W a k u DEL +8: ( 8 H X h x 8: & 0 : D N X b l v +9: ) 9 I Y i y 9: \[aq] 1 ; E O Y c m w +A: * : J Z j z +B: + ; K [ k { +C: , < L \e l | +D: \- = M ] m } +E: . > N \[ha] n \[ti] +F: / ? O _ o DEL +.EE +.SH NOTES +.SS History +/etc/ascii (VII) appears in the UNIX Programmer's Manual. +.P +On older terminals, the underscore code is displayed as a left arrow, +called backarrow, the caret is displayed as an up-arrow and the vertical +bar has a hole in the middle. +.P +Uppercase and lowercase characters differ by just one bit and the +ASCII character 2 differs from the double quote by just one bit, too. +That made it much easier to encode characters mechanically or with a +non-microcontroller-based electronic keyboard and that pairing was found +on old teletypes. +.P +The ASCII standard was published by the United States of America +Standards Institute (USASI) in 1968. +.\" +.\" ASA was the American Standards Association and X3 was an ASA sectional +.\" committee on computers and data processing. Its name changed to +.\" American National Standards Committee X3 (ANSC-X3) and now it is known +.\" as Accredited Standards Committee X3 (ASC X3). It is accredited by ANSI +.\" and administered by ITI. The subcommittee X3.2 worked on coded +.\" character sets; the task group working on ASCII appears to have been +.\" designated X3.2.4. In 1966, ASA became the United States of America +.\" Standards Institute (USASI) and published ASCII in 1968. It became the +.\" American National Standards Institute (ANSI) in 1969 and is the +.\" U.S. member body of ISO; private and nonprofit. +.\" +.SH SEE ALSO +.BR charsets (7), +.BR iso_8859\-1 (7), +.BR iso_8859\-2 (7), +.BR iso_8859\-3 (7), +.BR iso_8859\-4 (7), +.BR iso_8859\-5 (7), +.BR iso_8859\-6 (7), +.BR iso_8859\-7 (7), +.BR iso_8859\-8 (7), +.BR iso_8859\-9 (7), +.BR iso_8859\-10 (7), +.BR iso_8859\-11 (7), +.BR iso_8859\-13 (7), +.BR iso_8859\-14 (7), +.BR iso_8859\-15 (7), +.BR iso_8859\-16 (7), +.BR utf\-8 (7) diff --git a/man/man7/attributes.7 b/man/man7/attributes.7 new file mode 100644 index 0000000..9e734e4 --- /dev/null +++ b/man/man7/attributes.7 @@ -0,0 +1,865 @@ +.\" Copyright (c) 2014, Red Hat, Inc +.\" Written by Alexandre Oliva +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH attributes 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +attributes \- POSIX safety concepts +.SH DESCRIPTION +.\" +.\" +.IR Note : +the text of this man page is based on the material taken from +the "POSIX Safety Concepts" section of the GNU C Library manual. +Further details on the topics described here can be found in that +manual. +.P +Various function manual pages include a section ATTRIBUTES +that describes the safety of calling the function in various contexts. +This section annotates functions with the following safety markings: +.TP +.I MT-Safe +.I MT-Safe +or +Thread-Safe functions are safe to call in the presence +of other threads. +MT, in MT-Safe, stands for Multi Thread. +.IP +Being MT-Safe does not imply a function is atomic, nor that it uses any +of the memory synchronization mechanisms POSIX exposes to users. +It is even possible that calling MT-Safe functions in sequence +does not yield an MT-Safe combination. +For example, having a thread call two MT-Safe +functions one right after the other does not guarantee behavior +equivalent to atomic execution of a combination of both functions, +since concurrent calls in other threads may interfere in a destructive way. +.IP +Whole-program optimizations that could inline functions across library +interfaces may expose unsafe reordering, and so performing inlining +across the GNU C Library interface is not recommended. +The documented +MT-Safety status is not guaranteed under whole-program optimization. +However, functions defined in user-visible headers are designed to be +safe for inlining. +.\" .TP +.\" .I AS-Safe +.\" .I AS-Safe +.\" or Async-Signal-Safe functions are safe to call from +.\" asynchronous signal handlers. +.\" AS, in AS-Safe, stands for Asynchronous Signal. +.\" +.\" Many functions that are AS-Safe may set +.\" .IR errno , +.\" or modify the floating-point environment, +.\" because their doing so does not make them +.\" unsuitable for use in signal handlers. +.\" However, programs could misbehave should asynchronous signal handlers +.\" modify this thread-local state, +.\" and the signal handling machinery cannot be counted on to +.\" preserve it. +.\" Therefore, signal handlers that call functions that may set +.\" .I errno +.\" or modify the floating-point environment +.\" .I must +.\" save their original values, and restore them before returning. +.\" .TP +.\" .I AC-Safe +.\" .I AC-Safe +.\" or Async-Cancel-Safe functions are safe to call when +.\" asynchronous cancelation is enabled. +.\" AC in AC-Safe stands for Asynchronous Cancelation. +.\" +.\" The POSIX standard defines only three functions to be AC-Safe, namely +.\" .BR pthread_cancel (3), +.\" .BR pthread_setcancelstate (3), +.\" and +.\" .BR pthread_setcanceltype (3). +.\" At present the GNU C Library provides no +.\" guarantees beyond these three functions, +.\" but does document which functions are presently AC-Safe. +.\" This documentation is provided for use +.\" by the GNU C Library developers. +.\" +.\" Just like signal handlers, cancelation cleanup routines must configure +.\" the floating point environment they require. +.\" The routines cannot assume a floating point environment, +.\" particularly when asynchronous cancelation is enabled. +.\" If the configuration of the floating point +.\" environment cannot be performed atomically then it is also possible that +.\" the environment encountered is internally inconsistent. +.TP +.I MT-Unsafe \" ", " AS-Unsafe ", " AC-Unsafe +.I MT-Unsafe \" ", " AS-Unsafe ", " AC-Unsafe +functions are not safe to call in a multithreaded programs. +.\" functions are not +.\" safe to call within the safety contexts described above. +.\" Calling them +.\" within such contexts invokes undefined behavior. +.\" +.\" Functions not explicitly documented as safe in a safety context should +.\" be regarded as Unsafe. +.\" .TP +.\" .I Preliminary +.\" .I Preliminary +.\" safety properties are documented, indicating these +.\" properties may +.\" .I not +.\" be counted on in future releases of +.\" the GNU C Library. +.\" +.\" Such preliminary properties are the result of an assessment of the +.\" properties of our current implementation, +.\" rather than of what is mandated and permitted +.\" by current and future standards. +.\" +.\" Although we strive to abide by the standards, in some cases our +.\" implementation is safe even when the standard does not demand safety, +.\" and in other cases our implementation does not meet the standard safety +.\" requirements. +.\" The latter are most likely bugs; the former, when marked +.\" as +.\" .IR Preliminary , +.\" should not be counted on: future standards may +.\" require changes that are not compatible with the additional safety +.\" properties afforded by the current implementation. +.\" +.\" Furthermore, +.\" the POSIX standard does not offer a detailed definition of safety. +.\" We assume that, by "safe to call", POSIX means that, +.\" as long as the program does not invoke undefined behavior, +.\" the "safe to call" function behaves as specified, +.\" and does not cause other functions to deviate from their specified behavior. +.\" We have chosen to use its loose +.\" definitions of safety, not because they are the best definitions to use, +.\" but because choosing them harmonizes this manual with POSIX. +.\" +.\" Please keep in mind that these are preliminary definitions and annotations, +.\" and certain aspects of the definitions are still under +.\" discussion and might be subject to clarification or change. +.\" +.\" Over time, +.\" we envision evolving the preliminary safety notes into stable commitments, +.\" as stable as those of our interfaces. +.\" As we do, we will remove the +.\" .I Preliminary +.\" keyword from safety notes. +.\" As long as the keyword remains, however, +.\" they are not to be regarded as a promise of future behavior. +.P +Other keywords that appear in safety notes are defined in subsequent sections. +.\" +.\" +.\" .SS Unsafe features +.\" Functions that are unsafe to call in certain contexts are annotated with +.\" keywords that document their features that make them unsafe to call. +.\" AS-Unsafe features in this section indicate the functions are never safe +.\" to call when asynchronous signals are enabled. +.\" AC-Unsafe features +.\" indicate they are never safe to call when asynchronous cancelation is +.\" .\" enabled. +.\" There are no MT-Unsafe marks in this section. +.\" .TP +.\" .\" .I code +.\" Functions marked with +.\" .I lock +.\" as an AS-Unsafe feature may be +.\" .\" interrupted by a signal while holding a non-recursive lock. +.\" If the signal handler calls another such function that takes the same lock, +.\" the result is a deadlock. +.\" +.\" Functions annotated with +.\" .I lock +.\" as an AC-Unsafe feature may, if canceled asynchronously, +.\" fail to release a lock that would have been released if their execution +.\" had not been interrupted by asynchronous thread cancelation. +.\" Once a lock is left taken, +.\" attempts to take that lock will block indefinitely. +.\" .TP +.\" .I corrupt +.\" Functions marked with +.\" .\" .I corrupt +.\" as an AS-Unsafe feature may corrupt +.\" data structures and misbehave when they interrupt, +.\" or are interrupted by, another such function. +.\" Unlike functions marked with +.\" .IR lock , +.\" these take recursive locks to avoid MT-Safety problems, +.\" but this is not enough to stop a signal handler from observing +.\" a partially-updated data structure. +.\" Further corruption may arise from the interrupted function's +.\" failure to notice updates made by signal handlers. +.\" +.\" Functions marked with +.\" .I corrupt +.\" as an AC-Unsafe feature may leave +.\" data structures in a corrupt, partially updated state. +.\" Subsequent uses of the data structure may misbehave. +.\" +.\" .\" A special case, probably not worth documenting separately, involves +.\" .\" reallocing, or even freeing pointers. Any case involving free could +.\" .\" be easily turned into an ac-safe leak by resetting the pointer before +.\" .\" releasing it; I don't think we have any case that calls for this sort +.\" .\" of fixing. Fixing the realloc cases would require a new interface: +.\" .\" instead of @code{ptr=realloc(ptr,size)} we'd have to introduce +.\" .\" @code{acsafe_realloc(&ptr,size)} that would modify ptr before +.\" .\" releasing the old memory. The ac-unsafe realloc could be implemented +.\" .\" in terms of an internal interface with this semantics (say +.\" .\" __acsafe_realloc), but since realloc can be overridden, the function +.\" .\" we call to implement realloc should not be this internal interface, +.\" .\" but another internal interface that calls __acsafe_realloc if realloc +.\" .\" was not overridden, and calls the overridden realloc with async +.\" .\" cancel disabled. --lxoliva +.\" .TP +.\" .I heap +.\" Functions marked with +.\" .I heap +.\" may call heap memory management functions from the +.\" .BR malloc (3)/ free (3) +.\" family of functions and are only as safe as those functions. +.\" This note is thus equivalent to: +.\" +.\" | AS-Unsafe lock | AC-Unsafe lock fd mem | +.\" .\" @sampsafety{@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} +.\" .\" +.\" .\" Check for cases that should have used plugin instead of or in +.\" .\" addition to this. Then, after rechecking gettext, adjust i18n if +.\" .\" needed. +.\" .TP +.\" .I dlopen +.\" Functions marked with +.\" .I dlopen +.\" use the dynamic loader to load +.\" shared libraries into the current execution image. +.\" This involves opening files, mapping them into memory, +.\" allocating additional memory, resolving symbols, +.\" applying relocations and more, +.\" all of this while holding internal dynamic loader locks. +.\" +.\" The locks are enough for these functions to be AS-Unsafe and AC-Unsafe, +.\" but other issues may arise. +.\" At present this is a placeholder for all +.\" potential safety issues raised by +.\" .BR dlopen (3). +.\" +.\" .\" dlopen runs init and fini sections of the module; does this mean +.\" .\" dlopen always implies plugin? +.\" .TP +.\" .I plugin +.\" Functions annotated with +.\" .I plugin +.\" may run code from plugins that +.\" may be external to the GNU C Library. +.\" Such plugin functions are assumed to be +.\" MT-Safe, AS-Unsafe and AC-Unsafe. +.\" Examples of such plugins are stack unwinding libraries, +.\" name service switch (NSS) and character set conversion (iconv) back-ends. +.\" +.\" Although the plugins mentioned as examples are all brought in by means +.\" of dlopen, the +.\" .I plugin +.\" keyword does not imply any direct +.\" involvement of the dynamic loader or the +.\" .I libdl +.\" interfaces, +.\" those are covered by +.\" .IR dlopen . +.\" For example, if one function loads a module and finds the addresses +.\" of some of its functions, +.\" while another just calls those already-resolved functions, +.\" the former will be marked with +.\" .IR dlopen , +.\" whereas the latter will get the +.\" .IR plugin . +.\" When a single function takes all of these actions, then it gets both marks. +.\" .TP +.\" .I i18n +.\" Functions marked with +.\" .I i18n +.\" may call internationalization +.\" functions of the +.\" .BR gettext (3) +.\" family and will be only as safe as those +.\" functions. +.\" This note is thus equivalent to: +.\" +.\" | MT-Safe env | AS-Unsafe corrupt heap dlopen | AC-Unsafe corrupt | +.\" +.\" .\" @sampsafety{@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascudlopen{}}@acunsafe{@acucorrupt{}}} +.\" .TP +.\" .I timer +.\" Functions marked with +.\" .I timer +.\" use the +.\" .BR alarm (3) +.\" function or +.\" similar to set a time-out for a system call or a long-running operation. +.\" In a multi-threaded program, there is a risk that the time-out signal +.\" will be delivered to a different thread, +.\" thus failing to interrupt the intended thread. +.\" Besides being MT-Unsafe, such functions are always +.\" AS-Unsafe, because calling them in signal handlers may interfere with +.\" timers set in the interrupted code, and AC-Unsafe, +.\" because there is no safe way to guarantee an earlier timer +.\" will be reset in case of asynchronous cancelation. +.\" +.\" +.SS Conditionally safe features +For some features that make functions unsafe to call in certain contexts, +there are known ways to avoid the safety problem other than +refraining from calling the function altogether. +The keywords that follow refer to such features, +and each of their definitions indicates +how the whole program needs to be constrained in order to remove the +safety problem indicated by the keyword. +Only when all the reasons that +make a function unsafe are observed and addressed, +by applying the documented constraints, +does the function become safe to call in a context. +.TP +.I init +Functions marked with +.I init +as an MT-Unsafe feature perform +MT-Unsafe initialization when they are first called. +.IP +Calling such a function at least once in single-threaded mode removes +this specific cause for the function to be regarded as MT-Unsafe. +If no other cause for that remains, +the function can then be safely called after other threads are started. +.\" +.\" Functions marked with +.\" .I init +.\" as an AS-Unsafe or AC-Unsafe feature use the GNU C Library internal +.\" .I libc_once +.\" machinery or similar to initialize internal data structures. +.\" +.\" If a signal handler interrupts such an initializer, +.\" and calls any function that also performs +.\" .I libc_once +.\" initialization, it will deadlock if the thread library has been loaded. +.\" +.\" Furthermore, if an initializer is partially complete before it is canceled +.\" or interrupted by a signal whose handler requires the same initialization, +.\" some or all of the initialization may be performed more than once, +.\" leaking resources or even resulting in corrupt internal data. +.\" +.\" Applications that need to call functions marked with +.\" .I init +.\" as an AS-Safety or AC-Unsafe feature should ensure +.\" the initialization is performed +.\" before configuring signal handlers or enabling cancelation, +.\" so that the AS-Safety and AC-Safety issues related with +.\" .I libc_once +.\" do not arise. +.\" +.\" .\" We may have to extend the annotations to cover conditions in which +.\" .\" initialization may or may not occur, since an initial call in a safe +.\" .\" context is no use if the initialization doesn't take place at that +.\" .\" time: it doesn't remove the risk for later calls. +.TP +.I race +Functions annotated with +.I race +as an MT-Safety issue operate on +objects in ways that may cause data races or similar forms of +destructive interference out of concurrent execution. +In some cases, +the objects are passed to the functions by users; +in others, they are used by the functions to return values to users; +in others, they are not even exposed to users. +.\" +.\" We consider access to objects passed as (indirect) arguments to +.\" functions to be data race free. +.\" The assurance of data race free objects +.\" is the caller's responsibility. +.\" We will not mark a function as MT-Unsafe or AS-Unsafe +.\" if it misbehaves when users fail to take the measures required by +.\" POSIX to avoid data races when dealing with such objects. +.\" As a general rule, if a function is documented as reading from +.\" an object passed (by reference) to it, or modifying it, +.\" users ought to use memory synchronization primitives +.\" to avoid data races just as they would should they perform +.\" the accesses themselves rather than by calling the library function. +.\" Standard I/O +.\" .RI ( "FILE *" ) +.\" streams are the exception to the general rule, +.\" in that POSIX mandates the library to guard against data races +.\" in many functions that manipulate objects of this specific opaque type. +.\" We regard this as a convenience provided to users, +.\" rather than as a general requirement whose expectations +.\" should extend to other types. +.\" +.\" In order to remind users that guarding certain arguments is their +.\" responsibility, we will annotate functions that take objects of certain +.\" types as arguments. +.\" We draw the line for objects passed by users as follows: +.\" objects whose types are exposed to users, +.\" and that users are expected to access directly, +.\" such as memory buffers, strings, +.\" and various user-visible structured types, do +.\" .I not +.\" give reason for functions to be annotated with +.\" .IR race . +.\" It would be noisy and redundant with the general requirement, +.\" and not many would be surprised by the library's lack of internal +.\" guards when accessing objects that can be accessed directly by users. +.\" +.\" As for objects that are opaque or opaque-like, +.\" in that they are to be manipulated only by passing them +.\" to library functions (e.g., +.\" .IR FILE , +.\" .IR DIR , +.\" .IR obstack , +.\" .IR iconv_t ), +.\" there might be additional expectations as to internal coordination +.\" of access by the library. +.\" We will annotate, with +.\" .I race +.\" followed by a colon and the argument name, +.\" functions that take such objects but that do not take +.\" care of synchronizing access to them by default. +.\" For example, +.\" .I FILE +.\" stream +.\" .I unlocked +.\" functions +.\" .RB ( unlocked_stdio (3)) +.\" will be annotated, +.\" but those that perform implicit locking on +.\" .I FILE +.\" streams by default will not, +.\" even though the implicit locking may be disabled on a per-stream basis. +.\" +.\" In either case, we will not regard as MT-Unsafe functions that may +.\" access user-supplied objects in unsafe ways should users fail to ensure +.\" the accesses are well defined. +.\" The notion prevails that users are expected to safeguard against +.\" data races any user-supplied objects that the library accesses +.\" on their behalf. +.\" +.\" .\" The above describes @mtsrace; @mtasurace is described below. +.\" +.\" This user responsibility does not apply, however, +.\" to objects controlled by the library itself, +.\" such as internal objects and static buffers used +.\" to return values from certain calls. +.\" When the library doesn't guard them against concurrent uses, +.\" these cases are regarded as MT-Unsafe and AS-Unsafe (although the +.\" .I race +.\" mark under AS-Unsafe will be omitted +.\" as redundant with the one under MT-Unsafe). +.\" As in the case of user-exposed objects, +.\" the mark may be followed by a colon and an identifier. +.\" The identifier groups all functions that operate on a +.\" certain unguarded object; users may avoid the MT-Safety issues related +.\" with unguarded concurrent access to such internal objects by creating a +.\" non-recursive mutex related with the identifier, +.\" and always holding the mutex when calling any function marked +.\" as racy on that identifier, +.\" as they would have to should the identifier be +.\" an object under user control. +.\" The non-recursive mutex avoids the MT-Safety issue, +.\" but it trades one AS-Safety issue for another, +.\" so use in asynchronous signals remains undefined. +.\" +.\" When the identifier relates to a static buffer used to hold return values, +.\" the mutex must be held for as long as the buffer remains in use +.\" by the caller. +.\" Many functions that return pointers to static buffers offer reentrant +.\" variants that store return values in caller-supplied buffers instead. +.\" In some cases, such as +.\" .BR tmpname (3), +.\" the variant is chosen not by calling an alternate entry point, +.\" but by passing a non-null pointer to the buffer in which the +.\" returned values are to be stored. +.\" These variants are generally preferable in multi-threaded programs, +.\" although some of them are not MT-Safe because of other internal buffers, +.\" also documented with +.\" .I race +.\" notes. +.TP +.I const +Functions marked with +.I const +as an MT-Safety issue non-atomically +modify internal objects that are better regarded as constant, +because a substantial portion of the GNU C Library accesses them without +synchronization. +Unlike +.IR race , +which causes both readers and +writers of internal objects to be regarded as MT-Unsafe,\" and AS-Unsafe, +this mark is applied to writers only. +Writers remain\" equally +MT-Unsafe\" and AS-Unsafe +to call, +but the then-mandatory constness of objects they +modify enables readers to be regarded as MT-Safe\" and AS-Safe +(as long as no other reasons for them to be unsafe remain), +since the lack of synchronization is not a problem when the +objects are effectively constant. +.IP +The identifier that follows the +.I const +mark will appear by itself as a safety note in readers. +Programs that wish to work around this safety issue, +so as to call writers, may use a non-recursive +read-write lock +associated with the identifier, and guard +.I all +calls to functions marked with +.I const +followed by the identifier with a write lock, and +.I all +calls to functions marked with the identifier +by itself with a read lock. +.\" The non-recursive locking removes the MT-Safety problem, +.\" but it trades one AS-Safety problem for another, +.\" so use in asynchronous signals remains undefined. +.\" +.\" .\" But what if, instead of marking modifiers with const:id and readers +.\" .\" with just id, we marked writers with race:id and readers with ro:id? +.\" .\" Instead of having to define each instance of 'id', we'd have a +.\" .\" general pattern governing all such 'id's, wherein race:id would +.\" .\" suggest the need for an exclusive/write lock to make the function +.\" .\" safe, whereas ro:id would indicate 'id' is expected to be read-only, +.\" .\" but if any modifiers are called (while holding an exclusive lock), +.\" .\" then ro:id-marked functions ought to be guarded with a read lock for +.\" .\" safe operation. ro:env or ro:locale, for example, seems to convey +.\" .\" more clearly the expectations and the meaning, than just env or +.\" .\" locale. +.TP +.I sig +Functions marked with +.I sig +as a MT-Safety issue +.\" (that implies an identical AS-Safety issue, omitted for brevity) +may temporarily install a signal handler for internal purposes, +which may interfere with other uses of the signal, +identified after a colon. +.IP +This safety problem can be worked around by ensuring that no other uses +of the signal will take place for the duration of the call. +Holding a non-recursive mutex while calling all functions that use the same +temporary signal; +blocking that signal before the call and resetting its +handler afterwards is recommended. +.\" +.\" There is no safe way to guarantee the original signal handler is +.\" restored in case of asynchronous cancelation, +.\" therefore so-marked functions are also AC-Unsafe. +.\" +.\" .\" fixme: at least deferred cancelation should get it right, and would +.\" .\" obviate the restoring bit below, and the qualifier above. +.\" +.\" Besides the measures recommended to work around the +.\" MT-Safety and AS-Safety problem, +.\" in order to avert the cancelation problem, +.\" disabling asynchronous cancelation +.\" .I and +.\" installing a cleanup handler to restore the signal to the desired state +.\" and to release the mutex are recommended. +.TP +.I term +Functions marked with +.I term +as an MT-Safety issue may change the +terminal settings in the recommended way, namely: call +.BR tcgetattr (3), +modify some flags, and then call +.BR tcsetattr (3), +this creates a window in which changes made by other threads are lost. +Thus, functions marked with +.I term +are MT-Unsafe. +.\" The same window enables changes made by asynchronous signals to be lost. +.\" These functions are also AS-Unsafe, +.\" but the corresponding mark is omitted as redundant. +.IP +It is thus advisable for applications using the terminal to avoid +concurrent and reentrant interactions with it, +by not using it in signal handlers or blocking signals that might use it, +and holding a lock while calling these functions and interacting +with the terminal. +This lock should also be used for mutual exclusion with +functions marked with +.IR race:tcattr(fd) , +where +.I fd +is a file descriptor for the controlling terminal. +The caller may use a single mutex for simplicity, +or use one mutex per terminal, +even if referenced by different file descriptors. +.\" +.\" Functions marked with +.\" .I term +.\" as an AC-Safety issue are supposed to +.\" restore terminal settings to their original state, +.\" after temporarily changing them, but they may fail to do so if canceled. +.\" +.\" .\" fixme: at least deferred cancelation should get it right, and would +.\" .\" obviate the restoring bit below, and the qualifier above. +.\" +.\" Besides the measures recommended to work around the +.\" MT-Safety and AS-Safety problem, +.\" in order to avert the cancelation problem, +.\" disabling asynchronous cancelation +.\" .I and +.\" installing a cleanup handler to +.\" restore the terminal settings to the original state and to release the +.\" mutex are recommended. +.\" +.\" +.SS Other safety remarks +Additional keywords may be attached to functions, +indicating features that do not make a function unsafe to call, +but that may need to be taken into account in certain classes of programs: +.TP +.I locale +Functions annotated with +.I locale +as an MT-Safety issue read from +the locale object without any form of synchronization. +Functions +annotated with +.I locale +called concurrently with locale changes may +behave in ways that do not correspond to any of the locales active +during their execution, but an unpredictable mix thereof. +.IP +We do not mark these functions as MT-Unsafe,\" or AS-Unsafe, +however, +because functions that modify the locale object are marked with +.I const:locale +and regarded as unsafe. +Being unsafe, the latter are not to be called when multiple threads +are running or asynchronous signals are enabled, +and so the locale can be considered effectively constant +in these contexts, +which makes the former safe. +.\" Should the locking strategy suggested under @code{const} be used, +.\" failure to guard locale uses is not as fatal as data races in +.\" general: unguarded uses will @emph{not} follow dangling pointers or +.\" access uninitialized, unmapped or recycled memory. Each access will +.\" read from a consistent locale object that is or was active at some +.\" point during its execution. Without synchronization, however, it +.\" cannot even be assumed that, after a change in locale, earlier +.\" locales will no longer be used, even after the newly-chosen one is +.\" used in the thread. Nevertheless, even though unguarded reads from +.\" the locale will not violate type safety, functions that access the +.\" locale multiple times may invoke all sorts of undefined behavior +.\" because of the unexpected locale changes. +.TP +.I env +Functions marked with +.I env +as an MT-Safety issue access the +environment with +.BR getenv (3) +or similar, without any guards to ensure +safety in the presence of concurrent modifications. +.IP +We do not mark these functions as MT-Unsafe,\" or AS-Unsafe, +however, +because functions that modify the environment are all marked with +.I const:env +and regarded as unsafe. +Being unsafe, the latter are not to be called when multiple threads +are running or asynchronous signals are enabled, +and so the environment can be considered +effectively constant in these contexts, +which makes the former safe. +.TP +.I hostid +The function marked with +.I hostid +as an MT-Safety issue reads from the system-wide data structures that +hold the "host ID" of the machine. +These data structures cannot generally be modified atomically. +Since it is expected that the "host ID" will not normally change, +the function that reads from it +.RB ( gethostid (3)) +is regarded as safe, +whereas the function that modifies it +.RB ( sethostid (3)) +is marked with +.IR const:hostid , +indicating it may require special care if it is to be called. +In this specific case, +the special care amounts to system-wide +(not merely intra-process) coordination. +.TP +.I sigintr +Functions marked with +.I sigintr +as an MT-Safety issue access the +GNU C Library +.I _sigintr +internal data structure without any guards to ensure +safety in the presence of concurrent modifications. +.IP +We do not mark these functions as MT-Unsafe,\" or AS-Unsafe, +however, +because functions that modify this data structure are all marked with +.I const:sigintr +and regarded as unsafe. +Being unsafe, +the latter are not to be called when multiple threads are +running or asynchronous signals are enabled, +and so the data structure can be considered +effectively constant in these contexts, +which makes the former safe. +.\" .TP +.\" .I fd +.\" Functions annotated with +.\" .I fd +.\" as an AC-Safety issue may leak file +.\" descriptors if asynchronous thread cancelation interrupts their +.\" execution. +.\" +.\" Functions that allocate or deallocate file descriptors will generally be +.\" marked as such. +.\" Even if they attempted to protect the file descriptor +.\" allocation and deallocation with cleanup regions, +.\" allocating a new descriptor and storing its number where the cleanup region +.\" could release it cannot be performed as a single atomic operation. +.\" Similarly, +.\" releasing the descriptor and taking it out of the data structure +.\" normally responsible for releasing it cannot be performed atomically. +.\" There will always be a window in which the descriptor cannot be released +.\" because it was not stored in the cleanup handler argument yet, +.\" or it was already taken out before releasing it. +.\" .\" It cannot be taken out after release: +.\" an open descriptor could mean either that the descriptor still +.\" has to be closed, +.\" or that it already did so but the descriptor was +.\" reallocated by another thread or signal handler. +.\" +.\" Such leaks could be internally avoided, with some performance penalty, +.\" by temporarily disabling asynchronous thread cancelation. +.\" However, +.\" since callers of allocation or deallocation functions would have to do +.\" this themselves, to avoid the same sort of leak in their own layer, +.\" it makes more sense for the library to assume they are taking care of it +.\" than to impose a performance penalty that is redundant when the problem +.\" is solved in upper layers, and insufficient when it is not. +.\" +.\" This remark by itself does not cause a function to be regarded as +.\" AC-Unsafe. +.\" However, cumulative effects of such leaks may pose a +.\" problem for some programs. +.\" If this is the case, +.\" suspending asynchronous cancelation for the duration of calls +.\" to such functions is recommended. +.\" .TP +.\" .I mem +.\" Functions annotated with +.\" .I mem +.\" as an AC-Safety issue may leak +.\" memory if asynchronous thread cancelation interrupts their execution. +.\" +.\" The problem is similar to that of file descriptors: there is no atomic +.\" interface to allocate memory and store its address in the argument to a +.\" cleanup handler, +.\" or to release it and remove its address from that argument, +.\" without at least temporarily disabling asynchronous cancelation, +.\" which these functions do not do. +.\" +.\" This remark does not by itself cause a function to be regarded as +.\" generally AC-Unsafe. +.\" However, cumulative effects of such leaks may be +.\" severe enough for some programs that disabling asynchronous cancelation +.\" for the duration of calls to such functions may be required. +.TP +.I cwd +Functions marked with +.I cwd +as an MT-Safety issue may temporarily +change the current working directory during their execution, +which may cause relative pathnames to be resolved in unexpected ways in +other threads or within asynchronous signal or cancelation handlers. +.IP +This is not enough of a reason to mark so-marked functions as MT-Unsafe, +.\" or AS-Unsafe, +but when this behavior is optional (e.g., +.BR nftw (3) +with +.BR FTW_CHDIR ), +avoiding the option may be a good alternative to +using full pathnames or file descriptor-relative (e.g., +.BR openat (2)) +system calls. +.\" .TP +.\" .I !posix +.\" This remark, as an MT-Safety, AS-Safety or AC-Safety +.\" note to a function, +.\" indicates the safety status of the function is known to differ +.\" from the specified status in the POSIX standard. +.\" For example, POSIX does not require a function to be Safe, +.\" but our implementation is, or vice-versa. +.\" +.\" For the time being, the absence of this remark does not imply the safety +.\" properties we documented are identical to those mandated by POSIX for +.\" the corresponding functions. +.TP +.I :identifier +Annotations may sometimes be followed by identifiers, +intended to group several functions that, for example, +access the data structures in an unsafe way, as in +.I race +and +.IR const , +or to provide more specific information, +such as naming a signal in a function marked with +.IR sig . +It is envisioned that it may be applied to +.I lock +and +.I corrupt +as well in the future. +.IP +In most cases, the identifier will name a set of functions, +but it may name global objects or function arguments, +or identifiable properties or logical components associated with them, +with a notation such as, for example, +.I :buf(arg) +to denote a buffer associated with the argument +.IR arg , +or +.I :tcattr(fd) +to denote the terminal attributes of a file descriptor +.IR fd . +.IP +The most common use for identifiers is to provide logical groups of +functions and arguments that need to be protected by the same +synchronization primitive in order to ensure safe operation in a given +context. +.TP +.I /condition +Some safety annotations may be conditional, +in that they only apply if a boolean expression involving arguments, +global variables or even the underlying kernel evaluates to true. +.\" Such conditions as +.\" .I /hurd +.\" or +.\" .I /!linux!bsd +.\" indicate the preceding marker only +.\" applies when the underlying kernel is the HURD, +.\" or when it is neither Linux nor a BSD kernel, respectively. +For example, +.I /!ps +and +.I /one_per_line +indicate the preceding marker only applies when argument +.I ps +is NULL, or global variable +.I one_per_line +is nonzero. +.IP +When all marks that render a function unsafe are +adorned with such conditions, +and none of the named conditions hold, +then the function can be regarded as safe. +.SH SEE ALSO +.BR pthreads (7), +.BR signal\-safety (7) diff --git a/man/man7/boot.7 b/man/man7/boot.7 new file mode 100644 index 0000000..ff77032 --- /dev/null +++ b/man/man7/boot.7 @@ -0,0 +1,230 @@ +.\" Written by Oron Peled . +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" I tried to be as much generic in the description as possible: +.\" - General boot sequence is applicable to almost any +.\" OS/Machine (DOS/PC, Linux/PC, Solaris/SPARC, CMS/S390) +.\" - kernel and init(1) is applicable to almost any UNIX/Linux +.\" - boot scripts are applicable to SYSV-R4 based UNIX/Linux +.\" +.\" Modified 2004-11-03 patch from Martin Schulze +.\" +.TH boot 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +boot \- System bootup process based on UNIX System V Release 4 +.SH DESCRIPTION +The \fBbootup process\fR (or "\fBboot sequence\fR") varies in details +among systems, but can be roughly divided into phases controlled by +the following components: +.IP (1) 5 +hardware +.IP (2) +operating system (OS) loader +.IP (3) +kernel +.IP (4) +root user-space process (\fIinit\fR and \fIinittab\fR) +.IP (5) +boot scripts +.P +Each of these is described below in more detail. +.SS Hardware +After power-on or hard reset, control is given +to a program stored in read-only memory (normally +PROM); for historical reasons involving the personal +computer, this program is often called "the \fBBIOS\fR". +.P +This program normally performs a basic self-test of the +machine and accesses nonvolatile memory to read +further parameters. +This memory in the PC is +battery-backed CMOS memory, so most people +refer to it as "the \fBCMOS\fR"; outside +of the PC world, it is usually called "the \fBNVRAM\fR" +(nonvolatile RAM). +.P +The parameters stored in the NVRAM vary among +systems, but as a minimum, they should specify +which device can supply an OS loader, or at least which +devices may be probed for one; such a device is known as "the +\fBboot device\fR". +The hardware boot stage loads the OS loader from a fixed position on +the boot device, and then transfers control to it. +.TP +Note: +The device from which the OS loader is read may be attached via a network, +in which case the details of booting are further specified by protocols such as +DHCP, TFTP, PXE, Etherboot, etc. +.SS OS loader +The main job of the OS loader is to locate the kernel +on some device, load it, and run it. +Most OS loaders allow +interactive use, in order to enable specification of an alternative +kernel (maybe a backup in case the one last compiled +isn't functioning) and to pass optional parameters +to the kernel. +.P +In a traditional PC, the OS loader is located in the initial 512-byte block +of the boot device; this block is known as "the \fBMBR\fR" +(Master Boot Record). +.P +In most systems, the OS loader is very +limited due to various constraints. +Even on non-PC systems, +there are some limitations on the size and complexity +of this loader, but the size limitation of the PC MBR +(512 bytes, including the partition table) makes it +almost impossible to squeeze much functionality into it. +.P +Therefore, most systems split the role of loading the OS between +a primary OS loader and a secondary OS loader; this secondary +OS loader may be located within a larger portion of persistent +storage, such as a disk partition. +.P +In Linux, the OS loader is often +.BR grub (8) +(an alternative is +.BR lilo (8)). +.SS Kernel +When the kernel is loaded, it initializes various components of +the computer and operating system; each portion of software +responsible for such a task is usually consider "a \fBdriver\fR" for +the applicable component. +The kernel starts the virtual memory +swapper (it is a kernel process, called "kswapd" in a modern Linux +kernel), and mounts some filesystem at the root path, +.IR / . +.P +Some of the parameters that may be passed to the kernel +relate to these activities (for example, the default root filesystem +can be overridden); for further information +on Linux kernel parameters, read +.BR bootparam (7). +.P +Only then does the kernel create the initial userland +process, which is given the number 1 as its +.B PID +(process ID). +Traditionally, this process executes the +program +.IR /sbin/init , +to which are passed the parameters that haven't already been +handled by the kernel. +.SS Root user-space process +.TP +Note: +The following description applies to an OS based on UNIX System V Release 4. +However, a number of widely used systems have adopted a related but +fundamentally different approach known as +.BR systemd (1), +for which the bootup process is detailed in its associated +.BR bootup (7). +.P +When +.I /sbin/init +starts, it reads +.I /etc/inittab +for further instructions. +This file defines what should be run when the +.I /sbin/init +program is instructed to enter a particular run level, giving +the administrator an easy way to establish an environment +for some usage; each run level is associated with a set of services +(for example, run level +.B S +is single-user mode, +and run level +.B 2 +entails running most network services). +.P +The administrator may change the current run level via +.BR init (1), +and query the current run level via +.BR runlevel (8). +.P +However, since it is not convenient to manage individual services +by editing this file, +.I /etc/inittab +only bootstraps a set of scripts +that actually start/stop the individual services. +.SS Boot scripts +.TP +Note: +The following description applies to an OS based on UNIX System V Release 4. +However, a number of widely used systems (Slackware Linux, FreeBSD, OpenBSD) +have a somewhat different scheme for boot scripts. +.P +For each managed service (mail, nfs server, cron, etc.), there is +a single startup script located in a specific directory +.RI ( /etc/init.d +in most versions of Linux). +Each of these scripts accepts as a single argument +the word "start" (causing it to start the service) or the word +\&"stop" (causing it to stop the service). +The script may optionally +accept other "convenience" parameters (e.g., "restart" to stop and then +start, "status" to display the service status, etc.). +Running the script +without parameters displays the possible arguments. +.SS Sequencing directories +To make specific scripts start/stop at specific run levels and in a +specific order, there are \fIsequencing directories\fR, normally +of the form \fI/etc/rc[0\-6S].d\fR. +In each of these directories, +there are links (usually symbolic) to the scripts in the \fI/etc/init.d\fR +directory. +.P +A primary script (usually \fI/etc/rc\fR) is called from +.BR inittab (5); +this primary script calls each service's script via a link in the +relevant sequencing directory. +Each link whose name begins with \[aq]S\[aq] is called with +the argument "start" (thereby starting the service). +Each link whose name begins with \[aq]K\[aq] is called with +the argument "stop" (thereby stopping the service). +.P +To define the starting or stopping order within the same run level, +the name of a link contains an \fBorder-number\fR. +Also, for clarity, the name of a link usually +ends with the name of the service to which it refers. +For example, +the link \fI/etc/rc2.d/S80sendmail\fR starts the +.BR sendmail (8) +service on +run level 2. +This happens after \fI/etc/rc2.d/S12syslog\fR is run +but before \fI/etc/rc2.d/S90xfs\fR is run. +.P +To manage these links is to manage the boot order and run levels; +under many systems, there are tools to help with this task +(e.g., +.BR chkconfig (8)). +.SS Boot configuration +A program that provides a service is often called a "\fBdaemon\fR". +Usually, a daemon may receive various command-line options +and parameters. +To allow a system administrator to change these +inputs without editing an entire boot script, +some separate configuration file is used, and is located in a specific +directory where an associated boot script may find it +(\fI/etc/sysconfig\fR on older Red Hat systems). +.P +In older UNIX systems, such a file contained the actual command line +options for a daemon, but in modern Linux systems (and also +in HP-UX), it just contains shell variables. +A boot script in \fI/etc/init.d\fR reads and includes its configuration +file (that is, it "\fBsources\fR" its configuration file) and then uses +the variable values. +.SH FILES +.IR /etc/init.d/ , +.IR /etc/rc[S0\-6].d/ , +.I /etc/sysconfig/ +.SH SEE ALSO +.BR init (1), +.BR systemd (1), +.BR inittab (5), +.BR bootparam (7), +.BR bootup (7), +.BR runlevel (8), +.BR shutdown (8) diff --git a/man/man7/bootparam.7 b/man/man7/bootparam.7 new file mode 100644 index 0000000..aa44071 --- /dev/null +++ b/man/man7/bootparam.7 @@ -0,0 +1,664 @@ +.\" Copyright (c) 1995,1997 Paul Gortmaker and Andries Brouwer +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" This man page written 950814 by aeb, based on Paul Gortmaker's HOWTO +.\" (dated v1.0.1, 15/08/95). +.\" Major update, aeb, 970114. +.\" +.TH bootparam 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +bootparam \- introduction to boot time parameters of the Linux kernel +.SH DESCRIPTION +The Linux kernel accepts certain 'command-line options' or 'boot time +parameters' at the moment it is started. +In general, this is used to +supply the kernel with information about hardware parameters that +the kernel would not be able to determine on its own, or to avoid/override +the values that the kernel would otherwise detect. +.P +When the kernel is booted directly by the BIOS, +you have no opportunity to specify any parameters. +So, in order to take advantage of this possibility you have to +use a boot loader that is able to pass parameters, such as GRUB. +.SS The argument list +The kernel command line is parsed into a list of strings +(boot arguments) separated by spaces. +Most of the boot arguments have the form: +.P +.in +4n +.EX +name[=value_1][,value_2]...[,value_10] +.EE +.in +.P +where 'name' is a unique keyword that is used to identify what part of +the kernel the associated values (if any) are to be given to. +Note the limit of 10 is real, as the present code handles only 10 comma +separated parameters per keyword. +(However, you can reuse the same +keyword with up to an additional 10 parameters in unusually +complicated situations, assuming the setup function supports it.) +.P +Most of the sorting is coded in the kernel source file +.IR init/main.c . +First, the kernel +checks to see if the argument is any of the special arguments 'root=', +\&'nfsroot=', 'nfsaddrs=', 'ro', 'rw', 'debug', or 'init'. +The meaning of these special arguments is described below. +.P +Then it walks a list of setup functions +to see if the specified argument string (such as 'foo') has +been associated with a setup function ('foo_setup()') for a particular +device or part of the kernel. +If you passed the kernel the line +foo=3,4,5,6 then the kernel would search the bootsetups array to see +if 'foo' was registered. +If it was, then it would call the setup +function associated with 'foo' (foo_setup()) and hand it the arguments +3, 4, 5, and 6 as given on the kernel command line. +.P +Anything of the form 'foo=bar' that is not accepted as a setup function +as described above is then interpreted as an environment variable to +be set. +A (useless?) example would be to use 'TERM=vt100' as a boot +argument. +.P +Any remaining arguments that were not picked up by the kernel and were +not interpreted as environment variables are then passed onto PID 1, +which is usually the +.BR init (1) +program. +The most common argument that +is passed to the +.I init +process is the word 'single' which instructs it +to boot the computer in single user mode, and not launch all the usual +daemons. +Check the manual page for the version of +.BR init (1) +installed on +your system to see what arguments it accepts. +.SS General non-device-specific boot arguments +.TP +.B "'init=...'" +This sets the initial command to be executed by the kernel. +If this is not set, or cannot be found, the kernel will try +.IR /sbin/init , +then +.IR /etc/init , +then +.IR /bin/init , +then +.I /bin/sh +and panic if all of this fails. +.TP +.B "'nfsaddrs=...'" +This sets the NFS boot address to the given string. +This boot address is used in case of a net boot. +.TP +.B "'nfsroot=...'" +This sets the NFS root name to the given string. +If this string +does not begin with '/' or ',' or a digit, then it is prefixed by +\&'/tftpboot/'. +This root name is used in case of a net boot. +.TP +.B "'root=...'" +This argument tells the kernel what device is to be used as the root +filesystem while booting. +The default of this setting is determined +at compile time, and usually is the value of the root device of the +system that the kernel was built on. +To override this value, and +select the second floppy drive as the root device, one would +use 'root=/dev/fd1'. +.IP +The root device can be specified symbolically or numerically. +A symbolic specification has the form +.IR /dev/XXYN , +where XX designates +the device type (e.g., 'hd' for ST-506 compatible hard disk, with Y in +\&'a'\[en]'d'; 'sd' for SCSI compatible disk, with Y in 'a'\[en]'e'), +Y the driver letter or +number, and N the number (in decimal) of the partition on this device. +.IP +Note that this has nothing to do with the designation of these +devices on your filesystem. +The '/dev/' part is purely conventional. +.IP +The more awkward and less portable numeric specification of the above +possible root devices in major/minor format is also accepted. +(For example, +.I /dev/sda3 +is major 8, minor 3, so you could use 'root=0x803' as an +alternative.) +.TP +.B 'rootdelay=' +This parameter sets the delay (in seconds) to pause before attempting +to mount the root filesystem. +.TP +.B 'rootflags=...' +This parameter sets the mount option string for the root filesystem +(see also +.BR fstab (5)). +.TP +.B 'rootfstype=...' +The 'rootfstype' option tells the kernel to mount the root filesystem as +if it where of the type specified. +This can be useful (for example) to +mount an ext3 filesystem as ext2 and then remove the journal in the root +filesystem, in fact reverting its format from ext3 to ext2 without the +need to boot the box from alternate media. +.TP +.BR 'ro' " and " 'rw' +The 'ro' option tells the kernel to mount the root filesystem +as 'read-only' so that filesystem consistency check programs (fsck) +can do their work on a quiescent filesystem. +No processes can +write to files on the filesystem in question until it is 'remounted' +as read/write capable, for example, by 'mount \-w \-n \-o remount /'. +(See also +.BR mount (8).) +.IP +The 'rw' option tells the kernel to mount the root filesystem read/write. +This is the default. +.TP +.B "'resume=...'" +This tells the kernel the location of +the suspend-to-disk data that you want the machine to resume from +after hibernation. +Usually, it is the same as your swap partition or file. +Example: +.IP +.in +4n +.EX +resume=/dev/hda2 +.EE +.in +.TP +.B "'reserve=...'" +This is used to protect I/O port regions from probes. +The form of the command is: +.IP +.in +4n +.EX +.BI reserve= iobase,extent[,iobase,extent]... +.EE +.in +.IP +In some machines it may be necessary to prevent device drivers from +checking for devices (auto-probing) in a specific region. +This may be +because of hardware that reacts badly to the probing, or hardware +that would be mistakenly identified, or merely +hardware you don't want the kernel to initialize. +.IP +The reserve boot-time argument specifies an I/O port region that +shouldn't be probed. +A device driver will not probe a reserved region, +unless another boot argument explicitly specifies that it do so. +.IP +For example, the boot line +.IP +.in +4n +.EX +reserve=0x300,32 blah=0x300 +.EE +.in +.IP +keeps all device drivers except the driver for 'blah' from probing +0x300\-0x31f. +.TP +.B "'panic=N'" +By default, the kernel will not reboot after a panic, but this option +will cause a kernel reboot after N seconds (if N is greater than zero). +This panic timeout can also be set by +.IP +.in +4n +.EX +echo N > /proc/sys/kernel/panic +.EE +.in +.TP +.B "'reboot=[warm|cold][,[bios|hard]]'" +Since Linux 2.0.22, a reboot is by default a cold reboot. +One asks for the old default with 'reboot=warm'. +(A cold reboot may be required to reset certain hardware, +but might destroy not yet written data in a disk cache. +A warm reboot may be faster.) +By default, a reboot is hard, by asking the keyboard controller +to pulse the reset line low, but there is at least one type +of motherboard where that doesn't work. +The option 'reboot=bios' will +instead jump through the BIOS. +.TP +.BR 'nosmp' " and " 'maxcpus=N' +(Only when __SMP__ is defined.) +A command-line option of 'nosmp' or 'maxcpus=0' will disable SMP +activation entirely; an option 'maxcpus=N' limits the maximum number +of CPUs activated in SMP mode to N. +.SS Boot arguments for use by kernel developers +.TP +.B "'debug'" +Kernel messages are handed off to a daemon (e.g., +.BR klogd (8) +or similar) so that they may be logged to disk. +Messages with a priority above +.I console_loglevel +are also printed on the console. +(For a discussion of log levels, see +.BR syslog (2).) +By default, +.I console_loglevel +is set to log messages at levels higher than +.BR KERN_DEBUG . +This boot argument will cause the kernel to also +print messages logged at level +.BR KERN_DEBUG . +The console loglevel can also be set on a booted system via the +.I /proc/sys/kernel/printk +file (described in +.BR syslog (2)), +the +.BR syslog (2) +.B SYSLOG_ACTION_CONSOLE_LEVEL +operation, or +.BR dmesg (8). +.TP +.B "'profile=N'" +It is possible to enable a kernel profiling function, +if one wishes to find out where the kernel is spending its CPU cycles. +Profiling is enabled by setting the variable +.I prof_shift +to a nonzero value. +This is done either by specifying +.B CONFIG_PROFILE +at compile time, or by giving the 'profile=' option. +Now the value that +.I prof_shift +gets will be N, when given, or +.BR CONFIG_PROFILE_SHIFT , +when that is given, or 2, the default. +The significance of this variable is that it +gives the granularity of the profiling: each clock tick, if the +system was executing kernel code, a counter is incremented: +.IP +.in +4n +.EX +profile[address >> prof_shift]++; +.EE +.in +.IP +The raw profiling information can be read from +.IR /proc/profile . +Probably you'll want to use a tool such as readprofile.c to digest it. +Writing to +.I /proc/profile +will clear the counters. +.SS Boot arguments for ramdisk use +(Only if the kernel was compiled with +.BR CONFIG_BLK_DEV_RAM .) +In general it is a bad idea to use a ramdisk under Linux\[em]the +system will use available memory more efficiently itself. +But while booting, +it is often useful to load the floppy contents into a +ramdisk. +One might also have a system in which first +some modules (for filesystem or hardware) must be loaded +before the main disk can be accessed. +.IP +In Linux 1.3.48, ramdisk handling was changed drastically. +Earlier, the memory was allocated statically, and there was +a 'ramdisk=N' parameter to tell its size. +(This could also be set in the kernel image at compile time.) +These days ram disks use the buffer cache, and grow dynamically. +For a lot of information on the current ramdisk +setup, see the kernel source file +.I Documentation/blockdev/ramdisk.txt +.RI ( Documentation/ramdisk.txt +in older kernels). +.IP +There are four parameters, two boolean and two integral. +.TP +.B "'load_ramdisk=N'" +If N=1, do load a ramdisk. +If N=0, do not load a ramdisk. +(This is the default.) +.TP +.B "'prompt_ramdisk=N'" +If N=1, do prompt for insertion of the floppy. +(This is the default.) +If N=0, do not prompt. +(Thus, this parameter is never needed.) +.TP +.BR 'ramdisk_size=N' " or (obsolete) " 'ramdisk=N' +Set the maximal size of the ramdisk(s) to N kB. +The default is 4096 (4\ MB). +.TP +.B "'ramdisk_start=N'" +Sets the starting block number (the offset on the floppy where +the ramdisk starts) to N. +This is needed in case the ramdisk follows a kernel image. +.TP +.B "'noinitrd'" +(Only if the kernel was compiled with +.B CONFIG_BLK_DEV_RAM +and +.BR CONFIG_BLK_DEV_INITRD .) +These days it is possible to compile the kernel to use initrd. +When this feature is enabled, the boot process will load the kernel +and an initial ramdisk; then the kernel converts initrd into +a "normal" ramdisk, which is mounted read-write as root device; +then +.I /linuxrc +is executed; afterward the "real" root filesystem is mounted, +and the initrd filesystem is moved over to +.IR /initrd ; +finally +the usual boot sequence (e.g., invocation of +.IR /sbin/init ) +is performed. +.IP +For a detailed description of the initrd feature, see the kernel source file +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10). +.IP +The 'noinitrd' option tells the kernel that although it was compiled for +operation with initrd, it should not go through the above steps, but +leave the initrd data under +.IR /dev/initrd . +(This device can be used only once: the data is freed as soon as +the last process that used it has closed +.IR /dev/initrd .) +.SS Boot arguments for SCSI devices +General notation for this section: +.P +.I iobase +-- the first I/O port that the SCSI host occupies. +These are specified in hexadecimal notation, +and usually lie in the range from 0x200 to 0x3ff. +.P +.I irq +-- the hardware interrupt that the card is configured to use. +Valid values will be dependent on the card in question, but will +usually be 5, 7, 9, 10, 11, 12, and 15. +The other values are usually +used for common peripherals like IDE hard disks, floppies, serial +ports, and so on. +.P +.I scsi\-id +-- the ID that the host adapter uses to identify itself on the +SCSI bus. +Only some host adapters allow you to change this value, as +most have it permanently specified internally. +The usual default value +is 7, but the Seagate and Future Domain TMC-950 boards use 6. +.P +.I parity +-- whether the SCSI host adapter expects the attached devices +to supply a parity value with all information exchanges. +Specifying a one indicates parity checking is enabled, +and a zero disables parity checking. +Again, not all adapters will support selection of parity +behavior as a boot argument. +.TP +.B "'max_scsi_luns=...'" +A SCSI device can have a number of 'subdevices' contained within +itself. +The most common example is one of the new SCSI CD-ROMs that +handle more than one disk at a time. +Each CD is addressed as a +\&'Logical Unit Number' (LUN) of that particular device. +But most +devices, such as hard disks, tape drives, and such are only one device, +and will be assigned to LUN zero. +.IP +Some poorly designed SCSI devices cannot handle being probed for +LUNs not equal to zero. +Therefore, if the compile-time flag +.B CONFIG_SCSI_MULTI_LUN +is not set, newer kernels will by default probe only LUN zero. +.IP +To specify the number of probed LUNs at boot, one enters +\&'max_scsi_luns=n' as a boot arg, where n is a number between one and +eight. +To avoid problems as described above, one would use n=1 to +avoid upsetting such broken devices. +.TP +.B "SCSI tape configuration" +Some boot time configuration of the SCSI tape driver can be achieved +by using the following: +.IP +.in +4n +.EX +.BI st= buf_size[,write_threshold[,max_bufs]] +.EE +.in +.IP +The first two numbers are specified in units of kB. +The default +.I buf_size +is 32k\ B, and the maximum size that can be specified is a +ridiculous 16384\ kB. +The +.I write_threshold +is the value at which the buffer is committed to tape, with a +default value of 30\ kB. +The maximum number of buffers varies +with the number of drives detected, and has a default of two. +An example usage would be: +.IP +.in +4n +.EX +st=32,30,2 +.EE +.in +.IP +Full details can be found in the file +.I Documentation/scsi/st.txt +(or +.I drivers/scsi/README.st +for older kernels) in the Linux kernel source. +.SS Hard disks +.TP +.B "IDE Disk/CD-ROM Driver Parameters" +The IDE driver accepts a number of parameters, which range from disk +geometry specifications, to support for broken controller chips. +Drive-specific options are specified by using 'hdX=' with X in 'a'\[en]'h'. +.IP +Non-drive-specific options are specified with the prefix 'hd='. +Note that using a drive-specific prefix for a non-drive-specific option +will still work, and the option will just be applied as expected. +.IP +Also note that 'hd=' can be used to refer to the next unspecified +drive in the (a, ..., h) sequence. +For the following discussions, +the 'hd=' option will be cited for brevity. +See the file +.I Documentation/ide/ide.txt +(or +.I Documentation/ide.txt +.\" Linux 2.0, 2.2, 2.4 +in older kernels, or +.I drivers/block/README.ide +in ancient kernels) in the Linux kernel source for more details. +.TP +.B "The 'hd=cyls,heads,sects[,wpcom[,irq]]' options" +These options are used to specify the physical geometry of the disk. +Only the first three values are required. +The cylinder/head/sectors +values will be those used by fdisk. +The write precompensation value +is ignored for IDE disks. +The IRQ value specified will be the IRQ +used for the interface that the drive resides on, and is not really a +drive-specific parameter. +.TP +.B "The 'hd=serialize' option" +The dual IDE interface CMD-640 chip is broken as designed such that +when drives on the secondary interface are used at the same time as +drives on the primary interface, it will corrupt your data. +Using this +option tells the driver to make sure that both interfaces are never +used at the same time. +.TP +.B "The 'hd=noprobe' option" +Do not probe for this drive. +For example, +.IP +.in +4n +.EX +hdb=noprobe hdb=1166,7,17 +.EE +.in +.IP +would disable the probe, but still specify the drive geometry so +that it would be registered as a valid block device, and hence +usable. +.TP +.B "The 'hd=nowerr' option" +Some drives apparently have the +.B WRERR_STAT +bit stuck on permanently. +This enables a work-around for these broken devices. +.TP +.B "The 'hd=cdrom' option" +This tells the IDE driver that there is an ATAPI compatible CD-ROM +attached in place of a normal IDE hard disk. +In most cases the CD-ROM +is identified automatically, but if it isn't then this may help. +.TP +.B "Standard ST-506 Disk Driver Options ('hd=')" +The standard disk driver can accept geometry arguments for the disks +similar to the IDE driver. +Note however that it expects only three +values (C/H/S); any more or any less and it will silently ignore you. +Also, it accepts only 'hd=' as an argument, that is, 'hda=' +and so on are not valid here. +The format is as follows: +.IP +.in +4n +.EX +hd=cyls,heads,sects +.EE +.in +.IP +If there are two disks installed, the above is repeated with the +geometry parameters of the second disk. +.SS Ethernet devices +Different drivers make use of different parameters, but they all at +least share having an IRQ, an I/O port base value, and a name. +In its most generic form, it looks something like this: +.P +.in +4n +.EX +ether=irq,iobase[,param_1[,...param_8]],name +.EE +.in +.P +The first nonnumeric argument is taken as the name. +The param_n values (if applicable) usually have different meanings for each +different card/driver. +Typical param_n values are used to specify +things like shared memory address, interface selection, DMA channel +and the like. +.P +The most common use of this parameter is to force probing for a second +ethercard, as the default is to probe only for one. +This can be accomplished with a simple: +.P +.in +4n +.EX +ether=0,0,eth1 +.EE +.in +.P +Note that the values of zero for the IRQ and I/O base in the above +example tell the driver(s) to autoprobe. +.P +The Ethernet-HowTo has extensive documentation on using multiple +cards and on the card/driver-specific implementation +of the param_n values where used. +Interested readers should refer to +the section in that document on their particular card. +.SS The floppy disk driver +There are many floppy driver options, and they are all listed in +.I Documentation/blockdev/floppy.txt +(or +.I Documentation/floppy.txt +in older kernels, or +.I drivers/block/README.fd +for ancient kernels) in the Linux kernel source. +See that file for the details. +.SS The sound driver +The sound driver can also accept boot arguments to override the compiled-in +values. +This is not recommended, as it is rather complex. +It is described in the Linux kernel source file +.I Documentation/sound/oss/README.OSS +.RI ( drivers/sound/Readme.linux +in older kernel versions). +It accepts +a boot argument of the form: +.P +.in +4n +.EX +sound=device1[,device2[,device3...[,device10]]] +.EE +.in +.P +where each deviceN value is of the following format 0xTaaaId and the +bytes are used as follows: +.P +T \- device type: 1=FM, 2=SB, 3=PAS, 4=GUS, 5=MPU401, 6=SB16, +7=SB16-MPU401 +.P +aaa \- I/O address in hex. +.P +I \- interrupt line in hex (i.e., 10=a, 11=b, ...) +.P +d \- DMA channel. +.P +As you can see, it gets pretty messy, and you are better off to compile +in your own personal values as recommended. +Using a boot argument of +\&'sound=0' will disable the sound driver entirely. +.SS The line printer driver +.TP +.B "'lp='" +.br +Syntax: +.IP +.in +4n +.EX +lp=0 +lp=auto +lp=reset +lp=port[,port...] +.EE +.in +.IP +You can tell the printer driver what ports to use and what ports not +to use. +The latter comes in handy if you don't want the printer driver +to claim all available parallel ports, so that other drivers +(e.g., PLIP, PPA) can use them instead. +.IP +The format of the argument is multiple port names. +For example, +lp=none,parport0 would use the first parallel port for lp1, and +disable lp0. +To disable the printer driver entirely, one can use +lp=0. +.\" .SH AUTHORS +.\" Linus Torvalds (and many others) +.SH SEE ALSO +.BR klogd (8), +.BR mount (8) +.P +For up-to-date information, see the kernel source file +.IR Documentation/admin\-guide/kernel\-parameters.txt . diff --git a/man/man7/bpf-helpers.7 b/man/man7/bpf-helpers.7 new file mode 100644 index 0000000..b4236f1 --- /dev/null +++ b/man/man7/bpf-helpers.7 @@ -0,0 +1,5171 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "BPF-HELPERS" 7 "2023-11-10" "Linux v6.8" +.SH NAME +BPF-HELPERS \- list of eBPF helper functions +.\" Copyright (C) All BPF authors and contributors from 2014 to present. +. +.\" See git log include/uapi/linux/bpf.h in kernel tree for details. +. +.\" +. +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +. +.\" +. +.\" Please do not edit this file. It was generated from the documentation +. +.\" located in file include/uapi/linux/bpf.h of the Linux kernel sources +. +.\" (helpers description), and from scripts/bpf_doc.py in the same +. +.\" repository (header and footer). +. +.SH DESCRIPTION +.sp +The extended Berkeley Packet Filter (eBPF) subsystem consists in programs +written in a pseudo\-assembly language, then attached to one of the several +kernel hooks and run in reaction of specific events. This framework differs +from the older, \(dqclassic\(dq BPF (or \(dqcBPF\(dq) in several aspects, one of them being +the ability to call special functions (or \(dqhelpers\(dq) from within a program. +These functions are restricted to a white\-list of helpers defined in the +kernel. +.sp +These helpers are used by eBPF programs to interact with the system, or with +the context in which they work. For instance, they can be used to print +debugging messages, to get the time since the system was booted, to interact +with eBPF maps, or to manipulate network packets. Since there are several eBPF +program types, and that they do not run in the same context, each program type +can only call a subset of those helpers. +.sp +Due to eBPF conventions, a helper can not have more than five arguments. +.sp +Internally, eBPF programs call directly into the compiled helper functions +without requiring any foreign\-function interface. As a result, calling helpers +introduces no overhead, thus offering excellent performance. +.sp +This document is an attempt to list and document the helpers available to eBPF +developers. They are sorted by chronological order (the oldest helpers in the +kernel at the top). +.SH HELPERS +.INDENT 0.0 +.TP +.B \fBvoid *bpf_map_lookup_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIkey\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Perform a lookup in \fImap\fP for an entry associated to \fIkey\fP\&. +.TP +.B Return +Map value associated to \fIkey\fP, or \fBNULL\fP if no entry was +found. +.UNINDENT +.TP +.B \fBlong bpf_map_update_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIkey\fP\fB, const void *\fP\fIvalue\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Add or update the value of the entry associated to \fIkey\fP in +\fImap\fP with \fIvalue\fP\&. \fIflags\fP is one of: +.INDENT 7.0 +.TP +.B \fBBPF_NOEXIST\fP +The entry for \fIkey\fP must not exist in the map. +.TP +.B \fBBPF_EXIST\fP +The entry for \fIkey\fP must already exist in the map. +.TP +.B \fBBPF_ANY\fP +No condition on the existence of the entry for \fIkey\fP\&. +.UNINDENT +.sp +Flag value \fBBPF_NOEXIST\fP cannot be used for maps of types +\fBBPF_MAP_TYPE_ARRAY\fP or \fBBPF_MAP_TYPE_PERCPU_ARRAY\fP (all +elements always exist), the helper would return an error. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_map_delete_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIkey\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Delete entry with \fIkey\fP from \fImap\fP\&. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_probe_read(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +For tracing programs, safely attempt to read \fIsize\fP bytes from +kernel space address \fIunsafe_ptr\fP and store the data in \fIdst\fP\&. +.sp +Generally, use \fBbpf_probe_read_user\fP() or +\fBbpf_probe_read_kernel\fP() instead. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBu64 bpf_ktime_get_ns(void)\fP +.INDENT 7.0 +.TP +.B Description +Return the time elapsed since system boot, in nanoseconds. +Does not include time the system was suspended. +See: \fBclock_gettime\fP(\fBCLOCK_MONOTONIC\fP) +.TP +.B Return +Current \fIktime\fP\&. +.UNINDENT +.TP +.B \fBlong bpf_trace_printk(const char *\fP\fIfmt\fP\fB, u32\fP \fIfmt_size\fP\fB, ...)\fP +.INDENT 7.0 +.TP +.B Description +This helper is a \(dqprintk()\-like\(dq facility for debugging. It +prints a message defined by format \fIfmt\fP (of size \fIfmt_size\fP) +to file \fI/sys/kernel/tracing/trace\fP from TraceFS, if +available. It can take up to three additional \fBu64\fP +arguments (as an eBPF helpers, the total number of arguments is +limited to five). +.sp +Each time the helper is called, it appends a line to the trace. +Lines are discarded while \fI/sys/kernel/tracing/trace\fP is +open, use \fI/sys/kernel/tracing/trace_pipe\fP to avoid this. +The format of the trace is customizable, and the exact output +one will get depends on the options set in +\fI/sys/kernel/tracing/trace_options\fP (see also the +\fIREADME\fP file under the same directory). However, it usually +defaults to something like: +.INDENT 7.0 +.INDENT 3.5 +.sp +.EX +telnet\-470 [001] .N.. 419421.045894: 0x00000001: +.EE +.UNINDENT +.UNINDENT +.sp +In the above: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +\fBtelnet\fP is the name of the current task. +.IP \(bu 2 +\fB470\fP is the PID of the current task. +.IP \(bu 2 +\fB001\fP is the CPU number on which the task is +running. +.IP \(bu 2 +In \fB\&.N..\fP, each character refers to a set of +options (whether irqs are enabled, scheduling +options, whether hard/softirqs are running, level of +preempt_disabled respectively). \fBN\fP means that +\fBTIF_NEED_RESCHED\fP and \fBPREEMPT_NEED_RESCHED\fP +are set. +.IP \(bu 2 +\fB419421.045894\fP is a timestamp. +.IP \(bu 2 +\fB0x00000001\fP is a fake value used by BPF for the +instruction pointer register. +.IP \(bu 2 +\fB\fP is the message formatted with +\fIfmt\fP\&. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +The conversion specifiers supported by \fIfmt\fP are similar, but +more limited than for printk(). They are \fB%d\fP, \fB%i\fP, +\fB%u\fP, \fB%x\fP, \fB%ld\fP, \fB%li\fP, \fB%lu\fP, \fB%lx\fP, \fB%lld\fP, +\fB%lli\fP, \fB%llu\fP, \fB%llx\fP, \fB%p\fP, \fB%s\fP\&. No modifier (size +of field, padding with zeroes, etc.) is available, and the +helper will return \fB\-EINVAL\fP (but print nothing) if it +encounters an unknown specifier. +.sp +Also, note that \fBbpf_trace_printk\fP() is slow, and should +only be used for debugging purposes. For this reason, a notice +block (spanning several lines) is printed to kernel logs and +states that the helper should not be used \(dqfor production use\(dq +the first time this helper is used (or more precisely, when +\fBtrace_printk\fP() buffers are allocated). For passing values +to user space, perf events should be preferred. +.TP +.B Return +The number of bytes written to the buffer, or a negative error +in case of failure. +.UNINDENT +.TP +.B \fBu32 bpf_get_prandom_u32(void)\fP +.INDENT 7.0 +.TP +.B Description +Get a pseudo\-random number. +.sp +From a security point of view, this helper uses its own +pseudo\-random internal state, and cannot be used to infer the +seed of other random functions in the kernel. However, it is +essential to note that the generator used by the helper is not +cryptographically secure. +.TP +.B Return +A random 32\-bit unsigned value. +.UNINDENT +.TP +.B \fBu32 bpf_get_smp_processor_id(void)\fP +.INDENT 7.0 +.TP +.B Description +Get the SMP (symmetric multiprocessing) processor id. Note that +all programs run with migration disabled, which means that the +SMP processor id is stable during all the execution of the +program. +.TP +.B Return +The SMP id of the processor running the program. +.UNINDENT +.TP +.B \fBlong bpf_skb_store_bytes(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, const void *\fP\fIfrom\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Store \fIlen\fP bytes from address \fIfrom\fP into the packet +associated to \fIskb\fP, at \fIoffset\fP\&. \fIflags\fP are a combination of +\fBBPF_F_RECOMPUTE_CSUM\fP (automatically recompute the +checksum for the packet after storing the bytes) and +\fBBPF_F_INVALIDATE_HASH\fP (set \fIskb\fP\fB\->hash\fP, \fIskb\fP\fB\->swhash\fP and \fIskb\fP\fB\->l4hash\fP to 0). +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_l3_csum_replace(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, u64\fP \fIfrom\fP\fB, u64\fP \fIto\fP\fB, u64\fP \fIsize\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Recompute the layer 3 (e.g. IP) checksum for the packet +associated to \fIskb\fP\&. Computation is incremental, so the helper +must know the former value of the header field that was +modified (\fIfrom\fP), the new value of this field (\fIto\fP), and the +number of bytes (2 or 4) for this field, stored in \fIsize\fP\&. +Alternatively, it is possible to store the difference between +the previous and the new values of the header field in \fIto\fP, by +setting \fIfrom\fP and \fIsize\fP to 0. For both methods, \fIoffset\fP +indicates the location of the IP checksum within the packet. +.sp +This helper works in combination with \fBbpf_csum_diff\fP(), +which does not update the checksum in\-place, but offers more +flexibility and can handle sizes larger than 2 or 4 for the +checksum to update. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_l4_csum_replace(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, u64\fP \fIfrom\fP\fB, u64\fP \fIto\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Recompute the layer 4 (e.g. TCP, UDP or ICMP) checksum for the +packet associated to \fIskb\fP\&. Computation is incremental, so the +helper must know the former value of the header field that was +modified (\fIfrom\fP), the new value of this field (\fIto\fP), and the +number of bytes (2 or 4) for this field, stored on the lowest +four bits of \fIflags\fP\&. Alternatively, it is possible to store +the difference between the previous and the new values of the +header field in \fIto\fP, by setting \fIfrom\fP and the four lowest +bits of \fIflags\fP to 0. For both methods, \fIoffset\fP indicates the +location of the IP checksum within the packet. In addition to +the size of the field, \fIflags\fP can be added (bitwise OR) actual +flags. With \fBBPF_F_MARK_MANGLED_0\fP, a null checksum is left +untouched (unless \fBBPF_F_MARK_ENFORCE\fP is added as well), and +for updates resulting in a null checksum the value is set to +\fBCSUM_MANGLED_0\fP instead. Flag \fBBPF_F_PSEUDO_HDR\fP indicates +the checksum is to be computed against a pseudo\-header. +.sp +This helper works in combination with \fBbpf_csum_diff\fP(), +which does not update the checksum in\-place, but offers more +flexibility and can handle sizes larger than 2 or 4 for the +checksum to update. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_tail_call(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fIprog_array_map\fP\fB, u32\fP \fIindex\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This special helper is used to trigger a \(dqtail call\(dq, or in +other words, to jump into another eBPF program. The same stack +frame is used (but values on stack and in registers for the +caller are not accessible to the callee). This mechanism allows +for program chaining, either for raising the maximum number of +available eBPF instructions, or to execute given programs in +conditional blocks. For security reasons, there is an upper +limit to the number of successive tail calls that can be +performed. +.sp +Upon call of this helper, the program attempts to jump into a +program referenced at index \fIindex\fP in \fIprog_array_map\fP, a +special map of type \fBBPF_MAP_TYPE_PROG_ARRAY\fP, and passes +\fIctx\fP, a pointer to the context. +.sp +If the call succeeds, the kernel immediately runs the first +instruction of the new program. This is not a function call, +and it never returns to the previous program. If the call +fails, then the helper has no effect, and the caller continues +to run its subsequent instructions. A call can fail if the +destination program for the jump does not exist (i.e. \fIindex\fP +is superior to the number of entries in \fIprog_array_map\fP), or +if the maximum number of tail calls has been reached for this +chain of programs. This limit is defined in the kernel by the +macro \fBMAX_TAIL_CALL_CNT\fP (not accessible to user space), +which is currently set to 33. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_clone_redirect(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIifindex\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Clone and redirect the packet associated to \fIskb\fP to another +net device of index \fIifindex\fP\&. Both ingress and egress +interfaces can be used for redirection. The \fBBPF_F_INGRESS\fP +value in \fIflags\fP is used to make the distinction (ingress path +is selected if the flag is present, egress path otherwise). +This is the only flag supported for now. +.sp +In comparison with \fBbpf_redirect\fP() helper, +\fBbpf_clone_redirect\fP() has the associated cost of +duplicating the packet buffer, but this can be executed out of +the eBPF program. Conversely, \fBbpf_redirect\fP() is more +efficient, but it is handled through an action code where the +redirection happens only after the eBPF program has returned. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. Positive +error indicates a potential drop or congestion in the target +device. The particular positive error codes are not defined. +.UNINDENT +.TP +.B \fBu64 bpf_get_current_pid_tgid(void)\fP +.INDENT 7.0 +.TP +.B Description +Get the current pid and tgid. +.TP +.B Return +A 64\-bit integer containing the current tgid and pid, and +created as such: +\fIcurrent_task\fP\fB\->tgid << 32 |\fP +\fIcurrent_task\fP\fB\->pid\fP\&. +.UNINDENT +.TP +.B \fBu64 bpf_get_current_uid_gid(void)\fP +.INDENT 7.0 +.TP +.B Description +Get the current uid and gid. +.TP +.B Return +A 64\-bit integer containing the current GID and UID, and +created as such: \fIcurrent_gid\fP \fB<< 32 |\fP \fIcurrent_uid\fP\&. +.UNINDENT +.TP +.B \fBlong bpf_get_current_comm(void *\fP\fIbuf\fP\fB, u32\fP \fIsize_of_buf\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Copy the \fBcomm\fP attribute of the current task into \fIbuf\fP of +\fIsize_of_buf\fP\&. The \fBcomm\fP attribute contains the name of +the executable (excluding the path) for the current task. The +\fIsize_of_buf\fP must be strictly positive. On success, the +helper makes sure that the \fIbuf\fP is NUL\-terminated. On failure, +it is filled with zeroes. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBu32 bpf_get_cgroup_classid(struct sk_buff *\fP\fIskb\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Retrieve the classid for the current task, i.e. for the net_cls +cgroup to which \fIskb\fP belongs. +.sp +This helper can be used on TC egress path, but not on ingress. +.sp +The net_cls cgroup provides an interface to tag network packets +based on a user\-provided identifier for all traffic coming from +the tasks belonging to the related cgroup. See also the related +kernel documentation, available from the Linux sources in file +\fIDocumentation/admin\-guide/cgroup\-v1/net_cls.rst\fP\&. +.sp +The Linux kernel has two versions for cgroups: there are +cgroups v1 and cgroups v2. Both are available to users, who can +use a mixture of them, but note that the net_cls cgroup is for +cgroup v1 only. This makes it incompatible with BPF programs +run on cgroups, which is a cgroup\-v2\-only feature (a socket can +only hold data for one version of cgroups at a time). +.sp +This helper is only available is the kernel was compiled with +the \fBCONFIG_CGROUP_NET_CLASSID\fP configuration option set to +\(dq\fBy\fP\(dq or to \(dq\fBm\fP\(dq. +.TP +.B Return +The classid, or 0 for the default unconfigured classid. +.UNINDENT +.TP +.B \fBlong bpf_skb_vlan_push(struct sk_buff *\fP\fIskb\fP\fB, __be16\fP \fIvlan_proto\fP\fB, u16\fP \fIvlan_tci\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Push a \fIvlan_tci\fP (VLAN tag control information) of protocol +\fIvlan_proto\fP to the packet associated to \fIskb\fP, then update +the checksum. Note that if \fIvlan_proto\fP is different from +\fBETH_P_8021Q\fP and \fBETH_P_8021AD\fP, it is considered to +be \fBETH_P_8021Q\fP\&. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_vlan_pop(struct sk_buff *\fP\fIskb\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Pop a VLAN header from the packet associated to \fIskb\fP\&. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_get_tunnel_key(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_tunnel_key *\fP\fIkey\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get tunnel metadata. This helper takes a pointer \fIkey\fP to an +empty \fBstruct bpf_tunnel_key\fP of \fBsize\fP, that will be +filled with tunnel metadata for the packet associated to \fIskb\fP\&. +The \fIflags\fP can be set to \fBBPF_F_TUNINFO_IPV6\fP, which +indicates that the tunnel is based on IPv6 protocol instead of +IPv4. +.sp +The \fBstruct bpf_tunnel_key\fP is an object that generalizes the +principal parameters used by various tunneling protocols into a +single struct. This way, it can be used to easily make a +decision based on the contents of the encapsulation header, +\(dqsummarized\(dq in this struct. In particular, it holds the IP +address of the remote end (IPv4 or IPv6, depending on the case) +in \fIkey\fP\fB\->remote_ipv4\fP or \fIkey\fP\fB\->remote_ipv6\fP\&. Also, +this struct exposes the \fIkey\fP\fB\->tunnel_id\fP, which is +generally mapped to a VNI (Virtual Network Identifier), making +it programmable together with the \fBbpf_skb_set_tunnel_key\fP() helper. +.sp +Let\(aqs imagine that the following code is part of a program +attached to the TC ingress interface, on one end of a GRE +tunnel, and is supposed to filter out all messages coming from +remote ends with IPv4 address other than 10.0.0.1: +.INDENT 7.0 +.INDENT 3.5 +.sp +.EX +int ret; +struct bpf_tunnel_key key = {}; + +ret = bpf_skb_get_tunnel_key(skb, &key, sizeof(key), 0); +if (ret < 0) + return TC_ACT_SHOT; // drop packet + +if (key.remote_ipv4 != 0x0a000001) + return TC_ACT_SHOT; // drop packet + +return TC_ACT_OK; // accept packet +.EE +.UNINDENT +.UNINDENT +.sp +This interface can also be used with all encapsulation devices +that can operate in \(dqcollect metadata\(dq mode: instead of having +one network device per specific configuration, the \(dqcollect +metadata\(dq mode only requires a single device where the +configuration can be extracted from this helper. +.sp +This can be used together with various tunnels such as VXLan, +Geneve, GRE or IP in IP (IPIP). +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_set_tunnel_key(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_tunnel_key *\fP\fIkey\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Populate tunnel metadata for packet associated to \fIskb.\fP The +tunnel metadata is set to the contents of \fIkey\fP, of \fIsize\fP\&. The +\fIflags\fP can be set to a combination of the following values: +.INDENT 7.0 +.TP +.B \fBBPF_F_TUNINFO_IPV6\fP +Indicate that the tunnel is based on IPv6 protocol +instead of IPv4. +.TP +.B \fBBPF_F_ZERO_CSUM_TX\fP +For IPv4 packets, add a flag to tunnel metadata +indicating that checksum computation should be skipped +and checksum set to zeroes. +.TP +.B \fBBPF_F_DONT_FRAGMENT\fP +Add a flag to tunnel metadata indicating that the +packet should not be fragmented. +.TP +.B \fBBPF_F_SEQ_NUMBER\fP +Add a flag to tunnel metadata indicating that a +sequence number should be added to tunnel header before +sending the packet. This flag was added for GRE +encapsulation, but might be used with other protocols +as well in the future. +.TP +.B \fBBPF_F_NO_TUNNEL_KEY\fP +Add a flag to tunnel metadata indicating that no tunnel +key should be set in the resulting tunnel header. +.UNINDENT +.sp +Here is a typical usage on the transmit path: +.INDENT 7.0 +.INDENT 3.5 +.sp +.EX +struct bpf_tunnel_key key; + populate key ... +bpf_skb_set_tunnel_key(skb, &key, sizeof(key), 0); +bpf_clone_redirect(skb, vxlan_dev_ifindex, 0); +.EE +.UNINDENT +.UNINDENT +.sp +See also the description of the \fBbpf_skb_get_tunnel_key\fP() +helper for additional information. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBu64 bpf_perf_event_read(struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Read the value of a perf event counter. This helper relies on a +\fImap\fP of type \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. The nature of +the perf event counter is selected when \fImap\fP is updated with +perf event file descriptors. The \fImap\fP is an array whose size +is the number of available CPUs, and each cell contains a value +relative to one CPU. The value to retrieve is indicated by +\fIflags\fP, that contains the index of the CPU to look up, masked +with \fBBPF_F_INDEX_MASK\fP\&. Alternatively, \fIflags\fP can be set to +\fBBPF_F_CURRENT_CPU\fP to indicate that the value for the +current CPU should be retrieved. +.sp +Note that before Linux 4.13, only hardware perf event can be +retrieved. +.sp +Also, be aware that the newer helper +\fBbpf_perf_event_read_value\fP() is recommended over +\fBbpf_perf_event_read\fP() in general. The latter has some ABI +quirks where error and counter value are used as a return code +(which is wrong to do since ranges may overlap). This issue is +fixed with \fBbpf_perf_event_read_value\fP(), which at the same +time provides more features over the \fBbpf_perf_event_read\fP() interface. Please refer to the description of +\fBbpf_perf_event_read_value\fP() for details. +.TP +.B Return +The value of the perf event counter read from the map, or a +negative error code in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_redirect(u32\fP \fIifindex\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Redirect the packet to another net device of index \fIifindex\fP\&. +This helper is somewhat similar to \fBbpf_clone_redirect\fP(), except that the packet is not cloned, which provides +increased performance. +.sp +Except for XDP, both ingress and egress interfaces can be used +for redirection. The \fBBPF_F_INGRESS\fP value in \fIflags\fP is used +to make the distinction (ingress path is selected if the flag +is present, egress path otherwise). Currently, XDP only +supports redirection to the egress interface, and accepts no +flag at all. +.sp +The same effect can also be attained with the more generic +\fBbpf_redirect_map\fP(), which uses a BPF map to store the +redirect target instead of providing it directly to the helper. +.TP +.B Return +For XDP, the helper returns \fBXDP_REDIRECT\fP on success or +\fBXDP_ABORTED\fP on error. For other program types, the values +are \fBTC_ACT_REDIRECT\fP on success or \fBTC_ACT_SHOT\fP on +error. +.UNINDENT +.TP +.B \fBu32 bpf_get_route_realm(struct sk_buff *\fP\fIskb\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Retrieve the realm or the route, that is to say the +\fBtclassid\fP field of the destination for the \fIskb\fP\&. The +identifier retrieved is a user\-provided tag, similar to the +one used with the net_cls cgroup (see description for +\fBbpf_get_cgroup_classid\fP() helper), but here this tag is +held by a route (a destination entry), not by a task. +.sp +Retrieving this identifier works with the clsact TC egress hook +(see also \fBtc\-bpf(8)\fP), or alternatively on conventional +classful egress qdiscs, but not on TC ingress path. In case of +clsact TC egress hook, this has the advantage that, internally, +the destination entry has not been dropped yet in the transmit +path. Therefore, the destination entry does not need to be +artificially held via \fBnetif_keep_dst\fP() for a classful +qdisc until the \fIskb\fP is freed. +.sp +This helper is available only if the kernel was compiled with +\fBCONFIG_IP_ROUTE_CLASSID\fP configuration option. +.TP +.B Return +The realm of the route for the packet associated to \fIskb\fP, or 0 +if none was found. +.UNINDENT +.TP +.B \fBlong bpf_perf_event_output(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64\fP \fIsize\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Write raw \fIdata\fP blob into a special BPF perf event held by +\fImap\fP of type \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. This perf +event must have the following attributes: \fBPERF_SAMPLE_RAW\fP +as \fBsample_type\fP, \fBPERF_TYPE_SOFTWARE\fP as \fBtype\fP, and +\fBPERF_COUNT_SW_BPF_OUTPUT\fP as \fBconfig\fP\&. +.sp +The \fIflags\fP are used to indicate the index in \fImap\fP for which +the value must be put, masked with \fBBPF_F_INDEX_MASK\fP\&. +Alternatively, \fIflags\fP can be set to \fBBPF_F_CURRENT_CPU\fP +to indicate that the index of the current CPU core should be +used. +.sp +The value to write, of \fIsize\fP, is passed through eBPF stack and +pointed by \fIdata\fP\&. +.sp +The context of the program \fIctx\fP needs also be passed to the +helper. +.sp +On user space, a program willing to read the values needs to +call \fBperf_event_open\fP() on the perf event (either for +one or for all CPUs) and to store the file descriptor into the +\fImap\fP\&. This must be done before the eBPF program can send data +into it. An example is available in file +\fIsamples/bpf/trace_output_user.c\fP in the Linux kernel source +tree (the eBPF program counterpart is in +\fIsamples/bpf/trace_output_kern.c\fP). +.sp +\fBbpf_perf_event_output\fP() achieves better performance +than \fBbpf_trace_printk\fP() for sharing data with user +space, and is much better suitable for streaming data from eBPF +programs. +.sp +Note that this helper is not restricted to tracing use cases +and can be used with programs attached to TC or XDP as well, +where it allows for passing data to user space listeners. Data +can be: +.INDENT 7.0 +.IP \(bu 2 +Only custom structs, +.IP \(bu 2 +Only the packet payload, or +.IP \(bu 2 +A combination of both. +.UNINDENT +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_load_bytes(const void *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, void *\fP\fIto\fP\fB, u32\fP \fIlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper was provided as an easy way to load data from a +packet. It can be used to load \fIlen\fP bytes from \fIoffset\fP from +the packet associated to \fIskb\fP, into the buffer pointed by +\fIto\fP\&. +.sp +Since Linux 4.7, usage of this helper has mostly been replaced +by \(dqdirect packet access\(dq, enabling packet data to be +manipulated with \fIskb\fP\fB\->data\fP and \fIskb\fP\fB\->data_end\fP +pointing respectively to the first byte of packet data and to +the byte after the last byte of packet data. However, it +remains useful if one wishes to read large quantities of data +at once from a packet into the eBPF stack. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_get_stackid(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Walk a user or a kernel stack and return its id. To achieve +this, the helper needs \fIctx\fP, which is a pointer to the context +on which the tracing program is executed, and a pointer to a +\fImap\fP of type \fBBPF_MAP_TYPE_STACK_TRACE\fP\&. +.sp +The last argument, \fIflags\fP, holds the number of stack frames to +skip (from 0 to 255), masked with +\fBBPF_F_SKIP_FIELD_MASK\fP\&. The next bits can be used to set +a combination of the following flags: +.INDENT 7.0 +.TP +.B \fBBPF_F_USER_STACK\fP +Collect a user space stack instead of a kernel stack. +.TP +.B \fBBPF_F_FAST_STACK_CMP\fP +Compare stacks by hash only. +.TP +.B \fBBPF_F_REUSE_STACKID\fP +If two different stacks hash into the same \fIstackid\fP, +discard the old one. +.UNINDENT +.sp +The stack id retrieved is a 32 bit long integer handle which +can be further combined with other data (including other stack +ids) and used as a key into maps. This can be useful for +generating a variety of graphs (such as flame graphs or off\-cpu +graphs). +.sp +For walking a stack, this helper is an improvement over +\fBbpf_probe_read\fP(), which can be used with unrolled loops +but is not efficient and consumes a lot of eBPF instructions. +Instead, \fBbpf_get_stackid\fP() can collect up to +\fBPERF_MAX_STACK_DEPTH\fP both kernel and user frames. Note that +this limit can be controlled with the \fBsysctl\fP program, and +that it should be manually increased in order to profile long +user stacks (such as stacks for Java programs). To do so, use: +.INDENT 7.0 +.INDENT 3.5 +.sp +.EX +# sysctl kernel.perf_event_max_stack= +.EE +.UNINDENT +.UNINDENT +.TP +.B Return +The positive or null stack id on success, or a negative error +in case of failure. +.UNINDENT +.TP +.B \fBs64 bpf_csum_diff(__be32 *\fP\fIfrom\fP\fB, u32\fP \fIfrom_size\fP\fB, __be32 *\fP\fIto\fP\fB, u32\fP \fIto_size\fP\fB, __wsum\fP \fIseed\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Compute a checksum difference, from the raw buffer pointed by +\fIfrom\fP, of length \fIfrom_size\fP (that must be a multiple of 4), +towards the raw buffer pointed by \fIto\fP, of size \fIto_size\fP +(same remark). An optional \fIseed\fP can be added to the value +(this can be cascaded, the seed may come from a previous call +to the helper). +.sp +This is flexible enough to be used in several ways: +.INDENT 7.0 +.IP \(bu 2 +With \fIfrom_size\fP == 0, \fIto_size\fP > 0 and \fIseed\fP set to +checksum, it can be used when pushing new data. +.IP \(bu 2 +With \fIfrom_size\fP > 0, \fIto_size\fP == 0 and \fIseed\fP set to +checksum, it can be used when removing data from a packet. +.IP \(bu 2 +With \fIfrom_size\fP > 0, \fIto_size\fP > 0 and \fIseed\fP set to 0, it +can be used to compute a diff. Note that \fIfrom_size\fP and +\fIto_size\fP do not need to be equal. +.UNINDENT +.sp +This helper can be used in combination with +\fBbpf_l3_csum_replace\fP() and \fBbpf_l4_csum_replace\fP(), to +which one can feed in the difference computed with +\fBbpf_csum_diff\fP(). +.TP +.B Return +The checksum result, or a negative error code in case of +failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_get_tunnel_opt(struct sk_buff *\fP\fIskb\fP\fB, void *\fP\fIopt\fP\fB, u32\fP \fIsize\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Retrieve tunnel options metadata for the packet associated to +\fIskb\fP, and store the raw tunnel option data to the buffer \fIopt\fP +of \fIsize\fP\&. +.sp +This helper can be used with encapsulation devices that can +operate in \(dqcollect metadata\(dq mode (please refer to the related +note in the description of \fBbpf_skb_get_tunnel_key\fP() for +more details). A particular example where this can be used is +in combination with the Geneve encapsulation protocol, where it +allows for pushing (with \fBbpf_skb_get_tunnel_opt\fP() helper) +and retrieving arbitrary TLVs (Type\-Length\-Value headers) from +the eBPF program. This allows for full customization of these +headers. +.TP +.B Return +The size of the option data retrieved. +.UNINDENT +.TP +.B \fBlong bpf_skb_set_tunnel_opt(struct sk_buff *\fP\fIskb\fP\fB, void *\fP\fIopt\fP\fB, u32\fP \fIsize\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Set tunnel options metadata for the packet associated to \fIskb\fP +to the option data contained in the raw buffer \fIopt\fP of \fIsize\fP\&. +.sp +See also the description of the \fBbpf_skb_get_tunnel_opt\fP() +helper for additional information. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_change_proto(struct sk_buff *\fP\fIskb\fP\fB, __be16\fP \fIproto\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Change the protocol of the \fIskb\fP to \fIproto\fP\&. Currently +supported are transition from IPv4 to IPv6, and from IPv6 to +IPv4. The helper takes care of the groundwork for the +transition, including resizing the socket buffer. The eBPF +program is expected to fill the new headers, if any, via +\fBskb_store_bytes\fP() and to recompute the checksums with +\fBbpf_l3_csum_replace\fP() and \fBbpf_l4_csum_replace\fP(). The main case for this helper is to perform NAT64 +operations out of an eBPF program. +.sp +Internally, the GSO type is marked as dodgy so that headers are +checked and segments are recalculated by the GSO/GRO engine. +The size for GSO target is adapted as well. +.sp +All values for \fIflags\fP are reserved for future usage, and must +be left at zero. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_change_type(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fItype\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Change the packet type for the packet associated to \fIskb\fP\&. This +comes down to setting \fIskb\fP\fB\->pkt_type\fP to \fItype\fP, except +the eBPF program does not have a write access to \fIskb\fP\fB\->pkt_type\fP beside this helper. Using a helper here allows +for graceful handling of errors. +.sp +The major use case is to change incoming \fIskb*s to +**PACKET_HOST*\fP in a programmatic way instead of having to +recirculate via \fBredirect\fP(..., \fBBPF_F_INGRESS\fP), for +example. +.sp +Note that \fItype\fP only allows certain values. At this time, they +are: +.INDENT 7.0 +.TP +.B \fBPACKET_HOST\fP +Packet is for us. +.TP +.B \fBPACKET_BROADCAST\fP +Send packet to all. +.TP +.B \fBPACKET_MULTICAST\fP +Send packet to group. +.TP +.B \fBPACKET_OTHERHOST\fP +Send packet to someone else. +.UNINDENT +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_under_cgroup(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u32\fP \fIindex\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Check whether \fIskb\fP is a descendant of the cgroup2 held by +\fImap\fP of type \fBBPF_MAP_TYPE_CGROUP_ARRAY\fP, at \fIindex\fP\&. +.TP +.B Return +The return value depends on the result of the test, and can be: +.INDENT 7.0 +.IP \(bu 2 +0, if the \fIskb\fP failed the cgroup2 descendant test. +.IP \(bu 2 +1, if the \fIskb\fP succeeded the cgroup2 descendant test. +.IP \(bu 2 +A negative error code, if an error occurred. +.UNINDENT +.UNINDENT +.TP +.B \fBu32 bpf_get_hash_recalc(struct sk_buff *\fP\fIskb\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Retrieve the hash of the packet, \fIskb\fP\fB\->hash\fP\&. If it is +not set, in particular if the hash was cleared due to mangling, +recompute this hash. Later accesses to the hash can be done +directly with \fIskb\fP\fB\->hash\fP\&. +.sp +Calling \fBbpf_set_hash_invalid\fP(), changing a packet +prototype with \fBbpf_skb_change_proto\fP(), or calling +\fBbpf_skb_store_bytes\fP() with the +\fBBPF_F_INVALIDATE_HASH\fP are actions susceptible to clear +the hash and to trigger a new computation for the next call to +\fBbpf_get_hash_recalc\fP(). +.TP +.B Return +The 32\-bit hash. +.UNINDENT +.TP +.B \fBu64 bpf_get_current_task(void)\fP +.INDENT 7.0 +.TP +.B Description +Get the current task. +.TP +.B Return +A pointer to the current task struct. +.UNINDENT +.TP +.B \fBlong bpf_probe_write_user(void *\fP\fIdst\fP\fB, const void *\fP\fIsrc\fP\fB, u32\fP \fIlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Attempt in a safe way to write \fIlen\fP bytes from the buffer +\fIsrc\fP to \fIdst\fP in memory. It only works for threads that are in +user context, and \fIdst\fP must be a valid user space address. +.sp +This helper should not be used to implement any kind of +security mechanism because of TOC\-TOU attacks, but rather to +debug, divert, and manipulate execution of semi\-cooperative +processes. +.sp +Keep in mind that this feature is meant for experiments, and it +has a risk of crashing the system and running programs. +Therefore, when an eBPF program using this helper is attached, +a warning including PID and process name is printed to kernel +logs. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_current_task_under_cgroup(struct bpf_map *\fP\fImap\fP\fB, u32\fP \fIindex\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Check whether the probe is being run is the context of a given +subset of the cgroup2 hierarchy. The cgroup2 to test is held by +\fImap\fP of type \fBBPF_MAP_TYPE_CGROUP_ARRAY\fP, at \fIindex\fP\&. +.TP +.B Return +The return value depends on the result of the test, and can be: +.INDENT 7.0 +.IP \(bu 2 +1, if current task belongs to the cgroup2. +.IP \(bu 2 +0, if current task does not belong to the cgroup2. +.IP \(bu 2 +A negative error code, if an error occurred. +.UNINDENT +.UNINDENT +.TP +.B \fBlong bpf_skb_change_tail(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Resize (trim or grow) the packet associated to \fIskb\fP to the +new \fIlen\fP\&. The \fIflags\fP are reserved for future usage, and must +be left at zero. +.sp +The basic idea is that the helper performs the needed work to +change the size of the packet, then the eBPF program rewrites +the rest via helpers like \fBbpf_skb_store_bytes\fP(), +\fBbpf_l3_csum_replace\fP(), \fBbpf_l3_csum_replace\fP() +and others. This helper is a slow path utility intended for +replies with control messages. And because it is targeted for +slow path, the helper itself can afford to be slow: it +implicitly linearizes, unclones and drops offloads from the +\fIskb\fP\&. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_pull_data(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Pull in non\-linear data in case the \fIskb\fP is non\-linear and not +all of \fIlen\fP are part of the linear section. Make \fIlen\fP bytes +from \fIskb\fP readable and writable. If a zero value is passed for +\fIlen\fP, then all bytes in the linear part of \fIskb\fP will be made +readable and writable. +.sp +This helper is only needed for reading and writing with direct +packet access. +.sp +For direct packet access, testing that offsets to access +are within packet boundaries (test on \fIskb\fP\fB\->data_end\fP) is +susceptible to fail if offsets are invalid, or if the requested +data is in non\-linear parts of the \fIskb\fP\&. On failure the +program can just bail out, or in the case of a non\-linear +buffer, use a helper to make the data available. The +\fBbpf_skb_load_bytes\fP() helper is a first solution to access +the data. Another one consists in using \fBbpf_skb_pull_data\fP +to pull in once the non\-linear parts, then retesting and +eventually access the data. +.sp +At the same time, this also makes sure the \fIskb\fP is uncloned, +which is a necessary condition for direct write. As this needs +to be an invariant for the write part only, the verifier +detects writes and adds a prologue that is calling +\fBbpf_skb_pull_data()\fP to effectively unclone the \fIskb\fP from +the very beginning in case it is indeed cloned. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBs64 bpf_csum_update(struct sk_buff *\fP\fIskb\fP\fB, __wsum\fP \fIcsum\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Add the checksum \fIcsum\fP into \fIskb\fP\fB\->csum\fP in case the +driver has supplied a checksum for the entire packet into that +field. Return an error otherwise. This helper is intended to be +used in combination with \fBbpf_csum_diff\fP(), in particular +when the checksum needs to be updated after data has been +written into the packet through direct packet access. +.TP +.B Return +The checksum on success, or a negative error code in case of +failure. +.UNINDENT +.TP +.B \fBvoid bpf_set_hash_invalid(struct sk_buff *\fP\fIskb\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Invalidate the current \fIskb\fP\fB\->hash\fP\&. It can be used after +mangling on headers through direct packet access, in order to +indicate that the hash is outdated and to trigger a +recalculation the next time the kernel tries to access this +hash or when the \fBbpf_get_hash_recalc\fP() helper is called. +.TP +.B Return +void. +.UNINDENT +.TP +.B \fBlong bpf_get_numa_node_id(void)\fP +.INDENT 7.0 +.TP +.B Description +Return the id of the current NUMA node. The primary use case +for this helper is the selection of sockets for the local NUMA +node, when the program is attached to sockets using the +\fBSO_ATTACH_REUSEPORT_EBPF\fP option (see also \fBsocket(7)\fP), +but the helper is also available to other eBPF program types, +similarly to \fBbpf_get_smp_processor_id\fP(). +.TP +.B Return +The id of current NUMA node. +.UNINDENT +.TP +.B \fBlong bpf_skb_change_head(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Grows headroom of packet associated to \fIskb\fP and adjusts the +offset of the MAC header accordingly, adding \fIlen\fP bytes of +space. It automatically extends and reallocates memory as +required. +.sp +This helper can be used on a layer 3 \fIskb\fP to push a MAC header +for redirection into a layer 2 device. +.sp +All values for \fIflags\fP are reserved for future usage, and must +be left at zero. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_xdp_adjust_head(struct xdp_buff *\fP\fIxdp_md\fP\fB, int\fP \fIdelta\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Adjust (move) \fIxdp_md\fP\fB\->data\fP by \fIdelta\fP bytes. Note that +it is possible to use a negative value for \fIdelta\fP\&. This helper +can be used to prepare the packet for pushing or popping +headers. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_probe_read_str(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Copy a NUL terminated string from an unsafe kernel address +\fIunsafe_ptr\fP to \fIdst\fP\&. See \fBbpf_probe_read_kernel_str\fP() for +more details. +.sp +Generally, use \fBbpf_probe_read_user_str\fP() or +\fBbpf_probe_read_kernel_str\fP() instead. +.TP +.B Return +On success, the strictly positive length of the string, +including the trailing NUL character. On error, a negative +value. +.UNINDENT +.TP +.B \fBu64 bpf_get_socket_cookie(struct sk_buff *\fP\fIskb\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +If the \fBstruct sk_buff\fP pointed by \fIskb\fP has a known socket, +retrieve the cookie (generated by the kernel) of this socket. +If no cookie has been set yet, generate a new cookie. Once +generated, the socket cookie remains stable for the life of the +socket. This helper can be useful for monitoring per socket +networking traffic statistics as it provides a global socket +identifier that can be assumed unique. +.TP +.B Return +A 8\-byte long unique number on success, or 0 if the socket +field is missing inside \fIskb\fP\&. +.UNINDENT +.TP +.B \fBu64 bpf_get_socket_cookie(struct bpf_sock_addr *\fP\fIctx\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Equivalent to bpf_get_socket_cookie() helper that accepts +\fIskb\fP, but gets socket from \fBstruct bpf_sock_addr\fP context. +.TP +.B Return +A 8\-byte long unique number. +.UNINDENT +.TP +.B \fBu64 bpf_get_socket_cookie(struct bpf_sock_ops *\fP\fIctx\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Equivalent to \fBbpf_get_socket_cookie\fP() helper that accepts +\fIskb\fP, but gets socket from \fBstruct bpf_sock_ops\fP context. +.TP +.B Return +A 8\-byte long unique number. +.UNINDENT +.TP +.B \fBu64 bpf_get_socket_cookie(struct sock *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Equivalent to \fBbpf_get_socket_cookie\fP() helper that accepts +\fIsk\fP, but gets socket from a BTF \fBstruct sock\fP\&. This helper +also works for sleepable programs. +.TP +.B Return +A 8\-byte long unique number or 0 if \fIsk\fP is NULL. +.UNINDENT +.TP +.B \fBu32 bpf_get_socket_uid(struct sk_buff *\fP\fIskb\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get the owner UID of the socked associated to \fIskb\fP\&. +.TP +.B Return +The owner UID of the socket associated to \fIskb\fP\&. If the socket +is \fBNULL\fP, or if it is not a full socket (i.e. if it is a +time\-wait or a request socket instead), \fBoverflowuid\fP value +is returned (note that \fBoverflowuid\fP might also be the actual +UID value for the socket). +.UNINDENT +.TP +.B \fBlong bpf_set_hash(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIhash\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Set the full hash for \fIskb\fP (set the field \fIskb\fP\fB\->hash\fP) +to value \fIhash\fP\&. +.TP +.B Return +0 +.UNINDENT +.TP +.B \fBlong bpf_setsockopt(void *\fP\fIbpf_socket\fP\fB, int\fP \fIlevel\fP\fB, int\fP \fIoptname\fP\fB, void *\fP\fIoptval\fP\fB, int\fP \fIoptlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Emulate a call to \fBsetsockopt()\fP on the socket associated to +\fIbpf_socket\fP, which must be a full socket. The \fIlevel\fP at +which the option resides and the name \fIoptname\fP of the option +must be specified, see \fBsetsockopt(2)\fP for more information. +The option value of length \fIoptlen\fP is pointed by \fIoptval\fP\&. +.sp +\fIbpf_socket\fP should be one of the following: +.INDENT 7.0 +.IP \(bu 2 +\fBstruct bpf_sock_ops\fP for \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. +.IP \(bu 2 +\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP, +\fBBPF_CGROUP_INET6_CONNECT\fP and \fBBPF_CGROUP_UNIX_CONNECT\fP\&. +.UNINDENT +.sp +This helper actually implements a subset of \fBsetsockopt()\fP\&. +It supports the following \fIlevel\fPs: +.INDENT 7.0 +.IP \(bu 2 +\fBSOL_SOCKET\fP, which supports the following \fIoptname\fPs: +\fBSO_RCVBUF\fP, \fBSO_SNDBUF\fP, \fBSO_MAX_PACING_RATE\fP, +\fBSO_PRIORITY\fP, \fBSO_RCVLOWAT\fP, \fBSO_MARK\fP, +\fBSO_BINDTODEVICE\fP, \fBSO_KEEPALIVE\fP, \fBSO_REUSEADDR\fP, +\fBSO_REUSEPORT\fP, \fBSO_BINDTOIFINDEX\fP, \fBSO_TXREHASH\fP\&. +.IP \(bu 2 +\fBIPPROTO_TCP\fP, which supports the following \fIoptname\fPs: +\fBTCP_CONGESTION\fP, \fBTCP_BPF_IW\fP, +\fBTCP_BPF_SNDCWND_CLAMP\fP, \fBTCP_SAVE_SYN\fP, +\fBTCP_KEEPIDLE\fP, \fBTCP_KEEPINTVL\fP, \fBTCP_KEEPCNT\fP, +\fBTCP_SYNCNT\fP, \fBTCP_USER_TIMEOUT\fP, \fBTCP_NOTSENT_LOWAT\fP, +\fBTCP_NODELAY\fP, \fBTCP_MAXSEG\fP, \fBTCP_WINDOW_CLAMP\fP, +\fBTCP_THIN_LINEAR_TIMEOUTS\fP, \fBTCP_BPF_DELACK_MAX\fP, +\fBTCP_BPF_RTO_MIN\fP\&. +.IP \(bu 2 +\fBIPPROTO_IP\fP, which supports \fIoptname\fP \fBIP_TOS\fP\&. +.IP \(bu 2 +\fBIPPROTO_IPV6\fP, which supports the following \fIoptname\fPs: +\fBIPV6_TCLASS\fP, \fBIPV6_AUTOFLOWLABEL\fP\&. +.UNINDENT +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_adjust_room(struct sk_buff *\fP\fIskb\fP\fB, s32\fP \fIlen_diff\fP\fB, u32\fP \fImode\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Grow or shrink the room for data in the packet associated to +\fIskb\fP by \fIlen_diff\fP, and according to the selected \fImode\fP\&. +.sp +By default, the helper will reset any offloaded checksum +indicator of the skb to CHECKSUM_NONE. This can be avoided +by the following flag: +.INDENT 7.0 +.IP \(bu 2 +\fBBPF_F_ADJ_ROOM_NO_CSUM_RESET\fP: Do not reset offloaded +checksum data of the skb to CHECKSUM_NONE. +.UNINDENT +.sp +There are two supported modes at this time: +.INDENT 7.0 +.IP \(bu 2 +\fBBPF_ADJ_ROOM_MAC\fP: Adjust room at the mac layer +(room space is added or removed between the layer 2 and +layer 3 headers). +.IP \(bu 2 +\fBBPF_ADJ_ROOM_NET\fP: Adjust room at the network layer +(room space is added or removed between the layer 3 and +layer 4 headers). +.UNINDENT +.sp +The following flags are supported at this time: +.INDENT 7.0 +.IP \(bu 2 +\fBBPF_F_ADJ_ROOM_FIXED_GSO\fP: Do not adjust gso_size. +Adjusting mss in this way is not allowed for datagrams. +.IP \(bu 2 +\fBBPF_F_ADJ_ROOM_ENCAP_L3_IPV4\fP, +\fBBPF_F_ADJ_ROOM_ENCAP_L3_IPV6\fP: +Any new space is reserved to hold a tunnel header. +Configure skb offsets and other fields accordingly. +.IP \(bu 2 +\fBBPF_F_ADJ_ROOM_ENCAP_L4_GRE\fP, +\fBBPF_F_ADJ_ROOM_ENCAP_L4_UDP\fP: +Use with ENCAP_L3 flags to further specify the tunnel type. +.IP \(bu 2 +\fBBPF_F_ADJ_ROOM_ENCAP_L2\fP(\fIlen\fP): +Use with ENCAP_L3/L4 flags to further specify the tunnel +type; \fIlen\fP is the length of the inner MAC header. +.IP \(bu 2 +\fBBPF_F_ADJ_ROOM_ENCAP_L2_ETH\fP: +Use with BPF_F_ADJ_ROOM_ENCAP_L2 flag to further specify the +L2 type as Ethernet. +.IP \(bu 2 +\fBBPF_F_ADJ_ROOM_DECAP_L3_IPV4\fP, +\fBBPF_F_ADJ_ROOM_DECAP_L3_IPV6\fP: +Indicate the new IP header version after decapsulating the outer +IP header. Used when the inner and outer IP versions are different. +.UNINDENT +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_redirect_map(struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Redirect the packet to the endpoint referenced by \fImap\fP at +index \fIkey\fP\&. Depending on its type, this \fImap\fP can contain +references to net devices (for forwarding packets through other +ports), or to CPUs (for redirecting XDP frames to another CPU; +but this is only implemented for native XDP (with driver +support) as of this writing). +.sp +The lower two bits of \fIflags\fP are used as the return code if +the map lookup fails. This is so that the return value can be +one of the XDP program return codes up to \fBXDP_TX\fP, as chosen +by the caller. The higher bits of \fIflags\fP can be set to +BPF_F_BROADCAST or BPF_F_EXCLUDE_INGRESS as defined below. +.sp +With BPF_F_BROADCAST the packet will be broadcasted to all the +interfaces in the map, with BPF_F_EXCLUDE_INGRESS the ingress +interface will be excluded when do broadcasting. +.sp +See also \fBbpf_redirect\fP(), which only supports redirecting +to an ifindex, but doesn\(aqt require a map to do so. +.TP +.B Return +\fBXDP_REDIRECT\fP on success, or the value of the two lower bits +of the \fIflags\fP argument on error. +.UNINDENT +.TP +.B \fBlong bpf_sk_redirect_map(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u32\fP \fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Redirect the packet to the socket referenced by \fImap\fP (of type +\fBBPF_MAP_TYPE_SOCKMAP\fP) at index \fIkey\fP\&. Both ingress and +egress interfaces can be used for redirection. The +\fBBPF_F_INGRESS\fP value in \fIflags\fP is used to make the +distinction (ingress path is selected if the flag is present, +egress path otherwise). This is the only flag supported for now. +.TP +.B Return +\fBSK_PASS\fP on success, or \fBSK_DROP\fP on error. +.UNINDENT +.TP +.B \fBlong bpf_sock_map_update(struct bpf_sock_ops *\fP\fIskops\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Add an entry to, or update a \fImap\fP referencing sockets. The +\fIskops\fP is used as a new value for the entry associated to +\fIkey\fP\&. \fIflags\fP is one of: +.INDENT 7.0 +.TP +.B \fBBPF_NOEXIST\fP +The entry for \fIkey\fP must not exist in the map. +.TP +.B \fBBPF_EXIST\fP +The entry for \fIkey\fP must already exist in the map. +.TP +.B \fBBPF_ANY\fP +No condition on the existence of the entry for \fIkey\fP\&. +.UNINDENT +.sp +If the \fImap\fP has eBPF programs (parser and verdict), those will +be inherited by the socket being added. If the socket is +already attached to eBPF programs, this results in an error. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_xdp_adjust_meta(struct xdp_buff *\fP\fIxdp_md\fP\fB, int\fP \fIdelta\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Adjust the address pointed by \fIxdp_md\fP\fB\->data_meta\fP by +\fIdelta\fP (which can be positive or negative). Note that this +operation modifies the address stored in \fIxdp_md\fP\fB\->data\fP, +so the latter must be loaded only after the helper has been +called. +.sp +The use of \fIxdp_md\fP\fB\->data_meta\fP is optional and programs +are not required to use it. The rationale is that when the +packet is processed with XDP (e.g. as DoS filter), it is +possible to push further meta data along with it before passing +to the stack, and to give the guarantee that an ingress eBPF +program attached as a TC classifier on the same device can pick +this up for further post\-processing. Since TC works with socket +buffers, it remains possible to set from XDP the \fBmark\fP or +\fBpriority\fP pointers, or other pointers for the socket buffer. +Having this scratch space generic and programmable allows for +more flexibility as the user is free to store whatever meta +data they need. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_perf_event_read_value(struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB, struct bpf_perf_event_value *\fP\fIbuf\fP\fB, u32\fP \fIbuf_size\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Read the value of a perf event counter, and store it into \fIbuf\fP +of size \fIbuf_size\fP\&. This helper relies on a \fImap\fP of type +\fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. The nature of the perf event +counter is selected when \fImap\fP is updated with perf event file +descriptors. The \fImap\fP is an array whose size is the number of +available CPUs, and each cell contains a value relative to one +CPU. The value to retrieve is indicated by \fIflags\fP, that +contains the index of the CPU to look up, masked with +\fBBPF_F_INDEX_MASK\fP\&. Alternatively, \fIflags\fP can be set to +\fBBPF_F_CURRENT_CPU\fP to indicate that the value for the +current CPU should be retrieved. +.sp +This helper behaves in a way close to +\fBbpf_perf_event_read\fP() helper, save that instead of +just returning the value observed, it fills the \fIbuf\fP +structure. This allows for additional data to be retrieved: in +particular, the enabled and running times (in \fIbuf\fP\fB\->enabled\fP and \fIbuf\fP\fB\->running\fP, respectively) are +copied. In general, \fBbpf_perf_event_read_value\fP() is +recommended over \fBbpf_perf_event_read\fP(), which has some +ABI issues and provides fewer functionalities. +.sp +These values are interesting, because hardware PMU (Performance +Monitoring Unit) counters are limited resources. When there are +more PMU based perf events opened than available counters, +kernel will multiplex these events so each event gets certain +percentage (but not all) of the PMU time. In case that +multiplexing happens, the number of samples or counter value +will not reflect the case compared to when no multiplexing +occurs. This makes comparison between different runs difficult. +Typically, the counter value should be normalized before +comparing to other experiments. The usual normalization is done +as follows. +.INDENT 7.0 +.INDENT 3.5 +.sp +.EX +normalized_counter = counter * t_enabled / t_running +.EE +.UNINDENT +.UNINDENT +.sp +Where t_enabled is the time enabled for event and t_running is +the time running for event since last normalization. The +enabled and running times are accumulated since the perf event +open. To achieve scaling factor between two invocations of an +eBPF program, users can use CPU id as the key (which is +typical for perf array usage model) to remember the previous +value and do the calculation inside the eBPF program. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_perf_prog_read_value(struct bpf_perf_event_data *\fP\fIctx\fP\fB, struct bpf_perf_event_value *\fP\fIbuf\fP\fB, u32\fP \fIbuf_size\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +For an eBPF program attached to a perf event, retrieve the +value of the event counter associated to \fIctx\fP and store it in +the structure pointed by \fIbuf\fP and of size \fIbuf_size\fP\&. Enabled +and running times are also stored in the structure (see +description of helper \fBbpf_perf_event_read_value\fP() for +more details). +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_getsockopt(void *\fP\fIbpf_socket\fP\fB, int\fP \fIlevel\fP\fB, int\fP \fIoptname\fP\fB, void *\fP\fIoptval\fP\fB, int\fP \fIoptlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Emulate a call to \fBgetsockopt()\fP on the socket associated to +\fIbpf_socket\fP, which must be a full socket. The \fIlevel\fP at +which the option resides and the name \fIoptname\fP of the option +must be specified, see \fBgetsockopt(2)\fP for more information. +The retrieved value is stored in the structure pointed by +\fIopval\fP and of length \fIoptlen\fP\&. +.sp +\fIbpf_socket\fP should be one of the following: +.INDENT 7.0 +.IP \(bu 2 +\fBstruct bpf_sock_ops\fP for \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. +.IP \(bu 2 +\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP, +\fBBPF_CGROUP_INET6_CONNECT\fP and \fBBPF_CGROUP_UNIX_CONNECT\fP\&. +.UNINDENT +.sp +This helper actually implements a subset of \fBgetsockopt()\fP\&. +It supports the same set of \fIoptname\fPs that is supported by +the \fBbpf_setsockopt\fP() helper. The exceptions are +\fBTCP_BPF_*\fP is \fBbpf_setsockopt\fP() only and +\fBTCP_SAVED_SYN\fP is \fBbpf_getsockopt\fP() only. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_override_return(struct pt_regs *\fP\fIregs\fP\fB, u64\fP \fIrc\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Used for error injection, this helper uses kprobes to override +the return value of the probed function, and to set it to \fIrc\fP\&. +The first argument is the context \fIregs\fP on which the kprobe +works. +.sp +This helper works by setting the PC (program counter) +to an override function which is run in place of the original +probed function. This means the probed function is not run at +all. The replacement function just returns with the required +value. +.sp +This helper has security implications, and thus is subject to +restrictions. It is only available if the kernel was compiled +with the \fBCONFIG_BPF_KPROBE_OVERRIDE\fP configuration +option, and in this case it only works on functions tagged with +\fBALLOW_ERROR_INJECTION\fP in the kernel code. +.sp +Also, the helper is only available for the architectures having +the CONFIG_FUNCTION_ERROR_INJECTION option. As of this writing, +x86 architecture is the only one to support this feature. +.TP +.B Return +0 +.UNINDENT +.TP +.B \fBlong bpf_sock_ops_cb_flags_set(struct bpf_sock_ops *\fP\fIbpf_sock\fP\fB, int\fP \fIargval\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Attempt to set the value of the \fBbpf_sock_ops_cb_flags\fP field +for the full TCP socket associated to \fIbpf_sock_ops\fP to +\fIargval\fP\&. +.sp +The primary use of this field is to determine if there should +be calls to eBPF programs of type +\fBBPF_PROG_TYPE_SOCK_OPS\fP at various points in the TCP +code. A program of the same type can change its value, per +connection and as necessary, when the connection is +established. This field is directly accessible for reading, but +this helper must be used for updates in order to return an +error if an eBPF program tries to set a callback that is not +supported in the current kernel. +.sp +\fIargval\fP is a flag array which can combine these flags: +.INDENT 7.0 +.IP \(bu 2 +\fBBPF_SOCK_OPS_RTO_CB_FLAG\fP (retransmission time out) +.IP \(bu 2 +\fBBPF_SOCK_OPS_RETRANS_CB_FLAG\fP (retransmission) +.IP \(bu 2 +\fBBPF_SOCK_OPS_STATE_CB_FLAG\fP (TCP state change) +.IP \(bu 2 +\fBBPF_SOCK_OPS_RTT_CB_FLAG\fP (every RTT) +.UNINDENT +.sp +Therefore, this function can be used to clear a callback flag by +setting the appropriate bit to zero. e.g. to disable the RTO +callback: +.INDENT 7.0 +.TP +.B \fBbpf_sock_ops_cb_flags_set(bpf_sock,\fP +\fBbpf_sock\->bpf_sock_ops_cb_flags & ~BPF_SOCK_OPS_RTO_CB_FLAG)\fP +.UNINDENT +.sp +Here are some examples of where one could call such eBPF +program: +.INDENT 7.0 +.IP \(bu 2 +When RTO fires. +.IP \(bu 2 +When a packet is retransmitted. +.IP \(bu 2 +When the connection terminates. +.IP \(bu 2 +When a packet is sent. +.IP \(bu 2 +When a packet is received. +.UNINDENT +.TP +.B Return +Code \fB\-EINVAL\fP if the socket is not a full TCP socket; +otherwise, a positive number containing the bits that could not +be set is returned (which comes down to 0 if all bits were set +as required). +.UNINDENT +.TP +.B \fBlong bpf_msg_redirect_map(struct sk_msg_buff *\fP\fImsg\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u32\fP \fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper is used in programs implementing policies at the +socket level. If the message \fImsg\fP is allowed to pass (i.e. if +the verdict eBPF program returns \fBSK_PASS\fP), redirect it to +the socket referenced by \fImap\fP (of type +\fBBPF_MAP_TYPE_SOCKMAP\fP) at index \fIkey\fP\&. Both ingress and +egress interfaces can be used for redirection. The +\fBBPF_F_INGRESS\fP value in \fIflags\fP is used to make the +distinction (ingress path is selected if the flag is present, +egress path otherwise). This is the only flag supported for now. +.TP +.B Return +\fBSK_PASS\fP on success, or \fBSK_DROP\fP on error. +.UNINDENT +.TP +.B \fBlong bpf_msg_apply_bytes(struct sk_msg_buff *\fP\fImsg\fP\fB, u32\fP \fIbytes\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +For socket policies, apply the verdict of the eBPF program to +the next \fIbytes\fP (number of bytes) of message \fImsg\fP\&. +.sp +For example, this helper can be used in the following cases: +.INDENT 7.0 +.IP \(bu 2 +A single \fBsendmsg\fP() or \fBsendfile\fP() system call +contains multiple logical messages that the eBPF program is +supposed to read and for which it should apply a verdict. +.IP \(bu 2 +An eBPF program only cares to read the first \fIbytes\fP of a +\fImsg\fP\&. If the message has a large payload, then setting up +and calling the eBPF program repeatedly for all bytes, even +though the verdict is already known, would create unnecessary +overhead. +.UNINDENT +.sp +When called from within an eBPF program, the helper sets a +counter internal to the BPF infrastructure, that is used to +apply the last verdict to the next \fIbytes\fP\&. If \fIbytes\fP is +smaller than the current data being processed from a +\fBsendmsg\fP() or \fBsendfile\fP() system call, the first +\fIbytes\fP will be sent and the eBPF program will be re\-run with +the pointer for start of data pointing to byte number \fIbytes\fP +\fB+ 1\fP\&. If \fIbytes\fP is larger than the current data being +processed, then the eBPF verdict will be applied to multiple +\fBsendmsg\fP() or \fBsendfile\fP() calls until \fIbytes\fP are +consumed. +.sp +Note that if a socket closes with the internal counter holding +a non\-zero value, this is not a problem because data is not +being buffered for \fIbytes\fP and is sent as it is received. +.TP +.B Return +0 +.UNINDENT +.TP +.B \fBlong bpf_msg_cork_bytes(struct sk_msg_buff *\fP\fImsg\fP\fB, u32\fP \fIbytes\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +For socket policies, prevent the execution of the verdict eBPF +program for message \fImsg\fP until \fIbytes\fP (byte number) have been +accumulated. +.sp +This can be used when one needs a specific number of bytes +before a verdict can be assigned, even if the data spans +multiple \fBsendmsg\fP() or \fBsendfile\fP() calls. The extreme +case would be a user calling \fBsendmsg\fP() repeatedly with +1\-byte long message segments. Obviously, this is bad for +performance, but it is still valid. If the eBPF program needs +\fIbytes\fP bytes to validate a header, this helper can be used to +prevent the eBPF program to be called again until \fIbytes\fP have +been accumulated. +.TP +.B Return +0 +.UNINDENT +.TP +.B \fBlong bpf_msg_pull_data(struct sk_msg_buff *\fP\fImsg\fP\fB, u32\fP \fIstart\fP\fB, u32\fP \fIend\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +For socket policies, pull in non\-linear data from user space +for \fImsg\fP and set pointers \fImsg\fP\fB\->data\fP and \fImsg\fP\fB\->data_end\fP to \fIstart\fP and \fIend\fP bytes offsets into \fImsg\fP, +respectively. +.sp +If a program of type \fBBPF_PROG_TYPE_SK_MSG\fP is run on a +\fImsg\fP it can only parse data that the (\fBdata\fP, \fBdata_end\fP) +pointers have already consumed. For \fBsendmsg\fP() hooks this +is likely the first scatterlist element. But for calls relying +on the \fBsendpage\fP handler (e.g. \fBsendfile\fP()) this will +be the range (\fB0\fP, \fB0\fP) because the data is shared with +user space and by default the objective is to avoid allowing +user space to modify data while (or after) eBPF verdict is +being decided. This helper can be used to pull in data and to +set the start and end pointer to given values. Data will be +copied if necessary (i.e. if data was not linear and if start +and end pointers do not point to the same chunk). +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.sp +All values for \fIflags\fP are reserved for future usage, and must +be left at zero. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_bind(struct bpf_sock_addr *\fP\fIctx\fP\fB, struct sockaddr *\fP\fIaddr\fP\fB, int\fP \fIaddr_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Bind the socket associated to \fIctx\fP to the address pointed by +\fIaddr\fP, of length \fIaddr_len\fP\&. This allows for making outgoing +connection from the desired IP address, which can be useful for +example when all processes inside a cgroup should use one +single IP address on a host that has multiple IP configured. +.sp +This helper works for IPv4 and IPv6, TCP and UDP sockets. The +domain (\fIaddr\fP\fB\->sa_family\fP) must be \fBAF_INET\fP (or +\fBAF_INET6\fP). It\(aqs advised to pass zero port (\fBsin_port\fP +or \fBsin6_port\fP) which triggers IP_BIND_ADDRESS_NO_PORT\-like +behavior and lets the kernel efficiently pick up an unused +port as long as 4\-tuple is unique. Passing non\-zero port might +lead to degraded performance. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_xdp_adjust_tail(struct xdp_buff *\fP\fIxdp_md\fP\fB, int\fP \fIdelta\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Adjust (move) \fIxdp_md\fP\fB\->data_end\fP by \fIdelta\fP bytes. It is +possible to both shrink and grow the packet tail. +Shrink done via \fIdelta\fP being a negative integer. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_get_xfrm_state(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIindex\fP\fB, struct bpf_xfrm_state *\fP\fIxfrm_state\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Retrieve the XFRM state (IP transform framework, see also +\fBip\-xfrm(8)\fP) at \fIindex\fP in XFRM \(dqsecurity path\(dq for \fIskb\fP\&. +.sp +The retrieved value is stored in the \fBstruct bpf_xfrm_state\fP +pointed by \fIxfrm_state\fP and of length \fIsize\fP\&. +.sp +All values for \fIflags\fP are reserved for future usage, and must +be left at zero. +.sp +This helper is available only if the kernel was compiled with +\fBCONFIG_XFRM\fP configuration option. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_get_stack(void *\fP\fIctx\fP\fB, void *\fP\fIbuf\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Return a user or a kernel stack in bpf program provided buffer. +To achieve this, the helper needs \fIctx\fP, which is a pointer +to the context on which the tracing program is executed. +To store the stacktrace, the bpf program provides \fIbuf\fP with +a nonnegative \fIsize\fP\&. +.sp +The last argument, \fIflags\fP, holds the number of stack frames to +skip (from 0 to 255), masked with +\fBBPF_F_SKIP_FIELD_MASK\fP\&. The next bits can be used to set +the following flags: +.INDENT 7.0 +.TP +.B \fBBPF_F_USER_STACK\fP +Collect a user space stack instead of a kernel stack. +.TP +.B \fBBPF_F_USER_BUILD_ID\fP +Collect (build_id, file_offset) instead of ips for user +stack, only valid if \fBBPF_F_USER_STACK\fP is also +specified. +.sp +\fIfile_offset\fP is an offset relative to the beginning +of the executable or shared object file backing the vma +which the \fIip\fP falls in. It is \fInot\fP an offset relative +to that object\(aqs base address. Accordingly, it must be +adjusted by adding (sh_addr \- sh_offset), where +sh_{addr,offset} correspond to the executable section +containing \fIfile_offset\fP in the object, for comparisons +to symbols\(aq st_value to be valid. +.UNINDENT +.sp +\fBbpf_get_stack\fP() can collect up to +\fBPERF_MAX_STACK_DEPTH\fP both kernel and user frames, subject +to sufficient large buffer size. Note that +this limit can be controlled with the \fBsysctl\fP program, and +that it should be manually increased in order to profile long +user stacks (such as stacks for Java programs). To do so, use: +.INDENT 7.0 +.INDENT 3.5 +.sp +.EX +# sysctl kernel.perf_event_max_stack= +.EE +.UNINDENT +.UNINDENT +.TP +.B Return +The non\-negative copied \fIbuf\fP length equal to or less than +\fIsize\fP on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_load_bytes_relative(const void *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, void *\fP\fIto\fP\fB, u32\fP \fIlen\fP\fB, u32\fP \fIstart_header\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper is similar to \fBbpf_skb_load_bytes\fP() in that +it provides an easy way to load \fIlen\fP bytes from \fIoffset\fP +from the packet associated to \fIskb\fP, into the buffer pointed +by \fIto\fP\&. The difference to \fBbpf_skb_load_bytes\fP() is that +a fifth argument \fIstart_header\fP exists in order to select a +base offset to start from. \fIstart_header\fP can be one of: +.INDENT 7.0 +.TP +.B \fBBPF_HDR_START_MAC\fP +Base offset to load data from is \fIskb\fP\(aqs mac header. +.TP +.B \fBBPF_HDR_START_NET\fP +Base offset to load data from is \fIskb\fP\(aqs network header. +.UNINDENT +.sp +In general, \(dqdirect packet access\(dq is the preferred method to +access packet data, however, this helper is in particular useful +in socket filters where \fIskb\fP\fB\->data\fP does not always point +to the start of the mac header and where \(dqdirect packet access\(dq +is not available. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_fib_lookup(void *\fP\fIctx\fP\fB, struct bpf_fib_lookup *\fP\fIparams\fP\fB, int\fP \fIplen\fP\fB, u32\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Do FIB lookup in kernel tables using parameters in \fIparams\fP\&. +If lookup is successful and result shows packet is to be +forwarded, the neighbor tables are searched for the nexthop. +If successful (ie., FIB lookup shows forwarding and nexthop +is resolved), the nexthop address is returned in ipv4_dst +or ipv6_dst based on family, smac is set to mac address of +egress device, dmac is set to nexthop mac address, rt_metric +is set to metric from route (IPv4/IPv6 only), and ifindex +is set to the device index of the nexthop from the FIB lookup. +.sp +\fIplen\fP argument is the size of the passed in struct. +\fIflags\fP argument can be a combination of one or more of the +following values: +.INDENT 7.0 +.TP +.B \fBBPF_FIB_LOOKUP_DIRECT\fP +Do a direct table lookup vs full lookup using FIB +rules. +.TP +.B \fBBPF_FIB_LOOKUP_TBID\fP +Used with BPF_FIB_LOOKUP_DIRECT. +Use the routing table ID present in \fIparams\fP\->tbid +for the fib lookup. +.TP +.B \fBBPF_FIB_LOOKUP_OUTPUT\fP +Perform lookup from an egress perspective (default is +ingress). +.TP +.B \fBBPF_FIB_LOOKUP_SKIP_NEIGH\fP +Skip the neighbour table lookup. \fIparams\fP\->dmac +and \fIparams\fP\->smac will not be set as output. A common +use case is to call \fBbpf_redirect_neigh\fP() after +doing \fBbpf_fib_lookup\fP(). +.TP +.B \fBBPF_FIB_LOOKUP_SRC\fP +Derive and set source IP addr in \fIparams\fP\->ipv{4,6}_src +for the nexthop. If the src addr cannot be derived, +\fBBPF_FIB_LKUP_RET_NO_SRC_ADDR\fP is returned. In this +case, \fIparams\fP\->dmac and \fIparams\fP\->smac are not set either. +.UNINDENT +.sp +\fIctx\fP is either \fBstruct xdp_md\fP for XDP programs or +\fBstruct sk_buff\fP tc cls_act programs. +.TP +.B Return +.INDENT 7.0 +.IP \(bu 2 +< 0 if any input argument is invalid +.IP \(bu 2 +0 on success (packet is forwarded, nexthop neighbor exists) +.IP \(bu 2 +> 0 one of \fBBPF_FIB_LKUP_RET_\fP codes explaining why the +packet is not forwarded or needs assist from full stack +.UNINDENT +.sp +If lookup fails with BPF_FIB_LKUP_RET_FRAG_NEEDED, then the MTU +was exceeded and output params\->mtu_result contains the MTU. +.UNINDENT +.TP +.B \fBlong bpf_sock_hash_update(struct bpf_sock_ops *\fP\fIskops\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Add an entry to, or update a sockhash \fImap\fP referencing sockets. +The \fIskops\fP is used as a new value for the entry associated to +\fIkey\fP\&. \fIflags\fP is one of: +.INDENT 7.0 +.TP +.B \fBBPF_NOEXIST\fP +The entry for \fIkey\fP must not exist in the map. +.TP +.B \fBBPF_EXIST\fP +The entry for \fIkey\fP must already exist in the map. +.TP +.B \fBBPF_ANY\fP +No condition on the existence of the entry for \fIkey\fP\&. +.UNINDENT +.sp +If the \fImap\fP has eBPF programs (parser and verdict), those will +be inherited by the socket being added. If the socket is +already attached to eBPF programs, this results in an error. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_msg_redirect_hash(struct sk_msg_buff *\fP\fImsg\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper is used in programs implementing policies at the +socket level. If the message \fImsg\fP is allowed to pass (i.e. if +the verdict eBPF program returns \fBSK_PASS\fP), redirect it to +the socket referenced by \fImap\fP (of type +\fBBPF_MAP_TYPE_SOCKHASH\fP) using hash \fIkey\fP\&. Both ingress and +egress interfaces can be used for redirection. The +\fBBPF_F_INGRESS\fP value in \fIflags\fP is used to make the +distinction (ingress path is selected if the flag is present, +egress path otherwise). This is the only flag supported for now. +.TP +.B Return +\fBSK_PASS\fP on success, or \fBSK_DROP\fP on error. +.UNINDENT +.TP +.B \fBlong bpf_sk_redirect_hash(struct sk_buff *\fP\fIskb\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper is used in programs implementing policies at the +skb socket level. If the sk_buff \fIskb\fP is allowed to pass (i.e. +if the verdict eBPF program returns \fBSK_PASS\fP), redirect it +to the socket referenced by \fImap\fP (of type +\fBBPF_MAP_TYPE_SOCKHASH\fP) using hash \fIkey\fP\&. Both ingress and +egress interfaces can be used for redirection. The +\fBBPF_F_INGRESS\fP value in \fIflags\fP is used to make the +distinction (ingress path is selected if the flag is present, +egress otherwise). This is the only flag supported for now. +.TP +.B Return +\fBSK_PASS\fP on success, or \fBSK_DROP\fP on error. +.UNINDENT +.TP +.B \fBlong bpf_lwt_push_encap(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fItype\fP\fB, void *\fP\fIhdr\fP\fB, u32\fP \fIlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Encapsulate the packet associated to \fIskb\fP within a Layer 3 +protocol header. This header is provided in the buffer at +address \fIhdr\fP, with \fIlen\fP its size in bytes. \fItype\fP indicates +the protocol of the header and can be one of: +.INDENT 7.0 +.TP +.B \fBBPF_LWT_ENCAP_SEG6\fP +IPv6 encapsulation with Segment Routing Header +(\fBstruct ipv6_sr_hdr\fP). \fIhdr\fP only contains the SRH, +the IPv6 header is computed by the kernel. +.TP +.B \fBBPF_LWT_ENCAP_SEG6_INLINE\fP +Only works if \fIskb\fP contains an IPv6 packet. Insert a +Segment Routing Header (\fBstruct ipv6_sr_hdr\fP) inside +the IPv6 header. +.TP +.B \fBBPF_LWT_ENCAP_IP\fP +IP encapsulation (GRE/GUE/IPIP/etc). The outer header +must be IPv4 or IPv6, followed by zero or more +additional headers, up to \fBLWT_BPF_MAX_HEADROOM\fP +total bytes in all prepended headers. Please note that +if \fBskb_is_gso\fP(\fIskb\fP) is true, no more than two +headers can be prepended, and the inner header, if +present, should be either GRE or UDP/GUE. +.UNINDENT +.sp +\fBBPF_LWT_ENCAP_SEG6\fP* types can be called by BPF programs +of type \fBBPF_PROG_TYPE_LWT_IN\fP; \fBBPF_LWT_ENCAP_IP\fP type can +be called by bpf programs of types \fBBPF_PROG_TYPE_LWT_IN\fP and +\fBBPF_PROG_TYPE_LWT_XMIT\fP\&. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_lwt_seg6_store_bytes(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, const void *\fP\fIfrom\fP\fB, u32\fP \fIlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Store \fIlen\fP bytes from address \fIfrom\fP into the packet +associated to \fIskb\fP, at \fIoffset\fP\&. Only the flags, tag and TLVs +inside the outermost IPv6 Segment Routing Header can be +modified through this helper. +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_lwt_seg6_adjust_srh(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIoffset\fP\fB, s32\fP \fIdelta\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Adjust the size allocated to TLVs in the outermost IPv6 +Segment Routing Header contained in the packet associated to +\fIskb\fP, at position \fIoffset\fP by \fIdelta\fP bytes. Only offsets +after the segments are accepted. \fIdelta\fP can be as well +positive (growing) as negative (shrinking). +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_lwt_seg6_action(struct sk_buff *\fP\fIskb\fP\fB, u32\fP \fIaction\fP\fB, void *\fP\fIparam\fP\fB, u32\fP \fIparam_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Apply an IPv6 Segment Routing action of type \fIaction\fP to the +packet associated to \fIskb\fP\&. Each action takes a parameter +contained at address \fIparam\fP, and of length \fIparam_len\fP bytes. +\fIaction\fP can be one of: +.INDENT 7.0 +.TP +.B \fBSEG6_LOCAL_ACTION_END_X\fP +End.X action: Endpoint with Layer\-3 cross\-connect. +Type of \fIparam\fP: \fBstruct in6_addr\fP\&. +.TP +.B \fBSEG6_LOCAL_ACTION_END_T\fP +End.T action: Endpoint with specific IPv6 table lookup. +Type of \fIparam\fP: \fBint\fP\&. +.TP +.B \fBSEG6_LOCAL_ACTION_END_B6\fP +End.B6 action: Endpoint bound to an SRv6 policy. +Type of \fIparam\fP: \fBstruct ipv6_sr_hdr\fP\&. +.TP +.B \fBSEG6_LOCAL_ACTION_END_B6_ENCAP\fP +End.B6.Encap action: Endpoint bound to an SRv6 +encapsulation policy. +Type of \fIparam\fP: \fBstruct ipv6_sr_hdr\fP\&. +.UNINDENT +.sp +A call to this helper is susceptible to change the underlying +packet buffer. Therefore, at load time, all checks on pointers +previously done by the verifier are invalidated and must be +performed again, if the helper is used in combination with +direct packet access. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_rc_repeat(void *\fP\fIctx\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper is used in programs implementing IR decoding, to +report a successfully decoded repeat key message. This delays +the generation of a key up event for previously generated +key down event. +.sp +Some IR protocols like NEC have a special IR message for +repeating last button, for when a button is held down. +.sp +The \fIctx\fP should point to the lirc sample as passed into +the program. +.sp +This helper is only available is the kernel was compiled with +the \fBCONFIG_BPF_LIRC_MODE2\fP configuration option set to +\(dq\fBy\fP\(dq. +.TP +.B Return +0 +.UNINDENT +.TP +.B \fBlong bpf_rc_keydown(void *\fP\fIctx\fP\fB, u32\fP \fIprotocol\fP\fB, u64\fP \fIscancode\fP\fB, u32\fP \fItoggle\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper is used in programs implementing IR decoding, to +report a successfully decoded key press with \fIscancode\fP, +\fItoggle\fP value in the given \fIprotocol\fP\&. The scancode will be +translated to a keycode using the rc keymap, and reported as +an input key down event. After a period a key up event is +generated. This period can be extended by calling either +\fBbpf_rc_keydown\fP() again with the same values, or calling +\fBbpf_rc_repeat\fP(). +.sp +Some protocols include a toggle bit, in case the button was +released and pressed again between consecutive scancodes. +.sp +The \fIctx\fP should point to the lirc sample as passed into +the program. +.sp +The \fIprotocol\fP is the decoded protocol number (see +\fBenum rc_proto\fP for some predefined values). +.sp +This helper is only available is the kernel was compiled with +the \fBCONFIG_BPF_LIRC_MODE2\fP configuration option set to +\(dq\fBy\fP\(dq. +.TP +.B Return +0 +.UNINDENT +.TP +.B \fBu64 bpf_skb_cgroup_id(struct sk_buff *\fP\fIskb\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Return the cgroup v2 id of the socket associated with the \fIskb\fP\&. +This is roughly similar to the \fBbpf_get_cgroup_classid\fP() +helper for cgroup v1 by providing a tag resp. identifier that +can be matched on or used for map lookups e.g. to implement +policy. The cgroup v2 id of a given path in the hierarchy is +exposed in user space through the f_handle API in order to get +to the same 64\-bit id. +.sp +This helper can be used on TC egress path, but not on ingress, +and is available only if the kernel was compiled with the +\fBCONFIG_SOCK_CGROUP_DATA\fP configuration option. +.TP +.B Return +The id is returned or 0 in case the id could not be retrieved. +.UNINDENT +.TP +.B \fBu64 bpf_get_current_cgroup_id(void)\fP +.INDENT 7.0 +.TP +.B Description +Get the current cgroup id based on the cgroup within which +the current task is running. +.TP +.B Return +A 64\-bit integer containing the current cgroup id based +on the cgroup within which the current task is running. +.UNINDENT +.TP +.B \fBvoid *bpf_get_local_storage(void *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get the pointer to the local storage area. +The type and the size of the local storage is defined +by the \fImap\fP argument. +The \fIflags\fP meaning is specific for each map type, +and has to be 0 for cgroup local storage. +.sp +Depending on the BPF program type, a local storage area +can be shared between multiple instances of the BPF program, +running simultaneously. +.sp +A user should care about the synchronization by himself. +For example, by using the \fBBPF_ATOMIC\fP instructions to alter +the shared data. +.TP +.B Return +A pointer to the local storage area. +.UNINDENT +.TP +.B \fBlong bpf_sk_select_reuseport(struct sk_reuseport_md *\fP\fIreuse\fP\fB, struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIkey\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Select a \fBSO_REUSEPORT\fP socket from a +\fBBPF_MAP_TYPE_REUSEPORT_SOCKARRAY\fP \fImap\fP\&. +It checks the selected socket is matching the incoming +request in the socket buffer. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBu64 bpf_skb_ancestor_cgroup_id(struct sk_buff *\fP\fIskb\fP\fB, int\fP \fIancestor_level\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Return id of cgroup v2 that is ancestor of cgroup associated +with the \fIskb\fP at the \fIancestor_level\fP\&. The root cgroup is at +\fIancestor_level\fP zero and each step down the hierarchy +increments the level. If \fIancestor_level\fP == level of cgroup +associated with \fIskb\fP, then return value will be same as that +of \fBbpf_skb_cgroup_id\fP(). +.sp +The helper is useful to implement policies based on cgroups +that are upper in hierarchy than immediate cgroup associated +with \fIskb\fP\&. +.sp +The format of returned id and helper limitations are same as in +\fBbpf_skb_cgroup_id\fP(). +.TP +.B Return +The id is returned or 0 in case the id could not be retrieved. +.UNINDENT +.TP +.B \fBstruct bpf_sock *bpf_sk_lookup_tcp(void *\fP\fIctx\fP\fB, struct bpf_sock_tuple *\fP\fItuple\fP\fB, u32\fP \fItuple_size\fP\fB, u64\fP \fInetns\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Look for TCP socket matching \fItuple\fP, optionally in a child +network namespace \fInetns\fP\&. The return value must be checked, +and if non\-\fBNULL\fP, released via \fBbpf_sk_release\fP(). +.sp +The \fIctx\fP should point to the context of the program, such as +the skb or socket (depending on the hook in use). This is used +to determine the base network namespace for the lookup. +.sp +\fItuple_size\fP must be one of: +.INDENT 7.0 +.TP +.B \fBsizeof\fP(\fItuple\fP\fB\->ipv4\fP) +Look for an IPv4 socket. +.TP +.B \fBsizeof\fP(\fItuple\fP\fB\->ipv6\fP) +Look for an IPv6 socket. +.UNINDENT +.sp +If the \fInetns\fP is a negative signed 32\-bit integer, then the +socket lookup table in the netns associated with the \fIctx\fP +will be used. For the TC hooks, this is the netns of the device +in the skb. For socket hooks, this is the netns of the socket. +If \fInetns\fP is any other signed 32\-bit value greater than or +equal to zero then it specifies the ID of the netns relative to +the netns associated with the \fIctx\fP\&. \fInetns\fP values beyond the +range of 32\-bit integers are reserved for future use. +.sp +All values for \fIflags\fP are reserved for future usage, and must +be left at zero. +.sp +This helper is available only if the kernel was compiled with +\fBCONFIG_NET\fP configuration option. +.TP +.B Return +Pointer to \fBstruct bpf_sock\fP, or \fBNULL\fP in case of failure. +For sockets with reuseport option, the \fBstruct bpf_sock\fP +result is from \fIreuse\fP\fB\->socks\fP[] using the hash of the +tuple. +.UNINDENT +.TP +.B \fBstruct bpf_sock *bpf_sk_lookup_udp(void *\fP\fIctx\fP\fB, struct bpf_sock_tuple *\fP\fItuple\fP\fB, u32\fP \fItuple_size\fP\fB, u64\fP \fInetns\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Look for UDP socket matching \fItuple\fP, optionally in a child +network namespace \fInetns\fP\&. The return value must be checked, +and if non\-\fBNULL\fP, released via \fBbpf_sk_release\fP(). +.sp +The \fIctx\fP should point to the context of the program, such as +the skb or socket (depending on the hook in use). This is used +to determine the base network namespace for the lookup. +.sp +\fItuple_size\fP must be one of: +.INDENT 7.0 +.TP +.B \fBsizeof\fP(\fItuple\fP\fB\->ipv4\fP) +Look for an IPv4 socket. +.TP +.B \fBsizeof\fP(\fItuple\fP\fB\->ipv6\fP) +Look for an IPv6 socket. +.UNINDENT +.sp +If the \fInetns\fP is a negative signed 32\-bit integer, then the +socket lookup table in the netns associated with the \fIctx\fP +will be used. For the TC hooks, this is the netns of the device +in the skb. For socket hooks, this is the netns of the socket. +If \fInetns\fP is any other signed 32\-bit value greater than or +equal to zero then it specifies the ID of the netns relative to +the netns associated with the \fIctx\fP\&. \fInetns\fP values beyond the +range of 32\-bit integers are reserved for future use. +.sp +All values for \fIflags\fP are reserved for future usage, and must +be left at zero. +.sp +This helper is available only if the kernel was compiled with +\fBCONFIG_NET\fP configuration option. +.TP +.B Return +Pointer to \fBstruct bpf_sock\fP, or \fBNULL\fP in case of failure. +For sockets with reuseport option, the \fBstruct bpf_sock\fP +result is from \fIreuse\fP\fB\->socks\fP[] using the hash of the +tuple. +.UNINDENT +.TP +.B \fBlong bpf_sk_release(void *\fP\fIsock\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Release the reference held by \fIsock\fP\&. \fIsock\fP must be a +non\-\fBNULL\fP pointer that was returned from +\fBbpf_sk_lookup_xxx\fP(). +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_map_push_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIvalue\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Push an element \fIvalue\fP in \fImap\fP\&. \fIflags\fP is one of: +.INDENT 7.0 +.TP +.B \fBBPF_EXIST\fP +If the queue/stack is full, the oldest element is +removed to make room for this. +.UNINDENT +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_map_pop_elem(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIvalue\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Pop an element from \fImap\fP\&. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_map_peek_elem(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIvalue\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get an element from \fImap\fP without removing it. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_msg_push_data(struct sk_msg_buff *\fP\fImsg\fP\fB, u32\fP \fIstart\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +For socket policies, insert \fIlen\fP bytes into \fImsg\fP at offset +\fIstart\fP\&. +.sp +If a program of type \fBBPF_PROG_TYPE_SK_MSG\fP is run on a +\fImsg\fP it may want to insert metadata or options into the \fImsg\fP\&. +This can later be read and used by any of the lower layer BPF +hooks. +.sp +This helper may fail if under memory pressure (a malloc +fails) in these cases BPF programs will get an appropriate +error and BPF programs will need to handle them. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_msg_pop_data(struct sk_msg_buff *\fP\fImsg\fP\fB, u32\fP \fIstart\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Will remove \fIlen\fP bytes from a \fImsg\fP starting at byte \fIstart\fP\&. +This may result in \fBENOMEM\fP errors under certain situations if +an allocation and copy are required due to a full ring buffer. +However, the helper will try to avoid doing the allocation +if possible. Other errors can occur if input parameters are +invalid either due to \fIstart\fP byte not being valid part of \fImsg\fP +payload and/or \fIpop\fP value being to large. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_rc_pointer_rel(void *\fP\fIctx\fP\fB, s32\fP \fIrel_x\fP\fB, s32\fP \fIrel_y\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper is used in programs implementing IR decoding, to +report a successfully decoded pointer movement. +.sp +The \fIctx\fP should point to the lirc sample as passed into +the program. +.sp +This helper is only available is the kernel was compiled with +the \fBCONFIG_BPF_LIRC_MODE2\fP configuration option set to +\(dq\fBy\fP\(dq. +.TP +.B Return +0 +.UNINDENT +.TP +.B \fBlong bpf_spin_lock(struct bpf_spin_lock *\fP\fIlock\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Acquire a spinlock represented by the pointer \fIlock\fP, which is +stored as part of a value of a map. Taking the lock allows to +safely update the rest of the fields in that value. The +spinlock can (and must) later be released with a call to +\fBbpf_spin_unlock\fP(\fIlock\fP). +.sp +Spinlocks in BPF programs come with a number of restrictions +and constraints: +.INDENT 7.0 +.IP \(bu 2 +\fBbpf_spin_lock\fP objects are only allowed inside maps of +types \fBBPF_MAP_TYPE_HASH\fP and \fBBPF_MAP_TYPE_ARRAY\fP (this +list could be extended in the future). +.IP \(bu 2 +BTF description of the map is mandatory. +.IP \(bu 2 +The BPF program can take ONE lock at a time, since taking two +or more could cause dead locks. +.IP \(bu 2 +Only one \fBstruct bpf_spin_lock\fP is allowed per map element. +.IP \(bu 2 +When the lock is taken, calls (either BPF to BPF or helpers) +are not allowed. +.IP \(bu 2 +The \fBBPF_LD_ABS\fP and \fBBPF_LD_IND\fP instructions are not +allowed inside a spinlock\-ed region. +.IP \(bu 2 +The BPF program MUST call \fBbpf_spin_unlock\fP() to release +the lock, on all execution paths, before it returns. +.IP \(bu 2 +The BPF program can access \fBstruct bpf_spin_lock\fP only via +the \fBbpf_spin_lock\fP() and \fBbpf_spin_unlock\fP() +helpers. Loading or storing data into the \fBstruct +bpf_spin_lock\fP \fIlock\fP\fB;\fP field of a map is not allowed. +.IP \(bu 2 +To use the \fBbpf_spin_lock\fP() helper, the BTF description +of the map value must be a struct and have \fBstruct +bpf_spin_lock\fP \fIanyname\fP\fB;\fP field at the top level. +Nested lock inside another struct is not allowed. +.IP \(bu 2 +The \fBstruct bpf_spin_lock\fP \fIlock\fP field in a map value must +be aligned on a multiple of 4 bytes in that value. +.IP \(bu 2 +Syscall with command \fBBPF_MAP_LOOKUP_ELEM\fP does not copy +the \fBbpf_spin_lock\fP field to user space. +.IP \(bu 2 +Syscall with command \fBBPF_MAP_UPDATE_ELEM\fP, or update from +a BPF program, do not update the \fBbpf_spin_lock\fP field. +.IP \(bu 2 +\fBbpf_spin_lock\fP cannot be on the stack or inside a +networking packet (it can only be inside of a map values). +.IP \(bu 2 +\fBbpf_spin_lock\fP is available to root only. +.IP \(bu 2 +Tracing programs and socket filter programs cannot use +\fBbpf_spin_lock\fP() due to insufficient preemption checks +(but this may change in the future). +.IP \(bu 2 +\fBbpf_spin_lock\fP is not allowed in inner maps of map\-in\-map. +.UNINDENT +.TP +.B Return +0 +.UNINDENT +.TP +.B \fBlong bpf_spin_unlock(struct bpf_spin_lock *\fP\fIlock\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Release the \fIlock\fP previously locked by a call to +\fBbpf_spin_lock\fP(\fIlock\fP). +.TP +.B Return +0 +.UNINDENT +.TP +.B \fBstruct bpf_sock *bpf_sk_fullsock(struct bpf_sock *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper gets a \fBstruct bpf_sock\fP pointer such +that all the fields in this \fBbpf_sock\fP can be accessed. +.TP +.B Return +A \fBstruct bpf_sock\fP pointer on success, or \fBNULL\fP in +case of failure. +.UNINDENT +.TP +.B \fBstruct bpf_tcp_sock *bpf_tcp_sock(struct bpf_sock *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper gets a \fBstruct bpf_tcp_sock\fP pointer from a +\fBstruct bpf_sock\fP pointer. +.TP +.B Return +A \fBstruct bpf_tcp_sock\fP pointer on success, or \fBNULL\fP in +case of failure. +.UNINDENT +.TP +.B \fBlong bpf_skb_ecn_set_ce(struct sk_buff *\fP\fIskb\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Set ECN (Explicit Congestion Notification) field of IP header +to \fBCE\fP (Congestion Encountered) if current value is \fBECT\fP +(ECN Capable Transport). Otherwise, do nothing. Works with IPv6 +and IPv4. +.TP +.B Return +1 if the \fBCE\fP flag is set (either by the current helper call +or because it was already present), 0 if it is not set. +.UNINDENT +.TP +.B \fBstruct bpf_sock *bpf_get_listener_sock(struct bpf_sock *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Return a \fBstruct bpf_sock\fP pointer in \fBTCP_LISTEN\fP state. +\fBbpf_sk_release\fP() is unnecessary and not allowed. +.TP +.B Return +A \fBstruct bpf_sock\fP pointer on success, or \fBNULL\fP in +case of failure. +.UNINDENT +.TP +.B \fBstruct bpf_sock *bpf_skc_lookup_tcp(void *\fP\fIctx\fP\fB, struct bpf_sock_tuple *\fP\fItuple\fP\fB, u32\fP \fItuple_size\fP\fB, u64\fP \fInetns\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Look for TCP socket matching \fItuple\fP, optionally in a child +network namespace \fInetns\fP\&. The return value must be checked, +and if non\-\fBNULL\fP, released via \fBbpf_sk_release\fP(). +.sp +This function is identical to \fBbpf_sk_lookup_tcp\fP(), except +that it also returns timewait or request sockets. Use +\fBbpf_sk_fullsock\fP() or \fBbpf_tcp_sock\fP() to access the +full structure. +.sp +This helper is available only if the kernel was compiled with +\fBCONFIG_NET\fP configuration option. +.TP +.B Return +Pointer to \fBstruct bpf_sock\fP, or \fBNULL\fP in case of failure. +For sockets with reuseport option, the \fBstruct bpf_sock\fP +result is from \fIreuse\fP\fB\->socks\fP[] using the hash of the +tuple. +.UNINDENT +.TP +.B \fBlong bpf_tcp_check_syncookie(void *\fP\fIsk\fP\fB, void *\fP\fIiph\fP\fB, u32\fP \fIiph_len\fP\fB, struct tcphdr *\fP\fIth\fP\fB, u32\fP \fIth_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Check whether \fIiph\fP and \fIth\fP contain a valid SYN cookie ACK for +the listening socket in \fIsk\fP\&. +.sp +\fIiph\fP points to the start of the IPv4 or IPv6 header, while +\fIiph_len\fP contains \fBsizeof\fP(\fBstruct iphdr\fP) or +\fBsizeof\fP(\fBstruct ipv6hdr\fP). +.sp +\fIth\fP points to the start of the TCP header, while \fIth_len\fP +contains the length of the TCP header (at least +\fBsizeof\fP(\fBstruct tcphdr\fP)). +.TP +.B Return +0 if \fIiph\fP and \fIth\fP are a valid SYN cookie ACK, or a negative +error otherwise. +.UNINDENT +.TP +.B \fBlong bpf_sysctl_get_name(struct bpf_sysctl *\fP\fIctx\fP\fB, char *\fP\fIbuf\fP\fB, size_t\fP \fIbuf_len\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get name of sysctl in /proc/sys/ and copy it into provided by +program buffer \fIbuf\fP of size \fIbuf_len\fP\&. +.sp +The buffer is always NUL terminated, unless it\(aqs zero\-sized. +.sp +If \fIflags\fP is zero, full name (e.g. \(dqnet/ipv4/tcp_mem\(dq) is +copied. Use \fBBPF_F_SYSCTL_BASE_NAME\fP flag to copy base name +only (e.g. \(dqtcp_mem\(dq). +.TP +.B Return +Number of character copied (not including the trailing NUL). +.sp +\fB\-E2BIG\fP if the buffer wasn\(aqt big enough (\fIbuf\fP will contain +truncated name in this case). +.UNINDENT +.TP +.B \fBlong bpf_sysctl_get_current_value(struct bpf_sysctl *\fP\fIctx\fP\fB, char *\fP\fIbuf\fP\fB, size_t\fP \fIbuf_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get current value of sysctl as it is presented in /proc/sys +(incl. newline, etc), and copy it as a string into provided +by program buffer \fIbuf\fP of size \fIbuf_len\fP\&. +.sp +The whole value is copied, no matter what file position user +space issued e.g. sys_read at. +.sp +The buffer is always NUL terminated, unless it\(aqs zero\-sized. +.TP +.B Return +Number of character copied (not including the trailing NUL). +.sp +\fB\-E2BIG\fP if the buffer wasn\(aqt big enough (\fIbuf\fP will contain +truncated name in this case). +.sp +\fB\-EINVAL\fP if current value was unavailable, e.g. because +sysctl is uninitialized and read returns \-EIO for it. +.UNINDENT +.TP +.B \fBlong bpf_sysctl_get_new_value(struct bpf_sysctl *\fP\fIctx\fP\fB, char *\fP\fIbuf\fP\fB, size_t\fP \fIbuf_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get new value being written by user space to sysctl (before +the actual write happens) and copy it as a string into +provided by program buffer \fIbuf\fP of size \fIbuf_len\fP\&. +.sp +User space may write new value at file position > 0. +.sp +The buffer is always NUL terminated, unless it\(aqs zero\-sized. +.TP +.B Return +Number of character copied (not including the trailing NUL). +.sp +\fB\-E2BIG\fP if the buffer wasn\(aqt big enough (\fIbuf\fP will contain +truncated name in this case). +.sp +\fB\-EINVAL\fP if sysctl is being read. +.UNINDENT +.TP +.B \fBlong bpf_sysctl_set_new_value(struct bpf_sysctl *\fP\fIctx\fP\fB, const char *\fP\fIbuf\fP\fB, size_t\fP \fIbuf_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Override new value being written by user space to sysctl with +value provided by program in buffer \fIbuf\fP of size \fIbuf_len\fP\&. +.sp +\fIbuf\fP should contain a string in same form as provided by user +space on sysctl write. +.sp +User space may write new value at file position > 0. To override +the whole sysctl value file position should be set to zero. +.TP +.B Return +0 on success. +.sp +\fB\-E2BIG\fP if the \fIbuf_len\fP is too big. +.sp +\fB\-EINVAL\fP if sysctl is being read. +.UNINDENT +.TP +.B \fBlong bpf_strtol(const char *\fP\fIbuf\fP\fB, size_t\fP \fIbuf_len\fP\fB, u64\fP \fIflags\fP\fB, long *\fP\fIres\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Convert the initial part of the string from buffer \fIbuf\fP of +size \fIbuf_len\fP to a long integer according to the given base +and save the result in \fIres\fP\&. +.sp +The string may begin with an arbitrary amount of white space +(as determined by \fBisspace\fP(3)) followed by a single +optional \(aq\fB\-\fP\(aq sign. +.sp +Five least significant bits of \fIflags\fP encode base, other bits +are currently unused. +.sp +Base must be either 8, 10, 16 or 0 to detect it automatically +similar to user space \fBstrtol\fP(3). +.TP +.B Return +Number of characters consumed on success. Must be positive but +no more than \fIbuf_len\fP\&. +.sp +\fB\-EINVAL\fP if no valid digits were found or unsupported base +was provided. +.sp +\fB\-ERANGE\fP if resulting value was out of range. +.UNINDENT +.TP +.B \fBlong bpf_strtoul(const char *\fP\fIbuf\fP\fB, size_t\fP \fIbuf_len\fP\fB, u64\fP \fIflags\fP\fB, unsigned long *\fP\fIres\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Convert the initial part of the string from buffer \fIbuf\fP of +size \fIbuf_len\fP to an unsigned long integer according to the +given base and save the result in \fIres\fP\&. +.sp +The string may begin with an arbitrary amount of white space +(as determined by \fBisspace\fP(3)). +.sp +Five least significant bits of \fIflags\fP encode base, other bits +are currently unused. +.sp +Base must be either 8, 10, 16 or 0 to detect it automatically +similar to user space \fBstrtoul\fP(3). +.TP +.B Return +Number of characters consumed on success. Must be positive but +no more than \fIbuf_len\fP\&. +.sp +\fB\-EINVAL\fP if no valid digits were found or unsupported base +was provided. +.sp +\fB\-ERANGE\fP if resulting value was out of range. +.UNINDENT +.TP +.B \fBvoid *bpf_sk_storage_get(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIsk\fP\fB, void *\fP\fIvalue\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get a bpf\-local\-storage from a \fIsk\fP\&. +.sp +Logically, it could be thought of getting the value from +a \fImap\fP with \fIsk\fP as the \fBkey\fP\&. From this +perspective, the usage is not much different from +\fBbpf_map_lookup_elem\fP(\fImap\fP, \fB&\fP\fIsk\fP) except this +helper enforces the key must be a full socket and the map must +be a \fBBPF_MAP_TYPE_SK_STORAGE\fP also. +.sp +Underneath, the value is stored locally at \fIsk\fP instead of +the \fImap\fP\&. The \fImap\fP is used as the bpf\-local\-storage +\(dqtype\(dq. The bpf\-local\-storage \(dqtype\(dq (i.e. the \fImap\fP) is +searched against all bpf\-local\-storages residing at \fIsk\fP\&. +.sp +\fIsk\fP is a kernel \fBstruct sock\fP pointer for LSM program. +\fIsk\fP is a \fBstruct bpf_sock\fP pointer for other program types. +.sp +An optional \fIflags\fP (\fBBPF_SK_STORAGE_GET_F_CREATE\fP) can be +used such that a new bpf\-local\-storage will be +created if one does not exist. \fIvalue\fP can be used +together with \fBBPF_SK_STORAGE_GET_F_CREATE\fP to specify +the initial value of a bpf\-local\-storage. If \fIvalue\fP is +\fBNULL\fP, the new bpf\-local\-storage will be zero initialized. +.TP +.B Return +A bpf\-local\-storage pointer is returned on success. +.sp +\fBNULL\fP if not found or there was an error in adding +a new bpf\-local\-storage. +.UNINDENT +.TP +.B \fBlong bpf_sk_storage_delete(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Delete a bpf\-local\-storage from a \fIsk\fP\&. +.TP +.B Return +0 on success. +.sp +\fB\-ENOENT\fP if the bpf\-local\-storage cannot be found. +\fB\-EINVAL\fP if sk is not a fullsock (e.g. a request_sock). +.UNINDENT +.TP +.B \fBlong bpf_send_signal(u32\fP \fIsig\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Send signal \fIsig\fP to the process of the current task. +The signal may be delivered to any of this process\(aqs threads. +.TP +.B Return +0 on success or successfully queued. +.sp +\fB\-EBUSY\fP if work queue under nmi is full. +.sp +\fB\-EINVAL\fP if \fIsig\fP is invalid. +.sp +\fB\-EPERM\fP if no permission to send the \fIsig\fP\&. +.sp +\fB\-EAGAIN\fP if bpf program can try again. +.UNINDENT +.TP +.B \fBs64 bpf_tcp_gen_syncookie(void *\fP\fIsk\fP\fB, void *\fP\fIiph\fP\fB, u32\fP \fIiph_len\fP\fB, struct tcphdr *\fP\fIth\fP\fB, u32\fP \fIth_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Try to issue a SYN cookie for the packet with corresponding +IP/TCP headers, \fIiph\fP and \fIth\fP, on the listening socket in \fIsk\fP\&. +.sp +\fIiph\fP points to the start of the IPv4 or IPv6 header, while +\fIiph_len\fP contains \fBsizeof\fP(\fBstruct iphdr\fP) or +\fBsizeof\fP(\fBstruct ipv6hdr\fP). +.sp +\fIth\fP points to the start of the TCP header, while \fIth_len\fP +contains the length of the TCP header with options (at least +\fBsizeof\fP(\fBstruct tcphdr\fP)). +.TP +.B Return +On success, lower 32 bits hold the generated SYN cookie in +followed by 16 bits which hold the MSS value for that cookie, +and the top 16 bits are unused. +.sp +On failure, the returned value is one of the following: +.sp +\fB\-EINVAL\fP SYN cookie cannot be issued due to error +.sp +\fB\-ENOENT\fP SYN cookie should not be issued (no SYN flood) +.sp +\fB\-EOPNOTSUPP\fP kernel configuration does not enable SYN cookies +.sp +\fB\-EPROTONOSUPPORT\fP IP packet version is not 4 or 6 +.UNINDENT +.TP +.B \fBlong bpf_skb_output(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64\fP \fIsize\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Write raw \fIdata\fP blob into a special BPF perf event held by +\fImap\fP of type \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. This perf +event must have the following attributes: \fBPERF_SAMPLE_RAW\fP +as \fBsample_type\fP, \fBPERF_TYPE_SOFTWARE\fP as \fBtype\fP, and +\fBPERF_COUNT_SW_BPF_OUTPUT\fP as \fBconfig\fP\&. +.sp +The \fIflags\fP are used to indicate the index in \fImap\fP for which +the value must be put, masked with \fBBPF_F_INDEX_MASK\fP\&. +Alternatively, \fIflags\fP can be set to \fBBPF_F_CURRENT_CPU\fP +to indicate that the index of the current CPU core should be +used. +.sp +The value to write, of \fIsize\fP, is passed through eBPF stack and +pointed by \fIdata\fP\&. +.sp +\fIctx\fP is a pointer to in\-kernel struct sk_buff. +.sp +This helper is similar to \fBbpf_perf_event_output\fP() but +restricted to raw_tracepoint bpf programs. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_probe_read_user(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Safely attempt to read \fIsize\fP bytes from user space address +\fIunsafe_ptr\fP and store the data in \fIdst\fP\&. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_probe_read_kernel(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Safely attempt to read \fIsize\fP bytes from kernel space address +\fIunsafe_ptr\fP and store the data in \fIdst\fP\&. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_probe_read_user_str(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Copy a NUL terminated string from an unsafe user address +\fIunsafe_ptr\fP to \fIdst\fP\&. The \fIsize\fP should include the +terminating NUL byte. In case the string length is smaller than +\fIsize\fP, the target is not padded with further NUL bytes. If the +string length is larger than \fIsize\fP, just \fIsize\fP\-1 bytes are +copied and the last byte is set to NUL. +.sp +On success, returns the number of bytes that were written, +including the terminal NUL. This makes this helper useful in +tracing programs for reading strings, and more importantly to +get its length at runtime. See the following snippet: +.INDENT 7.0 +.INDENT 3.5 +.sp +.EX +SEC(\(dqkprobe/sys_open\(dq) +void bpf_sys_open(struct pt_regs *ctx) +{ + char buf[PATHLEN]; // PATHLEN is defined to 256 + int res = bpf_probe_read_user_str(buf, sizeof(buf), + ctx\->di); + + // Consume buf, for example push it to + // userspace via bpf_perf_event_output(); we + // can use res (the string length) as event + // size, after checking its boundaries. +} +.EE +.UNINDENT +.UNINDENT +.sp +In comparison, using \fBbpf_probe_read_user\fP() helper here +instead to read the string would require to estimate the length +at compile time, and would often result in copying more memory +than necessary. +.sp +Another useful use case is when parsing individual process +arguments or individual environment variables navigating +\fIcurrent\fP\fB\->mm\->arg_start\fP and \fIcurrent\fP\fB\->mm\->env_start\fP: using this helper and the return value, +one can quickly iterate at the right offset of the memory area. +.TP +.B Return +On success, the strictly positive length of the output string, +including the trailing NUL character. On error, a negative +value. +.UNINDENT +.TP +.B \fBlong bpf_probe_read_kernel_str(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIunsafe_ptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Copy a NUL terminated string from an unsafe kernel address \fIunsafe_ptr\fP +to \fIdst\fP\&. Same semantics as with \fBbpf_probe_read_user_str\fP() apply. +.TP +.B Return +On success, the strictly positive length of the string, including +the trailing NUL character. On error, a negative value. +.UNINDENT +.TP +.B \fBlong bpf_tcp_send_ack(void *\fP\fItp\fP\fB, u32\fP \fIrcv_nxt\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Send out a tcp\-ack. \fItp\fP is the in\-kernel struct \fBtcp_sock\fP\&. +\fIrcv_nxt\fP is the ack_seq to be sent out. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_send_signal_thread(u32\fP \fIsig\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Send signal \fIsig\fP to the thread corresponding to the current task. +.TP +.B Return +0 on success or successfully queued. +.sp +\fB\-EBUSY\fP if work queue under nmi is full. +.sp +\fB\-EINVAL\fP if \fIsig\fP is invalid. +.sp +\fB\-EPERM\fP if no permission to send the \fIsig\fP\&. +.sp +\fB\-EAGAIN\fP if bpf program can try again. +.UNINDENT +.TP +.B \fBu64 bpf_jiffies64(void)\fP +.INDENT 7.0 +.TP +.B Description +Obtain the 64bit jiffies +.TP +.B Return +The 64 bit jiffies +.UNINDENT +.TP +.B \fBlong bpf_read_branch_records(struct bpf_perf_event_data *\fP\fIctx\fP\fB, void *\fP\fIbuf\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +For an eBPF program attached to a perf event, retrieve the +branch records (\fBstruct perf_branch_entry\fP) associated to \fIctx\fP +and store it in the buffer pointed by \fIbuf\fP up to size +\fIsize\fP bytes. +.TP +.B Return +On success, number of bytes written to \fIbuf\fP\&. On error, a +negative value. +.sp +The \fIflags\fP can be set to \fBBPF_F_GET_BRANCH_RECORDS_SIZE\fP to +instead return the number of bytes required to store all the +branch entries. If this flag is set, \fIbuf\fP may be NULL. +.sp +\fB\-EINVAL\fP if arguments invalid or \fBsize\fP not a multiple +of \fBsizeof\fP(\fBstruct perf_branch_entry\fP). +.sp +\fB\-ENOENT\fP if architecture does not support branch records. +.UNINDENT +.TP +.B \fBlong bpf_get_ns_current_pid_tgid(u64\fP \fIdev\fP\fB, u64\fP \fIino\fP\fB, struct bpf_pidns_info *\fP\fInsdata\fP\fB, u32\fP \fIsize\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Returns 0 on success, values for \fIpid\fP and \fItgid\fP as seen from the current +\fInamespace\fP will be returned in \fInsdata\fP\&. +.TP +.B Return +0 on success, or one of the following in case of failure: +.sp +\fB\-EINVAL\fP if dev and inum supplied don\(aqt match dev_t and inode number +with nsfs of current task, or if dev conversion to dev_t lost high bits. +.sp +\fB\-ENOENT\fP if pidns does not exists for the current task. +.UNINDENT +.TP +.B \fBlong bpf_xdp_output(void *\fP\fIctx\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB, void *\fP\fIdata\fP\fB, u64\fP \fIsize\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Write raw \fIdata\fP blob into a special BPF perf event held by +\fImap\fP of type \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. This perf +event must have the following attributes: \fBPERF_SAMPLE_RAW\fP +as \fBsample_type\fP, \fBPERF_TYPE_SOFTWARE\fP as \fBtype\fP, and +\fBPERF_COUNT_SW_BPF_OUTPUT\fP as \fBconfig\fP\&. +.sp +The \fIflags\fP are used to indicate the index in \fImap\fP for which +the value must be put, masked with \fBBPF_F_INDEX_MASK\fP\&. +Alternatively, \fIflags\fP can be set to \fBBPF_F_CURRENT_CPU\fP +to indicate that the index of the current CPU core should be +used. +.sp +The value to write, of \fIsize\fP, is passed through eBPF stack and +pointed by \fIdata\fP\&. +.sp +\fIctx\fP is a pointer to in\-kernel struct xdp_buff. +.sp +This helper is similar to \fBbpf_perf_eventoutput\fP() but +restricted to raw_tracepoint bpf programs. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBu64 bpf_get_netns_cookie(void *\fP\fIctx\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Retrieve the cookie (generated by the kernel) of the network +namespace the input \fIctx\fP is associated with. The network +namespace cookie remains stable for its lifetime and provides +a global identifier that can be assumed unique. If \fIctx\fP is +NULL, then the helper returns the cookie for the initial +network namespace. The cookie itself is very similar to that +of \fBbpf_get_socket_cookie\fP() helper, but for network +namespaces instead of sockets. +.TP +.B Return +A 8\-byte long opaque number. +.UNINDENT +.TP +.B \fBu64 bpf_get_current_ancestor_cgroup_id(int\fP \fIancestor_level\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Return id of cgroup v2 that is ancestor of the cgroup associated +with the current task at the \fIancestor_level\fP\&. The root cgroup +is at \fIancestor_level\fP zero and each step down the hierarchy +increments the level. If \fIancestor_level\fP == level of cgroup +associated with the current task, then return value will be the +same as that of \fBbpf_get_current_cgroup_id\fP(). +.sp +The helper is useful to implement policies based on cgroups +that are upper in hierarchy than immediate cgroup associated +with the current task. +.sp +The format of returned id and helper limitations are same as in +\fBbpf_get_current_cgroup_id\fP(). +.TP +.B Return +The id is returned or 0 in case the id could not be retrieved. +.UNINDENT +.TP +.B \fBlong bpf_sk_assign(struct sk_buff *\fP\fIskb\fP\fB, void *\fP\fIsk\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Helper is overloaded depending on BPF program type. This +description applies to \fBBPF_PROG_TYPE_SCHED_CLS\fP and +\fBBPF_PROG_TYPE_SCHED_ACT\fP programs. +.sp +Assign the \fIsk\fP to the \fIskb\fP\&. When combined with appropriate +routing configuration to receive the packet towards the socket, +will cause \fIskb\fP to be delivered to the specified socket. +Subsequent redirection of \fIskb\fP via \fBbpf_redirect\fP(), +\fBbpf_clone_redirect\fP() or other methods outside of BPF may +interfere with successful delivery to the socket. +.sp +This operation is only valid from TC ingress path. +.sp +The \fIflags\fP argument must be zero. +.TP +.B Return +0 on success, or a negative error in case of failure: +.sp +\fB\-EINVAL\fP if specified \fIflags\fP are not supported. +.sp +\fB\-ENOENT\fP if the socket is unavailable for assignment. +.sp +\fB\-ENETUNREACH\fP if the socket is unreachable (wrong netns). +.sp +\fB\-EOPNOTSUPP\fP if the operation is not supported, for example +a call from outside of TC ingress. +.UNINDENT +.TP +.B \fBlong bpf_sk_assign(struct bpf_sk_lookup *\fP\fIctx\fP\fB, struct bpf_sock *\fP\fIsk\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Helper is overloaded depending on BPF program type. This +description applies to \fBBPF_PROG_TYPE_SK_LOOKUP\fP programs. +.sp +Select the \fIsk\fP as a result of a socket lookup. +.sp +For the operation to succeed passed socket must be compatible +with the packet description provided by the \fIctx\fP object. +.sp +L4 protocol (\fBIPPROTO_TCP\fP or \fBIPPROTO_UDP\fP) must +be an exact match. While IP family (\fBAF_INET\fP or +\fBAF_INET6\fP) must be compatible, that is IPv6 sockets +that are not v6\-only can be selected for IPv4 packets. +.sp +Only TCP listeners and UDP unconnected sockets can be +selected. \fIsk\fP can also be NULL to reset any previous +selection. +.sp +\fIflags\fP argument can combination of following values: +.INDENT 7.0 +.IP \(bu 2 +\fBBPF_SK_LOOKUP_F_REPLACE\fP to override the previous +socket selection, potentially done by a BPF program +that ran before us. +.IP \(bu 2 +\fBBPF_SK_LOOKUP_F_NO_REUSEPORT\fP to skip +load\-balancing within reuseport group for the socket +being selected. +.UNINDENT +.sp +On success \fIctx\->sk\fP will point to the selected socket. +.TP +.B Return +0 on success, or a negative errno in case of failure. +.INDENT 7.0 +.IP \(bu 2 +\fB\-EAFNOSUPPORT\fP if socket family (\fIsk\->family\fP) is +not compatible with packet family (\fIctx\->family\fP). +.IP \(bu 2 +\fB\-EEXIST\fP if socket has been already selected, +potentially by another program, and +\fBBPF_SK_LOOKUP_F_REPLACE\fP flag was not specified. +.IP \(bu 2 +\fB\-EINVAL\fP if unsupported flags were specified. +.IP \(bu 2 +\fB\-EPROTOTYPE\fP if socket L4 protocol +(\fIsk\->protocol\fP) doesn\(aqt match packet protocol +(\fIctx\->protocol\fP). +.IP \(bu 2 +\fB\-ESOCKTNOSUPPORT\fP if socket is not in allowed +state (TCP listening or UDP unconnected). +.UNINDENT +.UNINDENT +.TP +.B \fBu64 bpf_ktime_get_boot_ns(void)\fP +.INDENT 7.0 +.TP +.B Description +Return the time elapsed since system boot, in nanoseconds. +Does include the time the system was suspended. +See: \fBclock_gettime\fP(\fBCLOCK_BOOTTIME\fP) +.TP +.B Return +Current \fIktime\fP\&. +.UNINDENT +.TP +.B \fBlong bpf_seq_printf(struct seq_file *\fP\fIm\fP\fB, const char *\fP\fIfmt\fP\fB, u32\fP \fIfmt_size\fP\fB, const void *\fP\fIdata\fP\fB, u32\fP \fIdata_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +\fBbpf_seq_printf\fP() uses seq_file \fBseq_printf\fP() to print +out the format string. +The \fIm\fP represents the seq_file. The \fIfmt\fP and \fIfmt_size\fP are for +the format string itself. The \fIdata\fP and \fIdata_len\fP are format string +arguments. The \fIdata\fP are a \fBu64\fP array and corresponding format string +values are stored in the array. For strings and pointers where pointees +are accessed, only the pointer values are stored in the \fIdata\fP array. +The \fIdata_len\fP is the size of \fIdata\fP in bytes \- must be a multiple of 8. +.sp +Formats \fB%s\fP, \fB%p{i,I}{4,6}\fP requires to read kernel memory. +Reading kernel memory may fail due to either invalid address or +valid address but requiring a major memory fault. If reading kernel memory +fails, the string for \fB%s\fP will be an empty string, and the ip +address for \fB%p{i,I}{4,6}\fP will be 0. Not returning error to +bpf program is consistent with what \fBbpf_trace_printk\fP() does for now. +.TP +.B Return +0 on success, or a negative error in case of failure: +.sp +\fB\-EBUSY\fP if per\-CPU memory copy buffer is busy, can try again +by returning 1 from bpf program. +.sp +\fB\-EINVAL\fP if arguments are invalid, or if \fIfmt\fP is invalid/unsupported. +.sp +\fB\-E2BIG\fP if \fIfmt\fP contains too many format specifiers. +.sp +\fB\-EOVERFLOW\fP if an overflow happened: The same object will be tried again. +.UNINDENT +.TP +.B \fBlong bpf_seq_write(struct seq_file *\fP\fIm\fP\fB, const void *\fP\fIdata\fP\fB, u32\fP \fIlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +\fBbpf_seq_write\fP() uses seq_file \fBseq_write\fP() to write the data. +The \fIm\fP represents the seq_file. The \fIdata\fP and \fIlen\fP represent the +data to write in bytes. +.TP +.B Return +0 on success, or a negative error in case of failure: +.sp +\fB\-EOVERFLOW\fP if an overflow happened: The same object will be tried again. +.UNINDENT +.TP +.B \fBu64 bpf_sk_cgroup_id(void *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Return the cgroup v2 id of the socket \fIsk\fP\&. +.sp +\fIsk\fP must be a non\-\fBNULL\fP pointer to a socket, e.g. one +returned from \fBbpf_sk_lookup_xxx\fP(), +\fBbpf_sk_fullsock\fP(), etc. The format of returned id is +same as in \fBbpf_skb_cgroup_id\fP(). +.sp +This helper is available only if the kernel was compiled with +the \fBCONFIG_SOCK_CGROUP_DATA\fP configuration option. +.TP +.B Return +The id is returned or 0 in case the id could not be retrieved. +.UNINDENT +.TP +.B \fBu64 bpf_sk_ancestor_cgroup_id(void *\fP\fIsk\fP\fB, int\fP \fIancestor_level\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Return id of cgroup v2 that is ancestor of cgroup associated +with the \fIsk\fP at the \fIancestor_level\fP\&. The root cgroup is at +\fIancestor_level\fP zero and each step down the hierarchy +increments the level. If \fIancestor_level\fP == level of cgroup +associated with \fIsk\fP, then return value will be same as that +of \fBbpf_sk_cgroup_id\fP(). +.sp +The helper is useful to implement policies based on cgroups +that are upper in hierarchy than immediate cgroup associated +with \fIsk\fP\&. +.sp +The format of returned id and helper limitations are same as in +\fBbpf_sk_cgroup_id\fP(). +.TP +.B Return +The id is returned or 0 in case the id could not be retrieved. +.UNINDENT +.TP +.B \fBlong bpf_ringbuf_output(void *\fP\fIringbuf\fP\fB, void *\fP\fIdata\fP\fB, u64\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Copy \fIsize\fP bytes from \fIdata\fP into a ring buffer \fIringbuf\fP\&. +If \fBBPF_RB_NO_WAKEUP\fP is specified in \fIflags\fP, no notification +of new data availability is sent. +If \fBBPF_RB_FORCE_WAKEUP\fP is specified in \fIflags\fP, notification +of new data availability is sent unconditionally. +If \fB0\fP is specified in \fIflags\fP, an adaptive notification +of new data availability is sent. +.sp +An adaptive notification is a notification sent whenever the user\-space +process has caught up and consumed all available payloads. In case the user\-space +process is still processing a previous payload, then no notification is needed +as it will process the newly added payload automatically. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBvoid *bpf_ringbuf_reserve(void *\fP\fIringbuf\fP\fB, u64\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Reserve \fIsize\fP bytes of payload in a ring buffer \fIringbuf\fP\&. +\fIflags\fP must be 0. +.TP +.B Return +Valid pointer with \fIsize\fP bytes of memory available; NULL, +otherwise. +.UNINDENT +.TP +.B \fBvoid bpf_ringbuf_submit(void *\fP\fIdata\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Submit reserved ring buffer sample, pointed to by \fIdata\fP\&. +If \fBBPF_RB_NO_WAKEUP\fP is specified in \fIflags\fP, no notification +of new data availability is sent. +If \fBBPF_RB_FORCE_WAKEUP\fP is specified in \fIflags\fP, notification +of new data availability is sent unconditionally. +If \fB0\fP is specified in \fIflags\fP, an adaptive notification +of new data availability is sent. +.sp +See \(aqbpf_ringbuf_output()\(aq for the definition of adaptive notification. +.TP +.B Return +Nothing. Always succeeds. +.UNINDENT +.TP +.B \fBvoid bpf_ringbuf_discard(void *\fP\fIdata\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Discard reserved ring buffer sample, pointed to by \fIdata\fP\&. +If \fBBPF_RB_NO_WAKEUP\fP is specified in \fIflags\fP, no notification +of new data availability is sent. +If \fBBPF_RB_FORCE_WAKEUP\fP is specified in \fIflags\fP, notification +of new data availability is sent unconditionally. +If \fB0\fP is specified in \fIflags\fP, an adaptive notification +of new data availability is sent. +.sp +See \(aqbpf_ringbuf_output()\(aq for the definition of adaptive notification. +.TP +.B Return +Nothing. Always succeeds. +.UNINDENT +.TP +.B \fBu64 bpf_ringbuf_query(void *\fP\fIringbuf\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Query various characteristics of provided ring buffer. What +exactly is queries is determined by \fIflags\fP: +.INDENT 7.0 +.IP \(bu 2 +\fBBPF_RB_AVAIL_DATA\fP: Amount of data not yet consumed. +.IP \(bu 2 +\fBBPF_RB_RING_SIZE\fP: The size of ring buffer. +.IP \(bu 2 +\fBBPF_RB_CONS_POS\fP: Consumer position (can wrap around). +.IP \(bu 2 +\fBBPF_RB_PROD_POS\fP: Producer(s) position (can wrap around). +.UNINDENT +.sp +Data returned is just a momentary snapshot of actual values +and could be inaccurate, so this facility should be used to +power heuristics and for reporting, not to make 100% correct +calculation. +.TP +.B Return +Requested value, or 0, if \fIflags\fP are not recognized. +.UNINDENT +.TP +.B \fBlong bpf_csum_level(struct sk_buff *\fP\fIskb\fP\fB, u64\fP \fIlevel\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Change the skbs checksum level by one layer up or down, or +reset it entirely to none in order to have the stack perform +checksum validation. The level is applicable to the following +protocols: TCP, UDP, GRE, SCTP, FCOE. For example, a decap of +| ETH | IP | UDP | GUE | IP | TCP | into | ETH | IP | TCP | +through \fBbpf_skb_adjust_room\fP() helper with passing in +\fBBPF_F_ADJ_ROOM_NO_CSUM_RESET\fP flag would require one call +to \fBbpf_csum_level\fP() with \fBBPF_CSUM_LEVEL_DEC\fP since +the UDP header is removed. Similarly, an encap of the latter +into the former could be accompanied by a helper call to +\fBbpf_csum_level\fP() with \fBBPF_CSUM_LEVEL_INC\fP if the +skb is still intended to be processed in higher layers of the +stack instead of just egressing at tc. +.sp +There are three supported level settings at this time: +.INDENT 7.0 +.IP \(bu 2 +\fBBPF_CSUM_LEVEL_INC\fP: Increases skb\->csum_level for skbs +with CHECKSUM_UNNECESSARY. +.IP \(bu 2 +\fBBPF_CSUM_LEVEL_DEC\fP: Decreases skb\->csum_level for skbs +with CHECKSUM_UNNECESSARY. +.IP \(bu 2 +\fBBPF_CSUM_LEVEL_RESET\fP: Resets skb\->csum_level to 0 and +sets CHECKSUM_NONE to force checksum validation by the stack. +.IP \(bu 2 +\fBBPF_CSUM_LEVEL_QUERY\fP: No\-op, returns the current +skb\->csum_level. +.UNINDENT +.TP +.B Return +0 on success, or a negative error in case of failure. In the +case of \fBBPF_CSUM_LEVEL_QUERY\fP, the current skb\->csum_level +is returned or the error code \-EACCES in case the skb is not +subject to CHECKSUM_UNNECESSARY. +.UNINDENT +.TP +.B \fBstruct tcp6_sock *bpf_skc_to_tcp6_sock(void *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Dynamically cast a \fIsk\fP pointer to a \fItcp6_sock\fP pointer. +.TP +.B Return +\fIsk\fP if casting is valid, or \fBNULL\fP otherwise. +.UNINDENT +.TP +.B \fBstruct tcp_sock *bpf_skc_to_tcp_sock(void *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Dynamically cast a \fIsk\fP pointer to a \fItcp_sock\fP pointer. +.TP +.B Return +\fIsk\fP if casting is valid, or \fBNULL\fP otherwise. +.UNINDENT +.TP +.B \fBstruct tcp_timewait_sock *bpf_skc_to_tcp_timewait_sock(void *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Dynamically cast a \fIsk\fP pointer to a \fItcp_timewait_sock\fP pointer. +.TP +.B Return +\fIsk\fP if casting is valid, or \fBNULL\fP otherwise. +.UNINDENT +.TP +.B \fBstruct tcp_request_sock *bpf_skc_to_tcp_request_sock(void *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Dynamically cast a \fIsk\fP pointer to a \fItcp_request_sock\fP pointer. +.TP +.B Return +\fIsk\fP if casting is valid, or \fBNULL\fP otherwise. +.UNINDENT +.TP +.B \fBstruct udp6_sock *bpf_skc_to_udp6_sock(void *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Dynamically cast a \fIsk\fP pointer to a \fIudp6_sock\fP pointer. +.TP +.B Return +\fIsk\fP if casting is valid, or \fBNULL\fP otherwise. +.UNINDENT +.TP +.B \fBlong bpf_get_task_stack(struct task_struct *\fP\fItask\fP\fB, void *\fP\fIbuf\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Return a user or a kernel stack in bpf program provided buffer. +Note: the user stack will only be populated if the \fItask\fP is +the current task; all other tasks will return \-EOPNOTSUPP. +To achieve this, the helper needs \fItask\fP, which is a valid +pointer to \fBstruct task_struct\fP\&. To store the stacktrace, the +bpf program provides \fIbuf\fP with a nonnegative \fIsize\fP\&. +.sp +The last argument, \fIflags\fP, holds the number of stack frames to +skip (from 0 to 255), masked with +\fBBPF_F_SKIP_FIELD_MASK\fP\&. The next bits can be used to set +the following flags: +.INDENT 7.0 +.TP +.B \fBBPF_F_USER_STACK\fP +Collect a user space stack instead of a kernel stack. +The \fItask\fP must be the current task. +.TP +.B \fBBPF_F_USER_BUILD_ID\fP +Collect buildid+offset instead of ips for user stack, +only valid if \fBBPF_F_USER_STACK\fP is also specified. +.UNINDENT +.sp +\fBbpf_get_task_stack\fP() can collect up to +\fBPERF_MAX_STACK_DEPTH\fP both kernel and user frames, subject +to sufficient large buffer size. Note that +this limit can be controlled with the \fBsysctl\fP program, and +that it should be manually increased in order to profile long +user stacks (such as stacks for Java programs). To do so, use: +.INDENT 7.0 +.INDENT 3.5 +.sp +.EX +# sysctl kernel.perf_event_max_stack= +.EE +.UNINDENT +.UNINDENT +.TP +.B Return +The non\-negative copied \fIbuf\fP length equal to or less than +\fIsize\fP on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_load_hdr_opt(struct bpf_sock_ops *\fP\fIskops\fP\fB, void *\fP\fIsearchby_res\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Load header option. Support reading a particular TCP header +option for bpf program (\fBBPF_PROG_TYPE_SOCK_OPS\fP). +.sp +If \fIflags\fP is 0, it will search the option from the +\fIskops\fP\fB\->skb_data\fP\&. The comment in \fBstruct bpf_sock_ops\fP +has details on what skb_data contains under different +\fIskops\fP\fB\->op\fP\&. +.sp +The first byte of the \fIsearchby_res\fP specifies the +kind that it wants to search. +.sp +If the searching kind is an experimental kind +(i.e. 253 or 254 according to RFC6994). It also +needs to specify the \(dqmagic\(dq which is either +2 bytes or 4 bytes. It then also needs to +specify the size of the magic by using +the 2nd byte which is \(dqkind\-length\(dq of a TCP +header option and the \(dqkind\-length\(dq also +includes the first 2 bytes \(dqkind\(dq and \(dqkind\-length\(dq +itself as a normal TCP header option also does. +.sp +For example, to search experimental kind 254 with +2 byte magic 0xeB9F, the searchby_res should be +[ 254, 4, 0xeB, 0x9F, 0, 0, .... 0 ]. +.sp +To search for the standard window scale option (3), +the \fIsearchby_res\fP should be [ 3, 0, 0, .... 0 ]. +Note, kind\-length must be 0 for regular option. +.sp +Searching for No\-Op (0) and End\-of\-Option\-List (1) are +not supported. +.sp +\fIlen\fP must be at least 2 bytes which is the minimal size +of a header option. +.sp +Supported flags: +.INDENT 7.0 +.IP \(bu 2 +\fBBPF_LOAD_HDR_OPT_TCP_SYN\fP to search from the +saved_syn packet or the just\-received syn packet. +.UNINDENT +.TP +.B Return +> 0 when found, the header option is copied to \fIsearchby_res\fP\&. +The return value is the total length copied. On failure, a +negative error code is returned: +.sp +\fB\-EINVAL\fP if a parameter is invalid. +.sp +\fB\-ENOMSG\fP if the option is not found. +.sp +\fB\-ENOENT\fP if no syn packet is available when +\fBBPF_LOAD_HDR_OPT_TCP_SYN\fP is used. +.sp +\fB\-ENOSPC\fP if there is not enough space. Only \fIlen\fP number of +bytes are copied. +.sp +\fB\-EFAULT\fP on failure to parse the header options in the +packet. +.sp +\fB\-EPERM\fP if the helper cannot be used under the current +\fIskops\fP\fB\->op\fP\&. +.UNINDENT +.TP +.B \fBlong bpf_store_hdr_opt(struct bpf_sock_ops *\fP\fIskops\fP\fB, const void *\fP\fIfrom\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Store header option. The data will be copied +from buffer \fIfrom\fP with length \fIlen\fP to the TCP header. +.sp +The buffer \fIfrom\fP should have the whole option that +includes the kind, kind\-length, and the actual +option data. The \fIlen\fP must be at least kind\-length +long. The kind\-length does not have to be 4 byte +aligned. The kernel will take care of the padding +and setting the 4 bytes aligned value to th\->doff. +.sp +This helper will check for duplicated option +by searching the same option in the outgoing skb. +.sp +This helper can only be called during +\fBBPF_SOCK_OPS_WRITE_HDR_OPT_CB\fP\&. +.TP +.B Return +0 on success, or negative error in case of failure: +.sp +\fB\-EINVAL\fP If param is invalid. +.sp +\fB\-ENOSPC\fP if there is not enough space in the header. +Nothing has been written +.sp +\fB\-EEXIST\fP if the option already exists. +.sp +\fB\-EFAULT\fP on failure to parse the existing header options. +.sp +\fB\-EPERM\fP if the helper cannot be used under the current +\fIskops\fP\fB\->op\fP\&. +.UNINDENT +.TP +.B \fBlong bpf_reserve_hdr_opt(struct bpf_sock_ops *\fP\fIskops\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Reserve \fIlen\fP bytes for the bpf header option. The +space will be used by \fBbpf_store_hdr_opt\fP() later in +\fBBPF_SOCK_OPS_WRITE_HDR_OPT_CB\fP\&. +.sp +If \fBbpf_reserve_hdr_opt\fP() is called multiple times, +the total number of bytes will be reserved. +.sp +This helper can only be called during +\fBBPF_SOCK_OPS_HDR_OPT_LEN_CB\fP\&. +.TP +.B Return +0 on success, or negative error in case of failure: +.sp +\fB\-EINVAL\fP if a parameter is invalid. +.sp +\fB\-ENOSPC\fP if there is not enough space in the header. +.sp +\fB\-EPERM\fP if the helper cannot be used under the current +\fIskops\fP\fB\->op\fP\&. +.UNINDENT +.TP +.B \fBvoid *bpf_inode_storage_get(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIinode\fP\fB, void *\fP\fIvalue\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get a bpf_local_storage from an \fIinode\fP\&. +.sp +Logically, it could be thought of as getting the value from +a \fImap\fP with \fIinode\fP as the \fBkey\fP\&. From this +perspective, the usage is not much different from +\fBbpf_map_lookup_elem\fP(\fImap\fP, \fB&\fP\fIinode\fP) except this +helper enforces the key must be an inode and the map must also +be a \fBBPF_MAP_TYPE_INODE_STORAGE\fP\&. +.sp +Underneath, the value is stored locally at \fIinode\fP instead of +the \fImap\fP\&. The \fImap\fP is used as the bpf\-local\-storage +\(dqtype\(dq. The bpf\-local\-storage \(dqtype\(dq (i.e. the \fImap\fP) is +searched against all bpf_local_storage residing at \fIinode\fP\&. +.sp +An optional \fIflags\fP (\fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP) can be +used such that a new bpf_local_storage will be +created if one does not exist. \fIvalue\fP can be used +together with \fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP to specify +the initial value of a bpf_local_storage. If \fIvalue\fP is +\fBNULL\fP, the new bpf_local_storage will be zero initialized. +.TP +.B Return +A bpf_local_storage pointer is returned on success. +.sp +\fBNULL\fP if not found or there was an error in adding +a new bpf_local_storage. +.UNINDENT +.TP +.B \fBint bpf_inode_storage_delete(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIinode\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Delete a bpf_local_storage from an \fIinode\fP\&. +.TP +.B Return +0 on success. +.sp +\fB\-ENOENT\fP if the bpf_local_storage cannot be found. +.UNINDENT +.TP +.B \fBlong bpf_d_path(struct path *\fP\fIpath\fP\fB, char *\fP\fIbuf\fP\fB, u32\fP \fIsz\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Return full path for given \fBstruct path\fP object, which +needs to be the kernel BTF \fIpath\fP object. The path is +returned in the provided buffer \fIbuf\fP of size \fIsz\fP and +is zero terminated. +.TP +.B Return +On success, the strictly positive length of the string, +including the trailing NUL character. On error, a negative +value. +.UNINDENT +.TP +.B \fBlong bpf_copy_from_user(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIuser_ptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Read \fIsize\fP bytes from user space address \fIuser_ptr\fP and store +the data in \fIdst\fP\&. This is a wrapper of \fBcopy_from_user\fP(). +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_snprintf_btf(char *\fP\fIstr\fP\fB, u32\fP \fIstr_size\fP\fB, struct btf_ptr *\fP\fIptr\fP\fB, u32\fP \fIbtf_ptr_size\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Use BTF to store a string representation of \fIptr\fP\->ptr in \fIstr\fP, +using \fIptr\fP\->type_id. This value should specify the type +that \fIptr\fP\->ptr points to. LLVM __builtin_btf_type_id(type, 1) +can be used to look up vmlinux BTF type ids. Traversing the +data structure using BTF, the type information and values are +stored in the first \fIstr_size\fP \- 1 bytes of \fIstr\fP\&. Safe copy of +the pointer data is carried out to avoid kernel crashes during +operation. Smaller types can use string space on the stack; +larger programs can use map data to store the string +representation. +.sp +The string can be subsequently shared with userspace via +bpf_perf_event_output() or ring buffer interfaces. +bpf_trace_printk() is to be avoided as it places too small +a limit on string size to be useful. +.sp +\fIflags\fP is a combination of +.INDENT 7.0 +.TP +.B \fBBTF_F_COMPACT\fP +no formatting around type information +.TP +.B \fBBTF_F_NONAME\fP +no struct/union member names/types +.TP +.B \fBBTF_F_PTR_RAW\fP +show raw (unobfuscated) pointer values; +equivalent to printk specifier %px. +.TP +.B \fBBTF_F_ZERO\fP +show zero\-valued struct/union members; they +are not displayed by default +.UNINDENT +.TP +.B Return +The number of bytes that were written (or would have been +written if output had to be truncated due to string size), +or a negative error in cases of failure. +.UNINDENT +.TP +.B \fBlong bpf_seq_printf_btf(struct seq_file *\fP\fIm\fP\fB, struct btf_ptr *\fP\fIptr\fP\fB, u32\fP \fIptr_size\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Use BTF to write to seq_write a string representation of +\fIptr\fP\->ptr, using \fIptr\fP\->type_id as per bpf_snprintf_btf(). +\fIflags\fP are identical to those used for bpf_snprintf_btf. +.TP +.B Return +0 on success or a negative error in case of failure. +.UNINDENT +.TP +.B \fBu64 bpf_skb_cgroup_classid(struct sk_buff *\fP\fIskb\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +See \fBbpf_get_cgroup_classid\fP() for the main description. +This helper differs from \fBbpf_get_cgroup_classid\fP() in that +the cgroup v1 net_cls class is retrieved only from the \fIskb\fP\(aqs +associated socket instead of the current process. +.TP +.B Return +The id is returned or 0 in case the id could not be retrieved. +.UNINDENT +.TP +.B \fBlong bpf_redirect_neigh(u32\fP \fIifindex\fP\fB, struct bpf_redir_neigh *\fP\fIparams\fP\fB, int\fP \fIplen\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Redirect the packet to another net device of index \fIifindex\fP +and fill in L2 addresses from neighboring subsystem. This helper +is somewhat similar to \fBbpf_redirect\fP(), except that it +populates L2 addresses as well, meaning, internally, the helper +relies on the neighbor lookup for the L2 address of the nexthop. +.sp +The helper will perform a FIB lookup based on the skb\(aqs +networking header to get the address of the next hop, unless +this is supplied by the caller in the \fIparams\fP argument. The +\fIplen\fP argument indicates the len of \fIparams\fP and should be set +to 0 if \fIparams\fP is NULL. +.sp +The \fIflags\fP argument is reserved and must be 0. The helper is +currently only supported for tc BPF program types, and enabled +for IPv4 and IPv6 protocols. +.TP +.B Return +The helper returns \fBTC_ACT_REDIRECT\fP on success or +\fBTC_ACT_SHOT\fP on error. +.UNINDENT +.TP +.B \fBvoid *bpf_per_cpu_ptr(const void *\fP\fIpercpu_ptr\fP\fB, u32\fP \fIcpu\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Take a pointer to a percpu ksym, \fIpercpu_ptr\fP, and return a +pointer to the percpu kernel variable on \fIcpu\fP\&. A ksym is an +extern variable decorated with \(aq__ksym\(aq. For ksym, there is a +global var (either static or global) defined of the same name +in the kernel. The ksym is percpu if the global var is percpu. +The returned pointer points to the global percpu var on \fIcpu\fP\&. +.sp +bpf_per_cpu_ptr() has the same semantic as per_cpu_ptr() in the +kernel, except that bpf_per_cpu_ptr() may return NULL. This +happens if \fIcpu\fP is larger than nr_cpu_ids. The caller of +bpf_per_cpu_ptr() must check the returned value. +.TP +.B Return +A pointer pointing to the kernel percpu variable on \fIcpu\fP, or +NULL, if \fIcpu\fP is invalid. +.UNINDENT +.TP +.B \fBvoid *bpf_this_cpu_ptr(const void *\fP\fIpercpu_ptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Take a pointer to a percpu ksym, \fIpercpu_ptr\fP, and return a +pointer to the percpu kernel variable on this cpu. See the +description of \(aqksym\(aq in \fBbpf_per_cpu_ptr\fP(). +.sp +bpf_this_cpu_ptr() has the same semantic as this_cpu_ptr() in +the kernel. Different from \fBbpf_per_cpu_ptr\fP(), it would +never return NULL. +.TP +.B Return +A pointer pointing to the kernel percpu variable on this cpu. +.UNINDENT +.TP +.B \fBlong bpf_redirect_peer(u32\fP \fIifindex\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Redirect the packet to another net device of index \fIifindex\fP\&. +This helper is somewhat similar to \fBbpf_redirect\fP(), except +that the redirection happens to the \fIifindex\fP\(aq peer device and +the netns switch takes place from ingress to ingress without +going through the CPU\(aqs backlog queue. +.sp +The \fIflags\fP argument is reserved and must be 0. The helper is +currently only supported for tc BPF program types at the ingress +hook and for veth device types. The peer device must reside in a +different network namespace. +.TP +.B Return +The helper returns \fBTC_ACT_REDIRECT\fP on success or +\fBTC_ACT_SHOT\fP on error. +.UNINDENT +.TP +.B \fBvoid *bpf_task_storage_get(struct bpf_map *\fP\fImap\fP\fB, struct task_struct *\fP\fItask\fP\fB, void *\fP\fIvalue\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get a bpf_local_storage from the \fItask\fP\&. +.sp +Logically, it could be thought of as getting the value from +a \fImap\fP with \fItask\fP as the \fBkey\fP\&. From this +perspective, the usage is not much different from +\fBbpf_map_lookup_elem\fP(\fImap\fP, \fB&\fP\fItask\fP) except this +helper enforces the key must be a task_struct and the map must also +be a \fBBPF_MAP_TYPE_TASK_STORAGE\fP\&. +.sp +Underneath, the value is stored locally at \fItask\fP instead of +the \fImap\fP\&. The \fImap\fP is used as the bpf\-local\-storage +\(dqtype\(dq. The bpf\-local\-storage \(dqtype\(dq (i.e. the \fImap\fP) is +searched against all bpf_local_storage residing at \fItask\fP\&. +.sp +An optional \fIflags\fP (\fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP) can be +used such that a new bpf_local_storage will be +created if one does not exist. \fIvalue\fP can be used +together with \fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP to specify +the initial value of a bpf_local_storage. If \fIvalue\fP is +\fBNULL\fP, the new bpf_local_storage will be zero initialized. +.TP +.B Return +A bpf_local_storage pointer is returned on success. +.sp +\fBNULL\fP if not found or there was an error in adding +a new bpf_local_storage. +.UNINDENT +.TP +.B \fBlong bpf_task_storage_delete(struct bpf_map *\fP\fImap\fP\fB, struct task_struct *\fP\fItask\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Delete a bpf_local_storage from a \fItask\fP\&. +.TP +.B Return +0 on success. +.sp +\fB\-ENOENT\fP if the bpf_local_storage cannot be found. +.UNINDENT +.TP +.B \fBstruct task_struct *bpf_get_current_task_btf(void)\fP +.INDENT 7.0 +.TP +.B Description +Return a BTF pointer to the \(dqcurrent\(dq task. +This pointer can also be used in helpers that accept an +\fIARG_PTR_TO_BTF_ID\fP of type \fItask_struct\fP\&. +.TP +.B Return +Pointer to the current task. +.UNINDENT +.TP +.B \fBlong bpf_bprm_opts_set(struct linux_binprm *\fP\fIbprm\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Set or clear certain options on \fIbprm\fP: +.sp +\fBBPF_F_BPRM_SECUREEXEC\fP Set the secureexec bit +which sets the \fBAT_SECURE\fP auxv for glibc. The bit +is cleared if the flag is not specified. +.TP +.B Return +\fB\-EINVAL\fP if invalid \fIflags\fP are passed, zero otherwise. +.UNINDENT +.TP +.B \fBu64 bpf_ktime_get_coarse_ns(void)\fP +.INDENT 7.0 +.TP +.B Description +Return a coarse\-grained version of the time elapsed since +system boot, in nanoseconds. Does not include time the system +was suspended. +.sp +See: \fBclock_gettime\fP(\fBCLOCK_MONOTONIC_COARSE\fP) +.TP +.B Return +Current \fIktime\fP\&. +.UNINDENT +.TP +.B \fBlong bpf_ima_inode_hash(struct inode *\fP\fIinode\fP\fB, void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Returns the stored IMA hash of the \fIinode\fP (if it\(aqs available). +If the hash is larger than \fIsize\fP, then only \fIsize\fP +bytes will be copied to \fIdst\fP +.TP +.B Return +The \fBhash_algo\fP is returned on success, +\fB\-EOPNOTSUP\fP if IMA is disabled or \fB\-EINVAL\fP if +invalid arguments are passed. +.UNINDENT +.TP +.B \fBstruct socket *bpf_sock_from_file(struct file *\fP\fIfile\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +If the given file represents a socket, returns the associated +socket. +.TP +.B Return +A pointer to a struct socket on success or NULL if the file is +not a socket. +.UNINDENT +.TP +.B \fBlong bpf_check_mtu(void *\fP\fIctx\fP\fB, u32\fP \fIifindex\fP\fB, u32 *\fP\fImtu_len\fP\fB, s32\fP \fIlen_diff\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Check packet size against exceeding MTU of net device (based +on \fIifindex\fP). This helper will likely be used in combination +with helpers that adjust/change the packet size. +.sp +The argument \fIlen_diff\fP can be used for querying with a planned +size change. This allows to check MTU prior to changing packet +ctx. Providing a \fIlen_diff\fP adjustment that is larger than the +actual packet size (resulting in negative packet size) will in +principle not exceed the MTU, which is why it is not considered +a failure. Other BPF helpers are needed for performing the +planned size change; therefore the responsibility for catching +a negative packet size belongs in those helpers. +.sp +Specifying \fIifindex\fP zero means the MTU check is performed +against the current net device. This is practical if this isn\(aqt +used prior to redirect. +.sp +On input \fImtu_len\fP must be a valid pointer, else verifier will +reject BPF program. If the value \fImtu_len\fP is initialized to +zero then the ctx packet size is use. When value \fImtu_len\fP is +provided as input this specify the L3 length that the MTU check +is done against. Remember XDP and TC length operate at L2, but +this value is L3 as this correlate to MTU and IP\-header tot_len +values which are L3 (similar behavior as bpf_fib_lookup). +.sp +The Linux kernel route table can configure MTUs on a more +specific per route level, which is not provided by this helper. +For route level MTU checks use the \fBbpf_fib_lookup\fP() +helper. +.sp +\fIctx\fP is either \fBstruct xdp_md\fP for XDP programs or +\fBstruct sk_buff\fP for tc cls_act programs. +.sp +The \fIflags\fP argument can be a combination of one or more of the +following values: +.INDENT 7.0 +.TP +.B \fBBPF_MTU_CHK_SEGS\fP +This flag will only works for \fIctx\fP \fBstruct sk_buff\fP\&. +If packet context contains extra packet segment buffers +(often knows as GSO skb), then MTU check is harder to +check at this point, because in transmit path it is +possible for the skb packet to get re\-segmented +(depending on net device features). This could still be +a MTU violation, so this flag enables performing MTU +check against segments, with a different violation +return code to tell it apart. Check cannot use len_diff. +.UNINDENT +.sp +On return \fImtu_len\fP pointer contains the MTU value of the net +device. Remember the net device configured MTU is the L3 size, +which is returned here and XDP and TC length operate at L2. +Helper take this into account for you, but remember when using +MTU value in your BPF\-code. +.TP +.B Return +.INDENT 7.0 +.IP \(bu 2 +0 on success, and populate MTU value in \fImtu_len\fP pointer. +.IP \(bu 2 +< 0 if any input argument is invalid (\fImtu_len\fP not updated) +.UNINDENT +.sp +MTU violations return positive values, but also populate MTU +value in \fImtu_len\fP pointer, as this can be needed for +implementing PMTU handing: +.INDENT 7.0 +.IP \(bu 2 +\fBBPF_MTU_CHK_RET_FRAG_NEEDED\fP +.IP \(bu 2 +\fBBPF_MTU_CHK_RET_SEGS_TOOBIG\fP +.UNINDENT +.UNINDENT +.TP +.B \fBlong bpf_for_each_map_elem(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIcallback_fn\fP\fB, void *\fP\fIcallback_ctx\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +For each element in \fBmap\fP, call \fBcallback_fn\fP function with +\fBmap\fP, \fBcallback_ctx\fP and other map\-specific parameters. +The \fBcallback_fn\fP should be a static function and +the \fBcallback_ctx\fP should be a pointer to the stack. +The \fBflags\fP is used to control certain aspects of the helper. +Currently, the \fBflags\fP must be 0. +.sp +The following are a list of supported map types and their +respective expected callback signatures: +.sp +BPF_MAP_TYPE_HASH, BPF_MAP_TYPE_PERCPU_HASH, +BPF_MAP_TYPE_LRU_HASH, BPF_MAP_TYPE_LRU_PERCPU_HASH, +BPF_MAP_TYPE_ARRAY, BPF_MAP_TYPE_PERCPU_ARRAY +.sp +long (*callback_fn)(struct bpf_map *map, const void *key, void *value, void *ctx); +.sp +For per_cpu maps, the map_value is the value on the cpu where the +bpf_prog is running. +.sp +If \fBcallback_fn\fP return 0, the helper will continue to the next +element. If return value is 1, the helper will skip the rest of +elements and return. Other return values are not used now. +.TP +.B Return +The number of traversed map elements for success, \fB\-EINVAL\fP for +invalid \fBflags\fP\&. +.UNINDENT +.TP +.B \fBlong bpf_snprintf(char *\fP\fIstr\fP\fB, u32\fP \fIstr_size\fP\fB, const char *\fP\fIfmt\fP\fB, u64 *\fP\fIdata\fP\fB, u32\fP \fIdata_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Outputs a string into the \fBstr\fP buffer of size \fBstr_size\fP +based on a format string stored in a read\-only map pointed by +\fBfmt\fP\&. +.sp +Each format specifier in \fBfmt\fP corresponds to one u64 element +in the \fBdata\fP array. For strings and pointers where pointees +are accessed, only the pointer values are stored in the \fIdata\fP +array. The \fIdata_len\fP is the size of \fIdata\fP in bytes \- must be +a multiple of 8. +.sp +Formats \fB%s\fP and \fB%p{i,I}{4,6}\fP require to read kernel +memory. Reading kernel memory may fail due to either invalid +address or valid address but requiring a major memory fault. If +reading kernel memory fails, the string for \fB%s\fP will be an +empty string, and the ip address for \fB%p{i,I}{4,6}\fP will be 0. +Not returning error to bpf program is consistent with what +\fBbpf_trace_printk\fP() does for now. +.TP +.B Return +The strictly positive length of the formatted string, including +the trailing zero character. If the return value is greater than +\fBstr_size\fP, \fBstr\fP contains a truncated string, guaranteed to +be zero\-terminated except when \fBstr_size\fP is 0. +.sp +Or \fB\-EBUSY\fP if the per\-CPU memory copy buffer is busy. +.UNINDENT +.TP +.B \fBlong bpf_sys_bpf(u32\fP \fIcmd\fP\fB, void *\fP\fIattr\fP\fB, u32\fP \fIattr_size\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Execute bpf syscall with given arguments. +.TP +.B Return +A syscall result. +.UNINDENT +.TP +.B \fBlong bpf_btf_find_by_name_kind(char *\fP\fIname\fP\fB, int\fP \fIname_sz\fP\fB, u32\fP \fIkind\fP\fB, int\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Find BTF type with given name and kind in vmlinux BTF or in module\(aqs BTFs. +.TP +.B Return +Returns btf_id and btf_obj_fd in lower and upper 32 bits. +.UNINDENT +.TP +.B \fBlong bpf_sys_close(u32\fP \fIfd\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Execute close syscall for given FD. +.TP +.B Return +A syscall result. +.UNINDENT +.TP +.B \fBlong bpf_timer_init(struct bpf_timer *\fP\fItimer\fP\fB, struct bpf_map *\fP\fImap\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Initialize the timer. +First 4 bits of \fIflags\fP specify clockid. +Only CLOCK_MONOTONIC, CLOCK_REALTIME, CLOCK_BOOTTIME are allowed. +All other bits of \fIflags\fP are reserved. +The verifier will reject the program if \fItimer\fP is not from +the same \fImap\fP\&. +.TP +.B Return +0 on success. +\fB\-EBUSY\fP if \fItimer\fP is already initialized. +\fB\-EINVAL\fP if invalid \fIflags\fP are passed. +\fB\-EPERM\fP if \fItimer\fP is in a map that doesn\(aqt have any user references. +The user space should either hold a file descriptor to a map with timers +or pin such map in bpffs. When map is unpinned or file descriptor is +closed all timers in the map will be cancelled and freed. +.UNINDENT +.TP +.B \fBlong bpf_timer_set_callback(struct bpf_timer *\fP\fItimer\fP\fB, void *\fP\fIcallback_fn\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Configure the timer to call \fIcallback_fn\fP static function. +.TP +.B Return +0 on success. +\fB\-EINVAL\fP if \fItimer\fP was not initialized with bpf_timer_init() earlier. +\fB\-EPERM\fP if \fItimer\fP is in a map that doesn\(aqt have any user references. +The user space should either hold a file descriptor to a map with timers +or pin such map in bpffs. When map is unpinned or file descriptor is +closed all timers in the map will be cancelled and freed. +.UNINDENT +.TP +.B \fBlong bpf_timer_start(struct bpf_timer *\fP\fItimer\fP\fB, u64\fP \fInsecs\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Set timer expiration N nanoseconds from the current time. The +configured callback will be invoked in soft irq context on some cpu +and will not repeat unless another bpf_timer_start() is made. +In such case the next invocation can migrate to a different cpu. +Since struct bpf_timer is a field inside map element the map +owns the timer. The bpf_timer_set_callback() will increment refcnt +of BPF program to make sure that callback_fn code stays valid. +When user space reference to a map reaches zero all timers +in a map are cancelled and corresponding program\(aqs refcnts are +decremented. This is done to make sure that Ctrl\-C of a user +process doesn\(aqt leave any timers running. If map is pinned in +bpffs the callback_fn can re\-arm itself indefinitely. +bpf_map_update/delete_elem() helpers and user space sys_bpf commands +cancel and free the timer in the given map element. +The map can contain timers that invoke callback_fn\-s from different +programs. The same callback_fn can serve different timers from +different maps if key/value layout matches across maps. +Every bpf_timer_set_callback() can have different callback_fn. +.sp +\fIflags\fP can be one of: +.INDENT 7.0 +.TP +.B \fBBPF_F_TIMER_ABS\fP +Start the timer in absolute expire value instead of the +default relative one. +.TP +.B \fBBPF_F_TIMER_CPU_PIN\fP +Timer will be pinned to the CPU of the caller. +.UNINDENT +.TP +.B Return +0 on success. +\fB\-EINVAL\fP if \fItimer\fP was not initialized with bpf_timer_init() earlier +or invalid \fIflags\fP are passed. +.UNINDENT +.TP +.B \fBlong bpf_timer_cancel(struct bpf_timer *\fP\fItimer\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Cancel the timer and wait for callback_fn to finish if it was running. +.TP +.B Return +0 if the timer was not active. +1 if the timer was active. +\fB\-EINVAL\fP if \fItimer\fP was not initialized with bpf_timer_init() earlier. +\fB\-EDEADLK\fP if callback_fn tried to call bpf_timer_cancel() on its +own timer which would have led to a deadlock otherwise. +.UNINDENT +.TP +.B \fBu64 bpf_get_func_ip(void *\fP\fIctx\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get address of the traced function (for tracing and kprobe programs). +.sp +When called for kprobe program attached as uprobe it returns +probe address for both entry and return uprobe. +.TP +.B Return +Address of the traced function for kprobe. +0 for kprobes placed within the function (not at the entry). +Address of the probe for uprobe and return uprobe. +.UNINDENT +.TP +.B \fBu64 bpf_get_attach_cookie(void *\fP\fIctx\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get bpf_cookie value provided (optionally) during the program +attachment. It might be different for each individual +attachment, even if BPF program itself is the same. +Expects BPF program context \fIctx\fP as a first argument. +.INDENT 7.0 +.TP +.B Supported for the following program types: +.INDENT 7.0 +.IP \(bu 2 +kprobe/uprobe; +.IP \(bu 2 +tracepoint; +.IP \(bu 2 +perf_event. +.UNINDENT +.UNINDENT +.TP +.B Return +Value specified by user at BPF link creation/attachment time +or 0, if it was not specified. +.UNINDENT +.TP +.B \fBlong bpf_task_pt_regs(struct task_struct *\fP\fItask\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get the struct pt_regs associated with \fBtask\fP\&. +.TP +.B Return +A pointer to struct pt_regs. +.UNINDENT +.TP +.B \fBlong bpf_get_branch_snapshot(void *\fP\fIentries\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get branch trace from hardware engines like Intel LBR. The +hardware engine is stopped shortly after the helper is +called. Therefore, the user need to filter branch entries +based on the actual use case. To capture branch trace +before the trigger point of the BPF program, the helper +should be called at the beginning of the BPF program. +.sp +The data is stored as struct perf_branch_entry into output +buffer \fIentries\fP\&. \fIsize\fP is the size of \fIentries\fP in bytes. +\fIflags\fP is reserved for now and must be zero. +.TP +.B Return +On success, number of bytes written to \fIbuf\fP\&. On error, a +negative value. +.sp +\fB\-EINVAL\fP if \fIflags\fP is not zero. +.sp +\fB\-ENOENT\fP if architecture does not support branch records. +.UNINDENT +.TP +.B \fBlong bpf_trace_vprintk(const char *\fP\fIfmt\fP\fB, u32\fP \fIfmt_size\fP\fB, const void *\fP\fIdata\fP\fB, u32\fP \fIdata_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Behaves like \fBbpf_trace_printk\fP() helper, but takes an array of u64 +to format and can handle more format args as a result. +.sp +Arguments are to be used as in \fBbpf_seq_printf\fP() helper. +.TP +.B Return +The number of bytes written to the buffer, or a negative error +in case of failure. +.UNINDENT +.TP +.B \fBstruct unix_sock *bpf_skc_to_unix_sock(void *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Dynamically cast a \fIsk\fP pointer to a \fIunix_sock\fP pointer. +.TP +.B Return +\fIsk\fP if casting is valid, or \fBNULL\fP otherwise. +.UNINDENT +.TP +.B \fBlong bpf_kallsyms_lookup_name(const char *\fP\fIname\fP\fB, int\fP \fIname_sz\fP\fB, int\fP \fIflags\fP\fB, u64 *\fP\fIres\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get the address of a kernel symbol, returned in \fIres\fP\&. \fIres\fP is +set to 0 if the symbol is not found. +.TP +.B Return +On success, zero. On error, a negative value. +.sp +\fB\-EINVAL\fP if \fIflags\fP is not zero. +.sp +\fB\-EINVAL\fP if string \fIname\fP is not the same size as \fIname_sz\fP\&. +.sp +\fB\-ENOENT\fP if symbol is not found. +.sp +\fB\-EPERM\fP if caller does not have permission to obtain kernel address. +.UNINDENT +.TP +.B \fBlong bpf_find_vma(struct task_struct *\fP\fItask\fP\fB, u64\fP \fIaddr\fP\fB, void *\fP\fIcallback_fn\fP\fB, void *\fP\fIcallback_ctx\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Find vma of \fItask\fP that contains \fIaddr\fP, call \fIcallback_fn\fP +function with \fItask\fP, \fIvma\fP, and \fIcallback_ctx\fP\&. +The \fIcallback_fn\fP should be a static function and +the \fIcallback_ctx\fP should be a pointer to the stack. +The \fIflags\fP is used to control certain aspects of the helper. +Currently, the \fIflags\fP must be 0. +.sp +The expected callback signature is +.sp +long (*callback_fn)(struct task_struct *task, struct vm_area_struct *vma, void *callback_ctx); +.TP +.B Return +0 on success. +\fB\-ENOENT\fP if \fItask\->mm\fP is NULL, or no vma contains \fIaddr\fP\&. +\fB\-EBUSY\fP if failed to try lock mmap_lock. +\fB\-EINVAL\fP for invalid \fBflags\fP\&. +.UNINDENT +.TP +.B \fBlong bpf_loop(u32\fP \fInr_loops\fP\fB, void *\fP\fIcallback_fn\fP\fB, void *\fP\fIcallback_ctx\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +For \fBnr_loops\fP, call \fBcallback_fn\fP function +with \fBcallback_ctx\fP as the context parameter. +The \fBcallback_fn\fP should be a static function and +the \fBcallback_ctx\fP should be a pointer to the stack. +The \fBflags\fP is used to control certain aspects of the helper. +Currently, the \fBflags\fP must be 0. Currently, nr_loops is +limited to 1 << 23 (~8 million) loops. +.sp +long (*callback_fn)(u32 index, void *ctx); +.sp +where \fBindex\fP is the current index in the loop. The index +is zero\-indexed. +.sp +If \fBcallback_fn\fP returns 0, the helper will continue to the next +loop. If return value is 1, the helper will skip the rest of +the loops and return. Other return values are not used now, +and will be rejected by the verifier. +.TP +.B Return +The number of loops performed, \fB\-EINVAL\fP for invalid \fBflags\fP, +\fB\-E2BIG\fP if \fBnr_loops\fP exceeds the maximum number of loops. +.UNINDENT +.TP +.B \fBlong bpf_strncmp(const char *\fP\fIs1\fP\fB, u32\fP \fIs1_sz\fP\fB, const char *\fP\fIs2\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Do strncmp() between \fBs1\fP and \fBs2\fP\&. \fBs1\fP doesn\(aqt need +to be null\-terminated and \fBs1_sz\fP is the maximum storage +size of \fBs1\fP\&. \fBs2\fP must be a read\-only string. +.TP +.B Return +An integer less than, equal to, or greater than zero +if the first \fBs1_sz\fP bytes of \fBs1\fP is found to be +less than, to match, or be greater than \fBs2\fP\&. +.UNINDENT +.TP +.B \fBlong bpf_get_func_arg(void *\fP\fIctx\fP\fB, u32\fP \fIn\fP\fB, u64 *\fP\fIvalue\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get \fBn\fP\-th argument register (zero based) of the traced function (for tracing programs) +returned in \fBvalue\fP\&. +.TP +.B Return +0 on success. +\fB\-EINVAL\fP if n >= argument register count of traced function. +.UNINDENT +.TP +.B \fBlong bpf_get_func_ret(void *\fP\fIctx\fP\fB, u64 *\fP\fIvalue\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get return value of the traced function (for tracing programs) +in \fBvalue\fP\&. +.TP +.B Return +0 on success. +\fB\-EOPNOTSUPP\fP for tracing programs other than BPF_TRACE_FEXIT or BPF_MODIFY_RETURN. +.UNINDENT +.TP +.B \fBlong bpf_get_func_arg_cnt(void *\fP\fIctx\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get number of registers of the traced function (for tracing programs) where +function arguments are stored in these registers. +.TP +.B Return +The number of argument registers of the traced function. +.UNINDENT +.TP +.B \fBint bpf_get_retval(void)\fP +.INDENT 7.0 +.TP +.B Description +Get the BPF program\(aqs return value that will be returned to the upper layers. +.sp +This helper is currently supported by cgroup programs and only by the hooks +where BPF program\(aqs return value is returned to the userspace via errno. +.TP +.B Return +The BPF program\(aqs return value. +.UNINDENT +.TP +.B \fBint bpf_set_retval(int\fP \fIretval\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Set the BPF program\(aqs return value that will be returned to the upper layers. +.sp +This helper is currently supported by cgroup programs and only by the hooks +where BPF program\(aqs return value is returned to the userspace via errno. +.sp +Note that there is the following corner case where the program exports an error +via bpf_set_retval but signals success via \(aqreturn 1\(aq: +.INDENT 7.0 +.INDENT 3.5 +bpf_set_retval(\-EPERM); +return 1; +.UNINDENT +.UNINDENT +.sp +In this case, the BPF program\(aqs return value will use helper\(aqs \-EPERM. This +still holds true for cgroup/bind{4,6} which supports extra \(aqreturn 3\(aq success case. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBu64 bpf_xdp_get_buff_len(struct xdp_buff *\fP\fIxdp_md\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get the total size of a given xdp buff (linear and paged area) +.TP +.B Return +The total size of a given xdp buffer. +.UNINDENT +.TP +.B \fBlong bpf_xdp_load_bytes(struct xdp_buff *\fP\fIxdp_md\fP\fB, u32\fP \fIoffset\fP\fB, void *\fP\fIbuf\fP\fB, u32\fP \fIlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +This helper is provided as an easy way to load data from a +xdp buffer. It can be used to load \fIlen\fP bytes from \fIoffset\fP from +the frame associated to \fIxdp_md\fP, into the buffer pointed by +\fIbuf\fP\&. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_xdp_store_bytes(struct xdp_buff *\fP\fIxdp_md\fP\fB, u32\fP \fIoffset\fP\fB, void *\fP\fIbuf\fP\fB, u32\fP \fIlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Store \fIlen\fP bytes from buffer \fIbuf\fP into the frame +associated to \fIxdp_md\fP, at \fIoffset\fP\&. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBlong bpf_copy_from_user_task(void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB, const void *\fP\fIuser_ptr\fP\fB, struct task_struct *\fP\fItsk\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Read \fIsize\fP bytes from user space address \fIuser_ptr\fP in \fItsk\fP\(aqs +address space, and stores the data in \fIdst\fP\&. \fIflags\fP is not +used yet and is provided for future extensibility. This helper +can only be used by sleepable programs. +.TP +.B Return +0 on success, or a negative error in case of failure. On error +\fIdst\fP buffer is zeroed out. +.UNINDENT +.TP +.B \fBlong bpf_skb_set_tstamp(struct sk_buff *\fP\fIskb\fP\fB, u64\fP \fItstamp\fP\fB, u32\fP \fItstamp_type\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Change the __sk_buff\->tstamp_type to \fItstamp_type\fP +and set \fItstamp\fP to the __sk_buff\->tstamp together. +.sp +If there is no need to change the __sk_buff\->tstamp_type, +the tstamp value can be directly written to __sk_buff\->tstamp +instead. +.sp +BPF_SKB_TSTAMP_DELIVERY_MONO is the only tstamp that +will be kept during bpf_redirect_*(). A non zero +\fItstamp\fP must be used with the BPF_SKB_TSTAMP_DELIVERY_MONO +\fItstamp_type\fP\&. +.sp +A BPF_SKB_TSTAMP_UNSPEC \fItstamp_type\fP can only be used +with a zero \fItstamp\fP\&. +.sp +Only IPv4 and IPv6 skb\->protocol are supported. +.sp +This function is most useful when it needs to set a +mono delivery time to __sk_buff\->tstamp and then +bpf_redirect_*() to the egress of an iface. For example, +changing the (rcv) timestamp in __sk_buff\->tstamp at +ingress to a mono delivery time and then bpf_redirect_*() +to \fI\%sch_fq@phy\-dev\fP\&. +.TP +.B Return +0 on success. +\fB\-EINVAL\fP for invalid input +\fB\-EOPNOTSUPP\fP for unsupported protocol +.UNINDENT +.TP +.B \fBlong bpf_ima_file_hash(struct file *\fP\fIfile\fP\fB, void *\fP\fIdst\fP\fB, u32\fP \fIsize\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Returns a calculated IMA hash of the \fIfile\fP\&. +If the hash is larger than \fIsize\fP, then only \fIsize\fP +bytes will be copied to \fIdst\fP +.TP +.B Return +The \fBhash_algo\fP is returned on success, +\fB\-EOPNOTSUP\fP if the hash calculation failed or \fB\-EINVAL\fP if +invalid arguments are passed. +.UNINDENT +.TP +.B \fBvoid *bpf_kptr_xchg(void *\fP\fImap_value\fP\fB, void *\fP\fIptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Exchange kptr at pointer \fImap_value\fP with \fIptr\fP, and return the +old value. \fIptr\fP can be NULL, otherwise it must be a referenced +pointer which will be released when this helper is called. +.TP +.B Return +The old value of kptr (which can be NULL). The returned pointer +if not NULL, is a reference which must be released using its +corresponding release function, or moved into a BPF map before +program exit. +.UNINDENT +.TP +.B \fBvoid *bpf_map_lookup_percpu_elem(struct bpf_map *\fP\fImap\fP\fB, const void *\fP\fIkey\fP\fB, u32\fP \fIcpu\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Perform a lookup in \fIpercpu map\fP for an entry associated to +\fIkey\fP on \fIcpu\fP\&. +.TP +.B Return +Map value associated to \fIkey\fP on \fIcpu\fP, or \fBNULL\fP if no entry +was found or \fIcpu\fP is invalid. +.UNINDENT +.TP +.B \fBstruct mptcp_sock *bpf_skc_to_mptcp_sock(void *\fP\fIsk\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Dynamically cast a \fIsk\fP pointer to a \fImptcp_sock\fP pointer. +.TP +.B Return +\fIsk\fP if casting is valid, or \fBNULL\fP otherwise. +.UNINDENT +.TP +.B \fBlong bpf_dynptr_from_mem(void *\fP\fIdata\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB, struct bpf_dynptr *\fP\fIptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get a dynptr to local memory \fIdata\fP\&. +.sp +\fIdata\fP must be a ptr to a map value. +The maximum \fIsize\fP supported is DYNPTR_MAX_SIZE. +\fIflags\fP is currently unused. +.TP +.B Return +0 on success, \-E2BIG if the size exceeds DYNPTR_MAX_SIZE, +\-EINVAL if flags is not 0. +.UNINDENT +.TP +.B \fBlong bpf_ringbuf_reserve_dynptr(void *\fP\fIringbuf\fP\fB, u32\fP \fIsize\fP\fB, u64\fP \fIflags\fP\fB, struct bpf_dynptr *\fP\fIptr\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Reserve \fIsize\fP bytes of payload in a ring buffer \fIringbuf\fP +through the dynptr interface. \fIflags\fP must be 0. +.sp +Please note that a corresponding bpf_ringbuf_submit_dynptr or +bpf_ringbuf_discard_dynptr must be called on \fIptr\fP, even if the +reservation fails. This is enforced by the verifier. +.TP +.B Return +0 on success, or a negative error in case of failure. +.UNINDENT +.TP +.B \fBvoid bpf_ringbuf_submit_dynptr(struct bpf_dynptr *\fP\fIptr\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Submit reserved ring buffer sample, pointed to by \fIdata\fP, +through the dynptr interface. This is a no\-op if the dynptr is +invalid/null. +.sp +For more information on \fIflags\fP, please see +\(aqbpf_ringbuf_submit\(aq. +.TP +.B Return +Nothing. Always succeeds. +.UNINDENT +.TP +.B \fBvoid bpf_ringbuf_discard_dynptr(struct bpf_dynptr *\fP\fIptr\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Discard reserved ring buffer sample through the dynptr +interface. This is a no\-op if the dynptr is invalid/null. +.sp +For more information on \fIflags\fP, please see +\(aqbpf_ringbuf_discard\(aq. +.TP +.B Return +Nothing. Always succeeds. +.UNINDENT +.TP +.B \fBlong bpf_dynptr_read(void *\fP\fIdst\fP\fB, u32\fP \fIlen\fP\fB, const struct bpf_dynptr *\fP\fIsrc\fP\fB, u32\fP \fIoffset\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Read \fIlen\fP bytes from \fIsrc\fP into \fIdst\fP, starting from \fIoffset\fP +into \fIsrc\fP\&. +\fIflags\fP is currently unused. +.TP +.B Return +0 on success, \-E2BIG if \fIoffset\fP + \fIlen\fP exceeds the length +of \fIsrc\fP\(aqs data, \-EINVAL if \fIsrc\fP is an invalid dynptr or if +\fIflags\fP is not 0. +.UNINDENT +.TP +.B \fBlong bpf_dynptr_write(const struct bpf_dynptr *\fP\fIdst\fP\fB, u32\fP \fIoffset\fP\fB, void *\fP\fIsrc\fP\fB, u32\fP \fIlen\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Write \fIlen\fP bytes from \fIsrc\fP into \fIdst\fP, starting from \fIoffset\fP +into \fIdst\fP\&. +.sp +\fIflags\fP must be 0 except for skb\-type dynptrs. +.INDENT 7.0 +.TP +.B For skb\-type dynptrs: +.INDENT 7.0 +.IP \(bu 2 +All data slices of the dynptr are automatically +invalidated after \fBbpf_dynptr_write\fP(). This is +because writing may pull the skb and change the +underlying packet buffer. +.IP \(bu 2 +For \fIflags\fP, please see the flags accepted by +\fBbpf_skb_store_bytes\fP(). +.UNINDENT +.UNINDENT +.TP +.B Return +0 on success, \-E2BIG if \fIoffset\fP + \fIlen\fP exceeds the length +of \fIdst\fP\(aqs data, \-EINVAL if \fIdst\fP is an invalid dynptr or if \fIdst\fP +is a read\-only dynptr or if \fIflags\fP is not correct. For skb\-type dynptrs, +other errors correspond to errors returned by \fBbpf_skb_store_bytes\fP(). +.UNINDENT +.TP +.B \fBvoid *bpf_dynptr_data(const struct bpf_dynptr *\fP\fIptr\fP\fB, u32\fP \fIoffset\fP\fB, u32\fP \fIlen\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get a pointer to the underlying dynptr data. +.sp +\fIlen\fP must be a statically known value. The returned data slice +is invalidated whenever the dynptr is invalidated. +.sp +skb and xdp type dynptrs may not use bpf_dynptr_data. They should +instead use bpf_dynptr_slice and bpf_dynptr_slice_rdwr. +.TP +.B Return +Pointer to the underlying dynptr data, NULL if the dynptr is +read\-only, if the dynptr is invalid, or if the offset and length +is out of bounds. +.UNINDENT +.TP +.B \fBs64 bpf_tcp_raw_gen_syncookie_ipv4(struct iphdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB, u32\fP \fIth_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Try to issue a SYN cookie for the packet with corresponding +IPv4/TCP headers, \fIiph\fP and \fIth\fP, without depending on a +listening socket. +.sp +\fIiph\fP points to the IPv4 header. +.sp +\fIth\fP points to the start of the TCP header, while \fIth_len\fP +contains the length of the TCP header (at least +\fBsizeof\fP(\fBstruct tcphdr\fP)). +.TP +.B Return +On success, lower 32 bits hold the generated SYN cookie in +followed by 16 bits which hold the MSS value for that cookie, +and the top 16 bits are unused. +.sp +On failure, the returned value is one of the following: +.sp +\fB\-EINVAL\fP if \fIth_len\fP is invalid. +.UNINDENT +.TP +.B \fBs64 bpf_tcp_raw_gen_syncookie_ipv6(struct ipv6hdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB, u32\fP \fIth_len\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Try to issue a SYN cookie for the packet with corresponding +IPv6/TCP headers, \fIiph\fP and \fIth\fP, without depending on a +listening socket. +.sp +\fIiph\fP points to the IPv6 header. +.sp +\fIth\fP points to the start of the TCP header, while \fIth_len\fP +contains the length of the TCP header (at least +\fBsizeof\fP(\fBstruct tcphdr\fP)). +.TP +.B Return +On success, lower 32 bits hold the generated SYN cookie in +followed by 16 bits which hold the MSS value for that cookie, +and the top 16 bits are unused. +.sp +On failure, the returned value is one of the following: +.sp +\fB\-EINVAL\fP if \fIth_len\fP is invalid. +.sp +\fB\-EPROTONOSUPPORT\fP if CONFIG_IPV6 is not builtin. +.UNINDENT +.TP +.B \fBlong bpf_tcp_raw_check_syncookie_ipv4(struct iphdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Check whether \fIiph\fP and \fIth\fP contain a valid SYN cookie ACK +without depending on a listening socket. +.sp +\fIiph\fP points to the IPv4 header. +.sp +\fIth\fP points to the TCP header. +.TP +.B Return +0 if \fIiph\fP and \fIth\fP are a valid SYN cookie ACK. +.sp +On failure, the returned value is one of the following: +.sp +\fB\-EACCES\fP if the SYN cookie is not valid. +.UNINDENT +.TP +.B \fBlong bpf_tcp_raw_check_syncookie_ipv6(struct ipv6hdr *\fP\fIiph\fP\fB, struct tcphdr *\fP\fIth\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Check whether \fIiph\fP and \fIth\fP contain a valid SYN cookie ACK +without depending on a listening socket. +.sp +\fIiph\fP points to the IPv6 header. +.sp +\fIth\fP points to the TCP header. +.TP +.B Return +0 if \fIiph\fP and \fIth\fP are a valid SYN cookie ACK. +.sp +On failure, the returned value is one of the following: +.sp +\fB\-EACCES\fP if the SYN cookie is not valid. +.sp +\fB\-EPROTONOSUPPORT\fP if CONFIG_IPV6 is not builtin. +.UNINDENT +.TP +.B \fBu64 bpf_ktime_get_tai_ns(void)\fP +.INDENT 7.0 +.TP +.B Description +A nonsettable system\-wide clock derived from wall\-clock time but +ignoring leap seconds. This clock does not experience +discontinuities and backwards jumps caused by NTP inserting leap +seconds as CLOCK_REALTIME does. +.sp +See: \fBclock_gettime\fP(\fBCLOCK_TAI\fP) +.TP +.B Return +Current \fIktime\fP\&. +.UNINDENT +.TP +.B \fBlong bpf_user_ringbuf_drain(struct bpf_map *\fP\fImap\fP\fB, void *\fP\fIcallback_fn\fP\fB, void *\fP\fIctx\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Drain samples from the specified user ring buffer, and invoke +the provided callback for each such sample: +.sp +long (*callback_fn)(const struct bpf_dynptr *dynptr, void *ctx); +.sp +If \fBcallback_fn\fP returns 0, the helper will continue to try +and drain the next sample, up to a maximum of +BPF_MAX_USER_RINGBUF_SAMPLES samples. If the return value is 1, +the helper will skip the rest of the samples and return. Other +return values are not used now, and will be rejected by the +verifier. +.TP +.B Return +The number of drained samples if no error was encountered while +draining samples, or 0 if no samples were present in the ring +buffer. If a user\-space producer was epoll\-waiting on this map, +and at least one sample was drained, they will receive an event +notification notifying them of available space in the ring +buffer. If the BPF_RB_NO_WAKEUP flag is passed to this +function, no wakeup notification will be sent. If the +BPF_RB_FORCE_WAKEUP flag is passed, a wakeup notification will +be sent even if no sample was drained. +.sp +On failure, the returned value is one of the following: +.sp +\fB\-EBUSY\fP if the ring buffer is contended, and another calling +context was concurrently draining the ring buffer. +.sp +\fB\-EINVAL\fP if user\-space is not properly tracking the ring +buffer due to the producer position not being aligned to 8 +bytes, a sample not being aligned to 8 bytes, or the producer +position not matching the advertised length of a sample. +.sp +\fB\-E2BIG\fP if user\-space has tried to publish a sample which is +larger than the size of the ring buffer, or which cannot fit +within a struct bpf_dynptr. +.UNINDENT +.TP +.B \fBvoid *bpf_cgrp_storage_get(struct bpf_map *\fP\fImap\fP\fB, struct cgroup *\fP\fIcgroup\fP\fB, void *\fP\fIvalue\fP\fB, u64\fP \fIflags\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Get a bpf_local_storage from the \fIcgroup\fP\&. +.sp +Logically, it could be thought of as getting the value from +a \fImap\fP with \fIcgroup\fP as the \fBkey\fP\&. From this +perspective, the usage is not much different from +\fBbpf_map_lookup_elem\fP(\fImap\fP, \fB&\fP\fIcgroup\fP) except this +helper enforces the key must be a cgroup struct and the map must also +be a \fBBPF_MAP_TYPE_CGRP_STORAGE\fP\&. +.sp +In reality, the local\-storage value is embedded directly inside of the +\fIcgroup\fP object itself, rather than being located in the +\fBBPF_MAP_TYPE_CGRP_STORAGE\fP map. When the local\-storage value is +queried for some \fImap\fP on a \fIcgroup\fP object, the kernel will perform an +O(n) iteration over all of the live local\-storage values for that +\fIcgroup\fP object until the local\-storage value for the \fImap\fP is found. +.sp +An optional \fIflags\fP (\fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP) can be +used such that a new bpf_local_storage will be +created if one does not exist. \fIvalue\fP can be used +together with \fBBPF_LOCAL_STORAGE_GET_F_CREATE\fP to specify +the initial value of a bpf_local_storage. If \fIvalue\fP is +\fBNULL\fP, the new bpf_local_storage will be zero initialized. +.TP +.B Return +A bpf_local_storage pointer is returned on success. +.sp +\fBNULL\fP if not found or there was an error in adding +a new bpf_local_storage. +.UNINDENT +.TP +.B \fBlong bpf_cgrp_storage_delete(struct bpf_map *\fP\fImap\fP\fB, struct cgroup *\fP\fIcgroup\fP\fB)\fP +.INDENT 7.0 +.TP +.B Description +Delete a bpf_local_storage from a \fIcgroup\fP\&. +.TP +.B Return +0 on success. +.sp +\fB\-ENOENT\fP if the bpf_local_storage cannot be found. +.UNINDENT +.UNINDENT +.SH EXAMPLES +.sp +Example usage for most of the eBPF helpers listed in this manual page are +available within the Linux kernel sources, at the following locations: +.INDENT 0.0 +.IP \(bu 2 +\fIsamples/bpf/\fP +.IP \(bu 2 +\fItools/testing/selftests/bpf/\fP +.UNINDENT +.SH LICENSE +.sp +eBPF programs can have an associated license, passed along with the bytecode +instructions to the kernel when the programs are loaded. The format for that +string is identical to the one in use for kernel modules (Dual licenses, such +as \(dqDual BSD/GPL\(dq, may be used). Some helper functions are only accessible to +programs that are compatible with the GNU General Public License (GNU GPL). +.sp +In order to use such helpers, the eBPF program must be loaded with the correct +license string passed (via \fBattr\fP) to the \fBbpf\fP() system call, and this +generally translates into the C source code of the program containing a line +similar to the following: +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +char ____license[] __attribute__((section(\(dqlicense\(dq), used)) = \(dqGPL\(dq; +.EE +.UNINDENT +.UNINDENT +.SH IMPLEMENTATION +.sp +This manual page is an effort to document the existing eBPF helper functions. +But as of this writing, the BPF sub\-system is under heavy development. New eBPF +program or map types are added, along with new helper functions. Some helpers +are occasionally made available for additional program types. So in spite of +the efforts of the community, this page might not be up\-to\-date. If you want to +check by yourself what helper functions exist in your kernel, or what types of +programs they can support, here are some files among the kernel tree that you +may be interested in: +.INDENT 0.0 +.IP \(bu 2 +\fIinclude/uapi/linux/bpf.h\fP is the main BPF header. It contains the full list +of all helper functions, as well as many other BPF definitions including most +of the flags, structs or constants used by the helpers. +.IP \(bu 2 +\fInet/core/filter.c\fP contains the definition of most network\-related helper +functions, and the list of program types from which they can be used. +.IP \(bu 2 +\fIkernel/trace/bpf_trace.c\fP is the equivalent for most tracing program\-related +helpers. +.IP \(bu 2 +\fIkernel/bpf/verifier.c\fP contains the functions used to check that valid types +of eBPF maps are used with a given helper function. +.IP \(bu 2 +\fIkernel/bpf/\fP directory contains other files in which additional helpers are +defined (for cgroups, sockmaps, etc.). +.IP \(bu 2 +The bpftool utility can be used to probe the availability of helper functions +on the system (as well as supported program and map types, and a number of +other parameters). To do so, run \fBbpftool feature probe\fP (see +\fBbpftool\-feature\fP(8) for details). Add the \fBunprivileged\fP keyword to +list features available to unprivileged users. +.UNINDENT +.sp +Compatibility between helper functions and program types can generally be found +in the files where helper functions are defined. Look for the \fBstruct +bpf_func_proto\fP objects and for functions returning them: these functions +contain a list of helpers that a given program type can call. Note that the +\fBdefault:\fP label of the \fBswitch ... case\fP used to filter helpers can call +other functions, themselves allowing access to additional helpers. The +requirement for GPL license is also in those \fBstruct bpf_func_proto\fP\&. +.sp +Compatibility between helper functions and map types can be found in the +\fBcheck_map_func_compatibility\fP() function in file \fIkernel/bpf/verifier.c\fP\&. +.sp +Helper functions that invalidate the checks on \fBdata\fP and \fBdata_end\fP +pointers for network processing are listed in function +\fBbpf_helper_changes_pkt_data\fP() in file \fInet/core/filter.c\fP\&. +.SH SEE ALSO +.sp +\fBbpf\fP(2), +\fBbpftool\fP(8), +\fBcgroups\fP(7), +\fBip\fP(8), +\fBperf_event_open\fP(2), +\fBsendmsg\fP(2), +\fBsocket\fP(7), +\fBtc\-bpf\fP(8) +.\" Generated by docutils manpage writer. +. diff --git a/man/man7/capabilities.7 b/man/man7/capabilities.7 new file mode 100644 index 0000000..98b65f4 --- /dev/null +++ b/man/man7/capabilities.7 @@ -0,0 +1,1872 @@ +.\" Copyright (c) 2002 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 6 Aug 2002 - Initial Creation +.\" Modified 2003-05-23, Michael Kerrisk, +.\" Modified 2004-05-27, Michael Kerrisk, +.\" 2004-12-08, mtk Added O_NOATIME for CAP_FOWNER +.\" 2005-08-16, mtk, Added CAP_AUDIT_CONTROL and CAP_AUDIT_WRITE +.\" 2008-07-15, Serge Hallyn +.\" Document file capabilities, per-process capability +.\" bounding set, changed semantics for CAP_SETPCAP, +.\" and other changes in Linux 2.6.2[45]. +.\" Add CAP_MAC_ADMIN, CAP_MAC_OVERRIDE, CAP_SETFCAP. +.\" 2008-07-15, mtk +.\" Add text describing circumstances in which CAP_SETPCAP +.\" (theoretically) permits a thread to change the +.\" capability sets of another thread. +.\" Add section describing rules for programmatically +.\" adjusting thread capability sets. +.\" Describe rationale for capability bounding set. +.\" Document "securebits" flags. +.\" Add text noting that if we set the effective flag for one file +.\" capability, then we must also set the effective flag for all +.\" other capabilities where the permitted or inheritable bit is set. +.\" 2011-09-07, mtk/Serge hallyn: Add CAP_SYSLOG +.\" +.TH Capabilities 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +capabilities \- overview of Linux capabilities +.SH DESCRIPTION +For the purpose of performing permission checks, +traditional UNIX implementations distinguish two categories of processes: +.I privileged +processes (whose effective user ID is 0, referred to as superuser or root), +and +.I unprivileged +processes (whose effective UID is nonzero). +Privileged processes bypass all kernel permission checks, +while unprivileged processes are subject to full permission +checking based on the process's credentials +(usually: effective UID, effective GID, and supplementary group list). +.P +Starting with Linux 2.2, Linux divides the privileges traditionally +associated with superuser into distinct units, known as +.IR capabilities , +which can be independently enabled and disabled. +Capabilities are a per-thread attribute. +.\" +.SS Capabilities list +The following list shows the capabilities implemented on Linux, +and the operations or behaviors that each capability permits: +.TP +.BR CAP_AUDIT_CONTROL " (since Linux 2.6.11)" +Enable and disable kernel auditing; change auditing filter rules; +retrieve auditing status and filtering rules. +.TP +.BR CAP_AUDIT_READ " (since Linux 3.16)" +.\" commit a29b694aa1739f9d76538e34ae25524f9c549d59 +.\" commit 3a101b8de0d39403b2c7e5c23fd0b005668acf48 +Allow reading the audit log via a multicast netlink socket. +.TP +.BR CAP_AUDIT_WRITE " (since Linux 2.6.11)" +Write records to kernel auditing log. +.\" FIXME Add FAN_ENABLE_AUDIT +.TP +.BR CAP_BLOCK_SUSPEND " (since Linux 3.5)" +Employ features that can block system suspend +.RB ( epoll (7) +.BR EPOLLWAKEUP , +.IR /proc/sys/wake_lock ). +.TP +.BR CAP_BPF " (since Linux 5.8)" +Employ privileged BPF operations; see +.BR bpf (2) +and +.BR bpf\-helpers (7). +.IP +This capability was added in Linux 5.8 to separate out +BPF functionality from the overloaded +.B CAP_SYS_ADMIN +capability. +.TP +.BR CAP_CHECKPOINT_RESTORE " (since Linux 5.9)" +.\" commit 124ea650d3072b005457faed69909221c2905a1f +.PD 0 +.RS +.IP \[bu] 3 +Update +.I /proc/sys/kernel/ns_last_pid +(see +.BR pid_namespaces (7)); +.IP \[bu] +employ the +.I set_tid +feature of +.BR clone3 (2); +.\" FIXME There is also some use case relating to +.\" prctl_set_mm_exe_file(); in the 5.9 sources, see +.\" prctl_set_mm_map(). +.IP \[bu] +read the contents of the symbolic links in +.IR /proc/ pid /map_files +for other processes. +.RE +.PD +.IP +This capability was added in Linux 5.9 to separate out +checkpoint/restore functionality from the overloaded +.B CAP_SYS_ADMIN +capability. +.TP +.B CAP_CHOWN +Make arbitrary changes to file UIDs and GIDs (see +.BR chown (2)). +.TP +.B CAP_DAC_OVERRIDE +Bypass file read, write, and execute permission checks. +(DAC is an abbreviation of "discretionary access control".) +.TP +.B CAP_DAC_READ_SEARCH +.PD 0 +.RS +.IP \[bu] 3 +Bypass file read permission checks and +directory read and execute permission checks; +.IP \[bu] +invoke +.BR open_by_handle_at (2); +.IP \[bu] +use the +.BR linkat (2) +.B AT_EMPTY_PATH +flag to create a link to a file referred to by a file descriptor. +.RE +.PD +.TP +.B CAP_FOWNER +.PD 0 +.RS +.IP \[bu] 3 +Bypass permission checks on operations that normally +require the filesystem UID of the process to match the UID of +the file (e.g., +.BR chmod (2), +.BR utime (2)), +excluding those operations covered by +.B CAP_DAC_OVERRIDE +and +.BR CAP_DAC_READ_SEARCH ; +.IP \[bu] +set inode flags (see +.BR ioctl_iflags (2)) +on arbitrary files; +.IP \[bu] +set Access Control Lists (ACLs) on arbitrary files; +.IP \[bu] +ignore directory sticky bit on file deletion; +.IP \[bu] +modify +.I user +extended attributes on sticky directory owned by any user; +.IP \[bu] +specify +.B O_NOATIME +for arbitrary files in +.BR open (2) +and +.BR fcntl (2). +.RE +.PD +.TP +.B CAP_FSETID +.PD 0 +.RS +.IP \[bu] 3 +Don't clear set-user-ID and set-group-ID mode +bits when a file is modified; +.IP \[bu] +set the set-group-ID bit for a file whose GID does not match +the filesystem or any of the supplementary GIDs of the calling process. +.RE +.PD +.TP +.B CAP_IPC_LOCK +.\" FIXME . As at Linux 3.2, there are some strange uses of this capability +.\" in other places; they probably should be replaced with something else. +.PD 0 +.RS +.IP \[bu] 3 +Lock memory +.RB ( mlock (2), +.BR mlockall (2), +.BR mmap (2), +.BR shmctl (2)); +.IP \[bu] +Allocate memory using huge pages +.RB ( memfd_create (2), +.BR mmap (2), +.BR shmctl (2)). +.RE +.PD +.TP +.B CAP_IPC_OWNER +Bypass permission checks for operations on System V IPC objects. +.TP +.B CAP_KILL +Bypass permission checks for sending signals (see +.BR kill (2)). +This includes use of the +.BR ioctl (2) +.B KDSIGACCEPT +operation. +.\" FIXME . CAP_KILL also has an effect for threads + setting child +.\" termination signal to other than SIGCHLD: without this +.\" capability, the termination signal reverts to SIGCHLD +.\" if the child does an exec(). What is the rationale +.\" for this? +.TP +.BR CAP_LEASE " (since Linux 2.4)" +Establish leases on arbitrary files (see +.BR fcntl (2)). +.TP +.B CAP_LINUX_IMMUTABLE +Set the +.B FS_APPEND_FL +and +.B FS_IMMUTABLE_FL +inode flags (see +.BR ioctl_iflags (2)). +.TP +.BR CAP_MAC_ADMIN " (since Linux 2.6.25)" +Allow MAC configuration or state changes. +Implemented for the Smack Linux Security Module (LSM). +.TP +.BR CAP_MAC_OVERRIDE " (since Linux 2.6.25)" +Override Mandatory Access Control (MAC). +Implemented for the Smack LSM. +.TP +.BR CAP_MKNOD " (since Linux 2.4)" +Create special files using +.BR mknod (2). +.TP +.B CAP_NET_ADMIN +Perform various network-related operations: +.PD 0 +.RS +.IP \[bu] 3 +interface configuration; +.IP \[bu] +administration of IP firewall, masquerading, and accounting; +.IP \[bu] +modify routing tables; +.IP \[bu] +bind to any address for transparent proxying; +.IP \[bu] +set type-of-service (TOS); +.IP \[bu] +clear driver statistics; +.IP \[bu] +set promiscuous mode; +.IP \[bu] +enabling multicasting; +.IP \[bu] +use +.BR setsockopt (2) +to set the following socket options: +.BR SO_DEBUG , +.BR SO_MARK , +.B SO_PRIORITY +(for a priority outside the range 0 to 6), +.BR SO_RCVBUFFORCE , +and +.BR SO_SNDBUFFORCE . +.RE +.PD +.TP +.B CAP_NET_BIND_SERVICE +Bind a socket to Internet domain privileged ports +(port numbers less than 1024). +.TP +.B CAP_NET_BROADCAST +(Unused) Make socket broadcasts, and listen to multicasts. +.\" FIXME Since Linux 4.2, there are use cases for netlink sockets +.\" commit 59324cf35aba5336b611074028777838a963d03b +.TP +.B CAP_NET_RAW +.PD 0 +.RS +.IP \[bu] 3 +Use RAW and PACKET sockets; +.IP \[bu] +bind to any address for transparent proxying. +.RE +.PD +.\" Also various IP options and setsockopt(SO_BINDTODEVICE) +.TP +.BR CAP_PERFMON " (since Linux 5.8)" +Employ various performance-monitoring mechanisms, including: +.RS +.IP \[bu] 3 +.PD 0 +call +.BR perf_event_open (2); +.IP \[bu] +employ various BPF operations that have performance implications. +.RE +.PD +.IP +This capability was added in Linux 5.8 to separate out +performance monitoring functionality from the overloaded +.B CAP_SYS_ADMIN +capability. +See also the kernel source file +.IR Documentation/admin\-guide/perf\-security.rst . +.TP +.B CAP_SETGID +.RS +.PD 0 +.IP \[bu] 3 +Make arbitrary manipulations of process GIDs and supplementary GID list; +.IP \[bu] +forge GID when passing socket credentials via UNIX domain sockets; +.IP \[bu] +write a group ID mapping in a user namespace (see +.BR user_namespaces (7)). +.PD +.RE +.TP +.BR CAP_SETFCAP " (since Linux 2.6.24)" +Set arbitrary capabilities on a file. +.IP +.\" commit db2e718a47984b9d71ed890eb2ea36ecf150de18 +Since Linux 5.12, this capability is +also needed to map user ID 0 in a new user namespace; see +.BR user_namespaces (7) +for details. +.TP +.B CAP_SETPCAP +If file capabilities are supported (i.e., since Linux 2.6.24): +add any capability from the calling thread's bounding set +to its inheritable set; +drop capabilities from the bounding set (via +.BR prctl (2) +.BR PR_CAPBSET_DROP ); +make changes to the +.I securebits +flags. +.IP +If file capabilities are not supported (i.e., before Linux 2.6.24): +grant or remove any capability in the +caller's permitted capability set to or from any other process. +(This property of +.B CAP_SETPCAP +is not available when the kernel is configured to support +file capabilities, since +.B CAP_SETPCAP +has entirely different semantics for such kernels.) +.TP +.B CAP_SETUID +.RS +.PD 0 +.IP \[bu] 3 +Make arbitrary manipulations of process UIDs +.RB ( setuid (2), +.BR setreuid (2), +.BR setresuid (2), +.BR setfsuid (2)); +.IP \[bu] +forge UID when passing socket credentials via UNIX domain sockets; +.IP \[bu] +write a user ID mapping in a user namespace (see +.BR user_namespaces (7)). +.PD +.RE +.\" FIXME CAP_SETUID also an effect in exec(); document this. +.TP +.B CAP_SYS_ADMIN +.IR Note : +this capability is overloaded; see +.I Notes to kernel developers +below. +.IP +.PD 0 +.RS +.IP \[bu] 3 +Perform a range of system administration operations including: +.BR quotactl (2), +.BR mount (2), +.BR umount (2), +.BR pivot_root (2), +.BR swapon (2), +.BR swapoff (2), +.BR sethostname (2), +and +.BR setdomainname (2); +.IP \[bu] +perform privileged +.BR syslog (2) +operations (since Linux 2.6.37, +.B CAP_SYSLOG +should be used to permit such operations); +.IP \[bu] +perform +.B VM86_REQUEST_IRQ +.BR vm86 (2) +command; +.IP \[bu] +access the same checkpoint/restore functionality that is governed by +.B CAP_CHECKPOINT_RESTORE +(but the latter, weaker capability is preferred for accessing +that functionality). +.IP \[bu] +perform the same BPF operations as are governed by +.B CAP_BPF +(but the latter, weaker capability is preferred for accessing +that functionality). +.IP \[bu] +employ the same performance monitoring mechanisms as are governed by +.B CAP_PERFMON +(but the latter, weaker capability is preferred for accessing +that functionality). +.IP \[bu] +perform +.B IPC_SET +and +.B IPC_RMID +operations on arbitrary System V IPC objects; +.IP \[bu] +override +.B RLIMIT_NPROC +resource limit; +.IP \[bu] +perform operations on +.I trusted +and +.I security +extended attributes (see +.BR xattr (7)); +.IP \[bu] +use +.BR lookup_dcookie (2); +.IP \[bu] +use +.BR ioprio_set (2) +to assign +.B IOPRIO_CLASS_RT +and (before Linux 2.6.25) +.B IOPRIO_CLASS_IDLE +I/O scheduling classes; +.IP \[bu] +forge PID when passing socket credentials via UNIX domain sockets; +.IP \[bu] +exceed +.IR /proc/sys/fs/file\-max , +the system-wide limit on the number of open files, +in system calls that open files (e.g., +.BR accept (2), +.BR execve (2), +.BR open (2), +.BR pipe (2)); +.IP \[bu] +employ +.B CLONE_* +flags that create new namespaces with +.BR clone (2) +and +.BR unshare (2) +(but, since Linux 3.8, +creating user namespaces does not require any capability); +.IP \[bu] +access privileged +.I perf +event information; +.IP \[bu] +call +.BR setns (2) +(requires +.B CAP_SYS_ADMIN +in the +.I target +namespace); +.IP \[bu] +call +.BR fanotify_init (2); +.IP \[bu] +perform privileged +.B KEYCTL_CHOWN +and +.B KEYCTL_SETPERM +.BR keyctl (2) +operations; +.IP \[bu] +perform +.BR madvise (2) +.B MADV_HWPOISON +operation; +.IP \[bu] +employ the +.B TIOCSTI +.BR ioctl (2) +to insert characters into the input queue of a terminal other than +the caller's controlling terminal; +.IP \[bu] +employ the obsolete +.BR nfsservctl (2) +system call; +.IP \[bu] +employ the obsolete +.BR bdflush (2) +system call; +.IP \[bu] +perform various privileged block-device +.BR ioctl (2) +operations; +.IP \[bu] +perform various privileged filesystem +.BR ioctl (2) +operations; +.IP \[bu] +perform privileged +.BR ioctl (2) +operations on the +.I /dev/random +device (see +.BR random (4)); +.IP \[bu] +install a +.BR seccomp (2) +filter without first having to set the +.I no_new_privs +thread attribute; +.IP \[bu] +modify allow/deny rules for device control groups; +.IP \[bu] +employ the +.BR ptrace (2) +.B PTRACE_SECCOMP_GET_FILTER +operation to dump tracee's seccomp filters; +.IP \[bu] +employ the +.BR ptrace (2) +.B PTRACE_SETOPTIONS +operation to suspend the tracee's seccomp protections (i.e., the +.B PTRACE_O_SUSPEND_SECCOMP +flag); +.IP \[bu] +perform administrative operations on many device drivers; +.IP \[bu] +modify autogroup nice values by writing to +.IR /proc/ pid /autogroup +(see +.BR sched (7)). +.RE +.PD +.TP +.B CAP_SYS_BOOT +Use +.BR reboot (2) +and +.BR kexec_load (2). +.TP +.B CAP_SYS_CHROOT +.RS +.PD 0 +.IP \[bu] 3 +Use +.BR chroot (2); +.IP \[bu] +change mount namespaces using +.BR setns (2). +.PD +.RE +.TP +.B CAP_SYS_MODULE +.RS +.PD 0 +.IP \[bu] 3 +Load and unload kernel modules +(see +.BR init_module (2) +and +.BR delete_module (2)); +.IP \[bu] +before Linux 2.6.25: +drop capabilities from the system-wide capability bounding set. +.PD +.RE +.TP +.B CAP_SYS_NICE +.PD 0 +.RS +.IP \[bu] 3 +Lower the process nice value +.RB ( nice (2), +.BR setpriority (2)) +and change the nice value for arbitrary processes; +.IP \[bu] +set real-time scheduling policies for calling process, +and set scheduling policies and priorities for arbitrary processes +.RB ( sched_setscheduler (2), +.BR sched_setparam (2), +.BR sched_setattr (2)); +.IP \[bu] +set CPU affinity for arbitrary processes +.RB ( sched_setaffinity (2)); +.IP \[bu] +set I/O scheduling class and priority for arbitrary processes +.RB ( ioprio_set (2)); +.IP \[bu] +apply +.BR migrate_pages (2) +to arbitrary processes and allow processes +to be migrated to arbitrary nodes; +.\" FIXME CAP_SYS_NICE also has the following effect for +.\" migrate_pages(2): +.\" do_migrate_pages(mm, &old, &new, +.\" capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE); +.\" +.\" Document this. +.IP \[bu] +apply +.BR move_pages (2) +to arbitrary processes; +.IP \[bu] +use the +.B MPOL_MF_MOVE_ALL +flag with +.BR mbind (2) +and +.BR move_pages (2). +.RE +.PD +.TP +.B CAP_SYS_PACCT +Use +.BR acct (2). +.TP +.B CAP_SYS_PTRACE +.PD 0 +.RS +.IP \[bu] 3 +Trace arbitrary processes using +.BR ptrace (2); +.IP \[bu] +apply +.BR get_robust_list (2) +to arbitrary processes; +.IP \[bu] +transfer data to or from the memory of arbitrary processes using +.BR process_vm_readv (2) +and +.BR process_vm_writev (2); +.IP \[bu] +inspect processes using +.BR kcmp (2). +.RE +.PD +.TP +.B CAP_SYS_RAWIO +.PD 0 +.RS +.IP \[bu] 3 +Perform I/O port operations +.RB ( iopl (2) +and +.BR ioperm (2)); +.IP \[bu] +access +.IR /proc/kcore ; +.IP \[bu] +employ the +.B FIBMAP +.BR ioctl (2) +operation; +.IP \[bu] +open devices for accessing x86 model-specific registers (MSRs, see +.BR msr (4)); +.IP \[bu] +update +.IR /proc/sys/vm/mmap_min_addr ; +.IP \[bu] +create memory mappings at addresses below the value specified by +.IR /proc/sys/vm/mmap_min_addr ; +.IP \[bu] +map files in +.IR /proc/bus/pci ; +.IP \[bu] +open +.I /dev/mem +and +.IR /dev/kmem ; +.IP \[bu] +perform various SCSI device commands; +.IP \[bu] +perform certain operations on +.BR hpsa (4) +and +.BR cciss (4) +devices; +.IP \[bu] +perform a range of device-specific operations on other devices. +.RE +.PD +.TP +.B CAP_SYS_RESOURCE +.PD 0 +.RS +.IP \[bu] 3 +Use reserved space on ext2 filesystems; +.IP \[bu] +make +.BR ioctl (2) +calls controlling ext3 journaling; +.IP \[bu] +override disk quota limits; +.IP \[bu] +increase resource limits (see +.BR setrlimit (2)); +.IP \[bu] +override +.B RLIMIT_NPROC +resource limit; +.IP \[bu] +override maximum number of consoles on console allocation; +.IP \[bu] +override maximum number of keymaps; +.IP \[bu] +allow more than 64hz interrupts from the real-time clock; +.IP \[bu] +raise +.I msg_qbytes +limit for a System V message queue above the limit in +.I /proc/sys/kernel/msgmnb +(see +.BR msgop (2) +and +.BR msgctl (2)); +.IP \[bu] +allow the +.B RLIMIT_NOFILE +resource limit on the number of "in-flight" file descriptors +to be bypassed when passing file descriptors to another process +via a UNIX domain socket (see +.BR unix (7)); +.IP \[bu] +override the +.I /proc/sys/fs/pipe\-size\-max +limit when setting the capacity of a pipe using the +.B F_SETPIPE_SZ +.BR fcntl (2) +command; +.IP \[bu] +use +.B F_SETPIPE_SZ +to increase the capacity of a pipe above the limit specified by +.IR /proc/sys/fs/pipe\-max\-size ; +.IP \[bu] +override +.IR /proc/sys/fs/mqueue/queues_max , +.IR /proc/sys/fs/mqueue/msg_max , +and +.I /proc/sys/fs/mqueue/msgsize_max +limits when creating POSIX message queues (see +.BR mq_overview (7)); +.IP \[bu] +employ the +.BR prctl (2) +.B PR_SET_MM +operation; +.IP \[bu] +set +.IR /proc/ pid /oom_score_adj +to a value lower than the value last set by a process with +.BR CAP_SYS_RESOURCE . +.RE +.PD +.TP +.B CAP_SYS_TIME +Set system clock +.RB ( settimeofday (2), +.BR stime (2), +.BR adjtimex (2)); +set real-time (hardware) clock. +.TP +.B CAP_SYS_TTY_CONFIG +Use +.BR vhangup (2); +employ various privileged +.BR ioctl (2) +operations on virtual terminals. +.TP +.BR CAP_SYSLOG " (since Linux 2.6.37)" +.RS +.PD 0 +.IP \[bu] 3 +Perform privileged +.BR syslog (2) +operations. +See +.BR syslog (2) +for information on which operations require privilege. +.IP \[bu] +View kernel addresses exposed via +.I /proc +and other interfaces when +.I /proc/sys/kernel/kptr_restrict +has the value 1. +(See the discussion of the +.I kptr_restrict +in +.BR proc (5).) +.PD +.RE +.TP +.BR CAP_WAKE_ALARM " (since Linux 3.0)" +Trigger something that will wake up the system (set +.B CLOCK_REALTIME_ALARM +and +.B CLOCK_BOOTTIME_ALARM +timers). +.\" +.SS Past and current implementation +A full implementation of capabilities requires that: +.IP \[bu] 3 +For all privileged operations, +the kernel must check whether the thread has the required +capability in its effective set. +.IP \[bu] +The kernel must provide system calls allowing a thread's capability sets to +be changed and retrieved. +.IP \[bu] +The filesystem must support attaching capabilities to an executable file, +so that a process gains those capabilities when the file is executed. +.P +Before Linux 2.6.24, only the first two of these requirements are met; +since Linux 2.6.24, all three requirements are met. +.\" +.SS Notes to kernel developers +When adding a new kernel feature that should be governed by a capability, +consider the following points. +.IP \[bu] 3 +The goal of capabilities is divide the power of superuser into pieces, +such that if a program that has one or more capabilities is compromised, +its power to do damage to the system would be less than the same program +running with root privilege. +.IP \[bu] +You have the choice of either creating a new capability for your new feature, +or associating the feature with one of the existing capabilities. +In order to keep the set of capabilities to a manageable size, +the latter option is preferable, +unless there are compelling reasons to take the former option. +(There is also a technical limit: +the size of capability sets is currently limited to 64 bits.) +.IP \[bu] +To determine which existing capability might best be associated +with your new feature, review the list of capabilities above in order +to find a "silo" into which your new feature best fits. +One approach to take is to determine if there are other features +requiring capabilities that will always be used along with the new feature. +If the new feature is useless without these other features, +you should use the same capability as the other features. +.IP \[bu] +.I Don't +choose +.B CAP_SYS_ADMIN +if you can possibly avoid it! +A vast proportion of existing capability checks are associated +with this capability (see the partial list above). +It can plausibly be called "the new root", +since on the one hand, it confers a wide range of powers, +and on the other hand, +its broad scope means that this is the capability +that is required by many privileged programs. +Don't make the problem worse. +The only new features that should be associated with +.B CAP_SYS_ADMIN +are ones that +.I closely +match existing uses in that silo. +.IP \[bu] +If you have determined that it really is necessary to create +a new capability for your feature, +don't make or name it as a "single-use" capability. +Thus, for example, the addition of the highly specific +.B CAP_SYS_PACCT +was probably a mistake. +Instead, try to identify and name your new capability as a broader +silo into which other related future use cases might fit. +.\" +.SS Thread capability sets +Each thread has the following capability sets containing zero or more +of the above capabilities: +.TP +.I Permitted +This is a limiting superset for the effective +capabilities that the thread may assume. +It is also a limiting superset for the capabilities that +may be added to the inheritable set by a thread that does not have the +.B CAP_SETPCAP +capability in its effective set. +.IP +If a thread drops a capability from its permitted set, +it can never reacquire that capability (unless it +.BR execve (2)s +either a set-user-ID-root program, or +a program whose associated file capabilities grant that capability). +.TP +.I Inheritable +This is a set of capabilities preserved across an +.BR execve (2). +Inheritable capabilities remain inheritable when executing any program, +and inheritable capabilities are added to the permitted set when executing +a program that has the corresponding bits set in the file inheritable set. +.IP +Because inheritable capabilities are not generally preserved across +.BR execve (2) +when running as a non-root user, applications that wish to run helper +programs with elevated capabilities should consider using +ambient capabilities, described below. +.TP +.I Effective +This is the set of capabilities used by the kernel to +perform permission checks for the thread. +.TP +.IR Bounding " (per-thread since Linux 2.6.25)" +The capability bounding set is a mechanism that can be used +to limit the capabilities that are gained during +.BR execve (2). +.IP +Since Linux 2.6.25, this is a per-thread capability set. +In older kernels, the capability bounding set was a system wide attribute +shared by all threads on the system. +.IP +For more details, see +.I Capability bounding set +below. +.TP +.IR Ambient " (since Linux 4.3)" +.\" commit 58319057b7847667f0c9585b9de0e8932b0fdb08 +This is a set of capabilities that are preserved across an +.BR execve (2) +of a program that is not privileged. +The ambient capability set obeys the invariant that no capability +can ever be ambient if it is not both permitted and inheritable. +.IP +The ambient capability set can be directly modified using +.BR prctl (2). +Ambient capabilities are automatically lowered if either of +the corresponding permitted or inheritable capabilities is lowered. +.IP +Executing a program that changes UID or GID due to the +set-user-ID or set-group-ID bits or executing a program that has +any file capabilities set will clear the ambient set. +Ambient capabilities are added to the permitted set and +assigned to the effective set when +.BR execve (2) +is called. +If ambient capabilities cause a process's permitted and effective +capabilities to increase during an +.BR execve (2), +this does not trigger the secure-execution mode described in +.BR ld.so (8). +.P +A child created via +.BR fork (2) +inherits copies of its parent's capability sets. +For details on how +.BR execve (2) +affects capabilities, see +.I Transformation of capabilities during execve() +below. +.P +Using +.BR capset (2), +a thread may manipulate its own capability sets; see +.I Programmatically adjusting capability sets +below. +.P +Since Linux 3.2, the file +.I /proc/sys/kernel/cap_last_cap +.\" commit 73efc0394e148d0e15583e13712637831f926720 +exposes the numerical value of the highest capability +supported by the running kernel; +this can be used to determine the highest bit +that may be set in a capability set. +.\" +.SS File capabilities +Since Linux 2.6.24, the kernel supports +associating capability sets with an executable file using +.BR setcap (8). +The file capability sets are stored in an extended attribute (see +.BR setxattr (2) +and +.BR xattr (7)) +named +.IR "security.capability" . +Writing to this extended attribute requires the +.B CAP_SETFCAP +capability. +The file capability sets, +in conjunction with the capability sets of the thread, +determine the capabilities of a thread after an +.BR execve (2). +.P +The three file capability sets are: +.TP +.IR Permitted " (formerly known as " forced ): +These capabilities are automatically permitted to the thread, +regardless of the thread's inheritable capabilities. +.TP +.IR Inheritable " (formerly known as " allowed ): +This set is ANDed with the thread's inheritable set to determine which +inheritable capabilities are enabled in the permitted set of +the thread after the +.BR execve (2). +.TP +.IR Effective : +This is not a set, but rather just a single bit. +If this bit is set, then during an +.BR execve (2) +all of the new permitted capabilities for the thread are +also raised in the effective set. +If this bit is not set, then after an +.BR execve (2), +none of the new permitted capabilities is in the new effective set. +.IP +Enabling the file effective capability bit implies +that any file permitted or inheritable capability that causes a +thread to acquire the corresponding permitted capability during an +.BR execve (2) +(see +.I Transformation of capabilities during execve() +below) will also acquire that +capability in its effective set. +Therefore, when assigning capabilities to a file +.RB ( setcap (8), +.BR cap_set_file (3), +.BR cap_set_fd (3)), +if we specify the effective flag as being enabled for any capability, +then the effective flag must also be specified as enabled +for all other capabilities for which the corresponding permitted or +inheritable flag is enabled. +.\" +.SS File capability extended attribute versioning +To allow extensibility, +the kernel supports a scheme to encode a version number inside the +.I security.capability +extended attribute that is used to implement file capabilities. +These version numbers are internal to the implementation, +and not directly visible to user-space applications. +To date, the following versions are supported: +.TP +.B VFS_CAP_REVISION_1 +This was the original file capability implementation, +which supported 32-bit masks for file capabilities. +.TP +.BR VFS_CAP_REVISION_2 " (since Linux 2.6.25)" +.\" commit e338d263a76af78fe8f38a72131188b58fceb591 +This version allows for file capability masks that are 64 bits in size, +and was necessary as the number of supported capabilities grew beyond 32. +The kernel transparently continues to support the execution of files +that have 32-bit version 1 capability masks, +but when adding capabilities to files that did not previously +have capabilities, or modifying the capabilities of existing files, +it automatically uses the version 2 scheme +(or possibly the version 3 scheme, as described below). +.TP +.BR VFS_CAP_REVISION_3 " (since Linux 4.14)" +.\" commit 8db6c34f1dbc8e06aa016a9b829b06902c3e1340 +Version 3 file capabilities are provided +to support namespaced file capabilities (described below). +.IP +As with version 2 file capabilities, +version 3 capability masks are 64 bits in size. +But in addition, the root user ID of namespace is encoded in the +.I security.capability +extended attribute. +(A namespace's root user ID is the value that user ID 0 +inside that namespace maps to in the initial user namespace.) +.IP +Version 3 file capabilities are designed to coexist +with version 2 capabilities; +that is, on a modern Linux system, +there may be some files with version 2 capabilities +while others have version 3 capabilities. +.P +Before Linux 4.14, +the only kind of file capability extended attribute +that could be attached to a file was a +.B VFS_CAP_REVISION_2 +attribute. +Since Linux 4.14, +the version of the +.I security.capability +extended attribute that is attached to a file +depends on the circumstances in which the attribute was created. +.P +Starting with Linux 4.14, a +.I security.capability +extended attribute is automatically created as (or converted to) +a version 3 +.RB ( VFS_CAP_REVISION_3 ) +attribute if both of the following are true: +.IP \[bu] 3 +The thread writing the attribute resides in a noninitial user namespace. +(More precisely: the thread resides in a user namespace other +than the one from which the underlying filesystem was mounted.) +.IP \[bu] +The thread has the +.B CAP_SETFCAP +capability over the file inode, +meaning that (a) the thread has the +.B CAP_SETFCAP +capability in its own user namespace; +and (b) the UID and GID of the file inode have mappings in +the writer's user namespace. +.P +When a +.B VFS_CAP_REVISION_3 +.I security.capability +extended attribute is created, the root user ID of the creating thread's +user namespace is saved in the extended attribute. +.P +By contrast, creating or modifying a +.I security.capability +extended attribute from a privileged +.RB ( CAP_SETFCAP ) +thread that resides in the +namespace where the underlying filesystem was mounted +(this normally means the initial user namespace) +automatically results in the creation of a version 2 +.RB ( VFS_CAP_REVISION_2 ) +attribute. +.P +Note that the creation of a version 3 +.I security.capability +extended attribute is automatic. +That is to say, when a user-space application writes +.RB ( setxattr (2)) +a +.I security.capability +attribute in the version 2 format, +the kernel will automatically create a version 3 attribute +if the attribute is created in the circumstances described above. +Correspondingly, when a version 3 +.I security.capability +attribute is retrieved +.RB ( getxattr (2)) +by a process that resides inside a user namespace that was created by the +root user ID (or a descendant of that user namespace), +the returned attribute is (automatically) +simplified to appear as a version 2 attribute +(i.e., the returned value is the size of a version 2 attribute and does +not include the root user ID). +These automatic translations mean that no changes are required to +user-space tools (e.g., +.BR setcap (1) +and +.BR getcap (1)) +in order for those tools to be used to create and retrieve version 3 +.I security.capability +attributes. +.P +Note that a file can have either a version 2 or a version 3 +.I security.capability +extended attribute associated with it, but not both: +creation or modification of the +.I security.capability +extended attribute will automatically modify the version +according to the circumstances in which the extended attribute is +created or modified. +.\" +.SS Transformation of capabilities during execve() +During an +.BR execve (2), +the kernel calculates the new capabilities of +the process using the following algorithm: +.P +.in +4n +.EX +P'(ambient) = (file is privileged) ? 0 : P(ambient) +\& +P'(permitted) = (P(inheritable) & F(inheritable)) | + (F(permitted) & P(bounding)) | P'(ambient) +\& +P'(effective) = F(effective) ? P'(permitted) : P'(ambient) +\& +P'(inheritable) = P(inheritable) [i.e., unchanged] +\& +P'(bounding) = P(bounding) [i.e., unchanged] +.EE +.in +.P +where: +.RS 4 +.TP +P() +denotes the value of a thread capability set before the +.BR execve (2) +.TP +P'() +denotes the value of a thread capability set after the +.BR execve (2) +.TP +F() +denotes a file capability set +.RE +.P +Note the following details relating to the above capability +transformation rules: +.IP \[bu] 3 +The ambient capability set is present only since Linux 4.3. +When determining the transformation of the ambient set during +.BR execve (2), +a privileged file is one that has capabilities or +has the set-user-ID or set-group-ID bit set. +.IP \[bu] +Prior to Linux 2.6.25, +the bounding set was a system-wide attribute shared by all threads. +That system-wide value was employed to calculate the new permitted set during +.BR execve (2) +in the same manner as shown above for +.IR P(bounding) . +.P +.IR Note : +during the capability transitions described above, +file capabilities may be ignored (treated as empty) for the same reasons +that the set-user-ID and set-group-ID bits are ignored; see +.BR execve (2). +File capabilities are similarly ignored if the kernel was booted with the +.I no_file_caps +option. +.P +.IR Note : +according to the rules above, +if a process with nonzero user IDs performs an +.BR execve (2) +then any capabilities that are present in +its permitted and effective sets will be cleared. +For the treatment of capabilities when a process with a +user ID of zero performs an +.BR execve (2), +see +.I Capabilities and execution of programs by root +below. +.\" +.SS Safety checking for capability-dumb binaries +A capability-dumb binary is an application that has been +marked to have file capabilities, but has not been converted to use the +.BR libcap (3) +API to manipulate its capabilities. +(In other words, this is a traditional set-user-ID-root program +that has been switched to use file capabilities, +but whose code has not been modified to understand capabilities.) +For such applications, +the effective capability bit is set on the file, +so that the file permitted capabilities are automatically +enabled in the process effective set when executing the file. +The kernel recognizes a file which has the effective capability bit set +as capability-dumb for the purpose of the check described here. +.P +When executing a capability-dumb binary, +the kernel checks if the process obtained all permitted capabilities +that were specified in the file permitted set, +after the capability transformations described above have been performed. +(The typical reason why this might +.I not +occur is that the capability bounding set masked out some +of the capabilities in the file permitted set.) +If the process did not obtain the full set of +file permitted capabilities, then +.BR execve (2) +fails with the error +.BR EPERM . +This prevents possible security risks that could arise when +a capability-dumb application is executed with less privilege than it needs. +Note that, by definition, +the application could not itself recognize this problem, +since it does not employ the +.BR libcap (3) +API. +.\" +.SS Capabilities and execution of programs by root +.\" See cap_bprm_set_creds(), bprm_caps_from_vfs_cap() and +.\" handle_privileged_root() in security/commoncap.c (Linux 5.0 source) +In order to mirror traditional UNIX semantics, +the kernel performs special treatment of file capabilities when +a process with UID 0 (root) executes a program and +when a set-user-ID-root program is executed. +.P +After having performed any changes to the process effective ID that +were triggered by the set-user-ID mode bit of the binary\[em]e.g., +switching the effective user ID to 0 (root) because +a set-user-ID-root program was executed\[em]the +kernel calculates the file capability sets as follows: +.IP (1) 5 +If the real or effective user ID of the process is 0 (root), +then the file inheritable and permitted sets are ignored; +instead they are notionally considered to be all ones +(i.e., all capabilities enabled). +(There is one exception to this behavior, described in +.I Set-user-ID-root programs that have file capabilities +below.) +.IP (2) +If the effective user ID of the process is 0 (root) or +the file effective bit is in fact enabled, +then the file effective bit is notionally defined to be one (enabled). +.P +These notional values for the file's capability sets are then used +as described above to calculate the transformation of the process's +capabilities during +.BR execve (2). +.P +Thus, when a process with nonzero UIDs +.BR execve (2)s +a set-user-ID-root program that does not have capabilities attached, +or when a process whose real and effective UIDs are zero +.BR execve (2)s +a program, the calculation of the process's new +permitted capabilities simplifies to: +.P +.in +4n +.EX +P'(permitted) = P(inheritable) | P(bounding) +\& +P'(effective) = P'(permitted) +.EE +.in +.P +Consequently, the process gains all capabilities in its permitted and +effective capability sets, +except those masked out by the capability bounding set. +(In the calculation of P'(permitted), +the P'(ambient) term can be simplified away because it is by +definition a proper subset of P(inheritable).) +.P +The special treatments of user ID 0 (root) described in this subsection +can be disabled using the securebits mechanism described below. +.\" +.\" +.SS Set-user-ID-root programs that have file capabilities +There is one exception to the behavior described in +.I Capabilities and execution of programs by root +above. +If (a) the binary that is being executed has capabilities attached and +(b) the real user ID of the process is +.I not +0 (root) and +(c) the effective user ID of the process +.I is +0 (root), then the file capability bits are honored +(i.e., they are not notionally considered to be all ones). +The usual way in which this situation can arise is when executing +a set-UID-root program that also has file capabilities. +When such a program is executed, +the process gains just the capabilities granted by the program +(i.e., not all capabilities, +as would occur when executing a set-user-ID-root program +that does not have any associated file capabilities). +.P +Note that one can assign empty capability sets to a program file, +and thus it is possible to create a set-user-ID-root program that +changes the effective and saved set-user-ID of the process +that executes the program to 0, +but confers no capabilities to that process. +.\" +.SS Capability bounding set +The capability bounding set is a security mechanism that can be used +to limit the capabilities that can be gained during an +.BR execve (2). +The bounding set is used in the following ways: +.IP \[bu] 3 +During an +.BR execve (2), +the capability bounding set is ANDed with the file permitted +capability set, and the result of this operation is assigned to the +thread's permitted capability set. +The capability bounding set thus places a limit on the permitted +capabilities that may be granted by an executable file. +.IP \[bu] +(Since Linux 2.6.25) +The capability bounding set acts as a limiting superset for +the capabilities that a thread can add to its inheritable set using +.BR capset (2). +This means that if a capability is not in the bounding set, +then a thread can't add this capability to its +inheritable set, even if it was in its permitted capabilities, +and thereby cannot have this capability preserved in its +permitted set when it +.BR execve (2)s +a file that has the capability in its inheritable set. +.P +Note that the bounding set masks the file permitted capabilities, +but not the inheritable capabilities. +If a thread maintains a capability in its inheritable set +that is not in its bounding set, +then it can still gain that capability in its permitted set +by executing a file that has the capability in its inheritable set. +.P +Depending on the kernel version, the capability bounding set is either +a system-wide attribute, or a per-process attribute. +.P +.B "Capability bounding set from Linux 2.6.25 onward" +.P +From Linux 2.6.25, the +.I "capability bounding set" +is a per-thread attribute. +(The system-wide capability bounding set described below no longer exists.) +.P +The bounding set is inherited at +.BR fork (2) +from the thread's parent, and is preserved across an +.BR execve (2). +.P +A thread may remove capabilities from its capability bounding set using the +.BR prctl (2) +.B PR_CAPBSET_DROP +operation, provided it has the +.B CAP_SETPCAP +capability. +Once a capability has been dropped from the bounding set, +it cannot be restored to that set. +A thread can determine if a capability is in its bounding set using the +.BR prctl (2) +.B PR_CAPBSET_READ +operation. +.P +Removing capabilities from the bounding set is supported only if file +capabilities are compiled into the kernel. +Before Linux 2.6.33, +file capabilities were an optional feature configurable via the +.B CONFIG_SECURITY_FILE_CAPABILITIES +option. +Since Linux 2.6.33, +.\" commit b3a222e52e4d4be77cc4520a57af1a4a0d8222d1 +the configuration option has been removed +and file capabilities are always part of the kernel. +When file capabilities are compiled into the kernel, the +.B init +process (the ancestor of all processes) begins with a full bounding set. +If file capabilities are not compiled into the kernel, then +.B init +begins with a full bounding set minus +.BR CAP_SETPCAP , +because this capability has a different meaning when there are +no file capabilities. +.P +Removing a capability from the bounding set does not remove it +from the thread's inheritable set. +However it does prevent the capability from being added +back into the thread's inheritable set in the future. +.P +.B "Capability bounding set prior to Linux 2.6.25" +.P +Before Linux 2.6.25, the capability bounding set is a system-wide +attribute that affects all threads on the system. +The bounding set is accessible via the file +.IR /proc/sys/kernel/cap\-bound . +(Confusingly, this bit mask parameter is expressed as a +signed decimal number in +.IR /proc/sys/kernel/cap\-bound .) +.P +Only the +.B init +process may set capabilities in the capability bounding set; +other than that, the superuser (more precisely: a process with the +.B CAP_SYS_MODULE +capability) may only clear capabilities from this set. +.P +On a standard system the capability bounding set always masks out the +.B CAP_SETPCAP +capability. +To remove this restriction (dangerous!), modify the definition of +.B CAP_INIT_EFF_SET +in +.I include/linux/capability.h +and rebuild the kernel. +.P +The system-wide capability bounding set feature was added +to Linux 2.2.11. +.\" +.\" +.\" +.SS Effect of user ID changes on capabilities +To preserve the traditional semantics for transitions between +0 and nonzero user IDs, +the kernel makes the following changes to a thread's capability +sets on changes to the thread's real, effective, saved set, +and filesystem user IDs (using +.BR setuid (2), +.BR setresuid (2), +or similar): +.IP \[bu] 3 +If one or more of the real, effective, or saved set user IDs +was previously 0, and as a result of the UID changes all of these IDs +have a nonzero value, +then all capabilities are cleared from the permitted, effective, and ambient +capability sets. +.IP \[bu] +If the effective user ID is changed from 0 to nonzero, +then all capabilities are cleared from the effective set. +.IP \[bu] +If the effective user ID is changed from nonzero to 0, +then the permitted set is copied to the effective set. +.IP \[bu] +If the filesystem user ID is changed from 0 to nonzero (see +.BR setfsuid (2)), +then the following capabilities are cleared from the effective set: +.BR CAP_CHOWN , +.BR CAP_DAC_OVERRIDE , +.BR CAP_DAC_READ_SEARCH , +.BR CAP_FOWNER , +.BR CAP_FSETID , +.B CAP_LINUX_IMMUTABLE +(since Linux 2.6.30), +.BR CAP_MAC_OVERRIDE , +and +.B CAP_MKNOD +(since Linux 2.6.30). +If the filesystem UID is changed from nonzero to 0, +then any of these capabilities that are enabled in the permitted set +are enabled in the effective set. +.P +If a thread that has a 0 value for one or more of its user IDs wants +to prevent its permitted capability set being cleared when it resets +all of its user IDs to nonzero values, it can do so using the +.B SECBIT_KEEP_CAPS +securebits flag described below. +.\" +.SS Programmatically adjusting capability sets +A thread can retrieve and change its permitted, effective, and inheritable +capability sets using the +.BR capget (2) +and +.BR capset (2) +system calls. +However, the use of +.BR cap_get_proc (3) +and +.BR cap_set_proc (3), +both provided in the +.I libcap +package, +is preferred for this purpose. +The following rules govern changes to the thread capability sets: +.IP \[bu] 3 +If the caller does not have the +.B CAP_SETPCAP +capability, +the new inheritable set must be a subset of the combination +of the existing inheritable and permitted sets. +.IP \[bu] +(Since Linux 2.6.25) +The new inheritable set must be a subset of the combination of the +existing inheritable set and the capability bounding set. +.IP \[bu] +The new permitted set must be a subset of the existing permitted set +(i.e., it is not possible to acquire permitted capabilities +that the thread does not currently have). +.IP \[bu] +The new effective set must be a subset of the new permitted set. +.SS The securebits flags: establishing a capabilities-only environment +.\" For some background: +.\" see http://lwn.net/Articles/280279/ and +.\" http://article.gmane.org/gmane.linux.kernel.lsm/5476/ +Starting with Linux 2.6.26, +and with a kernel in which file capabilities are enabled, +Linux implements a set of per-thread +.I securebits +flags that can be used to disable special handling of capabilities for UID 0 +.RI ( root ). +These flags are as follows: +.TP +.B SECBIT_KEEP_CAPS +Setting this flag allows a thread that has one or more 0 UIDs to retain +capabilities in its permitted set +when it switches all of its UIDs to nonzero values. +If this flag is not set, +then such a UID switch causes the thread to lose all permitted capabilities. +This flag is always cleared on an +.BR execve (2). +.IP +Note that even with the +.B SECBIT_KEEP_CAPS +flag set, the effective capabilities of a thread are cleared when it +switches its effective UID to a nonzero value. +However, +if the thread has set this flag and its effective UID is already nonzero, +and the thread subsequently switches all other UIDs to nonzero values, +then the effective capabilities will not be cleared. +.IP +The setting of the +.B SECBIT_KEEP_CAPS +flag is ignored if the +.B SECBIT_NO_SETUID_FIXUP +flag is set. +(The latter flag provides a superset of the effect of the former flag.) +.IP +This flag provides the same functionality as the older +.BR prctl (2) +.B PR_SET_KEEPCAPS +operation. +.TP +.B SECBIT_NO_SETUID_FIXUP +Setting this flag stops the kernel from adjusting the process's +permitted, effective, and ambient capability sets when +the thread's effective and filesystem UIDs are switched between +zero and nonzero values. +See +.I Effect of user ID changes on capabilities +above. +.TP +.B SECBIT_NOROOT +If this bit is set, then the kernel does not grant capabilities +when a set-user-ID-root program is executed, or when a process with +an effective or real UID of 0 calls +.BR execve (2). +(See +.I Capabilities and execution of programs by root +above.) +.TP +.B SECBIT_NO_CAP_AMBIENT_RAISE +Setting this flag disallows raising ambient capabilities via the +.BR prctl (2) +.B PR_CAP_AMBIENT_RAISE +operation. +.P +Each of the above "base" flags has a companion "locked" flag. +Setting any of the "locked" flags is irreversible, +and has the effect of preventing further changes to the +corresponding "base" flag. +The locked flags are: +.BR SECBIT_KEEP_CAPS_LOCKED , +.BR SECBIT_NO_SETUID_FIXUP_LOCKED , +.BR SECBIT_NOROOT_LOCKED , +and +.BR SECBIT_NO_CAP_AMBIENT_RAISE_LOCKED . +.P +The +.I securebits +flags can be modified and retrieved using the +.BR prctl (2) +.B PR_SET_SECUREBITS +and +.B PR_GET_SECUREBITS +operations. +The +.B CAP_SETPCAP +capability is required to modify the flags. +Note that the +.B SECBIT_* +constants are available only after including the +.I +header file. +.P +The +.I securebits +flags are inherited by child processes. +During an +.BR execve (2), +all of the flags are preserved, except +.B SECBIT_KEEP_CAPS +which is always cleared. +.P +An application can use the following call to lock itself, +and all of its descendants, +into an environment where the only way of gaining capabilities +is by executing a program with associated file capabilities: +.P +.in +4n +.EX +prctl(PR_SET_SECUREBITS, + /* SECBIT_KEEP_CAPS off */ + SECBIT_KEEP_CAPS_LOCKED | + SECBIT_NO_SETUID_FIXUP | + SECBIT_NO_SETUID_FIXUP_LOCKED | + SECBIT_NOROOT | + SECBIT_NOROOT_LOCKED); + /* Setting/locking SECBIT_NO_CAP_AMBIENT_RAISE + is not required */ +.EE +.in +.\" +.\" +.SS Per-user-namespace \[dq]set-user-ID-root\[dq] programs +A set-user-ID program whose UID matches the UID that +created a user namespace will confer capabilities +in the process's permitted and effective sets +when executed by any process inside that namespace +or any descendant user namespace. +.P +The rules about the transformation of the process's capabilities during the +.BR execve (2) +are exactly as described in +.I Transformation of capabilities during execve() +and +.I Capabilities and execution of programs by root +above, +with the difference that, in the latter subsection, "root" +is the UID of the creator of the user namespace. +.\" +.\" +.SS Namespaced file capabilities +.\" commit 8db6c34f1dbc8e06aa016a9b829b06902c3e1340 +Traditional (i.e., version 2) file capabilities associate +only a set of capability masks with a binary executable file. +When a process executes a binary with such capabilities, +it gains the associated capabilities (within its user namespace) +as per the rules described in +.I Transformation of capabilities during execve() +above. +.P +Because version 2 file capabilities confer capabilities to +the executing process regardless of which user namespace it resides in, +only privileged processes are permitted to associate capabilities with a file. +Here, "privileged" means a process that has the +.B CAP_SETFCAP +capability in the user namespace where the filesystem was mounted +(normally the initial user namespace). +This limitation renders file capabilities useless for certain use cases. +For example, in user-namespaced containers, +it can be desirable to be able to create a binary that +confers capabilities only to processes executed inside that container, +but not to processes that are executed outside the container. +.P +Linux 4.14 added so-called namespaced file capabilities +to support such use cases. +Namespaced file capabilities are recorded as version 3 (i.e., +.BR VFS_CAP_REVISION_3 ) +.I security.capability +extended attributes. +Such an attribute is automatically created in the circumstances described +in +.I File capability extended attribute versioning +above. +When a version 3 +.I security.capability +extended attribute is created, +the kernel records not just the capability masks in the extended attribute, +but also the namespace root user ID. +.P +As with a binary that has +.B VFS_CAP_REVISION_2 +file capabilities, a binary with +.B VFS_CAP_REVISION_3 +file capabilities confers capabilities to a process during +.BR execve (). +However, capabilities are conferred only if the binary is executed by +a process that resides in a user namespace whose +UID 0 maps to the root user ID that is saved in the extended attribute, +or when executed by a process that resides in a descendant of such a namespace. +.\" +.\" +.SS Interaction with user namespaces +For further information on the interaction of +capabilities and user namespaces, see +.BR user_namespaces (7). +.SH STANDARDS +No standards govern capabilities, but the Linux capability implementation +is based on the withdrawn +.UR https://archive.org\:/details\:/posix_1003.1e\-990310 +POSIX.1e draft standard +.UE . +.SH NOTES +When attempting to +.BR strace (1) +binaries that have capabilities (or set-user-ID-root binaries), +you may find the +.I \-u +option useful. +Something like: +.P +.in +4n +.EX +$ \fBsudo strace \-o trace.log \-u ceci ./myprivprog\fP +.EE +.in +.P +From Linux 2.5.27 to Linux 2.6.26, +.\" commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27 removed +.\" CONFIG_SECURITY_CAPABILITIES +capabilities were an optional kernel component, +and could be enabled/disabled via the +.B CONFIG_SECURITY_CAPABILITIES +kernel configuration option. +.P +The +.IR /proc/ pid /task/TID/status +file can be used to view the capability sets of a thread. +The +.IR /proc/ pid /status +file shows the capability sets of a process's main thread. +Before Linux 3.8, nonexistent capabilities were shown as being +enabled (1) in these sets. +Since Linux 3.8, +.\" 7b9a7ec565505699f503b4fcf61500dceb36e744 +all nonexistent capabilities (above +.BR CAP_LAST_CAP ) +are shown as disabled (0). +.P +The +.I libcap +package provides a suite of routines for setting and +getting capabilities that is more comfortable and less likely +to change than the interface provided by +.BR capset (2) +and +.BR capget (2). +This package also provides the +.BR setcap (8) +and +.BR getcap (8) +programs. +It can be found at +.br +.UR https://git.kernel.org\:/pub\:/scm\:/libs\:/libcap\:/libcap.git\:/refs/ +.UE . +.P +Before Linux 2.6.24, and from Linux 2.6.24 to Linux 2.6.32 if +file capabilities are not enabled, a thread with the +.B CAP_SETPCAP +capability can manipulate the capabilities of threads other than itself. +However, this is only theoretically possible, +since no thread ever has +.B CAP_SETPCAP +in either of these cases: +.IP \[bu] 3 +In the pre-2.6.25 implementation the system-wide capability bounding set, +.IR /proc/sys/kernel/cap\-bound , +always masks out the +.B CAP_SETPCAP +capability, and this can not be changed +without modifying the kernel source and rebuilding the kernel. +.IP \[bu] +If file capabilities are disabled (i.e., the kernel +.B CONFIG_SECURITY_FILE_CAPABILITIES +option is disabled), then +.B init +starts out with the +.B CAP_SETPCAP +capability removed from its per-process bounding +set, and that bounding set is inherited by all other processes +created on the system. +.SH SEE ALSO +.BR capsh (1), +.BR setpriv (1), +.BR prctl (2), +.BR setfsuid (2), +.BR cap_clear (3), +.BR cap_copy_ext (3), +.BR cap_from_text (3), +.BR cap_get_file (3), +.BR cap_get_proc (3), +.BR cap_init (3), +.BR capgetp (3), +.BR capsetp (3), +.BR libcap (3), +.BR proc (5), +.BR credentials (7), +.BR pthreads (7), +.BR user_namespaces (7), +.BR captest (8), \" from libcap-ng +.BR filecap (8), \" from libcap-ng +.BR getcap (8), +.BR getpcaps (8), +.BR netcap (8), \" from libcap-ng +.BR pscap (8), \" from libcap-ng +.BR setcap (8) +.P +.I include/linux/capability.h +in the Linux kernel source tree diff --git a/man/man7/cgroup_namespaces.7 b/man/man7/cgroup_namespaces.7 new file mode 100644 index 0000000..392aa08 --- /dev/null +++ b/man/man7/cgroup_namespaces.7 @@ -0,0 +1,248 @@ +.\" Copyright (c) 2016 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH cgroup_namespaces 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cgroup_namespaces \- overview of Linux cgroup namespaces +.SH DESCRIPTION +For an overview of namespaces, see +.BR namespaces (7). +.P +Cgroup namespaces virtualize the view of a process's cgroups (see +.BR cgroups (7)) +as seen via +.IR /proc/ pid /cgroup +and +.IR /proc/ pid /mountinfo . +.P +Each cgroup namespace has its own set of cgroup root directories. +These root directories are the base points for the relative +locations displayed in the corresponding records in the +.IR /proc/ pid /cgroup +file. +When a process creates a new cgroup namespace using +.BR clone (2) +or +.BR unshare (2) +with the +.B CLONE_NEWCGROUP +flag, its current +cgroups directories become the cgroup root directories +of the new namespace. +(This applies both for the cgroups version 1 hierarchies +and the cgroups version 2 unified hierarchy.) +.P +When reading the cgroup memberships of a "target" process from +.IR /proc/ pid /cgroup , +the pathname shown in the third field of each record will be +relative to the reading process's root directory +for the corresponding cgroup hierarchy. +If the cgroup directory of the target process lies outside +the root directory of the reading process's cgroup namespace, +then the pathname will show +.I ../ +entries for each ancestor level in the cgroup hierarchy. +.P +The following shell session demonstrates the effect of creating +a new cgroup namespace. +.P +First, (as superuser) in a shell in the initial cgroup namespace, +we create a child cgroup in the +.I freezer +hierarchy, and place a process in that cgroup that we will +use as part of the demonstration below: +.P +.in +4n +.EX +# \fBmkdir \-p /sys/fs/cgroup/freezer/sub2\fP +# \fBsleep 10000 &\fP # Create a process that lives for a while +[1] 20124 +# \fBecho 20124 > /sys/fs/cgroup/freezer/sub2/cgroup.procs\fP +.EE +.in +.P +We then create another child cgroup in the +.I freezer +hierarchy and put the shell into that cgroup: +.P +.in +4n +.EX +# \fBmkdir \-p /sys/fs/cgroup/freezer/sub\fP +# \fBecho $$\fP # Show PID of this shell +30655 +# \fBecho 30655 > /sys/fs/cgroup/freezer/sub/cgroup.procs\fP +# \fBcat /proc/self/cgroup | grep freezer\fP +7:freezer:/sub +.EE +.in +.P +Next, we use +.BR unshare (1) +to create a process running a new shell in new cgroup and mount namespaces: +.P +.in +4n +.EX +# \fBPS1="sh2# " unshare \-Cm bash\fP +.EE +.in +.P +From the new shell started by +.BR unshare (1), +we then inspect the +.IR /proc/ pid /cgroup +files of, respectively, the new shell, +a process that is in the initial cgroup namespace +.RI ( init , +with PID 1), and the process in the sibling cgroup +.RI ( sub2 ): +.P +.in +4n +.EX +sh2# \fBcat /proc/self/cgroup | grep freezer\fP +7:freezer:/ +sh2# \fBcat /proc/1/cgroup | grep freezer\fP +7:freezer:/.. +sh2# \fBcat /proc/20124/cgroup | grep freezer\fP +7:freezer:/../sub2 +.EE +.in +.P +From the output of the first command, +we see that the freezer cgroup membership of the new shell +(which is in the same cgroup as the initial shell) +is shown defined relative to the freezer cgroup root directory +that was established when the new cgroup namespace was created. +(In absolute terms, +the new shell is in the +.I /sub +freezer cgroup, +and the root directory of the freezer cgroup hierarchy +in the new cgroup namespace is also +.IR /sub . +Thus, the new shell's cgroup membership is displayed as \[aq]/\[aq].) +.P +However, when we look in +.I /proc/self/mountinfo +we see the following anomaly: +.P +.in +4n +.EX +sh2# \fBcat /proc/self/mountinfo | grep freezer\fP +155 145 0:32 /.. /sys/fs/cgroup/freezer ... +.EE +.in +.P +The fourth field of this line +.RI ( /.. ) +should show the +directory in the cgroup filesystem which forms the root of this mount. +Since by the definition of cgroup namespaces, the process's current +freezer cgroup directory became its root freezer cgroup directory, +we should see \[aq]/\[aq] in this field. +The problem here is that we are seeing a mount entry for the cgroup +filesystem corresponding to the initial cgroup namespace +(whose cgroup filesystem is indeed rooted at the parent directory of +.IR sub ). +To fix this problem, we must remount the freezer cgroup filesystem +from the new shell (i.e., perform the mount from a process that is in the +new cgroup namespace), after which we see the expected results: +.P +.in +4n +.EX +sh2# \fBmount \-\-make\-rslave /\fP # Don\[aq]t propagate mount events + # to other namespaces +sh2# \fBumount /sys/fs/cgroup/freezer\fP +sh2# \fBmount \-t cgroup \-o freezer freezer /sys/fs/cgroup/freezer\fP +sh2# \fBcat /proc/self/mountinfo | grep freezer\fP +155 145 0:32 / /sys/fs/cgroup/freezer rw,relatime ... +.EE +.in +.\" +.SH STANDARDS +Linux. +.SH NOTES +Use of cgroup namespaces requires a kernel that is configured with the +.B CONFIG_CGROUPS +option. +.P +The virtualization provided by cgroup namespaces serves a number of purposes: +.IP \[bu] 3 +It prevents information leaks whereby cgroup directory paths outside of +a container would otherwise be visible to processes in the container. +Such leakages could, for example, +reveal information about the container framework +to containerized applications. +.IP \[bu] +It eases tasks such as container migration. +The virtualization provided by cgroup namespaces +allows containers to be isolated from knowledge of +the pathnames of ancestor cgroups. +Without such isolation, the full cgroup pathnames (displayed in +.IR /proc/self/cgroups ) +would need to be replicated on the target system when migrating a container; +those pathnames would also need to be unique, +so that they don't conflict with other pathnames on the target system. +.IP \[bu] +It allows better confinement of containerized processes, +because it is possible to mount the container's cgroup filesystems such that +the container processes can't gain access to ancestor cgroup directories. +Consider, for example, the following scenario: +.RS +.IP \[bu] 3 +We have a cgroup directory, +.IR /cg/1 , +that is owned by user ID 9000. +.IP \[bu] +We have a process, +.IR X , +also owned by user ID 9000, +that is namespaced under the cgroup +.I /cg/1/2 +(i.e., +.I X +was placed in a new cgroup namespace via +.BR clone (2) +or +.BR unshare (2) +with the +.B CLONE_NEWCGROUP +flag). +.RE +.IP +In the absence of cgroup namespacing, because the cgroup directory +.I /cg/1 +is owned (and writable) by UID 9000 and process +.I X +is also owned by user ID 9000, process +.I X +would be able to modify the contents of cgroups files +(i.e., change cgroup settings) not only in +.I /cg/1/2 +but also in the ancestor cgroup directory +.IR /cg/1 . +Namespacing process +.I X +under the cgroup directory +.IR /cg/1/2 , +in combination with suitable mount operations +for the cgroup filesystem (as shown above), +prevents it modifying files in +.IR /cg/1 , +since it cannot even see the contents of that directory +(or of further removed cgroup ancestor directories). +Combined with correct enforcement of hierarchical limits, +this prevents process +.I X +from escaping the limits imposed by ancestor cgroups. +.SH SEE ALSO +.BR unshare (1), +.BR clone (2), +.BR setns (2), +.BR unshare (2), +.BR proc (5), +.BR cgroups (7), +.BR credentials (7), +.BR namespaces (7), +.BR user_namespaces (7) diff --git a/man/man7/cgroups.7 b/man/man7/cgroups.7 new file mode 100644 index 0000000..964f13c --- /dev/null +++ b/man/man7/cgroups.7 @@ -0,0 +1,1914 @@ +.\" Copyright (C) 2015 Serge Hallyn +.\" and Copyright (C) 2016, 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH cgroups 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cgroups \- Linux control groups +.SH DESCRIPTION +Control groups, usually referred to as cgroups, +are a Linux kernel feature which allow processes to +be organized into hierarchical groups whose usage of +various types of resources can then be limited and monitored. +The kernel's cgroup interface is provided through +a pseudo-filesystem called cgroupfs. +Grouping is implemented in the core cgroup kernel code, +while resource tracking and limits are implemented in +a set of per-resource-type subsystems (memory, CPU, and so on). +.\" +.SS Terminology +A +.I cgroup +is a collection of processes that are bound to a set of +limits or parameters defined via the cgroup filesystem. +.P +A +.I subsystem +is a kernel component that modifies the behavior of +the processes in a cgroup. +Various subsystems have been implemented, making it possible to do things +such as limiting the amount of CPU time and memory available to a cgroup, +accounting for the CPU time used by a cgroup, +and freezing and resuming execution of the processes in a cgroup. +Subsystems are sometimes also known as +.I resource controllers +(or simply, controllers). +.P +The cgroups for a controller are arranged in a +.IR hierarchy . +This hierarchy is defined by creating, removing, and +renaming subdirectories within the cgroup filesystem. +At each level of the hierarchy, attributes (e.g., limits) can be defined. +The limits, control, and accounting provided by cgroups generally have +effect throughout the subhierarchy underneath the cgroup where the +attributes are defined. +Thus, for example, the limits placed on +a cgroup at a higher level in the hierarchy cannot be exceeded +by descendant cgroups. +.\" +.SS Cgroups version 1 and version 2 +The initial release of the cgroups implementation was in Linux 2.6.24. +Over time, various cgroup controllers have been added +to allow the management of various types of resources. +However, the development of these controllers was largely uncoordinated, +with the result that many inconsistencies arose between controllers +and management of the cgroup hierarchies became rather complex. +A longer description of these problems can be found in the kernel +source file +.I Documentation/admin\-guide/cgroup\-v2.rst +(or +.I Documentation/cgroup\-v2.txt +in Linux 4.17 and earlier). +.P +Because of the problems with the initial cgroups implementation +(cgroups version 1), +starting in Linux 3.10, work began on a new, +orthogonal implementation to remedy these problems. +Initially marked experimental, and hidden behind the +.I "\-o\ __DEVEL__sane_behavior" +mount option, the new version (cgroups version 2) +was eventually made official with the release of Linux 4.5. +Differences between the two versions are described in the text below. +The file +.IR cgroup.sane_behavior , +present in cgroups v1, is a relic of this mount option. +The file always reports "0" and is only retained for backward compatibility. +.P +Although cgroups v2 is intended as a replacement for cgroups v1, +the older system continues to exist +(and for compatibility reasons is unlikely to be removed). +Currently, cgroups v2 implements only a subset of the controllers +available in cgroups v1. +The two systems are implemented so that both v1 controllers and +v2 controllers can be mounted on the same system. +Thus, for example, it is possible to use those controllers +that are supported under version 2, +while also using version 1 controllers +where version 2 does not yet support those controllers. +The only restriction here is that a controller can't be simultaneously +employed in both a cgroups v1 hierarchy and in the cgroups v2 hierarchy. +.\" +.SH CGROUPS VERSION 1 +Under cgroups v1, each controller may be mounted against a separate +cgroup filesystem that provides its own hierarchical organization of the +processes on the system. +It is also possible to comount multiple (or even all) cgroups v1 controllers +against the same cgroup filesystem, meaning that the comounted controllers +manage the same hierarchical organization of processes. +.P +For each mounted hierarchy, +the directory tree mirrors the control group hierarchy. +Each control group is represented by a directory, with each of its child +control cgroups represented as a child directory. +For instance, +.I /user/joe/1.session +represents control group +.IR 1.session , +which is a child of cgroup +.IR joe , +which is a child of +.IR /user . +Under each cgroup directory is a set of files which can be read or +written to, reflecting resource limits and a few general cgroup +properties. +.\" +.SS Tasks (threads) versus processes +In cgroups v1, a distinction is drawn between +.I processes +and +.IR tasks . +In this view, a process can consist of multiple tasks +(more commonly called threads, from a user-space perspective, +and called such in the remainder of this man page). +In cgroups v1, it is possible to independently manipulate +the cgroup memberships of the threads in a process. +.P +The cgroups v1 ability to split threads across different cgroups +caused problems in some cases. +For example, it made no sense for the +.I memory +controller, +since all of the threads of a process share a single address space. +Because of these problems, +the ability to independently manipulate the cgroup memberships +of the threads in a process was removed in the initial cgroups v2 +implementation, and subsequently restored in a more limited form +(see the discussion of "thread mode" below). +.\" +.SS Mounting v1 controllers +The use of cgroups requires a kernel built with the +.B CONFIG_CGROUP +option. +In addition, each of the v1 controllers has an associated +configuration option that must be set in order to employ that controller. +.P +In order to use a v1 controller, +it must be mounted against a cgroup filesystem. +The usual place for such mounts is under a +.BR tmpfs (5) +filesystem mounted at +.IR /sys/fs/cgroup . +Thus, one might mount the +.I cpu +controller as follows: +.P +.in +4n +.EX +mount \-t cgroup \-o cpu none /sys/fs/cgroup/cpu +.EE +.in +.P +It is possible to comount multiple controllers against the same hierarchy. +For example, here the +.I cpu +and +.I cpuacct +controllers are comounted against a single hierarchy: +.P +.in +4n +.EX +mount \-t cgroup \-o cpu,cpuacct none /sys/fs/cgroup/cpu,cpuacct +.EE +.in +.P +Comounting controllers has the effect that a process is in the same cgroup for +all of the comounted controllers. +Separately mounting controllers allows a process to +be in cgroup +.I /foo1 +for one controller while being in +.I /foo2/foo3 +for another. +.P +It is possible to comount all v1 controllers against the same hierarchy: +.P +.in +4n +.EX +mount \-t cgroup \-o all cgroup /sys/fs/cgroup +.EE +.in +.P +(One can achieve the same result by omitting +.IR "\-o all" , +since it is the default if no controllers are explicitly specified.) +.P +It is not possible to mount the same controller +against multiple cgroup hierarchies. +For example, it is not possible to mount both the +.I cpu +and +.I cpuacct +controllers against one hierarchy, and to mount the +.I cpu +controller alone against another hierarchy. +It is possible to create multiple mount with exactly +the same set of comounted controllers. +However, in this case all that results is multiple mount points +providing a view of the same hierarchy. +.P +Note that on many systems, the v1 controllers are automatically mounted under +.IR /sys/fs/cgroup ; +in particular, +.BR systemd (1) +automatically creates such mounts. +.\" +.SS Unmounting v1 controllers +A mounted cgroup filesystem can be unmounted using the +.BR umount (8) +command, as in the following example: +.P +.in +4n +.EX +umount /sys/fs/cgroup/pids +.EE +.in +.P +.IR "But note well" : +a cgroup filesystem is unmounted only if it is not busy, +that is, it has no child cgroups. +If this is not the case, then the only effect of the +.BR umount (8) +is to make the mount invisible. +Thus, to ensure that the mount is really removed, +one must first remove all child cgroups, +which in turn can be done only after all member processes +have been moved from those cgroups to the root cgroup. +.\" +.SS Cgroups version 1 controllers +Each of the cgroups version 1 controllers is governed +by a kernel configuration option (listed below). +Additionally, the availability of the cgroups feature is governed by the +.B CONFIG_CGROUPS +kernel configuration option. +.TP +.IR cpu " (since Linux 2.6.24; " \fBCONFIG_CGROUP_SCHED\fP ) +Cgroups can be guaranteed a minimum number of "CPU shares" +when a system is busy. +This does not limit a cgroup's CPU usage if the CPUs are not busy. +For further information, see +.I Documentation/scheduler/sched\-design\-CFS.rst +(or +.I Documentation/scheduler/sched\-design\-CFS.txt +in Linux 5.2 and earlier). +.IP +In Linux 3.2, +this controller was extended to provide CPU "bandwidth" control. +If the kernel is configured with +.BR CONFIG_CFS_BANDWIDTH , +then within each scheduling period +(defined via a file in the cgroup directory), it is possible to define +an upper limit on the CPU time allocated to the processes in a cgroup. +This upper limit applies even if there is no other competition for the CPU. +Further information can be found in the kernel source file +.I Documentation/scheduler/sched\-bwc.rst +(or +.I Documentation/scheduler/sched\-bwc.txt +in Linux 5.2 and earlier). +.TP +.IR cpuacct " (since Linux 2.6.24; " \fBCONFIG_CGROUP_CPUACCT\fP ) +This provides accounting for CPU usage by groups of processes. +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/cpuacct.rst +(or +.I Documentation/cgroup\-v1/cpuacct.txt +in Linux 5.2 and earlier). +.TP +.IR cpuset " (since Linux 2.6.24; " \fBCONFIG_CPUSETS\fP ) +This cgroup can be used to bind the processes in a cgroup to +a specified set of CPUs and NUMA nodes. +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/cpusets.rst +(or +.I Documentation/cgroup\-v1/cpusets.txt +in Linux 5.2 and earlier). +. +.TP +.IR memory " (since Linux 2.6.25; " \fBCONFIG_MEMCG\fP ) +The memory controller supports reporting and limiting of process memory, kernel +memory, and swap used by cgroups. +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/memory.rst +(or +.I Documentation/cgroup\-v1/memory.txt +in Linux 5.2 and earlier). +.TP +.IR devices " (since Linux 2.6.26; " \fBCONFIG_CGROUP_DEVICE\fP ) +This supports controlling which processes may create (mknod) devices as +well as open them for reading or writing. +The policies may be specified as allow-lists and deny-lists. +Hierarchy is enforced, so new rules must not +violate existing rules for the target or ancestor cgroups. +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/devices.rst +(or +.I Documentation/cgroup\-v1/devices.txt +in Linux 5.2 and earlier). +.TP +.IR freezer " (since Linux 2.6.28; " \fBCONFIG_CGROUP_FREEZER\fP ) +The +.I freezer +cgroup can suspend and restore (resume) all processes in a cgroup. +Freezing a cgroup +.I /A +also causes its children, for example, processes in +.IR /A/B , +to be frozen. +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/freezer\-subsystem.rst +(or +.I Documentation/cgroup\-v1/freezer\-subsystem.txt +in Linux 5.2 and earlier). +.TP +.IR net_cls " (since Linux 2.6.29; " \fBCONFIG_CGROUP_NET_CLASSID\fP ) +This places a classid, specified for the cgroup, on network packets +created by a cgroup. +These classids can then be used in firewall rules, +as well as used to shape traffic using +.BR tc (8). +This applies only to packets +leaving the cgroup, not to traffic arriving at the cgroup. +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/net_cls.rst +(or +.I Documentation/cgroup\-v1/net_cls.txt +in Linux 5.2 and earlier). +.TP +.IR blkio " (since Linux 2.6.33; " \fBCONFIG_BLK_CGROUP\fP ) +The +.I blkio +cgroup controls and limits access to specified block devices by +applying IO control in the form of throttling and upper limits against leaf +nodes and intermediate nodes in the storage hierarchy. +.IP +Two policies are available. +The first is a proportional-weight time-based division +of disk implemented with CFQ. +This is in effect for leaf nodes using CFQ. +The second is a throttling policy which specifies +upper I/O rate limits on a device. +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/blkio\-controller.rst +(or +.I Documentation/cgroup\-v1/blkio\-controller.txt +in Linux 5.2 and earlier). +.TP +.IR perf_event " (since Linux 2.6.39; " \fBCONFIG_CGROUP_PERF\fP ) +This controller allows +.I perf +monitoring of the set of processes grouped in a cgroup. +.IP +Further information can be found in the kernel source files +.TP +.IR net_prio " (since Linux 3.3; " \fBCONFIG_CGROUP_NET_PRIO\fP ) +This allows priorities to be specified, per network interface, for cgroups. +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/net_prio.rst +(or +.I Documentation/cgroup\-v1/net_prio.txt +in Linux 5.2 and earlier). +.TP +.IR hugetlb " (since Linux 3.5; " \fBCONFIG_CGROUP_HUGETLB\fP ) +This supports limiting the use of huge pages by cgroups. +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/hugetlb.rst +(or +.I Documentation/cgroup\-v1/hugetlb.txt +in Linux 5.2 and earlier). +.TP +.IR pids " (since Linux 4.3; " \fBCONFIG_CGROUP_PIDS\fP ) +This controller permits limiting the number of process that may be created +in a cgroup (and its descendants). +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/pids.rst +(or +.I Documentation/cgroup\-v1/pids.txt +in Linux 5.2 and earlier). +.TP +.IR rdma " (since Linux 4.11; " \fBCONFIG_CGROUP_RDMA\fP ) +The RDMA controller permits limiting the use of +RDMA/IB-specific resources per cgroup. +.IP +Further information can be found in the kernel source file +.I Documentation/admin\-guide/cgroup\-v1/rdma.rst +(or +.I Documentation/cgroup\-v1/rdma.txt +in Linux 5.2 and earlier). +.\" +.SS Creating cgroups and moving processes +A cgroup filesystem initially contains a single root cgroup, '/', +which all processes belong to. +A new cgroup is created by creating a directory in the cgroup filesystem: +.P +.in +4n +.EX +mkdir /sys/fs/cgroup/cpu/cg1 +.EE +.in +.P +This creates a new empty cgroup. +.P +A process may be moved to this cgroup by writing its PID into the cgroup's +.I cgroup.procs +file: +.P +.in +4n +.EX +echo $$ > /sys/fs/cgroup/cpu/cg1/cgroup.procs +.EE +.in +.P +Only one PID at a time should be written to this file. +.P +Writing the value 0 to a +.I cgroup.procs +file causes the writing process to be moved to the corresponding cgroup. +.P +When writing a PID into the +.IR cgroup.procs , +all threads in the process are moved into the new cgroup at once. +.P +Within a hierarchy, a process can be a member of exactly one cgroup. +Writing a process's PID to a +.I cgroup.procs +file automatically removes it from the cgroup of +which it was previously a member. +.P +The +.I cgroup.procs +file can be read to obtain a list of the processes that are +members of a cgroup. +The returned list of PIDs is not guaranteed to be in order. +Nor is it guaranteed to be free of duplicates. +(For example, a PID may be recycled while reading from the list.) +.P +In cgroups v1, an individual thread can be moved to +another cgroup by writing its thread ID +(i.e., the kernel thread ID returned by +.BR clone (2) +and +.BR gettid (2)) +to the +.I tasks +file in a cgroup directory. +This file can be read to discover the set of threads +that are members of the cgroup. +.\" +.SS Removing cgroups +To remove a cgroup, +it must first have no child cgroups and contain no (nonzombie) processes. +So long as that is the case, one can simply +remove the corresponding directory pathname. +Note that files in a cgroup directory cannot and need not be +removed. +.\" +.SS Cgroups v1 release notification +Two files can be used to determine whether the kernel provides +notifications when a cgroup becomes empty. +A cgroup is considered to be empty when it contains no child +cgroups and no member processes. +.P +A special file in the root directory of each cgroup hierarchy, +.IR release_agent , +can be used to register the pathname of a program that may be invoked when +a cgroup in the hierarchy becomes empty. +The pathname of the newly empty cgroup (relative to the cgroup mount point) +is provided as the sole command-line argument when the +.I release_agent +program is invoked. +The +.I release_agent +program might remove the cgroup directory, +or perhaps repopulate it with a process. +.P +The default value of the +.I release_agent +file is empty, meaning that no release agent is invoked. +.P +The content of the +.I release_agent +file can also be specified via a mount option when the +cgroup filesystem is mounted: +.P +.in +4n +.EX +mount \-o release_agent=pathname ... +.EE +.in +.P +Whether or not the +.I release_agent +program is invoked when a particular cgroup becomes empty is determined +by the value in the +.I notify_on_release +file in the corresponding cgroup directory. +If this file contains the value 0, then the +.I release_agent +program is not invoked. +If it contains the value 1, the +.I release_agent +program is invoked. +The default value for this file in the root cgroup is 0. +At the time when a new cgroup is created, +the value in this file is inherited from the corresponding file +in the parent cgroup. +.\" +.SS Cgroup v1 named hierarchies +In cgroups v1, +it is possible to mount a cgroup hierarchy that has no attached controllers: +.P +.in +4n +.EX +mount \-t cgroup \-o none,name=somename none /some/mount/point +.EE +.in +.P +Multiple instances of such hierarchies can be mounted; +each hierarchy must have a unique name. +The only purpose of such hierarchies is to track processes. +(See the discussion of release notification below.) +An example of this is the +.I name=systemd +cgroup hierarchy that is used by +.BR systemd (1) +to track services and user sessions. +.P +Since Linux 5.0, the +.I cgroup_no_v1 +kernel boot option (described below) can be used to disable cgroup v1 +named hierarchies, by specifying +.IR cgroup_no_v1=named . +.\" +.SH CGROUPS VERSION 2 +In cgroups v2, +all mounted controllers reside in a single unified hierarchy. +While (different) controllers may be simultaneously +mounted under the v1 and v2 hierarchies, +it is not possible to mount the same controller simultaneously +under both the v1 and the v2 hierarchies. +.P +The new behaviors in cgroups v2 are summarized here, +and in some cases elaborated in the following subsections. +.IP \[bu] 3 +Cgroups v2 provides a unified hierarchy against +which all controllers are mounted. +.IP \[bu] +"Internal" processes are not permitted. +With the exception of the root cgroup, processes may reside +only in leaf nodes (cgroups that do not themselves contain child cgroups). +The details are somewhat more subtle than this, and are described below. +.IP \[bu] +Active cgroups must be specified via the files +.I cgroup.controllers +and +.IR cgroup.subtree_control . +.IP \[bu] +The +.I tasks +file has been removed. +In addition, the +.I cgroup.clone_children +file that is employed by the +.I cpuset +controller has been removed. +.IP \[bu] +An improved mechanism for notification of empty cgroups is provided by the +.I cgroup.events +file. +.P +For more changes, see the +.I Documentation/admin\-guide/cgroup\-v2.rst +file in the kernel source +(or +.I Documentation/cgroup\-v2.txt +in Linux 4.17 and earlier). +. +.P +Some of the new behaviors listed above saw subsequent modification with +the addition in Linux 4.14 of "thread mode" (described below). +.\" +.SS Cgroups v2 unified hierarchy +In cgroups v1, the ability to mount different controllers +against different hierarchies was intended to allow great flexibility +for application design. +In practice, though, +the flexibility turned out to be less useful than expected, +and in many cases added complexity. +Therefore, in cgroups v2, +all available controllers are mounted against a single hierarchy. +The available controllers are automatically mounted, +meaning that it is not necessary (or possible) to specify the controllers +when mounting the cgroup v2 filesystem using a command such as the following: +.P +.in +4n +.EX +mount \-t cgroup2 none /mnt/cgroup2 +.EE +.in +.P +A cgroup v2 controller is available only if it is not currently in use +via a mount against a cgroup v1 hierarchy. +Or, to put things another way, it is not possible to employ +the same controller against both a v1 hierarchy and the unified v2 hierarchy. +This means that it may be necessary first to unmount a v1 controller +(as described above) before that controller is available in v2. +Since +.BR systemd (1) +makes heavy use of some v1 controllers by default, +it can in some cases be simpler to boot the system with +selected v1 controllers disabled. +To do this, specify the +.I cgroup_no_v1=list +option on the kernel boot command line; +.I list +is a comma-separated list of the names of the controllers to disable, +or the word +.I all +to disable all v1 controllers. +(This situation is correctly handled by +.BR systemd (1), +which falls back to operating without the specified controllers.) +.P +Note that on many modern systems, +.BR systemd (1) +automatically mounts the +.I cgroup2 +filesystem at +.I /sys/fs/cgroup/unified +during the boot process. +.\" +.SS Cgroups v2 mount options +The following options +.RI ( mount\~\-o ) +can be specified when mounting the group v2 filesystem: +.TP +.IR nsdelegate " (since Linux 4.15)" +Treat cgroup namespaces as delegation boundaries. +For details, see below. +.TP +.IR memory_localevents " (since Linux 5.2)" +.\" commit 9852ae3fe5293264f01c49f2571ef7688f7823ce +The +.I memory.events +should show statistics only for the cgroup itself, +and not for any descendant cgroups. +This was the behavior before Linux 5.2. +Starting in Linux 5.2, +the default behavior is to include statistics for descendant cgroups in +.IR memory.events , +and this mount option can be used to revert to the legacy behavior. +This option is system wide and can be set on mount or +modified through remount only from the initial mount namespace; +it is silently ignored in noninitial namespaces. +.\" +.SS Cgroups v2 controllers +The following controllers, documented in the kernel source file +.I Documentation/admin\-guide/cgroup\-v2.rst +(or +.I Documentation/cgroup\-v2.txt +in Linux 4.17 and earlier), +are supported in cgroups version 2: +.TP +.IR cpu " (since Linux 4.15)" +This is the successor to the version 1 +.I cpu +and +.I cpuacct +controllers. +.TP +.IR cpuset " (since Linux 5.0)" +This is the successor of the version 1 +.I cpuset +controller. +.TP +.IR freezer " (since Linux 5.2)" +.\" commit 76f969e8948d82e78e1bc4beb6b9465908e74873 +This is the successor of the version 1 +.I freezer +controller. +.TP +.IR hugetlb " (since Linux 5.6)" +This is the successor of the version 1 +.I hugetlb +controller. +.TP +.IR io " (since Linux 4.5)" +This is the successor of the version 1 +.I blkio +controller. +.TP +.IR memory " (since Linux 4.5)" +This is the successor of the version 1 +.I memory +controller. +.TP +.IR perf_event " (since Linux 4.11)" +This is the same as the version 1 +.I perf_event +controller. +.TP +.IR pids " (since Linux 4.5)" +This is the same as the version 1 +.I pids +controller. +.TP +.IR rdma " (since Linux 4.11)" +This is the same as the version 1 +.I rdma +controller. +.P +There is no direct equivalent of the +.I net_cls +and +.I net_prio +controllers from cgroups version 1. +Instead, support has been added to +.BR iptables (8) +to allow eBPF filters that hook on cgroup v2 pathnames to make decisions +about network traffic on a per-cgroup basis. +.P +The v2 +.I devices +controller provides no interface files; +instead, device control is gated by attaching an eBPF +.RB ( BPF_CGROUP_DEVICE ) +program to a v2 cgroup. +.\" +.SS Cgroups v2 subtree control +Each cgroup in the v2 hierarchy contains the following two files: +.TP +.I cgroup.controllers +This read-only file exposes a list of the controllers that are +.I available +in this cgroup. +The contents of this file match the contents of the +.I cgroup.subtree_control +file in the parent cgroup. +.TP +.I cgroup.subtree_control +This is a list of controllers that are +.I active +.RI ( enabled ) +in the cgroup. +The set of controllers in this file is a subset of the set in the +.I cgroup.controllers +of this cgroup. +The set of active controllers is modified by writing strings to this file +containing space-delimited controller names, +each preceded by '+' (to enable a controller) +or '\-' (to disable a controller), as in the following example: +.IP +.in +4n +.EX +echo \[aq]+pids \-memory\[aq] > x/y/cgroup.subtree_control +.EE +.in +.IP +An attempt to enable a controller +that is not present in +.I cgroup.controllers +leads to an +.B ENOENT +error when writing to the +.I cgroup.subtree_control +file. +.P +Because the list of controllers in +.I cgroup.subtree_control +is a subset of those +.IR cgroup.controllers , +a controller that has been disabled in one cgroup in the hierarchy +can never be re-enabled in the subtree below that cgroup. +.P +A cgroup's +.I cgroup.subtree_control +file determines the set of controllers that are exercised in the +.I child +cgroups. +When a controller (e.g., +.IR pids ) +is present in the +.I cgroup.subtree_control +file of a parent cgroup, +then the corresponding controller-interface files (e.g., +.IR pids.max ) +are automatically created in the children of that cgroup +and can be used to exert resource control in the child cgroups. +.\" +.SS Cgroups v2 \[dq]no internal processes\[dq] rule +Cgroups v2 enforces a so-called "no internal processes" rule. +Roughly speaking, this rule means that, +with the exception of the root cgroup, processes may reside +only in leaf nodes (cgroups that do not themselves contain child cgroups). +This avoids the need to decide how to partition resources between +processes which are members of cgroup A and processes in child cgroups of A. +.P +For instance, if cgroup +.I /cg1/cg2 +exists, then a process may reside in +.IR /cg1/cg2 , +but not in +.IR /cg1 . +This is to avoid an ambiguity in cgroups v1 +with respect to the delegation of resources between processes in +.I /cg1 +and its child cgroups. +The recommended approach in cgroups v2 is to create a subdirectory called +.I leaf +for any nonleaf cgroup which should contain processes, but no child cgroups. +Thus, processes which previously would have gone into +.I /cg1 +would now go into +.IR /cg1/leaf . +This has the advantage of making explicit +the relationship between processes in +.I /cg1/leaf +and +.IR /cg1 's +other children. +.P +The "no internal processes" rule is in fact more subtle than stated above. +More precisely, the rule is that a (nonroot) cgroup can't both +(1) have member processes, and +(2) distribute resources into child cgroups\[em]that is, have a nonempty +.I cgroup.subtree_control +file. +Thus, it +.I is +possible for a cgroup to have both member processes and child cgroups, +but before controllers can be enabled for that cgroup, +the member processes must be moved out of the cgroup +(e.g., perhaps into the child cgroups). +.P +With the Linux 4.14 addition of "thread mode" (described below), +the "no internal processes" rule has been relaxed in some cases. +.\" +.SS Cgroups v2 cgroup.events file +Each nonroot cgroup in the v2 hierarchy contains a read-only file, +.IR cgroup.events , +whose contents are key-value pairs +(delimited by newline characters, with the key and value separated by spaces) +providing state information about the cgroup: +.P +.in +4n +.EX +$ \fBcat mygrp/cgroup.events\fP +populated 1 +frozen 0 +.EE +.in +.P +The following keys may appear in this file: +.TP +.I populated +The value of this key is either 1, +if this cgroup or any of its descendants has member processes, +or otherwise 0. +.TP +.IR frozen " (since Linux 5.2)" +.\" commit 76f969e8948d82e78e1bc4beb6b9465908e7487 +The value of this key is 1 if this cgroup is currently frozen, +or 0 if it is not. +.P +The +.I cgroup.events +file can be monitored, in order to receive notification when the value of +one of its keys changes. +Such monitoring can be done using +.BR inotify (7), +which notifies changes as +.B IN_MODIFY +events, or +.BR poll (2), +which notifies changes by returning the +.B POLLPRI +and +.B POLLERR +bits in the +.I revents +field. +.\" +.SS Cgroup v2 release notification +Cgroups v2 provides a new mechanism for obtaining notification +when a cgroup becomes empty. +The cgroups v1 +.I release_agent +and +.I notify_on_release +files are removed, and replaced by the +.I populated +key in the +.I cgroup.events +file. +This key either has the value 0, +meaning that the cgroup (and its descendants) +contain no (nonzombie) member processes, +or 1, meaning that the cgroup (or one of its descendants) +contains member processes. +.P +The cgroups v2 release-notification mechanism +offers the following advantages over the cgroups v1 +.I release_agent +mechanism: +.IP \[bu] 3 +It allows for cheaper notification, +since a single process can monitor multiple +.I cgroup.events +files (using the techniques described earlier). +By contrast, the cgroups v1 mechanism requires the expense of creating +a process for each notification. +.IP \[bu] +Notification for different cgroup subhierarchies can be delegated +to different processes. +By contrast, the cgroups v1 mechanism allows only one release agent +for an entire hierarchy. +.\" +.SS Cgroups v2 cgroup.stat file +.\" commit ec39225cca42c05ac36853d11d28f877fde5c42e +Each cgroup in the v2 hierarchy contains a read-only +.I cgroup.stat +file (first introduced in Linux 4.14) +that consists of lines containing key-value pairs. +The following keys currently appear in this file: +.TP +.I nr_descendants +This is the total number of visible (i.e., living) descendant cgroups +underneath this cgroup. +.TP +.I nr_dying_descendants +This is the total number of dying descendant cgroups +underneath this cgroup. +A cgroup enters the dying state after being deleted. +It remains in that state for an undefined period +(which will depend on system load) +while resources are freed before the cgroup is destroyed. +Note that the presence of some cgroups in the dying state is normal, +and is not indicative of any problem. +.IP +A process can't be made a member of a dying cgroup, +and a dying cgroup can't be brought back to life. +.\" +.SS Limiting the number of descendant cgroups +Each cgroup in the v2 hierarchy contains the following files, +which can be used to view and set limits on the number +of descendant cgroups under that cgroup: +.TP +.IR cgroup.max.depth " (since Linux 4.14)" +.\" commit 1a926e0bbab83bae8207d05a533173425e0496d1 +This file defines a limit on the depth of nesting of descendant cgroups. +A value of 0 in this file means that no descendant cgroups can be created. +An attempt to create a descendant whose nesting level exceeds +the limit fails +.RI ( mkdir (2) +fails with the error +.BR EAGAIN ). +.IP +Writing the string +.I \[dq]max\[dq] +to this file means that no limit is imposed. +The default value in this file is +.IR \[dq]max\[dq] . +.TP +.IR cgroup.max.descendants " (since Linux 4.14)" +.\" commit 1a926e0bbab83bae8207d05a533173425e0496d1 +This file defines a limit on the number of live descendant cgroups that +this cgroup may have. +An attempt to create more descendants than allowed by the limit fails +.RI ( mkdir (2) +fails with the error +.BR EAGAIN ). +.IP +Writing the string +.I \[dq]max\[dq] +to this file means that no limit is imposed. +The default value in this file is +.IR \[dq]max\[dq] . +.\" +.SH CGROUPS DELEGATION: DELEGATING A HIERARCHY TO A LESS PRIVILEGED USER +In the context of cgroups, +delegation means passing management of some subtree +of the cgroup hierarchy to a nonprivileged user. +Cgroups v1 provides support for delegation based on file permissions +in the cgroup hierarchy but with less strict containment rules than v2 +(as noted below). +Cgroups v2 supports delegation with containment by explicit design. +The focus of the discussion in this section is on delegation in cgroups v2, +with some differences for cgroups v1 noted along the way. +.P +Some terminology is required in order to describe delegation. +A +.I delegater +is a privileged user (i.e., root) who owns a parent cgroup. +A +.I delegatee +is a nonprivileged user who will be granted the permissions needed +to manage some subhierarchy under that parent cgroup, +known as the +.IR "delegated subtree" . +.P +To perform delegation, +the delegater makes certain directories and files writable by the delegatee, +typically by changing the ownership of the objects to be the user ID +of the delegatee. +Assuming that we want to delegate the hierarchy rooted at (say) +.I /dlgt_grp +and that there are not yet any child cgroups under that cgroup, +the ownership of the following is changed to the user ID of the delegatee: +.TP +.I /dlgt_grp +Changing the ownership of the root of the subtree means that any new +cgroups created under the subtree (and the files they contain) +will also be owned by the delegatee. +.TP +.I /dlgt_grp/cgroup.procs +Changing the ownership of this file means that the delegatee +can move processes into the root of the delegated subtree. +.TP +.IR /dlgt_grp/cgroup.subtree_control " (cgroups v2 only)" +Changing the ownership of this file means that the delegatee +can enable controllers (that are present in +.IR /dlgt_grp/cgroup.controllers ) +in order to further redistribute resources at lower levels in the subtree. +(As an alternative to changing the ownership of this file, +the delegater might instead add selected controllers to this file.) +.TP +.IR /dlgt_grp/cgroup.threads " (cgroups v2 only)" +Changing the ownership of this file is necessary if a threaded subtree +is being delegated (see the description of "thread mode", below). +This permits the delegatee to write thread IDs to the file. +(The ownership of this file can also be changed when delegating +a domain subtree, but currently this serves no purpose, +since, as described below, it is not possible to move a thread between +domain cgroups by writing its thread ID to the +.I cgroup.threads +file.) +.IP +In cgroups v1, the corresponding file that should instead be delegated is the +.I tasks +file. +.P +The delegater should +.I not +change the ownership of any of the controller interfaces files (e.g., +.IR pids.max , +.IR memory.high ) +in +.IR dlgt_grp . +Those files are used from the next level above the delegated subtree +in order to distribute resources into the subtree, +and the delegatee should not have permission to change +the resources that are distributed into the delegated subtree. +.P +See also the discussion of the +.I /sys/kernel/cgroup/delegate +file in NOTES for information about further delegatable files in cgroups v2. +.P +After the aforementioned steps have been performed, +the delegatee can create child cgroups within the delegated subtree +(the cgroup subdirectories and the files they contain +will be owned by the delegatee) +and move processes between cgroups in the subtree. +If some controllers are present in +.IR dlgt_grp/cgroup.subtree_control , +or the ownership of that file was passed to the delegatee, +the delegatee can also control the further redistribution +of the corresponding resources into the delegated subtree. +.\" +.SS Cgroups v2 delegation: nsdelegate and cgroup namespaces +Starting with Linux 4.13, +.\" commit 5136f6365ce3eace5a926e10f16ed2a233db5ba9 +there is a second way to perform cgroup delegation in the cgroups v2 hierarchy. +This is done by mounting or remounting the cgroup v2 filesystem with the +.I nsdelegate +mount option. +For example, if the cgroup v2 filesystem has already been mounted, +we can remount it with the +.I nsdelegate +option as follows: +.P +.in +4n +.EX +mount \-t cgroup2 \-o remount,nsdelegate \e + none /sys/fs/cgroup/unified +.EE +.in +.\" +.\" Alternatively, we could boot the kernel with the options: +.\" +.\" cgroup_no_v1=all systemd.legacy_systemd_cgroup_controller +.\" +.\" The effect of the latter option is to prevent systemd from employing +.\" its "hybrid" cgroup mode, where it tries to make use of cgroups v2. +.P +The effect of this mount option is to cause cgroup namespaces +to automatically become delegation boundaries. +More specifically, +the following restrictions apply for processes inside the cgroup namespace: +.IP \[bu] 3 +Writes to controller interface files in the root directory of the namespace +will fail with the error +.BR EPERM . +Processes inside the cgroup namespace can still write to delegatable +files in the root directory of the cgroup namespace such as +.I cgroup.procs +and +.IR cgroup.subtree_control , +and can create subhierarchy underneath the root directory. +.IP \[bu] +Attempts to migrate processes across the namespace boundary are denied +(with the error +.BR ENOENT ). +Processes inside the cgroup namespace can still +(subject to the containment rules described below) +move processes between cgroups +.I within +the subhierarchy under the namespace root. +.P +The ability to define cgroup namespaces as delegation boundaries +makes cgroup namespaces more useful. +To understand why, suppose that we already have one cgroup hierarchy +that has been delegated to a nonprivileged user, +.IR cecilia , +using the older delegation technique described above. +Suppose further that +.I cecilia +wanted to further delegate a subhierarchy +under the existing delegated hierarchy. +(For example, the delegated hierarchy might be associated with +an unprivileged container run by +.IR cecilia .) +Even if a cgroup namespace was employed, +because both hierarchies are owned by the unprivileged user +.IR cecilia , +the following illegitimate actions could be performed: +.IP \[bu] 3 +A process in the inferior hierarchy could change the +resource controller settings in the root directory of that hierarchy. +(These resource controller settings are intended to allow control to +be exercised from the +.I parent +cgroup; +a process inside the child cgroup should not be allowed to modify them.) +.IP \[bu] +A process inside the inferior hierarchy could move processes +into and out of the inferior hierarchy if the cgroups in the +superior hierarchy were somehow visible. +.P +Employing the +.I nsdelegate +mount option prevents both of these possibilities. +.P +The +.I nsdelegate +mount option only has an effect when performed in +the initial mount namespace; +in other mount namespaces, the option is silently ignored. +.P +.IR Note : +On some systems, +.BR systemd (1) +automatically mounts the cgroup v2 filesystem. +In order to experiment with the +.I nsdelegate +operation, it may be useful to boot the kernel with +the following command-line options: +.P +.in +4n +.EX +cgroup_no_v1=all systemd.legacy_systemd_cgroup_controller +.EE +.in +.P +These options cause the kernel to boot with the cgroups v1 controllers +disabled (meaning that the controllers are available in the v2 hierarchy), +and tells +.BR systemd (1) +not to mount and use the cgroup v2 hierarchy, +so that the v2 hierarchy can be manually mounted +with the desired options after boot-up. +.\" +.SS Cgroup delegation containment rules +Some delegation +.I containment rules +ensure that the delegatee can move processes between cgroups within the +delegated subtree, +but can't move processes from outside the delegated subtree into +the subtree or vice versa. +A nonprivileged process (i.e., the delegatee) can write the PID of +a "target" process into a +.I cgroup.procs +file only if all of the following are true: +.IP \[bu] 3 +The writer has write permission on the +.I cgroup.procs +file in the destination cgroup. +.IP \[bu] +The writer has write permission on the +.I cgroup.procs +file in the nearest common ancestor of the source and destination cgroups. +Note that in some cases, +the nearest common ancestor may be the source or destination cgroup itself. +This requirement is not enforced for cgroups v1 hierarchies, +with the consequence that containment in v1 is less strict than in v2. +(For example, in cgroups v1 the user that owns two distinct +delegated subhierarchies can move a process between the hierarchies.) +.IP \[bu] +If the cgroup v2 filesystem was mounted with the +.I nsdelegate +option, the writer must be able to see the source and destination cgroups +from its cgroup namespace. +.IP \[bu] +In cgroups v1: +the effective UID of the writer (i.e., the delegatee) matches the +real user ID or the saved set-user-ID of the target process. +Before Linux 4.11, +.\" commit 576dd464505fc53d501bb94569db76f220104d28 +this requirement also applied in cgroups v2 +(This was a historical requirement inherited from cgroups v1 +that was later deemed unnecessary, +since the other rules suffice for containment in cgroups v2.) +.P +.IR Note : +one consequence of these delegation containment rules is that the +unprivileged delegatee can't place the first process into +the delegated subtree; +instead, the delegater must place the first process +(a process owned by the delegatee) into the delegated subtree. +.\" +.SH CGROUPS VERSION 2 THREAD MODE +Among the restrictions imposed by cgroups v2 that were not present +in cgroups v1 are the following: +.IP \[bu] 3 +.IR "No thread-granularity control" : +all of the threads of a process must be in the same cgroup. +.IP \[bu] +.IR "No internal processes" : +a cgroup can't both have member processes and +exercise controllers on child cgroups. +.P +Both of these restrictions were added because +the lack of these restrictions had caused problems +in cgroups v1. +In particular, the cgroups v1 ability to allow thread-level granularity +for cgroup membership made no sense for some controllers. +(A notable example was the +.I memory +controller: since threads share an address space, +it made no sense to split threads across different +.I memory +cgroups.) +.P +Notwithstanding the initial design decision in cgroups v2, +there were use cases for certain controllers, notably the +.I cpu +controller, +for which thread-level granularity of control was meaningful and useful. +To accommodate such use cases, Linux 4.14 added +.I "thread mode" +for cgroups v2. +.P +Thread mode allows the following: +.IP \[bu] 3 +The creation of +.I threaded subtrees +in which the threads of a process may +be spread across cgroups inside the tree. +(A threaded subtree may contain multiple multithreaded processes.) +.IP \[bu] +The concept of +.IR "threaded controllers" , +which can distribute resources across the cgroups in a threaded subtree. +.IP \[bu] +A relaxation of the "no internal processes rule", +so that, within a threaded subtree, +a cgroup can both contain member threads and +exercise resource control over child cgroups. +.P +With the addition of thread mode, +each nonroot cgroup now contains a new file, +.IR cgroup.type , +that exposes, and in some circumstances can be used to change, +the "type" of a cgroup. +This file contains one of the following type values: +.TP +.I domain +This is a normal v2 cgroup that provides process-granularity control. +If a process is a member of this cgroup, +then all threads of the process are (by definition) in the same cgroup. +This is the default cgroup type, +and provides the same behavior that was provided for +cgroups in the initial cgroups v2 implementation. +.TP +.I threaded +This cgroup is a member of a threaded subtree. +Threads can be added to this cgroup, +and controllers can be enabled for the cgroup. +.TP +.I domain threaded +This is a domain cgroup that serves as the root of a threaded subtree. +This cgroup type is also known as "threaded root". +.TP +.I domain invalid +This is a cgroup inside a threaded subtree +that is in an "invalid" state. +Processes can't be added to the cgroup, +and controllers can't be enabled for the cgroup. +The only thing that can be done with this cgroup (other than deleting it) +is to convert it to a +.I threaded +cgroup by writing the string +.I \[dq]threaded\[dq] +to the +.I cgroup.type +file. +.IP +The rationale for the existence of this "interim" type +during the creation of a threaded subtree +(rather than the kernel simply immediately converting all cgroups +under the threaded root to the type +.IR threaded ) +is to allow for +possible future extensions to the thread mode model +.\" +.SS Threaded versus domain controllers +With the addition of threads mode, +cgroups v2 now distinguishes two types of resource controllers: +.IP \[bu] 3 +.I Threaded +.\" In the kernel source, look for ".threaded[ \t]*= true" in +.\" initializations of struct cgroup_subsys +controllers: these controllers support thread-granularity for +resource control and can be enabled inside threaded subtrees, +with the result that the corresponding controller-interface files +appear inside the cgroups in the threaded subtree. +As at Linux 4.19, the following controllers are threaded: +.IR cpu , +.IR perf_event , +and +.IR pids . +.IP \[bu] +.I Domain +controllers: these controllers support only process granularity +for resource control. +From the perspective of a domain controller, +all threads of a process are always in the same cgroup. +Domain controllers can't be enabled inside a threaded subtree. +.\" +.SS Creating a threaded subtree +There are two pathways that lead to the creation of a threaded subtree. +The first pathway proceeds as follows: +.IP (1) 5 +We write the string +.I \[dq]threaded\[dq] +to the +.I cgroup.type +file of a cgroup +.I y/z +that currently has the type +.IR domain . +This has the following effects: +.RS +.IP \[bu] 3 +The type of the cgroup +.I y/z +becomes +.IR threaded . +.IP \[bu] +The type of the parent cgroup, +.IR y , +becomes +.IR "domain threaded" . +The parent cgroup is the root of a threaded subtree +(also known as the "threaded root"). +.IP \[bu] +All other cgroups under +.I y +that were not already of type +.I threaded +(because they were inside already existing threaded subtrees +under the new threaded root) +are converted to type +.IR "domain invalid" . +Any subsequently created cgroups under +.I y +will also have the type +.IR "domain invalid" . +.RE +.IP (2) +We write the string +.I \[dq]threaded\[dq] +to each of the +.I domain invalid +cgroups under +.IR y , +in order to convert them to the type +.IR threaded . +As a consequence of this step, all threads under the threaded root +now have the type +.I threaded +and the threaded subtree is now fully usable. +The requirement to write +.I \[dq]threaded\[dq] +to each of these cgroups is somewhat cumbersome, +but allows for possible future extensions to the thread-mode model. +.P +The second way of creating a threaded subtree is as follows: +.IP (1) 5 +In an existing cgroup, +.IR z , +that currently has the type +.IR domain , +we (1.1) enable one or more threaded controllers and +(1.2) make a process a member of +.IR z . +(These two steps can be done in either order.) +This has the following consequences: +.RS +.IP \[bu] 3 +The type of +.I z +becomes +.IR "domain threaded" . +.IP \[bu] +All of the descendant cgroups of +.I z +that were not already of type +.I threaded +are converted to type +.IR "domain invalid" . +.RE +.IP (2) +As before, we make the threaded subtree usable by writing the string +.I \[dq]threaded\[dq] +to each of the +.I domain invalid +cgroups under +.IR z , +in order to convert them to the type +.IR threaded . +.P +One of the consequences of the above pathways to creating a threaded subtree +is that the threaded root cgroup can be a parent only to +.I threaded +(and +.IR "domain invalid" ) +cgroups. +The threaded root cgroup can't be a parent of a +.I domain +cgroups, and a +.I threaded +cgroup +can't have a sibling that is a +.I domain +cgroup. +.\" +.SS Using a threaded subtree +Within a threaded subtree, threaded controllers can be enabled +in each subgroup whose type has been changed to +.IR threaded ; +upon doing so, the corresponding controller interface files +appear in the children of that cgroup. +.P +A process can be moved into a threaded subtree by writing its PID to the +.I cgroup.procs +file in one of the cgroups inside the tree. +This has the effect of making all of the threads +in the process members of the corresponding cgroup +and makes the process a member of the threaded subtree. +The threads of the process can then be spread across +the threaded subtree by writing their thread IDs (see +.BR gettid (2)) +to the +.I cgroup.threads +files in different cgroups inside the subtree. +The threads of a process must all reside in the same threaded subtree. +.P +As with writing to +.IR cgroup.procs , +some containment rules apply when writing to the +.I cgroup.threads +file: +.IP \[bu] 3 +The writer must have write permission on the +cgroup.threads +file in the destination cgroup. +.IP \[bu] +The writer must have write permission on the +.I cgroup.procs +file in the common ancestor of the source and destination cgroups. +(In some cases, +the common ancestor may be the source or destination cgroup itself.) +.IP \[bu] +The source and destination cgroups must be in the same threaded subtree. +(Outside a threaded subtree, an attempt to move a thread by writing +its thread ID to the +.I cgroup.threads +file in a different +.I domain +cgroup fails with the error +.BR EOPNOTSUPP .) +.P +The +.I cgroup.threads +file is present in each cgroup (including +.I domain +cgroups) and can be read in order to discover the set of threads +that is present in the cgroup. +The set of thread IDs obtained when reading this file +is not guaranteed to be ordered or free of duplicates. +.P +The +.I cgroup.procs +file in the threaded root shows the PIDs of all processes +that are members of the threaded subtree. +The +.I cgroup.procs +files in the other cgroups in the subtree are not readable. +.P +Domain controllers can't be enabled in a threaded subtree; +no controller-interface files appear inside the cgroups underneath the +threaded root. +From the point of view of a domain controller, +threaded subtrees are invisible: +a multithreaded process inside a threaded subtree appears to a domain +controller as a process that resides in the threaded root cgroup. +.P +Within a threaded subtree, the "no internal processes" rule does not apply: +a cgroup can both contain member processes (or thread) +and exercise controllers on child cgroups. +.\" +.SS Rules for writing to cgroup.type and creating threaded subtrees +A number of rules apply when writing to the +.I cgroup.type +file: +.IP \[bu] 3 +Only the string +.I \[dq]threaded\[dq] +may be written. +In other words, the only explicit transition that is possible is to convert a +.I domain +cgroup to type +.IR threaded . +.IP \[bu] +The effect of writing +.I \[dq]threaded\[dq] +depends on the current value in +.IR cgroup.type , +as follows: +.RS +.IP \[bu] 3 +.I domain +or +.IR "domain threaded" : +start the creation of a threaded subtree +(whose root is the parent of this cgroup) via +the first of the pathways described above; +.IP \[bu] +.IR "domain\ invalid" : +convert this cgroup (which is inside a threaded subtree) to a usable (i.e., +.IR threaded ) +state; +.IP \[bu] +.IR threaded : +no effect (a "no-op"). +.RE +.IP \[bu] +We can't write to a +.I cgroup.type +file if the parent's type is +.IR "domain invalid" . +In other words, the cgroups of a threaded subtree must be converted to the +.I threaded +state in a top-down manner. +.P +There are also some constraints that must be satisfied +in order to create a threaded subtree rooted at the cgroup +.IR x : +.IP \[bu] 3 +There can be no member processes in the descendant cgroups of +.IR x . +(The cgroup +.I x +can itself have member processes.) +.IP \[bu] +No domain controllers may be enabled in +.IR x 's +.I cgroup.subtree_control +file. +.P +If any of the above constraints is violated, then an attempt to write +.I \[dq]threaded\[dq] +to a +.I cgroup.type +file fails with the error +.BR ENOTSUP . +.\" +.SS The \[dq]domain threaded\[dq] cgroup type +According to the pathways described above, +the type of a cgroup can change to +.I domain threaded +in either of the following cases: +.IP \[bu] 3 +The string +.I \[dq]threaded\[dq] +is written to a child cgroup. +.IP \[bu] +A threaded controller is enabled inside the cgroup and +a process is made a member of the cgroup. +.P +A +.I domain threaded +cgroup, +.IR x , +can revert to the type +.I domain +if the above conditions no longer hold true\[em]that is, if all +.I threaded +child cgroups of +.I x +are removed and either +.I x +no longer has threaded controllers enabled or +no longer has member processes. +.P +When a +.I domain threaded +cgroup +.I x +reverts to the type +.IR domain : +.IP \[bu] 3 +All +.I domain invalid +descendants of +.I x +that are not in lower-level threaded subtrees revert to the type +.IR domain . +.IP \[bu] +The root cgroups in any lower-level threaded subtrees revert to the type +.IR "domain threaded" . +.\" +.SS Exceptions for the root cgroup +The root cgroup of the v2 hierarchy is treated exceptionally: +it can be the parent of both +.I domain +and +.I threaded +cgroups. +If the string +.I \[dq]threaded\[dq] +is written to the +.I cgroup.type +file of one of the children of the root cgroup, then +.IP \[bu] 3 +The type of that cgroup becomes +.IR threaded . +.IP \[bu] +The type of any descendants of that cgroup that +are not part of lower-level threaded subtrees changes to +.IR "domain invalid" . +.P +Note that in this case, there is no cgroup whose type becomes +.IR "domain threaded" . +(Notionally, the root cgroup can be considered as the threaded root +for the cgroup whose type was changed to +.IR threaded .) +.P +The aim of this exceptional treatment for the root cgroup is to +allow a threaded cgroup that employs the +.I cpu +controller to be placed as high as possible in the hierarchy, +so as to minimize the (small) cost of traversing the cgroup hierarchy. +.\" +.SS The cgroups v2 \[dq]cpu\[dq] controller and realtime threads +As at Linux 4.19, the cgroups v2 +.I cpu +controller does not support control of realtime threads +(specifically threads scheduled under any of the policies +.BR SCHED_FIFO , +.BR SCHED_RR , +described +.BR SCHED_DEADLINE ; +see +.BR sched (7)). +Therefore, the +.I cpu +controller can be enabled in the root cgroup only +if all realtime threads are in the root cgroup. +(If there are realtime threads in nonroot cgroups, then a +.BR write (2) +of the string +.I \[dq]+cpu\[dq] +to the +.I cgroup.subtree_control +file fails with the error +.BR EINVAL .) +.P +On some systems, +.BR systemd (1) +places certain realtime threads in nonroot cgroups in the v2 hierarchy. +On such systems, +these threads must first be moved to the root cgroup before the +.I cpu +controller can be enabled. +.\" +.SH ERRORS +The following errors can occur for +.BR mount (2): +.TP +.B EBUSY +An attempt to mount a cgroup version 1 filesystem specified neither the +.I name= +option (to mount a named hierarchy) nor a controller name (or +.IR all ). +.SH NOTES +A child process created via +.BR fork (2) +inherits its parent's cgroup memberships. +A process's cgroup memberships are preserved across +.BR execve (2). +.P +The +.BR clone3 (2) +.B CLONE_INTO_CGROUP +flag can be used to create a child process that begins its life in +a different version 2 cgroup from the parent process. +.\" +.SS /proc files +.TP +.IR /proc/cgroups " (since Linux 2.6.24)" +This file contains information about the controllers +that are compiled into the kernel. +An example of the contents of this file (reformatted for readability) +is the following: +.IP +.in +4n +.EX +#subsys_name hierarchy num_cgroups enabled +cpuset 4 1 1 +cpu 8 1 1 +cpuacct 8 1 1 +blkio 6 1 1 +memory 3 1 1 +devices 10 84 1 +freezer 7 1 1 +net_cls 9 1 1 +perf_event 5 1 1 +net_prio 9 1 1 +hugetlb 0 1 0 +pids 2 1 1 +.EE +.in +.IP +The fields in this file are, from left to right: +.RS +.IP [1] 5 +The name of the controller. +.IP [2] +The unique ID of the cgroup hierarchy on which this controller is mounted. +If multiple cgroups v1 controllers are bound to the same hierarchy, +then each will show the same hierarchy ID in this field. +The value in this field will be 0 if: +.RS +.IP \[bu] 3 +the controller is not mounted on a cgroups v1 hierarchy; +.IP \[bu] +the controller is bound to the cgroups v2 single unified hierarchy; or +.IP \[bu] +the controller is disabled (see below). +.RE +.IP [3] +The number of control groups in this hierarchy using this controller. +.IP [4] +This field contains the value 1 if this controller is enabled, +or 0 if it has been disabled (via the +.I cgroup_disable +kernel command-line boot parameter). +.RE +.TP +.IR /proc/ pid /cgroup " (since Linux 2.6.24)" +This file describes control groups to which the process +with the corresponding PID belongs. +The displayed information differs for +cgroups version 1 and version 2 hierarchies. +.IP +For each cgroup hierarchy of which the process is a member, +there is one entry containing three colon-separated fields: +.IP +.in +4n +.EX +hierarchy\-ID:controller\-list:cgroup\-path +.EE +.in +.IP +For example: +.IP +.in +4n +.EX +5:cpuacct,cpu,cpuset:/daemons +.EE +.in +.IP +The colon-separated fields are, from left to right: +.RS +.IP [1] 5 +For cgroups version 1 hierarchies, +this field contains a unique hierarchy ID number +that can be matched to a hierarchy ID in +.IR /proc/cgroups . +For the cgroups version 2 hierarchy, this field contains the value 0. +.IP [2] +For cgroups version 1 hierarchies, +this field contains a comma-separated list of the controllers +bound to the hierarchy. +For the cgroups version 2 hierarchy, this field is empty. +.IP [3] +This field contains the pathname of the control group in the hierarchy +to which the process belongs. +This pathname is relative to the mount point of the hierarchy. +.RE +.\" +.SS /sys/kernel/cgroup files +.TP +.IR /sys/kernel/cgroup/delegate " (since Linux 4.15)" +.\" commit 01ee6cfb1483fe57c9cbd8e73817dfbf9bacffd3 +This file exports a list of the cgroups v2 files +(one per line) that are delegatable +(i.e., whose ownership should be changed to the user ID of the delegatee). +In the future, the set of delegatable files may change or grow, +and this file provides a way for the kernel to inform +user-space applications of which files must be delegated. +As at Linux 4.15, one sees the following when inspecting this file: +.IP +.in +4n +.EX +$ \fBcat /sys/kernel/cgroup/delegate\fP +cgroup.procs +cgroup.subtree_control +cgroup.threads +.EE +.in +.TP +.IR /sys/kernel/cgroup/features " (since Linux 4.15)" +.\" commit 5f2e673405b742be64e7c3604ed4ed3ac14f35ce +Over time, the set of cgroups v2 features that are provided by the +kernel may change or grow, +or some features may not be enabled by default. +This file provides a way for user-space applications to discover what +features the running kernel supports and has enabled. +Features are listed one per line: +.IP +.in +4n +.EX +$ \fBcat /sys/kernel/cgroup/features\fP +nsdelegate +memory_localevents +.EE +.in +.IP +The entries that can appear in this file are: +.RS +.TP +.IR memory_localevents " (since Linux 5.2)" +The kernel supports the +.I memory_localevents +mount option. +.TP +.IR nsdelegate " (since Linux 4.15)" +The kernel supports the +.I nsdelegate +mount option. +.TP +.IR memory_recursiveprot " (since Linux 5.7)" +.\" commit 8a931f801340c2be10552c7b5622d5f4852f3a36 +The kernel supports the +.I memory_recursiveprot +mount option. +.RE +.SH SEE ALSO +.BR prlimit (1), +.BR systemd (1), +.BR systemd\-cgls (1), +.BR systemd\-cgtop (1), +.BR clone (2), +.BR ioprio_set (2), +.BR perf_event_open (2), +.BR setrlimit (2), +.BR cgroup_namespaces (7), +.BR cpuset (7), +.BR namespaces (7), +.BR sched (7), +.BR user_namespaces (7) +.P +The kernel source file +.IR Documentation/admin\-guide/cgroup\-v2.rst . diff --git a/man/man7/charsets.7 b/man/man7/charsets.7 new file mode 100644 index 0000000..58dfee7 --- /dev/null +++ b/man/man7/charsets.7 @@ -0,0 +1,335 @@ +.\" Copyright (c) 1996 Eric S. Raymond +.\" and Copyright (c) Andries Brouwer +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" This is combined from many sources, including notes by aeb and +.\" research by esr. Portions derive from a writeup by Roman Czyborra. +.\" +.\" Changes also by David Starner . +.\" +.TH charsets 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +charsets \- character set standards and internationalization +.SH DESCRIPTION +This manual page gives an overview on different character set standards +and how they were used on Linux before Unicode became ubiquitous. +Some of this information is still helpful for people working with legacy +systems and documents. +.P +Standards discussed include such as +ASCII, GB 2312, ISO/IEC\~8859, JIS, KOI8-R, KS, and Unicode. +.P +The primary emphasis is on character sets that were actually used by +locale character sets, not the myriad others that could be found in data +from other systems. +.SS ASCII +ASCII (American Standard Code For Information Interchange) is the original +7-bit character set, originally designed for American English. +Also known as US-ASCII. +It is currently described by the ISO/IEC\~646:1991 IRV +(International Reference Version) standard. +.P +Various ASCII variants replacing the dollar sign with other currency +symbols and replacing punctuation with non-English alphabetic +characters to cover German, French, Spanish, and others in 7 bits +emerged. +All are deprecated; +glibc does not support locales whose character sets are not true +supersets of ASCII. +.P +As Unicode, when using UTF-8, is ASCII-compatible, plain ASCII text +still renders properly on modern UTF-8 using systems. +.SS ISO/IEC\~8859 +ISO/IEC\~8859 is a series of 15 8-bit character sets, all of which have ASCII +in their low (7-bit) half, invisible control characters in positions +128 to 159, and 96 fixed-width graphics in positions 160\[en]255. +.P +Of these, the most important is ISO/IEC\~8859-1 +("Latin Alphabet No. 1" / Latin-1). +It was widely adopted and supported by different systems, +and is gradually being replaced with Unicode. +The ISO/IEC\~8859-1 characters are also the first 256 characters of Unicode. +.P +Console support for the other ISO/IEC\~8859 character sets is available under +Linux through user-mode utilities (such as +.BR setfont (8)) +that modify keyboard bindings and the EGA graphics +table and employ the "user mapping" font table in the console +driver. +.P +Here are brief descriptions of each character set: +.TP +ISO/IEC\~8859-1 (Latin-1) +Latin-1 covers many European languages such as Albanian, Basque, +Danish, English, Faroese, Galician, Icelandic, Irish, Italian, +Norwegian, Portuguese, Spanish, and Swedish. +The lack of the ligatures +Dutch IJ/ij, +French œ, +and „German“ quotation marks +was considered tolerable. +.TP +ISO/IEC\~8859-2 (Latin-2) +Latin-2 supports many Latin-written Central and East European +languages such as Bosnian, Croatian, Czech, German, Hungarian, Polish, +Slovak, and Slovene. +Replacing Romanian ș/ț with ş/ţ +was considered tolerable. +.TP +ISO/IEC\~8859-3 (Latin-3) +Latin-3 was designed to cover of Esperanto, Maltese, and Turkish, but +ISO/IEC\~8859-9 later superseded it for Turkish. +.TP +ISO/IEC\~8859-4 (Latin-4) +Latin-4 introduced letters for North European languages such as +Estonian, Latvian, and Lithuanian, but was superseded by ISO/IEC\~8859-10 and +ISO/IEC\~8859-13. +.TP +ISO/IEC\~8859-5 +Cyrillic letters supporting Bulgarian, Byelorussian, Macedonian, +Russian, Serbian, and (almost completely) Ukrainian. +It was never widely used, see the discussion of KOI8-R/KOI8-U below. +.TP +ISO/IEC\~8859-6 +Was created for Arabic. +The ISO/IEC\~8859-6 glyph table is a fixed font of separate +letter forms, but a proper display engine should combine these +using the proper initial, medial, and final forms. +.TP +ISO/IEC\~8859-7 +Was created for Modern Greek in 1987, updated in 2003. +.TP +ISO/IEC\~8859-8 +Supports Modern Hebrew without niqud (punctuation signs). +Niqud and full-fledged Biblical Hebrew were outside the scope of this +character set. +.TP +ISO/IEC\~8859-9 (Latin-5) +This is a variant of Latin-1 that replaces Icelandic letters with +Turkish ones. +.TP +ISO/IEC\~8859-10 (Latin-6) +Latin-6 added the Inuit (Greenlandic) and Sami (Lappish) letters that were +missing in Latin-4 to cover the entire Nordic area. +.TP +ISO/IEC\~8859-11 +Supports the Thai alphabet and is nearly identical to the TIS-620 +standard. +.TP +ISO/IEC\~8859-12 +This character set does not exist. +.TP +ISO/IEC\~8859-13 (Latin-7) +Supports the Baltic Rim languages; in particular, it includes Latvian +characters not found in Latin-4. +.TP +ISO/IEC\~8859-14 (Latin-8) +This is the Celtic character set, covering Old Irish, Manx, Gaelic, +Welsh, Cornish, and Breton. +.TP +ISO/IEC\~8859-15 (Latin-9) +Latin-9 is similar to the widely used Latin-1 but replaces some less +common symbols with the Euro sign and French and Finnish letters that +were missing in Latin-1. +.TP +ISO/IEC\~8859-16 (Latin-10) +This character set covers many Southeast European languages, +and most importantly supports Romanian more completely than Latin-2. +.SS KOI8-R / KOI8-U +KOI8-R is a non-ISO character set popular in Russia before Unicode. +The lower half is ASCII; +the upper is a Cyrillic character set somewhat better designed than +ISO/IEC\~8859-5. +KOI8-U, based on KOI8-R, has better support for Ukrainian. +Neither of these sets are ISO/IEC\~2022 compatible, +unlike the ISO/IEC\~8859 series. +.P +Console support for KOI8-R is available under Linux through user-mode +utilities that modify keyboard bindings and the EGA graphics table, +and employ the "user mapping" font table in the console driver. +.SS GB 2312 +GB 2312 is a mainland Chinese national standard character set used +to express simplified Chinese. +Just like JIS X 0208, characters are +mapped into a 94x94 two-byte matrix used to construct EUC-CN. +EUC-CN +is the most important encoding for Linux and includes ASCII and +GB 2312. +Note that EUC-CN is often called as GB, GB 2312, or CN-GB. +.SS Big5 +Big5 was a popular character set in Taiwan to express traditional +Chinese. +(Big5 is both a character set and an encoding.) +It is a superset of ASCII. +Non-ASCII characters are expressed in two bytes. +Bytes 0xa1\[en]0xfe are used as leading bytes for two-byte characters. +Big5 and its extension were widely used in Taiwan and Hong Kong. +It is not ISO/IEC\~2022 compliant. +.\" Thanks to Tomohiro KUBOTA for the following sections about +.\" national standards. +.SS JIS X 0208 +JIS X 0208 is a Japanese national standard character set. +Though there are some more Japanese national standard character sets (like +JIS X 0201, JIS X 0212, and JIS X 0213), this is the most important one. +Characters are mapped into a 94x94 two-byte matrix, +whose each byte is in the range 0x21\[en]0x7e. +Note that JIS X 0208 is a character set, not an encoding. +This means that JIS X 0208 +itself is not used for expressing text data. +JIS X 0208 is used +as a component to construct encodings such as EUC-JP, Shift_JIS, +and ISO/IEC\~2022-JP. +EUC-JP is the most important encoding for Linux +and includes ASCII and JIS X 0208. +In EUC-JP, JIS X 0208 +characters are expressed in two bytes, each of which is the +JIS X 0208 code plus 0x80. +.SS KS X 1001 +KS X 1001 is a Korean national standard character set. +Just as +JIS X 0208, characters are mapped into a 94x94 two-byte matrix. +KS X 1001 is used like JIS X 0208, as a component +to construct encodings such as EUC-KR, Johab, and ISO/IEC\~2022-KR. +EUC-KR is the most important encoding for Linux and includes +ASCII and KS X 1001. +KS C 5601 is an older name for KS X 1001. +.SS ISO/IEC\~2022 and ISO/IEC\~4873 +The ISO/IEC\~2022 and ISO/IEC\~4873 standards describe a font-control model +based on VT100 practice. +This model is (partially) supported +by the Linux kernel and by +.BR xterm (1). +Several ISO/IEC\~2022-based character encodings have been defined, +especially for Japanese. +.P +There are 4 graphic character sets, called G0, G1, G2, and G3, +and one of them is the current character set for codes with +high bit zero (initially G0), and one of them is the current +character set for codes with high bit one (initially G1). +Each graphic character set has 94 or 96 characters, and is +essentially a 7-bit character set. +It uses codes either +040\[en]0177 (041\[en]0176) or 0240\[en]0377 (0241\[en]0376). +G0 always has size 94 and uses codes 041\[en]0176. +.P +Switching between character sets is done using the shift functions +\fB\[ha]N\fP (SO or LS1), \fB\[ha]O\fP (SI or LS0), ESC n (LS2), ESC o (LS3), +ESC N (SS2), ESC O (SS3), ESC \[ti] (LS1R), ESC } (LS2R), ESC | (LS3R). +The function LS\fIn\fP makes character set G\fIn\fP the current one +for codes with high bit zero. +The function LS\fIn\fPR makes character set G\fIn\fP the current one +for codes with high bit one. +The function SS\fIn\fP makes character set G\fIn\fP (\fIn\fP=2 or 3) +the current one for the next character only (regardless of the value +of its high order bit). +.P +A 94-character set is designated as G\fIn\fP character set +by an escape sequence ESC ( xx (for G0), ESC ) xx (for G1), +ESC * xx (for G2), ESC + xx (for G3), where xx is a symbol +or a pair of symbols found in the ISO/IEC\~2375 International +Register of Coded Character Sets. +For example, ESC ( @ selects the ISO/IEC\~646 character set as G0, +ESC ( A selects the UK standard character set (with pound +instead of number sign), ESC ( B selects ASCII (with dollar +instead of currency sign), ESC ( M selects a character set +for African languages, ESC ( ! A selects the Cuban character +set, and so on. +.P +A 96-character set is designated as G\fIn\fP character set +by an escape sequence ESC \- xx (for G1), ESC . xx (for G2) +or ESC / xx (for G3). +For example, ESC \- G selects the Hebrew alphabet as G1. +.P +A multibyte character set is designated as G\fIn\fP character set +by an escape sequence ESC $ xx or ESC $ ( xx (for G0), +ESC $ ) xx (for G1), ESC $ * xx (for G2), ESC $ + xx (for G3). +For example, ESC $ ( C selects the Korean character set for G0. +The Japanese character set selected by ESC $ B has a more +recent version selected by ESC & @ ESC $ B. +.P +ISO/IEC\~4873 stipulates a narrower use of character sets, where G0 +is fixed (always ASCII), so that G1, G2, and G3 +can be invoked only for codes with the high order bit set. +In particular, \fB\[ha]N\fP and \fB\[ha]O\fP are not used anymore, ESC ( xx +can be used only with xx=B, and ESC ) xx, ESC * xx, ESC + xx +are equivalent to ESC \- xx, ESC . xx, ESC / xx, respectively. +.SS TIS-620 +TIS-620 is a Thai national standard character set and a superset +of ASCII. +In the same fashion as the ISO/IEC\~8859 series, Thai characters are mapped into +0xa1\[en]0xfe. +.SS Unicode +Unicode (ISO/IEC 10646) is a standard which aims to unambiguously represent +every character in every human language. +Unicode's structure permits 20.1 bits to encode every character. +Since most computers don't include 20.1-bit integers, Unicode is +usually encoded as 32-bit integers internally and either a series of +16-bit integers (UTF-16) (needing two 16-bit integers only when +encoding certain rare characters) or a series of 8-bit bytes (UTF-8). +.P +Linux represents Unicode using the 8-bit Unicode Transformation Format +(UTF-8). +UTF-8 is a variable length encoding of Unicode. +It uses 1 +byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes +for 21 bits, 5 bytes for 26 bits, 6 bytes for 31 bits. +.P +Let 0,1,x stand for a zero, one, or arbitrary bit. +A byte 0xxxxxxx +stands for the Unicode 00000000 0xxxxxxx which codes the same symbol +as the ASCII 0xxxxxxx. +Thus, ASCII goes unchanged into UTF-8, and +people using only ASCII do not notice any change: not in code, and not +in file size. +.P +A byte 110xxxxx is the start of a 2-byte code, and 110xxxxx 10yyyyyy +is assembled into 00000xxx xxyyyyyy. +A byte 1110xxxx is the start +of a 3-byte code, and 1110xxxx 10yyyyyy 10zzzzzz is assembled +into xxxxyyyy yyzzzzzz. +(When UTF-8 is used to code the 31-bit ISO/IEC 10646 +then this progression continues up to 6-byte codes.) +.P +For most texts in ISO/IEC\~8859 character sets, this means that the +characters outside of ASCII are now coded with two bytes. +This tends +to expand ordinary text files by only one or two percent. +For Russian +or Greek texts, this expands ordinary text files by 100%, since text in +those languages is mostly outside of ASCII. +For Japanese users this means +that the 16-bit codes now in common use will take three bytes. +While there are algorithmic conversions from some character sets +(especially ISO/IEC\~8859-1) to Unicode, general conversion requires +carrying around conversion tables, which can be quite large for 16-bit +codes. +.P +Note that UTF-8 is self-synchronizing: +10xxxxxx is a tail, +any other byte is the head of a code. +Note that the only way ASCII bytes occur in a UTF-8 stream, +is as themselves. +In particular, +there are no embedded NULs (\[aq]\e0\[aq]) or \[aq]/\[aq]s +that form part of some larger code. +.P +Since ASCII, and, in particular, NUL and \[aq]/\[aq], are unchanged, the +kernel does not notice that UTF-8 is being used. +It does not care at +all what the bytes it is handling stand for. +.P +Rendering of Unicode data streams is typically handled through +"subfont" tables which map a subset of Unicode to glyphs. +Internally +the kernel uses Unicode to describe the subfont loaded in video RAM. +This means that in the Linux console in UTF-8 mode, one can use a character +set with 512 different symbols. +This is not enough for Japanese, Chinese, and +Korean, but it is enough for most other purposes. +.SH SEE ALSO +.BR iconv (1), +.BR ascii (7), +.BR iso_8859\-1 (7), +.BR unicode (7), +.BR utf\-8 (7) diff --git a/man/man7/complex.7 b/man/man7/complex.7 new file mode 100644 index 0000000..422adf4 --- /dev/null +++ b/man/man7/complex.7 @@ -0,0 +1,83 @@ +.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH complex 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +complex \- basics of complex mathematics +.SH LIBRARY +Math library +.RI ( libm ", " \-lm ) +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +Complex numbers are numbers of the form z = a+b*i, where a and b are +real numbers and i = sqrt(\-1), so that i*i = \-1. +.P +There are other ways to represent that number. +The pair (a,b) of real +numbers may be viewed as a point in the plane, given by X- and +Y-coordinates. +This same point may also be described by giving +the pair of real numbers (r,phi), where r is the distance to the origin O, +and phi the angle between the X-axis and the line Oz. +Now +z = r*exp(i*phi) = r*(cos(phi)+i*sin(phi)). +.P +The basic operations are defined on z = a+b*i and w = c+d*i as: +.TP +.B addition: z+w = (a+c) + (b+d)*i +.TP +.B multiplication: z*w = (a*c \- b*d) + (a*d + b*c)*i +.TP +.B division: z/w = ((a*c + b*d)/(c*c + d*d)) + ((b*c \- a*d)/(c*c + d*d))*i +.P +Nearly all math function have a complex counterpart but there are +some complex-only functions. +.SH EXAMPLES +Your C-compiler can work with complex numbers if it supports the C99 standard. +The imaginary unit is represented by I. +.P +.EX +/* check that exp(i * pi) == \-1 */ +#include /* for atan */ +#include +#include +\& +int +main(void) +{ + double pi = 4 * atan(1.0); + double complex z = cexp(I * pi); + printf("%f + %f * i\en", creal(z), cimag(z)); +} +.EE +.SH SEE ALSO +.BR cabs (3), +.BR cacos (3), +.BR cacosh (3), +.BR carg (3), +.BR casin (3), +.BR casinh (3), +.BR catan (3), +.BR catanh (3), +.BR ccos (3), +.BR ccosh (3), +.BR cerf (3), +.BR cexp (3), +.BR cexp2 (3), +.BR cimag (3), +.BR clog (3), +.BR clog10 (3), +.BR clog2 (3), +.BR conj (3), +.BR cpow (3), +.BR cproj (3), +.BR creal (3), +.BR csin (3), +.BR csinh (3), +.BR csqrt (3), +.BR ctan (3), +.BR ctanh (3) diff --git a/man/man7/cp1251.7 b/man/man7/cp1251.7 new file mode 100644 index 0000000..ed3636f --- /dev/null +++ b/man/man7/cp1251.7 @@ -0,0 +1,166 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH cp1251 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cp1251 \- CP\ 1251 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The Windows Code Pages include several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +CP\ 1251 encodes the +characters used in Cyrillic scripts. +.SS CP\ 1251 characters +The following table displays the characters in CP\ 1251 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +200 128 80 Ђ CYRILLIC CAPITAL LETTER DJE +201 129 81 Ѓ CYRILLIC CAPITAL LETTER GJE +202 130 82 ‚ SINGLE LOW-9 QUOTATION MARK +203 131 83 ѓ CYRILLIC SMALL LETTER GJE +204 132 84 „ DOUBLE LOW-9 QUOTATION MARK +205 133 85 … HORIZONTAL ELLIPSIS +206 134 86 † DAGGER +207 135 87 ‡ DOUBLE DAGGER +210 136 88 € EURO SIGN +211 137 89 ‰ PER MILLE SIGN +212 138 8A Љ CYRILLIC CAPITAL LETTER LJE +213 139 8B ‹ SINGLE LEFT-POINTING ANGLE QUOTATION MARK +214 140 8C Њ CYRILLIC CAPITAL LETTER NJE +215 141 8D Ќ CYRILLIC CAPITAL LETTER KJE +216 142 8E Ћ CYRILLIC CAPITAL LETTER TSHE +217 143 8F Џ CYRILLIC CAPITAL LETTER DZHE +220 144 90 ђ CYRILLIC SMALL LETTER DJE +221 145 91 ‘ LEFT SINGLE QUOTATION MARK +222 146 92 ’ RIGHT SINGLE QUOTATION MARK +223 147 93 “ LEFT DOUBLE QUOTATION MARK +224 148 94 ” RIGHT DOUBLE QUOTATION MARK +225 149 95 • BULLET +226 150 96 – EN DASH +227 151 97 — EM DASH +230 152 98 UNDEFINED +231 153 99 ™ TRADE MARK SIGN +232 154 9A љ CYRILLIC SMALL LETTER LJE +233 155 9B › SINGLE RIGHT-POINTING ANGLE QUOTATION MARK +234 156 9C њ CYRILLIC SMALL LETTER NJE +235 157 9D ќ CYRILLIC SMALL LETTER KJE +236 158 9E ћ CYRILLIC SMALL LETTER TSHE +237 159 9F џ CYRILLIC SMALL LETTER DZHE +240 160 A0   NO-BREAK SPACE +241 161 A1 Ў CYRILLIC CAPITAL LETTER SHORT U +242 162 A2 ў CYRILLIC SMALL LETTER SHORT U +243 163 A3 Ј CYRILLIC CAPITAL LETTER JE +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 Ґ CYRILLIC CAPITAL LETTER GHE WITH UPTURN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 Ё CYRILLIC CAPITAL LETTER IO +251 169 A9 © COPYRIGHT SIGN +252 170 AA Є CYRILLIC CAPITAL LETTER UKRAINIAN IE +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF Ї CYRILLIC CAPITAL LETTER YI +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 І T{ +CYRILLIC CAPITAL LETTER +.br +BYELORUSSIAN-UKRAINIAN I +T} +263 179 B3 і CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I +264 180 B4 ґ CYRILLIC SMALL LETTER GHE WITH UPTURN +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ё CYRILLIC SMALL LETTER IO +271 185 B9 № NUMERO SIGN +272 186 BA є CYRILLIC SMALL LETTER UKRAINIAN IE +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ј CYRILLIC SMALL LETTER JE +275 189 BD Ѕ CYRILLIC CAPITAL LETTER DZE +276 190 BE ѕ CYRILLIC SMALL LETTER DZE +277 191 BF ї CYRILLIC SMALL LETTER YI +300 192 C0 А CYRILLIC CAPITAL LETTER A +301 193 C1 Б CYRILLIC CAPITAL LETTER BE +302 194 C2 В CYRILLIC CAPITAL LETTER VE +303 195 C3 Г CYRILLIC CAPITAL LETTER GHE +304 196 C4 Д CYRILLIC CAPITAL LETTER DE +305 197 C5 Е CYRILLIC CAPITAL LETTER IE +306 198 C6 Ж CYRILLIC CAPITAL LETTER ZHE +307 199 C7 З CYRILLIC CAPITAL LETTER ZE +310 200 C8 И CYRILLIC CAPITAL LETTER I +311 201 C9 Й CYRILLIC CAPITAL LETTER SHORT I +312 202 CA К CYRILLIC CAPITAL LETTER KA +313 203 CB Л CYRILLIC CAPITAL LETTER EL +314 204 CC М CYRILLIC CAPITAL LETTER EM +315 205 CD Н CYRILLIC CAPITAL LETTER EN +316 206 CE О CYRILLIC CAPITAL LETTER O +317 207 CF П CYRILLIC CAPITAL LETTER PE +320 208 D0 Р CYRILLIC CAPITAL LETTER ER +321 209 D1 С CYRILLIC CAPITAL LETTER ES +322 210 D2 Т CYRILLIC CAPITAL LETTER TE +323 211 D3 У CYRILLIC CAPITAL LETTER U +324 212 D4 Ф CYRILLIC CAPITAL LETTER EF +325 213 D5 Х CYRILLIC CAPITAL LETTER HA +326 214 D6 Ц CYRILLIC CAPITAL LETTER TSE +327 215 D7 Ч CYRILLIC CAPITAL LETTER CHE +330 216 D8 Ш CYRILLIC CAPITAL LETTER SHA +331 217 D9 Щ CYRILLIC CAPITAL LETTER SHCHA +332 218 DA Ъ CYRILLIC CAPITAL LETTER HARD SIGN +333 219 DB Ы CYRILLIC CAPITAL LETTER YERU +334 220 DC Ь CYRILLIC CAPITAL LETTER SOFT SIGN +335 221 DD Э CYRILLIC CAPITAL LETTER E +336 222 DE Ю CYRILLIC CAPITAL LETTER YU +337 223 DF Я CYRILLIC CAPITAL LETTER YA +340 224 E0 а CYRILLIC SMALL LETTER A +341 225 E1 б CYRILLIC SMALL LETTER BE +342 226 E2 в CYRILLIC SMALL LETTER VE +343 227 E3 г CYRILLIC SMALL LETTER GHE +344 228 E4 д CYRILLIC SMALL LETTER DE +345 229 E5 е CYRILLIC SMALL LETTER IE +346 230 E6 ж CYRILLIC SMALL LETTER ZHE +347 231 E7 з CYRILLIC SMALL LETTER ZE +350 232 E8 и CYRILLIC SMALL LETTER I +351 233 E9 й CYRILLIC SMALL LETTER SHORT I +352 234 EA к CYRILLIC SMALL LETTER KA +353 235 EB л CYRILLIC SMALL LETTER EL +354 236 EC м CYRILLIC SMALL LETTER EM +355 237 ED н CYRILLIC SMALL LETTER EN +356 238 EE о CYRILLIC SMALL LETTER O +357 239 EF п CYRILLIC SMALL LETTER PE +360 240 F0 р CYRILLIC SMALL LETTER ER +361 241 F1 с CYRILLIC SMALL LETTER ES +362 242 F2 т CYRILLIC SMALL LETTER TE +363 243 F3 у CYRILLIC SMALL LETTER U +364 244 F4 ф CYRILLIC SMALL LETTER EF +365 245 F5 х CYRILLIC SMALL LETTER HA +366 246 F6 ц CYRILLIC SMALL LETTER TSE +367 247 F7 ч CYRILLIC SMALL LETTER CHE +370 248 F8 ш CYRILLIC SMALL LETTER SHA +371 249 F9 щ CYRILLIC SMALL LETTER SHCHA +372 250 FA ъ CYRILLIC SMALL LETTER HARD SIGN +373 251 FB ы CYRILLIC SMALL LETTER YERU +374 252 FC ь CYRILLIC SMALL LETTER SOFT SIGN +375 253 FD э CYRILLIC SMALL LETTER E +376 254 FE ю CYRILLIC SMALL LETTER YU +377 255 FF я CYRILLIC SMALL LETTER YA +.TE +.SH NOTES +CP\ 1251 is also known as Windows Cyrillic. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1252 (7), +.BR iso_8859\-5 (7), +.BR koi8\-r (7), +.BR koi8\-u (7), +.BR utf\-8 (7) diff --git a/man/man7/cp1252.7 b/man/man7/cp1252.7 new file mode 100644 index 0000000..6e76af9 --- /dev/null +++ b/man/man7/cp1252.7 @@ -0,0 +1,156 @@ +'\" t +.\" Copyright 2014 (C) Marko Myllynen +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH cp1252 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cp1252 \- CP\ 1252 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The Windows Code Pages include several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +CP\ 1252 encodes the +characters used in many West European languages. +.SS CP\ 1252 characters +The following table displays the characters in CP\ 1252 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +200 128 80 € EURO SIGN +202 130 82 ‚ SINGLE LOW-9 QUOTATION MARK +203 131 83 ƒ LATIN SMALL LETTER F WITH HOOK +204 132 84 „ DOUBLE LOW-9 QUOTATION MARK +205 133 85 … HORIZONTAL ELLIPSIS +206 134 86 † DAGGER +207 135 87 ‡ DOUBLE DAGGER +210 136 88 ˆ MODIFIER LETTER CIRCUMFLEX ACCENT +211 137 89 ‰ PER MILLE SIGN +212 138 8A Š LATIN CAPITAL LETTER S WITH CARON +213 139 8B ‹ SINGLE LEFT-POINTING ANGLE QUOTATION MARK +214 140 8C Œ LATIN CAPITAL LIGATURE OE +216 142 8E Ž LATIN CAPITAL LETTER Z WITH CARON +221 145 91 ‘ LEFT SINGLE QUOTATION MARK +222 146 92 ’ RIGHT SINGLE QUOTATION MARK +223 147 93 “ LEFT DOUBLE QUOTATION MARK +224 148 94 ” RIGHT DOUBLE QUOTATION MARK +225 149 95 • BULLET +226 150 96 – EN DASH +227 151 97 — EM DASH +230 152 98 ˜ SMALL TILDE +231 153 99 ™ TRADE MARK SIGN +232 154 9A š LATIN SMALL LETTER S WITH CARON +233 155 9B › SINGLE RIGHT-POINTING ANGLE QUOTATION MARK +234 156 9C œ LATIN SMALL LIGATURE OE +236 158 9E ž LATIN SMALL LETTER Z WITH CARON +237 159 9F Ÿ LATIN CAPITAL LETTER Y WITH DIAERESIS +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER ETH +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER THORN +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER ETH +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER THORN +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +CP\ 1252 is also known as Windows-1252. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1251 (7), +.BR iso_8859\-1 (7), +.BR iso_8859\-15 (7), +.BR utf\-8 (7) diff --git a/man/man7/cpuset.7 b/man/man7/cpuset.7 new file mode 100644 index 0000000..52fec48 --- /dev/null +++ b/man/man7/cpuset.7 @@ -0,0 +1,1504 @@ +.\" Copyright (c) 2008 Silicon Graphics, Inc. +.\" +.\" Author: Paul Jackson (http://oss.sgi.com/projects/cpusets) +.\" +.\" SPDX-License-Identifier: GPL-2.0-only +.\" +.TH cpuset 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +cpuset \- confine processes to processor and memory node subsets +.SH DESCRIPTION +The cpuset filesystem is a pseudo-filesystem interface +to the kernel cpuset mechanism, +which is used to control the processor placement +and memory placement of processes. +It is commonly mounted at +.IR /dev/cpuset . +.P +On systems with kernels compiled with built in support for cpusets, +all processes are attached to a cpuset, and cpusets are always present. +If a system supports cpusets, then it will have the entry +.B nodev cpuset +in the file +.IR /proc/filesystems . +By mounting the cpuset filesystem (see the +.B EXAMPLES +section below), +the administrator can configure the cpusets on a system +to control the processor and memory placement of processes +on that system. +By default, if the cpuset configuration +on a system is not modified or if the cpuset filesystem +is not even mounted, then the cpuset mechanism, +though present, has no effect on the system's behavior. +.P +A cpuset defines a list of CPUs and memory nodes. +.P +The CPUs of a system include all the logical processing +units on which a process can execute, including, if present, +multiple processor cores within a package and Hyper-Threads +within a processor core. +Memory nodes include all distinct +banks of main memory; small and SMP systems typically have +just one memory node that contains all the system's main memory, +while NUMA (non-uniform memory access) systems have multiple memory nodes. +.P +Cpusets are represented as directories in a hierarchical +pseudo-filesystem, where the top directory in the hierarchy +.RI ( /dev/cpuset ) +represents the entire system (all online CPUs and memory nodes) +and any cpuset that is the child (descendant) of +another parent cpuset contains a subset of that parent's +CPUs and memory nodes. +The directories and files representing cpusets have normal +filesystem permissions. +.P +Every process in the system belongs to exactly one cpuset. +A process is confined to run only on the CPUs in +the cpuset it belongs to, and to allocate memory only +on the memory nodes in that cpuset. +When a process +.BR fork (2)s, +the child process is placed in the same cpuset as its parent. +With sufficient privilege, a process may be moved from one +cpuset to another and the allowed CPUs and memory nodes +of an existing cpuset may be changed. +.P +When the system begins booting, a single cpuset is +defined that includes all CPUs and memory nodes on the +system, and all processes are in that cpuset. +During the boot process, or later during normal system operation, +other cpusets may be created, as subdirectories of this top cpuset, +under the control of the system administrator, +and processes may be placed in these other cpusets. +.P +Cpusets are integrated with the +.BR sched_setaffinity (2) +scheduling affinity mechanism and the +.BR mbind (2) +and +.BR set_mempolicy (2) +memory-placement mechanisms in the kernel. +Neither of these mechanisms let a process make use +of a CPU or memory node that is not allowed by that process's cpuset. +If changes to a process's cpuset placement conflict with these +other mechanisms, then cpuset placement is enforced +even if it means overriding these other mechanisms. +The kernel accomplishes this overriding by silently +restricting the CPUs and memory nodes requested by +these other mechanisms to those allowed by the +invoking process's cpuset. +This can result in these +other calls returning an error, if for example, such +a call ends up requesting an empty set of CPUs or +memory nodes, after that request is restricted to +the invoking process's cpuset. +.P +Typically, a cpuset is used to manage +the CPU and memory-node confinement for a set of +cooperating processes such as a batch scheduler job, and these +other mechanisms are used to manage the placement of +individual processes or memory regions within that set or job. +.SH FILES +Each directory below +.I /dev/cpuset +represents a cpuset and contains a fixed set of pseudo-files +describing the state of that cpuset. +.P +New cpusets are created using the +.BR mkdir (2) +system call or the +.BR mkdir (1) +command. +The properties of a cpuset, such as its flags, allowed +CPUs and memory nodes, and attached processes, are queried and modified +by reading or writing to the appropriate file in that cpuset's directory, +as listed below. +.P +The pseudo-files in each cpuset directory are automatically created when +the cpuset is created, as a result of the +.BR mkdir (2) +invocation. +It is not possible to directly add or remove these pseudo-files. +.P +A cpuset directory that contains no child cpuset directories, +and has no attached processes, can be removed using +.BR rmdir (2) +or +.BR rmdir (1). +It is not necessary, or possible, +to remove the pseudo-files inside the directory before removing it. +.P +The pseudo-files in each cpuset directory are +small text files that may be read and +written using traditional shell utilities such as +.BR cat (1), +and +.BR echo (1), +or from a program by using file I/O library functions or system calls, +such as +.BR open (2), +.BR read (2), +.BR write (2), +and +.BR close (2). +.P +The pseudo-files in a cpuset directory represent internal kernel +state and do not have any persistent image on disk. +Each of these per-cpuset files is listed and described below. +.\" ====================== tasks ====================== +.TP +.I tasks +List of the process IDs (PIDs) of the processes in that cpuset. +The list is formatted as a series of ASCII +decimal numbers, each followed by a newline. +A process may be added to a cpuset (automatically removing +it from the cpuset that previously contained it) by writing its +PID to that cpuset's +.I tasks +file (with or without a trailing newline). +.IP +.B Warning: +only one PID may be written to the +.I tasks +file at a time. +If a string is written that contains more +than one PID, only the first one will be used. +.\" =================== notify_on_release =================== +.TP +.I notify_on_release +Flag (0 or 1). +If set (1), that cpuset will receive special handling +after it is released, that is, after all processes cease using +it (i.e., terminate or are moved to a different cpuset) +and all child cpuset directories have been removed. +See the \fBNotify On Release\fR section, below. +.\" ====================== cpus ====================== +.TP +.I cpuset.cpus +List of the physical numbers of the CPUs on which processes +in that cpuset are allowed to execute. +See \fBList Format\fR below for a description of the +format of +.IR cpus . +.IP +The CPUs allowed to a cpuset may be changed by +writing a new list to its +.I cpus +file. +.\" ==================== cpu_exclusive ==================== +.TP +.I cpuset.cpu_exclusive +Flag (0 or 1). +If set (1), the cpuset has exclusive use of +its CPUs (no sibling or cousin cpuset may overlap CPUs). +By default, this is off (0). +Newly created cpusets also initially default this to off (0). +.IP +Two cpusets are +.I sibling +cpusets if they share the same parent cpuset in the +.I /dev/cpuset +hierarchy. +Two cpusets are +.I cousin +cpusets if neither is the ancestor of the other. +Regardless of the +.I cpu_exclusive +setting, if one cpuset is the ancestor of another, +and if both of these cpusets have nonempty +.IR cpus , +then their +.I cpus +must overlap, because the +.I cpus +of any cpuset are always a subset of the +.I cpus +of its parent cpuset. +.\" ====================== mems ====================== +.TP +.I cpuset.mems +List of memory nodes on which processes in this cpuset are +allowed to allocate memory. +See \fBList Format\fR below for a description of the +format of +.IR mems . +.\" ==================== mem_exclusive ==================== +.TP +.I cpuset.mem_exclusive +Flag (0 or 1). +If set (1), the cpuset has exclusive use of +its memory nodes (no sibling or cousin may overlap). +Also if set (1), the cpuset is a \fBHardwall\fR cpuset (see below). +By default, this is off (0). +Newly created cpusets also initially default this to off (0). +.IP +Regardless of the +.I mem_exclusive +setting, if one cpuset is the ancestor of another, +then their memory nodes must overlap, because the memory +nodes of any cpuset are always a subset of the memory nodes +of that cpuset's parent cpuset. +.\" ==================== mem_hardwall ==================== +.TP +.IR cpuset.mem_hardwall " (since Linux 2.6.26)" +Flag (0 or 1). +If set (1), the cpuset is a \fBHardwall\fR cpuset (see below). +Unlike \fBmem_exclusive\fR, +there is no constraint on whether cpusets +marked \fBmem_hardwall\fR may have overlapping +memory nodes with sibling or cousin cpusets. +By default, this is off (0). +Newly created cpusets also initially default this to off (0). +.\" ==================== memory_migrate ==================== +.TP +.IR cpuset.memory_migrate " (since Linux 2.6.16)" +Flag (0 or 1). +If set (1), then memory migration is enabled. +By default, this is off (0). +See the \fBMemory Migration\fR section, below. +.\" ==================== memory_pressure ==================== +.TP +.IR cpuset.memory_pressure " (since Linux 2.6.16)" +A measure of how much memory pressure the processes in this +cpuset are causing. +See the \fBMemory Pressure\fR section, below. +Unless +.I memory_pressure_enabled +is enabled, always has value zero (0). +This file is read-only. +See the +.B WARNINGS +section, below. +.\" ================= memory_pressure_enabled ================= +.TP +.IR cpuset.memory_pressure_enabled " (since Linux 2.6.16)" +Flag (0 or 1). +This file is present only in the root cpuset, normally +.IR /dev/cpuset . +If set (1), the +.I memory_pressure +calculations are enabled for all cpusets in the system. +By default, this is off (0). +See the +\fBMemory Pressure\fR section, below. +.\" ================== memory_spread_page ================== +.TP +.IR cpuset.memory_spread_page " (since Linux 2.6.17)" +Flag (0 or 1). +If set (1), pages in the kernel page cache +(filesystem buffers) are uniformly spread across the cpuset. +By default, this is off (0) in the top cpuset, +and inherited from the parent cpuset in +newly created cpusets. +See the \fBMemory Spread\fR section, below. +.\" ================== memory_spread_slab ================== +.TP +.IR cpuset.memory_spread_slab " (since Linux 2.6.17)" +Flag (0 or 1). +If set (1), the kernel slab caches +for file I/O (directory and inode structures) are +uniformly spread across the cpuset. +By default, is off (0) in the top cpuset, +and inherited from the parent cpuset in +newly created cpusets. +See the \fBMemory Spread\fR section, below. +.\" ================== sched_load_balance ================== +.TP +.IR cpuset.sched_load_balance " (since Linux 2.6.24)" +Flag (0 or 1). +If set (1, the default) the kernel will +automatically load balance processes in that cpuset over +the allowed CPUs in that cpuset. +If cleared (0) the +kernel will avoid load balancing processes in this cpuset, +.I unless +some other cpuset with overlapping CPUs has its +.I sched_load_balance +flag set. +See \fBScheduler Load Balancing\fR, below, for further details. +.\" ================== sched_relax_domain_level ================== +.TP +.IR cpuset.sched_relax_domain_level " (since Linux 2.6.26)" +Integer, between \-1 and a small positive value. +The +.I sched_relax_domain_level +controls the width of the range of CPUs over which the kernel scheduler +performs immediate rebalancing of runnable tasks across CPUs. +If +.I sched_load_balance +is disabled, then the setting of +.I sched_relax_domain_level +does not matter, as no such load balancing is done. +If +.I sched_load_balance +is enabled, then the higher the value of the +.IR sched_relax_domain_level , +the wider +the range of CPUs over which immediate load balancing is attempted. +See \fBScheduler Relax Domain Level\fR, below, for further details. +.\" ================== proc cpuset ================== +.P +In addition to the above pseudo-files in each directory below +.IR /dev/cpuset , +each process has a pseudo-file, +.IR /proc/ pid /cpuset , +that displays the path of the process's cpuset directory +relative to the root of the cpuset filesystem. +.\" ================== proc status ================== +.P +Also the +.IR /proc/ pid /status +file for each process has four added lines, +displaying the process's +.I Cpus_allowed +(on which CPUs it may be scheduled) and +.I Mems_allowed +(on which memory nodes it may obtain memory), +in the two formats \fBMask Format\fR and \fBList Format\fR (see below) +as shown in the following example: +.P +.in +4n +.EX +Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff +Cpus_allowed_list: 0\-127 +Mems_allowed: ffffffff,ffffffff +Mems_allowed_list: 0\-63 +.EE +.in +.P +The "allowed" fields were added in Linux 2.6.24; +the "allowed_list" fields were added in Linux 2.6.26. +.\" ================== EXTENDED CAPABILITIES ================== +.SH EXTENDED CAPABILITIES +In addition to controlling which +.I cpus +and +.I mems +a process is allowed to use, cpusets provide the following +extended capabilities. +.\" ================== Exclusive Cpusets ================== +.SS Exclusive cpusets +If a cpuset is marked +.I cpu_exclusive +or +.IR mem_exclusive , +no other cpuset, other than a direct ancestor or descendant, +may share any of the same CPUs or memory nodes. +.P +A cpuset that is +.I mem_exclusive +restricts kernel allocations for +buffer cache pages and other internal kernel data pages +commonly shared by the kernel across +multiple users. +All cpusets, whether +.I mem_exclusive +or not, restrict allocations of memory for user space. +This enables configuring a +system so that several independent jobs can share common kernel data, +while isolating each job's user allocation in +its own cpuset. +To do this, construct a large +.I mem_exclusive +cpuset to hold all the jobs, and construct child, +.RI non- mem_exclusive +cpusets for each individual job. +Only a small amount of kernel memory, +such as requests from interrupt handlers, is allowed to be +placed on memory nodes +outside even a +.I mem_exclusive +cpuset. +.\" ================== Hardwall ================== +.SS Hardwall +A cpuset that has +.I mem_exclusive +or +.I mem_hardwall +set is a +.I hardwall +cpuset. +A +.I hardwall +cpuset restricts kernel allocations for page, buffer, +and other data commonly shared by the kernel across multiple users. +All cpusets, whether +.I hardwall +or not, restrict allocations of memory for user space. +.P +This enables configuring a system so that several independent +jobs can share common kernel data, such as filesystem pages, +while isolating each job's user allocation in its own cpuset. +To do this, construct a large +.I hardwall +cpuset to hold +all the jobs, and construct child cpusets for each individual +job which are not +.I hardwall +cpusets. +.P +Only a small amount of kernel memory, such as requests from +interrupt handlers, is allowed to be taken outside even a +.I hardwall +cpuset. +.\" ================== Notify On Release ================== +.SS Notify on release +If the +.I notify_on_release +flag is enabled (1) in a cpuset, +then whenever the last process in the cpuset leaves +(exits or attaches to some other cpuset) +and the last child cpuset of that cpuset is removed, +the kernel will run the command +.IR /sbin/cpuset_release_agent , +supplying the pathname (relative to the mount point of the +cpuset filesystem) of the abandoned cpuset. +This enables automatic removal of abandoned cpusets. +.P +The default value of +.I notify_on_release +in the root cpuset at system boot is disabled (0). +The default value of other cpusets at creation +is the current value of their parent's +.I notify_on_release +setting. +.P +The command +.I /sbin/cpuset_release_agent +is invoked, with the name +.RI ( /dev/cpuset +relative path) +of the to-be-released cpuset in +.IR argv[1] . +.P +The usual contents of the command +.I /sbin/cpuset_release_agent +is simply the shell script: +.P +.in +4n +.EX +#!/bin/sh +rmdir /dev/cpuset/$1 +.EE +.in +.P +As with other flag values below, this flag can +be changed by writing an ASCII +number 0 or 1 (with optional trailing newline) +into the file, to clear or set the flag, respectively. +.\" ================== Memory Pressure ================== +.SS Memory pressure +The +.I memory_pressure +of a cpuset provides a simple per-cpuset running average of +the rate that the processes in a cpuset are attempting to free up in-use +memory on the nodes of the cpuset to satisfy additional memory requests. +.P +This enables batch managers that are monitoring jobs running in dedicated +cpusets to efficiently detect what level of memory pressure that job +is causing. +.P +This is useful both on tightly managed systems running a wide mix of +submitted jobs, which may choose to terminate or reprioritize jobs that +are trying to use more memory than allowed on the nodes assigned them, +and with tightly coupled, long-running, massively parallel scientific +computing jobs that will dramatically fail to meet required performance +goals if they start to use more memory than allowed to them. +.P +This mechanism provides a very economical way for the batch manager +to monitor a cpuset for signs of memory pressure. +It's up to the batch manager or other user code to decide +what action to take if it detects signs of memory pressure. +.P +Unless memory pressure calculation is enabled by setting the pseudo-file +.IR /dev/cpuset/cpuset.memory_pressure_enabled , +it is not computed for any cpuset, and reads from any +.I memory_pressure +always return zero, as represented by the ASCII string "0\en". +See the \fBWARNINGS\fR section, below. +.P +A per-cpuset, running average is employed for the following reasons: +.IP \[bu] 3 +Because this meter is per-cpuset rather than per-process or per virtual +memory region, the system load imposed by a batch scheduler monitoring +this metric is sharply reduced on large systems, because a scan of +the tasklist can be avoided on each set of queries. +.IP \[bu] +Because this meter is a running average rather than an accumulating +counter, a batch scheduler can detect memory pressure with a +single read, instead of having to read and accumulate results +for a period of time. +.IP \[bu] +Because this meter is per-cpuset rather than per-process, +the batch scheduler can obtain the key information\[em]memory +pressure in a cpuset\[em]with a single read, rather than having to +query and accumulate results over all the (dynamically changing) +set of processes in the cpuset. +.P +The +.I memory_pressure +of a cpuset is calculated using a per-cpuset simple digital filter +that is kept within the kernel. +For each cpuset, this filter tracks +the recent rate at which processes attached to that cpuset enter the +kernel direct reclaim code. +.P +The kernel direct reclaim code is entered whenever a process has to +satisfy a memory page request by first finding some other page to +repurpose, due to lack of any readily available already free pages. +Dirty filesystem pages are repurposed by first writing them +to disk. +Unmodified filesystem buffer pages are repurposed +by simply dropping them, though if that page is needed again, it +will have to be reread from disk. +.P +The +.I cpuset.memory_pressure +file provides an integer number representing the recent (half-life of +10 seconds) rate of entries to the direct reclaim code caused by any +process in the cpuset, in units of reclaims attempted per second, +times 1000. +.\" ================== Memory Spread ================== +.SS Memory spread +There are two Boolean flag files per cpuset that control where the +kernel allocates pages for the filesystem buffers and related +in-kernel data structures. +They are called +.I cpuset.memory_spread_page +and +.IR cpuset.memory_spread_slab . +.P +If the per-cpuset Boolean flag file +.I cpuset.memory_spread_page +is set, then +the kernel will spread the filesystem buffers (page cache) evenly +over all the nodes that the faulting process is allowed to use, instead +of preferring to put those pages on the node where the process is running. +.P +If the per-cpuset Boolean flag file +.I cpuset.memory_spread_slab +is set, +then the kernel will spread some filesystem-related slab caches, +such as those for inodes and directory entries, evenly over all the nodes +that the faulting process is allowed to use, instead of preferring to +put those pages on the node where the process is running. +.P +The setting of these flags does not affect the data segment +(see +.BR brk (2)) +or stack segment pages of a process. +.P +By default, both kinds of memory spreading are off and the kernel +prefers to allocate memory pages on the node local to where the +requesting process is running. +If that node is not allowed by the +process's NUMA memory policy or cpuset configuration or if there are +insufficient free memory pages on that node, then the kernel looks +for the nearest node that is allowed and has sufficient free memory. +.P +When new cpusets are created, they inherit the memory spread settings +of their parent. +.P +Setting memory spreading causes allocations for the affected page or +slab caches to ignore the process's NUMA memory policy and be spread +instead. +However, the effect of these changes in memory placement +caused by cpuset-specified memory spreading is hidden from the +.BR mbind (2) +or +.BR set_mempolicy (2) +calls. +These two NUMA memory policy calls always appear to behave as if +no cpuset-specified memory spreading is in effect, even if it is. +If cpuset memory spreading is subsequently turned off, the NUMA +memory policy most recently specified by these calls is automatically +reapplied. +.P +Both +.I cpuset.memory_spread_page +and +.I cpuset.memory_spread_slab +are Boolean flag files. +By default, they contain "0", meaning that the feature is off +for that cpuset. +If a "1" is written to that file, that turns the named feature on. +.P +Cpuset-specified memory spreading behaves similarly to what is known +(in other contexts) as round-robin or interleave memory placement. +.P +Cpuset-specified memory spreading can provide substantial performance +improvements for jobs that: +.IP \[bu] 3 +need to place thread-local data on +memory nodes close to the CPUs which are running the threads that most +frequently access that data; but also +.IP \[bu] +need to access large filesystem data sets that must to be spread +across the several nodes in the job's cpuset in order to fit. +.P +Without this policy, +the memory allocation across the nodes in the job's cpuset +can become very uneven, +especially for jobs that might have just a single +thread initializing or reading in the data set. +.\" ================== Memory Migration ================== +.SS Memory migration +Normally, under the default setting (disabled) of +.IR cpuset.memory_migrate , +once a page is allocated (given a physical page +of main memory), then that page stays on whatever node it +was allocated, so long as it remains allocated, even if the +cpuset's memory-placement policy +.I mems +subsequently changes. +.P +When memory migration is enabled in a cpuset, if the +.I mems +setting of the cpuset is changed, then any memory page in use by any +process in the cpuset that is on a memory node that is no longer +allowed will be migrated to a memory node that is allowed. +.P +Furthermore, if a process is moved into a cpuset with +.I memory_migrate +enabled, any memory pages it uses that were on memory nodes allowed +in its previous cpuset, but which are not allowed in its new cpuset, +will be migrated to a memory node allowed in the new cpuset. +.P +The relative placement of a migrated page within +the cpuset is preserved during these migration operations if possible. +For example, +if the page was on the second valid node of the prior cpuset, +then the page will be placed on the second valid node of the new cpuset, +if possible. +.\" ================== Scheduler Load Balancing ================== +.SS Scheduler load balancing +The kernel scheduler automatically load balances processes. +If one CPU is underutilized, +the kernel will look for processes on other more +overloaded CPUs and move those processes to the underutilized CPU, +within the constraints of such placement mechanisms as cpusets and +.BR sched_setaffinity (2). +.P +The algorithmic cost of load balancing and its impact on key shared +kernel data structures such as the process list increases more than +linearly with the number of CPUs being balanced. +For example, it +costs more to load balance across one large set of CPUs than it does +to balance across two smaller sets of CPUs, each of half the size +of the larger set. +(The precise relationship between the number of CPUs being balanced +and the cost of load balancing depends +on implementation details of the kernel process scheduler, which is +subject to change over time, as improved kernel scheduler algorithms +are implemented.) +.P +The per-cpuset flag +.I sched_load_balance +provides a mechanism to suppress this automatic scheduler load +balancing in cases where it is not needed and suppressing it would have +worthwhile performance benefits. +.P +By default, load balancing is done across all CPUs, except those +marked isolated using the kernel boot time "isolcpus=" argument. +(See \fBScheduler Relax Domain Level\fR, below, to change this default.) +.P +This default load balancing across all CPUs is not well suited to +the following two situations: +.IP \[bu] 3 +On large systems, load balancing across many CPUs is expensive. +If the system is managed using cpusets to place independent jobs +on separate sets of CPUs, full load balancing is unnecessary. +.IP \[bu] +Systems supporting real-time on some CPUs need to minimize +system overhead on those CPUs, including avoiding process load +balancing if that is not needed. +.P +When the per-cpuset flag +.I sched_load_balance +is enabled (the default setting), +it requests load balancing across +all the CPUs in that cpuset's allowed CPUs, +ensuring that load balancing can move a process (not otherwise pinned, +as by +.BR sched_setaffinity (2)) +from any CPU in that cpuset to any other. +.P +When the per-cpuset flag +.I sched_load_balance +is disabled, then the +scheduler will avoid load balancing across the CPUs in that cpuset, +\fIexcept\fR in so far as is necessary because some overlapping cpuset +has +.I sched_load_balance +enabled. +.P +So, for example, if the top cpuset has the flag +.I sched_load_balance +enabled, then the scheduler will load balance across all +CPUs, and the setting of the +.I sched_load_balance +flag in other cpusets has no effect, +as we're already fully load balancing. +.P +Therefore in the above two situations, the flag +.I sched_load_balance +should be disabled in the top cpuset, and only some of the smaller, +child cpusets would have this flag enabled. +.P +When doing this, you don't usually want to leave any unpinned processes in +the top cpuset that might use nontrivial amounts of CPU, as such processes +may be artificially constrained to some subset of CPUs, depending on +the particulars of this flag setting in descendant cpusets. +Even if such a process could use spare CPU cycles in some other CPUs, +the kernel scheduler might not consider the possibility of +load balancing that process to the underused CPU. +.P +Of course, processes pinned to a particular CPU can be left in a cpuset +that disables +.I sched_load_balance +as those processes aren't going anywhere else anyway. +.\" ================== Scheduler Relax Domain Level ================== +.SS Scheduler relax domain level +The kernel scheduler performs immediate load balancing whenever +a CPU becomes free or another task becomes runnable. +This load +balancing works to ensure that as many CPUs as possible are usefully +employed running tasks. +The kernel also performs periodic load +balancing off the software clock described in +.BR time (7). +The setting of +.I sched_relax_domain_level +applies only to immediate load balancing. +Regardless of the +.I sched_relax_domain_level +setting, periodic load balancing is attempted over all CPUs +(unless disabled by turning off +.IR sched_load_balance .) +In any case, of course, tasks will be scheduled to run only on +CPUs allowed by their cpuset, as modified by +.BR sched_setaffinity (2) +system calls. +.P +On small systems, such as those with just a few CPUs, immediate load +balancing is useful to improve system interactivity and to minimize +wasteful idle CPU cycles. +But on large systems, attempting immediate +load balancing across a large number of CPUs can be more costly than +it is worth, depending on the particular performance characteristics +of the job mix and the hardware. +.P +The exact meaning of the small integer values of +.I sched_relax_domain_level +will depend on internal +implementation details of the kernel scheduler code and on the +non-uniform architecture of the hardware. +Both of these will evolve +over time and vary by system architecture and kernel version. +.P +As of this writing, when this capability was introduced in Linux +2.6.26, on certain popular architectures, the positive values of +.I sched_relax_domain_level +have the following meanings. +.P +.PD 0 +.TP +.B 1 +Perform immediate load balancing across Hyper-Thread +siblings on the same core. +.TP +.B 2 +Perform immediate load balancing across other cores in the same package. +.TP +.B 3 +Perform immediate load balancing across other CPUs +on the same node or blade. +.TP +.B 4 +Perform immediate load balancing across over several +(implementation detail) nodes [On NUMA systems]. +.TP +.B 5 +Perform immediate load balancing across over all CPUs +in system [On NUMA systems]. +.PD +.P +The +.I sched_relax_domain_level +value of zero (0) always means +don't perform immediate load balancing, +hence that load balancing is done only periodically, +not immediately when a CPU becomes available or another task becomes +runnable. +.P +The +.I sched_relax_domain_level +value of minus one (\-1) +always means use the system default value. +The system default value can vary by architecture and kernel version. +This system default value can be changed by kernel +boot-time "relax_domain_level=" argument. +.P +In the case of multiple overlapping cpusets which have conflicting +.I sched_relax_domain_level +values, then the highest such value +applies to all CPUs in any of the overlapping cpusets. +In such cases, +.B \-1 +is the lowest value, +overridden by any other value, +and +.B 0 +is the next lowest value. +.SH FORMATS +The following formats are used to represent sets of +CPUs and memory nodes. +.\" ================== Mask Format ================== +.SS Mask format +The \fBMask Format\fR is used to represent CPU and memory-node bit masks +in the +.IR /proc/ pid /status +file. +.P +This format displays each 32-bit +word in hexadecimal (using ASCII characters "0" - "9" and "a" - "f"); +words are filled with leading zeros, if required. +For masks longer than one word, a comma separator is used between words. +Words are displayed in big-endian +order, which has the most significant bit first. +The hex digits within a word are also in big-endian order. +.P +The number of 32-bit words displayed is the minimum number needed to +display all bits of the bit mask, based on the size of the bit mask. +.P +Examples of the \fBMask Format\fR: +.P +.in +4n +.EX +00000001 # just bit 0 set +40000000,00000000,00000000 # just bit 94 set +00000001,00000000,00000000 # just bit 64 set +000000ff,00000000 # bits 32\-39 set +00000000,000e3862 # 1,5,6,11\-13,17\-19 set +.EE +.in +.P +A mask with bits 0, 1, 2, 4, 8, 16, 32, and 64 set displays as: +.P +.in +4n +.EX +00000001,00000001,00010117 +.EE +.in +.P +The first "1" is for bit 64, the +second for bit 32, the third for bit 16, the fourth for bit 8, the +fifth for bit 4, and the "7" is for bits 2, 1, and 0. +.\" ================== List Format ================== +.SS List format +The \fBList Format\fR for +.I cpus +and +.I mems +is a comma-separated list of CPU or memory-node +numbers and ranges of numbers, in ASCII decimal. +.P +Examples of the \fBList Format\fR: +.P +.in +4n +.EX +0\-4,9 # bits 0, 1, 2, 3, 4, and 9 set +0\-2,7,12\-14 # bits 0, 1, 2, 7, 12, 13, and 14 set +.EE +.in +.\" ================== RULES ================== +.SH RULES +The following rules apply to each cpuset: +.IP \[bu] 3 +Its CPUs and memory nodes must be a (possibly equal) +subset of its parent's. +.IP \[bu] +It can be marked +.I cpu_exclusive +only if its parent is. +.IP \[bu] +It can be marked +.I mem_exclusive +only if its parent is. +.IP \[bu] +If it is +.IR cpu_exclusive , +its CPUs may not overlap any sibling. +.IP \[bu] +If it is +.IR mem_exclusive , +its memory nodes may not overlap any sibling. +.\" ================== PERMISSIONS ================== +.SH PERMISSIONS +The permissions of a cpuset are determined by the permissions +of the directories and pseudo-files in the cpuset filesystem, +normally mounted at +.IR /dev/cpuset . +.P +For instance, a process can put itself in some other cpuset (than +its current one) if it can write the +.I tasks +file for that cpuset. +This requires execute permission on the encompassing directories +and write permission on the +.I tasks +file. +.P +An additional constraint is applied to requests to place some +other process in a cpuset. +One process may not attach another to +a cpuset unless it would have permission to send that process +a signal (see +.BR kill (2)). +.P +A process may create a child cpuset if it can access and write the +parent cpuset directory. +It can modify the CPUs or memory nodes +in a cpuset if it can access that cpuset's directory (execute +permissions on the each of the parent directories) and write the +corresponding +.I cpus +or +.I mems +file. +.P +There is one minor difference between the manner in which these +permissions are evaluated and the manner in which normal filesystem +operation permissions are evaluated. +The kernel interprets +relative pathnames starting at a process's current working directory. +Even if one is operating on a cpuset file, relative pathnames +are interpreted relative to the process's current working directory, +not relative to the process's current cpuset. +The only ways that +cpuset paths relative to a process's current cpuset can be used are +if either the process's current working directory is its cpuset +(it first did a +.B cd +or +.BR chdir (2) +to its cpuset directory beneath +.IR /dev/cpuset , +which is a bit unusual) +or if some user code converts the relative cpuset path to a +full filesystem path. +.P +In theory, this means that user code should specify cpusets +using absolute pathnames, which requires knowing the mount point of +the cpuset filesystem (usually, but not necessarily, +.IR /dev/cpuset ). +In practice, all user level code that this author is aware of +simply assumes that if the cpuset filesystem is mounted, then +it is mounted at +.IR /dev/cpuset . +Furthermore, it is common practice for carefully written +user code to verify the presence of the pseudo-file +.I /dev/cpuset/tasks +in order to verify that the cpuset pseudo-filesystem +is currently mounted. +.\" ================== WARNINGS ================== +.SH WARNINGS +.SS Enabling memory_pressure +By default, the per-cpuset file +.I cpuset.memory_pressure +always contains zero (0). +Unless this feature is enabled by writing "1" to the pseudo-file +.IR /dev/cpuset/cpuset.memory_pressure_enabled , +the kernel does +not compute per-cpuset +.IR memory_pressure . +.SS Using the echo command +When using the +.B echo +command at the shell prompt to change the values of cpuset files, +beware that the built-in +.B echo +command in some shells does not display an error message if the +.BR write (2) +system call fails. +.\" Gack! csh(1)'s echo does this +For example, if the command: +.P +.in +4n +.EX +echo 19 > cpuset.mems +.EE +.in +.P +failed because memory node 19 was not allowed (perhaps +the current system does not have a memory node 19), then the +.B echo +command might not display any error. +It is better to use the +.B /bin/echo +external command to change cpuset file settings, as this +command will display +.BR write (2) +errors, as in the example: +.P +.in +4n +.EX +/bin/echo 19 > cpuset.mems +/bin/echo: write error: Invalid argument +.EE +.in +.\" ================== EXCEPTIONS ================== +.SH EXCEPTIONS +.SS Memory placement +Not all allocations of system memory are constrained by cpusets, +for the following reasons. +.P +If hot-plug functionality is used to remove all the CPUs that are +currently assigned to a cpuset, then the kernel will automatically +update the +.I cpus_allowed +of all processes attached to CPUs in that cpuset +to allow all CPUs. +When memory hot-plug functionality for removing +memory nodes is available, a similar exception is expected to apply +there as well. +In general, the kernel prefers to violate cpuset placement, +rather than starving a process that has had all its allowed CPUs or +memory nodes taken offline. +User code should reconfigure cpusets to refer only to online CPUs +and memory nodes when using hot-plug to add or remove such resources. +.P +A few kernel-critical, internal memory-allocation requests, marked +GFP_ATOMIC, must be satisfied immediately. +The kernel may drop some +request or malfunction if one of these allocations fail. +If such a request cannot be satisfied within the current process's cpuset, +then we relax the cpuset, and look for memory anywhere we can find it. +It's better to violate the cpuset than stress the kernel. +.P +Allocations of memory requested by kernel drivers while processing +an interrupt lack any relevant process context, and are not confined +by cpusets. +.SS Renaming cpusets +You can use the +.BR rename (2) +system call to rename cpusets. +Only simple renaming is supported; that is, changing the name of a cpuset +directory is permitted, but moving a directory into +a different directory is not permitted. +.\" ================== ERRORS ================== +.SH ERRORS +The Linux kernel implementation of cpusets sets +.I errno +to specify the reason for a failed system call affecting cpusets. +.P +The possible +.I errno +settings and their meaning when set on +a failed cpuset call are as listed below. +.TP +.B E2BIG +Attempted a +.BR write (2) +on a special cpuset file +with a length larger than some kernel-determined upper +limit on the length of such writes. +.TP +.B EACCES +Attempted to +.BR write (2) +the process ID (PID) of a process to a cpuset +.I tasks +file when one lacks permission to move that process. +.TP +.B EACCES +Attempted to add, using +.BR write (2), +a CPU or memory node to a cpuset, when that CPU or memory node was +not already in its parent. +.TP +.B EACCES +Attempted to set, using +.BR write (2), +.I cpuset.cpu_exclusive +or +.I cpuset.mem_exclusive +on a cpuset whose parent lacks the same setting. +.TP +.B EACCES +Attempted to +.BR write (2) +a +.I cpuset.memory_pressure +file. +.TP +.B EACCES +Attempted to create a file in a cpuset directory. +.TP +.B EBUSY +Attempted to remove, using +.BR rmdir (2), +a cpuset with attached processes. +.TP +.B EBUSY +Attempted to remove, using +.BR rmdir (2), +a cpuset with child cpusets. +.TP +.B EBUSY +Attempted to remove +a CPU or memory node from a cpuset +that is also in a child of that cpuset. +.TP +.B EEXIST +Attempted to create, using +.BR mkdir (2), +a cpuset that already exists. +.TP +.B EEXIST +Attempted to +.BR rename (2) +a cpuset to a name that already exists. +.TP +.B EFAULT +Attempted to +.BR read (2) +or +.BR write (2) +a cpuset file using +a buffer that is outside the writing processes accessible address space. +.TP +.B EINVAL +Attempted to change a cpuset, using +.BR write (2), +in a way that would violate a +.I cpu_exclusive +or +.I mem_exclusive +attribute of that cpuset or any of its siblings. +.TP +.B EINVAL +Attempted to +.BR write (2) +an empty +.I cpuset.cpus +or +.I cpuset.mems +list to a cpuset which has attached processes or child cpusets. +.TP +.B EINVAL +Attempted to +.BR write (2) +a +.I cpuset.cpus +or +.I cpuset.mems +list which included a range with the second number smaller than +the first number. +.TP +.B EINVAL +Attempted to +.BR write (2) +a +.I cpuset.cpus +or +.I cpuset.mems +list which included an invalid character in the string. +.TP +.B EINVAL +Attempted to +.BR write (2) +a list to a +.I cpuset.cpus +file that did not include any online CPUs. +.TP +.B EINVAL +Attempted to +.BR write (2) +a list to a +.I cpuset.mems +file that did not include any online memory nodes. +.TP +.B EINVAL +Attempted to +.BR write (2) +a list to a +.I cpuset.mems +file that included a node that held no memory. +.TP +.B EIO +Attempted to +.BR write (2) +a string to a cpuset +.I tasks +file that +does not begin with an ASCII decimal integer. +.TP +.B EIO +Attempted to +.BR rename (2) +a cpuset into a different directory. +.TP +.B ENAMETOOLONG +Attempted to +.BR read (2) +a +.IR /proc/ pid /cpuset +file for a cpuset path that is longer than the kernel page size. +.TP +.B ENAMETOOLONG +Attempted to create, using +.BR mkdir (2), +a cpuset whose base directory name is longer than 255 characters. +.TP +.B ENAMETOOLONG +Attempted to create, using +.BR mkdir (2), +a cpuset whose full pathname, +including the mount point (typically "/dev/cpuset/") prefix, +is longer than 4095 characters. +.TP +.B ENODEV +The cpuset was removed by another process at the same time as a +.BR write (2) +was attempted on one of the pseudo-files in the cpuset directory. +.TP +.B ENOENT +Attempted to create, using +.BR mkdir (2), +a cpuset in a parent cpuset that doesn't exist. +.TP +.B ENOENT +Attempted to +.BR access (2) +or +.BR open (2) +a nonexistent file in a cpuset directory. +.TP +.B ENOMEM +Insufficient memory is available within the kernel; can occur +on a variety of system calls affecting cpusets, but only if the +system is extremely short of memory. +.TP +.B ENOSPC +Attempted to +.BR write (2) +the process ID (PID) +of a process to a cpuset +.I tasks +file when the cpuset had an empty +.I cpuset.cpus +or empty +.I cpuset.mems +setting. +.TP +.B ENOSPC +Attempted to +.BR write (2) +an empty +.I cpuset.cpus +or +.I cpuset.mems +setting to a cpuset that +has tasks attached. +.TP +.B ENOTDIR +Attempted to +.BR rename (2) +a nonexistent cpuset. +.TP +.B EPERM +Attempted to remove a file from a cpuset directory. +.TP +.B ERANGE +Specified a +.I cpuset.cpus +or +.I cpuset.mems +list to the kernel which included a number too large for the kernel +to set in its bit masks. +.TP +.B ESRCH +Attempted to +.BR write (2) +the process ID (PID) of a nonexistent process to a cpuset +.I tasks +file. +.\" ================== VERSIONS ================== +.SH VERSIONS +Cpusets appeared in Linux 2.6.12. +.\" ================== NOTES ================== +.SH NOTES +Despite its name, the +.I pid +parameter is actually a thread ID, +and each thread in a threaded group can be attached to a different +cpuset. +The value returned from a call to +.BR gettid (2) +can be passed in the argument +.IR pid . +.\" ================== BUGS ================== +.SH BUGS +.I cpuset.memory_pressure +cpuset files can be opened +for writing, creation, or truncation, but then the +.BR write (2) +fails with +.I errno +set to +.BR EACCES , +and the creation and truncation options on +.BR open (2) +have no effect. +.\" ================== EXAMPLES ================== +.SH EXAMPLES +The following examples demonstrate querying and setting cpuset +options using shell commands. +.SS Creating and attaching to a cpuset. +To create a new cpuset and attach the current command shell to it, +the steps are: +.P +.PD 0 +.IP (1) 5 +mkdir /dev/cpuset (if not already done) +.IP (2) +mount \-t cpuset none /dev/cpuset (if not already done) +.IP (3) +Create the new cpuset using +.BR mkdir (1). +.IP (4) +Assign CPUs and memory nodes to the new cpuset. +.IP (5) +Attach the shell to the new cpuset. +.PD +.P +For example, the following sequence of commands will set up a cpuset +named "Charlie", containing just CPUs 2 and 3, and memory node 1, +and then attach the current shell to that cpuset. +.P +.in +4n +.EX +.RB "$" " mkdir /dev/cpuset" +.RB "$" " mount \-t cpuset cpuset /dev/cpuset" +.RB "$" " cd /dev/cpuset" +.RB "$" " mkdir Charlie" +.RB "$" " cd Charlie" +.RB "$" " /bin/echo 2\-3 > cpuset.cpus" +.RB "$" " /bin/echo 1 > cpuset.mems" +.RB "$" " /bin/echo $$ > tasks" +# The current shell is now running in cpuset Charlie +# The next line should display \[aq]/Charlie\[aq] +.RB "$" " cat /proc/self/cpuset" +.EE +.in +.\" +.SS Migrating a job to different memory nodes. +To migrate a job (the set of processes attached to a cpuset) +to different CPUs and memory nodes in the system, including moving +the memory pages currently allocated to that job, +perform the following steps. +.P +.PD 0 +.IP (1) 5 +Let's say we want to move the job in cpuset +.I alpha +(CPUs 4\[en]7 and memory nodes 2\[en]3) to a new cpuset +.I beta +(CPUs 16\[en]19 and memory nodes 8\[en]9). +.IP (2) +First create the new cpuset +.IR beta . +.IP (3) +Then allow CPUs 16\[en]19 and memory nodes 8\[en]9 in +.IR beta . +.IP (4) +Then enable +.I memory_migration +in +.IR beta . +.IP (5) +Then move each process from +.I alpha +to +.IR beta . +.PD +.P +The following sequence of commands accomplishes this. +.P +.in +4n +.EX +.RB "$" " cd /dev/cpuset" +.RB "$" " mkdir beta" +.RB "$" " cd beta" +.RB "$" " /bin/echo 16\-19 > cpuset.cpus" +.RB "$" " /bin/echo 8\-9 > cpuset.mems" +.RB "$" " /bin/echo 1 > cpuset.memory_migrate" +.RB "$" " while read i; do /bin/echo $i; done < ../alpha/tasks > tasks" +.EE +.in +.P +The above should move any processes in +.I alpha +to +.IR beta , +and any memory held by these processes on memory nodes 2\[en]3 to memory +nodes 8\[en]9, respectively. +.P +Notice that the last step of the above sequence did not do: +.P +.in +4n +.EX +.RB "$" " cp ../alpha/tasks tasks" +.EE +.in +.P +The +.I while +loop, rather than the seemingly easier use of the +.BR cp (1) +command, was necessary because +only one process PID at a time may be written to the +.I tasks +file. +.P +The same effect (writing one PID at a time) as the +.I while +loop can be accomplished more efficiently, in fewer keystrokes and in +syntax that works on any shell, but alas more obscurely, by using the +.B \-u +(unbuffered) option of +.BR sed (1): +.P +.in +4n +.EX +.RB "$" " sed \-un p < ../alpha/tasks > tasks" +.EE +.in +.\" ================== SEE ALSO ================== +.SH SEE ALSO +.BR taskset (1), +.BR get_mempolicy (2), +.BR getcpu (2), +.BR mbind (2), +.BR sched_getaffinity (2), +.BR sched_setaffinity (2), +.BR sched_setscheduler (2), +.BR set_mempolicy (2), +.BR CPU_SET (3), +.BR proc (5), +.BR cgroups (7), +.BR numa (7), +.BR sched (7), +.BR migratepages (8), +.BR numactl (8) +.P +.I Documentation/admin\-guide/cgroup\-v1/cpusets.rst +in the Linux kernel source tree +.\" commit 45ce80fb6b6f9594d1396d44dd7e7c02d596fef8 +(or +.I Documentation/cgroup\-v1/cpusets.txt +before Linux 4.18, and +.I Documentation/cpusets.txt +before Linux 2.6.29) diff --git a/man/man7/credentials.7 b/man/man7/credentials.7 new file mode 100644 index 0000000..bdf2c67 --- /dev/null +++ b/man/man7/credentials.7 @@ -0,0 +1,384 @@ +.\" Copyright (c) 2007 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-06-13 Creation +.\" +.TH credentials 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +credentials \- process identifiers +.SH DESCRIPTION +.SS Process ID (PID) +Each process has a unique nonnegative integer identifier +that is assigned when the process is created using +.BR fork (2). +A process can obtain its PID using +.BR getpid (2). +A PID is represented using the type +.I pid_t +(defined in +.IR ). +.P +PIDs are used in a range of system calls to identify the process +affected by the call, for example: +.BR kill (2), +.BR ptrace (2), +.BR setpriority (2), +.\" .BR sched_rr_get_interval (2), +.\" .BR sched_getaffinity (2), +.\" .BR sched_setaffinity (2), +.\" .BR sched_getparam (2), +.\" .BR sched_setparam (2), +.\" .BR sched_setscheduler (2), +.\" .BR sched_getscheduler (2), +.BR setpgid (2), +.\" .BR getsid (2), +.BR setsid (2), +.BR sigqueue (3), +and +.BR waitpid (2). +.\" .BR waitid (2), +.\" .BR wait4 (2), +.P +A process's PID is preserved across an +.BR execve (2). +.SS Parent process ID (PPID) +A process's parent process ID identifies the process that created +this process using +.BR fork (2). +A process can obtain its PPID using +.BR getppid (2). +A PPID is represented using the type +.IR pid_t . +.P +A process's PPID is preserved across an +.BR execve (2). +.SS Process group ID and session ID +Each process has a session ID and a process group ID, +both represented using the type +.IR pid_t . +A process can obtain its session ID using +.BR getsid (2), +and its process group ID using +.BR getpgrp (2). +.P +A child created by +.BR fork (2) +inherits its parent's session ID and process group ID. +A process's session ID and process group ID are preserved across an +.BR execve (2). +.P +Sessions and process groups are abstractions devised to support shell +job control. +A process group (sometimes called a "job") is a collection of +processes that share the same process group ID; +the shell creates a new process group for the process(es) used +to execute single command or pipeline (e.g., the two processes +created to execute the command "ls\ |\ wc" are placed in the +same process group). +A process's group membership can be set using +.BR setpgid (2). +The process whose process ID is the same as its process group ID is the +\fIprocess group leader\fP for that group. +.P +A session is a collection of processes that share the same session ID. +All of the members of a process group also have the same session ID +(i.e., all of the members of a process group always belong to the +same session, so that sessions and process groups form a strict +two-level hierarchy of processes.) +A new session is created when a process calls +.BR setsid (2), +which creates a new session whose session ID is the same +as the PID of the process that called +.BR setsid (2). +The creator of the session is called the \fIsession leader\fP. +.P +All of the processes in a session share a +.IR "controlling terminal" . +The controlling terminal is established when the session leader +first opens a terminal (unless the +.B O_NOCTTY +flag is specified when calling +.BR open (2)). +A terminal may be the controlling terminal of at most one session. +.P +At most one of the jobs in a session may be the +.IR "foreground job" ; +other jobs in the session are +.IR "background jobs" . +Only the foreground job may read from the terminal; +when a process in the background attempts to read from the terminal, +its process group is sent a +.B SIGTTIN +signal, which suspends the job. +If the +.B TOSTOP +flag has been set for the terminal (see +.BR termios (3)), +then only the foreground job may write to the terminal; +writes from background jobs cause a +.B SIGTTOU +signal to be generated, which suspends the job. +When terminal keys that generate a signal (such as the +.I interrupt +key, normally control-C) +are pressed, the signal is sent to the processes in the foreground job. +.P +Various system calls and library functions +may operate on all members of a process group, +including +.BR kill (2), +.BR killpg (3), +.BR getpriority (2), +.BR setpriority (2), +.BR ioprio_get (2), +.BR ioprio_set (2), +.BR waitid (2), +and +.BR waitpid (2). +See also the discussion of the +.BR F_GETOWN , +.BR F_GETOWN_EX , +.BR F_SETOWN , +and +.B F_SETOWN_EX +operations in +.BR fcntl (2). +.SS User and group identifiers +Each process has various associated user and group IDs. +These IDs are integers, respectively represented using the types +.I uid_t +and +.I gid_t +(defined in +.IR ). +.P +On Linux, each process has the following user and group identifiers: +.IP \[bu] 3 +Real user ID and real group ID. +These IDs determine who owns the process. +A process can obtain its real user (group) ID using +.BR getuid (2) +.RB ( getgid (2)). +.IP \[bu] +Effective user ID and effective group ID. +These IDs are used by the kernel to determine the permissions +that the process will have when accessing shared resources such +as message queues, shared memory, and semaphores. +On most UNIX systems, these IDs also determine the +permissions when accessing files. +However, Linux uses the filesystem IDs described below +for this task. +A process can obtain its effective user (group) ID using +.BR geteuid (2) +.RB ( getegid (2)). +.IP \[bu] +Saved set-user-ID and saved set-group-ID. +These IDs are used in set-user-ID and set-group-ID programs to save +a copy of the corresponding effective IDs that were set when +the program was executed (see +.BR execve (2)). +A set-user-ID program can assume and drop privileges by +switching its effective user ID back and forth between the values +in its real user ID and saved set-user-ID. +This switching is done via calls to +.BR seteuid (2), +.BR setreuid (2), +or +.BR setresuid (2). +A set-group-ID program performs the analogous tasks using +.BR setegid (2), +.BR setregid (2), +or +.BR setresgid (2). +A process can obtain its saved set-user-ID (set-group-ID) using +.BR getresuid (2) +.RB ( getresgid (2)). +.IP \[bu] +Filesystem user ID and filesystem group ID (Linux-specific). +These IDs, in conjunction with the supplementary group IDs described +below, are used to determine permissions for accessing files; see +.BR path_resolution (7) +for details. +Whenever a process's effective user (group) ID is changed, +the kernel also automatically changes the filesystem user (group) ID +to the same value. +Consequently, the filesystem IDs normally have the same values +as the corresponding effective ID, and the semantics for file-permission +checks are thus the same on Linux as on other UNIX systems. +The filesystem IDs can be made to differ from the effective IDs +by calling +.BR setfsuid (2) +and +.BR setfsgid (2). +.IP \[bu] +Supplementary group IDs. +This is a set of additional group IDs that are used for permission +checks when accessing files and other shared resources. +Before Linux 2.6.4, +a process can be a member of up to 32 supplementary groups; +since Linux 2.6.4, +a process can be a member of up to 65536 supplementary groups. +The call +.I sysconf(_SC_NGROUPS_MAX) +can be used to determine the number of supplementary groups +of which a process may be a member. +.\" Since Linux 2.6.4, the limit is visible via the read-only file +.\" /proc/sys/kernel/ngroups_max. +.\" As at 2.6.22-rc2, this file is still read-only. +A process can obtain its set of supplementary group IDs using +.BR getgroups (2). +.P +A child process created by +.BR fork (2) +inherits copies of its parent's user and groups IDs. +During an +.BR execve (2), +a process's real user and group ID and supplementary +group IDs are preserved; +the effective and saved set IDs may be changed, as described in +.BR execve (2). +.P +Aside from the purposes noted above, +a process's user IDs are also employed in a number of other contexts: +.IP \[bu] 3 +when determining the permissions for sending signals (see +.BR kill (2)); +.IP \[bu] +when determining the permissions for setting +process-scheduling parameters (nice value, real time +scheduling policy and priority, CPU affinity, I/O priority) using +.BR setpriority (2), +.BR sched_setaffinity (2), +.BR sched_setscheduler (2), +.BR sched_setparam (2), +.BR sched_setattr (2), +and +.BR ioprio_set (2); +.IP \[bu] +when checking resource limits (see +.BR getrlimit (2)); +.IP \[bu] +when checking the limit on the number of inotify instances +that the process may create (see +.BR inotify (7)). +.\" +.SS Modifying process user and group IDs +Subject to rules described in the relevant manual pages, +a process can use the following APIs to modify its user and group IDs: +.TP +.BR setuid (2)\~(\c +.BR setgid (2)) +Modify the process's real (and possibly effective and saved-set) +user (group) IDs. +.TP +.BR seteuid (2)\~(\c +.BR setegid (2)) +Modify the process's effective user (group) ID. +.TP +.BR setfsuid (2)\~(\c +.BR setfsgid (2)) +Modify the process's filesystem user (group) ID. +.TP +.BR setreuid (2)\~(\c +.BR setregid (2)) +Modify the process's real and effective (and possibly saved-set) +user (group) IDs. +.TP +.BR setresuid (2)\~(\c +.BR setresgid (2)) +Modify the process's real, effective, and saved-set user (group) IDs. +.TP +.BR setgroups (2) +Modify the process's supplementary group list. +.P +Any changes to a process's effective user (group) ID +are automatically carried over to the process's +filesystem user (group) ID. +Changes to a process's effective user or group ID can also affect the +process "dumpable" attribute, as described in +.BR prctl (2). +.P +Changes to process user and group IDs can affect the capabilities +of the process, as described in +.BR capabilities (7). +.SH STANDARDS +Process IDs, parent process IDs, process group IDs, and session IDs +are specified in POSIX.1. +The real, effective, and saved set user and groups IDs, +and the supplementary group IDs, are specified in POSIX.1. +.P +The filesystem user and group IDs are a Linux extension. +.SH NOTES +Various fields in the +.IR /proc/ pid /status +file show the process credentials described above. +See +.BR proc (5) +for further information. +.P +The POSIX threads specification requires that +credentials are shared by all of the threads in a process. +However, at the kernel level, Linux maintains separate user and group +credentials for each thread. +The NPTL threading implementation does some work to ensure +that any change to user or group credentials +(e.g., calls to +.BR setuid (2), +.BR setresuid (2)) +is carried through to all of the POSIX threads in a process. +See +.BR nptl (7) +for further details. +.SH SEE ALSO +.BR bash (1), +.BR csh (1), +.BR groups (1), +.BR id (1), +.BR newgrp (1), +.BR ps (1), +.BR runuser (1), +.BR setpriv (1), +.BR sg (1), +.BR su (1), +.BR access (2), +.BR execve (2), +.BR faccessat (2), +.BR fork (2), +.BR getgroups (2), +.BR getpgrp (2), +.BR getpid (2), +.BR getppid (2), +.BR getsid (2), +.BR kill (2), +.BR setegid (2), +.BR seteuid (2), +.BR setfsgid (2), +.BR setfsuid (2), +.BR setgid (2), +.BR setgroups (2), +.BR setpgid (2), +.BR setresgid (2), +.BR setresuid (2), +.BR setsid (2), +.BR setuid (2), +.BR waitpid (2), +.BR euidaccess (3), +.BR initgroups (3), +.BR killpg (3), +.BR tcgetpgrp (3), +.BR tcgetsid (3), +.BR tcsetpgrp (3), +.BR group (5), +.BR passwd (5), +.BR shadow (5), +.BR capabilities (7), +.BR namespaces (7), +.BR path_resolution (7), +.BR pid_namespaces (7), +.BR pthreads (7), +.BR signal (7), +.BR system_data_types (7), +.BR unix (7), +.BR user_namespaces (7), +.BR sudo (8) diff --git a/man/man7/ddp.7 b/man/man7/ddp.7 new file mode 100644 index 0000000..bb9ce84 --- /dev/null +++ b/man/man7/ddp.7 @@ -0,0 +1,245 @@ +.\" This man page is Copyright (C) 1998 Alan Cox. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" $Id: ddp.7,v 1.3 1999/05/13 11:33:22 freitag Exp $ +.\" +.TH ddp 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ddp \- Linux AppleTalk protocol implementation +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.IB ddp_socket " = socket(AF_APPLETALK, SOCK_DGRAM, 0);" +.IB raw_socket " = socket(AF_APPLETALK, SOCK_RAW, " protocol ");" +.fi +.SH DESCRIPTION +Linux implements the AppleTalk protocols described in +.IR "Inside AppleTalk" . +Only the DDP layer and AARP are present in +the kernel. +They are designed to be used via the +.B netatalk +protocol +libraries. +This page documents the interface for those who wish or need to +use the DDP layer directly. +.P +The communication between AppleTalk and the user program works using a +BSD-compatible socket interface. +For more information on sockets, see +.BR socket (7). +.P +An AppleTalk socket is created by calling the +.BR socket (2) +function with a +.B AF_APPLETALK +socket family argument. +Valid socket types are +.B SOCK_DGRAM +to open a +.B ddp +socket or +.B SOCK_RAW +to open a +.B raw +socket. +.I protocol +is the AppleTalk protocol to be received or sent. +For +.B SOCK_RAW +you must specify +.BR ATPROTO_DDP . +.P +Raw sockets may be opened only by a process with effective user ID 0 +or when the process has the +.B CAP_NET_RAW +capability. +.SS Address format +An AppleTalk socket address is defined as a combination of a network number, +a node number, and a port number. +.P +.in +4n +.EX +struct at_addr { + unsigned short s_net; + unsigned char s_node; +}; +\& +struct sockaddr_atalk { + sa_family_t sat_family; /* address family */ + unsigned char sat_port; /* port */ + struct at_addr sat_addr; /* net/node */ +}; +.EE +.in +.P +.I sat_family +is always set to +.BR AF_APPLETALK . +.I sat_port +contains the port. +The port numbers below 129 are known as +.IR "reserved ports" . +Only processes with the effective user ID 0 or the +.B CAP_NET_BIND_SERVICE +capability may +.BR bind (2) +to these sockets. +.I sat_addr +is the host address. +The +.I net +member of +.I struct at_addr +contains the host network in network byte order. +The value of +.B AT_ANYNET +is a +wildcard and also implies \[lq]this network.\[rq] +The +.I node +member of +.I struct at_addr +contains the host node number. +The value of +.B AT_ANYNODE +is a +wildcard and also implies \[lq]this node.\[rq] The value of +.B ATADDR_BCAST +is a link +local broadcast address. +.\" FIXME . this doesn't make sense [johnl] +.SS Socket options +No protocol-specific socket options are supported. +.SS /proc interfaces +IP supports a set of +.I /proc +interfaces to configure some global AppleTalk parameters. +The parameters can be accessed by reading or writing files in the directory +.IR /proc/sys/net/atalk/ . +.TP +.I aarp\-expiry\-time +The time interval (in seconds) before an AARP cache entry expires. +.TP +.I aarp\-resolve\-time +The time interval (in seconds) before an AARP cache entry is resolved. +.TP +.I aarp\-retransmit\-limit +The number of retransmissions of an AARP query before the node is declared +dead. +.TP +.I aarp\-tick\-time +The timer rate (in seconds) for the timer driving AARP. +.P +The default values match the specification and should never need to be +changed. +.SS Ioctls +All ioctls described in +.BR socket (7) +apply to DDP. +.\" FIXME . Add a section about multicasting +.SH ERRORS +.TP +.B EACCES +The user tried to execute an operation without the necessary permissions. +These include sending to a broadcast address without +having the broadcast flag set, +and trying to bind to a reserved port without effective user ID 0 or +.BR CAP_NET_BIND_SERVICE . +.TP +.B EADDRINUSE +Tried to bind to an address already in use. +.TP +.B EADDRNOTAVAIL +A nonexistent interface was requested or the requested source address was +not local. +.TP +.B EAGAIN +Operation on a nonblocking socket would block. +.TP +.B EALREADY +A connection operation on a nonblocking socket is already in progress. +.TP +.B ECONNABORTED +A connection was closed during an +.BR accept (2). +.TP +.B EHOSTUNREACH +No routing table entry matches the destination address. +.TP +.B EINVAL +Invalid argument passed. +.TP +.B EISCONN +.BR connect (2) +was called on an already connected socket. +.TP +.B EMSGSIZE +Datagram is bigger than the DDP MTU. +.TP +.B ENODEV +Network device not available or not capable of sending IP. +.TP +.B ENOENT +.B SIOCGSTAMP +was called on a socket where no packet arrived. +.TP +.BR ENOMEM " and " ENOBUFS +Not enough memory available. +.TP +.B ENOPKG +A kernel subsystem was not configured. +.TP +.BR ENOPROTOOPT " and " EOPNOTSUPP +Invalid socket option passed. +.TP +.B ENOTCONN +The operation is defined only on a connected socket, but the socket wasn't +connected. +.TP +.B EPERM +User doesn't have permission to set high priority, +make a configuration change, +or send signals to the requested process or group. +.TP +.B EPIPE +The connection was unexpectedly closed or shut down by the other end. +.TP +.B ESOCKTNOSUPPORT +The socket was unconfigured, or an unknown socket type was requested. +.SH VERSIONS +AppleTalk is supported by Linux 2.0 or higher. +The +.I /proc +interfaces exist since Linux 2.2. +.SH NOTES +Be very careful with the +.B SO_BROADCAST +option; it is not privileged in Linux. +It is easy to overload the network +with careless sending to broadcast addresses. +.SS Compatibility +The basic AppleTalk socket interface is compatible with +.B netatalk +on BSD-derived systems. +Many BSD systems fail to check +.B SO_BROADCAST +when sending broadcast frames; this can lead to compatibility problems. +.P +The +raw +socket mode is unique to Linux and exists to support the alternative CAP +package and AppleTalk monitoring tools more easily. +.SH BUGS +There are too many inconsistent error values. +.P +The ioctls used to configure routing tables, devices, +AARP tables, and other devices are not yet described. +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2), +.BR capabilities (7), +.BR socket (7) diff --git a/man/man7/environ.7 b/man/man7/environ.7 new file mode 100644 index 0000000..86be682 --- /dev/null +++ b/man/man7/environ.7 @@ -0,0 +1,354 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" and Andries Brouwer (aeb@cwi.nl), Fri Feb 14 21:47:50 1997. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sun Jul 25 10:45:30 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Mon Oct 21 17:47:19 1996 by Eric S. Raymond (esr@thyrsus.com) +.\" Modified Wed Aug 27 20:28:58 1997 by Nicolás Lichtmaier (nick@debian.org) +.\" Modified Mon Sep 21 00:00:26 1998 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Wed Jan 24 06:37:24 2001 by Eric S. Raymond (esr@thyrsus.com) +.\" Modified Thu Dec 13 23:53:27 2001 by Martin Schulze +.\" +.TH environ 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +environ \- user environment +.SH SYNOPSIS +.nf +.BI "extern char **" environ ; +.fi +.SH DESCRIPTION +The variable +.I environ +points to an array of pointers to strings called the "environment". +The last pointer in this array has the value NULL. +This array of strings is made available to the process by the +.BR execve (2) +call when a new program is started. +When a child process is created via +.BR fork (2), +it inherits a +.I copy +of its parent's environment. +.P +By convention, the strings in +.I environ +have the form "\fIname\fP\fB=\fP\fIvalue\fP". +The name is case-sensitive and may not contain +the character "\fB=\fP". +The value can be anything that can be represented as a string. +The name and the value may not contain an embedded null byte (\[aq]\e0\[aq]), +since this is assumed to terminate the string. +.P +Environment variables may be placed in the shell's environment by the +.I export +command in +.BR sh (1), +or by the +.I setenv +command if you use +.BR csh (1). +.P +The initial environment of the shell is populated in various ways, +such as definitions from +.I /etc/environment +that are processed by +.BR pam_env (8) +for all users at login time (on systems that employ +.BR pam (8)). +In addition, various shell initialization scripts, such as the system-wide +.I /etc/profile +script and per-user initializations script may include commands +that add variables to the shell's environment; +see the manual page of your preferred shell for details. +.P +Bourne-style shells support the syntax +.P +.in +4n +.EX +NAME=value command +.EE +.in +.P +to create an environment variable definition only in the scope +of the process that executes +.IR command . +Multiple variable definitions, separated by white space, may precede +.IR command . +.P +Arguments may also be placed in the +environment at the point of an +.BR exec (3). +A C program can manipulate its environment using the functions +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +and +.BR unsetenv (3). +.P +What follows is a list of environment variables typically seen on a +system. +This list is incomplete and includes only common variables seen +by average users in their day-to-day routine. +Environment variables specific to a particular program or library function +are documented in the ENVIRONMENT section of the appropriate manual page. +.TP +.B USER +The name of the logged-in user (used by some BSD-derived programs). +Set at login time, see section NOTES below. +.TP +.B LOGNAME +The name of the logged-in user (used by some System-V derived programs). +Set at login time, see section NOTES below. +.TP +.B HOME +A user's login directory. +Set at login time, see section NOTES below. +.TP +.B LANG +The name of a locale to use for locale categories when not overridden +by +.B LC_ALL +or more specific environment variables such as +.BR LC_COLLATE , +.BR LC_CTYPE , +.BR LC_MESSAGES , +.BR LC_MONETARY , +.BR LC_NUMERIC , +and +.B LC_TIME +(see +.BR locale (7) +for further details of the +.B LC_* +environment variables). +.TP +.B PATH +The sequence of directory prefixes that +.BR sh (1) +and many other +programs employ when searching for an executable file that is specified +as a simple filename (i.a., a pathname that contains no slashes). +The prefixes are separated by colons (\fB:\fP). +The list of prefixes is searched from beginning to end, +by checking the pathname formed by concatenating +a prefix, a slash, and the filename, +until a file with execute permission is found. +.IP +As a legacy feature, a zero-length prefix +(specified as two adjacent colons, or an initial or terminating colon) +is interpreted to mean the current working directory. +However, use of this feature is deprecated, +and POSIX notes that a conforming application shall use +an explicit pathname (e.g., +.IR . ) +to specify the current working directory. +.IP +Analogously to +.BR PATH , +one has +.B CDPATH +used by some shells to find the target +of a change directory command, +.B MANPATH +used by +.BR man (1) +to find manual pages, and so on. +.TP +.B PWD +Absolute path to the current working directory; +required to be partially canonical (no +.I .\& +or +.I ..\& +components). +.TP +.B SHELL +The absolute pathname of the user's login shell. +Set at login time, see section NOTES below. +.TP +.B TERM +The terminal type for which output is to be prepared. +.TP +.B PAGER +The user's preferred utility to display text files. +Any string acceptable as a command-string operand to the +.I sh\ \-c +command shall be valid. +If +.B PAGER +is null or is not set, +then applications that launch a pager will default to a program such as +.BR less (1) +or +.BR more (1). +.TP +.BR EDITOR / VISUAL +The user's preferred utility to edit text files. +Any string acceptable as a command_string operand to the +.I sh\ \-c +command shall be valid. +.\" .TP +.\" .B BROWSER +.\" The user's preferred utility to browse URLs. Sequence of colon-separated +.\" browser commands. See http://www.catb.org/\[ti]esr/BROWSER/ . +.P +Note that the behavior of many programs and library routines is +influenced by the presence or value of certain environment variables. +Examples include the following: +.IP \[bu] 3 +The variables +.BR LANG ", " LANGUAGE ", " NLSPATH ", " LOCPATH , +.BR LC_ALL ", " LC_MESSAGES , +and so on influence locale handling; see +.BR catopen (3), +.BR gettext (3), +and +.BR locale (7). +.IP \[bu] +.B TMPDIR +influences the path prefix of names created by +.BR tempnam (3) +and other routines, and the temporary directory used by +.BR sort (1) +and other programs. +.IP \[bu] +.BR LD_LIBRARY_PATH ", " LD_PRELOAD , +and other +.B LD_* +variables influence the behavior of the dynamic loader/linker. +See also +.BR ld.so (8). +.IP \[bu] +.B POSIXLY_CORRECT +makes certain programs and library routines follow +the prescriptions of POSIX. +.IP \[bu] +The behavior of +.BR malloc (3) +is influenced by +.B MALLOC_* +variables. +.IP \[bu] +The variable +.B HOSTALIASES +gives the name of a file containing aliases +to be used with +.BR gethostbyname (3). +.IP \[bu] +.BR TZ " and " TZDIR +give timezone information used by +.BR tzset (3) +and through that by functions like +.BR ctime (3), +.BR localtime (3), +.BR mktime (3), +.BR strftime (3). +See also +.BR tzselect (8). +.IP \[bu] +.B TERMCAP +gives information on how to address a given terminal +(or gives the name of a file containing such information). +.IP \[bu] +.BR COLUMNS " and " LINES +tell applications about the window size, possibly overriding the actual size. +.IP \[bu] +.BR PRINTER " or " LPDEST +may specify the desired printer to use. +See +.BR lpr (1). +.SH NOTES +Historically and by standard, +.I environ +must be declared in the user program. +However, as a (nonstandard) programmer convenience, +.I environ +is declared in the header file +.I +if the +.B _GNU_SOURCE +feature test macro is defined (see +.BR feature_test_macros (7)). +.P +The +.BR prctl (2) +.B PR_SET_MM_ENV_START +and +.B PR_SET_MM_ENV_END +operations can be used to control the location of the process's environment. +.P +The +.BR HOME , +.BR LOGNAME , +.BR SHELL , +and +.B USER +variables are set when the user is changed via a +session management interface, typically by a program such as +.BR login (1) +from a user database (such as +.BR passwd (5)). +(Switching to the root user using +.BR su (1) +may result in a mixed environment where +.B LOGNAME +and +.B USER +are retained from old user; see the +.BR su (1) +manual page.) +.SH BUGS +Clearly there is a security risk here. +Many a system command has been +tricked into mischief by a user who specified unusual values for +.BR IFS " or " LD_LIBRARY_PATH . +.P +There is also the risk of name space pollution. +Programs like +.I make +and +.I autoconf +allow overriding of default utility names from the +environment with similarly named variables in all caps. +Thus one uses +.B CC +to select the desired C compiler (and similarly +.BR MAKE , +.BR AR , +.BR AS , +.BR FC , +.BR LD , +.BR LEX , +.BR RM , +.BR YACC , +etc.). +However, in some traditional uses such an environment variable +gives options for the program instead of a pathname. +Thus, one has +.B MORE +and +.BR LESS . +Such usage is considered mistaken, and to be avoided in new +programs. +.SH SEE ALSO +.BR bash (1), +.BR csh (1), +.BR env (1), +.BR login (1), +.BR printenv (1), +.BR sh (1), +.BR su (1), +.BR tcsh (1), +.BR execve (2), +.BR clearenv (3), +.BR exec (3), +.BR getenv (3), +.BR putenv (3), +.BR setenv (3), +.BR unsetenv (3), +.BR locale (7), +.BR ld.so (8), +.BR pam_env (8) diff --git a/man/man7/epoll.7 b/man/man7/epoll.7 new file mode 100644 index 0000000..bcc19bd --- /dev/null +++ b/man/man7/epoll.7 @@ -0,0 +1,610 @@ +.\" Copyright (C) 2003 Davide Libenzi +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Davide Libenzi +.\" +.TH epoll 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +epoll \- I/O event notification facility +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +The +.B epoll +API performs a similar task to +.BR poll (2): +monitoring multiple file descriptors to see if I/O is possible on any of them. +The +.B epoll +API can be used either as an edge-triggered or a level-triggered +interface and scales well to large numbers of watched file descriptors. +.P +The central concept of the +.B epoll +API is the +.B epoll +.IR instance , +an in-kernel data structure which, from a user-space perspective, +can be considered as a container for two lists: +.IP \[bu] 3 +The +.I interest +list (sometimes also called the +.B epoll +set): the set of file descriptors that the process has registered +an interest in monitoring. +.IP \[bu] +The +.I ready +list: the set of file descriptors that are "ready" for I/O. +The ready list is a subset of +(or, more precisely, a set of references to) +the file descriptors in the interest list. +The ready list is dynamically populated +by the kernel as a result of I/O activity on those file descriptors. +.P +The following system calls are provided to +create and manage an +.B epoll +instance: +.IP \[bu] 3 +.BR epoll_create (2) +creates a new +.B epoll +instance and returns a file descriptor referring to that instance. +(The more recent +.BR epoll_create1 (2) +extends the functionality of +.BR epoll_create (2).) +.IP \[bu] +Interest in particular file descriptors is then registered via +.BR epoll_ctl (2), +which adds items to the interest list of the +.B epoll +instance. +.IP \[bu] +.BR epoll_wait (2) +waits for I/O events, +blocking the calling thread if no events are currently available. +(This system call can be thought of as fetching items from +the ready list of the +.B epoll +instance.) +.\" +.SS Level-triggered and edge-triggered +The +.B epoll +event distribution interface is able to behave both as edge-triggered +(ET) and as level-triggered (LT). +The difference between the two mechanisms +can be described as follows. +Suppose that +this scenario happens: +.IP (1) 5 +The file descriptor that represents the read side of a pipe +.RI ( rfd ) +is registered on the +.B epoll +instance. +.IP (2) +A pipe writer writes 2\ kB of data on the write side of the pipe. +.IP (3) +A call to +.BR epoll_wait (2) +is done that will return +.I rfd +as a ready file descriptor. +.IP (4) +The pipe reader reads 1\ kB of data from +.IR rfd . +.IP (5) +A call to +.BR epoll_wait (2) +is done. +.P +If the +.I rfd +file descriptor has been added to the +.B epoll +interface using the +.B EPOLLET +(edge-triggered) +flag, the call to +.BR epoll_wait (2) +done in step +.B 5 +will probably hang despite the available data still present in the file +input buffer; +meanwhile the remote peer might be expecting a response based on the +data it already sent. +The reason for this is that edge-triggered mode +delivers events only when changes occur on the monitored file descriptor. +So, in step +.B 5 +the caller might end up waiting for some data that is already present inside +the input buffer. +In the above example, an event on +.I rfd +will be generated because of the write done in +.B 2 +and the event is consumed in +.BR 3 . +Since the read operation done in +.B 4 +does not consume the whole buffer data, the call to +.BR epoll_wait (2) +done in step +.B 5 +might block indefinitely. +.P +An application that employs the +.B EPOLLET +flag should use nonblocking file descriptors to avoid having a blocking +read or write starve a task that is handling multiple file descriptors. +The suggested way to use +.B epoll +as an edge-triggered +.RB ( EPOLLET ) +interface is as follows: +.IP (1) 5 +with nonblocking file descriptors; and +.IP (2) +by waiting for an event only after +.BR read (2) +or +.BR write (2) +return +.BR EAGAIN . +.P +By contrast, when used as a level-triggered interface +(the default, when +.B EPOLLET +is not specified), +.B epoll +is simply a faster +.BR poll (2), +and can be used wherever the latter is used since it shares the +same semantics. +.P +Since even with edge-triggered +.BR epoll , +multiple events can be generated upon receipt of multiple chunks of data, +the caller has the option to specify the +.B EPOLLONESHOT +flag, to tell +.B epoll +to disable the associated file descriptor after the receipt of an event with +.BR epoll_wait (2). +When the +.B EPOLLONESHOT +flag is specified, +it is the caller's responsibility to rearm the file descriptor using +.BR epoll_ctl (2) +with +.BR EPOLL_CTL_MOD . +.P +If multiple threads +(or processes, if child processes have inherited the +.B epoll +file descriptor across +.BR fork (2)) +are blocked in +.BR epoll_wait (2) +waiting on the same epoll file descriptor and a file descriptor +in the interest list that is marked for edge-triggered +.RB ( EPOLLET ) +notification becomes ready, +just one of the threads (or processes) is awoken from +.BR epoll_wait (2). +This provides a useful optimization for avoiding "thundering herd" wake-ups +in some scenarios. +.\" +.SS Interaction with autosleep +If the system is in +.B autosleep +mode via +.I /sys/power/autosleep +and an event happens which wakes the device from sleep, the device +driver will keep the device awake only until that event is queued. +To keep the device awake until the event has been processed, +it is necessary to use the +.BR epoll_ctl (2) +.B EPOLLWAKEUP +flag. +.P +When the +.B EPOLLWAKEUP +flag is set in the +.B events +field for a +.IR "struct epoll_event" , +the system will be kept awake from the moment the event is queued, +through the +.BR epoll_wait (2) +call which returns the event until the subsequent +.BR epoll_wait (2) +call. +If the event should keep the system awake beyond that time, +then a separate +.I wake_lock +should be taken before the second +.BR epoll_wait (2) +call. +.SS /proc interfaces +The following interfaces can be used to limit the amount of +kernel memory consumed by epoll: +.\" Following was added in Linux 2.6.28, but them removed in Linux 2.6.29 +.\" .TP +.\" .IR /proc/sys/fs/epoll/max_user_instances " (since Linux 2.6.28)" +.\" This specifies an upper limit on the number of epoll instances +.\" that can be created per real user ID. +.TP +.IR /proc/sys/fs/epoll/max_user_watches " (since Linux 2.6.28)" +This specifies a limit on the total number of +file descriptors that a user can register across +all epoll instances on the system. +The limit is per real user ID. +Each registered file descriptor costs roughly 90 bytes on a 32-bit kernel, +and roughly 160 bytes on a 64-bit kernel. +Currently, +.\" Linux 2.6.29 (in Linux 2.6.28, the default was 1/32 of lowmem) +the default value for +.I max_user_watches +is 1/25 (4%) of the available low memory, +divided by the registration cost in bytes. +.SS Example for suggested usage +While the usage of +.B epoll +when employed as a level-triggered interface does have the same +semantics as +.BR poll (2), +the edge-triggered usage requires more clarification to avoid stalls +in the application event loop. +In this example, listener is a +nonblocking socket on which +.BR listen (2) +has been called. +The function +.I do_use_fd() +uses the new ready file descriptor until +.B EAGAIN +is returned by either +.BR read (2) +or +.BR write (2). +An event-driven state machine application should, after having received +.BR EAGAIN , +record its current state so that at the next call to +.I do_use_fd() +it will continue to +.BR read (2) +or +.BR write (2) +from where it stopped before. +.P +.in +4n +.EX +#define MAX_EVENTS 10 +struct epoll_event ev, events[MAX_EVENTS]; +int listen_sock, conn_sock, nfds, epollfd; +\& +/* Code to set up listening socket, \[aq]listen_sock\[aq], + (socket(), bind(), listen()) omitted. */ +\& +epollfd = epoll_create1(0); +if (epollfd == \-1) { + perror("epoll_create1"); + exit(EXIT_FAILURE); +} +\& +ev.events = EPOLLIN; +ev.data.fd = listen_sock; +if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == \-1) { + perror("epoll_ctl: listen_sock"); + exit(EXIT_FAILURE); +} +\& +for (;;) { + nfds = epoll_wait(epollfd, events, MAX_EVENTS, \-1); + if (nfds == \-1) { + perror("epoll_wait"); + exit(EXIT_FAILURE); + } +\& + for (n = 0; n < nfds; ++n) { + if (events[n].data.fd == listen_sock) { + conn_sock = accept(listen_sock, + (struct sockaddr *) &addr, &addrlen); + if (conn_sock == \-1) { + perror("accept"); + exit(EXIT_FAILURE); + } + setnonblocking(conn_sock); + ev.events = EPOLLIN | EPOLLET; + ev.data.fd = conn_sock; + if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock, + &ev) == \-1) { + perror("epoll_ctl: conn_sock"); + exit(EXIT_FAILURE); + } + } else { + do_use_fd(events[n].data.fd); + } + } +} +.EE +.in +.P +When used as an edge-triggered interface, for performance reasons, it is +possible to add the file descriptor inside the +.B epoll +interface +.RB ( EPOLL_CTL_ADD ) +once by specifying +.RB ( EPOLLIN | EPOLLOUT ). +This allows you to avoid +continuously switching between +.B EPOLLIN +and +.B EPOLLOUT +calling +.BR epoll_ctl (2) +with +.BR EPOLL_CTL_MOD . +.SS Questions and answers +.IP \[bu] 3 +What is the key used to distinguish the file descriptors registered in an +interest list? +.IP +The key is the combination of the file descriptor number and +the open file description +(also known as an "open file handle", +the kernel's internal representation of an open file). +.IP \[bu] +What happens if you register the same file descriptor on an +.B epoll +instance twice? +.IP +You will probably get +.BR EEXIST . +However, it is possible to add a duplicate +.RB ( dup (2), +.BR dup2 (2), +.BR fcntl (2) +.BR F_DUPFD ) +file descriptor to the same +.B epoll +instance. +.\" But a file descriptor duplicated by fork(2) can't be added to the +.\" set, because the [file *, fd] pair is already in the epoll set. +.\" That is a somewhat ugly inconsistency. On the one hand, a child process +.\" cannot add the duplicate file descriptor to the epoll set. (In every +.\" other case that I can think of, file descriptors duplicated by fork have +.\" similar semantics to file descriptors duplicated by dup() and friends.) On +.\" the other hand, the very fact that the child has a duplicate of the +.\" file descriptor means that even if the parent closes its file descriptor, +.\" then epoll_wait() in the parent will continue to receive notifications for +.\" that file descriptor because of the duplicated file descriptor in the child. +.\" +.\" See http://thread.gmane.org/gmane.linux.kernel/596462/ +.\" "epoll design problems with common fork/exec patterns" +.\" +.\" mtk, Feb 2008 +This can be a useful technique for filtering events, +if the duplicate file descriptors are registered with different +.I events +masks. +.IP \[bu] +Can two +.B epoll +instances wait for the same file descriptor? +If so, are events reported to both +.B epoll +file descriptors? +.IP +Yes, and events would be reported to both. +However, careful programming may be needed to do this correctly. +.IP \[bu] +Is the +.B epoll +file descriptor itself poll/epoll/selectable? +.IP +Yes. +If an +.B epoll +file descriptor has events waiting, then it will +indicate as being readable. +.IP \[bu] +What happens if one attempts to put an +.B epoll +file descriptor into its own file descriptor set? +.IP +The +.BR epoll_ctl (2) +call fails +.RB ( EINVAL ). +However, you can add an +.B epoll +file descriptor inside another +.B epoll +file descriptor set. +.IP \[bu] +Can I send an +.B epoll +file descriptor over a UNIX domain socket to another process? +.IP +Yes, but it does not make sense to do this, since the receiving process +would not have copies of the file descriptors in the interest list. +.IP \[bu] +Will closing a file descriptor cause it to be removed from all +.B epoll +interest lists? +.IP +Yes, but be aware of the following point. +A file descriptor is a reference to an open file description (see +.BR open (2)). +Whenever a file descriptor is duplicated via +.BR dup (2), +.BR dup2 (2), +.BR fcntl (2) +.BR F_DUPFD , +or +.BR fork (2), +a new file descriptor referring to the same open file description is +created. +An open file description continues to exist until all +file descriptors referring to it have been closed. +.IP +A file descriptor is removed from an +interest list only after all the file descriptors referring to the underlying +open file description have been closed. +This means that even after a file descriptor that is part of an +interest list has been closed, +events may be reported for that file descriptor if other file +descriptors referring to the same underlying file description remain open. +To prevent this happening, +the file descriptor must be explicitly removed from the interest list (using +.BR epoll_ctl (2) +.BR EPOLL_CTL_DEL ) +before it is duplicated. +Alternatively, +the application must ensure that all file descriptors are closed +(which may be difficult if file descriptors were duplicated +behind the scenes by library functions that used +.BR dup (2) +or +.BR fork (2)). +.IP \[bu] +If more than one event occurs between +.BR epoll_wait (2) +calls, are they combined or reported separately? +.IP +They will be combined. +.IP \[bu] +Does an operation on a file descriptor affect the +already collected but not yet reported events? +.IP +You can do two operations on an existing file descriptor. +Remove would be meaningless for +this case. +Modify will reread available I/O. +.IP \[bu] +Do I need to continuously read/write a file descriptor +until +.B EAGAIN +when using the +.B EPOLLET +flag (edge-triggered behavior)? +.IP +Receiving an event from +.BR epoll_wait (2) +should suggest to you that such +file descriptor is ready for the requested I/O operation. +You must consider it ready until the next (nonblocking) +read/write yields +.BR EAGAIN . +When and how you will use the file descriptor is entirely up to you. +.IP +For packet/token-oriented files (e.g., datagram socket, +terminal in canonical mode), +the only way to detect the end of the read/write I/O space +is to continue to read/write until +.BR EAGAIN . +.IP +For stream-oriented files (e.g., pipe, FIFO, stream socket), the +condition that the read/write I/O space is exhausted can also be detected by +checking the amount of data read from / written to the target file +descriptor. +For example, if you call +.BR read (2) +by asking to read a certain amount of data and +.BR read (2) +returns a lower number of bytes, you +can be sure of having exhausted the read I/O space for the file +descriptor. +The same is true when writing using +.BR write (2). +(Avoid this latter technique if you cannot guarantee that +the monitored file descriptor always refers to a stream-oriented file.) +.SS Possible pitfalls and ways to avoid them +.IP \[bu] 3 +.B Starvation (edge-triggered) +.IP +If there is a large amount of I/O space, +it is possible that by trying to drain +it the other files will not get processed causing starvation. +(This problem is not specific to +.BR epoll .) +.IP +The solution is to maintain a ready list +and mark the file descriptor as ready +in its associated data structure, thereby allowing the application to +remember which files need to be processed but still round robin amongst +all the ready files. +This also supports ignoring subsequent events you +receive for file descriptors that are already ready. +.IP \[bu] +.B If using an event cache... +.IP +If you use an event cache or store all the file descriptors returned from +.BR epoll_wait (2), +then make sure to provide a way to mark +its closure dynamically (i.e., caused by +a previous event's processing). +Suppose you receive 100 events from +.BR epoll_wait (2), +and in event #47 a condition causes event #13 to be closed. +If you remove the structure and +.BR close (2) +the file descriptor for event #13, then your +event cache might still say there are events waiting for that +file descriptor causing confusion. +.IP +One solution for this is to call, during the processing of event 47, +.BR epoll_ctl ( EPOLL_CTL_DEL ) +to delete file descriptor 13 and +.BR close (2), +then mark its associated +data structure as removed and link it to a cleanup list. +If you find another +event for file descriptor 13 in your batch processing, +you will discover the file descriptor had been +previously removed and there will be no confusion. +.SH VERSIONS +Some other systems provide similar mechanisms; +for example, +FreeBSD has +.IR kqueue , +and Solaris has +.IR /dev/poll . +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.5.44. +.\" Its interface should be finalized in Linux 2.5.66. +glibc 2.3.2. +.SH NOTES +The set of file descriptors that is being monitored via +an epoll file descriptor can be viewed via the entry for +the epoll file descriptor in the process's +.IR /proc/ pid /fdinfo +directory. +See +.BR proc (5) +for further details. +.P +The +.BR kcmp (2) +.B KCMP_EPOLL_TFD +operation can be used to test whether a file descriptor +is present in an epoll instance. +.SH SEE ALSO +.BR epoll_create (2), +.BR epoll_create1 (2), +.BR epoll_ctl (2), +.BR epoll_wait (2), +.BR poll (2), +.BR select (2) diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7 new file mode 100644 index 0000000..c08ce33 --- /dev/null +++ b/man/man7/fanotify.7 @@ -0,0 +1,1456 @@ +.\" Copyright (C) 2013, Heinrich Schuchardt +.\" and Copyright (C) 2014, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.TH fanotify 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fanotify \- monitoring filesystem events +.SH DESCRIPTION +The fanotify API provides notification and interception of +filesystem events. +Use cases include virus scanning and hierarchical storage management. +In the original fanotify API, only a limited set of events was supported. +In particular, there was no support for create, delete, and move events. +The support for those events was added in Linux 5.1. +(See +.BR inotify (7) +for details of an API that did notify those events pre Linux 5.1.) +.P +Additional capabilities compared to the +.BR inotify (7) +API include the ability to monitor all of the objects +in a mounted filesystem, +the ability to make access permission decisions, and the +possibility to read or modify files before access by other applications. +.P +The following system calls are used with this API: +.BR fanotify_init (2), +.BR fanotify_mark (2), +.BR read (2), +.BR write (2), +and +.BR close (2). +.SS fanotify_init(), fanotify_mark(), and notification groups +The +.BR fanotify_init (2) +system call creates and initializes an fanotify notification group +and returns a file descriptor referring to it. +.P +An fanotify notification group is a kernel-internal object that holds +a list of files, directories, filesystems, and mounts for which +events shall be created. +.P +For each entry in an fanotify notification group, two bit masks exist: the +.I mark +mask and the +.I ignore +mask. +The mark mask defines file activities for which an event shall be created. +The ignore mask defines activities for which no event shall be generated. +Having these two types of masks permits a filesystem, mount, or +directory to be marked for receiving events, while at the same time +ignoring events for specific objects under a mount or directory. +.P +The +.BR fanotify_mark (2) +system call adds a file, directory, filesystem, or mount to a +notification group and specifies which events +shall be reported (or ignored), or removes or modifies such an entry. +.P +A possible usage of the ignore mask is for a file cache. +Events of interest for a file cache are modification of a file and closing +of the same. +Hence, the cached directory or mount is to be marked to receive these +events. +After receiving the first event informing that a file has been modified, +the corresponding cache entry will be invalidated. +No further modification events for this file are of interest until the file +is closed. +Hence, the modify event can be added to the ignore mask. +Upon receiving the close event, the modify event can be removed from the +ignore mask and the file cache entry can be updated. +.P +The entries in the fanotify notification groups refer to files and +directories via their inode number and to mounts via their mount ID. +If files or directories are renamed or moved within the same mount, +the respective entries survive. +If files or directories are deleted or moved to another mount or if +filesystems or mounts are unmounted, the corresponding entries are deleted. +.SS The event queue +As events occur on the filesystem objects monitored by a notification group, +the fanotify system generates events that are collected in a queue. +These events can then be read (using +.BR read (2) +or similar) +from the fanotify file descriptor +returned by +.BR fanotify_init (2). +.P +Two types of events are generated: +.I notification +events and +.I permission +events. +Notification events are merely informative and require no action to be taken +by the receiving application with one exception: if a valid file descriptor +is provided within a generic event, the file descriptor must be closed. +Permission events are requests to the receiving application to decide +whether permission for a file access shall be granted. +For these events, the recipient must write a response which decides whether +access is granted or not. +.P +An event is removed from the event queue of the fanotify group +when it has been read. +Permission events that have been read are kept in an internal list of the +fanotify group until either a permission decision has been taken by +writing to the fanotify file descriptor or the fanotify file descriptor +is closed. +.SS Reading fanotify events +Calling +.BR read (2) +for the file descriptor returned by +.BR fanotify_init (2) +blocks (if the flag +.B FAN_NONBLOCK +is not specified in the call to +.BR fanotify_init (2)) +until either a file event occurs or the call is interrupted by a signal +(see +.BR signal (7)). +.P +After a successful +.BR read (2), +the read buffer contains one or more of the following structures: +.P +.in +4n +.EX +struct fanotify_event_metadata { + __u32 event_len; + __u8 vers; + __u8 reserved; + __u16 metadata_len; + __aligned_u64 mask; + __s32 fd; + __s32 pid; +}; +.EE +.in +.P +Information records are +supplemental pieces of information that +may be provided alongside the generic +.I fanotify_event_metadata +structure. +The +.I flags +passed to +.BR fanotify_init (2) +have influence over the type of information records that +may be returned for an event. +For example, +if a notification group is initialized with +.B FAN_REPORT_FID +or +.BR FAN_REPORT_DIR_FID , +then event listeners should also expect to receive a +.I fanotify_event_info_fid +structure alongside the +.I fanotify_event_metadata +structure, +whereby file handles are used to +identify filesystem objects +rather than file descriptors. +Information records may also be stacked, +meaning that using the various +.B FAN_REPORT_* +flags in conjunction with one another is supported. +In such cases, +multiple information records can be returned for an event +alongside the generic +.I fanotify_event_metadata +structure. +For example, +if a notification group is initialized with +.B FAN_REPORT_TARGET_FID +and +.BR FAN_REPORT_PIDFD , +then an event listener should expect to receive up to two +.I fanotify_event_info_fid +information records and one +.I fanotify_event_info_pidfd +information record alongside the generic +.I fanotify_event_metadata +structure. +Importantly, +fanotify provides no guarantee around +the ordering of information records +when a notification group is initialized with a +stacked based configuration. +Each information record has a nested structure of type +.IR fanotify_event_info_header . +It is imperative for event listeners to inspect the +.I info_type +field of this structure in order to +determine the type of information record that +had been received for a given event. +.P +In cases where an fanotify group +identifies filesystem objects by file handles, +event listeners should also expect to +receive one or more of the below +information record objects alongside the generic +.I fanotify_event_metadata +structure within the read buffer: +.P +.in +4n +.EX +struct fanotify_event_info_fid { + struct fanotify_event_info_header hdr; + __kernel_fsid_t fsid; + unsigned char handle[]; +}; +.EE +.in +.P +In cases where an fanotify group is initialized with +.BR FAN_REPORT_PIDFD , +event listeners should expect to receive the below +information record object alongside the generic +.I fanotify_event_metadata +structure within the read buffer: +.P +.in +4n +.EX +struct fanotify_event_info_pidfd { + struct fanotify_event_info_header hdr; + __s32 pidfd; +}; +.EE +.in +.P +In case of a +.B FAN_FS_ERROR +event, +an additional information record describing the error that occurred +is returned alongside the generic +.I fanotify_event_metadata +structure within the read buffer. +This structure is defined as follows: +.P +.in +4n +.EX +struct fanotify_event_info_error { + struct fanotify_event_info_header hdr; + __s32 error; + __u32 error_count; +}; +.EE +.in +.P +All information records contain a nested structure of type +.IR fanotify_event_info_header . +This structure holds meta-information about the information record +that may have been returned alongside the generic +.I fanotify_event_metadata +structure. +This structure is defined as follows: +.P +.in +4n +.EX +struct fanotify_event_info_header { + __u8 info_type; + __u8 pad; + __u16 len; +}; +.EE +.in +.P +For performance reasons, it is recommended to use a large +buffer size (for example, 4096 bytes), +so that multiple events can be retrieved by a single +.BR read (2). +.P +The return value of +.BR read (2) +is the number of bytes placed in the buffer, +or \-1 in case of an error (but see BUGS). +.P +The fields of the +.I fanotify_event_metadata +structure are as follows: +.TP +.I event_len +This is the length of the data for the current event and the offset +to the next event in the buffer. +Unless the group identifies filesystem objects by file handles, the value of +.I event_len +is always +.BR FAN_EVENT_METADATA_LEN . +For a group that identifies filesystem objects by file handles, +.I event_len +also includes the variable length file identifier records. +.TP +.I vers +This field holds a version number for the structure. +It must be compared to +.B FANOTIFY_METADATA_VERSION +to verify that the structures returned at run time match +the structures defined at compile time. +In case of a mismatch, the application should abandon trying to use the +fanotify file descriptor. +.TP +.I reserved +This field is not used. +.TP +.I metadata_len +This is the length of the structure. +The field was introduced to facilitate the implementation of +optional headers per event type. +No such optional headers exist in the current implementation. +.TP +.I mask +This is a bit mask describing the event (see below). +.TP +.I fd +This is an open file descriptor for the object being accessed, or +.B FAN_NOFD +if a queue overflow occurred. +With an fanotify group that identifies filesystem objects by file handles, +applications should expect this value to be set to +.B FAN_NOFD +for each event that is received. +The file descriptor can be used to access the contents +of the monitored file or directory. +The reading application is responsible for closing this file descriptor. +.IP +When calling +.BR fanotify_init (2), +the caller may specify (via the +.I event_f_flags +argument) various file status flags that are to be set +on the open file description that corresponds to this file descriptor. +In addition, the (kernel-internal) +.B FMODE_NONOTIFY +file status flag is set on the open file description. +This flag suppresses fanotify event generation. +Hence, when the receiver of the fanotify event accesses the notified file or +directory using this file descriptor, no additional events will be created. +.TP +.I pid +If flag +.B FAN_REPORT_TID +was set in +.BR fanotify_init (2), +this is the TID of the thread that caused the event. +Otherwise, this the PID of the process that caused the event. +.P +A program listening to fanotify events can compare this PID +to the PID returned by +.BR getpid (2), +to determine whether the event is caused by the listener itself, +or is due to a file access by another process. +.P +The bit mask in +.I mask +indicates which events have occurred for a single filesystem object. +Multiple bits may be set in this mask, +if more than one event occurred for the monitored filesystem object. +In particular, +consecutive events for the same filesystem object and originating from the +same process may be merged into a single event, with the exception that two +permission events are never merged into one queue entry. +.P +The bits that may appear in +.I mask +are as follows: +.TP +.B FAN_ACCESS +A file or a directory (but see BUGS) was accessed (read). +.TP +.B FAN_OPEN +A file or a directory was opened. +.TP +.B FAN_OPEN_EXEC +A file was opened with the intent to be executed. +See NOTES in +.BR fanotify_mark (2) +for additional details. +.TP +.B FAN_ATTRIB +A file or directory metadata was changed. +.TP +.B FAN_CREATE +A child file or directory was created in a watched parent. +.TP +.B FAN_DELETE +A child file or directory was deleted in a watched parent. +.TP +.B FAN_DELETE_SELF +A watched file or directory was deleted. +.TP +.B FAN_FS_ERROR +A filesystem error was detected. +.TP +.B FAN_RENAME +A file or directory has been moved to or from a watched parent directory. +.TP +.B FAN_MOVED_FROM +A file or directory has been moved from a watched parent directory. +.TP +.B FAN_MOVED_TO +A file or directory has been moved to a watched parent directory. +.TP +.B FAN_MOVE_SELF +A watched file or directory was moved. +.TP +.B FAN_MODIFY +A file was modified. +.TP +.B FAN_CLOSE_WRITE +A file that was opened for writing +.RB ( O_WRONLY +or +.BR O_RDWR ) +was closed. +.TP +.B FAN_CLOSE_NOWRITE +A file or directory that was opened read-only +.RB ( O_RDONLY ) +was closed. +.TP +.B FAN_Q_OVERFLOW +The event queue exceeded the limit on number of events. +This limit can be overridden by specifying the +.B FAN_UNLIMITED_QUEUE +flag when calling +.BR fanotify_init (2). +.TP +.B FAN_ACCESS_PERM +An application wants to read a file or directory, for example using +.BR read (2) +or +.BR readdir (2). +The reader must write a response (as described below) +that determines whether the permission to +access the filesystem object shall be granted. +.TP +.B FAN_OPEN_PERM +An application wants to open a file or directory. +The reader must write a response that determines whether the permission to +open the filesystem object shall be granted. +.TP +.B FAN_OPEN_EXEC_PERM +An application wants to open a file for execution. +The reader must write a response that determines whether the permission to +open the filesystem object for execution shall be granted. +See NOTES in +.BR fanotify_mark (2) +for additional details. +.P +To check for any close event, the following bit mask may be used: +.TP +.B FAN_CLOSE +A file was closed. +This is a synonym for: +.IP +.in +4n +.EX +FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE +.EE +.in +.P +To check for any move event, the following bit mask may be used: +.TP +.B FAN_MOVE +A file or directory was moved. +This is a synonym for: +.IP +.in +4n +.EX +FAN_MOVED_FROM | FAN_MOVED_TO +.EE +.in +.P +The following bits may appear in +.I mask +only in conjunction with other event type bits: +.TP +.B FAN_ONDIR +The events described in the +.I mask +have occurred on a directory object. +Reporting events on directories requires setting this flag in the mark mask. +See +.BR fanotify_mark (2) +for additional details. +The +.B FAN_ONDIR +flag is reported in an event mask only if the fanotify group identifies +filesystem objects by file handles. +.P +Information records that are supplied alongside the generic +.I fanotify_event_metadata +structure will always contain a nested structure of type +.IR fanotify_event_info_header . +The fields of the +.I fanotify_event_info_header +are as follows: +.TP +.I info_type +A unique integer value representing +the type of information record object received for an event. +The value of this field can be set to one of the following: +.BR FAN_EVENT_INFO_TYPE_FID , +.BR FAN_EVENT_INFO_TYPE_DFID , +.BR FAN_EVENT_INFO_TYPE_DFID_NAME , +or +.BR FAN_EVENT_INFO_TYPE_PIDFD . +The value set for this field +is dependent on the flags that have been supplied to +.BR fanotify_init (2). +Refer to the field details of each information record object type below +to understand the different cases in which the +.I info_type +values can be set. +.TP +.I pad +This field is currently not used by any information record object type +and therefore is set to zero. +.TP +.I len +The value of +.I len +is set to the size of the information record object, +including the +.IR fanotify_event_info_header . +The total size of all additional information records +is not expected to be larger than +.RI ( event_len +\- +.IR metadata_len ). +.P +The fields of the +.I fanotify_event_info_fid +structure are as follows: +.TP +.I hdr +This is a structure of type +.IR fanotify_event_info_header . +For example, when an fanotify file descriptor is created using +.BR FAN_REPORT_FID , +a single information record is expected to be attached to the event with +.I info_type +field value of +.BR FAN_EVENT_INFO_TYPE_FID . +When an fanotify file descriptor is created using the combination of +.B FAN_REPORT_FID +and +.BR FAN_REPORT_DIR_FID , +there may be two information records attached to the event: +one with +.I info_type +field value of +.BR FAN_EVENT_INFO_TYPE_DFID , +identifying a parent directory object, and one with +.I info_type +field value of +.BR FAN_EVENT_INFO_TYPE_FID , +identifying a child object. +Note that for the directory entry modification events +.BR FAN_CREATE , +.BR FAN_DELETE , +.BR FAN_MOVE , +and +.BR FAN_RENAME , +an information record identifying the created/deleted/moved child object +is reported only if an fanotify group was initialized with the flag +.BR FAN_REPORT_TARGET_FID . +.TP +.I fsid +This is a unique identifier of the filesystem containing the object +associated with the event. +It is a structure of type +.I __kernel_fsid_t +and contains the same value as +.I f_fsid +when calling +.BR statfs (2). +.TP +.I handle +This field contains a variable-length structure of type +.IR "struct file_handle" . +It is an opaque handle that corresponds to a specified object on a +filesystem as returned by +.BR name_to_handle_at (2). +It can be used to uniquely identify a file on a filesystem and can be +passed as an argument to +.BR open_by_handle_at (2). +If the value of +.I info_type +field is +.BR FAN_EVENT_INFO_TYPE_DFID_NAME , +the file handle is followed by a null terminated string that identifies the +created/deleted/moved directory entry name. +For other events such as +.BR FAN_OPEN , +.BR FAN_ATTRIB , +.BR FAN_DELETE_SELF , +and +.BR FAN_MOVE_SELF , +if the value of +.I info_type +field is +.BR FAN_EVENT_INFO_TYPE_FID , +the +.I handle +identifies the object correlated to the event. +If the value of +.I info_type +field is +.BR FAN_EVENT_INFO_TYPE_DFID , +the +.I handle +identifies the directory object correlated to the event or the parent directory +of a non-directory object correlated to the event. +If the value of +.I info_type +field is +.BR FAN_EVENT_INFO_TYPE_DFID_NAME , +the +.I handle +identifies the same directory object that would be reported with +.B FAN_EVENT_INFO_TYPE_DFID +and the file handle is followed by a null terminated string that identifies the +name of a directory entry in that directory, or '.' to identify the directory +object itself. +.P +The fields of the +.I fanotify_event_info_pidfd +structure are as follows: +.TP +.I hdr +This is a structure of type +.IR fanotify_event_info_header . +When an fanotify group is initialized using +.BR FAN_REPORT_PIDFD , +the +.I info_type +field value of the +.I fanotify_event_info_header +is set to +.BR FAN_EVENT_INFO_TYPE_PIDFD . +.TP +.I pidfd +This is a process file descriptor that refers to +the process responsible for generating the event. +The returned process file descriptor is no different from +one which could be obtained manually if +.BR pidfd_open (2) +were to be called on +.IR fanotify_event_metadata.pid . +In the instance that an error is encountered during pidfd creation, +one of two possible error types represented by +a negative integer value may be returned in this +.I pidfd +field. +In cases where +the process responsible for generating the event +has terminated prior to +the event listener being able to +read events from the notification queue, +.B FAN_NOPIDFD +is returned. +The pidfd creation for an event is only performed at the time the +events are read from the notification queue. +All other possible pidfd creation failures are represented by +.BR FAN_EPIDFD . +Once the event listener has dealt with an event +and the pidfd is no longer required, +the pidfd should be closed via +.BR close (2). +.P +The fields of the +.I fanotify_event_info_error +structure are as follows: +.TP +.I hdr +This is a structure of type +.IR fanotify_event_info_header . +The +.I info_type +field is set to +.BR FAN_EVENT_INFO_TYPE_ERROR . +.TP +.I error +Identifies the type of error that occurred. +.TP +.I error_count +This is a counter of the number of errors suppressed +since the last error was read. +.P +The following macros are provided to iterate over a buffer containing +fanotify event metadata returned by a +.BR read (2) +from an fanotify file descriptor: +.TP +.B FAN_EVENT_OK(meta, len) +This macro checks the remaining length +.I len +of the buffer +.I meta +against the length of the metadata structure and the +.I event_len +field of the first metadata structure in the buffer. +.TP +.B FAN_EVENT_NEXT(meta, len) +This macro uses the length indicated in the +.I event_len +field of the metadata structure pointed to by +.I meta +to calculate the address of the next metadata structure that follows +.IR meta . +.I len +is the number of bytes of metadata that currently remain in the buffer. +The macro returns a pointer to the next metadata structure that follows +.IR meta , +and reduces +.I len +by the number of bytes in the metadata structure that +has been skipped over (i.e., it subtracts +.I meta\->event_len +from +.IR len ). +.P +In addition, there is: +.TP +.B FAN_EVENT_METADATA_LEN +This macro returns the size (in bytes) of the structure +.IR fanotify_event_metadata . +This is the minimum size (and currently the only size) of any event metadata. +.\" +.SS Monitoring an fanotify file descriptor for events +When an fanotify event occurs, the fanotify file descriptor indicates as +readable when passed to +.BR epoll (7), +.BR poll (2), +or +.BR select (2). +.SS Dealing with permission events +For permission events, the application must +.BR write (2) +a structure of the following form to the +fanotify file descriptor: +.P +.in +4n +.EX +struct fanotify_response { + __s32 fd; + __u32 response; +}; +.EE +.in +.P +The fields of this structure are as follows: +.TP +.I fd +This is the file descriptor from the structure +.IR fanotify_event_metadata . +.TP +.I response +This field indicates whether or not the permission is to be granted. +Its value must be either +.B FAN_ALLOW +to allow the file operation or +.B FAN_DENY +to deny the file operation. +.P +If access is denied, the requesting application call will receive an +.B EPERM +error. +Additionally, if the notification group has been created with the +.B FAN_ENABLE_AUDIT +flag, then the +.B FAN_AUDIT +flag can be set in the +.I response +field. +In that case, the audit subsystem will log information about the access +decision to the audit logs. +.\" +.SS Monitoring filesystems for errors +A single +.B FAN_FS_ERROR +event is stored per filesystem at once. +Extra error messages are suppressed and accounted for in the +.I error_count +field of the existing +.B FAN_FS_ERROR +event record, +but details about the errors are lost. +.P +Errors reported by +.B FAN_FS_ERROR +are generic +.I errno +values, +but not all kinds of error types are reported by all filesystems. +.P +Errors not directly related to a file (i.e. super block corruption) +are reported with an invalid +.IR handle . +For these errors, the +.I handle +will have the field +.I handle_type +set to +.BR FILEID_INVALID , +and the handle buffer size set to +.BR 0 . +.\" +.SS Closing the fanotify file descriptor +When all file descriptors referring to the fanotify notification group are +closed, the fanotify group is released and its resources +are freed for reuse by the kernel. +Upon +.BR close (2), +outstanding permission events will be set to allowed. +.SS /proc interfaces +The file +.IR /proc/ pid /fdinfo/ fd +contains information about fanotify marks for file descriptor +.I fd +of process +.IR pid . +See +.BR proc (5) +for details. +.P +Since Linux 5.13, +.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b +the following interfaces can be used to control the amount of +kernel resources consumed by fanotify: +.TP +.I /proc/sys/fs/fanotify/max_queued_events +The value in this file is used when an application calls +.BR fanotify_init (2) +to set an upper limit on the number of events that can be +queued to the corresponding fanotify group. +Events in excess of this limit are dropped, but an +.B FAN_Q_OVERFLOW +event is always generated. +Prior to Linux kernel 5.13, +.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b +the hardcoded limit was 16384 events. +.TP +.I /proc/sys/fs/fanotify/max_user_group +This specifies an upper limit on the number of fanotify groups +that can be created per real user ID. +Prior to Linux kernel 5.13, +.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b +the hardcoded limit was 128 groups per user. +.TP +.I /proc/sys/fs/fanotify/max_user_marks +This specifies an upper limit on the number of fanotify marks +that can be created per real user ID. +Prior to Linux kernel 5.13, +.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b +the hardcoded limit was 8192 marks per group (not per user). +.SH ERRORS +In addition to the usual errors for +.BR read (2), +the following errors can occur when reading from the +fanotify file descriptor: +.TP +.B EINVAL +The buffer is too small to hold the event. +.TP +.B EMFILE +The per-process limit on the number of open files has been reached. +See the description of +.B RLIMIT_NOFILE +in +.BR getrlimit (2). +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +See +.I /proc/sys/fs/file\-max +in +.BR proc (5). +.TP +.B ETXTBSY +This error is returned by +.BR read (2) +if +.B O_RDWR +or +.B O_WRONLY +was specified in the +.I event_f_flags +argument when calling +.BR fanotify_init (2) +and an event occurred for a monitored file that is currently being executed. +.P +In addition to the usual errors for +.BR write (2), +the following errors can occur when writing to the fanotify file descriptor: +.TP +.B EINVAL +Fanotify access permissions are not enabled in the kernel configuration +or the value of +.I response +in the response structure is not valid. +.TP +.B ENOENT +The file descriptor +.I fd +in the response structure is not valid. +This may occur when a response for the permission event has already been +written. +.SH STANDARDS +Linux. +.SH HISTORY +The fanotify API was introduced in Linux 2.6.36 and +enabled in Linux 2.6.37. +fdinfo support was added in Linux 3.8. +.SH NOTES +The fanotify API is available only if the kernel was built with the +.B CONFIG_FANOTIFY +configuration option enabled. +In addition, fanotify permission handling is available only if the +.B CONFIG_FANOTIFY_ACCESS_PERMISSIONS +configuration option is enabled. +.SS Limitations and caveats +Fanotify reports only events that a user-space program triggers through the +filesystem API. +As a result, +it does not catch remote events that occur on network filesystems. +.P +The fanotify API does not report file accesses and modifications that +may occur because of +.BR mmap (2), +.BR msync (2), +and +.BR munmap (2). +.P +Events for directories are created only if the directory itself is opened, +read, and closed. +Adding, removing, or changing children of a marked directory does not create +events for the monitored directory itself. +.P +Fanotify monitoring of directories is not recursive: +to monitor subdirectories under a directory, +additional marks must be created. +The +.B FAN_CREATE +event can be used for detecting when a subdirectory has been created under +a marked directory. +An additional mark must then be set on the newly created subdirectory. +This approach is racy, because it can lose events that occurred inside the +newly created subdirectory, before a mark is added on that subdirectory. +Monitoring mounts offers the capability to monitor a whole directory tree +in a race-free manner. +Monitoring filesystems offers the capability to monitor changes made from +any mount of a filesystem instance in a race-free manner. +.P +The event queue can overflow. +In this case, events are lost. +.SH BUGS +Before Linux 3.19, +.BR fallocate (2) +did not generate fanotify events. +Since Linux 3.19, +.\" commit 820c12d5d6c0890bc93dd63893924a13041fdc35 +calls to +.BR fallocate (2) +generate +.B FAN_MODIFY +events. +.P +As of Linux 3.17, +the following bugs exist: +.IP \[bu] 3 +On Linux, a filesystem object may be accessible through multiple paths, +for example, a part of a filesystem may be remounted using the +.I \-\-bind +option of +.BR mount (8). +A listener that marked a mount will be notified only of events that were +triggered for a filesystem object using the same mount. +Any other event will pass unnoticed. +.IP \[bu] +.\" FIXME . A patch was proposed. +When an event is generated, +no check is made to see whether the user ID of the +receiving process has authorization to read or write the file +before passing a file descriptor for that file. +This poses a security risk, when the +.B CAP_SYS_ADMIN +capability is set for programs executed by unprivileged users. +.IP \[bu] +If a call to +.BR read (2) +processes multiple events from the fanotify queue and an error occurs, +the return value will be the total length of the events successfully +copied to the user-space buffer before the error occurred. +The return value will not be \-1, and +.I errno +will not be set. +Thus, the reading application has no way to detect the error. +.SH EXAMPLES +The two example programs below demonstrate the usage of the fanotify API. +.SS Example program: fanotify_example.c +The first program is an example of fanotify being +used with its event object information passed in the form of a file +descriptor. +The program marks the mount passed as a command-line argument and +waits for events of type +.B FAN_OPEN_PERM +and +.BR FAN_CLOSE_WRITE . +When a permission event occurs, a +.B FAN_ALLOW +response is given. +.P +The following shell session shows an example of +running this program. +This session involved editing the file +.IR /home/user/temp/notes . +Before the file was opened, a +.B FAN_OPEN_PERM +event occurred. +After the file was closed, a +.B FAN_CLOSE_WRITE +event occurred. +Execution of the program ends when the user presses the ENTER key. +.P +.in +4n +.EX +# \fB./fanotify_example /home\fP +Press enter key to terminate. +Listening for events. +FAN_OPEN_PERM: File /home/user/temp/notes +FAN_CLOSE_WRITE: File /home/user/temp/notes +\& +Listening for events stopped. +.EE +.in +.SS Program source: fanotify_example.c +\& +.EX +#define _GNU_SOURCE /* Needed to get O_LARGEFILE definition */ +#include +#include +#include +#include +#include +#include +#include +#include +\& +/* Read all available fanotify events from the file descriptor \[aq]fd\[aq]. */ +\& +static void +handle_events(int fd) +{ + const struct fanotify_event_metadata *metadata; + struct fanotify_event_metadata buf[200]; + ssize_t len; + char path[PATH_MAX]; + ssize_t path_len; + char procfd_path[PATH_MAX]; + struct fanotify_response response; +\& + /* Loop while events can be read from fanotify file descriptor. */ +\& + for (;;) { +\& + /* Read some events. */ +\& + len = read(fd, buf, sizeof(buf)); + if (len == \-1 && errno != EAGAIN) { + perror("read"); + exit(EXIT_FAILURE); + } +\& + /* Check if end of available data reached. */ +\& + if (len <= 0) + break; +\& + /* Point to the first event in the buffer. */ +\& + metadata = buf; +\& + /* Loop over all events in the buffer. */ +\& + while (FAN_EVENT_OK(metadata, len)) { +\& + /* Check that run\-time and compile\-time structures match. */ +\& + if (metadata\->vers != FANOTIFY_METADATA_VERSION) { + fprintf(stderr, + "Mismatch of fanotify metadata version.\en"); + exit(EXIT_FAILURE); + } +\& + /* metadata\->fd contains either FAN_NOFD, indicating a + queue overflow, or a file descriptor (a nonnegative + integer). Here, we simply ignore queue overflow. */ +\& + if (metadata\->fd >= 0) { +\& + /* Handle open permission event. */ +\& + if (metadata\->mask & FAN_OPEN_PERM) { + printf("FAN_OPEN_PERM: "); +\& + /* Allow file to be opened. */ +\& + response.fd = metadata\->fd; + response.response = FAN_ALLOW; + write(fd, &response, sizeof(response)); + } +\& + /* Handle closing of writable file event. */ +\& + if (metadata\->mask & FAN_CLOSE_WRITE) + printf("FAN_CLOSE_WRITE: "); +\& + /* Retrieve and print pathname of the accessed file. */ +\& + snprintf(procfd_path, sizeof(procfd_path), + "/proc/self/fd/%d", metadata\->fd); + path_len = readlink(procfd_path, path, + sizeof(path) \- 1); + if (path_len == \-1) { + perror("readlink"); + exit(EXIT_FAILURE); + } +\& + path[path_len] = \[aq]\e0\[aq]; + printf("File %s\en", path); +\& + /* Close the file descriptor of the event. */ +\& + close(metadata\->fd); + } +\& + /* Advance to next event. */ +\& + metadata = FAN_EVENT_NEXT(metadata, len); + } + } +} +\& +int +main(int argc, char *argv[]) +{ + char buf; + int fd, poll_num; + nfds_t nfds; + struct pollfd fds[2]; +\& + /* Check mount point is supplied. */ +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s MOUNT\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + printf("Press enter key to terminate.\en"); +\& + /* Create the file descriptor for accessing the fanotify API. */ +\& + fd = fanotify_init(FAN_CLOEXEC | FAN_CLASS_CONTENT | FAN_NONBLOCK, + O_RDONLY | O_LARGEFILE); + if (fd == \-1) { + perror("fanotify_init"); + exit(EXIT_FAILURE); + } +\& + /* Mark the mount for: + \- permission events before opening files + \- notification events after closing a write\-enabled + file descriptor. */ +\& + if (fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT, + FAN_OPEN_PERM | FAN_CLOSE_WRITE, AT_FDCWD, + argv[1]) == \-1) { + perror("fanotify_mark"); + exit(EXIT_FAILURE); + } +\& + /* Prepare for polling. */ +\& + nfds = 2; +\& + fds[0].fd = STDIN_FILENO; /* Console input */ + fds[0].events = POLLIN; +\& + fds[1].fd = fd; /* Fanotify input */ + fds[1].events = POLLIN; +\& + /* This is the loop to wait for incoming events. */ +\& + printf("Listening for events.\en"); +\& + while (1) { + poll_num = poll(fds, nfds, \-1); + if (poll_num == \-1) { + if (errno == EINTR) /* Interrupted by a signal */ + continue; /* Restart poll() */ +\& + perror("poll"); /* Unexpected error */ + exit(EXIT_FAILURE); + } +\& + if (poll_num > 0) { + if (fds[0].revents & POLLIN) { +\& + /* Console input is available: empty stdin and quit. */ +\& + while (read(STDIN_FILENO, &buf, 1) > 0 && buf != \[aq]\en\[aq]) + continue; + break; + } +\& + if (fds[1].revents & POLLIN) { +\& + /* Fanotify events are available. */ +\& + handle_events(fd); + } + } + } +\& + printf("Listening for events stopped.\en"); + exit(EXIT_SUCCESS); +} +.EE +.\" +.SS Example program: fanotify_fid.c +The second program is an example of fanotify being used with a group that +identifies objects by file handles. +The program marks the filesystem object that is passed as +a command-line argument +and waits until an event of type +.B FAN_CREATE +has occurred. +The event mask indicates which type of filesystem object\[em]either +a file or a directory\[em]was created. +Once all events have been read from the buffer and processed accordingly, +the program simply terminates. +.P +The following shell sessions show two different invocations of +this program, with different actions performed on a watched object. +.P +The first session shows a mark being placed on +.IR /home/user . +This is followed by the creation of a regular file, +.IR /home/user/testfile.txt . +This results in a +.B FAN_CREATE +event being generated and reported against the file's parent watched +directory object and with the created file name. +Program execution ends once all events captured within the buffer have +been processed. +.P +.in +4n +.EX +# \fB./fanotify_fid /home/user\fP +Listening for events. +FAN_CREATE (file created): + Directory /home/user has been modified. + Entry \[aq]testfile.txt\[aq] is not a subdirectory. +All events processed successfully. Program exiting. +\& +$ \fBtouch /home/user/testfile.txt\fP # In another terminal +.EE +.in +.P +The second session shows a mark being placed on +.IR /home/user . +This is followed by the creation of a directory, +.IR /home/user/testdir . +This specific action results in a +.B FAN_CREATE +event being generated and is reported with the +.B FAN_ONDIR +flag set and with the created directory name. +.P +.in +4n +.EX +# \fB./fanotify_fid /home/user\fP +Listening for events. +FAN_CREATE | FAN_ONDIR (subdirectory created): + Directory /home/user has been modified. + Entry \[aq]testdir\[aq] is a subdirectory. +All events processed successfully. Program exiting. +\& +$ \fBmkdir \-p /home/user/testdir\fP # In another terminal +.EE +.in +.SS Program source: fanotify_fid.c +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +#define BUF_SIZE 256 +\& +int +main(int argc, char *argv[]) +{ + int fd, ret, event_fd, mount_fd; + ssize_t len, path_len; + char path[PATH_MAX]; + char procfd_path[PATH_MAX]; + char events_buf[BUF_SIZE]; + struct file_handle *file_handle; + struct fanotify_event_metadata *metadata; + struct fanotify_event_info_fid *fid; + const char *file_name; + struct stat sb; +\& + if (argc != 2) { + fprintf(stderr, "Invalid number of command line arguments.\en"); + exit(EXIT_FAILURE); + } +\& + mount_fd = open(argv[1], O_DIRECTORY | O_RDONLY); + if (mount_fd == \-1) { + perror(argv[1]); + exit(EXIT_FAILURE); + } +\& + /* Create an fanotify file descriptor with FAN_REPORT_DFID_NAME as + a flag so that program can receive fid events with directory + entry name. */ +\& + fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_DFID_NAME, 0); + if (fd == \-1) { + perror("fanotify_init"); + exit(EXIT_FAILURE); + } +\& + /* Place a mark on the filesystem object supplied in argv[1]. */ +\& + ret = fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_ONLYDIR, + FAN_CREATE | FAN_ONDIR, + AT_FDCWD, argv[1]); + if (ret == \-1) { + perror("fanotify_mark"); + exit(EXIT_FAILURE); + } +\& + printf("Listening for events.\en"); +\& + /* Read events from the event queue into a buffer. */ +\& + len = read(fd, events_buf, sizeof(events_buf)); + if (len == \-1 && errno != EAGAIN) { + perror("read"); + exit(EXIT_FAILURE); + } +\& + /* Process all events within the buffer. */ +\& + for (metadata = (struct fanotify_event_metadata *) events_buf; + FAN_EVENT_OK(metadata, len); + metadata = FAN_EVENT_NEXT(metadata, len)) { + fid = (struct fanotify_event_info_fid *) (metadata + 1); + file_handle = (struct file_handle *) fid\->handle; +\& + /* Ensure that the event info is of the correct type. */ +\& + if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_FID || + fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID) { + file_name = NULL; + } else if (fid\->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID_NAME) { + file_name = file_handle\->f_handle + + file_handle\->handle_bytes; + } else { + fprintf(stderr, "Received unexpected event info type.\en"); + exit(EXIT_FAILURE); + } +\& + if (metadata\->mask == FAN_CREATE) + printf("FAN_CREATE (file created):\en"); +\& + if (metadata\->mask == (FAN_CREATE | FAN_ONDIR)) + printf("FAN_CREATE | FAN_ONDIR (subdirectory created):\en"); +\& + /* metadata\->fd is set to FAN_NOFD when the group identifies + objects by file handles. To obtain a file descriptor for + the file object corresponding to an event you can use the + struct file_handle that\[aq]s provided within the + fanotify_event_info_fid in conjunction with the + open_by_handle_at(2) system call. A check for ESTALE is + done to accommodate for the situation where the file handle + for the object was deleted prior to this system call. */ +\& + event_fd = open_by_handle_at(mount_fd, file_handle, O_RDONLY); + if (event_fd == \-1) { + if (errno == ESTALE) { + printf("File handle is no longer valid. " + "File has been deleted\en"); + continue; + } else { + perror("open_by_handle_at"); + exit(EXIT_FAILURE); + } + } +\& + snprintf(procfd_path, sizeof(procfd_path), "/proc/self/fd/%d", + event_fd); +\& + /* Retrieve and print the path of the modified dentry. */ +\& + path_len = readlink(procfd_path, path, sizeof(path) \- 1); + if (path_len == \-1) { + perror("readlink"); + exit(EXIT_FAILURE); + } +\& + path[path_len] = \[aq]\e0\[aq]; + printf("\etDirectory \[aq]%s\[aq] has been modified.\en", path); +\& + if (file_name) { + ret = fstatat(event_fd, file_name, &sb, 0); + if (ret == \-1) { + if (errno != ENOENT) { + perror("fstatat"); + exit(EXIT_FAILURE); + } + printf("\etEntry \[aq]%s\[aq] does not exist.\en", file_name); + } else if ((sb.st_mode & S_IFMT) == S_IFDIR) { + printf("\etEntry \[aq]%s\[aq] is a subdirectory.\en", file_name); + } else { + printf("\etEntry \[aq]%s\[aq] is not a subdirectory.\en", + file_name); + } + } +\& + /* Close associated file descriptor for this event. */ +\& + close(event_fd); + } +\& + printf("All events processed successfully. Program exiting.\en"); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.ad l +.BR fanotify_init (2), +.BR fanotify_mark (2), +.BR inotify (7) diff --git a/man/man7/feature_test_macros.7 b/man/man7/feature_test_macros.7 new file mode 100644 index 0000000..591c139 --- /dev/null +++ b/man/man7/feature_test_macros.7 @@ -0,0 +1,937 @@ +.\" This manpage is Copyright (C) 2006, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH feature_test_macros 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +feature_test_macros \- feature test macros +.SH DESCRIPTION +Feature test macros allow the programmer to control the definitions that +are exposed by system header files when a program is compiled. +.P +.B NOTE: +In order to be effective, a feature test macro +.IR "must be defined before including any header files" . +This can be done either in the compilation command +.RI ( "cc \-DMACRO=value" ) +or by defining the macro within the source code before +including any headers. +The requirement that the macro must be defined before including any +header file exists because header files may freely include one another. +Thus, for example, in the following lines, defining the +.B _GNU_SOURCE +macro may have no effect because the header +.I +itself includes +.I +(POSIX explicitly allows this): +.P +.in +4n +.EX +#include +#define _GNU_SOURCE +#include +.EE +.in +.P +Some feature test macros are useful for creating portable applications, +by preventing nonstandard definitions from being exposed. +Other macros can be used to expose nonstandard definitions that +are not exposed by default. +.P +The precise effects of each of the feature test macros described below +can be ascertained by inspecting the +.I +header file. +.BR Note : +applications do +.I not +need to directly include +.IR ; +indeed, doing so is actively discouraged. +See NOTES. +.SS Specification of feature test macro requirements in manual pages +When a function requires that a feature test macro is defined, +the manual page SYNOPSIS typically includes a note of the following form +(this example from the +.BR acct (2) +manual page): +.P +.RS +.B #include +.P +.BI "int acct(const char *" filename ); +.P +.RS -4 +.EX +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.EE +.RE +.P +.BR acct (): +_BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.RE +.P +The +.B || +means that in order to obtain the declaration of +.BR acct (2) +from +.IR , +.I either +of the following macro +definitions must be made before including any header files: +.P +.in +4n +.EX +#define _BSD_SOURCE +#define _XOPEN_SOURCE /* or any value < 500 */ +.EE +.in +.P +Alternatively, equivalent definitions can be included in the +compilation command: +.P +.in +4n +.EX +cc \-D_BSD_SOURCE +cc \-D_XOPEN_SOURCE # Or any value < 500 +.EE +.in +.P +Note that, as described below, +.BR "some feature test macros are defined by default" , +so that it may not always be necessary to +explicitly specify the feature test macro(s) shown in the +SYNOPSIS. +.P +In a few cases, manual pages use a shorthand for expressing the +feature test macro requirements (this example from +.BR readahead (2)): +.P +.RS +4 +.EX +.B #define _GNU_SOURCE +.B #define _FILE_OFFSET_BITS 64 +.B #include +.P +.BI "ssize_t readahead(int " fd ", off_t *" offset ", size_t " count ); +.EE +.RE +.P +This format is employed when the feature test macros ensure +that the proper function declarations are visible, +and the macros are not defined by default. +.SS Feature test macros understood by glibc +The paragraphs below explain how feature test macros are handled +in glibc 2.\fIx\fP, +.I x +> 0. +.P +First, though, a summary of a few details for the impatient: +.IP \[bu] 3 +The macros that you most likely need to use in modern source code are +.B _POSIX_C_SOURCE +(for definitions from various versions of POSIX.1), +.B _XOPEN_SOURCE +(for definitions from various versions of SUS), +.B _GNU_SOURCE +(for GNU and/or Linux specific stuff), and +.B _DEFAULT_SOURCE +(to get definitions that would normally be provided by default). +.IP \[bu] +Certain macros are defined with default values. +Thus, although one or more macros may be indicated as being +required in the SYNOPSIS of a man page, +it may not be necessary to define them explicitly. +Full details of the defaults are given later in this man page. +.IP \[bu] +Defining +.B _XOPEN_SOURCE +with a value of 600 or greater produces the same effects as defining +.B _POSIX_C_SOURCE +with a value of 200112L or greater. +Where one sees +.IP +.in +4n +.EX +_POSIX_C_SOURCE >= 200112L +.EE +.in +.IP +in the feature test macro requirements in the SYNOPSIS of a man page, +it is implicit that the following has the same effect: +.IP +.in +4n +.EX +_XOPEN_SOURCE >= 600 +.EE +.in +.IP \[bu] +Defining +.B _XOPEN_SOURCE +with a value of 700 or greater produces the same effects as defining +.B _POSIX_C_SOURCE +with a value of 200809L or greater. +Where one sees +.IP +.in +4n +.EX +_POSIX_C_SOURCE >= 200809L +.EE +.in +.IP +in the feature test macro requirements in the SYNOPSIS of a man page, +it is implicit that the following has the same effect: +.IP +.in +4n +.EX +_XOPEN_SOURCE >= 700 +.EE +.in +.\" The details in glibc 2.0 are simpler, but combining a +.\" a description of them with the details in later glibc versions +.\" would make for a complicated description. +.P +glibc understands the following feature test macros: +.TP +.B __STRICT_ANSI__ +ISO Standard C. +This macro is implicitly defined by +.BR gcc (1) +when invoked with, for example, the +.I \-std=c99 +or +.I \-ansi +flag. +.TP +.B _POSIX_C_SOURCE +Defining this macro causes header files to expose definitions as follows: +.RS +.IP \[bu] 3 +The value 1 exposes definitions conforming to POSIX.1-1990 and +ISO C (1990). +.IP \[bu] +The value 2 or greater additionally exposes +definitions for POSIX.2-1992. +.IP \[bu] +The value 199309L or greater additionally exposes +definitions for POSIX.1b (real-time extensions). +.\" 199506L functionality is available only since glibc 2.1 +.IP \[bu] +The value 199506L or greater additionally exposes +definitions for POSIX.1c (threads). +.IP \[bu] +(Since glibc 2.3.3) +The value 200112L or greater additionally exposes definitions corresponding +to the POSIX.1-2001 base specification (excluding the XSI extension). +This value also causes C95 (since glibc 2.12) and +C99 (since glibc 2.10) features to be exposed +(in other words, the equivalent of defining +.BR _ISOC99_SOURCE ). +.IP \[bu] +(Since glibc 2.10) +The value 200809L or greater additionally exposes definitions corresponding +to the POSIX.1-2008 base specification (excluding the XSI extension). +.RE +.TP +.B _POSIX_SOURCE +Defining this obsolete macro with any value is equivalent to defining +.B _POSIX_C_SOURCE +with the value 1. +.IP +Since this macro is obsolete, +its usage is generally not documented when discussing +feature test macro requirements in the man pages. +.TP +.B _XOPEN_SOURCE +Defining this macro causes header files to expose definitions as follows: +.RS +.IP \[bu] 3 +Defining with any value exposes +definitions conforming to POSIX.1, POSIX.2, and XPG4. +.IP \[bu] +The value 500 or greater additionally exposes +definitions for SUSv2 (UNIX 98). +.IP \[bu] +(Since glibc 2.2) The value 600 or greater additionally exposes +definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification +plus the XSI extension) and C99 definitions. +.IP \[bu] +(Since glibc 2.10) The value 700 or greater additionally exposes +definitions for SUSv4 (i.e., the POSIX.1-2008 base specification +plus the XSI extension). +.RE +.IP +If +.B __STRICT_ANSI__ +is not defined, or +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 500 +.I and +neither +.B _POSIX_SOURCE +nor +.B _POSIX_C_SOURCE +is explicitly defined, then +the following macros are implicitly defined: +.RS +.IP \[bu] 3 +.B _POSIX_SOURCE +is defined with the value 1. +.IP \[bu] +.B _POSIX_C_SOURCE +is defined, according to the value of +.BR _XOPEN_SOURCE : +.RS +.TP +.BR _XOPEN_SOURCE " < 500" +.B _POSIX_C_SOURCE +is defined with the value 2. +.TP +.RB "500 <= " _XOPEN_SOURCE " < 600" +.B _POSIX_C_SOURCE +is defined with the value 199506L. +.TP +.RB "600 <= " _XOPEN_SOURCE " < 700" +.B _POSIX_C_SOURCE +is defined with the value 200112L. +.TP +.RB "700 <= " _XOPEN_SOURCE " (since glibc 2.10)" +.B _POSIX_C_SOURCE +is defined with the value 200809L. +.RE +.RE +.IP +In addition, defining +.B _XOPEN_SOURCE +with a value of 500 or greater produces the same effects as defining +.BR _XOPEN_SOURCE_EXTENDED . +.TP +.B _XOPEN_SOURCE_EXTENDED +If this macro is defined, +.I and +.B _XOPEN_SOURCE +is defined, then expose definitions corresponding to the XPG4v2 +(SUSv1) UNIX extensions (UNIX 95). +Defining +.B _XOPEN_SOURCE +with a value of 500 or more also produces the same effect as defining +.BR _XOPEN_SOURCE_EXTENDED . +Use of +.B _XOPEN_SOURCE_EXTENDED +in new source code should be avoided. +.IP +Since defining +.B _XOPEN_SOURCE +with a value of 500 or more has the same effect as defining +.BR _XOPEN_SOURCE_EXTENDED , +the latter (obsolete) feature test macro is generally not described in the +SYNOPSIS in man pages. +.TP +.BR _ISOC99_SOURCE " (since glibc 2.1.3)" +Exposes declarations consistent with the ISO C99 standard. +.IP +Earlier glibc 2.1.x versions recognized an equivalent macro named +.B _ISOC9X_SOURCE +(because the C99 standard had not then been finalized). +Although the use of this macro is obsolete, glibc continues +to recognize it for backward compatibility. +.IP +Defining +.B _ISOC99_SOURCE +also exposes ISO C (1990) Amendment 1 ("C95") definitions. +(The primary change in C95 was support for international character sets.) +.IP +Invoking the C compiler with the option +.I \-std=c99 +produces the same effects as defining this macro. +.TP +.BR _ISOC11_SOURCE " (since glibc 2.16)" +Exposes declarations consistent with the ISO C11 standard. +Defining this macro also enables C99 and C95 features (like +.BR _ISOC99_SOURCE ). +.IP +Invoking the C compiler with the option +.I \-std=c11 +produces the same effects as defining this macro. +.TP +.B _LARGEFILE64_SOURCE +Expose definitions for the alternative API specified by the +LFS (Large File Summit) as a "transitional extension" to the +Single UNIX Specification. +(See +.UR http:\:/\:/opengroup.org\:/platform\:/lfs.html +.UE .) +The alternative API consists of a set of new objects +(i.e., functions and types) whose names are suffixed with "64" +(e.g., +.I off64_t +versus +.IR off_t , +.BR lseek64 () +versus +.BR lseek (), +etc.). +New programs should not employ this macro; instead +.I _FILE_OFFSET_BITS=64 +should be employed. +.TP +.B _LARGEFILE_SOURCE +This macro was historically used to expose certain functions (specifically +.BR fseeko (3) +and +.BR ftello (3)) +that address limitations of earlier APIs +.RB ( fseek (3) +and +.BR ftell (3)) +that use +.I long +for file offsets. +This macro is implicitly defined if +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 500. +New programs should not employ this macro; +defining +.B _XOPEN_SOURCE +as just described or defining +.B _FILE_OFFSET_BITS +with the value 64 is the preferred mechanism to achieve the same result. +.TP +.B _FILE_OFFSET_BITS +Defining this macro with the value 64 +automatically converts references to 32-bit functions and data types +related to file I/O and filesystem operations into references to +their 64-bit counterparts. +This is useful for performing I/O on large files (> 2 Gigabytes) +on 32-bit systems. +It is also useful when calling functions like +.BR copy_file_range (2) +that were added more recently and that come only in 64-bit flavors. +(Defining this macro permits correctly written programs to use +large files with only a recompilation being required.) +.IP +64-bit systems naturally permit file sizes greater than 2 Gigabytes, +and on those systems this macro has no effect. +.TP +.B _TIME_BITS +Defining this macro with the value 64 +changes the width of +.BR time_t (3type) +to 64-bit which allows handling of timestamps beyond +2038. +It is closely related to +.B _FILE_OFFSET_BITS +and depending on implementation, may require it set. +This macro is available as of glibc 2.34. +.TP +.BR _BSD_SOURCE " (deprecated since glibc 2.20)" +Defining this macro with any value causes header files to expose +BSD-derived definitions. +.IP +In glibc versions up to and including 2.18, +defining this macro also causes BSD definitions to be preferred in +some situations where standards conflict, unless one or more of +.BR _SVID_SOURCE , +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.BR _XOPEN_SOURCE_EXTENDED , +or +.B _GNU_SOURCE +is defined, in which case BSD definitions are disfavored. +Since glibc 2.19, +.B _BSD_SOURCE +no longer causes BSD definitions to be preferred in case of conflicts. +.IP +Since glibc 2.20, this macro is deprecated. +.\" commit c941736c92fa3a319221f65f6755659b2a5e0a20 +.\" commit 498afc54dfee41d33ba519f496e96480badace8e +.\" commit acd7f096d79c181866d56d4aaf3b043e741f1e2c +It now has the same effect as defining +.BR _DEFAULT_SOURCE , +but generates a compile-time warning (unless +.B _DEFAULT_SOURCE +.\" commit ade40b10ff5fa59a318cf55b9d8414b758e8df78 +is also defined). +Use +.B _DEFAULT_SOURCE +instead. +To allow code that requires +.B _BSD_SOURCE +in glibc 2.19 and earlier and +.B _DEFAULT_SOURCE +in glibc 2.20 and later to compile without warnings, define +.I both +.B _BSD_SOURCE +and +.BR _DEFAULT_SOURCE . +.TP +.BR _SVID_SOURCE " (deprecated since glibc 2.20)" +Defining this macro with any value causes header files to expose +System V-derived definitions. +(SVID == System V Interface Definition; see +.BR standards (7).) +.IP +Since glibc 2.20, this macro is deprecated in the same fashion as +.BR _BSD_SOURCE . +.TP +.BR _DEFAULT_SOURCE " (since glibc 2.19)" +This macro can be defined to ensure that the "default" +definitions are provided even when the defaults would otherwise +be disabled, +as happens when individual macros are explicitly defined, +or the compiler is invoked in one of its "standard" modes (e.g., +.IR cc\~\-std=c99 ). +Defining +.B _DEFAULT_SOURCE +without defining other individual macros +or invoking the compiler in one of its "standard" modes has no effect. +.IP +The "default" definitions comprise those required by POSIX.1-2008 and ISO C99, +as well as various definitions originally derived from BSD and System V. +On glibc 2.19 and earlier, these defaults were approximately equivalent +to explicitly defining the following: +.IP +.in +4n +.EX +cc \-D_BSD_SOURCE \-D_SVID_SOURCE \-D_POSIX_C_SOURCE=200809 +.EE +.in +.TP +.BR _ATFILE_SOURCE " (since glibc 2.4)" +Defining this macro with any value causes header files to expose +declarations of a range of functions with the suffix "at"; +see +.BR openat (2). +Since glibc 2.10, this macro is also implicitly defined if +.B _POSIX_C_SOURCE +is defined with a value greater than or equal to 200809L. +.TP +.B _GNU_SOURCE +Defining this macro (with any value) implicitly defines +.BR _ATFILE_SOURCE , +.BR _LARGEFILE64_SOURCE , +.BR _ISOC99_SOURCE , +.BR _XOPEN_SOURCE_EXTENDED , +.BR _POSIX_SOURCE , +.B _POSIX_C_SOURCE +with the value 200809L +(200112L before glibc 2.10; +199506L before glibc 2.5; +199309L before glibc 2.1) +and +.B _XOPEN_SOURCE +with the value 700 +(600 before glibc 2.10; +500 before glibc 2.2). +In addition, various GNU-specific extensions are also exposed. +.IP +Since glibc 2.19, defining +.B _GNU_SOURCE +also has the effect of implicitly defining +.BR _DEFAULT_SOURCE . +Before glibc 2.20, defining +.B _GNU_SOURCE +also had the effect of implicitly defining +.B _BSD_SOURCE +and +.BR _SVID_SOURCE . +.TP +.B _REENTRANT +Historically, on various C libraries +it was necessary to define this macro in all +multithreaded code. +.\" Zack Weinberg +.\" There did once exist C libraries where it was necessary. The ones +.\" I remember were proprietary Unix vendor libcs from the mid-1990s +.\" You would get completely unlocked stdio without _REENTRANT. +(Some C libraries may still require this.) +In glibc, +this macro also exposed definitions of certain reentrant functions. +.IP +However, glibc has been thread-safe by default for many years; +since glibc 2.3, the only effect of defining +.B _REENTRANT +has been to enable one or two of the same declarations that +are also enabled by defining +.B _POSIX_C_SOURCE +with a value of 199606L or greater. +.IP +.B _REENTRANT +is now obsolete. +In glibc 2.25 and later, defining +.B _REENTRANT +is equivalent to defining +.B _POSIX_C_SOURCE +with the value 199606L. +If a higher POSIX conformance level is +selected by any other means (such as +.B _POSIX_C_SOURCE +itself, +.BR _XOPEN_SOURCE , +.BR _DEFAULT_SOURCE , +or +.BR _GNU_SOURCE ), +then defining +.B _REENTRANT +has no effect. +.IP +This macro is automatically defined if one compiles with +.IR cc\~\-pthread . +.TP +.B _THREAD_SAFE +Synonym for the (deprecated) +.BR _REENTRANT , +provided for compatibility with some other implementations. +.TP +.BR _FORTIFY_SOURCE " (since glibc 2.3.4)" +.\" For more detail, see: +.\" http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html +.\" [PATCH] Object size checking to prevent (some) buffer overflows +.\" * From: Jakub Jelinek +.\" * To: gcc-patches at gcc dot gnu dot org +.\" * Date: Tue, 21 Sep 2004 04:16:40 -0400 +Defining this macro causes some lightweight checks to be performed +to detect some buffer overflow errors when employing +various string and memory manipulation functions (for example, +.BR memcpy (3), +.BR memset (3), +.BR stpcpy (3), +.BR strcpy (3), +.BR strncpy (3), +.BR strcat (3), +.BR strncat (3), +.BR sprintf (3), +.BR snprintf (3), +.BR vsprintf (3), +.BR vsnprintf (3), +.BR gets (3), +and wide character variants thereof). +For some functions, argument consistency is checked; +for example, a check is made that +.BR open (2) +has been supplied with a +.I mode +argument when the specified flags include +.BR O_CREAT . +Not all problems are detected, just some common cases. +.\" Look for __USE_FORTIFY_LEVEL in the header files +.IP +If +.B _FORTIFY_SOURCE +is set to 1, with compiler optimization level 1 +.RI ( "gcc\ \-O1" ) +and above, checks that shouldn't change the behavior of +conforming programs are performed. +With +.B _FORTIFY_SOURCE +set to 2, some more checking is added, but +some conforming programs might fail. +.\" For example, given the following code +.\" int d; +.\" char buf[1000], buf[1000]; +.\" strcpy(fmt, "Hello world\n%n"); +.\" snprintf(buf, sizeof(buf), fmt, &d); +.\" +.\" Compiling with "gcc -D_FORTIFY_SOURCE=2 -O1" and then running will +.\" cause the following diagnostic at run time at the snprintf() call +.\" +.\" *** %n in writable segment detected *** +.\" Aborted (core dumped) +.\" +.IP +Some of the checks can be performed at compile time +(via macros logic implemented in header files), +and result in compiler warnings; +other checks take place at run time, +and result in a run-time error if the check fails. +.IP +With +.B _FORTIFY_SOURCE +set to 3, additional checking is added to intercept +some function calls used with an argument of variable size +where the compiler can deduce an upper bound for its value. +For example, a program where +.BR malloc (3)'s +size argument is variable +can now be fortified. +.IP +Use of this macro requires compiler support, available since +gcc 4.0 and clang 2.6. +Use of +.B _FORTIFY_SOURCE +set to 3 requires gcc 12.0 or later, or clang 9.0 or later, +in conjunction with glibc 2.33 or later. +.\" glibc is not an absolute requirement (gcc has libssp; NetBSD/newlib +.\" and Darwin each have their own implementation), but let's keep it +.\" simple. +.SS Default definitions, implicit definitions, and combining definitions +If no feature test macros are explicitly defined, +then the following feature test macros are defined by default: +.B _BSD_SOURCE +(in glibc 2.19 and earlier), +.B _SVID_SOURCE +(in glibc 2.19 and earlier), +.B _DEFAULT_SOURCE +(since glibc 2.19), +.BR _POSIX_SOURCE , +and +.BR _POSIX_C_SOURCE =200809L +(200112L before glibc 2.10; +199506L before glibc 2.4; +199309L before glibc 2.1). +.P +If any of +.BR __STRICT_ANSI__ , +.BR _ISOC99_SOURCE , +.B _ISOC11_SOURCE +(since glibc 2.18), +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.B _XOPEN_SOURCE_EXTENDED +(in glibc 2.11 and earlier), +.B _BSD_SOURCE +(in glibc 2.19 and earlier), +or +.B _SVID_SOURCE +(in glibc 2.19 and earlier) +is explicitly defined, then +.BR _BSD_SOURCE , +.BR _SVID_SOURCE , +and +.B _DEFAULT_SOURCE +are not defined by default. +.P +If +.B _POSIX_SOURCE +and +.B _POSIX_C_SOURCE +are not explicitly defined, +and either +.B __STRICT_ANSI__ +is not defined or +.B _XOPEN_SOURCE +is defined with a value of 500 or more, then +.IP \[bu] 3 +.B _POSIX_SOURCE +is defined with the value 1; and +.IP \[bu] +.B _POSIX_C_SOURCE +is defined with one of the following values: +.RS +.IP \[bu] 3 +2, +if +.B _XOPEN_SOURCE +is defined with a value less than 500; +.IP \[bu] +199506L, +if +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 500 and less than 600; +or +.IP \[bu] +(since glibc 2.4) 200112L, +if +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 600 and less than 700. +.IP \[bu] +(Since glibc 2.10) +200809L, +if +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 700. +.IP \[bu] +Older versions of glibc do not know about the values +200112L and 200809L for +.BR _POSIX_C_SOURCE , +and the setting of this macro will depend on the glibc version. +.IP \[bu] +If +.B _XOPEN_SOURCE +is undefined, then the setting of +.B _POSIX_C_SOURCE +depends on the glibc version: +199506L, before glibc 2.4; +200112L, since glibc 2.4 to glibc 2.9; and +200809L, since glibc 2.10. +.RE +.P +Multiple macros can be defined; the results are additive. +.SH STANDARDS +POSIX.1 specifies +.BR _POSIX_C_SOURCE , +.BR _POSIX_SOURCE , +and +.BR _XOPEN_SOURCE . +.P +.B _FILE_OFFSET_BITS +is not specified by any standard, +but is employed on some other implementations. +.P +.BR _BSD_SOURCE , +.BR _SVID_SOURCE , +.BR _DEFAULT_SOURCE , +.BR _ATFILE_SOURCE , +.BR _GNU_SOURCE , +.BR _FORTIFY_SOURCE , +.BR _REENTRANT , +and +.B _THREAD_SAFE +are specific to glibc. +.SH HISTORY +.B _XOPEN_SOURCE_EXTENDED +was specified by XPG4v2 (aka SUSv1), but is not present in SUSv2 and later. +.SH NOTES +.I +is a Linux/glibc-specific header file. +Other systems have an analogous file, but typically with a different name. +This header file is automatically included by other header files as +required: it is not necessary to explicitly include it in order to +employ feature test macros. +.P +According to which of the above feature test macros are defined, +.I +internally defines various other macros that are checked by +other glibc header files. +These macros have names prefixed by two underscores (e.g., +.BR __USE_MISC ). +Programs should +.I never +define these macros directly: +instead, the appropriate feature test macro(s) from the +list above should be employed. +.SH EXAMPLES +The program below can be used to explore how the various +feature test macros are set depending on the glibc version +and what feature test macros are explicitly set. +The following shell session, on a system with glibc 2.10, +shows some examples of what we would see: +.P +.in +4n +.EX +$ \fBcc ftm.c\fP +$ \fB./a.out\fP +_POSIX_SOURCE defined +_POSIX_C_SOURCE defined: 200809L +_BSD_SOURCE defined +_SVID_SOURCE defined +_ATFILE_SOURCE defined +$ \fBcc \-D_XOPEN_SOURCE=500 ftm.c\fP +$ \fB./a.out\fP +_POSIX_SOURCE defined +_POSIX_C_SOURCE defined: 199506L +_XOPEN_SOURCE defined: 500 +$ \fBcc \-D_GNU_SOURCE ftm.c\fP +$ \fB./a.out\fP +_POSIX_SOURCE defined +_POSIX_C_SOURCE defined: 200809L +_ISOC99_SOURCE defined +_XOPEN_SOURCE defined: 700 +_XOPEN_SOURCE_EXTENDED defined +_LARGEFILE64_SOURCE defined +_BSD_SOURCE defined +_SVID_SOURCE defined +_ATFILE_SOURCE defined +_GNU_SOURCE defined +.EE +.in +.SS Program source +\& +.EX +/* ftm.c */ +\& +#include +#include +#include +#include +\& +int +main(int argc, char *argv[]) +{ +#ifdef _POSIX_SOURCE + printf("_POSIX_SOURCE defined\en"); +#endif +\& +#ifdef _POSIX_C_SOURCE + printf("_POSIX_C_SOURCE defined: %jdL\en", + (intmax_t) _POSIX_C_SOURCE); +#endif +\& +#ifdef _ISOC99_SOURCE + printf("_ISOC99_SOURCE defined\en"); +#endif +\& +#ifdef _ISOC11_SOURCE + printf("_ISOC11_SOURCE defined\en"); +#endif +\& +#ifdef _XOPEN_SOURCE + printf("_XOPEN_SOURCE defined: %d\en", _XOPEN_SOURCE); +#endif +\& +#ifdef _XOPEN_SOURCE_EXTENDED + printf("_XOPEN_SOURCE_EXTENDED defined\en"); +#endif +\& +#ifdef _LARGEFILE64_SOURCE + printf("_LARGEFILE64_SOURCE defined\en"); +#endif +\& +#ifdef _FILE_OFFSET_BITS + printf("_FILE_OFFSET_BITS defined: %d\en", _FILE_OFFSET_BITS); +#endif +\& +#ifdef _TIME_BITS + printf("_TIME_BITS defined: %d\en", _TIME_BITS); +#endif +\& +#ifdef _BSD_SOURCE + printf("_BSD_SOURCE defined\en"); +#endif +\& +#ifdef _SVID_SOURCE + printf("_SVID_SOURCE defined\en"); +#endif +\& +#ifdef _DEFAULT_SOURCE + printf("_DEFAULT_SOURCE defined\en"); +#endif +\& +#ifdef _ATFILE_SOURCE + printf("_ATFILE_SOURCE defined\en"); +#endif +\& +#ifdef _GNU_SOURCE + printf("_GNU_SOURCE defined\en"); +#endif +\& +#ifdef _REENTRANT + printf("_REENTRANT defined\en"); +#endif +\& +#ifdef _THREAD_SAFE + printf("_THREAD_SAFE defined\en"); +#endif +\& +#ifdef _FORTIFY_SOURCE + printf("_FORTIFY_SOURCE defined\en"); +#endif +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR libc (7), +.BR standards (7), +.BR system_data_types (7) +.P +The section "Feature Test Macros" under +.IR "info libc" . +.\" But beware: the info libc document is out of date (Jul 07, mtk) +.P +.I /usr/include/features.h diff --git a/man/man7/fifo.7 b/man/man7/fifo.7 new file mode 100644 index 0000000..f9480d9 --- /dev/null +++ b/man/man7/fifo.7 @@ -0,0 +1,70 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Claus Fischer. +.\" +.\" 990620 - page created - aeb@cwi.nl +.\" +.TH fifo 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +fifo \- first-in first-out special file, named pipe +.SH DESCRIPTION +A FIFO special file (a named pipe) is similar to a pipe, +except that it is accessed as part of the filesystem. +It can be opened by multiple processes for reading or +writing. +When processes are exchanging data via the FIFO, +the kernel passes all data internally without writing it +to the filesystem. +Thus, the FIFO special file has no +contents on the filesystem; the filesystem entry merely +serves as a reference point so that processes can access +the pipe using a name in the filesystem. +.P +The kernel maintains exactly one pipe object for each +FIFO special file that is opened by at least one process. +The FIFO must be opened on both ends (reading and writing) +before data can be passed. +Normally, opening the FIFO blocks +until the other end is opened also. +.P +A process can open a FIFO in nonblocking mode. +In this +case, opening for read-only succeeds even if no one has +opened on the write side yet and opening for write-only +fails with +.B ENXIO +(no such device or address) unless the other +end has already been opened. +.P +Under Linux, opening a FIFO for read and write will succeed +both in blocking and nonblocking mode. +POSIX leaves this +behavior undefined. +This can be used to open a FIFO for +writing while there are no readers available. +A process +that uses both ends of the connection in order to communicate +with itself should be very careful to avoid deadlocks. +.SH NOTES +For details of the semantics of I/O on FIFOs, see +.BR pipe (7). +.P +When a process tries to write to a FIFO that is not opened +for read on the other side, the process is sent a +.B SIGPIPE +signal. +.P +FIFO special files can be created by +.BR mkfifo (3), +and are indicated by +.I ls\~\-l +with the file type \[aq]p\[aq]. +.SH SEE ALSO +.BR mkfifo (1), +.BR open (2), +.BR pipe (2), +.BR sigaction (2), +.BR signal (2), +.BR socketpair (2), +.BR mkfifo (3), +.BR pipe (7) diff --git a/man/man7/futex.7 b/man/man7/futex.7 new file mode 100644 index 0000000..c12268a --- /dev/null +++ b/man/man7/futex.7 @@ -0,0 +1,121 @@ +.\" This manpage has been automatically generated by docbook2man +.\" from a DocBook document. This tool can be found at: +.\" +.\" Please send any bug reports, improvements, comments, patches, +.\" etc. to Steve Cheng . +.\" +.\" SPDX-License-Identifier: MIT +.\" +.TH futex 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +futex \- fast user-space locking +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +The Linux kernel provides futexes ("Fast user-space mutexes") +as a building block for fast user-space +locking and semaphores. +Futexes are very basic and lend themselves well for building higher-level +locking abstractions such as +mutexes, condition variables, read-write locks, barriers, and semaphores. +.P +Most programmers will in fact not be using futexes directly but will +instead rely on system libraries built on them, +such as the Native POSIX Thread Library (NPTL) (see +.BR pthreads (7)). +.P +A futex is identified by a piece of memory which can be +shared between processes or threads. +In these different processes, the futex need not have identical addresses. +In its bare form, a futex has semaphore semantics; +it is a counter that can be incremented and decremented atomically; +processes can wait for the value to become positive. +.P +Futex operation occurs entirely in user space for the noncontended case. +The kernel is involved only to arbitrate the contended case. +As any sane design will strive for noncontention, +futexes are also optimized for this situation. +.P +In its bare form, a futex is an aligned integer which is +touched only by atomic assembler instructions. +This integer is four bytes long on all platforms. +Processes can share this integer using +.BR mmap (2), +via shared memory segments, or because they share memory space, +in which case the application is commonly called multithreaded. +.SS Semantics +Any futex operation starts in user space, +but it may be necessary to communicate with the kernel using the +.BR futex (2) +system call. +.P +To "up" a futex, execute the proper assembler instructions that +will cause the host CPU to atomically increment the integer. +Afterward, check if it has in fact changed from 0 to 1, in which case +there were no waiters and the operation is done. +This is the noncontended case which is fast and should be common. +.P +In the contended case, the atomic increment changed the counter +from \-1 (or some other negative number). +If this is detected, there are waiters. +User space should now set the counter to 1 and instruct the +kernel to wake up any waiters using the +.B FUTEX_WAKE +operation. +.P +Waiting on a futex, to "down" it, is the reverse operation. +Atomically decrement the counter and check if it changed to 0, +in which case the operation is done and the futex was uncontended. +In all other circumstances, the process should set the counter to \-1 +and request that the kernel wait for another process to up the futex. +This is done using the +.B FUTEX_WAIT +operation. +.P +The +.BR futex (2) +system call can optionally be passed a timeout specifying how long +the kernel should +wait for the futex to be upped. +In this case, semantics are more complex and the programmer is referred +to +.BR futex (2) +for +more details. +The same holds for asynchronous futex waiting. +.SH VERSIONS +Initial futex support was merged in Linux 2.5.7 +but with different semantics from those described above. +Current semantics are available from Linux 2.5.40 onward. +.SH NOTES +To reiterate, bare futexes are not intended as an easy-to-use +abstraction for end users. +Implementors are expected to be assembly literate and to have read +the sources of the futex user-space library referenced +below. +.P +This man page illustrates the most common use of the +.BR futex (2) +primitives; it is by no means the only one. +.\" .SH AUTHORS +.\" .P +.\" Futexes were designed and worked on by Hubertus Franke +.\" (IBM Thomas J. Watson Research Center), +.\" Matthew Kirkwood, Ingo Molnar (Red Hat) and +.\" Rusty Russell (IBM Linux Technology Center). +.\" This page written by bert hubert. +.SH SEE ALSO +.BR clone (2), +.BR futex (2), +.BR get_robust_list (2), +.BR set_robust_list (2), +.BR set_tid_address (2), +.BR pthreads (7) +.P +.I Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux +(proceedings of the Ottawa Linux Symposium 2002), +futex example library, futex-*.tar.bz2 +.UR https://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ +.UE . diff --git a/man/man7/glibc.7 b/man/man7/glibc.7 new file mode 100644 index 0000000..0d1ed26 --- /dev/null +++ b/man/man7/glibc.7 @@ -0,0 +1 @@ +.so man7/libc.7 diff --git a/man/man7/glob.7 b/man/man7/glob.7 new file mode 100644 index 0000000..a7546b4 --- /dev/null +++ b/man/man7/glob.7 @@ -0,0 +1,205 @@ +.\" Copyright (c) 1998 Andries Brouwer +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2003-08-24 fix for / by John Kristoff + joey +.\" +.TH glob 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +glob \- globbing pathnames +.SH DESCRIPTION +Long ago, in UNIX\ V6, there was a program +.I /etc/glob +that would expand wildcard patterns. +Soon afterward this became a shell built-in. +.P +These days there is also a library routine +.BR glob (3) +that will perform this function for a user program. +.P +The rules are as follows (POSIX.2, 3.13). +.SS Wildcard matching +A string is a wildcard pattern if it contains one of the +characters \[aq]?\[aq], \[aq]*\[aq], or \[aq][\[aq]. +Globbing is the operation +that expands a wildcard pattern into the list of pathnames +matching the pattern. +Matching is defined by: +.P +A \[aq]?\[aq] (not between brackets) matches any single character. +.P +A \[aq]*\[aq] (not between brackets) matches any string, +including the empty string. +.P +.B "Character classes" +.P +An expression "\fI[...]\fP" where the first character after the +leading \[aq][\[aq] is not an \[aq]!\[aq] matches a single character, +namely any of the characters enclosed by the brackets. +The string enclosed by the brackets cannot be empty; +therefore \[aq]]\[aq] can be allowed between the brackets, provided +that it is the first character. +(Thus, "\fI[][!]\fP" matches the +three characters \[aq][\[aq], \[aq]]\[aq], and \[aq]!\[aq].) +.P +.B Ranges +.P +There is one special convention: +two characters separated by \[aq]\-\[aq] denote a range. +(Thus, +"\fI[A\-Fa\-f0\-9]\fP" is equivalent to "\fI[ABCDEFabcdef0123456789]\fP".) +One may include \[aq]\-\[aq] in its literal meaning +by making it the first or last character between the brackets. +(Thus, +"\fI[]\-]\fP" matches just the two characters \[aq]]\[aq] and \[aq]\-\[aq], +and "\fI[\-\-0]\fP" matches the +three characters \[aq]\-\[aq], \[aq].\[aq], and \[aq]0\[aq], +since \[aq]/\[aq] cannot be matched.) +.P +.B Complementation +.P +An expression "\fI[!...]\fP" matches a single character, namely +any character that is not matched by the expression obtained +by removing the first \[aq]!\[aq] from it. +(Thus, "\fI[!]a\-]\fP" matches any +single character except \[aq]]\[aq], \[aq]a\[aq], and \[aq]\-\[aq].) +.P +One can remove the special meaning of \[aq]?\[aq], \[aq]*\[aq], and \[aq][\[aq] +by preceding them by a backslash, +or, +in case this is part of a shell command line, +enclosing them in quotes. +Between brackets these characters stand for themselves. +Thus, "\fI[[?*\e]\fP" matches the +four characters \[aq][\[aq], \[aq]?\[aq], \[aq]*\[aq], and \[aq]\e\[aq]. +.SS Pathnames +Globbing is applied on each of the components of a pathname +separately. +A \[aq]/\[aq] in a pathname cannot be matched by a \[aq]?\[aq] or \[aq]*\[aq] +wildcard, or by a range like "\fI[.\-0]\fP". +A range containing an explicit \[aq]/\[aq] character is syntactically incorrect. +(POSIX requires that syntactically incorrect patterns are left unchanged.) +.P +If a filename starts with a \[aq].\[aq], +this character must be matched explicitly. +(Thus, \fIrm\ *\fP will not remove .profile, and \fItar\ c\ *\fP will not +archive all your files; \fItar\ c\ .\fP is better.) +.SS Empty lists +The nice and simple rule given above: "expand a wildcard pattern +into the list of matching pathnames" was the original UNIX +definition. +It allowed one to have patterns that expand into +an empty list, as in +.P +.nf + xv \-wait 0 *.gif *.jpg +.fi +.P +where perhaps no *.gif files are present (and this is not +an error). +However, POSIX requires that a wildcard pattern is left +unchanged when it is syntactically incorrect, or the list of +matching pathnames is empty. +With +.I bash +one can force the classical behavior using this command: +.P +.in +4n +.EX +shopt \-s nullglob +.EE +.in +.\" In Bash v1, by setting allow_null_glob_expansion=true +.P +(Similar problems occur elsewhere. +For example, where old scripts have +.P +.in +4n +.EX +rm \`find . \-name "*\[ti]"\` +.EE +.in +.P +new scripts require +.P +.in +4n +.EX +rm \-f nosuchfile \`find . \-name "*\[ti]"\` +.EE +.in +.P +to avoid error messages from +.I rm +called with an empty argument list.) +.SH NOTES +.SS Regular expressions +Note that wildcard patterns are not regular expressions, +although they are a bit similar. +First of all, they match +filenames, rather than text, and secondly, the conventions +are not the same: for example, in a regular expression \[aq]*\[aq] means zero or +more copies of the preceding thing. +.P +Now that regular expressions have bracket expressions where +the negation is indicated by a \[aq]\[ha]\[aq], POSIX has declared the +effect of a wildcard pattern "\fI[\[ha]...]\fP" to be undefined. +.SS Character classes and internationalization +Of course ranges were originally meant to be ASCII ranges, +so that "\fI[\ \-%]\fP" stands for "\fI[\ !"#$%]\fP" and "\fI[a\-z]\fP" stands +for "any lowercase letter". +Some UNIX implementations generalized this so that a range X\-Y +stands for the set of characters with code between the codes for +X and for Y. +However, this requires the user to know the +character coding in use on the local system, and moreover, is +not convenient if the collating sequence for the local alphabet +differs from the ordering of the character codes. +Therefore, POSIX extended the bracket notation greatly, +both for wildcard patterns and for regular expressions. +In the above we saw three types of items that can occur in a bracket +expression: namely (i) the negation, (ii) explicit single characters, +and (iii) ranges. +POSIX specifies ranges in an internationally +more useful way and adds three more types: +.P +(iii) Ranges X\-Y comprise all characters that fall between X +and Y (inclusive) in the current collating sequence as defined +by the +.B LC_COLLATE +category in the current locale. +.P +(iv) Named character classes, like +.P +.nf +[:alnum:] [:alpha:] [:blank:] [:cntrl:] +[:digit:] [:graph:] [:lower:] [:print:] +[:punct:] [:space:] [:upper:] [:xdigit:] +.fi +.P +so that one can say "\fI[[:lower:]]\fP" instead of "\fI[a\-z]\fP", and have +things work in Denmark, too, where there are three letters past \[aq]z\[aq] +in the alphabet. +These character classes are defined by the +.B LC_CTYPE +category +in the current locale. +.P +(v) Collating symbols, like "\fI[.ch.]\fP" or "\fI[.a-acute.]\fP", +where the string between "\fI[.\fP" and "\fI.]\fP" is a collating +element defined for the current locale. +Note that this may +be a multicharacter element. +.P +(vi) Equivalence class expressions, like "\fI[=a=]\fP", +where the string between "\fI[=\fP" and "\fI=]\fP" is any collating +element from its equivalence class, as defined for the +current locale. +For example, "\fI[[=a=]]\fP" might be equivalent +to "\fI[a\('a\(`a\(:a\(^a]\fP", that is, +to "\fI[a[.a-acute.][.a-grave.][.a-umlaut.][.a-circumflex.]]\fP". +.SH SEE ALSO +.BR sh (1), +.BR fnmatch (3), +.BR glob (3), +.BR locale (7), +.BR regex (7) diff --git a/man/man7/hier.7 b/man/man7/hier.7 new file mode 100644 index 0000000..d6c4978 --- /dev/null +++ b/man/man7/hier.7 @@ -0,0 +1,654 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sun Jul 25 11:05:58 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sat Feb 10 16:18:03 1996 by Urs Thuermann (urs@isnogud.escape.de) +.\" Modified Mon Jun 16 20:02:00 1997 by Nicolás Lichtmaier +.\" Modified Mon Feb 6 16:41:00 1999 by Nicolás Lichtmaier +.\" Modified Tue Feb 8 16:46:45 2000 by Chris Pepper +.\" Modified Fri Sep 7 20:32:45 2001 by Tammy Fox +.TH hier 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +hier \- description of the filesystem hierarchy +.SH DESCRIPTION +A typical Linux system has, among others, the following directories: +.TP +.I / +This is the root directory. +This is where the whole tree starts. +.TP +.I /bin +This directory contains executable programs which are needed in +single user mode and to bring the system up or repair it. +.TP +.I /boot +Contains static files for the boot loader. +This directory holds only +the files which are needed during the boot process. +The map installer +and configuration files should go to +.I /sbin +and +.IR /etc . +The operating system kernel (initrd for example) must be located in either +.I / +or +.IR /boot . +.TP +.I /dev +Special or device files, which refer to physical devices. +See +.BR mknod (1). +.TP +.I /etc +Contains configuration files which are local to the machine. +Some +larger software packages, like X11, can have their own subdirectories +below +.IR /etc . +Site-wide configuration files may be placed here or in +.IR /usr/etc . +Nevertheless, programs should always look for these files in +.I /etc +and you may have links for these files to +.IR /usr/etc . +.TP +.I /etc/opt +Host-specific configuration files for add-on applications installed +in +.IR /opt . +.TP +.I /etc/sgml +This directory contains the configuration files for SGML (optional). +.TP +.I /etc/skel +When a new user account is created, files from this directory are +usually copied into the user's home directory. +.TP +.I /etc/X11 +Configuration files for the X11 window system (optional). +.TP +.I /etc/xml +This directory contains the configuration files for XML (optional). +.TP +.I /home +On machines with home directories for users, these are usually beneath +this directory, directly or not. +The structure of this directory +depends on local administration decisions (optional). +.TP +.I /lib +This directory should hold those shared libraries that are necessary +to boot the system and to run the commands in the root filesystem. +.TP +.I /lib +These directories are variants of +.I /lib +on system which support more than one binary format requiring separate +libraries (optional). +.TP +.I /lib/modules +Loadable kernel modules (optional). +.TP +.I /lost+found +This directory contains items lost in the filesystem. +These items are usually chunks of files mangled as a consequence of +a faulty disk or a system crash. +.TP +.I /media +This directory contains mount points for removable media such as CD +and DVD disks or USB sticks. +On systems where more than one device exists +for mounting a certain type of media, +mount directories can be created by appending a digit +to the name of those available above starting with '0', +but the unqualified name must also exist. +.TP +.I /media/floppy[1\-9] +Floppy drive (optional). +.TP +.I /media/cdrom[1\-9] +CD-ROM drive (optional). +.TP +.I /media/cdrecorder[1\-9] +CD writer (optional). +.TP +.I /media/zip[1\-9] +Zip drive (optional). +.TP +.I /media/usb[1\-9] +USB drive (optional). +.TP +.I /mnt +This directory is a mount point for a temporarily mounted filesystem. +In some distributions, +.I /mnt +contains subdirectories intended to be used as mount points for several +temporary filesystems. +.TP +.I /opt +This directory should contain add-on packages that contain static files. +.TP +.I /proc +This is a mount point for the +.I proc +filesystem, which provides information about running processes and +the kernel. +This pseudo-filesystem is described in more detail in +.BR proc (5). +.TP +.I /root +This directory is usually the home directory for the root user (optional). +.TP +.I /run +This directory contains information which +describes the system since it was booted. +Once this purpose was served by +.I /var/run +and programs may continue to use it. +.TP +.I /sbin +Like +.IR /bin , +this directory holds commands needed to boot the system, but which are +usually not executed by normal users. +.TP +.I /srv +This directory contains site-specific data that is served by this system. +.TP +.I /sys +This is a mount point for the sysfs filesystem, which provides information +about the kernel like +.IR /proc , +but better structured, following the formalism of kobject infrastructure. +.TP +.I /tmp +This directory contains temporary files which may be deleted with no +notice, such as by a regular job or at system boot up. +.TP +.I /usr +This directory is usually mounted from a separate partition. +It should hold only shareable, read-only data, so that it can be mounted +by various machines running Linux. +.TP +.I /usr/X11R6 +The X\-Window system, version 11 release 6 (present in FHS 2.3, removed +in FHS 3.0). +.TP +.I /usr/X11R6/bin +Binaries which belong to the X\-Window system; often, there is a +symbolic link from the more traditional +.I /usr/bin/X11 +to here. +.TP +.I /usr/X11R6/lib +Data files associated with the X\-Window system. +.TP +.I /usr/X11R6/lib/X11 +These contain miscellaneous files needed to run X; Often, there is a +symbolic link from +.I /usr/lib/X11 +to this directory. +.TP +.I /usr/X11R6/include/X11 +Contains include files needed for compiling programs using the X11 +window system. +Often, there is a symbolic link from +.I /usr/include/X11 +to this directory. +.TP +.I /usr/bin +This is the primary directory for executable programs. +Most programs +executed by normal users which are not needed for booting or for +repairing the system and which are not installed locally should be +placed in this directory. +.TP +.I /usr/bin/mh +Commands for the MH mail handling system (optional). +.TP +.I /usr/bin/X11 +This is the traditional place to look for X11 executables; on Linux, it +usually is a symbolic link to +.IR /usr/X11R6/bin . +.TP +.I /usr/dict +Replaced by +.IR /usr/share/dict . +.TP +.I /usr/doc +Replaced by +.IR /usr/share/doc . +.TP +.I /usr/etc +Site-wide configuration files to be shared between several machines +may be stored in this directory. +However, commands should always +reference those files using the +.I /etc +directory. +Links from files in +.I /etc +should point to the appropriate files in +.IR /usr/etc . +.TP +.I /usr/games +Binaries for games and educational programs (optional). +.TP +.I /usr/include +Include files for the C compiler. +.TP +.I /usr/include/bsd +BSD compatibility include files (optional). +.TP +.I /usr/include/X11 +Include files for the C compiler and the X\-Window system. +This is +usually a symbolic link to +.IR /usr/X11R6/include/X11 . +.TP +.I /usr/include/asm +Include files which declare some assembler functions. +This used to be a +symbolic link to +.IR /usr/src/linux/include/asm . +.TP +.I /usr/include/linux +This contains information which may change from system release to +system release and used to be a symbolic link to +.I /usr/src/linux/include/linux +to get at operating-system-specific information. +.IP +(Note that one should have include files there that work correctly with +the current libc and in user space. +However, Linux kernel source is not +designed to be used with user programs and does not know anything +about the libc you are using. +It is very likely that things will break +if you let +.I /usr/include/asm +and +.I /usr/include/linux +point at a random kernel tree. +Debian systems don't do this +and use headers from a known good kernel +version, provided in the libc*\-dev package.) +.TP +.I /usr/include/g++ +Include files to use with the GNU C++ compiler. +.TP +.I /usr/lib +Object libraries, including dynamic libraries, plus some executables +which usually are not invoked directly. +More complicated programs may +have whole subdirectories there. +.TP +.I /usr/libexec +Directory contains binaries for internal use only and they are not meant +to be executed directly by users shell or scripts. +.TP +.I /usr/lib +These directories are variants of +.I /usr/lib +on system which support more than one binary format requiring separate +libraries, except that the symbolic link +.IR /usr/lib qual /X11 +is not required (optional). +.TP +.I /usr/lib/X11 +The usual place for data files associated with X programs, and +configuration files for the X system itself. +On Linux, it usually is +a symbolic link to +.IR /usr/X11R6/lib/X11 . +.TP +.I /usr/lib/gcc\-lib +contains executables and include files for the GNU C compiler, +.BR gcc (1). +.TP +.I /usr/lib/groff +Files for the GNU groff document formatting system. +.TP +.I /usr/lib/uucp +Files for +.BR uucp (1). +.TP +.I /usr/local +This is where programs which are local to the site typically go. +.TP +.I /usr/local/bin +Binaries for programs local to the site. +.TP +.I /usr/local/doc +Local documentation. +.TP +.I /usr/local/etc +Configuration files associated with locally installed programs. +.TP +.I /usr/local/games +Binaries for locally installed games. +.TP +.I /usr/local/lib +Files associated with locally installed programs. +.TP +.I /usr/local/lib +These directories are variants of +.I /usr/local/lib +on system which support more than one binary format requiring separate +libraries (optional). +.TP +.I /usr/local/include +Header files for the local C compiler. +.TP +.I /usr/local/info +Info pages associated with locally installed programs. +.TP +.I /usr/local/man +Man pages associated with locally installed programs. +.TP +.I /usr/local/sbin +Locally installed programs for system administration. +.TP +.I /usr/local/share +Local application data that can be shared among different architectures +of the same OS. +.TP +.I /usr/local/src +Source code for locally installed software. +.TP +.I /usr/man +Replaced by +.IR /usr/share/man . +.TP +.I /usr/sbin +This directory contains program binaries for system administration +which are not essential for the boot process, for mounting +.IR /usr , +or for system repair. +.TP +.I /usr/share +This directory contains subdirectories with specific application data, that +can be shared among different architectures of the same OS. +Often one finds stuff here that used to live in +.I /usr/doc +or +.I /usr/lib +or +.IR /usr/man . +.TP +.I /usr/share/color +Contains color management information, like International Color Consortium (ICC) +Color profiles (optional). +.TP +.I /usr/share/dict +Contains the word lists used by spell checkers (optional). +.TP +.I /usr/share/dict/words +List of English words (optional). +.TP +.I /usr/share/doc +Documentation about installed programs (optional). +.TP +.I /usr/share/games +Static data files for games in +.I /usr/games +(optional). +.TP +.I /usr/share/info +Info pages go here (optional). +.TP +.I /usr/share/locale +Locale information goes here (optional). +.TP +.I /usr/share/man +Manual pages go here in subdirectories according to the man page sections. +.TP +.IR /usr/share/man/ locale /man[1\-9] +These directories contain manual pages for the +specific locale in source code form. +Systems which use a unique language and code set for all manual pages +may omit the substring. +.TP +.I /usr/share/misc +Miscellaneous data that can be shared among different architectures of the +same OS. +.TP +.I /usr/share/nls +The message catalogs for native language support go here (optional). +.TP +.I /usr/share/ppd +Postscript Printer Definition (PPD) files (optional). +.TP +.I /usr/share/sgml +Files for SGML (optional). +.TP +.I /usr/share/sgml/docbook +DocBook DTD (optional). +.TP +.I /usr/share/sgml/tei +TEI DTD (optional). +.TP +.I /usr/share/sgml/html +HTML DTD (optional). +.TP +.I /usr/share/sgml/mathml +MathML DTD (optional). +.TP +.I /usr/share/terminfo +The database for terminfo (optional). +.TP +.I /usr/share/tmac +Troff macros that are not distributed with groff (optional). +.TP +.I /usr/share/xml +Files for XML (optional). +.TP +.I /usr/share/xml/docbook +DocBook DTD (optional). +.TP +.I /usr/share/xml/xhtml +XHTML DTD (optional). +.TP +.I /usr/share/xml/mathml +MathML DTD (optional). +.TP +.I /usr/share/zoneinfo +Files for timezone information (optional). +.TP +.I /usr/src +Source files for different parts of the system, included with some packages +for reference purposes. +Don't work here with your own projects, as files +below /usr should be read-only except when installing software (optional). +.TP +.I /usr/src/linux +This was the traditional place for the kernel source. +Some distributions put here the source for the default kernel they ship. +You should probably use another directory when building your own kernel. +.TP +.I /usr/tmp +Obsolete. +This should be a link +to +.IR /var/tmp . +This link is present only for compatibility reasons and shouldn't be used. +.TP +.I /var +This directory contains files which may change in size, such as spool +and log files. +.TP +.I /var/account +Process accounting logs (optional). +.TP +.I /var/adm +This directory is superseded by +.I /var/log +and should be a symbolic link to +.IR /var/log . +.TP +.I /var/backups +Reserved for historical reasons. +.TP +.I /var/cache +Data cached for programs. +.TP +.I /var/cache/fonts +Locally generated fonts (optional). +.TP +.I /var/cache/man +Locally formatted man pages (optional). +.TP +.I /var/cache/www +WWW proxy or cache data (optional). +.TP +.I /var/cache/ +Package specific cache data (optional). +.TP +.IR /var/catman/cat[1\-9] " or " /var/cache/man/cat[1\-9] +These directories contain preformatted manual pages according to their +man page section. +(The use of preformatted manual pages is deprecated.) +.TP +.I /var/crash +System crash dumps (optional). +.TP +.I /var/cron +Reserved for historical reasons. +.TP +.I /var/games +Variable game data (optional). +.TP +.I /var/lib +Variable state information for programs. +.TP +.I /var/lib/color +Variable files containing color management information (optional). +.TP +.I /var/lib/hwclock +State directory for hwclock (optional). +.TP +.I /var/lib/misc +Miscellaneous state data. +.TP +.I /var/lib/xdm +X display manager variable data (optional). +.TP +.I /var/lib/ +Editor backup files and state (optional). +.TP +.I /var/lib/ +These directories must be used for all distribution packaging support. +.TP +.I /var/lib/ +State data for packages and subsystems (optional). +.TP +.I /var/lib/ +Packaging support files (optional). +.TP +.I /var/local +Variable data for +.IR /usr/local . +.TP +.I /var/lock +Lock files are placed in this directory. +The naming convention for +device lock files is +.I LCK.. +where +.I +is the device's name in the filesystem. +The format used is that of HDU UUCP lock files, that is, lock files +contain a PID as a 10-byte ASCII decimal number, followed by a newline +character. +.TP +.I /var/log +Miscellaneous log files. +.TP +.I /var/opt +Variable data for +.IR /opt . +.TP +.I /var/mail +Users' mailboxes. +Replaces +.IR /var/spool/mail . +.TP +.I /var/msgs +Reserved for historical reasons. +.TP +.I /var/preserve +Reserved for historical reasons. +.TP +.I /var/run +Run-time variable files, like files holding process identifiers (PIDs) +and logged user information +.IR (utmp) . +Files in this directory are usually cleared when the system boots. +.TP +.I /var/spool +Spooled (or queued) files for various programs. +.TP +.I /var/spool/at +Spooled jobs for +.BR at (1). +.TP +.I /var/spool/cron +Spooled jobs for +.BR cron (8). +.TP +.I /var/spool/lpd +Spooled files for printing (optional). +.TP +.I /var/spool/lpd/printer +Spools for a specific printer (optional). +.TP +.I /var/spool/mail +Replaced by +.IR /var/mail . +.TP +.I /var/spool/mqueue +Queued outgoing mail (optional). +.TP +.I /var/spool/news +Spool directory for news (optional). +.TP +.I /var/spool/rwho +Spooled files for +.BR rwhod (8) +(optional). +.TP +.I /var/spool/smail +Spooled files for the +.BR smail (1) +mail delivery program. +.TP +.I /var/spool/uucp +Spooled files for +.BR uucp (1) +(optional). +.TP +.I /var/tmp +Like +.IR /tmp , +this directory holds temporary files stored for an unspecified duration. +.TP +.I /var/yp +Database files for NIS, +formerly known as the Sun Yellow Pages (YP). +.SH STANDARDS +.UR https://refspecs.linuxfoundation.org/fhs.shtml +The Filesystem Hierarchy Standard (FHS), Version 3.0 +.UE , +published March 19, 2015 +.SH BUGS +This list is not exhaustive; +different distributions and systems may be configured differently. +.SH SEE ALSO +.BR find (1), +.BR ln (1), +.BR proc (5), +.BR file\-hierarchy (7), +.BR mount (8) +.P +The Filesystem Hierarchy Standard diff --git a/man/man7/hostname.7 b/man/man7/hostname.7 new file mode 100644 index 0000000..01bf839 --- /dev/null +++ b/man/man7/hostname.7 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1987, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)hostname.7 8.2 (Berkeley) 12/30/93 +.\" $FreeBSD: src/share/man/man7/hostname.7,v 1.7 2004/07/03 18:29:23 ru Exp $ +.\" +.\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and modified for Linux. +.\" +.TH hostname 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +hostname \- hostname resolution description +.SH DESCRIPTION +Hostnames are domains, where a domain is a hierarchical, dot-separated +list of subdomains; for example, the machine "monet", in the "example" +subdomain of the "com" domain would be represented as "monet.example.com". +.P +Each element of the hostname must be from 1 to 63 characters long and the +entire hostname, including the dots, can be at most 253 characters long. +Valid characters for hostnames are +.BR ASCII (7) +letters from +.I a +to +.IR z , +the digits from +.I 0 +to +.IR 9 , +and the hyphen (\-). +A hostname may not start with a hyphen. +.P +Hostnames are often used with network client and server programs, +which must generally translate the name to an address for use. +(This task is generally performed by either +.BR getaddrinfo (3) +or the obsolete +.BR gethostbyname (3).) +.P +Hostnames are resolved by the NSS framework in glibc according +to the +.B hosts +configuration in +.BR nsswitch.conf (5). +The DNS-based name resolver +(in the +.B dns +NSS service module) resolves them in the following fashion. +.P +If the name consists of a single component, that is, contains no dot, +and if the environment variable +.B HOSTALIASES +is set to the name of a file, +that file is searched for any string matching the input hostname. +The file should consist of lines made up of two white-space separated strings, +the first of which is the hostname alias, +and the second of which is the complete hostname +to be substituted for that alias. +If a case-insensitive match is found between the hostname to be resolved +and the first field of a line in the file, the substituted name is looked +up with no further processing. +.P +If the input name ends with a trailing dot, +the trailing dot is removed, +and the remaining name is looked up with no further processing. +.P +If the input name does not end with a trailing dot, it is looked up +by searching through a list of domains until a match is found. +The default search list includes first the local domain, +then its parent domains with at least 2 name components (longest first). +For example, +in the domain cs.example.com, the name lithium.cchem will be checked first +as lithium.cchem.cs.example and then as lithium.cchem.example.com. +lithium.cchem.com will not be tried, as there is only one component +remaining from the local domain. +The search path can be changed from the default +by a system-wide configuration file (see +.BR resolver (5)). +.SH SEE ALSO +.BR getaddrinfo (3), +.BR gethostbyname (3), +.BR nsswitch.conf (5), +.BR resolver (5), +.BR mailaddr (7), +.BR named (8) +.P +.UR http://www.ietf.org\:/rfc\:/rfc1123.txt +IETF RFC\ 1123 +.UE +.P +.UR http://www.ietf.org\:/rfc\:/rfc1178.txt +IETF RFC\ 1178 +.UE +.\" .SH HISTORY +.\" Hostname appeared in +.\" 4.2BSD. diff --git a/man/man7/icmp.7 b/man/man7/icmp.7 new file mode 100644 index 0000000..f197547 --- /dev/null +++ b/man/man7/icmp.7 @@ -0,0 +1,196 @@ +'\" t +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" $Id: icmp.7,v 1.6 2000/08/14 08:03:45 ak Exp $ +.\" +.TH icmp 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +icmp \- Linux IPv4 ICMP kernel module. +.SH DESCRIPTION +This kernel protocol module implements the Internet Control +Message Protocol defined in RFC\ 792. +It is used to signal error conditions and for diagnosis. +The user doesn't interact directly with this module; +instead it communicates with the other protocols in the kernel +and these pass the ICMP errors to the application layers. +The kernel ICMP module also answers ICMP requests. +.P +A user protocol may receive ICMP packets for all local sockets by opening +a raw socket with the protocol +.BR IPPROTO_ICMP . +See +.BR raw (7) +for more information. +The types of ICMP packets passed to the socket can be filtered using the +.B ICMP_FILTER +socket option. +ICMP packets are always processed by the kernel too, even +when passed to a user socket. +.P +Linux limits the rate of ICMP error packets to each destination. +.B ICMP_REDIRECT +and +.B ICMP_DEST_UNREACH +are also limited by the destination route of the incoming packets. +.SS /proc interfaces +ICMP supports a set of +.I /proc +interfaces to configure some global IP parameters. +The parameters can be accessed by reading or writing files in the directory +.IR /proc/sys/net/ipv4/ . +Most of these parameters are rate limitations for specific ICMP types. +Linux 2.2 uses a token bucket filter to limit ICMPs. +.\" FIXME . better description needed +The value is the timeout in jiffies until the token bucket filter is +cleared after a burst. +A jiffy is a system dependent unit, usually 10ms on i386 and +about 1ms on alpha and ia64. +.TP +.IR icmp_destunreach_rate " (Linux 2.2 to Linux 2.4.9)" +.\" Precisely: from Linux 2.1.102 +Maximum rate to send ICMP Destination Unreachable packets. +This limits the rate at which packets are sent to any individual +route or destination. +The limit does not affect sending of +.B ICMP_FRAG_NEEDED +packets needed for path MTU discovery. +.TP +.IR icmp_echo_ignore_all " (since Linux 2.2)" +.\" Precisely: 2.1.68 +If this value is nonzero, Linux will ignore all +.B ICMP_ECHO +requests. +.TP +.IR icmp_echo_ignore_broadcasts " (since Linux 2.2)" +.\" Precisely: from Linux 2.1.68 +If this value is nonzero, Linux will ignore all +.B ICMP_ECHO +packets sent to broadcast addresses. +.TP +.IR icmp_echoreply_rate " (Linux 2.2 to Linux 2.4.9)" +.\" Precisely: from Linux 2.1.102 +Maximum rate for sending +.B ICMP_ECHOREPLY +packets in response to +.B ICMP_ECHOREQUEST +packets. +.TP +.IR icmp_errors_use_inbound_ifaddr " (Boolean; default: disabled; since Linux 2.6.12)" +.\" The following taken from Linux 2.6.28-rc4 Documentation/networking/ip-sysctl.txt +If disabled, ICMP error messages are sent with the primary address of +the exiting interface. +.IP +If enabled, the message will be sent with the primary address of +the interface that received the packet that caused the ICMP error. +This is the behavior that many network administrators will expect from +a router. +And it can make debugging complicated network layouts much easier. +.IP +Note that if no primary address exists for the interface selected, +then the primary address of the first non-loopback interface that +has one will be used regardless of this setting. +.TP +.IR icmp_ignore_bogus_error_responses " (Boolean; default: disabled; since Linux 2.2)" +.\" precisely: since Linux 2.1.32 +.\" The following taken from Linux 2.6.28-rc4 Documentation/networking/ip-sysctl.txt +Some routers violate RFC1122 by sending bogus responses to broadcast frames. +Such violations are normally logged via a kernel warning. +If this parameter is enabled, the kernel will not give such warnings, +which will avoid log file clutter. +.TP +.IR icmp_paramprob_rate " (Linux 2.2 to Linux 2.4.9)" +.\" Precisely: from Linux 2.1.102 +Maximum rate for sending +.B ICMP_PARAMETERPROB +packets. +These packets are sent when a packet arrives with an invalid IP header. +.TP +.IR icmp_ratelimit " (integer; default: 1000; since Linux 2.4.10)" +.\" The following taken from Linux 2.6.28-rc4 Documentation/networking/ip-sysctl.txt +Limit the maximum rates for sending ICMP packets whose type matches +.I icmp_ratemask +(see below) to specific targets. +0 to disable any limiting, +otherwise the minimum space between responses in milliseconds. +.TP +.IR icmp_ratemask " (integer; default: see below; since Linux 2.4.10)" +.\" The following taken from Linux 2.6.28-rc4 Documentation/networking/ip-sysctl.txt +Mask made of ICMP types for which rates are being limited. +.IP +Significant bits: IHGFEDCBA9876543210 +.br +Default mask: 0000001100000011000 (0x1818) +.IP +Bit definitions (see the Linux kernel source file +.IR include/linux/icmp.h ): +.RS 12 +.TS +l l. +0 Echo Reply +3 Destination Unreachable * +4 Source Quench * +5 Redirect +8 Echo Request +B Time Exceeded * +C Parameter Problem * +D Timestamp Request +E Timestamp Reply +F Info Request +G Info Reply +H Address Mask Request +I Address Mask Reply +.TE +.RE +.P +The bits marked with an asterisk are rate limited by default +(see the default mask above). +.TP +.IR icmp_timeexceed_rate " (Linux 2.2 to Linux 2.4.9)" +Maximum rate for sending +.B ICMP_TIME_EXCEEDED +packets. +These packets are +sent to prevent loops when a packet has crossed too many hops. +.TP +.IR ping_group_range " (two integers; default: see below; since Linux 2.6.39)" +Range of the group IDs (minimum and maximum group IDs, inclusive) +that are allowed to create ICMP Echo sockets. +The default is "1 0", which +means no group is allowed to create ICMP Echo sockets. +.SH VERSIONS +Support for the +.B ICMP_ADDRESS +request was removed in Linux 2.2. +.P +Support for +.B ICMP_SOURCE_QUENCH +was removed in Linux 2.2. +.SH NOTES +As many other implementations don't support +.B IPPROTO_ICMP +raw sockets, this feature +should not be relied on in portable programs. +.\" not really true ATM +.\" .P +.\" Linux ICMP should be compliant to RFC 1122. +.P +.B ICMP_REDIRECT +packets are not sent when Linux is not acting as a router. +They are also accepted only from the old gateway defined in the +routing table and the redirect routes are expired after some time. +.P +The 64-bit timestamp returned by +.B ICMP_TIMESTAMP +is in milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.P +Linux ICMP internally uses a raw socket to send ICMPs. +This raw socket may appear in +.BR netstat (8) +output with a zero inode. +.SH SEE ALSO +.BR ip (7), +.BR rdisc (8) +.P +RFC\ 792 for a description of the ICMP protocol. diff --git a/man/man7/inode.7 b/man/man7/inode.7 new file mode 100644 index 0000000..a95332f --- /dev/null +++ b/man/man7/inode.7 @@ -0,0 +1,480 @@ +'\" t +.\" Copyright (c) 2017 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH inode 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inode \- file inode information +.SH DESCRIPTION +Each file has an inode containing metadata about the file. +An application can retrieve this metadata using +.BR stat (2) +(or related calls), which returns a +.I stat +structure, or +.BR statx (2), +which returns a +.I statx +structure. +.P +The following is a list of the information typically found in, +or associated with, the file inode, +with the names of the corresponding structure fields returned by +.BR stat (2) +and +.BR statx (2): +.TP +Device where inode resides +\fIstat.st_dev\fP; \fIstatx.stx_dev_minor\fP and \fIstatx.stx_dev_major\fP +.IP +Each inode (as well as the associated file) resides in a filesystem +that is hosted on a device. +That device is identified by the combination of its major ID +(which identifies the general class of device) +and minor ID (which identifies a specific instance in the general class). +.TP +Inode number +\fIstat.st_ino\fP; \fIstatx.stx_ino\fP +.IP +Each file in a filesystem has a unique inode number. +Inode numbers are guaranteed to be unique only within a filesystem +(i.e., the same inode numbers may be used by different filesystems, +which is the reason that hard links may not cross filesystem boundaries). +This field contains the file's inode number. +.TP +File type and mode +\fIstat.st_mode\fP; \fIstatx.stx_mode\fP +.IP +See the discussion of file type and mode, below. +.TP +Link count +\fIstat.st_nlink\fP; \fIstatx.stx_nlink\fP +.IP +This field contains the number of hard links to the file. +Additional links to an existing file are created using +.BR link (2). +.TP +User ID +\fIstat.st_uid\fP; \fIstatx.stx_uid\fP +.IP +This field records the user ID of the owner of the file. +For newly created files, +the file user ID is the effective user ID of the creating process. +The user ID of a file can be changed using +.BR chown (2). +.TP +Group ID +\fIstat.st_gid\fP; \fIstatx.stx_gid\fP +.IP +The inode records the ID of the group owner of the file. +For newly created files, +the file group ID is either the group ID of the parent directory or +the effective group ID of the creating process, +depending on whether or not the set-group-ID bit +is set on the parent directory (see below). +The group ID of a file can be changed using +.BR chown (2). +.TP +Device represented by this inode +\fIstat.st_rdev\fP; \fIstatx.stx_rdev_minor\fP and \fIstatx.stx_rdev_major\fP +.IP +If this file (inode) represents a device, +then the inode records the major and minor ID of that device. +.TP +File size +\fIstat.st_size\fP; \fIstatx.stx_size\fP +.IP +This field gives the size of the file (if it is a regular +file or a symbolic link) in bytes. +The size of a symbolic link is the length of the pathname +it contains, without a terminating null byte. +.TP +Preferred block size for I/O +\fIstat.st_blksize\fP; \fIstatx.stx_blksize\fP +.IP +This field gives the "preferred" blocksize for efficient filesystem I/O. +(Writing to a file in smaller chunks may cause +an inefficient read-modify-rewrite.) +.TP +Number of blocks allocated to the file +\fIstat.st_blocks\fP; \fIstatx.stx_blocks\fP +.IP +This field indicates the number of blocks allocated to the file, +512-byte units, +(This may be smaller than +.IR st_size /512 +when the file has holes.) +.IP +The POSIX.1 standard notes +.\" Rationale for sys/stat.h in POSIX.1-2008 +that the unit for the +.I st_blocks +member of the +.I stat +structure is not defined by the standard. +On many implementations it is 512 bytes; +on a few systems, a different unit is used, such as 1024. +Furthermore, the unit may differ on a per-filesystem basis. +.TP +Last access timestamp (atime) +\fIstat.st_atime\fP; \fIstatx.stx_atime\fP +.IP +This is the file's last access timestamp. +It is changed by file accesses, for example, by +.BR execve (2), +.BR mknod (2), +.BR pipe (2), +.BR utime (2), +and +.BR read (2) +(of more than zero bytes). +Other interfaces, such as +.BR mmap (2), +may or may not update the atime timestamp +.IP +Some filesystem types allow mounting in such a way that file +and/or directory accesses do not cause an update of the atime timestamp. +(See +.IR noatime , +.IR nodiratime , +and +.I relatime +in +.BR mount (8), +and related information in +.BR mount (2).) +In addition, the atime timestamp +is not updated if a file is opened with the +.B O_NOATIME +flag; see +.BR open (2). +.TP +File creation (birth) timestamp (btime) +(not returned in the \fIstat\fP structure); \fIstatx.stx_btime\fP +.IP +The file's creation timestamp. +This is set on file creation and not changed subsequently. +.IP +The btime timestamp was not historically present on UNIX systems +and is not currently supported by most Linux filesystems. +.\" FIXME Is it supported on ext4 and XFS? +.TP +Last modification timestamp (mtime) +\fIstat.st_mtime\fP; \fIstatx.stx_mtime\fP +.IP +This is the file's last modification timestamp. +It is changed by file modifications, for example, by +.BR mknod (2), +.BR truncate (2), +.BR utime (2), +and +.BR write (2) +(of more than zero bytes). +Moreover, the mtime timestamp +of a directory is changed by the creation or deletion of files +in that directory. +The mtime timestamp is +.I not +changed for changes in owner, group, hard link count, or mode. +.TP +Last status change timestamp (ctime) +\fIstat.st_ctime\fP; \fIstatx.stx_ctime\fP +.IP +This is the file's last status change timestamp. +It is changed by writing or by setting inode information +(i.e., owner, group, link count, mode, etc.). +.P +The timestamp fields report time measured with a zero point at the +.IR Epoch , +1970-01-01 00:00:00 +0000, UTC (see +.BR time (7)). +.P +Nanosecond timestamps are supported on XFS, JFS, Btrfs, and +ext4 (since Linux 2.6.23). +.\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80 +Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs. +In order to return timestamps with nanosecond precision, +the timestamp fields in the +.I stat +and +.I statx +structures are defined as structures that include a nanosecond component. +See +.BR stat (2) +and +.BR statx (2) +for details. +On filesystems that do not support subsecond timestamps, +the nanosecond fields in the +.I stat +and +.I statx +structures are returned with the value 0. +.\" +.SS The file type and mode +The +.I stat.st_mode +field (for +.BR statx (2), +the +.I statx.stx_mode +field) contains the file type and mode. +.P +POSIX refers to the +.I stat.st_mode +bits corresponding to the mask +.B S_IFMT +(see below) as the +.IR "file type" , +the 12 bits corresponding to the mask 07777 as the +.I file mode bits +and the least significant 9 bits (0777) as the +.IR "file permission bits" . +.P +The following mask values are defined for the file type: +.in +4n +.TS +lB l l. +S_IFMT 0170000 bit mask for the file type bit field + +S_IFSOCK 0140000 socket +S_IFLNK 0120000 symbolic link +S_IFREG 0100000 regular file +S_IFBLK 0060000 block device +S_IFDIR 0040000 directory +S_IFCHR 0020000 character device +S_IFIFO 0010000 FIFO +.TE +.in +.P +Thus, to test for a regular file (for example), one could write: +.P +.in +4n +.EX +stat(pathname, &sb); +if ((sb.st_mode & S_IFMT) == S_IFREG) { + /* Handle regular file */ +} +.EE +.in +.P +Because tests of the above form are common, additional +macros are defined by POSIX to allow the test of the file type in +.I st_mode +to be written more concisely: +.RS 4 +.TP 1.2i +.BR S_ISREG (m) +is it a regular file? +.TP +.BR S_ISDIR (m) +directory? +.TP +.BR S_ISCHR (m) +character device? +.TP +.BR S_ISBLK (m) +block device? +.TP +.BR S_ISFIFO (m) +FIFO (named pipe)? +.TP +.BR S_ISLNK (m) +symbolic link? (Not in POSIX.1-1996.) +.TP +.BR S_ISSOCK (m) +socket? (Not in POSIX.1-1996.) +.RE +.P +The preceding code snippet could thus be rewritten as: +.P +.in +4n +.EX +stat(pathname, &sb); +if (S_ISREG(sb.st_mode)) { + /* Handle regular file */ +} +.EE +.in +.P +The definitions of most of the above file type test macros +are provided if any of the following feature test macros is defined: +.B _BSD_SOURCE +(in glibc 2.19 and earlier), +.B _SVID_SOURCE +(in glibc 2.19 and earlier), +or +.B _DEFAULT_SOURCE +(in glibc 2.20 and later). +In addition, definitions of all of the above macros except +.B S_IFSOCK +and +.BR S_ISSOCK () +are provided if +.B _XOPEN_SOURCE +is defined. +.P +The definition of +.B S_IFSOCK +can also be exposed either by defining +.B _XOPEN_SOURCE +with a value of 500 or greater or (since glibc 2.24) by defining both +.B _XOPEN_SOURCE +and +.BR _XOPEN_SOURCE_EXTENDED . +.P +The definition of +.BR S_ISSOCK () +is exposed if any of the following feature test macros is defined: +.B _BSD_SOURCE +(in glibc 2.19 and earlier), +.B _DEFAULT_SOURCE +(in glibc 2.20 and later), +.B _XOPEN_SOURCE +with a value of 500 or greater, +.B _POSIX_C_SOURCE +with a value of 200112L or greater, or (since glibc 2.24) by defining both +.B _XOPEN_SOURCE +and +.BR _XOPEN_SOURCE_EXTENDED . +.P +The following mask values are defined for +the file mode component of the +.I st_mode +field: +.in +4n +.TS +lB l lx. +S_ISUID 04000 T{ +set-user-ID bit (see \fBexecve\fP(2)) +T} +S_ISGID 02000 T{ +set-group-ID bit (see below) +T} +S_ISVTX 01000 T{ +sticky bit (see below) +T} + +S_IRWXU 00700 T{ +owner has read, write, and execute permission +T} +S_IRUSR 00400 T{ +owner has read permission +T} +S_IWUSR 00200 T{ +owner has write permission +T} +S_IXUSR 00100 T{ +owner has execute permission +T} + +S_IRWXG 00070 T{ +group has read, write, and execute permission +T} +S_IRGRP 00040 T{ +group has read permission +T} +S_IWGRP 00020 T{ +group has write permission +T} +S_IXGRP 00010 T{ +group has execute permission +T} + +S_IRWXO 00007 T{ +others (not in group) have read, write, and execute permission +T} +S_IROTH 00004 T{ +others have read permission +T} +S_IWOTH 00002 T{ +others have write permission +T} +S_IXOTH 00001 T{ +others have execute permission +T} +.TE +.in +.P +The set-group-ID bit +.RB ( S_ISGID ) +has several special uses. +For a directory, it indicates that BSD semantics are to be used +for that directory: files created there inherit their group ID from +the directory, not from the effective group ID of the creating process, +and directories created there will also get the +.B S_ISGID +bit set. +For an executable file, the set-group-ID bit causes the effective group ID +of a process that executes the file to change as described in +.BR execve (2). +For a file that does not have the group execution bit +.RB ( S_IXGRP ) +set, +the set-group-ID bit indicates mandatory file/record locking. +.P +The sticky bit +.RB ( S_ISVTX ) +on a directory means that a file +in that directory can be renamed or deleted only by the owner +of the file, by the owner of the directory, and by a privileged +process. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +POSIX.1-1990 did not describe the +.BR S_IFMT , +.BR S_IFSOCK , +.BR S_IFLNK , +.BR S_IFREG , +.BR S_IFBLK , +.BR S_IFDIR , +.BR S_IFCHR , +.BR S_IFIFO , +and +.B S_ISVTX +constants, but instead specified the use of +the macros +.BR S_ISDIR () +and so on. +.P +The +.BR S_ISLNK () +and +.BR S_ISSOCK () +macros were not in +POSIX.1-1996; +the former is from SVID 4, the latter from SUSv2. +.P +UNIX\ V7 (and later systems) had +.BR S_IREAD , +.BR S_IWRITE , +.BR S_IEXEC , +and +where POSIX +prescribes the synonyms +.BR S_IRUSR , +.BR S_IWUSR , +and +.BR S_IXUSR . +.SH NOTES +For pseudofiles that are autogenerated by the kernel, the file size +(\fIstat.st_size\fP; \fIstatx.stx_size\fP) +reported by the kernel is not accurate. +For example, the value 0 is returned for many files under the +.I /proc +directory, +while various files under +.I /sys +report a size of 4096 bytes, even though the file content is smaller. +For such files, one should simply try to read as many bytes as possible +(and append \[aq]\e0\[aq] to the returned buffer +if it is to be interpreted as a string). +.SH SEE ALSO +.BR stat (1), +.BR stat (2), +.BR statx (2), +.BR symlink (7) diff --git a/man/man7/inotify.7 b/man/man7/inotify.7 new file mode 100644 index 0000000..e050df9 --- /dev/null +++ b/man/man7/inotify.7 @@ -0,0 +1,1100 @@ +.\" Copyright (C) 2006, 2014 Michael Kerrisk +.\" Copyright (C) 2014 Heinrich Schuchardt +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH inotify 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +inotify \- monitoring filesystem events +.SH DESCRIPTION +The +.I inotify +API provides a mechanism for monitoring filesystem events. +Inotify can be used to monitor individual files, +or to monitor directories. +When a directory is monitored, inotify will return events +for the directory itself, and for files inside the directory. +.P +The following system calls are used with this API: +.IP \[bu] 3 +.BR inotify_init (2) +creates an inotify instance and returns a file descriptor +referring to the inotify instance. +The more recent +.BR inotify_init1 (2) +is like +.BR inotify_init (2), +but has a +.I flags +argument that provides access to some extra functionality. +.IP \[bu] +.BR inotify_add_watch (2) +manipulates the "watch list" associated with an inotify instance. +Each item ("watch") in the watch list specifies the pathname of +a file or directory, +along with some set of events that the kernel should monitor for the +file referred to by that pathname. +.BR inotify_add_watch (2) +either creates a new watch item, or modifies an existing watch. +Each watch has a unique "watch descriptor", an integer +returned by +.BR inotify_add_watch (2) +when the watch is created. +.IP \[bu] +When events occur for monitored files and directories, +those events are made available to the application as structured data that +can be read from the inotify file descriptor using +.BR read (2) +(see below). +.IP \[bu] +.BR inotify_rm_watch (2) +removes an item from an inotify watch list. +.IP \[bu] +When all file descriptors referring to an inotify +instance have been closed (using +.BR close (2)), +the underlying object and its resources are +freed for reuse by the kernel; +all associated watches are automatically freed. +.P +With careful programming, +an application can use inotify to efficiently monitor and cache +the state of a set of filesystem objects. +However, robust applications should allow for the fact that bugs +in the monitoring logic or races of the kind described below +may leave the cache inconsistent with the filesystem state. +It is probably wise to do some consistency checking, +and rebuild the cache when inconsistencies are detected. +.SS Reading events from an inotify file descriptor +To determine what events have occurred, an application +.BR read (2)s +from the inotify file descriptor. +If no events have so far occurred, then, +assuming a blocking file descriptor, +.BR read (2) +will block until at least one event occurs +(unless interrupted by a signal, +in which case the call fails with the error +.BR EINTR ; +see +.BR signal (7)). +.P +Each successful +.BR read (2) +returns a buffer containing one or more of the following structures: +.P +.in +4n +.EX +struct inotify_event { + int wd; /* Watch descriptor */ +.\" FIXME . The type of the 'wd' field should probably be "int32_t". +.\" I submitted a patch to fix this. See the LKML thread +.\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008 +.\" glibc bug filed: https://www.sourceware.org/bugzilla/show_bug.cgi?id=7040 + uint32_t mask; /* Mask describing event */ + uint32_t cookie; /* Unique cookie associating related + events (for rename(2)) */ + uint32_t len; /* Size of \fIname\fP field */ + char name[]; /* Optional null\-terminated name */ +}; +.EE +.in +.P +.I wd +identifies the watch for which this event occurs. +It is one of the watch descriptors returned by a previous call to +.BR inotify_add_watch (2). +.P +.I mask +contains bits that describe the event that occurred (see below). +.P +.I cookie +is a unique integer that connects related events. +Currently, this is used only for rename events, and +allows the resulting pair of +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +events to be connected by the application. +For all other event types, +.I cookie +is set to 0. +.P +The +.I name +field is present only when an event is returned +for a file inside a watched directory; +it identifies the filename within the watched directory. +This filename is null-terminated, +and may include further null bytes (\[aq]\e0\[aq]) +to align subsequent reads to a suitable address boundary. +.P +The +.I len +field counts all of the bytes in +.IR name , +including the null bytes; +the length of each +.I inotify_event +structure is thus +.IR "sizeof(struct inotify_event)+len" . +.P +The behavior when the buffer given to +.BR read (2) +is too small to return information about the next event depends +on the kernel version: before Linux 2.6.21, +.BR read (2) +returns 0; since Linux 2.6.21, +.BR read (2) +fails with the error +.BR EINVAL . +Specifying a buffer of size +.P +.in +4n +.EX +sizeof(struct inotify_event) + NAME_MAX + 1 +.EE +.in +.P +will be sufficient to read at least one event. +.SS inotify events +The +.BR inotify_add_watch (2) +.I mask +argument and the +.I mask +field of the +.I inotify_event +structure returned when +.BR read (2)ing +an inotify file descriptor are both bit masks identifying +inotify events. +The following bits can be specified in +.I mask +when calling +.BR inotify_add_watch (2) +and may be returned in the +.I mask +field returned by +.BR read (2): +.RS 4 +.TP +.BR IN_ACCESS " (+)" +File was accessed (e.g., +.BR read (2), +.BR execve (2)). +.TP +.BR IN_ATTRIB " (*)" +Metadata changed\[em]for example, permissions (e.g., +.BR chmod (2)), +timestamps (e.g., +.BR utimensat (2)), +extended attributes +.RB ( setxattr (2)), +link count (since Linux 2.6.25; e.g., +.\" FIXME . +.\" Events do not occur for link count changes on a file inside a monitored +.\" directory. This differs from other metadata changes for files inside +.\" a monitored directory. +for the target of +.BR link (2) +and for +.BR unlink (2)), +and user/group ID (e.g., +.BR chown (2)). +.TP +.BR IN_CLOSE_WRITE " (+)" +File opened for writing was closed. +.TP +.BR IN_CLOSE_NOWRITE " (*)" +File or directory not opened for writing was closed. +.TP +.BR IN_CREATE " (+)" +File/directory created in watched directory (e.g., +.BR open (2) +.BR O_CREAT , +.BR mkdir (2), +.BR link (2), +.BR symlink (2), +.BR bind (2) +on a UNIX domain socket). +.TP +.BR IN_DELETE " (+)" +File/directory deleted from watched directory. +.TP +.B IN_DELETE_SELF +Watched file/directory was itself deleted. +(This event also occurs if an object is moved to another filesystem, +since +.BR mv (1) +in effect copies the file to the other filesystem and +then deletes it from the original filesystem.) +In addition, an +.B IN_IGNORED +event will subsequently be generated for the watch descriptor. +.TP +.BR IN_MODIFY " (+)" +File was modified (e.g., +.BR write (2), +.BR truncate (2)). +.TP +.B IN_MOVE_SELF +Watched file/directory was itself moved. +.TP +.BR IN_MOVED_FROM " (+)" +Generated for the directory containing the old filename +when a file is renamed. +.TP +.BR IN_MOVED_TO " (+)" +Generated for the directory containing the new filename +when a file is renamed. +.TP +.BR IN_OPEN " (*)" +File or directory was opened. +.RE +.P +Inotify monitoring is inode-based: when monitoring a file +(but not when monitoring the directory containing a file), +an event can be generated for activity on any link to the file +(in the same or a different directory). +.P +When monitoring a directory: +.IP \[bu] 3 +the events marked above with an asterisk (*) can occur both +for the directory itself and for objects inside the directory; and +.IP \[bu] +the events marked with a plus sign (+) occur only for objects +inside the directory (not for the directory itself). +.P +.IR Note : +when monitoring a directory, +events are not generated for the files inside the directory +when the events are performed via a pathname (i.e., a link) +that lies outside the monitored directory. +.P +When events are generated for objects inside a watched directory, the +.I name +field in the returned +.I inotify_event +structure identifies the name of the file within the directory. +.P +The +.B IN_ALL_EVENTS +macro is defined as a bit mask of all of the above events. +This macro can be used as the +.I mask +argument when calling +.BR inotify_add_watch (2). +.P +Two additional convenience macros are defined: +.RS 4 +.TP +.B IN_MOVE +Equates to +.BR "IN_MOVED_FROM | IN_MOVED_TO" . +.TP +.B IN_CLOSE +Equates to +.BR "IN_CLOSE_WRITE | IN_CLOSE_NOWRITE" . +.RE +.P +The following further bits can be specified in +.I mask +when calling +.BR inotify_add_watch (2): +.RS 4 +.TP +.BR IN_DONT_FOLLOW " (since Linux 2.6.15)" +Don't dereference +.I pathname +if it is a symbolic link. +.TP +.BR IN_EXCL_UNLINK " (since Linux 2.6.36)" +.\" commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6 +By default, when watching events on the children of a directory, +events are generated for children even after they have been unlinked +from the directory. +This can result in large numbers of uninteresting events for +some applications (e.g., if watching +.IR /tmp , +in which many applications create temporary files whose +names are immediately unlinked). +Specifying +.B IN_EXCL_UNLINK +changes the default behavior, +so that events are not generated for children after +they have been unlinked from the watched directory. +.TP +.B IN_MASK_ADD +If a watch instance already exists for the filesystem object corresponding to +.IR pathname , +add (OR) the events in +.I mask +to the watch mask (instead of replacing the mask); +the error +.B EINVAL +results if +.B IN_MASK_CREATE +is also specified. +.TP +.B IN_ONESHOT +Monitor the filesystem object corresponding to +.I pathname +for one event, then remove from +watch list. +.TP +.BR IN_ONLYDIR " (since Linux 2.6.15)" +Watch +.I pathname +only if it is a directory; +the error +.B ENOTDIR +results if +.I pathname +is not a directory. +Using this flag provides an application with a race-free way of +ensuring that the monitored object is a directory. +.TP +.BR IN_MASK_CREATE " (since Linux 4.18)" +Watch +.I pathname +only if it does not already have a watch associated with it; +the error +.B EEXIST +results if +.I pathname +is already being watched. +.IP +Using this flag provides an application with a way of ensuring +that new watches do not modify existing ones. +This is useful because multiple paths may refer to the same inode, +and multiple calls to +.BR inotify_add_watch (2) +without this flag may clobber existing watch masks. +.RE +.P +The following bits may be set in the +.I mask +field returned by +.BR read (2): +.RS 4 +.TP +.B IN_IGNORED +Watch was removed explicitly +.RB ( inotify_rm_watch (2)) +or automatically (file was deleted, or filesystem was unmounted). +See also BUGS. +.TP +.B IN_ISDIR +Subject of this event is a directory. +.TP +.B IN_Q_OVERFLOW +Event queue overflowed +.RI ( wd +is \-1 for this event). +.TP +.B IN_UNMOUNT +Filesystem containing watched object was unmounted. +In addition, an +.B IN_IGNORED +event will subsequently be generated for the watch descriptor. +.RE +.SS Examples +Suppose an application is watching the directory +.I dir +and the file +.I dir/myfile +for all events. +The examples below show some events that will be generated +for these two objects. +.RS 4 +.TP +fd = open("dir/myfile", O_RDWR); +Generates +.B IN_OPEN +events for both +.I dir +and +.IR dir/myfile . +.TP +read(fd, buf, count); +Generates +.B IN_ACCESS +events for both +.I dir +and +.IR dir/myfile . +.TP +write(fd, buf, count); +Generates +.B IN_MODIFY +events for both +.I dir +and +.IR dir/myfile . +.TP +fchmod(fd, mode); +Generates +.B IN_ATTRIB +events for both +.I dir +and +.IR dir/myfile . +.TP +close(fd); +Generates +.B IN_CLOSE_WRITE +events for both +.I dir +and +.IR dir/myfile . +.RE +.P +Suppose an application is watching the directories +.I dir1 +and +.IR dir2 , +and the file +.IR dir1/myfile . +The following examples show some events that may be generated. +.RS 4 +.TP +link("dir1/myfile", "dir2/new"); +Generates an +.B IN_ATTRIB +event for +.I myfile +and an +.B IN_CREATE +event for +.IR dir2 . +.TP +rename("dir1/myfile", "dir2/myfile"); +Generates an +.B IN_MOVED_FROM +event for +.IR dir1 , +an +.B IN_MOVED_TO +event for +.IR dir2 , +and an +.B IN_MOVE_SELF +event for +.IR myfile . +The +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +events will have the same +.I cookie +value. +.RE +.P +Suppose that +.I dir1/xx +and +.I dir2/yy +are (the only) links to the same file, and an application is watching +.IR dir1 , +.IR dir2 , +.IR dir1/xx , +and +.IR dir2/yy . +Executing the following calls in the order given below will generate +the following events: +.RS 4 +.TP +unlink("dir2/yy"); +Generates an +.B IN_ATTRIB +event for +.I xx +(because its link count changes) +and an +.B IN_DELETE +event for +.IR dir2 . +.TP +unlink("dir1/xx"); +Generates +.BR IN_ATTRIB , +.BR IN_DELETE_SELF , +and +.B IN_IGNORED +events for +.IR xx , +and an +.B IN_DELETE +event for +.IR dir1 . +.RE +.P +Suppose an application is watching the directory +.I dir +and (the empty) directory +.IR dir/subdir . +The following examples show some events that may be generated. +.RS 4 +.TP +mkdir("dir/new", mode); +Generates an +.B "IN_CREATE | IN_ISDIR" +event for +.IR dir . +.TP +rmdir("dir/subdir"); +Generates +.B IN_DELETE_SELF +and +.B IN_IGNORED +events for +.IR subdir , +and an +.B "IN_DELETE | IN_ISDIR" +event for +.IR dir . +.RE +.SS /proc interfaces +The following interfaces can be used to limit the amount of +kernel memory consumed by inotify: +.TP +.I /proc/sys/fs/inotify/max_queued_events +The value in this file is used when an application calls +.BR inotify_init (2) +to set an upper limit on the number of events that can be +queued to the corresponding inotify instance. +Events in excess of this limit are dropped, but an +.B IN_Q_OVERFLOW +event is always generated. +.TP +.I /proc/sys/fs/inotify/max_user_instances +This specifies an upper limit on the number of inotify instances +that can be created per real user ID. +.TP +.I /proc/sys/fs/inotify/max_user_watches +This specifies an upper limit on the number of watches +that can be created per real user ID. +.SH STANDARDS +Linux. +.SH HISTORY +Inotify was merged into Linux 2.6.13. +The required library interfaces were added in glibc 2.4. +.RB ( IN_DONT_FOLLOW , +.BR IN_MASK_ADD , +and +.B IN_ONLYDIR +were added in glibc 2.5.) +.SH NOTES +Inotify file descriptors can be monitored using +.BR select (2), +.BR poll (2), +and +.BR epoll (7). +When an event is available, the file descriptor indicates as readable. +.P +Since Linux 2.6.25, +signal-driven I/O notification is available for inotify file descriptors; +see the discussion of +.B F_SETFL +(for setting the +.B O_ASYNC +flag), +.BR F_SETOWN , +and +.B F_SETSIG +in +.BR fcntl (2). +The +.I siginfo_t +structure (described in +.BR sigaction (2)) +that is passed to the signal handler has the following fields set: +.I si_fd +is set to the inotify file descriptor number; +.I si_signo +is set to the signal number; +.I si_code +is set to +.BR POLL_IN ; +and +.B POLLIN +is set in +.IR si_band . +.P +If successive output inotify events produced on the +inotify file descriptor are identical (same +.IR wd , +.IR mask , +.IR cookie , +and +.IR name ), +then they are coalesced into a single event if the +older event has not yet been read (but see BUGS). +This reduces the amount of kernel memory required for the event queue, +but also means that an application can't use inotify to reliably count +file events. +.P +The events returned by reading from an inotify file descriptor +form an ordered queue. +Thus, for example, it is guaranteed that when renaming from +one directory to another, events will be produced in the +correct order on the inotify file descriptor. +.P +The set of watch descriptors that is being monitored via +an inotify file descriptor can be viewed via the entry for +the inotify file descriptor in the process's +.IR /proc/ pid /fdinfo +directory. +See +.BR proc (5) +for further details. +The +.B FIONREAD +.BR ioctl (2) +returns the number of bytes available to read from an +inotify file descriptor. +.SS Limitations and caveats +The inotify API provides no information about the user or process that +triggered the inotify event. +In particular, there is no easy +way for a process that is monitoring events via inotify +to distinguish events that it triggers +itself from those that are triggered by other processes. +.P +Inotify reports only events that a user-space program triggers through +the filesystem API. +As a result, it does not catch remote events that occur +on network filesystems. +(Applications must fall back to polling the filesystem +to catch such events.) +Furthermore, various pseudo-filesystems such as +.IR /proc , +.IR /sys , +and +.I /dev/pts +are not monitorable with inotify. +.P +The inotify API does not report file accesses and modifications that +may occur because of +.BR mmap (2), +.BR msync (2), +and +.BR munmap (2). +.P +The inotify API identifies affected files by filename. +However, by the time an application processes an inotify event, +the filename may already have been deleted or renamed. +.P +The inotify API identifies events via watch descriptors. +It is the application's responsibility to cache a mapping +(if one is needed) between watch descriptors and pathnames. +Be aware that directory renamings may affect multiple cached pathnames. +.P +Inotify monitoring of directories is not recursive: +to monitor subdirectories under a directory, +additional watches must be created. +This can take a significant amount time for large directory trees. +.P +If monitoring an entire directory subtree, +and a new subdirectory is created in that tree or an existing directory +is renamed into that tree, +be aware that by the time you create a watch for the new subdirectory, +new files (and subdirectories) may already exist inside the subdirectory. +Therefore, you may want to scan the contents of the subdirectory +immediately after adding the watch (and, if desired, +recursively add watches for any subdirectories that it contains). +.P +Note that the event queue can overflow. +In this case, events are lost. +Robust applications should handle the possibility of +lost events gracefully. +For example, it may be necessary to rebuild part or all of +the application cache. +(One simple, but possibly expensive, +approach is to close the inotify file descriptor, empty the cache, +create a new inotify file descriptor, +and then re-create watches and cache entries +for the objects to be monitored.) +.P +If a filesystem is mounted on top of a monitored directory, +no event is generated, and no events are generated +for objects immediately under the new mount point. +If the filesystem is subsequently unmounted, +events will subsequently be generated for the directory and +the objects it contains. +.\" +.SS Dealing with rename() events +As noted above, the +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +event pair that is generated by +.BR rename (2) +can be matched up via their shared cookie value. +However, the task of matching has some challenges. +.P +These two events are usually consecutive in the event stream available +when reading from the inotify file descriptor. +However, this is not guaranteed. +If multiple processes are triggering events for monitored objects, +then (on rare occasions) an arbitrary number of +other events may appear between the +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +events. +Furthermore, it is not guaranteed that the event pair is atomically +inserted into the queue: there may be a brief interval where the +.B IN_MOVED_FROM +has appeared, but the +.B IN_MOVED_TO +has not. +.P +Matching up the +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +event pair generated by +.BR rename (2) +is thus inherently racy. +(Don't forget that if an object is renamed outside of a monitored directory, +there may not even be an +.B IN_MOVED_TO +event.) +Heuristic approaches (e.g., assume the events are always consecutive) +can be used to ensure a match in most cases, +but will inevitably miss some cases, +causing the application to perceive the +.B IN_MOVED_FROM +and +.B IN_MOVED_TO +events as being unrelated. +If watch descriptors are destroyed and re-created as a result, +then those watch descriptors will be inconsistent with +the watch descriptors in any pending events. +(Re-creating the inotify file descriptor and rebuilding the cache may +be useful to deal with this scenario.) +.P +Applications should also allow for the possibility that the +.B IN_MOVED_FROM +event was the last event that could fit in the buffer +returned by the current call to +.BR read (2), +and the accompanying +.B IN_MOVED_TO +event might be fetched only on the next +.BR read (2), +which should be done with a (small) timeout to allow for the fact that +insertion of the +.BR IN_MOVED_FROM + IN_MOVED_TO +event pair is not atomic, +and also the possibility that there may not be any +.B IN_MOVED_TO +event. +.SH BUGS +Before Linux 3.19, +.BR fallocate (2) +did not create any inotify events. +Since Linux 3.19, +.\" commit 820c12d5d6c0890bc93dd63893924a13041fdc35 +calls to +.BR fallocate (2) +generate +.B IN_MODIFY +events. +.P +.\" FIXME . kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321 +.\" implies that unmount events were buggy since Linux 2.6.11 to Linux 2.6.36 +.\" +Before Linux 2.6.16, the +.B IN_ONESHOT +.I mask +flag does not work. +.P +As originally designed and implemented, the +.B IN_ONESHOT +flag did not cause an +.B IN_IGNORED +event to be generated when the watch was dropped after one event. +However, as an unintended effect of other changes, +since Linux 2.6.36, an +.B IN_IGNORED +event is generated in this case. +.P +Before Linux 2.6.25, +.\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2 +the kernel code that was intended to coalesce successive identical events +(i.e., the two most recent events could potentially be coalesced +if the older had not yet been read) +instead checked if the most recent event could be coalesced with the +.I oldest +unread event. +.P +When a watch descriptor is removed by calling +.BR inotify_rm_watch (2) +(or because a watch file is deleted or the filesystem +that contains it is unmounted), +any pending unread events for that watch descriptor remain available to read. +As watch descriptors are subsequently allocated with +.BR inotify_add_watch (2), +the kernel cycles through the range of possible watch descriptors (1 to +.BR INT_MAX ) +incrementally. +When allocating a free watch descriptor, no check is made to see whether that +watch descriptor number has any pending unread events in the inotify queue. +Thus, it can happen that a watch descriptor is reallocated even +when pending unread events exist for a previous incarnation of +that watch descriptor number, with the result that the application +might then read those events and interpret them as belonging to +the file associated with the newly recycled watch descriptor. +In practice, the likelihood of hitting this bug may be extremely low, +since it requires that an application cycle through +.B INT_MAX +watch descriptors, +release a watch descriptor while leaving unread events for that +watch descriptor in the queue, +and then recycle that watch descriptor. +For this reason, and because there have been no reports +of the bug occurring in real-world applications, +as of Linux 3.15, +.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=77111 +no kernel changes have yet been made to eliminate this possible bug. +.SH EXAMPLES +The following program demonstrates the usage of the inotify API. +It marks the directories passed as a command-line arguments +and waits for events of type +.BR IN_OPEN , +.BR IN_CLOSE_NOWRITE , +and +.BR IN_CLOSE_WRITE . +.P +The following output was recorded while editing the file +.I /home/user/temp/foo +and listing directory +.IR /tmp . +Before the file and the directory were opened, +.B IN_OPEN +events occurred. +After the file was closed, an +.B IN_CLOSE_WRITE +event occurred. +After the directory was closed, an +.B IN_CLOSE_NOWRITE +event occurred. +Execution of the program ended when the user pressed the ENTER key. +.SS Example output +.in +4n +.EX +$ \fB./a.out /tmp /home/user/temp\fP +Press enter key to terminate. +Listening for events. +IN_OPEN: /home/user/temp/foo [file] +IN_CLOSE_WRITE: /home/user/temp/foo [file] +IN_OPEN: /tmp/ [directory] +IN_CLOSE_NOWRITE: /tmp/ [directory] +\& +Listening for events stopped. +.EE +.in +.SS Program source +\& +.EX +#include +#include +#include +#include +#include +#include +#include +\& +/* Read all available inotify events from the file descriptor \[aq]fd\[aq]. + wd is the table of watch descriptors for the directories in argv. + argc is the length of wd and argv. + argv is the list of watched directories. + Entry 0 of wd and argv is unused. */ +\& +static void +handle_events(int fd, int *wd, int argc, char* argv[]) +{ + /* Some systems cannot read integer variables if they are not + properly aligned. On other systems, incorrect alignment may + decrease performance. Hence, the buffer used for reading from + the inotify file descriptor should have the same alignment as + struct inotify_event. */ +\& + char buf[4096] + __attribute__ ((aligned(__alignof__(struct inotify_event)))); + const struct inotify_event *event; + ssize_t len; +\& + /* Loop while events can be read from inotify file descriptor. */ +\& + for (;;) { +\& + /* Read some events. */ +\& + len = read(fd, buf, sizeof(buf)); + if (len == \-1 && errno != EAGAIN) { + perror("read"); + exit(EXIT_FAILURE); + } +\& + /* If the nonblocking read() found no events to read, then + it returns \-1 with errno set to EAGAIN. In that case, + we exit the loop. */ +\& + if (len <= 0) + break; +\& + /* Loop over all events in the buffer. */ +\& + for (char *ptr = buf; ptr < buf + len; + ptr += sizeof(struct inotify_event) + event\->len) { +\& + event = (const struct inotify_event *) ptr; +\& + /* Print event type. */ +\& + if (event\->mask & IN_OPEN) + printf("IN_OPEN: "); + if (event\->mask & IN_CLOSE_NOWRITE) + printf("IN_CLOSE_NOWRITE: "); + if (event\->mask & IN_CLOSE_WRITE) + printf("IN_CLOSE_WRITE: "); +\& + /* Print the name of the watched directory. */ +\& + for (size_t i = 1; i < argc; ++i) { + if (wd[i] == event\->wd) { + printf("%s/", argv[i]); + break; + } + } +\& + /* Print the name of the file. */ +\& + if (event\->len) + printf("%s", event\->name); +\& + /* Print type of filesystem object. */ +\& + if (event\->mask & IN_ISDIR) + printf(" [directory]\en"); + else + printf(" [file]\en"); + } + } +} +\& +int +main(int argc, char* argv[]) +{ + char buf; + int fd, i, poll_num; + int *wd; + nfds_t nfds; + struct pollfd fds[2]; +\& + if (argc < 2) { + printf("Usage: %s PATH [PATH ...]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + printf("Press ENTER key to terminate.\en"); +\& + /* Create the file descriptor for accessing the inotify API. */ +\& + fd = inotify_init1(IN_NONBLOCK); + if (fd == \-1) { + perror("inotify_init1"); + exit(EXIT_FAILURE); + } +\& + /* Allocate memory for watch descriptors. */ +\& + wd = calloc(argc, sizeof(int)); + if (wd == NULL) { + perror("calloc"); + exit(EXIT_FAILURE); + } +\& + /* Mark directories for events + \- file was opened + \- file was closed */ +\& + for (i = 1; i < argc; i++) { + wd[i] = inotify_add_watch(fd, argv[i], + IN_OPEN | IN_CLOSE); + if (wd[i] == \-1) { + fprintf(stderr, "Cannot watch \[aq]%s\[aq]: %s\en", + argv[i], strerror(errno)); + exit(EXIT_FAILURE); + } + } +\& + /* Prepare for polling. */ +\& + nfds = 2; +\& + fds[0].fd = STDIN_FILENO; /* Console input */ + fds[0].events = POLLIN; +\& + fds[1].fd = fd; /* Inotify input */ + fds[1].events = POLLIN; +\& + /* Wait for events and/or terminal input. */ +\& + printf("Listening for events.\en"); + while (1) { + poll_num = poll(fds, nfds, \-1); + if (poll_num == \-1) { + if (errno == EINTR) + continue; + perror("poll"); + exit(EXIT_FAILURE); + } +\& + if (poll_num > 0) { +\& + if (fds[0].revents & POLLIN) { +\& + /* Console input is available. Empty stdin and quit. */ +\& + while (read(STDIN_FILENO, &buf, 1) > 0 && buf != \[aq]\en\[aq]) + continue; + break; + } +\& + if (fds[1].revents & POLLIN) { +\& + /* Inotify events are available. */ +\& + handle_events(fd, wd, argc, argv); + } + } + } +\& + printf("Listening for events stopped.\en"); +\& + /* Close inotify file descriptor. */ +\& + close(fd); +\& + free(wd); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR inotifywait (1), +.BR inotifywatch (1), +.BR inotify_add_watch (2), +.BR inotify_init (2), +.BR inotify_init1 (2), +.BR inotify_rm_watch (2), +.BR read (2), +.BR stat (2), +.BR fanotify (7) +.P +.I Documentation/filesystems/inotify.txt +in the Linux kernel source tree diff --git a/man/man7/intro.7 b/man/man7/intro.7 new file mode 100644 index 0000000..1bb6658 --- /dev/null +++ b/man/man7/intro.7 @@ -0,0 +1,23 @@ +.\" Copyright (c) 1993 Michael Haardt +.\" (michael@moria.de), Fri Apr 2 11:32:09 MET DST +.\" 1993 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified by Thomas Koenig (ig25@rz.uni-karlsruhe.de) 24 Apr 1993 +.\" Modified Sat Jul 24 17:28:08 1993 by Rik Faith (faith@cs.unc.edu) +.TH intro 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intro \- introduction to overview and miscellany section +.SH DESCRIPTION +Section 7 of the manual provides overviews on various topics, and +describes conventions and protocols, +character set standards, the standard filesystem layout, +and miscellaneous other things. +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! +.SH SEE ALSO +.BR standards (7) diff --git a/man/man7/ip.7 b/man/man7/ip.7 new file mode 100644 index 0000000..92f7543 --- /dev/null +++ b/man/man7/ip.7 @@ -0,0 +1,1541 @@ +'\" t +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $ +.\" +.\" FIXME The following socket options are yet to be documented +.\" +.\" IP_XFRM_POLICY (2.5.48) +.\" Needs CAP_NET_ADMIN +.\" +.\" IP_IPSEC_POLICY (2.5.47) +.\" Needs CAP_NET_ADMIN +.\" +.\" IP_MINTTL (2.6.34) +.\" commit d218d11133d888f9745802146a50255a4781d37a +.\" Author: Stephen Hemminger +.\" +.\" MCAST_JOIN_GROUP (2.4.22 / 2.6) +.\" +.\" MCAST_BLOCK_SOURCE (2.4.22 / 2.6) +.\" +.\" MCAST_UNBLOCK_SOURCE (2.4.22 / 2.6) +.\" +.\" MCAST_LEAVE_GROUP (2.4.22 / 2.6) +.\" +.\" MCAST_JOIN_SOURCE_GROUP (2.4.22 / 2.6) +.\" +.\" MCAST_LEAVE_SOURCE_GROUP (2.4.22 / 2.6) +.\" +.\" MCAST_MSFILTER (2.4.22 / 2.6) +.\" +.\" IP_UNICAST_IF (3.4) +.\" commit 76e21053b5bf33a07c76f99d27a74238310e3c71 +.\" Author: Erich E. Hoover +.\" +.TH ip 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ip \- Linux IPv4 protocol implementation +.SH SYNOPSIS +.nf +.B #include +.\" .B #include -- does not exist anymore +.\" .B #include -- never include +.B #include +.B #include \fR/* superset of previous */ +.P +.IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" +.IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" +.IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");" +.fi +.SH DESCRIPTION +Linux implements the Internet Protocol, version 4, +described in RFC\ 791 and RFC\ 1122. +.B ip +contains a level 2 multicasting implementation conforming to RFC\ 1112. +It also contains an IP router including a packet filter. +.P +The programming interface is BSD-sockets compatible. +For more information on sockets, see +.BR socket (7). +.P +An IP socket is created using +.BR socket (2): +.P +.in +4n +.EX +socket(AF_INET, socket_type, protocol); +.EE +.in +.P +Valid socket types include +.B SOCK_STREAM +to open a stream socket, +.B SOCK_DGRAM +to open a datagram socket, and +.B SOCK_RAW +to open a +.BR raw (7) +socket to access the IP protocol directly. +.P +.I protocol +is the IP protocol in the IP header to be received or sent. +Valid values for +.I protocol +include: +.IP \[bu] 3 +0 and +.B IPPROTO_TCP +for +.BR tcp (7) +stream sockets; +.IP \[bu] +0 and +.B IPPROTO_UDP +for +.BR udp (7) +datagram sockets; +.IP \[bu] +.B IPPROTO_SCTP +for +.BR sctp (7) +stream sockets; and +.IP \[bu] +.B IPPROTO_UDPLITE +for +.BR udplite (7) +datagram sockets. +.P +For +.B SOCK_RAW +you may specify a valid IANA IP protocol defined in +RFC\ 1700 assigned numbers. +.P +When a process wants to receive new incoming packets or connections, it +should bind a socket to a local interface address using +.BR bind (2). +In this case, only one IP socket may be bound to any given local +(address, port) pair. +When +.B INADDR_ANY +is specified in the bind call, the socket will be bound to +.I all +local interfaces. +When +.BR listen (2) +is called on an unbound socket, the socket is automatically bound +to a random free port with the local address set to +.BR INADDR_ANY . +When +.BR connect (2) +is called on an unbound socket, the socket is automatically bound +to a random free port or to a usable shared port with the local address +set to +.BR INADDR_ANY . +.P +A TCP local socket address that has been bound is unavailable for +some time after closing, unless the +.B SO_REUSEADDR +flag has been set. +Care should be taken when using this flag as it makes TCP less reliable. +.SS Address format +An IP socket address is defined as a combination of an IP interface +address and a 16-bit port number. +The basic IP protocol does not supply port numbers, they +are implemented by higher level protocols like +.BR udp (7) +and +.BR tcp (7). +On raw sockets +.I sin_port +is set to the IP protocol. +.P +.in +4n +.EX +struct sockaddr_in { + sa_family_t sin_family; /* address family: AF_INET */ + in_port_t sin_port; /* port in network byte order */ + struct in_addr sin_addr; /* internet address */ +}; +\& +/* Internet address */ +struct in_addr { + uint32_t s_addr; /* address in network byte order */ +}; +.EE +.in +.P +.I sin_family +is always set to +.BR AF_INET . +This is required; in Linux 2.2 most networking functions return +.B EINVAL +when this setting is missing. +.I sin_port +contains the port in network byte order. +The port numbers below 1024 are called +.I privileged ports +(or sometimes: +.IR "reserved ports" ). +Only a privileged process +(on Linux: a process that has the +.B CAP_NET_BIND_SERVICE +capability in the user namespace governing its network namespace) may +.BR bind (2) +to these sockets. +Note that the raw IPv4 protocol as such has no concept of a +port, they are implemented only by higher protocols like +.BR tcp (7) +and +.BR udp (7). +.P +.I sin_addr +is the IP host address. +The +.I s_addr +member of +.I struct in_addr +contains the host interface address in network byte order. +.I in_addr +should be assigned one of the +.B INADDR_* +values +(e.g., +.BR INADDR_LOOPBACK ) +using +.BR htonl (3) +or set using the +.BR inet_aton (3), +.BR inet_addr (3), +.BR inet_makeaddr (3) +library functions or directly with the name resolver (see +.BR gethostbyname (3)). +.P +IPv4 addresses are divided into unicast, broadcast, +and multicast addresses. +Unicast addresses specify a single interface of a host, +broadcast addresses specify all hosts on a network, and multicast +addresses address all hosts in a multicast group. +Datagrams to broadcast addresses can be sent or received only when the +.B SO_BROADCAST +socket flag is set. +In the current implementation, connection-oriented sockets are allowed +to use only unicast addresses. +.\" Leave a loophole for XTP @) +.P +Note that the address and the port are always stored in +network byte order. +In particular, this means that you need to call +.BR htons (3) +on the number that is assigned to a port. +All address/port manipulation +functions in the standard library work in network byte order. +.SS Special and reserved addresses +There are several special addresses: +.TP +.BR INADDR_LOOPBACK " (127.0.0.1)" +always refers to the local host via the loopback device; +.TP +.BR INADDR_ANY " (0.0.0.0)" +means any address for socket binding; +.TP +.BR INADDR_BROADCAST " (255.255.255.255)" +has the same effect on +.BR bind (2) +as +.B INADDR_ANY +for historical reasons. +A packet addressed to +.B INADDR_BROADCAST +through a socket which has +.B SO_BROADCAST +set will be broadcast to all hosts on the local network segment, +as long as the link is broadcast-capable. +.TP +Highest-numbered address +.TQ +Lowest-numbered address +On any locally-attached non-point-to-point IP subnet +with a link type that supports broadcasts, +the highest-numbered address +(e.g., the .255 address on a subnet with netmask 255.255.255.0) +is designated as a broadcast address. +It cannot usefully be assigned to an individual interface, +and can only be addressed with a socket on which the +.B SO_BROADCAST +option has been set. +Internet standards have historically +also reserved the lowest-numbered address +(e.g., the .0 address on a subnet with netmask 255.255.255.0) +for broadcast, though they call it "obsolete" for this purpose. +(Some sources also refer to this as the "network address.") +Since Linux 5.14, +.\" commit 58fee5fc83658aaacf60246aeab738946a9ba516 +it is treated as an ordinary unicast address +and can be assigned to an interface. +.P +Internet standards have traditionally also reserved various addresses +for particular uses, though Linux no longer treats +some of these specially. +.TP +[0.0.0.1, 0.255.255.255] +.TQ +[240.0.0.0, 255.255.255.254] +Addresses in these ranges (0/8 and 240/4) are reserved globally. +Since Linux 5.3 +.\" commit 96125bf9985a75db00496dd2bc9249b777d2b19b +and Linux 2.6.25, +.\" commit 1e637c74b0f84eaca02b914c0b8c6f67276e9697 +respectively, +the 0/8 and 240/4 addresses, other than +.B INADDR_ANY +and +.BR INADDR_BROADCAST , +are treated as ordinary unicast addresses. +Systems that follow the traditional behaviors may not +interoperate with these historically reserved addresses. +.TP +[127.0.0.1, 127.255.255.254] +Addresses in this range (127/8) are treated as loopback addresses +akin to the standardized local loopback address +.B INADDR_LOOPBACK +(127.0.0.1); +.TP +[224.0.0.0, 239.255.255.255] +Addresses in this range (224/4) are dedicated to multicast use. +.SS Socket options +IP supports some protocol-specific socket options that can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2). +The socket option level for IP is +.BR IPPROTO_IP . +.\" or SOL_IP on Linux +A boolean integer flag is zero when it is false, otherwise true. +.P +When an invalid socket option is specified, +.BR getsockopt (2) +and +.BR setsockopt (2) +fail with the error +.BR ENOPROTOOPT . +.TP +.BR IP_ADD_MEMBERSHIP " (since Linux 1.2)" +Join a multicast group. +Argument is an +.I ip_mreqn +structure. +.IP +.in +4n +.EX +struct ip_mreqn { + struct in_addr imr_multiaddr; /* IP multicast group + address */ + struct in_addr imr_address; /* IP address of local + interface */ + int imr_ifindex; /* interface index */ +}; +.EE +.in +.IP +.I imr_multiaddr +contains the address of the multicast group the application +wants to join or leave. +It must be a valid multicast address +.\" (i.e., within the 224.0.0.0-239.255.255.255 range) +(or +.BR setsockopt (2) +fails with the error +.BR EINVAL ). +.I imr_address +is the address of the local interface with which the system +should join the multicast group; if it is equal to +.BR INADDR_ANY , +an appropriate interface is chosen by the system. +.I imr_ifindex +is the interface index of the interface that should join/leave the +.I imr_multiaddr +group, or 0 to indicate any interface. +.IP +The +.I ip_mreqn +structure is available only since Linux 2.2. +For compatibility, the old +.I ip_mreq +structure (present since Linux 1.2) is still supported; +it differs from +.I ip_mreqn +only by not including the +.I imr_ifindex +field. +(The kernel determines which structure is being passed based +on the size passed in +.IR optlen .) +.IP +.B IP_ADD_MEMBERSHIP +is valid only for +.BR setsockopt (2). +.\" +.TP +.BR IP_ADD_SOURCE_MEMBERSHIP " (since Linux 2.4.22 / Linux 2.5.68)" +Join a multicast group and allow receiving data only +from a specified source. +Argument is an +.I ip_mreq_source +structure. +.IP +.in +4n +.EX +struct ip_mreq_source { + struct in_addr imr_multiaddr; /* IP multicast group + address */ + struct in_addr imr_interface; /* IP address of local + interface */ + struct in_addr imr_sourceaddr; /* IP address of + multicast source */ +}; +.EE +.in +.IP +The +.I ip_mreq_source +structure is similar to +.I ip_mreqn +described under +.BR IP_ADD_MEMBERSHIP . +The +.I imr_multiaddr +field contains the address of the multicast group the application +wants to join or leave. +The +.I imr_interface +field is the address of the local interface with which +the system should join the multicast group. +Finally, the +.I imr_sourceaddr +field contains the address of the source the +application wants to receive data from. +.IP +This option can be used multiple times to allow +receiving data from more than one source. +.TP +.BR IP_BIND_ADDRESS_NO_PORT " (since Linux 4.2)" +.\" commit 90c337da1524863838658078ec34241f45d8394d +Inform the kernel to not reserve an ephemeral port when using +.BR bind (2) +with a port number of 0. +The port will later be automatically chosen at +.BR connect (2) +time, +in a way that allows sharing a source port as long as the 4-tuple is unique. +.TP +.BR IP_BLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)" +Stop receiving multicast data from a specific source in a given group. +This is valid only after the application has subscribed +to the multicast group using either +.B IP_ADD_MEMBERSHIP +or +.BR IP_ADD_SOURCE_MEMBERSHIP . +.IP +Argument is an +.I ip_mreq_source +structure as described under +.BR IP_ADD_SOURCE_MEMBERSHIP . +.TP +.BR IP_DROP_MEMBERSHIP " (since Linux 1.2)" +Leave a multicast group. +Argument is an +.I ip_mreqn +or +.I ip_mreq +structure similar to +.BR IP_ADD_MEMBERSHIP . +.TP +.BR IP_DROP_SOURCE_MEMBERSHIP " (since Linux 2.4.22 / 2.5.68)" +Leave a source-specific group\[em]that is, stop receiving data from +a given multicast group that come from a given source. +If the application has subscribed to multiple sources within +the same group, data from the remaining sources will still be delivered. +To stop receiving data from all sources at once, use +.BR IP_DROP_MEMBERSHIP . +.IP +Argument is an +.I ip_mreq_source +structure as described under +.BR IP_ADD_SOURCE_MEMBERSHIP . +.TP +.BR IP_FREEBIND " (since Linux 2.4)" +.\" Precisely: since Linux 2.4.0-test10 +If enabled, this boolean option allows binding to an IP address +that is nonlocal or does not (yet) exist. +This permits listening on a socket, +without requiring the underlying network interface or the +specified dynamic IP address to be up at the time that +the application is trying to bind to it. +This option is the per-socket equivalent of the +.I ip_nonlocal_bind +.I /proc +interface described below. +.TP +.BR IP_HDRINCL " (since Linux 2.0)" +If enabled, +the user supplies an IP header in front of the user data. +Valid only for +.B SOCK_RAW +sockets; see +.BR raw (7) +for more information. +When this flag is enabled, the values set by +.BR IP_OPTIONS , +.BR IP_TTL , +and +.B IP_TOS +are ignored. +.TP +.BR IP_LOCAL_PORT_RANGE " (since Linux 6.3)" +Set or get the per-socket default local port range. +This option can be used to clamp down the global local port range, +defined by the +.I ip_local_port_range +.I /proc +interface described below, for a given socket. +.IP +The option takes an +.I uint32_t +value with +the high 16 bits set to the upper range bound, +and the low 16 bits set to the lower range bound. +Range bounds are inclusive. +The 16-bit values should be in host byte order. +.IP +The lower bound has to be less than the upper bound +when both bounds are not zero. +Otherwise, setting the option fails with EINVAL. +.IP +If either bound is outside of the global local port range, or is zero, +then that bound has no effect. +.IP +To reset the setting, +pass zero as both the upper and the lower bound. +.TP +.BR IP_MSFILTER " (since Linux 2.4.22 / 2.5.68)" +This option provides access to the advanced full-state filtering API. +Argument is an +.I ip_msfilter +structure. +.IP +.in +4n +.EX +struct ip_msfilter { + struct in_addr imsf_multiaddr; /* IP multicast group + address */ + struct in_addr imsf_interface; /* IP address of local + interface */ + uint32_t imsf_fmode; /* Filter\-mode */ +\& + uint32_t imsf_numsrc; /* Number of sources in + the following array */ + struct in_addr imsf_slist[1]; /* Array of source + addresses */ +}; +.EE +.in +.IP +There are two macros, +.B MCAST_INCLUDE +and +.BR MCAST_EXCLUDE , +which can be used to specify the filtering mode. +Additionally, the +.BR IP_MSFILTER_SIZE (n) +macro exists to determine how much memory is needed to store +.I ip_msfilter +structure with +.I n +sources in the source list. +.IP +For the full description of multicast source filtering +refer to RFC 3376. +.TP +.BR IP_MTU " (since Linux 2.2)" +.\" Precisely: since Linux 2.1.124 +Retrieve the current known path MTU of the current socket. +Returns an integer. +.IP +.B IP_MTU +is valid only for +.BR getsockopt (2) +and can be employed only when the socket has been connected. +.TP +.BR IP_MTU_DISCOVER " (since Linux 2.2)" +.\" Precisely: since Linux 2.1.124 +Set or receive the Path MTU Discovery setting for a socket. +When enabled, Linux will perform Path MTU Discovery +as defined in RFC\ 1191 on +.B SOCK_STREAM +sockets. +For +.RB non- SOCK_STREAM +sockets, +.B IP_PMTUDISC_DO +forces the don't-fragment flag to be set on all outgoing packets. +It is the user's responsibility to packetize the data +in MTU-sized chunks and to do the retransmits if necessary. +The kernel will reject (with +.BR EMSGSIZE ) +datagrams that are bigger than the known path MTU. +.B IP_PMTUDISC_WANT +will fragment a datagram if needed according to the path MTU, +or will set the don't-fragment flag otherwise. +.IP +The system-wide default can be toggled between +.B IP_PMTUDISC_WANT +and +.B IP_PMTUDISC_DONT +by writing (respectively, zero and nonzero values) to the +.I /proc/sys/net/ipv4/ip_no_pmtu_disc +file. +.TS +tab(:); +c l +l l. +Path MTU discovery value:Meaning +IP_PMTUDISC_WANT:Use per-route settings. +IP_PMTUDISC_DONT:Never do Path MTU Discovery. +IP_PMTUDISC_DO:Always do Path MTU Discovery. +IP_PMTUDISC_PROBE:Set DF but ignore Path MTU. +.TE +.IP +When PMTU discovery is enabled, the kernel automatically keeps track of +the path MTU per destination host. +When it is connected to a specific peer with +.BR connect (2), +the currently known path MTU can be retrieved conveniently using the +.B IP_MTU +socket option (e.g., after an +.B EMSGSIZE +error occurred). +The path MTU may change over time. +For connectionless sockets with many destinations, +the new MTU for a given destination can also be accessed using the +error queue (see +.BR IP_RECVERR ). +A new error will be queued for every incoming MTU update. +.IP +While MTU discovery is in progress, initial packets from datagram sockets +may be dropped. +Applications using UDP should be aware of this and not +take it into account for their packet retransmit strategy. +.IP +To bootstrap the path MTU discovery process on unconnected sockets, it +is possible to start with a big datagram size +(headers up to 64 kilobytes long) and let it shrink by updates of the path MTU. +.IP +To get an initial estimate of the +path MTU, connect a datagram socket to the destination address using +.BR connect (2) +and retrieve the MTU by calling +.BR getsockopt (2) +with the +.B IP_MTU +option. +.IP +It is possible to implement RFC 4821 MTU probing with +.B SOCK_DGRAM +or +.B SOCK_RAW +sockets by setting a value of +.B IP_PMTUDISC_PROBE +(available since Linux 2.6.22). +This is also particularly useful for diagnostic tools such as +.BR tracepath (8) +that wish to deliberately send probe packets larger than +the observed Path MTU. +.TP +.BR IP_MULTICAST_ALL " (since Linux 2.6.31)" +This option can be used to modify the delivery policy of multicast messages. +The argument is a boolean integer (defaults to 1). +If set to 1, +the socket will receive messages from all the groups that have been joined +globally on the whole system. +Otherwise, it will deliver messages only from +the groups that have been explicitly joined (for example via the +.B IP_ADD_MEMBERSHIP +option) on this particular socket. +.TP +.BR IP_MULTICAST_IF " (since Linux 1.2)" +Set the local device for a multicast socket. +The argument for +.BR setsockopt (2) +is an +.I ip_mreqn +or +.\" net: IP_MULTICAST_IF setsockopt now recognizes struct mreq +.\" Commit: 3a084ddb4bf299a6e898a9a07c89f3917f0713f7 +(since Linux 3.5) +.I ip_mreq +structure similar to +.BR IP_ADD_MEMBERSHIP , +or an +.I in_addr +structure. +(The kernel determines which structure is being passed based +on the size passed in +.IR optlen .) +For +.BR getsockopt (2), +the argument is an +.I in_addr +structure. +.TP +.BR IP_MULTICAST_LOOP " (since Linux 1.2)" +Set or read a boolean integer argument that determines whether +sent multicast packets should be looped back to the local sockets. +.TP +.BR IP_MULTICAST_TTL " (since Linux 1.2)" +Set or read the time-to-live value of outgoing multicast packets for this +socket. +It is very important for multicast packets to set the smallest TTL possible. +The default is 1 which means that multicast packets don't leave the local +network unless the user program explicitly requests it. +Argument is an integer. +.TP +.BR IP_NODEFRAG " (since Linux 2.6.36)" +If enabled (argument is nonzero), +the reassembly of outgoing packets is disabled in the netfilter layer. +The argument is an integer. +.IP +This option is valid only for +.B SOCK_RAW +sockets. +.TP +.BR IP_OPTIONS " (since Linux 2.0)" +.\" Precisely: since Linux 1.3.30 +Set or get the IP options to be sent with every packet from this socket. +The arguments are a pointer to a memory buffer containing the options +and the option length. +The +.BR setsockopt (2) +call sets the IP options associated with a socket. +The maximum option size for IPv4 is 40 bytes. +See RFC\ 791 for the allowed options. +When the initial connection request packet for a +.B SOCK_STREAM +socket contains IP options, the IP options will be set automatically +to the options from the initial packet with routing headers reversed. +Incoming packets are not allowed to change options after the connection +is established. +The processing of all incoming source routing options +is disabled by default and can be enabled by using the +.I accept_source_route +.I /proc +interface. +Other options like timestamps are still handled. +For datagram sockets, IP options can be set only by the local user. +Calling +.BR getsockopt (2) +with +.B IP_OPTIONS +puts the current IP options used for sending into the supplied buffer. +.TP +.BR IP_PASSSEC " (since Linux 2.6.17)" +.\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c +If labeled IPSEC or NetLabel is configured on the sending and receiving +hosts, this option enables receiving of the security context of the peer +socket in an ancillary message of type +.B SCM_SECURITY +retrieved using +.BR recvmsg (2). +This option is supported only for UDP sockets; for TCP or SCTP sockets, +see the description of the +.B SO_PEERSEC +option below. +.IP +The value given as an argument to +.BR setsockopt (2) +and returned as the result of +.BR getsockopt (2) +is an integer boolean flag. +.IP +The security context returned in the +.B SCM_SECURITY +ancillary message +is of the same format as the one described under the +.B SO_PEERSEC +option below. +.IP +Note: the reuse of the +.B SCM_SECURITY +message type for the +.B IP_PASSSEC +socket option was likely a mistake, since other IP control messages use +their own numbering scheme in the IP namespace and often use the +socket option value as the message type. +There is no conflict currently since the IP option with the same value as +.B SCM_SECURITY +is +.B IP_HDRINCL +and this is never used for a control message type. +.TP +.BR IP_PKTINFO " (since Linux 2.2)" +.\" Precisely: since Linux 2.1.68 +Pass an +.B IP_PKTINFO +ancillary message that contains a +.I pktinfo +structure that supplies some information about the incoming packet. +This works only for datagram oriented sockets. +The argument is a flag that tells the socket whether the +.B IP_PKTINFO +message should be passed or not. +The message itself can be sent/retrieved +only as a control message with a packet using +.BR recvmsg (2) +or +.BR sendmsg (2). +.IP +.in +4n +.EX +struct in_pktinfo { + unsigned int ipi_ifindex; /* Interface index */ + struct in_addr ipi_spec_dst; /* Local address */ + struct in_addr ipi_addr; /* Header Destination + address */ +}; +.EE +.in +.IP +.I ipi_ifindex +is the unique index of the interface the packet was received on. +.I ipi_spec_dst +is the local address of the packet and +.I ipi_addr +is the destination address in the packet header. +If +.B IP_PKTINFO +is passed to +.BR sendmsg (2) +and +.\" This field is grossly misnamed +.I ipi_spec_dst +is not zero, then it is used as the local source address for the routing +table lookup and for setting up IP source route options. +When +.I ipi_ifindex +is not zero, the primary local address of the interface specified by the +index overwrites +.I ipi_spec_dst +for the routing table lookup. +.IP +Not supported for +.B SOCK_STREAM +sockets. +.TP +.BR IP_RECVERR " (since Linux 2.2)" +.\" Precisely: since Linux 2.1.15 +Enable extended reliable error message passing. +When enabled on a datagram socket, all +generated errors will be queued in a per-socket error queue. +When the user receives an error from a socket operation, +the errors can be received by calling +.BR recvmsg (2) +with the +.B MSG_ERRQUEUE +flag set. +The +.I sock_extended_err +structure describing the error will be passed in an ancillary message with +the type +.B IP_RECVERR +and the level +.BR IPPROTO_IP . +.\" or SOL_IP on Linux +This is useful for reliable error handling on unconnected sockets. +The received data portion of the error queue contains the error packet. +.IP +The +.B IP_RECVERR +control message contains a +.I sock_extended_err +structure: +.IP +.in +4n +.EX +#define SO_EE_ORIGIN_NONE 0 +#define SO_EE_ORIGIN_LOCAL 1 +#define SO_EE_ORIGIN_ICMP 2 +#define SO_EE_ORIGIN_ICMP6 3 +\& +struct sock_extended_err { + uint32_t ee_errno; /* error number */ + uint8_t ee_origin; /* where the error originated */ + uint8_t ee_type; /* type */ + uint8_t ee_code; /* code */ + uint8_t ee_pad; + uint32_t ee_info; /* additional information */ + uint32_t ee_data; /* other data */ + /* More data may follow */ +}; +\& +struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); +.EE +.in +.IP +.I ee_errno +contains the +.I errno +number of the queued error. +.I ee_origin +is the origin code of where the error originated. +The other fields are protocol-specific. +The macro +.B SO_EE_OFFENDER +returns a pointer to the address of the network object +where the error originated from given a pointer to the ancillary message. +If this address is not known, the +.I sa_family +member of the +.I sockaddr +contains +.B AF_UNSPEC +and the other fields of the +.I sockaddr +are undefined. +.IP +IP uses the +.I sock_extended_err +structure as follows: +.I ee_origin +is set to +.B SO_EE_ORIGIN_ICMP +for errors received as an ICMP packet, or +.B SO_EE_ORIGIN_LOCAL +for locally generated errors. +Unknown values should be ignored. +.I ee_type +and +.I ee_code +are set from the type and code fields of the ICMP header. +.I ee_info +contains the discovered MTU for +.B EMSGSIZE +errors. +The message also contains the +.I sockaddr_in of the node +caused the error, which can be accessed with the +.B SO_EE_OFFENDER +macro. +The +.I sin_family +field of the +.B SO_EE_OFFENDER +address is +.B AF_UNSPEC +when the source was unknown. +When the error originated from the network, all IP options +.RB ( IP_OPTIONS ", " IP_TTL , +etc.) enabled on the socket and contained in the +error packet are passed as control messages. +The payload of the packet causing the error is returned as normal payload. +.\" FIXME . Is it a good idea to document that? It is a dubious feature. +.\" On +.\" .B SOCK_STREAM +.\" sockets, +.\" .B IP_RECVERR +.\" has slightly different semantics. Instead of +.\" saving the errors for the next timeout, it passes all incoming +.\" errors immediately to the user. +.\" This might be useful for very short-lived TCP connections which +.\" need fast error handling. Use this option with care: +.\" it makes TCP unreliable +.\" by not allowing it to recover properly from routing +.\" shifts and other normal +.\" conditions and breaks the protocol specification. +Note that TCP has no error queue; +.B MSG_ERRQUEUE +is not permitted on +.B SOCK_STREAM +sockets. +.B IP_RECVERR +is valid for TCP, but all errors are returned by socket function return or +.B SO_ERROR +only. +.IP +For raw sockets, +.B IP_RECVERR +enables passing of all received ICMP errors to the +application, otherwise errors are reported only on connected sockets +.IP +It sets or retrieves an integer boolean flag. +.B IP_RECVERR +defaults to off. +.TP +.BR IP_RECVOPTS " (since Linux 2.2)" +.\" Precisely: since Linux 2.1.15 +Pass all incoming IP options to the user in a +.B IP_OPTIONS +control message. +The routing header and other options are already filled in +for the local host. +Not supported for +.B SOCK_STREAM +sockets. +.TP +.BR IP_RECVORIGDSTADDR " (since Linux 2.6.29)" +.\" commit e8b2dfe9b4501ed0047459b2756ba26e5a940a69 +This boolean option enables the +.B IP_ORIGDSTADDR +ancillary message in +.BR recvmsg (2), +in which the kernel returns the original destination address +of the datagram being received. +The ancillary message contains a +.IR "struct sockaddr_in" . +Not supported for +.B SOCK_STREAM +sockets. +.TP +.BR IP_RECVTOS " (since Linux 2.2)" +.\" Precisely: since Linux 2.1.68 +If enabled, the +.B IP_TOS +ancillary message is passed with incoming packets. +It contains a byte which specifies the Type of Service/Precedence +field of the packet header. +Expects a boolean integer flag. +Not supported for +.B SOCK_STREAM +sockets. +.TP +.BR IP_RECVTTL " (since Linux 2.2)" +.\" Precisely: since Linux 2.1.68 +When this flag is set, pass a +.B IP_TTL +control message with the time-to-live +field of the received packet as a 32 bit integer. +Not supported for +.B SOCK_STREAM +sockets. +.TP +.BR IP_RETOPTS " (since Linux 2.2)" +.\" Precisely: since Linux 2.1.15 +Identical to +.BR IP_RECVOPTS , +but returns raw unprocessed options with timestamp and route record +options not filled in for this hop. +Not supported for +.B SOCK_STREAM +sockets. +.TP +.BR IP_ROUTER_ALERT " (since Linux 2.2)" +.\" Precisely: since Linux 2.1.68 +Pass all to-be forwarded packets with the +IP Router Alert option set to this socket. +Valid only for raw sockets. +This is useful, for instance, for user-space RSVP daemons. +The tapped packets are not forwarded by the kernel; it is +the user's responsibility to send them out again. +Socket binding is ignored, +such packets are filtered only by protocol. +Expects an integer flag. +.TP +.BR IP_TOS " (since Linux 1.0)" +Set or receive the Type-Of-Service (TOS) field that is sent +with every IP packet originating from this socket. +It is used to prioritize packets on the network. +TOS is a byte. +There are some standard TOS flags defined: +.B IPTOS_LOWDELAY +to minimize delays for interactive traffic, +.B IPTOS_THROUGHPUT +to optimize throughput, +.B IPTOS_RELIABILITY +to optimize for reliability, +.B IPTOS_MINCOST +should be used for "filler data" where slow transmission doesn't matter. +At most one of these TOS values can be specified. +Other bits are invalid and shall be cleared. +Linux sends +.B IPTOS_LOWDELAY +datagrams first by default, +but the exact behavior depends on the configured queueing discipline. +.\" FIXME elaborate on this +Some high-priority levels may require superuser privileges (the +.B CAP_NET_ADMIN +capability). +.\" The priority can also be set in a protocol-independent way by the +.\" .RB ( SOL_SOCKET ", " SO_PRIORITY ) +.\" socket option (see +.\" .BR socket (7)). +.TP +.BR IP_TRANSPARENT " (since Linux 2.6.24)" +.\" commit f5715aea4564f233767ea1d944b2637a5fd7cd2e +.\" This patch introduces the IP_TRANSPARENT socket option: enabling that +.\" will make the IPv4 routing omit the non-local source address check on +.\" output. Setting IP_TRANSPARENT requires NET_ADMIN capability. +.\" http://lwn.net/Articles/252545/ +Setting this boolean option enables transparent proxying on this socket. +This socket option allows +the calling application to bind to a nonlocal IP address and operate +both as a client and a server with the foreign address as the local endpoint. +NOTE: this requires that routing be set up in a way that +packets going to the foreign address are routed through the TProxy box +(i.e., the system hosting the application that employs the +.B IP_TRANSPARENT +socket option). +Enabling this socket option requires superuser privileges +(the +.B CAP_NET_ADMIN +capability). +.IP +TProxy redirection with the iptables TPROXY target also requires that +this option be set on the redirected socket. +.TP +.BR IP_TTL " (since Linux 1.0)" +Set or retrieve the current time-to-live field that is used in every packet +sent from this socket. +.TP +.BR IP_UNBLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)" +Unblock previously blocked multicast source. +Returns +.B EADDRNOTAVAIL +when given source is not being blocked. +.IP +Argument is an +.I ip_mreq_source +structure as described under +.BR IP_ADD_SOURCE_MEMBERSHIP . +.TP +.BR SO_PEERSEC " (since Linux 2.6.17)" +If labeled IPSEC or NetLabel is configured on both the sending and +receiving hosts, this read-only socket option returns the security +context of the peer socket connected to this socket. +By default, +this will be the same as the security context of the process that created +the peer socket unless overridden by the policy or by a process with +the required permissions. +.IP +The argument to +.BR getsockopt (2) +is a pointer to a buffer of the specified length in bytes +into which the security context string will be copied. +If the buffer length is less than the length of the security +context string, then +.BR getsockopt (2) +returns \-1, sets +.I errno +to +.BR ERANGE , +and returns the required length via +.IR optlen . +The caller should allocate at least +.B NAME_MAX +bytes for the buffer initially, although this is not guaranteed +to be sufficient. +Resizing the buffer to the returned length +and retrying may be necessary. +.IP +The security context string may include a terminating null character +in the returned length, but is not guaranteed to do so: a security +context "foo" might be represented as either {'f','o','o'} of length 3 +or {'f','o','o','\\0'} of length 4, which are considered to be +interchangeable. +The string is printable, does not contain non-terminating null characters, +and is in an unspecified encoding (in particular, it +is not guaranteed to be ASCII or UTF-8). +.IP +The use of this option for sockets in the +.B AF_INET +address family is supported since Linux 2.6.17 +.\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c +for TCP sockets, and since Linux 4.17 +.\" commit d452930fd3b9031e59abfeddb2fa383f1403d61a +for SCTP sockets. +.IP +For SELinux, NetLabel conveys only the MLS portion of the security +context of the peer across the wire, defaulting the rest of the +security context to the values defined in the policy for the +netmsg initial security identifier (SID). +However, NetLabel can +be configured to pass full security contexts over loopback. +Labeled IPSEC always passes full security contexts as part of establishing +the security association (SA) and looks them up based on the association +for each packet. +.\" +.SS /proc interfaces +The IP protocol +supports a set of +.I /proc +interfaces to configure some global parameters. +The parameters can be accessed by reading or writing files in the directory +.IR /proc/sys/net/ipv4/ . +.\" FIXME As at 2.6.12, 14 Jun 2005, the following are undocumented: +.\" ip_queue_maxlen +.\" ip_conntrack_max +Interfaces described as +.I Boolean +take an integer value, with a nonzero value ("true") meaning that +the corresponding option is enabled, and a zero value ("false") +meaning that the option is disabled. +.\" +.TP +.IR ip_always_defrag " (Boolean; since Linux 2.2.13)" +[New with Linux 2.2.13; in earlier kernel versions this feature +was controlled at compile time by the +.B CONFIG_IP_ALWAYS_DEFRAG +option; this option is not present in Linux 2.4.x and later] +.IP +When this boolean flag is enabled (not equal 0), incoming fragments +(parts of IP packets +that arose when some host between origin and destination decided +that the packets were too large and cut them into pieces) will be +reassembled (defragmented) before being processed, even if they are +about to be forwarded. +.IP +Enable only if running either a firewall that is the sole link +to your network or a transparent proxy; never ever use it for a +normal router or host. +Otherwise, fragmented communication can be disturbed +if the fragments travel over different links. +Defragmentation also has a large memory and CPU time cost. +.IP +This is automagically turned on when masquerading or transparent +proxying are configured. +.\" +.TP +.IR ip_autoconfig " (since Linux 2.2 to Linux 2.6.17)" +.\" Precisely: since Linux 2.1.68 +.\" FIXME document ip_autoconfig +Not documented. +.\" +.TP +.IR ip_default_ttl " (integer; default: 64; since Linux 2.2)" +.\" Precisely: since Linux 2.1.15 +Set the default time-to-live value of outgoing packets. +This can be changed per socket with the +.B IP_TTL +option. +.\" +.TP +.IR ip_dynaddr " (Boolean; default: disabled; since Linux 2.0.31)" +Enable dynamic socket address and masquerading entry rewriting on interface +address change. +This is useful for dialup interface with changing IP addresses. +0 means no rewriting, 1 turns it on and 2 enables verbose mode. +.\" +.TP +.IR ip_forward " (Boolean; default: disabled; since Linux 1.2)" +Enable IP forwarding with a boolean flag. +IP forwarding can be also set on a per-interface basis. +.\" +.TP +.IR ip_local_port_range " (since Linux 2.2)" +.\" Precisely: since Linux 2.1.68 +This file contains two integers that define the default local port range +allocated to sockets that are not explicitly bound to a port number\[em]that +is, the range used for +.IR "ephemeral ports" . +An ephemeral port is allocated to a socket in the following circumstances: +.RS +.IP \[bu] 3 +the port number in a socket address is specified as 0 when calling +.BR bind (2); +.IP \[bu] +.BR listen (2) +is called on a stream socket that was not previously bound; +.IP \[bu] +.BR connect (2) +was called on a socket that was not previously bound; +.IP \[bu] +.BR sendto (2) +is called on a datagram socket that was not previously bound. +.RE +.IP +Allocation of ephemeral ports starts with the first number in +.I ip_local_port_range +and ends with the second number. +If the range of ephemeral ports is exhausted, +then the relevant system call returns an error (but see BUGS). +.IP +Note that the port range in +.I ip_local_port_range +should not conflict with the ports used by masquerading +(although the case is handled). +Also, arbitrary choices may cause problems with some firewall packet +filters that make assumptions about the local ports in use. +The first number should be at least greater than 1024, +or better, greater than 4096, to avoid clashes +with well known ports and to minimize firewall problems. +.\" +.TP +.IR ip_no_pmtu_disc " (Boolean; default: disabled; since Linux 2.2)" +.\" Precisely: 2.1.15 +If enabled, don't do Path MTU Discovery for TCP sockets by default. +Path MTU discovery may fail if misconfigured firewalls (that drop +all ICMP packets) or misconfigured interfaces (e.g., a point-to-point +link where the both ends don't agree on the MTU) are on the path. +It is better to fix the broken routers on the path than to turn off +Path MTU Discovery globally, because not doing it incurs a high cost +to the network. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR ip_nonlocal_bind " (Boolean; default: disabled; since Linux 2.4)" +.\" Precisely: patch-2.4.0-test10 +If set, allows processes to +.BR bind (2) +to nonlocal IP addresses, +which can be quite useful, but may break some applications. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR ip6frag_time " (integer; default: 30)" +Time in seconds to keep an IPv6 fragment in memory. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR ip6frag_secret_interval " (integer; default: 600)" +Regeneration interval (in seconds) of the hash secret (or lifetime +for the hash secret) for IPv6 fragments. +.TP +.IR ipfrag_high_thresh " (integer)" +.TQ +.IR ipfrag_low_thresh " (integer)" +If the amount of queued IP fragments reaches +.IR ipfrag_high_thresh , +the queue is pruned down to +.IR ipfrag_low_thresh . +Contains an integer with the number of bytes. +.TP +.I neigh/* +See +.BR arp (7). +.\" FIXME Document the conf/*/* interfaces +.\" +.\" FIXME Document the route/* interfaces +.SS Ioctls +All ioctls described in +.BR socket (7) +apply to +.BR ip . +.P +Ioctls to configure generic device parameters are described in +.BR netdevice (7). +.\" FIXME Add a discussion of multicasting +.SH ERRORS +.\" FIXME document all errors. +.\" We should really fix the kernels to give more uniform +.\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.) +.TP +.B EACCES +The user tried to execute an operation without the necessary permissions. +These include: +sending a packet to a broadcast address without having the +.B SO_BROADCAST +flag set; +sending a packet via a +.I prohibit +route; +modifying firewall settings without superuser privileges (the +.B CAP_NET_ADMIN +capability); +binding to a privileged port without superuser privileges (the +.B CAP_NET_BIND_SERVICE +capability). +.TP +.B EADDRINUSE +Tried to bind to an address already in use. +.TP +.B EADDRNOTAVAIL +A nonexistent interface was requested or the requested source +address was not local. +.TP +.B EAGAIN +Operation on a nonblocking socket would block. +.TP +.B EALREADY +A connection operation on a nonblocking socket is already in progress. +.TP +.B ECONNABORTED +A connection was closed during an +.BR accept (2). +.TP +.B EHOSTUNREACH +No valid routing table entry matches the destination address. +This error can be caused by an ICMP message from a remote router or +for the local routing table. +.TP +.B EINVAL +Invalid argument passed. +For send operations this can be caused by sending to a +.I blackhole +route. +.TP +.B EISCONN +.BR connect (2) +was called on an already connected socket. +.TP +.B EMSGSIZE +Datagram is bigger than an MTU on the path and it cannot be fragmented. +.TP +.B ENOBUFS +.TQ +.B ENOMEM +Not enough free memory. +This often means that the memory allocation is limited by the socket +buffer limits, not by the system memory, but this is not 100% consistent. +.TP +.B ENOENT +.B SIOCGSTAMP +was called on a socket where no packet arrived. +.TP +.B ENOPKG +A kernel subsystem was not configured. +.TP +.BR ENOPROTOOPT " and " EOPNOTSUPP +Invalid socket option passed. +.TP +.B ENOTCONN +The operation is defined only on a connected socket, but the socket wasn't +connected. +.TP +.B EPERM +User doesn't have permission to set high priority, change configuration, +or send signals to the requested process or group. +.TP +.B EPIPE +The connection was unexpectedly closed or shut down by the other end. +.TP +.B ESOCKTNOSUPPORT +The socket is not configured or an unknown socket type was requested. +.P +Other errors may be generated by the overlaying protocols; see +.BR tcp (7), +.BR raw (7), +.BR udp (7), +and +.BR socket (7). +.SH NOTES +.BR IP_FREEBIND , +.BR IP_MSFILTER , +.BR IP_MTU , +.BR IP_MTU_DISCOVER , +.BR IP_RECVORIGDSTADDR , +.BR IP_PASSSEC , +.BR IP_PKTINFO , +.BR IP_RECVERR , +.BR IP_ROUTER_ALERT , +and +.B IP_TRANSPARENT +are Linux-specific. +.\" IP_XFRM_POLICY is Linux-specific +.\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs +.P +Be very careful with the +.B SO_BROADCAST +option \- it is not privileged in Linux. +It is easy to overload the network +with careless broadcasts. +For new application protocols +it is better to use a multicast group instead of broadcasting. +Broadcasting is discouraged. +See RFC 6762 for an example of a protocol (mDNS) +using the more modern multicast approach +to communicating with an open-ended +group of hosts on the local network. +.P +Some other BSD sockets implementations provide +.B IP_RCVDSTADDR +and +.B IP_RECVIF +socket options to get the destination address and the interface of +received datagrams. +Linux has the more general +.B IP_PKTINFO +for the same task. +.P +Some BSD sockets implementations also provide an +.B IP_RECVTTL +option, but an ancillary message with type +.B IP_RECVTTL +is passed with the incoming packet. +This is different from the +.B IP_TTL +option used in Linux. +.P +Using the +.B SOL_IP +socket options level isn't portable; BSD-based stacks use the +.B IPPROTO_IP +level. +.P +.B INADDR_ANY +(0.0.0.0) and +.B INADDR_BROADCAST +(255.255.255.255) are byte-order-neutral. +This means +.BR htonl (3) +has no effect on them. +.SS Compatibility +For compatibility with Linux 2.0, the obsolete +.BI "socket(AF_INET, SOCK_PACKET, " protocol ) +syntax is still supported to open a +.BR packet (7) +socket. +This is deprecated and should be replaced by +.BI "socket(AF_PACKET, SOCK_RAW, " protocol ) +instead. +The main difference is the new +.I sockaddr_ll +address structure for generic link layer information instead of the old +.BR sockaddr_pkt . +.SH BUGS +There are too many inconsistent error values. +.P +The error used to diagnose exhaustion of the ephemeral port range differs +across the various system calls +.RB ( connect (2), +.BR bind (2), +.BR listen (2), +.BR sendto (2)) +that can assign ephemeral ports. +.P +The ioctls to configure IP-specific interface options and ARP tables are +not described. +.\" .P +.\" Some versions of glibc forget to declare +.\" .IR in_pktinfo . +.\" Workaround currently is to copy it into your program from this man page. +.P +Receiving the original destination address with +.B MSG_ERRQUEUE +in +.I msg_name +by +.BR recvmsg (2) +does not work in some Linux 2.2 kernels. +.\" .SH AUTHORS +.\" This man page was written by Andi Kleen. +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2), +.BR byteorder (3), +.BR capabilities (7), +.BR icmp (7), +.BR ipv6 (7), +.BR netdevice (7), +.BR netlink (7), +.BR raw (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR ip (8) +.P +The kernel source file +.IR Documentation/networking/ip\-sysctl.txt . +.P +RFC\ 791 for the original IP specification. +RFC\ 1122 for the IPv4 host requirements. +RFC\ 1812 for the IPv4 router requirements. diff --git a/man/man7/ipc_namespaces.7 b/man/man7/ipc_namespaces.7 new file mode 100644 index 0000000..d9e41b7 --- /dev/null +++ b/man/man7/ipc_namespaces.7 @@ -0,0 +1,66 @@ +.\" Copyright (c) 2019 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH ipc_namespaces 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ipc_namespaces \- overview of Linux IPC namespaces +.SH DESCRIPTION +IPC namespaces isolate certain IPC resources, +namely, System V IPC objects (see +.BR sysvipc (7)) +and (since Linux 2.6.30) +.\" commit 7eafd7c74c3f2e67c27621b987b28397110d643f +.\" https://lwn.net/Articles/312232/ +POSIX message queues (see +.BR mq_overview (7)). +The common characteristic of these IPC mechanisms is that IPC +objects are identified by mechanisms other than filesystem +pathnames. +.P +Each IPC namespace has its own set of System V IPC identifiers and +its own POSIX message queue filesystem. +Objects created in an IPC namespace are visible to all other processes +that are members of that namespace, +but are not visible to processes in other IPC namespaces. +.P +The following +.I /proc +interfaces are distinct in each IPC namespace: +.IP \[bu] 3 +The POSIX message queue interfaces in +.IR /proc/sys/fs/mqueue . +.IP \[bu] +The System V IPC interfaces in +.IR /proc/sys/kernel , +namely: +.IR msgmax , +.IR msgmnb , +.IR msgmni , +.IR sem , +.IR shmall , +.IR shmmax , +.IR shmmni , +and +.IR shm_rmid_forced . +.IP \[bu] +The System V IPC interfaces in +.IR /proc/sysvipc . +.P +When an IPC namespace is destroyed +(i.e., when the last process that is a member of the namespace terminates), +all IPC objects in the namespace are automatically destroyed. +.P +Use of IPC namespaces requires a kernel that is configured with the +.B CONFIG_IPC_NS +option. +.SH SEE ALSO +.BR nsenter (1), +.BR unshare (1), +.BR clone (2), +.BR setns (2), +.BR unshare (2), +.BR mq_overview (7), +.BR namespaces (7), +.BR sysvipc (7) diff --git a/man/man7/ipv6.7 b/man/man7/ipv6.7 new file mode 100644 index 0000000..5998137 --- /dev/null +++ b/man/man7/ipv6.7 @@ -0,0 +1,416 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 2000 Andi Kleen . +.\" +.\" $Id: ipv6.7,v 1.3 2000/12/20 18:10:31 ak Exp $ +.\" +.\" The following socket options are undocumented +.\" All of the following are from: +.\" commit 333fad5364d6b457c8d837f7d05802d2aaf8a961 +.\" Author: YOSHIFUJI Hideaki +.\" Support several new sockopt / ancillary data in Advanced API (RFC3542). +.\" IPV6_2292PKTINFO (2.6.14) +.\" Formerly IPV6_PKTINFO +.\" IPV6_2292HOPOPTS (2.6.14) +.\" Formerly IPV6_HOPOPTS, which is documented +.\" IPV6_2292DSTOPTS (2.6.14) +.\" Formerly IPV6_DSTOPTS, which is documented +.\" IPV6_2292RTHDR (2.6.14) +.\" Formerly IPV6_RTHDR, which is documented +.\" IPV6_2292PKTOPTIONS (2.6.14) +.\" Formerly IPV6_PKTOPTIONS +.\" IPV6_2292HOPLIMIT (2.6.14) +.\" Formerly IPV6_HOPLIMIT, which is documented +.\" +.\" IPV6_RECVHOPLIMIT (2.6.14) +.\" IPV6_RECVHOPOPTS (2.6.14) +.\" IPV6_RTHDRDSTOPTS (2.6.14) +.\" IPV6_RECVRTHDR (2.6.14) +.\" IPV6_RECVDSTOPTS (2.6.14) +.\" +.\" IPV6_RECVPATHMTU (Linux 2.6.35, flag value added in Linux 2.6.14) +.\" commit 793b14731686595a741d9f47726ad8b9a235385a +.\" Author: Brian Haley +.\" IPV6_PATHMTU (Linux 2.6.35, flag value added in Linux 2.6.14) +.\" commit 793b14731686595a741d9f47726ad8b9a235385a +.\" Author: Brian Haley +.\" IPV6_DONTFRAG (Linux 2.6.35, flag value added in Linux 2.6.14) +.\" commit 793b14731686595a741d9f47726ad8b9a235385a +.\" Author: Brian Haley +.\" commit 4b340ae20d0e2366792abe70f46629e576adaf5e +.\" Author: Brian Haley +.\" +.\" IPV6_RECVTCLASS (Linux 2.6.14) +.\" commit 41a1f8ea4fbfcdc4232f023732584aae2220de31 +.\" Author: YOSHIFUJI Hideaki +.\" Based on patch from David L Stevens +.\" +.\" IPV6_CHECKSUM (Linux 2.2) +.\" IPV6_NEXTHOP (Linux 2.2) +.\" IPV6_JOIN_ANYCAST (Linux 2.4.21 / Linux 2.6) +.\" IPV6_LEAVE_ANYCAST (Linux 2.4.21 / Linux 2.6) +.\" IPV6_FLOWLABEL_MGR (Linux 2.2.7 / Linux 2.4) +.\" IPV6_FLOWINFO_SEND (Linux 2.2.7 / Linux 2.4) +.\" IPV6_IPSEC_POLICY (Linux 2.6) +.\" IPV6_XFRM_POLICY (Linux 2.6) +.\" IPV6_TCLASS (Linux 2.6) +.\" +.\" IPV6_ADDR_PREFERENCES (Linux 2.6.26) +.\" commit 7cbca67c073263c179f605bdbbdc565ab29d801d +.\" Author: YOSHIFUJI Hideaki +.\" IPV6_MINHOPCOUNT (Linux 2.6.35) +.\" commit e802af9cabb011f09b9c19a82faef3dd315f27eb +.\" Author: Stephen Hemminger +.\" IPV6_ORIGDSTADDR (Linux 2.6.37) +.\" Actually a CMSG rather than a sockopt? +.\" In header file, we have IPV6_RECVORIGDSTADDR == IPV6_ORIGDSTADDR +.\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 +.\" Author: Balazs Scheidler +.\" IPV6_RECVORIGDSTADDR (Linux 2.6.37) +.\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 +.\" Author: Balazs Scheidler +.\" Support for IPV6_RECVORIGDSTADDR sockopt for UDP sockets +.\" were contributed by Harry Mason. +.\" IPV6_TRANSPARENT (Linux 2.6.37) +.\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 +.\" Author: Balazs Scheidler +.\" IPV6_UNICAST_IF (Linux 3.4) +.\" commit c4062dfc425e94290ac427a98d6b4721dd2bc91f +.\" Author: Erich E. Hoover +.\" +.TH ipv6 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ipv6 \- Linux IPv6 protocol implementation +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.IB tcp6_socket " = socket(AF_INET6, SOCK_STREAM, 0);" +.IB raw6_socket " = socket(AF_INET6, SOCK_RAW, " protocol ");" +.IB udp6_socket " = socket(AF_INET6, SOCK_DGRAM, " protocol ");" +.fi +.SH DESCRIPTION +Linux 2.2 optionally implements the Internet Protocol, version 6. +This man page contains a description of the IPv6 basic API as +implemented by the Linux kernel and glibc 2.1. +The interface +is based on the BSD sockets interface; see +.BR socket (7). +.P +The IPv6 API aims to be mostly compatible with the +IPv4 API (see +.BR ip (7)). +Only differences are described in this man page. +.P +To bind an +.B AF_INET6 +socket to any process, the local address should be copied from the +.I in6addr_any +variable which has +.I in6_addr +type. +In static initializations, +.B IN6ADDR_ANY_INIT +may also be used, which expands to a constant expression. +Both of them are in network byte order. +.P +The IPv6 loopback address (::1) is available in the global +.I in6addr_loopback +variable. +For initializations, +.B IN6ADDR_LOOPBACK_INIT +should be used. +.P +IPv4 connections can be handled with the v6 API by using the +v4-mapped-on-v6 address type; +thus a program needs to support only this API type to +support both protocols. +This is handled transparently by the address +handling functions in the C library. +.P +IPv4 and IPv6 share the local port space. +When you get an IPv4 connection +or packet to an IPv6 socket, +its source address will be mapped to v6. +.SS Address format +.in +4n +.EX +struct sockaddr_in6 { + sa_family_t sin6_family; /* AF_INET6 */ + in_port_t sin6_port; /* port number */ + uint32_t sin6_flowinfo; /* IPv6 flow information */ + struct in6_addr sin6_addr; /* IPv6 address */ + uint32_t sin6_scope_id; /* Scope ID (new in Linux 2.4) */ +}; +\& +struct in6_addr { + unsigned char s6_addr[16]; /* IPv6 address */ +}; +.EE +.in +.P +.I sin6_family +is always set to +.BR AF_INET6 ; +.I sin6_port +is the protocol port (see +.I sin_port +in +.BR ip (7)); +.I sin6_flowinfo +is the IPv6 flow identifier; +.I sin6_addr +is the 128-bit IPv6 address. +.I sin6_scope_id +is an ID depending on the scope of the address. +It is new in Linux 2.4. +Linux supports it only for link-local addresses, in that case +.I sin6_scope_id +contains the interface index (see +.BR netdevice (7)) +.P +IPv6 supports several address types: unicast to address a single +host, multicast to address a group of hosts, +anycast to address the nearest member of a group of hosts +(not implemented in Linux), IPv4-on-IPv6 to +address an IPv4 host, and other reserved address types. +.P +The address notation for IPv6 is a group of 8 4-digit hexadecimal +numbers, separated with a \[aq]:\[aq]. +\&"::" stands for a string of 0 bits. +Special addresses are ::1 for loopback and ::FFFF: +for IPv4-mapped-on-IPv6. +.P +The port space of IPv6 is shared with IPv4. +.SS Socket options +IPv6 supports some protocol-specific socket options that can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2). +The socket option level for IPv6 is +.BR IPPROTO_IPV6 . +A boolean integer flag is zero when it is false, otherwise true. +.TP +.B IPV6_ADDRFORM +Turn an +.B AF_INET6 +socket into a socket of a different address family. +Only +.B AF_INET +is currently supported for that. +It is allowed only for IPv6 sockets +that are connected and bound to a v4-mapped-on-v6 address. +The argument is a pointer to an integer containing +.BR AF_INET . +This is useful to pass v4-mapped sockets as file descriptors to +programs that don't know how to deal with the IPv6 API. +.TP +.B IPV6_ADD_MEMBERSHIP, IPV6_DROP_MEMBERSHIP +Control membership in multicast groups. +Argument is a pointer to a +.IR "struct ipv6_mreq" . +.TP +.B IPV6_MTU +.BR getsockopt (): +Retrieve the current known path MTU of the current socket. +Valid only when the socket has been connected. +Returns an integer. +.IP +.BR setsockopt (): +Set the MTU to be used for the socket. +The MTU is limited by the device +MTU or the path MTU when path MTU discovery is enabled. +Argument is a pointer to integer. +.TP +.B IPV6_MTU_DISCOVER +Control path-MTU discovery on the socket. +See +.B IP_MTU_DISCOVER +in +.BR ip (7) +for details. +.TP +.B IPV6_MULTICAST_HOPS +Set the multicast hop limit for the socket. +Argument is a pointer to an +integer. +\-1 in the value means use the route default, otherwise it should be +between 0 and 255. +.TP +.B IPV6_MULTICAST_IF +Set the device for outgoing multicast packets on the socket. +This is allowed only for +.B SOCK_DGRAM +and +.B SOCK_RAW +socket. +The argument is a pointer to an interface index (see +.BR netdevice (7)) +in an integer. +.TP +.B IPV6_MULTICAST_LOOP +Control whether the socket sees multicast packets that it has send itself. +Argument is a pointer to boolean. +.TP +.BR IPV6_RECVPKTINFO " (since Linux 2.6.14)" +Set delivery of the +.B IPV6_PKTINFO +control message on incoming datagrams. +Such control messages contain a +.IR "struct in6_pktinfo" , +as per RFC 3542. +Allowed only for +.B SOCK_DGRAM +or +.B SOCK_RAW +sockets. +Argument is a pointer to a boolean value in an integer. +.TP +.B \%IPV6_RTHDR, \%IPV6_AUTHHDR, \%IPV6_DSTOPTS, \%IPV6_HOPOPTS, \ +\%IPV6_FLOWINFO, \%IPV6_HOPLIMIT +Set delivery of control messages for incoming datagrams containing +extension headers from the received packet. +.B IPV6_RTHDR +delivers the routing header, +.B IPV6_AUTHHDR +delivers the authentication header, +.B IPV6_DSTOPTS +delivers the destination options, +.B IPV6_HOPOPTS +delivers the hop options, +.B IPV6_FLOWINFO +delivers an integer containing the flow ID, +.B IPV6_HOPLIMIT +delivers an integer containing the hop count of the packet. +The control messages have the same type as the socket option. +All these header options can also be set for outgoing packets +by putting the appropriate control message into the control buffer of +.BR sendmsg (2). +Allowed only for +.B SOCK_DGRAM +or +.B SOCK_RAW +sockets. +Argument is a pointer to a boolean value. +.TP +.B IPV6_RECVERR +Control receiving of asynchronous error options. +See +.B IP_RECVERR +in +.BR ip (7) +for details. +Argument is a pointer to boolean. +.TP +.B IPV6_ROUTER_ALERT +Pass forwarded packets containing a router alert hop-by-hop option to +this socket. +Allowed only for +.B SOCK_RAW +sockets. +The tapped packets are not forwarded by the kernel, it is the +user's responsibility to send them out again. +Argument is a pointer to an integer. +A positive integer indicates a router alert option value to intercept. +Packets carrying a router alert option with a value field containing +this integer will be delivered to the socket. +A negative integer disables delivery of packets with router alert options +to this socket. +.TP +.B IPV6_UNICAST_HOPS +Set the unicast hop limit for the socket. +Argument is a pointer to an integer. +\-1 in the value means use the route default, +otherwise it should be between 0 and 255. +.TP +.BR IPV6_V6ONLY " (since Linux 2.4.21 and 2.6)" +.\" See RFC 3493 +If this flag is set to true (nonzero), then the socket is restricted +to sending and receiving IPv6 packets only. +In this case, an IPv4 and an IPv6 application can bind +to a single port at the same time. +.IP +If this flag is set to false (zero), +then the socket can be used to send and receive packets +to and from an IPv6 address or an IPv4-mapped IPv6 address. +.IP +The argument is a pointer to a boolean value in an integer. +.IP +The default value for this flag is defined by the contents of the file +.IR /proc/sys/net/ipv6/bindv6only . +The default value for that file is 0 (false). +.\" FLOWLABEL_MGR, FLOWINFO_SEND +.SH ERRORS +.TP +.B ENODEV +The user tried to +.BR bind (2) +to a link-local IPv6 address, but the +.I sin6_scope_id +in the supplied +.I sockaddr_in6 +structure is not a valid +interface index. +.SH VERSIONS +Linux 2.4 will break binary compatibility for the +.I sockaddr_in6 +for 64-bit +hosts by changing the alignment of +.I in6_addr +and adding an additional +.I sin6_scope_id +field. +The kernel interfaces stay compatible, but a program including +.I sockaddr_in6 +or +.I in6_addr +into other structures may not be. +This is not +a problem for 32-bit hosts like i386. +.P +The +.I sin6_flowinfo +field is new in Linux 2.4. +It is transparently passed/read by the kernel +when the passed address length contains it. +Some programs that pass a longer address buffer and then +check the outgoing address length may break. +.SH NOTES +The +.I sockaddr_in6 +structure is bigger than the generic +.IR sockaddr . +Programs that assume that all address types can be stored safely in a +.I struct sockaddr +need to be changed to use +.I struct sockaddr_storage +for that instead. +.P +.BR SOL_IP , +.BR SOL_IPV6 , +.BR SOL_ICMPV6 , +and other +.B SOL_* +socket options are nonportable variants of +.BR IPPROTO_* . +See also +.BR ip (7). +.SH BUGS +The IPv6 extended API as in RFC\ 2292 is currently only partly +implemented; +although the 2.2 kernel has near complete support for receiving options, +the macros for generating IPv6 options are missing in glibc 2.1. +.P +IPSec support for EH and AH headers is missing. +.P +Flow label management is not complete and not documented here. +.P +This man page is not complete. +.SH SEE ALSO +.BR cmsg (3), +.BR ip (7) +.P +RFC\ 2553: IPv6 BASIC API; +Linux tries to be compliant to this. +RFC\ 2460: IPv6 specification. diff --git a/man/man7/iso-8859-1.7 b/man/man7/iso-8859-1.7 new file mode 100644 index 0000000..1969dfb --- /dev/null +++ b/man/man7/iso-8859-1.7 @@ -0,0 +1 @@ +.so man7/iso_8859-1.7 diff --git a/man/man7/iso-8859-10.7 b/man/man7/iso-8859-10.7 new file mode 100644 index 0000000..9b4658f --- /dev/null +++ b/man/man7/iso-8859-10.7 @@ -0,0 +1 @@ +.so man7/iso_8859-10.7 diff --git a/man/man7/iso-8859-11.7 b/man/man7/iso-8859-11.7 new file mode 100644 index 0000000..cbd4cfe --- /dev/null +++ b/man/man7/iso-8859-11.7 @@ -0,0 +1 @@ +.so man7/iso_8859-11.7 diff --git a/man/man7/iso-8859-13.7 b/man/man7/iso-8859-13.7 new file mode 100644 index 0000000..8ad2335 --- /dev/null +++ b/man/man7/iso-8859-13.7 @@ -0,0 +1 @@ +.so man7/iso_8859-13.7 diff --git a/man/man7/iso-8859-14.7 b/man/man7/iso-8859-14.7 new file mode 100644 index 0000000..4aa555d --- /dev/null +++ b/man/man7/iso-8859-14.7 @@ -0,0 +1 @@ +.so man7/iso_8859-14.7 diff --git a/man/man7/iso-8859-15.7 b/man/man7/iso-8859-15.7 new file mode 100644 index 0000000..a4095d7 --- /dev/null +++ b/man/man7/iso-8859-15.7 @@ -0,0 +1 @@ +.so man7/iso_8859-15.7 diff --git a/man/man7/iso-8859-16.7 b/man/man7/iso-8859-16.7 new file mode 100644 index 0000000..b9c8e91 --- /dev/null +++ b/man/man7/iso-8859-16.7 @@ -0,0 +1 @@ +.so man7/iso_8859-16.7 diff --git a/man/man7/iso-8859-2.7 b/man/man7/iso-8859-2.7 new file mode 100644 index 0000000..da36668 --- /dev/null +++ b/man/man7/iso-8859-2.7 @@ -0,0 +1 @@ +.so man7/iso_8859-2.7 diff --git a/man/man7/iso-8859-3.7 b/man/man7/iso-8859-3.7 new file mode 100644 index 0000000..75e42ce --- /dev/null +++ b/man/man7/iso-8859-3.7 @@ -0,0 +1 @@ +.so man7/iso_8859-3.7 diff --git a/man/man7/iso-8859-4.7 b/man/man7/iso-8859-4.7 new file mode 100644 index 0000000..15a829e --- /dev/null +++ b/man/man7/iso-8859-4.7 @@ -0,0 +1 @@ +.so man7/iso_8859-4.7 diff --git a/man/man7/iso-8859-5.7 b/man/man7/iso-8859-5.7 new file mode 100644 index 0000000..1f20320 --- /dev/null +++ b/man/man7/iso-8859-5.7 @@ -0,0 +1 @@ +.so man7/iso_8859-5.7 diff --git a/man/man7/iso-8859-6.7 b/man/man7/iso-8859-6.7 new file mode 100644 index 0000000..edcafdf --- /dev/null +++ b/man/man7/iso-8859-6.7 @@ -0,0 +1 @@ +.so man7/iso_8859-6.7 diff --git a/man/man7/iso-8859-7.7 b/man/man7/iso-8859-7.7 new file mode 100644 index 0000000..951384c --- /dev/null +++ b/man/man7/iso-8859-7.7 @@ -0,0 +1 @@ +.so man7/iso_8859-7.7 diff --git a/man/man7/iso-8859-8.7 b/man/man7/iso-8859-8.7 new file mode 100644 index 0000000..07cf216 --- /dev/null +++ b/man/man7/iso-8859-8.7 @@ -0,0 +1 @@ +.so man7/iso_8859-8.7 diff --git a/man/man7/iso-8859-9.7 b/man/man7/iso-8859-9.7 new file mode 100644 index 0000000..0fcc7d4 --- /dev/null +++ b/man/man7/iso-8859-9.7 @@ -0,0 +1 @@ +.so man7/iso_8859-9.7 diff --git a/man/man7/iso_8859-1.7 b/man/man7/iso_8859-1.7 new file mode 100644 index 0000000..cd69000 --- /dev/null +++ b/man/man7/iso_8859-1.7 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright 1993-1995 Daniel Quinlan (quinlan@yggdrasil.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Slightly rearranged, aeb, 950713 +.\" Updated, dpo, 990531 +.TH ISO_8859-1 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-1 \- ISO/IEC\~8859-1 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-1 encodes the +characters used in many West European languages. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-1 characters +The following table displays the characters in ISO/IEC\~8859-1 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER ETH +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER THORN +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER ETH +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER THORN +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +ISO/IEC\~8859-1 is also known as Latin-1. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1252 (7), +.BR iso_8859\-15 (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-10.7 b/man/man7/iso_8859-10.7 new file mode 100644 index 0000000..7001851 --- /dev/null +++ b/man/man7/iso_8859-10.7 @@ -0,0 +1,146 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-10 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-10 \- ISO/IEC\~8859-10 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-10 encodes the +characters used in Nordic languages. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-10 characters +The following table displays the characters in ISO/IEC\~8859-10 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ą LATIN CAPITAL LETTER A WITH OGONEK +242 162 A2 Ē LATIN CAPITAL LETTER E WITH MACRON +243 163 A3 Ģ LATIN CAPITAL LETTER G WITH CEDILLA +244 164 A4 Ī LATIN CAPITAL LETTER I WITH MACRON +245 165 A5 Ĩ LATIN CAPITAL LETTER I WITH TILDE +246 166 A6 Ķ LATIN CAPITAL LETTER K WITH CEDILLA +247 167 A7 § SECTION SIGN +250 168 A8 Ļ LATIN CAPITAL LETTER L WITH CEDILLA +251 169 A9 Đ LATIN CAPITAL LETTER D WITH STROKE +252 170 AA Š LATIN CAPITAL LETTER S WITH CARON +253 171 AB Ŧ LATIN CAPITAL LETTER T WITH STROKE +254 172 AC Ž LATIN CAPITAL LETTER Z WITH CARON +255 173 AD ­ SOFT HYPHEN +256 174 AE Ū LATIN CAPITAL LETTER U WITH MACRON +257 175 AF Ŋ LATIN CAPITAL LETTER ENG +260 176 B0 ° DEGREE SIGN +261 177 B1 ą LATIN SMALL LETTER A WITH OGONEK +262 178 B2 ē LATIN SMALL LETTER E WITH MACRON +263 179 B3 ģ LATIN SMALL LETTER G WITH CEDILLA +264 180 B4 ī LATIN SMALL LETTER I WITH MACRON +265 181 B5 ĩ LATIN SMALL LETTER I WITH TILDE +266 182 B6 ķ LATIN SMALL LETTER K WITH CEDILLA +267 183 B7 · MIDDLE DOT +270 184 B8 ļ LATIN SMALL LETTER L WITH CEDILLA +271 185 B9 đ LATIN SMALL LETTER D WITH STROKE +272 186 BA š LATIN SMALL LETTER S WITH CARON +273 187 BB ŧ LATIN SMALL LETTER T WITH STROKE +274 188 BC ž LATIN SMALL LETTER Z WITH CARON +275 189 BD ― HORIZONTAL BAR +276 190 BE ū LATIN SMALL LETTER U WITH MACRON +277 191 BF ŋ LATIN SMALL LETTER ENG +300 192 C0 Ā LATIN CAPITAL LETTER A WITH MACRON +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Į LATIN CAPITAL LETTER I WITH OGONEK +310 200 C8 Č LATIN CAPITAL LETTER C WITH CARON +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ę LATIN CAPITAL LETTER E WITH OGONEK +312 202 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ė LATIN CAPITAL LETTER E WITH DOT ABOVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER ETH +321 209 D1 Ņ LATIN CAPITAL LETTER N WITH CEDILLA +322 210 D2 Ō LATIN CAPITAL LETTER O WITH MACRON +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 Ũ LATIN CAPITAL LETTER U WITH TILDE +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ų LATIN CAPITAL LETTER U WITH OGONEK +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER THORN +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 ā LATIN SMALL LETTER A WITH MACRON +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 į LATIN SMALL LETTER I WITH OGONEK +350 232 E8 č LATIN SMALL LETTER C WITH CARON +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ę LATIN SMALL LETTER E WITH OGONEK +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ė LATIN SMALL LETTER E WITH DOT ABOVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER ETH +361 241 F1 ņ LATIN SMALL LETTER N WITH CEDILLA +362 242 F2 ō LATIN SMALL LETTER O WITH MACRON +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ũ LATIN SMALL LETTER U WITH TILDE +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ų LATIN SMALL LETTER U WITH OGONEK +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER THORN +377 255 FF ĸ LATIN SMALL LETTER KRA +.TE +.SH NOTES +ISO/IEC\~8859-10 is also known as Latin-6. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-11.7 b/man/man7/iso_8859-11.7 new file mode 100644 index 0000000..ab59d96 --- /dev/null +++ b/man/man7/iso_8859-11.7 @@ -0,0 +1,143 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\"Thanomsub Noppaburana made valuable suggestions. +.\" +.TH ISO_8859-11 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-11 \- ISO/IEC\~8859-11 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-11 encodes the +characters used in the Thai language. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-11 characters +The following table displays the characters in ISO/IEC\~8859-11 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ก THAI CHARACTER KO KAI +242 162 A2 ข THAI CHARACTER KHO KHAI +243 163 A3 ฃ THAI CHARACTER KHO KHUAT +244 164 A4 ค THAI CHARACTER KHO KHWAI +245 165 A5 ฅ THAI CHARACTER KHO KHON +246 166 A6 ฆ THAI CHARACTER KHO RAKHANG +247 167 A7 ง THAI CHARACTER NGO NGU +250 168 A8 จ THAI CHARACTER CHO CHAN +251 169 A9 ฉ THAI CHARACTER CHO CHING +252 170 AA ช THAI CHARACTER CHO CHANG +253 171 AB ซ THAI CHARACTER SO SO +254 172 AC ฌ THAI CHARACTER CHO CHOE +255 173 AD ญ THAI CHARACTER YO YING +256 174 AE ฎ THAI CHARACTER DO CHADA +257 175 AF ฏ THAI CHARACTER TO PATAK +260 176 B0 ฐ THAI CHARACTER THO THAN +261 177 B1 ฑ THAI CHARACTER THO NANGMONTHO +262 178 B2 ฒ THAI CHARACTER THO PHUTHAO +263 179 B3 ณ THAI CHARACTER NO NEN +264 180 B4 ด THAI CHARACTER DO DEK +265 181 B5 ต THAI CHARACTER TO TAO +266 182 B6 ถ THAI CHARACTER THO THUNG +267 183 B7 ท THAI CHARACTER THO THAHAN +270 184 B8 ธ THAI CHARACTER THO THONG +271 185 B9 น THAI CHARACTER NO NU +272 186 BA บ THAI CHARACTER BO BAIMAI +273 187 BB ป THAI CHARACTER PO PLA +274 188 BC ผ THAI CHARACTER PHO PHUNG +275 189 BD ฝ THAI CHARACTER FO FA +276 190 BE พ THAI CHARACTER PHO PHAN +277 191 BF ฟ THAI CHARACTER FO FAN +300 192 C0 ภ THAI CHARACTER PHO SAMPHAO +301 193 C1 ม THAI CHARACTER MO MA +302 194 C2 ย THAI CHARACTER YO YAK +303 195 C3 ร THAI CHARACTER RO RUA +304 196 C4 ฤ THAI CHARACTER RU +305 197 C5 ล THAI CHARACTER LO LING +306 198 C6 ฦ THAI CHARACTER LU +307 199 C7 ว THAI CHARACTER WO WAEN +310 200 C8 ศ THAI CHARACTER SO SALA +311 201 C9 ษ THAI CHARACTER SO RUSI +312 202 CA ส THAI CHARACTER SO SUA +313 203 CB ห THAI CHARACTER HO HIP +314 204 CC ฬ THAI CHARACTER LO CHULA +315 205 CD อ THAI CHARACTER O ANG +316 206 CE ฮ THAI CHARACTER HO NOKHUK +317 207 CF ฯ THAI CHARACTER PAIYANNOI +320 208 D0 ะ THAI CHARACTER SARA A +321 209 D1 ั THAI CHARACTER MAI HAN-AKAT +322 210 D2 า THAI CHARACTER SARA AA +323 211 D3 ำ THAI CHARACTER SARA AM +324 212 D4 ิ THAI CHARACTER SARA I +325 213 D5 ี THAI CHARACTER SARA II +326 214 D6 ึ THAI CHARACTER SARA UE +327 215 D7 ื THAI CHARACTER SARA UEE +330 216 D8 ุ THAI CHARACTER SARA U +331 217 D9 ู THAI CHARACTER SARA UU +332 218 DA ฺ THAI CHARACTER PHINTHU +337 223 DF ฿ THAI CURRENCY SYMBOL BAHT +340 224 E0 เ THAI CHARACTER SARA E +341 225 E1 แ THAI CHARACTER SARA AE +342 226 E2 โ THAI CHARACTER SARA O +343 227 E3 ใ THAI CHARACTER SARA AI MAIMUAN +344 228 E4 ไ THAI CHARACTER SARA AI MAIMALAI +345 229 E5 ๅ THAI CHARACTER LAKKHANGYAO +346 230 E6 ๆ THAI CHARACTER MAIYAMOK +347 231 E7 ็ THAI CHARACTER MAITAIKHU +350 232 E8 ่ THAI CHARACTER MAI EK +351 233 E9 ้ THAI CHARACTER MAI THO +352 234 EA ๊ THAI CHARACTER MAI TRI +353 235 EB ๋ THAI CHARACTER MAI CHATTAWA +354 236 EC ์ THAI CHARACTER THANTHAKHAT +355 237 ED ํ THAI CHARACTER NIKHAHIT +356 238 EE ๎ THAI CHARACTER YAMAKKAN +357 239 EF ๏ THAI CHARACTER FONGMAN +360 240 F0 ๐ THAI DIGIT ZERO +361 241 F1 ๑ THAI DIGIT ONE +362 242 F2 ๒ THAI DIGIT TWO +363 243 F3 ๓ THAI DIGIT THREE +364 244 F4 ๔ THAI DIGIT FOUR +365 245 F5 ๕ THAI DIGIT FIVE +366 246 F6 ๖ THAI DIGIT SIX +367 247 F7 ๗ THAI DIGIT SEVEN +370 248 F8 ๘ THAI DIGIT EIGHT +371 249 F9 ๙ THAI DIGIT NINE +372 250 FA ๚ THAI CHARACTER ANGKHANKHU +373 251 FB ๛ THAI CHARACTER KHOMUT +.TE +.SH NOTES +ISO/IEC\~8859-11 is the same as TIS (Thai Industrial Standard) 620-2253, +commonly known as TIS-620, except for the character in position A0: +ISO/IEC\~8859-11 defines this as NO-BREAK SPACE, +while TIS-620 leaves it undefined. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-13.7 b/man/man7/iso_8859-13.7 new file mode 100644 index 0000000..3949915 --- /dev/null +++ b/man/man7/iso_8859-13.7 @@ -0,0 +1,146 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-13 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-13 \- ISO/IEC\~8859-13 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-13 encodes the +characters used in Baltic Rim languages. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-13 characters +The following table displays the characters in ISO/IEC\~8859-13 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ” RIGHT DOUBLE QUOTATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 „ DOUBLE LOW-9 QUOTATION MARK +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 Ø LATIN CAPITAL LETTER O WITH STROKE +251 169 A9 © COPYRIGHT SIGN +252 170 AA Ŗ LATIN CAPITAL LETTER R WITH CEDILLA +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF Æ LATIN CAPITAL LETTER AE +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 “ LEFT DOUBLE QUOTATION MARK +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ø LATIN SMALL LETTER O WITH STROKE +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA ŗ LATIN SMALL LETTER R WITH CEDILLA +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +277 191 BF æ LATIN SMALL LETTER AE +300 192 C0 Ą LATIN CAPITAL LETTER A WITH OGONEK +301 193 C1 Į LATIN CAPITAL LETTER I WITH OGONEK +302 194 C2 Ā LATIN CAPITAL LETTER A WITH MACRON +303 195 C3 Ć LATIN CAPITAL LETTER C WITH ACUTE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Ę LATIN CAPITAL LETTER E WITH OGONEK +307 199 C7 Ē LATIN CAPITAL LETTER E WITH MACRON +310 200 C8 Č LATIN CAPITAL LETTER C WITH CARON +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ź LATIN CAPITAL LETTER Z WITH ACUTE +313 203 CB Ė LATIN CAPITAL LETTER E WITH DOT ABOVE +314 204 CC Ģ LATIN CAPITAL LETTER G WITH CEDILLA +315 205 CD Ķ LATIN CAPITAL LETTER K WITH CEDILLA +316 206 CE Ī LATIN CAPITAL LETTER I WITH MACRON +317 207 CF Ļ LATIN CAPITAL LETTER L WITH CEDILLA +320 208 D0 Š LATIN CAPITAL LETTER S WITH CARON +321 209 D1 Ń LATIN CAPITAL LETTER N WITH ACUTE +322 210 D2 Ņ LATIN CAPITAL LETTER N WITH CEDILLA +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ō LATIN CAPITAL LETTER O WITH MACRON +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ų LATIN CAPITAL LETTER U WITH OGONEK +331 217 D9 Ł LATIN CAPITAL LETTER L WITH STROKE +332 218 DA Ś LATIN CAPITAL LETTER S WITH ACUTE +333 219 DB Ū LATIN CAPITAL LETTER U WITH MACRON +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ż LATIN CAPITAL LETTER Z WITH DOT ABOVE +336 222 DE Ž LATIN CAPITAL LETTER Z WITH CARON +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 ą LATIN SMALL LETTER A WITH OGONEK +341 225 E1 į LATIN SMALL LETTER I WITH OGONEK +342 226 E2 ā LATIN SMALL LETTER A WITH MACRON +343 227 E3 ć LATIN SMALL LETTER C WITH ACUTE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 ę LATIN SMALL LETTER E WITH OGONEK +347 231 E7 ē LATIN SMALL LETTER E WITH MACRON +350 232 E8 č LATIN SMALL LETTER C WITH CARON +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ź LATIN SMALL LETTER Z WITH ACUTE +353 235 EB ė LATIN SMALL LETTER E WITH DOT ABOVE +354 236 EC ģ LATIN SMALL LETTER G WITH CEDILLA +355 237 ED ķ LATIN SMALL LETTER K WITH CEDILLA +356 238 EE ī LATIN SMALL LETTER I WITH MACRON +357 239 EF ļ LATIN SMALL LETTER L WITH CEDILLA +360 240 F0 š LATIN SMALL LETTER S WITH CARON +361 241 F1 ń LATIN SMALL LETTER N WITH ACUTE +362 242 F2 ņ LATIN SMALL LETTER N WITH CEDILLA +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ō LATIN SMALL LETTER O WITH MACRON +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ų LATIN SMALL LETTER U WITH OGONEK +371 249 F9 ł LATIN SMALL LETTER L WITH STROKE +372 250 FA ś LATIN SMALL LETTER S WITH ACUTE +373 251 FB ū LATIN SMALL LETTER U WITH MACRON +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ż LATIN SMALL LETTER Z WITH DOT ABOVE +376 254 FE ž LATIN SMALL LETTER Z WITH CARON +377 255 FF ’ RIGHT SINGLE QUOTATION MARK +.TE +.SH NOTES +ISO/IEC\~8859-13 is also known as Latin-7. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-14.7 b/man/man7/iso_8859-14.7 new file mode 100644 index 0000000..41cf719 --- /dev/null +++ b/man/man7/iso_8859-14.7 @@ -0,0 +1,146 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-14 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-14 \- ISO/IEC\~8859-14 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-14 encodes the +characters used in Celtic languages. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-14 characters +The following table displays the characters in ISO/IEC\~8859-14 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ḃ LATIN CAPITAL LETTER B WITH DOT ABOVE +242 162 A2 ḃ LATIN SMALL LETTER B WITH DOT ABOVE +243 163 A3 £ POUND SIGN +244 164 A4 Ċ LATIN CAPITAL LETTER C WITH DOT ABOVE +245 165 A5 ċ LATIN SMALL LETTER C WITH DOT ABOVE +246 166 A6 Ḋ LATIN CAPITAL LETTER D WITH DOT ABOVE +247 167 A7 § SECTION SIGN +250 168 A8 Ẁ LATIN CAPITAL LETTER W WITH GRAVE +251 169 A9 © COPYRIGHT SIGN +252 170 AA Ẃ LATIN CAPITAL LETTER W WITH ACUTE +253 171 AB ḋ LATIN SMALL LETTER D WITH DOT ABOVE +254 172 AC Ỳ LATIN CAPITAL LETTER Y WITH GRAVE +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF Ÿ LATIN CAPITAL LETTER Y WITH DIAERESIS +260 176 B0 Ḟ LATIN CAPITAL LETTER F WITH DOT ABOVE +261 177 B1 ḟ LATIN SMALL LETTER F WITH DOT ABOVE +262 178 B2 Ġ LATIN CAPITAL LETTER G WITH DOT ABOVE +263 179 B3 ġ LATIN SMALL LETTER G WITH DOT ABOVE +264 180 B4 Ṁ LATIN CAPITAL LETTER M WITH DOT ABOVE +265 181 B5 ṁ LATIN SMALL LETTER M WITH DOT ABOVE +266 182 B6 ¶ PILCROW SIGN +267 183 B7 Ṗ LATIN CAPITAL LETTER P WITH DOT ABOVE +270 184 B8 ẁ LATIN SMALL LETTER W WITH GRAVE +271 185 B9 ṗ LATIN SMALL LETTER P WITH DOT ABOVE +272 186 BA ẃ LATIN SMALL LETTER W WITH ACUTE +273 187 BB Ṡ LATIN CAPITAL LETTER S WITH DOT ABOVE +274 188 BC ỳ LATIN SMALL LETTER Y WITH GRAVE +275 189 BD Ẅ LATIN CAPITAL LETTER W WITH DIAERESIS +276 190 BE ẅ LATIN SMALL LETTER W WITH DIAERESIS +277 191 BF ṡ LATIN SMALL LETTER S WITH DOT ABOVE +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ŵ LATIN CAPITAL LETTER W WITH CIRCUMFLEX +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 Ṫ LATIN CAPITAL LETTER T WITH DOT ABOVE +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Ŷ LATIN CAPITAL LETTER Y WITH CIRCUMFLEX +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ŵ LATIN SMALL LETTER W WITH CIRCUMFLEX +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ṫ LATIN SMALL LETTER T WITH DOT ABOVE +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE ŷ LATIN SMALL LETTER Y WITH CIRCUMFLEX +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +ISO/IEC\~8859-14 is also known as Latin-8. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-15.7 b/man/man7/iso_8859-15.7 new file mode 100644 index 0000000..20af655 --- /dev/null +++ b/man/man7/iso_8859-15.7 @@ -0,0 +1,149 @@ +'\" t +.\" Copyright 1993-1995 Daniel Quinlan (quinlan@yggdrasil.com) +.\" Copyright 1999 Dimitri Papadopoulos (dpo@club-internet.fr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-15 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-15 \- ISO/IEC\~8859-15 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-15 encodes the +characters used in many West European languages and adds the Euro sign. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-15 characters +The following table displays the characters in ISO/IEC\~8859-15 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 € EURO SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 Š LATIN CAPITAL LETTER S WITH CARON +247 167 A7 § SECTION SIGN +250 168 A8 š LATIN SMALL LETTER S WITH CARON +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 Ž LATIN CAPITAL LETTER Z WITH CARON +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ž LATIN SMALL LETTER Z WITH CARON +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC Œ LATIN CAPITAL LIGATURE OE +275 189 BD œ LATIN SMALL LIGATURE OE +276 190 BE Ÿ LATIN CAPITAL LETTER Y WITH DIAERESIS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ð LATIN CAPITAL LETTER ETH +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Þ LATIN CAPITAL LETTER THORN +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ð LATIN SMALL LETTER ETH +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE þ LATIN SMALL LETTER THORN +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +ISO/IEC\~8859-15 is also known as Latin-9 (or sometimes as Latin-0). +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1252 (7), +.BR iso_8859\-1 (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-16.7 b/man/man7/iso_8859-16.7 new file mode 100644 index 0000000..88d443c --- /dev/null +++ b/man/man7/iso_8859-16.7 @@ -0,0 +1,147 @@ +'\" t +.\" Copyright 2002 Ionel Mugurel Ciobîcă (IMCiobica@netscape.net) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-16 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-16 \- ISO/IEC\~8859-16 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-16 encodes the +Latin characters used in Southeast European languages. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-16 characters +The following table displays the characters in ISO/IEC\~8859-16 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ą LATIN CAPITAL LETTER A WITH OGONEK +242 162 A2 ą LATIN SMALL LETTER A WITH OGONEK +243 163 A3 Ł LATIN CAPITAL LETTER L WITH STROKE +244 164 A4 € EURO SIGN +245 165 A5 „ DOUBLE LOW-9 QUOTATION MARK +246 166 A6 Š LATIN CAPITAL LETTER S WITH CARON +247 167 A7 § SECTION SIGN +250 168 A8 š LATIN SMALL LETTER S WITH CARON +251 169 A9 © COPYRIGHT SIGN +252 170 AA Ș LATIN CAPITAL LETTER S WITH COMMA BELOW +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC Ź LATIN CAPITAL LETTER Z WITH ACUTE +255 173 AD ­ SOFT HYPHEN +256 174 AE ź LATIN SMALL LETTER Z WITH ACUTE +257 175 AF Ż LATIN CAPITAL LETTER Z WITH DOT ABOVE +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 Č LATIN CAPITAL LETTER C WITH CARON +263 179 B3 ł LATIN SMALL LETTER L WITH STROKE +264 180 B4 Ž LATIN CAPITAL LETTER Z WITH CARON +265 181 B5 ” LEFT DOUBLE QUOTATION MARK +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ž LATIN SMALL LETTER Z WITH CARON +271 185 B9 č LATIN SMALL LETTER C WITH CARON +272 186 BA ș LATIN SMALL LETTER S WITH COMMA BELOW +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC Œ LATIN CAPITAL LIGATURE OE +275 189 BD œ LATIN SMALL LIGATURE OE +276 190 BE Ÿ LATIN CAPITAL LETTER Y WITH DIAERESIS +277 191 BF ż LATIN SMALL LETTER Z WITH DOT ABOVE +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 Ă LATIN CAPITAL LETTER A WITH BREVE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Ć LATIN CAPITAL LETTER C WITH ACUTE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Đ LATIN CAPITAL LETTER D WITH STROKE +321 209 D1 Ń LATIN CAPITAL LETTER N WITH ACUTE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Ő LATIN CAPITAL LETTER O WITH DOUBLE ACUTE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 Ś LATIN CAPITAL LETTER S WITH ACUTE +330 216 D8 Ű LATIN CAPITAL LETTER U WITH DOUBLE ACUTE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ę LATIN CAPITAL LETTER E WITH OGONEK +336 222 DE Ț LATIN CAPITAL LETTER T WITH COMMA BELOW +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ă LATIN SMALL LETTER A WITH BREVE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 ć LATIN SMALL LETTER C WITH ACUTE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 đ LATIN SMALL LETTER D WITH STROKE +361 241 F1 ń LATIN SMALL LETTER N WITH ACUTE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 ő LATIN SMALL LETTER O WITH DOUBLE ACUTE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ś LATIN SMALL LETTER S WITH ACUTE +370 248 F8 ű LATIN SMALL LETTER U WITH DOUBLE ACUTE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ę LATIN SMALL LETTER E WITH OGONEK +376 254 FE ț LATIN SMALL LETTER T WITH COMMA BELOW +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +ISO/IEC\~8859-16 is also known as Latin-10. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR iso_8859\-3 (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-2.7 b/man/man7/iso_8859-2.7 new file mode 100644 index 0000000..0aec6f1 --- /dev/null +++ b/man/man7/iso_8859-2.7 @@ -0,0 +1,151 @@ +'\" t +.\" Copyright 1999 Roman Maurer (roman.maurer@hermes.si) +.\" Copyright 1993-1995 Daniel Quinlan (quinlan@yggdrasil.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Slightly rearranged, aeb, 950713 +.\" Updated, dpo, 990531 +.TH ISO_8859-2 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-2 \- ISO/IEC\~8859-2 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-2 encodes the +Latin characters used in many Central and East European languages. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-2 characters +The following table displays the characters in ISO/IEC\~8859-2 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ą LATIN CAPITAL LETTER A WITH OGONEK +242 162 A2 ˘ BREVE +243 163 A3 Ł LATIN CAPITAL LETTER L WITH STROKE +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 Ľ LATIN CAPITAL LETTER L WITH CARON +246 166 A6 Ś LATIN CAPITAL LETTER S WITH ACUTE +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 Š LATIN CAPITAL LETTER S WITH CARON +252 170 AA Ş LATIN CAPITAL LETTER S WITH CEDILLA +253 171 AB Ť LATIN CAPITAL LETTER T WITH CARON +254 172 AC Ź LATIN CAPITAL LETTER Z WITH ACUTE +255 173 AD ­ SOFT HYPHEN +256 174 AE Ž LATIN CAPITAL LETTER Z WITH CARON +257 175 AF Ż LATIN CAPITAL LETTER Z WITH DOT ABOVE +260 176 B0 ° DEGREE SIGN +261 177 B1 ą LATIN SMALL LETTER A WITH OGONEK +262 178 B2 ˛ OGONEK +263 179 B3 ł LATIN SMALL LETTER L WITH STROKE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 ľ LATIN SMALL LETTER L WITH CARON +266 182 B6 ś LATIN SMALL LETTER S WITH ACUTE +267 183 B7 ˇ CARON +270 184 B8 ¸ CEDILLA +271 185 B9 š LATIN SMALL LETTER S WITH CARON +272 186 BA ş LATIN SMALL LETTER S WITH CEDILLA +273 187 BB ť LATIN SMALL LETTER T WITH CARON +274 188 BC ź LATIN SMALL LETTER Z WITH ACUTE +275 189 BD ˝ DOUBLE ACUTE ACCENT +276 190 BE ž LATIN SMALL LETTER Z WITH CARON +277 191 BF ż LATIN SMALL LETTER Z WITH DOT ABOVE +300 192 C0 Ŕ LATIN CAPITAL LETTER R WITH ACUTE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 Ă LATIN CAPITAL LETTER A WITH BREVE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Ĺ LATIN CAPITAL LETTER L WITH ACUTE +306 198 C6 Ć LATIN CAPITAL LETTER C WITH ACUTE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 Č LATIN CAPITAL LETTER C WITH CARON +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ę LATIN CAPITAL LETTER E WITH OGONEK +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ě LATIN CAPITAL LETTER E WITH CARON +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ď LATIN CAPITAL LETTER D WITH CARON +320 208 D0 Đ LATIN CAPITAL LETTER D WITH STROKE +321 209 D1 Ń LATIN CAPITAL LETTER N WITH ACUTE +322 210 D2 Ň LATIN CAPITAL LETTER N WITH CARON +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Ő LATIN CAPITAL LETTER O WITH DOUBLE ACUTE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ř LATIN CAPITAL LETTER R WITH CARON +331 217 D9 Ů LATIN CAPITAL LETTER U WITH RING ABOVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Ű LATIN CAPITAL LETTER U WITH DOUBLE ACUTE +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ý LATIN CAPITAL LETTER Y WITH ACUTE +336 222 DE Ţ LATIN CAPITAL LETTER T WITH CEDILLA +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 ŕ LATIN SMALL LETTER R WITH ACUTE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ă LATIN SMALL LETTER A WITH BREVE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 ĺ LATIN SMALL LETTER L WITH ACUTE +346 230 E6 ć LATIN SMALL LETTER C WITH ACUTE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 č LATIN SMALL LETTER C WITH CARON +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ę LATIN SMALL LETTER E WITH OGONEK +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ě LATIN SMALL LETTER E WITH CARON +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ď LATIN SMALL LETTER D WITH CARON +360 240 F0 đ LATIN SMALL LETTER D WITH STROKE +361 241 F1 ń LATIN SMALL LETTER N WITH ACUTE +362 242 F2 ň LATIN SMALL LETTER N WITH CARON +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 ő LATIN SMALL LETTER O WITH DOUBLE ACUTE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ř LATIN SMALL LETTER R WITH CARON +371 249 F9 ů LATIN SMALL LETTER U WITH RING ABOVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB ű LATIN SMALL LETTER U WITH DOUBLE ACUTE +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ý LATIN SMALL LETTER Y WITH ACUTE +376 254 FE ţ LATIN SMALL LETTER T WITH CEDILLA +377 255 FF ˙ DOT ABOVE +.TE +.SH NOTES +ISO/IEC\~8859-2 is also known as Latin-2. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR iso_8859\-1 (7), +.BR iso_8859\-16 (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-3.7 b/man/man7/iso_8859-3.7 new file mode 100644 index 0000000..fc696aa --- /dev/null +++ b/man/man7/iso_8859-3.7 @@ -0,0 +1,139 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-3 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-3 \- ISO/IEC\~8859-3 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-3 encodes the +characters used in certain Southeast European languages. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-3 characters +The following table displays the characters in ISO/IEC\~8859-3 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ħ LATIN CAPITAL LETTER H WITH STROKE +242 162 A2 ˘ BREVE +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +246 166 A6 Ĥ LATIN CAPITAL LETTER H WITH CIRCUMFLEX +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 İ LATIN CAPITAL LETTER I WITH DOT ABOVE +252 170 AA Ş LATIN CAPITAL LETTER S WITH CEDILLA +253 171 AB Ğ LATIN CAPITAL LETTER G WITH BREVE +254 172 AC Ĵ LATIN CAPITAL LETTER J WITH CIRCUMFLEX +255 173 AD ­ SOFT HYPHEN +257 175 AF Ż LATIN CAPITAL LETTER Z WITH DOT ABOVE +260 176 B0 ° DEGREE SIGN +261 177 B1 ħ LATIN SMALL LETTER H WITH STROKE +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ĥ LATIN SMALL LETTER H WITH CIRCUMFLEX +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ı LATIN SMALL LETTER DOTLESS I +272 186 BA ş LATIN SMALL LETTER S WITH CEDILLA +273 187 BB ğ LATIN SMALL LETTER G WITH BREVE +274 188 BC ĵ LATIN SMALL LETTER J WITH CIRCUMFLEX +275 189 BD ½ VULGAR FRACTION ONE HALF +277 191 BF ż LATIN SMALL LETTER Z WITH DOT ABOVE +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Ċ LATIN CAPITAL LETTER C WITH DOT ABOVE +306 198 C6 Ĉ LATIN CAPITAL LETTER C WITH CIRCUMFLEX +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Ġ LATIN CAPITAL LETTER G WITH DOT ABOVE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ĝ LATIN CAPITAL LETTER G WITH CIRCUMFLEX +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ŭ LATIN CAPITAL LETTER U WITH BREVE +336 222 DE Ŝ LATIN CAPITAL LETTER S WITH CIRCUMFLEX +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 ċ LATIN SMALL LETTER C WITH DOT ABOVE +346 230 E6 ĉ LATIN SMALL LETTER C WITH CIRCUMFLEX +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 ġ LATIN SMALL LETTER G WITH DOT ABOVE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ĝ LATIN SMALL LETTER G WITH CIRCUMFLEX +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ŭ LATIN SMALL LETTER U WITH BREVE +376 254 FE ŝ LATIN SMALL LETTER S WITH CIRCUMFLEX +377 255 FF ˙ DOT ABOVE +.TE +.SH NOTES +ISO/IEC\~8859-3 is also known as Latin-3. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-4.7 b/man/man7/iso_8859-4.7 new file mode 100644 index 0000000..e2b0bc2 --- /dev/null +++ b/man/man7/iso_8859-4.7 @@ -0,0 +1,146 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-4 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-4 \- ISO/IEC\~8859-4 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-4 encodes the +characters used in Scandinavian and Baltic languages. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-4 characters +The following table displays the characters in ISO/IEC\~8859-4 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ą LATIN CAPITAL LETTER A WITH OGONEK +242 162 A2 ĸ LATIN SMALL LETTER KRA (Greenlandic) +243 163 A3 Ŗ LATIN CAPITAL LETTER R WITH CEDILLA +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 Ĩ LATIN CAPITAL LETTER I WITH TILDE +246 166 A6 Ļ LATIN CAPITAL LETTER L WITH CEDILLA +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 Š LATIN CAPITAL LETTER S WITH CARON +252 170 AA Ē LATIN CAPITAL LETTER E WITH MACRON +253 171 AB Ģ LATIN CAPITAL LETTER G WITH CEDILLA +254 172 AC Ŧ LATIN CAPITAL LETTER T WITH STROKE +255 173 AD ­ SOFT HYPHEN +256 174 AE Ž LATIN CAPITAL LETTER Z WITH CARON +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ą LATIN SMALL LETTER A WITH OGONEK +262 178 B2 ˛ OGONEK +263 179 B3 ŗ LATIN SMALL LETTER R WITH CEDILLA +264 180 B4 ´ ACUTE ACCENT +265 181 B5 ĩ LATIN SMALL LETTER I WITH TILDE +266 182 B6 ļ LATIN SMALL LETTER L WITH CEDILLA +267 183 B7 ˇ CARON +270 184 B8 ¸ CEDILLA +271 185 B9 š LATIN SMALL LETTER S WITH CARON +272 186 BA ē LATIN SMALL LETTER E WITH MACRON +273 187 BB ģ LATIN SMALL LETTER G WITH CEDILLA +274 188 BC ŧ LATIN SMALL LETTER T WITH STROKE +275 189 BD Ŋ LATIN CAPITAL LETTER ENG +276 190 BE ž LATIN SMALL LETTER Z WITH CARON +277 191 BF ŋ LATIN SMALL LETTER ENG +300 192 C0 Ā LATIN CAPITAL LETTER A WITH MACRON +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Į LATIN CAPITAL LETTER I WITH OGONEK +310 200 C8 Č LATIN CAPITAL LETTER C WITH CARON +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ę LATIN CAPITAL LETTER E WITH OGONEK +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ė LATIN CAPITAL LETTER E WITH DOT ABOVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ī LATIN CAPITAL LETTER I WITH MACRON +320 208 D0 Đ LATIN CAPITAL LETTER D WITH STROKE +321 209 D1 Ņ LATIN CAPITAL LETTER N WITH CEDILLA +322 210 D2 Ō LATIN CAPITAL LETTER O WITH MACRON +323 211 D3 Ķ LATIN CAPITAL LETTER K WITH CEDILLA +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ų LATIN CAPITAL LETTER U WITH OGONEK +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD Ũ LATIN CAPITAL LETTER U WITH TILDE +336 222 DE Ū LATIN CAPITAL LETTER U WITH MACRON +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 ā LATIN SMALL LETTER A WITH MACRON +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 į LATIN SMALL LETTER I WITH OGONEK +350 232 E8 č LATIN SMALL LETTER C WITH CARON +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ę LATIN SMALL LETTER E WITH OGONEK +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ė LATIN SMALL LETTER E WITH DOT ABOVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ī LATIN SMALL LETTER I WITH MACRON +360 240 F0 đ LATIN SMALL LETTER D WITH STROKE +361 241 F1 ņ LATIN SMALL LETTER N WITH CEDILLA +362 242 F2 ō LATIN SMALL LETTER O WITH MACRON +363 243 F3 ķ LATIN SMALL LETTER K WITH CEDILLA +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ų LATIN SMALL LETTER U WITH OGONEK +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ũ LATIN SMALL LETTER U WITH TILDE +376 254 FE ū LATIN SMALL LETTER U WITH MACRON +377 255 FF ˙ DOT ABOVE +.TE +.SH NOTES +ISO/IEC\~8859-4 is also known as Latin-4. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-5.7 b/man/man7/iso_8859-5.7 new file mode 100644 index 0000000..9bf4848 --- /dev/null +++ b/man/man7/iso_8859-5.7 @@ -0,0 +1,151 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-5 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-5 \- ISO/IEC\~8859-5 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-5 encodes the +Cyrillic characters used in many East European languages. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-5 characters +The following table displays the characters in ISO/IEC\~8859-5 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 Ё CYRILLIC CAPITAL LETTER IO +242 162 A2 Ђ CYRILLIC CAPITAL LETTER DJE +243 163 A3 Ѓ CYRILLIC CAPITAL LETTER GJE +244 164 A4 Є CYRILLIC CAPITAL LETTER UKRAINIAN IE +245 165 A5 Ѕ CYRILLIC CAPITAL LETTER DZE +246 166 A6 І T{ +CYRILLIC CAPITAL LETTER +.br +BYELORUSSIAN-UKRAINIAN I +T} +247 167 A7 Ї CYRILLIC CAPITAL LETTER YI +250 168 A8 Ј CYRILLIC CAPITAL LETTER JE +251 169 A9 Љ CYRILLIC CAPITAL LETTER LJE +252 170 AA Њ CYRILLIC CAPITAL LETTER NJE +253 171 AB Ћ CYRILLIC CAPITAL LETTER TSHE +254 172 AC Ќ CYRILLIC CAPITAL LETTER KJE +255 173 AD ­ SOFT HYPHEN +256 174 AE Ў CYRILLIC CAPITAL LETTER SHORT U +257 175 AF Џ CYRILLIC CAPITAL LETTER DZHE +260 176 B0 А CYRILLIC CAPITAL LETTER A +261 177 B1 Б CYRILLIC CAPITAL LETTER BE +262 178 B2 В CYRILLIC CAPITAL LETTER VE +263 179 B3 Г CYRILLIC CAPITAL LETTER GHE +264 180 B4 Д CYRILLIC CAPITAL LETTER DE +265 181 B5 Е CYRILLIC CAPITAL LETTER IE +266 182 B6 Ж CYRILLIC CAPITAL LETTER ZHE +267 183 B7 З CYRILLIC CAPITAL LETTER ZE +270 184 B8 И CYRILLIC CAPITAL LETTER I +271 185 B9 Й CYRILLIC CAPITAL LETTER SHORT I +272 186 BA К CYRILLIC CAPITAL LETTER KA +273 187 BB Л CYRILLIC CAPITAL LETTER EL +274 188 BC М CYRILLIC CAPITAL LETTER EM +275 189 BD Н CYRILLIC CAPITAL LETTER EN +276 190 BE О CYRILLIC CAPITAL LETTER O +277 191 BF П CYRILLIC CAPITAL LETTER PE +300 192 C0 Р CYRILLIC CAPITAL LETTER ER +301 193 C1 С CYRILLIC CAPITAL LETTER ES +302 194 C2 Т CYRILLIC CAPITAL LETTER TE +303 195 C3 У CYRILLIC CAPITAL LETTER U +304 196 C4 Ф CYRILLIC CAPITAL LETTER EF +305 197 C5 Х CYRILLIC CAPITAL LETTER HA +306 198 C6 Ц CYRILLIC CAPITAL LETTER TSE +307 199 C7 Ч CYRILLIC CAPITAL LETTER CHE +310 200 C8 Ш CYRILLIC CAPITAL LETTER SHA +311 201 C9 Щ CYRILLIC CAPITAL LETTER SHCHA +312 202 CA Ъ CYRILLIC CAPITAL LETTER HARD SIGN +313 203 CB Ы CYRILLIC CAPITAL LETTER YERU +314 204 CC Ь CYRILLIC CAPITAL LETTER SOFT SIGN +315 205 CD Э CYRILLIC CAPITAL LETTER E +316 206 CE Ю CYRILLIC CAPITAL LETTER YU +317 207 CF Я CYRILLIC CAPITAL LETTER YA +320 208 D0 а CYRILLIC SMALL LETTER A +321 209 D1 б CYRILLIC SMALL LETTER BE +322 210 D2 в CYRILLIC SMALL LETTER VE +323 211 D3 г CYRILLIC SMALL LETTER GHE +324 212 D4 д CYRILLIC SMALL LETTER DE +325 213 D5 е CYRILLIC SMALL LETTER IE +326 214 D6 ж CYRILLIC SMALL LETTER ZHE +327 215 D7 з CYRILLIC SMALL LETTER ZE +330 216 D8 и CYRILLIC SMALL LETTER I +331 217 D9 й CYRILLIC SMALL LETTER SHORT I +332 218 DA к CYRILLIC SMALL LETTER KA +333 219 DB л CYRILLIC SMALL LETTER EL +334 220 DC м CYRILLIC SMALL LETTER EM +335 221 DD н CYRILLIC SMALL LETTER EN +336 222 DE о CYRILLIC SMALL LETTER O +337 223 DF п CYRILLIC SMALL LETTER PE +340 224 E0 р CYRILLIC SMALL LETTER ER +341 225 E1 с CYRILLIC SMALL LETTER ES +342 226 E2 т CYRILLIC SMALL LETTER TE +343 227 E3 у CYRILLIC SMALL LETTER U +344 228 E4 ф CYRILLIC SMALL LETTER EF +345 229 E5 х CYRILLIC SMALL LETTER HA +346 230 E6 ц CYRILLIC SMALL LETTER TSE +347 231 E7 ч CYRILLIC SMALL LETTER CHE +350 232 E8 ш CYRILLIC SMALL LETTER SHA +351 233 E9 щ CYRILLIC SMALL LETTER SHCHA +352 234 EA ъ CYRILLIC SMALL LETTER HARD SIGN +353 235 EB ы CYRILLIC SMALL LETTER YERU +354 236 EC ь CYRILLIC SMALL LETTER SOFT SIGN +355 237 ED э CYRILLIC SMALL LETTER E +356 238 EE ю CYRILLIC SMALL LETTER YU +357 239 EF я CYRILLIC SMALL LETTER YA +360 240 F0 № NUMERO SIGN +361 241 F1 ё CYRILLIC SMALL LETTER IO +362 242 F2 ђ CYRILLIC SMALL LETTER DJE +363 243 F3 ѓ CYRILLIC SMALL LETTER GJE +364 244 F4 є CYRILLIC SMALL LETTER UKRAINIAN IE +365 245 F5 ѕ CYRILLIC SMALL LETTER DZE +366 246 F6 і CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I +367 247 F7 ї CYRILLIC SMALL LETTER YI +370 248 F8 ј CYRILLIC SMALL LETTER JE +371 249 F9 љ CYRILLIC SMALL LETTER LJE +372 250 FA њ CYRILLIC SMALL LETTER NJE +373 251 FB ј CYRILLIC SMALL LETTER TSHE +374 252 FC ќ CYRILLIC SMALL LETTER KJE +375 253 FD § SECTION SIGN +376 254 FE ў CYRILLIC SMALL LETTER SHORT U +377 255 FF џ CYRILLIC SMALL LETTER DZHE +.TE +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1251 (7), +.BR koi8\-r (7), +.BR koi8\-u (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-6.7 b/man/man7/iso_8859-6.7 new file mode 100644 index 0000000..4f8ddc6 --- /dev/null +++ b/man/man7/iso_8859-6.7 @@ -0,0 +1,104 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-6 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-6 +\- +ISO/IEC\~8859-6 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-6 encodes the +characters used in the Arabic language. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-6 characters +The following table displays the characters in ISO/IEC\~8859-6 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +244 164 A4 ¤ CURRENCY SIGN +254 172 AC ، ARABIC COMMA +255 173 AD ­ SOFT HYPHEN +273 187 BB ؛ ARABIC SEMICOLON +277 191 BF ؟ ARABIC QUESTION MARK +301 193 C1 ء ARABIC LETTER HAMZA +302 194 C2 آ ARABIC LETTER ALEF WITH MADDA ABOVE +303 195 C3 أ ARABIC LETTER ALEF WITH HAMZA ABOVE +304 196 C4 ؤ ARABIC LETTER WAW WITH HAMZA ABOVE +305 197 C5 إ ARABIC LETTER ALEF WITH HAMZA BELOW +306 198 C6 ئ ARABIC LETTER YEH WITH HAMZA ABOVE +307 199 C7 ا ARABIC LETTER ALEF +310 200 C8 ب ARABIC LETTER BEH +311 201 C9 ة ARABIC LETTER TEH MARBUTA +312 202 CA ت ARABIC LETTER TEH +313 203 CB ث ARABIC LETTER THEH +314 204 CC ج ARABIC LETTER JEEM +315 205 CD ح ARABIC LETTER HAH +316 206 CE خ ARABIC LETTER KHAH +317 207 CF د ARABIC LETTER DAL +320 208 D0 ذ ARABIC LETTER THAL +321 209 D1 ر ARABIC LETTER REH +322 210 D2 ز ARABIC LETTER ZAIN +323 211 D3 س ARABIC LETTER SEEN +324 212 D4 ش ARABIC LETTER SHEEN +325 213 D5 ص ARABIC LETTER SAD +326 214 D6 ض ARABIC LETTER DAD +327 215 D7 ط ARABIC LETTER TAH +330 216 D8 ظ ARABIC LETTER ZAH +331 217 D9 ع ARABIC LETTER AIN +332 218 DA غ ARABIC LETTER GHAIN +340 224 E0 ـ ARABIC TATWEEL +341 225 E1 ف ARABIC LETTER FEH +342 226 E2 ق ARABIC LETTER QAF +343 227 E3 ك ARABIC LETTER KAF +344 228 E4 ل ARABIC LETTER LAM +345 229 E5 م ARABIC LETTER MEEM +346 230 E6 ن ARABIC LETTER NOON +347 231 E7 ه ARABIC LETTER HEH +350 232 E8 و ARABIC LETTER WAW +351 233 E9 ى ARABIC LETTER ALEF MAKSURA +352 234 EA ي ARABIC LETTER YEH +353 235 EB ً ARABIC FATHATAN +354 236 EC ٌ ARABIC DAMMATAN +355 237 ED ٍ ARABIC KASRATAN +356 238 EE َ ARABIC FATHA +357 239 EF ُ ARABIC DAMMA +360 240 F0 ِ ARABIC KASRA +361 241 F1 ّ ARABIC SHADDA +362 242 F2 ْ ARABIC SUKUN +.TE +.SH NOTES +ISO/IEC\~8859-6 lacks the glyphs required for many related languages, +such as Urdu and Persian (Farsi). +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-7.7 b/man/man7/iso_8859-7.7 new file mode 100644 index 0000000..e1f044f --- /dev/null +++ b/man/man7/iso_8859-7.7 @@ -0,0 +1,150 @@ +'\" t +.\" Copyright 1999 Dimitri Papadopoulos (dpo@club-internet.fr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-7 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-7 \- ISO/IEC\~8859-7 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-7 encodes the +characters used in modern monotonic Greek. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-7 characters +The following table displays the characters in ISO/IEC\~8859-7 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ‘ LEFT SINGLE QUOTATION MARK +242 162 A2 ’ RIGHT SINGLE QUOTATION MARK +243 163 A3 £ POUND SIGN +244 164 A4 € EURO SIGN +245 165 A5 ₯ DRACHMA SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA ͺ GREEK YPOGEGRAMMENI +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +257 175 AF ― HORIZONTAL BAR +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ΄ GREEK TONOS +265 181 B5 ΅ GREEK DIALYTIKA TONOS +266 182 B6 Ά GREEK CAPITAL LETTER ALPHA WITH TONOS +267 183 B7 · MIDDLE DOT +270 184 B8 Έ GREEK CAPITAL LETTER EPSILON WITH TONOS +271 185 B9 Ή GREEK CAPITAL LETTER ETA WITH TONOS +272 186 BA Ί GREEK CAPITAL LETTER IOTA WITH TONOS +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC Ό GREEK CAPITAL LETTER OMICRON WITH TONOS +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE Ύ GREEK CAPITAL LETTER UPSILON WITH TONOS +277 191 BF Ώ GREEK CAPITAL LETTER OMEGA WITH TONOS +300 192 C0 ΐ T{ +GREEK SMALL LETTER IOTA WITH +.br +DIALYTIKA AND TONOS +T} +301 193 C1 Α GREEK CAPITAL LETTER ALPHA +302 194 C2 Β GREEK CAPITAL LETTER BETA +303 195 C3 Γ GREEK CAPITAL LETTER GAMMA +304 196 C4 Δ GREEK CAPITAL LETTER DELTA +305 197 C5 Ε GREEK CAPITAL LETTER EPSILON +306 198 C6 Ζ GREEK CAPITAL LETTER ZETA +307 199 C7 Η GREEK CAPITAL LETTER ETA +310 200 C8 Θ GREEK CAPITAL LETTER THETA +311 201 C9 Ι GREEK CAPITAL LETTER IOTA +312 202 CA Κ GREEK CAPITAL LETTER KAPPA +313 203 CB Λ GREEK CAPITAL LETTER LAMBDA +314 204 CC Μ GREEK CAPITAL LETTER MU +315 205 CD Ν GREEK CAPITAL LETTER NU +316 206 CE Ξ GREEK CAPITAL LETTER XI +317 207 CF Ο GREEK CAPITAL LETTER OMICRON +320 208 D0 Π GREEK CAPITAL LETTER PI +321 209 D1 Ρ GREEK CAPITAL LETTER RHO +323 211 D3 Σ GREEK CAPITAL LETTER SIGMA +324 212 D4 Τ GREEK CAPITAL LETTER TAU +325 213 D5 Υ GREEK CAPITAL LETTER UPSILON +326 214 D6 Φ GREEK CAPITAL LETTER PHI +327 215 D7 Χ GREEK CAPITAL LETTER CHI +330 216 D8 Ψ GREEK CAPITAL LETTER PSI +331 217 D9 Ω GREEK CAPITAL LETTER OMEGA +332 218 DA Ϊ GREEK CAPITAL LETTER IOTA WITH DIALYTIKA +333 219 DB Ϋ GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA +334 220 DC ά GREEK SMALL LETTER ALPHA WITH TONOS +335 221 DD έ GREEK SMALL LETTER EPSILON WITH TONOS +336 222 DE ή GREEK SMALL LETTER ETA WITH TONOS +337 223 DF ί GREEK SMALL LETTER IOTA WITH TONOS +340 224 E0 ΰ T{ +GREEK SMALL LETTER UPSILON WITH +DIALYTIKA AND TONOS +T} +341 225 E1 α GREEK SMALL LETTER ALPHA +342 226 E2 β GREEK SMALL LETTER BETA +343 227 E3 γ GREEK SMALL LETTER GAMMA +344 228 E4 δ GREEK SMALL LETTER DELTA +345 229 E5 ε GREEK SMALL LETTER EPSILON +346 230 E6 ζ GREEK SMALL LETTER ZETA +347 231 E7 η GREEK SMALL LETTER ETA +350 232 E8 θ GREEK SMALL LETTER THETA +351 233 E9 ι GREEK SMALL LETTER IOTA +352 234 EA κ GREEK SMALL LETTER KAPPA +353 235 EB λ GREEK SMALL LETTER LAMBDA +354 236 EC μ GREEK SMALL LETTER MU +355 237 ED ν GREEK SMALL LETTER NU +356 238 EE ξ GREEK SMALL LETTER XI +357 239 EF ο GREEK SMALL LETTER OMICRON +360 240 F0 π GREEK SMALL LETTER PI +361 241 F1 ρ GREEK SMALL LETTER RHO +362 242 F2 ς GREEK SMALL LETTER FINAL SIGMA +363 243 F3 σ GREEK SMALL LETTER SIGMA +364 244 F4 τ GREEK SMALL LETTER TAU +365 245 F5 υ GREEK SMALL LETTER UPSILON +366 246 F6 φ GREEK SMALL LETTER PHI +367 247 F7 χ GREEK SMALL LETTER CHI +370 248 F8 ψ GREEK SMALL LETTER PSI +371 249 F9 ω GREEK SMALL LETTER OMEGA +372 250 FA ϊ GREEK SMALL LETTER IOTA WITH DIALYTIKA +373 251 FB ϋ GREEK SMALL LETTER UPSILON WITH DIALYTIKA +374 252 FC ό GREEK SMALL LETTER OMICRON WITH TONOS +375 253 FD ύ GREEK SMALL LETTER UPSILON WITH TONOS +376 254 FE ώ GREEK SMALL LETTER OMEGA WITH TONOS +.TE +.SH NOTES +ISO/IEC\~8859-7 was formerly known as ELOT-928 or ECMA-118:1986. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-8.7 b/man/man7/iso_8859-8.7 new file mode 100644 index 0000000..f443cbd --- /dev/null +++ b/man/man7/iso_8859-8.7 @@ -0,0 +1,114 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis (edimitro@tee.gr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Eli Zaretskii made valuable suggestions +.\" +.TH ISO_8859-8 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-8 \- ISO/IEC\~8859-8 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-8 encodes the +characters used in Modern Hebrew. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-8 characters +The following table displays the characters in ISO/IEC\~8859-8 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0 NO-BREAK SPACE +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA × MULTIPLICATION SIGN +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA ÷ DIVISION SIGN +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +337 223 DF ‗ DOUBLE LOW LINE +340 224 E0 א HEBREW LETTER ALEF +341 225 E1 ב HEBREW LETTER BET +342 226 E2 ג HEBREW LETTER GIMEL +343 227 E3 ד HEBREW LETTER DALET +344 228 E4 ה HEBREW LETTER HE +345 229 E5 ו HEBREW LETTER VAV +346 230 E6 ז HEBREW LETTER ZAYIN +347 231 E7 ח HEBREW LETTER HET +350 232 E8 ט HEBREW LETTER TET +351 233 E9 י HEBREW LETTER YOD +352 234 EA ך HEBREW LETTER FINAL KAF +353 235 EB כ HEBREW LETTER KAF +354 236 EC ל HEBREW LETTER LAMED +355 237 ED ם HEBREW LETTER FINAL MEM +356 238 EE מ HEBREW LETTER MEM +357 239 EF ן HEBREW LETTER FINAL NUN +360 240 F0 נ HEBREW LETTER NUN +361 241 F1 ס HEBREW LETTER SAMEKH +362 242 F2 ע HEBREW LETTER AYIN +363 243 F3 ף HEBREW LETTER FINAL PE +364 244 F4 פ HEBREW LETTER PE +365 245 F5 ץ HEBREW LETTER FINAL TSADI +366 246 F6 צ HEBREW LETTER TSADI +367 247 F7 ק HEBREW LETTER QOF +370 248 F8 ר HEBREW LETTER RESH +371 249 F9 ש HEBREW LETTER SHIN +372 250 FA ת HEBREW LETTER TAV +375 253 FD ‎ LEFT-TO-RIGHT MARK +376 254 FE ‏ RIGHT-TO-LEFT MARK +.TE +.SH NOTES +ISO/IEC\~8859-8 was also known as ISO-IR-138. +ISO/IEC\~8859-8 includes neither short vowels nor diacritical marks, +and Yiddish is not provided for. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859-9.7 b/man/man7/iso_8859-9.7 new file mode 100644 index 0000000..7d2f944 --- /dev/null +++ b/man/man7/iso_8859-9.7 @@ -0,0 +1,146 @@ +'\" t +.\" Copyright 2002 Dimitri Papadopoulos (dpo@club-internet.fr) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH ISO_8859-9 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iso_8859-9 \- ISO/IEC\~8859-9 character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-9 encodes the +characters used in Turkish. +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: +.TS +l l. +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) +.TE +.SS ISO/IEC\~8859-9 characters +The following table displays the characters in ISO/IEC\~8859-9 that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +240 160 A0   NO-BREAK SPACE +241 161 A1 ¡ INVERTED EXCLAMATION MARK +242 162 A2 ¢ CENT SIGN +243 163 A3 £ POUND SIGN +244 164 A4 ¤ CURRENCY SIGN +245 165 A5 ¥ YEN SIGN +246 166 A6 ¦ BROKEN BAR +247 167 A7 § SECTION SIGN +250 168 A8 ¨ DIAERESIS +251 169 A9 © COPYRIGHT SIGN +252 170 AA ª FEMININE ORDINAL INDICATOR +253 171 AB « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK +254 172 AC ¬ NOT SIGN +255 173 AD ­ SOFT HYPHEN +256 174 AE ® REGISTERED SIGN +257 175 AF ¯ MACRON +260 176 B0 ° DEGREE SIGN +261 177 B1 ± PLUS-MINUS SIGN +262 178 B2 ² SUPERSCRIPT TWO +263 179 B3 ³ SUPERSCRIPT THREE +264 180 B4 ´ ACUTE ACCENT +265 181 B5 µ MICRO SIGN +266 182 B6 ¶ PILCROW SIGN +267 183 B7 · MIDDLE DOT +270 184 B8 ¸ CEDILLA +271 185 B9 ¹ SUPERSCRIPT ONE +272 186 BA º MASCULINE ORDINAL INDICATOR +273 187 BB » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK +274 188 BC ¼ VULGAR FRACTION ONE QUARTER +275 189 BD ½ VULGAR FRACTION ONE HALF +276 190 BE ¾ VULGAR FRACTION THREE QUARTERS +277 191 BF ¿ INVERTED QUESTION MARK +300 192 C0 À LATIN CAPITAL LETTER A WITH GRAVE +301 193 C1 Á LATIN CAPITAL LETTER A WITH ACUTE +302 194 C2  LATIN CAPITAL LETTER A WITH CIRCUMFLEX +303 195 C3 à LATIN CAPITAL LETTER A WITH TILDE +304 196 C4 Ä LATIN CAPITAL LETTER A WITH DIAERESIS +305 197 C5 Å LATIN CAPITAL LETTER A WITH RING ABOVE +306 198 C6 Æ LATIN CAPITAL LETTER AE +307 199 C7 Ç LATIN CAPITAL LETTER C WITH CEDILLA +310 200 C8 È LATIN CAPITAL LETTER E WITH GRAVE +311 201 C9 É LATIN CAPITAL LETTER E WITH ACUTE +312 202 CA Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX +313 203 CB Ë LATIN CAPITAL LETTER E WITH DIAERESIS +314 204 CC Ì LATIN CAPITAL LETTER I WITH GRAVE +315 205 CD Í LATIN CAPITAL LETTER I WITH ACUTE +316 206 CE Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX +317 207 CF Ï LATIN CAPITAL LETTER I WITH DIAERESIS +320 208 D0 Ğ LATIN CAPITAL LETTER G WITH BREVE +321 209 D1 Ñ LATIN CAPITAL LETTER N WITH TILDE +322 210 D2 Ò LATIN CAPITAL LETTER O WITH GRAVE +323 211 D3 Ó LATIN CAPITAL LETTER O WITH ACUTE +324 212 D4 Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX +325 213 D5 Õ LATIN CAPITAL LETTER O WITH TILDE +326 214 D6 Ö LATIN CAPITAL LETTER O WITH DIAERESIS +327 215 D7 × MULTIPLICATION SIGN +330 216 D8 Ø LATIN CAPITAL LETTER O WITH STROKE +331 217 D9 Ù LATIN CAPITAL LETTER U WITH GRAVE +332 218 DA Ú LATIN CAPITAL LETTER U WITH ACUTE +333 219 DB Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX +334 220 DC Ü LATIN CAPITAL LETTER U WITH DIAERESIS +335 221 DD İ LATIN CAPITAL LETTER I WITH DOT ABOVE +336 222 DE Ş LATIN CAPITAL LETTER S WITH CEDILLA +337 223 DF ß LATIN SMALL LETTER SHARP S +340 224 E0 à LATIN SMALL LETTER A WITH GRAVE +341 225 E1 á LATIN SMALL LETTER A WITH ACUTE +342 226 E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX +343 227 E3 ã LATIN SMALL LETTER A WITH TILDE +344 228 E4 ä LATIN SMALL LETTER A WITH DIAERESIS +345 229 E5 å LATIN SMALL LETTER A WITH RING ABOVE +346 230 E6 æ LATIN SMALL LETTER AE +347 231 E7 ç LATIN SMALL LETTER C WITH CEDILLA +350 232 E8 è LATIN SMALL LETTER E WITH GRAVE +351 233 E9 é LATIN SMALL LETTER E WITH ACUTE +352 234 EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX +353 235 EB ë LATIN SMALL LETTER E WITH DIAERESIS +354 236 EC ì LATIN SMALL LETTER I WITH GRAVE +355 237 ED í LATIN SMALL LETTER I WITH ACUTE +356 238 EE î LATIN SMALL LETTER I WITH CIRCUMFLEX +357 239 EF ï LATIN SMALL LETTER I WITH DIAERESIS +360 240 F0 ğ LATIN SMALL LETTER G WITH BREVE +361 241 F1 ñ LATIN SMALL LETTER N WITH TILDE +362 242 F2 ò LATIN SMALL LETTER O WITH GRAVE +363 243 F3 ó LATIN SMALL LETTER O WITH ACUTE +364 244 F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX +365 245 F5 õ LATIN SMALL LETTER O WITH TILDE +366 246 F6 ö LATIN SMALL LETTER O WITH DIAERESIS +367 247 F7 ÷ DIVISION SIGN +370 248 F8 ø LATIN SMALL LETTER O WITH STROKE +371 249 F9 ù LATIN SMALL LETTER U WITH GRAVE +372 250 FA ú LATIN SMALL LETTER U WITH ACUTE +373 251 FB û LATIN SMALL LETTER U WITH CIRCUMFLEX +374 252 FC ü LATIN SMALL LETTER U WITH DIAERESIS +375 253 FD ı LATIN SMALL LETTER DOTLESS I +376 254 FE ş LATIN SMALL LETTER S WITH CEDILLA +377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS +.TE +.SH NOTES +ISO/IEC\~8859-9 is also known as Latin-5. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/iso_8859_1.7 b/man/man7/iso_8859_1.7 new file mode 100644 index 0000000..1969dfb --- /dev/null +++ b/man/man7/iso_8859_1.7 @@ -0,0 +1 @@ +.so man7/iso_8859-1.7 diff --git a/man/man7/iso_8859_10.7 b/man/man7/iso_8859_10.7 new file mode 100644 index 0000000..9b4658f --- /dev/null +++ b/man/man7/iso_8859_10.7 @@ -0,0 +1 @@ +.so man7/iso_8859-10.7 diff --git a/man/man7/iso_8859_11.7 b/man/man7/iso_8859_11.7 new file mode 100644 index 0000000..cbd4cfe --- /dev/null +++ b/man/man7/iso_8859_11.7 @@ -0,0 +1 @@ +.so man7/iso_8859-11.7 diff --git a/man/man7/iso_8859_13.7 b/man/man7/iso_8859_13.7 new file mode 100644 index 0000000..8ad2335 --- /dev/null +++ b/man/man7/iso_8859_13.7 @@ -0,0 +1 @@ +.so man7/iso_8859-13.7 diff --git a/man/man7/iso_8859_14.7 b/man/man7/iso_8859_14.7 new file mode 100644 index 0000000..4aa555d --- /dev/null +++ b/man/man7/iso_8859_14.7 @@ -0,0 +1 @@ +.so man7/iso_8859-14.7 diff --git a/man/man7/iso_8859_15.7 b/man/man7/iso_8859_15.7 new file mode 100644 index 0000000..a4095d7 --- /dev/null +++ b/man/man7/iso_8859_15.7 @@ -0,0 +1 @@ +.so man7/iso_8859-15.7 diff --git a/man/man7/iso_8859_16.7 b/man/man7/iso_8859_16.7 new file mode 100644 index 0000000..b9c8e91 --- /dev/null +++ b/man/man7/iso_8859_16.7 @@ -0,0 +1 @@ +.so man7/iso_8859-16.7 diff --git a/man/man7/iso_8859_2.7 b/man/man7/iso_8859_2.7 new file mode 100644 index 0000000..da36668 --- /dev/null +++ b/man/man7/iso_8859_2.7 @@ -0,0 +1 @@ +.so man7/iso_8859-2.7 diff --git a/man/man7/iso_8859_3.7 b/man/man7/iso_8859_3.7 new file mode 100644 index 0000000..75e42ce --- /dev/null +++ b/man/man7/iso_8859_3.7 @@ -0,0 +1 @@ +.so man7/iso_8859-3.7 diff --git a/man/man7/iso_8859_4.7 b/man/man7/iso_8859_4.7 new file mode 100644 index 0000000..15a829e --- /dev/null +++ b/man/man7/iso_8859_4.7 @@ -0,0 +1 @@ +.so man7/iso_8859-4.7 diff --git a/man/man7/iso_8859_5.7 b/man/man7/iso_8859_5.7 new file mode 100644 index 0000000..1f20320 --- /dev/null +++ b/man/man7/iso_8859_5.7 @@ -0,0 +1 @@ +.so man7/iso_8859-5.7 diff --git a/man/man7/iso_8859_6.7 b/man/man7/iso_8859_6.7 new file mode 100644 index 0000000..edcafdf --- /dev/null +++ b/man/man7/iso_8859_6.7 @@ -0,0 +1 @@ +.so man7/iso_8859-6.7 diff --git a/man/man7/iso_8859_7.7 b/man/man7/iso_8859_7.7 new file mode 100644 index 0000000..951384c --- /dev/null +++ b/man/man7/iso_8859_7.7 @@ -0,0 +1 @@ +.so man7/iso_8859-7.7 diff --git a/man/man7/iso_8859_8.7 b/man/man7/iso_8859_8.7 new file mode 100644 index 0000000..07cf216 --- /dev/null +++ b/man/man7/iso_8859_8.7 @@ -0,0 +1 @@ +.so man7/iso_8859-8.7 diff --git a/man/man7/iso_8859_9.7 b/man/man7/iso_8859_9.7 new file mode 100644 index 0000000..0fcc7d4 --- /dev/null +++ b/man/man7/iso_8859_9.7 @@ -0,0 +1 @@ +.so man7/iso_8859-9.7 diff --git a/man/man7/kernel_lockdown.7 b/man/man7/kernel_lockdown.7 new file mode 100644 index 0000000..735f8bb --- /dev/null +++ b/man/man7/kernel_lockdown.7 @@ -0,0 +1,109 @@ +.\" +.\" Copyright (C) 2017 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH kernel_lockdown 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +kernel_lockdown \- kernel image access prevention feature +.SH DESCRIPTION +The Kernel Lockdown feature is designed to prevent both direct and indirect +access to a running kernel image, attempting to protect against unauthorized +modification of the kernel image and to prevent access to security and +cryptographic data located in kernel memory, whilst still permitting driver +modules to be loaded. +.P +If a prohibited or restricted feature is accessed or used, the kernel will emit +a message that looks like: +.P +.in +4n +.EX +Lockdown: X: Y is restricted, see man kernel_lockdown.7 +.EE +.in +.P +where X indicates the process name and Y indicates what is restricted. +.P +On an EFI-enabled x86 or arm64 machine, lockdown will be automatically enabled +if the system boots in EFI Secure Boot mode. +.\" +.SS Coverage +When lockdown is in effect, a number of features are disabled or have their +use restricted. +This includes special device files and kernel services that allow +direct access of the kernel image: +.P +.RS +/dev/mem +.br +/dev/kmem +.br +/dev/kcore +.br +/dev/ioports +.br +BPF +.br +kprobes +.RE +.P +and the ability to directly configure and control devices, so as to prevent +the use of a device to access or modify a kernel image: +.IP \[bu] 3 +The use of module parameters that directly specify hardware parameters to +drivers through the kernel command line or when loading a module. +.IP \[bu] +The use of direct PCI BAR access. +.IP \[bu] +The use of the ioperm and iopl instructions on x86. +.IP \[bu] +The use of the KD*IO console ioctls. +.IP \[bu] +The use of the TIOCSSERIAL serial ioctl. +.IP \[bu] +The alteration of MSR registers on x86. +.IP \[bu] +The replacement of the PCMCIA CIS. +.IP \[bu] +The overriding of ACPI tables. +.IP \[bu] +The use of ACPI error injection. +.IP \[bu] +The specification of the ACPI RDSP address. +.IP \[bu] +The use of ACPI custom methods. +.P +Certain facilities are restricted: +.IP \[bu] 3 +Only validly signed modules may be loaded (waived if the module file being +loaded is vouched for by IMA appraisal). +.IP \[bu] +Only validly signed binaries may be kexec'd (waived if the binary image file +to be executed is vouched for by IMA appraisal). +.IP \[bu] +Unencrypted hibernation/suspend to swap are disallowed as the kernel image is +saved to a medium that can then be accessed. +.IP \[bu] +Use of debugfs is not permitted as this allows a whole range of actions +including direct configuration of, access to and driving of hardware. +.IP \[bu] +IMA requires the addition of the "secure_boot" rules to the policy, +whether or not they are specified on the command line, +for both the built-in and custom policies in secure boot lockdown mode. +.SH VERSIONS +The Kernel Lockdown feature was added in Linux 5.4. +.SH NOTES +The Kernel Lockdown feature is enabled by CONFIG_SECURITY_LOCKDOWN_LSM. +The +.I lsm=lsm1,...,lsmN +command line parameter controls the sequence of the initialization of +Linux Security Modules. +It must contain the string +.I lockdown +to enable the Kernel Lockdown feature. +If the command line parameter is not specified, +the initialization falls back to the value of the deprecated +.I security= +command line parameter and further to the value of CONFIG_LSM. +.\" commit 000d388ed3bbed745f366ce71b2bb7c2ee70f449 diff --git a/man/man7/keyrings.7 b/man/man7/keyrings.7 new file mode 100644 index 0000000..492bfca --- /dev/null +++ b/man/man7/keyrings.7 @@ -0,0 +1,901 @@ +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" and Copyright (C) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH keyrings 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +keyrings \- in-kernel key management and retention facility +.SH DESCRIPTION +The Linux key-management facility +is primarily a way for various kernel components +to retain or cache security data, +authentication keys, encryption keys, and other data in the kernel. +.P +System call interfaces are provided so that user-space programs can manage +those objects and also use the facility for their own purposes; see +.BR add_key (2), +.BR request_key (2), +and +.BR keyctl (2). +.P +A library and some user-space utilities are provided to allow access to the +facility. +See +.BR keyctl (1), +.BR keyctl (3), +and +.BR keyutils (7) +for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Keys +A key has the following attributes: +.TP +Serial number (ID) +This is a unique integer handle by which a key is referred to in system calls. +The serial number is sometimes synonymously referred as the key ID. +Programmatically, key serial numbers are represented using the type +.IR key_serial_t . +.TP +Type +A key's type defines what sort of data can be held in the key, +how the proposed content of the key will be parsed, +and how the payload will be used. +.IP +There are a number of general-purpose types available, plus some specialist +types defined by specific kernel components. +.TP +Description (name) +The key description is a printable string that is used as the search term +for the key (in conjunction with the key type) as well as a display name. +During searches, the description may be partially matched or exactly matched. +.TP +Payload (data) +The payload is the actual content of a key. +This is usually set when a key is created, +but it is possible for the kernel to upcall to user space to finish the +instantiation of a key if that key wasn't already known to the kernel +when it was requested. +For further details, see +.BR request_key (2). +.IP +A key's payload can be read and updated if the key type supports it and if +suitable permission is granted to the caller. +.TP +Access rights +Much as files do, +each key has an owning user ID, an owning group ID, and a security label. +Each key also has a set of permissions, +though there are more than for a normal UNIX file, +and there is an additional category\[em]possessor\[em]beyond the usual user, +group, and other (see +.IR Possession , +below). +.IP +Note that keys are quota controlled, since they require unswappable kernel +memory. +The owning user ID specifies whose quota is to be debited. +.TP +Expiration time +Each key can have an expiration time set. +When that time is reached, +the key is marked as being expired and accesses to it fail with the error +.BR EKEYEXPIRED . +If not deleted, updated, or replaced, then, after a set amount of time, +an expired key is automatically removed (garbage collected) +along with all links to it, +and attempts to access the key fail with the error +.BR ENOKEY . +.TP +Reference count +Each key has a reference count. +Keys are referenced by keyrings, by currently active users, +and by a process's credentials. +When the reference count reaches zero, +the key is scheduled for garbage collection. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Key types +The kernel provides several basic types of key: +.TP +.I \[dq]keyring\[dq] +.\" Note that keyrings use different fields in struct key in order to store +.\" their data - index_key instead of type/description and name_link/keys +.\" instead of payload. +Keyrings are special keys which store a set of links +to other keys (including other keyrings), +analogous to a directory holding links to files. +The main purpose of a keyring is to prevent other keys from +being garbage collected because nothing refers to them. +.IP +Keyrings with descriptions (names) +that begin with a period (\[aq].\[aq]) are reserved to the implementation. +.TP +.I \[dq]user\[dq] +This is a general-purpose key type. +The key is kept entirely within kernel memory. +The payload may be read and updated by user-space applications. +.IP +The payload for keys of this type is a blob of arbitrary data +of up to 32,767 bytes. +.IP +The description may be any valid string, though it is preferred that it +start with a colon-delimited prefix representing the service +to which the key is of interest +(for instance +.IR \[dq]afs:mykey\[dq] ). +.TP +.IR \[dq]logon\[dq] " (since Linux 3.3)" +.\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b +This key type is essentially the same as +.IR \[dq]user\[dq] , +but it does not provide reading (i.e., the +.BR keyctl (2) +.B KEYCTL_READ +operation), +meaning that the key payload is never visible from user space. +This is suitable for storing username-password pairs +that should not be readable from user space. +.IP +The description of a +.I \[dq]logon\[dq] +key +.I must +start with a non-empty colon-delimited prefix whose purpose +is to identify the service to which the key belongs. +(Note that this differs from keys of the +.I \[dq]user\[dq] +type, where the inclusion of a prefix is recommended but is not enforced.) +.TP +.IR \[dq]big_key\[dq] " (since Linux 3.13)" +.\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 +This key type is similar to the +.I \[dq]user\[dq] +key type, but it may hold a payload of up to 1\ MiB in size. +This key type is useful for purposes such as holding Kerberos ticket caches. +.IP +The payload data may be stored in a tmpfs filesystem, +rather than in kernel memory, +if the data size exceeds the overhead of storing the data in the filesystem. +(Storing the data in a filesystem requires filesystem structures +to be allocated in the kernel. +The size of these structures determines the size threshold +above which the tmpfs storage method is used.) +Since Linux 4.8, +.\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef +the payload data is encrypted when stored in tmpfs, +thereby preventing it from being written unencrypted into swap space. +.P +There are more specialized key types available also, +but they aren't discussed here +because they aren't intended for normal user-space use. +.P +Key type names +that begin with a period (\[aq].\[aq]) are reserved to the implementation. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Keyrings +As previously mentioned, keyrings are a special type of key that contain +links to other keys (which may include other keyrings). +Keys may be linked to by multiple keyrings. +Keyrings may be considered as analogous to UNIX directories +where each directory contains a set of hard links to files. +.P +Various operations (system calls) may be applied only to keyrings: +.TP +Adding +A key may be added to a keyring by system calls that create keys. +This prevents the new key from being immediately deleted +when the system call releases its last reference to the key. +.TP +Linking +A link may be added to a keyring pointing to a key that is already known, +provided this does not create a self-referential cycle. +.TP +Unlinking +A link may be removed from a keyring. +When the last link to a key is removed, +that key will be scheduled for deletion by the garbage collector. +.TP +Clearing +All the links may be removed from a keyring. +.TP +Searching +A keyring may be considered the root of a tree or subtree in which keyrings +form the branches and non-keyrings the leaves. +This tree may be searched for a key matching +a particular type and description. +.P +See +.BR keyctl_clear (3), +.BR keyctl_link (3), +.BR keyctl_search (3), +and +.BR keyctl_unlink (3) +for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Anchoring keys +To prevent a key from being garbage collected, +it must be anchored to keep its reference count elevated +when it is not in active use by the kernel. +.P +Keyrings are used to anchor other keys: +each link is a reference on a key. +Note that keyrings themselves are just keys and +are also subject to the same anchoring requirement to prevent +them being garbage collected. +.P +The kernel makes available a number of anchor keyrings. +Note that some of these keyrings will be created only when first accessed. +.TP +Process keyrings +Process credentials themselves reference keyrings with specific semantics. +These keyrings are pinned as long as the set of credentials exists, +which is usually as long as the process exists. +.IP +There are three keyrings with different inheritance/sharing rules: +the +.BR session\-keyring (7) +(inherited and shared by all child processes), +the +.BR process\-keyring (7) +(shared by all threads in a process) and +the +.BR thread\-keyring (7) +(specific to a particular thread). +.IP +As an alternative to using the actual keyring IDs, +in calls to +.BR add_key (2), +.BR keyctl (2), +and +.BR request_key (2), +the special keyring values +.BR KEY_SPEC_SESSION_KEYRING , +.BR KEY_SPEC_PROCESS_KEYRING , +and +.B KEY_SPEC_THREAD_KEYRING +can be used to refer to the caller's own instances of these keyrings. +.TP +User keyrings +Each UID known to the kernel has a record that contains two keyrings: the +.BR user\-keyring (7) +and the +.BR user\-session\-keyring (7). +These exist for as long as the UID record in the kernel exists. +.IP +As an alternative to using the actual keyring IDs, +in calls to +.BR add_key (2), +.BR keyctl (2), +and +.BR request_key (2), +the special keyring values +.B KEY_SPEC_USER_KEYRING +and +.B KEY_SPEC_USER_SESSION_KEYRING +can be used to refer to the caller's own instances of these keyrings. +.IP +A link to the user keyring is placed in a new session keyring by +.BR pam_keyinit (8) +when a new login session is initiated. +.TP +Persistent keyrings +There is a +.BR persistent\-keyring (7) +available to each UID known to the system. +It may persist beyond the life of the UID record previously mentioned, +but has an expiration time set such that it is automatically cleaned up +after a set time. +The persistent keyring permits, for example, +.BR cron (8) +scripts to use credentials that are left in the persistent keyring after +the user logs out. +.IP +Note that the expiration time of the persistent keyring +is reset every time the persistent key is requested. +.TP +Special keyrings +There are special keyrings owned by the kernel that can anchor keys +for special purposes. +An example of this is the \fIsystem keyring\fR used for holding +encryption keys for module signature verification. +.IP +These special keyrings are usually closed to direct alteration +by user space. +.P +An originally planned "group keyring", +for storing keys associated with each GID known to the kernel, +is not so far implemented, is unlikely to be implemented. +Nevertheless, the constant +.B KEY_SPEC_GROUP_KEYRING +has been defined for this keyring. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Possession +The concept of possession is important to understanding the keyrings +security model. +Whether a thread possesses a key is determined by the following rules: +.IP (1) 5 +Any key or keyring that does not grant +.I search +permission to the caller is ignored in all the following rules. +.IP (2) +A thread possesses its +.BR session\-keyring (7), +.BR process\-keyring (7), +and +.BR thread\-keyring (7) +directly because those keyrings are referred to by its credentials. +.IP (3) +If a keyring is possessed, then any key it links to is also possessed. +.IP (4) +If any key a keyring links to is itself a keyring, then rule (3) applies +recursively. +.IP (5) +If a process is upcalled from the kernel to instantiate a key (see +.BR request_key (2)), +then it also possesses the requester's keyrings as in +rule (1) as if it were the requester. +.P +Note that possession is not a fundamental property of a key, +but must rather be calculated each time the key is needed. +.P +Possession is designed to allow set-user-ID programs run from, say +a user's shell to access the user's keys. +Granting permissions to the key possessor while denying them +to the key owner and group allows the prevention of access to keys +on the basis of UID and GID matches. +.P +When it creates the session keyring, +.BR pam_keyinit (8) +adds a link to the +.BR user\-keyring (7), +thus making the user keyring and anything it contains possessed by default. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Access rights +Each key has the following security-related attributes: +.IP \[bu] 3 +The owning user ID +.IP \[bu] +The ID of a group that is permitted to access the key +.IP \[bu] +A security label +.IP \[bu] +A permissions mask +.P +The permissions mask contains four sets of rights. +The first three sets are mutually exclusive. +One and only one will be in force for a particular access check. +In order of descending priority, these three sets are: +.TP +.I user +The set specifies the rights granted +if the key's user ID matches the caller's filesystem user ID. +.TP +.I group +The set specifies the rights granted +if the user ID didn't match and the key's group ID matches the caller's +filesystem GID or one of the caller's supplementary group IDs. +.TP +.I other +The set specifies the rights granted +if neither the key's user ID nor group ID matched. +.P +The fourth set of rights is: +.TP +.I possessor +The set specifies the rights granted +if a key is determined to be possessed by the caller. +.P +The complete set of rights for a key is the union of whichever +of the first three sets is applicable plus the fourth set +if the key is possessed. +.P +The set of rights that may be granted in each of the four masks +is as follows: +.TP +.I view +The attributes of the key may be read. +This includes the type, +description, and access rights (excluding the security label). +.TP +.I read +For a key: the payload of the key may be read. +For a keyring: the list of serial numbers (keys) to +which the keyring has links may be read. +.TP +.I write +The payload of the key may be updated and the key may be revoked. +For a keyring, links may be added to or removed from the keyring, +and the keyring may be cleared completely (all links are removed), +.TP +.I search +For a key (or a keyring): the key may be found by a search. +For a keyring: keys and keyrings that are linked to by the +keyring may be searched. +.TP +.I link +Links may be created from keyrings to the key. +The initial link to a key that is established when the key is created +doesn't require this permission. +.TP +.I setattr +The ownership details and security label of the key may be changed, +the key's expiration time may be set, and the key may be revoked. +.P +In addition to access rights, any active Linux Security Module (LSM) may +prevent access to a key if its policy so dictates. +A key may be given a +security label or other attribute by the LSM; +this label is retrievable via +.BR keyctl_get_security (3). +.P +See +.BR keyctl_chown (3), +.BR keyctl_describe (3), +.BR keyctl_get_security (3), +.BR keyctl_setperm (3), +and +.BR selinux (8) +for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Searching for keys +One of the key features of the Linux key-management facility +is the ability to find a key that a process is retaining. +The +.BR request_key (2) +system call is the primary point of +access for user-space applications to find a key. +(Internally, the kernel has something similar available +for use by internal components that make use of keys.) +.P +The search algorithm works as follows: +.IP (1) 5 +The process keyrings are searched in the following order: the +.BR thread\-keyring (7) +if it exists, the +.BR process\-keyring (7) +if it exists, and then either the +.BR session\-keyring (7) +if it exists or the +.BR user\-session\-keyring (7) +if that exists. +.IP (2) +If the caller was a process that was invoked by the +.BR request_key (2) +upcall mechanism, then the keyrings of the original caller of +.BR request_key (2) +will be searched as well. +.IP (3) +The search of a keyring tree is in breadth-first order: +each keyring is searched first for a match, +then the keyrings referred to by that keyring are searched. +.IP (4) +If a matching key is found that is valid, +then the search terminates and that key is returned. +.IP (5) +If a matching key is found that has an error state attached, +that error state is noted and the search continues. +.IP (6) +If no valid matching key is found, +then the first noted error state is returned; otherwise, an +.B ENOKEY +error is returned. +.P +It is also possible to search a specific keyring, in which case only steps +(3) to (6) apply. +.P +See +.BR request_key (2) +and +.BR keyctl_search (3) +for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS On-demand key creation +If a key cannot be found, +.BR request_key (2) +will, if given a +.I callout_info +argument, create a new key and then upcall to user space to +instantiate the key. +This allows keys to be created on an as-needed basis. +.P +Typically, +this will involve the kernel creating a new process that executes the +.BR request\-key (8) +program, which will then execute the appropriate handler based on its +configuration. +.P +The handler is passed a special authorization key that allows it +and only it to instantiate the new key. +This is also used to permit searches performed by the +handler program to also search the requester's keyrings. +.P +See +.BR request_key (2), +.BR keyctl_assume_authority (3), +.BR keyctl_instantiate (3), +.BR keyctl_negate (3), +.BR keyctl_reject (3), +.BR request\-key (8), +and +.BR request\-key.conf (5) +for more information. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS /proc files +The kernel provides various +.I /proc +files that expose information about keys or define limits on key usage. +.TP +.IR /proc/keys " (since Linux 2.6.10)" +This file exposes a list of the keys for which the reading thread has +.I view +permission, providing various information about each key. +The thread need not possess the key for it to be visible in this file. +.\" David Howells, Dec 2016 linux-man@: +.\" This [The thread need not possess the key for it to be visible in +.\" this file.] is correct. See proc_keys_show() in security/keys/proc.c: +.\" +.\" rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW); +.\" if (rc < 0) +.\" return 0; +.\" +.\"Possibly it shouldn't be, but for now it is. +.\" +.IP +The only keys included in the list are those that grant +.I view +permission to the reading process +(regardless of whether or not it possesses them). +LSM security checks are still performed, +and may filter out further keys that the process is not authorized to view. +.IP +An example of the data that one might see in this file +(with the columns numbered for easy reference below) +is the following: +.IP +.EX + (1) (2) (3)(4) (5) (6) (7) (8) (9) +009a2028 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12 +1806c4ba I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 keyring _pid: 2 +25d3a08f I\-\-Q\-\-\- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1 +28576bd8 I\-\-Q\-\-\- 3 perm 3f010000 1000 1000 keyring _krb: 1 +2c546d21 I\-\-Q\-\-\- 190 perm 3f030000 1000 1000 keyring _ses: 2 +30a4e0be I\-\-\-\-\-\- 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1 +32100fab I\-\-Q\-\-\- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2 +32a387ea I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 keyring _pid: 2 +3ce56aea I\-\-Q\-\-\- 5 perm 3f030000 1000 1000 keyring _ses: 1 +.EE +.IP +The fields shown in each line of this file are as follows: +.RS +.TP +ID (1) +The ID (serial number) of the key, expressed in hexadecimal. +.TP +Flags (2) +A set of flags describing the state of the key: +.RS +.TP +I +.\" KEY_FLAG_INSTANTIATED +The key has been instantiated. +.TP +R +.\" KEY_FLAG_REVOKED +The key has been revoked. +.TP +D +.\" KEY_FLAG_DEAD +The key is dead (i.e., the key type has been unregistered). +.\" unregister_key_type() in the kernel source +(A key may be briefly in this state during garbage collection.) +.TP +Q +.\" KEY_FLAG_IN_QUOTA +The key contributes to the user's quota. +.TP +U +.\" KEY_FLAG_USER_CONSTRUCT +The key is under construction via a callback to user space; +see +.BR request\-key (2). +.TP +N +.\" KEY_FLAG_NEGATIVE +The key is negatively instantiated. +.TP +i +.\" KEY_FLAG_INVALIDATED +The key has been invalidated. +.RE +.TP +Usage (3) +This is a count of the number of kernel credential +structures that are pinning the key +(approximately: the number of threads and open file references +that refer to this key). +.TP +Timeout (4) +The amount of time until the key will expire, +expressed in human-readable form (weeks, days, hours, minutes, and seconds). +The string +.I perm +here means that the key is permanent (no timeout). +The string +.I expd +means that the key has already expired, +but has not yet been garbage collected. +.TP +Permissions (5) +The key permissions, expressed as four hexadecimal bytes containing, +from left to right, the possessor, user, group, and other permissions. +Within each byte, the permission bits are as follows: +.IP +.PD 0 +.RS 12 +.TP +0x01 +.I view +.TP +0x02 +.I read +.TP +0x04 +.I write +.TP +0x08 +.I search +.TP +0x10 +.I link +.TP +0x20 +.I setattr +.RE +.PD +.TP +UID (6) +The user ID of the key owner. +.TP +GID (7) +The group ID of the key. +The value \-1 here means that the key has no group ID; +this can occur in certain circumstances for keys created by the kernel. +.TP +Type (8) +The key type (user, keyring, etc.) +.TP +Description (9) +The key description (name). +This field contains descriptive information about the key. +For most key types, it has the form +.IP +.in +4n +.EX +name[: extra\-info] +.EE +.in +.IP +The +.I name +subfield is the key's description (name). +The optional +.I extra\-info +field provides some further information about the key. +The information that appears here depends on the key type, as follows: +.RS +.TP +.IR \[dq]user\[dq] " and " \[dq]logon\[dq] +The size in bytes of the key payload (expressed in decimal). +.TP +.I \[dq]keyring\[dq] +The number of keys linked to the keyring, +or the string +.I empty +if there are no keys linked to the keyring. +.TP +.I \[dq]big_key\[dq] +The payload size in bytes, followed either by the string +.IR [file] , +if the key payload exceeds the threshold that means that the +payload is stored in a (swappable) +.BR tmpfs (5) +filesystem, +or otherwise the string +.IR [buff] , +indicating that the key is small enough to reside in kernel memory. +.RE +.IP +For the +.I \[dq].request_key_auth\[dq] +key type +(authorization key; see +.BR request_key (2)), +the description field has the form shown in the following example: +.IP +.in +4n +.EX +key:c9a9b19 pid:28880 ci:10 +.EE +.in +.IP +The three subfields are as follows: +.RS +.TP +.I key +The hexadecimal ID of the key being instantiated in the requesting program. +.TP +.I pid +The PID of the requesting program. +.TP +.I ci +The length of the callout data with which the requested key should +be instantiated +(i.e., the length of the payload associated with the authorization key). +.RE +.RE +.TP +.IR /proc/key\-users " (since Linux 2.6.10)" +This file lists various information for each user ID that +has at least one key on the system. +An example of the data that one might see in this file is the following: +.IP +.in +4n +.EX + 0: 10 9/9 2/1000000 22/25000000 + 42: 9 9/9 8/200 106/20000 +1000: 11 11/11 10/200 271/20000 +.EE +.in +.IP +The fields shown in each line are as follows: +.RS +.TP +.I uid +The user ID. +.TP +.I usage +This is a kernel-internal usage count for the kernel structure +used to record key users. +.TP +.IR nkeys / nikeys +The total number of keys owned by the user, +and the number of those keys that have been instantiated. +.TP +.IR qnkeys / maxkeys +The number of keys owned by the user, +and the maximum number of keys that the user may own. +.TP +.IR qnbytes / maxbytes +The number of bytes consumed in payloads of the keys owned by this user, +and the upper limit on the number of bytes in key payloads for that user. +.RE +.TP +.IR /proc/sys/kernel/keys/gc_delay " (since Linux 2.6.32)" +.\" commit 5d135440faf7db8d566de0c6fab36b16cf9cfc3b +The value in this file specifies the interval, in seconds, +after which revoked and expired keys will be garbage collected. +The purpose of having such an interval is so that there is a window +of time where user space can see an error (respectively +.B EKEYREVOKED +and +.BR EKEYEXPIRED ) +that indicates what happened to the key. +.IP +The default value in this file is 300 (i.e., 5 minutes). +.TP +.IR /proc/sys/kernel/keys/persistent_keyring_expiry " (since Linux 3.13)" +.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e +This file defines an interval, in seconds, +to which the persistent keyring's expiration timer is reset +each time the keyring is accessed (via +.BR keyctl_get_persistent (3) +or the +.BR keyctl (2) +.B KEYCTL_GET_PERSISTENT +operation.) +.IP +The default value in this file is 259200 (i.e., 3 days). +.P +The following files (which are writable by privileged processes) +are used to enforce quotas on the number of keys +and number of bytes of data that can be stored in key payloads: +.TP +.IR /proc/sys/kernel/keys/maxbytes " (since Linux 2.6.26)" +.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 +.\" Previously: KEYQUOTA_MAX_BYTES 10000 +This is the maximum number of bytes of data that a nonroot user +can hold in the payloads of the keys owned by the user. +.IP +The default value in this file is 20,000. +.TP +.IR /proc/sys/kernel/keys/maxkeys " (since Linux 2.6.26)" +.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 +.\" Previously: KEYQUOTA_MAX_KEYS 100 +This is the maximum number of keys that a nonroot user may own. +.IP +The default value in this file is 200. +.TP +.IR /proc/sys/kernel/keys/root_maxbytes " (since Linux 2.6.26)" +This is the maximum number of bytes of data that the root user +(UID 0 in the root user namespace) +can hold in the payloads of the keys owned by root. +.IP +.\"738c5d190f6540539a04baf36ce21d46b5da04bd +The default value in this file is 25,000,000 (20,000 before Linux 3.17). +.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 +.TP +.IR /proc/sys/kernel/keys/root_maxkeys " (since Linux 2.6.26)" +.\" commit 0b77f5bfb45c13e1e5142374f9d6ca75292252a4 +This is the maximum number of keys that the root user +(UID 0 in the root user namespace) +may own. +.IP +.\"738c5d190f6540539a04baf36ce21d46b5da04bd +The default value in this file is 1,000,000 (200 before Linux 3.17). +.P +With respect to keyrings, +note that each link in a keyring consumes 4 bytes of the keyring payload. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Users +The Linux key-management facility has a number of users and usages, +but is not limited to those that already exist. +.P +In-kernel users of this facility include: +.TP +Network filesystems - DNS +The kernel uses the upcall mechanism provided by the keys to upcall to +user space to do DNS lookups and then to cache the results. +.TP +AF_RXRPC and kAFS - Authentication +The AF_RXRPC network protocol and the in-kernel AFS filesystem +use keys to store the ticket needed to do secured or encrypted traffic. +These are then looked up by +network operations on AF_RXRPC and filesystem operations on kAFS. +.TP +NFS - User ID mapping +The NFS filesystem uses keys to store mappings of +foreign user IDs to local user IDs. +.TP +CIFS - Password +The CIFS filesystem uses keys to store passwords for accessing remote shares. +.TP +Module verification +The kernel build process can be made to cryptographically sign modules. +That signature is then checked when a module is loaded. +.P +User-space users of this facility include: +.TP +Kerberos key storage +The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication +tokens which can be made to be automatically cleaned up a set time after +the user last uses them, +but until then permits them to hang around after the user +has logged out so that +.BR cron (8) +scripts can use them. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyutils (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7), +.BR pam_keyinit (8), +.BR request\-key (8) +.P +The kernel source files +.I Documentation/crypto/asymmetric\-keys.txt +and under +.I Documentation/security/keys +(or, before Linux 4.13, in the file +.IR Documentation/security/keys.txt ). diff --git a/man/man7/koi8-r.7 b/man/man7/koi8-r.7 new file mode 100644 index 0000000..d563cfa --- /dev/null +++ b/man/man7/koi8-r.7 @@ -0,0 +1,169 @@ +'\" t +.\" Copyright 2001 Alexey Mahotkin +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH KOI8-R 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +koi8-r \- Russian character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +RFC\ 1489 defines an 8-bit character set, KOI8-R. +KOI8-R encodes the +characters used in Russian. +.SS KOI8-R characters +The following table displays the characters in KOI8-R that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +200 128 80 ─ BOX DRAWINGS LIGHT HORIZONTAL +201 129 81 │ BOX DRAWINGS LIGHT VERTICAL +202 130 82 ┌ BOX DRAWINGS LIGHT DOWN AND RIGHT +203 131 83 ┐ BOX DRAWINGS LIGHT DOWN AND LEFT +204 132 84 └ BOX DRAWINGS LIGHT UP AND RIGHT +205 133 85 ┘ BOX DRAWINGS LIGHT UP AND LEFT +206 134 86 ├ BOX DRAWINGS LIGHT VERTICAL AND RIGHT +207 135 87 ┤ BOX DRAWINGS LIGHT VERTICAL AND LEFT +210 136 88 ┬ BOX DRAWINGS LIGHT DOWN AND HORIZONTAL +211 137 89 ┴ BOX DRAWINGS LIGHT UP AND HORIZONTAL +212 138 8A ┼ BOX DRAWINGS LIGHT VERTICAL AND HORIZONTAL +213 139 8B ▀ UPPER HALF BLOCK +214 140 8C ▄ LOWER HALF BLOCK +215 141 8D █ FULL BLOCK +216 142 8E ▌ LEFT HALF BLOCK +217 143 8F ▐ RIGHT HALF BLOCK +220 144 90 ░ LIGHT SHADE +221 145 91 ▒ MEDIUM SHADE +222 146 92 ▓ DARK SHADE +223 147 93 ⌠ TOP HALF INTEGRAL +224 148 94 ■ BLACK SQUARE +225 149 95 ∙ BULLET OPERATOR +226 150 96 √ SQUARE ROOT +227 151 97 ≈ ALMOST EQUAL TO +230 152 98 ≤ LESS-THAN OR EQUAL TO +231 153 99 ≥ GREATER-THAN OR EQUAL TO +232 154 9A   NO-BREAK SPACE +233 155 9B ⌡ BOTTOM HALF INTEGRAL +234 156 9C ° DEGREE SIGN +235 157 9D ² SUPERSCRIPT TWO +236 158 9E · MIDDLE DOT +237 159 9F ÷ DIVISION SIGN +240 160 A0 ═ BOX DRAWINGS DOUBLE HORIZONTAL +241 161 A1 ║ BOX DRAWINGS DOUBLE VERTICAL +242 162 A2 ╒ BOX DRAWINGS DOWN SINGLE AND RIGHT DOUBLE +243 163 A3 ё CYRILLIC SMALL LETTER IO +244 164 A4 ╓ BOX DRAWINGS DOWN DOUBLE AND RIGHT SINGLE +245 165 A5 ╔ BOX DRAWINGS DOUBLE DOWN AND RIGHT +246 166 A6 ╕ BOX DRAWINGS DOWN SINGLE AND LEFT DOUBLE +247 167 A7 ╖ BOX DRAWINGS DOWN DOUBLE AND LEFT SINGLE +250 168 A8 ╗ BOX DRAWINGS DOUBLE DOWN AND LEFT +251 169 A9 ╘ BOX DRAWINGS UP SINGLE AND RIGHT DOUBLE +252 170 AA ╙ BOX DRAWINGS UP DOUBLE AND RIGHT SINGLE +253 171 AB ╚ BOX DRAWINGS DOUBLE UP AND RIGHT +254 172 AC ╛ BOX DRAWINGS UP SINGLE AND LEFT DOUBLE +255 173 AD ╜ BOX DRAWINGS UP DOUBLE AND LEFT SINGLE +256 174 AE ╝ BOX DRAWINGS DOUBLE UP AND LEFT +257 175 AF ╞ BOX DRAWINGS VERTICAL SINGLE AND RIGHT DOUBLE +260 176 B0 ╟ BOX DRAWINGS VERTICAL DOUBLE AND RIGHT SINGLE +261 177 B1 ╠ BOX DRAWINGS DOUBLE VERTICAL AND RIGHT +262 178 B2 ╡ BOX DRAWINGS VERTICAL SINGLE AND LEFT DOUBLE +263 179 B3 Ё CYRILLIC CAPITAL LETTER IO +264 180 B4 ╢ BOX DRAWINGS VERTICAL DOUBLE AND LEFT SINGLE +265 181 B5 ╣ BOX DRAWINGS DOUBLE VERTICAL AND LEFT +266 182 B6 ╤ BOX DRAWINGS DOWN SINGLE AND HORIZONTAL DOUBLE +267 183 B7 ╥ BOX DRAWINGS DOWN DOUBLE AND HORIZONTAL SINGLE +270 184 B8 ╦ BOX DRAWINGS DOUBLE DOWN AND HORIZONTAL +271 185 B9 ╧ BOX DRAWINGS UP SINGLE AND HORIZONTAL DOUBLE +272 186 BA ╨ BOX DRAWINGS UP DOUBLE AND HORIZONTAL SINGLE +273 187 BB ╩ BOX DRAWINGS DOUBLE UP AND HORIZONTAL +274 188 BC ╪ T{ +BOX DRAWINGS VERTICAL SINGLE +.br +AND HORIZONTAL DOUBLE +T} +275 189 BD ╫ T{ +BOX DRAWINGS VERTICAL DOUBLE +.br +AND HORIZONTAL SINGLE +T} +276 190 BE ╬ BOX DRAWINGS DOUBLE VERTICAL AND HORIZONTAL +277 191 BF © COPYRIGHT SIGN +300 192 C0 ю CYRILLIC SMALL LETTER YU +301 193 C1 а CYRILLIC SMALL LETTER A +302 194 C2 б CYRILLIC SMALL LETTER BE +303 195 C3 ц CYRILLIC SMALL LETTER TSE +304 196 C4 д CYRILLIC SMALL LETTER DE +305 197 C5 е CYRILLIC SMALL LETTER IE +306 198 C6 ф CYRILLIC SMALL LETTER EF +307 199 C7 г CYRILLIC SMALL LETTER GHE +310 200 C8 х CYRILLIC SMALL LETTER HA +311 201 C9 и CYRILLIC SMALL LETTER I +312 202 CA й CYRILLIC SMALL LETTER SHORT I +313 203 CB к CYRILLIC SMALL LETTER KA +314 204 CC л CYRILLIC SMALL LETTER EL +315 205 CD м CYRILLIC SMALL LETTER EM +316 206 CE н CYRILLIC SMALL LETTER EN +317 207 CF о CYRILLIC SMALL LETTER O +320 208 D0 п CYRILLIC SMALL LETTER PE +321 209 D1 я CYRILLIC SMALL LETTER YA +322 210 D2 р CYRILLIC SMALL LETTER ER +323 211 D3 с CYRILLIC SMALL LETTER ES +324 212 D4 т CYRILLIC SMALL LETTER TE +325 213 D5 у CYRILLIC SMALL LETTER U +326 214 D6 ж CYRILLIC SMALL LETTER ZHE +327 215 D7 в CYRILLIC SMALL LETTER VE +330 216 D8 ь CYRILLIC SMALL LETTER SOFT SIGN +331 217 D9 ы CYRILLIC SMALL LETTER YERU +332 218 DA з CYRILLIC SMALL LETTER ZE +333 219 DB ш CYRILLIC SMALL LETTER SHA +334 220 DC э CYRILLIC SMALL LETTER E +335 221 DD щ CYRILLIC SMALL LETTER SHCHA +336 222 DE ч CYRILLIC SMALL LETTER CHE +337 223 DF ъ CYRILLIC SMALL LETTER HARD SIGN +340 224 E0 Ю CYRILLIC CAPITAL LETTER YU +341 225 E1 А CYRILLIC CAPITAL LETTER A +342 226 E2 Б CYRILLIC CAPITAL LETTER BE +343 227 E3 Ц CYRILLIC CAPITAL LETTER TSE +344 228 E4 Д CYRILLIC CAPITAL LETTER DE +345 229 E5 Е CYRILLIC CAPITAL LETTER IE +346 230 E6 Ф CYRILLIC CAPITAL LETTER EF +347 231 E7 Г CYRILLIC CAPITAL LETTER GHE +350 232 E8 Х CYRILLIC CAPITAL LETTER HA +351 233 E9 И CYRILLIC CAPITAL LETTER I +352 234 EA Й CYRILLIC CAPITAL LETTER SHORT I +353 235 EB К CYRILLIC CAPITAL LETTER KA +354 236 EC Л CYRILLIC CAPITAL LETTER EL +355 237 ED М CYRILLIC CAPITAL LETTER EM +356 238 EE Н CYRILLIC CAPITAL LETTER EN +357 239 EF О CYRILLIC CAPITAL LETTER O +360 240 F0 П CYRILLIC CAPITAL LETTER PE +361 241 F1 Я CYRILLIC CAPITAL LETTER YA +362 242 F2 Р CYRILLIC CAPITAL LETTER ER +363 243 F3 С CYRILLIC CAPITAL LETTER ES +364 244 F4 Т CYRILLIC CAPITAL LETTER TE +365 245 F5 У CYRILLIC CAPITAL LETTER U +366 246 F6 Ж CYRILLIC CAPITAL LETTER ZHE +367 247 F7 В CYRILLIC CAPITAL LETTER VE +370 248 F8 Ь CYRILLIC CAPITAL LETTER SOFT SIGN +371 249 F9 Ы CYRILLIC CAPITAL LETTER YERU +372 250 FA З CYRILLIC CAPITAL LETTER ZE +373 251 FB Ш CYRILLIC CAPITAL LETTER SHA +374 252 FC Э CYRILLIC CAPITAL LETTER E +375 253 FD Щ CYRILLIC CAPITAL LETTER SHCHA +376 254 FE Ч CYRILLIC CAPITAL LETTER CHE +377 255 FF Ъ CYRILLIC CAPITAL LETTER HARD SIGN +.TE +.SH NOTES +The differences with KOI8-U are in the hex positions +A4, A6, A7, AD, B4, B6, B7, and BD. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1251 (7), +.BR iso_8859\-5 (7), +.BR koi8\-u (7), +.BR utf\-8 (7) diff --git a/man/man7/koi8-u.7 b/man/man7/koi8-u.7 new file mode 100644 index 0000000..52fa852 --- /dev/null +++ b/man/man7/koi8-u.7 @@ -0,0 +1,175 @@ +'\" t +.\" Copyright 2009 Lefteris Dimitroulakis +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2009-01-15, mtk, Some edits +.\" +.TH KOI8-U 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +koi8-u \- Ukrainian character set encoded in octal, decimal, +and hexadecimal +.SH DESCRIPTION +RFC\ 2310 defines an 8-bit character set, KOI8-U. +KOI8-U encodes the +characters used in Ukrainian and Byelorussian. +.SS KOI8-U characters +The following table displays the characters in KOI8-U that +are printable and unlisted in the +.BR ascii (7) +manual page. +.TS +l l l c lp-1. +Oct Dec Hex Char Description +_ +200 128 80 ─ BOX DRAWINGS LIGHT HORIZONTAL +201 129 81 │ BOX DRAWINGS LIGHT VERTICAL +202 130 82 ┌ BOX DRAWINGS LIGHT DOWN AND RIGHT +203 131 83 ┐ BOX DRAWINGS LIGHT DOWN AND LEFT +204 132 84 └ BOX DRAWINGS LIGHT UP AND RIGHT +205 133 85 ┘ BOX DRAWINGS LIGHT UP AND LEFT +206 134 86 ├ BOX DRAWINGS LIGHT VERTICAL AND RIGHT +207 135 87 ┤ BOX DRAWINGS LIGHT VERTICAL AND LEFT +210 136 88 ┬ BOX DRAWINGS LIGHT DOWN AND HORIZONTAL +211 137 89 ┴ BOX DRAWINGS LIGHT UP AND HORIZONTAL +212 138 8A ┼ BOX DRAWINGS LIGHT VERTICAL AND HORIZONTAL +213 139 8B ▀ UPPER HALF BLOCK +214 140 8C ▄ LOWER HALF BLOCK +215 141 8D █ FULL BLOCK +216 142 8E ▌ LEFT HALF BLOCK +217 143 8F ▐ RIGHT HALF BLOCK +220 144 90 ░ LIGHT SHADE +221 145 91 ▒ MEDIUM SHADE +222 146 92 ▓ DARK SHADE +223 147 93 ⌠ TOP HALF INTEGRAL +224 148 94 ■ BLACK SQUARE +225 149 95 ∙ BULLET OPERATOR +226 150 96 √ SQUARE ROOT +227 151 97 ≈ ALMOST EQUAL TO +230 152 98 ≤ LESS-THAN OR EQUAL TO +231 153 99 ≥ GREATER-THAN OR EQUAL TO +232 154 9A   NO-BREAK SPACE +233 155 9B ⌡ BOTTOM HALF INTEGRAL +234 156 9C ° DEGREE SIGN +235 157 9D ² SUPERSCRIPT TWO +236 158 9E · MIDDLE DOT +237 159 9F ÷ DIVISION SIGN +240 160 A0 ═ BOX DRAWINGS DOUBLE HORIZONTAL +241 161 A1 ║ BOX DRAWINGS DOUBLE VERTICAL +242 162 A2 ╒ BOX DRAWINGS DOWN SINGLE AND RIGHT DOUBLE +243 163 A3 ё CYRILLIC SMALL LETTER IO +244 164 A4 є CYRILLIC SMALL LETTER UKRAINIAN IE +245 165 A5 ╔ BOX DRAWINGS DOUBLE DOWN AND RIGHT +246 166 A6 і T{ +CYRILLIC SMALL LETTER +.br +BYELORUSSIAN-UKRAINIAN I +T} +247 167 A7 ї CYRILLIC SMALL LETTER YI (Ukrainian) +250 168 A8 ╗ BOX DRAWINGS DOUBLE DOWN AND LEFT +251 169 A9 ╘ BOX DRAWINGS UP SINGLE AND RIGHT DOUBLE +252 170 AA ╙ BOX DRAWINGS UP DOUBLE AND RIGHT SINGLE +253 171 AB ╚ BOX DRAWINGS DOUBLE UP AND RIGHT +254 172 AC ╛ BOX DRAWINGS UP SINGLE AND LEFT DOUBLE +255 173 AD ґ CYRILLIC SMALL LETTER GHE WITH UPTURN +256 174 AE ╝ BOX DRAWINGS DOUBLE UP AND LEFT +257 175 AF ╞ BOX DRAWINGS VERTICAL SINGLE AND RIGHT DOUBLE +260 176 B0 ╟ BOX DRAWINGS VERTICAL DOUBLE AND RIGHT SINGLE +261 177 B1 ╠ BOX DRAWINGS DOUBLE VERTICAL AND RIGHT +262 178 B2 ╡ BOX DRAWINGS VERTICAL SINGLE AND LEFT DOUBLE +263 179 B3 Ё CYRILLIC CAPITAL LETTER IO +264 180 B4 Є CYRILLIC CAPITAL LETTER UKRAINIAN IE +265 181 B5 ╣ BOX DRAWINGS DOUBLE VERTICAL AND LEFT +266 182 B6 І T{ +CYRILLIC CAPITAL LETTER +.br +BYELORUSSIAN-UKRAINIAN I +T} +267 183 B7 Ї CYRILLIC CAPITAL LETTER YI (Ukrainian) +270 184 B8 ╦ BOX DRAWINGS DOUBLE DOWN AND HORIZONTAL +271 185 B9 ╧ BOX DRAWINGS UP SINGLE AND HORIZONTAL DOUBLE +272 186 BA ╨ BOX DRAWINGS UP DOUBLE AND HORIZONTAL SINGLE +273 187 BB ╩ BOX DRAWINGS DOUBLE UP AND HORIZONTAL +274 188 BC ╪ T{ +BOX DRAWINGS VERTICAL SINGLE +.br +AND HORIZONTAL DOUBLE +T} +275 189 BD Ґ CYRILLIC CAPITAL LETTER GHE WITH UPTURN +276 190 BE ╬ BOX DRAWINGS DOUBLE VERTICAL AND HORIZONTAL +277 191 BF © COPYRIGHT SIGN +300 192 C0 ю CYRILLIC SMALL LETTER YU +301 193 C1 а CYRILLIC SMALL LETTER A +302 194 C2 б CYRILLIC SMALL LETTER BE +303 195 C3 ц CYRILLIC SMALL LETTER TSE +304 196 C4 д CYRILLIC SMALL LETTER DE +305 197 C5 е CYRILLIC SMALL LETTER IE +306 198 C6 ф CYRILLIC SMALL LETTER EF +307 199 C7 г CYRILLIC SMALL LETTER GHE +310 200 C8 х CYRILLIC SMALL LETTER HA +311 201 C9 и CYRILLIC SMALL LETTER I +312 202 CA й CYRILLIC SMALL LETTER SHORT I +313 203 CB к CYRILLIC SMALL LETTER KA +314 204 CC л CYRILLIC SMALL LETTER EL +315 205 CD м CYRILLIC SMALL LETTER EM +316 206 CE н CYRILLIC SMALL LETTER EN +317 207 CF о CYRILLIC SMALL LETTER O +320 208 D0 п CYRILLIC SMALL LETTER PE +321 209 D1 я CYRILLIC SMALL LETTER YA +322 210 D2 р CYRILLIC SMALL LETTER ER +323 211 D3 с CYRILLIC SMALL LETTER ES +324 212 D4 т CYRILLIC SMALL LETTER TE +325 213 D5 у CYRILLIC SMALL LETTER U +326 214 D6 ж CYRILLIC SMALL LETTER ZHE +327 215 D7 в CYRILLIC SMALL LETTER VE +330 216 D8 ь CYRILLIC SMALL LETTER SOFT SIGN +331 217 D9 ы CYRILLIC SMALL LETTER YERU +332 218 DA з CYRILLIC SMALL LETTER ZE +333 219 DB ш CYRILLIC SMALL LETTER SHA +334 220 DC э CYRILLIC SMALL LETTER E +335 221 DD щ CYRILLIC SMALL LETTER SHCHA +336 222 DE ч CYRILLIC SMALL LETTER CHE +337 223 DF ъ CYRILLIC SMALL LETTER HARD SIGN +340 224 E0 Ю CYRILLIC CAPITAL LETTER YU +341 225 E1 А CYRILLIC CAPITAL LETTER A +342 226 E2 Б CYRILLIC CAPITAL LETTER BE +343 227 E3 Ц CYRILLIC CAPITAL LETTER TSE +344 228 E4 Д CYRILLIC CAPITAL LETTER DE +345 229 E5 Е CYRILLIC CAPITAL LETTER IE +346 230 E6 Ф CYRILLIC CAPITAL LETTER EF +347 231 E7 Г CYRILLIC CAPITAL LETTER GHE +350 232 E8 Х CYRILLIC CAPITAL LETTER HA +351 233 E9 И CYRILLIC CAPITAL LETTER I +352 234 EA Й CYRILLIC CAPITAL LETTER SHORT I +353 235 EB К CYRILLIC CAPITAL LETTER KA +354 236 EC Л CYRILLIC CAPITAL LETTER EL +355 237 ED М CYRILLIC CAPITAL LETTER EM +356 238 EE Н CYRILLIC CAPITAL LETTER EN +357 239 EF О CYRILLIC CAPITAL LETTER O +360 240 F0 П CYRILLIC CAPITAL LETTER PE +361 241 F1 Я CYRILLIC CAPITAL LETTER YA +362 242 F2 Р CYRILLIC CAPITAL LETTER ER +363 243 F3 С CYRILLIC CAPITAL LETTER ES +364 244 F4 Т CYRILLIC CAPITAL LETTER TE +365 245 F5 У CYRILLIC CAPITAL LETTER U +366 246 F6 Ж CYRILLIC CAPITAL LETTER ZHE +367 247 F7 В CYRILLIC CAPITAL LETTER VE +370 248 F8 Ь CYRILLIC CAPITAL LETTER SOFT SIGN +371 249 F9 Ы CYRILLIC CAPITAL LETTER YERU +372 250 FA З CYRILLIC CAPITAL LETTER ZE +373 251 FB Ш CYRILLIC CAPITAL LETTER SHA +374 252 FC Э CYRILLIC CAPITAL LETTER E +375 253 FD Щ CYRILLIC CAPITAL LETTER SHCHA +376 254 FE Ч CYRILLIC CAPITAL LETTER CHE +377 255 FF Ъ CYRILLIC CAPITAL LETTER HARD SIGN +.TE +.SH NOTES +The differences from KOI8-R are in the hex positions +A4, A6, A7, AD, B4, B6, B7, and BD. +.SH SEE ALSO +.BR ascii (7), +.BR charsets (7), +.BR cp1251 (7), +.BR iso_8859\-5 (7), +.BR koi8\-r (7), +.BR utf\-8 (7) diff --git a/man/man7/landlock.7 b/man/man7/landlock.7 new file mode 100644 index 0000000..fa44925 --- /dev/null +++ b/man/man7/landlock.7 @@ -0,0 +1,585 @@ +'\" t +.\" Copyright © 2017-2020 Mickaël Salaün +.\" Copyright © 2019-2020 ANSSI +.\" Copyright © 2021 Microsoft Corporation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH Landlock 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +Landlock \- unprivileged access-control +.SH DESCRIPTION +Landlock is an access-control system that enables any processes to +securely restrict themselves and their future children. +Because Landlock is a stackable Linux Security Module (LSM), +it makes it possible to create safe security sandboxes +as new security layers in addition to +the existing system-wide access-controls. +This kind of sandbox is expected to help mitigate +the security impact of bugs, +and unexpected or malicious behaviors in applications. +.P +A Landlock security policy is a set of access rights +(e.g., open a file in read-only, make a directory, etc.) +tied to a file hierarchy. +Such policy can be configured and enforced by processes for themselves +using three system calls: +.IP \[bu] 3 +.BR landlock_create_ruleset (2) +creates a new ruleset; +.IP \[bu] +.BR landlock_add_rule (2) +adds a new rule to a ruleset; +.IP \[bu] +.BR landlock_restrict_self (2) +enforces a ruleset on the calling thread. +.P +To be able to use these system calls, +the running kernel must support Landlock and +it must be enabled at boot time. +.\" +.SS Landlock rules +A Landlock rule describes an action on an object. +An object is currently a file hierarchy, +and the related filesystem actions are defined with access rights (see +.BR landlock_add_rule (2)). +A set of rules is aggregated in a ruleset, +which can then restrict the thread enforcing it, +and its future children. +.\" +.SS Filesystem actions +These flags enable to restrict a sandboxed process to a +set of actions on files and directories. +Files or directories opened before the sandboxing +are not subject to these restrictions. +See +.BR landlock_add_rule (2) +and +.BR landlock_create_ruleset (2) +for more context. +.P +A file can only receive these access rights: +.TP +.B LANDLOCK_ACCESS_FS_EXECUTE +Execute a file. +.TP +.B LANDLOCK_ACCESS_FS_WRITE_FILE +Open a file with write access. +.IP +When opening files for writing, +you will often additionally need the +.B LANDLOCK_ACCESS_FS_TRUNCATE +right. +In many cases, +these system calls truncate existing files when overwriting them +(e.g., +.BR creat (2)). +.TP +.B LANDLOCK_ACCESS_FS_READ_FILE +Open a file with read access. +.TP +.B LANDLOCK_ACCESS_FS_TRUNCATE +Truncate a file with +.BR truncate (2), +.BR ftruncate (2), +.BR creat (2), +or +.BR open (2) +with +.BR O_TRUNC . +Whether an opened file can be truncated with +.BR ftruncate (2) +is determined during +.BR open (2), +in the same way as read and write permissions are checked during +.BR open (2) +using +.B LANDLOCK_ACCESS_FS_READ_FILE +and +.BR LANDLOCK_ACCESS_FS_WRITE_FILE . +This access right is available since the third version of the Landlock ABI. +.P +A directory can receive access rights related to files or directories. +The following access right is applied to the directory itself, +and the directories beneath it: +.TP +.B LANDLOCK_ACCESS_FS_READ_DIR +Open a directory or list its content. +.P +However, +the following access rights only apply to the content of a directory, +not the directory itself: +.TP +.B LANDLOCK_ACCESS_FS_REMOVE_DIR +Remove an empty directory or rename one. +.TP +.B LANDLOCK_ACCESS_FS_REMOVE_FILE +Unlink (or rename) a file. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_CHAR +Create (or rename or link) a character device. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_DIR +Create (or rename) a directory. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_REG +Create (or rename or link) a regular file. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_SOCK +Create (or rename or link) a UNIX domain socket. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_FIFO +Create (or rename or link) a named pipe. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_BLOCK +Create (or rename or link) a block device. +.TP +.B LANDLOCK_ACCESS_FS_MAKE_SYM +Create (or rename or link) a symbolic link. +.TP +.B LANDLOCK_ACCESS_FS_REFER +Link or rename a file from or to a different directory +(i.e., reparent a file hierarchy). +.IP +This access right is available since the second version of the Landlock ABI. +.IP +This is the only access right which is denied by default by any ruleset, +even if the right is not specified as handled at ruleset creation time. +The only way to make a ruleset grant this right +is to explicitly allow it for a specific directory +by adding a matching rule to the ruleset. +.IP +In particular, when using the first Landlock ABI version, +Landlock will always deny attempts to reparent files +between different directories. +.IP +In addition to the source and destination directories having the +.B LANDLOCK_ACCESS_FS_REFER +access right, +the attempted link or rename operation must meet the following constraints: +.RS +.IP \[bu] 3 +The reparented file may not gain more access rights in the destination directory +than it previously had in the source directory. +If this is attempted, the operation results in an +.B EXDEV +error. +.IP \[bu] +When linking or renaming, the +.BI LANDLOCK_ACCESS_FS_MAKE_ * +right for the respective file type must be granted +for the destination directory. +Otherwise, the operation results in an +.B EACCES +error. +.IP \[bu] +When renaming, the +.BI LANDLOCK_ACCESS_FS_REMOVE_ * +right for the respective file type must be granted +for the source directory. +Otherwise, the operation results in an +.B EACCES +error. +.RE +.IP +If multiple requirements are not met, the +.B EACCES +error code takes precedence over +.BR EXDEV . +.\" +.SS Layers of file path access rights +Each time a thread enforces a ruleset on itself, +it updates its Landlock domain with a new layer of policy. +Indeed, this complementary policy is composed with the +potentially other rulesets already restricting this thread. +A sandboxed thread can then safely add more constraints to itself with a +new enforced ruleset. +.P +One policy layer grants access to a file path +if at least one of its rules encountered on the path grants the access. +A sandboxed thread can only access a file path +if all its enforced policy layers grant the access +as well as all the other system access controls +(e.g., filesystem DAC, other LSM policies, etc.). +.\" +.SS Bind mounts and OverlayFS +Landlock enables restricting access to file hierarchies, +which means that these access rights can be propagated with bind mounts +(cf. +.BR mount_namespaces (7)) +but not with OverlayFS. +.P +A bind mount mirrors a source file hierarchy to a destination. +The destination hierarchy is then composed of the exact same files, +on which Landlock rules can be tied, +either via the source or the destination path. +These rules restrict access when they are encountered on a path, +which means that they can restrict access to +multiple file hierarchies at the same time, +whether these hierarchies are the result of bind mounts or not. +.P +An OverlayFS mount point consists of upper and lower layers. +These layers are combined in a merge directory, result of the mount point. +This merge hierarchy may include files from the upper and lower layers, +but modifications performed on the merge hierarchy +only reflect on the upper layer. +From a Landlock policy point of view, +each of the OverlayFS layers and merge hierarchies is standalone and +contains its own set of files and directories, +which is different from a bind mount. +A policy restricting an OverlayFS layer will not restrict +the resulted merged hierarchy, and vice versa. +Landlock users should then only think about file hierarchies they want to +allow access to, regardless of the underlying filesystem. +.\" +.SS Inheritance +Every new thread resulting from a +.BR clone (2) +inherits Landlock domain restrictions from its parent. +This is similar to the +.BR seccomp (2) +inheritance or any other LSM dealing with tasks' +.BR credentials (7). +For instance, one process's thread may apply Landlock rules to itself, +but they will not be automatically applied to other sibling threads +(unlike POSIX thread credential changes, cf. +.BR nptl (7)). +.P +When a thread sandboxes itself, +we have the guarantee that the related security policy +will stay enforced on all this thread's descendants. +This allows creating standalone and modular security policies +per application, +which will automatically be composed between themselves +according to their run-time parent policies. +.\" +.SS Ptrace restrictions +A sandboxed process has less privileges than a non-sandboxed process and +must then be subject to additional restrictions +when manipulating another process. +To be allowed to use +.BR ptrace (2) +and related syscalls on a target process, +a sandboxed process should have a subset of the target process rules, +which means the tracee must be in a sub-domain of the tracer. +.\" +.SS Truncating files +The operations covered by +.B LANDLOCK_ACCESS_FS_WRITE_FILE +and +.B LANDLOCK_ACCESS_FS_TRUNCATE +both change the contents of a file and sometimes overlap in +non-intuitive ways. +It is recommended to always specify both of these together. +.P +A particularly surprising example is +.BR creat (2). +The name suggests that this system call requires +the rights to create and write files. +However, it also requires the truncate right +if an existing file under the same name is already present. +.P +It should also be noted that truncating files does not require the +.B LANDLOCK_ACCESS_FS_WRITE_FILE +right. +Apart from the +.BR truncate (2) +system call, this can also be done through +.BR open (2) +with the flags +.IR "O_RDONLY\ |\ O_TRUNC" . +.P +When opening a file, the availability of the +.B LANDLOCK_ACCESS_FS_TRUNCATE +right is associated with the newly created file descriptor +and will be used for subsequent truncation attempts using +.BR ftruncate (2). +The behavior is similar to opening a file for reading or writing, +where permissions are checked during +.BR open (2), +but not during the subsequent +.BR read (2) +and +.BR write (2) +calls. +.P +As a consequence, +it is possible to have multiple open file descriptors for the same file, +where one grants the right to truncate the file and the other does not. +It is also possible to pass such file descriptors between processes, +keeping their Landlock properties, +even when these processes do not have an enforced Landlock ruleset. +.SH VERSIONS +Landlock was introduced in Linux 5.13. +.P +To determine which Landlock features are available, +users should query the Landlock ABI version: +.TS +box; +ntb| ntb| lbx +nt| nt| lbx. +ABI Kernel Newly introduced access rights +_ _ _ +1 5.13 LANDLOCK_ACCESS_FS_EXECUTE +\^ \^ LANDLOCK_ACCESS_FS_WRITE_FILE +\^ \^ LANDLOCK_ACCESS_FS_READ_FILE +\^ \^ LANDLOCK_ACCESS_FS_READ_DIR +\^ \^ LANDLOCK_ACCESS_FS_REMOVE_DIR +\^ \^ LANDLOCK_ACCESS_FS_REMOVE_FILE +\^ \^ LANDLOCK_ACCESS_FS_MAKE_CHAR +\^ \^ LANDLOCK_ACCESS_FS_MAKE_DIR +\^ \^ LANDLOCK_ACCESS_FS_MAKE_REG +\^ \^ LANDLOCK_ACCESS_FS_MAKE_SOCK +\^ \^ LANDLOCK_ACCESS_FS_MAKE_FIFO +\^ \^ LANDLOCK_ACCESS_FS_MAKE_BLOCK +\^ \^ LANDLOCK_ACCESS_FS_MAKE_SYM +_ _ _ +2 5.19 LANDLOCK_ACCESS_FS_REFER +_ _ _ +3 6.2 LANDLOCK_ACCESS_FS_TRUNCATE +.TE +.P +Users should use the Landlock ABI version rather than the kernel version +to determine which features are available. +The mainline kernel versions listed here are only included for orientation. +Kernels from other sources may contain backported features, +and their version numbers may not match. +.P +To query the running kernel's Landlock ABI version, +programs may pass the +.B LANDLOCK_CREATE_RULESET_VERSION +flag to +.BR landlock_create_ruleset (2). +.P +When building fallback mechanisms for compatibility with older kernels, +users are advised to consider the special semantics of the +.B LANDLOCK_ACCESS_FS_REFER +access right: +In ABI v1, +linking and moving of files between different directories is always forbidden, +so programs relying on such operations are only compatible +with Landlock ABI v2 and higher. +.SH NOTES +Landlock is enabled by +.BR CONFIG_SECURITY_LANDLOCK . +The +.I lsm=lsm1,...,lsmN +command line parameter controls the sequence of the initialization of +Linux Security Modules. +It must contain the string +.I landlock +to enable Landlock. +If the command line parameter is not specified, +the initialization falls back to the value of the deprecated +.I security= +command line parameter and further to the value of +.BR CONFIG_LSM . +We can check that Landlock is enabled by looking for +.I landlock: Up and running. +in kernel logs. +.SH CAVEATS +It is currently not possible to restrict some file-related actions +accessible through these system call families: +.BR chdir (2), +.BR stat (2), +.BR flock (2), +.BR chmod (2), +.BR chown (2), +.BR setxattr (2), +.BR utime (2), +.BR ioctl (2), +.BR fcntl (2), +.BR access (2). +Future Landlock evolutions will enable to restrict them. +.SH EXAMPLES +We first need to create the ruleset that will contain our rules. +.P +For this example, +the ruleset will contain rules that only allow read actions, +but write actions will be denied. +The ruleset then needs to handle both of these kinds of actions. +See the +.B DESCRIPTION +section for the description of filesystem actions. +.P +.in +4n +.EX +struct landlock_ruleset_attr attr = {0}; +int ruleset_fd; +\& +attr.handled_access_fs = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_WRITE_FILE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR | + LANDLOCK_ACCESS_FS_REMOVE_DIR | + LANDLOCK_ACCESS_FS_REMOVE_FILE | + LANDLOCK_ACCESS_FS_MAKE_CHAR | + LANDLOCK_ACCESS_FS_MAKE_DIR | + LANDLOCK_ACCESS_FS_MAKE_REG | + LANDLOCK_ACCESS_FS_MAKE_SOCK | + LANDLOCK_ACCESS_FS_MAKE_FIFO | + LANDLOCK_ACCESS_FS_MAKE_BLOCK | + LANDLOCK_ACCESS_FS_MAKE_SYM | + LANDLOCK_ACCESS_FS_REFER | + LANDLOCK_ACCESS_FS_TRUNCATE; +.EE +.in +.P +To be compatible with older Linux versions, +we detect the available Landlock ABI version, +and only use the available subset of access rights: +.P +.in +4n +.EX +/* + * Table of available file system access rights by ABI version, + * numbers hardcoded to keep the example short. + */ +__u64 landlock_fs_access_rights[] = { + (LANDLOCK_ACCESS_FS_MAKE_SYM << 1) \- 1, /* v1 */ + (LANDLOCK_ACCESS_FS_REFER << 1) \- 1, /* v2: add "refer" */ + (LANDLOCK_ACCESS_FS_TRUNCATE << 1) \- 1, /* v3: add "truncate" */ +}; +\& +int abi = landlock_create_ruleset(NULL, 0, + LANDLOCK_CREATE_RULESET_VERSION); +if (abi == \-1) { + /* + * Kernel too old, not compiled with Landlock, + * or Landlock was not enabled at boot time. + */ + perror("Unable to use Landlock"); + return; /* Graceful fallback: Do nothing. */ +} +abi = MIN(abi, 3); +\& +/* Only use the available rights in the ruleset. */ +attr.handled_access_fs &= landlock_fs_access_rights[abi \- 1]; +.EE +.in +.P +The available access rights for each ABI version are listed in the +.B VERSIONS +section. +.P +If our program needed to create hard links +or rename files between different directories +.RB ( LANDLOCK_ACCESS_FS_REFER ), +we would require the following change to the backwards compatibility logic: +Directory reparenting is not possible +in a process restricted with Landlock ABI version 1. +Therefore, +if the program needed to do file reparenting, +and if only Landlock ABI version 1 was available, +we could not restrict the process. +.P +Now that the ruleset attributes are determined, +we create the Landlock ruleset +and acquire a file descriptor as a handle to it, +using +.BR landlock_create_ruleset (2): +.P +.in +4n +.EX +ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); +if (ruleset_fd == \-1) { + perror("Failed to create a ruleset"); + exit(EXIT_FAILURE); +} +.EE +.in +.P +We can now add a new rule to the ruleset through the ruleset's file descriptor. +The requested access rights must be a subset of the access rights +which were specified in +.I attr.handled_access_fs +at ruleset creation time. +.P +In this example, the rule will only allow reading the file hierarchy +.IR /usr . +Without another rule, write actions would then be denied by the ruleset. +To add +.I /usr +to the ruleset, we open it with the +.I O_PATH +flag and fill the +.I struct landlock_path_beneath_attr +with this file descriptor. +.P +.in +4n +.EX +struct landlock_path_beneath_attr path_beneath = {0}; +int err; +\& +path_beneath.allowed_access = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR; +\& +path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC); +if (path_beneath.parent_fd == \-1) { + perror("Failed to open file"); + close(ruleset_fd); + exit(EXIT_FAILURE); +} +err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH, + &path_beneath, 0); +close(path_beneath.parent_fd); +if (err) { + perror("Failed to update ruleset"); + close(ruleset_fd); + exit(EXIT_FAILURE); +} +.EE +.in +.P +We now have a ruleset with one rule allowing read access to +.I /usr +while denying all other handled accesses for the filesystem. +The next step is to restrict the current thread from gaining more +privileges +(e.g., thanks to a set-user-ID binary). +.P +.in +4n +.EX +if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { + perror("Failed to restrict privileges"); + close(ruleset_fd); + exit(EXIT_FAILURE); +} +.EE +.in +.P +The current thread is now ready to sandbox itself with the ruleset. +.P +.in +4n +.EX +if (landlock_restrict_self(ruleset_fd, 0)) { + perror("Failed to enforce ruleset"); + close(ruleset_fd); + exit(EXIT_FAILURE); +} +close(ruleset_fd); +.EE +.in +.P +If the +.BR landlock_restrict_self (2) +system call succeeds, the current thread is now restricted and +this policy will be enforced on all its subsequently created children as well. +Once a thread is landlocked, there is no way to remove its security policy; +only adding more restrictions is allowed. +These threads are now in a new Landlock domain, +merge of their parent one (if any) with the new ruleset. +.P +Full working code can be found in +.UR https://git.kernel.org/\:pub/\:scm/\:linux/\:kernel/\:git/\:stable/\:linux.git/\:tree/\:samples/\:landlock/\:sandboxer.c +.UE +.SH SEE ALSO +.BR landlock_create_ruleset (2), +.BR landlock_add_rule (2), +.BR landlock_restrict_self (2) +.P +.UR https://landlock.io/ +.UE diff --git a/man/man7/latin1.7 b/man/man7/latin1.7 new file mode 100644 index 0000000..1969dfb --- /dev/null +++ b/man/man7/latin1.7 @@ -0,0 +1 @@ +.so man7/iso_8859-1.7 diff --git a/man/man7/latin10.7 b/man/man7/latin10.7 new file mode 100644 index 0000000..b9c8e91 --- /dev/null +++ b/man/man7/latin10.7 @@ -0,0 +1 @@ +.so man7/iso_8859-16.7 diff --git a/man/man7/latin2.7 b/man/man7/latin2.7 new file mode 100644 index 0000000..da36668 --- /dev/null +++ b/man/man7/latin2.7 @@ -0,0 +1 @@ +.so man7/iso_8859-2.7 diff --git a/man/man7/latin3.7 b/man/man7/latin3.7 new file mode 100644 index 0000000..75e42ce --- /dev/null +++ b/man/man7/latin3.7 @@ -0,0 +1 @@ +.so man7/iso_8859-3.7 diff --git a/man/man7/latin4.7 b/man/man7/latin4.7 new file mode 100644 index 0000000..15a829e --- /dev/null +++ b/man/man7/latin4.7 @@ -0,0 +1 @@ +.so man7/iso_8859-4.7 diff --git a/man/man7/latin5.7 b/man/man7/latin5.7 new file mode 100644 index 0000000..0fcc7d4 --- /dev/null +++ b/man/man7/latin5.7 @@ -0,0 +1 @@ +.so man7/iso_8859-9.7 diff --git a/man/man7/latin6.7 b/man/man7/latin6.7 new file mode 100644 index 0000000..9b4658f --- /dev/null +++ b/man/man7/latin6.7 @@ -0,0 +1 @@ +.so man7/iso_8859-10.7 diff --git a/man/man7/latin7.7 b/man/man7/latin7.7 new file mode 100644 index 0000000..8ad2335 --- /dev/null +++ b/man/man7/latin7.7 @@ -0,0 +1 @@ +.so man7/iso_8859-13.7 diff --git a/man/man7/latin8.7 b/man/man7/latin8.7 new file mode 100644 index 0000000..4aa555d --- /dev/null +++ b/man/man7/latin8.7 @@ -0,0 +1 @@ +.so man7/iso_8859-14.7 diff --git a/man/man7/latin9.7 b/man/man7/latin9.7 new file mode 100644 index 0000000..a4095d7 --- /dev/null +++ b/man/man7/latin9.7 @@ -0,0 +1 @@ +.so man7/iso_8859-15.7 diff --git a/man/man7/libc.7 b/man/man7/libc.7 new file mode 100644 index 0000000..d7ae95d --- /dev/null +++ b/man/man7/libc.7 @@ -0,0 +1,115 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH libc 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +libc \- overview of standard C libraries on Linux +.SH DESCRIPTION +The term \[lq]libc\[rq] is commonly used as a shorthand for +the \[lq]standard C library\[rq] +a library of standard functions that can be used by all C programs +(and sometimes by programs in other languages). +Because of some history +(see below), +use of the term \[lq]libc\[rq] +to refer to the standard C library is somewhat ambiguous on Linux. +.SS glibc +By far the most widely used C library on Linux is the +.UR http://www.gnu.org\:/software\:/libc/ +GNU C Library +.UE , +often referred to as +.IR glibc . +This is the C library that is nowadays used in all +major Linux distributions. +It is also the C library whose details are documented +in the relevant pages of the +.I man-pages +project +(primarily in Section 3 of the manual). +Documentation of glibc is also available in the glibc manual, +available via the command +.IR "info libc" . +Release 1.0 of glibc was made in September 1992. +(There were earlier 0.x releases.) +The next major release of glibc was 2.0, +at the beginning of 1997. +.P +The pathname +.I /lib/libc.so.6 +(or something similar) +is normally a symbolic link that +points to the location of the glibc library, +and executing this pathname will cause glibc to display +various information about the version installed on your system. +.SS Linux libc +In the early to mid 1990s, +there was for a while +.IR "Linux libc" , +a fork of glibc 1.x created by Linux developers who felt that glibc +development at the time was not sufficing for the needs of Linux. +Often, +this library was referred to (ambiguously) as just \[lq]libc\[rq]. +Linux libc released major versions 2, 3, 4, and 5, +as well as many minor versions of those releases. +Linux libc4 was the last version to use the a.out binary format, +and the first version to provide (primitive) shared library support. +Linux libc 5 was the first version to support the ELF binary format; +this version used the shared library soname +.IR libc.so.5 . +For a while, +Linux libc was the standard C library in many Linux distributions. +.P +However, +notwithstanding the original motivations of the Linux libc effort, +by the time glibc 2.0 was released +(in 1997), +it was clearly superior to Linux libc, +and all major Linux distributions that had been using Linux libc +soon switched back to glibc. +To avoid any confusion with Linux libc versions, +glibc 2.0 and later used the shared library soname +.IR libc.so.6 . +.P +Since the switch from Linux libc to glibc 2.0 occurred long ago, +.I man-pages +no longer takes care to document Linux libc details. +Nevertheless, +the history is visible in vestiges of information +about Linux libc that remain in a few manual pages, +in particular, +references to +.I libc4 +and +.IR libc5 . +.SS Other C libraries +There are various other less widely used C libraries for Linux. +These libraries are generally smaller than glibc, +both in terms of features and memory footprint, +and often intended for building small binaries, +perhaps targeted at development for embedded Linux systems. +Among such libraries are +.UR http://www\:.uclibc\:.org/ +.I uClibc +.UE , +.UR http://www\:.fefe\:.de/\:dietlibc/ +.I dietlibc +.UE , +and +.UR http://www\:.musl\-libc\:.org/ +.I "musl libc" +.UE . +Details of these libraries are covered by the +.I man-pages +project, +where they are known. +.SH SEE ALSO +.BR syscalls (2), +.BR getauxval (3), +.BR proc (5), +.BR feature_test_macros (7), +.BR man\-pages (7), +.BR standards (7), +.BR vdso (7) diff --git a/man/man7/locale.7 b/man/man7/locale.7 new file mode 100644 index 0000000..894a575 --- /dev/null +++ b/man/man7/locale.7 @@ -0,0 +1,379 @@ +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (C) 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 17:28:34 1993 by Rik Faith +.\" Modified Sun Jun 01 17:16:34 1997 by Jochen Hein +.\" +.\" Modified Thu Apr 25 00:43:19 2002 by Bruno Haible +.\" +.TH locale 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +locale \- description of multilanguage support +.SH SYNOPSIS +.nf +.B #include +.fi +.SH DESCRIPTION +A locale is a set of language and cultural rules. +These cover aspects +such as language for messages, different character sets, lexicographic +conventions, and so on. +A program needs to be able to determine its locale +and act accordingly to be portable to different cultures. +.P +The header +.I +declares data types, functions, and macros which are useful in this +task. +.P +The functions it declares are +.BR setlocale (3) +to set the current locale, and +.BR localeconv (3) +to get information about number formatting. +.P +There are different categories for locale information a program might +need; they are declared as macros. +Using them as the first argument +to the +.BR setlocale (3) +function, it is possible to set one of these to the desired locale: +.TP +.BR LC_ADDRESS " (GNU extension, since glibc 2.2)" +.\" See ISO/IEC Technical Report 14652 +Change settings that describe the formats (e.g., postal addresses) +used to describe locations and geography-related items. +Applications that need this information can use +.BR nl_langinfo (3) +to retrieve nonstandard elements, such as +.B _NL_ADDRESS_COUNTRY_NAME +(country name, in the language of the locale) +and +.B _NL_ADDRESS_LANG_NAME +(language name, in the language of the locale), +which return strings such as "Deutschland" and "Deutsch" +(for German-language locales). +(Other element names are listed in +.IR .) +.TP +.B LC_COLLATE +This category governs the collation rules used for +sorting and regular expressions, +including character equivalence classes and +multicharacter collating elements. +This locale category changes the behavior of the functions +.BR strcoll (3) +and +.BR strxfrm (3), +which are used to compare strings in the local alphabet. +For example, +the German sharp s is sorted as "ss". +.TP +.B LC_CTYPE +This category determines the interpretation of byte sequences as characters +(e.g., single versus multibyte characters), character classifications +(e.g., alphabetic or digit), and the behavior of character classes. +On glibc systems, this category also determines +the character transliteration rules for +.BR iconv (1) +and +.BR iconv (3). +It changes the behavior of the character handling and +classification functions, such as +.BR isupper (3) +and +.BR toupper (3), +and the multibyte character functions such as +.BR mblen (3) +or +.BR wctomb (3). +.TP +.BR LC_IDENTIFICATION " (GNU extension, since glibc 2.2)" +.\" See ISO/IEC Technical Report 14652 +Change settings that relate to the metadata for the locale. +Applications that need this information can use +.BR nl_langinfo (3) +to retrieve nonstandard elements, such as +.B _NL_IDENTIFICATION_TITLE +(title of this locale document) +and +.B _NL_IDENTIFICATION_TERRITORY +(geographical territory to which this locale document applies), +which might return strings such as "English locale for the USA" +and "USA". +(Other element names are listed in +.IR .) +.TP +.B LC_MONETARY +This category determines the formatting used for +monetary-related numeric values. +This changes the information returned by +.BR localeconv (3), +which describes the way numbers are usually printed, with details such +as decimal point versus decimal comma. +This information is internally +used by the function +.BR strfmon (3). +.TP +.B LC_MESSAGES +This category affects the language in which messages are displayed +and what an affirmative or negative answer looks like. +The GNU C library contains the +.BR gettext (3), +.BR ngettext (3), +and +.BR rpmatch (3) +functions to ease the use of this information. +The GNU gettext family of +functions also obey the environment variable +.B LANGUAGE +(containing a colon-separated list of locales) +if the category is set to a valid locale other than +.BR \[dq]C\[dq] . +This category also affects the behavior of +.BR catopen (3). +.TP +.BR LC_MEASUREMENT " (GNU extension, since glibc 2.2)" +Change the settings relating to the measurement system in the locale +(i.e., metric versus US customary units). +Applications can use +.BR nl_langinfo (3) +to retrieve the nonstandard +.B _NL_MEASUREMENT_MEASUREMENT +element, which returns a pointer to a character +that has the value 1 (metric) or 2 (US customary units). +.TP +.BR LC_NAME " (GNU extension, since glibc 2.2)" +.\" See ISO/IEC Technical Report 14652 +Change settings that describe the formats used to address persons. +Applications that need this information can use +.BR nl_langinfo (3) +to retrieve nonstandard elements, such as +.B _NL_NAME_NAME_MR +(general salutation for men) +and +.B _NL_NAME_NAME_MS +(general salutation for women) +elements, which return strings such as "Herr" and "Frau" +(for German-language locales). +(Other element names are listed in +.IR .) +.TP +.B LC_NUMERIC +This category determines the formatting rules used for nonmonetary +numeric values\[em]for example, +the thousands separator and the radix character +(a period in most English-speaking countries, +but a comma in many other regions). +It affects functions such as +.BR printf (3), +.BR scanf (3), +and +.BR strtod (3). +This information can also be read with the +.BR localeconv (3) +function. +.TP +.BR LC_PAPER " (GNU extension, since glibc 2.2)" +.\" See ISO/IEC Technical Report 14652 +Change the settings relating to the dimensions of the standard paper size +(e.g., US letter versus A4). +Applications that need the dimensions can obtain them by using +.BR nl_langinfo (3) +to retrieve the nonstandard +.B _NL_PAPER_WIDTH +and +.B _NL_PAPER_HEIGHT +elements, which return +.I int +values specifying the dimensions in millimeters. +.TP +.BR LC_TELEPHONE " (GNU extension, since glibc 2.2)" +.\" See ISO/IEC Technical Report 14652 +Change settings that describe the formats to be used with telephone services. +Applications that need this information can use +.BR nl_langinfo (3) +to retrieve nonstandard elements, such as +.B _NL_TELEPHONE_INT_PREFIX +(international prefix used to call numbers in this locale), +which returns a string such as "49" (for Germany). +(Other element names are listed in +.IR .) +.TP +.B LC_TIME +This category governs the formatting used for date and time values. +For example, most of Europe uses a 24-hour clock versus the +12-hour clock used in the United States. +The setting of this category affects the behavior of functions such as +.BR strftime (3) +and +.BR strptime (3). +.TP +.B LC_ALL +All of the above. +.P +If the second argument to +.BR setlocale (3) +is an empty string, +.IR \[dq]\[dq] , +for the default locale, it is determined using the following steps: +.IP (1) 5 +If there is a non-null environment variable +.BR LC_ALL , +the value of +.B LC_ALL +is used. +.IP (2) +If an environment variable with the same name as one of the categories +above exists and is non-null, its value is used for that category. +.IP (3) +If there is a non-null environment variable +.BR LANG , +the value of +.B LANG +is used. +.P +Values about local numeric formatting is made available in a +.I struct lconv +returned by the +.BR localeconv (3) +function, which has the following declaration: +.P +.in +4n +.EX +struct lconv { +\& + /* Numeric (nonmonetary) information */ +\& + char *decimal_point; /* Radix character */ + char *thousands_sep; /* Separator for digit groups to left + of radix character */ + char *grouping; /* Each element is the number of digits in + a group; elements with higher indices + are further left. An element with value + CHAR_MAX means that no further grouping + is done. An element with value 0 means + that the previous element is used for + all groups further left. */ +\& + /* Remaining fields are for monetary information */ +\& + char *int_curr_symbol; /* First three chars are a currency + symbol from ISO 4217. Fourth char + is the separator. Fifth char + is \[aq]\e0\[aq]. */ + char *currency_symbol; /* Local currency symbol */ + char *mon_decimal_point; /* Radix character */ + char *mon_thousands_sep; /* Like \fIthousands_sep\fP above */ + char *mon_grouping; /* Like \fIgrouping\fP above */ + char *positive_sign; /* Sign for positive values */ + char *negative_sign; /* Sign for negative values */ + char int_frac_digits; /* International fractional digits */ + char frac_digits; /* Local fractional digits */ + char p_cs_precedes; /* 1 if currency_symbol precedes a + positive value, 0 if succeeds */ + char p_sep_by_space; /* 1 if a space separates + currency_symbol from a positive + value */ + char n_cs_precedes; /* 1 if currency_symbol precedes a + negative value, 0 if succeeds */ + char n_sep_by_space; /* 1 if a space separates + currency_symbol from a negative + value */ + /* Positive and negative sign positions: + 0 Parentheses surround the quantity and currency_symbol. + 1 The sign string precedes the quantity and currency_symbol. + 2 The sign string succeeds the quantity and currency_symbol. + 3 The sign string immediately precedes the currency_symbol. + 4 The sign string immediately succeeds the currency_symbol. */ + char p_sign_posn; + char n_sign_posn; +}; +.EE +.in +.SS POSIX.1-2008 extensions to the locale API +POSIX.1-2008 standardized a number of extensions to the locale API, +based on implementations that first appeared in glibc 2.3. +These extensions are designed to address the problem that +the traditional locale APIs do not mix well with multithreaded applications +and with applications that must deal with multiple locales. +.P +The extensions take the form of new functions for creating and +manipulating locale objects +.RB ( newlocale (3), +.BR freelocale (3), +.BR duplocale (3), +and +.BR uselocale (3)) +and various new library functions with the suffix "_l" (e.g., +.BR toupper_l (3)) +that extend the traditional locale-dependent APIs (e.g., +.BR toupper (3)) +to allow the specification of a locale object that should apply when +executing the function. +.SH ENVIRONMENT +The following environment variable is used by +.BR newlocale (3) +and +.BR setlocale (3), +and thus affects all unprivileged localized programs: +.TP +.B LOCPATH +A list of pathnames, separated by colons (\[aq]:\[aq]), +that should be used to find locale data. +If this variable is set, +only the individual compiled locale data files from +.B LOCPATH +and the system default locale data path are used; +any available locale archives are not used (see +.BR localedef (1)). +The individual compiled locale data files are searched for under +subdirectories which depend on the currently used locale. +For example, when +.I en_GB.UTF\-8 +is used for a category, the following subdirectories are searched for, +in this order: +.IR en_GB.UTF\-8 , +.IR en_GB.utf8 , +.IR en_GB , +.IR en.UTF\-8 , +.IR en.utf8 , +and +.IR en . +.SH FILES +.TP +.I /usr/lib/locale/locale\-archive +Usual default locale archive location. +.TP +.I /usr/lib/locale +Usual default path for compiled individual locale files. +.SH STANDARDS +POSIX.1-2001. +.\" +.\" The GNU gettext functions are specified in LI18NUX2000. +.SH SEE ALSO +.BR iconv (1), +.BR locale (1), +.BR localedef (1), +.BR catopen (3), +.BR gettext (3), +.BR iconv (3), +.BR localeconv (3), +.BR mbstowcs (3), +.BR newlocale (3), +.BR ngettext (3), +.BR nl_langinfo (3), +.BR rpmatch (3), +.BR setlocale (3), +.BR strcoll (3), +.BR strfmon (3), +.BR strftime (3), +.BR strxfrm (3), +.BR uselocale (3), +.BR wcstombs (3), +.BR locale (5), +.BR charsets (7), +.BR unicode (7), +.BR utf\-8 (7) diff --git a/man/man7/mailaddr.7 b/man/man7/mailaddr.7 new file mode 100644 index 0000000..684b4b4 --- /dev/null +++ b/man/man7/mailaddr.7 @@ -0,0 +1,134 @@ +.\" Copyright (c) 1983, 1987 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" @(#)mailaddr.7 6.5 (Berkeley) 2/14/89 +.\" +.\" Extensively rewritten by Arnt Gulbrandsen . My +.\" changes are placed under the same copyright as the original BSD page. +.\" +.\" Adjusted by Arnt Gulbrandsen in 2004 to +.\" account for changes since 1995. Route-addrs are now even less +.\" common, etc. Some minor wording improvements. Same copyright. +.\" +.\" %%%LICENSE_START(PERMISSIVE_MISC) +.\" Redistribution and use in source and binary forms are permitted +.\" provided that the above copyright notice and this paragraph are +.\" duplicated in all such forms and that any documentation, +.\" advertising materials, and other materials related to such +.\" distribution and use acknowledge that the software was developed +.\" by the University of California, Berkeley. The name of the +.\" University may not be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" %%%LICENSE_END +.\" +.TH mailaddr 7 2024-05-02 "Linux man-pages (unreleased)" +.UC 5 +.SH NAME +mailaddr \- mail addressing description +.SH DESCRIPTION +.nh +This manual page gives a brief introduction to SMTP mail addresses, +as used on the Internet. +These addresses are in the general format +.P +.in +4n +.EX +user@domain +.EE +.in +.P +where a domain is a hierarchical dot-separated list of subdomains. +These examples are valid forms of the same address: +.P +.in +4n +.EX +john.doe@monet.example.com +John Doe +john.doe@monet.example.com (John Doe) +.EE +.in +.P +The domain part ("monet.example.com") is a mail-accepting domain. +It can be a host and in the past it usually was, but it doesn't have to be. +The domain part is not case sensitive. +.P +The local part ("john.doe") is often a username, +but its meaning is defined by the local software. +Sometimes it is case sensitive, +although that is unusual. +If you see a local-part that looks like garbage, +it is usually because of a gateway between an internal e-mail +system and the net, here are some examples: +.P +.in +4n +.EX +"surname/admd=telemail/c=us/o=hp/prmd=hp"@some.where +USER%SOMETHING@some.where +machine!machine!name@some.where +I2461572@some.where +.EE +.in +.P +(These are, respectively, an X.400 gateway, a gateway to an arbitrary +internal mail system that lacks proper internet support, an UUCP +gateway, and the last one is just boring username policy.) +.P +The real-name part ("John Doe") can either be placed before +<>, or in () at the end. +(Strictly speaking the two aren't the same, +but the difference is beyond the scope of this page.) +The name may have to be quoted using "", for example, if it contains ".": +.P +.in +4n +.EX +"John Q. Doe" +.EE +.in +.SS Abbreviation +Some mail systems let users abbreviate the domain name. +For instance, +users at example.com may get away with "john.doe@monet" to +send mail to John Doe. +.I This behavior is deprecated. +Sometimes it works, but you should not depend on it. +.SS Route-addrs +In the past, sometimes one had to route a message through +several hosts to get it to its final destination. +Addresses which show these relays are termed "route-addrs". +These use the syntax: +.P +.in +4n +.EX +<@hosta,@hostb:user@hostc> +.EE +.in +.P +This specifies that the message should be sent to hosta, +from there to hostb, and finally to hostc. +Many hosts disregard route-addrs and send directly to hostc. +.P +Route-addrs are very unusual now. +They occur sometimes in old mail archives. +It is generally possible to ignore all but the "user@hostc" +part of the address to determine the actual address. +.SS Postmaster +Every site is required to have a user or user alias designated +"postmaster" to which problems with the mail system may be +addressed. +The "postmaster" address is not case sensitive. +.SH FILES +.I /etc/aliases +.br +.I \[ti]/.forward +.SH SEE ALSO +.BR mail (1), +.BR aliases (5), +.BR forward (5), +.BR sendmail (8) +.P +.UR http://www.ietf.org\:/rfc\:/rfc5322.txt +IETF RFC\ 5322 +.UE diff --git a/man/man7/man-pages.7 b/man/man7/man-pages.7 new file mode 100644 index 0000000..14ba7ba --- /dev/null +++ b/man/man7/man-pages.7 @@ -0,0 +1,1227 @@ +'\" t +.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler +.\" (faith@cs.unc.edu and dwheeler@ida.org) +.\" and (C) Copyright 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-05-30 created by mtk, using text from old man.7 plus +.\" rewrites and additional text. +.\" +.TH man-pages 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +man-pages \- conventions for writing Linux man pages +.SH SYNOPSIS +.B man +.RI [ section ] +.I title +.SH DESCRIPTION +This page describes the conventions that should be employed +when writing man pages for the Linux \fIman-pages\fP project, +which documents the user-space API provided by the Linux kernel +and the GNU C library. +The project thus provides most of the pages in Section 2, +many of the pages that appear in Sections 3, 4, and 7, +and a few of the pages that appear in Sections 1, 5, and 8 +of the man pages on a Linux system. +The conventions described on this page may also be useful +for authors writing man pages for other projects. +.SS Sections of the manual pages +The manual Sections are traditionally defined as follows: +.TP +.B 1 User commands (Programs) +Commands that can be executed by the user from within +a shell. +.TP +.B 2 System calls +Functions which wrap operations performed by the kernel. +.TP +.B 3 Library calls +All library functions excluding the system call wrappers +(Most of the +.I libc +functions). +.TP +.B 4 Special files (devices) +Files found in +.I /dev +which allow to access to devices through the kernel. +.TP +.B 5 File formats and configuration files +Describes various human-readable file formats and configuration files. +.TP +.B 6 Games +Games and funny little programs available on the system. +.TP +.B 7 Overview, conventions, and miscellaneous +Overviews or descriptions of various topics, conventions, and protocols, +character set standards, the standard filesystem layout, and miscellaneous +other things. +.TP +.B 8 System management commands +Commands like +.BR mount (8), +many of which only root can execute. +.\" .TP +.\" .B 9 Kernel routines +.\" This is an obsolete manual section. +.\" Once it was thought a good idea to document the Linux kernel here, +.\" but in fact very little has been documented, and the documentation +.\" that exists is outdated already. +.\" There are better sources of +.\" information for kernel developers. +.SS Macro package +New manual pages should be marked up using the +.B groff an.tmac +package described in +.BR man (7). +This choice is mainly for consistency: the vast majority of +existing Linux manual pages are marked up using these macros. +.SS Conventions for source file layout +Please limit source code line length to no more than about 75 characters +wherever possible. +This helps avoid line-wrapping in some mail clients when patches are +submitted inline. +.SS Title line +The first command in a man page should be a +.B TH +command: +.P +.RS +.B \&.TH +.I "title section date source manual-section" +.RE +.P +The arguments of the command are as follows: +.TP +.I title +The title of the man page, written in all caps (e.g., +.IR MAN-PAGES ). +.TP +.I section +The section number in which the man page should be placed (e.g., +.IR 7 ). +.TP +.I date +The date of the last nontrivial change that was made to the man page. +(Within the +.I man-pages +project, the necessary updates to these timestamps are handled +automatically by scripts, so there is no need to manually update +them as part of a patch.) +Dates should be written in the form YYYY-MM-DD. +.TP +.I source +The name and version of the project that provides the manual page +(not necessarily the package that provides the functionality). +.TP +.I manual-section +Normally, this should be empty, +since the default value will be good. +.\" +.SS Sections within a manual page +The list below shows conventional or suggested sections. +Most manual pages should include at least the +.B highlighted +sections. +Arrange a new manual page so that sections +are placed in the order shown in the list. +.P +.RS +.TS +l l. +\fBNAME\fP +LIBRARY [Normally only in Sections 2, 3] +\fBSYNOPSIS\fP +CONFIGURATION [Normally only in Section 4] +\fBDESCRIPTION\fP +OPTIONS [Normally only in Sections 1, 8] +EXIT STATUS [Normally only in Sections 1, 8] +RETURN VALUE [Normally only in Sections 2, 3] +.\" May 07: Few current man pages have an ERROR HANDLING section,,, +.\" ERROR HANDLING, +ERRORS [Typically only in Sections 2, 3] +.\" May 07: Almost no current man pages have a USAGE section,,, +.\" USAGE, +.\" DIAGNOSTICS, +.\" May 07: Almost no current man pages have a SECURITY section,,, +.\" SECURITY, +ENVIRONMENT +FILES +ATTRIBUTES [Normally only in Sections 2, 3] +VERSIONS [Normally only in Sections 2, 3] +STANDARDS +HISTORY +NOTES +CAVEATS +BUGS +EXAMPLES +.\" AUTHORS sections are discouraged +AUTHORS [Discouraged] +REPORTING BUGS [Not used in man-pages] +COPYRIGHT [Not used in man-pages] +\fBSEE ALSO\fP +.TE +.RE +.P +.IR "Where a traditional heading would apply" ", " "please use it" ; +this kind of consistency can make the information easier to understand. +If you must, you can create your own +headings if they make things easier to understand (this can +be especially useful for pages in Sections 4 and 5). +However, before doing this, consider whether you could use the +traditional headings, with some subsections (\fI.SS\fP) within +those sections. +.P +The following list elaborates on the contents of each of +the above sections. +.TP +.B NAME +The name of this manual page. +.IP +See +.BR man (7) +for important details of the line(s) that should follow the +\fB.SH NAME\fP command. +All words in this line (including the word immediately +following the "\e\-") should be in lowercase, +except where English or technical terminological convention +dictates otherwise. +.TP +.B LIBRARY +The library providing a symbol. +.IP +It shows the common name of the library, +and in parentheses, +the name of the library file +and, if needed, the linker flag needed to link a program against it: +.RI ( libfoo "[, " \-lfoo ]). +.TP +.B SYNOPSIS +A brief summary of the command or function's interface. +.IP +For commands, this shows the syntax of the command and its arguments +(including options); +boldface is used for as-is text and italics are used to +indicate replaceable arguments. +Brackets ([]) surround optional arguments, vertical bars (|) +separate choices, and ellipses (\&...) can be repeated. +For functions, it shows any required data declarations or +.B #include +directives, followed by the function declaration. +.IP +Where a feature test macro must be defined in order to obtain +the declaration of a function (or a variable) from a header file, +then the SYNOPSIS should indicate this, as described in +.BR feature_test_macros (7). +.\" FIXME . Say something here about compiler options +.TP +.B CONFIGURATION +Configuration details for a device. +.IP +This section normally appears only in Section 4 pages. +.TP +.B DESCRIPTION +An explanation of what the program, function, or format does. +.IP +Discuss how it interacts with files and standard input, and what it +produces on standard output or standard error. +Omit internals and implementation details unless they're critical for +understanding the interface. +Describe the usual case; +for information on command-line options of a program use the +.B OPTIONS +section. +.\" If there is some kind of input grammar or complex set of subcommands, +.\" consider describing them in a separate +.\" .B USAGE +.\" section (and just place an overview in the +.\" .B DESCRIPTION +.\" section). +.IP +When describing new behavior or new flags for +a system call or library function, +be careful to note the kernel or C library version +that introduced the change. +The preferred method of noting this information for flags is as part of a +.B .TP +list, in the following form (here, for a new system call flag): +.RS 16 +.TP +.BR XYZ_FLAG " (since Linux 3.7)" +Description of flag... +.RE +.IP +Including version information is especially useful to users +who are constrained to using older kernel or C library versions +(which is typical in embedded systems, for example). +.TP +.B OPTIONS +A description of the command-line options accepted by a +program and how they change its behavior. +.IP +This section should appear only for Section 1 and 8 manual pages. +.\" .TP +.\" .B USAGE +.\" describes the grammar of any sublanguage this implements. +.TP +.B EXIT STATUS +A list of the possible exit status values of a program and +the conditions that cause these values to be returned. +.IP +This section should appear only for Section 1 and 8 manual pages. +.TP +.B RETURN VALUE +For Section 2 and 3 pages, this section gives a +list of the values the library routine will return to the caller +and the conditions that cause these values to be returned. +.TP +.B ERRORS +For Section 2 and 3 manual pages, this is a list of the +values that may be placed in +.I errno +in the event of an error, along with information about the cause +of the errors. +.IP +Where several different conditions produce the same error, +the preferred approach is to create separate list entries +(with duplicate error names) for each of the conditions. +This makes the separate conditions clear, may make the list easier to read, +and allows metainformation +(e.g., kernel version number where the condition first became applicable) +to be more easily marked for each condition. +.IP +.IR "The error list should be in alphabetical order" . +.TP +.B ENVIRONMENT +A list of all environment variables that affect the program or function +and how they affect it. +.TP +.B FILES +A list of the files the program or function uses, such as +configuration files, startup files, +and files the program directly operates on. +.IP +Give the full pathname of these files, and use the installation +process to modify the directory part to match user preferences. +For many programs, the default installation location is in +.IR /usr/local , +so your base manual page should use +.I /usr/local +as the base. +.\" May 07: Almost no current man pages have a DIAGNOSTICS section; +.\" "RETURN VALUE" or "EXIT STATUS" is preferred. +.\" .TP +.\" .B DIAGNOSTICS +.\" gives an overview of the most common error messages and how to +.\" cope with them. +.\" You don't need to explain system error messages +.\" or fatal signals that can appear during execution of any program +.\" unless they're special in some way to the program. +.\" +.\" May 07: Almost no current man pages have a SECURITY section. +.\".TP +.\".B SECURITY +.\"discusses security issues and implications. +.\"Warn about configurations or environments that should be avoided, +.\"commands that may have security implications, and so on, especially +.\"if they aren't obvious. +.\"Discussing security in a separate section isn't necessary; +.\"if it's easier to understand, place security information in the +.\"other sections (such as the +.\" .B DESCRIPTION +.\" or +.\" .B USAGE +.\" section). +.\" However, please include security information somewhere! +.TP +.B ATTRIBUTES +A summary of various attributes of the function(s) documented on this page. +See +.BR attributes (7) +for further details. +.TP +.B VERSIONS +A summary of systems where the API performs differently, +or where there's a similar API. +.TP +.B STANDARDS +A description of any standards or conventions that relate to the function +or command described by the manual page. +.IP +The preferred terms to use for the various standards are listed as +headings in +.BR standards (7). +.IP +This section should note the current standards to which the API conforms to. +.IP +If the API is not governed by any standards but commonly +exists on other systems, note them. +If the call is Linux-specific or GNU-specific, note this. +If it's available in the BSDs, note that. +.IP +If this section consists of just a list of standards +(which it commonly does), +terminate the list with a period (\[aq].\[aq]). +.TP +.B HISTORY +A brief summary of the Linux kernel or glibc versions where a +system call or library function appeared, +or changed significantly in its operation. +.IP +As a general rule, every new interface should +include a HISTORY section in its manual page. +Unfortunately, +many existing manual pages don't include this information +(since there was no policy to do so when they were written). +Patches to remedy this are welcome, +but, from the perspective of programmers writing new code, +this information probably matters only in the case of kernel +interfaces that have been added in Linux 2.4 or later +(i.e., changes since Linux 2.2), +and library functions that have been added to glibc since glibc 2.1 +(i.e., changes since glibc 2.0). +.IP +The +.BR syscalls (2) +manual page also provides information about kernel versions +in which various system calls first appeared. +.P +Old versions of standards should be mentioned here, +rather than in STANDARDS, +for example, +SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD implementation standards. +.TP +.B NOTES +Miscellaneous notes. +.IP +For Section 2 and 3 man pages you may find it useful to include +subsections (\fBSS\fP) named \fILinux Notes\fP and \fIglibc Notes\fP. +.IP +In Section 2, use the heading +.I "C library/kernel differences" +to mark off notes that describe the differences (if any) between +the C library wrapper function for a system call and +the raw system call interface provided by the kernel. +.TP +.B CAVEATS +Warnings about typical user misuse of an API, +that don't constitute an API bug or design defect. +.TP +.B BUGS +A list of limitations, known defects or inconveniences, +and other questionable activities. +.TP +.B EXAMPLES +One or more examples demonstrating how this function, file, or +command is used. +.IP +For details on writing example programs, +see \fIExample programs\fP below. +.TP +.B AUTHORS +A list of authors of the documentation or program. +.IP +\fBUse of an AUTHORS section is strongly discouraged\fP. +Generally, it is better not to clutter every page with a list +of (over time potentially numerous) authors; +if you write or significantly amend a page, +add a copyright notice as a comment in the source file. +If you are the author of a device driver and want to include +an address for reporting bugs, place this under the BUGS section. +.TP +.B REPORTING BUGS +The +.I man-pages +project doesn't use a REPORTING BUGS section in manual pages. +Information on reporting bugs is instead supplied in the +script-generated COLOPHON section. +However, various projects do use a REPORTING BUGS section. +It is recommended to place it near the foot of the page. +.TP +.B COPYRIGHT +The +.I man-pages +project doesn't use a COPYRIGHT section in manual pages. +Copyright information is instead maintained in the page source. +In pages where this section is present, +it is recommended to place it near the foot of the page, just above SEE ALSO. +.TP +.B SEE ALSO +A comma-separated list of related man pages, possibly followed by +other related pages or documents. +.IP +The list should be ordered by section number and +then alphabetically by name. +Do not terminate this list with a period. +.IP +Where the SEE ALSO list contains many long manual page names, +to improve the visual result of the output, it may be useful to employ the +.I .ad l +(don't right justify) +and +.I .nh +(don't hyphenate) +directives. +Hyphenation of individual page names can be prevented +by preceding words with the string "\e%". +.IP +Given the distributed, autonomous nature of FOSS projects +and their documentation, it is sometimes necessary\[em]and in many cases +desirable\[em]that the SEE ALSO section includes references to +manual pages provided by other projects. +.SH FORMATTING AND WORDING CONVENTIONS +The following subsections note some details for preferred formatting and +wording conventions in various sections of the pages in the +.I man-pages +project. +.SS SYNOPSIS +Wrap the function prototype(s) in a +.IR .nf / .fi +pair to prevent filling. +.P +In general, where more than one function prototype is shown in the SYNOPSIS, +the prototypes should +.I not +be separated by blank lines. +However, blank lines (achieved using +.IR .P ) +may be added in the following cases: +.IP \[bu] 3 +to separate long lists of function prototypes into related groups +(see for example +.BR list (3)); +.IP \[bu] +in other cases that may improve readability. +.P +In the SYNOPSIS, a long function prototype may need to be +continued over to the next line. +The continuation line is indented according to the following rules: +.IP (1) 5 +If there is a single such prototype that needs to be continued, +then align the continuation line so that when the page is +rendered on a fixed-width font device (e.g., on an xterm) the +continuation line starts just below the start of the argument +list in the line above. +(Exception: the indentation may be +adjusted if necessary to prevent a very long continuation line +or a further continuation line where the function prototype is +very long.) +As an example: +.IP +.in +4n +.nf +.BI "int tcsetattr(int " fd ", int " optional_actions , +.BI " const struct termios *" termios_p ); +.fi +.in +.IP (2) +But, where multiple functions in the SYNOPSIS require +continuation lines, and the function names have different +lengths, then align all continuation lines to start in the +same column. +This provides a nicer rendering in PDF output +(because the SYNOPSIS uses a variable width font where +spaces render narrower than most characters). +As an example: +.IP +.in +4n +.nf +.BI "int getopt(int " argc ", char * const " argv[] , +.BI " const char *" optstring ); +.BI "int getopt_long(int " argc ", char * const " argv[] , +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.fi +.in +.SS RETURN VALUE +The preferred wording to describe how +.I errno +is set is +.RI \[dq] errno +is set to indicate the error" +or similar. +.\" Before man-pages 5.11, many different wordings were used, which +.\" was confusing, and potentially made scripted edits more difficult. +This wording is consistent with the wording used in both POSIX.1 and FreeBSD. +.SS ATTRIBUTES +.\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf +Note the following: +.IP \[bu] 3 +Wrap the table in this section in a +.IR ".ad\ l" / .ad +pair to disable text filling and a +.IR .nh / .hy +pair to disable hyphenation. +.IP \[bu] +Ensure that the table occupies the full page width through the use of an +.I lbx +description for one of the columns +(usually the first column, +though in some cases the last column if it contains a lot of text). +.IP \[bu] +Make free use of +.IR T{ / T} +macro pairs to allow table cells to be broken over multiple lines +(also bearing in mind that pages may sometimes be rendered to a +width of less than 80 columns). +.P +For examples of all of the above, see the source code of various pages. +.SH STYLE GUIDE +The following subsections describe the preferred style for the +.I man-pages +project. +For details not covered below, the Chicago Manual of Style +is usually a good source; +try also grepping for preexisting usage in the project source tree. +.SS Use of gender-neutral language +As far as possible, use gender-neutral language in the text of man +pages. +Use of "they" ("them", "themself", "their") as a gender-neutral singular +pronoun is acceptable. +.\" +.SS Formatting conventions for manual pages describing commands +For manual pages that describe a command (typically in Sections 1 and 8), +the arguments are always specified using italics, +.IR "even in the SYNOPSIS section" . +.P +The name of the command, and its options, should +always be formatted in bold. +.\" +.SS Formatting conventions for manual pages describing functions +For manual pages that describe functions (typically in Sections 2 and 3), +the arguments are always specified using italics, +.IR "even in the SYNOPSIS section" , +where the rest of the function is specified in bold: +.P +.BI " int myfunction(int " argc ", char **" argv ); +.P +Variable names should, like argument names, be specified in italics. +.P +Any reference to the subject of the current manual page +should be written with the name in bold followed by +a pair of parentheses in Roman (normal) font. +For example, in the +.BR fcntl (2) +man page, references to the subject of the page would be written as: +.BR fcntl (). +The preferred way to write this in the source file is: +.P +.EX + .BR fcntl () +.EE +.P +(Using this format, rather than the use of "\efB...\efP()" +makes it easier to write tools that parse man page source files.) +.\" +.SS Use semantic newlines +In the source of a manual page, +new sentences should be started on new lines, +long sentences should be split into lines at clause breaks +(commas, semicolons, colons, and so on), +and long clauses should be split at phrase boundaries. +This convention, sometimes known as "semantic newlines", +makes it easier to see the effect of patches, +which often operate at the level of +individual sentences, clauses, or phrases. +.\" +.SS Lists +There are different kinds of lists: +.TP +Tagged paragraphs +These are used for a list of tags and their descriptions. +When the tags are constants (either macros or numbers) +they are in bold. +Use the +.B .TP +macro. +.IP +An example is this "Tagged paragraphs" subsection is itself. +.TP +Ordered lists +Elements are preceded by a number in parentheses (1), (2). +These represent a set of steps that have an order. +.IP +When there are substeps, +they will be numbered like (4.2). +.TP +Positional lists +Elements are preceded by a number (index) in square brackets [4], [5]. +These represent fields in a set. +The first index will be: +.RS +.TP +.B 0 +When it represents fields of a C data structure, +to be consistent with arrays. +.PD 0 +.TP +.B 1 +When it represents fields of a file, +to be consistent with tools like +.BR cut (1). +.PD +.RE +.TP +Alternatives list +Elements are preceded by a letter in parentheses (a), (b). +These represent a set of (normally) exclusive alternatives. +.TP +Bullet lists +Elements are preceded by bullet symbols +.RB ( \e[bu] ). +Anything that doesn't fit elsewhere is +usually covered by this type of list. +.TP +Numbered notes +Not really a list, +but the syntax is identical to "positional lists". +.P +There should always be exactly +2 spaces between the list symbol and the elements. +This doesn't apply to "tagged paragraphs", +which use the default indentation rules. +.\" +.SS Formatting conventions (general) +Paragraphs should be separated by suitable markers (usually either +.I .P +or +.IR .IP ). +Do +.I not +separate paragraphs using blank lines, as this results in poor rendering +in some output formats (such as PostScript and PDF). +.P +Filenames (whether pathnames, or references to header files) +are always in italics (e.g., +.IR ), +except in the SYNOPSIS section, where included files are in bold (e.g., +.BR "#include " ). +When referring to a standard header file include, +specify the header file surrounded by angle brackets, +in the usual C way (e.g., +.IR ). +.P +Special macros, which are usually in uppercase, are in bold (e.g., +.BR MAXINT ). +Exception: don't boldface NULL. +.P +When enumerating a list of error codes, the codes are in bold (this list +usually uses the +.B \&.TP +macro). +.P +Complete commands should, if long, +be written as an indented line on their own, +with a blank line before and after the command, for example +.P +.in +4n +.EX +man 7 man\-pages +.EE +.in +.P +If the command is short, then it can be included inline in the text, +in italic format, for example, +.IR "man 7 man-pages" . +In this case, it may be worth using nonbreaking spaces +(\e[ti]) at suitable places in the command. +Command options should be written in italics (e.g., +.IR \-l ). +.P +Expressions, if not written on a separate indented line, should +be specified in italics. +Again, the use of nonbreaking spaces may be appropriate +if the expression is inlined with normal text. +.P +When showing example shell sessions, +user input should be formatted in bold, +for example +.P +.in +4n +.EX +$ \fBdate\fP +Thu Jul 7 13:01:27 CEST 2016 +.EE +.in +.P +Any reference to another man page +should be written with the name in bold, +.I always +followed by the section number, +formatted in Roman (normal) font, without any +separating spaces (e.g., +.BR intro (2)). +The preferred way to write this in the source file is: +.P +.EX + .BR intro (2) +.EE +.P +(Including the section number in cross references lets tools like +.BR man2html (1) +create properly hyperlinked pages.) +.P +Control characters should be written in bold face, +with no quotes; for example, +.BR \[ha]X . +.SS Spelling +Starting with release 2.59, +.I man-pages +follows American spelling conventions +(previously, there was a random mix of British and American spellings); +please write all new pages and patches according to these conventions. +.P +Aside from the well-known spelling differences, +there are a few other subtleties to watch for: +.IP \[bu] 3 +American English tends to use the forms "backward", "upward", "toward", +and so on +rather than the British forms "backwards", "upwards", "towards", and so on. +.IP \[bu] +Opinions are divided on "acknowledgement" vs "acknowledgment". +The latter is predominant, but not universal usage in American English. +POSIX and the BSD license use the former spelling. +In the Linux man-pages project, we use "acknowledgement". +.SS BSD version numbers +The classical scheme for writing BSD version numbers is +.IR x.yBSD , +where +.I x.y +is the version number (e.g., 4.2BSD). +Avoid forms such as +.IR "BSD 4.3" . +.SS Capitalization +In subsection ("SS") headings, +capitalize the first word in the heading, but otherwise use lowercase, +except where English usage (e.g., proper nouns) or programming +language requirements (e.g., identifier names) dictate otherwise. +For example: +.P +.in +4n +.EX +\&.SS Unicode under Linux +.EE +.in +.\" +.SS Indentation of structure definitions, shell session logs, and so on +When structure definitions, shell session logs, and so on are included +in running text, indent them by 4 spaces (i.e., a block enclosed by +.I ".in\ +4n" +and +.IR ".in" ), +format them using the +.I .EX +and +.I .EE +macros, and surround them with suitable paragraph markers (either +.I .P +or +.IR .IP ). +For example: +.P +.in +4n +.EX +\&.P +\&.in +4n +\&.EX +int +main(int argc, char *argv[]) +{ + return 0; +} +\&.EE +\&.in +\&.P +.EE +.in +.SS Preferred terms +The following table lists some preferred terms to use in man pages, +mainly to ensure consistency across pages. +.ad l +.TS +l l l +--- +l l ll. +Term Avoid using Notes + +bit mask bitmask +built-in builtin +Epoch epoch T{ +For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC) +T} +filename file name +filesystem file system +hostname host name +inode i-node +lowercase lower case, lower-case +nonzero non-zero +pathname path name +pseudoterminal pseudo-terminal +privileged port T{ +reserved port, +system port +T} +real-time T{ +realtime, +real time +T} +run time runtime +saved set-group-ID T{ +saved group ID, +saved set-GID +T} +saved set-user-ID T{ +saved user ID, +saved set-UID +T} +set-group-ID set-GID, setgid +set-user-ID set-UID, setuid +superuser T{ +super user, +super-user +T} +superblock T{ +super block, +super-block +T} +symbolic link symlink +timestamp time stamp +timezone time zone +uppercase upper case, upper-case +usable useable +user space userspace +username user name +x86-64 x86_64 T{ +Except if referring to result of "uname\ \-m" or similar +T} +zeros zeroes +.TE +.P +See also the discussion +.I Hyphenation of attributive compounds +below. +.SS Terms to avoid +The following table lists some terms to avoid using in man pages, +along with some suggested alternatives, +mainly to ensure consistency across pages. +.ad l +.TS +l l l +--- +l l l. +Avoid Use instead Notes + +32bit 32-bit T{ +same for 8-bit, 16-bit, etc. +T} +current process calling process T{ +A common mistake made by kernel programmers when writing man pages +T} +manpage T{ +man page, manual page +T} +minus infinity negative infinity +non-root unprivileged user +non-superuser unprivileged user +nonprivileged unprivileged +OS operating system +plus infinity positive infinity +pty pseudoterminal +tty terminal +Unices UNIX systems +Unixes UNIX systems +.TE +.ad +.\" +.SS Trademarks +Use the correct spelling and case for trademarks. +The following is a list of the correct spellings of various +relevant trademarks that are sometimes misspelled: +.IP +.TS +l. +DG/UX +HP-UX +UNIX +UnixWare +.TE +.SS NULL, NUL, null pointer, and null byte +A +.I null pointer +is a pointer that points to nothing, +and is normally indicated by the constant +.IR NULL . +On the other hand, +.I NUL +is the +.IR "null byte" , +a byte with the value 0, represented in C via the character constant +.IR \[aq]\e0\[aq] . +.P +The preferred term for the pointer is "null pointer" or simply "NULL"; +avoid writing "NULL pointer". +.P +The preferred term for the byte is "null byte". +Avoid writing "NUL", since it is too easily confused with "NULL". +Avoid also the terms "zero byte" and "null character". +The byte that terminates a C string should be described +as "the terminating null byte"; +strings may be described as "null-terminated", +but avoid the use of "NUL-terminated". +.SS Hyperlinks +For hyperlinks, use the +.IR .UR / .UE +macro pair +(see +.BR groff_man (7)). +This produces proper hyperlinks that can be used in a web browser, +when rendering a page with, say: +.P +.in +4n +.EX +BROWSER=firefox man -H pagename +.EE +.in +.SS Use of e.g., i.e., etc., a.k.a., and similar +In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", +"cf.", and "a.k.a." should be avoided, +in favor of suitable full wordings +("for example", "that is", "and so on", "compare to", "also known as"). +.P +The only place where such abbreviations may be acceptable is in +.I short +parenthetical asides (e.g., like this one). +.P +Always include periods in such abbreviations, as shown here. +In addition, "e.g." and "i.e." should always be followed by a comma. +.SS Em-dashes +The way to write an em-dash\[em]the glyph that appears +at either end of this subphrase\[em]in *roff is with the macro "\e[em]". +(On an ASCII terminal, an em-dash typically renders as two hyphens, +but in other typographical contexts it renders as a long dash.) +Em-dashes should be written +.I without +surrounding spaces. +.SS Hyphenation of attributive compounds +Compound terms should be hyphenated when used attributively +(i.e., to qualify a following noun). Some examples: +.IP +.TS +l. +32-bit value +command-line argument +floating-point number +run-time check +user-space function +wide-character string +.TE +.SS Hyphenation with multi, non, pre, re, sub, and so on +The general tendency in modern English is not to hyphenate +after prefixes such as "multi", "non", "pre", "re", "sub", and so on. +Manual pages should generally follow this rule when these prefixes are +used in natural English constructions with simple suffixes. +The following list gives some examples of the preferred forms: +.IP +.TS +l. +interprocess +multithreaded +multiprocess +nonblocking +nondefault +nonempty +noninteractive +nonnegative +nonportable +nonzero +preallocated +precreate +prerecorded +reestablished +reinitialize +rearm +reread +subcomponent +subdirectory +subsystem +.TE +.P +Hyphens should be retained when the prefixes are used in nonstandard +English words, with trademarks, proper nouns, acronyms, or compound terms. +Some examples: +.IP +.TS +l. +non-ASCII +non-English +non-NULL +non-real-time +.TE +.P +Finally, note that "re-create" and "recreate" are two different verbs, +and the former is probably what you want. +.\" +.SS Generating optimal glyphs +Where a real minus character is required (e.g., for numbers such as \-1, +for man page cross references such as +.BR utf\-8 (7), +or when writing options that have a leading dash, such as in +.IR "ls\ \-l"), +use the following form in the man page source: +.P +.in +4n +.EX +\e\- +.EE +.in +.P +This guideline applies also to code examples. +.P +The use of real minus signs serves the following purposes: +.\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/ +.IP \[bu] 3 +To provide better renderings on various targets other than +ASCII terminals, +notably in PDF and on Unicode/UTF\-8-capable terminals. +.IP \[bu] +To generate glyphs that when copied from rendered pages will +produce real minus signs when pasted into a terminal. +.P +To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, +use "\e[aq]" ("apostrophe quote"); for example +.P +.in +4n +.EX +\e[aq]C\e[aq] +.EE +.in +.P +where +.I C +is the quoted character. +This guideline applies also to character constants used in code examples. +.P +Where a proper caret (\[ha]) that renders well in both a terminal and PDF +is required, use "\\[ha]". +This is especially necessary in code samples, +to get a nicely rendered caret when rendering to PDF. +.P +Using a naked "\[ti]" character results in a poor rendering in PDF. +Instead use "\\[ti]". +This is especially necessary in code samples, +to get a nicely rendered tilde when rendering to PDF. +.\" +.SS Example programs and shell sessions +Manual pages may include example programs demonstrating how to +use a system call or library function. +However, note the following: +.IP \[bu] 3 +Example programs should be written in C. +.IP \[bu] +An example program is necessary and useful only if it demonstrates +something beyond what can easily be provided in a textual +description of the interface. +An example program that does nothing +other than call an interface usually serves little purpose. +.IP \[bu] +Example programs should ideally be short +(e.g., a good example can often be provided in less than 100 lines of code), +though in some cases longer programs may be necessary +to properly illustrate the use of an API. +.IP \[bu] +Expressive code is appreciated. +.IP \[bu] +Comments should included where helpful. +Complete sentences in free-standing comments should be +terminated by a period. +Periods should generally be omitted in "tag" comments +(i.e., comments that are placed on the same line of code); +such comments are in any case typically brief phrases +rather than complete sentences. +.IP \[bu] +Example programs should do error checking after system calls and +library function calls. +.IP \[bu] +Example programs should be complete, and compile without +warnings when compiled with \fIcc\ \-Wall\fP. +.IP \[bu] +Where possible and appropriate, example programs should allow +experimentation, by varying their behavior based on inputs +(ideally from command-line arguments, or alternatively, via +input read by the program). +.IP \[bu] +Example programs should be laid out according to Kernighan and +Ritchie style, with 4-space indents. +(Avoid the use of TAB characters in source code!) +The following command can be used to format your source code to +something close to the preferred style: +.IP +.in +4n +.EX +indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c +.EE +.in +.IP \[bu] +For consistency, all example programs should terminate using either of: +.IP +.in +4n +.EX +exit(EXIT_SUCCESS); +exit(EXIT_FAILURE); +.EE +.in +.IP +Avoid using the following forms to terminate a program: +.IP +.in +4n +.EX +exit(0); +exit(1); +return n; +.EE +.in +.IP \[bu] +If there is extensive explanatory text before the +program source code, mark off the source code +with a subsection heading +.IR "Program source" , +as in: +.IP +.in +4n +.EX +\&.SS Program source +.EE +.in +.IP +Always do this if the explanatory text includes a shell session log. +.P +If you include a shell session log demonstrating the use of a program +or other system feature: +.IP \[bu] 3 +Place the session log above the source code listing. +.IP \[bu] +Indent the session log by four spaces. +.IP \[bu] +Boldface the user input text, +to distinguish it from output produced by the system. +.P +For some examples of what example programs should look like, see +.BR wait (2) +and +.BR pipe (2). +.SH EXAMPLES +For canonical examples of how man pages in the +.I man-pages +package should look, see +.BR pipe (2) +and +.BR fcntl (2). +.SH SEE ALSO +.BR man (1), +.BR man2html (1), +.BR attributes (7), +.BR groff (7), +.BR groff_man (7), +.BR man (7), +.BR mdoc (7) diff --git a/man/man7/man.7 b/man/man7/man.7 new file mode 100644 index 0000000..f460f4a --- /dev/null +++ b/man/man7/man.7 @@ -0,0 +1 @@ +.so man7/groff_man.7 diff --git a/man/man7/math_error.7 b/man/man7/math_error.7 new file mode 100644 index 0000000..9c7fa9e --- /dev/null +++ b/man/man7/math_error.7 @@ -0,0 +1,246 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH math_error 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +math_error \- detecting errors from mathematical functions +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.fi +.SH DESCRIPTION +When an error occurs, +most library functions indicate this fact by returning a special value +(e.g., \-1 or NULL). +Because they typically return a floating-point number, +the mathematical functions declared in +.I +indicate an error using other mechanisms. +There are two error-reporting mechanisms: +the older one sets +.IR errno ; +the newer one uses the floating-point exception mechanism (the use of +.BR feclearexcept (3) +and +.BR fetestexcept (3), +as outlined below) +described in +.BR fenv (3). +.P +A portable program that needs to check for an error from a mathematical +function should set +.I errno +to zero, and make the following call +.P +.in +4n +.EX +feclearexcept(FE_ALL_EXCEPT); +.EE +.in +.P +before calling a mathematical function. +.P +Upon return from the mathematical function, if +.I errno +is nonzero, or the following call (see +.BR fenv (3)) +returns nonzero +.P +.in +4n +.EX +fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | + FE_UNDERFLOW); +.EE +.in +.P +.\" enum +.\" { +.\" FE_INVALID = 0x01, +.\" __FE_DENORM = 0x02, +.\" FE_DIVBYZERO = 0x04, +.\" FE_OVERFLOW = 0x08, +.\" FE_UNDERFLOW = 0x10, +.\" FE_INEXACT = 0x20 +.\" }; +then an error occurred in the mathematical function. +.P +The error conditions that can occur for mathematical functions +are described below. +.SS Domain error +A +.I domain error +occurs when a mathematical function is supplied with an argument whose +value falls outside the domain for which the function +is defined (e.g., giving a negative argument to +.BR log (3)). +When a domain error occurs, +math functions commonly return a NaN +(though some functions return a different value in this case); +.I errno +is set to +.BR EDOM , +and an "invalid" +.RB ( FE_INVALID ) +floating-point exception is raised. +.SS Pole error +A +.I pole error +occurs when the mathematical result of a function is an exact infinity +(e.g., the logarithm of 0 is negative infinity). +When a pole error occurs, +the function returns the (signed) value +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +depending on whether the function result type is +.IR double , +.IR float , +or +.IR "long double" . +The sign of the result is that which is mathematically correct for +the function. +.I errno +is set to +.BR ERANGE , +and a "divide-by-zero" +.RB ( FE_DIVBYZERO ) +floating-point exception is raised. +.SS Range error +A +.I range error +occurs when the magnitude of the function result means that it +cannot be represented in the result type of the function. +The return value of the function depends on whether the range error +was an overflow or an underflow. +.P +A floating result +.I overflows +if the result is finite, +but is too large to represented in the result type. +When an overflow occurs, +the function returns the value +.BR HUGE_VAL , +.BR HUGE_VALF , +or +.BR HUGE_VALL , +depending on whether the function result type is +.IR double , +.IR float , +or +.IR "long double" . +.I errno +is set to +.BR ERANGE , +and an "overflow" +.RB ( FE_OVERFLOW ) +floating-point exception is raised. +.P +A floating result +.I underflows +if the result is too small to be represented in the result type. +If an underflow occurs, +a mathematical function typically returns 0.0 +(C99 says a function shall return "an implementation-defined value +whose magnitude is no greater than the smallest normalized +positive number in the specified type"). +.I errno +may be set to +.BR ERANGE , +and an "underflow" +.RB ( FE_UNDERFLOW ) +floating-point exception may be raised. +.P +Some functions deliver a range error if the supplied argument value, +or the correct function result, would be +.IR subnormal . +A subnormal value is one that is nonzero, +but with a magnitude that is so small that +it can't be presented in normalized form +(i.e., with a 1 in the most significant bit of the significand). +The representation of a subnormal number will contain one +or more leading zeros in the significand. +.SH NOTES +The +.I math_errhandling +identifier specified by C99 and POSIX.1 is not supported by glibc. +.\" See CONFORMANCE in the glibc 2.8 (and earlier) source. +This identifier is supposed to indicate which of the two +error-notification mechanisms +.RI ( errno , +exceptions retrievable via +.BR fetestexcept (3)) +is in use. +The standards require that at least one be in use, +but permit both to be available. +The current (glibc 2.8) situation under glibc is messy. +Most (but not all) functions raise exceptions on errors. +Some also set +.IR errno . +A few functions set +.IR errno , +but don't raise an exception. +A very few functions do neither. +See the individual manual pages for details. +.P +To avoid the complexities of using +.I errno +and +.BR fetestexcept (3) +for error checking, +it is often advised that one should instead check for bad argument +values before each call. +.\" http://www.securecoding.cert.org/confluence/display/seccode/FLP32-C.+Prevent+or+detect+domain+and+range+errors+in+math+functions +For example, the following code ensures that +.BR log (3)'s +argument is not a NaN and is not zero (a pole error) or +less than zero (a domain error): +.P +.in +4n +.EX +double x, r; +\& +if (isnan(x) || islessequal(x, 0)) { + /* Deal with NaN / pole error / domain error */ +} +\& +r = log(x); +.EE +.in +.P +The discussion on this page does not apply to the complex +mathematical functions (i.e., those declared by +.IR ), +which in general are not required to return errors by C99 +and POSIX.1. +.P +The +.BR gcc (1) +.I "\-fno\-math\-errno" +option causes the executable to employ implementations of some +mathematical functions that are faster than the standard +implementations, but do not set +.I errno +on error. +(The +.BR gcc (1) +.I "\-ffast\-math" +option also enables +.IR "\-fno\-math\-errno" .) +An error can still be tested for using +.BR fetestexcept (3). +.SH SEE ALSO +.BR gcc (1), +.BR errno (3), +.BR fenv (3), +.BR fpclassify (3), +.BR INFINITY (3), +.BR isgreater (3), +.BR matherr (3), +.BR nan (3) +.P +.I "info libc" diff --git a/man/man7/mount_namespaces.7 b/man/man7/mount_namespaces.7 new file mode 100644 index 0000000..d7514a9 --- /dev/null +++ b/man/man7/mount_namespaces.7 @@ -0,0 +1,1371 @@ +'\" t +.\" Copyright (c) 2016, 2019, 2021 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH mount_namespaces 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mount_namespaces \- overview of Linux mount namespaces +.SH DESCRIPTION +For an overview of namespaces, see +.BR namespaces (7). +.P +Mount namespaces provide isolation of the list of mounts seen +by the processes in each namespace instance. +Thus, the processes in each of the mount namespace instances +will see distinct single-directory hierarchies. +.P +The views provided by the +.IR /proc/ pid /mounts , +.IR /proc/ pid /mountinfo , +and +.IR /proc/ pid /mountstats +files (all described in +.BR proc (5)) +correspond to the mount namespace in which the process with the PID +.I pid +resides. +(All of the processes that reside in the same mount namespace +will see the same view in these files.) +.P +A new mount namespace is created using either +.BR clone (2) +or +.BR unshare (2) +with the +.B CLONE_NEWNS +flag. +When a new mount namespace is created, +its mount list is initialized as follows: +.IP \[bu] 3 +If the namespace is created using +.BR clone (2), +the mount list of the child's namespace is a copy +of the mount list in the parent process's mount namespace. +.IP \[bu] +If the namespace is created using +.BR unshare (2), +the mount list of the new namespace is a copy of +the mount list in the caller's previous mount namespace. +.P +Subsequent modifications to the mount list +.RB ( mount (2) +and +.BR umount (2)) +in either mount namespace will not (by default) affect the +mount list seen in the other namespace +(but see the following discussion of shared subtrees). +.\" +.SH SHARED SUBTREES +After the implementation of mount namespaces was completed, +experience showed that the isolation that they provided was, +in some cases, too great. +For example, in order to make a newly loaded optical disk +available in all mount namespaces, +a mount operation was required in each namespace. +For this use case, and others, +the shared subtree feature was introduced in Linux 2.6.15. +This feature allows for automatic, controlled propagation of +.BR mount (2) +and +.BR umount (2) +.I events +between namespaces +(or, more precisely, between the mounts that are members of a +.I peer group +that are propagating events to one another). +.P +Each mount is marked (via +.BR mount (2)) +as having one of the following +.IR "propagation types" : +.TP +.B MS_SHARED +This mount shares events with members of a peer group. +.BR mount (2) +and +.BR umount (2) +events immediately under this mount will propagate +to the other mounts that are members of the peer group. +.I Propagation +here means that the same +.BR mount (2) +or +.BR umount (2) +will automatically occur +under all of the other mounts in the peer group. +Conversely, +.BR mount (2) +and +.BR umount (2) +events that take place under +peer mounts will propagate to this mount. +.TP +.B MS_PRIVATE +This mount is private; it does not have a peer group. +.BR mount (2) +and +.BR umount (2) +events do not propagate into or out of this mount. +.TP +.B MS_SLAVE +.BR mount (2) +and +.BR umount (2) +events propagate into this mount from +a (master) shared peer group. +.BR mount (2) +and +.BR umount (2) +events under this mount do not propagate to any peer. +.IP +Note that a mount can be the slave of another peer group +while at the same time sharing +.BR mount (2) +and +.BR umount (2) +events +with a peer group of which it is a member. +(More precisely, one peer group can be the slave of another peer group.) +.TP +.B MS_UNBINDABLE +This is like a private mount, +and in addition this mount can't be bind mounted. +Attempts to bind mount this mount +.RB ( mount (2) +with the +.B MS_BIND +flag) will fail. +.IP +When a recursive bind mount +.RB ( mount (2) +with the +.B MS_BIND +and +.B MS_REC +flags) is performed on a directory subtree, +any bind mounts within the subtree are automatically pruned +(i.e., not replicated) +when replicating that subtree to produce the target subtree. +.P +For a discussion of the propagation type assigned to a new mount, +see NOTES. +.P +The propagation type is a per-mount-point setting; +some mounts may be marked as shared +(with each shared mount being a member of a distinct peer group), +while others are private +(or slaved or unbindable). +.P +Note that a mount's propagation type determines whether +.BR mount (2) +and +.BR umount (2) +of mounts +.I immediately under +the mount are propagated. +Thus, the propagation type does not affect propagation of events for +grandchildren and further removed descendant mounts. +What happens if the mount itself is unmounted is determined by +the propagation type that is in effect for the +.I parent +of the mount. +.P +Members are added to a +.I peer group +when a mount is marked as shared and either: +.IP (a) 5 +the mount is replicated during the creation of a new mount namespace; or +.IP (b) +a new bind mount is created from the mount. +.P +In both of these cases, the new mount joins the peer group +of which the existing mount is a member. +.P +A new peer group is also created when a child mount is created under +an existing mount that is marked as shared. +In this case, the new child mount is also marked as shared and +the resulting peer group consists of all the mounts +that are replicated under the peers of parent mounts. +.P +A mount ceases to be a member of a peer group when either +the mount is explicitly unmounted, +or when the mount is implicitly unmounted because a mount namespace is removed +(because it has no more member processes). +.P +The propagation type of the mounts in a mount namespace +can be discovered via the "optional fields" exposed in +.IR /proc/ pid /mountinfo . +(See +.BR proc (5) +for details of this file.) +The following tags can appear in the optional fields +for a record in that file: +.TP +.I shared:X +This mount is shared in peer group +.IR X . +Each peer group has a unique ID that is automatically +generated by the kernel, +and all mounts in the same peer group will show the same ID. +(These IDs are assigned starting from the value 1, +and may be recycled when a peer group ceases to have any members.) +.TP +.I master:X +This mount is a slave to shared peer group +.IR X . +.TP +.IR propagate_from:X " (since Linux 2.6.26)" +.\" commit 97e7e0f71d6d948c25f11f0a33878d9356d9579e +This mount is a slave and receives propagation from shared peer group +.IR X . +This tag will always appear in conjunction with a +.I master:X +tag. +Here, +.I X +is the closest dominant peer group under the process's root directory. +If +.I X +is the immediate master of the mount, +or if there is no dominant peer group under the same root, +then only the +.I master:X +field is present and not the +.I propagate_from:X +field. +For further details, see below. +.TP +.I unbindable +This is an unbindable mount. +.P +If none of the above tags is present, then this is a private mount. +.SS MS_SHARED and MS_PRIVATE example +Suppose that on a terminal in the initial mount namespace, +we mark one mount as shared and another as private, +and then view the mounts in +.IR /proc/self/mountinfo : +.P +.in +4n +.EX +sh1# \fBmount \-\-make\-shared /mntS\fP +sh1# \fBmount \-\-make\-private /mntP\fP +sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +77 61 8:17 / /mntS rw,relatime shared:1 +83 61 8:15 / /mntP rw,relatime +.EE +.in +.P +From the +.I /proc/self/mountinfo +output, we see that +.I /mntS +is a shared mount in peer group 1, and that +.I /mntP +has no optional tags, indicating that it is a private mount. +The first two fields in each record in this file are the unique +ID for this mount, and the mount ID of the parent mount. +We can further inspect this file to see that the parent mount of +.I /mntS +and +.I /mntP +is the root directory, +.IR / , +which is mounted as private: +.P +.in +4n +.EX +sh1# \fBcat /proc/self/mountinfo | awk \[aq]$1 == 61\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +61 0 8:2 / / rw,relatime +.EE +.in +.P +On a second terminal, +we create a new mount namespace where we run a second shell +and inspect the mounts: +.P +.in +4n +.EX +$ \fBPS1=\[aq]sh2# \[aq] sudo unshare \-m \-\-propagation unchanged sh\fP +sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +222 145 8:17 / /mntS rw,relatime shared:1 +225 145 8:15 / /mntP rw,relatime +.EE +.in +.P +The new mount namespace received a copy of the initial mount namespace's +mounts. +These new mounts maintain the same propagation types, +but have unique mount IDs. +(The +.I \-\-propagation\~unchanged +option prevents +.BR unshare (1) +from marking all mounts as private when creating a new mount namespace, +.\" Since util-linux 2.27 +which it does by default.) +.P +In the second terminal, we then create submounts under each of +.I /mntS +and +.I /mntP +and inspect the set-up: +.P +.in +4n +.EX +sh2# \fBmkdir /mntS/a\fP +sh2# \fBmount /dev/sdb6 /mntS/a\fP +sh2# \fBmkdir /mntP/b\fP +sh2# \fBmount /dev/sdb7 /mntP/b\fP +sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +222 145 8:17 / /mntS rw,relatime shared:1 +225 145 8:15 / /mntP rw,relatime +178 222 8:22 / /mntS/a rw,relatime shared:2 +230 225 8:23 / /mntP/b rw,relatime +.EE +.in +.P +From the above, it can be seen that +.I /mntS/a +was created as shared (inheriting this setting from its parent mount) and +.I /mntP/b +was created as a private mount. +.P +Returning to the first terminal and inspecting the set-up, +we see that the new mount created under the shared mount +.I /mntS +propagated to its peer mount (in the initial mount namespace), +but the new mount created under the private mount +.I /mntP +did not propagate: +.P +.in +4n +.EX +sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +77 61 8:17 / /mntS rw,relatime shared:1 +83 61 8:15 / /mntP rw,relatime +179 77 8:22 / /mntS/a rw,relatime shared:2 +.EE +.in +.\" +.SS MS_SLAVE example +Making a mount a slave allows it to receive propagated +.BR mount (2) +and +.BR umount (2) +events from a master shared peer group, +while preventing it from propagating events to that master. +This is useful if we want to (say) receive a mount event when +an optical disk is mounted in the master shared peer group +(in another mount namespace), +but want to prevent +.BR mount (2) +and +.BR umount (2) +events under the slave mount +from having side effects in other namespaces. +.P +We can demonstrate the effect of slaving by first marking +two mounts as shared in the initial mount namespace: +.P +.in +4n +.EX +sh1# \fBmount \-\-make\-shared /mntX\fP +sh1# \fBmount \-\-make\-shared /mntY\fP +sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +132 83 8:23 / /mntX rw,relatime shared:1 +133 83 8:22 / /mntY rw,relatime shared:2 +.EE +.in +.P +On a second terminal, +we create a new mount namespace and inspect the mounts: +.P +.in +4n +.EX +sh2# \fBunshare \-m \-\-propagation unchanged sh\fP +sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +168 167 8:23 / /mntX rw,relatime shared:1 +169 167 8:22 / /mntY rw,relatime shared:2 +.EE +.in +.P +In the new mount namespace, we then mark one of the mounts as a slave: +.P +.in +4n +.EX +sh2# \fBmount \-\-make\-slave /mntY\fP +sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +168 167 8:23 / /mntX rw,relatime shared:1 +169 167 8:22 / /mntY rw,relatime master:2 +.EE +.in +.P +From the above output, we see that +.I /mntY +is now a slave mount that is receiving propagation events from +the shared peer group with the ID 2. +.P +Continuing in the new namespace, we create submounts under each of +.I /mntX +and +.IR /mntY : +.P +.in +4n +.EX +sh2# \fBmkdir /mntX/a\fP +sh2# \fBmount /dev/sda3 /mntX/a\fP +sh2# \fBmkdir /mntY/b\fP +sh2# \fBmount /dev/sda5 /mntY/b\fP +.EE +.in +.P +When we inspect the state of the mounts in the new mount namespace, +we see that +.I /mntX/a +was created as a new shared mount +(inheriting the "shared" setting from its parent mount) and +.I /mntY/b +was created as a private mount: +.P +.in +4n +.EX +sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +168 167 8:23 / /mntX rw,relatime shared:1 +169 167 8:22 / /mntY rw,relatime master:2 +173 168 8:3 / /mntX/a rw,relatime shared:3 +175 169 8:5 / /mntY/b rw,relatime +.EE +.in +.P +Returning to the first terminal (in the initial mount namespace), +we see that the mount +.I /mntX/a +propagated to the peer (the shared +.IR /mntX ), +but the mount +.I /mntY/b +was not propagated: +.P +.in +4n +.EX +sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +132 83 8:23 / /mntX rw,relatime shared:1 +133 83 8:22 / /mntY rw,relatime shared:2 +174 132 8:3 / /mntX/a rw,relatime shared:3 +.EE +.in +.P +Now we create a new mount under +.I /mntY +in the first shell: +.P +.in +4n +.EX +sh1# \fBmkdir /mntY/c\fP +sh1# \fBmount /dev/sda1 /mntY/c\fP +sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +132 83 8:23 / /mntX rw,relatime shared:1 +133 83 8:22 / /mntY rw,relatime shared:2 +174 132 8:3 / /mntX/a rw,relatime shared:3 +178 133 8:1 / /mntY/c rw,relatime shared:4 +.EE +.in +.P +When we examine the mounts in the second mount namespace, +we see that in this case the new mount has been propagated +to the slave mount, +and that the new mount is itself a slave mount (to peer group 4): +.P +.in +4n +.EX +sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +168 167 8:23 / /mntX rw,relatime shared:1 +169 167 8:22 / /mntY rw,relatime master:2 +173 168 8:3 / /mntX/a rw,relatime shared:3 +175 169 8:5 / /mntY/b rw,relatime +179 169 8:1 / /mntY/c rw,relatime master:4 +.EE +.in +.\" +.SS MS_UNBINDABLE example +One of the primary purposes of unbindable mounts is to avoid +the "mount explosion" problem when repeatedly performing bind mounts +of a higher-level subtree at a lower-level mount. +The problem is illustrated by the following shell session. +.P +Suppose we have a system with the following mounts: +.P +.in +4n +.EX +# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP +/dev/sda1 on / +/dev/sdb6 on /mntX +/dev/sdb7 on /mntY +.EE +.in +.P +Suppose furthermore that we wish to recursively bind mount +the root directory under several users' home directories. +We do this for the first user, and inspect the mounts: +.P +.in +4n +.EX +# \fBmount \-\-rbind / /home/cecilia/\fP +# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP +/dev/sda1 on / +/dev/sdb6 on /mntX +/dev/sdb7 on /mntY +/dev/sda1 on /home/cecilia +/dev/sdb6 on /home/cecilia/mntX +/dev/sdb7 on /home/cecilia/mntY +.EE +.in +.P +When we repeat this operation for the second user, +we start to see the explosion problem: +.P +.in +4n +.EX +# \fBmount \-\-rbind / /home/henry\fP +# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP +/dev/sda1 on / +/dev/sdb6 on /mntX +/dev/sdb7 on /mntY +/dev/sda1 on /home/cecilia +/dev/sdb6 on /home/cecilia/mntX +/dev/sdb7 on /home/cecilia/mntY +/dev/sda1 on /home/henry +/dev/sdb6 on /home/henry/mntX +/dev/sdb7 on /home/henry/mntY +/dev/sda1 on /home/henry/home/cecilia +/dev/sdb6 on /home/henry/home/cecilia/mntX +/dev/sdb7 on /home/henry/home/cecilia/mntY +.EE +.in +.P +Under +.IR /home/henry , +we have not only recursively added the +.I /mntX +and +.I /mntY +mounts, but also the recursive mounts of those directories under +.I /home/cecilia +that were created in the previous step. +Upon repeating the step for a third user, +it becomes obvious that the explosion is exponential in nature: +.P +.in +4n +.EX +# \fBmount \-\-rbind / /home/otto\fP +# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP +/dev/sda1 on / +/dev/sdb6 on /mntX +/dev/sdb7 on /mntY +/dev/sda1 on /home/cecilia +/dev/sdb6 on /home/cecilia/mntX +/dev/sdb7 on /home/cecilia/mntY +/dev/sda1 on /home/henry +/dev/sdb6 on /home/henry/mntX +/dev/sdb7 on /home/henry/mntY +/dev/sda1 on /home/henry/home/cecilia +/dev/sdb6 on /home/henry/home/cecilia/mntX +/dev/sdb7 on /home/henry/home/cecilia/mntY +/dev/sda1 on /home/otto +/dev/sdb6 on /home/otto/mntX +/dev/sdb7 on /home/otto/mntY +/dev/sda1 on /home/otto/home/cecilia +/dev/sdb6 on /home/otto/home/cecilia/mntX +/dev/sdb7 on /home/otto/home/cecilia/mntY +/dev/sda1 on /home/otto/home/henry +/dev/sdb6 on /home/otto/home/henry/mntX +/dev/sdb7 on /home/otto/home/henry/mntY +/dev/sda1 on /home/otto/home/henry/home/cecilia +/dev/sdb6 on /home/otto/home/henry/home/cecilia/mntX +/dev/sdb7 on /home/otto/home/henry/home/cecilia/mntY +.EE +.in +.P +The mount explosion problem in the above scenario can be avoided +by making each of the new mounts unbindable. +The effect of doing this is that recursive mounts of the root +directory will not replicate the unbindable mounts. +We make such a mount for the first user: +.P +.in +4n +.EX +# \fBmount \-\-rbind \-\-make\-unbindable / /home/cecilia\fP +.EE +.in +.P +Before going further, we show that unbindable mounts are indeed unbindable: +.P +.in +4n +.EX +# \fBmkdir /mntZ\fP +# \fBmount \-\-bind /home/cecilia /mntZ\fP +mount: wrong fs type, bad option, bad superblock on /home/cecilia, + missing codepage or helper program, or other error +\& + In some cases useful info is found in syslog \- try + dmesg | tail or so. +.EE +.in +.P +Now we create unbindable recursive bind mounts for the other two users: +.P +.in +4n +.EX +# \fBmount \-\-rbind \-\-make\-unbindable / /home/henry\fP +# \fBmount \-\-rbind \-\-make\-unbindable / /home/otto\fP +.EE +.in +.P +Upon examining the list of mounts, +we see there has been no explosion of mounts, +because the unbindable mounts were not replicated +under each user's directory: +.P +.in +4n +.EX +# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP +/dev/sda1 on / +/dev/sdb6 on /mntX +/dev/sdb7 on /mntY +/dev/sda1 on /home/cecilia +/dev/sdb6 on /home/cecilia/mntX +/dev/sdb7 on /home/cecilia/mntY +/dev/sda1 on /home/henry +/dev/sdb6 on /home/henry/mntX +/dev/sdb7 on /home/henry/mntY +/dev/sda1 on /home/otto +/dev/sdb6 on /home/otto/mntX +/dev/sdb7 on /home/otto/mntY +.EE +.in +.\" +.SS Propagation type transitions +The following table shows the effect that applying a new propagation type +(i.e., +.IR mount\~\-\-make\-xxxx ) +has on the existing propagation type of a mount. +The rows correspond to existing propagation types, +and the columns are the new propagation settings. +For reasons of space, "private" is abbreviated as "priv" and +"unbindable" as "unbind". +.TS +lb2 lb2 lb2 lb2 lb1 +lb | l l l l l. + make-shared make-slave make-priv make-unbind +_ +shared shared slave/priv [1] priv unbind +slave slave+shared slave [2] priv unbind +slave+shared slave+shared slave priv unbind +private shared priv [2] priv unbind +unbindable shared unbind [2] priv unbind +.TE +.P +Note the following details to the table: +.IP [1] 5 +If a shared mount is the only mount in its peer group, +making it a slave automatically makes it private. +.IP [2] +Slaving a nonshared mount has no effect on the mount. +.\" +.SS Bind (MS_BIND) semantics +Suppose that the following command is performed: +.P +.in +4n +.EX +mount \-\-bind A/a B/b +.EE +.in +.P +Here, +.I A +is the source mount, +.I B +is the destination mount, +.I a +is a subdirectory path under the mount point +.IR A , +and +.I b +is a subdirectory path under the mount point +.IR B . +The propagation type of the resulting mount, +.IR B/b , +depends on the propagation types of the mounts +.I A +and +.IR B , +and is summarized in the following table. +.P +.TS +lb2 lb1 lb2 lb2 lb2 lb0 +lb2 lb1 lb2 lb2 lb2 lb0 +lb lb | l l l l l. + source(A) + shared private slave unbind +_ +dest(B) shared shared shared slave+shared invalid + nonshared shared private slave invalid +.TE +.P +Note that a recursive bind of a subtree follows the same semantics +as for a bind operation on each mount in the subtree. +(Unbindable mounts are automatically pruned at the target mount point.) +.P +For further details, see +.I Documentation/filesystems/sharedsubtree.rst +in the kernel source tree. +.\" +.SS Move (MS_MOVE) semantics +Suppose that the following command is performed: +.P +.in +4n +.EX +mount \-\-move A B/b +.EE +.in +.P +Here, +.I A +is the source mount, +.I B +is the destination mount, and +.I b +is a subdirectory path under the mount point +.IR B . +The propagation type of the resulting mount, +.IR B/b , +depends on the propagation types of the mounts +.I A +and +.IR B , +and is summarized in the following table. +.P +.TS +lb2 lb1 lb2 lb2 lb2 lb0 +lb2 lb1 lb2 lb2 lb2 lb0 +lb lb | l l l l l. + source(A) + shared private slave unbind +_ +dest(B) shared shared shared slave+shared invalid + nonshared shared private slave unbindable +.TE +.P +Note: moving a mount that resides under a shared mount is invalid. +.P +For further details, see +.I Documentation/filesystems/sharedsubtree.rst +in the kernel source tree. +.\" +.SS Mount semantics +Suppose that we use the following command to create a mount: +.P +.in +4n +.EX +mount device B/b +.EE +.in +.P +Here, +.I B +is the destination mount, and +.I b +is a subdirectory path under the mount point +.IR B . +The propagation type of the resulting mount, +.IR B/b , +follows the same rules as for a bind mount, +where the propagation type of the source mount +is considered always to be private. +.\" +.SS Unmount semantics +Suppose that we use the following command to tear down a mount: +.P +.in +4n +.EX +umount A +.EE +.in +.P +Here, +.I A +is a mount on +.IR B/b , +where +.I B +is the parent mount and +.I b +is a subdirectory path under the mount point +.IR B . +If +.B B +is shared, then all most-recently-mounted mounts at +.I b +on mounts that receive propagation from mount +.I B +and do not have submounts under them are unmounted. +.\" +.SS The /proc/ pid /mountinfo "propagate_from" tag +The +.I propagate_from:X +tag is shown in the optional fields of a +.IR /proc/ pid /mountinfo +record in cases where a process can't see a slave's immediate master +(i.e., the pathname of the master is not reachable from +the filesystem root directory) +and so cannot determine the +chain of propagation between the mounts it can see. +.P +In the following example, we first create a two-link master-slave chain +between the mounts +.IR /mnt , +.IR /tmp/etc , +and +.IR /mnt/tmp/etc . +Then the +.BR chroot (1) +command is used to make the +.I /tmp/etc +mount point unreachable from the root directory, +creating a situation where the master of +.I /mnt/tmp/etc +is not reachable from the (new) root directory of the process. +.P +First, we bind mount the root directory onto +.I /mnt +and then bind mount +.I /proc +at +.I /mnt/proc +so that after the later +.BR chroot (1) +the +.BR proc (5) +filesystem remains visible at the correct location +in the chroot-ed environment. +.P +.in +4n +.EX +# \fBmkdir \-p /mnt/proc\fP +# \fBmount \-\-bind / /mnt\fP +# \fBmount \-\-bind /proc /mnt/proc\fP +.EE +.in +.P +Next, we ensure that the +.I /mnt +mount is a shared mount in a new peer group (with no peers): +.P +.in +4n +.EX +# \fBmount \-\-make\-private /mnt\fP # Isolate from any previous peer group +# \fBmount \-\-make\-shared /mnt\fP +# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +239 61 8:2 / /mnt ... shared:102 +248 239 0:4 / /mnt/proc ... shared:5 +.EE +.in +.P +Next, we bind mount +.I /mnt/etc +onto +.IR /tmp/etc : +.P +.in +4n +.EX +# \fBmkdir \-p /tmp/etc\fP +# \fBmount \-\-bind /mnt/etc /tmp/etc\fP +# \fBcat /proc/self/mountinfo | egrep \[aq]/mnt|/tmp/\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +239 61 8:2 / /mnt ... shared:102 +248 239 0:4 / /mnt/proc ... shared:5 +267 40 8:2 /etc /tmp/etc ... shared:102 +.EE +.in +.P +Initially, these two mounts are in the same peer group, +but we then make the +.I /tmp/etc +a slave of +.IR /mnt/etc , +and then make +.I /tmp/etc +shared as well, +so that it can propagate events to the next slave in the chain: +.P +.in +4n +.EX +# \fBmount \-\-make\-slave /tmp/etc\fP +# \fBmount \-\-make\-shared /tmp/etc\fP +# \fBcat /proc/self/mountinfo | egrep \[aq]/mnt|/tmp/\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +239 61 8:2 / /mnt ... shared:102 +248 239 0:4 / /mnt/proc ... shared:5 +267 40 8:2 /etc /tmp/etc ... shared:105 master:102 +.EE +.in +.P +Then we bind mount +.I /tmp/etc +onto +.IR /mnt/tmp/etc . +Again, the two mounts are initially in the same peer group, +but we then make +.I /mnt/tmp/etc +a slave of +.IR /tmp/etc : +.P +.in +4n +.EX +# \fBmkdir \-p /mnt/tmp/etc\fP +# \fBmount \-\-bind /tmp/etc /mnt/tmp/etc\fP +# \fBmount \-\-make\-slave /mnt/tmp/etc\fP +# \fBcat /proc/self/mountinfo | egrep \[aq]/mnt|/tmp/\[aq] | sed \[aq]s/ \- .*//\[aq]\fP +239 61 8:2 / /mnt ... shared:102 +248 239 0:4 / /mnt/proc ... shared:5 +267 40 8:2 /etc /tmp/etc ... shared:105 master:102 +273 239 8:2 /etc /mnt/tmp/etc ... master:105 +.EE +.in +.P +From the above, we see that +.I /mnt +is the master of the slave +.IR /tmp/etc , +which in turn is the master of the slave +.IR /mnt/tmp/etc . +.P +We then +.BR chroot (1) +to the +.I /mnt +directory, which renders the mount with ID 267 unreachable +from the (new) root directory: +.P +.in +4n +.EX +# \fBchroot /mnt\fP +.EE +.in +.P +When we examine the state of the mounts inside the chroot-ed environment, +we see the following: +.P +.in +4n +.EX +# \fBcat /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP +239 61 8:2 / / ... shared:102 +248 239 0:4 / /proc ... shared:5 +273 239 8:2 /etc /tmp/etc ... master:105 propagate_from:102 +.EE +.in +.P +Above, we see that the mount with ID 273 +is a slave whose master is the peer group 105. +The mount point for that master is unreachable, and so a +.I propagate_from +tag is displayed, indicating that the closest dominant peer group +(i.e., the nearest reachable mount in the slave chain) +is the peer group with the ID 102 (corresponding to the +.I /mnt +mount point before the +.BR chroot (1) +was performed). +.\" +.SH STANDARDS +Linux. +.SH HISTORY +Linux 2.4.19. +.\" +.SH NOTES +The propagation type assigned to a new mount depends +on the propagation type of the parent mount. +If the mount has a parent (i.e., it is a non-root mount +point) and the propagation type of the parent is +.BR MS_SHARED , +then the propagation type of the new mount is also +.BR MS_SHARED . +Otherwise, the propagation type of the new mount is +.BR MS_PRIVATE . +.P +Notwithstanding the fact that the default propagation type +for new mount is in many cases +.BR MS_PRIVATE , +.B MS_SHARED +is typically more useful. +For this reason, +.BR systemd (1) +automatically remounts all mounts as +.B MS_SHARED +on system startup. +Thus, on most modern systems, the default propagation type is in practice +.BR MS_SHARED . +.P +Since, when one uses +.BR unshare (1) +to create a mount namespace, +the goal is commonly to provide full isolation of the mounts +in the new namespace, +.BR unshare (1) +(since +.I util\-linux +2.27) in turn reverses the step performed by +.BR systemd (1), +by making all mounts private in the new namespace. +That is, +.BR unshare (1) +performs the equivalent of the following in the new mount namespace: +.P +.in +4n +.EX +mount \-\-make\-rprivate / +.EE +.in +.P +To prevent this, one can use the +.I \-\-propagation\~unchanged +option to +.BR unshare (1). +.P +An application that creates a new mount namespace directly using +.BR clone (2) +or +.BR unshare (2) +may desire to prevent propagation of mount events to other mount namespaces +(as is done by +.BR unshare (1)). +This can be done by changing the propagation type of +mounts in the new namespace to either +.B MS_SLAVE +or +.BR MS_PRIVATE , +using a call such as the following: +.P +.in +4n +.EX +mount(NULL, "/", MS_SLAVE | MS_REC, NULL); +.EE +.in +.P +For a discussion of propagation types when moving mounts +.RB ( MS_MOVE ) +and creating bind mounts +.RB ( MS_BIND ), +see +.IR Documentation/filesystems/sharedsubtree.rst . +.\" +.\" ============================================================ +.\" +.SS Restrictions on mount namespaces +Note the following points with respect to mount namespaces: +.IP [1] 5 +Each mount namespace has an owner user namespace. +As explained above, when a new mount namespace is created, +its mount list is initialized as a copy of the mount list +of another mount namespace. +If the new namespace and the namespace from which the mount list +was copied are owned by different user namespaces, +then the new mount namespace is considered +.IR "less privileged" . +.IP [2] +When creating a less privileged mount namespace, +shared mounts are reduced to slave mounts. +This ensures that mappings performed in less +privileged mount namespaces will not propagate to more privileged +mount namespaces. +.IP [3] +Mounts that come as a single unit from a more privileged mount namespace are +locked together and may not be separated in a less privileged mount +namespace. +(The +.BR unshare (2) +.B CLONE_NEWNS +operation brings across all of the mounts from the original +mount namespace as a single unit, +and recursive mounts that propagate between +mount namespaces propagate as a single unit.) +.IP +In this context, "may not be separated" means that the mounts +are locked so that they may not be individually unmounted. +Consider the following example: +.IP +.in +4n +.EX +$ \fBsudo sh\fP +# \fBmount \-\-bind /dev/null /etc/shadow\fP +# \fBcat /etc/shadow\fP # Produces no output +.EE +.in +.IP +The above steps, performed in a more privileged mount namespace, +have created a bind mount that +obscures the contents of the shadow password file, +.IR /etc/shadow . +For security reasons, it should not be possible to +.BR umount (2) +that mount in a less privileged mount namespace, +since that would reveal the contents of +.IR /etc/shadow . +.IP +Suppose we now create a new mount namespace +owned by a new user namespace. +The new mount namespace will inherit copies of all of the mounts +from the previous mount namespace. +However, those mounts will be locked because the new mount namespace +is less privileged. +Consequently, an attempt to +.BR umount (2) +the mount fails as show +in the following step: +.IP +.in +4n +.EX +# \fBunshare \-\-user \-\-map\-root\-user \-\-mount \e\fP + \fBstrace \-o /tmp/log \e\fP + \fBumount /mnt/dir\fP +umount: /etc/shadow: not mounted. +# \fBgrep \[aq]\[ha]umount\[aq] /tmp/log\fP +umount2("/etc/shadow", 0) = \-1 EINVAL (Invalid argument) +.EE +.in +.IP +The error message from +.BR mount (8) +is a little confusing, but the +.BR strace (1) +output reveals that the underlying +.BR umount2 (2) +system call failed with the error +.BR EINVAL , +which is the error that the kernel returns to indicate that +the mount is locked. +.IP +Note, however, that it is possible to stack (and unstack) a +mount on top of one of the inherited locked mounts in a +less privileged mount namespace: +.IP +.in +4n +.EX +# \fBecho \[aq]aaaaa\[aq] > /tmp/a\fP # File to mount onto /etc/shadow +# \fBunshare \-\-user \-\-map\-root\-user \-\-mount \e\fP + \fBsh \-c \[aq]mount \-\-bind /tmp/a /etc/shadow; cat /etc/shadow\[aq]\fP +aaaaa +# \fBumount /etc/shadow\fP +.EE +.in +.IP +The final +.BR umount (8) +command above, which is performed in the initial mount namespace, +makes the original +.I /etc/shadow +file once more visible in that namespace. +.IP [4] +Following on from point [3], +note that it is possible to +.BR umount (2) +an entire subtree of mounts that +propagated as a unit into a less privileged mount namespace, +as illustrated in the following example. +.IP +First, we create new user and mount namespaces using +.BR unshare (1). +In the new mount namespace, +the propagation type of all mounts is set to private. +We then create a shared bind mount at +.IR /mnt , +and a small hierarchy of mounts underneath that mount. +.IP +.in +4n +.EX +$ \fBPS1=\[aq]ns1# \[aq] sudo unshare \-\-user \-\-map\-root\-user \e\fP + \fB\-\-mount \-\-propagation private bash\fP +ns1# \fBecho $$\fP # We need the PID of this shell later +778501 +ns1# \fBmount \-\-make\-shared \-\-bind /mnt /mnt\fP +ns1# \fBmkdir /mnt/x\fP +ns1# \fBmount \-\-make\-private \-t tmpfs none /mnt/x\fP +ns1# \fBmkdir /mnt/x/y\fP +ns1# \fBmount \-\-make\-private \-t tmpfs none /mnt/x/y\fP +ns1# \fBgrep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP +986 83 8:5 /mnt /mnt rw,relatime shared:344 +989 986 0:56 / /mnt/x rw,relatime +990 989 0:57 / /mnt/x/y rw,relatime +.EE +.in +.IP +Continuing in the same shell session, +we then create a second shell in a new user namespace and a new +(less privileged) mount namespace and +check the state of the propagated mounts rooted at +.IR /mnt . +.IP +.in +4n +.EX +ns1# \fBPS1=\[aq]ns2# \[aq] unshare \-\-user \-\-map\-root\-user \e\fP + \fB\-\-mount \-\-propagation unchanged bash\fP +ns2# \fBgrep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP +1239 1204 8:5 /mnt /mnt rw,relatime master:344 +1240 1239 0:56 / /mnt/x rw,relatime +1241 1240 0:57 / /mnt/x/y rw,relatime +.EE +.in +.IP +Of note in the above output is that the propagation type of the mount +.I /mnt +has been reduced to slave, as explained in point [2]. +This means that submount events will propagate from the master +.I /mnt +in "ns1", but propagation will not occur in the opposite direction. +.IP +From a separate terminal window, we then use +.BR nsenter (1) +to enter the mount and user namespaces corresponding to "ns1". +In that terminal window, we then recursively bind mount +.I /mnt/x +at the location +.IR /mnt/ppp . +.IP +.in +4n +.EX +$ \fBPS1=\[aq]ns3# \[aq] sudo nsenter \-t 778501 \-\-user \-\-mount\fP +ns3# \fBmount \-\-rbind \-\-make\-private /mnt/x /mnt/ppp\fP +ns3# \fBgrep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP +986 83 8:5 /mnt /mnt rw,relatime shared:344 +989 986 0:56 / /mnt/x rw,relatime +990 989 0:57 / /mnt/x/y rw,relatime +1242 986 0:56 / /mnt/ppp rw,relatime +1243 1242 0:57 / /mnt/ppp/y rw,relatime shared:518 +.EE +.in +.IP +Because the propagation type of the parent mount, +.IR /mnt , +was shared, the recursive bind mount propagated a small subtree of +mounts under the slave mount +.I /mnt +into "ns2", +as can be verified by executing the following command in that shell session: +.IP +.in +4n +.EX +ns2# \fBgrep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP +1239 1204 8:5 /mnt /mnt rw,relatime master:344 +1240 1239 0:56 / /mnt/x rw,relatime +1241 1240 0:57 / /mnt/x/y rw,relatime +1244 1239 0:56 / /mnt/ppp rw,relatime +1245 1244 0:57 / /mnt/ppp/y rw,relatime master:518 +.EE +.in +.IP +While it is not possible to +.BR umount (2) +a part of the propagated subtree +.RI ( /mnt/ppp/y ) +in "ns2", +it is possible to +.BR umount (2) +the entire subtree, +as shown by the following commands: +.IP +.in +4n +.EX +ns2# \fBumount /mnt/ppp/y\fP +umount: /mnt/ppp/y: not mounted. +ns2# \fBumount \-l /mnt/ppp | sed \[aq]s/ \- .*//\[aq]\fP # Succeeds... +ns2# \fBgrep /mnt /proc/self/mountinfo\fP +1239 1204 8:5 /mnt /mnt rw,relatime master:344 +1240 1239 0:56 / /mnt/x rw,relatime +1241 1240 0:57 / /mnt/x/y rw,relatime +.EE +.in +.IP [5] +The +.BR mount (2) +flags +.BR MS_RDONLY , +.BR MS_NOSUID , +.BR MS_NOEXEC , +and the "atime" flags +.RB ( MS_NOATIME , +.BR MS_NODIRATIME , +.BR MS_RELATIME ) +settings become locked +.\" commit 9566d6742852c527bf5af38af5cbb878dad75705 +.\" Author: Eric W. Biederman +.\" Date: Mon Jul 28 17:26:07 2014 -0700 +.\" +.\" mnt: Correct permission checks in do_remount +.\" +when propagated from a more privileged to +a less privileged mount namespace, +and may not be changed in the less privileged mount namespace. +.IP +This point is illustrated in the following example where, +in a more privileged mount namespace, +we create a bind mount that is marked as read-only. +For security reasons, +it should not be possible to make the mount writable in +a less privileged mount namespace, and indeed the kernel prevents this: +.IP +.in +4n +.EX +$ \fBsudo mkdir /mnt/dir\fP +$ \fBsudo mount \-\-bind \-o ro /some/path /mnt/dir\fP +$ \fBsudo unshare \-\-user \-\-map\-root\-user \-\-mount \e\fP + \fBmount \-o remount,rw /mnt/dir\fP +mount: /mnt/dir: permission denied. +.EE +.in +.IP [6] +.\" (As of 3.18-rc1 (in Al Viro's 2014-08-30 vfs.git#for-next tree)) +A file or directory that is a mount point in one namespace that is not +a mount point in another namespace, may be renamed, unlinked, or removed +.RB ( rmdir (2)) +in the mount namespace in which it is not a mount point +(subject to the usual permission checks). +Consequently, the mount point is removed in the mount namespace +where it was a mount point. +.IP +Previously (before Linux 3.18), +.\" mtk: The change was in Linux 3.18, I think, with this commit: +.\" commit 8ed936b5671bfb33d89bc60bdcc7cf0470ba52fe +.\" Author: Eric W. Biederman +.\" Date: Tue Oct 1 18:33:48 2013 -0700 +.\" +.\" vfs: Lazily remove mounts on unlinked files and directories. +attempting to unlink, rename, or remove a file or directory +that was a mount point in another mount namespace would result in the error +.BR EBUSY . +That behavior had technical problems of enforcement (e.g., for NFS) +and permitted denial-of-service attacks against more privileged users +(i.e., preventing individual files from being updated +by bind mounting on top of them). +.SH EXAMPLES +See +.BR pivot_root (2). +.SH SEE ALSO +.BR unshare (1), +.BR clone (2), +.BR mount (2), +.BR mount_setattr (2), +.BR pivot_root (2), +.BR setns (2), +.BR umount (2), +.BR unshare (2), +.BR proc (5), +.BR namespaces (7), +.BR user_namespaces (7), +.BR findmnt (8), +.BR mount (8), +.BR pam_namespace (8), +.BR pivot_root (8), +.BR umount (8) +.P +.I Documentation/filesystems/sharedsubtree.rst +in the kernel source tree. diff --git a/man/man7/mq_overview.7 b/man/man7/mq_overview.7 new file mode 100644 index 0000000..03135bf --- /dev/null +++ b/man/man7/mq_overview.7 @@ -0,0 +1,389 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_overview 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +mq_overview \- overview of POSIX message queues +.SH DESCRIPTION +POSIX message queues allow processes to exchange data in +the form of messages. +This API is distinct from that provided by System V message queues +.RB ( msgget (2), +.BR msgsnd (2), +.BR msgrcv (2), +etc.), but provides similar functionality. +.P +Message queues are created and opened using +.BR mq_open (3); +this function returns a +.I message queue descriptor +.RI ( mqd_t ), +which is used to refer to the open message queue in later calls. +Each message queue is identified by a name of the form +.IR /somename ; +that is, a null-terminated string of up to +.B NAME_MAX +(i.e., 255) characters consisting of an initial slash, +followed by one or more characters, none of which are slashes. +Two processes can operate on the same queue by passing the same name to +.BR mq_open (3). +.P +Messages are transferred to and from a queue using +.BR mq_send (3) +and +.BR mq_receive (3). +When a process has finished using the queue, it closes it using +.BR mq_close (3), +and when the queue is no longer required, it can be deleted using +.BR mq_unlink (3). +Queue attributes can be retrieved and (in some cases) modified using +.BR mq_getattr (3) +and +.BR mq_setattr (3). +A process can request asynchronous notification +of the arrival of a message on a previously empty queue using +.BR mq_notify (3). +.P +A message queue descriptor is a reference to an +.I "open message queue description" +(see +.BR open (2)). +After a +.BR fork (2), +a child inherits copies of its parent's message queue descriptors, +and these descriptors refer to the same open message queue descriptions +as the corresponding message queue descriptors in the parent. +Corresponding message queue descriptors in the two processes share the flags +.RI ( mq_flags ) +that are associated with the open message queue description. +.P +Each message has an associated +.IR priority , +and messages are always delivered to the receiving process +highest priority first. +Message priorities range from 0 (low) to +.I sysconf(_SC_MQ_PRIO_MAX)\ \-\ 1 +(high). +On Linux, +.I sysconf(_SC_MQ_PRIO_MAX) +returns 32768, but POSIX.1 requires only that +an implementation support at least priorities in the range 0 to 31; +some implementations provide only this range. +.P +The remainder of this section describes some specific details +of the Linux implementation of POSIX message queues. +.SS Library interfaces and system calls +In most cases the +.BR mq_* () +library interfaces listed above are implemented +on top of underlying system calls of the same name. +Deviations from this scheme are indicated in the following table: +.RS +.TS +lB lB +l l. +Library interface System call +mq_close(3) close(2) +mq_getattr(3) mq_getsetattr(2) +mq_notify(3) mq_notify(2) +mq_open(3) mq_open(2) +mq_receive(3) mq_timedreceive(2) +mq_send(3) mq_timedsend(2) +mq_setattr(3) mq_getsetattr(2) +mq_timedreceive(3) mq_timedreceive(2) +mq_timedsend(3) mq_timedsend(2) +mq_unlink(3) mq_unlink(2) +.TE +.RE +.SS Versions +POSIX message queues have been supported since Linux 2.6.6. +glibc support has been provided since glibc 2.3.4. +.SS Kernel configuration +Support for POSIX message queues is configurable via the +.B CONFIG_POSIX_MQUEUE +kernel configuration option. +This option is enabled by default. +.SS Persistence +POSIX message queues have kernel persistence: +if not removed by +.BR mq_unlink (3), +a message queue will exist until the system is shut down. +.SS Linking +Programs using the POSIX message queue API must be compiled with +.I cc \-lrt +to link against the real-time library, +.IR librt . +.SS /proc interfaces +The following interfaces can be used to limit the amount of +kernel memory consumed by POSIX message queues and to set +the default attributes for new message queues: +.TP +.IR /proc/sys/fs/mqueue/msg_default " (since Linux 3.5)" +This file defines the value used for a new queue's +.I mq_maxmsg +setting when the queue is created with a call to +.BR mq_open (3) +where +.I attr +is specified as NULL. +The default value for this file is 10. +The minimum and maximum are as for +.IR /proc/sys/fs/mqueue/msg_max . +A new queue's default +.I mq_maxmsg +value will be the smaller of +.I msg_default +and +.IR msg_max . +Before Linux 2.6.28, the default +.I mq_maxmsg +was 10; +from Linux 2.6.28 to Linux 3.4, the default was the value defined for the +.I msg_max +limit. +.TP +.I /proc/sys/fs/mqueue/msg_max +This file can be used to view and change the ceiling value for the +maximum number of messages in a queue. +This value acts as a ceiling on the +.I attr\->mq_maxmsg +argument given to +.BR mq_open (3). +The default value for +.I msg_max +is 10. +The minimum value is 1 (10 before Linux 2.6.28). +The upper limit is +.BR HARD_MSGMAX . +The +.I msg_max +limit is ignored for privileged processes +.RB ( CAP_SYS_RESOURCE ), +but the +.B HARD_MSGMAX +ceiling is nevertheless imposed. +.IP +The definition of +.B HARD_MSGMAX +has changed across kernel versions: +.RS +.IP \[bu] 3 +Up to Linux 2.6.32: +.I 131072\~/\~sizeof(void\~*) +.IP \[bu] +Linux 2.6.33 to Linux 3.4: +.I (32768\~*\~sizeof(void\~*) / 4) +.IP \[bu] +Since Linux 3.5: +.\" commit 5b5c4d1a1440e94994c73dddbad7be0676cd8b9a +65,536 +.RE +.TP +.IR /proc/sys/fs/mqueue/msgsize_default " (since Linux 3.5)" +This file defines the value used for a new queue's +.I mq_msgsize +setting when the queue is created with a call to +.BR mq_open (3) +where +.I attr +is specified as NULL. +The default value for this file is 8192 (bytes). +The minimum and maximum are as for +.IR /proc/sys/fs/mqueue/msgsize_max . +If +.I msgsize_default +exceeds +.IR msgsize_max , +a new queue's default +.I mq_msgsize +value is capped to the +.I msgsize_max +limit. +Before Linux 2.6.28, the default +.I mq_msgsize +was 8192; +from Linux 2.6.28 to Linux 3.4, the default was the value defined for the +.I msgsize_max +limit. +.TP +.I /proc/sys/fs/mqueue/msgsize_max +This file can be used to view and change the ceiling on the +maximum message size. +This value acts as a ceiling on the +.I attr\->mq_msgsize +argument given to +.BR mq_open (3). +The default value for +.I msgsize_max +is 8192 bytes. +The minimum value is 128 (8192 before Linux 2.6.28). +The upper limit for +.I msgsize_max +has varied across kernel versions: +.RS +.IP \[bu] 3 +Before Linux 2.6.28, the upper limit is +.BR INT_MAX . +.IP \[bu] +From Linux 2.6.28 to Linux 3.4, the limit is 1,048,576. +.IP \[bu] +Since Linux 3.5, the limit is 16,777,216 +.RB ( HARD_MSGSIZEMAX ). +.RE +.IP +The +.I msgsize_max +limit is ignored for privileged process +.RB ( CAP_SYS_RESOURCE ), +but, since Linux 3.5, the +.B HARD_MSGSIZEMAX +ceiling is enforced for privileged processes. +.TP +.I /proc/sys/fs/mqueue/queues_max +This file can be used to view and change the system-wide limit on the +number of message queues that can be created. +The default value for +.I queues_max +is 256. +No ceiling is imposed on the +.I queues_max +limit; privileged processes +.RB ( CAP_SYS_RESOURCE ) +can exceed the limit (but see BUGS). +.SS Resource limit +The +.B RLIMIT_MSGQUEUE +resource limit, which places a limit on the amount of space +that can be consumed by all of the message queues +belonging to a process's real user ID, is described in +.BR getrlimit (2). +.SS Mounting the message queue filesystem +On Linux, message queues are created in a virtual filesystem. +(Other implementations may also provide such a feature, +but the details are likely to differ.) +This filesystem can be mounted (by the superuser) using the following +commands: +.P +.in +4n +.EX +.RB "#" " mkdir /dev/mqueue" +.RB "#" " mount \-t mqueue none /dev/mqueue" +.EE +.in +.P +The sticky bit is automatically enabled on the mount directory. +.P +After the filesystem has been mounted, the message queues on the system +can be viewed and manipulated using the commands usually used for files +(e.g., +.BR ls (1) +and +.BR rm (1)). +.P +The contents of each file in the directory consist of a single line +containing information about the queue: +.P +.in +4n +.EX +.RB "$" " cat /dev/mqueue/mymq" +QSIZE:129 NOTIFY:2 SIGNO:0 NOTIFY_PID:8260 +.EE +.in +.P +These fields are as follows: +.TP +.B QSIZE +Number of bytes of data in all messages in the queue (but see BUGS). +.TP +.B NOTIFY_PID +If this is nonzero, then the process with this PID has used +.BR mq_notify (3) +to register for asynchronous message notification, +and the remaining fields describe how notification occurs. +.TP +.B NOTIFY +Notification method: +0 is +.BR SIGEV_SIGNAL ; +1 is +.BR SIGEV_NONE ; +and +2 is +.BR SIGEV_THREAD . +.TP +.B SIGNO +Signal number to be used for +.BR SIGEV_SIGNAL . +.SS Linux implementation of message queue descriptors +On Linux, a message queue descriptor is actually a file descriptor. +(POSIX does not require such an implementation.) +This means that a message queue descriptor can be monitored using +.BR select (2), +.BR poll (2), +or +.BR epoll (7). +This is not portable. +.P +The close-on-exec flag (see +.BR open (2)) +is automatically set on the file descriptor returned by +.BR mq_open (2). +.SS IPC namespaces +For a discussion of the interaction of POSIX message queue objects and +IPC namespaces, see +.BR ipc_namespaces (7). +.SH NOTES +System V message queues +.RB ( msgget (2), +.BR msgsnd (2), +.BR msgrcv (2), +etc.) are an older API for exchanging messages between processes. +POSIX message queues provide a better designed interface than +System V message queues; +on the other hand POSIX message queues are less widely available +(especially on older systems) than System V message queues. +.P +Linux does not currently (Linux 2.6.26) support the use of access control +lists (ACLs) for POSIX message queues. +.SH BUGS +Since Linux 3.5 to Linux 3.14, the kernel imposed a ceiling of 1024 +.RB ( HARD_QUEUESMAX ) +on the value to which the +.I queues_max +limit could be raised, +and the ceiling was enforced even for privileged processes. +This ceiling value was removed in Linux 3.14, +and patches to stable Linux 3.5.x to Linux 3.13.x also removed the ceiling. +.P +As originally implemented (and documented), +the QSIZE field displayed the total number of (user-supplied) +bytes in all messages in the message queue. +Some changes in Linux 3.5 +.\" commit d6629859b36d +inadvertently changed the behavior, +so that this field also included a count of kernel overhead bytes +used to store the messages in the queue. +This behavioral regression was rectified in Linux 4.2 +.\" commit de54b9ac253787c366bbfb28d901a31954eb3511 +(and earlier stable kernel series), +so that the count once more included just the bytes of user data +in messages in the queue. +.SH EXAMPLES +An example of the use of various message queue functions is shown in +.BR mq_notify (3). +.SH SEE ALSO +.BR getrlimit (2), +.BR mq_getsetattr (2), +.BR poll (2), +.BR select (2), +.BR mq_close (3), +.BR mq_getattr (3), +.BR mq_notify (3), +.BR mq_open (3), +.BR mq_receive (3), +.BR mq_send (3), +.BR mq_unlink (3), +.BR epoll (7), +.BR namespaces (7) diff --git a/man/man7/namespaces.7 b/man/man7/namespaces.7 new file mode 100644 index 0000000..c7a96aa --- /dev/null +++ b/man/man7/namespaces.7 @@ -0,0 +1,417 @@ +'\" t +.\" Copyright (c) 2013, 2016, 2017 by Michael Kerrisk +.\" and Copyright (c) 2012 by Eric W. Biederman +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH namespaces 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +namespaces \- overview of Linux namespaces +.SH DESCRIPTION +A namespace wraps a global system resource in an abstraction that +makes it appear to the processes within the namespace that they +have their own isolated instance of the global resource. +Changes to the global resource are visible to other processes +that are members of the namespace, but are invisible to other processes. +One use of namespaces is to implement containers. +.P +This page provides pointers to information on the various namespace types, +describes the associated +.I /proc +files, and summarizes the APIs for working with namespaces. +.\" +.SS Namespace types +The following table shows the namespace types available on Linux. +The second column of the table shows the flag value that is used to specify +the namespace type in various APIs. +The third column identifies the manual page that provides details +on the namespace type. +The last column is a summary of the resources that are isolated by +the namespace type. +.TS +lB lB lB lB +l1 lB1 l1 l. +Namespace Flag Page Isolates +Cgroup CLONE_NEWCGROUP \fBcgroup_namespaces\fP(7) T{ +Cgroup root directory +T} +IPC CLONE_NEWIPC \fBipc_namespaces\fP(7) T{ +System V IPC, +POSIX message queues +T} +Network CLONE_NEWNET \fBnetwork_namespaces\fP(7) T{ +Network devices, +stacks, ports, etc. +T} +Mount CLONE_NEWNS \fBmount_namespaces\fP(7) Mount points +PID CLONE_NEWPID \fBpid_namespaces\fP(7) Process IDs +Time CLONE_NEWTIME \fBtime_namespaces\fP(7) T{ +Boot and monotonic +clocks +T} +User CLONE_NEWUSER \fBuser_namespaces\fP(7) T{ +User and group IDs +T} +UTS CLONE_NEWUTS \fButs_namespaces\fP(7) T{ +Hostname and NIS +domain name +T} +.TE +.\" +.\" ==================== The namespaces API ==================== +.\" +.SS The namespaces API +As well as various +.I /proc +files described below, +the namespaces API includes the following system calls: +.TP +.BR clone (2) +The +.BR clone (2) +system call creates a new process. +If the +.I flags +argument of the call specifies one or more of the +.B CLONE_NEW* +flags listed above, then new namespaces are created for each flag, +and the child process is made a member of those namespaces. +(This system call also implements a number of features +unrelated to namespaces.) +.TP +.BR setns (2) +The +.BR setns (2) +system call allows the calling process to join an existing namespace. +The namespace to join is specified via a file descriptor that refers to +one of the +.IR /proc/ pid /ns +files described below. +.TP +.BR unshare (2) +The +.BR unshare (2) +system call moves the calling process to a new namespace. +If the +.I flags +argument of the call specifies one or more of the +.B CLONE_NEW* +flags listed above, then new namespaces are created for each flag, +and the calling process is made a member of those namespaces. +(This system call also implements a number of features +unrelated to namespaces.) +.TP +.BR ioctl (2) +Various +.BR ioctl (2) +operations can be used to discover information about namespaces. +These operations are described in +.BR ioctl_ns (2). +.P +Creation of new namespaces using +.BR clone (2) +and +.BR unshare (2) +in most cases requires the +.B CAP_SYS_ADMIN +capability, since, in the new namespace, +the creator will have the power to change global resources +that are visible to other processes that are subsequently created in, +or join the namespace. +User namespaces are the exception: since Linux 3.8, +no privilege is required to create a user namespace. +.\" +.\" ==================== The /proc/[pid]/ns/ directory ==================== +.\" +.SS The \fI/proc/\fPpid\fI/ns/\fP directory +Each process has a +.IR /proc/ pid /ns/ +.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f +subdirectory containing one entry for each namespace that +supports being manipulated by +.BR setns (2): +.P +.in +4n +.EX +$ \fBls \-l /proc/$$/ns | awk \[aq]{print $1, $9, $10, $11}\[aq]\fP +total 0 +lrwxrwxrwx. cgroup \-> cgroup:[4026531835] +lrwxrwxrwx. ipc \-> ipc:[4026531839] +lrwxrwxrwx. mnt \-> mnt:[4026531840] +lrwxrwxrwx. net \-> net:[4026531969] +lrwxrwxrwx. pid \-> pid:[4026531836] +lrwxrwxrwx. pid_for_children \-> pid:[4026531834] +lrwxrwxrwx. time \-> time:[4026531834] +lrwxrwxrwx. time_for_children \-> time:[4026531834] +lrwxrwxrwx. user \-> user:[4026531837] +lrwxrwxrwx. uts \-> uts:[4026531838] +.EE +.in +.P +Bind mounting (see +.BR mount (2)) +one of the files in this directory +to somewhere else in the filesystem keeps +the corresponding namespace of the process specified by +.I pid +alive even if all processes currently in the namespace terminate. +.P +Opening one of the files in this directory +(or a file that is bind mounted to one of these files) +returns a file handle for +the corresponding namespace of the process specified by +.IR pid . +As long as this file descriptor remains open, +the namespace will remain alive, +even if all processes in the namespace terminate. +The file descriptor can be passed to +.BR setns (2). +.P +In Linux 3.7 and earlier, these files were visible as hard links. +Since Linux 3.8, +.\" commit bf056bfa80596a5d14b26b17276a56a0dcb080e5 +they appear as symbolic links. +If two processes are in the same namespace, +then the device IDs and inode numbers of their +.IR /proc/ pid /ns/ xxx +symbolic links will be the same; an application can check this using the +.I stat.st_dev +.\" Eric Biederman: "I reserve the right for st_dev to be significant +.\" when comparing namespaces." +.\" https://lore.kernel.org/lkml/87poky5ca9.fsf@xmission.com/ +.\" Re: Documenting the ioctl interfaces to discover relationships... +.\" Date: Mon, 12 Dec 2016 11:30:38 +1300 +and +.I stat.st_ino +fields returned by +.BR stat (2). +The content of this symbolic link is a string containing +the namespace type and inode number as in the following example: +.P +.in +4n +.EX +$ \fBreadlink /proc/$$/ns/uts\fP +uts:[4026531838] +.EE +.in +.P +The symbolic links in this subdirectory are as follows: +.TP +.IR /proc/ pid /ns/cgroup " (since Linux 4.6)" +This file is a handle for the cgroup namespace of the process. +.TP +.IR /proc/ pid /ns/ipc " (since Linux 3.0)" +This file is a handle for the IPC namespace of the process. +.TP +.IR /proc/ pid /ns/mnt " (since Linux 3.8)" +.\" commit 8823c079ba7136dc1948d6f6dcb5f8022bde438e +This file is a handle for the mount namespace of the process. +.TP +.IR /proc/ pid /ns/net " (since Linux 3.0)" +This file is a handle for the network namespace of the process. +.TP +.IR /proc/ pid /ns/pid " (since Linux 3.8)" +.\" commit 57e8391d327609cbf12d843259c968b9e5c1838f +This file is a handle for the PID namespace of the process. +This handle is permanent for the lifetime of the process +(i.e., a process's PID namespace membership never changes). +.TP +.IR /proc/ pid /ns/pid_for_children " (since Linux 4.12)" +.\" commit eaa0d190bfe1ed891b814a52712dcd852554cb08 +This file is a handle for the PID namespace of +child processes created by this process. +This can change as a consequence of calls to +.BR unshare (2) +and +.BR setns (2) +(see +.BR pid_namespaces (7)), +so the file may differ from +.IR /proc/ pid /ns/pid . +The symbolic link gains a value only after the first child process +is created in the namespace. +(Beforehand, +.BR readlink (2) +of the symbolic link will return an empty buffer.) +.TP +.IR /proc/ pid /ns/time " (since Linux 5.6)" +This file is a handle for the time namespace of the process. +.TP +.IR /proc/ pid /ns/time_for_children " (since Linux 5.6)" +This file is a handle for the time namespace of +child processes created by this process. +This can change as a consequence of calls to +.BR unshare (2) +and +.BR setns (2) +(see +.BR time_namespaces (7)), +so the file may differ from +.IR /proc/ pid /ns/time . +.TP +.IR /proc/ pid /ns/user " (since Linux 3.8)" +.\" commit cde1975bc242f3e1072bde623ef378e547b73f91 +This file is a handle for the user namespace of the process. +.TP +.IR /proc/ pid /ns/uts " (since Linux 3.0)" +This file is a handle for the UTS namespace of the process. +.P +Permission to dereference or read +.RB ( readlink (2)) +these symbolic links is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.\" +.\" ==================== The /proc/sys/user directory ==================== +.\" +.SS The \fI/proc/sys/user\fP directory +The files in the +.I /proc/sys/user +directory (which is present since Linux 4.9) expose limits +on the number of namespaces of various types that can be created. +The files are as follows: +.TP +.I max_cgroup_namespaces +The value in this file defines a per-user limit on the number of +cgroup namespaces that may be created in the user namespace. +.TP +.I max_ipc_namespaces +The value in this file defines a per-user limit on the number of +ipc namespaces that may be created in the user namespace. +.TP +.I max_mnt_namespaces +The value in this file defines a per-user limit on the number of +mount namespaces that may be created in the user namespace. +.TP +.I max_net_namespaces +The value in this file defines a per-user limit on the number of +network namespaces that may be created in the user namespace. +.TP +.I max_pid_namespaces +The value in this file defines a per-user limit on the number of +PID namespaces that may be created in the user namespace. +.TP +.IR max_time_namespaces " (since Linux 5.7)" +.\" commit eeec26d5da8248ea4e240b8795bb4364213d3247 +The value in this file defines a per-user limit on the number of +time namespaces that may be created in the user namespace. +.TP +.I max_user_namespaces +The value in this file defines a per-user limit on the number of +user namespaces that may be created in the user namespace. +.TP +.I max_uts_namespaces +The value in this file defines a per-user limit on the number of +uts namespaces that may be created in the user namespace. +.P +Note the following details about these files: +.IP \[bu] 3 +The values in these files are modifiable by privileged processes. +.IP \[bu] +The values exposed by these files are the limits for the user namespace +in which the opening process resides. +.IP \[bu] +The limits are per-user. +Each user in the same user namespace +can create namespaces up to the defined limit. +.IP \[bu] +The limits apply to all users, including UID 0. +.IP \[bu] +These limits apply in addition to any other per-namespace +limits (such as those for PID and user namespaces) that may be enforced. +.IP \[bu] +Upon encountering these limits, +.BR clone (2) +and +.BR unshare (2) +fail with the error +.BR ENOSPC . +.IP \[bu] +For the initial user namespace, +the default value in each of these files is half the limit on the number +of threads that may be created +.RI ( /proc/sys/kernel/threads\-max ). +In all descendant user namespaces, the default value in each file is +.BR MAXINT . +.IP \[bu] +When a namespace is created, the object is also accounted +against ancestor namespaces. +More precisely: +.RS +.IP \[bu] 3 +Each user namespace has a creator UID. +.IP \[bu] +When a namespace is created, +it is accounted against the creator UIDs in each of the +ancestor user namespaces, +and the kernel ensures that the corresponding namespace limit +for the creator UID in the ancestor namespace is not exceeded. +.IP \[bu] +The aforementioned point ensures that creating a new user namespace +cannot be used as a means to escape the limits in force +in the current user namespace. +.RE +.\" +.SS Namespace lifetime +Absent any other factors, +a namespace is automatically torn down when the last process in +the namespace terminates or leaves the namespace. +However, there are a number of other factors that may pin +a namespace into existence even though it has no member processes. +These factors include the following: +.IP \[bu] 3 +An open file descriptor or a bind mount exists for the corresponding +.IR /proc/ pid /ns/* +file. +.IP \[bu] +The namespace is hierarchical (i.e., a PID or user namespace), +and has a child namespace. +.IP \[bu] +It is a user namespace that owns one or more nonuser namespaces. +.IP \[bu] +It is a PID namespace, +and there is a process that refers to the namespace via a +.IR /proc/ pid /ns/pid_for_children +symbolic link. +.IP \[bu] +It is a time namespace, +and there is a process that refers to the namespace via a +.IR /proc/ pid /ns/time_for_children +symbolic link. +.IP \[bu] +It is an IPC namespace, and a corresponding mount of an +.I mqueue +filesystem (see +.BR mq_overview (7)) +refers to this namespace. +.IP \[bu] +It is a PID namespace, and a corresponding mount of a +.BR proc (5) +filesystem refers to this namespace. +.SH EXAMPLES +See +.BR clone (2) +and +.BR user_namespaces (7). +.SH SEE ALSO +.BR nsenter (1), +.BR readlink (1), +.BR unshare (1), +.BR clone (2), +.BR ioctl_ns (2), +.BR setns (2), +.BR unshare (2), +.BR proc (5), +.BR capabilities (7), +.BR cgroup_namespaces (7), +.BR cgroups (7), +.BR credentials (7), +.BR ipc_namespaces (7), +.BR network_namespaces (7), +.BR pid_namespaces (7), +.BR user_namespaces (7), +.BR uts_namespaces (7), +.BR lsns (8), +.BR switch_root (8) diff --git a/man/man7/netdevice.7 b/man/man7/netdevice.7 new file mode 100644 index 0000000..76b3612 --- /dev/null +++ b/man/man7/netdevice.7 @@ -0,0 +1,449 @@ +'\" t +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" $Id: netdevice.7,v 1.10 2000/08/17 10:09:54 ak Exp $ +.\" +.\" Modified, 2004-11-25, mtk, formatting and a few wording fixes +.\" +.\" Modified, 2011-11-02, , added many basic +.\" but missing ioctls, such as SIOCGIFADDR. +.\" +.TH netdevice 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +netdevice \- low-level access to Linux network devices +.SH SYNOPSIS +.nf +.B "#include " +.B "#include " +.fi +.SH DESCRIPTION +This man page describes the sockets interface which is used to configure +network devices. +.P +Linux supports some standard ioctls to configure network devices. +They can be used on any socket's file descriptor regardless of the +family or type. +Most of them pass an +.I ifreq +structure: +.P +.in +4n +.EX +struct ifreq { + char ifr_name[IFNAMSIZ]; /* Interface name */ + union { + struct sockaddr ifr_addr; + struct sockaddr ifr_dstaddr; + struct sockaddr ifr_broadaddr; + struct sockaddr ifr_netmask; + struct sockaddr ifr_hwaddr; + short ifr_flags; + int ifr_ifindex; + int ifr_metric; + int ifr_mtu; + struct ifmap ifr_map; + char ifr_slave[IFNAMSIZ]; + char ifr_newname[IFNAMSIZ]; + char *ifr_data; + }; +}; +.EE +.in +.P +.B AF_INET6 +is an exception. +It passes an +.I in6_ifreq +structure: +.P +.in +4n +.EX +struct in6_ifreq { + struct in6_addr ifr6_addr; + u32 ifr6_prefixlen; + int ifr6_ifindex; /* Interface index */ +}; +.EE +.in +.P +Normally, the user specifies which device to affect by setting +.I ifr_name +to the name of the interface or +.I ifr6_ifindex +to the index of the interface. +All other members of the structure may +share memory. +.SS Ioctls +If an ioctl is marked as privileged, then using it requires an effective +user ID of 0 or the +.B CAP_NET_ADMIN +capability. +If this is not the case, +.B EPERM +will be returned. +.TP +.B SIOCGIFNAME +Given the +.IR ifr_ifindex , +return the name of the interface in +.IR ifr_name . +This is the only ioctl which returns its result in +.IR ifr_name . +.TP +.B SIOCGIFINDEX +Retrieve the interface index of the interface into +.IR ifr_ifindex . +.TP +.B SIOCGIFFLAGS +.TQ +.B SIOCSIFFLAGS +Get or set the active flag word of the device. +.I ifr_flags +contains a bit mask of the following values: +.\" Do not right adjust text blocks in tables +.na +.TS +tab(:); +c s +l l. +Device flags +IFF_UP:Interface is running. +IFF_BROADCAST:Valid broadcast address set. +IFF_DEBUG:Internal debugging flag. +IFF_LOOPBACK:Interface is a loopback interface. +IFF_POINTOPOINT:Interface is a point-to-point link. +IFF_RUNNING:Resources allocated. +IFF_NOARP:T{ +No arp protocol, L2 destination address not set. +T} +IFF_PROMISC:Interface is in promiscuous mode. +IFF_NOTRAILERS:Avoid use of trailers. +IFF_ALLMULTI:Receive all multicast packets. +IFF_MASTER:Master of a load balancing bundle. +IFF_SLAVE:Slave of a load balancing bundle. +IFF_MULTICAST:Supports multicast +IFF_PORTSEL:Is able to select media type via ifmap. +IFF_AUTOMEDIA:Auto media selection active. +IFF_DYNAMIC:T{ +The addresses are lost when the interface goes down. +T} +IFF_LOWER_UP:Driver signals L1 up (since Linux 2.6.17) +IFF_DORMANT:Driver signals dormant (since Linux 2.6.17) +IFF_ECHO:Echo sent packets (since Linux 2.6.25) +.TE +.ad +.P +Setting the active flag word is a privileged operation, but any +process may read it. +.TP +.B SIOCGIFPFLAGS +.TQ +.B SIOCSIFPFLAGS +Get or set extended (private) flags for the device. +.I ifr_flags +contains a bit mask of the following values: +.TS +tab(:); +c s +l l. +Private flags +IFF_802_1Q_VLAN:Interface is 802.1Q VLAN device. +IFF_EBRIDGE:Interface is Ethernet bridging device. +IFF_SLAVE_INACTIVE:Interface is inactive bonding slave. +IFF_MASTER_8023AD:Interface is 802.3ad bonding master. +IFF_MASTER_ALB:Interface is balanced-alb bonding master. +IFF_BONDING:Interface is a bonding master or slave. +IFF_SLAVE_NEEDARP:Interface needs ARPs for validation. +IFF_ISATAP:Interface is RFC4214 ISATAP interface. +.TE +.P +Setting the extended (private) interface flags is a privileged operation. +.TP +.B SIOCGIFADDR +.TQ +.B SIOCSIFADDR +.TQ +.B SIOCDIFADDR +Get, set, or delete the address of the device using +.IR ifr_addr , +or +.I ifr6_addr +with +.IR ifr6_prefixlen . +Setting or deleting the interface address is a privileged operation. +For compatibility, +.B SIOCGIFADDR +returns only +.B AF_INET +addresses, +.B SIOCSIFADDR +accepts +.B AF_INET +and +.B AF_INET6 +addresses, and +.B SIOCDIFADDR +deletes only +.B AF_INET6 +addresses. +A +.B AF_INET +address can be deleted by setting it to zero via +.BR SIOCSIFADDR . +.TP +.B SIOCGIFDSTADDR +.TQ +.B SIOCSIFDSTADDR +Get or set the destination address of a point-to-point device using +.IR ifr_dstaddr . +For compatibility, only +.B AF_INET +addresses are accepted or returned. +Setting the destination address is a privileged operation. +.TP +.B SIOCGIFBRDADDR +.TQ +.B SIOCSIFBRDADDR +Get or set the broadcast address for a device using +.IR ifr_brdaddr . +For compatibility, only +.B AF_INET +addresses are accepted or returned. +Setting the broadcast address is a privileged operation. +.TP +.B SIOCGIFNETMASK +.TQ +.B SIOCSIFNETMASK +Get or set the network mask for a device using +.IR ifr_netmask . +For compatibility, only +.B AF_INET +addresses are accepted or returned. +Setting the network mask is a privileged operation. +.TP +.B SIOCGIFMETRIC +.TQ +.B SIOCSIFMETRIC +Get or set the metric of the device using +.IR ifr_metric . +This is currently not implemented; it sets +.I ifr_metric +to 0 if you attempt to read it and returns +.B EOPNOTSUPP +if you attempt to set it. +.TP +.B SIOCGIFMTU +.TQ +.B SIOCSIFMTU +Get or set the MTU (Maximum Transfer Unit) of a device using +.IR ifr_mtu . +Setting the MTU is a privileged operation. +Setting the MTU to +too small values may cause kernel crashes. +.TP +.B SIOCGIFHWADDR +.TQ +.B SIOCSIFHWADDR +Get or set the hardware address of a device using +.IR ifr_hwaddr . +The hardware address is specified in a struct +.IR sockaddr . +.I sa_family +contains the ARPHRD_* device type, +.I sa_data +the L2 hardware address starting from byte 0. +Setting the hardware address is a privileged operation. +.TP +.B SIOCSIFHWBROADCAST +Set the hardware broadcast address of a device from +.IR ifr_hwaddr . +This is a privileged operation. +.TP +.B SIOCGIFMAP +.TQ +.B SIOCSIFMAP +Get or set the interface's hardware parameters using +.IR ifr_map . +Setting the parameters is a privileged operation. +.IP +.in +4n +.EX +struct ifmap { + unsigned long mem_start; + unsigned long mem_end; + unsigned short base_addr; + unsigned char irq; + unsigned char dma; + unsigned char port; +}; +.EE +.in +.IP +The interpretation of the ifmap structure depends on the device driver +and the architecture. +.TP +.B SIOCADDMULTI +.TQ +.B SIOCDELMULTI +Add an address to or delete an address from the device's link layer +multicast filters using +.IR ifr_hwaddr . +These are privileged operations. +See also +.BR packet (7) +for an alternative. +.TP +.B SIOCGIFTXQLEN +.TQ +.B SIOCSIFTXQLEN +Get or set the transmit queue length of a device using +.IR ifr_qlen . +Setting the transmit queue length is a privileged operation. +.TP +.B SIOCSIFNAME +Changes the name of the interface specified in +.I ifr_name +to +.IR ifr_newname . +This is a privileged operation. +It is allowed only when the interface +is not up. +.TP +.B SIOCGIFCONF +Return a list of interface (network layer) addresses. +This currently +means only addresses of the +.B AF_INET +(IPv4) family for compatibility. +Unlike the others, this ioctl passes an +.I ifconf +structure: +.IP +.in +4n +.EX +struct ifconf { + int ifc_len; /* size of buffer */ + union { + char *ifc_buf; /* buffer address */ + struct ifreq *ifc_req; /* array of structures */ + }; +}; +.EE +.in +.IP +If +.I ifc_req +is NULL, +.B SIOCGIFCONF +returns the necessary buffer size in bytes +for receiving all available addresses in +.IR ifc_len . +Otherwise, +.I ifc_req +contains a pointer to an array of +.I ifreq +structures to be filled with all currently active L3 interface addresses. +.I ifc_len +contains the size of the array in bytes. +Within each +.I ifreq +structure, +.I ifr_name +will receive the interface name, and +.I ifr_addr +the address. +The actual number of bytes transferred is returned in +.IR ifc_len . +.IP +If the size specified by +.I ifc_len +is insufficient to store all the addresses, +the kernel will skip the exceeding ones and return success. +There is no reliable way of detecting this condition once it has occurred. +It is therefore recommended to either determine the necessary buffer size +beforehand by calling +.B SIOCGIFCONF +with +.I ifc_req +set to NULL, or to retry the call with a bigger buffer whenever +.I ifc_len +upon return differs by less than +.I sizeof(struct ifreq) +from its original value. +.IP +If an error occurs accessing the +.I ifconf +or +.I ifreq +structures, +.B EFAULT +will be returned. +.\" Slaving isn't supported in Linux 2.2 +.\" . +.\" .TP +.\" .B SIOCGIFSLAVE +.\" .TQ +.\" .B SIOCSIFSLAVE +.\" Get or set the slave device using +.\" .IR ifr_slave . +.\" Setting the slave device is a privileged operation. +.\" .P +.\" FIXME . add amateur radio stuff. +.P +Most protocols support their own ioctls to configure protocol-specific +interface options. +See the protocol man pages for a description. +For configuring IP addresses, see +.BR ip (7). +.P +In addition, some devices support private ioctls. +These are not described here. +.SH NOTES +.B SIOCGIFCONF +and the other ioctls that accept or return only +.B AF_INET +socket addresses +are IP-specific and perhaps should rather be documented in +.BR ip (7). +.P +The names of interfaces with no addresses or that don't have the +.B IFF_RUNNING +flag set can be found via +.IR /proc/net/dev . +.P +.B AF_INET6 +IPv6 addresses can be read from +.I /proc/net/if_inet6 +or via +.BR rtnetlink (7). +Adding a new IPv6 address and deleting an existing IPv6 address +can be done via +.B SIOCSIFADDR +and +.B SIOCDIFADDR +or via +.BR rtnetlink (7). +Retrieving or changing destination IPv6 addresses of a point-to-point +interface is possible only via +.BR rtnetlink (7). +.SH BUGS +glibc 2.1 is missing the +.I ifr_newname +macro in +.IR . +Add the following to your program as a workaround: +.P +.in +4n +.EX +#ifndef ifr_newname +#define ifr_newname ifr_ifru.ifru_slave +#endif +.EE +.in +.SH SEE ALSO +.BR proc (5), +.BR capabilities (7), +.BR ip (7), +.BR rtnetlink (7) diff --git a/man/man7/netlink.7 b/man/man7/netlink.7 new file mode 100644 index 0000000..971d5a6 --- /dev/null +++ b/man/man7/netlink.7 @@ -0,0 +1,611 @@ +'\" t +.\" This man page is Copyright (c) 1998 by Andi Kleen. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" Based on the original comments from Alexey Kuznetsov +.\" Modified 2005-12-27 by Hasso Tepper +.\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $ +.TH netlink 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +netlink \- communication between kernel and user space (AF_NETLINK) +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family ); +.fi +.SH DESCRIPTION +Netlink is used to transfer information between the kernel and +user-space processes. +It consists of a standard sockets-based interface for user space +processes and an internal kernel API for kernel modules. +The internal kernel interface is not documented in this manual page. +There is also an obsolete netlink interface +via netlink character devices; this interface is not documented here +and is provided only for backward compatibility. +.P +Netlink is a datagram-oriented service. +Both +.B SOCK_RAW +and +.B SOCK_DGRAM +are valid values for +.IR socket_type . +However, the netlink protocol does not distinguish between datagram +and raw sockets. +.P +.I netlink_family +selects the kernel module or netlink group to communicate with. +The currently assigned netlink families are: +.TP +.B NETLINK_ROUTE +Receives routing and link updates and may be used to modify the routing +tables (both IPv4 and IPv6), IP addresses, link parameters, +neighbor setups, queueing disciplines, traffic classes, and +packet classifiers (see +.BR rtnetlink (7)). +.TP +.BR NETLINK_W1 " (Linux 2.6.13 to Linux 2.16.17)" +Messages from 1-wire subsystem. +.TP +.B NETLINK_USERSOCK +Reserved for user-mode socket protocols. +.TP +.BR NETLINK_FIREWALL " (up to and including Linux 3.4)" +.\" removed by commit d16cf20e2f2f13411eece7f7fb72c17d141c4a84 +Transport IPv4 packets from netfilter to user space. +Used by +.I ip_queue +kernel module. +After a long period of being declared obsolete (in favor of the more advanced +.I nfnetlink_queue +feature), +.B NETLINK_FIREWALL +was removed in Linux 3.5. +.TP +.BR NETLINK_SOCK_DIAG " (since Linux 3.3)" +.\" commit 7f1fb60c4fc9fb29fbb406ac8c4cfb4e59e168d6 +Query information about sockets of various protocol families from the kernel +(see +.BR sock_diag (7)). +.TP +.BR NETLINK_INET_DIAG " (since Linux 2.6.14)" +An obsolete synonym for +.BR NETLINK_SOCK_DIAG . +.TP +.BR NETLINK_NFLOG " (up to and including Linux 3.16)" +Netfilter/iptables ULOG. +.TP +.B NETLINK_XFRM +.\" FIXME More details on NETLINK_XFRM needed. +IPsec. +.TP +.BR NETLINK_SELINUX " (since Linux 2.6.4)" +SELinux event notifications. +.TP +.BR NETLINK_ISCSI " (since Linux 2.6.15)" +.\" FIXME More details on NETLINK_ISCSI needed. +Open-iSCSI. +.TP +.BR NETLINK_AUDIT " (since Linux 2.6.6)" +.\" FIXME More details on NETLINK_AUDIT needed. +Auditing. +.TP +.BR NETLINK_FIB_LOOKUP " (since Linux 2.6.13)" +.\" FIXME More details on NETLINK_FIB_LOOKUP needed. +Access to FIB lookup from user space. +.TP +.BR NETLINK_CONNECTOR " (since Linux 2.6.14)" +Kernel connector. +See +.I Documentation/driver\-api/connector.rst +(or +.I /Documentation/connector/connector.* +.\" commit baa293e9544bea71361950d071579f0e4d5713ed +in Linux 5.2 and earlier) +in the Linux kernel source tree for further information. +.TP +.BR NETLINK_NETFILTER " (since Linux 2.6.14)" +.\" FIXME More details on NETLINK_NETFILTER needed. +Netfilter subsystem. +.TP +.BR NETLINK_SCSITRANSPORT " (since Linux 2.6.19)" +.\" commit 84314fd4740ad73550c76dee4a9578979d84af48 +.\" FIXME More details on NETLINK_SCSITRANSPORT needed. +SCSI Transports. +.TP +.BR NETLINK_RDMA " (since Linux 3.0)" +.\" commit b2cbae2c248776d81cc265ff7d48405b6a4cc463 +.\" FIXME More details on NETLINK_RDMA needed. +Infiniband RDMA. +.TP +.BR NETLINK_IP6_FW " (up to and including Linux 3.4)" +Transport IPv6 packets from netfilter to user space. +Used by +.I ip6_queue +kernel module. +.TP +.B NETLINK_DNRTMSG +DECnet routing messages. +.TP +.BR NETLINK_KOBJECT_UEVENT " (since Linux 2.6.10)" +.\" FIXME More details on NETLINK_KOBJECT_UEVENT needed. +Kernel messages to user space. +.TP +.BR NETLINK_GENERIC " (since Linux 2.6.15)" +Generic netlink family for simplified netlink usage. +.TP +.BR NETLINK_CRYPTO " (since Linux 3.2)" +.\" commit a38f7907b926e4c6c7d389ad96cc38cec2e5a9e9 +.\" Author: Steffen Klassert +Netlink interface to request information about ciphers registered +with the kernel crypto API as well as allow configuration of the +kernel crypto API. +.P +Netlink messages consist of a byte stream with one or multiple +.I nlmsghdr +headers and associated payload. +The byte stream should be accessed only with the standard +.B NLMSG_* +macros. +See +.BR netlink (3) +for further information. +.P +In multipart messages (multiple +.I nlmsghdr +headers with associated payload in one byte stream) the first and all +following headers have the +.B NLM_F_MULTI +flag set, except for the last header which has the type +.BR NLMSG_DONE . +.P +After each +.I nlmsghdr +the payload follows. +.P +.in +4n +.EX +struct nlmsghdr { + __u32 nlmsg_len; /* Length of message including header */ + __u16 nlmsg_type; /* Type of message content */ + __u16 nlmsg_flags; /* Additional flags */ + __u32 nlmsg_seq; /* Sequence number */ + __u32 nlmsg_pid; /* Sender port ID */ +}; +.EE +.in +.P +.I nlmsg_type +can be one of the standard message types: +.B NLMSG_NOOP +message is to be ignored, +.B NLMSG_ERROR +message signals an error and the payload contains an +.I nlmsgerr +structure, +.B NLMSG_DONE +message terminates a multipart message. +Error messages get the +original request appended, unless the user requests to cap the +error message, and get extra error data if requested. +.P +.in +4n +.EX +struct nlmsgerr { + int error; /* Negative errno or 0 for acknowledgements */ + struct nlmsghdr msg; /* Message header that caused the error */ + /* + * followed by the message contents + * unless NETLINK_CAP_ACK was set + * or the ACK indicates success (error == 0). + * For example Generic Netlink message with attributes. + * message length is aligned with NLMSG_ALIGN() + */ + /* + * followed by TLVs defined in enum nlmsgerr_attrs + * if NETLINK_EXT_ACK was set + */ +}; +.EE +.in +.P +A netlink family usually specifies more message types, see the +appropriate manual pages for that, for example, +.BR rtnetlink (7) +for +.BR NETLINK_ROUTE . +.TS +tab(:); +l s +lB lx. +Standard flag bits in \fInlmsg_flags\fP +_ +NLM_F_REQUEST:T{ +Must be set on all request messages. +T} +NLM_F_MULTI:T{ +The message is part of a multipart message terminated by +.BR NLMSG_DONE . +T} +NLM_F_ACK:T{ +Request for an acknowledgement on success. +T} +NLM_F_ECHO:T{ +Echo this request. +T} +.TE +.\" No right adjustment for text blocks in tables +.TS +tab(:); +l s +lB lx. +Additional flag bits for GET requests +_ +NLM_F_ROOT:T{ +Return the complete table instead of a single entry. +T} +NLM_F_MATCH:T{ +Return all entries matching criteria passed in message content. +Not implemented yet. +T} +NLM_F_ATOMIC:T{ +Return an atomic snapshot of the table. +T} +NLM_F_DUMP:T{ +Convenience macro; equivalent to +(NLM_F_ROOT|NLM_F_MATCH). +T} +.TE +.\" FIXME NLM_F_ATOMIC is not used anymore? +.P +Note that +.B NLM_F_ATOMIC +requires the +.B CAP_NET_ADMIN +capability or an effective UID of 0. +.TS +tab(:); +l s +lB lx. +Additional flag bits for NEW requests +_ +NLM_F_REPLACE:T{ +Replace existing matching object. +T} +NLM_F_EXCL:T{ +Don't replace if the object already exists. +T} +NLM_F_CREATE:T{ +Create object if it doesn't already exist. +T} +NLM_F_APPEND:T{ +Add to the end of the object list. +T} +.TE +.P +.I nlmsg_seq +and +.I nlmsg_pid +are used to track messages. +.I nlmsg_pid +shows the origin of the message. +Note that there isn't a 1:1 relationship between +.I nlmsg_pid +and the PID of the process if the message originated from a netlink +socket. +See the +.B ADDRESS FORMATS +section for further information. +.P +Both +.I nlmsg_seq +and +.I nlmsg_pid +.\" FIXME Explain more about nlmsg_seq and nlmsg_pid. +are opaque to netlink core. +.P +Netlink is not a reliable protocol. +It tries its best to deliver a message to its destination(s), +but may drop messages when an out-of-memory condition or +other error occurs. +For reliable transfer the sender can request an +acknowledgement from the receiver by setting the +.B NLM_F_ACK +flag. +An acknowledgement is an +.B NLMSG_ERROR +packet with the error field set to 0. +The application must generate acknowledgements for +received messages itself. +The kernel tries to send an +.B NLMSG_ERROR +message for every failed packet. +A user process should follow this convention too. +.P +However, reliable transmissions from kernel to user are impossible +in any case. +The kernel can't send a netlink message if the socket buffer is full: +the message will be dropped and the kernel and the user-space process will +no longer have the same view of kernel state. +It is up to the application to detect when this happens (via the +.B ENOBUFS +error returned by +.BR recvmsg (2)) +and resynchronize. +.SS Address formats +The +.I sockaddr_nl +structure describes a netlink client in user space or in the kernel. +A +.I sockaddr_nl +can be either unicast (only sent to one peer) or sent to +netlink multicast groups +.RI ( nl_groups +not equal 0). +.P +.in +4n +.EX +struct sockaddr_nl { + sa_family_t nl_family; /* AF_NETLINK */ + unsigned short nl_pad; /* Zero */ + pid_t nl_pid; /* Port ID */ + __u32 nl_groups; /* Multicast groups mask */ +}; +.EE +.in +.P +.I nl_pid +is the unicast address of netlink socket. +It's always 0 if the destination is in the kernel. +For a user-space process, +.I nl_pid +is usually the PID of the process owning the destination socket. +However, +.I nl_pid +identifies a netlink socket, not a process. +If a process owns several netlink +sockets, then +.I nl_pid +can be equal to the process ID only for at most one socket. +There are two ways to assign +.I nl_pid +to a netlink socket. +If the application sets +.I nl_pid +before calling +.BR bind (2), +then it is up to the application to make sure that +.I nl_pid +is unique. +If the application sets it to 0, the kernel takes care of assigning it. +The kernel assigns the process ID to the first netlink socket the process +opens and assigns a unique +.I nl_pid +to every netlink socket that the process subsequently creates. +.P +.I nl_groups +is a bit mask with every bit representing a netlink group number. +Each netlink family has a set of 32 multicast groups. +When +.BR bind (2) +is called on the socket, the +.I nl_groups +field in the +.I sockaddr_nl +should be set to a bit mask of the groups which it wishes to listen to. +The default value for this field is zero which means that no multicasts +will be received. +A socket may multicast messages to any of the multicast groups by setting +.I nl_groups +to a bit mask of the groups it wishes to send to when it calls +.BR sendmsg (2) +or does a +.BR connect (2). +Only processes with an effective UID of 0 or the +.B CAP_NET_ADMIN +capability may send or listen to a netlink multicast group. +Since Linux 2.6.13, +.\" commit d629b836d151d43332492651dd841d32e57ebe3b +messages can't be broadcast to multiple groups. +Any replies to a message received for a multicast group should be +sent back to the sending PID and the multicast group. +Some Linux kernel subsystems may additionally allow other users +to send and/or receive messages. +As at Linux 3.0, the +.BR NETLINK_KOBJECT_UEVENT , +.BR NETLINK_GENERIC , +.BR NETLINK_ROUTE , +and +.B NETLINK_SELINUX +groups allow other users to receive messages. +No groups allow other users to send messages. +.SS Socket options +To set or get a netlink socket option, call +.BR getsockopt (2) +to read or +.BR setsockopt (2) +to write the option with the option level argument set to +.BR SOL_NETLINK . +Unless otherwise noted, +.I optval +is a pointer to an +.IR int . +.TP +.BR NETLINK_PKTINFO " (since Linux 2.6.14)" +.\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99 +.\" Author: Patrick McHardy +Enable +.B nl_pktinfo +control messages for received packets to get the extended +destination group number. +.TP +.B NETLINK_ADD_MEMBERSHIP +.TQ +.BR NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)" +.\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99 +.\" Author: Patrick McHardy +Join/leave a group specified by +.IR optval . +.TP +.BR NETLINK_LIST_MEMBERSHIPS " (since Linux 4.2)" +.\" commit b42be38b2778eda2237fc759e55e3b698b05b315 +.\" Author: David Herrmann +Retrieve all groups a socket is a member of. +.I optval +is a pointer to +.B __u32 +and +.I optlen +is the size of the array. +The array is filled with the full membership set of the +socket, and the required array size is returned in +.IR optlen . +.TP +.BR NETLINK_BROADCAST_ERROR " (since Linux 2.6.30)" +.\" commit be0c22a46cfb79ab2342bb28fde99afa94ef868e +.\" Author: Pablo Neira Ayuso +When not set, +.B netlink_broadcast() +only reports +.B ESRCH +errors and silently ignore +.B ENOBUFS +errors. +.TP +.BR NETLINK_NO_ENOBUFS " (since Linux 2.6.30)" +.\" commit 38938bfe3489394e2eed5e40c9bb8f66a2ce1405 +.\" Author: Pablo Neira Ayuso +This flag can be used by unicast and broadcast listeners to avoid receiving +.B ENOBUFS +errors. +.TP +.BR NETLINK_LISTEN_ALL_NSID " (since Linux 4.2)" +.\" commit 59324cf35aba5336b611074028777838a963d03b +.\" Author: Nicolas Dichtel +When set, this socket will receive netlink notifications from +all network namespaces that have an +.I nsid +assigned into the network namespace where the socket has been opened. +The +.I nsid +is sent to user space via an ancillary data. +.TP +.BR NETLINK_CAP_ACK " (since Linux 4.3)" +.\" commit 0a6a3a23ea6efde079a5b77688541a98bf202721 +.\" Author: Christophe Ricard +The kernel may fail to allocate the necessary room for the acknowledgement +message back to user space. +This option trims off the payload of the original netlink message. +The netlink message header is still included, so the user can guess from the +sequence number which message triggered the acknowledgement. +.SH VERSIONS +The socket interface to netlink first appeared Linux 2.2. +.P +Linux 2.0 supported a more primitive device-based netlink interface +(which is still available as a compatibility option). +This obsolete interface is not described here. +.SH NOTES +It is often better to use netlink via +.I libnetlink +or +.I libnl +than via the low-level kernel interface. +.SH BUGS +This manual page is not complete. +.SH EXAMPLES +The following example creates a +.B NETLINK_ROUTE +netlink socket which will listen to the +.B RTMGRP_LINK +(network interface create/delete/up/down events) and +.B RTMGRP_IPV4_IFADDR +(IPv4 addresses add/delete events) multicast groups. +.P +.in +4n +.EX +struct sockaddr_nl sa; +\& +memset(&sa, 0, sizeof(sa)); +sa.nl_family = AF_NETLINK; +sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR; +\& +fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE); +bind(fd, (struct sockaddr *) &sa, sizeof(sa)); +.EE +.in +.P +The next example demonstrates how to send a netlink message to the +kernel (pid 0). +Note that the application must take care of message sequence numbers +in order to reliably track acknowledgements. +.P +.in +4n +.EX +struct nlmsghdr *nh; /* The nlmsghdr with payload to send */ +struct sockaddr_nl sa; +struct iovec iov = { nh, nh\->nlmsg_len }; +struct msghdr msg; +\& +msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 }; +memset(&sa, 0, sizeof(sa)); +sa.nl_family = AF_NETLINK; +nh\->nlmsg_pid = 0; +nh\->nlmsg_seq = ++sequence_number; +/* Request an ack from kernel by setting NLM_F_ACK */ +nh\->nlmsg_flags |= NLM_F_ACK; +\& +sendmsg(fd, &msg, 0); +.EE +.in +.P +And the last example is about reading netlink message. +.P +.in +4n +.EX +int len; +/* 8192 to avoid message truncation on platforms with + page size > 4096 */ +struct nlmsghdr buf[8192/sizeof(struct nlmsghdr)]; +struct iovec iov = { buf, sizeof(buf) }; +struct sockaddr_nl sa; +struct msghdr msg; +struct nlmsghdr *nh; +\& +msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 }; +len = recvmsg(fd, &msg, 0); +\& +for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len); + nh = NLMSG_NEXT (nh, len)) { + /* The end of multipart message */ + if (nh\->nlmsg_type == NLMSG_DONE) + return; +\& + if (nh\->nlmsg_type == NLMSG_ERROR) + /* Do some error handling */ + ... +\& + /* Continue with parsing payload */ + ... +} +.EE +.in +.SH SEE ALSO +.BR cmsg (3), +.BR netlink (3), +.BR capabilities (7), +.BR rtnetlink (7), +.BR sock_diag (7) +.P +.UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2* +information about libnetlink +.UE +.P +.UR http://www.infradead.org\:/\[ti]tgr\:/libnl/ +information about libnl +.UE +.P +RFC 3549 "Linux Netlink as an IP Services Protocol" diff --git a/man/man7/network_namespaces.7 b/man/man7/network_namespaces.7 new file mode 100644 index 0000000..00ea8aa --- /dev/null +++ b/man/man7/network_namespaces.7 @@ -0,0 +1,62 @@ +.\" Copyright (c) 2017 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH network_namespaces 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +network_namespaces \- overview of Linux network namespaces +.SH DESCRIPTION +Network namespaces provide isolation of the system resources associated +with networking: network devices, IPv4 and IPv6 protocol stacks, +IP routing tables, firewall rules, the +.I /proc/net +directory (which is a symbolic link to +.IR /proc/ pid /net ), +the +.I /sys/class/net +directory, various files under +.IR /proc/sys/net , +port numbers (sockets), and so on. +In addition, +network namespaces isolate the UNIX domain abstract socket namespace (see +.BR unix (7)). +.P +A physical network device can live in exactly one +network namespace. +When a network namespace is freed +(i.e., when the last process in the namespace terminates), +its physical network devices are moved back to the +initial network namespace +(not to the namespace of the parent of the process). +.P +A virtual network +.RB ( veth (4)) +device pair provides a pipe-like abstraction +that can be used to create tunnels between network namespaces, +and can be used to create a bridge to a physical network device +in another namespace. +When a namespace is freed, the +.BR veth (4) +devices that it contains are destroyed. +.P +Use of network namespaces requires a kernel that is configured with the +.B CONFIG_NET_NS +option. +.\" FIXME .SH EXAMPLES +.SH SEE ALSO +.BR nsenter (1), +.BR unshare (1), +.BR clone (2), +.BR veth (4), +.BR proc (5), +.BR sysfs (5), +.BR namespaces (7), +.BR user_namespaces (7), +.BR brctl (8), +.BR ip (8), +.BR ip\-address (8), +.BR ip\-link (8), +.BR ip\-netns (8), +.BR iptables (8), +.BR ovs\-vsctl (8) diff --git a/man/man7/nptl.7 b/man/man7/nptl.7 new file mode 100644 index 0000000..8fc3046 --- /dev/null +++ b/man/man7/nptl.7 @@ -0,0 +1,112 @@ +.\" Copyright (c) 2015 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH nptl 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nptl \- Native POSIX Threads Library +.SH DESCRIPTION +NPTL (Native POSIX Threads Library) +is the GNU C library POSIX threads implementation that is used on modern +Linux systems. +.\" +.SS NPTL and signals +NPTL makes internal use of the first two real-time signals +(signal numbers 32 and 33). +One of these signals is used to support thread cancelation and POSIX timers +(see +.BR timer_create (2)); +the other is used as part of a mechanism that ensures all threads in +a process always have the same UIDs and GIDs, as required by POSIX. +These signals cannot be used in applications. +.P +To prevent accidental use of these signals in applications, +which might interfere with the operation of the NPTL implementation, +various glibc library functions and system call wrapper functions +attempt to hide these signals from applications, +as follows: +.IP \[bu] 3 +.B SIGRTMIN +is defined with the value 34 (rather than 32). +.IP \[bu] +The +.BR sigwaitinfo (2), +.BR sigtimedwait (2), +and +.BR sigwait (3) +interfaces silently ignore requests to wait for these two signals +if they are specified in the signal set argument of these calls. +.IP \[bu] +The +.BR sigprocmask (2) +and +.BR pthread_sigmask (3) +interfaces silently ignore attempts to block these two signals. +.IP \[bu] +The +.BR sigaction (2), +.BR pthread_kill (3), +and +.BR pthread_sigqueue (3) +interfaces fail with the error +.B EINVAL +(indicating an invalid signal number) if these signals are specified. +.IP \[bu] +.BR sigfillset (3) +does not include these two signals when it creates a full signal set. +.\" +.SS NPTL and process credential changes +At the Linux kernel level, +credentials (user and group IDs) are a per-thread attribute. +However, POSIX requires that all of the POSIX threads in a process +have the same credentials. +To accommodate this requirement, +the NPTL implementation wraps all of the system calls that +change process credentials with functions that, +in addition to invoking the underlying system call, +arrange for all other threads in the process to also change their credentials. +.P +The implementation of each of these system calls involves the use of +a real-time signal that is sent (using +.BR tgkill (2)) +to each of the other threads that must change its credentials. +Before sending these signals, the thread that is changing credentials +saves the new credential(s) and records the system call being employed +in a global buffer. +A signal handler in the receiving thread(s) fetches this information and +then uses the same system call to change its credentials. +.P +Wrapper functions employing this technique are provided for +.BR setgid (2), +.BR setuid (2), +.BR setegid (2), +.BR seteuid (2), +.BR setregid (2), +.BR setreuid (2), +.BR setresgid (2), +.BR setresuid (2), +and +.BR setgroups (2). +.\" FIXME . +.\" Maybe say something about vfork() not being serialized wrt set*id() APIs? +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14749 +.SH STANDARDS +For details of the conformance of NPTL to the POSIX standard, see +.BR pthreads (7). +.SH NOTES +POSIX says +.\" See POSIX.1-2008 specification of pthread_mutexattr_init() +that any thread in any process with access to the memory +containing a process-shared +.RB ( PTHREAD_PROCESS_SHARED ) +mutex can operate on that mutex. +However, on 64-bit x86 systems, the mutex definition for x86-64 +is incompatible with the mutex definition for i386, +.\" See sysdeps/x86/bits/pthreadtypes.h +meaning that 32-bit and 64-bit binaries can't share mutexes on x86-64 systems. +.SH SEE ALSO +.BR credentials (7), +.BR pthreads (7), +.BR signal (7), +.BR standards (7) diff --git a/man/man7/numa.7 b/man/man7/numa.7 new file mode 100644 index 0000000..2907756 --- /dev/null +++ b/man/man7/numa.7 @@ -0,0 +1,170 @@ +.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" and Copyright 2003,2004 Andi Kleen, SuSE Labs. +.\" numa_maps material Copyright (c) 2005 Silicon Graphics Incorporated. +.\" Christoph Lameter, . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH numa 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +numa \- overview of Non-Uniform Memory Architecture +.SH DESCRIPTION +Non-Uniform Memory Access (NUMA) refers to multiprocessor systems +whose memory is divided into multiple memory nodes. +The access time of a memory node depends on +the relative locations of the accessing CPU and the accessed node. +(This contrasts with a symmetric multiprocessor system, +where the access time for all of the memory is the same for all CPUs.) +Normally, each CPU on a NUMA system has a local memory node whose +contents can be accessed faster than the memory in +the node local to another CPU +or the memory on a bus shared by all CPUs. +.SS NUMA system calls +The Linux kernel implements the following NUMA-related system calls: +.BR get_mempolicy (2), +.BR mbind (2), +.BR migrate_pages (2), +.BR move_pages (2), +and +.BR set_mempolicy (2). +However, applications should normally use the interface provided by +.IR libnuma ; +see "Library Support" below. +.SS \fI/proc/\fPpid\fI/numa_maps\fP (since Linux 2.6.14) +.\" See also Changelog-2.6.14 +This file displays information about a process's +NUMA memory policy and allocation. +.P +Each line contains information about a memory range used by the process, +displaying\[em]among other information\[em]the effective memory policy for +that memory range and on which nodes the pages have been allocated. +.P +.I numa_maps +is a read-only file. +When +.IR /proc/ pid /numa_maps +is read, the kernel will scan the virtual address space of the +process and report how memory is used. +One line is displayed for each unique memory range of the process. +.P +The first field of each line shows the starting address of the memory range. +This field allows a correlation with the contents of the +.IR /proc/ pid /maps +file, +which contains the end address of the range and other information, +such as the access permissions and sharing. +.P +The second field shows the memory policy currently in effect for the +memory range. +Note that the effective policy is not necessarily the policy +installed by the process for that memory range. +Specifically, if the process installed a "default" policy for that range, +the effective policy for that range will be the process policy, +which may or may not be "default". +.P +The rest of the line contains information about the pages allocated in +the memory range, as follows: +.TP +.I N= +The number of pages allocated on +.IR . +.I +includes only pages currently mapped by the process. +Page migration and memory reclaim may have temporarily unmapped pages +associated with this memory range. +These pages may show up again only after the process has +attempted to reference them. +If the memory range represents a shared memory area or file mapping, +other processes may currently have additional pages mapped in a +corresponding memory range. +.TP +.I file= +The file backing the memory range. +If the file is mapped as private, write accesses may have generated +COW (Copy-On-Write) pages in this memory range. +These pages are displayed as anonymous pages. +.TP +.I heap +Memory range is used for the heap. +.TP +.I stack +Memory range is used for the stack. +.TP +.I huge +Huge memory range. +The page counts shown are huge pages and not regular sized pages. +.TP +.I anon= +The number of anonymous page in the range. +.TP +.I dirty= +Number of dirty pages. +.TP +.I mapped= +Total number of mapped pages, if different from +.I dirty +and +.I anon +pages. +.TP +.I mapmax= +Maximum mapcount (number of processes mapping a single page) encountered +during the scan. +This may be used as an indicator of the degree of sharing occurring in a +given memory range. +.TP +.I swapcache= +Number of pages that have an associated entry on a swap device. +.TP +.I active= +The number of pages on the active list. +This field is shown only if different from the number of pages in this range. +This means that some inactive pages exist in the memory range that may be +removed from memory by the swapper soon. +.TP +.I writeback= +Number of pages that are currently being written out to disk. +.SH STANDARDS +None. +.SH NOTES +The Linux NUMA system calls and +.I /proc +interface are available only +if the kernel was configured and built with the +.B CONFIG_NUMA +option. +.SS Library support +Link with \fI\-lnuma\fP +to get the system call definitions. +.I libnuma +and the required +.I +header are available in the +.I numactl +package. +.P +However, applications should not use these system calls directly. +Instead, the higher level interface provided by the +.BR numa (3) +functions in the +.I numactl +package is recommended. +The +.I numactl +package is available at +.UR ftp://oss.sgi.com\:/www\:/projects\:/libnuma\:/download/ +.UE . +The package is also included in some Linux distributions. +Some distributions include the development library and header +in the separate +.I numactl\-devel +package. +.SH SEE ALSO +.BR get_mempolicy (2), +.BR mbind (2), +.BR move_pages (2), +.BR set_mempolicy (2), +.BR numa (3), +.BR cpuset (7), +.BR numactl (8) diff --git a/man/man7/operator.7 b/man/man7/operator.7 new file mode 100644 index 0000000..d4ac97a --- /dev/null +++ b/man/man7/operator.7 @@ -0,0 +1,54 @@ +'\" t +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" @(#)operator.7 8.1 (Berkeley) 6/9/93 +.\" +.\" Copied shamelessly from FreeBSD with minor changes. 2003-05-21 +.\" Brian M. Carlson +.\" +.\" Restored automatic formatting from FreeBSD. 2003-08-24 +.\" Martin Schulze +.\" +.\" 2007-12-08, mtk, Converted from mdoc to man macros +.\" +.TH operator 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +operator \- C operator precedence and order of evaluation +.SH DESCRIPTION +This manual page lists C operators and their precedence in evaluation. +.P +.TS +lb lb lb +l l l. +Operator Associativity Notes +[] () . \-> ++ \-\- left to right [1] +++ \-\- & * + \- \[ti] ! sizeof right to left [2] +(type) right to left +* / % left to right ++ \- left to right +<< >> left to right +< > <= >= left to right +== != left to right +& left to right +\[ha] left to right +| left to right +&& left to right +|| left to right +?: right to left += *= /= %= += \-= <<= >>= &= \[ha]= |= right to left +, left to right +.TE +.P +The following notes provide further information to the above table: +.P +.PD 0 +.IP [1] 5 +The ++ and \-\- operators at this precedence level are +the postfix flavors of the operators. +.IP [2] +The ++ and \-\- operators at this precedence level are +the prefix flavors of the operators. +.PD diff --git a/man/man7/packet.7 b/man/man7/packet.7 new file mode 100644 index 0000000..d933b9c --- /dev/null +++ b/man/man7/packet.7 @@ -0,0 +1,694 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $ +.\" +.TH packet 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +packet \- packet interface on device level +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include /* the L2 protocols */ +.P +.BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol ); +.fi +.SH DESCRIPTION +Packet sockets are used to receive or send raw packets at the device driver +(OSI Layer 2) level. +They allow the user to implement protocol modules in user space +on top of the physical layer. +.P +The +.I socket_type +is either +.B SOCK_RAW +for raw packets including the link-level header or +.B SOCK_DGRAM +for cooked packets with the link-level header removed. +The link-level header information is available in a common format in a +.I sockaddr_ll +structure. +.I protocol +is the IEEE 802.3 protocol number in network byte order. +See the +.I +include file for a list of allowed protocols. +When protocol +is set to +.BR htons(ETH_P_ALL) , +then all protocols are received. +All incoming packets of that protocol type will be passed to the packet +socket before they are passed to the protocols implemented in the kernel. +If +.I protocol +is set to zero, +no packets are received. +.BR bind (2) +can optionally be called with a nonzero +.I sll_protocol +to start receiving packets for the protocols specified. +.P +In order to create a packet socket, a process must have the +.B CAP_NET_RAW +capability in the user namespace that governs its network namespace. +.P +.B SOCK_RAW +packets are passed to and from the device driver without any changes in +the packet data. +When receiving a packet, the address is still parsed and +passed in a standard +.I sockaddr_ll +address structure. +When transmitting a packet, the user-supplied buffer +should contain the physical-layer header. +That packet is then +queued unmodified to the network driver of the interface defined by the +destination address. +Some device drivers always add other headers. +.B SOCK_RAW +is similar to but not compatible with the obsolete +.B AF_INET/SOCK_PACKET +of Linux 2.0. +.P +.B SOCK_DGRAM +operates on a slightly higher level. +The physical header is removed before the packet is passed to the user. +Packets sent through a +.B SOCK_DGRAM +packet socket get a suitable physical-layer header based on the +information in the +.I sockaddr_ll +destination address before they are queued. +.P +By default, all packets of the specified protocol type +are passed to a packet socket. +To get packets only from a specific interface use +.BR bind (2) +specifying an address in a +.I struct sockaddr_ll +to bind the packet socket to an interface. +Fields used for binding are +.I sll_family +(should be +.BR AF_PACKET ), +.IR sll_protocol , +and +.IR sll_ifindex . +.P +The +.BR connect (2) +operation is not supported on packet sockets. +.P +When the +.B MSG_TRUNC +flag is passed to +.BR recvmsg (2), +.BR recv (2), +or +.BR recvfrom (2), +the real length of the packet on the wire is always returned, +even when it is longer than the buffer. +.SS Address types +The +.I sockaddr_ll +structure is a device-independent physical-layer address. +.P +.in +4n +.EX +struct sockaddr_ll { + unsigned short sll_family; /* Always AF_PACKET */ + unsigned short sll_protocol; /* Physical\-layer protocol */ + int sll_ifindex; /* Interface number */ + unsigned short sll_hatype; /* ARP hardware type */ + unsigned char sll_pkttype; /* Packet type */ + unsigned char sll_halen; /* Length of address */ + unsigned char sll_addr[8]; /* Physical\-layer address */ +}; +.EE +.in +.P +The fields of this structure are as follows: +.TP +.I sll_protocol +is the standard ethernet protocol type in network byte order as defined +in the +.I +include file. +It defaults to the socket's protocol. +.TP +.I sll_ifindex +is the interface index of the interface +(see +.BR netdevice (7)); +0 matches any interface (only permitted for binding). +.I sll_hatype +is an ARP type as defined in the +.I +include file. +.TP +.I sll_pkttype +contains the packet type. +Valid types are +.B PACKET_HOST +for a packet addressed to the local host, +.B PACKET_BROADCAST +for a physical-layer broadcast packet, +.B PACKET_MULTICAST +for a packet sent to a physical-layer multicast address, +.B PACKET_OTHERHOST +for a packet to some other host that has been caught by a device driver +in promiscuous mode, and +.B PACKET_OUTGOING +for a packet originating from the local host that is looped back to a packet +socket. +These types make sense only for receiving. +.TP +.I sll_addr +.TQ +.I sll_halen +contain the physical-layer (e.g., IEEE 802.3) address and its length. +The exact interpretation depends on the device. +.P +When you send packets, it is enough to specify +.IR sll_family , +.IR sll_addr , +.IR sll_halen , +.IR sll_ifindex , +and +.IR sll_protocol . +The other fields should be 0. +.I sll_hatype +and +.I sll_pkttype +are set on received packets for your information. +.SS Socket options +Packet socket options are configured by calling +.BR setsockopt (2) +with level +.BR SOL_PACKET . +.TP +.B PACKET_ADD_MEMBERSHIP +.PD 0 +.TP +.B PACKET_DROP_MEMBERSHIP +.PD +Packet sockets can be used to configure physical-layer multicasting +and promiscuous mode. +.B PACKET_ADD_MEMBERSHIP +adds a binding and +.B PACKET_DROP_MEMBERSHIP +drops it. +They both expect a +.I packet_mreq +structure as argument: +.IP +.in +4n +.EX +struct packet_mreq { + int mr_ifindex; /* interface index */ + unsigned short mr_type; /* action */ + unsigned short mr_alen; /* address length */ + unsigned char mr_address[8]; /* physical\-layer address */ +}; +.EE +.in +.IP +.I mr_ifindex +contains the interface index for the interface whose status +should be changed. +The +.I mr_type +field specifies which action to perform. +.B PACKET_MR_PROMISC +enables receiving all packets on a shared medium (often known as +"promiscuous mode"), +.B PACKET_MR_MULTICAST +binds the socket to the physical-layer multicast group specified in +.I mr_address +and +.IR mr_alen , +and +.B PACKET_MR_ALLMULTI +sets the socket up to receive all multicast packets arriving at +the interface. +.IP +In addition, the traditional ioctls +.BR SIOCSIFFLAGS , +.BR SIOCADDMULTI , +.B SIOCDELMULTI +can be used for the same purpose. +.TP +.BR PACKET_AUXDATA " (since Linux 2.6.21)" +.\" commit 8dc4194474159660d7f37c495e3fc3f10d0db8cc +If this binary option is enabled, the packet socket passes a metadata +structure along with each packet in the +.BR recvmsg (2) +control field. +The structure can be read with +.BR cmsg (3). +It is defined as +.IP +.in +4n +.EX +struct tpacket_auxdata { + __u32 tp_status; + __u32 tp_len; /* packet length */ + __u32 tp_snaplen; /* captured length */ + __u16 tp_mac; + __u16 tp_net; + __u16 tp_vlan_tci; + __u16 tp_vlan_tpid; /* Since Linux 3.14; earlier, these + were unused padding bytes */ +.\" commit a0cdfcf39362410d5ea983f4daf67b38de129408 added tp_vlan_tpid +}; +.EE +.in +.TP +.BR PACKET_FANOUT " (since Linux 3.1)" +.\" commit dc99f600698dcac69b8f56dda9a8a00d645c5ffc +To scale processing across threads, packet sockets can form a fanout +group. +In this mode, each matching packet is enqueued onto only one +socket in the group. +A socket joins a fanout group by calling +.BR setsockopt (2) +with level +.B SOL_PACKET +and option +.BR PACKET_FANOUT . +Each network namespace can have up to 65536 independent groups. +A socket selects a group by encoding the ID in the first 16 bits of +the integer option value. +The first packet socket to join a group implicitly creates it. +To successfully join an existing group, subsequent packet sockets +must have the same protocol, device settings, fanout mode, and +flags (see below). +Packet sockets can leave a fanout group only by closing the socket. +The group is deleted when the last socket is closed. +.IP +Fanout supports multiple algorithms to spread traffic between sockets, +as follows: +.RS +.IP \[bu] 3 +The default mode, +.BR PACKET_FANOUT_HASH , +sends packets from the same flow to the same socket to maintain +per-flow ordering. +For each packet, it chooses a socket by taking the packet flow hash +modulo the number of sockets in the group, where a flow hash is a hash +over network-layer address and optional transport-layer port fields. +.IP \[bu] +The load-balance mode +.B PACKET_FANOUT_LB +implements a round-robin algorithm. +.IP \[bu] +.B PACKET_FANOUT_CPU +selects the socket based on the CPU that the packet arrived on. +.IP \[bu] +.B PACKET_FANOUT_ROLLOVER +processes all data on a single socket, moving to the next when one +becomes backlogged. +.IP \[bu] +.B PACKET_FANOUT_RND +selects the socket using a pseudo-random number generator. +.IP \[bu] +.B PACKET_FANOUT_QM +.\" commit 2d36097d26b5991d71a2cf4a20c1a158f0f1bfcd +(available since Linux 3.14) +selects the socket using the recorded queue_mapping of the received skb. +.RE +.IP +Fanout modes can take additional options. +IP fragmentation causes packets from the same flow to have different +flow hashes. +The flag +.BR PACKET_FANOUT_FLAG_DEFRAG , +if set, causes packets to be defragmented before fanout is applied, to +preserve order even in this case. +Fanout mode and options are communicated in the second 16 bits of the +integer option value. +The flag +.B PACKET_FANOUT_FLAG_ROLLOVER +enables the roll over mechanism as a backup strategy: if the +original fanout algorithm selects a backlogged socket, the packet +rolls over to the next available one. +.TP +.BR PACKET_LOSS " (with " PACKET_TX_RING ) +When a malformed packet is encountered on a transmit ring, +the default is to reset its +.I tp_status +to +.B TP_STATUS_WRONG_FORMAT +and abort the transmission immediately. +The malformed packet blocks itself and subsequently enqueued packets from +being sent. +The format error must be fixed, the associated +.I tp_status +reset to +.BR TP_STATUS_SEND_REQUEST , +and the transmission process restarted via +.BR send (2). +However, if +.B PACKET_LOSS +is set, any malformed packet will be skipped, its +.I tp_status +reset to +.BR TP_STATUS_AVAILABLE , +and the transmission process continued. +.TP +.BR PACKET_RESERVE " (with " PACKET_RX_RING ) +By default, a packet receive ring writes packets immediately following the +metadata structure and alignment padding. +This integer option reserves additional headroom. +.TP +.B PACKET_RX_RING +Create a memory-mapped ring buffer for asynchronous packet reception. +The packet socket reserves a contiguous region of application address +space, lays it out into an array of packet slots and copies packets +(up to +.IR tp_snaplen ) +into subsequent slots. +Each packet is preceded by a metadata structure similar to +.IR tpacket_auxdata . +The protocol fields encode the offset to the data +from the start of the metadata header. +.I tp_net +stores the offset to the network layer. +If the packet socket is of type +.BR SOCK_DGRAM , +then +.I tp_mac +is the same. +If it is of type +.BR SOCK_RAW , +then that field stores the offset to the link-layer frame. +Packet socket and application communicate the head and tail of the ring +through the +.I tp_status +field. +The packet socket owns all slots with +.I tp_status +equal to +.BR TP_STATUS_KERNEL . +After filling a slot, it changes the status of the slot to transfer +ownership to the application. +During normal operation, the new +.I tp_status +value has at least the +.B TP_STATUS_USER +bit set to signal that a received packet has been stored. +When the application has finished processing a packet, it transfers +ownership of the slot back to the socket by setting +.I tp_status +equal to +.BR TP_STATUS_KERNEL . +.IP +Packet sockets implement multiple variants of the packet ring. +The implementation details are described in +.I Documentation/networking/packet_mmap.rst +in the Linux kernel source tree. +.TP +.B PACKET_STATISTICS +Retrieve packet socket statistics in the form of a structure +.IP +.in +4n +.EX +struct tpacket_stats { + unsigned int tp_packets; /* Total packet count */ + unsigned int tp_drops; /* Dropped packet count */ +}; +.EE +.in +.IP +Receiving statistics resets the internal counters. +The statistics structure differs when using a ring of variant +.BR TPACKET_V3 . +.TP +.BR PACKET_TIMESTAMP " (with " PACKET_RX_RING "; since Linux 2.6.36)" +.\" commit 614f60fa9d73a9e8fdff3df83381907fea7c5649 +The packet receive ring always stores a timestamp in the metadata header. +By default, this is a software generated timestamp generated when the +packet is copied into the ring. +This integer option selects the type of timestamp. +Besides the default, it support the two hardware formats described in +.I Documentation/networking/timestamping.rst +in the Linux kernel source tree. +.TP +.BR PACKET_TX_RING " (since Linux 2.6.31)" +.\" commit 69e3c75f4d541a6eb151b3ef91f34033cb3ad6e1 +Create a memory-mapped ring buffer for packet transmission. +This option is similar to +.B PACKET_RX_RING +and takes the same arguments. +The application writes packets into slots with +.I tp_status +equal to +.B TP_STATUS_AVAILABLE +and schedules them for transmission by changing +.I tp_status +to +.BR TP_STATUS_SEND_REQUEST . +When packets are ready to be transmitted, the application calls +.BR send (2) +or a variant thereof. +The +.I buf +and +.I len +fields of this call are ignored. +If an address is passed using +.BR sendto (2) +or +.BR sendmsg (2), +then that overrides the socket default. +On successful transmission, the socket resets +.I tp_status +to +.BR TP_STATUS_AVAILABLE . +It immediately aborts the transmission on error unless +.B PACKET_LOSS +is set. +.TP +.BR PACKET_VERSION " (with " PACKET_RX_RING "; since Linux 2.6.27)" +.\" commit bbd6ef87c544d88c30e4b762b1b61ef267a7d279 +By default, +.B PACKET_RX_RING +creates a packet receive ring of variant +.BR TPACKET_V1 . +To create another variant, configure the desired variant by setting this +integer option before creating the ring. +.TP +.BR PACKET_QDISC_BYPASS " (since Linux 3.14)" +.\" commit d346a3fae3ff1d99f5d0c819bf86edf9094a26a1 +By default, packets sent through packet sockets pass through the kernel's +qdisc (traffic control) layer, which is fine for the vast majority of use +cases. +For traffic generator appliances using packet sockets +that intend to brute-force flood the network\[em]for example, +to test devices under load in a similar +fashion to pktgen\[em]this layer can be bypassed by setting +this integer option to 1. +A side effect is that packet buffering in the qdisc layer is avoided, +which will lead to increased drops when network +device transmit queues are busy; +therefore, use at your own risk. +.SS Ioctls +.B SIOCGSTAMP +can be used to receive the timestamp of the last received packet. +Argument is a +.I struct timeval +variable. +.\" FIXME Document SIOCGSTAMPNS +.P +In addition, all standard ioctls defined in +.BR netdevice (7) +and +.BR socket (7) +are valid on packet sockets. +.SS Error handling +Packet sockets do no error handling other than errors occurred +while passing the packet to the device driver. +They don't have the concept of a pending error. +.SH ERRORS +.TP +.B EADDRNOTAVAIL +Unknown multicast group address passed. +.TP +.B EFAULT +User passed invalid memory address. +.TP +.B EINVAL +Invalid argument. +.TP +.B EMSGSIZE +Packet is bigger than interface MTU. +.TP +.B ENETDOWN +Interface is not up. +.TP +.B ENOBUFS +Not enough memory to allocate the packet. +.TP +.B ENODEV +Unknown device name or interface index specified in interface address. +.TP +.B ENOENT +No packet received. +.TP +.B ENOTCONN +No interface address passed. +.TP +.B ENXIO +Interface address contained an invalid interface index. +.TP +.B EPERM +User has insufficient privileges to carry out this operation. +.P +In addition, other errors may be generated by the low-level driver. +.SH VERSIONS +.B AF_PACKET +is a new feature in Linux 2.2. +Earlier Linux versions supported only +.BR SOCK_PACKET . +.SH NOTES +For portable programs it is suggested to use +.B AF_PACKET +via +.BR pcap (3); +although this covers only a subset of the +.B AF_PACKET +features. +.P +The +.B SOCK_DGRAM +packet sockets make no attempt to create or parse the IEEE 802.2 LLC +header for a IEEE 802.3 frame. +When +.B ETH_P_802_3 +is specified as protocol for sending the kernel creates the +802.3 frame and fills out the length field; the user has to supply the LLC +header to get a fully conforming packet. +Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol +fields; instead they are supplied to the user as protocol +.B ETH_P_802_2 +with the LLC header prefixed. +It is thus not possible to bind to +.BR ETH_P_802_3 ; +bind to +.B ETH_P_802_2 +instead and do the protocol multiplex yourself. +The default for sending is the standard Ethernet DIX +encapsulation with the protocol filled in. +.P +Packet sockets are not subject to the input or output firewall chains. +.SS Compatibility +In Linux 2.0, the only way to get a packet socket was with the call: +.P +.in +4n +.EX +socket(AF_INET, SOCK_PACKET, protocol) +.EE +.in +.P +This is still supported, but deprecated and strongly discouraged. +The main difference between the two methods is that +.B SOCK_PACKET +uses the old +.I struct sockaddr_pkt +to specify an interface, which doesn't provide physical-layer +independence. +.P +.in +4n +.EX +struct sockaddr_pkt { + unsigned short spkt_family; + unsigned char spkt_device[14]; + unsigned short spkt_protocol; +}; +.EE +.in +.P +.I spkt_family +contains +the device type, +.I spkt_protocol +is the IEEE 802.3 protocol type as defined in +.I +and +.I spkt_device +is the device name as a null-terminated string, for example, eth0. +.P +This structure is obsolete and should not be used in new code. +.SH BUGS +.SS LLC header handling +The IEEE 802.2/803.3 LLC handling could be considered as a bug. +.SS MSG_TRUNC issues +The +.B MSG_TRUNC +.BR recvmsg (2) +extension is an ugly hack and should be replaced by a control message. +There is currently no way to get the original destination address of +packets via +.BR SOCK_DGRAM . +.SS spkt_device device name truncation +The +.I spkt_device +field of +.I sockaddr_pkt +has a size of 14 bytes, +which is less than the constant +.B IFNAMSIZ +defined in +.I +which is 16 bytes and describes the system limit for a network interface name. +This means the names of network devices longer than 14 bytes +will be truncated to fit into +.IR spkt_device . +All these lengths include the terminating null byte (\[aq]\e0\[aq])). +.P +Issues from this with old code typically show up with +very long interface names used by the +.B Predictable Network Interface Names +feature enabled by default in many modern Linux distributions. +.P +The preferred solution is to rewrite code to avoid +.BR SOCK_PACKET . +Possible user solutions are to disable +.B Predictable Network Interface Names +or to rename the interface to a name of at most 13 bytes, +for example using the +.BR ip (8) +tool. +.SS Documentation issues +Socket filters are not documented. +.\" .SH CREDITS +.\" This man page was written by Andi Kleen with help from Matthew Wilcox. +.\" AF_PACKET in Linux 2.2 was implemented +.\" by Alexey Kuznetsov, based on code by Alan Cox and others. +.SH SEE ALSO +.BR socket (2), +.BR pcap (3), +.BR capabilities (7), +.BR ip (7), +.BR raw (7), +.BR socket (7), +.BR ip (8), +.P +RFC\ 894 for the standard IP Ethernet encapsulation. +RFC\ 1700 for the IEEE 802.3 IP encapsulation. +.P +The +.I +include file for physical-layer protocols. +.P +The Linux kernel source tree. +.I Documentation/networking/filter.rst +describes how to apply Berkeley Packet Filters to packet sockets. +.I tools/testing/selftests/net/psock_tpacket.c +contains example source code for all available versions of +.B PACKET_RX_RING +and +.BR PACKET_TX_RING . diff --git a/man/man7/path_resolution.7 b/man/man7/path_resolution.7 new file mode 100644 index 0000000..c07c7e0 --- /dev/null +++ b/man/man7/path_resolution.7 @@ -0,0 +1,264 @@ +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH path_resolution 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +path_resolution \- how a pathname is resolved to a file +.SH DESCRIPTION +Some UNIX/Linux system calls have as parameter one or more filenames. +A filename (or pathname) is resolved as follows. +.SS Step 1: start of the resolution process +If the pathname starts with the \[aq]/\[aq] character, the starting lookup +directory is the root directory of the calling process. +A process inherits its root directory from its parent. +Usually this will be the root directory of the file hierarchy. +A process may get a different root directory by use of the +.BR chroot (2) +system call, or may temporarily use a different root directory by using +.BR openat2 (2) +with the +.B RESOLVE_IN_ROOT +flag set. +.P +A process may get an entirely private mount namespace in case +it\[em]or one of its ancestors\[em]was started by an invocation of the +.BR clone (2) +system call that had the +.B CLONE_NEWNS +flag set. +This handles the \[aq]/\[aq] part of the pathname. +.P +If the pathname does not start with the \[aq]/\[aq] character, the starting +lookup directory of the resolution process is the current working directory of +the process \[em] or in the case of +.BR openat (2)-style +system calls, the +.I dfd +argument (or the current working directory if +.B AT_FDCWD +is passed as the +.I dfd +argument). +The current working directory is inherited from the parent, and can +be changed by use of the +.BR chdir (2) +system call. +.P +Pathnames starting with a \[aq]/\[aq] character are called absolute pathnames. +Pathnames not starting with a \[aq]/\[aq] are called relative pathnames. +.SS Step 2: walk along the path +Set the current lookup directory to the starting lookup directory. +Now, for each nonfinal component of the pathname, where a component +is a substring delimited by \[aq]/\[aq] characters, this component is looked up +in the current lookup directory. +.P +If the process does not have search permission on +the current lookup directory, +an +.B EACCES +error is returned ("Permission denied"). +.P +If the component is not found, an +.B ENOENT +error is returned +("No such file or directory"). +.P +If the component is found, but is neither a directory nor a symbolic link, +an +.B ENOTDIR +error is returned ("Not a directory"). +.P +If the component is found and is a directory, we set the +current lookup directory to that directory, and go to the +next component. +.P +If the component is found and is a symbolic link, +we first resolve this symbolic link +(with the current lookup directory +as starting lookup directory). +Upon error, that error is returned. +If the result is not a directory, an +.B ENOTDIR +error is returned. +If the resolution of the symbolic link is successful and returns a directory, +we set the current lookup directory to that directory, and go to +the next component. +Note that the resolution process here can involve recursion if the +prefix ('dirname') component of a pathname contains a filename +that is a symbolic link that resolves to a directory (where the +prefix component of that directory may contain a symbolic link, and so on). +In order to protect the kernel against stack overflow, and also +to protect against denial of service, there are limits on the +maximum recursion depth, and on the maximum number of symbolic links +followed. +An +.B ELOOP +error is returned when the maximum is +exceeded ("Too many levels of symbolic links"). +.P +.\" +.\" presently: max recursion depth during symlink resolution: 5 +.\" max total number of symbolic links followed: 40 +.\" _POSIX_SYMLOOP_MAX is 8 +As currently implemented on Linux, the maximum number +.\" MAXSYMLINKS is 40 +of symbolic links that will be followed while resolving a pathname is 40. +Before Linux 2.6.18, the limit on the recursion depth was 5. +Starting with Linux 2.6.18, this limit +.\" MAX_NESTED_LINKS +was raised to 8. +In Linux 4.2, +.\" commit 894bc8c4662ba9daceafe943a5ba0dd407da5cd3 +the kernel's pathname-resolution code +was reworked to eliminate the use of recursion, +so that the only limit that remains is the maximum of 40 +resolutions for the entire pathname. +.P +The resolution of symbolic links during this stage can be blocked by using +.BR openat2 (2), +with the +.B RESOLVE_NO_SYMLINKS +flag set. +.SS Step 3: find the final entry +The lookup of the final component of the pathname goes just like +that of all other components, as described in the previous step, +with two differences: (i) the final component need not be a +directory (at least as far as the path resolution process is +concerned\[em]it may have to be a directory, or a nondirectory, because of +the requirements of the specific system call), and (ii) it +is not necessarily an error if the component is not found\[em]maybe +we are just creating it. +The details on the treatment +of the final entry are described in the manual pages of the specific +system calls. +.SS "\&. and .." +By convention, every directory has the entries "." and "..", +which refer to the directory itself and to its parent directory, +respectively. +.P +The path resolution process will assume that these entries have +their conventional meanings, regardless of whether they are +actually present in the physical filesystem. +.P +One cannot walk up past the root: "/.." is the same as "/". +.SS Mount points +After a +.I mount dev path +command, the pathname "path" refers to +the root of the filesystem hierarchy on the device "dev", and no +longer to whatever it referred to earlier. +.P +One can walk out of a mounted filesystem: "path/.." refers to +the parent directory of "path", +outside of the filesystem hierarchy on "dev". +.P +Traversal of mount points can be blocked by using +.BR openat2 (2), +with the +.B RESOLVE_NO_XDEV +flag set (though note that this also restricts bind mount traversal). +.SS Trailing slashes +If a pathname ends in a \[aq]/\[aq], that forces resolution of the preceding +component as in Step 2: +the component preceding the slash either exists and resolves to a directory +or it names a directory that is to be created +immediately after the pathname is resolved. +Otherwise, a trailing \[aq]/\[aq] is ignored. +.SS Final symbolic link +If the last component of a pathname is a symbolic link, then it +depends on the system call whether the file referred to will be +the symbolic link or the result of path resolution on its contents. +For example, the system call +.BR lstat (2) +will operate on the symbolic link, +while +.BR stat (2) +operates on the file pointed to by the symbolic link. +.SS Length limit +There is a maximum length for pathnames. +If the pathname (or some +intermediate pathname obtained while resolving symbolic links) +is too long, an +.B ENAMETOOLONG +error is returned ("Filename too long"). +.SS Empty pathname +In the original UNIX, the empty pathname referred to the current directory. +Nowadays POSIX decrees that an empty pathname must not be resolved +successfully. +Linux returns +.B ENOENT +in this case. +.SS Permissions +The permission bits of a file consist of three groups of three bits; see +.BR chmod (1) +and +.BR stat (2). +The first group of three is used when the effective user ID of +the calling process equals the owner ID of the file. +The second group +of three is used when the group ID of the file either equals the +effective group ID of the calling process, or is one of the +supplementary group IDs of the calling process (as set by +.BR setgroups (2)). +When neither holds, the third group is used. +.P +Of the three bits used, the first bit determines read permission, +the second write permission, and the last execute permission +in case of ordinary files, or search permission in case of directories. +.P +Linux uses the fsuid instead of the effective user ID in permission checks. +Ordinarily the fsuid will equal the effective user ID, but the fsuid can be +changed by the system call +.BR setfsuid (2). +.P +(Here "fsuid" stands for something like "filesystem user ID". +The concept was required for the implementation of a user space +NFS server at a time when processes could send a signal to a process +with the same effective user ID. +It is obsolete now. +Nobody should use +.BR setfsuid (2).) +.P +Similarly, Linux uses the fsgid ("filesystem group ID") +instead of the effective group ID. +See +.BR setfsgid (2). +.\" FIXME . say something about filesystem mounted read-only ? +.SS Bypassing permission checks: superuser and capabilities +On a traditional UNIX system, the superuser +.RI ( root , +user ID 0) is all-powerful, and bypasses all permissions restrictions +when accessing files. +.\" (but for exec at least one x bit must be set) -- AEB +.\" but there is variation across systems on this point: for +.\" example, HP-UX and Tru64 are as described by AEB. However, +.\" on some implementations (e.g., Solaris, FreeBSD), +.\" access(X_OK) by superuser will report success, regardless +.\" of the file's execute permission bits. -- MTK (Oct 05) +.P +On Linux, superuser privileges are divided into capabilities (see +.BR capabilities (7)). +Two capabilities are relevant for file permissions checks: +.B CAP_DAC_OVERRIDE +and +.BR CAP_DAC_READ_SEARCH . +(A process has these capabilities if its fsuid is 0.) +.P +The +.B CAP_DAC_OVERRIDE +capability overrides all permission checking, +but grants execute permission only when at least one +of the file's three execute permission bits is set. +.P +The +.B CAP_DAC_READ_SEARCH +capability grants read and search permission +on directories, and read permission on ordinary files. +.\" FIXME . say something about immutable files +.\" FIXME . say something about ACLs +.SH SEE ALSO +.BR readlink (2), +.BR capabilities (7), +.BR credentials (7), +.BR symlink (7) diff --git a/man/man7/persistent-keyring.7 b/man/man7/persistent-keyring.7 new file mode 100644 index 0000000..6367586 --- /dev/null +++ b/man/man7/persistent-keyring.7 @@ -0,0 +1,124 @@ +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH persistent-keyring 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +persistent-keyring \- per-user persistent keyring +.SH DESCRIPTION +The persistent keyring is a keyring used to anchor keys on behalf of a user. +Each UID the kernel deals with has its own persistent keyring that +is shared between all threads owned by that UID. +The persistent keyring has a name (description) of the form +.I _persistent. +where +.I +is the user ID of the corresponding user. +.P +The persistent keyring may not be accessed directly, +even by processes with the appropriate UID. +.\" FIXME The meaning of the preceding sentence isn't clear. What is meant? +Instead, it must first be linked to one of a process's keyrings, +before that keyring can access the persistent keyring +by virtue of its possessor permits. +This linking is done with the +.BR keyctl_get_persistent (3) +function. +.P +If a persistent keyring does not exist when it is accessed by the +.BR keyctl_get_persistent (3) +operation, it will be automatically created. +.P +Each time the +.BR keyctl_get_persistent (3) +operation is performed, +the persistent keyring's expiration timer is reset to the value in: +.P +.in +4n +.EX +/proc/sys/kernel/keys/persistent_keyring_expiry +.EE +.in +.P +Should the timeout be reached, +the persistent keyring will be removed and +everything it pins can then be garbage collected. +The keyring will then be re-created on a subsequent call to +.BR keyctl_get_persistent (3). +.P +The persistent keyring is not directly searched by +.BR request_key (2); +it is searched only if it is linked into one of the keyrings +that is searched by +.BR request_key (2). +.P +The persistent keyring is independent of +.BR clone (2), +.BR fork (2), +.BR vfork (2), +.BR execve (2), +and +.BR _exit (2). +It persists until its expiration timer triggers, +at which point it is garbage collected. +This allows the persistent keyring to carry keys beyond the life of +the kernel's record of the corresponding UID +(the destruction of which results in the destruction of the +.BR user\-keyring (7) +and the +.BR user\-session\-keyring (7)). +The persistent keyring can thus be used to +hold authentication tokens for processes that run without user interaction, +such as programs started by +.BR cron (8). +.P +The persistent keyring is used to store UID-specific objects that +themselves have limited lifetimes (e.g., kerberos tokens). +If those tokens cease to be used +(i.e., the persistent keyring is not accessed), +then the timeout of the persistent keyring ensures that +the corresponding objects are automatically discarded. +.\" +.SS Special operations +The +.I keyutils +library provides the +.BR keyctl_get_persistent (3) +function for manipulating persistent keyrings. +(This function is an interface to the +.BR keyctl (2) +.B KEYCTL_GET_PERSISTENT +operation.) +This operation allows the calling thread to get the persistent keyring +corresponding to its own UID or, if the thread has the +.B CAP_SETUID +capability, the persistent keyring corresponding to some other UID +in the same user namespace. +.SH NOTES +Each user namespace owns a keyring called +.I .persistent_register +that contains links to all of the persistent keys in that namespace. +(The +.I .persistent_register +keyring can be seen when reading the contents of the +.I /proc/keys +file for the UID 0 in the namespace.) +The +.BR keyctl_get_persistent (3) +operation looks for a key with a name of the form +.IR _persistent. UID +in that keyring, +creates the key if it does not exist, and links it into the keyring. +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyctl_get_persistent (3), +.BR keyrings (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7) diff --git a/man/man7/pid_namespaces.7 b/man/man7/pid_namespaces.7 new file mode 100644 index 0000000..2ffbb15 --- /dev/null +++ b/man/man7/pid_namespaces.7 @@ -0,0 +1,388 @@ +.\" Copyright (c) 2013 by Michael Kerrisk +.\" and Copyright (c) 2012 by Eric W. Biederman +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH pid_namespaces 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pid_namespaces \- overview of Linux PID namespaces +.SH DESCRIPTION +For an overview of namespaces, see +.BR namespaces (7). +.P +PID namespaces isolate the process ID number space, +meaning that processes in different PID namespaces can have the same PID. +PID namespaces allow containers to provide functionality +such as suspending/resuming the set of processes in the container and +migrating the container to a new host +while the processes inside the container maintain the same PIDs. +.P +PIDs in a new PID namespace start at 1, +somewhat like a standalone system, and calls to +.BR fork (2), +.BR vfork (2), +or +.BR clone (2) +will produce processes with PIDs that are unique within the namespace. +.P +Use of PID namespaces requires a kernel that is configured with the +.B CONFIG_PID_NS +option. +.\" +.\" ============================================================ +.\" +.SS The namespace "init" process +The first process created in a new namespace +(i.e., the process created using +.BR clone (2) +with the +.B CLONE_NEWPID +flag, or the first child created by a process after a call to +.BR unshare (2) +using the +.B CLONE_NEWPID +flag) has the PID 1, and is the "init" process for the namespace (see +.BR init (1)). +This process becomes the parent of any child processes that are orphaned +because a process that resides in this PID namespace terminated +(see below for further details). +.P +If the "init" process of a PID namespace terminates, +the kernel terminates all of the processes in the namespace via a +.B SIGKILL +signal. +This behavior reflects the fact that the "init" process +is essential for the correct operation of a PID namespace. +In this case, a subsequent +.BR fork (2) +into this PID namespace fail with the error +.BR ENOMEM ; +it is not possible to create a new process in a PID namespace whose "init" +process has terminated. +Such scenarios can occur when, for example, +a process uses an open file descriptor for a +.IR /proc/ pid /ns/pid +file corresponding to a process that was in a namespace to +.BR setns (2) +into that namespace after the "init" process has terminated. +Another possible scenario can occur after a call to +.BR unshare (2): +if the first child subsequently created by a +.BR fork (2) +terminates, then subsequent calls to +.BR fork (2) +fail with +.BR ENOMEM . +.P +Only signals for which the "init" process has established a signal handler +can be sent to the "init" process by other members of the PID namespace. +This restriction applies even to privileged processes, +and prevents other members of the PID namespace from +accidentally killing the "init" process. +.P +Likewise, a process in an ancestor namespace +can\[em]subject to the usual permission checks described in +.BR kill (2)\[em]send +signals to the "init" process of a child PID namespace only +if the "init" process has established a handler for that signal. +(Within the handler, the +.I siginfo_t +.I si_pid +field described in +.BR sigaction (2) +will be zero.) +.B SIGKILL +or +.B SIGSTOP +are treated exceptionally: +these signals are forcibly delivered when sent from an ancestor PID namespace. +Neither of these signals can be caught by the "init" process, +and so will result in the usual actions associated with those signals +(respectively, terminating and stopping the process). +.P +Starting with Linux 3.4, the +.BR reboot (2) +system call causes a signal to be sent to the namespace "init" process. +See +.BR reboot (2) +for more details. +.\" +.\" ============================================================ +.\" +.SS Nesting PID namespaces +PID namespaces can be nested: +each PID namespace has a parent, +except for the initial ("root") PID namespace. +The parent of a PID namespace is the PID namespace of the process that +created the namespace using +.BR clone (2) +or +.BR unshare (2). +PID namespaces thus form a tree, +with all namespaces ultimately tracing their ancestry to the root namespace. +Since Linux 3.7, +.\" commit f2302505775fd13ba93f034206f1e2a587017929 +.\" The kernel constant MAX_PID_NS_LEVEL +the kernel limits the maximum nesting depth for PID namespaces to 32. +.P +A process is visible to other processes in its PID namespace, +and to the processes in each direct ancestor PID namespace +going back to the root PID namespace. +In this context, "visible" means that one process +can be the target of operations by another process using +system calls that specify a process ID. +Conversely, the processes in a child PID namespace can't see +processes in the parent and further removed ancestor namespaces. +More succinctly: a process can see (e.g., send signals with +.BR kill (2), +set nice values with +.BR setpriority (2), +etc.) only processes contained in its own PID namespace +and in descendants of that namespace. +.P +A process has one process ID in each of the layers of the PID +namespace hierarchy in which is visible, +and walking back though each direct ancestor namespace +through to the root PID namespace. +System calls that operate on process IDs always +operate using the process ID that is visible in the +PID namespace of the caller. +A call to +.BR getpid (2) +always returns the PID associated with the namespace in which +the process was created. +.P +Some processes in a PID namespace may have parents +that are outside of the namespace. +For example, the parent of the initial process in the namespace +(i.e., the +.BR init (1) +process with PID 1) is necessarily in another namespace. +Likewise, the direct children of a process that uses +.BR setns (2) +to cause its children to join a PID namespace are in a different +PID namespace from the caller of +.BR setns (2). +Calls to +.BR getppid (2) +for such processes return 0. +.P +While processes may freely descend into child PID namespaces +(e.g., using +.BR setns (2) +with a PID namespace file descriptor), +they may not move in the other direction. +That is to say, processes may not enter any ancestor namespaces +(parent, grandparent, etc.). +Changing PID namespaces is a one-way operation. +.P +The +.B NS_GET_PARENT +.BR ioctl (2) +operation can be used to discover the parental relationship +between PID namespaces; see +.BR ioctl_ns (2). +.\" +.\" ============================================================ +.\" +.SS setns(2) and unshare(2) semantics +Calls to +.BR setns (2) +that specify a PID namespace file descriptor +and calls to +.BR unshare (2) +with the +.B CLONE_NEWPID +flag cause children subsequently created +by the caller to be placed in a different PID namespace from the caller. +(Since Linux 4.12, that PID namespace is shown via the +.IR /proc/ pid /ns/pid_for_children +file, as described in +.BR namespaces (7).) +These calls do not, however, +change the PID namespace of the calling process, +because doing so would change the caller's idea of its own PID +(as reported by +.BR getpid ()), +which would break many applications and libraries. +.P +To put things another way: +a process's PID namespace membership is determined when the process is created +and cannot be changed thereafter. +Among other things, this means that the parental relationship +between processes mirrors the parental relationship between PID namespaces: +the parent of a process is either in the same namespace +or resides in the immediate parent PID namespace. +.P +A process may call +.BR unshare (2) +with the +.B CLONE_NEWPID +flag only once. +After it has performed this operation, its +.IR /proc/ pid /ns/pid_for_children +symbolic link will be empty until the first child is created in the namespace. +.\" +.\" ============================================================ +.\" +.SS Adoption of orphaned children +When a child process becomes orphaned, it is reparented to the "init" +process in the PID namespace of its parent +(unless one of the nearer ancestors of the parent employed the +.BR prctl (2) +.B PR_SET_CHILD_SUBREAPER +command to mark itself as the reaper of orphaned descendant processes). +Note that because of the +.BR setns (2) +and +.BR unshare (2) +semantics described above, this may be the "init" process in the PID +namespace that is the +.I parent +of the child's PID namespace, +rather than the "init" process in the child's own PID namespace. +.\" Furthermore, by definition, the parent of the "init" process +.\" of a PID namespace resides in the parent PID namespace. +.\" +.\" ============================================================ +.\" +.SS Compatibility of CLONE_NEWPID with other CLONE_* flags +In current versions of Linux, +.B CLONE_NEWPID +can't be combined with +.BR CLONE_THREAD . +Threads are required to be in the same PID namespace such that +the threads in a process can send signals to each other. +Similarly, it must be possible to see all of the threads +of a process in the +.BR proc (5) +filesystem. +Additionally, if two threads were in different PID +namespaces, the process ID of the process sending a signal +could not be meaningfully encoded when a signal is sent +(see the description of the +.I siginfo_t +type in +.BR sigaction (2)). +Since this is computed when a signal is enqueued, +a signal queue shared by processes in multiple PID namespaces +would defeat that. +.P +.\" Note these restrictions were all introduced in +.\" 8382fcac1b813ad0a4e68a838fc7ae93fa39eda0 +.\" when CLONE_NEWPID|CLONE_VM was disallowed +In earlier versions of Linux, +.B CLONE_NEWPID +was additionally disallowed (failing with the error +.BR EINVAL ) +in combination with +.B CLONE_SIGHAND +.\" (restriction lifted in faf00da544045fdc1454f3b9e6d7f65c841de302) +(before Linux 4.3) as well as +.\" (restriction lifted in e79f525e99b04390ca4d2366309545a836c03bf1) +.B CLONE_VM +(before Linux 3.12). +The changes that lifted these restrictions have also been ported to +earlier stable kernels. +.\" +.\" ============================================================ +.\" +.SS /proc and PID namespaces +A +.I /proc +filesystem shows (in the +.IR /proc/ pid +directories) only processes visible in the PID namespace +of the process that performed the mount, even if the +.I /proc +filesystem is viewed from processes in other namespaces. +.P +After creating a new PID namespace, +it is useful for the child to change its root directory +and mount a new procfs instance at +.I /proc +so that tools such as +.BR ps (1) +work correctly. +If a new mount namespace is simultaneously created by including +.B CLONE_NEWNS +in the +.I flags +argument of +.BR clone (2) +or +.BR unshare (2), +then it isn't necessary to change the root directory: +a new procfs instance can be mounted directly over +.IR /proc . +.P +From a shell, the command to mount +.I /proc +is: +.P +.in +4n +.EX +$ mount \-t proc proc /proc +.EE +.in +.P +Calling +.BR readlink (2) +on the path +.I /proc/self +yields the process ID of the caller in the PID namespace of the procfs mount +(i.e., the PID namespace of the process that mounted the procfs). +This can be useful for introspection purposes, +when a process wants to discover its PID in other namespaces. +.\" +.\" ============================================================ +.\" +.SS /proc files +.TP +.BR /proc/sys/kernel/ns_last_pid " (since Linux 3.3)" +.\" commit b8f566b04d3cddd192cfd2418ae6d54ac6353792 +This file +(which is virtualized per PID namespace) +displays the last PID that was allocated in this PID namespace. +When the next PID is allocated, +the kernel will search for the lowest unallocated PID +that is greater than this value, +and when this file is subsequently read it will show that PID. +.IP +This file is writable by a process that has the +.B CAP_SYS_ADMIN +or (since Linux 5.9) +.B CAP_CHECKPOINT_RESTORE +capability inside the user namespace that owns the PID namespace. +.\" This ability is necessary to support checkpoint restore in user-space +This makes it possible to determine the PID that is allocated +to the next process that is created inside this PID namespace. +.\" +.\" ============================================================ +.\" +.SS Miscellaneous +When a process ID is passed over a UNIX domain socket to a +process in a different PID namespace (see the description of +.B SCM_CREDENTIALS +in +.BR unix (7)), +it is translated into the corresponding PID value in +the receiving process's PID namespace. +.SH STANDARDS +Linux. +.SH EXAMPLES +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR clone (2), +.BR reboot (2), +.BR setns (2), +.BR unshare (2), +.BR proc (5), +.BR capabilities (7), +.BR credentials (7), +.BR mount_namespaces (7), +.BR namespaces (7), +.BR user_namespaces (7), +.BR switch_root (8) diff --git a/man/man7/pipe.7 b/man/man7/pipe.7 new file mode 100644 index 0000000..a62f507 --- /dev/null +++ b/man/man7/pipe.7 @@ -0,0 +1,407 @@ +.\" Copyright (C) 2005 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pipe 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pipe \- overview of pipes and FIFOs +.SH DESCRIPTION +Pipes and FIFOs (also known as named pipes) +provide a unidirectional interprocess communication channel. +A pipe has a +.I read end +and a +.IR "write end" . +Data written to the write end of a pipe can be read +from the read end of the pipe. +.P +A pipe is created using +.BR pipe (2), +which creates a new pipe and returns two file descriptors, +one referring to the read end of the pipe, +the other referring to the write end. +Pipes can be used to create a communication channel between related +processes; see +.BR pipe (2) +for an example. +.P +A FIFO (short for First In First Out) has a name within the filesystem +(created using +.BR mkfifo (3)), +and is opened using +.BR open (2). +Any process may open a FIFO, assuming the file permissions allow it. +The read end is opened using the +.B O_RDONLY +flag; the write end is opened using the +.B O_WRONLY +flag. +See +.BR fifo (7) +for further details. +.IR Note : +although FIFOs have a pathname in the filesystem, +I/O on FIFOs does not involve operations on the underlying device +(if there is one). +.SS I/O on pipes and FIFOs +The only difference between pipes and FIFOs is the manner in which +they are created and opened. +Once these tasks have been accomplished, +I/O on pipes and FIFOs has exactly the same semantics. +.P +If a process attempts to read from an empty pipe, then +.BR read (2) +will block until data is available. +If a process attempts to write to a full pipe (see below), then +.BR write (2) +blocks until sufficient data has been read from the pipe +to allow the write to complete. +.P +Nonblocking I/O is possible by using the +.BR fcntl (2) +.B F_SETFL +operation to enable the +.B O_NONBLOCK +open file status flag or by opening a +.BR fifo (7) +with +.BR O_NONBLOCK . +If any process has the pipe open for writing, reads fail with +.BR EAGAIN ; +otherwise\[em]with no potential writers\[em]reads succeed and return empty. +.P +The communication channel provided by a pipe is a +.IR "byte stream" : +there is no concept of message boundaries. +.P +If all file descriptors referring to the write end of a pipe +have been closed, then an attempt to +.BR read (2) +from the pipe will see end-of-file +.RB ( read (2) +will return 0). +If all file descriptors referring to the read end of a pipe +have been closed, then a +.BR write (2) +will cause a +.B SIGPIPE +signal to be generated for the calling process. +If the calling process is ignoring this signal, then +.BR write (2) +fails with the error +.BR EPIPE . +An application that uses +.BR pipe (2) +and +.BR fork (2) +should use suitable +.BR close (2) +calls to close unnecessary duplicate file descriptors; +this ensures that end-of-file and +.BR SIGPIPE / EPIPE +are delivered when appropriate. +.P +It is not possible to apply +.BR lseek (2) +to a pipe. +.SS Pipe capacity +A pipe has a limited capacity. +If the pipe is full, then a +.BR write (2) +will block or fail, depending on whether the +.B O_NONBLOCK +flag is set (see below). +Different implementations have different limits for the pipe capacity. +Applications should not rely on a particular capacity: +an application should be designed so that a reading process consumes data +as soon as it is available, +so that a writing process does not remain blocked. +.P +Before Linux 2.6.11, the capacity of a pipe was the same as +the system page size (e.g., 4096 bytes on i386). +Since Linux 2.6.11, the pipe capacity is 16 pages +(i.e., 65,536 bytes in a system with a page size of 4096 bytes). +Since Linux 2.6.35, the default pipe capacity is 16 pages, +but the capacity can be queried and set using the +.BR fcntl (2) +.B F_GETPIPE_SZ +and +.B F_SETPIPE_SZ +operations. +See +.BR fcntl (2) +for more information. +.P +The following +.BR ioctl (2) +operation, which can be applied to a file descriptor +that refers to either end of a pipe, +places a count of the number of unread bytes in the pipe in the +.I int +buffer pointed to by the final argument of the call: +.P +.in +4n +.EX +ioctl(fd, FIONREAD, &nbytes); +.EE +.in +.P +The +.B FIONREAD +operation is not specified in any standard, +but is provided on many implementations. +.\" +.SS /proc files +On Linux, the following files control how much memory can be used for pipes: +.TP +.IR /proc/sys/fs/pipe\-max\-pages " (only in Linux 2.6.34)" +.\" commit b492e95be0ae672922f4734acf3f5d35c30be948 +An upper limit, in pages, on the capacity that an unprivileged user +(one without the +.B CAP_SYS_RESOURCE +capability) +can set for a pipe. +.IP +The default value for this limit is 16 times the default pipe capacity +(see above); the lower limit is two pages. +.IP +This interface was removed in Linux 2.6.35, in favor of +.IR /proc/sys/fs/pipe\-max\-size . +.TP +.IR /proc/sys/fs/pipe\-max\-size " (since Linux 2.6.35)" +.\" commit ff9da691c0498ff81fdd014e7a0731dab2337dac +The maximum size (in bytes) of individual pipes that can be set +.\" This limit is not checked on pipe creation, where the capacity is +.\" always PIPE_DEF_BUFS, regardless of pipe-max-size +by users without the +.B CAP_SYS_RESOURCE +capability. +The value assigned to this file may be rounded upward, +to reflect the value actually employed for a convenient implementation. +To determine the rounded-up value, +display the contents of this file after assigning a value to it. +.IP +The default value for this file is 1048576 (1\ MiB). +The minimum value that can be assigned to this file is the system page size. +Attempts to set a limit less than the page size cause +.BR write (2) +to fail with the error +.BR EINVAL . +.IP +Since Linux 4.9, +.\" commit 086e774a57fba4695f14383c0818994c0b31da7c +the value on this file also acts as a ceiling on the default capacity +of a new pipe or newly opened FIFO. +.TP +.IR /proc/sys/fs/pipe\-user\-pages\-hard " (since Linux 4.5)" +.\" commit 759c01142a5d0f364a462346168a56de28a80f52 +The hard limit on the total size (in pages) of all pipes created or set by +a single unprivileged user (i.e., one with neither the +.B CAP_SYS_RESOURCE +nor the +.B CAP_SYS_ADMIN +capability). +So long as the total number of pages allocated to pipe buffers +for this user is at this limit, +attempts to create new pipes will be denied, +and attempts to increase a pipe's capacity will be denied. +.IP +When the value of this limit is zero (which is the default), +no hard limit is applied. +.\" The default was chosen to avoid breaking existing applications that +.\" make intensive use of pipes (e.g., for splicing). +.TP +.IR /proc/sys/fs/pipe\-user\-pages\-soft " (since Linux 4.5)" +.\" commit 759c01142a5d0f364a462346168a56de28a80f52 +The soft limit on the total size (in pages) of all pipes created or set by +a single unprivileged user (i.e., one with neither the +.B CAP_SYS_RESOURCE +nor the +.B CAP_SYS_ADMIN +capability). +So long as the total number of pages allocated to pipe buffers +for this user is at this limit, +individual pipes created by a user will be limited to one page, +and attempts to increase a pipe's capacity will be denied. +.IP +When the value of this limit is zero, no soft limit is applied. +The default value for this file is 16384, +which permits creating up to 1024 pipes with the default capacity. +.P +Before Linux 4.9, some bugs affected the handling of the +.I pipe\-user\-pages\-soft +and +.I pipe\-user\-pages\-hard +limits; see BUGS. +.\" +.SS PIPE_BUF +POSIX.1 says that writes of less than +.B PIPE_BUF +bytes must be atomic: the output data is written to the pipe as a +contiguous sequence. +Writes of more than +.B PIPE_BUF +bytes may be nonatomic: the kernel may interleave the data +with data written by other processes. +POSIX.1 requires +.B PIPE_BUF +to be at least 512 bytes. +(On Linux, +.B PIPE_BUF +is 4096 bytes.) +The precise semantics depend on whether the file descriptor is nonblocking +.RB ( O_NONBLOCK ), +whether there are multiple writers to the pipe, and on +.IR n , +the number of bytes to be written: +.TP +\fBO_NONBLOCK\fP disabled, \fIn\fP <= \fBPIPE_BUF\fP +All +.I n +bytes are written atomically; +.BR write (2) +may block if there is not room for +.I n +bytes to be written immediately +.TP +\fBO_NONBLOCK\fP enabled, \fIn\fP <= \fBPIPE_BUF\fP +If there is room to write +.I n +bytes to the pipe, then +.BR write (2) +succeeds immediately, writing all +.I n +bytes; otherwise +.BR write (2) +fails, with +.I errno +set to +.BR EAGAIN . +.TP +\fBO_NONBLOCK\fP disabled, \fIn\fP > \fBPIPE_BUF\fP +The write is nonatomic: the data given to +.BR write (2) +may be interleaved with +.BR write (2)s +by other process; +the +.BR write (2) +blocks until +.I n +bytes have been written. +.TP +\fBO_NONBLOCK\fP enabled, \fIn\fP > \fBPIPE_BUF\fP +If the pipe is full, then +.BR write (2) +fails, with +.I errno +set to +.BR EAGAIN . +Otherwise, from 1 to +.I n +bytes may be written (i.e., a "partial write" may occur; +the caller should check the return value from +.BR write (2) +to see how many bytes were actually written), +and these bytes may be interleaved with writes by other processes. +.SS Open file status flags +The only open file status flags that can be meaningfully applied to +a pipe or FIFO are +.B O_NONBLOCK +and +.BR O_ASYNC . +.P +Setting the +.B O_ASYNC +flag for the read end of a pipe causes a signal +.RB ( SIGIO +by default) to be generated when new input becomes available on the pipe. +The target for delivery of signals must be set using the +.BR fcntl (2) +.B F_SETOWN +command. +On Linux, +.B O_ASYNC +is supported for pipes and FIFOs only since Linux 2.6. +.SS Portability notes +On some systems (but not Linux), pipes are bidirectional: +data can be transmitted in both directions between the pipe ends. +POSIX.1 requires only unidirectional pipes. +Portable applications should avoid reliance on +bidirectional pipe semantics. +.SS BUGS +Before Linux 4.9, some bugs affected the handling of the +.I pipe\-user\-pages\-soft +and +.I pipe\-user\-pages\-hard +limits when using the +.BR fcntl (2) +.B F_SETPIPE_SZ +operation to change a pipe's capacity: +.\" These bugs where remedied by a series of patches, in particular, +.\" commit b0b91d18e2e97b741b294af9333824ecc3fadfd8 and +.\" commit a005ca0e6813e1d796a7422a7e31d8b8d6555df1 +.IP (a) 5 +When increasing the pipe capacity, the checks against the soft and +hard limits were made against existing consumption, +and excluded the memory required for the increased pipe capacity. +The new increase in pipe capacity could then push the total +memory used by the user for pipes (possibly far) over a limit. +(This could also trigger the problem described next.) +.IP +Starting with Linux 4.9, +the limit checking includes the memory required for the new pipe capacity. +.IP (b) +The limit checks were performed even when the new pipe capacity was +less than the existing pipe capacity. +This could lead to problems if a user set a large pipe capacity, +and then the limits were lowered, with the result that the user could +no longer decrease the pipe capacity. +.IP +Starting with Linux 4.9, checks against the limits +are performed only when increasing a pipe's capacity; +an unprivileged user can always decrease a pipe's capacity. +.IP (c) +The accounting and checking against the limits were done as follows: +.RS +.IP (1) 5 +.PD 0 +Test whether the user has exceeded the limit. +.IP (2) +Make the new pipe buffer allocation. +.IP (3) +Account new allocation against the limits. +.PD +.RE +.IP +This was racey. +Multiple processes could pass point (1) simultaneously, +and then allocate pipe buffers that were accounted for only in step (3), +with the result that the user's pipe buffer +allocation could be pushed over the limit. +.IP +Starting with Linux 4.9, +the accounting step is performed before doing the allocation, +and the operation fails if the limit would be exceeded. +.P +Before Linux 4.9, bugs similar to points (a) and (c) could also occur +when the kernel allocated memory for a new pipe buffer; +that is, when calling +.BR pipe (2) +and when opening a previously unopened FIFO. +.SH SEE ALSO +.BR mkfifo (1), +.BR dup (2), +.BR fcntl (2), +.BR open (2), +.BR pipe (2), +.BR poll (2), +.BR select (2), +.BR socketpair (2), +.BR splice (2), +.BR stat (2), +.BR tee (2), +.BR vmsplice (2), +.BR mkfifo (3), +.BR epoll (7), +.BR fifo (7) diff --git a/man/man7/pkeys.7 b/man/man7/pkeys.7 new file mode 100644 index 0000000..e7f92a4 --- /dev/null +++ b/man/man7/pkeys.7 @@ -0,0 +1,237 @@ +.\" Copyright (C) 2016 Intel Corporation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pkeys 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pkeys \- overview of Memory Protection Keys +.SH DESCRIPTION +Memory Protection Keys (pkeys) are an extension to existing +page-based memory permissions. +Normal page permissions using +page tables require expensive system calls and TLB invalidations +when changing permissions. +Memory Protection Keys provide a mechanism for changing +protections without requiring modification of the page tables on +every permission change. +.P +To use pkeys, software must first "tag" a page in the page tables +with a pkey. +After this tag is in place, an application only has +to change the contents of a register in order to remove write +access, or all access to a tagged page. +.P +Protection keys work in conjunction with the existing +.BR PROT_READ , +.BR PROT_WRITE , +and +.B PROT_EXEC +permissions passed to system calls such as +.BR mprotect (2) +and +.BR mmap (2), +but always act to further restrict these traditional permission +mechanisms. +.P +If a process performs an access that violates pkey +restrictions, it receives a +.B SIGSEGV +signal. +See +.BR sigaction (2) +for details of the information available with that signal. +.P +To use the pkeys feature, the processor must support it, and the kernel +must contain support for the feature on a given processor. +As of early 2016 only future Intel x86 processors are supported, +and this hardware supports 16 protection keys in each process. +However, pkey 0 is used as the default key, so a maximum of 15 +are available for actual application use. +The default key is assigned to any memory region for which a +pkey has not been explicitly assigned via +.BR pkey_mprotect (2). +.P +Protection keys have the potential to add a layer of security and +reliability to applications. +But they have not been primarily designed as +a security feature. +For instance, WRPKRU is a completely unprivileged +instruction, so pkeys are useless in any case that an attacker controls +the PKRU register or can execute arbitrary instructions. +.P +Applications should be very careful to ensure that they do not "leak" +protection keys. +For instance, before calling +.BR pkey_free (2), +the application should be sure that no memory has that pkey assigned. +If the application left the freed pkey assigned, a future user of +that pkey might inadvertently change the permissions of an unrelated +data structure, which could impact security or stability. +The kernel currently allows in-use pkeys to have +.BR pkey_free (2) +called on them because it would have processor or memory performance +implications to perform the additional checks needed to disallow it. +Implementation of the necessary checks is left up to applications. +Applications may implement these checks by searching the +.IR /proc/ pid /smaps +file for memory regions with the pkey assigned. +Further details can be found in +.BR proc (5). +.P +Any application wanting to use protection keys needs to be able +to function without them. +They might be unavailable because the hardware that the +application runs on does not support them, the kernel code does +not contain support, the kernel support has been disabled, or +because the keys have all been allocated, perhaps by a library +the application is using. +It is recommended that applications wanting to use protection +keys should simply call +.BR pkey_alloc (2) +and test whether the call succeeds, +instead of attempting to detect support for the +feature in any other way. +.P +Although unnecessary, hardware support for protection keys may be +enumerated with the +.I cpuid +instruction. +Details of how to do this can be found in the Intel Software +Developers Manual. +The kernel performs this enumeration and exposes the information in +.I /proc/cpuinfo +under the "flags" field. +The string "pku" in this field indicates hardware support for protection +keys and the string "ospke" indicates that the kernel contains and has +enabled protection keys support. +.P +Applications using threads and protection keys should be especially +careful. +Threads inherit the protection key rights of the parent at the time +of the +.BR clone (2), +system call. +Applications should either ensure that their own permissions are +appropriate for child threads at the time when +.BR clone (2) +is called, or ensure that each child thread can perform its +own initialization of protection key rights. +.\" +.SS Signal Handler Behavior +Each time a signal handler is invoked (including nested signals), the +thread is temporarily given a new, default set of protection key rights +that override the rights from the interrupted context. +This means that applications must re-establish their desired protection +key rights upon entering a signal handler if the desired rights differ +from the defaults. +The rights of any interrupted context are restored when the signal +handler returns. +.P +This signal behavior is unusual and is due to the fact that the x86 PKRU +register (which stores protection key access rights) is managed with the +same hardware mechanism (XSAVE) that manages floating-point registers. +The signal behavior is the same as that of floating-point registers. +.\" +.SS Protection Keys system calls +The Linux kernel implements the following pkey-related system calls: +.BR pkey_mprotect (2), +.BR pkey_alloc (2), +and +.BR pkey_free (2). +.P +The Linux pkey system calls are available only if the kernel was +configured and built with the +.B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS +option. +.SH EXAMPLES +The program below allocates a page of memory with read and write permissions. +It then writes some data to the memory and successfully reads it +back. +After that, it attempts to allocate a protection key and +disallows access to the page by using the WRPKRU instruction. +It then tries to access the page, +which we now expect to cause a fatal signal to the application. +.P +.in +4n +.EX +.RB "$" " ./a.out" +buffer contains: 73 +about to read buffer again... +Segmentation fault (core dumped) +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +\& +int +main(void) +{ + int status; + int pkey; + int *buffer; +\& + /* + * Allocate one page of memory. + */ + buffer = mmap(NULL, getpagesize(), PROT_READ | PROT_WRITE, + MAP_ANONYMOUS | MAP_PRIVATE, \-1, 0); + if (buffer == MAP_FAILED) + err(EXIT_FAILURE, "mmap"); +\& + /* + * Put some random data into the page (still OK to touch). + */ + *buffer = __LINE__; + printf("buffer contains: %d\en", *buffer); +\& + /* + * Allocate a protection key: + */ + pkey = pkey_alloc(0, 0); + if (pkey == \-1) + err(EXIT_FAILURE, "pkey_alloc"); +\& + /* + * Disable access to any memory with "pkey" set, + * even though there is none right now. + */ + status = pkey_set(pkey, PKEY_DISABLE_ACCESS); + if (status) + err(EXIT_FAILURE, "pkey_set"); +\& + /* + * Set the protection key on "buffer". + * Note that it is still read/write as far as mprotect() is + * concerned and the previous pkey_set() overrides it. + */ + status = pkey_mprotect(buffer, getpagesize(), + PROT_READ | PROT_WRITE, pkey); + if (status == \-1) + err(EXIT_FAILURE, "pkey_mprotect"); +\& + printf("about to read buffer again...\en"); +\& + /* + * This will crash, because we have disallowed access. + */ + printf("buffer contains: %d\en", *buffer); +\& + status = pkey_free(pkey); + if (status == \-1) + err(EXIT_FAILURE, "pkey_free"); +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR pkey_alloc (2), +.BR pkey_free (2), +.BR pkey_mprotect (2), +.BR sigaction (2) diff --git a/man/man7/posixoptions.7 b/man/man7/posixoptions.7 new file mode 100644 index 0000000..e9de31f --- /dev/null +++ b/man/man7/posixoptions.7 @@ -0,0 +1,1014 @@ +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH posixoptions 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +posixoptions \- optional parts of the POSIX standard +.SH DESCRIPTION +The POSIX standard (the information below is from POSIX.1-2001) +describes a set of behaviors and interfaces for a compliant system. +However, many interfaces are optional and there are feature test macros +to test the availability of interfaces at compile time, and functions +.BR sysconf (3), +.BR fpathconf (3), +.BR pathconf (3), +.BR confstr (3) +to do this at run time. +From shell scripts one can use +.BR getconf (1). +For more detail, see +.BR sysconf (3). +.P +We give the name of the POSIX abbreviation, the option, the name of the +.BR sysconf (3) +parameter used to inquire about the option, and possibly +a very short description. +Much more precise detail can be found in the POSIX standard itself, +versions of which can nowadays be accessed freely on the web. +.SS ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO +The following advisory functions are present: +.P +.nf +.in +4n +.IR posix_fadvise () +.IR posix_fallocate () +.IR posix_memalign () +.IR posix_madvise () +.in +.fi +.SS AIO - _POSIX_ASYNCHRONOUS_IO - _SC_ASYNCHRONOUS_IO +The header +.I +is present. +The following functions are present: +.P +.nf +.in +4n +.IR aio_cancel () +.IR aio_error () +.IR aio_fsync () +.IR aio_read () +.IR aio_return () +.IR aio_suspend () +.IR aio_write () +.IR lio_listio () +.in +.fi +.SS BAR - _POSIX_BARRIERS - _SC_BARRIERS +This option implies the +.B _POSIX_THREADS +and +.B _POSIX_THREAD_SAFE_FUNCTIONS +options. +The following functions are present: +.P +.nf +.in +4n +.IR pthread_barrier_destroy () +.IR pthread_barrier_init () +.IR pthread_barrier_wait () +.IR pthread_barrierattr_destroy () +.IR pthread_barrierattr_init () +.in +.fi +.\" .SS BE +.\" Batch environment. +.\" .SS CD +.\" C development. +.SS --- - POSIX_CHOWN_RESTRICTED +If this option is in effect (as it always is under POSIX.1-2001), +then only root may change the owner of a file, and nonroot can +set the group of a file only to one of the groups it belongs to. +This affects the following functions: +.P +.nf +.in +4n +.IR chown () +.IR fchown () +.in +.fi +.\" What about lchown() ? +.SS CS - _POSIX_CLOCK_SELECTION - _SC_CLOCK_SELECTION +This option implies the +.B _POSIX_TIMERS +option. +The following functions are present: +.P +.nf +.in +4n +.IR pthread_condattr_getclock () +.IR pthread_condattr_setclock () +.IR clock_nanosleep () +.in +.fi +.P +If +.B CLOCK_REALTIME +is changed by the function +.IR clock_settime (), +then this affects all timers set for an absolute time. +.SS CPT - _POSIX_CPUTIME - _SC_CPUTIME +The +.B CLOCK_PROCESS_CPUTIME_ID +clock ID is supported. +The initial value of this clock is 0 for each process. +This option implies the +.B _POSIX_TIMERS +option. +The function +.IR clock_getcpuclockid () +is present. +.\" .SS FD +.\" Fortran development +.\" .SS FR +.\" Fortran runtime +.SS --- - _POSIX_FILE_LOCKING - _SC_FILE_LOCKING +This option has been deleted. +Not in final XPG6. +.SS FSC - _POSIX_FSYNC - _SC_FSYNC +The function +.IR fsync () +is present. +.SS IP6 - _POSIX_IPV6 - _SC_IPV6 +Internet Protocol Version 6 is supported. +.SS --- - _POSIX_JOB_CONTROL - _SC_JOB_CONTROL +If this option is in effect (as it always is under POSIX.1-2001), +then the system implements POSIX-style job control, +and the following functions are present: +.P +.nf +.in +4n +.IR setpgid () +.IR tcdrain () +.IR tcflush () +.IR tcgetpgrp () +.IR tcsendbreak () +.IR tcsetattr () +.IR tcsetpgrp () +.in +.fi +.SS MF - _POSIX_MAPPED_FILES - _SC_MAPPED_FILES +Shared memory is supported. +The include file +.I +is present. +The following functions are present: +.P +.nf +.in +4n +.IR mmap () +.IR msync () +.IR munmap () +.in +.fi +.SS ML - _POSIX_MEMLOCK - _SC_MEMLOCK +Shared memory can be locked into core. +The following functions are present: +.P +.nf +.in +4n +.IR mlockall () +.IR munlockall () +.in +.fi +.SS MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE +More precisely, ranges can be locked into core. +The following functions are present: +.P +.nf +.in +4n +.IR mlock () +.IR munlock () +.in +.fi +.SS MPR - _POSIX_MEMORY_PROTECTION - _SC_MEMORY_PROTECTION +The function +.IR mprotect () +is present. +.SS MSG - _POSIX_MESSAGE_PASSING - _SC_MESSAGE_PASSING +The include file +.I +is present. +The following functions are present: +.P +.nf +.in +4n +.IR mq_close () +.IR mq_getattr () +.IR mq_notify () +.IR mq_open () +.IR mq_receive () +.IR mq_send () +.IR mq_setattr () +.IR mq_unlink () +.in +.fi +.SS MON - _POSIX_MONOTONIC_CLOCK - _SC_MONOTONIC_CLOCK +.B CLOCK_MONOTONIC +is supported. +This option implies the +.B _POSIX_TIMERS +option. +The following functions are affected: +.P +.nf +.in +4n +.IR aio_suspend () +.IR clock_getres () +.IR clock_gettime () +.IR clock_settime () +.IR timer_create () +.in +.fi +.SS --- - _POSIX_MULTI_PROCESS - _SC_MULTI_PROCESS +This option has been deleted. +Not in final XPG6. +.\" .SS MX +.\" IEC 60559 Floating-Point Option. +.SS --- - _POSIX_NO_TRUNC +If this option is in effect (as it always is under POSIX.1-2001), +then pathname components longer than +.B NAME_MAX +are not truncated, +but give an error. +This property may be dependent on the path prefix of the component. +.SS PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO +This option says that one can specify priorities for asynchronous I/O. +This affects the functions +.P +.nf +.in +4n +.IR aio_read () +.IR aio_write () +.in +.fi +.SS PS - _POSIX_PRIORITY_SCHEDULING - _SC_PRIORITY_SCHEDULING +The include file +.I +is present. +The following functions are present: +.P +.nf +.in +4n +.IR sched_get_priority_max () +.IR sched_get_priority_min () +.IR sched_getparam () +.IR sched_getscheduler () +.IR sched_rr_get_interval () +.IR sched_setparam () +.IR sched_setscheduler () +.IR sched_yield () +.in +.fi +.P +If also +.B _POSIX_SPAWN +is in effect, then the following functions are present: +.P +.nf +.in +4n +.IR posix_spawnattr_getschedparam () +.IR posix_spawnattr_getschedpolicy () +.IR posix_spawnattr_setschedparam () +.IR posix_spawnattr_setschedpolicy () +.in +.fi +.SS RS - _POSIX_RAW_SOCKETS +Raw sockets are supported. +The following functions are affected: +.P +.nf +.in +4n +.IR getsockopt () +.IR setsockopt () +.in +.fi +.SS --- - _POSIX_READER_WRITER_LOCKS - _SC_READER_WRITER_LOCKS +This option implies the +.B _POSIX_THREADS +option. +Conversely, +under POSIX.1-2001 the +.B _POSIX_THREADS +option implies this option. +.P +The following functions are present: +.P +.in +4n +.nf +.IR pthread_rwlock_destroy () +.IR pthread_rwlock_init () +.IR pthread_rwlock_rdlock () +.IR pthread_rwlock_tryrdlock () +.IR pthread_rwlock_trywrlock () +.IR pthread_rwlock_unlock () +.IR pthread_rwlock_wrlock () +.IR pthread_rwlockattr_destroy () +.IR pthread_rwlockattr_init () +.in +.fi +.SS RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS +Realtime signals are supported. +The following functions are present: +.P +.nf +.in +4n +.IR sigqueue () +.IR sigtimedwait () +.IR sigwaitinfo () +.in +.fi +.SS --- - _POSIX_REGEXP - _SC_REGEXP +If this option is in effect (as it always is under POSIX.1-2001), +then POSIX regular expressions are supported +and the following functions are present: +.P +.nf +.in +4n +.IR regcomp () +.IR regerror () +.IR regexec () +.IR regfree () +.in +.fi +.SS --- - _POSIX_SAVED_IDS - _SC_SAVED_IDS +If this option is in effect (as it always is under POSIX.1-2001), +then a process has a saved set-user-ID and a saved set-group-ID. +The following functions are affected: +.P +.nf +.in +4n +.IR exec () +.IR kill () +.IR seteuid () +.IR setegid () +.IR setgid () +.IR setuid () +.in +.fi +.\" .SS SD +.\" Software development +.SS SEM - _POSIX_SEMAPHORES - _SC_SEMAPHORES +The include file +.I +is present. +The following functions are present: +.P +.nf +.in +4n +.IR sem_close () +.IR sem_destroy () +.IR sem_getvalue () +.IR sem_init () +.IR sem_open () +.IR sem_post () +.IR sem_trywait () +.IR sem_unlink () +.IR sem_wait () +.in +.fi +.SS SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS +The following functions are present: +.P +.nf +.in +4n +.IR mmap () +.IR munmap () +.IR shm_open () +.IR shm_unlink () +.in +.fi +.SS --- - _POSIX_SHELL - _SC_SHELL +If this option is in effect (as it always is under POSIX.1-2001), +the function +.IR system () +is present. +.SS SPN - _POSIX_SPAWN - _SC_SPAWN +This option describes support for process creation in a context where +it is difficult or impossible to use +.IR fork (), +for example, because no MMU is present. +.P +If +.B _POSIX_SPAWN +is in effect, then the include file +.I +and the following functions are present: +.P +.nf +.in +4n +.IR posix_spawn () +.IR posix_spawn_file_actions_addclose () +.IR posix_spawn_file_actions_adddup2 () +.IR posix_spawn_file_actions_addopen () +.IR posix_spawn_file_actions_destroy () +.IR posix_spawn_file_actions_init () +.IR posix_spawnattr_destroy () +.IR posix_spawnattr_getsigdefault () +.IR posix_spawnattr_getflags () +.IR posix_spawnattr_getpgroup () +.IR posix_spawnattr_getsigmask () +.IR posix_spawnattr_init () +.IR posix_spawnattr_setsigdefault () +.IR posix_spawnattr_setflags () +.IR posix_spawnattr_setpgroup () +.IR posix_spawnattr_setsigmask () +.IR posix_spawnp () +.in +.fi +.P +If also +.B _POSIX_PRIORITY_SCHEDULING +is in effect, then +the following functions are present: +.P +.nf +.in +4n +.IR posix_spawnattr_getschedparam () +.IR posix_spawnattr_getschedpolicy () +.IR posix_spawnattr_setschedparam () +.IR posix_spawnattr_setschedpolicy () +.in +.fi +.SS SPI - _POSIX_SPIN_LOCKS - _SC_SPIN_LOCKS +This option implies the +.B _POSIX_THREADS +and +.B _POSIX_THREAD_SAFE_FUNCTIONS +options. +The following functions are present: +.P +.nf +.in +4n +.IR pthread_spin_destroy () +.IR pthread_spin_init () +.IR pthread_spin_lock () +.IR pthread_spin_trylock () +.IR pthread_spin_unlock () +.in -4n +.fi +.SS SS - _POSIX_SPORADIC_SERVER - _SC_SPORADIC_SERVER +The scheduling policy +.B SCHED_SPORADIC +is supported. +This option implies the +.B _POSIX_PRIORITY_SCHEDULING +option. +The following functions are affected: +.P +.nf +.in +4n +.IR sched_setparam () +.IR sched_setscheduler () +.in +.fi +.SS SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO +The following functions are affected: +.P +.nf +.in +4n +.IR open () +.IR msync () +.IR fsync () +.IR fdatasync () +.in +.fi +.SS TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR +The following functions are affected: +.P +.nf +.in +4n +.IR pthread_attr_getstack () +.IR pthread_attr_getstackaddr () +.IR pthread_attr_setstack () +.IR pthread_attr_setstackaddr () +.in +.fi +.SS TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE +The following functions are affected: +.P +.nf +.in +4n +.IR pthread_attr_getstack () +.IR pthread_attr_getstacksize () +.IR pthread_attr_setstack () +.IR pthread_attr_setstacksize () +.in +.fi +.SS TCT - _POSIX_THREAD_CPUTIME - _SC_THREAD_CPUTIME +The clockID CLOCK_THREAD_CPUTIME_ID is supported. +This option implies the +.B _POSIX_TIMERS +option. +The following functions are affected: +.P +.nf +.in +4n +.IR pthread_getcpuclockid () +.IR clock_getres () +.IR clock_gettime () +.IR clock_settime () +.IR timer_create () +.in +.fi +.SS TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT +The following functions are affected: +.P +.nf +.in +4n +.IR pthread_mutexattr_getprotocol () +.IR pthread_mutexattr_setprotocol () +.in +.fi +.SS TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT +The following functions are affected: +.P +.nf +.in +4n +.IR pthread_mutex_getprioceiling () +.IR pthread_mutex_setprioceiling () +.IR pthread_mutexattr_getprioceiling () +.IR pthread_mutexattr_getprotocol () +.IR pthread_mutexattr_setprioceiling () +.IR pthread_mutexattr_setprotocol () +.in +.fi +.SS TPS - _POSIX_THREAD_PRIORITY_SCHEDULING - _SC_THREAD_PRIORITY_SCHEDULING +If this option is in effect, the different threads inside a process +can run with different priorities and/or different schedulers. +The following functions are affected: +.P +.nf +.in +4n +.IR pthread_attr_getinheritsched () +.IR pthread_attr_getschedpolicy () +.IR pthread_attr_getscope () +.IR pthread_attr_setinheritsched () +.IR pthread_attr_setschedpolicy () +.IR pthread_attr_setscope () +.IR pthread_getschedparam () +.IR pthread_setschedparam () +.IR pthread_setschedprio () +.in +.fi +.SS TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED +The following functions are affected: +.P +.nf +.in +4n +.IR pthread_barrierattr_getpshared () +.IR pthread_barrierattr_setpshared () +.IR pthread_condattr_getpshared () +.IR pthread_condattr_setpshared () +.IR pthread_mutexattr_getpshared () +.IR pthread_mutexattr_setpshared () +.IR pthread_rwlockattr_getpshared () +.IR pthread_rwlockattr_setpshared () +.in +.fi +.SS TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS +The following functions are affected: +.P +.nf +.in +4n +.IR readdir_r () +.IR getgrgid_r () +.IR getgrnam_r () +.IR getpwnam_r () +.IR getpwuid_r () +.IR flockfile () +.IR ftrylockfile () +.IR funlockfile () +.IR getc_unlocked () +.IR getchar_unlocked () +.IR putc_unlocked () +.IR putchar_unlocked () +.IR rand_r () +.IR strerror_r () +.IR strtok_r () +.IR asctime_r () +.IR ctime_r () +.IR gmtime_r () +.IR localtime_r () +.in +.fi +.SS TSP - _POSIX_THREAD_SPORADIC_SERVER - _SC_THREAD_SPORADIC_SERVER +This option implies the +.B _POSIX_THREAD_PRIORITY_SCHEDULING +option. +The following functions are affected: +.P +.nf +.in +4n +.IR sched_getparam () +.IR sched_setparam () +.IR sched_setscheduler () +.in +.fi +.SS THR - _POSIX_THREADS - _SC_THREADS +Basic support for POSIX threads is available. +The following functions are present: +.P +.nf +.in +4n +.IR pthread_atfork () +.IR pthread_attr_destroy () +.IR pthread_attr_getdetachstate () +.IR pthread_attr_getschedparam () +.IR pthread_attr_init () +.IR pthread_attr_setdetachstate () +.IR pthread_attr_setschedparam () +.IR pthread_cancel () +.IR pthread_cleanup_push () +.IR pthread_cleanup_pop () +.IR pthread_cond_broadcast () +.IR pthread_cond_destroy () +.IR pthread_cond_init () +.IR pthread_cond_signal () +.IR pthread_cond_timedwait () +.IR pthread_cond_wait () +.IR pthread_condattr_destroy () +.IR pthread_condattr_init () +.IR pthread_create () +.IR pthread_detach () +.IR pthread_equal () +.IR pthread_exit () +.IR pthread_getspecific () +.IR pthread_join () +.IR pthread_key_create () +.IR pthread_key_delete () +.IR pthread_mutex_destroy () +.IR pthread_mutex_init () +.IR pthread_mutex_lock () +.IR pthread_mutex_trylock () +.IR pthread_mutex_unlock () +.IR pthread_mutexattr_destroy () +.IR pthread_mutexattr_init () +.IR pthread_once () +.IR pthread_rwlock_destroy () +.IR pthread_rwlock_init () +.IR pthread_rwlock_rdlock () +.IR pthread_rwlock_tryrdlock () +.IR pthread_rwlock_trywrlock () +.IR pthread_rwlock_unlock () +.IR pthread_rwlock_wrlock () +.IR pthread_rwlockattr_destroy () +.IR pthread_rwlockattr_init () +.IR pthread_self () +.IR pthread_setcancelstate () +.IR pthread_setcanceltype () +.IR pthread_setspecific () +.IR pthread_testcancel () +.in +.fi +.SS TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS +The following functions are present: +.P +.nf +.in +4n +.IR mq_timedreceive () +.IR mq_timedsend () +.IR pthread_mutex_timedlock () +.IR pthread_rwlock_timedrdlock () +.IR pthread_rwlock_timedwrlock () +.IR sem_timedwait () +.IR posix_trace_timedgetnext_event () +.in +.fi +.SS TMR - _POSIX_TIMERS - _SC_TIMERS +The following functions are present: +.P +.nf +.in +4n +.IR clock_getres () +.IR clock_gettime () +.IR clock_settime () +.IR nanosleep () +.IR timer_create () +.IR timer_delete () +.IR timer_gettime () +.IR timer_getoverrun () +.IR timer_settime () +.in +.fi +.SS TRC - _POSIX_TRACE - _SC_TRACE +POSIX tracing is available. +The following functions are present: +.P +.nf +.in +4n +.IR posix_trace_attr_destroy () +.IR posix_trace_attr_getclockres () +.IR posix_trace_attr_getcreatetime () +.IR posix_trace_attr_getgenversion () +.IR posix_trace_attr_getmaxdatasize () +.IR posix_trace_attr_getmaxsystemeventsize () +.IR posix_trace_attr_getmaxusereventsize () +.IR posix_trace_attr_getname () +.IR posix_trace_attr_getstreamfullpolicy () +.IR posix_trace_attr_getstreamsize () +.IR posix_trace_attr_init () +.IR posix_trace_attr_setmaxdatasize () +.IR posix_trace_attr_setname () +.IR posix_trace_attr_setstreamsize () +.IR posix_trace_attr_setstreamfullpolicy () +.IR posix_trace_clear () +.IR posix_trace_create () +.IR posix_trace_event () +.IR posix_trace_eventid_equal () +.IR posix_trace_eventid_get_name () +.IR posix_trace_eventid_open () +.IR posix_trace_eventtypelist_getnext_id () +.IR posix_trace_eventtypelist_rewind () +.IR posix_trace_flush () +.IR posix_trace_get_attr () +.IR posix_trace_get_status () +.IR posix_trace_getnext_event () +.IR posix_trace_shutdown () +.IR posix_trace_start () +.IR posix_trace_stop () +.IR posix_trace_trygetnext_event () +.in +.fi +.SS TEF - _POSIX_TRACE_EVENT_FILTER - _SC_TRACE_EVENT_FILTER +This option implies the +.B _POSIX_TRACE +option. +The following functions are present: +.P +.nf +.in +4n +.IR posix_trace_eventset_add () +.IR posix_trace_eventset_del () +.IR posix_trace_eventset_empty () +.IR posix_trace_eventset_fill () +.IR posix_trace_eventset_ismember () +.IR posix_trace_get_filter () +.IR posix_trace_set_filter () +.IR posix_trace_trid_eventid_open () +.in +.fi +.SS TRI - _POSIX_TRACE_INHERIT - _SC_TRACE_INHERIT +Tracing children of the traced process is supported. +This option implies the +.B _POSIX_TRACE +option. +The following functions are present: +.P +.nf +.in +4n +.IR posix_trace_attr_getinherited () +.IR posix_trace_attr_setinherited () +.in +.fi +.SS TRL - _POSIX_TRACE_LOG - _SC_TRACE_LOG +This option implies the +.B _POSIX_TRACE +option. +The following functions are present: +.P +.nf +.in +4n +.IR posix_trace_attr_getlogfullpolicy () +.IR posix_trace_attr_getlogsize () +.IR posix_trace_attr_setlogfullpolicy () +.IR posix_trace_attr_setlogsize () +.IR posix_trace_close () +.IR posix_trace_create_withlog () +.IR posix_trace_open () +.IR posix_trace_rewind () +.in +.fi +.SS TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT +The following functions are present: +.P +.nf +.in +4n +.IR posix_mem_offset () +.IR posix_typed_mem_get_info () +.IR posix_typed_mem_open () +.in +.fi +.SS --- - _POSIX_VDISABLE +Always present (probably 0). +Value to set a changeable special control +character to indicate that it is disabled. +.SH X/OPEN SYSTEM INTERFACE EXTENSIONS +.SS XSI - _XOPEN_CRYPT - _SC_XOPEN_CRYPT +The following functions are present: +.P +.nf +.in +4n +.IR crypt () +.IR encrypt () +.IR setkey () +.fi +.SS XSI - _XOPEN_REALTIME - _SC_XOPEN_REALTIME +This option implies the following options: +.P +.PD 0 +.TP +.BR _POSIX_ASYNCHRONOUS_IO == 200112L +.TP +.B _POSIX_FSYNC +.TP +.B _POSIX_MAPPED_FILES +.TP +.BR _POSIX_MEMLOCK == 200112L +.TP +.BR _POSIX_MEMLOCK_RANGE == 200112L +.TP +.B _POSIX_MEMORY_PROTECTION +.TP +.BR _POSIX_MESSAGE_PASSING == 200112L +.TP +.B _POSIX_PRIORITIZED_IO +.TP +.BR _POSIX_PRIORITY_SCHEDULING == 200112L +.TP +.BR _POSIX_REALTIME_SIGNALS == 200112L +.TP +.BR _POSIX_SEMAPHORES == 200112L +.TP +.BR _POSIX_SHARED_MEMORY_OBJECTS == 200112L +.TP +.BR _POSIX_SYNCHRONIZED_IO == 200112L +.TP +.BR _POSIX_TIMERS == 200112L +.PD +.\" +.SS ADV - --- - --- +The Advanced Realtime option group implies that the following options +are all defined to 200112L: +.P +.PD 0 +.TP +.B _POSIX_ADVISORY_INFO +.TP +.B _POSIX_CLOCK_SELECTION +(implies +.BR _POSIX_TIMERS ) +.TP +.B _POSIX_CPUTIME +(implies +.BR _POSIX_TIMERS ) +.TP +.B _POSIX_MONOTONIC_CLOCK +(implies +.BR _POSIX_TIMERS ) +.TP +.B _POSIX_SPAWN +.TP +.B _POSIX_SPORADIC_SERVER +(implies +.BR _POSIX_PRIORITY_SCHEDULING ) +.TP +.B _POSIX_TIMEOUTS +.TP +.B _POSIX_TYPED_MEMORY_OBJECTS +.PD +.\" +.SS XSI - _XOPEN_REALTIME_THREADS - _SC_XOPEN_REALTIME_THREADS +This option implies that the following options +are all defined to 200112L: +.P +.PD 0 +.TP +.B _POSIX_THREAD_PRIO_INHERIT +.TP +.B _POSIX_THREAD_PRIO_PROTECT +.TP +.B _POSIX_THREAD_PRIORITY_SCHEDULING +.PD +.SS ADVANCED REALTIME THREADS - --- - --- +This option implies that the following options +are all defined to 200112L: +.P +.PD 0 +.TP +.B _POSIX_BARRIERS +(implies +.BR _POSIX_THREADS , +.BR _POSIX_THREAD_SAFE_FUNCTIONS ) +.TP +.B _POSIX_SPIN_LOCKS +(implies +.BR _POSIX_THREADS , +.BR _POSIX_THREAD_SAFE_FUNCTIONS ) +.TP +.B _POSIX_THREAD_CPUTIME +(implies +.BR _POSIX_TIMERS ) +.TP +.B _POSIX_THREAD_SPORADIC_SERVER +(implies +.BR _POSIX_THREAD_PRIORITY_SCHEDULING ) +.PD +.\" +.SS TRACING - --- - --- +This option implies that the following options +are all defined to 200112L: +.P +.PD 0 +.TP +.B _POSIX_TRACE +.TP +.B _POSIX_TRACE_EVENT_FILTER +.TP +.B _POSIX_TRACE_LOG +.TP +.B _POSIX_TRACE_INHERIT +.PD +.SS STREAMS - _XOPEN_STREAMS - _SC_XOPEN_STREAMS +The following functions are present: +.P +.nf +.in +4n +.IR fattach () +.IR fdetach () +.IR getmsg () +.IR getpmsg () +.IR ioctl () +.IR isastream () +.IR putmsg () +.IR putpmsg () +.in +.fi +.SS XSI - _XOPEN_LEGACY - _SC_XOPEN_LEGACY +Functions included in the legacy option group were previously mandatory, +but are now optional in this version. +The following functions are present: +.P +.nf +.in +4n +.IR bcmp () +.IR bcopy () +.IR bzero () +.IR ecvt () +.IR fcvt () +.IR ftime () +.IR gcvt () +.IR getwd () +.IR index () +.IR mktemp () +.IR rindex () +.IR utimes () +.IR wcswcs () +.in +.fi +.SS XSI - _XOPEN_UNIX - _SC_XOPEN_UNIX +The following functions are present: +.P +.nf +.in +4n +.IR mmap () +.IR munmap () +.IR msync () +.in +.fi +.P +This option implies the following options: +.P +.PD 0 +.TP +.B _POSIX_FSYNC +.TP +.B _POSIX_MAPPED_FILES +.TP +.B _POSIX_MEMORY_PROTECTION +.TP +.B _POSIX_THREAD_ATTR_STACKADDR +.TP +.B _POSIX_THREAD_ATTR_STACKSIZE +.TP +.B _POSIX_THREAD_PROCESS_SHARED +.TP +.B _POSIX_THREAD_SAFE_FUNCTIONS +.TP +.B _POSIX_THREADS +.PD +.P +This option may imply the following options from the XSI option groups: +.P +.PD 0 +.TP +.RB "Encryption (" _XOPEN_CRYPT ) +.TP +.RB "Realtime (" _XOPEN_REALTIME ) +.TP +.RB "Advanced Realtime (" ADB ) +.TP +.RB "Realtime Threads (" _XOPEN_REALTIME_THREADS ) +.TP +.RB "Advanced Realtime Threads (" "ADVANCED REALTIME THREADS" ) +.TP +.RB "Tracing (" TRACING ) +.TP +.RB "XSI Streams (" STREAMS ) +.TP +.RB "Legacy (" _XOPEN_LEGACY ) +.PD +.SH SEE ALSO +.BR sysconf (3), +.BR standards (7) diff --git a/man/man7/precedence.7 b/man/man7/precedence.7 new file mode 100644 index 0000000..6ef216d --- /dev/null +++ b/man/man7/precedence.7 @@ -0,0 +1 @@ +.so man7/operator.7 diff --git a/man/man7/process-keyring.7 b/man/man7/process-keyring.7 new file mode 100644 index 0000000..8889971 --- /dev/null +++ b/man/man7/process-keyring.7 @@ -0,0 +1,55 @@ +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH process-keyring 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +process-keyring \- per-process shared keyring +.SH DESCRIPTION +The process keyring is a keyring used to anchor keys on behalf of a process. +It is created only when a process requests it. +The process keyring has the name (description) +.IR _pid . +.P +A special serial number value, +.BR KEY_SPEC_PROCESS_KEYRING , +is defined that can be used in lieu of the actual serial number of +the calling process's process keyring. +.P +From the +.BR keyctl (1) +utility, '\fB@p\fP' can be used instead of a numeric key ID in +much the same way, but since +.BR keyctl (1) +is a program run after forking, this is of no utility. +.P +A thread created using the +.BR clone (2) +.B CLONE_THREAD +flag has the same process keyring as the caller of +.BR clone (2). +When a new process is created using +.BR fork () +it initially has no process keyring. +A process's process keyring is cleared on +.BR execve (2). +The process keyring is destroyed when the last +thread that refers to it terminates. +.P +If a process doesn't have a process keyring when it is accessed, +then the process keyring will be created if the keyring is to be modified; +otherwise, the error +.B ENOKEY +results. +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyrings (7), +.BR persistent\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7) diff --git a/man/man7/pthreads.7 b/man/man7/pthreads.7 new file mode 100644 index 0000000..7079847 --- /dev/null +++ b/man/man7/pthreads.7 @@ -0,0 +1,937 @@ +.\" Copyright (c) 2005 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthreads 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pthreads \- POSIX threads +.SH DESCRIPTION +POSIX.1 specifies a set of interfaces (functions, header files) for +threaded programming commonly known as POSIX threads, or Pthreads. +A single process can contain multiple threads, +all of which are executing the same program. +These threads share the same global memory (data and heap segments), +but each thread has its own stack (automatic variables). +.P +POSIX.1 also requires that threads share a range of other attributes +(i.e., these attributes are process-wide rather than per-thread): +.IP \[bu] 3 +process ID +.IP \[bu] +parent process ID +.IP \[bu] +process group ID and session ID +.IP \[bu] +controlling terminal +.IP \[bu] +user and group IDs +.IP \[bu] +open file descriptors +.IP \[bu] +record locks (see +.BR fcntl (2)) +.IP \[bu] +signal dispositions +.IP \[bu] +file mode creation mask +.RB ( umask (2)) +.IP \[bu] +current directory +.RB ( chdir (2)) +and +root directory +.RB ( chroot (2)) +.IP \[bu] +interval timers +.RB ( setitimer (2)) +and POSIX timers +.RB ( timer_create (2)) +.IP \[bu] +nice value +.RB ( setpriority (2)) +.IP \[bu] +resource limits +.RB ( setrlimit (2)) +.IP \[bu] +measurements of the consumption of CPU time +.RB ( times (2)) +and resources +.RB ( getrusage (2)) +.P +As well as the stack, POSIX.1 specifies that various other +attributes are distinct for each thread, including: +.IP \[bu] 3 +thread ID (the +.I pthread_t +data type) +.IP \[bu] +signal mask +.RB ( pthread_sigmask (3)) +.IP \[bu] +the +.I errno +variable +.IP \[bu] +alternate signal stack +.RB ( sigaltstack (2)) +.IP \[bu] +real-time scheduling policy and priority +.RB ( sched (7)) +.P +The following Linux-specific features are also per-thread: +.IP \[bu] 3 +capabilities (see +.BR capabilities (7)) +.IP \[bu] +CPU affinity +.RB ( sched_setaffinity (2)) +.SS Pthreads function return values +Most pthreads functions return 0 on success, and an error number on failure. +The error numbers that can be returned have the same meaning as +the error numbers returned in +.I errno +by conventional system calls and C library functions. +Note that the pthreads functions do not set +.IR errno . +For each of the pthreads functions that can return an error, +POSIX.1-2001 specifies that the function can never fail with the error +.BR EINTR . +.SS Thread IDs +Each of the threads in a process has a unique thread identifier +(stored in the type +.IR pthread_t ). +This identifier is returned to the caller of +.BR pthread_create (3), +and a thread can obtain its own thread identifier using +.BR pthread_self (3). +.P +Thread IDs are guaranteed to be unique only within a process. +(In all pthreads functions that accept a thread ID as an argument, +that ID by definition refers to a thread in +the same process as the caller.) +.P +The system may reuse a thread ID after a terminated thread has been joined, +or a detached thread has terminated. +POSIX says: "If an application attempts to use a thread ID whose +lifetime has ended, the behavior is undefined." +.SS Thread-safe functions +A thread-safe function is one that can be safely +(i.e., it will deliver the same results regardless of whether it is) +called from multiple threads at the same time. +.P +POSIX.1-2001 and POSIX.1-2008 require that all functions specified +in the standard shall be thread-safe, +except for the following functions: +.P +.in +4n +.EX +asctime() +basename() +catgets() +crypt() +ctermid() if passed a non-NULL argument +ctime() +dbm_clearerr() +dbm_close() +dbm_delete() +dbm_error() +dbm_fetch() +dbm_firstkey() +dbm_nextkey() +dbm_open() +dbm_store() +dirname() +dlerror() +drand48() +ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +encrypt() +endgrent() +endpwent() +endutxent() +fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +ftw() +gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +getc_unlocked() +getchar_unlocked() +getdate() +getenv() +getgrent() +getgrgid() +getgrnam() +gethostbyaddr() [POSIX.1-2001 only (function removed in + POSIX.1-2008)] +gethostbyname() [POSIX.1-2001 only (function removed in + POSIX.1-2008)] +gethostent() +getlogin() +getnetbyaddr() +getnetbyname() +getnetent() +getopt() +getprotobyname() +getprotobynumber() +getprotoent() +getpwent() +getpwnam() +getpwuid() +getservbyname() +getservbyport() +getservent() +getutxent() +getutxid() +getutxline() +gmtime() +hcreate() +hdestroy() +hsearch() +inet_ntoa() +l64a() +lgamma() +lgammaf() +lgammal() +localeconv() +localtime() +lrand48() +mrand48() +nftw() +nl_langinfo() +ptsname() +putc_unlocked() +putchar_unlocked() +putenv() +pututxline() +rand() +readdir() +setenv() +setgrent() +setkey() +setpwent() +setutxent() +strerror() +strsignal() [Added in POSIX.1-2008] +strtok() +system() [Added in POSIX.1-2008] +tmpnam() if passed a non-NULL argument +ttyname() +unsetenv() +wcrtomb() if its final argument is NULL +wcsrtombs() if its final argument is NULL +wcstombs() +wctomb() +.EE +.in +.SS Async-cancel-safe functions +An async-cancel-safe function is one that can be safely called +in an application where asynchronous cancelability is enabled (see +.BR pthread_setcancelstate (3)). +.P +Only the following functions are required to be async-cancel-safe by +POSIX.1-2001 and POSIX.1-2008: +.P +.in +4n +.EX +pthread_cancel() +pthread_setcancelstate() +pthread_setcanceltype() +.EE +.in +.SS Cancelation points +POSIX.1 specifies that certain functions must, +and certain other functions may, be cancelation points. +If a thread is cancelable, its cancelability type is deferred, +and a cancelation request is pending for the thread, +then the thread is canceled when it calls a function +that is a cancelation point. +.P +The following functions are required to be cancelation points by +POSIX.1-2001 and/or POSIX.1-2008: +.P +.\" FIXME +.\" Document the list of all functions that are cancelation points in glibc +.in +4n +.EX +accept() +aio_suspend() +clock_nanosleep() +close() +connect() +creat() +fcntl() F_SETLKW +fdatasync() +fsync() +getmsg() +getpmsg() +lockf() F_LOCK +mq_receive() +mq_send() +mq_timedreceive() +mq_timedsend() +msgrcv() +msgsnd() +msync() +nanosleep() +open() +openat() [Added in POSIX.1-2008] +pause() +poll() +pread() +pselect() +pthread_cond_timedwait() +pthread_cond_wait() +pthread_join() +pthread_testcancel() +putmsg() +putpmsg() +pwrite() +read() +readv() +recv() +recvfrom() +recvmsg() +select() +sem_timedwait() +sem_wait() +send() +sendmsg() +sendto() +sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)] +sigsuspend() +sigtimedwait() +sigwait() +sigwaitinfo() +sleep() +system() +tcdrain() +usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +wait() +waitid() +waitpid() +write() +writev() +.EE +.in +.P +The following functions may be cancelation points according to +POSIX.1-2001 and/or POSIX.1-2008: +.P +.in +4n +.EX +access() +asctime() +asctime_r() +catclose() +catgets() +catopen() +chmod() [Added in POSIX.1-2008] +chown() [Added in POSIX.1-2008] +closedir() +closelog() +ctermid() +ctime() +ctime_r() +dbm_close() +dbm_delete() +dbm_fetch() +dbm_nextkey() +dbm_open() +dbm_store() +dlclose() +dlopen() +dprintf() [Added in POSIX.1-2008] +endgrent() +endhostent() +endnetent() +endprotoent() +endpwent() +endservent() +endutxent() +faccessat() [Added in POSIX.1-2008] +fchmod() [Added in POSIX.1-2008] +fchmodat() [Added in POSIX.1-2008] +fchown() [Added in POSIX.1-2008] +fchownat() [Added in POSIX.1-2008] +fclose() +fcntl() (for any value of cmd argument) +fflush() +fgetc() +fgetpos() +fgets() +fgetwc() +fgetws() +fmtmsg() +fopen() +fpathconf() +fprintf() +fputc() +fputs() +fputwc() +fputws() +fread() +freopen() +fscanf() +fseek() +fseeko() +fsetpos() +fstat() +fstatat() [Added in POSIX.1-2008] +ftell() +ftello() +ftw() +futimens() [Added in POSIX.1-2008] +fwprintf() +fwrite() +fwscanf() +getaddrinfo() +getc() +getc_unlocked() +getchar() +getchar_unlocked() +getcwd() +getdate() +getdelim() [Added in POSIX.1-2008] +getgrent() +getgrgid() +getgrgid_r() +getgrnam() +getgrnam_r() +gethostbyaddr() [POSIX.1-2001 only (function removed in + POSIX.1-2008)] +gethostbyname() [POSIX.1-2001 only (function removed in + POSIX.1-2008)] +gethostent() +gethostid() +gethostname() +getline() [Added in POSIX.1-2008] +getlogin() +getlogin_r() +getnameinfo() +getnetbyaddr() +getnetbyname() +getnetent() +getopt() (if opterr is nonzero) +getprotobyname() +getprotobynumber() +getprotoent() +getpwent() +getpwnam() +getpwnam_r() +getpwuid() +getpwuid_r() +gets() +getservbyname() +getservbyport() +getservent() +getutxent() +getutxid() +getutxline() +getwc() +getwchar() +getwd() [POSIX.1-2001 only (function removed in POSIX.1-2008)] +glob() +iconv_close() +iconv_open() +ioctl() +link() +linkat() [Added in POSIX.1-2008] +lio_listio() [Added in POSIX.1-2008] +localtime() +localtime_r() +lockf() [Added in POSIX.1-2008] +lseek() +lstat() +mkdir() [Added in POSIX.1-2008] +mkdirat() [Added in POSIX.1-2008] +mkdtemp() [Added in POSIX.1-2008] +mkfifo() [Added in POSIX.1-2008] +mkfifoat() [Added in POSIX.1-2008] +mknod() [Added in POSIX.1-2008] +mknodat() [Added in POSIX.1-2008] +mkstemp() +mktime() +nftw() +opendir() +openlog() +pathconf() +pclose() +perror() +popen() +posix_fadvise() +posix_fallocate() +posix_madvise() +posix_openpt() +posix_spawn() +posix_spawnp() +posix_trace_clear() +posix_trace_close() +posix_trace_create() +posix_trace_create_withlog() +posix_trace_eventtypelist_getnext_id() +posix_trace_eventtypelist_rewind() +posix_trace_flush() +posix_trace_get_attr() +posix_trace_get_filter() +posix_trace_get_status() +posix_trace_getnext_event() +posix_trace_open() +posix_trace_rewind() +posix_trace_set_filter() +posix_trace_shutdown() +posix_trace_timedgetnext_event() +posix_typed_mem_open() +printf() +psiginfo() [Added in POSIX.1-2008] +psignal() [Added in POSIX.1-2008] +pthread_rwlock_rdlock() +pthread_rwlock_timedrdlock() +pthread_rwlock_timedwrlock() +pthread_rwlock_wrlock() +putc() +putc_unlocked() +putchar() +putchar_unlocked() +puts() +pututxline() +putwc() +putwchar() +readdir() +readdir_r() +readlink() [Added in POSIX.1-2008] +readlinkat() [Added in POSIX.1-2008] +remove() +rename() +renameat() [Added in POSIX.1-2008] +rewind() +rewinddir() +scandir() [Added in POSIX.1-2008] +scanf() +seekdir() +semop() +setgrent() +sethostent() +setnetent() +setprotoent() +setpwent() +setservent() +setutxent() +sigpause() [Added in POSIX.1-2008] +stat() +strerror() +strerror_r() +strftime() +symlink() +symlinkat() [Added in POSIX.1-2008] +sync() +syslog() +tmpfile() +tmpnam() +ttyname() +ttyname_r() +tzset() +ungetc() +ungetwc() +unlink() +unlinkat() [Added in POSIX.1-2008] +utime() [Added in POSIX.1-2008] +utimensat() [Added in POSIX.1-2008] +utimes() [Added in POSIX.1-2008] +vdprintf() [Added in POSIX.1-2008] +vfprintf() +vfwprintf() +vprintf() +vwprintf() +wcsftime() +wordexp() +wprintf() +wscanf() +.EE +.in +.P +An implementation may also mark other functions +not specified in the standard as cancelation points. +In particular, an implementation is likely to mark +any nonstandard function that may block as a cancelation point. +(This includes most functions that can touch files.) +.P +It should be noted that even if an application is not using +asynchronous cancelation, that calling a function from the above list +from an asynchronous signal handler may cause the equivalent of +asynchronous cancelation. +The underlying user code may not expect +asynchronous cancelation and the state of the user data may become +inconsistent. +Therefore signals should be used with caution when +entering a region of deferred cancelation. +.\" So, scanning "cancelation point" comments in the glibc 2.8 header +.\" files, it looks as though at least the following nonstandard +.\" functions are cancelation points: +.\" endnetgrent +.\" endspent +.\" epoll_pwait +.\" epoll_wait +.\" fcloseall +.\" fdopendir +.\" fflush_unlocked +.\" fgetc_unlocked +.\" fgetgrent +.\" fgetgrent_r +.\" fgetpwent +.\" fgetpwent_r +.\" fgets_unlocked +.\" fgetspent +.\" fgetspent_r +.\" fgetwc_unlocked +.\" fgetws_unlocked +.\" fputc_unlocked +.\" fputs_unlocked +.\" fputwc_unlocked +.\" fputws_unlocked +.\" fread_unlocked +.\" fwrite_unlocked +.\" gai_suspend +.\" getaddrinfo_a +.\" getdate_r +.\" getgrent_r +.\" getgrouplist +.\" gethostbyaddr_r +.\" gethostbyname2 +.\" gethostbyname2_r +.\" gethostbyname_r +.\" gethostent_r +.\" getnetbyaddr_r +.\" getnetbyname_r +.\" getnetent_r +.\" getnetgrent +.\" getnetgrent_r +.\" getprotobyname_r +.\" getprotobynumber_r +.\" getprotoent_r +.\" getpw +.\" getpwent_r +.\" getservbyname_r +.\" getservbyport_r +.\" getservent_r +.\" getspent +.\" getspent_r +.\" getspnam +.\" getspnam_r +.\" getutmp +.\" getutmpx +.\" getw +.\" getwc_unlocked +.\" getwchar_unlocked +.\" initgroups +.\" innetgr +.\" mkostemp +.\" mkostemp64 +.\" mkstemp64 +.\" ppoll +.\" pthread_timedjoin_np +.\" putgrent +.\" putpwent +.\" putspent +.\" putw +.\" putwc_unlocked +.\" putwchar_unlocked +.\" rcmd +.\" rcmd_af +.\" rexec +.\" rexec_af +.\" rresvport +.\" rresvport_af +.\" ruserok +.\" ruserok_af +.\" setnetgrent +.\" setspent +.\" sgetspent +.\" sgetspent_r +.\" updwtmpx +.\" utmpxname +.\" vfscanf +.\" vfwscanf +.\" vscanf +.\" vsyslog +.\" vwscanf +.SS Compiling on Linux +On Linux, programs that use the Pthreads API should be compiled using +.IR "cc \-pthread" . +.SS Linux implementations of POSIX threads +Over time, two threading implementations have been provided by +the GNU C library on Linux: +.TP +.B LinuxThreads +This is the original Pthreads implementation. +Since glibc 2.4, this implementation is no longer supported. +.TP +.BR NPTL " (Native POSIX Threads Library)" +This is the modern Pthreads implementation. +By comparison with LinuxThreads, NPTL provides closer conformance to +the requirements of the POSIX.1 specification and better performance +when creating large numbers of threads. +NPTL is available since glibc 2.3.2, +and requires features that are present in the Linux 2.6 kernel. +.P +Both of these are so-called 1:1 implementations, meaning that each +thread maps to a kernel scheduling entity. +Both threading implementations employ the Linux +.BR clone (2) +system call. +In NPTL, thread synchronization primitives (mutexes, +thread joining, and so on) are implemented using the Linux +.BR futex (2) +system call. +.SS LinuxThreads +The notable features of this implementation are the following: +.IP \[bu] 3 +In addition to the main (initial) thread, +and the threads that the program creates using +.BR pthread_create (3), +the implementation creates a "manager" thread. +This thread handles thread creation and termination. +(Problems can result if this thread is inadvertently killed.) +.IP \[bu] +Signals are used internally by the implementation. +On Linux 2.2 and later, the first three real-time signals are used +(see also +.BR signal (7)). +On older Linux kernels, +.B SIGUSR1 +and +.B SIGUSR2 +are used. +Applications must avoid the use of whichever set of signals is +employed by the implementation. +.IP \[bu] +Threads do not share process IDs. +(In effect, LinuxThreads threads are implemented as processes which share +more information than usual, but which do not share a common process ID.) +LinuxThreads threads (including the manager thread) +are visible as separate processes using +.BR ps (1). +.P +The LinuxThreads implementation deviates from the POSIX.1 +specification in a number of ways, including the following: +.IP \[bu] 3 +Calls to +.BR getpid (2) +return a different value in each thread. +.IP \[bu] +Calls to +.BR getppid (2) +in threads other than the main thread return the process ID of the +manager thread; instead +.BR getppid (2) +in these threads should return the same value as +.BR getppid (2) +in the main thread. +.IP \[bu] +When one thread creates a new child process using +.BR fork (2), +any thread should be able to +.BR wait (2) +on the child. +However, the implementation allows only the thread that +created the child to +.BR wait (2) +on it. +.IP \[bu] +When a thread calls +.BR execve (2), +all other threads are terminated (as required by POSIX.1). +However, the resulting process has the same PID as the thread that called +.BR execve (2): +it should have the same PID as the main thread. +.IP \[bu] +Threads do not share user and group IDs. +This can cause complications with set-user-ID programs and +can cause failures in Pthreads functions if an application +changes its credentials using +.BR seteuid (2) +or similar. +.IP \[bu] +Threads do not share a common session ID and process group ID. +.IP \[bu] +Threads do not share record locks created using +.BR fcntl (2). +.IP \[bu] +The information returned by +.BR times (2) +and +.BR getrusage (2) +is per-thread rather than process-wide. +.IP \[bu] +Threads do not share semaphore undo values (see +.BR semop (2)). +.IP \[bu] +Threads do not share interval timers. +.IP \[bu] +Threads do not share a common nice value. +.IP \[bu] +POSIX.1 distinguishes the notions of signals that are directed +to the process as a whole and signals that are directed to individual +threads. +According to POSIX.1, a process-directed signal (sent using +.BR kill (2), +for example) should be handled by a single, +arbitrarily selected thread within the process. +LinuxThreads does not support the notion of process-directed signals: +signals may be sent only to specific threads. +.IP \[bu] +Threads have distinct alternate signal stack settings. +However, a new thread's alternate signal stack settings +are copied from the thread that created it, so that +the threads initially share an alternate signal stack. +(A new thread should start with no alternate signal stack defined. +If two threads handle signals on their shared alternate signal +stack at the same time, unpredictable program failures are +likely to occur.) +.SS NPTL +With NPTL, all of the threads in a process are placed +in the same thread group; +all members of a thread group share the same PID. +NPTL does not employ a manager thread. +.P +NPTL makes internal use of the first two real-time signals; +these signals cannot be used in applications. +See +.BR nptl (7) +for further details. +.P +NPTL still has at least one nonconformance with POSIX.1: +.IP \[bu] 3 +Threads do not share a common nice value. +.\" FIXME . bug report filed for NPTL nice nonconformance +.\" http://bugzilla.kernel.org/show_bug.cgi?id=6258 +.\" Sep 08: there is a patch by Denys Vlasenko to address this +.\" "make setpriority POSIX compliant; introduce PRIO_THREAD extension" +.\" Monitor this to see if it makes it into mainline. +.P +Some NPTL nonconformances occur only with older kernels: +.IP \[bu] 3 +The information returned by +.BR times (2) +and +.BR getrusage (2) +is per-thread rather than process-wide (fixed in Linux 2.6.9). +.IP \[bu] +Threads do not share resource limits (fixed in Linux 2.6.10). +.IP \[bu] +Threads do not share interval timers (fixed in Linux 2.6.12). +.IP \[bu] +Only the main thread is permitted to start a new session using +.BR setsid (2) +(fixed in Linux 2.6.16). +.IP \[bu] +Only the main thread is permitted to make the process into a +process group leader using +.BR setpgid (2) +(fixed in Linux 2.6.16). +.IP \[bu] +Threads have distinct alternate signal stack settings. +However, a new thread's alternate signal stack settings +are copied from the thread that created it, so that +the threads initially share an alternate signal stack +(fixed in Linux 2.6.16). +.P +Note the following further points about the NPTL implementation: +.IP \[bu] 3 +If the stack size soft resource limit (see the description of +.B RLIMIT_STACK +in +.BR setrlimit (2)) +is set to a value other than +.IR unlimited , +then this value defines the default stack size for new threads. +To be effective, this limit must be set before the program +is executed, perhaps using the +.I ulimit \-s +shell built-in command +.RI ( "limit stacksize" +in the C shell). +.SS Determining the threading implementation +Since glibc 2.3.2, the +.BR getconf (1) +command can be used to determine +the system's threading implementation, for example: +.P +.in +4n +.EX +bash$ getconf GNU_LIBPTHREAD_VERSION +NPTL 2.3.4 +.EE +.in +.P +With older glibc versions, a command such as the following should +be sufficient to determine the default threading implementation: +.P +.in +4n +.EX +bash$ $( ldd /bin/ls | grep libc.so | awk \[aq]{print $3}\[aq] ) | \e + egrep \-i \[aq]threads|nptl\[aq] + Native POSIX Threads Library by Ulrich Drepper et al +.EE +.in +.SS Selecting the threading implementation: LD_ASSUME_KERNEL +On systems with a glibc that supports both LinuxThreads and NPTL +(i.e., glibc 2.3.\fIx\fP), the +.B LD_ASSUME_KERNEL +environment variable can be used to override +the dynamic linker's default choice of threading implementation. +This variable tells the dynamic linker to assume that it is +running on top of a particular kernel version. +By specifying a kernel version that does not +provide the support required by NPTL, we can force the use +of LinuxThreads. +(The most likely reason for doing this is to run a +(broken) application that depends on some nonconformant behavior +in LinuxThreads.) +For example: +.P +.in +4n +.EX +bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e + awk \[aq]{print $3}\[aq] ) | egrep \-i \[aq]threads|nptl\[aq] + linuxthreads\-0.10 by Xavier Leroy +.EE +.in +.SH SEE ALSO +.ad l +.nh +.BR clone (2), +.BR fork (2), +.BR futex (2), +.BR gettid (2), +.BR proc (5), +.BR attributes (7), +.BR futex (7), +.BR nptl (7), +.BR sigevent (3type), +.BR signal (7) +.P +Various Pthreads manual pages, for example: +.BR pthread_atfork (3), +.BR pthread_attr_init (3), +.BR pthread_cancel (3), +.BR pthread_cleanup_push (3), +.BR pthread_cond_signal (3), +.BR pthread_cond_wait (3), +.BR pthread_create (3), +.BR pthread_detach (3), +.BR pthread_equal (3), +.BR pthread_exit (3), +.BR pthread_key_create (3), +.BR pthread_kill (3), +.BR pthread_mutex_lock (3), +.BR pthread_mutex_unlock (3), +.BR pthread_mutexattr_destroy (3), +.BR pthread_mutexattr_init (3), +.BR pthread_once (3), +.BR pthread_spin_init (3), +.BR pthread_spin_lock (3), +.BR pthread_rwlockattr_setkind_np (3), +.BR pthread_setcancelstate (3), +.BR pthread_setcanceltype (3), +.BR pthread_setspecific (3), +.BR pthread_sigmask (3), +.BR pthread_sigqueue (3), +and +.BR pthread_testcancel (3) diff --git a/man/man7/pty.7 b/man/man7/pty.7 new file mode 100644 index 0000000..182d279 --- /dev/null +++ b/man/man7/pty.7 @@ -0,0 +1,161 @@ +.\" Copyright (C) 2005 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pty 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +pty \- pseudoterminal interfaces +.SH DESCRIPTION +A pseudoterminal (sometimes abbreviated "pty") +is a pair of virtual character devices that +provide a bidirectional communication channel. +One end of the channel is called the +.IR master ; +the other end is called the +.IR slave . +.P +The slave end of the pseudoterminal provides an interface +that behaves exactly like a classical terminal. +A process that expects to be connected to a terminal, +can open the slave end of a pseudoterminal and +then be driven by a program that has opened the master end. +Anything that is written on the master end is provided to the process +on the slave end as though it was input typed on a terminal. +For example, writing the interrupt character (usually control-C) +to the master device would cause an interrupt signal +.RB ( SIGINT ) +to be generated for the foreground process group +that is connected to the slave. +Conversely, anything that is written to the slave end of the +pseudoterminal can be read by the process that is connected to +the master end. +.P +Data flow between master and slave is handled asynchronously, +much like data flow with a physical terminal. +Data written to the slave will be available at the master promptly, +but may not be available immediately. +Similarly, there may be a small processing delay between +a write to the master, and the effect being visible at the slave. +.P +Historically, two pseudoterminal APIs have evolved: BSD and System V. +SUSv1 standardized a pseudoterminal API based on the System V API, +and this API should be employed in all new programs that use +pseudoterminals. +.P +Linux provides both BSD-style and (standardized) System V-style +pseudoterminals. +System V-style terminals are commonly called UNIX 98 pseudoterminals +on Linux systems. +.P +Since Linux 2.6.4, BSD-style pseudoterminals are considered deprecated: +support can be disabled when building the kernel by disabling the +.B CONFIG_LEGACY_PTYS +option. +(Starting with Linux 2.6.30, +that option is disabled by default in the mainline kernel.) +UNIX 98 pseudoterminals should be used in new applications. +.SS UNIX 98 pseudoterminals +An unused UNIX 98 pseudoterminal master is opened by calling +.BR posix_openpt (3). +(This function opens the master clone device, +.IR /dev/ptmx ; +see +.BR pts (4).) +After performing any program-specific initializations, +changing the ownership and permissions of the slave device using +.BR grantpt (3), +and unlocking the slave using +.BR unlockpt (3)), +the corresponding slave device can be opened by passing +the name returned by +.BR ptsname (3) +in a call to +.BR open (2). +.P +The Linux kernel imposes a limit on the number of available +UNIX 98 pseudoterminals. +Up to and including Linux 2.6.3, this limit is configured +at kernel compilation time +.RB ( CONFIG_UNIX98_PTYS ), +and the permitted number of pseudoterminals can be up to 2048, +with a default setting of 256. +Since Linux 2.6.4, the limit is dynamically adjustable via +.IR /proc/sys/kernel/pty/max , +and a corresponding file, +.IR /proc/sys/kernel/pty/nr , +indicates how many pseudoterminals are currently in use. +For further details on these two files, see +.BR proc (5). +.SS BSD pseudoterminals +BSD-style pseudoterminals are provided as precreated pairs, with +names of the form +.I /dev/ptyXY +(master) and +.I /dev/ttyXY +(slave), +where X is a letter from the 16-character set [p\-za\-e], +and Y is a letter from the 16-character set [0\-9a\-f]. +(The precise range of letters in these two sets varies across UNIX +implementations.) +For example, +.I /dev/ptyp1 +and +.I /dev/ttyp1 +constitute a BSD pseudoterminal pair. +A process finds an unused pseudoterminal pair by trying to +.BR open (2) +each pseudoterminal master until an open succeeds. +The corresponding pseudoterminal slave (substitute "tty" +for "pty" in the name of the master) can then be opened. +.SH FILES +.TP +.I /dev/ptmx +UNIX 98 master clone device +.TP +.I /dev/pts/* +UNIX 98 slave devices +.TP +.I /dev/pty[p\-za\-e][0\-9a\-f] +BSD master devices +.TP +.I /dev/tty[p\-za\-e][0\-9a\-f] +BSD slave devices +.SH NOTES +Pseudoterminals are used by applications such as network login services +(\c +.BR ssh (1), +.BR rlogin (1), +.BR telnet (1)), +terminal emulators such as +.BR xterm (1), +.BR script (1), +.BR screen (1), +.BR tmux (1), +.BR unbuffer (1), +and +.BR expect (1). +.P +A description of the +.B TIOCPKT +.BR ioctl (2), +which controls packet mode operation, can be found in +.BR ioctl_tty (2). +.P +The BSD +.BR ioctl (2) +operations +.BR TIOCSTOP , +.BR TIOCSTART , +.BR TIOCUCNTL , +and +.B TIOCREMOTE +have not been implemented under Linux. +.SH SEE ALSO +.BR ioctl_tty (2), +.BR select (2), +.BR setsid (2), +.BR forkpty (3), +.BR openpty (3), +.BR termios (3), +.BR pts (4), +.BR tty (4) diff --git a/man/man7/queue.7 b/man/man7/queue.7 new file mode 100644 index 0000000..66c975b --- /dev/null +++ b/man/man7/queue.7 @@ -0,0 +1,138 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (c) 2020 by Alejandro Colomar +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" +.TH queue 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +queue \- implementations of linked lists and queues +.SH DESCRIPTION +The +.I +header file provides a set of macros that +define and operate on the following data structures: +.TP +SLIST +singly linked lists +.TP +LIST +doubly linked lists +.TP +STAILQ +singly linked tail queues +.TP +TAILQ +doubly linked tail queues +.TP +CIRCLEQ +doubly linked circular queues +.P +All structures support the following functionality: +.IP \[bu] 3 +Insertion of a new entry at the head of the list. +.IP \[bu] +Insertion of a new entry after any element in the list. +.IP \[bu] +O(1) removal of an entry from the head of the list. +.IP \[bu] +Forward traversal through the list. +.\".IP \[bu] +.\" Swapping the contents of two lists. +.P +Code size and execution time +depend on the complexity of the data structure being used, +so programmers should take care to choose the appropriate one. +.SS Singly linked lists (SLIST) +Singly linked lists are the simplest +and support only the above functionality. +Singly linked lists are ideal for applications with +large datasets and few or no removals, +or for implementing a LIFO queue. +Singly linked lists add the following functionality: +.IP \[bu] 3 +O(n) removal of any entry in the list. +.SS Singly linked tail queues (STAILQ) +Singly linked tail queues add the following functionality: +.IP \[bu] 3 +Entries can be added at the end of a list. +.IP \[bu] +O(n) removal of any entry in the list. +.IP \[bu] +They may be concatenated. +.P +However: +.IP \[bu] 3 +All list insertions must specify the head of the list. +.IP \[bu] +Each head entry requires two pointers rather than one. +.P +Singly linked tail queues are ideal for applications with +large datasets and few or no removals, +or for implementing a FIFO queue. +.SS Doubly linked data structures +All doubly linked types of data structures (lists and tail queues) +additionally allow: +.IP \[bu] 3 +Insertion of a new entry before any element in the list. +.IP \[bu] +O(1) removal of any entry in the list. +.P +However: +.IP \[bu] 3 +Each element requires two pointers rather than one. +.SS Doubly linked lists (LIST) +Linked lists are the simplest of the doubly linked data structures. +They add the following functionality over the above: +.IP \[bu] 3 +They may be traversed backwards. +.P +However: +.IP \[bu] 3 +To traverse backwards, an entry to begin the traversal and the list in +which it is contained must be specified. +.SS Doubly linked tail queues (TAILQ) +Tail queues add the following functionality: +.IP \[bu] 3 +Entries can be added at the end of a list. +.IP \[bu] +They may be traversed backwards, from tail to head. +.IP \[bu] +They may be concatenated. +.P +However: +.IP \[bu] 3 +All list insertions and removals must specify the head of the list. +.IP \[bu] +Each head entry requires two pointers rather than one. +.SS Doubly linked circular queues (CIRCLEQ) +Circular queues add the following functionality over the above: +.IP \[bu] 3 +The first and last entries are connected. +.P +However: +.IP \[bu] 3 +The termination condition for traversal is more complex. +.SH STANDARDS +BSD. +.SH HISTORY +.I +macros first appeared in 4.4BSD. +.SH NOTES +Some BSDs provide SIMPLEQ instead of STAILQ. +They are identical, but for historical reasons +they were named differently on different BSDs. +STAILQ originated on FreeBSD, and SIMPLEQ originated on NetBSD. +For compatibility reasons, some systems provide both sets of macros. +glibc provides both STAILQ and SIMPLEQ, +which are identical except for a missing SIMPLEQ equivalent to +.BR STAILQ_CONCAT (). +.SH SEE ALSO +.BR circleq (3), +.BR insque (3), +.BR list (3), +.BR slist (3), +.BR stailq (3), +.BR tailq (3) +.\" .BR tree (3) diff --git a/man/man7/random.7 b/man/man7/random.7 new file mode 100644 index 0000000..4eb4bae --- /dev/null +++ b/man/man7/random.7 @@ -0,0 +1,213 @@ +'\" t +.\" Copyright (C) 2008, George Spelvin , +.\" and Copyright (C) 2008, Matt Mackall +.\" and Copyright (C) 2016, Laurent Georget +.\" and Copyright (C) 2016, Nikos Mavrogiannopoulos +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" The following web page is quite informative: +.\" http://www.2uo.de/myths-about-urandom/ +.\" +.TH random 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +random \- overview of interfaces for obtaining randomness +.SH DESCRIPTION +The kernel random-number generator relies on entropy gathered from +device drivers and other sources of environmental noise to seed +a cryptographically secure pseudorandom number generator (CSPRNG). +It is designed for security, rather than speed. +.P +The following interfaces provide access to output from the kernel CSPRNG: +.IP \[bu] 3 +The +.I /dev/urandom +and +.I /dev/random +devices, both described in +.BR random (4). +These devices have been present on Linux since early times, +and are also available on many other systems. +.IP \[bu] +The Linux-specific +.BR getrandom (2) +system call, available since Linux 3.17. +This system call provides access either to the same source as +.I /dev/urandom +(called the +.I urandom +source in this page) +or to the same source as +.I /dev/random +(called the +.I random +source in this page). +The default is the +.I urandom +source; the +.I random +source is selected by specifying the +.B GRND_RANDOM +flag to the system call. +(The +.BR getentropy (3) +function provides a slightly more portable interface on top of +.BR getrandom (2).) +.\" +.SS Initialization of the entropy pool +The kernel collects bits of entropy from the environment. +When a sufficient number of random bits has been collected, the +entropy pool is considered to be initialized. +.SS Choice of random source +Unless you are doing long-term key generation (and most likely not even +then), you probably shouldn't be reading from the +.I /dev/random +device or employing +.BR getrandom (2) +with the +.B GRND_RANDOM +flag. +Instead, either read from the +.I /dev/urandom +device or employ +.BR getrandom (2) +without the +.B GRND_RANDOM +flag. +The cryptographic algorithms used for the +.I urandom +source are quite conservative, and so should be sufficient for all purposes. +.P +The disadvantage of +.B GRND_RANDOM +and reads from +.I /dev/random +is that the operation can block for an indefinite period of time. +Furthermore, dealing with the partially fulfilled +requests that can occur when using +.B GRND_RANDOM +or when reading from +.I /dev/random +increases code complexity. +.\" +.SS Monte Carlo and other probabilistic sampling applications +Using these interfaces to provide large quantities of data for +Monte Carlo simulations or other programs/algorithms which are +doing probabilistic sampling will be slow. +Furthermore, it is unnecessary, because such applications do not +need cryptographically secure random numbers. +Instead, use the interfaces described in this page to obtain +a small amount of data to seed a user-space pseudorandom +number generator for use by such applications. +.\" +.SS Comparison between getrandom, /dev/urandom, and /dev/random +The following table summarizes the behavior of the various +interfaces that can be used to obtain randomness. +.B GRND_NONBLOCK +is a flag that can be used to control the blocking behavior of +.BR getrandom (2). +The final column of the table considers the case that can occur +in early boot time when the entropy pool is not yet initialized. +.ad l +.TS +allbox; +lbw13 lbw12 lbw14 lbw18 +l l l l. +Interface Pool T{ +Blocking +\%behavior +T} T{ +Behavior when pool is not yet ready +T} +T{ +.I /dev/random +T} T{ +Blocking pool +T} T{ +If entropy too low, blocks until there is enough entropy again +T} T{ +Blocks until enough entropy gathered +T} +T{ +.I /dev/urandom +T} T{ +CSPRNG output +T} T{ +Never blocks +T} T{ +Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography) +T} +T{ +.BR getrandom () +T} T{ +Same as +.I /dev/urandom +T} T{ +Does not block once is pool ready +T} T{ +Blocks until pool ready +T} +T{ +.BR getrandom () +.B GRND_RANDOM +T} T{ +Same as +.I /dev/random +T} T{ +If entropy too low, blocks until there is enough entropy again +T} T{ +Blocks until pool ready +T} +T{ +.BR getrandom () +.B GRND_NONBLOCK +T} T{ +Same as +.I /dev/urandom +T} T{ +Does not block once is pool ready +T} T{ +.B EAGAIN +T} +T{ +.BR getrandom () +.B GRND_RANDOM ++ +.B GRND_NONBLOCK +T} T{ +Same as +.I /dev/random +T} T{ +.B EAGAIN +if not enough entropy available +T} T{ +.B EAGAIN +T} +.TE +.ad +.\" +.SS Generating cryptographic keys +The amount of seed material required to generate a cryptographic key +equals the effective key size of the key. +For example, a 3072-bit RSA +or Diffie-Hellman private key has an effective key size of 128 bits +(it requires about 2\[ha]128 operations to break) so a key generator +needs only 128 bits (16 bytes) of seed material from +.IR /dev/random . +.P +While some safety margin above that minimum is reasonable, as a guard +against flaws in the CSPRNG algorithm, no cryptographic primitive +available today can hope to promise more than 256 bits of security, +so if any program reads more than 256 bits (32 bytes) from the kernel +random pool per invocation, or per reasonable reseed interval (not less +than one minute), that should be taken as a sign that its cryptography is +.I not +skillfully implemented. +.\" +.SH SEE ALSO +.BR getrandom (2), +.BR getauxval (3), +.BR getentropy (3), +.BR random (4), +.BR urandom (4), +.BR signal (7) diff --git a/man/man7/raw.7 b/man/man7/raw.7 new file mode 100644 index 0000000..44b1aff --- /dev/null +++ b/man/man7/raw.7 @@ -0,0 +1,281 @@ +'\" t +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ +.\" +.TH raw 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +raw \- Linux IPv4 raw sockets +.SH SYNOPSIS +.nf +.B #include +.B #include +.BI "raw_socket = socket(AF_INET, SOCK_RAW, int " protocol ); +.fi +.SH DESCRIPTION +Raw sockets allow new IPv4 protocols to be implemented in user space. +A raw socket receives or sends the raw datagram not +including link level headers. +.P +The IPv4 layer generates an IP header when sending a packet unless the +.B IP_HDRINCL +socket option is enabled on the socket. +When it is enabled, the packet must contain an IP header. +For receiving, the IP header is always included in the packet. +.P +In order to create a raw socket, a process must have the +.B CAP_NET_RAW +capability in the user namespace that governs its network namespace. +.P +All packets or errors matching the +.I protocol +number specified +for the raw socket are passed to this socket. +For a list of the allowed protocols, +see the IANA list of assigned protocol numbers at +.UR http://www.iana.org/assignments/protocol\-numbers/ +.UE +and +.BR getprotobyname (3). +.P +A protocol of +.B IPPROTO_RAW +implies enabled +.B IP_HDRINCL +and is able to send any IP protocol that is specified in the passed +header. +Receiving of all IP protocols via +.B IPPROTO_RAW +is not possible using raw sockets. +.RS +.TS +tab(:) allbox; +c s +l l. +IP Header fields modified on sending by \fBIP_HDRINCL\fP +IP Checksum:Always filled in +Source Address:Filled in when zero +Packet ID:Filled in when zero +Total Length:Always filled in +.TE +.RE +.P +If +.B IP_HDRINCL +is specified and the IP header has a nonzero destination address, then +the destination address of the socket is used to route the packet. +When +.B MSG_DONTROUTE +is specified, the destination address should refer to a local interface, +otherwise a routing table lookup is done anyway but gatewayed routes +are ignored. +.P +If +.B IP_HDRINCL +isn't set, then IP header options can be set on raw sockets with +.BR setsockopt (2); +see +.BR ip (7) +for more information. +.P +Starting with Linux 2.2, all IP header fields and options can be set using +IP socket options. +This means raw sockets are usually needed only for new +protocols or protocols with no user interface (like ICMP). +.P +When a packet is received, it is passed to any raw sockets which have +been bound to its protocol before it is passed to other protocol handlers +(e.g., kernel protocol modules). +.SS Address format +For sending and receiving datagrams +.RB ( sendto (2), +.BR recvfrom (2), +and similar), +raw sockets use the standard +.I sockaddr_in +address structure defined in +.BR ip (7). +The +.I sin_port +field could be used to specify the IP protocol number, +but it is ignored for sending in Linux 2.2 and later, and should be always +set to 0 (see BUGS). +For incoming packets, +.I sin_port +.\" commit f59fc7f30b710d45aadf715460b3e60dbe9d3418 +is set to zero. +.SS Socket options +Raw socket options can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2) +by passing the +.B IPPROTO_RAW +.\" Or SOL_RAW on Linux +family flag. +.TP +.B ICMP_FILTER +Enable a special filter for raw sockets bound to the +.B IPPROTO_ICMP +protocol. +The value has a bit set for each ICMP message type which +should be filtered out. +The default is to filter no ICMP messages. +.P +In addition, all +.BR ip (7) +.B IPPROTO_IP +socket options valid for datagram sockets are supported. +.SS Error handling +Errors originating from the network are passed to the user only when the +socket is connected or the +.B IP_RECVERR +flag is enabled. +For connected sockets, only +.B EMSGSIZE +and +.B EPROTO +are passed for compatibility. +With +.BR IP_RECVERR , +all network errors are saved in the error queue. +.SH ERRORS +.TP +.B EACCES +User tried to send to a broadcast address without having the +broadcast flag set on the socket. +.TP +.B EFAULT +An invalid memory address was supplied. +.TP +.B EINVAL +Invalid argument. +.TP +.B EMSGSIZE +Packet too big. +Either Path MTU Discovery is enabled (the +.B IP_MTU_DISCOVER +socket flag) or the packet size exceeds the maximum allowed IPv4 +packet size of 64\ kB. +.TP +.B EOPNOTSUPP +Invalid flag has been passed to a socket call (like +.BR MSG_OOB ). +.TP +.B EPERM +The user doesn't have permission to open raw sockets. +Only processes with an effective user ID of 0 or the +.B CAP_NET_RAW +attribute may do that. +.TP +.B EPROTO +An ICMP error has arrived reporting a parameter problem. +.SH VERSIONS +.B IP_RECVERR +and +.B ICMP_FILTER +are new in Linux 2.2. +They are Linux extensions and should not be used in portable programs. +.P +Linux 2.0 enabled some bug-to-bug compatibility with BSD in the +raw socket code when the +.B SO_BSDCOMPAT +socket option was set; since Linux 2.2, +this option no longer has that effect. +.SH NOTES +By default, raw sockets do path MTU (Maximum Transmission Unit) discovery. +This means the kernel +will keep track of the MTU to a specific target IP address and return +.B EMSGSIZE +when a raw packet write exceeds it. +When this happens, the application should decrease the packet size. +Path MTU discovery can be also turned off using the +.B IP_MTU_DISCOVER +socket option or the +.I /proc/sys/net/ipv4/ip_no_pmtu_disc +file, see +.BR ip (7) +for details. +When turned off, raw sockets will fragment outgoing packets +that exceed the interface MTU. +However, disabling it is not recommended +for performance and reliability reasons. +.P +A raw socket can be bound to a specific local address using the +.BR bind (2) +call. +If it isn't bound, all packets with the specified IP protocol are received. +In addition, a raw socket can be bound to a specific network device using +.BR SO_BINDTODEVICE ; +see +.BR socket (7). +.P +An +.B IPPROTO_RAW +socket is send only. +If you really want to receive all IP packets, use a +.BR packet (7) +socket with the +.B ETH_P_IP +protocol. +Note that packet sockets don't reassemble IP fragments, +unlike raw sockets. +.P +If you want to receive all ICMP packets for a datagram socket, +it is often better to use +.B IP_RECVERR +on that particular socket; see +.BR ip (7). +.P +Raw sockets may tap all IP protocols in Linux, even +protocols like ICMP or TCP which have a protocol module in the kernel. +In this case, the packets are passed to both the kernel module and the raw +socket(s). +This should not be relied upon in portable programs, many other BSD +socket implementation have limitations here. +.P +Linux never changes headers passed from the user (except for filling +in some zeroed fields as described for +.BR IP_HDRINCL ). +This differs from many other implementations of raw sockets. +.P +Raw sockets are generally rather unportable and should be avoided in +programs intended to be portable. +.P +Sending on raw sockets should take the IP protocol from +.IR sin_port ; +this ability was lost in Linux 2.2. +The workaround is to use +.BR IP_HDRINCL . +.SH BUGS +Transparent proxy extensions are not described. +.P +When the +.B IP_HDRINCL +option is set, datagrams will not be fragmented and are limited to +the interface MTU. +.P +Setting the IP protocol for sending in +.I sin_port +got lost in Linux 2.2. +The protocol that the socket was bound to or that +was specified in the initial +.BR socket (2) +call is always used. +.\" .SH AUTHORS +.\" This man page was written by Andi Kleen. +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2), +.BR capabilities (7), +.BR ip (7), +.BR socket (7) +.P +.B RFC\ 1191 +for path MTU discovery. +.B RFC\ 791 +and the +.I +header file for the IP protocol. diff --git a/man/man7/regex.7 b/man/man7/regex.7 new file mode 100644 index 0000000..5788410 --- /dev/null +++ b/man/man7/regex.7 @@ -0,0 +1,293 @@ +'\" t +.\" From Henry Spencer's regex package (as found in the apache +.\" distribution). The package carries the following copyright: +.\" +.\" Copyright 1992, 1993, 1994 Henry Spencer. All rights reserved. +.\" %%%LICENSE_START(MISC) +.\" This software is not subject to any license of the American Telephone +.\" and Telegraph Company or of the Regents of the University of California. +.\" +.\" Permission is granted to anyone to use this software for any purpose +.\" on any computer system, and to alter it and redistribute it, subject +.\" to the following restrictions: +.\" +.\" 1. The author is not responsible for the consequences of use of this +.\" software, no matter how awful, even if they arise from flaws in it. +.\" +.\" 2. The origin of this software must not be misrepresented, either by +.\" explicit claim or by omission. Since few users ever read sources, +.\" credits must appear in the documentation. +.\" +.\" 3. Altered versions must be plainly marked as such, and must not be +.\" misrepresented as being the original software. Since few users +.\" ever read sources, credits must appear in the documentation. +.\" +.\" 4. This notice may not be removed or altered. +.\" %%%LICENSE_END +.\" +.\" In order to comply with `credits must appear in the documentation' +.\" I added an AUTHOR paragraph below - aeb. +.\" +.\" In the default nroff environment there is no dagger \(dg. +.\" +.\" 2005-05-11 Removed discussion of `[[:<:]]' and `[[:>:]]', which +.\" appear not to be in the glibc implementation of regcomp +.\" +.ie t .ds dg \(dg +.el .ds dg (!) +.TH regex 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +regex \- POSIX.2 regular expressions +.SH DESCRIPTION +Regular expressions ("RE"s), +as defined in POSIX.2, come in two forms: +modern REs (roughly those of +.BR egrep (1); +POSIX.2 calls these "extended" REs) +and obsolete REs (roughly those of +.BR ed (1); +POSIX.2 "basic" REs). +Obsolete REs mostly exist for backward compatibility in some old programs; +they will be discussed at the end. +POSIX.2 leaves some aspects of RE syntax and semantics open; +"\*(dg" marks decisions on these aspects that +may not be fully portable to other POSIX.2 implementations. +.P +A (modern) RE is one\*(dg or more nonempty\*(dg \fIbranches\fR, +separated by \[aq]|\[aq]. +It matches anything that matches one of the branches. +.P +A branch is one\*(dg or more \fIpieces\fR, concatenated. +It matches a match for the first, followed by a match for the second, +and so on. +.P +A piece is an \fIatom\fR possibly followed +by a single\*(dg \[aq]*\[aq], \[aq]+\[aq], \[aq]?\[aq], or \fIbound\fR. +An atom followed by \[aq]*\[aq] +matches a sequence of 0 or more matches of the atom. +An atom followed by \[aq]+\[aq] +matches a sequence of 1 or more matches of the atom. +An atom followed by \[aq]?\[aq] +matches a sequence of 0 or 1 matches of the atom. +.P +A \fIbound\fR is \[aq]{\[aq] followed by an unsigned decimal integer, +possibly followed by \[aq],\[aq] +possibly followed by another unsigned decimal integer, +always followed by \[aq]}\[aq]. +The integers must lie between 0 and +.B RE_DUP_MAX +(255\*(dg) inclusive, +and if there are two of them, the first may not exceed the second. +An atom followed by a bound containing one integer \fIi\fR +and no comma matches +a sequence of exactly \fIi\fR matches of the atom. +An atom followed by a bound +containing one integer \fIi\fR and a comma matches +a sequence of \fIi\fR or more matches of the atom. +An atom followed by a bound +containing two integers \fIi\fR and \fIj\fR matches +a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom. +.P +An atom is a regular expression enclosed in "\fI()\fP" +(matching a match for the regular expression), +an empty set of "\fI()\fP" (matching the null string)\*(dg, +a \fIbracket expression\fR (see below), +\[aq].\[aq] (matching any single character), +\[aq]\[ha]\[aq] (matching the null string at the beginning of a line), +\[aq]$\[aq] (matching the null string at the end of a line), +a \[aq]\e\[aq] followed by one of the characters "\fI\[ha].[$()|*+?{\e\fP" +(matching that character taken as an ordinary character), +a \[aq]\e\[aq] followed by any other character\*(dg +(matching that character taken as an ordinary character, +as if the \[aq]\e\[aq] had not been present\*(dg), +or a single character with no other significance (matching that character). +A \[aq]{\[aq] followed by a character other than a digit +is an ordinary character, +not the beginning of a bound\*(dg. +It is illegal to end an RE with \[aq]\e\[aq]. +.P +A \fIbracket expression\fR is a list of characters enclosed in "\fI[]\fP". +It normally matches any single character from the list (but see below). +If the list begins with \[aq]\[ha]\[aq], +it matches any single character +(but see below) \fInot\fR from the rest of the list. +If two characters in the list are separated by \[aq]\-\[aq], this is shorthand +for the full \fIrange\fR of characters between those two (inclusive) in the +collating sequence, +for example, "\fI[0\-9]\fP" in ASCII matches any decimal digit. +It is illegal\*(dg for two ranges to share an +endpoint, for example, "\fIa\-c\-e\fP". +Ranges are very collating-sequence-dependent, +and portable programs should avoid relying on them. +.P +To include a literal \[aq]]\[aq] in the list, make it the first character +(following a possible \[aq]\[ha]\[aq]). +To include a literal \[aq]\-\[aq], make it the first or last character, +or the second endpoint of a range. +To use a literal \[aq]\-\[aq] as the first endpoint of a range, +enclose it in "\fI[.\fP" and "\fI.]\fP" +to make it a collating element (see below). +With the exception of these and some combinations using \[aq][\[aq] (see next +paragraphs), all other special characters, including \[aq]\e\[aq], lose their +special significance within a bracket expression. +.P +Within a bracket expression, a collating element (a character, +a multicharacter sequence that collates as if it were a single character, +or a collating-sequence name for either) +enclosed in "\fI[.\fP" and "\fI.]\fP" stands for the +sequence of characters of that collating element. +The sequence is a single element of the bracket expression's list. +A bracket expression containing a multicharacter collating element +can thus match more than one character, +for example, if the collating sequence includes a "ch" collating element, +then the RE "\fI[[.ch.]]*c\fP" matches the first five characters +of "chchcc". +.P +Within a bracket expression, a collating element enclosed in "\fI[=\fP" and +"\fI=]\fP" is an equivalence class, standing for the sequences of characters +of all collating elements equivalent to that one, including itself. +(If there are no other equivalent collating elements, +the treatment is as if the enclosing delimiters +were "\fI[.\fP" and "\fI.]\fP".) +For example, if o and \(^o are the members of an equivalence class, +then "\fI[[=o=]]\fP", "\fI[[=\(^o=]]\fP", +and "\fI[o\(^o]\fP" are all synonymous. +An equivalence class may not\*(dg be an endpoint +of a range. +.P +Within a bracket expression, the name of a \fIcharacter class\fR enclosed +in "\fI[:\fP" and "\fI:]\fP" stands for the list +of all characters belonging to that +class. +Standard character class names are: +.P +.RS +.TS +l l l. +alnum digit punct +alpha graph space +blank lower upper +cntrl print xdigit +.TE +.RE +.P +These stand for the character classes defined in +.BR wctype (3). +A locale may provide others. +A character class may not be used as an endpoint of a range. +.\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 +.\" The following does not seem to apply in the glibc implementation +.\" .P +.\" There are two special cases\*(dg of bracket expressions: +.\" the bracket expressions "\fI[[:<:]]\fP" and "\fI[[:>:]]\fP" match +.\" the null string at the beginning and end of a word respectively. +.\" A word is defined as a sequence of +.\" word characters +.\" which is neither preceded nor followed by +.\" word characters. +.\" A word character is an +.\" .I alnum +.\" character (as defined by +.\" .BR wctype (3)) +.\" or an underscore. +.\" This is an extension, +.\" compatible with but not specified by POSIX.2, +.\" and should be used with +.\" caution in software intended to be portable to other systems. +.P +In the event that an RE could match more than one substring of a given +string, +the RE matches the one starting earliest in the string. +If the RE could match more than one substring starting at that point, +it matches the longest. +Subexpressions also match the longest possible substrings, subject to +the constraint that the whole match be as long as possible, +with subexpressions starting earlier in the RE taking priority over +ones starting later. +Note that higher-level subexpressions thus take priority over +their lower-level component subexpressions. +.P +Match lengths are measured in characters, not collating elements. +A null string is considered longer than no match at all. +For example, +"\fIbb*\fP" matches the three middle characters of "abbbc", +"\fI(wee|week)(knights|nights)\fP" +matches all ten characters of "weeknights", +when "\fI(.*).*\fP" is matched against "abc" the parenthesized subexpression +matches all three characters, and +when "\fI(a*)*\fP" is matched against "bc" +both the whole RE and the parenthesized +subexpression match the null string. +.P +If case-independent matching is specified, +the effect is much as if all case distinctions had vanished from the +alphabet. +When an alphabetic that exists in multiple cases appears as an +ordinary character outside a bracket expression, it is effectively +transformed into a bracket expression containing both cases, +for example, \[aq]x\[aq] becomes "\fI[xX]\fP". +When it appears inside a bracket expression, all case counterparts +of it are added to the bracket expression, so that, for example, "\fI[x]\fP" +becomes "\fI[xX]\fP" and "\fI[\[ha]x]\fP" becomes "\fI[\[ha]xX]\fP". +.P +No particular limit is imposed on the length of REs\*(dg. +Programs intended to be portable should not employ REs longer +than 256 bytes, +as an implementation can refuse to accept such REs and remain +POSIX-compliant. +.P +Obsolete ("basic") regular expressions differ in several respects. +\[aq]|\[aq], \[aq]+\[aq], and \[aq]?\[aq] are +ordinary characters and there is no equivalent +for their functionality. +The delimiters for bounds are "\fI\e{\fP" and "\fI\e}\fP", +with \[aq]{\[aq] and \[aq]}\[aq] by themselves ordinary characters. +The parentheses for nested subexpressions are "\fI\e(\fP" and "\fI\e)\fP", +with \[aq](\[aq] and \[aq])\[aq] by themselves ordinary characters. +\[aq]\[ha]\[aq] is an ordinary character except at the beginning of the +RE or\*(dg the beginning of a parenthesized subexpression, +\[aq]$\[aq] is an ordinary character except at the end of the +RE or\*(dg the end of a parenthesized subexpression, +and \[aq]*\[aq] is an ordinary character if it appears at the beginning of the +RE or the beginning of a parenthesized subexpression +(after a possible leading \[aq]\[ha]\[aq]). +.P +Finally, there is one new type of atom, a \fIback reference\fR: +\[aq]\e\[aq] followed by a nonzero decimal digit \fId\fR +matches the same sequence of characters +matched by the \fId\fRth parenthesized subexpression +(numbering subexpressions by the positions of their opening parentheses, +left to right), +so that, for example, "\fI\e([bc]\e)\e1\fP" matches "bb" or "cc" but not "bc". +.SH BUGS +Having two kinds of REs is a botch. +.P +The current POSIX.2 spec says that \[aq])\[aq] is an ordinary character in +the absence of an unmatched \[aq](\[aq]; +this was an unintentional result of a wording error, +and change is likely. +Avoid relying on it. +.P +Back references are a dreadful botch, +posing major problems for efficient implementations. +They are also somewhat vaguely defined +(does +"\fIa\e(\e(b\e)*\e2\e)*d\fP" match "abbbd"?). +Avoid using them. +.P +POSIX.2's specification of case-independent matching is vague. +The "one case implies all cases" definition given above +is current consensus among implementors as to the right interpretation. +.\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 +.\" The following does not seem to apply in the glibc implementation +.\" .P +.\" The syntax for word boundaries is incredibly ugly. +.SH AUTHOR +.\" Sigh... The page license means we must have the author's name +.\" in the formatted output. +This page was taken from Henry Spencer's regex package. +.SH SEE ALSO +.BR grep (1), +.BR regex (3) +.P +POSIX.2, section 2.8 (Regular Expression Notation). diff --git a/man/man7/rtld-audit.7 b/man/man7/rtld-audit.7 new file mode 100644 index 0000000..7eb401d --- /dev/null +++ b/man/man7/rtld-audit.7 @@ -0,0 +1,606 @@ +.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2009-01-12, mtk, Created +.\" +.TH RTLD-AUDIT 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rtld\-audit \- auditing API for the dynamic linker +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.fi +.SH DESCRIPTION +The GNU dynamic linker (run-time linker) +provides an auditing API that allows an application +to be notified when various dynamic linking events occur. +This API is very similar to the auditing interface provided by the +Solaris run-time linker. +The necessary constants and prototypes are defined by including +.IR . +.P +To use this interface, the programmer creates a shared library +that implements a standard set of function names. +Not all of the functions need to be implemented: in most cases, +if the programmer is not interested in a particular class of auditing event, +then no implementation needs to be provided for the corresponding +auditing function. +.P +To employ the auditing interface, the environment variable +.B LD_AUDIT +must be defined to contain a colon-separated list of shared libraries, +each of which can implement (parts of) the auditing API. +When an auditable event occurs, +the corresponding function is invoked in each library, +in the order that the libraries are listed. +.SS la_version() +\& +.nf +.BI "unsigned int la_version(unsigned int " version ); +.fi +.P +This is the only function that +.I must +be defined by an auditing library: +it performs the initial handshake between the dynamic linker and +the auditing library. +When invoking this function, the dynamic linker passes, in +.IR version , +the highest version of the auditing interface that the linker supports. +.P +A typical implementation of this function simply returns the constant +.BR LAV_CURRENT , +which indicates the version of +.I +that was used to build the audit module. +If the dynamic linker does +not support this version of the audit interface, it will refuse to +activate this audit module. +If the function returns zero, the dynamic +linker also does not activate this audit module. +.P +In order to enable backwards compatibility with older dynamic linkers, +an audit module can examine the +.I version +argument and return an earlier version than +.BR LAV_CURRENT , +assuming the module can adjust its implementation to match the +requirements of the previous version of the audit interface. +The +.B la_version +function should not return the value of +.I version +without further checks because it could correspond to an interface +that does not match the +.I +definitions used to build the audit module. +.SS la_objsearch() +\& +.nf +.BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie , +.BI " unsigned int " flag ); +.fi +.P +The dynamic linker invokes this function to inform the auditing library +that it is about to search for a shared object. +The +.I name +argument is the filename or pathname that is to be searched for. +.I cookie +identifies the shared object that initiated the search. +.I flag +is set to one of the following values: +.TP 17 +.B LA_SER_ORIG +This is the original name that is being searched for. +Typically, this name comes from an ELF +.B DT_NEEDED +entry, or is the +.I filename +argument given to +.BR dlopen (3). +.TP +.B LA_SER_LIBPATH +.I name +was created using a directory specified in +.BR LD_LIBRARY_PATH . +.TP +.B LA_SER_RUNPATH +.I name +was created using a directory specified in an ELF +.B DT_RPATH +or +.B DT_RUNPATH +list. +.TP +.B LA_SER_CONFIG +.I name +was found via the +.BR ldconfig (8) +cache +.RI ( /etc/ld.so.cache ). +.TP +.B LA_SER_DEFAULT +.I name +was found via a search of one of the default directories. +.TP +.B LA_SER_SECURE +.I name +is specific to a secure object (unused on Linux). +.P +As its function result, +.BR la_objsearch () +returns the pathname that the dynamic linker should use +for further processing. +If NULL is returned, then this pathname is ignored for further processing. +If this audit library simply intends to monitor search paths, then +.I name +should be returned. +.SS la_activity() +\& +.nf +.BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag ); +.fi +.P +The dynamic linker calls this function to inform the auditing library +that link-map activity is occurring. +.I cookie +identifies the object at the head of the link map. +When the dynamic linker invokes this function, +.I flag +is set to one of the following values: +.TP 19 +.B LA_ACT_ADD +New objects are being added to the link map. +.TP +.B LA_ACT_DELETE +Objects are being removed from the link map. +.TP +.B LA_ACT_CONSISTENT +Link-map activity has been completed: the map is once again consistent. +.SS la_objopen() +\& +.nf +.BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid , +.BI " uintptr_t *" cookie ); +.fi +.P +The dynamic linker calls this function when a new shared object is loaded. +The +.I map +argument is a pointer to a link-map structure that describes the object. +The +.I lmid +field has one of the following values +.TP 17 +.B LM_ID_BASE +Link map is part of the initial namespace. +.TP +.B LM_ID_NEWLM +Link map is part of a new namespace requested via +.BR dlmopen (3). +.P +.I cookie +is a pointer to an identifier for this object. +The identifier is provided to later calls to functions +in the auditing library in order to identify this object. +This identifier is initialized to point to object's link map, +but the audit library can change the identifier to some other value +that it may prefer to use to identify the object. +.P +As its return value, +.BR la_objopen () +returns a bit mask created by ORing zero or more of the +following constants, +which allow the auditing library to select the objects to be monitored by +.BR la_symbind* (): +.TP 17 +.B LA_FLG_BINDTO +Audit symbol bindings to this object. +.TP +.B LA_FLG_BINDFROM +Audit symbol bindings from this object. +.P +A return value of 0 from +.BR la_objopen () +indicates that no symbol bindings should be audited for this object. +.SS la_objclose() +\& +.nf +.BI "unsigned int la_objclose(uintptr_t *" cookie ); +.fi +.P +The dynamic linker invokes this function after any finalization +code for the object has been executed, +before the object is unloaded. +The +.I cookie +argument is the identifier obtained from a previous invocation of +.BR la_objopen (). +.P +In the current implementation, the value returned by +.BR la_objclose () +is ignored. +.SS la_preinit() +\& +.nf +.BI "void la_preinit(uintptr_t *" cookie ); +.fi +.P +The dynamic linker invokes this function after all shared objects +have been loaded, before control is passed to the application +(i.e., before calling +.IR main ()). +Note that +.IR main () +may still later dynamically load objects using +.BR dlopen (3). +.SS la_symbind*() +\& +.nf +.BI "uintptr_t la_symbind32(Elf32_Sym *" sym ", unsigned int " ndx , +.BI " uintptr_t *" refcook ", uintptr_t *" defcook , +.BI " unsigned int *" flags ", const char *" symname ); +.BI "uintptr_t la_symbind64(Elf64_Sym *" sym ", unsigned int " ndx , +.BI " uintptr_t *" refcook ", uintptr_t *" defcook , +.BI " unsigned int *" flags ", const char *" symname ); +.fi +.P +The dynamic linker invokes one of these functions +when a symbol binding occurs between two shared objects +that have been marked for auditing notification by +.BR la_objopen (). +The +.BR la_symbind32 () +function is employed on 32-bit platforms; +the +.BR la_symbind64 () +function is employed on 64-bit platforms. +.P +The +.I sym +argument is a pointer to a structure +that provides information about the symbol being bound. +The structure definition is shown in +.IR . +Among the fields of this structure, +.I st_value +indicates the address to which the symbol is bound. +.P +The +.I ndx +argument gives the index of the symbol in the symbol table +of the bound shared object. +.P +The +.I refcook +argument identifies the shared object that is making the symbol reference; +this is the same identifier that is provided to the +.BR la_objopen () +function that returned +.BR LA_FLG_BINDFROM . +The +.I defcook +argument identifies the shared object that defines the referenced symbol; +this is the same identifier that is provided to the +.BR la_objopen () +function that returned +.BR LA_FLG_BINDTO . +.P +The +.I symname +argument points a string containing the name of the symbol. +.P +The +.I flags +argument is a bit mask that both provides information about the symbol +and can be used to modify further auditing of this +PLT (Procedure Linkage Table) entry. +The dynamic linker may supply the following bit values in this argument: +.\" LA_SYMB_STRUCTCALL appears to be unused +.TP 22 +.B LA_SYMB_DLSYM +The binding resulted from a call to +.BR dlsym (3). +.TP +.B LA_SYMB_ALTVALUE +A previous +.BR la_symbind* () +call returned an alternate value for this symbol. +.P +By default, if the auditing library implements +.BR la_pltenter () +and +.BR la_pltexit () +functions (see below), then these functions are invoked, after +.BR la_symbind (), +for PLT entries, each time the symbol is referenced. +.\" pltenter/pltexit are called for non-dynamically loaded libraries, +.\" but don't seem to be called for dynamically loaded libs? +.\" Is this the same on Solaris? +The following flags can be ORed into +.I *flags +to change this default behavior: +.TP 22 +.B LA_SYMB_NOPLTENTER +Don't call +.BR la_pltenter () +for this symbol. +.TP 22 +.B LA_SYMB_NOPLTEXIT +Don't call +.BR la_pltexit () +for this symbol. +.P +The return value of +.BR la_symbind32 () +and +.BR la_symbind64 () +is the address to which control should be passed after the function returns. +If the auditing library is simply monitoring symbol bindings, +then it should return +.IR sym\->st_value . +A different value may be returned if the library wishes to direct control +to an alternate location. +.SS la_pltenter() +The precise name and argument types for this function +depend on the hardware platform. +(The appropriate definition is supplied by +.IR .) +Here is the definition for x86-32: +.P +.nf +.BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx , +.BI " uintptr_t *" refcook ", uintptr_t *" defcook , +.BI " La_i86_regs *" regs ", unsigned int *" flags , +.BI " const char *" symname ", long *" framesizep ); +.fi +.P +This function is invoked just before a PLT entry is called, +between two shared objects that have been marked for binding notification. +.P +The +.IR sym , +.IR ndx , +.IR refcook , +.IR defcook , +and +.I symname +are as for +.BR la_symbind* (). +.P +The +.I regs +argument points to a structure (defined in +.IR ) +containing the values of registers to be used for +the call to this PLT entry. +.P +The +.I flags +argument points to a bit mask that conveys information about, +and can be used to modify subsequent auditing of, this PLT entry, as for +.BR la_symbind* (). +.P +.\" FIXME . Is the following correct? +The +.I framesizep +argument points to a +.I long\~int +buffer that can be used to explicitly set the frame size +used for the call to this PLT entry. +If different +.BR la_pltenter () +invocations for this symbol return different values, +then the maximum returned value is used. +The +.BR la_pltexit () +function is called only if this buffer is +explicitly set to a suitable value. +.P +The return value of +.BR la_pltenter () +is as for +.BR la_symbind* (). +.SS la_pltexit() +The precise name and argument types for this function +depend on the hardware platform. +(The appropriate definition is supplied by +.IR .) +Here is the definition for x86-32: +.P +.nf +.BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx , +.BI " uintptr_t *" refcook ", uintptr_t *" defcook , +.BI " const La_i86_regs *" inregs ", La_i86_retval *" outregs , +.BI " const char *" symname ); +.fi +.P +This function is called when a PLT entry, +made between two shared objects that have been marked +for binding notification, returns. +The function is called just before control returns to the caller +of the PLT entry. +.P +The +.IR sym , +.IR ndx , +.IR refcook , +.IR defcook , +and +.I symname +are as for +.BR la_symbind* (). +.P +The +.I inregs +argument points to a structure (defined in +.IR ) +containing the values of registers used for the call to this PLT entry. +The +.I outregs +argument points to a structure (defined in +.IR ) +containing return values for the call to this PLT entry. +These values can be modified by the caller, +and the changes will be visible to the caller of the PLT entry. +.P +In the current GNU implementation, the return value of +.BR la_pltexit () +is ignored. +.\" This differs from Solaris, where an audit library that monitors +.\" symbol binding should return the value of the 'retval' argument +.\" (not provided by GNU, but equivalent to returning outregs->lrv_eax +.\" on (say) x86-32). +.SH VERSIONS +This API is very similar to the Solaris API +described in the Solaris +.IR "Linker and Libraries Guide" , +in the chapter +.IR "Runtime Linker Auditing Interface" . +.SH STANDARDS +None. +.SH NOTES +Note the following differences from the Solaris dynamic linker +auditing API: +.IP \[bu] 3 +The Solaris +.BR la_objfilter () +interface is not supported by the GNU implementation. +.IP \[bu] +The Solaris +.BR la_symbind32 () +and +.BR la_pltexit () +functions do not provide a +.I symname +argument. +.IP \[bu] +The Solaris +.BR la_pltexit () +function does not provide +.I inregs +and +.I outregs +arguments (but does provide a +.I retval +argument with the function return value). +.SH BUGS +In glibc versions up to and include 2.9, +specifying more than one audit library in +.B LD_AUDIT +results in a run-time crash. +This is reportedly fixed in glibc 2.10. +.\" FIXME . Specifying multiple audit libraries doesn't work on GNU. +.\" My simple tests on Solaris work okay, but not on Linux -- mtk, Jan 2009 +.\" glibc bug filed: http://sourceware.org/bugzilla/show_bug.cgi?id=9733 +.\" Reportedly, this is fixed on 16 Mar 2009 (i.e., for glibc 2.10) +.SH EXAMPLES +.EX +#include +#include +\& +unsigned int +la_version(unsigned int version) +{ + printf("la_version(): version = %u; LAV_CURRENT = %u\en", + version, LAV_CURRENT); +\& + return LAV_CURRENT; +} +\& +char * +la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag) +{ + printf("la_objsearch(): name = %s; cookie = %p", name, cookie); + printf("; flag = %s\en", + (flag == LA_SER_ORIG) ? "LA_SER_ORIG" : + (flag == LA_SER_LIBPATH) ? "LA_SER_LIBPATH" : + (flag == LA_SER_RUNPATH) ? "LA_SER_RUNPATH" : + (flag == LA_SER_DEFAULT) ? "LA_SER_DEFAULT" : + (flag == LA_SER_CONFIG) ? "LA_SER_CONFIG" : + (flag == LA_SER_SECURE) ? "LA_SER_SECURE" : + "???"); +\& + return name; +} +\& +void +la_activity (uintptr_t *cookie, unsigned int flag) +{ + printf("la_activity(): cookie = %p; flag = %s\en", cookie, + (flag == LA_ACT_CONSISTENT) ? "LA_ACT_CONSISTENT" : + (flag == LA_ACT_ADD) ? "LA_ACT_ADD" : + (flag == LA_ACT_DELETE) ? "LA_ACT_DELETE" : + "???"); +} +\& +unsigned int +la_objopen(struct link_map *map, Lmid_t lmid, uintptr_t *cookie) +{ + printf("la_objopen(): loading \e"%s\e"; lmid = %s; cookie=%p\en", + map\->l_name, + (lmid == LM_ID_BASE) ? "LM_ID_BASE" : + (lmid == LM_ID_NEWLM) ? "LM_ID_NEWLM" : + "???", + cookie); +\& + return LA_FLG_BINDTO | LA_FLG_BINDFROM; +} +\& +unsigned int +la_objclose (uintptr_t *cookie) +{ + printf("la_objclose(): %p\en", cookie); +\& + return 0; +} +\& +void +la_preinit(uintptr_t *cookie) +{ + printf("la_preinit(): %p\en", cookie); +} +\& +uintptr_t +la_symbind32(Elf32_Sym *sym, unsigned int ndx, uintptr_t *refcook, + uintptr_t *defcook, unsigned int *flags, const char *symname) +{ + printf("la_symbind32(): symname = %s; sym\->st_value = %p\en", + symname, sym\->st_value); + printf(" ndx = %u; flags = %#x", ndx, *flags); + printf("; refcook = %p; defcook = %p\en", refcook, defcook); +\& + return sym\->st_value; +} +\& +uintptr_t +la_symbind64(Elf64_Sym *sym, unsigned int ndx, uintptr_t *refcook, + uintptr_t *defcook, unsigned int *flags, const char *symname) +{ + printf("la_symbind64(): symname = %s; sym\->st_value = %p\en", + symname, sym\->st_value); + printf(" ndx = %u; flags = %#x", ndx, *flags); + printf("; refcook = %p; defcook = %p\en", refcook, defcook); +\& + return sym\->st_value; +} +\& +Elf32_Addr +la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx, + uintptr_t *refcook, uintptr_t *defcook, La_i86_regs *regs, + unsigned int *flags, const char *symname, long *framesizep) +{ + printf("la_i86_gnu_pltenter(): %s (%p)\en", symname, sym\->st_value); +\& + return sym\->st_value; +} +.EE +.SH SEE ALSO +.BR ldd (1), +.BR dlopen (3), +.BR ld.so (8), +.BR ldconfig (8) diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7 new file mode 100644 index 0000000..ce4cf35 --- /dev/null +++ b/man/man7/rtnetlink.7 @@ -0,0 +1,590 @@ +'\" t +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" Based on the original comments from Alexey Kuznetsov, written with +.\" help from Matthew Wilcox. +.\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $ +.\" +.TH rtnetlink 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +rtnetlink \- Linux routing socket +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.P +.BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type ", NETLINK_ROUTE);" +.fi +.SH DESCRIPTION +Rtnetlink allows the kernel's routing tables to be read and altered. +It is used within the kernel to communicate between +various subsystems, though this usage is not documented here, and for +communication with user-space programs. +Network routes, IP addresses, link parameters, neighbor setups, queueing +disciplines, traffic classes and packet classifiers may all be controlled +through +.B NETLINK_ROUTE +sockets. +It is based on netlink messages; see +.BR netlink (7) +for more information. +.\" FIXME . ? all these macros could be moved to rtnetlink(3) +.SS Routing attributes +Some rtnetlink messages have optional attributes after the initial header: +.P +.in +4n +.EX +struct rtattr { + unsigned short rta_len; /* Length of option */ + unsigned short rta_type; /* Type of option */ + /* Data follows */ +}; +.EE +.in +.P +These attributes should be manipulated using only the RTA_* macros +or libnetlink, see +.BR rtnetlink (3). +.SS Messages +Rtnetlink consists of these message types +(in addition to standard netlink messages): +.TP +.B RTM_NEWLINK +.TQ +.B RTM_DELLINK +.TQ +.B RTM_GETLINK +Create, remove, or get information about a specific network interface. +These messages contain an +.I ifinfomsg +structure followed by a series of +.I rtattr +structures. +.IP +.EX +struct ifinfomsg { + unsigned char ifi_family; /* AF_UNSPEC */ + unsigned short ifi_type; /* Device type */ + int ifi_index; /* Interface index */ + unsigned int ifi_flags; /* Device flags */ + unsigned int ifi_change; /* change mask */ +}; +.EE +.IP +.\" FIXME Document ifinfomsg.ifi_type +.I ifi_flags +contains the device flags, see +.BR netdevice (7); +.I ifi_index +is the unique interface index +(since Linux 3.7, it is possible to feed a nonzero value with the +.B RTM_NEWLINK +message, thus creating a link with the given +.IR ifindex ); +.I ifi_change +is reserved for future use and should be always set to 0xFFFFFFFF. +.TS +tab(:); +c s s +lb l l. +Routing attributes +rta_type:Value type:Description +_ +IFLA_UNSPEC:-:unspecified +IFLA_ADDRESS:hardware address:interface L2 address +IFLA_BROADCAST:hardware address:L2 broadcast address +IFLA_IFNAME:asciiz string:Device name +IFLA_MTU:unsigned int:MTU of the device +IFLA_LINK:int:Link type +IFLA_QDISC:asciiz string:Queueing discipline +IFLA_STATS:T{ +see below +T}:Interface Statistics +IFLA_PERM_ADDRESS:hardware address:T{ +hardware address provided by device (since Linux 5.5) +T} +.TE +.IP +The value type for +.B IFLA_STATS +is +.I struct rtnl_link_stats +.RI ( "struct net_device_stats" +in Linux 2.4 and earlier). +.TP +.B RTM_NEWADDR +.TQ +.B RTM_DELADDR +.TQ +.B RTM_GETADDR +Add, remove, or receive information about an IP address associated with +an interface. +In Linux 2.2, an interface can carry multiple IP addresses, +this replaces the alias device concept in Linux 2.0. +In Linux 2.2, these messages +support IPv4 and IPv6 addresses. +They contain an +.I ifaddrmsg +structure, optionally followed by +.I rtattr +routing attributes. +.IP +.EX +struct ifaddrmsg { + unsigned char ifa_family; /* Address type */ + unsigned char ifa_prefixlen; /* Prefixlength of address */ + unsigned char ifa_flags; /* Address flags */ + unsigned char ifa_scope; /* Address scope */ + unsigned int ifa_index; /* Interface index */ +}; +.EE +.IP +.I ifa_family +is the address family type (currently +.B AF_INET +or +.BR AF_INET6 ), +.I ifa_prefixlen +is the length of the address mask of the address if defined for the +family (like for IPv4), +.I ifa_scope +is the address scope, +.I ifa_index +is the interface index of the interface the address is associated with. +.I ifa_flags +is a flag word of +.B IFA_F_SECONDARY +for secondary address (old alias interface), +.B IFA_F_PERMANENT +for a permanent address set by the user and other undocumented flags. +.TS +tab(:); +c s s +lb l l. +Attributes +rta_type:Value type:Description +_ +IFA_UNSPEC:-:unspecified +IFA_ADDRESS:raw protocol address:interface address +IFA_LOCAL:raw protocol address:local address +IFA_LABEL:asciiz string:name of the interface +IFA_BROADCAST:raw protocol address:broadcast address +IFA_ANYCAST:raw protocol address:anycast address +IFA_CACHEINFO:struct ifa_cacheinfo:Address information +.TE +.\" FIXME Document struct ifa_cacheinfo +.TP +.B RTM_NEWROUTE +.TQ +.B RTM_DELROUTE +.TQ +.B RTM_GETROUTE +Create, remove, or receive information about a network route. +These messages contain an +.I rtmsg +structure with an optional sequence of +.I rtattr +structures following. +For +.BR RTM_GETROUTE , +setting +.I rtm_dst_len +and +.I rtm_src_len +to 0 means you get all entries for the specified routing table. +For the other fields, except +.I rtm_table +and +.IR rtm_protocol , +0 is the wildcard. +.IP +.EX +struct rtmsg { + unsigned char rtm_family; /* Address family of route */ + unsigned char rtm_dst_len; /* Length of destination */ + unsigned char rtm_src_len; /* Length of source */ + unsigned char rtm_tos; /* TOS filter */ + unsigned char rtm_table; /* Routing table ID; + see RTA_TABLE below */ + unsigned char rtm_protocol; /* Routing protocol; see below */ + unsigned char rtm_scope; /* See below */ + unsigned char rtm_type; /* See below */ +\& + unsigned int rtm_flags; +}; +.EE +.TS +tab(:); +lb l. +rtm_type:Route type +_ +RTN_UNSPEC:unknown route +RTN_UNICAST:a gateway or direct route +RTN_LOCAL:a local interface route +RTN_BROADCAST:T{ +a local broadcast route (sent as a broadcast) +T} +RTN_ANYCAST:T{ +a local broadcast route (sent as a unicast) +T} +RTN_MULTICAST:a multicast route +RTN_BLACKHOLE:a packet dropping route +RTN_UNREACHABLE:an unreachable destination +RTN_PROHIBIT:a packet rejection route +RTN_THROW:continue routing lookup in another table +RTN_NAT:a network address translation rule +RTN_XRESOLVE:T{ +refer to an external resolver (not implemented) +T} +.TE +.TS +tab(:); +lb l. +rtm_protocol:Route origin +_ +RTPROT_UNSPEC:unknown +RTPROT_REDIRECT:T{ +by an ICMP redirect (currently unused) +T} +RTPROT_KERNEL:by the kernel +RTPROT_BOOT:during boot +RTPROT_STATIC:by the administrator +.TE +.IP +Values larger than +.B RTPROT_STATIC +are not interpreted by the kernel, they are just for user information. +They may be used to tag the source of a routing information or to +distinguish between multiple routing daemons. +See +.I +for the routing daemon identifiers which are already assigned. +.IP +.I rtm_scope +is the distance to the destination: +.TS +tab(:); +lb l. +RT_SCOPE_UNIVERSE:global route +RT_SCOPE_SITE:T{ +interior route in the local autonomous system +T} +RT_SCOPE_LINK:route on this link +RT_SCOPE_HOST:route on the local host +RT_SCOPE_NOWHERE:destination doesn't exist +.TE +.IP +The values between +.B RT_SCOPE_UNIVERSE +and +.B RT_SCOPE_SITE +are available to the user. +.IP +The +.I rtm_flags +have the following meanings: +.TS +tab(:); +lb l. +RTM_F_NOTIFY:T{ +if the route changes, notify the user via rtnetlink +T} +RTM_F_CLONED:route is cloned from another route +RTM_F_EQUALIZE:a multipath equalizer (not yet implemented) +.TE +.IP +.I rtm_table +specifies the routing table +.TS +tab(:); +lb l. +RT_TABLE_UNSPEC:an unspecified routing table +RT_TABLE_DEFAULT:the default table +RT_TABLE_MAIN:the main table +RT_TABLE_LOCAL:the local table +.TE +.IP +The user may assign arbitrary values between +.B RT_TABLE_UNSPEC +and +.BR RT_TABLE_DEFAULT . +.\" Keep table on same page +.bp +1 +.TS +tab(:); +c s s +lb2 l2 l. +Attributes +rta_type:Value type:Description +_ +RTA_UNSPEC:-:ignored +RTA_DST:protocol address:Route destination address +RTA_SRC:protocol address:Route source address +RTA_IIF:int:Input interface index +RTA_OIF:int:Output interface index +RTA_GATEWAY:protocol address:The gateway of the route +RTA_PRIORITY:int:Priority of route +RTA_PREFSRC:protocol address:Preferred source address +RTA_METRICS:int:Route metric +RTA_MULTIPATH::T{ +Multipath nexthop data +br +(see below). +T} +RTA_PROTOINFO::No longer used +RTA_FLOW:int:Route realm +RTA_CACHEINFO:struct rta_cacheinfo:(see linux/rtnetlink.h) +RTA_SESSION::No longer used +RTA_MP_ALGO::No longer used +RTA_TABLE:int:T{ +Routing table ID; if set, +.br +rtm_table is ignored +T} +RTA_MARK:int: +RTA_MFC_STATS:struct rta_mfc_stats:(see linux/rtnetlink.h) +RTA_VIA:struct rtvia:T{ +Gateway in different AF +(see below) +T} +RTA_NEWDST:protocol address:T{ +Change packet +destination address +T} +RTA_PREF:char:T{ +RFC4191 IPv6 router +preference (see below) +T} +RTA_ENCAP_TYPE:short:T{ +Encapsulation type for +.br +lwtunnels (see below) +T} +RTA_ENCAP::Defined by RTA_ENCAP_TYPE +RTA_EXPIRES:int:T{ +Expire time for IPv6 +routes (in seconds) +T} +.TE +.IP +.B RTA_MULTIPATH +contains several packed instances of +.I struct rtnexthop +together with nested RTAs +.RB ( RTA_GATEWAY ): +.IP +.in +4n +.EX +struct rtnexthop { + unsigned short rtnh_len; /* Length of struct + length + of RTAs */ + unsigned char rtnh_flags; /* Flags (see + linux/rtnetlink.h) */ + unsigned char rtnh_hops; /* Nexthop priority */ + int rtnh_ifindex; /* Interface index for this + nexthop */ +} +.EE +.in +.IP +There exist a bunch of +.B RTNH_* +macros similar to +.B RTA_* +and +.B NLHDR_* +macros +useful to handle these structures. +.IP +.in +4n +.EX +struct rtvia { + unsigned short rtvia_family; + unsigned char rtvia_addr[0]; +}; +.EE +.in +.IP +.I rtvia_addr +is the address, +.I rtvia_family +is its family type. +.IP +.B RTA_PREF +may contain values +.BR ICMPV6_ROUTER_PREF_LOW , +.BR ICMPV6_ROUTER_PREF_MEDIUM , +and +.B ICMPV6_ROUTER_PREF_HIGH +defined incw +.IR . +.IP +.B RTA_ENCAP_TYPE +may contain values +.BR LWTUNNEL_ENCAP_MPLS , +.BR LWTUNNEL_ENCAP_IP , +.BR LWTUNNEL_ENCAP_ILA , +or +.B LWTUNNEL_ENCAP_IP6 +defined in +.IR . +.IP +.B Fill these values in! +.TP +.B RTM_NEWNEIGH +.TQ +.B RTM_DELNEIGH +.TQ +.B RTM_GETNEIGH +Add, remove, or receive information about a neighbor table +entry (e.g., an ARP entry). +The message contains an +.I ndmsg +structure. +.IP +.EX +struct ndmsg { + unsigned char ndm_family; + int ndm_ifindex; /* Interface index */ + __u16 ndm_state; /* State */ + __u8 ndm_flags; /* Flags */ + __u8 ndm_type; +}; +\& +struct nda_cacheinfo { + __u32 ndm_confirmed; + __u32 ndm_used; + __u32 ndm_updated; + __u32 ndm_refcnt; +}; +.EE +.IP +.I ndm_state +is a bit mask of the following states: +.TS +tab(:); +lb l. +NUD_INCOMPLETE:a currently resolving cache entry +NUD_REACHABLE:a confirmed working cache entry +NUD_STALE:an expired cache entry +NUD_DELAY:an entry waiting for a timer +NUD_PROBE:a cache entry that is currently reprobed +NUD_FAILED:an invalid cache entry +NUD_NOARP:a device with no destination cache +NUD_PERMANENT:a static entry +.TE +.IP +Valid +.I ndm_flags +are: +.TS +tab(:); +lb l. +NTF_PROXY:a proxy arp entry +NTF_ROUTER:an IPv6 router +.TE +.IP +.\" FIXME . +.\" document the members of the struct better +The +.I rtattr +struct has the following meanings for the +.I rta_type +field: +.TS +tab(:); +lb l. +NDA_UNSPEC:unknown type +NDA_DST:a neighbor cache n/w layer destination address +NDA_LLADDR:a neighbor cache link layer address +NDA_CACHEINFO:cache statistics +.TE +.IP +If the +.I rta_type +field is +.BR NDA_CACHEINFO , +then a +.I struct nda_cacheinfo +header follows. +.TP +.B RTM_NEWRULE +.TQ +.B RTM_DELRULE +.TQ +.B RTM_GETRULE +Add, delete, or retrieve a routing rule. +Carries a +.I struct rtmsg +.TP +.B RTM_NEWQDISC +.TQ +.B RTM_DELQDISC +.TQ +.B RTM_GETQDISC +Add, remove, or get a queueing discipline. +The message contains a +.I struct tcmsg +and may be followed by a series of +attributes. +.IP +.EX +struct tcmsg { + unsigned char tcm_family; + int tcm_ifindex; /* interface index */ + __u32 tcm_handle; /* Qdisc handle */ + __u32 tcm_parent; /* Parent qdisc */ + __u32 tcm_info; +}; +.EE +.TS +tab(:); +c s s +lb2 l2 l. +Attributes +rta_type:Value type:Description +_ +TCA_UNSPEC:-:unspecified +TCA_KIND:asciiz string:Name of queueing discipline +TCA_OPTIONS:byte sequence:Qdisc-specific options follow +TCA_STATS:struct tc_stats:Qdisc statistics +TCA_XSTATS:qdisc-specific:Module-specific statistics +TCA_RATE:struct tc_estimator:Rate limit +.TE +.IP +In addition, various other qdisc-module-specific attributes are allowed. +For more information see the appropriate include files. +.TP +.B RTM_NEWTCLASS +.TQ +.B RTM_DELTCLASS +.TQ +.B RTM_GETTCLASS +Add, remove, or get a traffic class. +These messages contain a +.I struct tcmsg +as described above. +.TP +.B RTM_NEWTFILTER +.TQ +.B RTM_DELTFILTER +.TQ +.B RTM_GETTFILTER +Add, remove, or receive information about a traffic filter. +These messages contain a +.I struct tcmsg +as described above. +.SH VERSIONS +.B rtnetlink +is a new feature of Linux 2.2. +.SH BUGS +This manual page is incomplete. +.SH SEE ALSO +.BR cmsg (3), +.BR rtnetlink (3), +.BR ip (7), +.BR netlink (7) diff --git a/man/man7/sched.7 b/man/man7/sched.7 new file mode 100644 index 0000000..607b919 --- /dev/null +++ b/man/man7/sched.7 @@ -0,0 +1,992 @@ +.\" Copyright (C) 2014 Michael Kerrisk +.\" and Copyright (C) 2014 Peter Zijlstra +.\" and Copyright (C) 2014 Juri Lelli +.\" Various pieces from the old sched_setscheduler(2) page +.\" Copyright (C) Tom Bjorkholm, Markus Kuhn & David A. Wheeler 1996-1999 +.\" and Copyright (C) 2007 Carsten Emde +.\" and Copyright (C) 2008 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Worth looking at: http://rt.wiki.kernel.org/index.php +.\" +.TH sched 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sched \- overview of CPU scheduling +.SH DESCRIPTION +Since Linux 2.6.23, the default scheduler is CFS, +the "Completely Fair Scheduler". +The CFS scheduler replaced the earlier "O(1)" scheduler. +.\" +.SS API summary +Linux provides the following system calls for controlling +the CPU scheduling behavior, policy, and priority of processes +(or, more precisely, threads). +.TP +.BR nice (2) +Set a new nice value for the calling thread, +and return the new nice value. +.TP +.BR getpriority (2) +Return the nice value of a thread, a process group, +or the set of threads owned by a specified user. +.TP +.BR setpriority (2) +Set the nice value of a thread, a process group, +or the set of threads owned by a specified user. +.TP +.BR sched_setscheduler (2) +Set the scheduling policy and parameters of a specified thread. +.TP +.BR sched_getscheduler (2) +Return the scheduling policy of a specified thread. +.TP +.BR sched_setparam (2) +Set the scheduling parameters of a specified thread. +.TP +.BR sched_getparam (2) +Fetch the scheduling parameters of a specified thread. +.TP +.BR sched_get_priority_max (2) +Return the maximum priority available in a specified scheduling policy. +.TP +.BR sched_get_priority_min (2) +Return the minimum priority available in a specified scheduling policy. +.TP +.BR sched_rr_get_interval (2) +Fetch the quantum used for threads that are scheduled under +the "round-robin" scheduling policy. +.TP +.BR sched_yield (2) +Cause the caller to relinquish the CPU, +so that some other thread be executed. +.TP +.BR sched_setaffinity (2) +(Linux-specific) +Set the CPU affinity of a specified thread. +.TP +.BR sched_getaffinity (2) +(Linux-specific) +Get the CPU affinity of a specified thread. +.TP +.BR sched_setattr (2) +Set the scheduling policy and parameters of a specified thread. +This (Linux-specific) system call provides a superset of the functionality of +.BR sched_setscheduler (2) +and +.BR sched_setparam (2). +.TP +.BR sched_getattr (2) +Fetch the scheduling policy and parameters of a specified thread. +This (Linux-specific) system call provides a superset of the functionality of +.BR sched_getscheduler (2) +and +.BR sched_getparam (2). +.\" +.SS Scheduling policies +The scheduler is the kernel component that decides which runnable thread +will be executed by the CPU next. +Each thread has an associated scheduling policy and a \fIstatic\fP +scheduling priority, +.IR sched_priority . +The scheduler makes its decisions based on knowledge of the scheduling +policy and static priority of all threads on the system. +.P +For threads scheduled under one of the normal scheduling policies +(\fBSCHED_OTHER\fP, \fBSCHED_IDLE\fP, \fBSCHED_BATCH\fP), +\fIsched_priority\fP is not used in scheduling +decisions (it must be specified as 0). +.P +Processes scheduled under one of the real-time policies +(\fBSCHED_FIFO\fP, \fBSCHED_RR\fP) have a +\fIsched_priority\fP value in the range 1 (low) to 99 (high). +(As the numbers imply, real-time threads always have higher priority +than normal threads.) +Note well: POSIX.1 requires an implementation to support only a +minimum 32 distinct priority levels for the real-time policies, +and some systems supply just this minimum. +Portable programs should use +.BR sched_get_priority_min (2) +and +.BR sched_get_priority_max (2) +to find the range of priorities supported for a particular policy. +.P +Conceptually, the scheduler maintains a list of runnable +threads for each possible \fIsched_priority\fP value. +In order to determine which thread runs next, the scheduler looks for +the nonempty list with the highest static priority and selects the +thread at the head of this list. +.P +A thread's scheduling policy determines +where it will be inserted into the list of threads +with equal static priority and how it will move inside this list. +.P +All scheduling is preemptive: if a thread with a higher static +priority becomes ready to run, the currently running thread +will be preempted and +returned to the wait list for its static priority level. +The scheduling policy determines the +ordering only within the list of runnable threads with equal static +priority. +.SS SCHED_FIFO: First in-first out scheduling +\fBSCHED_FIFO\fP can be used only with static priorities higher than +0, which means that when a \fBSCHED_FIFO\fP thread becomes runnable, +it will always immediately preempt any currently running +\fBSCHED_OTHER\fP, \fBSCHED_BATCH\fP, or \fBSCHED_IDLE\fP thread. +\fBSCHED_FIFO\fP is a simple scheduling +algorithm without time slicing. +For threads scheduled under the +\fBSCHED_FIFO\fP policy, the following rules apply: +.IP \[bu] 3 +A running \fBSCHED_FIFO\fP thread that has been preempted by another thread of +higher priority will stay at the head of the list for its priority and +will resume execution as soon as all threads of higher priority are +blocked again. +.IP \[bu] +When a blocked \fBSCHED_FIFO\fP thread becomes runnable, it +will be inserted at the end of the list for its priority. +.IP \[bu] +If a call to +.BR sched_setscheduler (2), +.BR sched_setparam (2), +.BR sched_setattr (2), +.BR pthread_setschedparam (3), +or +.BR pthread_setschedprio (3) +changes the priority of the running or runnable +.B SCHED_FIFO +thread identified by +.I pid +the effect on the thread's position in the list depends on +the direction of the change to the thread's priority: +.RS +.IP (a) 5 +If the thread's priority is raised, +it is placed at the end of the list for its new priority. +As a consequence, +it may preempt a currently running thread with the same priority. +.IP (b) +If the thread's priority is unchanged, +its position in the run list is unchanged. +.IP (c) +If the thread's priority is lowered, +it is placed at the front of the list for its new priority. +.RE +.IP +According to POSIX.1-2008, +changes to a thread's priority (or policy) using any mechanism other than +.BR pthread_setschedprio (3) +should result in the thread being placed at the end of +the list for its priority. +.\" In Linux 2.2.x and Linux 2.4.x, the thread is placed at the front of the queue +.\" In Linux 2.0.x, the Right Thing happened: the thread went to the back -- MTK +.IP \[bu] +A thread calling +.BR sched_yield (2) +will be put at the end of the list. +.P +No other events will move a thread +scheduled under the \fBSCHED_FIFO\fP policy in the wait list of +runnable threads with equal static priority. +.P +A \fBSCHED_FIFO\fP +thread runs until either it is blocked by an I/O request, it is +preempted by a higher priority thread, or it calls +.BR sched_yield (2). +.SS SCHED_RR: Round-robin scheduling +\fBSCHED_RR\fP is a simple enhancement of \fBSCHED_FIFO\fP. +Everything +described above for \fBSCHED_FIFO\fP also applies to \fBSCHED_RR\fP, +except that each thread is allowed to run only for a maximum time +quantum. +If a \fBSCHED_RR\fP thread has been running for a time +period equal to or longer than the time quantum, it will be put at the +end of the list for its priority. +A \fBSCHED_RR\fP thread that has +been preempted by a higher priority thread and subsequently resumes +execution as a running thread will complete the unexpired portion of +its round-robin time quantum. +The length of the time quantum can be +retrieved using +.BR sched_rr_get_interval (2). +.\" On Linux 2.4, the length of the RR interval is influenced +.\" by the process nice value -- MTK +.\" +.SS SCHED_DEADLINE: Sporadic task model deadline scheduling +Since Linux 3.14, Linux provides a deadline scheduling policy +.RB ( SCHED_DEADLINE ). +This policy is currently implemented using +GEDF (Global Earliest Deadline First) +in conjunction with CBS (Constant Bandwidth Server). +To set and fetch this policy and associated attributes, +one must use the Linux-specific +.BR sched_setattr (2) +and +.BR sched_getattr (2) +system calls. +.P +A sporadic task is one that has a sequence of jobs, where each +job is activated at most once per period. +Each job also has a +.IR "relative deadline" , +before which it should finish execution, and a +.IR "computation time" , +which is the CPU time necessary for executing the job. +The moment when a task wakes up +because a new job has to be executed is called the +.I arrival time +(also referred to as the request time or release time). +The +.I start time +is the time at which a task starts its execution. +The +.I absolute deadline +is thus obtained by adding the relative deadline to the arrival time. +.P +The following diagram clarifies these terms: +.P +.in +4n +.EX +arrival/wakeup absolute deadline + | start time | + | | | + v v v +-----x--------xooooooooooooooooo--------x--------x--- + |<- comp. time ->| + |<------- relative deadline ------>| + |<-------------- period ------------------->| +.EE +.in +.P +When setting a +.B SCHED_DEADLINE +policy for a thread using +.BR sched_setattr (2), +one can specify three parameters: +.IR Runtime , +.IR Deadline , +and +.IR Period . +These parameters do not necessarily correspond to the aforementioned terms: +usual practice is to set Runtime to something bigger than the average +computation time (or worst-case execution time for hard real-time tasks), +Deadline to the relative deadline, and Period to the period of the task. +Thus, for +.B SCHED_DEADLINE +scheduling, we have: +.P +.in +4n +.EX +arrival/wakeup absolute deadline + | start time | + | | | + v v v +-----x--------xooooooooooooooooo--------x--------x--- + |<-- Runtime ------->| + |<----------- Deadline ----------->| + |<-------------- Period ------------------->| +.EE +.in +.P +The three deadline-scheduling parameters correspond to the +.IR sched_runtime , +.IR sched_deadline , +and +.I sched_period +fields of the +.I sched_attr +structure; see +.BR sched_setattr (2). +These fields express values in nanoseconds. +.\" FIXME It looks as though specifying sched_period as 0 means +.\" "make sched_period the same as sched_deadline". +.\" This needs to be documented. +If +.I sched_period +is specified as 0, then it is made the same as +.IR sched_deadline . +.P +The kernel requires that: +.P +.in +4n +.EX +sched_runtime <= sched_deadline <= sched_period +.EE +.in +.P +.\" See __checkparam_dl in kernel/sched/core.c +In addition, under the current implementation, +all of the parameter values must be at least 1024 +(i.e., just over one microsecond, +which is the resolution of the implementation), and less than 2\[ha]63. +If any of these checks fails, +.BR sched_setattr (2) +fails with the error +.BR EINVAL . +.P +The CBS guarantees non-interference between tasks, by throttling +threads that attempt to over-run their specified Runtime. +.P +To ensure deadline scheduling guarantees, +the kernel must prevent situations where the set of +.B SCHED_DEADLINE +threads is not feasible (schedulable) within the given constraints. +The kernel thus performs an admittance test when setting or changing +.B SCHED_DEADLINE +policy and attributes. +This admission test calculates whether the change is feasible; +if it is not, +.BR sched_setattr (2) +fails with the error +.BR EBUSY . +.P +For example, it is required (but not necessarily sufficient) for +the total utilization to be less than or equal to the total number of +CPUs available, where, since each thread can maximally run for +Runtime per Period, that thread's utilization is its +Runtime divided by its Period. +.P +In order to fulfill the guarantees that are made when +a thread is admitted to the +.B SCHED_DEADLINE +policy, +.B SCHED_DEADLINE +threads are the highest priority (user controllable) threads in the +system; if any +.B SCHED_DEADLINE +thread is runnable, +it will preempt any thread scheduled under one of the other policies. +.P +A call to +.BR fork (2) +by a thread scheduled under the +.B SCHED_DEADLINE +policy fails with the error +.BR EAGAIN , +unless the thread has its reset-on-fork flag set (see below). +.P +A +.B SCHED_DEADLINE +thread that calls +.BR sched_yield (2) +will yield the current job and wait for a new period to begin. +.\" +.\" FIXME Calling sched_getparam() on a SCHED_DEADLINE thread +.\" fails with EINVAL, but sched_getscheduler() succeeds. +.\" Is that intended? (Why?) +.\" +.SS SCHED_OTHER: Default Linux time-sharing scheduling +\fBSCHED_OTHER\fP can be used at only static priority 0 +(i.e., threads under real-time policies always have priority over +.B SCHED_OTHER +processes). +\fBSCHED_OTHER\fP is the standard Linux time-sharing scheduler that is +intended for all threads that do not require the special +real-time mechanisms. +.P +The thread to run is chosen from the static +priority 0 list based on a \fIdynamic\fP priority that is determined only +inside this list. +The dynamic priority is based on the nice value (see below) +and is increased for each time quantum the thread is ready to run, +but denied to run by the scheduler. +This ensures fair progress among all \fBSCHED_OTHER\fP threads. +.P +In the Linux kernel source code, the +.B SCHED_OTHER +policy is actually named +.BR SCHED_NORMAL . +.\" +.SS The nice value +The nice value is an attribute +that can be used to influence the CPU scheduler to +favor or disfavor a process in scheduling decisions. +It affects the scheduling of +.B SCHED_OTHER +and +.B SCHED_BATCH +(see below) processes. +The nice value can be modified using +.BR nice (2), +.BR setpriority (2), +or +.BR sched_setattr (2). +.P +According to POSIX.1, the nice value is a per-process attribute; +that is, the threads in a process should share a nice value. +However, on Linux, the nice value is a per-thread attribute: +different threads in the same process may have different nice values. +.P +The range of the nice value +varies across UNIX systems. +On modern Linux, the range is \-20 (high priority) to +19 (low priority). +On some other systems, the range is \-20..20. +Very early Linux kernels (before Linux 2.0) had the range \-infinity..15. +.\" Linux before 1.3.36 had \-infinity..15. +.\" Since Linux 1.3.43, Linux has the range \-20..19. +.P +The degree to which the nice value affects the relative scheduling of +.B SCHED_OTHER +processes likewise varies across UNIX systems and +across Linux kernel versions. +.P +With the advent of the CFS scheduler in Linux 2.6.23, +Linux adopted an algorithm that causes +relative differences in nice values to have a much stronger effect. +In the current implementation, each unit of difference in the +nice values of two processes results in a factor of 1.25 +in the degree to which the scheduler favors the higher priority process. +This causes very low nice values (+19) to truly provide little CPU +to a process whenever there is any other +higher priority load on the system, +and makes high nice values (\-20) deliver most of the CPU to applications +that require it (e.g., some audio applications). +.P +On Linux, the +.B RLIMIT_NICE +resource limit can be used to define a limit to which +an unprivileged process's nice value can be raised; see +.BR setrlimit (2) +for details. +.P +For further details on the nice value, see the subsections on +the autogroup feature and group scheduling, below. +.\" +.SS SCHED_BATCH: Scheduling batch processes +(Since Linux 2.6.16.) +\fBSCHED_BATCH\fP can be used only at static priority 0. +This policy is similar to \fBSCHED_OTHER\fP in that it schedules +the thread according to its dynamic priority +(based on the nice value). +The difference is that this policy +will cause the scheduler to always assume +that the thread is CPU-intensive. +Consequently, the scheduler will apply a small scheduling +penalty with respect to wakeup behavior, +so that this thread is mildly disfavored in scheduling decisions. +.P +.\" The following paragraph is drawn largely from the text that +.\" accompanied Ingo Molnar's patch for the implementation of +.\" SCHED_BATCH. +.\" commit b0a9499c3dd50d333e2aedb7e894873c58da3785 +This policy is useful for workloads that are noninteractive, +but do not want to lower their nice value, +and for workloads that want a deterministic scheduling policy without +interactivity causing extra preemptions (between the workload's tasks). +.\" +.SS SCHED_IDLE: Scheduling very low priority jobs +(Since Linux 2.6.23.) +\fBSCHED_IDLE\fP can be used only at static priority 0; +the process nice value has no influence for this policy. +.P +This policy is intended for running jobs at extremely low +priority (lower even than a +19 nice value with the +.B SCHED_OTHER +or +.B SCHED_BATCH +policies). +.\" +.SS Resetting scheduling policy for child processes +Each thread has a reset-on-fork scheduling flag. +When this flag is set, children created by +.BR fork (2) +do not inherit privileged scheduling policies. +The reset-on-fork flag can be set by either: +.IP \[bu] 3 +ORing the +.B SCHED_RESET_ON_FORK +flag into the +.I policy +argument when calling +.BR sched_setscheduler (2) +(since Linux 2.6.32); +or +.IP \[bu] +specifying the +.B SCHED_FLAG_RESET_ON_FORK +flag in +.I attr.sched_flags +when calling +.BR sched_setattr (2). +.P +Note that the constants used with these two APIs have different names. +The state of the reset-on-fork flag can analogously be retrieved using +.BR sched_getscheduler (2) +and +.BR sched_getattr (2). +.P +The reset-on-fork feature is intended for media-playback applications, +and can be used to prevent applications evading the +.B RLIMIT_RTTIME +resource limit (see +.BR getrlimit (2)) +by creating multiple child processes. +.P +More precisely, if the reset-on-fork flag is set, +the following rules apply for subsequently created children: +.IP \[bu] 3 +If the calling thread has a scheduling policy of +.B SCHED_FIFO +or +.BR SCHED_RR , +the policy is reset to +.B SCHED_OTHER +in child processes. +.IP \[bu] +If the calling process has a negative nice value, +the nice value is reset to zero in child processes. +.P +After the reset-on-fork flag has been enabled, +it can be reset only if the thread has the +.B CAP_SYS_NICE +capability. +This flag is disabled in child processes created by +.BR fork (2). +.\" +.SS Privileges and resource limits +Before Linux 2.6.12, only privileged +.RB ( CAP_SYS_NICE ) +threads can set a nonzero static priority (i.e., set a real-time +scheduling policy). +The only change that an unprivileged thread can make is to set the +.B SCHED_OTHER +policy, and this can be done only if the effective user ID of the caller +matches the real or effective user ID of the target thread +(i.e., the thread specified by +.IR pid ) +whose policy is being changed. +.P +A thread must be privileged +.RB ( CAP_SYS_NICE ) +in order to set or modify a +.B SCHED_DEADLINE +policy. +.P +Since Linux 2.6.12, the +.B RLIMIT_RTPRIO +resource limit defines a ceiling on an unprivileged thread's +static priority for the +.B SCHED_RR +and +.B SCHED_FIFO +policies. +The rules for changing scheduling policy and priority are as follows: +.IP \[bu] 3 +If an unprivileged thread has a nonzero +.B RLIMIT_RTPRIO +soft limit, then it can change its scheduling policy and priority, +subject to the restriction that the priority cannot be set to a +value higher than the maximum of its current priority and its +.B RLIMIT_RTPRIO +soft limit. +.IP \[bu] +If the +.B RLIMIT_RTPRIO +soft limit is 0, then the only permitted changes are to lower the priority, +or to switch to a non-real-time policy. +.IP \[bu] +Subject to the same rules, +another unprivileged thread can also make these changes, +as long as the effective user ID of the thread making the change +matches the real or effective user ID of the target thread. +.IP \[bu] +Special rules apply for the +.B SCHED_IDLE +policy. +Before Linux 2.6.39, +an unprivileged thread operating under this policy cannot +change its policy, regardless of the value of its +.B RLIMIT_RTPRIO +resource limit. +Since Linux 2.6.39, +.\" commit c02aa73b1d18e43cfd79c2f193b225e84ca497c8 +an unprivileged thread can switch to either the +.B SCHED_BATCH +or the +.B SCHED_OTHER +policy so long as its nice value falls within the range permitted by its +.B RLIMIT_NICE +resource limit (see +.BR getrlimit (2)). +.P +Privileged +.RB ( CAP_SYS_NICE ) +threads ignore the +.B RLIMIT_RTPRIO +limit; as with older kernels, +they can make arbitrary changes to scheduling policy and priority. +See +.BR getrlimit (2) +for further information on +.BR RLIMIT_RTPRIO . +.SS Limiting the CPU usage of real-time and deadline processes +A nonblocking infinite loop in a thread scheduled under the +.BR SCHED_FIFO , +.BR SCHED_RR , +or +.B SCHED_DEADLINE +policy can potentially block all other threads from accessing +the CPU forever. +Before Linux 2.6.25, the only way of preventing a runaway real-time +process from freezing the system was to run (at the console) +a shell scheduled under a higher static priority than the tested application. +This allows an emergency kill of tested +real-time applications that do not block or terminate as expected. +.P +Since Linux 2.6.25, there are other techniques for dealing with runaway +real-time and deadline processes. +One of these is to use the +.B RLIMIT_RTTIME +resource limit to set a ceiling on the CPU time that +a real-time process may consume. +See +.BR getrlimit (2) +for details. +.P +Since Linux 2.6.25, Linux also provides two +.I /proc +files that can be used to reserve a certain amount of CPU time +to be used by non-real-time processes. +Reserving CPU time in this fashion allows some CPU time to be +allocated to (say) a root shell that can be used to kill a runaway process. +Both of these files specify time values in microseconds: +.TP +.I /proc/sys/kernel/sched_rt_period_us +This file specifies a scheduling period that is equivalent to +100% CPU bandwidth. +The value in this file can range from 1 to +.BR INT_MAX , +giving an operating range of 1 microsecond to around 35 minutes. +The default value in this file is 1,000,000 (1 second). +.TP +.I /proc/sys/kernel/sched_rt_runtime_us +The value in this file specifies how much of the "period" time +can be used by all real-time and deadline scheduled processes +on the system. +The value in this file can range from \-1 to +.BR INT_MAX \-1. +Specifying \-1 makes the run time the same as the period; +that is, no CPU time is set aside for non-real-time processes +(which was the behavior before Linux 2.6.25). +The default value in this file is 950,000 (0.95 seconds), +meaning that 5% of the CPU time is reserved for processes that +don't run under a real-time or deadline scheduling policy. +.SS Response time +A blocked high priority thread waiting for I/O has a certain +response time before it is scheduled again. +The device driver writer +can greatly reduce this response time by using a "slow interrupt" +interrupt handler. +.\" as described in +.\" .BR request_irq (9). +.SS Miscellaneous +Child processes inherit the scheduling policy and parameters across a +.BR fork (2). +The scheduling policy and parameters are preserved across +.BR execve (2). +.P +Memory locking is usually needed for real-time processes to avoid +paging delays; this can be done with +.BR mlock (2) +or +.BR mlockall (2). +.\" +.SS The autogroup feature +.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a +Since Linux 2.6.38, +the kernel provides a feature known as autogrouping to improve interactive +desktop performance in the face of multiprocess, CPU-intensive +workloads such as building the Linux kernel with large numbers of +parallel build processes (i.e., the +.BR make (1) +.B \-j +flag). +.P +This feature operates in conjunction with the +CFS scheduler and requires a kernel that is configured with +.BR CONFIG_SCHED_AUTOGROUP . +On a running system, this feature is enabled or disabled via the file +.IR /proc/sys/kernel/sched_autogroup_enabled ; +a value of 0 disables the feature, while a value of 1 enables it. +The default value in this file is 1, unless the kernel was booted with the +.I noautogroup +parameter. +.P +A new autogroup is created when a new session is created via +.BR setsid (2); +this happens, for example, when a new terminal window is started. +A new process created by +.BR fork (2) +inherits its parent's autogroup membership. +Thus, all of the processes in a session are members of the same autogroup. +An autogroup is automatically destroyed when the last process +in the group terminates. +.P +When autogrouping is enabled, all of the members of an autogroup +are placed in the same kernel scheduler "task group". +The CFS scheduler employs an algorithm that equalizes the +distribution of CPU cycles across task groups. +The benefits of this for interactive desktop performance +can be described via the following example. +.P +Suppose that there are two autogroups competing for the same CPU +(i.e., presume either a single CPU system or the use of +.BR taskset (1) +to confine all the processes to the same CPU on an SMP system). +The first group contains ten CPU-bound processes from +a kernel build started with +.IR "make\~\-j10" . +The other contains a single CPU-bound process: a video player. +The effect of autogrouping is that the two groups will +each receive half of the CPU cycles. +That is, the video player will receive 50% of the CPU cycles, +rather than just 9% of the cycles, +which would likely lead to degraded video playback. +The situation on an SMP system is more complex, +.\" Mike Galbraith, 25 Nov 2016: +.\" I'd say something more wishy-washy here, like cycles are +.\" distributed fairly across groups and leave it at that, as your +.\" detailed example is incorrect due to SMP fairness (which I don't +.\" like much because [very unlikely] worst case scenario +.\" renders a box sized group incapable of utilizing more that +.\" a single CPU total). For example, if a group of NR_CPUS +.\" size competes with a singleton, load balancing will try to give +.\" the singleton a full CPU of its very own. If groups intersect for +.\" whatever reason on say my quad lappy, distribution is 80/20 in +.\" favor of the singleton. +but the general effect is the same: +the scheduler distributes CPU cycles across task groups such that +an autogroup that contains a large number of CPU-bound processes +does not end up hogging CPU cycles at the expense of the other +jobs on the system. +.P +A process's autogroup (task group) membership can be viewed via the file +.IR /proc/ pid /autogroup : +.P +.in +4n +.EX +$ \fBcat /proc/1/autogroup\fP +/autogroup\-1 nice 0 +.EE +.in +.P +This file can also be used to modify the CPU bandwidth allocated +to an autogroup. +This is done by writing a number in the "nice" range to the file +to set the autogroup's nice value. +The allowed range is from +19 (low priority) to \-20 (high priority). +(Writing values outside of this range causes +.BR write (2) +to fail with the error +.BR EINVAL .) +.\" FIXME . +.\" Because of a bug introduced in Linux 4.7 +.\" (commit 2159197d66770ec01f75c93fb11dc66df81fd45b made changes +.\" that exposed the fact that autogroup didn't call scale_load()), +.\" it happened that *all* values in this range caused a task group +.\" to be further disfavored by the scheduler, with \-20 resulting +.\" in the scheduler mildly disfavoring the task group and +19 greatly +.\" disfavoring it. +.\" +.\" A patch was posted on 23 Nov 2016 +.\" ("sched/autogroup: Fix 64bit kernel nice adjustment"; +.\" check later to see in which kernel version it lands. +.P +The autogroup nice setting has the same meaning as the process nice value, +but applies to distribution of CPU cycles to the autogroup as a whole, +based on the relative nice values of other autogroups. +For a process inside an autogroup, the CPU cycles that it receives +will be a product of the autogroup's nice value +(compared to other autogroups) +and the process's nice value +(compared to other processes in the same autogroup. +.P +The use of the +.BR cgroups (7) +CPU controller to place processes in cgroups other than the +root CPU cgroup overrides the effect of autogrouping. +.P +The autogroup feature groups only processes scheduled under +non-real-time policies +.RB ( SCHED_OTHER , +.BR SCHED_BATCH , +and +.BR SCHED_IDLE ). +It does not group processes scheduled under real-time and +deadline policies. +Those processes are scheduled according to the rules described earlier. +.\" +.SS The nice value and group scheduling +When scheduling non-real-time processes (i.e., those scheduled under the +.BR SCHED_OTHER , +.BR SCHED_BATCH , +and +.B SCHED_IDLE +policies), the CFS scheduler employs a technique known as "group scheduling", +if the kernel was configured with the +.B CONFIG_FAIR_GROUP_SCHED +option (which is typical). +.P +Under group scheduling, threads are scheduled in "task groups". +Task groups have a hierarchical relationship, +rooted under the initial task group on the system, +known as the "root task group". +Task groups are formed in the following circumstances: +.IP \[bu] 3 +All of the threads in a CPU cgroup form a task group. +The parent of this task group is the task group of the +corresponding parent cgroup. +.IP \[bu] +If autogrouping is enabled, +then all of the threads that are (implicitly) placed in an autogroup +(i.e., the same session, as created by +.BR setsid (2)) +form a task group. +Each new autogroup is thus a separate task group. +The root task group is the parent of all such autogroups. +.IP \[bu] +If autogrouping is enabled, then the root task group consists of +all processes in the root CPU cgroup that were not +otherwise implicitly placed into a new autogroup. +.IP \[bu] +If autogrouping is disabled, then the root task group consists of +all processes in the root CPU cgroup. +.IP \[bu] +If group scheduling was disabled (i.e., the kernel was configured without +.BR CONFIG_FAIR_GROUP_SCHED ), +then all of the processes on the system are notionally placed +in a single task group. +.P +Under group scheduling, +a thread's nice value has an effect for scheduling decisions +.IR "only relative to other threads in the same task group" . +This has some surprising consequences in terms of the traditional semantics +of the nice value on UNIX systems. +In particular, if autogrouping +is enabled (which is the default in various distributions), then employing +.BR setpriority (2) +or +.BR nice (1) +on a process has an effect only for scheduling relative +to other processes executed in the same session +(typically: the same terminal window). +.P +Conversely, for two processes that are (for example) +the sole CPU-bound processes in different sessions +(e.g., different terminal windows, +each of whose jobs are tied to different autogroups), +.I modifying the nice value of the process in one of the sessions +.I has no effect +in terms of the scheduler's decisions relative to the +process in the other session. +.\" More succinctly: the nice(1) command is in many cases a no-op since +.\" Linux 2.6.38. +.\" +A possibly useful workaround here is to use a command such as +the following to modify the autogroup nice value for +.I all +of the processes in a terminal session: +.P +.in +4n +.EX +$ \fBecho 10 > /proc/self/autogroup\fP +.EE +.in +.SS Real-time features in the mainline Linux kernel +.\" FIXME . Probably this text will need some minor tweaking +.\" ask Carsten Emde about this. +Since Linux 2.6.18, Linux is gradually +becoming equipped with real-time capabilities, +most of which are derived from the former +.I realtime\-preempt +patch set. +Until the patches have been completely merged into the +mainline kernel, +they must be installed to achieve the best real-time performance. +These patches are named: +.P +.in +4n +.EX +patch\-\fIkernelversion\fP\-rt\fIpatchversion\fP +.EE +.in +.P +and can be downloaded from +.UR http://www.kernel.org\:/pub\:/linux\:/kernel\:/projects\:/rt/ +.UE . +.P +Without the patches and prior to their full inclusion into the mainline +kernel, the kernel configuration offers only the three preemption classes +.BR CONFIG_PREEMPT_NONE , +.BR CONFIG_PREEMPT_VOLUNTARY , +and +.B CONFIG_PREEMPT_DESKTOP +which respectively provide no, some, and considerable +reduction of the worst-case scheduling latency. +.P +With the patches applied or after their full inclusion into the mainline +kernel, the additional configuration item +.B CONFIG_PREEMPT_RT +becomes available. +If this is selected, Linux is transformed into a regular +real-time operating system. +The FIFO and RR scheduling policies are then used to run a thread +with true real-time priority and a minimum worst-case scheduling latency. +.SH NOTES +The +.BR cgroups (7) +CPU controller can be used to limit the CPU consumption of +groups of processes. +.P +Originally, Standard Linux was intended as a general-purpose operating +system being able to handle background processes, interactive +applications, and less demanding real-time applications (applications that +need to usually meet timing deadlines). +Although the Linux 2.6 +allowed for kernel preemption and the newly introduced O(1) scheduler +ensures that the time needed to schedule is fixed and deterministic +irrespective of the number of active tasks, true real-time computing +was not possible up to Linux 2.6.17. +.SH SEE ALSO +.ad l +.nh +.BR chcpu (1), +.BR chrt (1), +.BR lscpu (1), +.BR ps (1), +.BR taskset (1), +.BR top (1), +.BR getpriority (2), +.BR mlock (2), +.BR mlockall (2), +.BR munlock (2), +.BR munlockall (2), +.BR nice (2), +.BR sched_get_priority_max (2), +.BR sched_get_priority_min (2), +.BR sched_getaffinity (2), +.BR sched_getparam (2), +.BR sched_getscheduler (2), +.BR sched_rr_get_interval (2), +.BR sched_setaffinity (2), +.BR sched_setparam (2), +.BR sched_setscheduler (2), +.BR sched_yield (2), +.BR setpriority (2), +.BR pthread_getaffinity_np (3), +.BR pthread_getschedparam (3), +.BR pthread_setaffinity_np (3), +.BR sched_getcpu (3), +.BR capabilities (7), +.BR cpuset (7) +.ad +.P +.I Programming for the real world \- POSIX.4 +by Bill O.\& Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0. +.P +The Linux kernel source files +.IR \%Documentation/\:scheduler/\:sched\-deadline\:.txt , +.IR \%Documentation/\:scheduler/\:sched\-rt\-group\:.txt , +.IR \%Documentation/\:scheduler/\:sched\-design\-CFS\:.txt , +and +.I \%Documentation/\:scheduler/\:sched\-nice\-design\:.txt diff --git a/man/man7/sem_overview.7 b/man/man7/sem_overview.7 new file mode 100644 index 0000000..01d918c --- /dev/null +++ b/man/man7/sem_overview.7 @@ -0,0 +1,139 @@ +.\" Copyright (C) 2006 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sem_overview 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sem_overview \- overview of POSIX semaphores +.SH DESCRIPTION +POSIX semaphores allow processes and threads to synchronize their actions. +.P +A semaphore is an integer whose value is never allowed to fall below zero. +Two operations can be performed on semaphores: +increment the semaphore value by one +.RB ( sem_post (3)); +and decrement the semaphore value by one +.RB ( sem_wait (3)). +If the value of a semaphore is currently zero, then a +.BR sem_wait (3) +operation will block until the value becomes greater than zero. +.P +POSIX semaphores come in two forms: named semaphores and +unnamed semaphores. +.TP +.B Named semaphores +A named semaphore is identified by a name of the form +.IR /somename ; +that is, a null-terminated string of up to +.BI NAME_MAX \-4 +(i.e., 251) characters consisting of an initial slash, +.\" glibc allows the initial slash to be omitted, and makes +.\" multiple initial slashes equivalent to a single slash. +.\" This differs from the implementation of POSIX message queues. +followed by one or more characters, none of which are slashes. +.\" glibc allows subdirectory components in the name, in which +.\" case the subdirectory tree must exist under /dev/shm, and +.\" the fist subdirectory component must exist as the name +.\" sem.name, and all of the subdirectory components must allow the +.\" required permissions if a user wants to create a semaphore +.\" object in a subdirectory. +Two processes can operate on the same named semaphore by passing +the same name to +.BR sem_open (3). +.IP +The +.BR sem_open (3) +function creates a new named semaphore or opens an existing +named semaphore. +After the semaphore has been opened, it can be operated on using +.BR sem_post (3) +and +.BR sem_wait (3). +When a process has finished using the semaphore, it can use +.BR sem_close (3) +to close the semaphore. +When all processes have finished using the semaphore, +it can be removed from the system using +.BR sem_unlink (3). +.TP +.B Unnamed semaphores (memory-based semaphores) +An unnamed semaphore does not have a name. +Instead the semaphore is placed in a region of memory that +is shared between multiple threads (a +.IR "thread-shared semaphore" ) +or processes (a +.IR "process-shared semaphore" ). +A thread-shared semaphore is placed in an area of memory shared +between the threads of a process, for example, a global variable. +A process-shared semaphore must be placed in a shared memory region +(e.g., a System V shared memory segment created using +.BR shmget (2), +or a POSIX shared memory object built created using +.BR shm_open (3)). +.IP +Before being used, an unnamed semaphore must be initialized using +.BR sem_init (3). +It can then be operated on using +.BR sem_post (3) +and +.BR sem_wait (3). +When the semaphore is no longer required, +and before the memory in which it is located is deallocated, +the semaphore should be destroyed using +.BR sem_destroy (3). +.P +The remainder of this section describes some specific details +of the Linux implementation of POSIX semaphores. +.SS Versions +Before Linux 2.6, Linux supported only unnamed, +thread-shared semaphores. +On a system with Linux 2.6 and a glibc that provides the NPTL +threading implementation, +a complete implementation of POSIX semaphores is provided. +.SS Persistence +POSIX named semaphores have kernel persistence: +if not removed by +.BR sem_unlink (3), +a semaphore will exist until the system is shut down. +.SS Linking +Programs using the POSIX semaphores API must be compiled with +.I cc \-pthread +to link against the real-time library, +.IR librt . +.SS Accessing named semaphores via the filesystem +On Linux, named semaphores are created in a virtual filesystem, +normally mounted under +.IR /dev/shm , +with names of the form +.IR \fBsem.\fPsomename . +(This is the reason that semaphore names are limited to +.BI NAME_MAX \-4 +rather than +.B NAME_MAX +characters.) +.P +Since Linux 2.6.19, ACLs can be placed on files under this directory, +to control object permissions on a per-user and per-group basis. +.SH NOTES +System V semaphores +.RB ( semget (2), +.BR semop (2), +etc.) are an older semaphore API. +POSIX semaphores provide a simpler, and better designed interface than +System V semaphores; +on the other hand POSIX semaphores are less widely available +(especially on older systems) than System V semaphores. +.SH EXAMPLES +An example of the use of various POSIX semaphore functions is shown in +.BR sem_wait (3). +.SH SEE ALSO +.BR sem_close (3), +.BR sem_destroy (3), +.BR sem_getvalue (3), +.BR sem_init (3), +.BR sem_open (3), +.BR sem_post (3), +.BR sem_unlink (3), +.BR sem_wait (3), +.BR pthreads (7), +.BR shm_overview (7) diff --git a/man/man7/session-keyring.7 b/man/man7/session-keyring.7 new file mode 100644 index 0000000..fcaf689 --- /dev/null +++ b/man/man7/session-keyring.7 @@ -0,0 +1,113 @@ +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH session-keyring 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +session-keyring \- session shared process keyring +.SH DESCRIPTION +The session keyring is a keyring used to anchor keys on behalf of a process. +It is typically created by +.BR pam_keyinit (8) +when a user logs in and a link will be added that refers to the +.BR user\-keyring (7). +Optionally, +.BR PAM (7) +may revoke the session keyring on logout. +(In typical configurations, PAM does do this revocation.) +The session keyring has the name (description) +.IR _ses . +.P +A special serial number value, +.BR KEY_SPEC_SESSION_KEYRING , +is defined that can be used in lieu of the actual serial number of +the calling process's session keyring. +.P +From the +.BR keyctl (1) +utility, '\fB@s\fP' can be used instead of a numeric key ID in +much the same way. +.P +A process's session keyring is inherited across +.BR clone (2), +.BR fork (2), +and +.BR vfork (2). +The session keyring +is preserved across +.BR execve (2), +even when the executable is set-user-ID or set-group-ID or has capabilities. +The session keyring is destroyed when the last process that +refers to it exits. +.P +If a process doesn't have a session keyring when it is accessed, then, +under certain circumstances, the +.BR user\-session\-keyring (7) +will be attached as the session keyring +and under others a new session keyring will be created. +(See +.BR user\-session\-keyring (7) +for further details.) +.SS Special operations +The +.I keyutils +library provides the following special operations for manipulating +session keyrings: +.TP +.BR keyctl_join_session_keyring (3) +This operation allows the caller to change the session keyring +that it subscribes to. +The caller can join an existing keyring with a specified name (description), +create a new keyring with a given name, +or ask the kernel to create a new "anonymous" +session keyring with the name "_ses". +(This function is an interface to the +.BR keyctl (2) +.B KEYCTL_JOIN_SESSION_KEYRING +operation.) +.TP +.BR keyctl_session_to_parent (3) +This operation allows the caller to make the parent process's +session keyring to the same as its own. +For this to succeed, the parent process must have +identical security attributes and must be single threaded. +(This function is an interface to the +.BR keyctl (2) +.B KEYCTL_SESSION_TO_PARENT +operation.) +.P +These operations are also exposed through the +.BR keyctl (1) +utility as: +.P +.in +4n +.EX +keyctl session +keyctl session \- [ ...] +keyctl session [ ...] +.EE +.in +.P +and: +.P +.in +4n +.EX +keyctl new_session +.EE +.in +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyctl_join_session_keyring (3), +.BR keyctl_session_to_parent (3), +.BR keyrings (7), +.BR PAM (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7), +.BR pam_keyinit (8) diff --git a/man/man7/shm_overview.7 b/man/man7/shm_overview.7 new file mode 100644 index 0000000..8205f4b --- /dev/null +++ b/man/man7/shm_overview.7 @@ -0,0 +1,104 @@ +.\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH shm_overview 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +shm_overview \- overview of POSIX shared memory +.SH DESCRIPTION +The POSIX shared memory API allows processes to communicate information +by sharing a region of memory. +.P +The interfaces employed in the API are: +.TP 15 +.BR shm_open (3) +Create and open a new object, or open an existing object. +This is analogous to +.BR open (2). +The call returns a file descriptor for use by the other +interfaces listed below. +.TP +.BR ftruncate (2) +Set the size of the shared memory object. +(A newly created shared memory object has a length of zero.) +.TP +.BR mmap (2) +Map the shared memory object into the virtual address space +of the calling process. +.TP +.BR munmap (2) +Unmap the shared memory object from the virtual address space +of the calling process. +.TP +.BR shm_unlink (3) +Remove a shared memory object name. +.TP +.BR close (2) +Close the file descriptor allocated by +.BR shm_open (3) +when it is no longer needed. +.TP +.BR fstat (2) +Obtain a +.I stat +structure that describes the shared memory object. +Among the information returned by this call are the object's +size +.RI ( st_size ), +permissions +.RI ( st_mode ), +owner +.RI ( st_uid ), +and group +.RI ( st_gid ). +.TP +.BR fchown (2) +To change the ownership of a shared memory object. +.TP +.BR fchmod (2) +To change the permissions of a shared memory object. +.SS Versions +POSIX shared memory is supported since Linux 2.4 and glibc 2.2. +.SS Persistence +POSIX shared memory objects have kernel persistence: +a shared memory object will exist until the system is shut down, +or until all processes have unmapped the object and it has been deleted with +.BR shm_unlink (3) +.SS Linking +Programs using the POSIX shared memory API must be compiled with +.I cc \-lrt +to link against the real-time library, +.IR librt . +.SS Accessing shared memory objects via the filesystem +On Linux, shared memory objects are created in a +.RB ( tmpfs (5)) +virtual filesystem, normally mounted under +.IR /dev/shm . +Since Linux 2.6.19, Linux supports the use of access control lists (ACLs) +to control the permissions of objects in the virtual filesystem. +.SH NOTES +Typically, processes must synchronize their access to a shared +memory object, using, for example, POSIX semaphores. +.P +System V shared memory +.RB ( shmget (2), +.BR shmop (2), +etc.) is an older shared memory API. +POSIX shared memory provides a simpler, and better designed interface; +on the other hand POSIX shared memory is somewhat less widely available +(especially on older systems) than System V shared memory. +.SH SEE ALSO +.BR fchmod (2), +.BR fchown (2), +.BR fstat (2), +.BR ftruncate (2), +.BR memfd_create (2), +.BR mmap (2), +.BR mprotect (2), +.BR munmap (2), +.BR shmget (2), +.BR shmop (2), +.BR shm_open (3), +.BR shm_unlink (3), +.BR sem_overview (7) diff --git a/man/man7/sigevent.7 b/man/man7/sigevent.7 new file mode 100644 index 0000000..b43f1bb --- /dev/null +++ b/man/man7/sigevent.7 @@ -0,0 +1 @@ +.so man3type/sigevent.3type diff --git a/man/man7/signal-safety.7 b/man/man7/signal-safety.7 new file mode 100644 index 0000000..dfb3ba5 --- /dev/null +++ b/man/man7/signal-safety.7 @@ -0,0 +1,341 @@ +'\" t +.\" Copyright (c) 2016 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH signal-safety 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +signal-safety \- async-signal-safe functions +.SH DESCRIPTION +An +.I async-signal-safe +function is one that can be safely called from within a signal handler. +Many functions are +.I not +async-signal-safe. +In particular, +nonreentrant functions are generally unsafe to call from a signal handler. +.P +The kinds of issues that render a function +unsafe can be quickly understood when one considers +the implementation of the +.I stdio +library, all of whose functions are not async-signal-safe. +.P +When performing buffered I/O on a file, the +.I stdio +functions must maintain a statically allocated data buffer +along with associated counters and indexes (or pointers) +that record the amount of data and the current position in the buffer. +Suppose that the main program is in the middle of a call to a +.I stdio +function such as +.BR printf (3) +where the buffer and associated variables have been partially updated. +If, at that moment, +the program is interrupted by a signal handler that also calls +.BR printf (3), +then the second call to +.BR printf (3) +will operate on inconsistent data, with unpredictable results. +.P +To avoid problems with unsafe functions, there are two possible choices: +.IP (a) 5 +Ensure that +(1) the signal handler calls only async-signal-safe functions, +and +(2) the signal handler itself is reentrant +with respect to global variables in the main program. +.IP (b) +Block signal delivery in the main program when calling functions +that are unsafe or operating on global data that is also accessed +by the signal handler. +.P +Generally, the second choice is difficult in programs of any complexity, +so the first choice is taken. +.P +POSIX.1 specifies a set of functions that an implementation +must make async-signal-safe. +(An implementation may provide safe implementations of additional functions, +but this is not required by the standard and other implementations +may not provide the same guarantees.) +.P +In general, a function is async-signal-safe either because it is reentrant +or because it is atomic with respect to signals +(i.e., its execution can't be interrupted by a signal handler). +.P +The set of functions required to be async-signal-safe by POSIX.1 +is shown in the following table. +The functions not otherwise noted were required to be async-signal-safe +in POSIX.1-2001; +the table details changes in the subsequent standards. +.P +.TS +lb lb +l l. +Function Notes +\fBabort\fP(3) Added in POSIX.1-2001 TC1 +\fBaccept\fP(2) +\fBaccess\fP(2) +\fBaio_error\fP(3) +\fBaio_return\fP(3) +\fBaio_suspend\fP(3) See notes below +\fBalarm\fP(2) +\fBbind\fP(2) +\fBcfgetispeed\fP(3) +\fBcfgetospeed\fP(3) +\fBcfsetispeed\fP(3) +\fBcfsetospeed\fP(3) +\fBchdir\fP(2) +\fBchmod\fP(2) +\fBchown\fP(2) +\fBclock_gettime\fP(2) +\fBclose\fP(2) +\fBconnect\fP(2) +\fBcreat\fP(2) +\fBdup\fP(2) +\fBdup2\fP(2) +\fBexecl\fP(3) T{ +Added in POSIX.1-2008; see notes below +T} +\fBexecle\fP(3) See notes below +\fBexecv\fP(3) Added in POSIX.1-2008 +\fBexecve\fP(2) +\fB_exit\fP(2) +\fB_Exit\fP(2) +\fBfaccessat\fP(2) Added in POSIX.1-2008 +\fBfchdir\fP(2) Added in POSIX.1-2008 TC1 +\fBfchmod\fP(2) +\fBfchmodat\fP(2) Added in POSIX.1-2008 +\fBfchown\fP(2) +\fBfchownat\fP(2) Added in POSIX.1-2008 +\fBfcntl\fP(2) +\fBfdatasync\fP(2) +\fBfexecve\fP(3) Added in POSIX.1-2008 +\fBffs\fP(3) Added in POSIX.1-2008 TC2 +\fBfork\fP(2) See notes below +\fBfstat\fP(2) +\fBfstatat\fP(2) Added in POSIX.1-2008 +\fBfsync\fP(2) +\fBftruncate\fP(2) +\fBfutimens\fP(3) Added in POSIX.1-2008 +\fBgetegid\fP(2) +\fBgeteuid\fP(2) +\fBgetgid\fP(2) +\fBgetgroups\fP(2) +\fBgetpeername\fP(2) +\fBgetpgrp\fP(2) +\fBgetpid\fP(2) +\fBgetppid\fP(2) +\fBgetsockname\fP(2) +\fBgetsockopt\fP(2) +\fBgetuid\fP(2) +\fBhtonl\fP(3) Added in POSIX.1-2008 TC2 +\fBhtons\fP(3) Added in POSIX.1-2008 TC2 +\fBkill\fP(2) +\fBlink\fP(2) +\fBlinkat\fP(2) Added in POSIX.1-2008 +\fBlisten\fP(2) +\fBlongjmp\fP(3) T{ +Added in POSIX.1-2008 TC2; see notes below +T} +\fBlseek\fP(2) +\fBlstat\fP(2) +\fBmemccpy\fP(3) Added in POSIX.1-2008 TC2 +\fBmemchr\fP(3) Added in POSIX.1-2008 TC2 +\fBmemcmp\fP(3) Added in POSIX.1-2008 TC2 +\fBmemcpy\fP(3) Added in POSIX.1-2008 TC2 +\fBmemmove\fP(3) Added in POSIX.1-2008 TC2 +\fBmemset\fP(3) Added in POSIX.1-2008 TC2 +\fBmkdir\fP(2) +\fBmkdirat\fP(2) Added in POSIX.1-2008 +\fBmkfifo\fP(3) +\fBmkfifoat\fP(3) Added in POSIX.1-2008 +\fBmknod\fP(2) Added in POSIX.1-2008 +\fBmknodat\fP(2) Added in POSIX.1-2008 +\fBntohl\fP(3) Added in POSIX.1-2008 TC2 +\fBntohs\fP(3) Added in POSIX.1-2008 TC2 +\fBopen\fP(2) +\fBopenat\fP(2) Added in POSIX.1-2008 +\fBpause\fP(2) +\fBpipe\fP(2) +\fBpoll\fP(2) +\fBposix_trace_event\fP(3) +\fBpselect\fP(2) +\fBpthread_kill\fP(3) Added in POSIX.1-2008 TC1 +\fBpthread_self\fP(3) Added in POSIX.1-2008 TC1 +\fBpthread_sigmask\fP(3) Added in POSIX.1-2008 TC1 +\fBraise\fP(3) +\fBread\fP(2) +\fBreadlink\fP(2) +\fBreadlinkat\fP(2) Added in POSIX.1-2008 +\fBrecv\fP(2) +\fBrecvfrom\fP(2) +\fBrecvmsg\fP(2) +\fBrename\fP(2) +\fBrenameat\fP(2) Added in POSIX.1-2008 +\fBrmdir\fP(2) +\fBselect\fP(2) +\fBsem_post\fP(3) +\fBsend\fP(2) +\fBsendmsg\fP(2) +\fBsendto\fP(2) +\fBsetgid\fP(2) +\fBsetpgid\fP(2) +\fBsetsid\fP(2) +\fBsetsockopt\fP(2) +\fBsetuid\fP(2) +\fBshutdown\fP(2) +\fBsigaction\fP(2) +\fBsigaddset\fP(3) +\fBsigdelset\fP(3) +\fBsigemptyset\fP(3) +\fBsigfillset\fP(3) +\fBsigismember\fP(3) +\fBsiglongjmp\fP(3) T{ +Added in POSIX.1-2008 TC2; see notes below +T} +\fBsignal\fP(2) +\fBsigpause\fP(3) +\fBsigpending\fP(2) +\fBsigprocmask\fP(2) +\fBsigqueue\fP(2) +\fBsigset\fP(3) +\fBsigsuspend\fP(2) +\fBsleep\fP(3) +\fBsockatmark\fP(3) Added in POSIX.1-2001 TC2 +\fBsocket\fP(2) +\fBsocketpair\fP(2) +\fBstat\fP(2) +\fBstpcpy\fP(3) Added in POSIX.1-2008 TC2 +\fBstpncpy\fP(3) Added in POSIX.1-2008 TC2 +\fBstrcat\fP(3) Added in POSIX.1-2008 TC2 +\fBstrchr\fP(3) Added in POSIX.1-2008 TC2 +\fBstrcmp\fP(3) Added in POSIX.1-2008 TC2 +\fBstrcpy\fP(3) Added in POSIX.1-2008 TC2 +\fBstrcspn\fP(3) Added in POSIX.1-2008 TC2 +\fBstrlen\fP(3) Added in POSIX.1-2008 TC2 +\fBstrncat\fP(3) Added in POSIX.1-2008 TC2 +\fBstrncmp\fP(3) Added in POSIX.1-2008 TC2 +\fBstrncpy\fP(3) Added in POSIX.1-2008 TC2 +\fBstrnlen\fP(3) Added in POSIX.1-2008 TC2 +\fBstrpbrk\fP(3) Added in POSIX.1-2008 TC2 +\fBstrrchr\fP(3) Added in POSIX.1-2008 TC2 +\fBstrspn\fP(3) Added in POSIX.1-2008 TC2 +\fBstrstr\fP(3) Added in POSIX.1-2008 TC2 +\fBstrtok_r\fP(3) Added in POSIX.1-2008 TC2 +\fBsymlink\fP(2) +\fBsymlinkat\fP(2) Added in POSIX.1-2008 +\fBtcdrain\fP(3) +\fBtcflow\fP(3) +\fBtcflush\fP(3) +\fBtcgetattr\fP(3) +\fBtcgetpgrp\fP(3) +\fBtcsendbreak\fP(3) +\fBtcsetattr\fP(3) +\fBtcsetpgrp\fP(3) +\fBtime\fP(2) +\fBtimer_getoverrun\fP(2) +\fBtimer_gettime\fP(2) +\fBtimer_settime\fP(2) +\fBtimes\fP(2) +\fBumask\fP(2) +\fBuname\fP(2) +\fBunlink\fP(2) +\fBunlinkat\fP(2) Added in POSIX.1-2008 +\fButime\fP(2) +\fButimensat\fP(2) Added in POSIX.1-2008 +\fButimes\fP(2) Added in POSIX.1-2008 +\fBwait\fP(2) +\fBwaitpid\fP(2) +\fBwcpcpy\fP(3) Added in POSIX.1-2008 TC2 +\fBwcpncpy\fP(3) Added in POSIX.1-2008 TC2 +\fBwcscat\fP(3) Added in POSIX.1-2008 TC2 +\fBwcschr\fP(3) Added in POSIX.1-2008 TC2 +\fBwcscmp\fP(3) Added in POSIX.1-2008 TC2 +\fBwcscpy\fP(3) Added in POSIX.1-2008 TC2 +\fBwcscspn\fP(3) Added in POSIX.1-2008 TC2 +\fBwcslen\fP(3) Added in POSIX.1-2008 TC2 +\fBwcsncat\fP(3) Added in POSIX.1-2008 TC2 +\fBwcsncmp\fP(3) Added in POSIX.1-2008 TC2 +\fBwcsncpy\fP(3) Added in POSIX.1-2008 TC2 +\fBwcsnlen\fP(3) Added in POSIX.1-2008 TC2 +\fBwcspbrk\fP(3) Added in POSIX.1-2008 TC2 +\fBwcsrchr\fP(3) Added in POSIX.1-2008 TC2 +\fBwcsspn\fP(3) Added in POSIX.1-2008 TC2 +\fBwcsstr\fP(3) Added in POSIX.1-2008 TC2 +\fBwcstok\fP(3) Added in POSIX.1-2008 TC2 +\fBwmemchr\fP(3) Added in POSIX.1-2008 TC2 +\fBwmemcmp\fP(3) Added in POSIX.1-2008 TC2 +\fBwmemcpy\fP(3) Added in POSIX.1-2008 TC2 +\fBwmemmove\fP(3) Added in POSIX.1-2008 TC2 +\fBwmemset\fP(3) Added in POSIX.1-2008 TC2 +\fBwrite\fP(2) +.TE +.P +Notes: +.IP \[bu] 3 +POSIX.1-2001 and POSIX.1-2001 TC2 required the functions +.BR fpathconf (3), +.BR pathconf (3), +and +.BR sysconf (3) +to be async-signal-safe, but this requirement was removed in POSIX.1-2008. +.IP \[bu] +If a signal handler interrupts the execution of an unsafe function, +and the handler terminates via a call to +.BR longjmp (3) +or +.BR siglongjmp (3) +and the program subsequently calls an unsafe function, +then the behavior of the program is undefined. +.IP \[bu] +POSIX.1-2001 TC1 clarified +that if an application calls +.BR fork (2) +from a signal handler and any of the fork handlers registered by +.BR pthread_atfork (3) +calls a function that is not async-signal-safe, the behavior is undefined. +A future revision of the standard +.\" http://www.opengroup.org/austin/aardvark/latest/xshbug3.txt +is likely to remove +.BR fork (2) +from the list of async-signal-safe functions. +.\" +.IP \[bu] +Asynchronous signal handlers that call functions which are cancelation +points and nest over regions of deferred cancelation may trigger +cancelation whose behavior is as if asynchronous cancelation had +occurred and may cause application state to become inconsistent. +.\" +.SS errno +Fetching and setting the value of +.I errno +is async-signal-safe provided that the signal handler saves +.I errno +on entry and restores its value before returning. +.\" +.SS Deviations in the GNU C library +The following known deviations from the standard occur in +the GNU C library: +.IP \[bu] 3 +Before glibc 2.24, +.BR execl (3) +and +.BR execle (3) +employed +.BR realloc (3) +internally and were consequently not async-signal-safe. +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534 +This was fixed in glibc 2.24. +.IP \[bu] +.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=13172 +The glibc implementation of +.BR aio_suspend (3) +is not async-signal-safe because it uses +.BR pthread_mutex_lock (3) +internally. +.SH SEE ALSO +.BR sigaction (2), +.BR signal (7), +.BR standards (7) diff --git a/man/man7/signal.7 b/man/man7/signal.7 new file mode 100644 index 0000000..7409507 --- /dev/null +++ b/man/man7/signal.7 @@ -0,0 +1,1019 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright (c) 2002, 2006, 2020 by Michael Kerrisk +.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 17:34:08 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Sun Jan 7 01:41:27 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sun Apr 14 12:02:29 1996 by Andries Brouwer (aeb@cwi.nl) +.\" Modified Sat Nov 13 16:28:23 1999 by Andries Brouwer (aeb@cwi.nl) +.\" Modified 10 Apr 2002, by Michael Kerrisk +.\" Modified 7 Jun 2002, by Michael Kerrisk +.\" Added information on real-time signals +.\" Modified 13 Jun 2002, by Michael Kerrisk +.\" Noted that SIGSTKFLT is in fact unused +.\" 2004-12-03, Modified mtk, added notes on RLIMIT_SIGPENDING +.\" 2006-04-24, mtk, Added text on changing signal dispositions, +.\" signal mask, and pending signals. +.\" 2008-07-04, mtk: +.\" Added section on system call restarting (SA_RESTART) +.\" Added section on stop/cont signals interrupting syscalls. +.\" 2008-10-05, mtk: various additions +.\" +.TH signal 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +signal \- overview of signals +.SH DESCRIPTION +Linux supports both POSIX reliable signals (hereinafter +"standard signals") and POSIX real-time signals. +.SS Signal dispositions +Each signal has a current +.IR disposition , +which determines how the process behaves when it is delivered +the signal. +.P +The entries in the "Action" column of the table below specify +the default disposition for each signal, as follows: +.TP +Term +Default action is to terminate the process. +.TP +Ign +Default action is to ignore the signal. +.TP +Core +Default action is to terminate the process and dump core (see +.BR core (5)). +.TP +Stop +Default action is to stop the process. +.TP +Cont +Default action is to continue the process if it is currently stopped. +.P +A process can change the disposition of a signal using +.BR sigaction (2) +or +.BR signal (2). +(The latter is less portable when establishing a signal handler; +see +.BR signal (2) +for details.) +Using these system calls, a process can elect one of the +following behaviors to occur on delivery of the signal: +perform the default action; ignore the signal; +or catch the signal with a +.IR "signal handler" , +a programmer-defined function that is automatically invoked +when the signal is delivered. +.P +By default, a signal handler is invoked on the +normal process stack. +It is possible to arrange that the signal handler +uses an alternate stack; see +.BR sigaltstack (2) +for a discussion of how to do this and when it might be useful. +.P +The signal disposition is a per-process attribute: +in a multithreaded application, the disposition of a +particular signal is the same for all threads. +.P +A child created via +.BR fork (2) +inherits a copy of its parent's signal dispositions. +During an +.BR execve (2), +the dispositions of handled signals are reset to the default; +the dispositions of ignored signals are left unchanged. +.SS Sending a signal +The following system calls and library functions allow +the caller to send a signal: +.TP +.BR raise (3) +Sends a signal to the calling thread. +.TP +.BR kill (2) +Sends a signal to a specified process, +to all members of a specified process group, +or to all processes on the system. +.TP +.BR pidfd_send_signal (2) +Sends a signal to a process identified by a PID file descriptor. +.TP +.BR killpg (3) +Sends a signal to all of the members of a specified process group. +.TP +.BR pthread_kill (3) +Sends a signal to a specified POSIX thread in the same process as +the caller. +.TP +.BR tgkill (2) +Sends a signal to a specified thread within a specific process. +(This is the system call used to implement +.BR pthread_kill (3).) +.TP +.BR sigqueue (3) +Sends a real-time signal with accompanying data to a specified process. +.SS Waiting for a signal to be caught +The following system calls suspend execution of the calling +thread until a signal is caught +(or an unhandled signal terminates the process): +.TP +.BR pause (2) +Suspends execution until any signal is caught. +.TP +.BR sigsuspend (2) +Temporarily changes the signal mask (see below) and suspends +execution until one of the unmasked signals is caught. +.\" +.SS Synchronously accepting a signal +Rather than asynchronously catching a signal via a signal handler, +it is possible to synchronously accept the signal, that is, +to block execution until the signal is delivered, +at which point the kernel returns information about the +signal to the caller. +There are two general ways to do this: +.IP \[bu] 3 +.BR sigwaitinfo (2), +.BR sigtimedwait (2), +and +.BR sigwait (3) +suspend execution until one of the signals in a specified +set is delivered. +Each of these calls returns information about the delivered signal. +.IP \[bu] +.BR signalfd (2) +returns a file descriptor that can be used to read information +about signals that are delivered to the caller. +Each +.BR read (2) +from this file descriptor blocks until one of the signals +in the set specified in the +.BR signalfd (2) +call is delivered to the caller. +The buffer returned by +.BR read (2) +contains a structure describing the signal. +.SS Signal mask and pending signals +A signal may be +.IR blocked , +which means that it will not be delivered until it is later unblocked. +Between the time when it is generated and when it is delivered +a signal is said to be +.IR pending . +.P +Each thread in a process has an independent +.IR "signal mask" , +which indicates the set of signals that the thread is currently blocking. +A thread can manipulate its signal mask using +.BR pthread_sigmask (3). +In a traditional single-threaded application, +.BR sigprocmask (2) +can be used to manipulate the signal mask. +.P +A child created via +.BR fork (2) +inherits a copy of its parent's signal mask; +the signal mask is preserved across +.BR execve (2). +.P +A signal may be process-directed or thread-directed. +A process-directed signal is one that is targeted at (and thus pending for) +the process as a whole. +A signal may be process-directed +because it was generated by the kernel for reasons +other than a hardware exception, or because it was sent using +.BR kill (2) +or +.BR sigqueue (3). +A thread-directed signal is one that is targeted at a specific thread. +A signal may be thread-directed because it was generated as a consequence +of executing a specific machine-language instruction +that triggered a hardware exception (e.g., +.B SIGSEGV +for an invalid memory access, or +.B SIGFPE +for a math error), or because it was +targeted at a specific thread using +interfaces such as +.BR tgkill (2) +or +.BR pthread_kill (3). +.P +A process-directed signal may be delivered to any one of the +threads that does not currently have the signal blocked. +.\" Joseph C. Sible notes: +.\" On Linux, if the main thread has the signal unblocked, then the kernel +.\" will always deliver the signal there, citing this kernel code +.\" +.\" Per this comment in kernel/signal.c since time immemorial: +.\" +.\" /* +.\" * Now find a thread we can wake up to take the signal off the queue. +.\" * +.\" * If the main thread wants the signal, it gets first crack. +.\" * Probably the least surprising to the average bear. +.\" */ +.\" +.\" But this does not mean the signal will be delivered only in the +.\" main thread, since if a handler is already executing in the main thread +.\" (and thus the signal is blocked in that thread), then a further +.\" might be delivered in a different thread. +.\" +If more than one of the threads has the signal unblocked, then the +kernel chooses an arbitrary thread to which to deliver the signal. +.P +A thread can obtain the set of signals that it currently has pending +using +.BR sigpending (2). +This set will consist of the union of the set of pending +process-directed signals and the set of signals pending for +the calling thread. +.P +A child created via +.BR fork (2) +initially has an empty pending signal set; +the pending signal set is preserved across an +.BR execve (2). +.\" +.SS Execution of signal handlers +Whenever there is a transition from kernel-mode to user-mode execution +(e.g., on return from a system call or scheduling of a thread onto the CPU), +the kernel checks whether there is a pending unblocked signal +for which the process has established a signal handler. +If there is such a pending signal, the following steps occur: +.IP (1) 5 +The kernel performs the necessary preparatory steps for execution of +the signal handler: +.RS +.IP (1.1) 7 +The signal is removed from the set of pending signals. +.IP (1.2) +If the signal handler was installed by a call to +.BR sigaction (2) +that specified the +.B SA_ONSTACK +flag and the thread has defined an alternate signal stack (using +.BR sigaltstack (2)), +then that stack is installed. +.IP (1.3) +Various pieces of signal-related context are saved +into a special frame that is created on the stack. +The saved information includes: +.RS +.IP \[bu] 3 +the program counter register +(i.e., the address of the next instruction in the main program that +should be executed when the signal handler returns); +.IP \[bu] +architecture-specific register state required for resuming the +interrupted program; +.IP \[bu] +the thread's current signal mask; +.IP \[bu] +the thread's alternate signal stack settings. +.RE +.IP +(If the signal handler was installed using the +.BR sigaction (2) +.B SA_SIGINFO +flag, then the above information is accessible via the +.I ucontext_t +object that is pointed to by the third argument of the signal handler.) +.IP (1.4) +Any signals specified in +.I act\->sa_mask +when registering the handler with +.BR sigprocmask (2) +are added to the thread's signal mask. +The signal being delivered is also +added to the signal mask, unless +.B SA_NODEFER +was specified when registering the handler. +These signals are thus blocked while the handler executes. +.RE +.IP (2) +The kernel constructs a frame for the signal handler on the stack. +The kernel sets the program counter for the thread to point to the first +instruction of the signal handler function, +and configures the return address for that function to point to a piece +of user-space code known as the signal trampoline (described in +.BR sigreturn (2)). +.IP (3) +The kernel passes control back to user-space, where execution +commences at the start of the signal handler function. +.IP (4) +When the signal handler returns, control passes to the signal trampoline code. +.IP (5) +The signal trampoline calls +.BR sigreturn (2), +a system call that uses the information in the stack frame created in step 1 +to restore the thread to its state before the signal handler was +called. +The thread's signal mask and alternate signal stack settings +are restored as part of this procedure. +Upon completion of the call to +.BR sigreturn (2), +the kernel transfers control back to user space, +and the thread recommences execution at the point where it was +interrupted by the signal handler. +.P +Note that if the signal handler does not return +(e.g., control is transferred out of the handler using +.BR siglongjmp (3), +or the handler executes a new program with +.BR execve (2)), +then the final step is not performed. +In particular, in such scenarios it is the programmer's responsibility +to restore the state of the signal mask (using +.BR sigprocmask (2)), +if it is desired to unblock the signals that were blocked on entry +to the signal handler. +(Note that +.BR siglongjmp (3) +may or may not restore the signal mask, depending on the +.I savesigs +value that was specified in the corresponding call to +.BR sigsetjmp (3).) +.P +From the kernel's point of view, +execution of the signal handler code is exactly the same as the execution +of any other user-space code. +That is to say, the kernel does not record any special state information +indicating that the thread is currently executing inside a signal handler. +All necessary state information is maintained in user-space registers +and the user-space stack. +The depth to which nested signal handlers may be invoked is thus +limited only by the user-space stack (and sensible software design!). +.\" +.SS Standard signals +Linux supports the standard signals listed below. +The second column of the table indicates which standard (if any) +specified the signal: "P1990" indicates that the signal is described +in the original POSIX.1-1990 standard; +"P2001" indicates that the signal was added in SUSv2 and POSIX.1-2001. +.TS +l c c l +____ +lB c c l. +Signal Standard Action Comment +SIGABRT P1990 Core Abort signal from \fBabort\fP(3) +SIGALRM P1990 Term Timer signal from \fBalarm\fP(2) +SIGBUS P2001 Core Bus error (bad memory access) +SIGCHLD P1990 Ign Child stopped or terminated +SIGCLD \- Ign A synonym for \fBSIGCHLD\fP +SIGCONT P1990 Cont Continue if stopped +SIGEMT \- Term Emulator trap +SIGFPE P1990 Core Floating-point exception +SIGHUP P1990 Term Hangup detected on controlling terminal + or death of controlling process +SIGILL P1990 Core Illegal Instruction +SIGINFO \- A synonym for \fBSIGPWR\fP +SIGINT P1990 Term Interrupt from keyboard +SIGIO \- Term I/O now possible (4.2BSD) +SIGIOT \- Core IOT trap. A synonym for \fBSIGABRT\fP +SIGKILL P1990 Term Kill signal +SIGLOST \- Term File lock lost (unused) +SIGPIPE P1990 Term Broken pipe: write to pipe with no + readers; see \fBpipe\fP(7) +SIGPOLL P2001 Term Pollable event (Sys V); + synonym for \fBSIGIO\fP +SIGPROF P2001 Term Profiling timer expired +SIGPWR \- Term Power failure (System V) +SIGQUIT P1990 Core Quit from keyboard +SIGSEGV P1990 Core Invalid memory reference +SIGSTKFLT \- Term Stack fault on coprocessor (unused) +SIGSTOP P1990 Stop Stop process +SIGTSTP P1990 Stop Stop typed at terminal +SIGSYS P2001 Core Bad system call (SVr4); + see also \fBseccomp\fP(2) +SIGTERM P1990 Term Termination signal +SIGTRAP P2001 Core Trace/breakpoint trap +SIGTTIN P1990 Stop Terminal input for background process +SIGTTOU P1990 Stop Terminal output for background process +SIGUNUSED \- Core Synonymous with \fBSIGSYS\fP +SIGURG P2001 Ign Urgent condition on socket (4.2BSD) +SIGUSR1 P1990 Term User-defined signal 1 +SIGUSR2 P1990 Term User-defined signal 2 +SIGVTALRM P2001 Term Virtual alarm clock (4.2BSD) +SIGXCPU P2001 Core CPU time limit exceeded (4.2BSD); + see \fBsetrlimit\fP(2) +SIGXFSZ P2001 Core File size limit exceeded (4.2BSD); + see \fBsetrlimit\fP(2) +SIGWINCH \- Ign Window resize signal (4.3BSD, Sun) +.TE +.P +The signals +.B SIGKILL +and +.B SIGSTOP +cannot be caught, blocked, or ignored. +.P +Up to and including Linux 2.2, the default behavior for +.BR SIGSYS ", " SIGXCPU ", " SIGXFSZ , +and (on architectures other than SPARC and MIPS) +.B SIGBUS +was to terminate the process (without a core dump). +(On some other UNIX systems the default action for +.BR SIGXCPU " and " SIGXFSZ +is to terminate the process without a core dump.) +Linux 2.4 conforms to the POSIX.1-2001 requirements for these signals, +terminating the process with a core dump. +.P +.B SIGEMT +is not specified in POSIX.1-2001, but nevertheless appears +on most other UNIX systems, +where its default action is typically to terminate +the process with a core dump. +.P +.B SIGPWR +(which is not specified in POSIX.1-2001) is typically ignored +by default on those other UNIX systems where it appears. +.P +.B SIGIO +(which is not specified in POSIX.1-2001) is ignored by default +on several other UNIX systems. +.\" +.SS Queueing and delivery semantics for standard signals +If multiple standard signals are pending for a process, +the order in which the signals are delivered is unspecified. +.P +Standard signals do not queue. +If multiple instances of a standard signal are generated while +that signal is blocked, +then only one instance of the signal is marked as pending +(and the signal will be delivered just once when it is unblocked). +In the case where a standard signal is already pending, the +.I siginfo_t +structure (see +.BR sigaction (2)) +associated with that signal is not overwritten +on arrival of subsequent instances of the same signal. +Thus, the process will receive the information +associated with the first instance of the signal. +.\" +.SS Signal numbering for standard signals +The numeric value for each signal is given in the table below. +As shown in the table, many signals have different numeric values +on different architectures. +The first numeric value in each table row shows the signal number +on x86, ARM, and most other architectures; +the second value is for Alpha and SPARC; the third is for MIPS; +and the last is for PARISC. +A dash (\-) denotes that a signal is absent on the corresponding architecture. +.TS +l c c c c l +l c c c c l +______ +lB c c c c l. +Signal x86/ARM Alpha/ MIPS PARISC Notes + most others SPARC +SIGHUP \01 \01 \01 \01 +SIGINT \02 \02 \02 \02 +SIGQUIT \03 \03 \03 \03 +SIGILL \04 \04 \04 \04 +SIGTRAP \05 \05 \05 \05 +SIGABRT \06 \06 \06 \06 +SIGIOT \06 \06 \06 \06 +SIGBUS \07 10 10 10 +SIGEMT \- \07 \07 - +SIGFPE \08 \08 \08 \08 +SIGKILL \09 \09 \09 \09 +SIGUSR1 10 30 16 16 +SIGSEGV 11 11 11 11 +SIGUSR2 12 31 17 17 +SIGPIPE 13 13 13 13 +SIGALRM 14 14 14 14 +SIGTERM 15 15 15 15 +SIGSTKFLT 16 \- \- \07 +SIGCHLD 17 20 18 18 +SIGCLD \- \- 18 \- +SIGCONT 18 19 25 26 +SIGSTOP 19 17 23 24 +SIGTSTP 20 18 24 25 +SIGTTIN 21 21 26 27 +SIGTTOU 22 22 27 28 +SIGURG 23 16 21 29 +SIGXCPU 24 24 30 12 +SIGXFSZ 25 25 31 30 +SIGVTALRM 26 26 28 20 +SIGPROF 27 27 29 21 +SIGWINCH 28 28 20 23 +SIGIO 29 23 22 22 +SIGPOLL Same as SIGIO +SIGPWR 30 29/\- 19 19 +SIGINFO \- 29/\- \- \- +SIGLOST \- \-/29 \- \- +SIGSYS 31 12 12 31 +SIGUNUSED 31 \- \- 31 +.TE +.P +Note the following: +.IP \[bu] 3 +Where defined, +.B SIGUNUSED +is synonymous with +.BR SIGSYS . +Since glibc 2.26, +.B SIGUNUSED +is no longer defined on any architecture. +.IP \[bu] +Signal 29 is +.BR SIGINFO / SIGPWR +(synonyms for the same value) on Alpha but +.B SIGLOST +on SPARC. +.\" +.SS Real-time signals +Starting with Linux 2.2, +Linux supports real-time signals as originally defined in the POSIX.1b +real-time extensions (and now included in POSIX.1-2001). +The range of supported real-time signals is defined by the macros +.B SIGRTMIN +and +.BR SIGRTMAX . +POSIX.1-2001 requires that an implementation support at least +.B _POSIX_RTSIG_MAX +(8) real-time signals. +.P +The Linux kernel supports a range of 33 different real-time +signals, numbered 32 to 64. +However, the glibc POSIX threads implementation internally uses +two (for NPTL) or three (for LinuxThreads) real-time signals +(see +.BR pthreads (7)), +and adjusts the value of +.B SIGRTMIN +suitably (to 34 or 35). +Because the range of available real-time signals varies according +to the glibc threading implementation (and this variation can occur +at run time according to the available kernel and glibc), +and indeed the range of real-time signals varies across UNIX systems, +programs should +.IR "never refer to real-time signals using hard-coded numbers" , +but instead should always refer to real-time signals using the notation +.BR SIGRTMIN +n, +and include suitable (run-time) checks that +.BR SIGRTMIN +n +does not exceed +.BR SIGRTMAX . +.P +Unlike standard signals, real-time signals have no predefined meanings: +the entire set of real-time signals can be used for application-defined +purposes. +.P +The default action for an unhandled real-time signal is to terminate the +receiving process. +.P +Real-time signals are distinguished by the following: +.IP \[bu] 3 +Multiple instances of real-time signals can be queued. +By contrast, if multiple instances of a standard signal are delivered +while that signal is currently blocked, then only one instance is queued. +.IP \[bu] +If the signal is sent using +.BR sigqueue (3), +an accompanying value (either an integer or a pointer) can be sent +with the signal. +If the receiving process establishes a handler for this signal using the +.B SA_SIGINFO +flag to +.BR sigaction (2), +then it can obtain this data via the +.I si_value +field of the +.I siginfo_t +structure passed as the second argument to the handler. +Furthermore, the +.I si_pid +and +.I si_uid +fields of this structure can be used to obtain the PID +and real user ID of the process sending the signal. +.IP \[bu] +Real-time signals are delivered in a guaranteed order. +Multiple real-time signals of the same type are delivered in the order +they were sent. +If different real-time signals are sent to a process, they are delivered +starting with the lowest-numbered signal. +(I.e., low-numbered signals have highest priority.) +By contrast, if multiple standard signals are pending for a process, +the order in which they are delivered is unspecified. +.P +If both standard and real-time signals are pending for a process, +POSIX leaves it unspecified which is delivered first. +Linux, like many other implementations, gives priority +to standard signals in this case. +.P +According to POSIX, an implementation should permit at least +.B _POSIX_SIGQUEUE_MAX +(32) real-time signals to be queued to +a process. +However, Linux does things differently. +Up to and including Linux 2.6.7, Linux imposes +a system-wide limit on the number of queued real-time signals +for all processes. +This limit can be viewed and (with privilege) changed via the +.I /proc/sys/kernel/rtsig\-max +file. +A related file, +.IR /proc/sys/kernel/rtsig\-nr , +can be used to find out how many real-time signals are currently queued. +In Linux 2.6.8, these +.I /proc +interfaces were replaced by the +.B RLIMIT_SIGPENDING +resource limit, which specifies a per-user limit for queued +signals; see +.BR setrlimit (2) +for further details. +.P +The addition of real-time signals required the widening +of the signal set structure +.RI ( sigset_t ) +from 32 to 64 bits. +Consequently, various system calls were superseded by new system calls +that supported the larger signal sets. +The old and new system calls are as follows: +.TS +lb lb +l l. +Linux 2.0 and earlier Linux 2.2 and later +\fBsigaction\fP(2) \fBrt_sigaction\fP(2) +\fBsigpending\fP(2) \fBrt_sigpending\fP(2) +\fBsigprocmask\fP(2) \fBrt_sigprocmask\fP(2) +\fBsigreturn\fP(2) \fBrt_sigreturn\fP(2) +\fBsigsuspend\fP(2) \fBrt_sigsuspend\fP(2) +\fBsigtimedwait\fP(2) \fBrt_sigtimedwait\fP(2) +.TE +.\" +.SS Interruption of system calls and library functions by signal handlers +If a signal handler is invoked while a system call or library +function call is blocked, then either: +.IP \[bu] 3 +the call is automatically restarted after the signal handler returns; or +.IP \[bu] +the call fails with the error +.BR EINTR . +.P +Which of these two behaviors occurs depends on the interface and +whether or not the signal handler was established using the +.B SA_RESTART +flag (see +.BR sigaction (2)). +The details vary across UNIX systems; +below, the details for Linux. +.P +If a blocked call to one of the following interfaces is interrupted +by a signal handler, then the call is automatically restarted +after the signal handler returns if the +.B SA_RESTART +flag was used; otherwise the call fails with the error +.BR EINTR : +.\" The following system calls use ERESTARTSYS, +.\" so that they are restartable +.IP \[bu] 3 +.BR read (2), +.BR readv (2), +.BR write (2), +.BR writev (2), +and +.BR ioctl (2) +calls on "slow" devices. +A "slow" device is one where the I/O call may block for an +indefinite time, for example, a terminal, pipe, or socket. +If an I/O call on a slow device has already transferred some +data by the time it is interrupted by a signal handler, +then the call will return a success status +(normally, the number of bytes transferred). +Note that a (local) disk is not a slow device according to this definition; +I/O operations on disk devices are not interrupted by signals. +.IP \[bu] +.BR open (2), +if it can block (e.g., when opening a FIFO; see +.BR fifo (7)). +.IP \[bu] +.BR wait (2), +.BR wait3 (2), +.BR wait4 (2), +.BR waitid (2), +and +.BR waitpid (2). +.IP \[bu] +Socket interfaces: +.\" If a timeout (setsockopt()) is in effect on the socket, then these +.\" system calls switch to using EINTR. Consequently, they and are not +.\" automatically restarted, and they show the stop/cont behavior +.\" described below. (Verified from Linux 2.6.26 source, and by experiment; mtk) +.BR accept (2), +.BR connect (2), +.BR recv (2), +.BR recvfrom (2), +.BR recvmmsg (2), +.BR recvmsg (2), +.BR send (2), +.BR sendto (2), +and +.BR sendmsg (2), +.\" FIXME What about sendmmsg()? +unless a timeout has been set on the socket (see below). +.IP \[bu] +File locking interfaces: +.BR flock (2) +and +the +.B F_SETLKW +and +.B F_OFD_SETLKW +operations of +.BR fcntl (2) +.IP \[bu] +POSIX message queue interfaces: +.BR mq_receive (3), +.BR mq_timedreceive (3), +.BR mq_send (3), +and +.BR mq_timedsend (3). +.IP \[bu] +.BR futex (2) +.B FUTEX_WAIT +(since Linux 2.6.22; +.\" commit 72c1bbf308c75a136803d2d76d0e18258be14c7a +beforehand, always failed with +.BR EINTR ). +.IP \[bu] +.BR getrandom (2). +.IP \[bu] +.BR pthread_mutex_lock (3), +.BR pthread_cond_wait (3), +and related APIs. +.IP \[bu] +.BR futex (2) +.BR FUTEX_WAIT_BITSET . +.IP \[bu] +POSIX semaphore interfaces: +.BR sem_wait (3) +and +.BR sem_timedwait (3) +(since Linux 2.6.22; +.\" as a consequence of the 2.6.22 changes in the futex() implementation +beforehand, always failed with +.BR EINTR ). +.IP \[bu] +.BR read (2) +from an +.BR inotify (7) +file descriptor +(since Linux 3.8; +.\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06 +beforehand, always failed with +.BR EINTR ). +.P +The following interfaces are never restarted after +being interrupted by a signal handler, +regardless of the use of +.BR SA_RESTART ; +they always fail with the error +.B EINTR +when interrupted by a signal handler: +.\" These are the system calls that give EINTR or ERESTARTNOHAND +.\" on interruption by a signal handler. +.IP \[bu] 3 +"Input" socket interfaces, when a timeout +.RB ( SO_RCVTIMEO ) +has been set on the socket using +.BR setsockopt (2): +.BR accept (2), +.BR recv (2), +.BR recvfrom (2), +.BR recvmmsg (2) +(also with a non-NULL +.I timeout +argument), +and +.BR recvmsg (2). +.IP \[bu] +"Output" socket interfaces, when a timeout +.RB ( SO_RCVTIMEO ) +has been set on the socket using +.BR setsockopt (2): +.BR connect (2), +.BR send (2), +.BR sendto (2), +and +.BR sendmsg (2). +.\" FIXME What about sendmmsg()? +.IP \[bu] +Interfaces used to wait for signals: +.BR pause (2), +.BR sigsuspend (2), +.BR sigtimedwait (2), +and +.BR sigwaitinfo (2). +.IP \[bu] +File descriptor multiplexing interfaces: +.BR epoll_wait (2), +.BR epoll_pwait (2), +.BR poll (2), +.BR ppoll (2), +.BR select (2), +and +.BR pselect (2). +.IP \[bu] +System V IPC interfaces: +.\" On some other systems, SA_RESTART does restart these system calls +.BR msgrcv (2), +.BR msgsnd (2), +.BR semop (2), +and +.BR semtimedop (2). +.IP \[bu] +Sleep interfaces: +.BR clock_nanosleep (2), +.BR nanosleep (2), +and +.BR usleep (3). +.IP \[bu] +.BR io_getevents (2). +.P +The +.BR sleep (3) +function is also never restarted if interrupted by a handler, +but gives a success return: the number of seconds remaining to sleep. +.P +In certain circumstances, the +.BR seccomp (2) +user-space notification feature can lead to restarting of system calls +that would otherwise never be restarted by +.BR SA_RESTART ; +for details, see +.BR seccomp_unotify (2). +.\" +.SS Interruption of system calls and library functions by stop signals +On Linux, even in the absence of signal handlers, +certain blocking interfaces can fail with the error +.B EINTR +after the process is stopped by one of the stop signals +and then resumed via +.BR SIGCONT . +This behavior is not sanctioned by POSIX.1, and doesn't occur +on other systems. +.P +The Linux interfaces that display this behavior are: +.IP \[bu] 3 +"Input" socket interfaces, when a timeout +.RB ( SO_RCVTIMEO ) +has been set on the socket using +.BR setsockopt (2): +.BR accept (2), +.BR recv (2), +.BR recvfrom (2), +.BR recvmmsg (2) +(also with a non-NULL +.I timeout +argument), +and +.BR recvmsg (2). +.IP \[bu] +"Output" socket interfaces, when a timeout +.RB ( SO_RCVTIMEO ) +has been set on the socket using +.BR setsockopt (2): +.BR connect (2), +.BR send (2), +.BR sendto (2), +and +.\" FIXME What about sendmmsg()? +.BR sendmsg (2), +if a send timeout +.RB ( SO_SNDTIMEO ) +has been set. +.IP \[bu] +.BR epoll_wait (2), +.BR epoll_pwait (2). +.IP \[bu] +.BR semop (2), +.BR semtimedop (2). +.IP \[bu] +.BR sigtimedwait (2), +.BR sigwaitinfo (2). +.IP \[bu] +Linux 3.7 and earlier: +.BR read (2) +from an +.BR inotify (7) +file descriptor +.\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06 +.IP \[bu] +Linux 2.6.21 and earlier: +.BR futex (2) +.BR FUTEX_WAIT , +.BR sem_timedwait (3), +.BR sem_wait (3). +.IP \[bu] +Linux 2.6.8 and earlier: +.BR msgrcv (2), +.BR msgsnd (2). +.IP \[bu] +Linux 2.4 and earlier: +.BR nanosleep (2). +.SH STANDARDS +POSIX.1, except as noted. +.SH NOTES +For a discussion of async-signal-safe functions, see +.BR signal\-safety (7). +.P +The +.IR /proc/ pid /task/ tid /status +file contains various fields that show the signals +that a thread is blocking +.RI ( SigBlk ), +catching +.RI ( SigCgt ), +or ignoring +.RI ( SigIgn ). +(The set of signals that are caught or ignored will be the same +across all threads in a process.) +Other fields show the set of pending signals that are directed to the thread +.RI ( SigPnd ) +as well as the set of pending signals that are directed +to the process as a whole +.RI ( ShdPnd ). +The corresponding fields in +.IR /proc/ pid /status +show the information for the main thread. +See +.BR proc (5) +for further details. +.SH BUGS +There are six signals that can be delivered +as a consequence of a hardware exception: +.BR SIGBUS , +.BR SIGEMT , +.BR SIGFPE , +.BR SIGILL , +.BR SIGSEGV , +and +.BR SIGTRAP . +Which of these signals is delivered, +for any given hardware exception, +is not documented and does not always make sense. +.P +For example, an invalid memory access that causes delivery of +.B SIGSEGV +on one CPU architecture may cause delivery of +.B SIGBUS +on another architecture, or vice versa. +.P +For another example, using the x86 +.I int +instruction with a forbidden argument +(any number other than 3 or 128) +causes delivery of +.BR SIGSEGV , +even though +.B SIGILL +would make more sense, +because of how the CPU reports the forbidden operation to the kernel. +.SH SEE ALSO +.BR kill (1), +.BR clone (2), +.BR getrlimit (2), +.BR kill (2), +.BR pidfd_send_signal (2), +.BR restart_syscall (2), +.BR rt_sigqueueinfo (2), +.BR setitimer (2), +.BR setrlimit (2), +.BR sgetmask (2), +.BR sigaction (2), +.BR sigaltstack (2), +.BR signal (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigreturn (2), +.BR sigsuspend (2), +.BR sigwaitinfo (2), +.BR abort (3), +.BR bsd_signal (3), +.BR killpg (3), +.BR longjmp (3), +.BR pthread_sigqueue (3), +.BR raise (3), +.BR sigqueue (3), +.BR sigset (3), +.BR sigsetops (3), +.BR sigvec (3), +.BR sigwait (3), +.BR strsignal (3), +.BR swapcontext (3), +.BR sysv_signal (3), +.BR core (5), +.BR proc (5), +.BR nptl (7), +.BR pthreads (7), +.BR sigevent (3type) diff --git a/man/man7/sock_diag.7 b/man/man7/sock_diag.7 new file mode 100644 index 0000000..5942698 --- /dev/null +++ b/man/man7/sock_diag.7 @@ -0,0 +1,825 @@ +.\" Copyright (c) 2016 Pavel Emelyanov +.\" Copyright (c) 2016 Dmitry V. Levin +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.TH sock_diag 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sock_diag \- obtaining information about sockets +.SH SYNOPSIS +.nf +.B #include +.B #include +.BR "#include " " /* for UNIX domain sockets */" +.BR "#include " " /* for IPv4 and IPv6 sockets */" +.P +.BI "diag_socket = socket(AF_NETLINK, " socket_type ", NETLINK_SOCK_DIAG);" +.fi +.SH DESCRIPTION +The sock_diag netlink subsystem provides a mechanism for obtaining +information about sockets of various address families from the kernel. +This subsystem can be used to obtain information about individual +sockets or request a list of sockets. +.P +In the request, the caller can specify additional information it would +like to obtain about the socket, for example, memory information or +information specific to the address family. +.P +When requesting a list of sockets, the caller can specify filters that +would be applied by the kernel to select a subset of sockets to report. +For now, there is only the ability to filter sockets by state (connected, +listening, and so on.) +.P +Note that sock_diag reports only those sockets that have a name; +that is, either sockets bound explicitly with +.BR bind (2) +or sockets that were automatically bound to an address (e.g., by +.BR connect (2)). +This is the same set of sockets that is available via +.IR /proc/net/unix , +.IR /proc/net/tcp , +.IR /proc/net/udp , +and so on. +.\" +.SS Request +The request starts with a +.I "struct nlmsghdr" +header described in +.BR netlink (7) +with +.I nlmsg_type +field set to +.BR SOCK_DIAG_BY_FAMILY . +It is followed by a header specific to the address family that starts with +a common part shared by all address families: +.P +.in +4n +.EX +struct sock_diag_req { + __u8 sdiag_family; + __u8 sdiag_protocol; +}; +.EE +.in +.P +The fields of this structure are as follows: +.TP +.I sdiag_family +An address family. +It should be set to the appropriate +.B AF_* +constant. +.TP +.I sdiag_protocol +Depends on +.IR sdiag_family . +It should be set to the appropriate +.B IPPROTO_* +constant for +.B AF_INET +and +.BR AF_INET6 , +and to 0 otherwise. +.P +If the +.I nlmsg_flags +field of the +.I "struct nlmsghdr" +header has the +.B NLM_F_DUMP +flag set, it means that a list of sockets is being requested; +otherwise it is a query about an individual socket. +.\" +.SS Response +The response starts with a +.I "struct nlmsghdr" +header and is followed by an array of objects specific to the address family. +The array is to be accessed with the standard +.B NLMSG_* +macros from the +.BR netlink (3) +API. +.P +Each object is the NLA (netlink attributes) list that is to be accessed +with the +.B RTA_* +macros from +.BR rtnetlink (3) +API. +.\" +.SS UNIX domain sockets +For UNIX domain sockets the request is represented in the following structure: +.P +.in +4n +.EX +struct unix_diag_req { + __u8 sdiag_family; + __u8 sdiag_protocol; + __u16 pad; + __u32 udiag_states; + __u32 udiag_ino; + __u32 udiag_show; + __u32 udiag_cookie[2]; +}; +.EE +.in +.P +The fields of this structure are as follows: +.TP +.I sdiag_family +The address family; it should be set to +.BR AF_UNIX . +.P +.I sdiag_protocol +.PD 0 +.TP +.PD +.I pad +These fields should be set to 0. +.TP +.I udiag_states +This is a bit mask that defines a filter of sockets states. +Only those sockets whose states are in this mask will be reported. +Ignored when querying for an individual socket. +Supported values are: +.P +.RS 12 +1 << +.B TCP_ESTABLISHED +.P +1 << +.B TCP_LISTEN +.RE +.TP +.I udiag_ino +This is an inode number when querying for an individual socket. +Ignored when querying for a list of sockets. +.TP +.I udiag_show +This is a set of flags defining what kind of information to report. +Each requested kind of information is reported back as a netlink +attribute as described below: +.RS +.TP +.B UDIAG_SHOW_NAME +The attribute reported in answer to this request is +.BR UNIX_DIAG_NAME . +The payload associated with this attribute is the pathname to which +the socket was bound (a sequence of bytes up to +.B UNIX_PATH_MAX +length). +.TP +.B UDIAG_SHOW_VFS +The attribute reported in answer to this request is +.BR UNIX_DIAG_VFS . +The payload associated with this attribute is represented in the following +structure: +.IP +.in +4n +.EX +struct unix_diag_vfs { + __u32 udiag_vfs_dev; + __u32 udiag_vfs_ino; +}; +.EE +.in +.IP +The fields of this structure are as follows: +.RS +.TP +.I udiag_vfs_dev +The device number of the corresponding on-disk socket inode. +.TP +.I udiag_vfs_ino +The inode number of the corresponding on-disk socket inode. +.RE +.TP +.B UDIAG_SHOW_PEER +The attribute reported in answer to this request is +.BR UNIX_DIAG_PEER . +The payload associated with this attribute is a __u32 value +which is the peer's inode number. +This attribute is reported for connected sockets only. +.TP +.B UDIAG_SHOW_ICONS +The attribute reported in answer to this request is +.BR UNIX_DIAG_ICONS . +The payload associated with this attribute is an array of __u32 values +which are inode numbers of sockets that has passed the +.BR connect (2) +call, but hasn't been processed with +.BR accept (2) +yet. +This attribute is reported for listening sockets only. +.TP +.B UDIAG_SHOW_RQLEN +The attribute reported in answer to this request is +.BR UNIX_DIAG_RQLEN . +The payload associated with this attribute is represented in the following +structure: +.IP +.in +4n +.EX +struct unix_diag_rqlen { + __u32 udiag_rqueue; + __u32 udiag_wqueue; +}; +.EE +.in +.IP +The fields of this structure are as follows: +.RS +.TP +.I udiag_rqueue +For listening sockets: +the number of pending connections. +The length of the array associated with the +.B UNIX_DIAG_ICONS +response attribute is equal to this value. +.IP +For established sockets: +the amount of data in incoming queue. +.TP +.I udiag_wqueue +For listening sockets: +the backlog length which equals to the value passed as the second argument to +.BR listen (2). +.IP +For established sockets: +the amount of memory available for sending. +.RE +.TP +.B UDIAG_SHOW_MEMINFO +The attribute reported in answer to this request is +.BR UNIX_DIAG_MEMINFO . +The payload associated with this attribute is an array of __u32 values +described below in the subsection "Socket memory information". +.P +The following attributes are reported back without any specific request: +.TP +.B UNIX_DIAG_SHUTDOWN +The payload associated with this attribute is __u8 value which represents +bits of +.BR shutdown (2) +state. +.RE +.TP +.I udiag_cookie +This is an array of opaque identifiers that could be used along with +.I udiag_ino +to specify an individual socket. +It is ignored when querying for a list +of sockets, as well as when all its elements are set to \-1. +.P +The response to a query for UNIX domain sockets is represented as an array of +.P +.in +4n +.EX +struct unix_diag_msg { + __u8 udiag_family; + __u8 udiag_type; + __u8 udiag_state; + __u8 pad; + __u32 udiag_ino; + __u32 udiag_cookie[2]; +}; +.EE +.in +.P +followed by netlink attributes. +.P +The fields of this structure are as follows: +.TP +.I udiag_family +This field has the same meaning as in +.IR "struct unix_diag_req" . +.TP +.I udiag_type +This is set to one of +.BR SOCK_PACKET , +.BR SOCK_STREAM , +or +.BR SOCK_SEQPACKET . +.TP +.I udiag_state +This is set to one of +.B TCP_LISTEN +or +.BR TCP_ESTABLISHED . +.TP +.I pad +This field is set to 0. +.TP +.I udiag_ino +This is the socket inode number. +.TP +.I udiag_cookie +This is an array of opaque identifiers that could be used in subsequent +queries. +.\" +.SS IPv4 and IPv6 sockets +For IPv4 and IPv6 sockets, +the request is represented in the following structure: +.P +.in +4n +.EX +struct inet_diag_req_v2 { + __u8 sdiag_family; + __u8 sdiag_protocol; + __u8 idiag_ext; + __u8 pad; + __u32 idiag_states; + struct inet_diag_sockid id; +}; +.EE +.in +.P +where +.I "struct inet_diag_sockid" +is defined as follows: +.P +.in +4n +.EX +struct inet_diag_sockid { + __be16 idiag_sport; + __be16 idiag_dport; + __be32 idiag_src[4]; + __be32 idiag_dst[4]; + __u32 idiag_if; + __u32 idiag_cookie[2]; +}; +.EE +.in +.P +The fields of +.I "struct inet_diag_req_v2" +are as follows: +.TP +.I sdiag_family +This should be set to either +.B AF_INET +or +.B AF_INET6 +for IPv4 or IPv6 sockets respectively. +.TP +.I sdiag_protocol +This should be set to one of +.BR IPPROTO_TCP , +.BR IPPROTO_UDP , +or +.BR IPPROTO_UDPLITE . +.TP +.I idiag_ext +This is a set of flags defining what kind of extended information to report. +Each requested kind of information is reported back as a netlink attribute +as described below: +.RS +.TP +.B INET_DIAG_TOS +The payload associated with this attribute is a __u8 value +which is the TOS of the socket. +.TP +.B INET_DIAG_TCLASS +The payload associated with this attribute is a __u8 value +which is the TClass of the socket. +IPv6 sockets only. +For LISTEN and CLOSE sockets, this is followed by +.B INET_DIAG_SKV6ONLY +attribute with associated __u8 payload value meaning whether the socket +is IPv6-only or not. +.TP +.B INET_DIAG_MEMINFO +The payload associated with this attribute is represented in the following +structure: +.IP +.in +4n +.EX +struct inet_diag_meminfo { + __u32 idiag_rmem; + __u32 idiag_wmem; + __u32 idiag_fmem; + __u32 idiag_tmem; +}; +.EE +.in +.IP +The fields of this structure are as follows: +.RS +.TP 12 +.I idiag_rmem +The amount of data in the receive queue. +.TP +.I idiag_wmem +The amount of data that is queued by TCP but not yet sent. +.TP +.I idiag_fmem +The amount of memory scheduled for future use (TCP only). +.TP +.I idiag_tmem +The amount of data in send queue. +.RE +.TP +.B INET_DIAG_SKMEMINFO +The payload associated with this attribute is an array of __u32 values +described below in the subsection "Socket memory information". +.TP +.B INET_DIAG_INFO +The payload associated with this attribute is specific to the address family. +For TCP sockets, it is an object of type +.IR "struct tcp_info" . +.TP +.B INET_DIAG_CONG +The payload associated with this attribute is a string that describes the +congestion control algorithm used. +For TCP sockets only. +.RE +.TP +.I pad +This should be set to 0. +.TP +.I idiag_states +This is a bit mask that defines a filter of socket states. +Only those sockets whose states are in this mask will be reported. +Ignored when querying for an individual socket. +.TP +.I id +This is a socket ID object that is used in dump requests, in queries +about individual sockets, and is reported back in each response. +Unlike UNIX domain sockets, IPv4 and IPv6 sockets are identified +using addresses and ports. +All values are in network byte order. +.P +The fields of +.I "struct inet_diag_sockid" +are as follows: +.TP +.I idiag_sport +The source port. +.TP +.I idiag_dport +The destination port. +.TP +.I idiag_src +The source address. +.TP +.I idiag_dst +The destination address. +.TP +.I idiag_if +The interface number the socket is bound to. +.TP +.I idiag_cookie +This is an array of opaque identifiers that could be used along with +other fields of this structure to specify an individual socket. +It is ignored when querying for a list of sockets, as well as +when all its elements are set to \-1. +.P +The response to a query for IPv4 or IPv6 sockets is represented as an array of +.P +.in +4n +.EX +struct inet_diag_msg { + __u8 idiag_family; + __u8 idiag_state; + __u8 idiag_timer; + __u8 idiag_retrans; +\& + struct inet_diag_sockid id; +\& + __u32 idiag_expires; + __u32 idiag_rqueue; + __u32 idiag_wqueue; + __u32 idiag_uid; + __u32 idiag_inode; +}; +.EE +.in +.P +followed by netlink attributes. +.P +The fields of this structure are as follows: +.TP +.I idiag_family +This is the same field as in +.IR "struct inet_diag_req_v2" . +.TP +.I idiag_state +This denotes socket state as in +.IR "struct inet_diag_req_v2" . +.TP +.I idiag_timer +For TCP sockets, this field describes the type of timer that is currently +active for the socket. +It is set to one of the following constants: +.IP +.PD 0 +.RS 12 +.TP +.B 0 +no timer is active +.TP +.B 1 +a retransmit timer +.TP +.B 2 +a keep-alive timer +.TP +.B 3 +a TIME_WAIT timer +.TP +.B 4 +a zero window probe timer +.RE +.PD +.IP +For non-TCP sockets, this field is set to 0. +.TP +.I idiag_retrans +For +.I idiag_timer +values 1, 2, and 4, this field contains the number of retransmits. +For other +.I idiag_timer +values, this field is set to 0. +.TP +.I idiag_expires +For TCP sockets that have an active timer, this field describes its expiration +time in milliseconds. +For other sockets, this field is set to 0. +.TP +.I idiag_rqueue +For listening sockets: +the number of pending connections. +.IP +For other sockets: +the amount of data in the incoming queue. +.TP +.I idiag_wqueue +For listening sockets: +the backlog length. +.IP +For other sockets: +the amount of memory available for sending. +.TP +.I idiag_uid +This is the socket owner UID. +.TP +.I idiag_inode +This is the socket inode number. +.\" +.SS Socket memory information +The payload associated with +.B UNIX_DIAG_MEMINFO +and +.B INET_DIAG_SKMEMINFO +netlink attributes is an array of the following __u32 values: +.TP +.B SK_MEMINFO_RMEM_ALLOC +The amount of data in receive queue. +.TP +.B SK_MEMINFO_RCVBUF +The receive socket buffer as set by +.BR SO_RCVBUF . +.TP +.B SK_MEMINFO_WMEM_ALLOC +The amount of data in send queue. +.TP +.B SK_MEMINFO_SNDBUF +The send socket buffer as set by +.BR SO_SNDBUF . +.TP +.B SK_MEMINFO_FWD_ALLOC +The amount of memory scheduled for future use (TCP only). +.TP +.B SK_MEMINFO_WMEM_QUEUED +The amount of data queued by TCP, but not yet sent. +.TP +.B SK_MEMINFO_OPTMEM +The amount of memory allocated for the socket's service needs (e.g., socket +filter). +.TP +.B SK_MEMINFO_BACKLOG +The amount of packets in the backlog (not yet processed). +.SH VERSIONS +.B NETLINK_INET_DIAG +was introduced in Linux 2.6.14 and supported +.B AF_INET +and +.B AF_INET6 +sockets only. +In Linux 3.3, it was renamed to +.B NETLINK_SOCK_DIAG +and extended to support +.B AF_UNIX +sockets. +.P +.B UNIX_DIAG_MEMINFO +and +.B INET_DIAG_SKMEMINFO +were introduced in Linux 3.6. +.SH STANDARDS +Linux. +.SH EXAMPLES +The following example program prints inode number, peer's inode number, +and name of all UNIX domain sockets in the current namespace. +.P +.EX +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +static int +send_query(int fd) +{ + struct sockaddr_nl nladdr = { + .nl_family = AF_NETLINK + }; + struct + { + struct nlmsghdr nlh; + struct unix_diag_req udr; + } req = { + .nlh = { + .nlmsg_len = sizeof(req), + .nlmsg_type = SOCK_DIAG_BY_FAMILY, + .nlmsg_flags = NLM_F_REQUEST | NLM_F_DUMP + }, + .udr = { + .sdiag_family = AF_UNIX, + .udiag_states = \-1, + .udiag_show = UDIAG_SHOW_NAME | UDIAG_SHOW_PEER + } + }; + struct iovec iov = { + .iov_base = &req, + .iov_len = sizeof(req) + }; + struct msghdr msg = { + .msg_name = &nladdr, + .msg_namelen = sizeof(nladdr), + .msg_iov = &iov, + .msg_iovlen = 1 + }; +\& + for (;;) { + if (sendmsg(fd, &msg, 0) < 0) { + if (errno == EINTR) + continue; +\& + perror("sendmsg"); + return \-1; + } +\& + return 0; + } +} +\& +static int +print_diag(const struct unix_diag_msg *diag, unsigned int len) +{ + if (len < NLMSG_LENGTH(sizeof(*diag))) { + fputs("short response\en", stderr); + return \-1; + } + if (diag\->udiag_family != AF_UNIX) { + fprintf(stderr, "unexpected family %u\en", diag\->udiag_family); + return \-1; + } +\& + unsigned int rta_len = len \- NLMSG_LENGTH(sizeof(*diag)); + unsigned int peer = 0; + size_t path_len = 0; + char path[sizeof(((struct sockaddr_un *) 0)\->sun_path) + 1]; +\& + for (struct rtattr *attr = (struct rtattr *) (diag + 1); + RTA_OK(attr, rta_len); attr = RTA_NEXT(attr, rta_len)) { + switch (attr\->rta_type) { + case UNIX_DIAG_NAME: + if (!path_len) { + path_len = RTA_PAYLOAD(attr); + if (path_len > sizeof(path) \- 1) + path_len = sizeof(path) \- 1; + memcpy(path, RTA_DATA(attr), path_len); + path[path_len] = \[aq]\e0\[aq]; + } + break; +\& + case UNIX_DIAG_PEER: + if (RTA_PAYLOAD(attr) >= sizeof(peer)) + peer = *(unsigned int *) RTA_DATA(attr); + break; + } + } +\& + printf("inode=%u", diag\->udiag_ino); +\& + if (peer) + printf(", peer=%u", peer); +\& + if (path_len) + printf(", name=%s%s", *path ? "" : "@", + *path ? path : path + 1); +\& + putchar(\[aq]\en\[aq]); + return 0; +} +\& +static int +receive_responses(int fd) +{ + long buf[8192 / sizeof(long)]; + struct sockaddr_nl nladdr; + struct iovec iov = { + .iov_base = buf, + .iov_len = sizeof(buf) + }; + int flags = 0; +\& + for (;;) { + struct msghdr msg = { + .msg_name = &nladdr, + .msg_namelen = sizeof(nladdr), + .msg_iov = &iov, + .msg_iovlen = 1 + }; +\& + ssize_t ret = recvmsg(fd, &msg, flags); +\& + if (ret < 0) { + if (errno == EINTR) + continue; +\& + perror("recvmsg"); + return \-1; + } + if (ret == 0) + return 0; +\& + if (nladdr.nl_family != AF_NETLINK) { + fputs("!AF_NETLINK\en", stderr); + return \-1; + } +\& + const struct nlmsghdr *h = (struct nlmsghdr *) buf; +\& + if (!NLMSG_OK(h, ret)) { + fputs("!NLMSG_OK\en", stderr); + return \-1; + } +\& + for (; NLMSG_OK(h, ret); h = NLMSG_NEXT(h, ret)) { + if (h\->nlmsg_type == NLMSG_DONE) + return 0; +\& + if (h\->nlmsg_type == NLMSG_ERROR) { + const struct nlmsgerr *err = NLMSG_DATA(h); +\& + if (h\->nlmsg_len < NLMSG_LENGTH(sizeof(*err))) { + fputs("NLMSG_ERROR\en", stderr); + } else { + errno = \-err\->error; + perror("NLMSG_ERROR"); + } +\& + return \-1; + } +\& + if (h\->nlmsg_type != SOCK_DIAG_BY_FAMILY) { + fprintf(stderr, "unexpected nlmsg_type %u\en", + (unsigned) h\->nlmsg_type); + return \-1; + } +\& + if (print_diag(NLMSG_DATA(h), h\->nlmsg_len)) + return \-1; + } + } +} +\& +int +main(void) +{ + int fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_SOCK_DIAG); +\& + if (fd < 0) { + perror("socket"); + return 1; + } +\& + int ret = send_query(fd) || receive_responses(fd); +\& + close(fd); + return ret; +} +.EE +.SH SEE ALSO +.BR netlink (3), +.BR rtnetlink (3), +.BR netlink (7), +.BR tcp (7) diff --git a/man/man7/socket.7 b/man/man7/socket.7 new file mode 100644 index 0000000..1b89d14 --- /dev/null +++ b/man/man7/socket.7 @@ -0,0 +1,1274 @@ +'\" t +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" and copyright (c) 1999 Matthew Wilcox. +.\" +.\" 2002-10-30, Michael Kerrisk, +.\" Added description of SO_ACCEPTCONN +.\" 2004-05-20, aeb, added SO_RCVTIMEO/SO_SNDTIMEO text. +.\" Modified, 27 May 2004, Michael Kerrisk +.\" Added notes on capability requirements +.\" A few small grammar fixes +.\" 2010-06-13 Jan Engelhardt +.\" Documented SO_DOMAIN and SO_PROTOCOL. +.\" +.\" FIXME +.\" The following are not yet documented: +.\" +.\" SO_PEERNAME (2.4?) +.\" get only +.\" Seems to do something similar to getpeername(), but then +.\" why is it necessary / how does it differ? +.\" +.\" SO_TIMESTAMPING (2.6.30) +.\" Documentation/networking/timestamping.txt +.\" commit cb9eff097831007afb30d64373f29d99825d0068 +.\" Author: Patrick Ohly +.\" +.\" SO_WIFI_STATUS (3.3) +.\" commit 6e3e939f3b1bf8534b32ad09ff199d88800835a0 +.\" Author: Johannes Berg +.\" Also: SCM_WIFI_STATUS +.\" +.\" SO_NOFCS (3.4) +.\" commit 3bdc0eba0b8b47797f4a76e377dd8360f317450f +.\" Author: Ben Greear +.\" +.\" SO_GET_FILTER (3.8) +.\" commit a8fc92778080c845eaadc369a0ecf5699a03bef0 +.\" Author: Pavel Emelyanov +.\" +.\" SO_MAX_PACING_RATE (3.13) +.\" commit 62748f32d501f5d3712a7c372bbb92abc7c62bc7 +.\" Author: Eric Dumazet +.\" +.\" SO_BPF_EXTENSIONS (3.14) +.\" commit ea02f9411d9faa3553ed09ce0ec9f00ceae9885e +.\" Author: Michal Sekletar +.\" +.TH socket 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +socket \- Linux socket interface +.SH SYNOPSIS +.nf +.B #include +.P +.IB sockfd " = socket(int " socket_family ", int " socket_type ", int " protocol ); +.fi +.SH DESCRIPTION +This manual page describes the Linux networking socket layer user +interface. +The BSD compatible sockets +are the uniform interface +between the user process and the network protocol stacks in the kernel. +The protocol modules are grouped into +.I protocol families +such as +.BR AF_INET ", " AF_IPX ", and " AF_PACKET , +and +.I socket types +such as +.B SOCK_STREAM +or +.BR SOCK_DGRAM . +See +.BR socket (2) +for more information on families and types. +.SS Socket-layer functions +These functions are used by the user process to send or receive packets +and to do other socket operations. +For more information, see their respective manual pages. +.P +.BR socket (2) +creates a socket, +.BR connect (2) +connects a socket to a remote socket address, +the +.BR bind (2) +function binds a socket to a local socket address, +.BR listen (2) +tells the socket that new connections shall be accepted, and +.BR accept (2) +is used to get a new socket with a new incoming connection. +.BR socketpair (2) +returns two connected anonymous sockets (implemented only for a few +local families like +.BR AF_UNIX ) +.P +.BR send (2), +.BR sendto (2), +and +.BR sendmsg (2) +send data over a socket, and +.BR recv (2), +.BR recvfrom (2), +.BR recvmsg (2) +receive data from a socket. +.BR poll (2) +and +.BR select (2) +wait for arriving data or a readiness to send data. +In addition, the standard I/O operations like +.BR write (2), +.BR writev (2), +.BR sendfile (2), +.BR read (2), +and +.BR readv (2) +can be used to read and write data. +.P +.BR getsockname (2) +returns the local socket address and +.BR getpeername (2) +returns the remote socket address. +.BR getsockopt (2) +and +.BR setsockopt (2) +are used to set or get socket layer or protocol options. +.BR ioctl (2) +can be used to set or read some other options. +.P +.BR close (2) +is used to close a socket. +.BR shutdown (2) +closes parts of a full-duplex socket connection. +.P +Seeking, or calling +.BR pread (2) +or +.BR pwrite (2) +with a nonzero position is not supported on sockets. +.P +It is possible to do nonblocking I/O on sockets by setting the +.B O_NONBLOCK +flag on a socket file descriptor using +.BR fcntl (2). +Then all operations that would block will (usually) +return with +.B EAGAIN +(operation should be retried later); +.BR connect (2) +will return +.B EINPROGRESS +error. +The user can then wait for various events via +.BR poll (2) +or +.BR select (2). +.TS +tab(:) allbox; +c s s +l l lx. +I/O events +Event:Poll flag:Occurrence +Read:POLLIN:T{ +New data arrived. +T} +Read:POLLIN:T{ +A connection setup has been completed +(for connection-oriented sockets) +T} +Read:POLLHUP:T{ +A disconnection request has been initiated by the other end. +T} +Read:POLLHUP:T{ +A connection is broken (only for connection-oriented protocols). +When the socket is written +.B SIGPIPE +is also sent. +T} +Write:POLLOUT:T{ +Socket has enough send buffer space for writing new data. +T} +Read/Write:T{ +POLLIN | +.br +POLLOUT +T}:T{ +An outgoing +.BR connect (2) +finished. +T} +Read/Write:POLLERR:T{ +An asynchronous error occurred. +T} +Read/Write:POLLHUP:T{ +The other end has shut down one direction. +T} +Exception:POLLPRI:T{ +Urgent data arrived. +.B SIGURG +is sent then. +T} +.\" FIXME . The following is not true currently: +.\" It is no I/O event when the connection +.\" is broken from the local end using +.\" .BR shutdown (2) +.\" or +.\" .BR close (2). +.TE +.P +An alternative to +.BR poll (2) +and +.BR select (2) +is to let the kernel inform the application about events +via a +.B SIGIO +signal. +For that the +.B O_ASYNC +flag must be set on a socket file descriptor via +.BR fcntl (2) +and a valid signal handler for +.B SIGIO +must be installed via +.BR sigaction (2). +See the +.I Signals +discussion below. +.SS Socket address structures +Each socket domain has its own format for socket addresses, +with a domain-specific address structure. +Each of these structures begins with an +integer "family" field (typed as +.IR sa_family_t ) +that indicates the type of the address structure. +This allows +the various system calls (e.g., +.BR connect (2), +.BR bind (2), +.BR accept (2), +.BR getsockname (2), +.BR getpeername (2)), +which are generic to all socket domains, +to determine the domain of a particular socket address. +.P +To allow any type of socket address to be passed to +interfaces in the sockets API, +the type +.I struct sockaddr +is defined. +The purpose of this type is purely to allow casting of +domain-specific socket address types to a "generic" type, +so as to avoid compiler warnings about type mismatches in +calls to the sockets API. +.P +In addition, the sockets API provides the data type +.IR "struct sockaddr_storage". +This type +is suitable to accommodate all supported domain-specific socket +address structures; it is large enough and is aligned properly. +(In particular, it is large enough to hold +IPv6 socket addresses.) +The structure includes the following field, which can be used to identify +the type of socket address actually stored in the structure: +.P +.in +4n +.EX + sa_family_t ss_family; +.EE +.in +.P +The +.I sockaddr_storage +structure is useful in programs that must handle socket addresses +in a generic way +(e.g., programs that must deal with both IPv4 and IPv6 socket addresses). +.SS Socket options +The socket options listed below can be set by using +.BR setsockopt (2) +and read with +.BR getsockopt (2) +with the socket level set to +.B SOL_SOCKET +for all sockets. +Unless otherwise noted, +.I optval +is a pointer to an +.IR int . +.\" FIXME . +.\" In the list below, the text used to describe argument types +.\" for each socket option should be more consistent +.\" +.\" SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in +.\" W R Stevens, UNPv1 +.TP +.B SO_ACCEPTCONN +Returns a value indicating whether or not this socket has been marked +to accept connections with +.BR listen (2). +The value 0 indicates that this is not a listening socket, +the value 1 indicates that this is a listening socket. +This socket option is read-only. +.TP +.BR SO_ATTACH_FILTER " (since Linux 2.2)" +.TQ +.BR SO_ATTACH_BPF " (since Linux 3.19)" +Attach a classic BPF +.RB ( SO_ATTACH_FILTER ) +or an extended BPF +.RB ( SO_ATTACH_BPF ) +program to the socket for use as a filter of incoming packets. +A packet will be dropped if the filter program returns zero. +If the filter program returns a +nonzero value which is less than the packet's data length, +the packet will be truncated to the length returned. +If the value returned by the filter is greater than or equal to the +packet's data length, the packet is allowed to proceed unmodified. +.IP +The argument for +.B SO_ATTACH_FILTER +is a +.I sock_fprog +structure, defined in +.IR : +.IP +.in +4n +.EX +struct sock_fprog { + unsigned short len; + struct sock_filter *filter; +}; +.EE +.in +.IP +The argument for +.B SO_ATTACH_BPF +is a file descriptor returned by the +.BR bpf (2) +system call and must refer to a program of type +.BR BPF_PROG_TYPE_SOCKET_FILTER . +.IP +These options may be set multiple times for a given socket, +each time replacing the previous filter program. +The classic and extended versions may be called on the same socket, +but the previous filter will always be replaced such that a socket +never has more than one filter defined. +.IP +Both classic and extended BPF are explained in the kernel source file +.I Documentation/networking/filter.txt +.TP +.B SO_ATTACH_REUSEPORT_CBPF +.TQ +.B SO_ATTACH_REUSEPORT_EBPF +For use with the +.B SO_REUSEPORT +option, these options allow the user to set a classic BPF +.RB ( SO_ATTACH_REUSEPORT_CBPF ) +or an extended BPF +.RB ( SO_ATTACH_REUSEPORT_EBPF ) +program which defines how packets are assigned to +the sockets in the reuseport group (that is, all sockets which have +.B SO_REUSEPORT +set and are using the same local address to receive packets). +.IP +The BPF program must return an index between 0 and N\-1 representing +the socket which should receive the packet +(where N is the number of sockets in the group). +If the BPF program returns an invalid index, +socket selection will fall back to the plain +.B SO_REUSEPORT +mechanism. +.IP +Sockets are numbered in the order in which they are added to the group +(that is, the order of +.BR bind (2) +calls for UDP sockets or the order of +.BR listen (2) +calls for TCP sockets). +New sockets added to a reuseport group will inherit the BPF program. +When a socket is removed from a reuseport group (via +.BR close (2)), +the last socket in the group will be moved into the closed socket's +position. +.IP +These options may be set repeatedly at any time on any socket in the group +to replace the current BPF program used by all sockets in the group. +.IP +.B SO_ATTACH_REUSEPORT_CBPF +takes the same argument type as +.B SO_ATTACH_FILTER +and +.B SO_ATTACH_REUSEPORT_EBPF +takes the same argument type as +.BR SO_ATTACH_BPF . +.IP +UDP support for this feature is available since Linux 4.5; +TCP support is available since Linux 4.6. +.TP +.B SO_BINDTODEVICE +Bind this socket to a particular device like \[lq]eth0\[rq], +as specified in the passed interface name. +If the +name is an empty string or the option length is zero, the socket device +binding is removed. +The passed option is a variable-length null-terminated +interface name string with the maximum size of +.BR IFNAMSIZ . +If a socket is bound to an interface, +only packets received from that particular interface are processed by the +socket. +Note that this works only for some socket types, particularly +.B AF_INET +sockets. +It is not supported for packet sockets (use normal +.BR bind (2) +there). +.IP +Before Linux 3.8, +this socket option could be set, but could not retrieved with +.BR getsockopt (2). +Since Linux 3.8, it is readable. +The +.I optlen +argument should contain the buffer size available +to receive the device name and is recommended to be +.B IFNAMSIZ +bytes. +The real device name length is reported back in the +.I optlen +argument. +.TP +.B SO_BROADCAST +Set or get the broadcast flag. +When enabled, datagram sockets are allowed to send +packets to a broadcast address. +This option has no effect on stream-oriented sockets. +.TP +.B SO_BSDCOMPAT +Enable BSD bug-to-bug compatibility. +This is used by the UDP protocol module in Linux 2.0 and 2.2. +If enabled, ICMP errors received for a UDP socket will not be passed +to the user program. +In later kernel versions, support for this option has been phased out: +Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning +(printk()) if a program uses this option. +Linux 2.0 also enabled BSD bug-to-bug compatibility +options (random header changing, skipping of the broadcast flag) for raw +sockets with this option, but that was removed in Linux 2.2. +.TP +.B SO_DEBUG +Enable socket debugging. +Allowed only for processes with the +.B CAP_NET_ADMIN +capability or an effective user ID of 0. +.TP +.BR SO_DETACH_FILTER " (since Linux 2.2)" +.TQ +.BR SO_DETACH_BPF " (since Linux 3.19)" +These two options, which are synonyms, +may be used to remove the classic or extended BPF +program attached to a socket with either +.B SO_ATTACH_FILTER +or +.BR SO_ATTACH_BPF . +The option value is ignored. +.TP +.BR SO_DOMAIN " (since Linux 2.6.32)" +Retrieves the socket domain as an integer, returning a value such as +.BR AF_INET6 . +See +.BR socket (2) +for details. +This socket option is read-only. +.TP +.B SO_ERROR +Get and clear the pending socket error. +This socket option is read-only. +Expects an integer. +.TP +.B SO_DONTROUTE +Don't send via a gateway, send only to directly connected hosts. +The same effect can be achieved by setting the +.B MSG_DONTROUTE +flag on a socket +.BR send (2) +operation. +Expects an integer boolean flag. +.TP +.BR SO_INCOMING_CPU " (gettable since Linux 3.19, settable since Linux 4.4)" +.\" getsockopt 2c8c56e15df3d4c2af3d656e44feb18789f75837 +.\" setsockopt 70da268b569d32a9fddeea85dc18043de9d89f89 +Sets or gets the CPU affinity of a socket. +Expects an integer flag. +.IP +.in +4n +.EX +int cpu = 1; +setsockopt(fd, SOL_SOCKET, SO_INCOMING_CPU, &cpu, + sizeof(cpu)); +.EE +.in +.IP +Because all of the packets for a single stream +(i.e., all packets for the same 4-tuple) +arrive on the single RX queue that is associated with a particular CPU, +the typical use case is to employ one listening process per RX queue, +with the incoming flow being handled by a listener +on the same CPU that is handling the RX queue. +This provides optimal NUMA behavior and keeps CPU caches hot. +.\" +.\" From an email conversation with Eric Dumazet: +.\" >> Note that setting the option is not supported if SO_REUSEPORT is used. +.\" > +.\" > Please define "not supported". Does this yield an API diagnostic? +.\" > If so, what is it? +.\" > +.\" >> Socket will be selected from an array, either by a hash or BPF program +.\" >> that has no access to this information. +.\" > +.\" > Sorry -- I'm lost here. How does this comment relate to the proposed +.\" > man page text above? +.\" +.\" Simply that : +.\" +.\" If an application uses both SO_INCOMING_CPU and SO_REUSEPORT, then +.\" SO_REUSEPORT logic, selecting the socket to receive the packet, ignores +.\" SO_INCOMING_CPU setting. +.TP +.BR SO_INCOMING_NAPI_ID " (gettable since Linux 4.12)" +.\" getsockopt 6d4339028b350efbf87c61e6d9e113e5373545c9 +Returns a system-level unique ID called NAPI ID that is associated +with a RX queue on which the last packet associated with that +socket is received. +.IP +This can be used by an application to split the incoming flows among worker +threads based on the RX queue on which the packets associated with the +flows are received. +It allows each worker thread to be associated with +a NIC HW receive queue and service all the connection +requests received on that RX queue. +This mapping between an app thread and +a HW NIC queue streamlines the +flow of data from the NIC to the application. +.TP +.B SO_KEEPALIVE +Enable sending of keep-alive messages on connection-oriented sockets. +Expects an integer boolean flag. +.TP +.B SO_LINGER +Sets or gets the +.B SO_LINGER +option. +The argument is a +.I linger +structure. +.IP +.in +4n +.EX +struct linger { + int l_onoff; /* linger active */ + int l_linger; /* how many seconds to linger for */ +}; +.EE +.in +.IP +When enabled, a +.BR close (2) +or +.BR shutdown (2) +will not return until all queued messages for the socket have been +successfully sent or the linger timeout has been reached. +Otherwise, +the call returns immediately and the closing is done in the background. +When the socket is closed as part of +.BR exit (2), +it always lingers in the background. +.TP +.B SO_LOCK_FILTER +.\" commit d59577b6ffd313d0ab3be39cb1ab47e29bdc9182 +When set, this option will prevent +changing the filters associated with the socket. +These filters include any set using the socket options +.BR SO_ATTACH_FILTER , +.BR SO_ATTACH_BPF , +.BR SO_ATTACH_REUSEPORT_CBPF , +and +.BR SO_ATTACH_REUSEPORT_EBPF . +.IP +The typical use case is for a privileged process to set up a raw socket +(an operation that requires the +.B CAP_NET_RAW +capability), apply a restrictive filter, set the +.B SO_LOCK_FILTER +option, +and then either drop its privileges or pass the socket file descriptor +to an unprivileged process via a UNIX domain socket. +.IP +Once the +.B SO_LOCK_FILTER +option has been enabled, attempts to change or remove the filter +attached to a socket, or to disable the +.B SO_LOCK_FILTER +option will fail with the error +.BR EPERM . +.TP +.BR SO_MARK " (since Linux 2.6.25)" +.\" commit 4a19ec5800fc3bb64e2d87c4d9fdd9e636086fe0 +.\" and 914a9ab386a288d0f22252fc268ecbc048cdcbd5 +Set the mark for each packet sent through this socket +(similar to the netfilter MARK target but socket-based). +Changing the mark can be used for mark-based +routing without netfilter or for packet filtering. +Setting this option requires the +.B CAP_NET_ADMIN +or +.B CAP_NET_RAW +(since Linux 5.17) capability. +.TP +.B SO_OOBINLINE +If this option is enabled, +out-of-band data is directly placed into the receive data stream. +Otherwise, out-of-band data is passed only when the +.B MSG_OOB +flag is set during receiving. +.\" don't document it because it can do too much harm. +.\".B SO_NO_CHECK +.\" The kernel has support for the SO_NO_CHECK socket +.\" option (boolean: 0 == default, calculate checksum on xmit, +.\" 1 == do not calculate checksum on xmit). +.\" Additional note from Andi Kleen on SO_NO_CHECK (2010-08-30) +.\" On Linux UDP checksums are essentially free and there's no reason +.\" to turn them off and it would disable another safety line. +.\" That is why I didn't document the option. +.TP +.B SO_PASSCRED +Enable or disable the receiving of the +.B SCM_CREDENTIALS +control message. +For more information, see +.BR unix (7). +.TP +.B SO_PASSSEC +Enable or disable the receiving of the +.B SCM_SECURITY +control message. +For more information, see +.BR unix (7). +.TP +.BR SO_PEEK_OFF " (since Linux 3.4)" +.\" commit ef64a54f6e558155b4f149bb10666b9e914b6c54 +This option, which is currently supported only for +.BR unix (7) +sockets, sets the value of the "peek offset" for the +.BR recv (2) +system call when used with +.B MSG_PEEK +flag. +.IP +When this option is set to a negative value +(it is set to \-1 for all new sockets), +traditional behavior is provided: +.BR recv (2) +with the +.B MSG_PEEK +flag will peek data from the front of the queue. +.IP +When the option is set to a value greater than or equal to zero, +then the next peek at data queued in the socket will occur at +the byte offset specified by the option value. +At the same time, the "peek offset" will be +incremented by the number of bytes that were peeked from the queue, +so that a subsequent peek will return the next data in the queue. +.IP +If data is removed from the front of the queue via a call to +.BR recv (2) +(or similar) without the +.B MSG_PEEK +flag, the "peek offset" will be decreased by the number of bytes removed. +In other words, receiving data without the +.B MSG_PEEK +flag will cause the "peek offset" to be adjusted to maintain +the correct relative position in the queued data, +so that a subsequent peek will retrieve the data that would have been +retrieved had the data not been removed. +.IP +For datagram sockets, if the "peek offset" points to the middle of a packet, +the data returned will be marked with the +.B MSG_TRUNC +flag. +.IP +The following example serves to illustrate the use of +.BR SO_PEEK_OFF . +Suppose a stream socket has the following queued input data: +.IP +.in +4n +.EX +aabbccddeeff +.EE +.in +.IP +The following sequence of +.BR recv (2) +calls would have the effect noted in the comments: +.IP +.in +4n +.EX +int ov = 4; // Set peek offset to 4 +setsockopt(fd, SOL_SOCKET, SO_PEEK_OFF, &ov, sizeof(ov)); +\& +recv(fd, buf, 2, MSG_PEEK); // Peeks "cc"; offset set to 6 +recv(fd, buf, 2, MSG_PEEK); // Peeks "dd"; offset set to 8 +recv(fd, buf, 2, 0); // Reads "aa"; offset set to 6 +recv(fd, buf, 2, MSG_PEEK); // Peeks "ee"; offset set to 8 +.EE +.in +.TP +.B SO_PEERCRED +Return the credentials of the peer process connected to this socket. +For further details, see +.BR unix (7). +.TP +.BR SO_PEERSEC " (since Linux 2.6.2)" +Return the security context of the peer socket connected to this socket. +For further details, see +.BR unix (7) +and +.BR ip (7). +.TP +.B SO_PRIORITY +Set the protocol-defined priority for all packets to be sent on +this socket. +Linux uses this value to order the networking queues: +packets with a higher priority may be processed first depending +on the selected device queueing discipline. +.\" For +.\" .BR ip (7), +.\" this also sets the IP type-of-service (TOS) field for outgoing packets. +Setting a priority outside the range 0 to 6 requires the +.B CAP_NET_ADMIN +capability. +.TP +.BR SO_PROTOCOL " (since Linux 2.6.32)" +Retrieves the socket protocol as an integer, returning a value such as +.BR IPPROTO_SCTP . +See +.BR socket (2) +for details. +This socket option is read-only. +.TP +.B SO_RCVBUF +Sets or gets the maximum socket receive buffer in bytes. +The kernel doubles this value (to allow space for bookkeeping overhead) +when it is set using +.\" Most (all?) other implementations do not do this -- MTK, Dec 05 +.BR setsockopt (2), +and this doubled value is returned by +.BR getsockopt (2). +.\" The following thread on LMKL is quite informative: +.\" getsockopt/setsockopt with SO_RCVBUF and SO_SNDBUF "non-standard" behavior +.\" 17 July 2012 +.\" http://thread.gmane.org/gmane.linux.kernel/1328935 +The default value is set by the +.I /proc/sys/net/core/rmem_default +file, and the maximum allowed value is set by the +.I /proc/sys/net/core/rmem_max +file. +The minimum (doubled) value for this option is 256. +.TP +.BR SO_RCVBUFFORCE " (since Linux 2.6.14)" +Using this socket option, a privileged +.RB ( CAP_NET_ADMIN ) +process can perform the same task as +.BR SO_RCVBUF , +but the +.I rmem_max +limit can be overridden. +.TP +.BR SO_RCVLOWAT " and " SO_SNDLOWAT +Specify the minimum number of bytes in the buffer until the socket layer +will pass the data to the protocol +.RB ( SO_SNDLOWAT ) +or the user on receiving +.RB ( SO_RCVLOWAT ). +These two values are initialized to 1. +.B SO_SNDLOWAT +is not changeable on Linux +.RB ( setsockopt (2) +fails with the error +.BR ENOPROTOOPT ). +.B SO_RCVLOWAT +is changeable +only since Linux 2.4. +.IP +Before Linux 2.6.28 +.\" Tested on kernel 2.6.14 -- mtk, 30 Nov 05 +.BR select (2), +.BR poll (2), +and +.BR epoll (7) +did not respect the +.B SO_RCVLOWAT +setting on Linux, +and indicated a socket as readable when even a single byte of data +was available. +A subsequent read from the socket would then block until +.B SO_RCVLOWAT +bytes are available. +Since Linux 2.6.28, +.\" commit c7004482e8dcb7c3c72666395cfa98a216a4fb70 +.BR select (2), +.BR poll (2), +and +.BR epoll (7) +indicate a socket as readable only if at least +.B SO_RCVLOWAT +bytes are available. +.TP +.BR SO_RCVTIMEO " and " SO_SNDTIMEO +.\" Not implemented in Linux 2.0. +.\" Implemented in Linux 2.1.11 for getsockopt: always return a zero struct. +.\" Implemented in Linux 2.3.41 for setsockopt, and actually used. +Specify the receiving or sending timeouts until reporting an error. +The argument is a +.IR "struct timeval" . +If an input or output function blocks for this period of time, and +data has been sent or received, the return value of that function +will be the amount of data transferred; if no data has been transferred +and the timeout has been reached, then \-1 is returned with +.I errno +set to +.B EAGAIN +or +.BR EWOULDBLOCK , +.\" in fact to EAGAIN +or +.B EINPROGRESS +(for +.BR connect (2)) +just as if the socket was specified to be nonblocking. +If the timeout is set to zero (the default), +then the operation will never timeout. +Timeouts only have effect for system calls that perform socket I/O (e.g., +.BR accept (2), +.BR connect (2), +.BR read (2), +.BR recvmsg (2), +.BR send (2), +.BR sendmsg (2)); +timeouts have no effect for +.BR select (2), +.BR poll (2), +.BR epoll_wait (2), +and so on. +.TP +.B SO_REUSEADDR +.\" commit c617f398edd4db2b8567a28e899a88f8f574798d +.\" https://lwn.net/Articles/542629/ +Indicates that the rules used in validating addresses supplied in a +.BR bind (2) +call should allow reuse of local addresses. +For +.B AF_INET +sockets this +means that a socket may bind, except when there +is an active listening socket bound to the address. +When the listening socket is bound to +.B INADDR_ANY +with a specific port then it is not possible +to bind to this port for any local address. +Argument is an integer boolean flag. +.TP +.BR SO_REUSEPORT " (since Linux 3.9)" +Permits multiple +.B AF_INET +or +.B AF_INET6 +sockets to be bound to an identical socket address. +This option must be set on each socket (including the first socket) +prior to calling +.BR bind (2) +on the socket. +To prevent port hijacking, +all of the processes binding to the same address must have the same +effective UID. +This option can be employed with both TCP and UDP sockets. +.IP +For TCP sockets, this option allows +.BR accept (2) +load distribution in a multi-threaded server to be improved by +using a distinct listener socket for each thread. +This provides improved load distribution as compared +to traditional techniques such using a single +.BR accept (2)ing +thread that distributes connections, +or having multiple threads that compete to +.BR accept (2) +from the same socket. +.IP +For UDP sockets, +the use of this option can provide better distribution +of incoming datagrams to multiple processes (or threads) as compared +to the traditional technique of having multiple processes +compete to receive datagrams on the same socket. +.TP +.BR SO_RXQ_OVFL " (since Linux 2.6.33)" +.\" commit 3b885787ea4112eaa80945999ea0901bf742707f +Indicates that an unsigned 32-bit value ancillary message (cmsg) +should be attached to received skbs indicating +the number of packets dropped by the socket since its creation. +.TP +.BR SO_SELECT_ERR_QUEUE " (since Linux 3.10)" +.\" commit 7d4c04fc170087119727119074e72445f2bb192b +.\" Author: Keller, Jacob E +When this option is set on a socket, +an error condition on a socket causes notification not only via the +.I exceptfds +set of +.BR select (2). +Similarly, +.BR poll (2) +also returns a +.B POLLPRI +whenever an +.B POLLERR +event is returned. +.\" It does not affect wake up. +.IP +Background: this option was added when waking up on an error condition +occurred only via the +.I readfds +and +.I writefds +sets of +.BR select (2). +The option was added to allow monitoring for error conditions via the +.I exceptfds +argument without simultaneously having to receive notifications (via +.IR readfds ) +for regular data that can be read from the socket. +After changes in Linux 4.16, +.\" commit 6e5d58fdc9bedd0255a8 +.\" ("skbuff: Fix not waking applications when errors are enqueued") +the use of this flag to achieve the desired notifications +is no longer necessary. +This option is nevertheless retained for backwards compatibility. +.TP +.B SO_SNDBUF +Sets or gets the maximum socket send buffer in bytes. +The kernel doubles this value (to allow space for bookkeeping overhead) +when it is set using +.\" Most (all?) other implementations do not do this -- MTK, Dec 05 +.\" See also the comment to SO_RCVBUF (17 Jul 2012 LKML mail) +.BR setsockopt (2), +and this doubled value is returned by +.BR getsockopt (2). +The default value is set by the +.I /proc/sys/net/core/wmem_default +file and the maximum allowed value is set by the +.I /proc/sys/net/core/wmem_max +file. +The minimum (doubled) value for this option is 2048. +.TP +.BR SO_SNDBUFFORCE " (since Linux 2.6.14)" +Using this socket option, a privileged +.RB ( CAP_NET_ADMIN ) +process can perform the same task as +.BR SO_SNDBUF , +but the +.I wmem_max +limit can be overridden. +.TP +.B SO_TIMESTAMP +Enable or disable the receiving of the +.B SO_TIMESTAMP +control message. +The timestamp control message is sent with level +.B SOL_SOCKET +and a +.I cmsg_type +of +.BR SCM_TIMESTAMP . +The +.I cmsg_data +field is a +.I "struct timeval" +indicating the +reception time of the last packet passed to the user in this call. +See +.BR cmsg (3) +for details on control messages. +.TP +.BR SO_TIMESTAMPNS " (since Linux 2.6.22)" +.\" commit 92f37fd2ee805aa77925c1e64fd56088b46094fc +Enable or disable the receiving of the +.B SO_TIMESTAMPNS +control message. +The timestamp control message is sent with level +.B SOL_SOCKET +and a +.I cmsg_type +of +.BR SCM_TIMESTAMPNS . +The +.I cmsg_data +field is a +.I "struct timespec" +indicating the +reception time of the last packet passed to the user in this call. +The clock used for the timestamp is +.BR CLOCK_REALTIME . +See +.BR cmsg (3) +for details on control messages. +.IP +A socket cannot mix +.B SO_TIMESTAMP +and +.BR SO_TIMESTAMPNS : +the two modes are mutually exclusive. +.TP +.B SO_TYPE +Gets the socket type as an integer (e.g., +.BR SOCK_STREAM ). +This socket option is read-only. +.TP +.BR SO_BUSY_POLL " (since Linux 3.11)" +Sets the approximate time in microseconds to busy poll on a blocking receive +when there is no data. +Increasing this value requires +.BR CAP_NET_ADMIN . +The default for this option is controlled by the +.I /proc/sys/net/core/busy_read +file. +.IP +The value in the +.I /proc/sys/net/core/busy_poll +file determines how long +.BR select (2) +and +.BR poll (2) +will busy poll when they operate on sockets with +.B SO_BUSY_POLL +set and no events to report are found. +.IP +In both cases, +busy polling will only be done when the socket last received data +from a network device that supports this option. +.IP +While busy polling may improve latency of some applications, +care must be taken when using it since this will increase +both CPU utilization and power usage. +.SS Signals +When writing onto a connection-oriented socket that has been shut down +(by the local or the remote end) +.B SIGPIPE +is sent to the writing process and +.B EPIPE +is returned. +The signal is not sent when the write call +specified the +.B MSG_NOSIGNAL +flag. +.P +When requested with the +.B FIOSETOWN +.BR fcntl (2) +or +.B SIOCSPGRP +.BR ioctl (2), +.B SIGIO +is sent when an I/O event occurs. +It is possible to use +.BR poll (2) +or +.BR select (2) +in the signal handler to find out which socket the event occurred on. +An alternative (in Linux 2.2) is to set a real-time signal using the +.B F_SETSIG +.BR fcntl (2); +the handler of the real time signal will be called with +the file descriptor in the +.I si_fd +field of its +.IR siginfo_t . +See +.BR fcntl (2) +for more information. +.P +Under some circumstances (e.g., multiple processes accessing a +single socket), the condition that caused the +.B SIGIO +may have already disappeared when the process reacts to the signal. +If this happens, the process should wait again because Linux +will resend the signal later. +.\" .SS Ancillary messages +.SS /proc interfaces +The core socket networking parameters can be accessed +via files in the directory +.IR /proc/sys/net/core/ . +.TP +.I rmem_default +contains the default setting in bytes of the socket receive buffer. +.TP +.I rmem_max +contains the maximum socket receive buffer size in bytes which a user may +set by using the +.B SO_RCVBUF +socket option. +.TP +.I wmem_default +contains the default setting in bytes of the socket send buffer. +.TP +.I wmem_max +contains the maximum socket send buffer size in bytes which a user may +set by using the +.B SO_SNDBUF +socket option. +.TP +.IR message_cost " and " message_burst +configure the token bucket filter used to load limit warning messages +caused by external network events. +.TP +.I netdev_max_backlog +Maximum number of packets in the global input queue. +.TP +.I optmem_max +Maximum length of ancillary data and user control data like the iovecs +per socket. +.\" netdev_fastroute is not documented because it is experimental +.SS Ioctls +These operations can be accessed using +.BR ioctl (2): +.P +.in +4n +.EX +.IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");" +.EE +.in +.TP +.B SIOCGSTAMP +Return a +.I struct timeval +with the receive timestamp of the last packet passed to the user. +This is useful for accurate round trip time measurements. +See +.BR setitimer (2) +for a description of +.IR "struct timeval" . +.\" +This ioctl should be used only if the socket options +.B SO_TIMESTAMP +and +.B SO_TIMESTAMPNS +are not set on the socket. +Otherwise, it returns the timestamp of the +last packet that was received while +.B SO_TIMESTAMP +and +.B SO_TIMESTAMPNS +were not set, or it fails if no such packet has been received, +(i.e., +.BR ioctl (2) +returns \-1 with +.I errno +set to +.BR ENOENT ). +.TP +.B SIOCSPGRP +Set the process or process group that is to receive +.B SIGIO +or +.B SIGURG +signals when I/O becomes possible or urgent data is available. +The argument is a pointer to a +.IR pid_t . +For further details, see the description of +.B F_SETOWN +in +.BR fcntl (2). +.TP +.B FIOASYNC +Change the +.B O_ASYNC +flag to enable or disable asynchronous I/O mode of the socket. +Asynchronous I/O mode means that the +.B SIGIO +signal or the signal set with +.B F_SETSIG +is raised when a new I/O event occurs. +.IP +Argument is an integer boolean flag. +(This operation is synonymous with the use of +.BR fcntl (2) +to set the +.B O_ASYNC +flag.) +.\" +.TP +.B SIOCGPGRP +Get the current process or process group that receives +.B SIGIO +or +.B SIGURG +signals, +or 0 +when none is set. +.P +Valid +.BR fcntl (2) +operations: +.TP +.B FIOGETOWN +The same as the +.B SIOCGPGRP +.BR ioctl (2). +.TP +.B FIOSETOWN +The same as the +.B SIOCSPGRP +.BR ioctl (2). +.SH VERSIONS +.B SO_BINDTODEVICE +was introduced in Linux 2.0.30. +.B SO_PASSCRED +is new in Linux 2.2. +The +.I /proc +interfaces were introduced in Linux 2.2. +.B SO_RCVTIMEO +and +.B SO_SNDTIMEO +are supported since Linux 2.3.41. +Earlier, timeouts were fixed to +a protocol-specific setting, and could not be read or written. +.SH NOTES +Linux assumes that half of the send/receive buffer is used for internal +kernel structures; thus the values in the corresponding +.I /proc +files are twice what can be observed on the wire. +.P +Linux will allow port reuse only with the +.B SO_REUSEADDR +option +when this option was set both in the previous program that performed a +.BR bind (2) +to the port and in the program that wants to reuse the port. +This differs from some implementations (e.g., FreeBSD) +where only the later program needs to set the +.B SO_REUSEADDR +option. +Typically this difference is invisible, since, for example, a server +program is designed to always set this option. +.\" .SH AUTHORS +.\" This man page was written by Andi Kleen. +.SH SEE ALSO +.BR wireshark (1), +.BR bpf (2), +.BR connect (2), +.BR getsockopt (2), +.BR setsockopt (2), +.BR socket (2), +.BR pcap (3), +.BR address_families (7), +.BR capabilities (7), +.BR ddp (7), +.BR ip (7), +.BR ipv6 (7), +.BR packet (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7), +.BR tcpdump (8) diff --git a/man/man7/spufs.7 b/man/man7/spufs.7 new file mode 100644 index 0000000..7b1ca6a --- /dev/null +++ b/man/man7/spufs.7 @@ -0,0 +1,804 @@ +.\" Copyright (c) International Business Machines Corp., 2006 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" HISTORY: +.\" 2005-09-28, created by Arnd Bergmann , +.\" Mark Nutter and +.\" Ulrich Weigand +.\" 2006-06-16, revised by Eduardo M. Fleury +.\" 2007-07-10, quite a lot of polishing by mtk +.\" 2007-09-28, updates for newer kernels by Jeremy Kerr +.\" +.TH spufs 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +spufs \- SPU filesystem +.SH DESCRIPTION +The SPU filesystem is used on PowerPC machines that implement the +Cell Broadband Engine Architecture in order to access Synergistic +Processor Units (SPUs). +.P +The filesystem provides a name space similar to POSIX shared +memory or message queues. +Users that have write permissions +on the filesystem can use +.BR spu_create (2) +to establish SPU contexts under the +.B spufs +root directory. +.P +Every SPU context is represented by a directory containing +a predefined set of files. +These files can be +used for manipulating the state of the logical SPU. +Users can change permissions on the files, but can't +add or remove files. +.SS Mount options +.TP +.B uid= +Set the user owning the mount point; the default is 0 (root). +.TP +.B gid= +Set the group owning the mount point; the default is 0 (root). +.TP +.B mode= +Set the mode of the top-level directory in +.BR spufs , +as an octal mode string. +The default is 0775. +.SS Files +The files in +.B spufs +mostly follow the standard behavior for regular system calls like +.BR read (2) +or +.BR write (2), +but often support only a subset of the operations +supported on regular filesystems. +This list details the supported +operations and the deviations from the standard behavior described +in the respective man pages. +.P +All files that support the +.BR read (2) +operation also support +.BR readv (2) +and all files that support the +.BR write (2) +operation also support +.BR writev (2). +All files support the +.BR access (2) +and +.BR stat (2) +family of operations, but for the latter call, +the only fields of the returned +.I stat +structure that contain reliable information are +.IR st_mode , +.IR st_nlink , +.IR st_uid , +and +.IR st_gid . +.P +All files support the +.BR chmod (2)/\c +.BR fchmod (2) +and +.BR chown (2)/\c +.BR fchown (2) +operations, but will not be able to grant permissions that contradict +the possible operations (e.g., read access on the +.I wbox +file). +.P +The current set of files is: +.TP +.I /capabilities +Contains a comma-delimited string representing the capabilities of this +SPU context. +Possible capabilities are: +.RS +.TP +.B sched +This context may be scheduled. +.TP +.B step +This context can be run in single-step mode, for debugging. +.P +New capabilities flags may be added in the future. +.RE +.TP +.I /mem +the contents of the local storage memory of the SPU. +This can be accessed like a regular shared memory +file and contains both code and data in the address +space of the SPU. +The possible operations on an open +.I mem +file are: +.RS +.TP +.BR read (2) +.TQ +.BR pread (2) +.TQ +.BR write (2) +.TQ +.BR pwrite (2) +.TQ +.BR lseek (2) +These operate as usual, with the exception that +.BR lseek (2), +.BR write (2), +and +.BR pwrite (2) +are not supported beyond the end of the file. +The file size +is the size of the local storage of the SPU, +which is normally 256 kilobytes. +.TP +.BR mmap (2) +Mapping +.I mem +into the process address space provides access to the SPU local +storage within the process address space. +Only +.B MAP_SHARED +mappings are allowed. +.RE +.TP +.I /regs +Contains the saved general-purpose registers of the SPU context. +This file contains the 128-bit values of each register, +from register 0 to register 127, in order. +This allows the general-purpose registers to be +inspected for debugging. +.IP +Reading to or writing from this file requires that the context is +scheduled out, so use of this file is not recommended in normal +program operation. +.IP +The +.I regs +file is not present on contexts that have been created with the +.B SPU_CREATE_NOSCHED +flag. +.TP +.I /mbox +The first SPU-to-CPU communication mailbox. +This file is read-only and can be read in units of 4 bytes. +The file can be used only in nonblocking mode \- even +.BR poll (2) +cannot be used to block on this file. +The only possible operation on an open +.I mbox +file is: +.RS +.TP +.BR read (2) +If +.I count +is smaller than four, +.BR read (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +If there is no data available in the mailbox (i.e., the SPU has not +sent a mailbox message), the return value is set to \-1 and +.I errno +is set to +.BR EAGAIN . +When data +has been read successfully, four bytes are placed in +the data buffer and the value four is returned. +.RE +.TP +.I /ibox +The second SPU-to-CPU communication mailbox. +This file is similar to the first mailbox file, but can be read +in blocking I/O mode, thus calling +.BR read (2) +on an open +.I ibox +file will block until the SPU has written data to its interrupt mailbox +channel (unless the file has been opened with +.BR O_NONBLOCK , +see below). +Also, +.BR poll (2) +and similar system calls can be used to monitor for the presence +of mailbox data. +.IP +The possible operations on an open +.I ibox +file are: +.RS +.TP +.BR read (2) +If +.I count +is smaller than four, +.BR read (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +If there is no data available in the mailbox and the file +descriptor has been opened with +.BR O_NONBLOCK , +the return value is set to \-1 and +.I errno +is set to +.BR EAGAIN . +.IP +If there is no data available in the mailbox and the file +descriptor has been opened without +.BR O_NONBLOCK , +the call will +block until the SPU writes to its interrupt mailbox channel. +When data has been read successfully, four bytes are placed in +the data buffer and the value four is returned. +.TP +.BR poll (2) +Poll on the +.I ibox +file returns +.I "(POLLIN | POLLRDNORM)" +whenever data is available for reading. +.RE +.TP +.I /wbox +The CPU-to-SPU communication mailbox. +It is write-only and can be written in units of four bytes. +If the mailbox is full, +.BR write (2) +will block, and +.BR poll (2) +can be used to block until the mailbox is available for writing again. +The possible operations on an open +.I wbox +file are: +.RS +.TP +.BR write (2) +If +.I count +is smaller than four, +.BR write (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +If there is no space available in the mailbox and the file +descriptor has been opened with +.BR O_NONBLOCK , +the return +value is set to \-1 and +.I errno +is set to +.BR EAGAIN . +.IP +If there is no space available in the mailbox and the file +descriptor has been opened without +.BR O_NONBLOCK , +the call will block until the SPU reads from its +PPE (PowerPC Processing Element) +mailbox channel. +When data has been written successfully, +the system call returns four as its function result. +.TP +.BR poll (2) +A poll on the +.I wbox +file returns +.I "(POLLOUT | POLLWRNORM)" +whenever space is available for writing. +.RE +.TP +.I /mbox_stat +.TQ +.I /ibox_stat +.TQ +.I /wbox_stat +These are read-only files that contain the length of the current +queue of each mailbox\[em]that is, how many words can be read from +.IR mbox " or " ibox +or how many words can be written to +.I wbox +without blocking. +The files can be read only in four-byte units and return +a big-endian binary integer number. +The only possible operation on an open +.I *box_stat +file is: +.RS +.TP +.BR read (2) +If +.I count +is smaller than four, +.BR read (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +Otherwise, a four-byte value is placed in the data buffer. +This value is the number of elements that can be read from (for +.I mbox_stat +and +.IR ibox_stat ) +or written to (for +.IR wbox_stat ) +the respective mailbox without blocking or returning an +.B EAGAIN +error. +.RE +.TP +.I /npc +.TQ +.I /decr +.TQ +.I /decr_status +.TQ +.I /spu_tag_mask +.TQ +.I /event_mask +.TQ +.I /event_status +.TQ +.I /srr0 +.TQ +.I /lslr +Internal registers of the SPU. +These files contain an ASCII string +representing the hex value of the specified register. +Reads and writes on these +files (except for +.IR npc , +see below) require that the SPU context be scheduled out, +so frequent access to +these files is not recommended for normal program operation. +.IP +The contents of these files are: +.RS +.TP 16 +.I npc +Next Program Counter \- valid only when the SPU is in a stopped state. +.TP +.I decr +SPU Decrementer +.TP +.I decr_status +Decrementer Status +.TP +.I spu_tag_mask +MFC tag mask for SPU DMA +.TP +.I event_mask +Event mask for SPU interrupts +.TP +.I event_status +Number of SPU events pending (read-only) +.TP +.I srr0 +Interrupt Return address register +.TP +.I lslr +Local Store Limit Register +.RE +.IP +The possible operations on these files are: +.RS +.TP +.BR read (2) +Reads the current register value. +If the register value is larger than the buffer passed to the +.BR read (2) +system call, subsequent reads will continue reading from the same +buffer, until the end of the buffer is reached. +.IP +When a complete string has been read, all subsequent read operations +will return zero bytes and a new file descriptor needs to be opened +to read a new value. +.TP +.BR write (2) +A +.BR write (2) +operation on the file sets the register to the +value given in the string. +The string is parsed from the beginning +until the first nonnumeric character or the end of the buffer. +Subsequent writes to the same file descriptor overwrite the +previous setting. +.IP +Except for the +.I npc +file, these files are not present on contexts that have been created with +the +.B SPU_CREATE_NOSCHED +flag. +.RE +.TP +.I /fpcr +This file provides access to the Floating Point Status and +Control Register (fcpr) as a binary, four-byte file. +The operations on the +.I fpcr +file are: +.RS +.TP +.BR read (2) +If +.I count +is smaller than four, +.BR read (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +Otherwise, a four-byte value is placed in the data buffer; +this is the current value of the +.I fpcr +register. +.TP +.BR write (2) +If +.I count +is smaller than four, +.BR write (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +Otherwise, a four-byte value is copied from the data buffer, +updating the value of the +.I fpcr +register. +.RE +.TP +.I /signal1 +.TQ +.I /signal2 +The files provide access to the two signal notification channels +of an SPU. +These are read-write files that operate on four-byte words. +Writing to one of these files triggers an interrupt on the SPU. +The value written to the signal files can +be read from the SPU through a channel read or from +host user space through the file. +After the value has been read by the SPU, it is reset to zero. +The possible operations on an open +.I signal1 +or +.I signal2 +file are: +.RS +.TP +.BR read (2) +If +.I count +is smaller than four, +.BR read (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +Otherwise, a four-byte value is placed in the data buffer; +this is the current value of the specified signal notification +register. +.TP +.BR write (2) +If +.I count +is smaller than four, +.BR write (2) +returns \-1 and sets +.I errno +to +.BR EINVAL . +Otherwise, a four-byte value is copied from the data buffer, +updating the value of the specified signal notification +register. +The signal notification register will either be replaced with +the input data or will be updated to the bitwise OR operation +of the old value and the input data, depending on the contents +of the +.I signal1_type +or +.I signal2_type +files respectively. +.RE +.TP +.I /signal1_type +.TQ +.I /signal2_type +These two files change the behavior of the +.I signal1 +and +.I signal2 +notification files. +They contain a numeric ASCII string which is read +as either "1" or "0". +In mode 0 (overwrite), the hardware replaces the contents +of the signal channel with the data that is written to it. +In mode 1 (logical OR), the hardware accumulates the bits +that are subsequently written to it. +The possible operations on an open +.I signal1_type +or +.I signal2_type +file are: +.RS +.TP +.BR read (2) +When the count supplied to the +.BR read (2) +call is shorter than the required length for the digit (plus a newline +character), subsequent reads from the same file descriptor will +complete the string. +When a complete string has been read, all subsequent read operations +will return zero bytes and a new file descriptor needs to be opened +to read the value again. +.TP +.BR write (2) +A +.BR write (2) +operation on the file sets the register to the +value given in the string. +The string is parsed from the beginning +until the first nonnumeric character or the end of the buffer. +Subsequent writes to the same file descriptor overwrite the +previous setting. +.RE +.TP +.I /mbox_info +.TQ +.I /ibox_info +.TQ +.I /wbox_info +.TQ +.I /dma_into +.TQ +.I /proxydma_info +Read-only files that contain the saved state of the SPU mailboxes and +DMA queues. +This allows the SPU status to be inspected, mainly for debugging. +The +.I mbox_info +and +.I ibox_info +files each contain the four-byte mailbox message that has been written +by the SPU. +If no message has been written to these mailboxes, then +contents of these files is undefined. +The +.IR mbox_stat , +.IR ibox_stat , +and +.I wbox_stat +files contain the available message count. +.IP +The +.I wbox_info +file contains an array of four-byte mailbox messages, which have been +sent to the SPU. +With current CBEA machines, the array is four items in +length, so up to 4 * 4 = 16 bytes can be read from this file. +If any mailbox queue entry is empty, +then the bytes read at the corresponding location are undefined. +.IP +The +.I dma_info +file contains the contents of the SPU MFC DMA queue, represented as the +following structure: +.IP +.in +4n +.EX +struct spu_dma_info { + uint64_t dma_info_type; + uint64_t dma_info_mask; + uint64_t dma_info_status; + uint64_t dma_info_stall_and_notify; + uint64_t dma_info_atomic_command_status; + struct mfc_cq_sr dma_info_command_data[16]; +}; +.EE +.in +.IP +The last member of this data structure is the actual DMA queue, +containing 16 entries. +The +.I mfc_cq_sr +structure is defined as: +.IP +.in +4n +.EX +struct mfc_cq_sr { + uint64_t mfc_cq_data0_RW; + uint64_t mfc_cq_data1_RW; + uint64_t mfc_cq_data2_RW; + uint64_t mfc_cq_data3_RW; +}; +.EE +.in +.IP +The +.I proxydma_info +file contains similar information, but describes the proxy DMA queue +(i.e., DMAs initiated by entities outside the SPU) instead. +The file is in the following format: +.IP +.in +4n +.EX +struct spu_proxydma_info { + uint64_t proxydma_info_type; + uint64_t proxydma_info_mask; + uint64_t proxydma_info_status; + struct mfc_cq_sr proxydma_info_command_data[8]; +}; +.EE +.in +.IP +Accessing these files requires that the SPU context is scheduled out - +frequent use can be inefficient. +These files should not be used for normal program operation. +.IP +These files are not present on contexts that have been created with the +.B SPU_CREATE_NOSCHED +flag. +.TP +.I /cntl +This file provides access to the SPU Run Control and SPU status +registers, as an ASCII string. +The following operations are supported: +.RS +.TP +.BR read (2) +Reads from the +.I cntl +file will return an ASCII string with the hex +value of the SPU Status register. +.TP +.BR write (2) +Writes to the +.I cntl +file will set the context's SPU Run Control register. +.RE +.TP +.I /mfc +Provides access to the Memory Flow Controller of the SPU. +Reading from the file returns the contents of the +SPU's MFC Tag Status register, and +writing to the file initiates a DMA from the MFC. +The following operations are supported: +.RS +.TP +.BR write (2) +Writes to this file need to be in the format of a MFC DMA command, +defined as follows: +.IP +.in +4n +.EX +struct mfc_dma_command { + int32_t pad; /* reserved */ + uint32_t lsa; /* local storage address */ + uint64_t ea; /* effective address */ + uint16_t size; /* transfer size */ + uint16_t tag; /* command tag */ + uint16_t class; /* class ID */ + uint16_t cmd; /* command opcode */ +}; +.EE +.in +.IP +Writes are required to be exactly +.I sizeof(struct mfc_dma_command) +bytes in size. +The command will be sent to the SPU's MFC proxy queue, and the +tag stored in the kernel (see below). +.TP +.BR read (2) +Reads the contents of the tag status register. +If the file is opened in blocking mode (i.e., without +.BR O_NONBLOCK ), +then the read will block until a +DMA tag (as performed by a previous write) is complete. +In nonblocking mode, +the MFC tag status register will be returned without waiting. +.TP +.BR poll (2) +Calling +.BR poll (2) +on the +.I mfc +file will block until a new DMA can be +started (by checking for +.BR POLLOUT ) +or until a previously started DMA +(by checking for +.BR POLLIN ) +has been completed. +.IP +.I /mss +Provides access to the MFC MultiSource Synchronization (MSS) facility. +By +.BR mmap (2)-ing +this file, processes can access the MSS area of the SPU. +.IP +The following operations are supported: +.TP +.BR mmap (2) +Mapping +.B mss +into the process address space gives access to the SPU MSS area +within the process address space. +Only +.B MAP_SHARED +mappings are allowed. +.RE +.TP +.I /psmap +Provides access to the whole problem-state mapping of the SPU. +Applications can use this area to interface to the SPU, rather than +writing to individual register files in +.BR spufs . +.IP +The following operations are supported: +.RS +.TP +.BR mmap (2) +Mapping +.B psmap +gives a process a direct map of the SPU problem state area. +Only +.B MAP_SHARED +mappings are supported. +.RE +.TP +.I /phys\-id +Read-only file containing the physical SPU number that the SPU context +is running on. +When the context is not running, this file contains the +string "\-1". +.IP +The physical SPU number is given by an ASCII hex string. +.TP +.I /object\-id +Allows applications to store (or retrieve) a single 64-bit ID into the +context. +This ID is later used by profiling tools to uniquely identify +the context. +.RS +.TP +.BR write (2) +By writing an ASCII hex value into this file, applications can set the +object ID of the SPU context. +Any previous value of the object ID is overwritten. +.TP +.BR read (2) +Reading this file gives an ASCII hex string representing the object ID +for this SPU context. +.RE +.SH EXAMPLES +To automatically +.BR mount (8) +the SPU filesystem when booting, at the location +.I /spu +chosen by the user, put this line into the +.BR fstab (5) +configuration file: +.EX +none /spu spufs gid=spu 0 0 +.EE +.\" .SH AUTHORS +.\" Arnd Bergmann , Mark Nutter , +.\" Ulrich Weigand , Jeremy Kerr +.SH SEE ALSO +.BR close (2), +.BR spu_create (2), +.BR spu_run (2), +.BR capabilities (7) +.P +.I The Cell Broadband Engine Architecture (CBEA) specification diff --git a/man/man7/standards.7 b/man/man7/standards.7 new file mode 100644 index 0000000..1d6efc1 --- /dev/null +++ b/man/man7/standards.7 @@ -0,0 +1,307 @@ +.\" Copyright (c) 2006, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH standards 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +standards \- C and UNIX Standards +.SH DESCRIPTION +The STANDARDS section that appears in many manual pages identifies +various standards to which the documented interface conforms. +The following list briefly describes these standards. +.TP +.B V7 +Version 7 (also known as Seventh Edition) UNIX, +released by AT&T/Bell Labs in 1979. +After this point, UNIX systems diverged into two main dialects: +BSD and System V. +.TP +.B 4.2BSD +This is an implementation standard defined by the 4.2 release +of the +.IR "Berkeley Software Distribution", +released by the University of California at Berkeley. +This was the first Berkeley release that contained a TCP/IP +stack and the sockets API. +4.2BSD was released in 1983. +.IP +Earlier major BSD releases included +.I 3BSD +(1980), +.I 4BSD +(1980), +and +.I 4.1BSD +(1981). +.TP +.B 4.3BSD +The successor to 4.2BSD, released in 1986. +.TP +.B 4.4BSD +The successor to 4.3BSD, released in 1993. +This was the last major Berkeley release. +.TP +.B System V +This is an implementation standard defined by AT&T's milestone 1983 +release of its commercial System V (five) release. +The previous major AT&T release was +.IR "System III" , +released in 1981. +.TP +.B System V release 2 (SVr2) +This was the next System V release, made in 1985. +The SVr2 was formally described in the +.I "System V Interface Definition version 1" +.RI ( "SVID 1" ) +published in 1985. +.TP +.B System V release 3 (SVr3) +This was the successor to SVr2, released in 1986. +This release was formally described in the +.I "System V Interface Definition version 2" +.RI ( "SVID 2" ). +.TP +.B System V release 4 (SVr4) +This was the successor to SVr3, released in 1989. +This version of System V is described in the "Programmer's Reference +Manual: Operating System API (Intel processors)" (Prentice-Hall +1992, ISBN 0-13-951294-2) +This release was formally described in the +.I "System V Interface Definition version 3" +.RI ( "SVID 3" ), +and is considered the definitive System V release. +.TP +.B SVID 4 +System V Interface Definition version 4, issued in 1995. +Available online at +.UR http://www.sco.com\:/developers\:/devspecs/ +.UE . +.TP +.B C89 +This was the first C language standard, ratified by ANSI +(American National Standards Institute) in 1989 +.RI ( X3.159-1989 ). +Sometimes this is known as +.IR "ANSI C" , +but since C99 is also an +ANSI standard, this term is ambiguous. +This standard was also ratified by +ISO (International Standards Organization) in 1990 +.RI ( "ISO/IEC 9899:1990" ), +and is thus occasionally referred to as +.IR "ISO C90" . +.TP +.B C99 +This revision of the C language standard was ratified by ISO in 1999 +.RI ( "ISO/IEC 9899:1999" ). +Available online at +.UR http://www.open\-std.org\:/jtc1\:/sc22\:/wg14\:/www\:/standards +.UE . +.TP +.B C11 +This revision of the C language standard was ratified by ISO in 2011 +.RI ( "ISO/IEC 9899:2011" ). +.TP +.B LFS +The Large File Summit specification, completed in 1996. +This specification defined mechanisms that allowed 32-bit systems +to support the use of large files (i.e., 64-bit file offsets). +See +.UR https://www.opengroup.org\:/platform\:/lfs.html +.UE . +.TP +.B POSIX.1-1988 +This was the first POSIX standard, +ratified by IEEE as IEEE Std 1003.1-1988, +and subsequently adopted (with minor revisions) as an ISO standard in 1990. +The term "POSIX" was coined by Richard Stallman. +.TP +.B POSIX.1-1990 +"Portable Operating System Interface for Computing Environments". +IEEE 1003.1-1990 part 1, ratified by ISO in 1990 +.RI ( "ISO/IEC 9945-1:1990" ). +.TP +.B POSIX.2 +IEEE Std 1003.2-1992, +describing commands and utilities, ratified by ISO in 1993 +.RI ( "ISO/IEC 9945-2:1993" ). +.TP +.BR POSIX.1b " (formerly known as \fIPOSIX.4\fP)" +IEEE Std 1003.1b-1993, +describing real-time facilities +for portable operating systems, ratified by ISO in 1996 +.RI ( "ISO/IEC 9945-1:1996" ). +.TP +.BR POSIX.1c " (formerly known as \fIPOSIX.4a\fP)" +IEEE Std 1003.1c-1995, which describes the POSIX threads interfaces. +.TP +.B POSIX.1d +IEEE Std 1003.1d-1999, which describes additional real-time extensions. +.TP +.B POSIX.1g +IEEE Std 1003.1g-2000, which describes networking APIs (including sockets). +.TP +.B POSIX.1j +IEEE Std 1003.1j-2000, which describes advanced real-time extensions. +.TP +.B POSIX.1-1996 +A 1996 revision of POSIX.1 which incorporated POSIX.1b and POSIX.1c. +.TP +.B XPG3 +Released in 1989, this was the first release of the X/Open +Portability Guide to be based on a POSIX standard (POSIX.1-1988). +This multivolume guide was developed by the X/Open Group, +a multivendor consortium. +.TP +.B XPG4 +A revision of the X/Open Portability Guide, released in 1992. +This revision incorporated POSIX.2. +.TP +.B XPG4v2 +A 1994 revision of XPG4. +This is also referred to as +.IR "Spec 1170" , +where 1170 referred to the number of interfaces +defined by this standard. +.TP +.B "SUS (SUSv1)" +Single UNIX Specification. +This was a repackaging of XPG4v2 and other X/Open standards +(X/Open Curses Issue 4 version 2, +X/Open Networking Service (XNS) Issue 4). +Systems conforming to this standard can be branded +.IR "UNIX 95" . +.TP +.B SUSv2 +Single UNIX Specification version 2. +Sometimes also referred to (incorrectly) as +.IR XPG5 . +This standard appeared in 1997. +Systems conforming to this standard can be branded +.IR "UNIX 98" . +See also +.UR http://www.unix.org\:/version2/ +.UE .) +.TP +.B POSIX.1-2001 +.TQ +.B SUSv3 +This was a 2001 revision and consolidation of the +POSIX.1, POSIX.2, and SUS standards into a single document, +conducted under the auspices of the Austin Group +.UR http://www.opengroup.org\:/austin/ +.UE . +The standard is available online at +.UR http://www.unix.org\:/version3/ +.UE . +.IP +The standard defines two levels of conformance: +.IR "POSIX conformance" , +which is a baseline set of interfaces required of a conforming system; +and +.IR "XSI Conformance", +which additionally mandates a set of interfaces +(the "XSI extension") which are only optional for POSIX conformance. +XSI-conformant systems can be branded +.IR "UNIX 03" . +.IP +The POSIX.1-2001 document is broken into four parts: +.IP +.BR XBD : +Definitions, terms, and concepts, header file specifications. +.IP +.BR XSH : +Specifications of functions (i.e., system calls and library +functions in actual implementations). +.IP +.BR XCU : +Specifications of commands and utilities +(i.e., the area formerly described by POSIX.2). +.IP +.BR XRAT : +Informative text on the other parts of the standard. +.IP +POSIX.1-2001 is aligned with C99, so that all of the +library functions standardized in C99 are also +standardized in POSIX.1-2001. +.IP +The Single UNIX Specification version 3 (SUSv3) comprises the +Base Specifications containing XBD, XSH, XCU, and XRAT as above, +plus X/Open Curses Issue 4 version 2 as an extra volume that is +not in POSIX.1-2001. +.IP +Two Technical Corrigenda (minor fixes and improvements) +of the original 2001 standard have occurred: +TC1 in 2003 +and TC2 in 2004. +.TP +.B POSIX.1-2008 +.TQ +.B SUSv4 +Work on the next revision of POSIX.1/SUS was completed and +ratified in 2008. +The standard is available online at +.UR http://www.unix.org\:/version4/ +.UE . +.IP +The changes in this revision are not as large as those +that occurred for POSIX.1-2001/SUSv3, +but a number of new interfaces are added +and various details of existing specifications are modified. +Many of the interfaces that were optional in +POSIX.1-2001 become mandatory in the 2008 revision of the standard. +A few interfaces that are present in POSIX.1-2001 are marked +as obsolete in POSIX.1-2008, or removed from the standard altogether. +.IP +The revised standard is structured in the same way as its predecessor. +The Single UNIX Specification version 4 (SUSv4) comprises the +Base Specifications containing XBD, XSH, XCU, and XRAT, +plus X/Open Curses Issue 7 as an extra volume that is +not in POSIX.1-2008. +.IP +Again there are two levels of conformance: the baseline +.IR "POSIX Conformance" , +and +.IR "XSI Conformance" , +which mandates an additional set of interfaces +beyond those in the base specification. +.IP +In general, where the STANDARDS section of a manual page +lists POSIX.1-2001, it can be assumed that the interface also +conforms to POSIX.1-2008, unless otherwise noted. +.IP +Technical Corrigendum 1 (minor fixes and improvements) +of this standard was released in 2013. +.IP +Technical Corrigendum 2 of this standard was released in 2016. +.IP +Further information can be found on the Austin Group web site, +.UR http://www.opengroup.org\:/austin/ +.UE . +.TP +.B SUSv4 2016 edition +This is equivalent to POSIX.1-2008, with the addition of +Technical Corrigenda 1 and 2 and the XCurses specification. +.TP +.B POSIX.1-2017 +This revision of POSIX is technically identical to POSIX.1-2008 with +Technical Corrigenda 1 and 2 applied. +.TP +.B SUSv4 2018 edition +This is equivalent to POSIX.1-2017, with the addition of +the XCurses specification. +.P +The interfaces documented in POSIX.1/SUS are available as +manual pages under sections 0p (header files), 1p (commands), +and 3p (functions); +thus one can write "man 3p open". +.SH SEE ALSO +.BR getconf (1), +.BR confstr (3), +.BR pathconf (3), +.BR sysconf (3), +.BR attributes (7), +.BR feature_test_macros (7), +.BR libc (7), +.BR posixoptions (7), +.BR system_data_types (7) diff --git a/man/man7/string_copying.7 b/man/man7/string_copying.7 new file mode 100644 index 0000000..843b2cb --- /dev/null +++ b/man/man7/string_copying.7 @@ -0,0 +1,809 @@ +.\" Copyright 2022 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.TH string_copying 7 2024-05-14 "Linux man-pages (unreleased)" +.\" ----- NAME :: -----------------------------------------------------/ +.SH NAME +stpcpy, +strcpy, strcat, +stpecpy, +strtcpy, +strlcpy, strlcat, +stpncpy, +strncpy, +strncat +\- copying strings and character sequences +.\" ----- SYNOPSIS :: -------------------------------------------------/ +.SH SYNOPSIS +.\" ----- SYNOPSIS :: (Null-terminated) strings -----------------------/ +.SS Strings +.nf +// Chain-copy a string. +.BI "char *stpcpy(char *restrict " dst ", const char *restrict " src ); +.P +// Copy/catenate a string. +.BI "char *strcpy(char *restrict " dst ", const char *restrict " src ); +.BI "char *strcat(char *restrict " dst ", const char *restrict " src ); +.P +// Chain-copy a string with truncation. +.BI "char *stpecpy(char *" dst ", char " end "[0], const char *restrict " src ); +.P +// Copy/catenate a string with truncation. +.BI "ssize_t strtcpy(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.BI "size_t strlcpy(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.BI "size_t strlcat(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.fi +.\" ----- SYNOPSIS :: Null-padded character sequences --------/ +.SS Null-padded character sequences +.nf +// Fill a fixed-size buffer with characters from a string +// and pad with null bytes. +.BI "char *strncpy(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.BI "char *stpncpy(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); +.P +// Chain-copy a null-padded character sequence into a character sequence. +.I mempcpy(dst, src, strnlen(src, NITEMS(src))); +.P +// Chain-copy a null-padded character sequence into a string. +.I stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), \[dq]\[dq]); +.P +// Catenate a null-padded character sequence into a string. +.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." ssize ], +.BI " size_t " ssize ); +.P +// Duplicate a null-padded character sequence into a string. +.BI "char *strndup(const char " src [. ssize "], size_t " ssize ); +.fi +.\" ----- SYNOPSIS :: Known-length character sequences --------------------/ +.SS Known-length character sequences +.nf +// Chain-copy a known-length character sequence. +.BI "void *mempcpy(void " dst "[restrict ." len "], \ +const void " src "[restrict ." len ], +.BI " size_t " len ); +.P +// Chain-copy a known-length character sequence into a string. +.I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]); +.fi +.SH DESCRIPTION +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: -----------------/ +.SS Terms (and abbreviations) +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: string (str) ----/ +.TP +.IR "string " ( str ) +is a sequence of zero or more non-null characters followed by a null character. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: null-padded character seq +.TP +.I character sequence +is a sequence of zero or more non-null characters. +A program should never use a character sequence where a string is required. +However, with appropriate care, +a string can be used in the place of a character sequence. +.RS +.TP +.I null-padded character sequence +Character sequences can be contained in fixed-size buffers, +which contain padding null bytes after the character sequence, +to fill the rest of the buffer +without affecting the character sequence; +however, those padding null bytes are not part of the character sequence. +Don't confuse null-padded with null-terminated: +null-padded means 0 or more padding null bytes, +while null-terminated means exactly 1 terminating null character. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: known-length character sequence +.TP +.I known-length character sequence +Character sequence delimited by its length. +It may be a slice of a larger character sequence, +or even of a string. +.RE +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: length (len) ----/ +.TP +.IR "length " ( len ) +is the number of non-null characters in a string or character sequence. +It is the return value of +.I strlen(str) +and of +.IR "strnlen(buf, size)" . +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: size ------------/ +.TP +.I size +refers to the entire buffer +where the string or character sequence is contained. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: end -------------/ +.TP +.I end +is the name of a pointer to one past the last element of a buffer. +It is equivalent to +.IR &str[size] . +It is used as a sentinel value, +to be able to truncate strings or character sequences +instead of overrunning the containing buffer. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: copy ------------/ +.TP +.I copy +This term is used when +the writing starts at the first element pointed to by +.IR dst . +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: catenate --------/ +.TP +.I catenate +This term is used when +a function first finds the terminating null character in +.IR dst , +and then starts writing at that position. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: chain -----------/ +.TP +.I chain +This term is used when +it's the programmer who provides +a pointer to the terminating null character in the string +.I dst +(or one after the last character in a character sequence), +and the function starts writing at that location. +The function returns +a pointer to the new location of the terminating null character +(or one after the last character in a character sequence) +after the call, +so that the programmer can use it to chain such calls. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: duplicate -------/ +.TP +.I duplicate +Allocate a new buffer +where a copy is placed. +.\" ----- DESCRIPTION :: Copy, catenate, and chain-copy ---------------/ +.SS Copy, catenate, and chain-copy +Originally, +there was a distinction between functions that copy and those that catenate. +However, newer functions that copy while allowing chaining +cover both use cases with a single API. +They are also algorithmically faster, +since they don't need to search for +the terminating null character of the existing string. +However, functions that catenate have a much simpler use, +so if performance is not important, +it can make sense to use them for improving readability. +.P +The pointer returned by functions that allow chaining +is a byproduct of the copy operation, +so it has no performance costs. +Functions that return such a pointer, +and thus can be chained, +have names of the form +.RB * stp *(), +since it's common to name the pointer just +.IR p . +.P +Chain-copying functions that truncate +should accept a pointer to the end of the destination buffer, +and have names of the form +.RB * stpe *(). +This allows not having to recalculate the remaining size after each call. +.\" ----- DESCRIPTION :: Truncate or not? -----------------------------/ +.SS Truncate or not? +The first thing to note is that programmers should be careful with buffers, +so they always have the correct size, +and truncation is not necessary. +.P +In most cases, +truncation is not desired, +and it is simpler to just do the copy. +Simpler code is safer code. +Programming against programming mistakes by adding more code +just adds more points where mistakes can be made. +.P +Nowadays, +compilers can detect most programmer errors with features like +compiler warnings, +static analyzers, and +.B \%_FORTIFY_SOURCE +(see +.BR ftm (7)). +Keeping the code simple +helps these overflow-detection features be more precise. +.P +When validating user input, +code should normally not truncate, +but instead fail and prevent the copy at all. +.P +In some cases, +however, +it makes sense to truncate. +.P +Functions that truncate: +.IP \[bu] 3 +.BR stpecpy () +.IP \[bu] +.BR strtcpy () +.IP \[bu] +.BR strlcpy (3bsd) +and +.BR strlcat (3bsd) +are similar, but have important performance problems; see BUGS. +.IP \[bu] +.BR stpncpy (3) +and +.BR strncpy (3) +also truncate, but they don't write strings, +but rather null-padded character sequences. +.\" ----- DESCRIPTION :: Null-padded character sequences --------------/ +.SS Null-padded character sequences +For historic reasons, +some standard APIs and file formats, +such as +.BR utmpx (5) +and +.BR tar (1), +use null-padded character sequences in fixed-size buffers. +To interface with them, +specialized functions need to be used. +.P +To copy bytes from strings into these buffers, use +.BR strncpy (3) +or +.BR stpncpy (3). +.P +To read a null-padded character sequence, +use +.IR "strnlen(src,\ NITEMS(src))" , +and then you can treat it as a known-length character sequence; +or use +.BR strncat (3) +or +.BR strndup (3) +directly. +.\" ----- DESCRIPTION :: Known-length character sequences -----------------/ +.SS Known-length character sequences +The simplest character sequence copying function is +.BR mempcpy (3). +It requires always knowing the length of your character sequences, +for which structures can be used. +It makes the code much faster, +since you always know the length of your character sequences, +and can do the minimal copies and length measurements. +.BR mempcpy (3) +copies character sequences, +so you need to explicitly set the terminating null character +if you need a string. +.P +In programs that make considerable use of strings or character sequences, +and need the best performance, +using overlapping character sequences can make a big difference. +It allows holding subsequences of a larger character sequence, +while not duplicating memory +nor using time to do a copy. +.P +However, this is delicate, +since it requires using character sequences. +C library APIs use strings, +so programs that use character sequences +will have to take care of differentiating strings from character sequences. +.P +To copy a known-length character sequence, use +.BR mempcpy (3). +.P +To copy a known-length character sequence into a string, use +.IR "\%stpcpy(mempcpy(dst,\ src,\ len),\ \[dq]\[dq])" . +.P +A string is also accepted as input, +because +.BR mempcpy (3) +asks for the length, +and a string is composed of a character sequence of the same length +plus a terminating null character. +.\" ----- DESCRIPTION :: String vs character sequence -----------------/ +.SS String vs character sequence +Some functions only operate on strings. +Those require that the input +.I src +is a string, +and guarantee an output string +(even when truncation occurs). +Functions that catenate +also require that +.I dst +holds a string before the call. +List of functions: +.IP \[bu] 3 +.PD 0 +.BR stpcpy (3) +.IP \[bu] +.BR strcpy (3), +.BR strcat (3) +.IP \[bu] +.BR stpecpy () +.IP \[bu] +.BR strtcpy () +.IP \[bu] +.BR strlcpy (3bsd), +.BR strlcat (3bsd) +.PD +.P +Other functions require an input string, +but create a character sequence as output. +These functions have confusing names, +and have a long history of misuse. +List of functions: +.IP \[bu] 3 +.PD 0 +.BR stpncpy (3) +.IP \[bu] +.BR strncpy (3) +.PD +.P +Other functions operate on an input character sequence, +and create an output string. +Functions that catenate +also require that +.I dst +holds a string before the call. +.BR strncat (3) +has an even more misleading name than the functions above. +List of functions: +.IP \[bu] 3 +.PD 0 +.BR strncat (3) +.IP \[bu] +.BR strndup (3) +.PD +.P +Other functions operate on an input character sequence +to create an output character sequence. +List of functions: +.IP \[bu] 3 +.BR mempcpy (3) +.\" ----- DESCRIPTION :: Functions :: ---------------------------------/ +.SS Functions +.\" ----- DESCRIPTION :: Functions :: stpcpy(3) -----------------------/ +.TP +.BR stpcpy (3) +Copy the input string into a destination string. +The programmer is responsible for allocating a buffer large enough. +It returns a pointer suitable for chaining. +.\" ----- DESCRIPTION :: Functions :: strcpy(3), strcat(3) ------------/ +.TP +.BR strcpy (3) +.TQ +.BR strcat (3) +Copy and catenate the input string into a destination string. +The programmer is responsible for allocating a buffer large enough. +The return value is useless. +.IP +.BR stpcpy (3) +is a faster alternative to these functions. +.\" ----- DESCRIPTION :: Functions :: stpecpy() -----------------------/ +.TP +.BR stpecpy () +Chain-copy the input string into a destination string. +If the destination buffer, +limited by a pointer to its end, +isn't large enough to hold the copy, +the resulting string is truncated +(but it is guaranteed to be null-terminated). +It returns a pointer suitable for chaining. +Truncation needs to be detected only once after the last chained call. +.IP +This function is not provided by any library; +see EXAMPLES for a reference implementation. +.\" ----- DESCRIPTION :: Functions :: strtcpy() -----------------------/ +.TP +.BR strtcpy () +Copy the input string into a destination string. +If the destination buffer isn't large enough to hold the copy, +the resulting string is truncated +(but it is guaranteed to be null-terminated). +It returns the length of the string, +or \-1 if it truncated. +.IP +This function is not provided by any library; +see EXAMPLES for a reference implementation. +.\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/ +.TP +.BR strlcpy (3bsd) +.TQ +.BR strlcat (3bsd) +Copy and catenate the input string into a destination string. +If the destination buffer, +limited by its size, +isn't large enough to hold the copy, +the resulting string is truncated +(but it is guaranteed to be null-terminated). +They return the length of the total string they tried to create. +.IP +Check BUGS before using these functions. +.IP +.BR strtcpy () +and +.BR stpecpy () +are better alternatives to these functions. +.\" ----- DESCRIPTION :: Functions :: stpncpy(3) ----------------------/ +.TP +.BR stpncpy (3) +Copy the input string into +a destination null-padded character sequence in a fixed-size buffer. +If the destination buffer, +limited by its size, +isn't large enough to hold the copy, +the resulting character sequence is truncated. +Since it creates a character sequence, +it doesn't need to write a terminating null character. +It's impossible to distinguish truncation by the result of the call, +from a character sequence that just fits the destination buffer; +truncation should be detected by +comparing the length of the input string +with the size of the destination buffer. +.\" ----- DESCRIPTION :: Functions :: strncpy(3) ----------------------/ +.TP +.BR strncpy (3) +This function is identical to +.BR stpncpy (3) +except for the useless return value. +.IP +.BR stpncpy (3) +is a more useful alternative to this function. +.\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ +.TP +.BR strncat (3) +Catenate the input character sequence, +contained in a null-padded fixed-size buffer, +into a destination string. +The programmer is responsible for allocating a buffer large enough. +The return value is useless. +.IP +Do not confuse this function with +.BR strncpy (3); +they are not related at all. +.IP +.I \%stpcpy(mempcpy(dst,\ src,\ strnlen(src,\ NITEMS(src))),\ \[dq]\[dq]) +is a faster alternative to this function. +.\" ----- DESCRIPTION :: Functions :: strndup(3) ----------------------/ +.TP +.BR strndup (3) +Duplicate the input character sequence, +contained in a null-padded fixed-size buffer, +into a newly allocated destination string. +.IP +The string must be freed with +.BR free (3). +.\" ----- DESCRIPTION :: Functions :: mempcpy(3) ----------------------/ +.TP +.BR mempcpy (3) +Copy the input character sequence, +limited by its length, +into a destination character sequence. +The programmer is responsible for allocating a buffer large enough. +It returns a pointer suitable for chaining. +.\" ----- RETURN VALUE :: ---------------------------------------------/ +.SH RETURN VALUE +.TP +.BR stpcpy (3) +A pointer to the terminating null character in the destination string. +.TP +.BR stpecpy () +A pointer to the terminating null character in the destination string, +on success. +On error, +NULL is returned, +and +.I errno +is set to indicate the error. +.TP +.BR mempcpy (3) +.TQ +.BR stpncpy (3) +A pointer to one after the last character +in the destination character sequence. +.TP +.BR strtcpy () +The length of the string, +on success. +On error, +\-1 is returned, +and +.I errno +is set to indicate the error. +.TP +.BR strlcpy (3bsd) +.TQ +.BR strlcat (3bsd) +The length of the total string that they tried to create +(as if truncation didn't occur). +.TP +.BR strcpy (3) +.TQ +.BR strcat (3) +.TQ +.BR strncpy (3) +.TQ +.BR strncat (3) +The +.I dst +pointer, +which is useless. +.TP +.BR strndup (3) +The newly allocated string. +.\" ----- ERRORS ------------------------------------------------------/ +.SH ERRORS +Most of these functions don't set +.IR errno . +.TP +.BR stpecpy () +.TQ +.BR strtcpy () +.RS +.TP +.B ENOBUFS +.I dsize +was +.BR 0 . +.TP +.B E2BIG +The string has been truncated. +.RE +.TP +.BR strndup (3) +.RS +.TP +.B ENOMEM +Insufficient memory available to allocate duplicate string. +.RE +.\" ----- NOTES :: strscpy(9) -----------------------------------------/ +.SH NOTES +The Linux kernel has an internal function for copying strings, +.BR strscpy (9), +which is identical to +.BR strtcpy (), +except that it returns +.B \-E2BIG +instead of \-1 +and it doesn't set +.IR errno . +.\" ----- CAVEATS :: --------------------------------------------------/ +.SH CAVEATS +Don't mix chain calls to truncating and non-truncating functions. +It is conceptually wrong +unless you know that the first part of a copy will always fit. +Anyway, the performance difference will probably be negligible, +so it will probably be more clear if you use consistent semantics: +either truncating or non-truncating. +Calling a non-truncating function after a truncating one is necessarily wrong. +.\" ----- BUGS :: -----------------------------------------------------/ +.SH BUGS +All catenation functions share the same performance problem: +.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ +Shlemiel the painter +.UE . +As a mitigation, +compilers are able to transform some calls to catenation functions +into normal copy functions, +since +.I strlen(dst) +is usually a byproduct of the previous copy. +.P +.BR strlcpy (3) +and +.BR strlcat (3) +need to read the entire +.I src +string, +even if the destination buffer is small. +This makes them vulnerable to Denial of Service (DoS) attacks +if an attacker can control the length of the +.I src +string. +And if not, +they're still unnecessarily slow. +.\" ----- EXAMPLES :: -------------------------------------------------/ +.SH EXAMPLES +The following are examples of correct use of each of these functions. +.\" ----- EXAMPLES :: stpcpy(3) ---------------------------------------/ +.TP +.BR stpcpy (3) +.EX +p = buf; +p = stpcpy(p, "Hello "); +p = stpcpy(p, "world"); +p = stpcpy(p, "!"); +len = p \- buf; +puts(buf); +.EE +.\" ----- EXAMPLES :: strcpy(3), strcat(3) ----------------------------/ +.TP +.BR strcpy (3) +.TQ +.BR strcat (3) +.EX +strcpy(buf, "Hello "); +strcat(buf, "world"); +strcat(buf, "!"); +len = strlen(buf); +puts(buf); +.EE +.\" ----- EXAMPLES :: stpecpy() ---------------------------------------/ +.TP +.BR stpecpy () +.EX +end = buf + NITEMS(buf); +p = buf; +p = stpecpy(p, end, "Hello "); +p = stpecpy(p, end, "world"); +p = stpecpy(p, end, "!"); +if (p == NULL) { + len = NITEMS(buf) \- 1; + goto toolong; +} +len = p \- buf; +puts(buf); +.EE +.\" ----- EXAMPLES :: strtcpy() ---------------------------------------/ +.TP +.BR strtcpy () +.EX +len = strtcpy(buf, "Hello world!", NITEMS(buf)); +if (len == \-1) + goto toolong; +puts(buf); +.EE +.\" ----- EXAMPLES :: strlcpy(3bsd), strlcat(3bsd) --------------------/ +.TP +.BR strlcpy (3bsd) +.TQ +.BR strlcat (3bsd) +.EX +if (strlcpy(buf, "Hello ", NITEMS(buf)) >= NITEMS(buf)) + goto toolong; +if (strlcat(buf, "world", NITEMS(buf)) >= NITEMS(buf)) + goto toolong; +len = strlcat(buf, "!", NITEMS(buf)); +if (len >= NITEMS(buf)) + goto toolong; +puts(buf); +.EE +.\" ----- EXAMPLES :: stpncpy(3) --------------------------------------/ +.TP +.BR stpncpy (3) +.EX +p = stpncpy(u->ut_user, "alx", NITEMS(u->ut_user)); +if (NITEMS(u->ut_user) < strlen("alx")) + goto toolong; +len = p \- u->ut_user; +fwrite(u->ut_user, 1, len, stdout); +.EE +.\" ----- EXAMPLES :: strncpy(3) --------------------------------------/ +.TP +.BR strncpy (3) +.EX +strncpy(u->ut_user, "alx", NITEMS(u->ut_user)); +if (NITEMS(u->ut_user) < strlen("alx")) + goto toolong; +len = strnlen(u->ut_user, NITEMS(u->ut_user)); +fwrite(u->ut_user, 1, len, stdout); +.EE +.\" ----- EXAMPLES :: mempcpy(dst, src, strnlen(src, NITEMS(src))) ----/ +.TP +.I mempcpy(dst, src, strnlen(src, NITEMS(src))) +.EX +char buf[NITEMS(u->ut_user)]; +p = buf; +p = mempcpy(p, u->ut_user, strnlen(u->ut_user, NITEMS(u->ut_user))); +len = p \- buf; +fwrite(buf, 1, len, stdout); +.EE +.\" ----- EXAMPLES :: stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), "") +.TP +.I stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), \[dq]\[dq]) +.EX +char buf[NITEMS(u->ut_user) + 1]; +p = buf; +p = mempcpy(p, u->ut_user, strnlen(u->ut_user, NITEMS(u->ut_user))); +p = stpcpy(p, ""); +len = p \- buf; +puts(buf); +.EE +.\" ----- EXAMPLES :: strncat(3) --------------------------------------/ +.TP +.BR strncat (3) +.EX +char buf[NITEMS(u->ut_user) + 1]; +strcpy(buf, ""); +strncat(buf, u->ut_user, NITEMS(u->ut_user)); +len = strlen(buf); +puts(buf); +.EE +.\" ----- EXAMPLES :: strndup(3) --------------------------------------/ +.TP +.BR strndup (3) +.EX +buf = strndup(u->ut_user, NITEMS(u->ut_user)); +len = strlen(buf); +puts(buf); +free(buf); +.EE +.\" ----- EXAMPLES :: mempcpy(3) --------------------------------------/ +.TP +.BR mempcpy (3) +.EX +p = buf; +p = mempcpy(p, "Hello ", 6); +p = mempcpy(p, "world", 5); +p = mempcpy(p, "!", 1); +len = p \- buf; +fwrite(buf, 1, len, stdout); +.EE +.\" ----- EXAMPLES :: stpcpy(mempcpy(), "") ---------------------------/ +.TP +.I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]) +.EX +p = buf; +p = mempcpy(p, "Hello ", 6); +p = mempcpy(p, "world", 5); +p = mempcpy(p, "!", 1); +p = stpcpy(p, ""); +len = p \- buf; +puts(buf); +.EE +.\" ----- EXAMPLES :: Implementations :: ------------------------------/ +.SS Implementations +Here are reference implementations for functions not provided by libc. +.P +.in +4n +.EX +/* This code is in the public domain. */ +\& +.\" ----- EXAMPLES :: Implementations :: stpecpy() --------------------/ +char * +.IR stpecpy "(char *dst, char end[0], const char *restrict src)" +{ + size_t dlen; +\& + if (dst == NULL) + return NULL; +\& + dlen = strtcpy(dst, src, end \- dst); + return (dlen == \-1) ? NULL : dst + dlen; +} +\& +.\" ----- EXAMPLES :: Implementations :: strtcpy() --------------------/ +ssize_t +.IR strtcpy "(char *restrict dst, const char *restrict src, size_t dsize)" +{ + bool trunc; + size_t dlen, slen; +\& + if (dsize == 0) { + errno = ENOBUFS; + return \-1; + } +\& + slen = strnlen(src, dsize); + trunc = (slen == dsize); + dlen = slen \- trunc; +\& + stpcpy(mempcpy(dst, src, dlen), ""); + if (trunc) + errno = E2BIG; + return trunc ? \-1 : slen; +} +.\" ----- SEE ALSO :: -------------------------------------------------/ +.SH SEE ALSO +.BR bzero (3), +.BR memcpy (3), +.BR memccpy (3), +.BR mempcpy (3), +.BR stpcpy (3), +.BR strlcpy (3bsd), +.BR strncat (3), +.BR stpncpy (3), +.BR string (3) diff --git a/man/man7/suffixes.7 b/man/man7/suffixes.7 new file mode 100644 index 0000000..7f09cf7 --- /dev/null +++ b/man/man7/suffixes.7 @@ -0,0 +1,265 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 17:35:15 1993 by Rik Faith +.\" Modified Sun Feb 19 22:02:32 1995 by Rik Faith +.\" Modified Tue Oct 22 23:28:12 1996 by Eric S. Raymond +.\" Modified Sun Jan 26 21:56:56 1997 by Ralph Schleicher +.\" +.\" Modified Mon Jun 16 20:24:58 1997 by Nicolás Lichtmaier +.\" Modified Sun Oct 18 22:11:28 1998 by Joseph S. Myers +.\" Modified Mon Nov 16 17:24:47 1998 by Andries Brouwer +.\" Modified Thu Nov 16 23:28:25 2000 by David A. Wheeler +.\" +.\" +.TH SUFFIXES 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +suffixes \- list of file suffixes +.SH DESCRIPTION +It is customary to indicate the contents of a file with the file suffix, +which (typically) consists of a period, followed by one or more letters. +Many standard utilities, such as compilers, use this to recognize the type of +file they are dealing with. +The +.BR make (1) +utility is driven by rules based on file suffix. +.P +Following is a list of suffixes which are likely to be found on a +Linux system. +.P +.TS +l | l +_ | _ +lI | l . +Suffix File type +\&,v files for RCS (Revision Control System) +\&- backup file +\&.C C++ source code, equivalent to \fI.cc\fP +\&.F Fortran source with \fBcpp\fP(1) directives +\& or file compressed using freeze +\&.S assembler source with \fBcpp\fP(1) directives +\&.Y file compressed using yabba +\&.Z file compressed using \fBcompress\fP(1) +\&.[0\-9]+gf TeX generic font files +\&.[0\-9]+pk TeX packed font files +\&.[1\-9] manual page for the corresponding section +\&.[1\-9][a-z] manual page for section plus subsection +\&.a static object code library +\&.ad X application default resource file +\&.ada Ada source (may be body, spec, or combination) +\&.adb Ada body source +\&.ads Ada spec source +\&.afm PostScript font metrics +\&.al Perl autoload file +\&.am \fBautomake\fP(1) input file +\&.arc \fBarc\fP(1) archive +\&.arj \fBarj\fP(1) archive +\&.asc PGP ASCII-armored data +\&.asm (GNU) assembler source file +\&.au Audio sound file +\&.aux LaTeX auxiliary file +\&.avi (msvideo) movie +\&.awk AWK language program +\&.b LILO boot loader image +\&.bak backup file +\&.bash \fBbash\fP(1) shell script +\&.bb basic block list data produced by +\& gcc \-ftest\-coverage +\&.bbg basic block graph data produced by +\& gcc \-ftest\-coverage +\&.bbl BibTeX output +\&.bdf X font file +\&.bib TeX bibliographic database, BibTeX input +\&.bm bitmap source +\&.bmp bitmap +\&.bz2 file compressed using \fBbzip2\fP(1) +\&.c C source +\&.cat message catalog files +\&.cc C++ source +\&.cf configuration file +\&.cfg configuration file +\&.cgi WWW content generating script or program +\&.cls LaTeX Class definition +\&.class Java compiled byte-code +\&.conf configuration file +\&.config configuration file +\&.cpp equivalent to \fI.cc\fR +\&.csh \fBcsh\fP(1) shell script +\&.cxx equivalent to \fI.cc\fR +\&.dat data file +\&.deb Debian software package +\&.def Modula-2 source for definition modules +\&.def other definition files +\&.desc initial part of mail message unpacked with +\& \fBmunpack\fP(1) +\&.diff file differences (\fBdiff\fP(1) command output) +\&.dir dbm data base directory file +\&.doc documentation file +\&.dsc Debian Source Control (source package) +\&.dtx LaTeX package source file +\&.dvi TeX's device independent output +\&.el Emacs-Lisp source +\&.elc compiled Emacs-Lisp source +\&.eps encapsulated PostScript +\&.exp Expect source code +\&.f Fortran source +\&.f77 Fortran 77 source +\&.f90 Fortran 90 source +\&.fas precompiled Common-Lisp +\&.fi Fortran include files +\&.fig FIG image file (used by \fBxfig\fP(1)) +\&.fmt TeX format file +\&.gif Compuserve Graphics Image File format +\&.gmo GNU format message catalog +\&.gsf Ghostscript fonts +\&.gz file compressed using \fBgzip\fP(1) +\&.h C or C++ header files +\&.help help file +\&.hf equivalent to \fI.help\fP +\&.hlp equivalent to \fI.help\fP +\&.htm poor man's \fI.html\fP +\&.html HTML document used with the World Wide Web +\&.hqx 7-bit encoded Macintosh file +\&.i C source after preprocessing +\&.icon bitmap source +\&.idx reference or datum-index file for hypertext +\& or database system +\&.image bitmap source +\&.in configuration template, especially for GNU Autoconf +\&.info files for the Emacs info browser +\&.info-[0\-9]+ split info files +\&.ins LaTeX package install file for docstrip +\&.itcl itcl source code; +\& itcl ([incr Tcl]) is an OO extension of tcl +\&.java a Java source file +\&.jpeg Joint Photographic Experts Group format +\&.jpg poor man's \fI.jpeg\fP +\&.js JavaScript source code +\&.jsx JSX (JavaScript XML-like extension) source code +\&.kmap \fBlyx\fP(1) keymap +\&.l equivalent to \fI.lex\fP or \fI.lisp\fP +\&.lex \fBlex\fP(1) or \fBflex\fP(1) files +\&.lha lharc archive +\&.lib Common-Lisp library +\&.lisp Lisp source +\&.ln files for use with \fBlint\fP(1) +\&.log log file, in particular produced by TeX +\&.lsm Linux Software Map entry +\&.lsp Common-Lisp source +\&.lzh lharc archive +\&.m Objective-C source code +\&.m4 \fBm4\fP(1) source +\&.mac macro files for various programs +\&.man manual page (usually source rather than formatted) +\&.map map files for various programs +\&.me Nroff source using the me macro package +\&.mf Metafont (font generator for TeX) source +\&.mgp MagicPoint file +\&.mm sources for \fBgroff\fP(1) in mm - format +\&.mo Message catalog binary file +\&.mod Modula-2 source for implementation modules +\&.mov (quicktime) movie +\&.mp Metapost source +\&.mp2 MPEG Layer 2 (audio) file +\&.mp3 MPEG Layer 3 (audio) file +\&.mpeg movie file +\&.o object file +\&.old old or backup file +\&.orig backup (original) version of a file, from \fBpatch\fP(1) +\&.out output file, often executable program (a.out) +\&.p Pascal source +\&.pag dbm data base data file +\&.patch file differences for \fBpatch\fP(1) +\&.pbm portable bitmap format +\&.pcf X11 font files +\&.pdf Adobe Portable Data Format +\& (use Acrobat/\fBacroread\fP or \fBxpdf\fP) +\&.perl Perl source (see .ph, .pl, and .pm) +\&.pfa PostScript font definition files, ASCII format +\&.pfb PostScript font definition files, binary format +\&.pgm portable greymap format +\&.pgp PGP binary data +\&.ph Perl header file +\&.php PHP program file +\&.php3 PHP3 program file +\&.pid File to store daemon PID (e.g., crond.pid) +\&.pl TeX property list file or Perl library file +\&.pm Perl module +\&.png Portable Network Graphics file +\&.po Message catalog source +\&.pod \fBperldoc\fP(1) file +\&.ppm portable pixmap format +\&.pr bitmap source +\&.ps PostScript file +\&.py Python source +\&.pyc compiled python +\&.qt quicktime movie +\&.r RATFOR source (obsolete) +\&.rej patches that \fBpatch\fP(1) couldn't apply +\&.rpm RPM software package +\&.rtf Rich Text Format file +\&.rules rules for something +\&.s assembler source +\&.sa stub libraries for a.out shared libraries +\&.sc \fBsc\fP(1) spreadsheet commands +\&.scm Scheme source code +\&.sed sed source file +\&.sgml SGML source file +\&.sh \fBsh\fP(1) scripts +\&.shar archive created by the \fBshar\fP(1) utility +\&.shtml HTML using Server Side Includes +\&.so Shared library or dynamically loadable object +\&.sql SQL source +\&.sqml SQML schema or query program +\&.sty LaTeX style files +\&.sym Modula-2 compiled definition modules +\&.tar archive created by the \fBtar\fP(1) utility +\&.tar.Z tar(1) archive compressed with \fBcompress\fP(1) +\&.tar.bz2 tar(1) archive compressed with \fBbzip2\fP(1) +\&.tar.gz tar(1) archive compressed with \fBgzip\fP(1) +\&.taz tar(1) archive compressed with \fBcompress\fP(1) +\&.tcl tcl source code +\&.tex TeX or LaTeX source +\&.texi equivalent to \fI.texinfo\fP +\&.texinfo Texinfo documentation source +\&.text text file +\&.tfm TeX font metric file +\&.tgz tar archive compressed with \fBgzip\fP(1) +\&.tif poor man's \fI.tiff\fP +\&.tiff Tagged Image File Format +\&.tk tcl/tk script +\&.tmp temporary file +\&.tmpl template files +\&.ts TypeScript source code +\&.tsx TypeScript with JSX source code (\fI.ts\fP + \fI.jsx\fP) +\&.txt equivalent to \fI.text\fP +\&.uu equivalent to \fI.uue\fP +\&.uue binary file encoded with \fBuuencode\fP(1) +\&.vf TeX virtual font file +\&.vpl TeX virtual property list file +\&.w Silvio Levi's CWEB +\&.wav wave sound file +\&.web Donald Knuth's WEB +\&.wml Source file for Web Meta Language +\&.xbm X11 bitmap source +\&.xcf GIMP graphic +\&.xml eXtended Markup Language file +\&.xpm X11 pixmap source +\&.xs Perl xsub file produced by h2xs +\&.xsl XSL stylesheet +\&.y \fByacc\fP(1) or \fBbison\fP(1) (parser generator) files +\&.z File compressed using \fBpack\fP(1) (or an old \fBgzip\fP(1)) +\&.zip \fBzip\fP(1) archive +\&.zoo \fBzoo\fP(1) archive +\&\[ti] Emacs or \fBpatch\fP(1) backup file +\&rc startup (`run control') file, e.g., \fI.newsrc\fP +.TE +.SH STANDARDS +General UNIX conventions. +.SH BUGS +This list is not exhaustive. +.SH SEE ALSO +.BR file (1), +.BR make (1) diff --git a/man/man7/svipc.7 b/man/man7/svipc.7 new file mode 100644 index 0000000..cc543f5 --- /dev/null +++ b/man/man7/svipc.7 @@ -0,0 +1 @@ +.so man7/sysvipc.7 diff --git a/man/man7/symlink.7 b/man/man7/symlink.7 new file mode 100644 index 0000000..e8d0650 --- /dev/null +++ b/man/man7/symlink.7 @@ -0,0 +1,564 @@ +.\" Copyright (c) 1992, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" and Copyright (C) 2008, 2014 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" @(#)symlink.7 8.3 (Berkeley) 3/31/94 +.\" $FreeBSD: src/bin/ln/symlink.7,v 1.30 2005/02/13 22:25:09 ru Exp $ +.\" +.\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and heavily edited for +.\" specific Linux details, improved readability, and man-pages style. +.\" +.TH symlink 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +symlink \- symbolic link handling +.SH DESCRIPTION +Symbolic links are files that act as pointers to other files. +To understand their behavior, you must first understand how hard links +work. +.P +A hard link to a file is indistinguishable from the original file because +it is a reference to the object underlying the original filename. +(To be precise: each of the hard links to a file is a reference to +the same +.IR "inode number" , +where an inode number is an index into the inode table, +which contains metadata about all files on a filesystem. +See +.BR stat (2).) +Changes to a file are independent of the name used to reference the file. +Hard links may not refer to directories +(to prevent the possibility of loops within the filesystem tree, +which would confuse many programs) +and may not refer to files on different filesystems +(because inode numbers are not unique across filesystems). +.P +A symbolic link is a special type of file whose contents are a string +that is the pathname of another file, the file to which the link refers. +(The contents of a symbolic link can be read using +.BR readlink (2).) +In other words, a symbolic link is a pointer to another name, +and not to an underlying object. +For this reason, symbolic links may refer to directories and may cross +filesystem boundaries. +.P +There is no requirement that the pathname referred to by a symbolic link +should exist. +A symbolic link that refers to a pathname that does not exist is said +to be a +.IR "dangling link" . +.P +Because a symbolic link and its referenced object coexist in the filesystem +name space, confusion can arise in distinguishing between the link itself +and the referenced object. +On historical systems, +commands and system calls adopted their own link-following +conventions in a somewhat ad-hoc fashion. +Rules for a more uniform approach, +as they are implemented on Linux and other systems, +are outlined here. +It is important that site-local applications also conform to these rules, +so that the user interface can be as consistent as possible. +.\" +.SS Magic links +There is a special class of symbolic-link-like objects +known as "magic links", which +can be found in certain pseudofilesystems such as +.BR proc (5) +(examples include +.IR /proc/ pid /exe +and +.IR /proc/ pid /fd/ *). +Unlike normal symbolic links, magic links are not resolved through +pathname-expansion, but instead act as direct references to the kernel's own +representation of a file handle. +As such, these magic links allow users to +access files which cannot be referenced with normal paths (such as unlinked +files still referenced by a running program ). +.P +Because they can bypass ordinary +.BR mount_namespaces (7)-based +restrictions, +magic links have been used as attack vectors in various exploits. +.\" +.SS Symbolic link ownership, permissions, and timestamps +The owner and group of an existing symbolic link can be changed +using +.BR lchown (2). +The ownership of a symbolic link matters +when the link is being removed or renamed in a directory that +has the sticky bit set (see +.BR inode (7)), +and when the +.I fs.protected_symlinks +sysctl is set (see +.BR proc (5)). +.P +The last access and last modification timestamps +of a symbolic link can be changed using +.BR utimensat (2) +or +.BR lutimes (3). +.P +.\" Linux does not currently implement an lchmod(2). +On Linux, the permissions of an ordinary symbolic link are not used in any +operations; the permissions are always 0777 (read, write, and execute for all +user categories), and can't be changed. +.P +However, magic links do not follow this rule. +They can have a non-0777 mode, +though this mode is not currently used in any permission checks. +.\" .P +.\" The +.\" 4.4BSD +.\" system differs from historical +.\" 4BSD +.\" systems in that the system call +.\" .BR chown (2) +.\" has been changed to follow symbolic links. +.\" The +.\" .BR lchown (2) +.\" system call was added later when the limitations of the new +.\" .BR chown (2) +.\" became apparent. +.SS Obtaining a file descriptor that refers to a symbolic link +Using the combination of the +.B O_PATH +and +.B O_NOFOLLOW +flags to +.BR open (2) +yields a file descriptor that can be passed as the +.I dirfd +argument in system calls such as +.BR fstatat (2), +.BR fchownat (2), +.BR fchmodat (2), +.BR linkat (2), +and +.BR readlinkat (2), +in order to operate on the symbolic link itself +(rather than the file to which it refers). +.P +By default +(i.e., if the +.B AT_SYMLINK_FOLLOW +flag is not specified), if +.BR name_to_handle_at (2) +is applied to a symbolic link, it yields a handle for the symbolic link +(rather than the file to which it refers). +One can then obtain a file descriptor for the symbolic link +(rather than the file to which it refers) +by specifying the +.B O_PATH +flag in a subsequent call to +.BR open_by_handle_at (2). +Again, that file descriptor can be used in the +aforementioned system calls to operate on the symbolic link itself. +.SS Handling of symbolic links by system calls and commands +Symbolic links are handled either by operating on the link itself, +or by operating on the object referred to by the link. +In the latter case, +an application or system call is said to +.I follow +the link. +Symbolic links may refer to other symbolic links, +in which case the links are dereferenced until an object that is +not a symbolic link is found, +a symbolic link that refers to a file which does not exist is found, +or a loop is detected. +(Loop detection is done by placing an upper limit on the number of +links that may be followed, and an error results if this limit is +exceeded.) +.P +There are three separate areas that need to be discussed. +They are as follows: +.IP \[bu] 3 +Symbolic links used as filename arguments for system calls. +.IP \[bu] +Symbolic links specified as command-line arguments to utilities that +are not traversing a file tree. +.IP \[bu] +Symbolic links encountered by utilities that are traversing a file tree +(either specified on the command line or encountered as part of the +file hierarchy walk). +.P +Before describing the treatment of symbolic links by system calls and commands, +we require some terminology. +Given a pathname of the form +.IR a/b/c , +the part preceding the final slash (i.e., +.IR a/b ) +is called the +.I dirname +component, and the part following the final slash (i.e., +.IR c ) +is called the +.I basename +component. +.\" +.SS Treatment of symbolic links in system calls +The first area is symbolic links used as filename arguments for +system calls. +.P +The treatment of symbolic links within a pathname passed to +a system call is as follows: +.IP (1) 5 +Within the dirname component of a pathname, +symbolic links are always followed in nearly every system call. +(This is also true for commands.) +The one exception is +.BR openat2 (2), +which provides flags that can be used to explicitly +prevent following of symbolic links in the dirname component. +.IP (2) +Except as noted below, +all system calls follow symbolic links +in the basename component of a pathname. +For example, if there were a symbolic link +.I slink +which pointed to a file named +.IR afile , +the system call +.I "open(""slink"" ...\&)" +would return a file descriptor referring to the file +.IR afile . +.P +Various system calls do not follow links in +the basename component of a pathname, +and operate on the symbolic link itself. +They are: +.BR lchown (2), +.BR lgetxattr (2), +.BR llistxattr (2), +.BR lremovexattr (2), +.BR lsetxattr (2), +.BR lstat (2), +.BR readlink (2), +.BR rename (2), +.BR rmdir (2), +and +.BR unlink (2). +.P +Certain other system calls optionally follow symbolic links +in the basename component of a pathname. +They are: +.BR faccessat (2), +.\" Maybe one day: .BR fchownat (2) +.BR fchownat (2), +.BR fstatat (2), +.BR linkat (2), +.BR name_to_handle_at (2), +.BR open (2), +.BR openat (2), +.BR open_by_handle_at (2), +and +.BR utimensat (2); +see their manual pages for details. +Because +.BR remove (3) +is an alias for +.BR unlink (2), +that library function also does not follow symbolic links. +When +.BR rmdir (2) +is applied to a symbolic link, it fails with the error +.BR ENOTDIR . +.P +.BR link (2) +warrants special discussion. +POSIX.1-2001 specifies that +.BR link (2) +should dereference +.I oldpath +if it is a symbolic link. +However, Linux does not do this. +(By default, Solaris is the same, +but the POSIX.1-2001 specified behavior can be obtained with +suitable compiler options.) +POSIX.1-2008 changed the specification to allow +either behavior in an implementation. +.SS Commands not traversing a file tree +The second area is symbolic links, specified as command-line +filename arguments, to commands which are not traversing a file tree. +.P +Except as noted below, commands follow symbolic links named as +command-line arguments. +For example, if there were a symbolic link +.I slink +which pointed to a file named +.IR afile , +the command +.I "cat slink" +would display the contents of the file +.IR afile . +.P +It is important to realize that this rule includes commands which may +optionally traverse file trees; for example, the command +.I "chown file" +is included in this rule, while the command +.IR "chown\ \-R file" , +which performs a tree traversal, is not. +(The latter is described in the third area, below.) +.P +If it is explicitly intended that the command operate on the symbolic +link instead of following the symbolic link\[em]for example, it is desired that +.I "chown slink" +change the ownership of the file that +.I slink +is, whether it is a symbolic link or not\[em]then the +.I \-h +option should be used. +In the above example, +.I "chown root slink" +would change the ownership of the file referred to by +.IR slink , +while +.I "chown\ \-h root slink" +would change the ownership of +.I slink +itself. +.P +There are some exceptions to this rule: +.IP \[bu] 3 +The +.BR mv (1) +and +.BR rm (1) +commands do not follow symbolic links named as arguments, +but respectively attempt to rename and delete them. +(Note, if the symbolic link references a file via a relative path, +moving it to another directory may very well cause it to stop working, +since the path may no longer be correct.) +.IP \[bu] +The +.BR ls (1) +command is also an exception to this rule. +For compatibility with historic systems (when +.BR ls (1) +is not doing a tree walk\[em]that is, +.I \-R +option is not specified), +the +.BR ls (1) +command follows symbolic links named as arguments if the +.I \-H +or +.I \-L +option is specified, +or if the +.IR \-F , +.IR \-d , +or +.I \-l +options are not specified. +(The +.BR ls (1) +command is the only command where the +.I \-H +and +.I \-L +options affect its behavior even though it is not doing a walk of +a file tree.) +.IP \[bu] +The +.BR file (1) +command is also an exception to this rule. +The +.BR file (1) +command does not follow symbolic links named as argument by default. +The +.BR file (1) +command does follow symbolic links named as argument if the +.I \-L +option is specified. +.\" +.\"The 4.4BSD system differs from historical 4BSD systems in that the +.\".BR chown (1) +.\"and +.\".BR chgrp (1) +.\"commands follow symbolic links specified on the command line. +.SS Commands traversing a file tree +The following commands either optionally or always traverse file trees: +.BR chgrp (1), +.BR chmod (1), +.BR chown (1), +.BR cp (1), +.BR du (1), +.BR find (1), +.BR ls (1), +.BR pax (1), +.BR rm (1), +and +.BR tar (1). +.P +It is important to realize that the following rules apply equally to +symbolic links encountered during the file tree traversal and symbolic +links listed as command-line arguments. +.P +The \fIfirst rule\fP applies to symbolic links that reference files other +than directories. +Operations that apply to symbolic links are performed on the links +themselves, but otherwise the links are ignored. +.P +The command +.I "rm\ \-r slink directory" +will remove +.IR slink , +as well as any symbolic links encountered in the tree traversal of +.IR directory , +because symbolic links may be removed. +In no case will +.BR rm (1) +affect the file referred to by +.IR slink . +.P +The \fIsecond rule\fP applies to symbolic links that refer to directories. +Symbolic links that refer to directories are never followed by default. +This is often referred to as a "physical" walk, as opposed to a "logical" +walk (where symbolic links that refer to directories are followed). +.P +Certain conventions are (should be) followed as consistently as +possible by commands that perform file tree walks: +.IP \[bu] 3 +A command can be made to follow +any symbolic links named on the command line, +regardless of the type of file they reference, by specifying the +.I \-H +(for "half-logical") flag. +This flag is intended to make the command-line name space look +like the logical name space. +(Note, for commands that do not always do file tree traversals, the +.I \-H +flag will be ignored if the +.I \-R +flag is not also specified.) +.IP +For example, the command +.I "chown\ \-HR user slink" +will traverse the file hierarchy rooted in the file pointed to by +.IR slink . +Note, the +.I \-H +is not the same as the previously discussed +.I \-h +flag. +The +.I \-H +flag causes symbolic links specified on the command line to be +dereferenced for the purposes of both the action to be performed +and the tree walk, and it is as if the user had specified the +name of the file to which the symbolic link pointed. +.IP \[bu] +A command can be made to +follow any symbolic links named on the command line, +as well as any symbolic links encountered during the traversal, +regardless of the type of file they reference, by specifying the +.I \-L +(for "logical") flag. +This flag is intended to make the entire name space look like +the logical name space. +(Note, for commands that do not always do file tree traversals, the +.I \-L +flag will be ignored if the +.I \-R +flag is not also specified.) +.IP +For example, the command +.I "chown\ \-LR user slink" +will change the owner of the file referred to by +.IR slink . +If +.I slink +refers to a directory, +.B chown +will traverse the file hierarchy rooted in the directory that it +references. +In addition, if any symbolic links are encountered in any file tree that +.B chown +traverses, they will be treated in the same fashion as +.IR slink . +.IP \[bu] +A command can be made to +provide the default behavior by specifying the +.I \-P +(for "physical") flag. +This flag is intended to make the entire name space look like the +physical name space. +.P +For commands that do not by default do file tree traversals, the +.IR \-H , +.IR \-L , +and +.I \-P +flags are ignored if the +.I \-R +flag is not also specified. +In addition, you may specify the +.IR \-H , +.IR \-L , +and +.I \-P +options more than once; +the last one specified determines the command's behavior. +This is intended to permit you to alias commands to behave one way +or the other, and then override that behavior on the command line. +.P +The +.BR ls (1) +and +.BR rm (1) +commands have exceptions to these rules: +.IP \[bu] 3 +The +.BR rm (1) +command operates on the symbolic link, and not the file it references, +and therefore never follows a symbolic link. +The +.BR rm (1) +command does not support the +.IR \-H , +.IR \-L , +or +.I \-P +options. +.IP \[bu] +To maintain compatibility with historic systems, +the +.BR ls (1) +command acts a little differently. +If you do not specify the +.IR \-F , +.IR \-d , +or +.I \-l +options, +.BR ls (1) +will follow symbolic links specified on the command line. +If the +.I \-L +flag is specified, +.BR ls (1) +follows all symbolic links, +regardless of their type, +whether specified on the command line or encountered in the tree walk. +.SH SEE ALSO +.BR chgrp (1), +.BR chmod (1), +.BR find (1), +.BR ln (1), +.BR ls (1), +.BR mv (1), +.BR namei (1), +.BR rm (1), +.BR lchown (2), +.BR link (2), +.BR lstat (2), +.BR readlink (2), +.BR rename (2), +.BR symlink (2), +.BR unlink (2), +.BR utimensat (2), +.BR lutimes (3), +.BR path_resolution (7) diff --git a/man/man7/system_data_types.7 b/man/man7/system_data_types.7 new file mode 100644 index 0000000..b2dff72 --- /dev/null +++ b/man/man7/system_data_types.7 @@ -0,0 +1,242 @@ +.\" Copyright (c) 2020 by Alejandro Colomar +.\" and Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH system_data_types 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +system_data_types \- overview of system data types +.SH DESCRIPTION +.\" Layout: +.\" A list of type names (the struct/union keyword will be omitted). +.\" Each entry will have the following parts: +.\" * Include (see NOTES) +.\" +.\" * Definition (no "Definition" header) +.\" Only struct/union types will have definition; +.\" typedefs will remain opaque. +.\" +.\" * Description (no "Description" header) +.\" A few lines describing the type. +.\" +.\" * Versions (optional) +.\" +.\" * Conforming to (see NOTES) +.\" Format: CXY and later; POSIX.1-XXXX and later. +.\" +.\" * Notes (optional) +.\" +.\" * Bugs (if any) +.\" +.\" * See also +.\"------------------------------------- aiocb ------------------------/ +.\"------------------------------------- blkcnt_t ---------------------/ +.\"------------------------------------- blksize_t --------------------/ +.\"------------------------------------- cc_t -------------------------/ +.\"------------------------------------- clock_t ----------------------/ +.\"------------------------------------- clockid_t --------------------/ +.\"------------------------------------- dev_t ------------------------/ +.\"------------------------------------- div_t ------------------------/ +.\"------------------------------------- double_t ---------------------/ +.\"------------------------------------- fd_set -----------------------/ +.\"------------------------------------- fenv_t -----------------------/ +.\"------------------------------------- fexcept_t --------------------/ +.\"------------------------------------- FILE -------------------------/ +.\"------------------------------------- float_t ----------------------/ +.\"------------------------------------- gid_t ------------------------/ +.\"------------------------------------- id_t -------------------------/ +.\"------------------------------------- imaxdiv_t --------------------/ +.\"------------------------------------- intmax_t ---------------------/ +.\"------------------------------------- intN_t -----------------------/ +.\"------------------------------------- intptr_t ---------------------/ +.\"------------------------------------- lconv ------------------------/ +.\"------------------------------------- ldiv_t -----------------------/ +.\"------------------------------------- lldiv_t ----------------------/ +.\"------------------------------------- mode_t -----------------------/ +.\"------------------------------------- off64_t ----------------------/ +.\"------------------------------------- off_t ------------------------/ +.\"------------------------------------- pid_t ------------------------/ +.\"------------------------------------- ptrdiff_t --------------------/ +.\"------------------------------------- regex_t ----------------------/ +.\"------------------------------------- regmatch_t -------------------/ +.\"------------------------------------- regoff_t ---------------------/ +.\"------------------------------------- sigevent ---------------------/ +.\"------------------------------------- siginfo_t --------------------/ +.TP +.I siginfo_t +.RS +.IR Include : +.IR . +Alternatively, +.IR . +.P +.EX +typedef struct { + int si_signo; /* Signal number */ + int si_code; /* Signal code */ + pid_t si_pid; /* Sending process ID */ + uid_t si_uid; /* Real user ID of sending process */ + void *si_addr; /* Memory location which caused fault */ + int si_status; /* Exit value or signal */ + union sigval si_value; /* Signal value */ +} siginfo_t; +.EE +.P +Information associated with a signal. +For further details on this structure +(including additional, Linux-specific fields), see +.BR sigaction (2). +.P +.IR "Conforming to" : +POSIX.1-2001 and later. +.P +.IR "See also" : +.BR pidfd_send_signal (2), +.BR rt_sigqueueinfo (2), +.BR sigaction (2), +.BR sigwaitinfo (2), +.BR psiginfo (3) +.RE +.\"------------------------------------- sigset_t ---------------------/ +.TP +.I sigset_t +.RS +.IR Include : +.IR . +Alternatively, +.IR , +or +.IR . +.P +This is a type that represents a set of signals. +According to POSIX, this shall be an integer or structure type. +.P +.IR "Conforming to" : +POSIX.1-2001 and later. +.P +.IR "See also" : +.BR epoll_pwait (2), +.BR ppoll (2), +.BR pselect (2), +.BR sigaction (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigsuspend (2), +.BR sigwaitinfo (2), +.BR signal (7) +.RE +.\"------------------------------------- sigval -----------------------/ +.\"------------------------------------- size_t -----------------------/ +.\"------------------------------------- sockaddr ---------------------/ +.\"------------------------------------- socklen_t --------------------/ +.\"------------------------------------- ssize_t ----------------------/ +.\"------------------------------------- stat -------------------------/ +.\"------------------------------------- suseconds_t ------------------/ +.\"------------------------------------- time_t -----------------------/ +.\"------------------------------------- timer_t ----------------------/ +.\"------------------------------------- timespec ---------------------/ +.\"------------------------------------- timeval ----------------------/ +.\"------------------------------------- uid_t ----------------------/ +.\"------------------------------------- uintmax_t --------------------/ +.\"------------------------------------- uintN_t ----------------------/ +.\"------------------------------------- uintptr_t --------------------/ +.\"------------------------------------- useconds_t -------------------/ +.\"------------------------------------- va_list ----------------------/ +.\"------------------------------------- void * -----------------------/ +.\"--------------------------------------------------------------------/ +.SH NOTES +The structures described in this manual page shall contain, +at least, the members shown in their definition, in no particular order. +.P +Most of the integer types described in this page don't have +a corresponding length modifier for the +.BR printf (3) +and the +.BR scanf (3) +families of functions. +To print a value of an integer type that doesn't have a length modifier, +it should be converted to +.I intmax_t +or +.I uintmax_t +by an explicit cast. +To scan into a variable of an integer type +that doesn't have a length modifier, +an intermediate temporary variable of type +.I intmax_t +or +.I uintmax_t +should be used. +When copying from the temporary variable to the destination variable, +the value could overflow. +If the type has upper and lower limits, +the user should check that the value is within those limits, +before actually copying the value. +The example below shows how these conversions should be done. +.SS Conventions used in this page +In "Conforming to" we only concern ourselves with +C99 and later and POSIX.1-2001 and later. +Some types may be specified in earlier versions of one of these standards, +but in the interests of simplicity we omit details from earlier standards. +.P +In "Include", we first note the "primary" header(s) that +define the type according to either the C or POSIX.1 standards. +Under "Alternatively", we note additional headers that +the standards specify shall define the type. +.SH EXAMPLES +The program shown below scans from a string and prints a value stored in +a variable of an integer type that doesn't have a length modifier. +The appropriate conversions from and to +.IR intmax_t , +and the appropriate range checks, +are used as explained in the notes section above. +.P +.EX +#include +#include +#include +#include +\& +int +main (void) +{ + static const char *const str = "500000 us in half a second"; + suseconds_t us; + intmax_t tmp; +\& + /* Scan the number from the string into the temporary variable. */ +\& + sscanf(str, "%jd", &tmp); +\& + /* Check that the value is within the valid range of suseconds_t. */ +\& + if (tmp < \-1 || tmp > 1000000) { + fprintf(stderr, "Scanned value outside valid range!\en"); + exit(EXIT_FAILURE); + } +\& + /* Copy the value to the suseconds_t variable \[aq]us\[aq]. */ +\& + us = tmp; +\& + /* Even though suseconds_t can hold the value \-1, this isn\[aq]t + a sensible number of microseconds. */ +\& + if (us < 0) { + fprintf(stderr, "Scanned value shouldn\[aq]t be negative!\en"); + exit(EXIT_FAILURE); + } +\& + /* Print the value. */ +\& + printf("There are %jd microseconds in half a second.\en", + (intmax_t) us); +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR feature_test_macros (7), +.BR standards (7) diff --git a/man/man7/sysvipc.7 b/man/man7/sysvipc.7 new file mode 100644 index 0000000..898315f --- /dev/null +++ b/man/man7/sysvipc.7 @@ -0,0 +1,99 @@ +.\" Copyright 2020 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sysvipc 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sysvipc \- System V interprocess communication mechanisms +.SH DESCRIPTION +System V IPC is the name given to three interprocess +communication mechanisms that are widely available on UNIX systems: +message queues, semaphore, and shared memory. +.\" +.SS Message queues +System V message queues allow data to be exchanged in units called messages. +Each message can have an associated priority. +POSIX message queues provide an alternative API for achieving the same result; +see +.BR mq_overview (7). +.P +The System V message queue API consists of the following system calls: +.TP +.BR msgget (2) +Create a new message queue or obtain the ID of an existing message queue. +This call returns an identifier that is used in the remaining APIs. +.TP +.BR msgsnd (2) +Add a message to a queue. +.TP +.BR msgrcv (2) +Remove a message from a queue. +.TP +.BR msgctl (2) +Perform various control operations on a queue, including deletion. +.\" +.SS Semaphore sets +System V semaphores allow processes to synchronize their actions. +System V semaphores are allocated in groups called sets; +each semaphore in a set is a counting semaphore. +POSIX semaphores provide an alternative API for achieving the same result; +see +.BR sem_overview (7). +.P +The System V semaphore API consists of the following system calls: +.TP +.BR semget (2) +Create a new set or obtain the ID of an existing set. +This call returns an identifier that is used in the remaining APIs. +.TP +.BR semop (2) +Perform operations on the semaphores in a set. +.TP +.BR semctl (2) +Perform various control operations on a set, including deletion. +.\" +.SS Shared memory segments +System V shared memory allows processes to share a region a memory +(a "segment"). +POSIX shared memory is an alternative API for achieving the same result; see +.BR shm_overview (7). +.P +The System V shared memory API consists of the following system calls: +.TP +.BR shmget (2) +Create a new segment or obtain the ID of an existing segment. +This call returns an identifier that is used in the remaining APIs. +.TP +.BR shmat (2) +Attach an existing shared memory object into the calling process's +address space. +.TP +.BR shmdt (2) +Detach a segment from the calling process's address space. +.TP +.BR shmctl (2) +Perform various control operations on a segment, including deletion. +.\" +.SS IPC namespaces +For a discussion of the interaction of System V IPC objects and +IPC namespaces, see +.BR ipc_namespaces (7). +.SH SEE ALSO +.BR ipcmk (1), +.BR ipcrm (1), +.BR ipcs (1), +.BR lsipc (1), +.BR ipc (2), +.BR msgctl (2), +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR semctl (2), +.BR semget (2), +.BR semop (2), +.BR shmat (2), +.BR shmctl (2), +.BR shmdt (2), +.BR shmget (2), +.BR ftok (3), +.BR ipc_namespaces (7) diff --git a/man/man7/tcp.7 b/man/man7/tcp.7 new file mode 100644 index 0000000..0e3b1b1 --- /dev/null +++ b/man/man7/tcp.7 @@ -0,0 +1,1563 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" and Copyright (C) 2008 Michael Kerrisk +.\" Note also that many pieces are drawn from the kernel source file +.\" Documentation/networking/ip-sysctl.txt. +.\" +.\" 2.4 Updates by Nivedita Singhvi 4/20/02 . +.\" Modified, 2004-11-11, Michael Kerrisk and Andries Brouwer +.\" Updated details of interaction of TCP_CORK and TCP_NODELAY. +.\" +.\" 2008-11-21, mtk, many, many updates. +.\" The descriptions of /proc files and socket options should now +.\" be more or less up to date and complete as at Linux 2.6.27 +.\" (other than the remaining FIXMEs in the page source below). +.\" +.\" FIXME The following need to be documented +.\" TCP_MD5SIG (2.6.20) +.\" commit cfb6eeb4c860592edd123fdea908d23c6ad1c7dc +.\" Author was yoshfuji@linux-ipv6.org +.\" Needs CONFIG_TCP_MD5SIG +.\" From net/inet/Kconfig: +.\" bool "TCP: MD5 Signature Option support (RFC2385) (EXPERIMENTAL)" +.\" RFC2385 specifies a method of giving MD5 protection to TCP sessions. +.\" Its main (only?) use is to protect BGP sessions between core routers +.\" on the Internet. +.\" +.\" There is a TCP_MD5SIG option documented in FreeBSD's tcp(4), +.\" but probably many details are different on Linux +.\" http://thread.gmane.org/gmane.linux.network/47490 +.\" http://www.daemon-systems.org/man/tcp.4.html +.\" http://article.gmane.org/gmane.os.netbsd.devel.network/3767/match=tcp_md5sig+freebsd +.\" +.\" TCP_COOKIE_TRANSACTIONS (2.6.33) +.\" commit 519855c508b9a17878c0977a3cdefc09b59b30df +.\" Author: William Allen Simpson +.\" commit e56fb50f2b7958b931c8a2fc0966061b3f3c8f3a +.\" Author: William Allen Simpson +.\" +.\" REMOVED in Linux 3.10 +.\" commit 1a2c6181c4a1922021b4d7df373bba612c3e5f04 +.\" Author: Christoph Paasch +.\" +.\" TCP_THIN_LINEAR_TIMEOUTS (2.6.34) +.\" commit 36e31b0af58728071e8023cf8e20c5166b700717 +.\" Author: Andreas Petlund +.\" +.\" TCP_THIN_DUPACK (2.6.34) +.\" commit 7e38017557bc0b87434d184f8804cadb102bb903 +.\" Author: Andreas Petlund +.\" +.\" TCP_REPAIR (3.5) +.\" commit ee9952831cfd0bbe834f4a26489d7dce74582e37 +.\" Author: Pavel Emelyanov +.\" See also +.\" http://criu.org/TCP_connection +.\" https://lwn.net/Articles/495304/ +.\" +.\" TCP_REPAIR_QUEUE (3.5) +.\" commit ee9952831cfd0bbe834f4a26489d7dce74582e37 +.\" Author: Pavel Emelyanov +.\" +.\" TCP_QUEUE_SEQ (3.5) +.\" commit ee9952831cfd0bbe834f4a26489d7dce74582e37 +.\" Author: Pavel Emelyanov +.\" +.\" TCP_REPAIR_OPTIONS (3.5) +.\" commit b139ba4e90dccbf4cd4efb112af96a5c9e0b098c +.\" Author: Pavel Emelyanov +.\" +.\" TCP_FASTOPEN (3.6) +.\" (Fast Open server side implementation completed in Linux 3.7) +.\" http://lwn.net/Articles/508865/ +.\" +.\" TCP_TIMESTAMP (3.9) +.\" commit 93be6ce0e91b6a94783e012b1857a347a5e6e9f2 +.\" Author: Andrey Vagin +.\" +.\" TCP_NOTSENT_LOWAT (3.12) +.\" commit c9bee3b7fdecb0c1d070c7b54113b3bdfb9a3d36 +.\" Author: Eric Dumazet +.\" +.\" TCP_CC_INFO (4.1) +.\" commit 6e9250f59ef9efb932c84850cd221f22c2a03c4a +.\" Author: Eric Dumazet +.\" +.\" TCP_SAVE_SYN, TCP_SAVED_SYN (4.2) +.\" commit cd8ae85299d54155702a56811b2e035e63064d3d +.\" Author: Eric Dumazet +.\" +.TH tcp 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +tcp \- TCP protocol +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" +.fi +.SH DESCRIPTION +This is an implementation of the TCP protocol defined in +RFC\ 793, RFC\ 1122 and RFC\ 2001 with the NewReno and SACK +extensions. +It provides a reliable, stream-oriented, +full-duplex connection between two sockets on top of +.BR ip (7), +for both v4 and v6 versions. +TCP guarantees that the data arrives in order and +retransmits lost packets. +It generates and checks a per-packet checksum to catch +transmission errors. +TCP does not preserve record boundaries. +.P +A newly created TCP socket has no remote or local address and is not +fully specified. +To create an outgoing TCP connection use +.BR connect (2) +to establish a connection to another TCP socket. +To receive new incoming connections, first +.BR bind (2) +the socket to a local address and port and then call +.BR listen (2) +to put the socket into the listening state. +After that a new socket for each incoming connection can be accepted using +.BR accept (2). +A socket which has had +.BR accept (2) +or +.BR connect (2) +successfully called on it is fully specified and may transmit data. +Data cannot be transmitted on listening or not yet connected sockets. +.P +Linux supports RFC\ 1323 TCP high performance +extensions. +These include Protection Against Wrapped +Sequence Numbers (PAWS), Window Scaling and Timestamps. +Window scaling allows the use +of large (> 64\ kB) TCP windows in order to support links with high +latency or bandwidth. +To make use of them, the send and receive buffer sizes must be increased. +They can be set globally with the +.I /proc/sys/net/ipv4/tcp_wmem +and +.I /proc/sys/net/ipv4/tcp_rmem +files, or on individual sockets by using the +.B SO_SNDBUF +and +.B SO_RCVBUF +socket options with the +.BR setsockopt (2) +call. +.P +The maximum sizes for socket buffers declared via the +.B SO_SNDBUF +and +.B SO_RCVBUF +mechanisms are limited by the values in the +.I /proc/sys/net/core/rmem_max +and +.I /proc/sys/net/core/wmem_max +files. +Note that TCP actually allocates twice the size of +the buffer requested in the +.BR setsockopt (2) +call, and so a succeeding +.BR getsockopt (2) +call will not return the same size of buffer as requested in the +.BR setsockopt (2) +call. +TCP uses the extra space for administrative purposes and internal +kernel structures, and the +.I /proc +file values reflect the +larger sizes compared to the actual TCP windows. +On individual connections, the socket buffer size must be set prior to the +.BR listen (2) +or +.BR connect (2) +calls in order to have it take effect. +See +.BR socket (7) +for more information. +.P +TCP supports urgent data. +Urgent data is used to signal the +receiver that some important message is part of the data +stream and that it should be processed as soon as possible. +To send urgent data specify the +.B MSG_OOB +option to +.BR send (2). +When urgent data is received, the kernel sends a +.B SIGURG +signal to the process or process group that has been set as the +socket "owner" using the +.B SIOCSPGRP +or +.B FIOSETOWN +ioctls (or the POSIX.1-specified +.BR fcntl (2) +.B F_SETOWN +operation). +When the +.B SO_OOBINLINE +socket option is enabled, urgent data is put into the normal +data stream (a program can test for its location using the +.B SIOCATMARK +ioctl described below), +otherwise it can be received only when the +.B MSG_OOB +flag is set for +.BR recv (2) +or +.BR recvmsg (2). +.P +When out-of-band data is present, +.BR select (2) +indicates the file descriptor as having an exceptional condition and +.I poll (2) +indicates a +.B POLLPRI +event. +.P +Linux 2.4 introduced a number of changes for improved +throughput and scaling, as well as enhanced functionality. +Some of these features include support for zero-copy +.BR sendfile (2), +Explicit Congestion Notification, new +management of TIME_WAIT sockets, keep-alive socket options +and support for Duplicate SACK extensions. +.SS Address formats +TCP is built on top of IP (see +.BR ip (7)). +The address formats defined by +.BR ip (7) +apply to TCP. +TCP supports point-to-point communication only; +broadcasting and multicasting are not +supported. +.SS /proc interfaces +System-wide TCP parameter settings can be accessed by files in the directory +.IR /proc/sys/net/ipv4/ . +In addition, most IP +.I /proc +interfaces also apply to TCP; see +.BR ip (7). +Variables described as +.I Boolean +take an integer value, with a nonzero value ("true") meaning that +the corresponding option is enabled, and a zero value ("false") +meaning that the option is disabled. +.TP +.IR tcp_abc " (Integer; default: 0; Linux 2.6.15 to Linux 3.8)" +.\" Since Linux 2.6.15; removed in Linux 3.9 +.\" commit ca2eb5679f8ddffff60156af42595df44a315ef0 +.\" The following is from Linux 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +Control the Appropriate Byte Count (ABC), defined in RFC 3465. +ABC is a way of increasing the congestion window +.RI ( cwnd ) +more slowly in response to partial acknowledgements. +Possible values are: +.RS +.TP +.B 0 +increase +.I cwnd +once per acknowledgement (no ABC) +.TP +.B 1 +increase +.I cwnd +once per acknowledgement of full sized segment +.TP +.B 2 +allow increase +.I cwnd +by two if acknowledgement is +of two segments to compensate for delayed acknowledgements. +.RE +.TP +.IR tcp_abort_on_overflow " (Boolean; default: disabled; since Linux 2.4)" +.\" Since Linux 2.3.41 +Enable resetting connections if the listening service is too +slow and unable to keep up and accept them. +It means that if overflow occurred due +to a burst, the connection will recover. +Enable this option +.I only +if you are really sure that the listening daemon +cannot be tuned to accept connections faster. +Enabling this option can harm the clients of your server. +.TP +.IR tcp_adv_win_scale " (integer; default: 2; since Linux 2.4)" +.\" Since Linux 2.4.0-test7 +Count buffering overhead as +.IR "bytes/2\[ha]tcp_adv_win_scale" , +if +.I tcp_adv_win_scale +is greater than 0; or +.IR "bytes\-bytes/2\[ha](\-tcp_adv_win_scale)" , +if +.I tcp_adv_win_scale +is less than or equal to zero. +.IP +The socket receive buffer space is shared between the +application and kernel. +TCP maintains part of the buffer as +the TCP window, this is the size of the receive window +advertised to the other end. +The rest of the space is used +as the "application" buffer, used to isolate the network +from scheduling and application latencies. +The +.I tcp_adv_win_scale +default value of 2 implies that the space +used for the application buffer is one fourth that of the total. +.TP +.IR tcp_allowed_congestion_control " (String; default: see text; since Linux 2.4.20)" +.\" The following is from Linux 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +Show/set the congestion control algorithm choices available to unprivileged +processes (see the description of the +.B TCP_CONGESTION +socket option). +The items in the list are separated by white space and +terminated by a newline character. +The list is a subset of those listed in +.IR tcp_available_congestion_control . +The default value for this list is "reno" plus the default setting of +.IR tcp_congestion_control . +.TP +.IR tcp_autocorking " (Boolean; default: enabled; since Linux 3.14)" +.\" commit f54b311142a92ea2e42598e347b84e1655caf8e3 +.\" Text heavily based on Documentation/networking/ip-sysctl.txt +If this option is enabled, the kernel tries to coalesce small writes +(from consecutive +.BR write (2) +and +.BR sendmsg (2) +calls) as much as possible, +in order to decrease the total number of sent packets. +Coalescing is done if at least one prior packet for the flow +is waiting in Qdisc queues or device transmit queue. +Applications can still use the +.B TCP_CORK +socket option to obtain optimal behavior +when they know how/when to uncork their sockets. +.TP +.IR tcp_available_congestion_control " (String; read-only; since Linux 2.4.20)" +.\" The following is from Linux 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +Show a list of the congestion-control algorithms +that are registered. +The items in the list are separated by white space and +terminated by a newline character. +This list is a limiting set for the list in +.IR tcp_allowed_congestion_control . +More congestion-control algorithms may be available as modules, +but not loaded. +.TP +.IR tcp_app_win " (integer; default: 31; since Linux 2.4)" +.\" Since Linux 2.4.0-test7 +This variable defines how many +bytes of the TCP window are reserved for buffering overhead. +.IP +A maximum of (\fIwindow/2\[ha]tcp_app_win\fP, mss) bytes in the window +are reserved for the application buffer. +A value of 0 implies that no amount is reserved. +.\" +.\" The following is from Linux 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_base_mss " (Integer; default: 512; since Linux 2.6.17)" +The initial value of +.I search_low +to be used by the packetization layer Path MTU discovery (MTU probing). +If MTU probing is enabled, +this is the initial MSS used by the connection. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_bic " (Boolean; default: disabled; Linux 2.4.27/2.6.6 to Linux 2.6.13)" +Enable BIC TCP congestion control algorithm. +BIC-TCP is a sender-side-only change that ensures a linear RTT +fairness under large windows while offering both scalability and +bounded TCP-friendliness. +The protocol combines two schemes +called additive increase and binary search increase. +When the congestion window is large, additive increase with a large +increment ensures linear RTT fairness as well as good scalability. +Under small congestion windows, binary search +increase provides TCP friendliness. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_bic_low_window " (integer; default: 14; Linux 2.4.27/2.6.6 to Linux 2.6.13)" +Set the threshold window (in packets) where BIC TCP starts to +adjust the congestion window. +Below this threshold BIC TCP behaves the same as the default TCP Reno. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_bic_fast_convergence " (Boolean; default: enabled; Linux 2.4.27/2.6.6 to Linux 2.6.13)" +Force BIC TCP to more quickly respond to changes in congestion window. +Allows two flows sharing the same connection to converge more rapidly. +.TP +.IR tcp_congestion_control " (String; default: see text; since Linux 2.4.13)" +.\" The following is from Linux 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +Set the default congestion-control algorithm to be used for new connections. +The algorithm "reno" is always available, +but additional choices may be available depending on kernel configuration. +The default value for this file is set as part of kernel configuration. +.TP +.IR tcp_dma_copybreak " (integer; default: 4096; since Linux 2.6.24)" +Lower limit, in bytes, of the size of socket reads that will be +offloaded to a DMA copy engine, if one is present in the system +and the kernel was configured with the +.B CONFIG_NET_DMA +option. +.TP +.IR tcp_dsack " (Boolean; default: enabled; since Linux 2.4)" +.\" Since Linux 2.4.0-test7 +Enable RFC\ 2883 TCP Duplicate SACK support. +.TP +.IR tcp_fastopen " (Bitmask; default: 0x1; since Linux 3.7)" +Enables RFC\~7413 Fast Open support. +The flag is used as a bitmap with the following values: +.RS +.TP +.B 0x1 +Enables client side Fast Open support +.TP +.B 0x2 +Enables server side Fast Open support +.TP +.B 0x4 +Allows client side to transmit data in SYN without Fast Open option +.TP +.B 0x200 +Allows server side to accept SYN data without Fast Open option +.TP +.B 0x400 +Enables Fast Open on all listeners without +.B TCP_FASTOPEN +socket option +.RE +.TP +.IR tcp_fastopen_key " (since Linux 3.7)" +Set server side RFC\~7413 Fast Open key to generate Fast Open cookie +when server side Fast Open support is enabled. +.TP +.IR tcp_ecn " (Integer; default: see below; since Linux 2.4)" +.\" Since Linux 2.4.0-test7 +Enable RFC\ 3168 Explicit Congestion Notification. +.IP +This file can have one of the following values: +.RS +.TP +.B 0 +Disable ECN. +Neither initiate nor accept ECN. +This was the default up to and including Linux 2.6.30. +.TP +.B 1 +Enable ECN when requested by incoming connections and also +request ECN on outgoing connection attempts. +.TP +.B 2 +.\" commit 255cac91c3c9ce7dca7713b93ab03c75b7902e0e +Enable ECN when requested by incoming connections, +but do not request ECN on outgoing connections. +This value is supported, and is the default, since Linux 2.6.31. +.RE +.IP +When enabled, connectivity to some destinations could be affected +due to older, misbehaving middle boxes along the path, causing +connections to be dropped. +However, to facilitate and encourage deployment with option 1, and +to work around such buggy equipment, the +.B tcp_ecn_fallback +option has been introduced. +.TP +.IR tcp_ecn_fallback " (Boolean; default: enabled; since Linux 4.1)" +.\" commit 492135557dc090a1abb2cfbe1a412757e3ed68ab +Enable RFC\ 3168, Section 6.1.1.1. fallback. +When enabled, outgoing ECN-setup SYNs that time out within the +normal SYN retransmission timeout will be resent with CWR and +ECE cleared. +.TP +.IR tcp_fack " (Boolean; default: enabled; since Linux 2.2)" +.\" Since Linux 2.1.92 +Enable TCP Forward Acknowledgement support. +.TP +.IR tcp_fin_timeout " (integer; default: 60; since Linux 2.2)" +.\" Since Linux 2.1.53 +This specifies how many seconds to wait for a final FIN packet before the +socket is forcibly closed. +This is strictly a violation of the TCP specification, +but required to prevent denial-of-service attacks. +In Linux 2.2, the default value was 180. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_frto " (integer; default: see below; since Linux 2.4.21/2.6)" +.\" Since Linux 2.4.21/2.5.43 +Enable F-RTO, an enhanced recovery algorithm for TCP retransmission +timeouts (RTOs). +It is particularly beneficial in wireless environments +where packet loss is typically due to random radio interference +rather than intermediate router congestion. +See RFC 4138 for more details. +.IP +This file can have one of the following values: +.RS +.TP +.B 0 +Disabled. +This was the default up to and including Linux 2.6.23. +.TP +.B 1 +The basic version F-RTO algorithm is enabled. +.TP +.B 2 +.\" commit c96fd3d461fa495400df24be3b3b66f0e0b152f9 +Enable SACK-enhanced F-RTO if flow uses SACK. +The basic version can be used also when +SACK is in use though in that case scenario(s) exists where F-RTO +interacts badly with the packet counting of the SACK-enabled TCP flow. +This value is the default since Linux 2.6.24. +.RE +.IP +Before Linux 2.6.22, this parameter was a Boolean value, +supporting just values 0 and 1 above. +.TP +.IR tcp_frto_response " (integer; default: 0; since Linux 2.6.22)" +When F-RTO has detected that a TCP retransmission timeout was spurious +(i.e., the timeout would have been avoided had TCP set a +longer retransmission timeout), +TCP has several options concerning what to do next. +Possible values are: +.RS +.TP +.B 0 +Rate halving based; a smooth and conservative response, +results in halved congestion window +.RI ( cwnd ) +and slow-start threshold +.RI ( ssthresh ) +after one RTT. +.TP +.B 1 +Very conservative response; not recommended because even +though being valid, it interacts poorly with the rest of Linux TCP; halves +.I cwnd +and +.I ssthresh +immediately. +.TP +.B 2 +Aggressive response; undoes congestion-control measures +that are now known to be unnecessary +(ignoring the possibility of a lost retransmission that would require +TCP to be more cautious); +.I cwnd +and +.I ssthresh +are restored to the values prior to timeout. +.RE +.TP +.IR tcp_keepalive_intvl " (integer; default: 75; since Linux 2.4)" +.\" Since Linux 2.3.18 +The number of seconds between TCP keep-alive probes. +.TP +.IR tcp_keepalive_probes " (integer; default: 9; since Linux 2.2)" +.\" Since Linux 2.1.43 +The maximum number of TCP keep-alive probes to send +before giving up and killing the connection if +no response is obtained from the other end. +.TP +.IR tcp_keepalive_time " (integer; default: 7200; since Linux 2.2)" +.\" Since Linux 2.1.43 +The number of seconds a connection needs to be idle +before TCP begins sending out keep-alive probes. +Keep-alives are sent only when the +.B SO_KEEPALIVE +socket option is enabled. +The default value is 7200 seconds (2 hours). +An idle connection is terminated after +approximately an additional 11 minutes (9 probes an interval +of 75 seconds apart) when keep-alive is enabled. +.IP +Note that underlying connection tracking mechanisms and +application timeouts may be much shorter. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_low_latency " (Boolean; default: disabled; since Linux 2.4.21/2.6; \ +obsolete since Linux 4.14)" +.\" Since Linux 2.4.21/2.5.60 +If enabled, the TCP stack makes decisions that prefer lower +latency as opposed to higher throughput. +It this option is disabled, then higher throughput is preferred. +An example of an application where this default should be +changed would be a Beowulf compute cluster. +Since Linux 4.14, +.\" commit b6690b14386698ce2c19309abad3f17656bdfaea +this file still exists, but its value is ignored. +.TP +.IR tcp_max_orphans " (integer; default: see below; since Linux 2.4)" +.\" Since Linux 2.3.41 +The maximum number of orphaned (not attached to any user file +handle) TCP sockets allowed in the system. +When this number is exceeded, +the orphaned connection is reset and a warning is printed. +This limit exists only to prevent simple denial-of-service attacks. +Lowering this limit is not recommended. +Network conditions might require you to increase the number of +orphans allowed, but note that each orphan can eat up to \[ti]64\ kB +of unswappable memory. +The default initial value is set equal to the kernel parameter NR_FILE. +This initial default is adjusted depending on the memory in the system. +.TP +.IR tcp_max_syn_backlog " (integer; default: see below; since Linux 2.2)" +.\" Since Linux 2.1.53 +The maximum number of queued connection requests which have +still not received an acknowledgement from the connecting client. +If this number is exceeded, the kernel will begin +dropping requests. +The default value of 256 is increased to +1024 when the memory present in the system is adequate or +greater (>= 128\ MB), and reduced to 128 for those systems with +very low memory (<= 32\ MB). +.IP +Before Linux 2.6.20, +.\" commit 72a3effaf633bcae9034b7e176bdbd78d64a71db +it was recommended that if this needed to be increased above 1024, +the size of the SYNACK hash table +.RB ( TCP_SYNQ_HSIZE ) +in +.I include/net/tcp.h +should be modified to keep +.IP +.in +4n +.EX +TCP_SYNQ_HSIZE * 16 <= tcp_max_syn_backlog +.EE +.in +.IP +and the kernel should be +recompiled. +In Linux 2.6.20, the fixed sized +.B TCP_SYNQ_HSIZE +was removed in favor of dynamic sizing. +.TP +.IR tcp_max_tw_buckets " (integer; default: see below; since Linux 2.4)" +.\" Since Linux 2.3.41 +The maximum number of sockets in TIME_WAIT state allowed in +the system. +This limit exists only to prevent simple denial-of-service attacks. +The default value of NR_FILE*2 is adjusted +depending on the memory in the system. +If this number is +exceeded, the socket is closed and a warning is printed. +.TP +.IR tcp_moderate_rcvbuf " (Boolean; default: enabled; since Linux 2.4.17/2.6.7)" +.\" The following is from Linux 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +If enabled, TCP performs receive buffer auto-tuning, +attempting to automatically size the buffer (no greater than +.IR tcp_rmem[2] ) +to match the size required by the path for full throughput. +.TP +.IR tcp_mem " (since Linux 2.4)" +.\" Since Linux 2.4.0-test7 +This is a vector of 3 integers: [low, pressure, high]. +These bounds, measured in units of the system page size, +are used by TCP to track its memory usage. +The defaults are calculated at boot time from the amount of +available memory. +(TCP can only use +.I "low memory" +for this, which is limited to around 900 megabytes on 32-bit systems. +64-bit systems do not suffer this limitation.) +.RS +.TP +.I low +TCP doesn't regulate its memory allocation when the number +of pages it has allocated globally is below this number. +.TP +.I pressure +When the amount of memory allocated by TCP +exceeds this number of pages, TCP moderates its memory consumption. +This memory pressure state is exited +once the number of pages allocated falls below +the +.I low +mark. +.TP +.I high +The maximum number of pages, globally, that TCP will allocate. +This value overrides any other limits imposed by the kernel. +.RE +.TP +.IR tcp_mtu_probing " (integer; default: 0; since Linux 2.6.17)" +.\" The following is from Linux 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +This parameter controls TCP Packetization-Layer Path MTU Discovery. +The following values may be assigned to the file: +.RS +.TP +.B 0 +Disabled +.TP +.B 1 +Disabled by default, enabled when an ICMP black hole detected +.TP +.B 2 +Always enabled, use initial MSS of +.IR tcp_base_mss . +.RE +.TP +.IR tcp_no_metrics_save " (Boolean; default: disabled; since Linux 2.6.6)" +.\" The following is from Linux 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +By default, TCP saves various connection metrics in the route cache +when the connection closes, so that connections established in the +near future can use these to set initial conditions. +Usually, this increases overall performance, +but it may sometimes cause performance degradation. +If +.I tcp_no_metrics_save +is enabled, TCP will not cache metrics on closing connections. +.TP +.IR tcp_orphan_retries " (integer; default: 8; since Linux 2.4)" +.\" Since Linux 2.3.41 +The maximum number of attempts made to probe the other +end of a connection which has been closed by our end. +.TP +.IR tcp_reordering " (integer; default: 3; since Linux 2.4)" +.\" Since Linux 2.4.0-test7 +The maximum a packet can be reordered in a TCP packet stream +without TCP assuming packet loss and going into slow start. +It is not advisable to change this number. +This is a packet reordering detection metric designed to +minimize unnecessary back off and retransmits provoked by +reordering of packets on a connection. +.TP +.IR tcp_retrans_collapse " (Boolean; default: enabled; since Linux 2.2)" +.\" Since Linux 2.1.96 +Try to send full-sized packets during retransmit. +.TP +.IR tcp_retries1 " (integer; default: 3; since Linux 2.2)" +.\" Since Linux 2.1.43 +The number of times TCP will attempt to retransmit a +packet on an established connection normally, +without the extra effort of getting the network layers involved. +Once we exceed this number of +retransmits, we first have the network layer +update the route if possible before each new retransmit. +The default is the RFC specified minimum of 3. +.TP +.IR tcp_retries2 " (integer; default: 15; since Linux 2.2)" +.\" Since Linux 2.1.43 +The maximum number of times a TCP packet is retransmitted +in established state before giving up. +The default value is 15, which corresponds to a duration of +approximately between 13 to 30 minutes, depending +on the retransmission timeout. +The RFC\ 1122 specified +minimum limit of 100 seconds is typically deemed too short. +.TP +.IR tcp_rfc1337 " (Boolean; default: disabled; since Linux 2.2)" +.\" Since Linux 2.1.90 +Enable TCP behavior conformant with RFC\ 1337. +When disabled, +if a RST is received in TIME_WAIT state, we close +the socket immediately without waiting for the end +of the TIME_WAIT period. +.TP +.IR tcp_rmem " (since Linux 2.4)" +.\" Since Linux 2.4.0-test7 +This is a vector of 3 integers: [min, default, max]. +These parameters are used by TCP to regulate receive buffer sizes. +TCP dynamically adjusts the size of the +receive buffer from the defaults listed below, in the range +of these values, depending on memory available in the system. +.RS +.TP +.I min +minimum size of the receive buffer used by each TCP socket. +The default value is the system page size. +(On Linux 2.4, the default value is 4\ kB, lowered to +.B PAGE_SIZE +bytes in low-memory systems.) +This value +is used to ensure that in memory pressure mode, +allocations below this size will still succeed. +This is not +used to bound the size of the receive buffer declared +using +.B SO_RCVBUF +on a socket. +.TP +.I default +the default size of the receive buffer for a TCP socket. +This value overwrites the initial default buffer size from +the generic global +.I net.core.rmem_default +defined for all protocols. +The default value is 87380 bytes. +(On Linux 2.4, this will be lowered to 43689 in low-memory systems.) +If larger receive buffer sizes are desired, this value should +be increased (to affect all sockets). +To employ large TCP windows, the +.I net.ipv4.tcp_window_scaling +must be enabled (default). +.TP +.I max +the maximum size of the receive buffer used by each TCP socket. +This value does not override the global +.IR net.core.rmem_max . +This is not used to limit the size of the receive buffer declared using +.B SO_RCVBUF +on a socket. +The default value is calculated using the formula +.IP +.in +4n +.EX +max(87380, min(4\ MB, \fItcp_mem\fP[1]*PAGE_SIZE/128)) +.EE +.in +.IP +(On Linux 2.4, the default is 87380*2 bytes, +lowered to 87380 in low-memory systems). +.RE +.TP +.IR tcp_sack " (Boolean; default: enabled; since Linux 2.2)" +.\" Since Linux 2.1.36 +Enable RFC\ 2018 TCP Selective Acknowledgements. +.TP +.IR tcp_slow_start_after_idle " (Boolean; default: enabled; since Linux 2.6.18)" +.\" The following is from Linux 2.6.28-rc4: Documentation/networking/ip-sysctl.txt +If enabled, provide RFC 2861 behavior and time out the congestion +window after an idle period. +An idle period is defined as the current RTO (retransmission timeout). +If disabled, the congestion window will not +be timed out after an idle period. +.TP +.IR tcp_stdurg " (Boolean; default: disabled; since Linux 2.2)" +.\" Since Linux 2.1.44 +If this option is enabled, then use the RFC\ 1122 interpretation +of the TCP urgent-pointer field. +.\" RFC 793 was ambiguous in its specification of the meaning of the +.\" urgent pointer. RFC 1122 (and RFC 961) fixed on a particular +.\" resolution of this ambiguity (unfortunately the "wrong" one). +According to this interpretation, the urgent pointer points +to the last byte of urgent data. +If this option is disabled, then use the BSD-compatible interpretation of +the urgent pointer: +the urgent pointer points to the first byte after the urgent data. +Enabling this option may lead to interoperability problems. +.TP +.IR tcp_syn_retries " (integer; default: 6; since Linux 2.2)" +.\" Since Linux 2.1.38 +The maximum number of times initial SYNs for an active TCP +connection attempt will be retransmitted. +This value should not be higher than 255. +The default value is 6, which corresponds to retrying for up to +approximately 127 seconds. +Before Linux 3.7, +.\" commit 6c9ff979d1921e9fd05d89e1383121c2503759b9 +the default value was 5, which +(in conjunction with calculation based on other kernel parameters) +corresponded to approximately 180 seconds. +.TP +.IR tcp_synack_retries " (integer; default: 5; since Linux 2.2)" +.\" Since Linux 2.1.38 +The maximum number of times a SYN/ACK segment +for a passive TCP connection will be retransmitted. +This number should not be higher than 255. +.TP +.IR tcp_syncookies " (integer; default: 1; since Linux 2.2)" +.\" Since Linux 2.1.43 +Enable TCP syncookies. +The kernel must be compiled with +.BR CONFIG_SYN_COOKIES . +The syncookies feature attempts to protect a +socket from a SYN flood attack. +This should be used as a last resort, if at all. +This is a violation of the TCP protocol, +and conflicts with other areas of TCP such as TCP extensions. +It can cause problems for clients and relays. +It is not recommended as a tuning mechanism for heavily +loaded servers to help with overloaded or misconfigured conditions. +For recommended alternatives see +.IR tcp_max_syn_backlog , +.IR tcp_synack_retries , +and +.IR tcp_abort_on_overflow . +Set to one of the following values: +.RS +.TP +.B 0 +Disable TCP syncookies. +.TP +.B 1 +Send out syncookies when the syn backlog queue of a socket overflows. +.TP +.B 2 +(since Linux 3.12) +.\" commit 5ad37d5deee1ff7150a2d0602370101de158ad86 +Send out syncookies unconditionally. +This can be useful for network testing. +.RE +.TP +.IR tcp_timestamps " (integer; default: 1; since Linux 2.2)" +.\" Since Linux 2.1.36 +Set to one of the following values to enable or disable RFC\ 1323 +TCP timestamps: +.RS +.TP +.B 0 +Disable timestamps. +.TP +.B 1 +Enable timestamps as defined in RFC1323 and use random offset for +each connection rather than only using the current time. +.TP +.B 2 +As for the value 1, but without random offsets. +.\" commit 25429d7b7dca01dc4f17205de023a30ca09390d0 +Setting +.I tcp_timestamps +to this value is meaningful since Linux 4.10. +.RE +.TP +.IR tcp_tso_win_divisor " (integer; default: 3; since Linux 2.6.9)" +This parameter controls what percentage of the congestion window +can be consumed by a single TCP Segmentation Offload (TSO) frame. +The setting of this parameter is a tradeoff between burstiness and +building larger TSO frames. +.TP +.IR tcp_tw_recycle " (Boolean; default: disabled; Linux 2.4 to Linux 4.11)" +.\" Since Linux 2.3.15 +.\" removed in Linux 4.12; commit 4396e46187ca5070219b81773c4e65088dac50cc +Enable fast recycling of TIME_WAIT sockets. +Enabling this option is +not recommended as the remote IP may not use monotonically increasing +timestamps (devices behind NAT, devices with per-connection timestamp +offsets). +See RFC 1323 (PAWS) and RFC 6191. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_tw_reuse " (Boolean; default: disabled; since Linux 2.4.19/2.6)" +.\" Since Linux 2.4.19/2.5.43 +Allow to reuse TIME_WAIT sockets for new connections when it is +safe from protocol viewpoint. +It should not be changed without advice/request of technical experts. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_vegas_cong_avoid " (Boolean; default: disabled; Linux 2.2 to Linux 2.6.13)" +.\" Since Linux 2.1.8; removed in Linux 2.6.13 +Enable TCP Vegas congestion avoidance algorithm. +TCP Vegas is a sender-side-only change to TCP that anticipates +the onset of congestion by estimating the bandwidth. +TCP Vegas adjusts the sending rate by modifying the congestion window. +TCP Vegas should provide less packet loss, but it is +not as aggressive as TCP Reno. +.\" +.\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt +.TP +.IR tcp_westwood " (Boolean; default: disabled; Linux 2.4.26/2.6.3 to Linux 2.6.13)" +Enable TCP Westwood+ congestion control algorithm. +TCP Westwood+ is a sender-side-only modification of the TCP Reno +protocol stack that optimizes the performance of TCP congestion control. +It is based on end-to-end bandwidth estimation to set +congestion window and slow start threshold after a congestion episode. +Using this estimation, TCP Westwood+ adaptively sets a +slow start threshold and a congestion window which takes into +account the bandwidth used at the time congestion is experienced. +TCP Westwood+ significantly increases fairness with respect to +TCP Reno in wired networks and throughput over wireless links. +.TP +.IR tcp_window_scaling " (Boolean; default: enabled; since Linux 2.2)" +.\" Since Linux 2.1.36 +Enable RFC\ 1323 TCP window scaling. +This feature allows the use of a large window +(> 64\ kB) on a TCP connection, should the other end support it. +Normally, the 16 bit window length field in the TCP header +limits the window size to less than 64\ kB. +If larger windows are desired, applications can increase the size of +their socket buffers and the window scaling option will be employed. +If +.I tcp_window_scaling +is disabled, TCP will not negotiate the use of window +scaling with the other end during connection setup. +.TP +.IR tcp_wmem " (since Linux 2.4)" +.\" Since Linux 2.4.0-test7 +This is a vector of 3 integers: [min, default, max]. +These parameters are used by TCP to regulate send buffer sizes. +TCP dynamically adjusts the size of the send buffer from the +default values listed below, in the range of these values, +depending on memory available. +.RS +.TP +.I min +Minimum size of the send buffer used by each TCP socket. +The default value is the system page size. +(On Linux 2.4, the default value is 4\ kB.) +This value is used to ensure that in memory pressure mode, +allocations below this size will still succeed. +This is not used to bound the size of the send buffer declared using +.B SO_SNDBUF +on a socket. +.TP +.I default +The default size of the send buffer for a TCP socket. +This value overwrites the initial default buffer size from +the generic global +.I /proc/sys/net/core/wmem_default +defined for all protocols. +The default value is 16\ kB. +.\" True in Linux 2.4 and 2.6 +If larger send buffer sizes are desired, this value +should be increased (to affect all sockets). +To employ large TCP windows, the +.I /proc/sys/net/ipv4/tcp_window_scaling +must be set to a nonzero value (default). +.TP +.I max +The maximum size of the send buffer used by each TCP socket. +This value does not override the value in +.IR /proc/sys/net/core/wmem_max . +This is not used to limit the size of the send buffer declared using +.B SO_SNDBUF +on a socket. +The default value is calculated using the formula +.IP +.in +4n +.EX +max(65536, min(4\ MB, \fItcp_mem\fP[1]*PAGE_SIZE/128)) +.EE +.in +.IP +(On Linux 2.4, the default value is 128\ kB, +lowered 64\ kB depending on low-memory systems.) +.RE +.TP +.IR tcp_workaround_signed_windows " (Boolean; default: disabled; since Linux 2.6.26)" +If enabled, assume that no receipt of a window-scaling option means that the +remote TCP is broken and treats the window as a signed quantity. +If disabled, assume that the remote TCP is not broken even if we do +not receive a window scaling option from it. +.SS Socket options +To set or get a TCP socket option, call +.BR getsockopt (2) +to read or +.BR setsockopt (2) +to write the option with the option level argument set to +.BR IPPROTO_TCP . +Unless otherwise noted, +.I optval +is a pointer to an +.IR int . +.\" or SOL_TCP on Linux +In addition, +most +.B IPPROTO_IP +socket options are valid on TCP sockets. +For more information see +.BR ip (7). +.P +Following is a list of TCP-specific socket options. +For details of some other socket options that are also applicable +for TCP sockets, see +.BR socket (7). +.TP +.BR TCP_CONGESTION " (since Linux 2.6.13)" +.\" commit 5f8ef48d240963093451bcf83df89f1a1364f51d +.\" Author: Stephen Hemminger +The argument for this option is a string. +This option allows the caller to set the TCP congestion control +algorithm to be used, on a per-socket basis. +Unprivileged processes are restricted to choosing one of the algorithms in +.I tcp_allowed_congestion_control +(described above). +Privileged processes +.RB ( CAP_NET_ADMIN ) +can choose from any of the available congestion-control algorithms +(see the description of +.I tcp_available_congestion_control +above). +.TP +.BR TCP_CORK " (since Linux 2.2)" +.\" precisely: since Linux 2.1.127 +If set, don't send out partial frames. +All queued partial frames are sent when the option is cleared again. +This is useful for prepending headers before calling +.BR sendfile (2), +or for throughput optimization. +As currently implemented, there is a 200 millisecond ceiling on the time +for which output is corked by +.BR TCP_CORK . +If this ceiling is reached, then queued data is automatically transmitted. +This option can be combined with +.B TCP_NODELAY +only since Linux 2.5.71. +This option should not be used in code intended to be portable. +.TP +.BR TCP_DEFER_ACCEPT " (since Linux 2.4)" +.\" Precisely: since Linux 2.3.38 +.\" Useful references: +.\" http://www.techrepublic.com/article/take-advantage-of-tcp-ip-options-to-optimize-data-transmission/ +.\" http://unix.stackexchange.com/questions/94104/real-world-use-of-tcp-defer-accept +Allow a listener to be awakened only when data arrives on the socket. +Takes an integer value (seconds), this can +bound the maximum number of attempts TCP will make to +complete the connection. +This option should not be used in code intended to be portable. +.TP +.BR TCP_INFO " (since Linux 2.4)" +Used to collect information about this socket. +The kernel returns a \fIstruct tcp_info\fP as defined in the file +.IR /usr/include/linux/tcp.h . +This option should not be used in code intended to be portable. +.TP +.BR TCP_KEEPCNT " (since Linux 2.4)" +.\" Precisely: since Linux 2.3.18 +The maximum number of keepalive probes TCP should send +before dropping the connection. +This option should not be +used in code intended to be portable. +.TP +.BR TCP_KEEPIDLE " (since Linux 2.4)" +.\" Precisely: since Linux 2.3.18 +The time (in seconds) the connection needs to remain idle +before TCP starts sending keepalive probes, if the socket +option +.B SO_KEEPALIVE +has been set on this socket. +This option should not be used in code intended to be portable. +.TP +.BR TCP_KEEPINTVL " (since Linux 2.4)" +.\" Precisely: since Linux 2.3.18 +The time (in seconds) between individual keepalive probes. +This option should not be used in code intended to be portable. +.TP +.BR TCP_LINGER2 " (since Linux 2.4)" +.\" Precisely: since Linux 2.3.41 +The lifetime of orphaned FIN_WAIT2 state sockets. +This option can be used to override the system-wide setting in the file +.I /proc/sys/net/ipv4/tcp_fin_timeout +for this socket. +This is not to be confused with the +.BR socket (7) +level option +.BR SO_LINGER . +This option should not be used in code intended to be portable. +.TP +.B TCP_MAXSEG +.\" Present in Linux 1.0 +The maximum segment size for outgoing TCP packets. +In Linux 2.2 and earlier, and in Linux 2.6.28 and later, +if this option is set before connection establishment, it also +changes the MSS value announced to the other end in the initial packet. +Values greater than the (eventual) interface MTU have no effect. +TCP will also impose +its minimum and maximum bounds over the value provided. +.TP +.B TCP_NODELAY +.\" Present in Linux 1.0 +If set, disable the Nagle algorithm. +This means that segments +are always sent as soon as possible, even if there is only a +small amount of data. +When not set, data is buffered until there +is a sufficient amount to send out, thereby avoiding the +frequent sending of small packets, which results in poor +utilization of the network. +This option is overridden by +.BR TCP_CORK ; +however, setting this option forces an explicit flush of +pending output, even if +.B TCP_CORK +is currently set. +.TP +.BR TCP_QUICKACK " (since Linux 2.4.4)" +Enable quickack mode if set or disable quickack +mode if cleared. +In quickack mode, acks are sent +immediately, rather than delayed if needed in accordance +to normal TCP operation. +This flag is not permanent, +it only enables a switch to or from quickack mode. +Subsequent operation of the TCP protocol will +once again enter/leave quickack mode depending on +internal protocol processing and factors such as +delayed ack timeouts occurring and data transfer. +This option should not be used in code intended to be +portable. +.TP +.BR TCP_SYNCNT " (since Linux 2.4)" +.\" Precisely: since Linux 2.3.18 +Set the number of SYN retransmits that TCP should send before +aborting the attempt to connect. +It cannot exceed 255. +This option should not be used in code intended to be portable. +.TP +.BR TCP_USER_TIMEOUT " (since Linux 2.6.37)" +.\" commit dca43c75e7e545694a9dd6288553f55c53e2a3a3 +.\" Author: Jerry Chu +.\" The following text taken nearly verbatim from Jerry Chu's (excellent) +.\" commit message. +.\" +This option takes an +.I unsigned int +as an argument. +When the value is greater than 0, +it specifies the maximum amount of time in milliseconds that transmitted +data may remain unacknowledged, or buffered data may remain untransmitted +(due to zero window size) before TCP will forcibly close the +corresponding connection and return +.B ETIMEDOUT +to the application. +If the option value is specified as 0, +TCP will use the system default. +.IP +Increasing user timeouts allows a TCP connection to survive extended +periods without end-to-end connectivity. +Decreasing user timeouts +allows applications to "fail fast", if so desired. +Otherwise, failure may take up to 20 minutes with +the current system defaults in a normal WAN environment. +.IP +This option can be set during any state of a TCP connection, +but is effective only during the synchronized states of a connection +(ESTABLISHED, FIN-WAIT-1, FIN-WAIT-2, CLOSE-WAIT, CLOSING, and LAST-ACK). +Moreover, when used with the TCP keepalive +.RB ( SO_KEEPALIVE ) +option, +.B TCP_USER_TIMEOUT +will override keepalive to determine when to close a +connection due to keepalive failure. +.IP +The option has no effect on when TCP retransmits a packet, +nor when a keepalive probe is sent. +.IP +This option, like many others, will be inherited by the socket returned by +.BR accept (2), +if it was set on the listening socket. +.IP +Further details on the user timeout feature can be found in +RFC\ 793 and RFC\ 5482 ("TCP User Timeout Option"). +.TP +.BR TCP_WINDOW_CLAMP " (since Linux 2.4)" +.\" Precisely: since Linux 2.3.41 +Bound the size of the advertised window to this value. +The kernel imposes a minimum size of SOCK_MIN_RCVBUF/2. +This option should not be used in code intended to be +portable. +.TP +.BR TCP_FASTOPEN " (since Linux 3.6)" +This option enables Fast Open (RFC\~7413) on the listener socket. +The value specifies the maximum length of pending SYNs +(similar to the backlog argument in +.BR listen (2)). +Once enabled, +the listener socket grants the TCP Fast Open cookie +on incoming SYN with TCP Fast Open option. +.IP +More importantly it accepts the data in SYN with a valid Fast Open cookie +and responds SYN-ACK acknowledging both the data and the SYN sequence. +.BR accept (2) +returns a socket that is available for read and write +when the handshake has not completed yet. +Thus the data exchange can commence before the handshake completes. +This option requires enabling the server-side support on sysctl +.I net.ipv4.tcp_fastopen +(see above). +For TCP Fast Open client-side support, +see +.BR send (2) +.B MSG_FASTOPEN +or +.B TCP_FASTOPEN_CONNECT +below. +.TP +.BR TCP_FASTOPEN_CONNECT " (since Linux 4.11)" +This option enables an alternative way to perform Fast Open +on the active side (client). +When this option is enabled, +.BR connect (2) +would behave differently depending on +if a Fast Open cookie is available for the destination. +.IP +If a cookie is not available (i.e. first contact to the destination), +.BR connect (2) +behaves as usual by sending a SYN immediately, +except the SYN would include an empty Fast Open cookie option +to solicit a cookie. +.IP +If a cookie is available, +.BR connect (2) +would return 0 immediately but the SYN transmission is deferred. +A subsequent +.BR write (2) +or +.BR sendmsg (2) +would trigger a SYN with data plus cookie in the Fast Open option. +In other words, +the actual connect operation is deferred until data is supplied. +.IP +.B Note: +While this option is designed for convenience, +enabling it does change the behaviors and certain system calls might set +different +.I errno +values. +With cookie present, +.BR write (2) +or +.BR sendmsg (2) +must be called right after +.BR connect (2) +in order to send out SYN+data to complete 3WHS and establish connection. +Calling +.BR read (2) +right after +.BR connect (2) +without +.BR write (2) +will cause the blocking socket to be blocked forever. +.IP +The application should either set +.B TCP_FASTOPEN_CONNECT +socket option before +.BR write (2) +or +.BR sendmsg (2), +or call +.BR write (2) +or +.BR sendmsg (2) +with +.B MSG_FASTOPEN +flag directly, +instead of both on the same connection. +.IP +Here is the typical call flow with this new option: +.IP +.in +4n +.EX +s = socket(); +setsockopt(s, IPPROTO_TCP, TCP_FASTOPEN_CONNECT, 1, ...); +connect(s); +write(s); /* write() should always follow connect() + * in order to trigger SYN to go out. */ +read(s)/write(s); +/* ... */ +close(s); +.EE +.in +.SS Sockets API +TCP provides limited support for out-of-band data, +in the form of (a single byte of) urgent data. +In Linux this means if the other end sends newer out-of-band +data the older urgent data is inserted as normal data into +the stream (even when +.B SO_OOBINLINE +is not set). +This differs from BSD-based stacks. +.P +Linux uses the BSD compatible interpretation of the urgent +pointer field by default. +This violates RFC\ 1122, but is +required for interoperability with other stacks. +It can be changed via +.IR /proc/sys/net/ipv4/tcp_stdurg . +.P +It is possible to peek at out-of-band data using the +.BR recv (2) +.B MSG_PEEK +flag. +.P +Since Linux 2.4, Linux supports the use of +.B MSG_TRUNC +in the +.I flags +argument of +.BR recv (2) +(and +.BR recvmsg (2)). +This flag causes the received bytes of data to be discarded, +rather than passed back in a caller-supplied buffer. +Since Linux 2.4.4, +.B MSG_TRUNC +also has this effect when used in conjunction with +.B MSG_OOB +to receive out-of-band data. +.SS Ioctls +The following +.BR ioctl (2) +calls return information in +.IR value . +The correct syntax is: +.P +.RS +.nf +.BI int " value"; +.IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");" +.fi +.RE +.P +.I ioctl_type +is one of the following: +.TP +.B SIOCINQ +Returns the amount of queued unread data in the receive buffer. +The socket must not be in LISTEN state, otherwise an error +.RB ( EINVAL ) +is returned. +.B SIOCINQ +is defined in +.IR . +.\" FIXME https://www.sourceware.org/bugzilla/show_bug.cgi?id=12002, +.\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers +Alternatively, +you can use the synonymous +.BR FIONREAD , +defined in +.IR . +.TP +.B SIOCATMARK +Returns true (i.e., +.I value +is nonzero) if the inbound data stream is at the urgent mark. +.IP +If the +.B SO_OOBINLINE +socket option is set, and +.B SIOCATMARK +returns true, then the +next read from the socket will return the urgent data. +If the +.B SO_OOBINLINE +socket option is not set, and +.B SIOCATMARK +returns true, then the +next read from the socket will return the bytes following +the urgent data (to actually read the urgent data requires the +.B recv(MSG_OOB) +flag). +.IP +Note that a read never reads across the urgent mark. +If an application is informed of the presence of urgent data via +.BR select (2) +(using the +.I exceptfds +argument) or through delivery of a +.B SIGURG +signal, +then it can advance up to the mark using a loop which repeatedly tests +.B SIOCATMARK +and performs a read (requesting any number of bytes) as long as +.B SIOCATMARK +returns false. +.TP +.B SIOCOUTQ +Returns the amount of unsent data in the socket send queue. +The socket must not be in LISTEN state, otherwise an error +.RB ( EINVAL ) +is returned. +.B SIOCOUTQ +is defined in +.IR . +.\" FIXME . https://www.sourceware.org/bugzilla/show_bug.cgi?id=12002, +.\" filed 2010-09-10, may cause SIOCOUTQ to be defined in glibc headers +Alternatively, +you can use the synonymous +.BR TIOCOUTQ , +defined in +.IR . +.SS Error handling +When a network error occurs, TCP tries to resend the packet. +If it doesn't succeed after some time, either +.B ETIMEDOUT +or the last received error on this connection is reported. +.P +Some applications require a quicker error notification. +This can be enabled with the +.B IPPROTO_IP +level +.B IP_RECVERR +socket option. +When this option is enabled, all incoming +errors are immediately passed to the user program. +Use this option with care \[em] it makes TCP less tolerant to routing +changes and other normal network conditions. +.SH ERRORS +.TP +.B EAFNOTSUPPORT +Passed socket address type in +.I sin_family +was not +.BR AF_INET . +.TP +.B EPIPE +The other end closed the socket unexpectedly or a read is +executed on a shut down socket. +.TP +.B ETIMEDOUT +The other end didn't acknowledge retransmitted data after some time. +.P +Any errors defined for +.BR ip (7) +or the generic socket layer may also be returned for TCP. +.SH VERSIONS +Support for Explicit Congestion Notification, zero-copy +.BR sendfile (2), +reordering support and some SACK extensions +(DSACK) were introduced in Linux 2.4. +Support for forward acknowledgement (FACK), TIME_WAIT recycling, +and per-connection keepalive socket options were introduced in Linux 2.3. +.SH BUGS +Not all errors are documented. +.P +IPv6 is not described. +.\" Only a single Linux kernel version is described +.\" Info for 2.2 was lost. Should be added again, +.\" or put into a separate page. +.\" .SH AUTHORS +.\" This man page was originally written by Andi Kleen. +.\" It was updated for 2.4 by Nivedita Singhvi with input from +.\" Alexey Kuznetsov's Documentation/networking/ip-sysctl.txt +.\" document. +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR connect (2), +.BR getsockopt (2), +.BR listen (2), +.BR recvmsg (2), +.BR sendfile (2), +.BR sendmsg (2), +.BR socket (2), +.BR ip (7), +.BR socket (7) +.P +The kernel source file +.IR Documentation/networking/ip\-sysctl.txt . +.P +RFC\ 793 for the TCP specification. +.br +RFC\ 1122 for the TCP requirements and a description of the Nagle algorithm. +.br +RFC\ 1323 for TCP timestamp and window scaling options. +.br +RFC\ 1337 for a description of TIME_WAIT assassination hazards. +.br +RFC\ 3168 for a description of Explicit Congestion Notification. +.br +RFC\ 2581 for TCP congestion control algorithms. +.br +RFC\ 2018 and RFC\ 2883 for SACK and extensions to SACK. diff --git a/man/man7/termio.7 b/man/man7/termio.7 new file mode 100644 index 0000000..8643ac5 --- /dev/null +++ b/man/man7/termio.7 @@ -0,0 +1,45 @@ +.\" Copyright (c) 2006 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 28 Dec 2006 - Initial Creation +.\" +.TH termio 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +termio \- System V terminal driver interface +.SH DESCRIPTION +.B termio +is the name of the old System V terminal driver interface. +This interface defined a +.I termio +structure used to store terminal settings, and a range of +.BR ioctl (2) +operations to get and set terminal attributes. +.P +The +.B termio +interface is now obsolete: POSIX.1-1990 standardized a modified +version of this interface, under the name +.BR termios . +The POSIX.1 data structure differs slightly from the +System V version, and POSIX.1 defined a suite of functions +to replace the various +.BR ioctl (2) +operations that existed in System V. +(This was done because +.BR ioctl (2) +was unstandardized, and its variadic third argument +does not allow argument type checking.) +.P +If you're looking for a page called "termio", then you can probably +find most of the information that you seek in either +.BR termios (3) +or +.BR ioctl_tty (2). +.SH SEE ALSO +.BR reset (1), +.BR setterm (1), +.BR stty (1), +.BR ioctl_tty (2), +.BR termios (3), +.BR tty (4) diff --git a/man/man7/thread-keyring.7 b/man/man7/thread-keyring.7 new file mode 100644 index 0000000..fa79a09 --- /dev/null +++ b/man/man7/thread-keyring.7 @@ -0,0 +1,50 @@ +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH thread-keyring 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +thread-keyring \- per-thread keyring +.SH DESCRIPTION +The thread keyring is a keyring used to anchor keys on behalf of a process. +It is created only when a thread requests it. +The thread keyring has the name (description) +.IR _tid . +.P +A special serial number value, +.BR KEY_SPEC_THREAD_KEYRING , +is defined that can be used in lieu of the actual serial number of +the calling thread's thread keyring. +.P +From the +.BR keyctl (1) +utility, '\fB@t\fP' can be used instead of a numeric key ID in +much the same way, but as +.BR keyctl (1) +is a program run after forking, this is of no utility. +.P +Thread keyrings are not inherited across +.BR clone (2) +and +.BR fork (2) +and are cleared by +.BR execve (2). +A thread keyring is destroyed when the thread that refers to it terminates. +.P +Initially, a thread does not have a thread keyring. +If a thread doesn't have a thread keyring when it is accessed, +then it will be created if it is to be modified; +otherwise the operation fails with the error +.BR ENOKEY . +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyrings (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR user\-keyring (7), +.BR user\-session\-keyring (7) diff --git a/man/man7/time.7 b/man/man7/time.7 new file mode 100644 index 0000000..8d472a6 --- /dev/null +++ b/man/man7/time.7 @@ -0,0 +1,218 @@ +.\" Copyright (c) 2006 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2008-06-24, mtk: added some details about where jiffies come into +.\" play; added section on high-resolution timers. +.\" +.TH time 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +time \- overview of time and timers +.SH DESCRIPTION +.SS Real time and process time +.I "Real time" +is defined as time measured from some fixed point, +either from a standard point in the past +(see the description of the Epoch and calendar time below), +or from some point (e.g., the start) in the life of a process +.RI ( "elapsed time" ). +.P +.I "Process time" +is defined as the amount of CPU time used by a process. +This is sometimes divided into +.I user +and +.I system +components. +User CPU time is the time spent executing code in user mode. +System CPU time is the time spent by the kernel executing +in system mode on behalf of the process (e.g., executing system calls). +The +.BR time (1) +command can be used to determine the amount of CPU time consumed +during the execution of a program. +A program can determine the amount of CPU time it has consumed using +.BR times (2), +.BR getrusage (2), +or +.BR clock (3). +.SS The hardware clock +Most computers have a (battery-powered) hardware clock which the kernel +reads at boot time in order to initialize the software clock. +For further details, see +.BR rtc (4) +and +.BR hwclock (8). +.SS The software clock, HZ, and jiffies +The accuracy of various system calls that set timeouts, +(e.g., +.BR select (2), +.BR sigtimedwait (2)) +.\" semtimedop(), mq_timedwait(), io_getevents(), poll() are the same +.\" futexes and thus sem_timedwait() seem to use high-res timers. +and measure CPU time (e.g., +.BR getrusage (2)) +is limited by the resolution of the +.IR "software clock" , +a clock maintained by the kernel which measures time in +.IR jiffies . +The size of a jiffy is determined by the value of the kernel constant +.IR HZ . +.P +The value of +.I HZ +varies across kernel versions and hardware platforms. +On i386 the situation is as follows: +on kernels up to and including Linux 2.4.x, +HZ was 100, +giving a jiffy value of 0.01 seconds; +starting with Linux 2.6.0, +HZ was raised to 1000, +giving a jiffy of 0.001 seconds. +Since Linux 2.6.13, the HZ value is a kernel +configuration parameter and can be 100, 250 (the default) or 1000, +yielding a jiffies value of, respectively, 0.01, 0.004, or 0.001 seconds. +Since Linux 2.6.20, a further frequency is available: +300, a number that divides evenly for the common video frame rates +(PAL, 25 Hz; NTSC, 30 Hz). +.P +The +.BR times (2) +system call is a special case. +It reports times with a granularity defined by the kernel constant +.IR USER_HZ . +User-space applications can determine the value of this constant using +.IR sysconf(_SC_CLK_TCK) . +.\" glibc gets this info with a little help from the ELF loader; +.\" see glibc elf/dl-support.c and kernel fs/binfmt_elf.c. +.\" +.SS System and process clocks; time namespaces +The kernel supports a range of clocks that measure various kinds of +elapsed and virtual (i.e., consumed CPU) time. +These clocks are described in +.BR clock_gettime (2). +A few of the clocks are settable using +.BR clock_settime (2). +The values of certain clocks are virtualized by time namespaces; see +.BR time_namespaces (7). +.\" +.SS High-resolution timers +Before Linux 2.6.21, the accuracy of timer and sleep system calls +(see below) was also limited by the size of the jiffy. +.P +Since Linux 2.6.21, Linux supports high-resolution timers (HRTs), +optionally configurable via +.BR CONFIG_HIGH_RES_TIMERS . +On a system that supports HRTs, the accuracy of sleep and timer +system calls is no longer constrained by the jiffy, +but instead can be as accurate as the hardware allows +(microsecond accuracy is typical of modern hardware). +You can determine whether high-resolution timers are supported by +checking the resolution returned by a call to +.BR clock_getres (2) +or looking at the "resolution" entries in +.IR /proc/timer_list . +.P +HRTs are not supported on all hardware architectures. +(Support is provided on x86, ARM, and PowerPC, among others.) +.SS The Epoch +UNIX systems represent time in seconds since the +.IR Epoch , +1970-01-01 00:00:00 +0000 (UTC). +.P +A program can determine the +.I "calendar time" +via the +.BR clock_gettime (2) +.B CLOCK_REALTIME +clock, +which returns time (in seconds and nanoseconds) that have +elapsed since the Epoch; +.BR time (2) +provides similar information, but only with accuracy to the +nearest second. +The system time can be changed using +.BR clock_settime (2). +.\" +.SS Broken-down time +Certain library functions use a structure of +type +.I tm +to represent +.IR "broken-down time" , +which stores time value separated out into distinct components +(year, month, day, hour, minute, second, etc.). +This structure is described in +.BR tm (3type), +which also describes functions that convert between calendar time and +broken-down time. +Functions for converting between broken-down time and printable +string representations of the time are described in +.BR ctime (3), +.BR strftime (3), +and +.BR strptime (3). +.SS Sleeping and setting timers +Various system calls and functions allow a program to sleep +(suspend execution) for a specified period of time; see +.BR nanosleep (2), +.BR clock_nanosleep (2), +and +.BR sleep (3). +.P +Various system calls allow a process to set a timer that expires +at some point in the future, and optionally at repeated intervals; +see +.BR alarm (2), +.BR getitimer (2), +.BR timerfd_create (2), +and +.BR timer_create (2). +.SS Timer slack +Since Linux 2.6.28, it is possible to control the "timer slack" +value for a thread. +The timer slack is the length of time by +which the kernel may delay the wake-up of certain +system calls that block with a timeout. +Permitting this delay allows the kernel to coalesce wake-up events, +thus possibly reducing the number of system wake-ups and saving power. +For more details, see the description of +.B PR_SET_TIMERSLACK +in +.BR prctl (2). +.SH SEE ALSO +.ad l +.nh +.BR date (1), +.BR time (1), +.BR timeout (1), +.BR adjtimex (2), +.BR alarm (2), +.BR clock_gettime (2), +.BR clock_nanosleep (2), +.BR getitimer (2), +.BR getrlimit (2), +.BR getrusage (2), +.BR gettimeofday (2), +.BR nanosleep (2), +.BR stat (2), +.BR time (2), +.BR timer_create (2), +.BR timerfd_create (2), +.BR times (2), +.BR utime (2), +.BR adjtime (3), +.BR clock (3), +.BR clock_getcpuclockid (3), +.BR ctime (3), +.BR ntp_adjtime (3), +.BR ntp_gettime (3), +.BR pthread_getcpuclockid (3), +.BR sleep (3), +.BR strftime (3), +.BR strptime (3), +.BR timeradd (3), +.BR usleep (3), +.BR rtc (4), +.BR time_namespaces (7), +.BR hwclock (8) diff --git a/man/man7/time_namespaces.7 b/man/man7/time_namespaces.7 new file mode 100644 index 0000000..ba2a341 --- /dev/null +++ b/man/man7/time_namespaces.7 @@ -0,0 +1,345 @@ +.\" Copyright (c) 2020 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH time_namespaces 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +time_namespaces \- overview of Linux time namespaces +.SH DESCRIPTION +Time namespaces virtualize the values of two system clocks: +.IP \[bu] 3 +.B CLOCK_MONOTONIC +(and likewise +.B CLOCK_MONOTONIC_COARSE +and +.BR CLOCK_MONOTONIC_RAW ), +a nonsettable clock that represents monotonic time since\[em]as +described by POSIX\[em]"some unspecified point in the past". +.IP \[bu] +.B CLOCK_BOOTTIME +(and likewise +.BR CLOCK_BOOTTIME_ALARM ), +a nonsettable clock that is identical to +.BR CLOCK_MONOTONIC , +except that it also includes any time that the system is suspended. +.P +Thus, the processes in a time namespace share per-namespace values +for these clocks. +This affects various APIs that measure against these clocks, including: +.BR clock_gettime (2), +.BR clock_nanosleep (2), +.BR nanosleep (2), +.BR timer_settime (2), +.BR timerfd_settime (2), +and +.IR /proc/uptime . +.P +Currently, the only way to create a time namespace is by calling +.BR unshare (2) +with the +.B CLONE_NEWTIME +flag. +This call creates a new time namespace but does +.I not +place the calling process in the new namespace. +Instead, the calling process's +subsequently created children are placed in the new namespace. +This allows clock offsets (see below) for the new namespace +to be set before the first process is placed in the namespace. +The +.IR /proc/ pid /ns/time_for_children +symbolic link shows the time namespace in which +the children of a process will be created. +(A process can use a file descriptor opened on +this symbolic link in a call to +.BR setns (2) +in order to move into the namespace.) +.\" +.SS \fI/proc/\fPpid\fI/timens_offsets\fP +Associated with each time namespace are offsets, +expressed with respect to the initial time namespace, +that define the values of the monotonic and +boot-time clocks in that namespace. +These offsets are exposed via the file +.IR /proc/ pid /timens_offsets . +Within this file, +the offsets are expressed as lines consisting of +three space-delimited fields: +.P +.in +4n +.EX + +.EE +.in +.P +The +.I clock-id +is a string that identifies the clock whose offsets are being shown. +This field is either +.IR monotonic , +for +.BR CLOCK_MONOTONIC , +or +.IR boottime , +for +.BR CLOCK_BOOTTIME . +The remaining fields express the offset (seconds plus nanoseconds) for the +clock in this time namespace. +These offsets are expressed relative to the clock values in +the initial time namespace. +The +.I offset-secs +value can be negative, subject to restrictions noted below; +.I offset-nanosecs +is an unsigned value. +.P +In the initial time namespace, the contents of the +.I timens_offsets +file are as follows: +.P +.in +4n +.EX +$ \fBcat /proc/self/timens_offsets\fP +monotonic 0 0 +boottime 0 0 +.EE +.in +.P +In a new time namespace that has had no member processes, +the clock offsets can be modified by writing newline-terminated +records of the same form to the +.I timens_offsets +file. +The file can be written to multiple times, +but after the first process has been created in or has entered the namespace, +.BR write (2)s +on this file fail with the error +.BR EACCES . +In order to write to the +.I timens_offsets +file, a process must have the +.B CAP_SYS_TIME +capability in the user namespace that owns the time namespace. +.P +Writes to the +.I timens_offsets +file can fail with the following errors: +.TP +.B EINVAL +An +.I offset-nanosecs +value is greater than 999,999,999. +.TP +.B EINVAL +A +.I clock-id +value is not valid. +.TP +.B EPERM +The caller does not have the +.B CAP_SYS_TIME +capability. +.TP +.B ERANGE +An +.I offset-secs +value is out of range. +In particular; +.RS +.IP \[bu] 3 +.I offset-secs +can't be set to a value which would make the current +time on the corresponding clock inside the namespace a negative value; and +.IP \[bu] +.I offset-secs +can't be set to a value such that the time on the corresponding clock +inside the namespace would exceed half of the value of the kernel constant +.B KTIME_SEC_MAX +(this limits the clock value to a maximum of approximately 146 years). +.RE +.P +In a new time namespace created by +.BR unshare (2), +the contents of the +.I timens_offsets +file are inherited from the time namespace of the creating process. +.SH NOTES +Use of time namespaces requires a kernel that is configured with the +.B CONFIG_TIME_NS +option. +.P +Note that time namespaces do not virtualize the +.B CLOCK_REALTIME +clock. +Virtualization of this clock was avoided for reasons of complexity +and overhead within the kernel. +.P +For compatibility with the initial implementation, when writing a +.I clock-id +to the +.IR /proc/ pid /timens_offsets +file, the numerical values of the IDs can be written +instead of the symbolic names show above; i.e., 1 instead of +.IR monotonic , +and 7 instead of +.IR boottime . +For readability, the use of the symbolic names over the numbers is preferred. +.P +The motivation for adding time namespaces was to allow +the monotonic and boot-time clocks to maintain consistent values +during container migration and checkpoint/restore. +.SH EXAMPLES +The following shell session demonstrates the operation of time namespaces. +We begin by displaying the inode number of the time namespace +of a shell in the initial time namespace: +.P +.in +4n +.EX +$ \fBreadlink /proc/$$/ns/time\fP +time:[4026531834] +.EE +.in +.P +Continuing in the initial time namespace, we display the system uptime using +.BR uptime (1) +and use the +.I clock_times +example program shown in +.BR clock_getres (2) +to display the values of various clocks: +.P +.in +4n +.EX +$ \fBuptime \-\-pretty\fP +up 21 hours, 17 minutes +$ \fB./clock_times\fP +CLOCK_REALTIME : 1585989401.971 (18356 days + 8h 36m 41s) +CLOCK_TAI : 1585989438.972 (18356 days + 8h 37m 18s) +CLOCK_MONOTONIC: 56338.247 (15h 38m 58s) +CLOCK_BOOTTIME : 76633.544 (21h 17m 13s) +.EE +.in +.P +We then use +.BR unshare (1) +to create a time namespace and execute a +.BR bash (1) +shell. +From the new shell, we use the built-in +.B echo +command to write records to the +.I timens_offsets +file adjusting the offset for the +.B CLOCK_MONOTONIC +clock forward 2 days +and the offset for the +.B CLOCK_BOOTTIME +clock forward 7 days: +.P +.in +4n +.EX +$ \fBPS1="ns2# " sudo unshare \-T \-\- bash \-\-norc\fP +ns2# \fBecho "monotonic $((2*24*60*60)) 0" > /proc/$$/timens_offsets\fP +ns2# \fBecho "boottime $((7*24*60*60)) 0" > /proc/$$/timens_offsets\fP +.EE +.in +.P +Above, we started the +.BR bash (1) +shell with the +.B \-\-norc +option so that no start-up scripts were executed. +This ensures that no child processes are created from the +shell before we have a chance to update the +.I timens_offsets +file. +.P +We then use +.BR cat (1) +to display the contents of the +.I timens_offsets +file. +The execution of +.BR cat (1) +creates the first process in the new time namespace, +after which further attempts to update the +.I timens_offsets +file produce an error. +.P +.in +4n +.EX +ns2# \fBcat /proc/$$/timens_offsets\fP +monotonic 172800 0 +boottime 604800 0 +ns2# \fBecho "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets\fP +bash: echo: write error: Permission denied +.EE +.in +.P +Continuing in the new namespace, we execute +.BR uptime (1) +and the +.I clock_times +example program: +.P +.in +4n +.EX +ns2# \fBuptime \-\-pretty\fP +up 1 week, 21 hours, 18 minutes +ns2# \fB./clock_times\fP +CLOCK_REALTIME : 1585989457.056 (18356 days + 8h 37m 37s) +CLOCK_TAI : 1585989494.057 (18356 days + 8h 38m 14s) +CLOCK_MONOTONIC: 229193.332 (2 days + 15h 39m 53s) +CLOCK_BOOTTIME : 681488.629 (7 days + 21h 18m 8s) +.EE +.in +.P +From the above output, we can see that the monotonic +and boot-time clocks have different values in the new time namespace. +.P +Examining the +.IR /proc/ pid /ns/time +and +.IR /proc/ pid /ns/time_for_children +symbolic links, we see that the shell is a member of the initial time +namespace, but its children are created in the new namespace. +.P +.in +4n +.EX +ns2# \fBreadlink /proc/$$/ns/time\fP +time:[4026531834] +ns2# \fBreadlink /proc/$$/ns/time_for_children\fP +time:[4026532900] +ns2# \fBreadlink /proc/self/ns/time\fP # Creates a child process +time:[4026532900] +.EE +.in +.P +Returning to the shell in the initial time namespace, +we see that the monotonic and boot-time clocks +are unaffected by the +.I timens_offsets +changes that were made in the other time namespace: +.P +.in +4n +.EX +$ \fBuptime \-\-pretty\fP +up 21 hours, 19 minutes +$ \fB./clock_times\fP +CLOCK_REALTIME : 1585989401.971 (18356 days + 8h 38m 51s) +CLOCK_TAI : 1585989438.972 (18356 days + 8h 39m 28s) +CLOCK_MONOTONIC: 56338.247 (15h 41m 8s) +CLOCK_BOOTTIME : 76633.544 (21h 19m 23s) +.EE +.in +.SH SEE ALSO +.BR nsenter (1), +.BR unshare (1), +.BR clock_settime (2), +.\" clone3() support for time namespaces is a work in progress +.\" .BR clone3 (2), +.BR setns (2), +.BR unshare (2), +.BR namespaces (7), +.BR time (7) diff --git a/man/man7/tis-620.7 b/man/man7/tis-620.7 new file mode 100644 index 0000000..cbd4cfe --- /dev/null +++ b/man/man7/tis-620.7 @@ -0,0 +1 @@ +.so man7/iso_8859-11.7 diff --git a/man/man7/udp.7 b/man/man7/udp.7 new file mode 100644 index 0000000..5c6a490 --- /dev/null +++ b/man/man7/udp.7 @@ -0,0 +1,312 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen . +.\" +.\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $ +.\" +.TH udp 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +udp \- User Datagram Protocol for IPv4 +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.P +.IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" +.fi +.SH DESCRIPTION +This is an implementation of the User Datagram Protocol +described in RFC\ 768. +It implements a connectionless, unreliable datagram packet service. +Packets may be reordered or duplicated before they arrive. +UDP generates and checks checksums to catch transmission errors. +.P +When a UDP socket is created, +its local and remote addresses are unspecified. +Datagrams can be sent immediately using +.BR sendto (2) +or +.BR sendmsg (2) +with a valid destination address as an argument. +When +.BR connect (2) +is called on the socket, the default destination address is set and +datagrams can now be sent using +.BR send (2) +or +.BR write (2) +without specifying a destination address. +It is still possible to send to other destinations by passing an +address to +.BR sendto (2) +or +.BR sendmsg (2). +In order to receive packets, the socket can be bound to a local +address first by using +.BR bind (2). +Otherwise, the socket layer will automatically assign +a free local port out of the range defined by +.I /proc/sys/net/ipv4/ip_local_port_range +and bind the socket to +.BR INADDR_ANY . +.P +All receive operations return only one packet. +When the packet is smaller than the passed buffer, only that much +data is returned; when it is bigger, the packet is truncated and the +.B MSG_TRUNC +flag is set. +.B MSG_WAITALL +is not supported. +.P +IP options may be sent or received using the socket options described in +.BR ip (7). +They are processed by the kernel only when the appropriate +.I /proc +parameter +is enabled (but still passed to the user even when it is turned off). +See +.BR ip (7). +.P +When the +.B MSG_DONTROUTE +flag is set on sending, the destination address must refer to a local +interface address and the packet is sent only to that interface. +.P +By default, Linux UDP does path MTU (Maximum Transmission Unit) discovery. +This means the kernel +will keep track of the MTU to a specific target IP address and return +.B EMSGSIZE +when a UDP packet write exceeds it. +When this happens, the application should decrease the packet size. +Path MTU discovery can be also turned off using the +.B IP_MTU_DISCOVER +socket option or the +.I /proc/sys/net/ipv4/ip_no_pmtu_disc +file; see +.BR ip (7) +for details. +When turned off, UDP will fragment outgoing UDP packets +that exceed the interface MTU. +However, disabling it is not recommended +for performance and reliability reasons. +.SS Address format +UDP uses the IPv4 +.I sockaddr_in +address format described in +.BR ip (7). +.SS Error handling +All fatal errors will be passed to the user as an error return even +when the socket is not connected. +This includes asynchronous errors +received from the network. +You may get an error for an earlier packet +that was sent on the same socket. +This behavior differs from many other BSD socket implementations +which don't pass any errors unless the socket is connected. +Linux's behavior is mandated by +.BR RFC\ 1122 . +.P +For compatibility with legacy code, in Linux 2.0 and 2.2 +it was possible to set the +.B SO_BSDCOMPAT +.B SOL_SOCKET +option to receive remote errors only when the socket has been +connected (except for +.B EPROTO +and +.BR EMSGSIZE ). +Locally generated errors are always passed. +Support for this socket option was removed in later kernels; see +.BR socket (7) +for further information. +.P +When the +.B IP_RECVERR +option is enabled, all errors are stored in the socket error queue, +and can be received by +.BR recvmsg (2) +with the +.B MSG_ERRQUEUE +flag set. +.SS /proc interfaces +System-wide UDP parameter settings can be accessed by files in the directory +.IR /proc/sys/net/ipv4/ . +.TP +.IR udp_mem " (since Linux 2.6.25)" +This is a vector of three integers governing the number +of pages allowed for queueing by all UDP sockets. +.RS +.TP +.I min +Below this number of pages, UDP is not bothered about its +memory appetite. +When the amount of memory allocated by UDP exceeds +this number, UDP starts to moderate memory usage. +.TP +.I pressure +This value was introduced to follow the format of +.I tcp_mem +(see +.BR tcp (7)). +.TP +.I max +Number of pages allowed for queueing by all UDP sockets. +.RE +.IP +Defaults values for these three items are +calculated at boot time from the amount of available memory. +.TP +.IR udp_rmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)" +Minimal size, in bytes, of receive buffers used by UDP sockets in moderation. +Each UDP socket is able to use the size for receiving data, +even if total pages of UDP sockets exceed +.I udp_mem +pressure. +.TP +.IR udp_wmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)" +Minimal size, in bytes, of send buffer used by UDP sockets in moderation. +Each UDP socket is able to use the size for sending data, +even if total pages of UDP sockets exceed +.I udp_mem +pressure. +.SS Socket options +To set or get a UDP socket option, call +.BR getsockopt (2) +to read or +.BR setsockopt (2) +to write the option with the option level argument set to +.BR IPPROTO_UDP . +Unless otherwise noted, +.I optval +is a pointer to an +.IR int . +.P +Following is a list of UDP-specific socket options. +For details of some other socket options that are also applicable +for UDP sockets, see +.BR socket (7). +.TP +.BR UDP_CORK " (since Linux 2.5.44)" +If this option is enabled, then all data output on this socket +is accumulated into a single datagram that is transmitted when +the option is disabled. +This option should not be used in code intended to be +portable. +.\" FIXME document UDP_ENCAP (new in Linux 2.5.67) +.\" From include/linux/udp.h: +.\" UDP_ENCAP_ESPINUDP_NON_IKE draft-ietf-ipsec-nat-t-ike-00/01 +.\" UDP_ENCAP_ESPINUDP draft-ietf-ipsec-udp-encaps-06 +.\" UDP_ENCAP_L2TPINUDP rfc2661 +.\" FIXME Document UDP_NO_CHECK6_TX and UDP_NO_CHECK6_RX, added in Linux 3.16 +.TP +.BR UDP_SEGMENT " (since Linux 4.18)" +Enables UDP segmentation offload. +Segmentation offload reduces +.BR send (2) +cost by transferring multiple datagrams worth of data +as a single large packet through the kernel transmit path, +even when that exceeds MTU. +As late as possible, +the large packet is split by segment size into a series of datagrams. +This segmentation offload step is deferred to hardware if supported, +else performed in software. +This option takes a value in the range +.RB [ 0 ,\~ USHRT_MAX ] +that sets the segment size: +the size of datagram payload, +excluding the UDP header. +The segment size must be chosen such that +at most 64 datagrams are sent in a single call +and that the datagrams after segmentation meet +the same MTU rules that apply to datagrams sent without this option. +Segmentation offload depends on checksum offload, +as datagram checksums are computed after segmentation. +The option may also be set for individual +.BR sendmsg (2) +calls by passing it as a +.BR cmsg (3). +A value of zero disables the feature. +This option should not be used in code intended to be portable. +.TP +.BR UDP_GRO " (since Linux 5.0)" +Enables UDP receive offload. +If enabled, +the socket may receive multiple datagrams worth of data +as a single large buffer, +together with a +.BR cmsg (3) +that holds the segment size. +This option is the inverse of segmentation offload. +It reduces receive cost by handling multiple datagrams worth of data +as a single large packet in the kernel receive path, +even when that exceeds MTU. +This option should not be used in code intended to be portable. +.SS Ioctls +These ioctls can be accessed using +.BR ioctl (2). +The correct syntax is: +.P +.RS +.nf +.BI int " value"; +.IB error " = ioctl(" udp_socket ", " ioctl_type ", &" value ");" +.fi +.RE +.TP +.BR FIONREAD " (" SIOCINQ ) +Gets a pointer to an integer as argument. +Returns the size of the next pending datagram in the integer in bytes, +or 0 when no datagram is pending. +.B Warning: +Using +.BR FIONREAD , +it is impossible to distinguish the case where no datagram is pending +from the case where the next pending datagram contains zero bytes of data. +It is safer to use +.BR select (2), +.BR poll (2), +or +.BR epoll (7) +to distinguish these cases. +.\" See http://www.securiteam.com/unixfocus/5KP0I15IKO.html +.\" "GNUnet DoS (UDP Socket Unreachable)", 14 May 2006 +.TP +.BR TIOCOUTQ " (" SIOCOUTQ ) +Returns the number of data bytes in the local send queue. +Supported only with Linux 2.4 and above. +.P +In addition, all ioctls documented in +.BR ip (7) +and +.BR socket (7) +are supported. +.SH ERRORS +All errors documented for +.BR socket (7) +or +.BR ip (7) +may be returned by a send or receive on a UDP socket. +.TP +.B ECONNREFUSED +No receiver was associated with the destination address. +This might be caused by a previous packet sent over the socket. +.SH VERSIONS +.B IP_RECVERR +is a new feature in Linux 2.2. +.\" .SH CREDITS +.\" This man page was written by Andi Kleen. +.SH SEE ALSO +.BR ip (7), +.BR raw (7), +.BR socket (7), +.BR udplite (7) +.P +The kernel source file +.IR Documentation/networking/ip\-sysctl.txt . +.P +RFC\ 768 for the User Datagram Protocol. +.br +RFC\ 1122 for the host requirements. +.br +RFC\ 1191 for a description of path MTU discovery. diff --git a/man/man7/udplite.7 b/man/man7/udplite.7 new file mode 100644 index 0000000..eae059a --- /dev/null +++ b/man/man7/udplite.7 @@ -0,0 +1,137 @@ +.\" Copyright (c) 2008 by Gerrit Renker +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" $Id: udplite.7,v 1.12 2008/07/23 15:22:22 gerrit Exp gerrit $ +.\" +.TH udplite 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +udplite \- Lightweight User Datagram Protocol +.SH SYNOPSIS +.nf +.B #include +.\" FIXME . see #defines under `BUGS', +.\" when glibc supports this, add +.\" #include +.P +.B sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE); +.fi +.SH DESCRIPTION +This is an implementation of the Lightweight User Datagram Protocol +(UDP-Lite), as described in RFC\ 3828. +.P +UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length +checksums. +This has advantages for some types of multimedia transport that +may be able to make use of slightly damaged datagrams, +rather than having them discarded by lower-layer protocols. +.P +The variable-length checksum coverage is set via a +.BR setsockopt (2) +option. +If this option is not set, the only difference from UDP is +in using a different IP protocol identifier (IANA number 136). +.P +The UDP-Lite implementation is a full extension of +.BR udp (7)\[em]that +is, it shares the same API and API behavior, and in addition +offers two socket options to control the checksum coverage. +.SS Address format +UDP-Litev4 uses the +.I sockaddr_in +address format described in +.BR ip (7). +UDP-Litev6 uses the +.I sockaddr_in6 +address format described in +.BR ipv6 (7). +.SS Socket options +To set or get a UDP-Lite socket option, call +.BR getsockopt (2) +to read or +.BR setsockopt (2) +to write the option with the option level argument set to +.BR IPPROTO_UDPLITE . +In addition, all +.B IPPROTO_UDP +socket options are valid on a UDP-Lite socket. +See +.BR udp (7) +for more information. +.P +The following two options are specific to UDP-Lite. +.TP +.B UDPLITE_SEND_CSCOV +This option sets the sender checksum coverage and takes an +.I int +as argument, with a checksum coverage value in the range 0..2\[ha]16-1. +.IP +A value of 0 means that the entire datagram is always covered. +Values from 1\-7 are illegal (RFC\ 3828, 3.1) and are rounded up to +the minimum coverage of 8. +.IP +With regard to IPv6 jumbograms (RFC\ 2675), the UDP-Litev6 checksum +coverage is limited to the first 2\[ha]16-1 octets, as per RFC\ 3828, 3.5. +Higher values are therefore silently truncated to 2\[ha]16-1. +If in doubt, the current coverage value can always be queried using +.BR getsockopt (2). +.TP +.B UDPLITE_RECV_CSCOV +This is the receiver-side analogue and uses the same argument format +and value range as +.BR UDPLITE_SEND_CSCOV . +This option is not required to enable traffic with partial checksum +coverage. +Its function is that of a traffic filter: when enabled, it +instructs the kernel to drop all packets which have a coverage +.I less +than the specified coverage value. +.IP +When the value of +.B UDPLITE_RECV_CSCOV +exceeds the actual packet coverage, incoming packets are silently dropped, +but may generate a warning message in the system log. +.\" SO_NO_CHECK exists and is supported by UDPv4, but is +.\" commented out in socket(7), hence also commented out here +.\".P +.\"Since UDP-Lite mandates checksums, checksumming can not be disabled +.\"via the +.\".B SO_NO_CHECK +.\"option from +.\".BR socket (7). +.SH ERRORS +All errors documented for +.BR udp (7) +may be returned. +UDP-Lite does not add further errors. +.SH FILES +.TP +.I /proc/net/snmp +Basic UDP-Litev4 statistics counters. +.TP +.I /proc/net/snmp6 +Basic UDP-Litev6 statistics counters. +.SH VERSIONS +UDP-Litev4/v6 first appeared in Linux 2.6.20. +.SH BUGS +.\" FIXME . remove this section once glibc supports UDP-Lite +Where glibc support is missing, the following definitions are needed: +.P +.in +4n +.EX +#define IPPROTO_UDPLITE 136 +.\" The following two are defined in the kernel in linux/net/udplite.h +#define UDPLITE_SEND_CSCOV 10 +#define UDPLITE_RECV_CSCOV 11 +.EE +.in +.SH SEE ALSO +.BR ip (7), +.BR ipv6 (7), +.BR socket (7), +.BR udp (7) +.P +RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite). +.P +.I Documentation/networking/udplite.txt +in the Linux kernel source tree diff --git a/man/man7/unicode.7 b/man/man7/unicode.7 new file mode 100644 index 0000000..c4b952e --- /dev/null +++ b/man/man7/unicode.7 @@ -0,0 +1,246 @@ +.\" Copyright (C) Markus Kuhn, 1995, 2001 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1995-11-26 Markus Kuhn +.\" First version written +.\" 2001-05-11 Markus Kuhn +.\" Update +.\" +.TH unicode 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +unicode \- universal character set +.SH DESCRIPTION +The international standard ISO/IEC 10646 defines the +Universal Character Set (UCS). +UCS contains all characters of all other character set standards. +It also guarantees "round-trip compatibility"; +in other words, +conversion tables can be built such that no information is lost +when a string is converted from any other encoding to UCS and back. +.P +UCS contains the characters required to represent practically all +known languages. +This includes not only the Latin, Greek, Cyrillic, +Hebrew, Arabic, Armenian, and Georgian scripts, but also Chinese, +Japanese and Korean Han ideographs as well as scripts such as +Hiragana, Katakana, Hangul, Devanagari, Bengali, Gurmukhi, Gujarati, +Oriya, Tamil, Telugu, Kannada, Malayalam, Thai, Lao, Khmer, Bopomofo, +Tibetan, Runic, Ethiopic, Canadian Syllabics, Cherokee, Mongolian, +Ogham, Myanmar, Sinhala, Thaana, Yi, and others. +For scripts not yet +covered, research on how to best encode them for computer usage is +still going on and they will be added eventually. +This might +eventually include not only Hieroglyphs and various historic +Indo-European languages, but even some selected artistic scripts such +as Tengwar, Cirth, and Klingon. +UCS also covers a large number of +graphical, typographical, mathematical, and scientific symbols, +including those provided by TeX, Postscript, APL, MS-DOS, MS-Windows, +Macintosh, OCR fonts, as well as many word processing and publishing +systems, and more are being added. +.P +The UCS standard (ISO/IEC 10646) describes a +31-bit character set architecture +consisting of 128 24-bit +.IR groups , +each divided into 256 16-bit +.I planes +made up of 256 8-bit +.I rows +with 256 +.I column +positions, one for each character. +Part 1 of the standard (ISO/IEC 10646-1) +defines the first 65534 code positions (0x0000 to 0xfffd), which form +the +.I Basic Multilingual Plane +(BMP), that is plane 0 in group 0. +Part 2 of the standard (ISO/IEC 10646-2) +adds characters to group 0 outside the BMP in several +.I "supplementary planes" +in the range 0x10000 to 0x10ffff. +There are no plans to add characters +beyond 0x10ffff to the standard, therefore of the entire code space, +only a small fraction of group 0 will ever be actually used in the +foreseeable future. +The BMP contains all characters found in the +commonly used other character sets. +The supplemental planes added by +ISO/IEC 10646-2 cover only more exotic characters for special scientific, +dictionary printing, publishing industry, higher-level protocol and +enthusiast needs. +.P +The representation of each UCS character as a 2-byte word is referred +to as the UCS-2 form (only for BMP characters), +whereas UCS-4 is the representation of each character by a 4-byte word. +In addition, there exist two encoding forms UTF-8 +for backward compatibility with ASCII processing software and UTF-16 +for the backward-compatible handling of non-BMP characters up to +0x10ffff by UCS-2 software. +.P +The UCS characters 0x0000 to 0x007f are identical to those of the +classic US-ASCII +character set and the characters in the range 0x0000 to 0x00ff +are identical to those in +ISO/IEC\~8859-1 (Latin-1). +.SS Combining characters +Some code points in UCS +have been assigned to +.IR "combining characters" . +These are similar to the nonspacing accent keys on a typewriter. +A combining character just adds an accent to the previous character. +The most important accented characters have codes of their own in UCS, +however, the combining character mechanism allows us to add accents +and other diacritical marks to any character. +The combining characters +always follow the character which they modify. +For example, the German +character Umlaut-A ("Latin capital letter A with diaeresis") can +either be represented by the precomposed UCS code 0x00c4, or +alternatively as the combination of a normal "Latin capital letter A" +followed by a "combining diaeresis": 0x0041 0x0308. +.P +Combining characters are essential for instance for encoding the Thai +script or for mathematical typesetting and users of the International +Phonetic Alphabet. +.SS Implementation levels +As not all systems are expected to support advanced mechanisms like +combining characters, ISO/IEC 10646-1 specifies the following three +.I implementation levels +of UCS: +.TP 0.9i +Level 1 +Combining characters and Hangul Jamo +(a variant encoding of the Korean script, where a Hangul syllable +glyph is coded as a triplet or pair of vowel/consonant codes) are not +supported. +.TP +Level 2 +In addition to level 1, combining characters are now allowed for some +languages where they are essential (e.g., Thai, Lao, Hebrew, +Arabic, Devanagari, Malayalam). +.TP +Level 3 +All UCS characters are supported. +.P +The Unicode 3.0 Standard +published by the Unicode Consortium +contains exactly the UCS Basic Multilingual Plane +at implementation level 3, as described in ISO/IEC 10646-1:2000. +Unicode 3.1 added the supplemental planes of ISO/IEC 10646-2. +The Unicode standard and +technical reports published by the Unicode Consortium provide much +additional information on the semantics and recommended usages of +various characters. +They provide guidelines and algorithms for +editing, sorting, comparing, normalizing, converting, and displaying +Unicode strings. +.SS Unicode under Linux +Under GNU/Linux, the C type +.I wchar_t +is a signed 32-bit integer type. +Its values are always interpreted +by the C library as UCS +code values (in all locales), a convention that is signaled by the GNU +C library to applications by defining the constant +.B __STDC_ISO_10646__ +as specified in the ISO C99 standard. +.P +UCS/Unicode can be used just like ASCII in input/output streams, +terminal communication, plaintext files, filenames, and environment +variables in the ASCII compatible UTF-8 multibyte encoding. +To signal the use of UTF-8 as the character +encoding to all applications, a suitable +.I locale +has to be selected via environment variables (e.g., +"LANG=en_GB.UTF-8"). +.P +The +.B nl_langinfo(CODESET) +function returns the name of the selected encoding. +Library functions such as +.BR wctomb (3) +and +.BR mbsrtowcs (3) +can be used to transform the internal +.I wchar_t +characters and strings into the system character encoding and back +and +.BR wcwidth (3) +tells how many positions (0\[en]2) the cursor is advanced by the +output of a character. +.SS Private Use Areas (PUA) +In the Basic Multilingual Plane, +the range 0xe000 to 0xf8ff will never be assigned to any characters by +the standard and is reserved for private usage. +For the Linux +community, this private area has been subdivided further into the +range 0xe000 to 0xefff which can be used individually by any end-user +and the Linux zone in the range 0xf000 to 0xf8ff where extensions are +coordinated among all Linux users. +The registry of the characters +assigned to the Linux zone is maintained by LANANA and the registry +itself is +.I Documentation/admin\-guide/unicode.rst +in the Linux kernel sources +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/unicode.txt +before Linux 4.10). +.P +Two other planes are reserved for private usage, plane 15 +(Supplementary Private Use Area-A, range 0xf0000 to 0xffffd) +and plane 16 (Supplementary Private Use Area-B, range +0x100000 to 0x10fffd). +.SS Literature +.IP \[bu] 3 +Information technology \[em] Universal Multiple-Octet Coded Character +Set (UCS) \[em] Part 1: Architecture and Basic Multilingual Plane. +International Standard ISO/IEC 10646-1, International Organization +for Standardization, Geneva, 2000. +.IP +This is the official specification of UCS. +Available from +.UR http://www.iso.ch/ +.UE . +.IP \[bu] +The Unicode Standard, Version 3.0. +The Unicode Consortium, Addison-Wesley, +Reading, MA, 2000, ISBN 0-201-61633-5. +.IP \[bu] +S.\& Harbison, G.\& Steele. C: A Reference Manual. Fourth edition, +Prentice Hall, Englewood Cliffs, 1995, ISBN 0-13-326224-3. +.IP +A good reference book about the C programming language. +The fourth +edition covers the 1994 Amendment 1 to the ISO C90 standard, which +adds a large number of new C library functions for handling wide and +multibyte character encodings, but it does not yet cover ISO C99, +which improved wide and multibyte character support even further. +.IP \[bu] +Unicode Technical Reports. +.RS +.UR http://www.unicode.org\:/reports/ +.UE +.RE +.IP \[bu] +Markus Kuhn: UTF-8 and Unicode FAQ for UNIX/Linux. +.RS +.UR http://www.cl.cam.ac.uk\:/\[ti]mgk25\:/unicode.html +.UE +.RE +.IP \[bu] +Bruno Haible: Unicode HOWTO. +.RS +.UR http://www.tldp.org\:/HOWTO\:/Unicode\-HOWTO.html +.UE +.RE +.\" .SH AUTHOR +.\" Markus Kuhn +.SH SEE ALSO +.BR locale (1), +.BR setlocale (3), +.BR charsets (7), +.BR utf\-8 (7) diff --git a/man/man7/units.7 b/man/man7/units.7 new file mode 100644 index 0000000..b38ae87 --- /dev/null +++ b/man/man7/units.7 @@ -0,0 +1,108 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH units 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +units \- decimal and binary prefixes +.SH DESCRIPTION +.SS Decimal prefixes +The SI system of units uses prefixes that indicate powers of ten. +A kilometer is 1000 meter, and a megawatt is 1000000 watt. +Below the standard prefixes. +.RS +.TS +l l l. +Prefix Name Value +q quecto 10\[ha]\-30 = 0.000000000000000000000000000001 +r ronto 10\[ha]\-27 = 0.000000000000000000000000001 +y yocto 10\[ha]\-24 = 0.000000000000000000000001 +z zepto 10\[ha]\-21 = 0.000000000000000000001 +a atto 10\[ha]\-18 = 0.000000000000000001 +f femto 10\[ha]\-15 = 0.000000000000001 +p pico 10\[ha]\-12 = 0.000000000001 +n nano 10\[ha]\-9 = 0.000000001 +\[mc] micro 10\[ha]\-6 = 0.000001 +m milli 10\[ha]\-3 = 0.001 +c centi 10\[ha]\-2 = 0.01 +d deci 10\[ha]\-1 = 0.1 +da deka 10\[ha] 1 = 10 +h hecto 10\[ha] 2 = 100 +k kilo 10\[ha] 3 = 1000 +M mega 10\[ha] 6 = 1000000 +G giga 10\[ha] 9 = 1000000000 +T tera 10\[ha]12 = 1000000000000 +P peta 10\[ha]15 = 1000000000000000 +E exa 10\[ha]18 = 1000000000000000000 +Z zetta 10\[ha]21 = 1000000000000000000000 +Y yotta 10\[ha]24 = 1000000000000000000000000 +R ronna 10\[ha]27 = 1000000000000000000000000000 +Q quetta 10\[ha]30 = 1000000000000000000000000000000 +.TE +.RE +.P +The symbol for micro is the Greek letter mu, often written u +in an ASCII context where this Greek letter is not available. +.SS Binary prefixes +The binary prefixes resemble the decimal ones, +but have an additional \[aq]i\[aq] +(and "Ki" starts with a capital \[aq]K\[aq]). +The names are formed by taking the +first syllable of the names of the decimal prefix with roughly the same +size, followed by "bi" for "binary". +.RS +.TS +l l l. +Prefix Name Value +Ki kibi 2\[ha]10 = 1024 +Mi mebi 2\[ha]20 = 1048576 +Gi gibi 2\[ha]30 = 1073741824 +Ti tebi 2\[ha]40 = 1099511627776 +Pi pebi 2\[ha]50 = 1125899906842624 +Ei exbi 2\[ha]60 = 1152921504606846976 +Zi zebi 2\[ha]70 = 1180591620717411303424 +Yi yobi 2\[ha]80 = 1208925819614629174706176 +.TE +.RE +.SS Discussion +Before these binary prefixes were introduced, it was fairly +common to use k=1000 and K=1024, just like b=bit, B=byte. +Unfortunately, the M is capital already, and cannot be +capitalized to indicate binary-ness. +.P +At first that didn't matter too much, since memory modules +and disks came in sizes that were powers of two, so everyone +knew that in such contexts "kilobyte" and "megabyte" meant +1024 and 1048576 bytes, respectively. +What originally was a +sloppy use of the prefixes "kilo" and "mega" started to become +regarded as the "real true meaning" when computers were involved. +But then disk technology changed, and disk sizes became arbitrary numbers. +After a period of uncertainty all disk manufacturers settled on the +standard, namely k=1000, M=1000\ k, G=1000\ M. +.P +The situation was messy: in the 14k4 modems, k=1000; in the 1.44\ MB +.\" also common: 14.4k modem +diskettes, M=1024000; and so on. +In 1998 the IEC approved the standard +that defines the binary prefixes given above, enabling people +to be precise and unambiguous. +.P +Thus, today, MB = 1000000\ B and MiB = 1048576\ B. +.P +In the free software world programs are slowly +being changed to conform. +When the Linux kernel boots and says +.P +.in +4n +.EX +hda: 120064896 sectors (61473 MB) w/2048KiB Cache +.EE +.in +.P +the MB are megabytes and the KiB are kibibytes. +.SH SEE ALSO +.UR https://www.bipm.org/\:documents/\:20126/\:41483022/\:SI\-Brochure\-9.pdf +The International System of Units +.UE . diff --git a/man/man7/unix.7 b/man/man7/unix.7 new file mode 100644 index 0000000..eacc0a3 --- /dev/null +++ b/man/man7/unix.7 @@ -0,0 +1,1229 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1999 Andi Kleen , +.\" Copyright (C) 2008-2014, Michael Kerrisk , +.\" and Copyright (C) 2016, Heinrich Schuchardt +.\" +.\" Modified, 2003-12-02, Michael Kerrisk, +.\" Modified, 2003-09-23, Adam Langley +.\" Modified, 2004-05-27, Michael Kerrisk, +.\" Added SOCK_SEQPACKET +.\" 2008-05-27, mtk, Provide a clear description of the three types of +.\" address that can appear in the sockaddr_un structure: pathname, +.\" unnamed, and abstract. +.\" +.TH UNIX 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +unix \- sockets for local interprocess communication +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.IB unix_socket " = socket(AF_UNIX, type, 0);" +.IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");" +.fi +.SH DESCRIPTION +The +.B AF_UNIX +(also known as +.BR AF_LOCAL ) +socket family is used to communicate between processes on the same machine +efficiently. +Traditionally, UNIX domain sockets can be either unnamed, +or bound to a filesystem pathname (marked as being of type socket). +Linux also supports an abstract namespace which is independent of the +filesystem. +.P +Valid socket types in the UNIX domain are: +.BR SOCK_STREAM , +for a stream-oriented socket; +.BR SOCK_DGRAM , +for a datagram-oriented socket that preserves message boundaries +(as on most UNIX implementations, UNIX domain datagram +sockets are always reliable and don't reorder datagrams); +and (since Linux 2.6.4) +.BR SOCK_SEQPACKET , +for a sequenced-packet socket that is connection-oriented, +preserves message boundaries, +and delivers messages in the order that they were sent. +.P +UNIX domain sockets support passing file descriptors or process credentials +to other processes using ancillary data. +.SS Address format +A UNIX domain socket address is represented in the following structure: +.P +.in +4n +.EX +.\" #define UNIX_PATH_MAX 108 +.\" +struct sockaddr_un { + sa_family_t sun_family; /* AF_UNIX */ + char sun_path[108]; /* Pathname */ +}; +.EE +.in +.P +The +.I sun_family +field always contains +.BR AF_UNIX . +On Linux, +.I sun_path +is 108 bytes in size; see also BUGS, below. +.P +Various system calls (for example, +.BR bind (2), +.BR connect (2), +and +.BR sendto (2)) +take a +.I sockaddr_un +argument as input. +Some other system calls (for example, +.BR getsockname (2), +.BR getpeername (2), +.BR recvfrom (2), +and +.BR accept (2)) +return an argument of this type. +.P +Three types of address are distinguished in the +.I sockaddr_un +structure: +.TP +pathname +a UNIX domain socket can be bound to a null-terminated +filesystem pathname using +.BR bind (2). +When the address of a pathname socket is returned +(by one of the system calls noted above), +its length is +.IP +.in +4n +.EX +offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1 +.EE +.in +.IP +and +.I sun_path +contains the null-terminated pathname. +(On Linux, the above +.BR offsetof () +expression equates to the same value as +.IR sizeof(sa_family_t) , +but some other implementations include other fields before +.IR sun_path , +so the +.BR offsetof () +expression more portably describes the size of the address structure.) +.IP +For further details of pathname sockets, see below. +.TP +unnamed +A stream socket that has not been bound to a pathname using +.BR bind (2) +has no name. +Likewise, the two sockets created by +.BR socketpair (2) +are unnamed. +When the address of an unnamed socket is returned, +its length is +.IR "sizeof(sa_family_t)" , +and +.I sun_path +should not be inspected. +.\" There is quite some variation across implementations: FreeBSD +.\" says the length is 16 bytes, HP-UX 11 says it's zero bytes. +.TP +abstract +an abstract socket address is distinguished (from a pathname socket) +by the fact that +.I sun_path[0] +is a null byte (\[aq]\e0\[aq]). +The socket's address in this namespace is given by the additional +bytes in +.I sun_path +that are covered by the specified length of the address structure. +(Null bytes in the name have no special significance.) +The name has no connection with filesystem pathnames. +When the address of an abstract socket is returned, +the returned +.I addrlen +is greater than +.I sizeof(sa_family_t) +(i.e., greater than 2), and the name of the socket is contained in +the first +.I (addrlen \- sizeof(sa_family_t)) +bytes of +.IR sun_path . +.SS Pathname sockets +When binding a socket to a pathname, a few rules should be observed +for maximum portability and ease of coding: +.IP \[bu] 3 +The pathname in +.I sun_path +should be null-terminated. +.IP \[bu] +The length of the pathname, including the terminating null byte, +should not exceed the size of +.IR sun_path . +.IP \[bu] +The +.I addrlen +argument that describes the enclosing +.I sockaddr_un +structure should have a value of at least: +.IP +.in +4n +.EX +offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1 +.EE +.in +.IP +or, more simply, +.I addrlen +can be specified as +.IR "sizeof(struct sockaddr_un)" . +.P +There is some variation in how implementations handle UNIX domain +socket addresses that do not follow the above rules. +For example, some (but not all) implementations +.\" Linux does this, including for the case where the supplied path +.\" is 108 bytes +append a null terminator if none is present in the supplied +.IR sun_path . +.P +When coding portable applications, +keep in mind that some implementations +.\" HP-UX +have +.I sun_path +as short as 92 bytes. +.\" Modern BSDs generally have 104, Tru64 and AIX have 104, +.\" Solaris and Irix have 108 +.P +Various system calls +.RB ( accept (2), +.BR recvfrom (2), +.BR getsockname (2), +.BR getpeername (2)) +return socket address structures. +When applied to UNIX domain sockets, the value-result +.I addrlen +argument supplied to the call should be initialized as above. +Upon return, the argument is set to indicate the +.I actual +size of the address structure. +The caller should check the value returned in this argument: +if the output value exceeds the input value, +then there is no guarantee that a null terminator is present in +.IR sun_path . +(See BUGS.) +.\" +.SS Pathname socket ownership and permissions +In the Linux implementation, +pathname sockets honor the permissions of the directory they are in. +Creation of a new socket fails if the process does not have write and +search (execute) permission on the directory in which the socket is created. +.P +On Linux, +connecting to a stream socket object requires write permission on that socket; +sending a datagram to a datagram socket likewise +requires write permission on that socket. +POSIX does not make any statement about the effect of the permissions +on a socket file, and on some systems (e.g., older BSDs), +the socket permissions are ignored. +Portable programs should not rely on +this feature for security. +.P +When creating a new socket, the owner and group of the socket file +are set according to the usual rules. +The socket file has all permissions enabled, +other than those that are turned off by the process +.BR umask (2). +.P +The owner, group, and permissions of a pathname socket can be changed (using +.BR chown (2) +and +.BR chmod (2)). +.\" However, fchown() and fchmod() do not seem to have an effect +.\" +.SS Abstract sockets +Socket permissions have no meaning for abstract sockets: +the process +.BR umask (2) +has no effect when binding an abstract socket, +and changing the ownership and permissions of the object (via +.BR fchown (2) +and +.BR fchmod (2)) +has no effect on the accessibility of the socket. +.P +Abstract sockets automatically disappear when all open references +to the socket are closed. +.P +The abstract socket namespace is a nonportable Linux extension. +.\" +.SS Socket options +For historical reasons, these socket options are specified with a +.B SOL_SOCKET +type even though they are +.B AF_UNIX +specific. +They can be set with +.BR setsockopt (2) +and read with +.BR getsockopt (2) +by specifying +.B SOL_SOCKET +as the socket family. +.TP +.B SO_PASSCRED +Enabling this socket option causes receipt of the credentials of +the sending process in an +.B SCM_CREDENTIALS ancillary +message in each subsequently received message. +The returned credentials are those specified by the sender using +.BR SCM_CREDENTIALS , +or a default that includes the sender's PID, real user ID, and real group ID, +if the sender did not specify +.B SCM_CREDENTIALS +ancillary data. +.IP +When this option is set and the socket is not yet connected, +a unique name in the abstract namespace will be generated automatically. +.IP +The value given as an argument to +.BR setsockopt (2) +and returned as the result of +.BR getsockopt (2) +is an integer boolean flag. +.TP +.B SO_PASSSEC +Enables receiving of the SELinux security label of the peer socket +in an ancillary message of type +.B SCM_SECURITY +(see below). +.IP +The value given as an argument to +.BR setsockopt (2) +and returned as the result of +.BR getsockopt (2) +is an integer boolean flag. +.IP +The +.B SO_PASSSEC +option is supported for UNIX domain datagram sockets +.\" commit 877ce7c1b3afd69a9b1caeb1b9964c992641f52a +since Linux 2.6.18; +support for UNIX domain stream sockets was added +.\" commit 37a9a8df8ce9de6ea73349c9ac8bdf6ba4ec4f70 +in Linux 4.2. +.TP +.B SO_PEEK_OFF +See +.BR socket (7). +.TP +.B SO_PEERCRED +This read-only socket option returns the +credentials of the peer process connected to this socket. +The returned credentials are those that were in effect at the time +of the call to +.BR connect (2), +.BR listen (2), +or +.BR socketpair (2). +.IP +The argument to +.BR getsockopt (2) +is a pointer to a +.I ucred +structure; define the +.B _GNU_SOURCE +feature test macro to obtain the definition of that structure from +.IR . +.IP +The use of this option is possible only for connected +.B AF_UNIX +stream sockets and for +.B AF_UNIX +stream and datagram socket pairs created using +.BR socketpair (2). +.TP +.B SO_PEERSEC +This read-only socket option returns the +security context of the peer socket connected to this socket. +By default, this will be the same as the security context of +the process that created the peer socket unless overridden +by the policy or by a process with the required permissions. +.IP +The argument to +.BR getsockopt (2) +is a pointer to a buffer of the specified length in bytes +into which the security context string will be copied. +If the buffer length is less than the length of the security +context string, then +.BR getsockopt (2) +returns \-1, sets +.I errno +to +.BR ERANGE , +and returns the required length via +.IR optlen . +The caller should allocate at least +.B NAME_MAX +bytes for the buffer initially, although this is not guaranteed +to be sufficient. +Resizing the buffer to the returned length +and retrying may be necessary. +.IP +The security context string may include a terminating null character +in the returned length, but is not guaranteed to do so: a security +context "foo" might be represented as either {'f','o','o'} of length 3 +or {'f','o','o','\\0'} of length 4, which are considered to be +interchangeable. +The string is printable, does not contain non-terminating null characters, +and is in an unspecified encoding (in particular, it +is not guaranteed to be ASCII or UTF-8). +.IP +The use of this option for sockets in the +.B AF_UNIX +address family is supported since Linux 2.6.2 for connected stream sockets, +and since Linux 4.18 +.\" commit 0b811db2cb2aabc910e53d34ebb95a15997c33e7 +also for stream and datagram socket pairs created using +.BR socketpair (2). +.\" +.SS Autobind feature +If a +.BR bind (2) +call specifies +.I addrlen +as +.IR sizeof(sa_family_t) , +.\" i.e., sizeof(short) +or the +.B SO_PASSCRED +socket option was specified for a socket that was +not explicitly bound to an address, +then the socket is autobound to an abstract address. +The address consists of a null byte +followed by 5 bytes in the character set +.IR [0\-9a\-f] . +Thus, there is a limit of 2\[ha]20 autobind addresses. +(From Linux 2.1.15, when the autobind feature was added, +8 bytes were used, and the limit was thus 2\[ha]32 autobind addresses. +The change to 5 bytes came in Linux 2.3.15.) +.SS Sockets API +The following paragraphs describe domain-specific details and +unsupported features of the sockets API for UNIX domain sockets on Linux. +.P +UNIX domain sockets do not support the transmission of +out-of-band data (the +.B MSG_OOB +flag for +.BR send (2) +and +.BR recv (2)). +.P +The +.BR send (2) +.B MSG_MORE +flag is not supported by UNIX domain sockets. +.P +Before Linux 3.4, +.\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f +the use of +.B MSG_TRUNC +in the +.I flags +argument of +.BR recv (2) +was not supported by UNIX domain sockets. +.P +The +.B SO_SNDBUF +socket option does have an effect for UNIX domain sockets, but the +.B SO_RCVBUF +option does not. +For datagram sockets, the +.B SO_SNDBUF +value imposes an upper limit on the size of outgoing datagrams. +This limit is calculated as the doubled (see +.BR socket (7)) +option value less 32 bytes used for overhead. +.SS Ancillary messages +Ancillary data is sent and received using +.BR sendmsg (2) +and +.BR recvmsg (2). +For historical reasons, the ancillary message types listed below +are specified with a +.B SOL_SOCKET +type even though they are +.B AF_UNIX +specific. +To send them, set the +.I cmsg_level +field of the struct +.I cmsghdr +to +.B SOL_SOCKET +and the +.I cmsg_type +field to the type. +For more information, see +.BR cmsg (3). +.TP +.B SCM_RIGHTS +Send or receive a set of open file descriptors from another process. +The data portion contains an integer array of the file descriptors. +.IP +Commonly, this operation is referred to as "passing a file descriptor" +to another process. +However, more accurately, +what is being passed is a reference to an open file description (see +.BR open (2)), +and in the receiving process it is likely that a different +file descriptor number will be used. +Semantically, this operation is equivalent to duplicating +.RB ( dup (2)) +a file descriptor into the file descriptor table of another process. +.IP +If the buffer used to receive the ancillary data containing +file descriptors is too small (or is absent), +then the ancillary data is truncated (or discarded) +and the excess file descriptors are automatically closed +in the receiving process. +.IP +If the number of file descriptors received in the ancillary data would +cause the process to exceed its +.B RLIMIT_NOFILE +resource limit (see +.BR getrlimit (2)), +the excess file descriptors are automatically closed +in the receiving process. +.IP +The kernel constant +.B SCM_MAX_FD +defines a limit on the number of file descriptors in the array. +Attempting to send an array larger than this limit causes +.BR sendmsg (2) +to fail with the error +.BR EINVAL . +.B SCM_MAX_FD +has the value 253 +.\" commit bba14de98753cb6599a2dae0e520714b2153522d +(or 255 before Linux 2.6.38). +.TP +.B SCM_CREDENTIALS +Send or receive UNIX credentials. +This can be used for authentication. +The credentials are passed as a +.I struct ucred +ancillary message. +This structure is defined in +.I +as follows: +.IP +.in +4n +.EX +struct ucred { + pid_t pid; /* Process ID of the sending process */ + uid_t uid; /* User ID of the sending process */ + gid_t gid; /* Group ID of the sending process */ +}; +.EE +.in +.IP +Since glibc 2.8, the +.B _GNU_SOURCE +feature test macro must be defined (before including +.I any +header files) in order to obtain the definition +of this structure. +.IP +The credentials which the sender specifies are checked by the kernel. +A privileged process is allowed to specify values that do not match its own. +The sender must specify its own process ID (unless it has the capability +.BR CAP_SYS_ADMIN , +in which case the PID of any existing process may be specified), +its real user ID, effective user ID, or saved set-user-ID (unless it has +.BR CAP_SETUID ), +and its real group ID, effective group ID, or saved set-group-ID +(unless it has +.BR CAP_SETGID ). +.IP +To receive a +.I struct ucred +message, the +.B SO_PASSCRED +option must be enabled on the socket. +.TP +.B SCM_SECURITY +Receive the SELinux security context (the security label) +of the peer socket. +The received ancillary data is a null-terminated string containing +the security context. +The receiver should allocate at least +.B NAME_MAX +bytes in the data portion of the ancillary message for this data. +.IP +To receive the security context, the +.B SO_PASSSEC +option must be enabled on the socket (see above). +.P +When sending ancillary data with +.BR sendmsg (2), +only one item of each of the above types may be included in the sent message. +.P +At least one byte of real data should be sent when sending ancillary data. +On Linux, this is required to successfully send ancillary data over +a UNIX domain stream socket. +When sending ancillary data over a UNIX domain datagram socket, +it is not necessary on Linux to send any accompanying real data. +However, portable applications should also include at least one byte +of real data when sending ancillary data over a datagram socket. +.P +When receiving from a stream socket, +ancillary data forms a kind of barrier for the received data. +For example, suppose that the sender transmits as follows: +.P +.RS +.PD 0 +.IP (1) 5 +.BR sendmsg (2) +of four bytes, with no ancillary data. +.IP (2) +.BR sendmsg (2) +of one byte, with ancillary data. +.IP (3) +.BR sendmsg (2) +of four bytes, with no ancillary data. +.PD +.RE +.P +Suppose that the receiver now performs +.BR recvmsg (2) +calls each with a buffer size of 20 bytes. +The first call will receive five bytes of data, +along with the ancillary data sent by the second +.BR sendmsg (2) +call. +The next call will receive the remaining four bytes of data. +.P +If the space allocated for receiving incoming ancillary data is too small +then the ancillary data is truncated to the number of headers +that will fit in the supplied buffer (or, in the case of an +.B SCM_RIGHTS +file descriptor list, the list of file descriptors may be truncated). +If no buffer is provided for incoming ancillary data (i.e., the +.I msg_control +field of the +.I msghdr +structure supplied to +.BR recvmsg (2) +is NULL), +then the incoming ancillary data is discarded. +In both of these cases, the +.B MSG_CTRUNC +flag will be set in the +.I msg.msg_flags +value returned by +.BR recvmsg (2). +.\" +.SS Ioctls +The following +.BR ioctl (2) +calls return information in +.IR value . +The correct syntax is: +.P +.RS +.nf +.BI int " value"; +.IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");" +.fi +.RE +.P +.I ioctl_type +can be: +.TP +.B SIOCINQ +For +.B SOCK_STREAM +sockets, this call returns the number of unread bytes in the receive buffer. +The socket must not be in LISTEN state, otherwise an error +.RB ( EINVAL ) +is returned. +.B SIOCINQ +is defined in +.IR . +.\" FIXME . https://www.sourceware.org/bugzilla/show_bug.cgi?id=12002, +.\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers +Alternatively, +you can use the synonymous +.BR FIONREAD , +defined in +.IR . +.\" SIOCOUTQ also has an effect for UNIX domain sockets, but not +.\" quite what userland might expect. It seems to return the number +.\" of bytes allocated for buffers containing pending output. +.\" That number is normally larger than the number of bytes of pending +.\" output. Since this info is, from userland's point of view, imprecise, +.\" and it may well change, probably best not to document this now. +For +.B SOCK_DGRAM +sockets, +the returned value is the same as +for Internet domain datagram sockets; +see +.BR udp (7). +.SH ERRORS +.TP +.B EADDRINUSE +The specified local address is already in use or the filesystem socket +object already exists. +.TP +.B EBADF +This error can occur for +.BR sendmsg (2) +when sending a file descriptor as ancillary data over +a UNIX domain socket (see the description of +.BR SCM_RIGHTS , +above), and indicates that the file descriptor number that +is being sent is not valid (e.g., it is not an open file descriptor). +.TP +.B ECONNREFUSED +The remote address specified by +.BR connect (2) +was not a listening socket. +This error can also occur if the target pathname is not a socket. +.TP +.B ECONNRESET +Remote socket was unexpectedly closed. +.TP +.B EFAULT +User memory address was not valid. +.TP +.B EINVAL +Invalid argument passed. +A common cause is that the value +.B AF_UNIX +was not specified in the +.I sun_type +field of passed addresses, or the socket was in an +invalid state for the applied operation. +.TP +.B EISCONN +.BR connect (2) +called on an already connected socket or a target address was +specified on a connected socket. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +The pathname in the remote address specified to +.BR connect (2) +did not exist. +.TP +.B ENOMEM +Out of memory. +.TP +.B ENOTCONN +Socket operation needs a target address, but the socket is not connected. +.TP +.B EOPNOTSUPP +Stream operation called on non-stream oriented socket or tried to +use the out-of-band data option. +.TP +.B EPERM +The sender passed invalid credentials in the +.IR "struct ucred" . +.TP +.B EPIPE +Remote socket was closed on a stream socket. +If enabled, a +.B SIGPIPE +is sent as well. +This can be avoided by passing the +.B MSG_NOSIGNAL +flag to +.BR send (2) +or +.BR sendmsg (2). +.TP +.B EPROTONOSUPPORT +Passed protocol is not +.BR AF_UNIX . +.TP +.B EPROTOTYPE +Remote socket does not match the local socket type +.RB ( SOCK_DGRAM +versus +.BR SOCK_STREAM ). +.TP +.B ESOCKTNOSUPPORT +Unknown socket type. +.TP +.B ESRCH +While sending an ancillary message containing credentials +.RB ( SCM_CREDENTIALS ), +the caller specified a PID that does not match any existing process. +.TP +.B ETOOMANYREFS +This error can occur for +.BR sendmsg (2) +when sending a file descriptor as ancillary data over +a UNIX domain socket (see the description of +.BR SCM_RIGHTS , +above). +It occurs if the number of "in-flight" file descriptors exceeds the +.B RLIMIT_NOFILE +resource limit and the caller does not have the +.B CAP_SYS_RESOURCE +capability. +An in-flight file descriptor is one that has been sent using +.BR sendmsg (2) +but has not yet been accepted in the recipient process using +.BR recvmsg (2). +.IP +This error is diagnosed since mainline Linux 4.5 +(and in some earlier kernel versions where the fix has been backported). +.\" commit 712f4aad406bb1ed67f3f98d04c044191f0ff593 +In earlier kernel versions, +it was possible to place an unlimited number of file descriptors in flight, +by sending each file descriptor with +.BR sendmsg (2) +and then closing the file descriptor so that it was not accounted against the +.B RLIMIT_NOFILE +resource limit. +.P +Other errors can be generated by the generic socket layer or +by the filesystem while generating a filesystem socket object. +See the appropriate manual pages for more information. +.SH VERSIONS +.B SCM_CREDENTIALS +and the abstract namespace were introduced with Linux 2.2 and should not +be used in portable programs. +(Some BSD-derived systems also support credential passing, +but the implementation details differ.) +.SH NOTES +Binding to a socket with a filename creates a socket +in the filesystem that must be deleted by the caller when it is no +longer needed (using +.BR unlink (2)). +The usual UNIX close-behind semantics apply; the socket can be unlinked +at any time and will be finally removed from the filesystem when the last +reference to it is closed. +.P +To pass file descriptors or credentials over a +.B SOCK_STREAM +socket, you must +send or receive at least one byte of nonancillary data in the same +.BR sendmsg (2) +or +.BR recvmsg (2) +call. +.P +UNIX domain stream sockets do not support the notion of out-of-band data. +.\" +.SH BUGS +When binding a socket to an address, +Linux is one of the implementations that append a null terminator +if none is supplied in +.IR sun_path . +In most cases this is unproblematic: +when the socket address is retrieved, +it will be one byte longer than that supplied when the socket was bound. +However, there is one case where confusing behavior can result: +if 108 non-null bytes are supplied when a socket is bound, +then the addition of the null terminator takes the length of +the pathname beyond +.IR sizeof(sun_path) . +Consequently, when retrieving the socket address +(for example, via +.BR accept (2)), +.\" The behavior on Solaris is quite similar. +if the input +.I addrlen +argument for the retrieving call is specified as +.IR "sizeof(struct sockaddr_un)" , +then the returned address structure +.I won't +have a null terminator in +.IR sun_path . +.P +In addition, some implementations +.\" i.e., traditional BSD +don't require a null terminator when binding a socket (the +.I addrlen +argument is used to determine the length of +.IR sun_path ) +and when the socket address is retrieved on these implementations, +there is no null terminator in +.IR sun_path . +.P +Applications that retrieve socket addresses can (portably) code +to handle the possibility that there is no null terminator in +.I sun_path +by respecting the fact that the number of valid bytes in the pathname is: +.P +.in +4n +.EX +strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) +.EE +.in +.\" The following patch to amend kernel behavior was rejected: +.\" http://thread.gmane.org/gmane.linux.kernel.api/2437 +.\" Subject: [patch] Fix handling of overlength pathname in AF_UNIX sun_path +.\" 2012-04-17 +.\" And there was a related discussion in the Austin list: +.\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/5735 +.\" Subject: Having a sun_path with no null terminator +.\" 2012-04-18 +.\" +.\" FIXME . Track http://austingroupbugs.net/view.php?id=561 +.P +Alternatively, an application can retrieve +the socket address by allocating a buffer of size +.I "sizeof(struct sockaddr_un)+1" +that is zeroed out before the retrieval. +The retrieving call can specify +.I addrlen +as +.IR "sizeof(struct sockaddr_un)" , +and the extra zero byte ensures that there will be +a null terminator for the string returned in +.IR sun_path : +.P +.in +4n +.EX +void *addrp; +\& +addrlen = sizeof(struct sockaddr_un); +addrp = malloc(addrlen + 1); +if (addrp == NULL) + /* Handle error */ ; +memset(addrp, 0, addrlen + 1); +\& +if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1) + /* handle error */ ; +\& +printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path); +.EE +.in +.P +This sort of messiness can be avoided if it is guaranteed +that the applications that +.I create +pathname sockets follow the rules outlined above under +.IR "Pathname sockets" . +.SH EXAMPLES +The following code demonstrates the use of sequenced-packet +sockets for local interprocess communication. +It consists of two programs. +The server program waits for a connection from the client program. +The client sends each of its command-line arguments in separate messages. +The server treats the incoming messages as integers and adds them up. +The client sends the command string "END". +The server sends back a message containing the sum of the client's integers. +The client prints the sum and exits. +The server waits for the next client to connect. +To stop the server, the client is called with the command-line argument "DOWN". +.P +The following output was recorded while running the server in the background +and repeatedly executing the client. +Execution of the server program ends when it receives the "DOWN" command. +.SS Example output +.in +4n +.EX +$ \fB./server &\fP +[1] 25887 +$ \fB./client 3 4\fP +Result = 7 +$ \fB./client 11 \-5\fP +Result = 6 +$ \fB./client DOWN\fP +Result = 0 +[1]+ Done ./server +$ +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (connection.h) +.EX +/* + * File connection.h + */ +#ifndef CONNECTION_H +#define CONNECTION_H +\& +#define SOCKET_NAME "/tmp/9Lq7BNBnBycd6nxy.socket" +#define BUFFER_SIZE 12 +\& +#endif // include guard +.EE +.\" SRC END +.P +.\" SRC BEGIN (server.c) +.EX +/* + * File server.c + */ +\& +#include +#include +#include +#include +#include +#include +#include +\& +#include "connection.h" +\& +int +main(void) +{ + int down_flag = 0; + int ret; + int connection_socket; + int data_socket; + int result; + ssize_t r, w; + struct sockaddr_un name; + char buffer[BUFFER_SIZE]; +\& + /* Create local socket. */ +\& + connection_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0); + if (connection_socket == \-1) { + perror("socket"); + exit(EXIT_FAILURE); + } +\& + /* + * For portability clear the whole structure, since some + * implementations have additional (nonstandard) fields in + * the structure. + */ +\& + memset(&name, 0, sizeof(name)); +\& + /* Bind socket to socket name. */ +\& + name.sun_family = AF_UNIX; + strncpy(name.sun_path, SOCKET_NAME, sizeof(name.sun_path) \- 1); +\& + ret = bind(connection_socket, (const struct sockaddr *) &name, + sizeof(name)); + if (ret == \-1) { + perror("bind"); + exit(EXIT_FAILURE); + } +\& + /* + * Prepare for accepting connections. The backlog size is set + * to 20. So while one request is being processed other requests + * can be waiting. + */ +\& + ret = listen(connection_socket, 20); + if (ret == \-1) { + perror("listen"); + exit(EXIT_FAILURE); + } +\& + /* This is the main loop for handling connections. */ +\& + for (;;) { +\& + /* Wait for incoming connection. */ +\& + data_socket = accept(connection_socket, NULL, NULL); + if (data_socket == \-1) { + perror("accept"); + exit(EXIT_FAILURE); + } +\& + result = 0; + for (;;) { +\& + /* Wait for next data packet. */ +\& + r = read(data_socket, buffer, sizeof(buffer)); + if (r == \-1) { + perror("read"); + exit(EXIT_FAILURE); + } +\& + /* Ensure buffer is 0\-terminated. */ +\& + buffer[sizeof(buffer) \- 1] = 0; +\& + /* Handle commands. */ +\& + if (!strncmp(buffer, "DOWN", sizeof(buffer))) { + down_flag = 1; + continue; + } +\& + if (!strncmp(buffer, "END", sizeof(buffer))) { + break; + } +\& + if (down_flag) { + continue; + } +\& + /* Add received summand. */ +\& + result += atoi(buffer); + } +\& + /* Send result. */ +\& + sprintf(buffer, "%d", result); + w = write(data_socket, buffer, sizeof(buffer)); + if (w == \-1) { + perror("write"); + exit(EXIT_FAILURE); + } +\& + /* Close socket. */ +\& + close(data_socket); +\& + /* Quit on DOWN command. */ +\& + if (down_flag) { + break; + } + } +\& + close(connection_socket); +\& + /* Unlink the socket. */ +\& + unlink(SOCKET_NAME); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.P +.\" SRC BEGIN (client.c) +.EX +/* + * File client.c + */ +\& +#include +#include +#include +#include +#include +#include +#include +\& +#include "connection.h" +\& +int +main(int argc, char *argv[]) +{ + int ret; + int data_socket; + ssize_t r, w; + struct sockaddr_un addr; + char buffer[BUFFER_SIZE]; +\& + /* Create local socket. */ +\& + data_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0); + if (data_socket == \-1) { + perror("socket"); + exit(EXIT_FAILURE); + } +\& + /* + * For portability clear the whole structure, since some + * implementations have additional (nonstandard) fields in + * the structure. + */ +\& + memset(&addr, 0, sizeof(addr)); +\& + /* Connect socket to socket address. */ +\& + addr.sun_family = AF_UNIX; + strncpy(addr.sun_path, SOCKET_NAME, sizeof(addr.sun_path) \- 1); +\& + ret = connect(data_socket, (const struct sockaddr *) &addr, + sizeof(addr)); + if (ret == \-1) { + fprintf(stderr, "The server is down.\en"); + exit(EXIT_FAILURE); + } +\& + /* Send arguments. */ +\& + for (int i = 1; i < argc; ++i) { + w = write(data_socket, argv[i], strlen(argv[i]) + 1); + if (w == \-1) { + perror("write"); + break; + } + } +\& + /* Request result. */ +\& + strcpy(buffer, "END"); + w = write(data_socket, buffer, strlen(buffer) + 1); + if (w == \-1) { + perror("write"); + exit(EXIT_FAILURE); + } +\& + /* Receive result. */ +\& + r = read(data_socket, buffer, sizeof(buffer)); + if (r == \-1) { + perror("read"); + exit(EXIT_FAILURE); + } +\& + /* Ensure buffer is 0\-terminated. */ +\& + buffer[sizeof(buffer) \- 1] = 0; +\& + printf("Result = %s\en", buffer); +\& + /* Close socket. */ +\& + close(data_socket); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.P +For examples of the use of +.BR SCM_RIGHTS , +see +.BR cmsg (3) +and +.BR seccomp_unotify (2). +.SH SEE ALSO +.BR recvmsg (2), +.BR sendmsg (2), +.BR socket (2), +.BR socketpair (2), +.BR cmsg (3), +.BR capabilities (7), +.BR credentials (7), +.BR socket (7), +.BR udp (7) diff --git a/man/man7/uri.7 b/man/man7/uri.7 new file mode 100644 index 0000000..eaed85e --- /dev/null +++ b/man/man7/uri.7 @@ -0,0 +1,761 @@ +.\" (C) Copyright 1999-2000 David A. Wheeler (dwheeler@dwheeler.com) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Fragments of this document are directly derived from IETF standards. +.\" For those fragments which are directly derived from such standards, +.\" the following notice applies, which is the standard copyright and +.\" rights announcement of The Internet Society: +.\" +.\" Copyright (C) The Internet Society (1998). All Rights Reserved. +.\" This document and translations of it may be copied and furnished to +.\" others, and derivative works that comment on or otherwise explain it +.\" or assist in its implementation may be prepared, copied, published +.\" and distributed, in whole or in part, without restriction of any +.\" kind, provided that the above copyright notice and this paragraph are +.\" included on all such copies and derivative works. However, this +.\" document itself may not be modified in any way, such as by removing +.\" the copyright notice or references to the Internet Society or other +.\" Internet organizations, except as needed for the purpose of +.\" developing Internet standards in which case the procedures for +.\" copyrights defined in the Internet Standards process must be +.\" followed, or as required to translate it into languages other than English. +.\" +.\" Modified Fri Jul 25 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) +.\" Modified Fri Aug 21 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) +.\" Modified Tue Mar 14 2000 by David A. Wheeler (dwheeler@dwheeler.com) +.\" +.TH uri 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +uri, url, urn \- uniform resource identifier (URI), including a URL or URN +.SH SYNOPSIS +.SY "\fIURI\fP \fR=\fP" +.RI [\~ absoluteURI +| +.IR relativeURI \~] +.RB [\~\[dq] # \[dq]\~\c +.IR fragment \~] +.YS +.P +.SY "\fIabsoluteURI\fP \fR=\fP" +.I scheme\~\c +.RB \[dq] : \[dq] +.RI (\~ hierarchical_part +| +.IR opaque_part \~) +.YS +.P +.SY "\fIrelativeURI\fP \fR=\fP" +.RI (\~ net_path +| +.I absolute_path +| +.IR relative_path \~) +.RB [\~\[dq] ? \[dq]\~\c +.IR query \~] +.YS +.P +.SY "\fIscheme\fP \fR=\fP" +.RB \[dq] http \[dq] +| +.RB \[dq] ftp \[dq] +| +.RB \[dq] gopher \[dq] +| +.RB \[dq] mailto \[dq] +| +.RB \[dq] news \[dq] +| +.RB \[dq] telnet \[dq] +| +.RB \[dq] file \[dq] +| +.RB \[dq] ftp \[dq] +| +.RB \[dq] man \[dq] +| +.RB \[dq] info \[dq] +| +.RB \[dq] whatis \[dq] +| +.RB \[dq] ldap \[dq] +| +.RB \[dq] wais \[dq] +| \&... +.YS +.P +.SY "\fIhierarchical_part\fP \fR=\fP" +.RI (\~ net_path +| +.IR absolute_path \~) +.RB [\~\[dq] ? \[dq]\~\c +.IR query \~] +.YS +.P +.SY "\fInet_path\fP \fR=\fP" +.RB \[dq] // \[dq]\~\c +.I authority +.RI [\~ absolute_path \~] +.YS +.P +.SY "\fIabsolute_path\fP \fR=\fP" +.RB \[dq] / \[dq]\~\c +.I path_segments +.YS +.P +.SY "\fIrelative_path\fP \fR=\fP" +.I relative_segment +.RI [\~ absolute_path \~] +.YS +.SH DESCRIPTION +A Uniform Resource Identifier (URI) is a short string of characters +identifying an abstract or physical resource (for example, a web page). +A Uniform Resource Locator (URL) is a URI +that identifies a resource through its primary access +mechanism (e.g., its network "location"), rather than +by name or some other attribute of that resource. +A Uniform Resource Name (URN) is a URI +that must remain globally unique and persistent even when +the resource ceases to exist or becomes unavailable. +.P +URIs are the standard way to name hypertext link destinations +for tools such as web browsers. +The string "http://www.kernel.org" is a URL (and thus it +is also a URI). +Many people use the term URL loosely as a synonym for URI +(though technically URLs are a subset of URIs). +.P +URIs can be absolute or relative. +An absolute identifier refers to a resource independent of +context, while a relative +identifier refers to a resource by describing the difference +from the current context. +Within a relative path reference, the complete path segments "." and +".." have special meanings: "the current hierarchy level" and "the +level above this hierarchy level", respectively, just like they do in +UNIX-like systems. +A path segment which contains a colon +character can't be used as the first segment of a relative URI path +(e.g., "this:that"), because it would be mistaken for a scheme name; +precede such segments with ./ (e.g., "./this:that"). +Note that descendants of MS-DOS (e.g., Microsoft Windows) replace +devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|". +.P +A fragment identifier, +if included, +refers to a particular named portion (fragment) of a resource; +text after a \[aq]#\[aq] identifies the fragment. +A URI beginning with \[aq]#\[aq] +refers to that fragment in the current resource. +.SS Usage +There are many different URI schemes, each with specific +additional rules and meanings, but they are intentionally made to be +as similar as possible. +For example, many URL schemes +permit the authority to be the following format, called here an +.I ip_server +(square brackets show what's optional): +.P +.IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ] +.P +This format allows you to optionally insert a username, +a user plus password, and/or a port number. +The +.I host +is the name of the host computer, either its name as determined by DNS +or an IP address (numbers separated by periods). +Thus the URI + +logs into a web server on host example.com +as fred (using fredpassword) using port 8080. +Avoid including a password in a URI if possible because of the many +security risks of having a password written down. +If the URL supplies a username but no password, and the remote +server requests a password, the program interpreting the URL +should request one from the user. +.P +Here are some of the most common schemes in use on UNIX-like systems +that are understood by many tools. +Note that many tools using URIs also have internal schemes or specialized +schemes; see those tools' documentation for information on those schemes. +.P +.B "http \- Web (HTTP) server" +.P +.RI http:// ip_server / path +.br +.RI http:// ip_server / path ? query +.P +This is a URL accessing a web (HTTP) server. +The default port is 80. +If the path refers to a directory, the web server will choose what +to return; usually if there is a file named "index.html" or "index.htm" +its content is returned, otherwise, a list of the files in the current +directory (with appropriate links) is generated and returned. +An example is . +.P +A query can be given in the archaic "isindex" format, consisting of a +word or phrase and not including an equal sign (=). +A query can also be in the longer "GET" format, which has one or more +query entries of the form +.IR key = value +separated by the ampersand character (&). +Note that +.I key +can be repeated more than once, though it's up to the web server +and its application programs to determine if there's any meaning to that. +There is an unfortunate interaction with HTML/XML/SGML and +the GET query format; when such URIs with more than one key +are embedded in SGML/XML documents (including HTML), the ampersand +(&) has to be rewritten as &. +Note that not all queries use this format; larger forms +may be too long to store as a URI, so they use a different +interaction mechanism (called POST) which does +not include the data in the URI. +See the Common Gateway Interface specification at +.UR http://www.w3.org\:/CGI +.UE +for more information. +.P +.B "ftp \- File Transfer Protocol (FTP)" +.P +.RI ftp:// ip_server / path +.P +This is a URL accessing a file through the file transfer protocol (FTP). +The default port (for control) is 21. +If no username is included, the username "anonymous" is supplied, and +in that case many clients provide as the password the requestor's +Internet email address. +An example is +. +.P +.B "gopher \- Gopher server" +.P +.RI gopher:// ip_server / "gophertype selector" +.br +.RI gopher:// ip_server / "gophertype selector" %09 search +.br +.RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string +.br +.P +The default gopher port is 70. +.I gophertype +is a single-character field to denote the +Gopher type of the resource to +which the URL refers. +The entire path may also be empty, in +which case the delimiting "/" is also optional and the gophertype +defaults to "1". +.P +.I selector +is the Gopher selector string. +In the Gopher protocol, +Gopher selector strings are a sequence of octets which may contain +any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal +(US-ASCII character LF), and 0D (US-ASCII character CR). +.P +.B "mailto \- Email address" +.P +.RI mailto: email-address +.P +This is an email address, usually of the form +.IR name @ hostname . +See +.BR mailaddr (7) +for more information on the correct format of an email address. +Note that any % character must be rewritten as %25. +An example is . +.P +.B "news \- Newsgroup or News message" +.P +.RI news: newsgroup-name +.br +.RI news: message-id +.P +A +.I newsgroup-name +is a period-delimited hierarchical name, such as +"comp.infosystems.www.misc". +If is "*" (as in ), it is used to refer +to "all available news groups". +An example is . +.P +A +.I message-id +corresponds to the Message-ID of +.UR http://www.ietf.org\:/rfc\:/rfc1036.txt +IETF RFC\ 1036, +.UE +without the enclosing "<" +and ">"; it takes the form +.IR unique @ full_domain_name . +A message identifier may be distinguished from a news group name by the +presence of the "@" character. +.P +.B "telnet \- Telnet login" +.P +.RI telnet:// ip_server / +.P +The Telnet URL scheme is used to designate interactive text services that +may be accessed by the Telnet protocol. +The final "/" character may be omitted. +The default port is 23. +An example is . +.P +.B "file \- Normal file" +.P +.RI file:// ip_server / path_segments +.br +.RI file: path_segments +.P +This represents a file or directory accessible locally. +As a special case, +.I ip_server +can be the string "localhost" or the empty +string; this is interpreted as "the machine from which the URL is +being interpreted". +If the path is to a directory, the viewer should display the +directory's contents with links to each containee; +not all viewers currently do this. +KDE supports generated files through the URL . +If the given file isn't found, browser writers may want to try to expand +the filename via filename globbing +(see +.BR glob (7) +and +.BR glob (3)). +.P +The second format (e.g., ) +is a correct format for referring to +a local file. +However, older standards did not permit this format, +and some programs don't recognize this as a URI. +A more portable syntax is to use an empty string as the server name, +for example, +; this form does the same thing +and is easily recognized by pattern matchers and older programs as a URI. +Note that if you really mean to say "start from the current location", don't +specify the scheme at all; use a relative address like <../test.txt>, +which has the side-effect of being scheme-independent. +An example of this scheme is . +.P +.B "man \- Man page documentation" +.P +.RI man: command-name +.br +.RI man: command-name ( section ) +.P +This refers to local online manual (man) reference pages. +The command name can optionally be followed by a +parenthesis and section number; see +.BR man (7) +for more information on the meaning of the section numbers. +This URI scheme is unique to UNIX-like systems (such as Linux) +and is not currently registered by the IETF. +An example is . +.P +.B "info \- Info page documentation" +.P +.RI info: virtual-filename +.br +.RI info: virtual-filename # nodename +.br +.RI info:( virtual-filename ) +.br +.RI info:( virtual-filename ) nodename +.P +This scheme refers to online info reference pages (generated from +texinfo files), +a documentation format used by programs such as the GNU tools. +This URI scheme is unique to UNIX-like systems (such as Linux) +and is not currently registered by the IETF. +As of this writing, GNOME and KDE differ in their URI syntax +and do not accept the other's syntax. +The first two formats are the GNOME format; in nodenames all spaces +are written as underscores. +The second two formats are the KDE format; +spaces in nodenames must be written as spaces, even though this +is forbidden by the URI standards. +It's hoped that in the future most tools will understand all of these +formats and will always accept underscores for spaces in nodenames. +In both GNOME and KDE, if the form without the nodename is used the +nodename is assumed to be "Top". +Examples of the GNOME format are and . +Examples of the KDE format are and . +.P +.B "whatis \- Documentation search" +.P +.RI whatis: string +.P +This scheme searches the database of short (one-line) descriptions of +commands and returns a list of descriptions containing that string. +Only complete word matches are returned. +See +.BR whatis (1). +This URI scheme is unique to UNIX-like systems (such as Linux) +and is not currently registered by the IETF. +.P +.B "ghelp \- GNOME help documentation" +.P +.RI ghelp: name-of-application +.P +This loads GNOME help for the given application. +Note that not much documentation currently exists in this format. +.P +.B "ldap \- Lightweight Directory Access Protocol" +.P +.RI ldap:// hostport +.br +.RI ldap:// hostport / +.br +.RI ldap:// hostport / dn +.br +.RI ldap:// hostport / dn ? attributes +.br +.RI ldap:// hostport / dn ? attributes ? scope +.br +.RI ldap:// hostport / dn ? attributes ? scope ? filter +.br +.RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions +.P +This scheme supports queries to the +Lightweight Directory Access Protocol (LDAP), a protocol for querying +a set of servers for hierarchically organized information +(such as people and computing resources). +See +.UR http://www.ietf.org\:/rfc\:/rfc2255.txt +RFC\ 2255 +.UE +for more information on the LDAP URL scheme. +The components of this URL are: +.TP +hostport +the LDAP server to query, written as a hostname optionally followed by +a colon and the port number. +The default LDAP port is TCP port 389. +If empty, the client determines which the LDAP server to use. +.TP +dn +the LDAP Distinguished Name, which identifies +the base object of the LDAP search (see +.UR http://www.ietf.org\:/rfc\:/rfc2253.txt +RFC\ 2253 +.UE +section 3). +.TP +attributes +a comma-separated list of attributes to be returned; +see RFC\ 2251 section 4.1.5. +If omitted, all attributes should be returned. +.TP +scope +specifies the scope of the search, which can be one of +"base" (for a base object search), "one" (for a one-level search), +or "sub" (for a subtree search). +If scope is omitted, "base" is assumed. +.TP +filter +specifies the search filter (subset of entries +to return). +If omitted, all entries should be returned. +See +.UR http://www.ietf.org\:/rfc\:/rfc2254.txt +RFC\ 2254 +.UE +section 4. +.TP +extensions +a comma-separated list of type=value +pairs, where the =value portion may be omitted for options not +requiring it. +An extension prefixed with a \[aq]!\[aq] is critical +(must be supported to be valid), otherwise it is noncritical (optional). +.P +LDAP queries are easiest to explain by example. +Here's a query that asks ldap.itd.umich.edu for information about +the University of Michigan in the U.S.: +.P +.nf +ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US +.fi +.P +To just get its postal address attribute, request: +.P +.nf +ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress +.fi +.P +To ask a host.com at port 6666 for information about the person +with common name (cn) "Babs Jensen" at University of Michigan, request: +.P +.nf +ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen) +.fi +.P +.B "wais \- Wide Area Information Servers" +.P +.RI wais:// hostport / database +.br +.RI wais:// hostport / database ? search +.br +.RI wais:// hostport / database / wtype / wpath +.P +This scheme designates a WAIS database, search, or document +(see +.UR http://www.ietf.org\:/rfc\:/rfc1625.txt +IETF RFC\ 1625 +.UE +for more information on WAIS). +Hostport is the hostname, optionally followed by a colon and port number +(the default port number is 210). +.P +The first form designates a WAIS database for searching. +The second form designates a particular search of the WAIS database +.IR database . +The third form designates a particular document within a WAIS +database to be retrieved. +.I wtype +is the WAIS designation of the type of the object and +.I wpath +is the WAIS document-id. +.P +.B "other schemes" +.P +There are many other URI schemes. +Most tools that accept URIs support a set of internal URIs +(e.g., Mozilla has the about: scheme for internal information, +and the GNOME help browser has the toc: scheme for various starting +locations). +There are many schemes that have been defined but are not as widely +used at the current time +(e.g., prospero). +The nntp: scheme is deprecated in favor of the news: scheme. +URNs are to be supported by the urn: scheme, with a hierarchical name space +(e.g., urn:ietf:... would identify IETF documents); at this time +URNs are not widely implemented. +Not all tools support all schemes. +.SS Character encoding +URIs use a limited number of characters so that they can be +typed in and used in a variety of situations. +.P +The following characters are reserved, that is, they may appear in a +URI but their use is limited to their reserved purpose +(conflicting data must be escaped before forming the URI): +.IP +.in +4n +.EX +; / ? : @ & = + $ , +.EE +.in +.P +Unreserved characters may be included in a URI. +Unreserved characters +include uppercase and lowercase Latin letters, +decimal digits, and the following +limited set of punctuation marks and symbols: +.IP +.in +4n +.EX +\- _ . ! \[ti] * ' ( ) +.EE +.in +.P +All other characters must be escaped. +An escaped octet is encoded as a character triplet, consisting of the +percent character "%" followed by the two hexadecimal digits +representing the octet code (you can use uppercase or lowercase letters +for the hexadecimal digits). +For example, a blank space must be escaped +as "%20", a tab character as "%09", and the "&" as "%26". +Because the percent "%" character always has the reserved purpose of +being the escape indicator, it must be escaped as "%25". +It is common practice to escape space characters as the plus symbol (+) +in query text; this practice isn't uniformly defined +in the relevant RFCs (which recommend %20 instead) but any tool accepting +URIs with query text should be prepared for them. +A URI is always shown in its "escaped" form. +.P +Unreserved characters can be escaped without changing the semantics +of the URI, but this should not be done unless the URI is being used +in a context that does not allow the unescaped character to appear. +For example, "%7e" is sometimes used instead of "\[ti]" in an HTTP URL +path, but the two are equivalent for an HTTP URL. +.P +For URIs which must handle characters outside the US ASCII character set, +the HTML 4.01 specification (section B.2) and +IETF RFC\~3986 (last paragraph of section 2.5) +recommend the following approach: +.IP (1) 5 +translate the character sequences into UTF-8 (IETF RFC\~3629)\[em]see +.BR utf\-8 (7)\[em]and +then +.IP (2) +use the URI escaping mechanism, that is, +use the %HH encoding for unsafe octets. +.SS Writing a URI +When written, URIs should be placed inside double quotes +(e.g., "http://www.kernel.org"), +enclosed in angle brackets (e.g., ), +or placed on a line by themselves. +A warning for those who use double-quotes: +.B never +move extraneous punctuation (such as the period ending a sentence or the +comma in a list) +inside a URI, since this will change the value of the URI. +Instead, use angle brackets instead, or +switch to a quoting system that never includes extraneous characters +inside quotation marks. +This latter system, called the 'new' or 'logical' quoting system by +"Hart's Rules" and the "Oxford Dictionary for Writers and Editors", +is preferred practice in Great Britain and in various European languages. +Older documents suggested inserting the prefix "URL:" +just before the URI, but this form has never caught on. +.P +The URI syntax was designed to be unambiguous. +However, as URIs have become commonplace, traditional media +(television, radio, newspapers, billboards, etc.) have increasingly +used abbreviated URI references consisting of +only the authority and path portions of the identified resource +(e.g., ). +Such references are primarily +intended for human interpretation rather than machine, with the +assumption that context-based heuristics are sufficient to complete +the URI (e.g., hostnames beginning with "www" are likely to have +a URI prefix of "http://" and hostnames beginning with "ftp" likely +to have a prefix of "ftp://"). +Many client implementations heuristically resolve these references. +Such heuristics may +change over time, particularly when new schemes are introduced. +Since an abbreviated URI has the same syntax as a relative URL path, +abbreviated URI references cannot be used where relative URIs are +permitted, and can be used only when there is no defined base +(such as in dialog boxes). +Don't use abbreviated URIs as hypertext links inside a document; +use the standard format as described here. +.SH STANDARDS +.UR http://www.ietf.org\:/rfc\:/rfc2396.txt +(IETF RFC\ 2396) +.UE , +.UR http://www.w3.org\:/TR\:/REC\-html40 +(HTML 4.0) +.UE . +.SH NOTES +Any tool accepting URIs (e.g., a web browser) on a Linux system should +be able to handle (directly or indirectly) all of the +schemes described here, including the man: and info: schemes. +Handling them by invoking some other program is +fine and in fact encouraged. +.P +Technically the fragment isn't part of the URI. +.P +For information on how to embed URIs (including URLs) in a data format, +see documentation on that format. +HTML uses the format +.I text +. +Texinfo files use the format @uref{\fIuri\fP}. +Man and mdoc have the recently added UR macro, or just include the +URI in the text (viewers should be able to detect :// as part of a URI). +.P +The GNOME and KDE desktop environments currently vary in the URIs +they accept, in particular in their respective help browsers. +To list man pages, GNOME uses while KDE uses , and +to list info pages, GNOME uses while KDE uses +(the author of this man page prefers the KDE approach here, though a more +regular format would be even better). +In general, KDE uses as a prefix to a set of generated +files. +KDE prefers documentation in HTML, accessed via the +. +GNOME prefers the ghelp scheme to store and find documentation. +Neither browser handles file: references to directories at the time +of this writing, making it difficult to refer to an entire directory with +a browsable URI. +As noted above, these environments differ in how they handle the +info: scheme, probably the most important variation. +It is expected that GNOME and KDE +will converge to common URI formats, and a future +version of this man page will describe the converged result. +Efforts to aid this convergence are encouraged. +.SS Security +A URI does not in itself pose a security threat. +There is no general guarantee that a URL, which at one time +located a given resource, will continue to do so. +Nor is there any +guarantee that a URL will not locate a different resource at some +later point in time; such a guarantee can be +obtained only from the person(s) controlling that namespace and the +resource in question. +.P +It is sometimes possible to construct a URL such that an attempt to +perform a seemingly harmless operation, such as the +retrieval of an entity associated with the resource, will in fact +cause a possibly damaging remote operation to occur. +The unsafe URL +is typically constructed by specifying a port number other than that +reserved for the network protocol in question. +The client unwittingly contacts a site that is in fact +running a different protocol. +The content of the URL contains instructions that, when +interpreted according to this other protocol, cause an unexpected +operation. +An example has been the use of a gopher URL to cause an +unintended or impersonating message to be sent via a SMTP server. +.P +Caution should be used when using any URL that specifies a port +number other than the default for the protocol, especially when it is +a number within the reserved space. +.P +Care should be taken when a URI contains escaped delimiters for a +given protocol (for example, CR and LF characters for telnet +protocols) that these are not unescaped before transmission. +This might violate the protocol, but avoids the potential for such +characters to be used to simulate an extra operation or parameter in +that protocol, which might lead to an unexpected and possibly harmful +remote operation to be performed. +.P +It is clearly unwise to use a URI that contains a password which is +intended to be secret. +In particular, the use of a password within +the "userinfo" component of a URI is strongly recommended against except +in those rare cases where the "password" parameter is intended to be public. +.SH BUGS +Documentation may be placed in a variety of locations, so there +currently isn't a good URI scheme for general online documentation +in arbitrary formats. +References of the form + don't work because different distributions and +local installation requirements may place the files in different +directories +(it may be in /usr/doc, or /usr/local/doc, or /usr/share, +or somewhere else). +Also, the directory ZZZ usually changes when a version changes +(though filename globbing could partially overcome this). +Finally, using the file: scheme doesn't easily support people +who dynamically load documentation from the Internet (instead of +loading the files onto a local filesystem). +A future URI scheme may be added (e.g., "userdoc:") to permit +programs to include cross-references to more detailed documentation +without having to know the exact location of that documentation. +Alternatively, a future version of the filesystem specification may +specify file locations sufficiently so that the file: scheme will +be able to locate documentation. +.P +Many programs and file formats don't include a way to incorporate +or implement links using URIs. +.P +Many programs can't handle all of these different URI formats; there +should be a standard mechanism to load an arbitrary URI that automatically +detects the users' environment (e.g., text or graphics, +desktop environment, local user preferences, and currently executing +tools) and invokes the right tool for any URI. +.\" .SH AUTHOR +.\" David A. Wheeler (dwheeler@dwheeler.com) wrote this man page. +.SH SEE ALSO +.BR lynx (1), +.BR man2html (1), +.BR mailaddr (7), +.BR utf\-8 (7) +.P +.UR http://www.ietf.org\:/rfc\:/rfc2255.txt +IETF RFC\ 2255 +.UE diff --git a/man/man7/url.7 b/man/man7/url.7 new file mode 100644 index 0000000..079fb5e --- /dev/null +++ b/man/man7/url.7 @@ -0,0 +1 @@ +.so man7/uri.7 diff --git a/man/man7/urn.7 b/man/man7/urn.7 new file mode 100644 index 0000000..079fb5e --- /dev/null +++ b/man/man7/urn.7 @@ -0,0 +1 @@ +.so man7/uri.7 diff --git a/man/man7/user-keyring.7 b/man/man7/user-keyring.7 new file mode 100644 index 0000000..39c4be3 --- /dev/null +++ b/man/man7/user-keyring.7 @@ -0,0 +1,81 @@ +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH user-keyring 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +user-keyring \- per-user keyring +.SH DESCRIPTION +The user keyring is a keyring used to anchor keys on behalf of a user. +Each UID the kernel deals with has its own user keyring that +is shared by all processes with that UID. +The user keyring has a name (description) of the form +.I _uid. +where +.I +is the user ID of the corresponding user. +.P +The user keyring is associated with the record that the kernel maintains +for the UID. +It comes into existence upon the first attempt to access either the +user keyring, the +.BR user\-session\-keyring (7), +or the +.BR session\-keyring (7). +The keyring remains pinned in existence so long as there are processes +running with that real UID or files opened by those processes remain open. +(The keyring can also be pinned indefinitely by linking it +into another keyring.) +.P +Typically, the user keyring is created by +.BR pam_keyinit (8) +when a user logs in. +.P +The user keyring is not searched by default by +.BR request_key (2). +When +.BR pam_keyinit (8) +creates a session keyring, it adds to it a link to the user +keyring so that the user keyring will be searched when the session keyring is. +.P +A special serial number value, +.BR KEY_SPEC_USER_KEYRING , +is defined that can be used in lieu of the actual serial number of +the calling process's user keyring. +.P +From the +.BR keyctl (1) +utility, '\fB@u\fP' can be used instead of a numeric key ID in +much the same way. +.P +User keyrings are independent of +.BR clone (2), +.BR fork (2), +.BR vfork (2), +.BR execve (2), +and +.BR _exit (2) +excepting that the keyring is destroyed when the UID record is destroyed when +the last process pinning it exits. +.P +If it is necessary for a key associated with a user to exist beyond the UID +record being garbage collected\[em]for example, for use by a +.BR cron (8) +script\[em]then the +.BR persistent\-keyring (7) +should be used instead. +.P +If a user keyring does not exist when it is accessed, it will be created. +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyrings (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-session\-keyring (7), +.BR pam_keyinit (8) diff --git a/man/man7/user-session-keyring.7 b/man/man7/user-session-keyring.7 new file mode 100644 index 0000000..4a2082b --- /dev/null +++ b/man/man7/user-session-keyring.7 @@ -0,0 +1,92 @@ +.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH user-session-keyring 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +user-session-keyring \- per-user default session keyring +.SH DESCRIPTION +The user session keyring is a keyring used to anchor keys on behalf of a user. +Each UID the kernel deals with has its own user session keyring that +is shared by all processes with that UID. +The user session keyring has a name (description) of the form +.I _uid_ses. +where +.I +is the user ID of the corresponding user. +.P +The user session keyring is associated with the record that +the kernel maintains for the UID. +It comes into existence upon the first attempt to access either the +user session keyring, the +.BR user\-keyring (7), +or the +.BR session\-keyring (7). +.\" Davis Howells: the user and user-session keyrings are managed as a pair. +The keyring remains pinned in existence so long as there are processes +running with that real UID or files opened by those processes remain open. +(The keyring can also be pinned indefinitely by linking it +into another keyring.) +.P +The user session keyring is created on demand when a thread requests it +or when a thread asks for its +.BR session\-keyring (7) +and that keyring doesn't exist. +In the latter case, a user session keyring will be created and, +if the session keyring wasn't to be created, +the user session keyring will be set as the process's actual session keyring. +.P +The user session keyring is searched by +.BR request_key (2) +if the actual session keyring does not exist and is ignored otherwise. +.P +A special serial number value, +.BR KEY_SPEC_USER_SESSION_KEYRING , +is defined +that can be used in lieu of the actual serial number of +the calling process's user session keyring. +.P +From the +.BR keyctl (1) +utility, '\fB@us\fP' can be used instead of a numeric key ID in +much the same way. +.P +User session keyrings are independent of +.BR clone (2), +.BR fork (2), +.BR vfork (2), +.BR execve (2), +and +.BR _exit (2) +excepting that the keyring is destroyed when the UID record is destroyed +when the last process pinning it exits. +.P +If a user session keyring does not exist when it is accessed, +it will be created. +.P +Rather than relying on the user session keyring, +it is strongly recommended\[em]especially if the process +is running as root\[em]that a +.BR session\-keyring (7) +be set explicitly, for example by +.BR pam_keyinit (8). +.SH NOTES +The user session keyring was added to support situations where +a process doesn't have a session keyring, +perhaps because it was created via a pathway that didn't involve PAM +(e.g., perhaps it was a daemon started by +.BR inetd (8)). +In such a scenario, the user session keyring acts as a substitute for the +.BR session\-keyring (7). +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR keyctl (3), +.BR keyrings (7), +.BR persistent\-keyring (7), +.BR process\-keyring (7), +.BR session\-keyring (7), +.BR thread\-keyring (7), +.BR user\-keyring (7) diff --git a/man/man7/user_namespaces.7 b/man/man7/user_namespaces.7 new file mode 100644 index 0000000..286972d --- /dev/null +++ b/man/man7/user_namespaces.7 @@ -0,0 +1,1469 @@ +.\" Copyright (c) 2013, 2014 by Michael Kerrisk +.\" and Copyright (c) 2012, 2014 by Eric W. Biederman +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH user_namespaces 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +user_namespaces \- overview of Linux user namespaces +.SH DESCRIPTION +For an overview of namespaces, see +.BR namespaces (7). +.P +User namespaces isolate security-related identifiers and attributes, +in particular, +user IDs and group IDs (see +.BR credentials (7)), +the root directory, +keys (see +.BR keyrings (7)), +.\" FIXME: This page says very little about the interaction +.\" of user namespaces and keys. Add something on this topic. +and capabilities (see +.BR capabilities (7)). +A process's user and group IDs can be different +inside and outside a user namespace. +In particular, +a process can have a normal unprivileged user ID outside a user namespace +while at the same time having a user ID of 0 inside the namespace; +in other words, +the process has full privileges for operations inside the user namespace, +but is unprivileged for operations outside the namespace. +.\" +.\" ============================================================ +.\" +.SS Nested namespaces, namespace membership +User namespaces can be nested; +that is, each user namespace\[em]except the initial ("root") +namespace\[em]has a parent user namespace, +and can have zero or more child user namespaces. +The parent user namespace is the user namespace +of the process that creates the user namespace via a call to +.BR unshare (2) +or +.BR clone (2) +with the +.B CLONE_NEWUSER +flag. +.P +The kernel imposes (since Linux 3.11) a limit of 32 nested levels of +.\" commit 8742f229b635bf1c1c84a3dfe5e47c814c20b5c8 +user namespaces. +.\" FIXME Explain the rationale for this limit. (What is the rationale?) +Calls to +.BR unshare (2) +or +.BR clone (2) +that would cause this limit to be exceeded fail with the error +.BR EUSERS . +.P +Each process is a member of exactly one user namespace. +A process created via +.BR fork (2) +or +.BR clone (2) +without the +.B CLONE_NEWUSER +flag is a member of the same user namespace as its parent. +A single-threaded process can join another user namespace with +.BR setns (2) +if it has the +.B CAP_SYS_ADMIN +in that namespace; +upon doing so, it gains a full set of capabilities in that namespace. +.P +A call to +.BR clone (2) +or +.BR unshare (2) +with the +.B CLONE_NEWUSER +flag makes the new child process (for +.BR clone (2)) +or the caller (for +.BR unshare (2)) +a member of the new user namespace created by the call. +.P +The +.B NS_GET_PARENT +.BR ioctl (2) +operation can be used to discover the parental relationship +between user namespaces; see +.BR ioctl_ns (2). +.P +A task that changes one of its effective IDs +will have its dumpability reset to the value in +.IR /proc/sys/fs/suid_dumpable . +This may affect the ownership of proc files of child processes +and may thus cause the parent to lack the permissions +to write to mapping files of child processes running in a new user namespace. +In such cases making the parent process dumpable, using +.B PR_SET_DUMPABLE +in a call to +.BR prctl (2), +before creating a child process in a new user namespace +may rectify this problem. +See +.BR prctl (2) +and +.BR proc (5) +for details on how ownership is affected. +.\" +.\" ============================================================ +.\" +.SS Capabilities +The child process created by +.BR clone (2) +with the +.B CLONE_NEWUSER +flag starts out with a complete set +of capabilities in the new user namespace. +Likewise, a process that creates a new user namespace using +.BR unshare (2) +or joins an existing user namespace using +.BR setns (2) +gains a full set of capabilities in that namespace. +On the other hand, +that process has no capabilities in the parent (in the case of +.BR clone (2)) +or previous (in the case of +.BR unshare (2) +and +.BR setns (2)) +user namespace, +even if the new namespace is created or joined by the root user +(i.e., a process with user ID 0 in the root namespace). +.P +Note that a call to +.BR execve (2) +will cause a process's capabilities to be recalculated in the usual way (see +.BR capabilities (7)). +Consequently, +unless the process has a user ID of 0 within the namespace, +or the executable file has a nonempty inheritable capabilities mask, +the process will lose all capabilities. +See the discussion of user and group ID mappings, below. +.P +A call to +.BR clone (2) +or +.BR unshare (2) +using the +.B CLONE_NEWUSER +flag +or a call to +.BR setns (2) +that moves the caller into another user namespace +sets the "securebits" flags +(see +.BR capabilities (7)) +to their default values (all flags disabled) in the child (for +.BR clone (2)) +or caller (for +.BR unshare (2) +or +.BR setns (2)). +Note that because the caller no longer has capabilities +in its original user namespace after a call to +.BR setns (2), +it is not possible for a process to reset its "securebits" flags while +retaining its user namespace membership by using a pair of +.BR setns (2) +calls to move to another user namespace and then return to +its original user namespace. +.P +The rules for determining whether or not a process has a capability +in a particular user namespace are as follows: +.IP \[bu] 3 +A process has a capability inside a user namespace +if it is a member of that namespace and +it has the capability in its effective capability set. +A process can gain capabilities in its effective capability +set in various ways. +For example, it may execute a set-user-ID program or an +executable with associated file capabilities. +In addition, +a process may gain capabilities via the effect of +.BR clone (2), +.BR unshare (2), +or +.BR setns (2), +as already described. +.\" In the 3.8 sources, see security/commoncap.c::cap_capable(): +.IP \[bu] +If a process has a capability in a user namespace, +then it has that capability in all child (and further removed descendant) +namespaces as well. +.IP \[bu] +.\" * The owner of the user namespace in the parent of the +.\" * user namespace has all caps. +When a user namespace is created, the kernel records the effective +user ID of the creating process as being the "owner" of the namespace. +.\" (and likewise associates the effective group ID of the creating process +.\" with the namespace). +A process that resides +in the parent of the user namespace +.\" See kernel commit 520d9eabce18edfef76a60b7b839d54facafe1f9 for a fix +.\" on this point +and whose effective user ID matches the owner of the namespace +has all capabilities in the namespace. +.\" This includes the case where the process executes a set-user-ID +.\" program that confers the effective UID of the creator of the namespace. +By virtue of the previous rule, +this means that the process has all capabilities in all +further removed descendant user namespaces as well. +The +.B NS_GET_OWNER_UID +.BR ioctl (2) +operation can be used to discover the user ID of the owner of the namespace; +see +.BR ioctl_ns (2). +.\" +.\" ============================================================ +.\" +.SS Effect of capabilities within a user namespace +Having a capability inside a user namespace +permits a process to perform operations (that require privilege) +only on resources governed by that namespace. +In other words, having a capability in a user namespace permits a process +to perform privileged operations on resources that are governed by (nonuser) +namespaces owned by (associated with) the user namespace +(see the next subsection). +.P +On the other hand, there are many privileged operations that affect +resources that are not associated with any namespace type, +for example, changing the system (i.e., calendar) time (governed by +.BR CAP_SYS_TIME ), +loading a kernel module (governed by +.BR CAP_SYS_MODULE ), +and creating a device (governed by +.BR CAP_MKNOD ). +Only a process with privileges in the +.I initial +user namespace can perform such operations. +.P +Holding +.B CAP_SYS_ADMIN +within the user namespace that owns a process's mount namespace +allows that process to create bind mounts +and mount the following types of filesystems: +.\" fs_flags = FS_USERNS_MOUNT in kernel sources +.P +.RS 4 +.PD 0 +.IP \[bu] 3 +.I /proc +(since Linux 3.8) +.IP \[bu] +.I /sys +(since Linux 3.8) +.IP \[bu] +.I devpts +(since Linux 3.9) +.IP \[bu] +.BR tmpfs (5) +(since Linux 3.9) +.IP \[bu] +.I ramfs +(since Linux 3.9) +.IP \[bu] +.I mqueue +(since Linux 3.9) +.IP \[bu] +.I bpf +.\" commit b2197755b2633e164a439682fb05a9b5ea48f706 +(since Linux 4.4) +.IP \[bu] +.I overlayfs +.\" commit 92dbc9dedccb9759c7f9f2f0ae6242396376988f +.\" commit 4cb2c00c43b3fe88b32f29df4f76da1b92c33224 +(since Linux 5.11) +.PD +.RE +.P +Holding +.B CAP_SYS_ADMIN +within the user namespace that owns a process's cgroup namespace +allows (since Linux 4.6) +that process to the mount the cgroup version 2 filesystem and +cgroup version 1 named hierarchies +(i.e., cgroup filesystems mounted with the +.I \[dq]none,name=\[dq] +option). +.P +Holding +.B CAP_SYS_ADMIN +within the user namespace that owns a process's PID namespace +allows (since Linux 3.8) +that process to mount +.I /proc +filesystems. +.P +Note, however, that mounting block-based filesystems can be done +only by a process that holds +.B CAP_SYS_ADMIN +in the initial user namespace. +.\" +.\" ============================================================ +.\" +.SS Interaction of user namespaces and other types of namespaces +Starting in Linux 3.8, unprivileged processes can create user namespaces, +and the other types of namespaces can be created with just the +.B CAP_SYS_ADMIN +capability in the caller's user namespace. +.P +When a nonuser namespace is created, +it is owned by the user namespace in which the creating process +was a member at the time of the creation of the namespace. +Privileged operations on resources governed by the nonuser namespace +require that the process has the necessary capabilities +in the user namespace that owns the nonuser namespace. +.P +If +.B CLONE_NEWUSER +is specified along with other +.B CLONE_NEW* +flags in a single +.BR clone (2) +or +.BR unshare (2) +call, the user namespace is guaranteed to be created first, +giving the child +.RB ( clone (2)) +or caller +.RB ( unshare (2)) +privileges over the remaining namespaces created by the call. +Thus, it is possible for an unprivileged caller to specify this combination +of flags. +.P +When a new namespace (other than a user namespace) is created via +.BR clone (2) +or +.BR unshare (2), +the kernel records the user namespace of the creating process as the owner of +the new namespace. +(This association can't be changed.) +When a process in the new namespace subsequently performs +privileged operations that operate on global +resources isolated by the namespace, +the permission checks are performed according to the process's capabilities +in the user namespace that the kernel associated with the new namespace. +For example, suppose that a process attempts to change the hostname +.RB ( sethostname (2)), +a resource governed by the UTS namespace. +In this case, +the kernel will determine which user namespace owns +the process's UTS namespace, and check whether the process has the +required capability +.RB ( CAP_SYS_ADMIN ) +in that user namespace. +.P +The +.B NS_GET_USERNS +.BR ioctl (2) +operation can be used to discover the user namespace +that owns a nonuser namespace; see +.BR ioctl_ns (2). +.\" +.\" ============================================================ +.\" +.SS User and group ID mappings: uid_map and gid_map +When a user namespace is created, +it starts out without a mapping of user IDs (group IDs) +to the parent user namespace. +The +.IR /proc/ pid /uid_map +and +.IR /proc/ pid /gid_map +files (available since Linux 3.5) +.\" commit 22d917d80e842829d0ca0a561967d728eb1d6303 +expose the mappings for user and group IDs +inside the user namespace for the process +.IR pid . +These files can be read to view the mappings in a user namespace and +written to (once) to define the mappings. +.P +The description in the following paragraphs explains the details for +.IR uid_map ; +.I gid_map +is exactly the same, +but each instance of "user ID" is replaced by "group ID". +.P +The +.I uid_map +file exposes the mapping of user IDs from the user namespace +of the process +.I pid +to the user namespace of the process that opened +.I uid_map +(but see a qualification to this point below). +In other words, processes that are in different user namespaces +will potentially see different values when reading from a particular +.I uid_map +file, depending on the user ID mappings for the user namespaces +of the reading processes. +.P +Each line in the +.I uid_map +file specifies a 1-to-1 mapping of a range of contiguous +user IDs between two user namespaces. +(When a user namespace is first created, this file is empty.) +The specification in each line takes the form of +three numbers delimited by white space. +The first two numbers specify the starting user ID in +each of the two user namespaces. +The third number specifies the length of the mapped range. +In detail, the fields are interpreted as follows: +.IP (1) 5 +The start of the range of user IDs in +the user namespace of the process +.IR pid . +.IP (2) +The start of the range of user +IDs to which the user IDs specified by field one map. +How field two is interpreted depends on whether the process that opened +.I uid_map +and the process +.I pid +are in the same user namespace, as follows: +.RS +.IP (a) 5 +If the two processes are in different user namespaces: +field two is the start of a range of +user IDs in the user namespace of the process that opened +.IR uid_map . +.IP (b) +If the two processes are in the same user namespace: +field two is the start of the range of +user IDs in the parent user namespace of the process +.IR pid . +This case enables the opener of +.I uid_map +(the common case here is opening +.IR /proc/self/uid_map ) +to see the mapping of user IDs into the user namespace of the process +that created this user namespace. +.RE +.IP (3) +The length of the range of user IDs that is mapped between the two +user namespaces. +.P +System calls that return user IDs (group IDs)\[em]for example, +.BR getuid (2), +.BR getgid (2), +and the credential fields in the structure returned by +.BR stat (2)\[em]return +the user ID (group ID) mapped into the caller's user namespace. +.P +When a process accesses a file, its user and group IDs +are mapped into the initial user namespace for the purpose of permission +checking and assigning IDs when creating a file. +When a process retrieves file user and group IDs via +.BR stat (2), +the IDs are mapped in the opposite direction, +to produce values relative to the process user and group ID mappings. +.P +The initial user namespace has no parent namespace, +but, for consistency, the kernel provides dummy user and group +ID mapping files for this namespace. +Looking at the +.I uid_map +file +.RI ( gid_map +is the same) from a shell in the initial namespace shows: +.P +.in +4n +.EX +$ \fBcat /proc/$$/uid_map\fP + 0 0 4294967295 +.EE +.in +.P +This mapping tells us +that the range starting at user ID 0 in this namespace +maps to a range starting at 0 in the (nonexistent) parent namespace, +and the length of the range is the largest 32-bit unsigned integer. +This leaves 4294967295 (the 32-bit signed \-1 value) unmapped. +This is deliberate: +.I (uid_t)\~\-1 +is used in several interfaces (e.g., +.BR setreuid (2)) +as a way to specify "no user ID". +Leaving +.I (uid_t)\~\-1 +unmapped and unusable guarantees that there will be no +confusion when using these interfaces. +.\" +.\" ============================================================ +.\" +.SS Defining user and group ID mappings: writing to uid_map and gid_map +After the creation of a new user namespace, the +.I uid_map +file of +.I one +of the processes in the namespace may be written to +.I once +to define the mapping of user IDs in the new user namespace. +An attempt to write more than once to a +.I uid_map +file in a user namespace fails with the error +.BR EPERM . +Similar rules apply for +.I gid_map +files. +.P +The lines written to +.I uid_map +.RI ( gid_map ) +must conform to the following validity rules: +.IP \[bu] 3 +The three fields must be valid numbers, +and the last field must be greater than 0. +.IP \[bu] +Lines are terminated by newline characters. +.IP \[bu] +There is a limit on the number of lines in the file. +In Linux 4.14 and earlier, this limit was (arbitrarily) +.\" 5*12-byte records could fit in a 64B cache line +set at 5 lines. +Since Linux 4.15, +.\" commit 6397fac4915ab3002dc15aae751455da1a852f25 +the limit is 340 lines. +In addition, the number of bytes written to +the file must be less than the system page size, +and the write must be performed at the start of the file (i.e., +.BR lseek (2) +and +.BR pwrite (2) +can't be used to write to nonzero offsets in the file). +.IP \[bu] +The range of user IDs (group IDs) +specified in each line cannot overlap with the ranges +in any other lines. +In the initial implementation (Linux 3.8), this requirement was +satisfied by a simplistic implementation that imposed the further +requirement that +the values in both field 1 and field 2 of successive lines must be +in ascending numerical order, +which prevented some otherwise valid maps from being created. +Linux 3.9 and later +.\" commit 0bd14b4fd72afd5df41e9fd59f356740f22fceba +fix this limitation, allowing any valid set of nonoverlapping maps. +.IP \[bu] +At least one line must be written to the file. +.P +Writes that violate the above rules fail with the error +.BR EINVAL . +.P +In order for a process to write to the +.IR /proc/ pid /uid_map +.RI ( /proc/ pid /gid_map ) +file, all of the following permission requirements must be met: +.IP \[bu] 3 +The writing process must have the +.B CAP_SETUID +.RB ( CAP_SETGID ) +capability in the user namespace of the process +.IR pid . +.IP \[bu] +The writing process must either be in the user namespace of the process +.I pid +or be in the parent user namespace of the process +.IR pid . +.IP \[bu] +The mapped user IDs (group IDs) must in turn have a mapping +in the parent user namespace. +.IP \[bu] +If updating +.IR /proc/ pid /uid_map +to create a mapping that maps UID 0 in the parent namespace, +then one of the following must be true: +.RS +.IP (a) 5 +if writing process is in the parent user namespace, +then it must have the +.B CAP_SETFCAP +capability in that user namespace; or +.IP (b) +if the writing process is in the child user namespace, +then the process that created the user namespace must have had the +.B CAP_SETFCAP +capability when the namespace was created. +.RE +.IP +This rule has been in place since +.\" commit db2e718a47984b9d71ed890eb2ea36ecf150de18 +Linux 5.12. +It eliminates an earlier security bug whereby +a UID 0 process that lacks the +.B CAP_SETFCAP +capability, +which is needed to create a binary with namespaced file capabilities +(as described in +.BR capabilities (7)), +could nevertheless create such a binary, +by the following steps: +.RS +.IP (1) 5 +Create a new user namespace with the identity mapping +(i.e., UID 0 in the new user namespace maps to UID 0 in the parent namespace), +so that UID 0 in both namespaces is equivalent to the same root user ID. +.IP (2) +Since the child process has the +.B CAP_SETFCAP +capability, it could create a binary with namespaced file capabilities +that would then be effective in the parent user namespace +(because the root user IDs are the same in the two namespaces). +.RE +.IP \[bu] +One of the following two cases applies: +.RS +.IP (a) 5 +.I Either +the writing process has the +.B CAP_SETUID +.RB ( CAP_SETGID ) +capability in the +.I parent +user namespace. +.RS +.IP \[bu] 3 +No further restrictions apply: +the process can make mappings to arbitrary user IDs (group IDs) +in the parent user namespace. +.RE +.IP (b) +.I Or +otherwise all of the following restrictions apply: +.RS +.IP \[bu] 3 +The data written to +.I uid_map +.RI ( gid_map ) +must consist of a single line that maps +the writing process's effective user ID +(group ID) in the parent user namespace to a user ID (group ID) +in the user namespace. +.IP \[bu] +The writing process must have the same effective user ID as the process +that created the user namespace. +.IP \[bu] +In the case of +.IR gid_map , +use of the +.BR setgroups (2) +system call must first be denied by writing +.RI \[dq] deny \[dq] +to the +.IR /proc/ pid /setgroups +file (see below) before writing to +.IR gid_map . +.RE +.RE +.P +Writes that violate the above rules fail with the error +.BR EPERM . +.\" +.\" ============================================================ +.\" +.SS Project ID mappings: projid_map +Similarly to user and group ID mappings, +it is possible to create project ID mappings for a user namespace. +(Project IDs are used for disk quotas; see +.BR setquota (8) +and +.BR quotactl (2).) +.P +Project ID mappings are defined by writing to the +.IR /proc/ pid /projid_map +file (present since +.\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d +Linux 3.7). +.P +The validity rules for writing to the +.IR /proc/ pid /projid_map +file are as for writing to the +.I uid_map +file; violation of these rules causes +.BR write (2) +to fail with the error +.BR EINVAL . +.P +The permission rules for writing to the +.IR /proc/ pid /projid_map +file are as follows: +.IP \[bu] 3 +The writing process must either be in the user namespace of the process +.I pid +or be in the parent user namespace of the process +.IR pid . +.IP \[bu] +The mapped project IDs must in turn have a mapping +in the parent user namespace. +.P +Violation of these rules causes +.BR write (2) +to fail with the error +.BR EPERM . +.\" +.\" ============================================================ +.\" +.SS Interaction with system calls that change process UIDs or GIDs +In a user namespace where the +.I uid_map +file has not been written, the system calls that change user IDs will fail. +Similarly, if the +.I gid_map +file has not been written, the system calls that change group IDs will fail. +After the +.I uid_map +and +.I gid_map +files have been written, only the mapped values may be used in +system calls that change user and group IDs. +.P +For user IDs, the relevant system calls include +.BR setuid (2), +.BR setfsuid (2), +.BR setreuid (2), +and +.BR setresuid (2). +For group IDs, the relevant system calls include +.BR setgid (2), +.BR setfsgid (2), +.BR setregid (2), +.BR setresgid (2), +and +.BR setgroups (2). +.P +Writing +.RI \[dq] deny \[dq] +to the +.IR /proc/ pid /setgroups +file before writing to +.IR /proc/ pid /gid_map +.\" Things changed in Linux 3.19 +.\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8 +.\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272 +.\" http://lwn.net/Articles/626665/ +will permanently disable +.BR setgroups (2) +in a user namespace and allow writing to +.IR /proc/ pid /gid_map +without having the +.B CAP_SETGID +capability in the parent user namespace. +.\" +.\" ============================================================ +.\" +.SS The \fI/proc/\fPpid\fI/setgroups\fP file +.\" +.\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8 +.\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272 +.\" http://lwn.net/Articles/626665/ +.\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989 +.\" +The +.IR /proc/ pid /setgroups +file displays the string +.RI \[dq] allow \[dq] +if processes in the user namespace that contains the process +.I pid +are permitted to employ the +.BR setgroups (2) +system call; it displays +.RI \[dq] deny \[dq] +if +.BR setgroups (2) +is not permitted in that user namespace. +Note that regardless of the value in the +.IR /proc/ pid /setgroups +file (and regardless of the process's capabilities), calls to +.BR setgroups (2) +are also not permitted if +.IR /proc/ pid /gid_map +has not yet been set. +.P +A privileged process (one with the +.B CAP_SYS_ADMIN +capability in the namespace) may write either of the strings +.RI \[dq] allow \[dq] +or +.RI \[dq] deny \[dq] +to this file +.I before +writing a group ID mapping +for this user namespace to the file +.IR /proc/ pid /gid_map . +Writing the string +.RI \[dq] deny \[dq] +prevents any process in the user namespace from employing +.BR setgroups (2). +.P +The essence of the restrictions described in the preceding +paragraph is that it is permitted to write to +.IR /proc/ pid /setgroups +only so long as calling +.BR setgroups (2) +is disallowed because +.IR /proc/ pid /gid_map +has not been set. +This ensures that a process cannot transition from a state where +.BR setgroups (2) +is allowed to a state where +.BR setgroups (2) +is denied; +a process can transition only from +.BR setgroups (2) +being disallowed to +.BR setgroups (2) +being allowed. +.P +The default value of this file in the initial user namespace is +.RI \[dq] allow \[dq]. +.P +Once +.IR /proc/ pid /gid_map +has been written to +(which has the effect of enabling +.BR setgroups (2) +in the user namespace), +it is no longer possible to disallow +.BR setgroups (2) +by writing +.RI \[dq] deny \[dq] +to +.IR /proc/ pid /setgroups +(the write fails with the error +.BR EPERM ). +.P +A child user namespace inherits the +.IR /proc/ pid /setgroups +setting from its parent. +.P +If the +.I setgroups +file has the value +.RI \[dq] deny \[dq], +then the +.BR setgroups (2) +system call can't subsequently be reenabled (by writing +.RI \[dq] allow \[dq] +to the file) in this user namespace. +(Attempts to do so fail with the error +.BR EPERM .) +This restriction also propagates down to all child user namespaces of +this user namespace. +.P +The +.IR /proc/ pid /setgroups +file was added in Linux 3.19, +but was backported to many earlier stable kernel series, +because it addresses a security issue. +The issue concerned files with permissions such as "rwx\-\-\-rwx". +Such files give fewer permissions to "group" than they do to "other". +This means that dropping groups using +.BR setgroups (2) +might allow a process file access that it did not formerly have. +Before the existence of user namespaces this was not a concern, +since only a privileged process (one with the +.B CAP_SETGID +capability) could call +.BR setgroups (2). +However, with the introduction of user namespaces, +it became possible for an unprivileged process to create +a new namespace in which the user had all privileges. +This then allowed formerly unprivileged +users to drop groups and thus gain file access +that they did not previously have. +The +.IR /proc/ pid /setgroups +file was added to address this security issue, +by denying any pathway for an unprivileged process to drop groups with +.BR setgroups (2). +.\" +.\" /proc/PID/setgroups +.\" [allow == setgroups() is allowed, "deny" == setgroups() is disallowed] +.\" * Can write if have CAP_SYS_ADMIN in NS +.\" * Must write BEFORE writing to /proc/PID/gid_map +.\" +.\" setgroups() +.\" * Must already have written to gid_map +.\" * /proc/PID/setgroups must be "allow" +.\" +.\" /proc/PID/gid_map -- writing +.\" * Must already have written "deny" to /proc/PID/setgroups +.\" +.\" ============================================================ +.\" +.SS Unmapped user and group IDs +There are various places where an unmapped user ID (group ID) +may be exposed to user space. +For example, the first process in a new user namespace may call +.BR getuid (2) +before a user ID mapping has been defined for the namespace. +In most such cases, an unmapped user ID is converted +.\" from_kuid_munged(), from_kgid_munged() +to the overflow user ID (group ID); +the default value for the overflow user ID (group ID) is 65534. +See the descriptions of +.I /proc/sys/kernel/overflowuid +and +.I /proc/sys/kernel/overflowgid +in +.BR proc (5). +.P +The cases where unmapped IDs are mapped in this fashion include +system calls that return user IDs +.RB ( getuid (2), +.BR getgid (2), +and similar), +credentials passed over a UNIX domain socket, +.\" also SO_PEERCRED +credentials returned by +.BR stat (2), +.BR waitid (2), +and the System V IPC "ctl" +.B IPC_STAT +operations, +credentials exposed by +.IR /proc/ pid /status +and the files in +.IR /proc/sysvipc/* , +credentials returned via the +.I si_uid +field in the +.I siginfo_t +received with a signal (see +.BR sigaction (2)), +credentials written to the process accounting file (see +.BR acct (5)), +and credentials returned with POSIX message queue notifications (see +.BR mq_notify (3)). +.P +There is one notable case where unmapped user and group IDs are +.I not +.\" from_kuid(), from_kgid() +.\" Also F_GETOWNER_UIDS is an exception +converted to the corresponding overflow ID value. +When viewing a +.I uid_map +or +.I gid_map +file in which there is no mapping for the second field, +that field is displayed as 4294967295 (\-1 as an unsigned integer). +.\" +.\" ============================================================ +.\" +.SS Accessing files +In order to determine permissions when an unprivileged process accesses a file, +the process credentials (UID, GID) and the file credentials +are in effect mapped back to what they would be in +the initial user namespace and then compared to determine +the permissions that the process has on the file. +The same is also true of other objects that employ the credentials plus +permissions mask accessibility model, such as System V IPC objects. +.\" +.\" ============================================================ +.\" +.SS Operation of file-related capabilities +Certain capabilities allow a process to bypass various +kernel-enforced restrictions when performing operations on +files owned by other users or groups. +These capabilities are: +.BR CAP_CHOWN , +.BR CAP_DAC_OVERRIDE , +.BR CAP_DAC_READ_SEARCH , +.BR CAP_FOWNER , +and +.BR CAP_FSETID . +.P +Within a user namespace, +these capabilities allow a process to bypass the rules +if the process has the relevant capability over the file, +meaning that: +.IP \[bu] 3 +the process has the relevant effective capability in its user namespace; and +.IP \[bu] +the file's user ID and group ID both have valid mappings +in the user namespace. +.P +The +.B CAP_FOWNER +capability is treated somewhat exceptionally: +.\" These are the checks performed by the kernel function +.\" inode_owner_or_capable(). There is one exception to the exception: +.\" overriding the directory sticky permission bit requires that +.\" the file has a valid mapping for both its UID and GID. +it allows a process to bypass the corresponding rules so long as +at least the file's user ID has a mapping in the user namespace +(i.e., the file's group ID does not need to have a valid mapping). +.\" +.\" ============================================================ +.\" +.SS Set-user-ID and set-group-ID programs +When a process inside a user namespace executes +a set-user-ID (set-group-ID) program, +the process's effective user (group) ID inside the namespace is changed +to whatever value is mapped for the user (group) ID of the file. +However, if either the user +.I or +the group ID of the file has no mapping inside the namespace, +the set-user-ID (set-group-ID) bit is silently ignored: +the new program is executed, +but the process's effective user (group) ID is left unchanged. +(This mirrors the semantics of executing a set-user-ID or set-group-ID +program that resides on a filesystem that was mounted with the +.B MS_NOSUID +flag, as described in +.BR mount (2).) +.\" +.\" ============================================================ +.\" +.SS Miscellaneous +When a process's user and group IDs are passed over a UNIX domain socket +to a process in a different user namespace (see the description of +.B SCM_CREDENTIALS +in +.BR unix (7)), +they are translated into the corresponding values as per the +receiving process's user and group ID mappings. +.\" +.SH STANDARDS +Linux. +.\" +.SH NOTES +Over the years, there have been a lot of features that have been added +to the Linux kernel that have been made available only to privileged users +because of their potential to confuse set-user-ID-root applications. +In general, it becomes safe to allow the root user in a user namespace to +use those features because it is impossible, while in a user namespace, +to gain more privilege than the root user of a user namespace has. +.\" +.\" ============================================================ +.\" +.SS Global root +The term "global root" is sometimes used as a shorthand for +user ID 0 in the initial user namespace. +.\" +.\" ============================================================ +.\" +.SS Availability +Use of user namespaces requires a kernel that is configured with the +.B CONFIG_USER_NS +option. +User namespaces require support in a range of subsystems across +the kernel. +When an unsupported subsystem is configured into the kernel, +it is not possible to configure user namespaces support. +.P +As at Linux 3.8, most relevant subsystems supported user namespaces, +but a number of filesystems did not have the infrastructure needed +to map user and group IDs between user namespaces. +Linux 3.9 added the required infrastructure support for many of +the remaining unsupported filesystems +(Plan 9 (9P), Andrew File System (AFS), Ceph, CIFS, CODA, NFS, and OCFS2). +Linux 3.12 added support for the last of the unsupported major filesystems, +.\" commit d6970d4b726cea6d7a9bc4120814f95c09571fc3 +XFS. +.\" +.SH EXAMPLES +The program below is designed to allow experimenting with +user namespaces, as well as other types of namespaces. +It creates namespaces as specified by command-line options and then executes +a command inside those namespaces. +The comments and +.IR usage () +function inside the program provide a full explanation of the program. +The following shell session demonstrates its use. +.P +First, we look at the run-time environment: +.P +.in +4n +.EX +$ \fBuname \-rs\fP # Need Linux 3.8 or later +Linux 3.8.0 +$ \fBid \-u\fP # Running as unprivileged user +1000 +$ \fBid \-g\fP +1000 +.EE +.in +.P +Now start a new shell in new user +.RI ( \-U ), +mount +.RI ( \-m ), +and PID +.RI ( \-p ) +namespaces, with user ID +.RI ( \-M ) +and group ID +.RI ( \-G ) +1000 mapped to 0 inside the user namespace: +.P +.in +4n +.EX +$ \fB./userns_child_exec \-p \-m \-U \-M \[aq]0 1000 1\[aq] \-G \[aq]0 1000 1\[aq] bash\fP +.EE +.in +.P +The shell has PID 1, because it is the first process in the new +PID namespace: +.P +.in +4n +.EX +bash$ \fBecho $$\fP +1 +.EE +.in +.P +Mounting a new +.I /proc +filesystem and listing all of the processes visible +in the new PID namespace shows that the shell can't see +any processes outside the PID namespace: +.P +.in +4n +.EX +bash$ \fBmount \-t proc proc /proc\fP +bash$ \fBps ax\fP + PID TTY STAT TIME COMMAND + 1 pts/3 S 0:00 bash + 22 pts/3 R+ 0:00 ps ax +.EE +.in +.P +Inside the user namespace, the shell has user and group ID 0, +and a full set of permitted and effective capabilities: +.P +.in +4n +.EX +bash$ \fBcat /proc/$$/status | egrep \[aq]\[ha][UG]id\[aq]\fP +Uid: 0 0 0 0 +Gid: 0 0 0 0 +bash$ \fBcat /proc/$$/status | egrep \[aq]\[ha]Cap(Prm|Inh|Eff)\[aq]\fP +CapInh: 0000000000000000 +CapPrm: 0000001fffffffff +CapEff: 0000001fffffffff +.EE +.in +.SS Program source +\& +.EX +/* userns_child_exec.c +\& + Licensed under GNU General Public License v2 or later +\& + Create a child process that executes a shell command in new + namespace(s); allow UID and GID mappings to be specified when + creating a user namespace. +*/ +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +\& +struct child_args { + char **argv; /* Command to be executed by child, with args */ + int pipe_fd[2]; /* Pipe used to synchronize parent and child */ +}; +\& +static int verbose; +\& +static void +usage(char *pname) +{ + fprintf(stderr, "Usage: %s [options] cmd [arg...]\en\en", pname); + fprintf(stderr, "Create a child process that executes a shell " + "command in a new user namespace,\en" + "and possibly also other new namespace(s).\en\en"); + fprintf(stderr, "Options can be:\en\en"); +#define fpe(str) fprintf(stderr, " %s", str); + fpe("\-i New IPC namespace\en"); + fpe("\-m New mount namespace\en"); + fpe("\-n New network namespace\en"); + fpe("\-p New PID namespace\en"); + fpe("\-u New UTS namespace\en"); + fpe("\-U New user namespace\en"); + fpe("\-M uid_map Specify UID map for user namespace\en"); + fpe("\-G gid_map Specify GID map for user namespace\en"); + fpe("\-z Map user\[aq]s UID and GID to 0 in user namespace\en"); + fpe(" (equivalent to: \-M \[aq]0 1\[aq] \-G \[aq]0 1\[aq])\en"); + fpe("\-v Display verbose messages\en"); + fpe("\en"); + fpe("If \-z, \-M, or \-G is specified, \-U is required.\en"); + fpe("It is not permitted to specify both \-z and either \-M or \-G.\en"); + fpe("\en"); + fpe("Map strings for \-M and \-G consist of records of the form:\en"); + fpe("\en"); + fpe(" ID\-inside\-ns ID\-outside\-ns len\en"); + fpe("\en"); + fpe("A map string can contain multiple records, separated" + " by commas;\en"); + fpe("the commas are replaced by newlines before writing" + " to map files.\en"); +\& + exit(EXIT_FAILURE); +} +\& +/* Update the mapping file \[aq]map_file\[aq], with the value provided in + \[aq]mapping\[aq], a string that defines a UID or GID mapping. A UID or + GID mapping consists of one or more newline\-delimited records + of the form: +\& + ID_inside\-ns ID\-outside\-ns length +\& + Requiring the user to supply a string that contains newlines is + of course inconvenient for command\-line use. Thus, we permit the + use of commas to delimit records in this string, and replace them + with newlines before writing the string to the file. */ +\& +static void +update_map(char *mapping, char *map_file) +{ + int fd; + size_t map_len; /* Length of \[aq]mapping\[aq] */ +\& + /* Replace commas in mapping string with newlines. */ +\& + map_len = strlen(mapping); + for (size_t j = 0; j < map_len; j++) + if (mapping[j] == \[aq],\[aq]) + mapping[j] = \[aq]\en\[aq]; +\& + fd = open(map_file, O_RDWR); + if (fd == \-1) { + fprintf(stderr, "ERROR: open %s: %s\en", map_file, + strerror(errno)); + exit(EXIT_FAILURE); + } +\& + if (write(fd, mapping, map_len) != map_len) { + fprintf(stderr, "ERROR: write %s: %s\en", map_file, + strerror(errno)); + exit(EXIT_FAILURE); + } +\& + close(fd); +} +\& +/* Linux 3.19 made a change in the handling of setgroups(2) and + the \[aq]gid_map\[aq] file to address a security issue. The issue + allowed *unprivileged* users to employ user namespaces in + order to drop groups. The upshot of the 3.19 changes is that + in order to update the \[aq]gid_maps\[aq] file, use of the setgroups() + system call in this user namespace must first be disabled by + writing "deny" to one of the /proc/PID/setgroups files for + this namespace. That is the purpose of the following function. */ +\& +static void +proc_setgroups_write(pid_t child_pid, char *str) +{ + char setgroups_path[PATH_MAX]; + int fd; +\& + snprintf(setgroups_path, PATH_MAX, "/proc/%jd/setgroups", + (intmax_t) child_pid); +\& + fd = open(setgroups_path, O_RDWR); + if (fd == \-1) { +\& + /* We may be on a system that doesn\[aq]t support + /proc/PID/setgroups. In that case, the file won\[aq]t exist, + and the system won\[aq]t impose the restrictions that Linux 3.19 + added. That\[aq]s fine: we don\[aq]t need to do anything in order + to permit \[aq]gid_map\[aq] to be updated. +\& + However, if the error from open() was something other than + the ENOENT error that is expected for that case, let the + user know. */ +\& + if (errno != ENOENT) + fprintf(stderr, "ERROR: open %s: %s\en", setgroups_path, + strerror(errno)); + return; + } +\& + if (write(fd, str, strlen(str)) == \-1) + fprintf(stderr, "ERROR: write %s: %s\en", setgroups_path, + strerror(errno)); +\& + close(fd); +} +\& +static int /* Start function for cloned child */ +childFunc(void *arg) +{ + struct child_args *args = arg; + char ch; +\& + /* Wait until the parent has updated the UID and GID mappings. + See the comment in main(). We wait for end of file on a + pipe that will be closed by the parent process once it has + updated the mappings. */ +\& + close(args\->pipe_fd[1]); /* Close our descriptor for the write + end of the pipe so that we see EOF + when parent closes its descriptor. */ + if (read(args\->pipe_fd[0], &ch, 1) != 0) { + fprintf(stderr, + "Failure in child: read from pipe returned != 0\en"); + exit(EXIT_FAILURE); + } +\& + close(args\->pipe_fd[0]); +\& + /* Execute a shell command. */ +\& + printf("About to exec %s\en", args\->argv[0]); + execvp(args\->argv[0], args\->argv); + err(EXIT_FAILURE, "execvp"); +} +\& +#define STACK_SIZE (1024 * 1024) +\& +static char child_stack[STACK_SIZE]; /* Space for child\[aq]s stack */ +\& +int +main(int argc, char *argv[]) +{ + int flags, opt, map_zero; + pid_t child_pid; + struct child_args args; + char *uid_map, *gid_map; + const int MAP_BUF_SIZE = 100; + char map_buf[MAP_BUF_SIZE]; + char map_path[PATH_MAX]; +\& + /* Parse command\-line options. The initial \[aq]+\[aq] character in + the final getopt() argument prevents GNU\-style permutation + of command\-line options. That\[aq]s useful, since sometimes + the \[aq]command\[aq] to be executed by this program itself + has command\-line options. We don\[aq]t want getopt() to treat + those as options to this program. */ +\& + flags = 0; + verbose = 0; + gid_map = NULL; + uid_map = NULL; + map_zero = 0; + while ((opt = getopt(argc, argv, "+imnpuUM:G:zv")) != \-1) { + switch (opt) { + case \[aq]i\[aq]: flags |= CLONE_NEWIPC; break; + case \[aq]m\[aq]: flags |= CLONE_NEWNS; break; + case \[aq]n\[aq]: flags |= CLONE_NEWNET; break; + case \[aq]p\[aq]: flags |= CLONE_NEWPID; break; + case \[aq]u\[aq]: flags |= CLONE_NEWUTS; break; + case \[aq]v\[aq]: verbose = 1; break; + case \[aq]z\[aq]: map_zero = 1; break; + case \[aq]M\[aq]: uid_map = optarg; break; + case \[aq]G\[aq]: gid_map = optarg; break; + case \[aq]U\[aq]: flags |= CLONE_NEWUSER; break; + default: usage(argv[0]); + } + } +\& + /* \-M or \-G without \-U is nonsensical */ +\& + if (((uid_map != NULL || gid_map != NULL || map_zero) && + !(flags & CLONE_NEWUSER)) || + (map_zero && (uid_map != NULL || gid_map != NULL))) + usage(argv[0]); +\& + args.argv = &argv[optind]; +\& + /* We use a pipe to synchronize the parent and child, in order to + ensure that the parent sets the UID and GID maps before the child + calls execve(). This ensures that the child maintains its + capabilities during the execve() in the common case where we + want to map the child\[aq]s effective user ID to 0 in the new user + namespace. Without this synchronization, the child would lose + its capabilities if it performed an execve() with nonzero + user IDs (see the capabilities(7) man page for details of the + transformation of a process\[aq]s capabilities during execve()). */ +\& + if (pipe(args.pipe_fd) == \-1) + err(EXIT_FAILURE, "pipe"); +\& + /* Create the child in new namespace(s). */ +\& + child_pid = clone(childFunc, child_stack + STACK_SIZE, + flags | SIGCHLD, &args); + if (child_pid == \-1) + err(EXIT_FAILURE, "clone"); +\& + /* Parent falls through to here. */ +\& + if (verbose) + printf("%s: PID of child created by clone() is %jd\en", + argv[0], (intmax_t) child_pid); +\& + /* Update the UID and GID maps in the child. */ +\& + if (uid_map != NULL || map_zero) { + snprintf(map_path, PATH_MAX, "/proc/%jd/uid_map", + (intmax_t) child_pid); + if (map_zero) { + snprintf(map_buf, MAP_BUF_SIZE, "0 %jd 1", + (intmax_t) getuid()); + uid_map = map_buf; + } + update_map(uid_map, map_path); + } +\& + if (gid_map != NULL || map_zero) { + proc_setgroups_write(child_pid, "deny"); +\& + snprintf(map_path, PATH_MAX, "/proc/%jd/gid_map", + (intmax_t) child_pid); + if (map_zero) { + snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1", + (intmax_t) getgid()); + gid_map = map_buf; + } + update_map(gid_map, map_path); + } +\& + /* Close the write end of the pipe, to signal to the child that we + have updated the UID and GID maps. */ +\& + close(args.pipe_fd[1]); +\& + if (waitpid(child_pid, NULL, 0) == \-1) /* Wait for child */ + err(EXIT_FAILURE, "waitpid"); +\& + if (verbose) + printf("%s: terminating\en", argv[0]); +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR newgidmap (1), \" From the shadow package +.BR newuidmap (1), \" From the shadow package +.BR clone (2), +.BR ptrace (2), +.BR setns (2), +.BR unshare (2), +.BR proc (5), +.BR subgid (5), \" From the shadow package +.BR subuid (5), \" From the shadow package +.BR capabilities (7), +.BR cgroup_namespaces (7), +.BR credentials (7), +.BR namespaces (7), +.BR pid_namespaces (7) +.P +The kernel source file +.IR Documentation/admin\-guide/namespaces/resource\-control.rst . diff --git a/man/man7/utf-8.7 b/man/man7/utf-8.7 new file mode 100644 index 0000000..9762871 --- /dev/null +++ b/man/man7/utf-8.7 @@ -0,0 +1,205 @@ +.\" Copyright (C) Markus Kuhn, 1996, 2001 +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 1995-11-26 Markus Kuhn +.\" First version written +.\" 2001-05-11 Markus Kuhn +.\" Update +.\" +.TH UTF-8 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +UTF-8 \- an ASCII compatible multibyte Unicode encoding +.SH DESCRIPTION +The Unicode 3.0 character set occupies a 16-bit code space. +The most obvious +Unicode encoding (known as UCS-2) +consists of a sequence of 16-bit words. +Such strings can contain\[em]as part of many 16-bit characters\[em]bytes +such as \[aq]\e0\[aq] or \[aq]/\[aq], which have a +special meaning in filenames and other C library function arguments. +In addition, the majority of UNIX tools expect ASCII files and can't +read 16-bit words as characters without major modifications. +For these reasons, +UCS-2 is not a suitable external encoding of Unicode +in filenames, text files, environment variables, and so on. +The ISO/IEC 10646 Universal Character Set (UCS), +a superset of Unicode, occupies an even larger code +space\[em]31\ bits\[em]and the obvious +UCS-4 encoding for it (a sequence of 32-bit words) has the same problems. +.P +The UTF-8 encoding of Unicode and UCS +does not have these problems and is the common way in which +Unicode is used on UNIX-style operating systems. +.SS Properties +The UTF-8 encoding has the following nice properties: +.IP \[bu] 3 +UCS +characters 0x00000000 to 0x0000007f (the classic US-ASCII +characters) are encoded simply as bytes 0x00 to 0x7f (ASCII +compatibility). +This means that files and strings which contain only +7-bit ASCII characters have the same encoding under both +ASCII +and +UTF-8. +.IP \[bu] +All UCS characters greater than 0x7f are encoded as a multibyte sequence +consisting only of bytes in the range 0x80 to 0xfd, so no ASCII +byte can appear as part of another character and there are no +problems with, for example, \[aq]\e0\[aq] or \[aq]/\[aq]. +.IP \[bu] +The lexicographic sorting order of UCS-4 strings is preserved. +.IP \[bu] +All possible 2\[ha]31 UCS codes can be encoded using UTF-8. +.IP \[bu] +The bytes 0xc0, 0xc1, 0xfe, and 0xff are never used in the UTF-8 encoding. +.IP \[bu] +The first byte of a multibyte sequence which represents a single non-ASCII +UCS character is always in the range 0xc2 to 0xfd and indicates how long +this multibyte sequence is. +All further bytes in a multibyte sequence +are in the range 0x80 to 0xbf. +This allows easy resynchronization and +makes the encoding stateless and robust against missing bytes. +.IP \[bu] +UTF-8 encoded UCS characters may be up to six bytes long, however the +Unicode standard specifies no characters above 0x10ffff, so Unicode characters +can be only up to four bytes long in +UTF-8. +.SS Encoding +The following byte sequences are used to represent a character. +The sequence to be used depends on the UCS code number of the character: +.TP +0x00000000 \- 0x0000007F: +.RI 0 xxxxxxx +.TP +0x00000080 \- 0x000007FF: +.RI 110 xxxxx +.RI 10 xxxxxx +.TP +0x00000800 \- 0x0000FFFF: +.RI 1110 xxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.TP +0x00010000 \- 0x001FFFFF: +.RI 11110 xxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.TP +0x00200000 \- 0x03FFFFFF: +.RI 111110 xx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.TP +0x04000000 \- 0x7FFFFFFF: +.RI 1111110 x +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.RI 10 xxxxxx +.P +The +.I xxx +bit positions are filled with the bits of the character code number in +binary representation, most significant bit first (big-endian). +Only the shortest possible multibyte sequence +which can represent the code number of the character can be used. +.P +The UCS code values 0xd800\[en]0xdfff (UTF-16 surrogates) as well as 0xfffe and +0xffff (UCS noncharacters) should not appear in conforming UTF-8 streams. +According to RFC 3629 no point above U+10FFFF should be used, +which limits characters to four bytes. +.SS Example +The Unicode character 0xa9 = 1010 1001 (the copyright sign) is encoded +in UTF-8 as +.P +.RS +11000010 10101001 = 0xc2 0xa9 +.RE +.P +and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is +encoded as: +.P +.RS +11100010 10001001 10100000 = 0xe2 0x89 0xa0 +.RE +.SS Application notes +Users have to select a UTF-8 locale, for example with +.P +.RS +export LANG=en_GB.UTF-8 +.RE +.P +in order to activate the UTF-8 support in applications. +.P +Application software that has to be aware of the used character +encoding should always set the locale with for example +.P +.RS +setlocale(LC_CTYPE, "") +.RE +.P +and programmers can then test the expression +.P +.RS +strcmp(nl_langinfo(CODESET), "UTF-8") == 0 +.RE +.P +to determine whether a UTF-8 locale has been selected and whether +therefore all plaintext standard input and output, terminal +communication, plaintext file content, filenames, and environment +variables are encoded in UTF-8. +.P +Programmers accustomed to single-byte encodings +such as US-ASCII or ISO/IEC\~8859 +have to be aware that two assumptions made so far are no longer valid +in UTF-8 locales. +Firstly, a single byte does not necessarily correspond any +more to a single character. +Secondly, since modern terminal emulators in UTF-8 +mode also support Chinese, Japanese, and Korean +double-width characters as well as nonspacing combining characters, +outputting a single character does not necessarily advance the cursor +by one position as it did in ASCII. +Library functions such as +.BR mbsrtowcs (3) +and +.BR wcswidth (3) +should be used today to count characters and cursor positions. +.P +The official ESC sequence to switch from an ISO/IEC\~2022 +encoding scheme (as used for instance by VT100 terminals) to +UTF-8 is ESC % G +("\ex1b%G"). +The corresponding return sequence from +UTF-8 to ISO/IEC\~2022 is ESC % @ ("\ex1b%@"). +Other ISO/IEC\~2022 sequences (such as +for switching the G0 and G1 sets) are not applicable in UTF-8 mode. +.SS Security +The Unicode and UCS standards require that producers of UTF-8 +shall use the shortest form possible, for example, producing a two-byte +sequence with first byte 0xc0 is nonconforming. +Unicode 3.1 has added the requirement that conforming programs must not accept +non-shortest forms in their input. +This is for security reasons: if +user input is checked for possible security violations, a program +might check only for the ASCII +version of "/../" or ";" or NUL and overlook that there are many +non-ASCII ways to represent these things in a non-shortest UTF-8 +encoding. +.SS Standards +ISO/IEC 10646-1:2000, Unicode 3.1, RFC\ 3629, Plan 9. +.\" .SH AUTHOR +.\" Markus Kuhn +.SH SEE ALSO +.BR locale (1), +.BR nl_langinfo (3), +.BR setlocale (3), +.BR charsets (7), +.BR unicode (7) diff --git a/man/man7/utf8.7 b/man/man7/utf8.7 new file mode 100644 index 0000000..52a9008 --- /dev/null +++ b/man/man7/utf8.7 @@ -0,0 +1 @@ +.so man7/utf-8.7 diff --git a/man/man7/uts_namespaces.7 b/man/man7/uts_namespaces.7 new file mode 100644 index 0000000..ad509a4 --- /dev/null +++ b/man/man7/uts_namespaces.7 @@ -0,0 +1,46 @@ +.\" Copyright (c) 2019 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH uts_namespaces 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +uts_namespaces \- overview of Linux UTS namespaces +.SH DESCRIPTION +UTS namespaces provide isolation of two system identifiers: +the hostname and the NIS domain name. +These identifiers are set using +.BR sethostname (2) +and +.BR setdomainname (2), +and can be retrieved using +.BR uname (2), +.BR gethostname (2), +and +.BR getdomainname (2). +Changes made to these identifiers are visible to all other +processes in the same UTS namespace, +but are not visible to processes in other UTS namespaces. +.P +When a process creates a new UTS namespace using +.BR clone (2) +or +.BR unshare (2) +with the +.B CLONE_NEWUTS +flag, the hostname and domain name of the new UTS namespace are copied +from the corresponding values in the caller's UTS namespace. +.P +Use of UTS namespaces requires a kernel that is configured with the +.B CONFIG_UTS_NS +option. +.SH SEE ALSO +.BR nsenter (1), +.BR unshare (1), +.BR clone (2), +.BR getdomainname (2), +.BR gethostname (2), +.BR setns (2), +.BR uname (2), +.BR unshare (2), +.BR namespaces (7) diff --git a/man/man7/vdso.7 b/man/man7/vdso.7 new file mode 100644 index 0000000..2a9ae35 --- /dev/null +++ b/man/man7/vdso.7 @@ -0,0 +1,612 @@ +'\" t +.\" Written by Mike Frysinger +.\" +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This page is in the public domain. +.\" %%%LICENSE_END +.\" +.\" Useful background: +.\" http://articles.manugarg.com/systemcallinlinux2_6.html +.\" https://lwn.net/Articles/446528/ +.\" http://www.linuxjournal.com/content/creating-vdso-colonels-other-chicken +.\" http://www.trilithium.com/johan/2005/08/linux-gate/ +.\" +.TH vDSO 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +vdso \- overview of the virtual ELF dynamic shared object +.SH SYNOPSIS +.nf +.B #include +.P +.B void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR); +.fi +.SH DESCRIPTION +The "vDSO" (virtual dynamic shared object) is a small shared library that +the kernel automatically maps into the +address space of all user-space applications. +Applications usually do not need to concern themselves with these details +as the vDSO is most commonly called by the C library. +This way you can code in the normal way using standard functions +and the C library will take care +of using any functionality that is available via the vDSO. +.P +Why does the vDSO exist at all? +There are some system calls the kernel provides that +user-space code ends up using frequently, +to the point that such calls can dominate overall performance. +This is due both to the frequency of the call as well as the +context-switch overhead that results +from exiting user space and entering the kernel. +.P +The rest of this documentation is geared toward the curious and/or +C library writers rather than general developers. +If you're trying to call the vDSO in your own application rather than using +the C library, you're most likely doing it wrong. +.SS Example background +Making system calls can be slow. +In x86 32-bit systems, you can trigger a software interrupt +.RI ( "int $0x80" ) +to tell the kernel you wish to make a system call. +However, this instruction is expensive: it goes through +the full interrupt-handling paths +in the processor's microcode as well as in the kernel. +Newer processors have faster (but backward incompatible) instructions to +initiate system calls. +Rather than require the C library to figure out if this functionality is +available at run time, +the C library can use functions provided by the kernel in +the vDSO. +.P +Note that the terminology can be confusing. +On x86 systems, the vDSO function +used to determine the preferred method of making a system call is +named "__kernel_vsyscall", but on x86-64, +the term "vsyscall" also refers to an obsolete way to ask the kernel +what time it is or what CPU the caller is on. +.P +One frequently used system call is +.BR gettimeofday (2). +This system call is called both directly by user-space applications +as well as indirectly by +the C library. +Think timestamps or timing loops or polling\[em]all of these +frequently need to know what time it is right now. +This information is also not secret\[em]any application in any +privilege mode (root or any unprivileged user) will get the same answer. +Thus the kernel arranges for the information required to answer +this question to be placed in memory the process can access. +Now a call to +.BR gettimeofday (2) +changes from a system call to a normal function +call and a few memory accesses. +.SS Finding the vDSO +The base address of the vDSO (if one exists) is passed by the kernel to +each program in the initial auxiliary vector (see +.BR getauxval (3)), +via the +.B AT_SYSINFO_EHDR +tag. +.P +You must not assume the vDSO is mapped at any particular location in the +user's memory map. +The base address will usually be randomized at run time every time a new +process image is created (at +.BR execve (2) +time). +This is done for security reasons, +to prevent "return-to-libc" attacks. +.P +For some architectures, there is also an +.B AT_SYSINFO +tag. +This is used only for locating the vsyscall entry point and is frequently +omitted or set to 0 (meaning it's not available). +This tag is a throwback to the initial vDSO work (see +.I History +below) and its use should be avoided. +.SS File format +Since the vDSO is a fully formed ELF image, you can do symbol lookups on it. +This allows new symbols to be added with newer kernel releases, +and allows the C library to detect available functionality at +run time when running under different kernel versions. +Oftentimes the C library will do detection with the first call and then +cache the result for subsequent calls. +.P +All symbols are also versioned (using the GNU version format). +This allows the kernel to update the function signature without breaking +backward compatibility. +This means changing the arguments that the function accepts as well as the +return value. +Thus, when looking up a symbol in the vDSO, +you must always include the version +to match the ABI you expect. +.P +Typically the vDSO follows the naming convention of prefixing +all symbols with "__vdso_" or "__kernel_" +so as to distinguish them from other standard symbols. +For example, the "gettimeofday" function is named "__vdso_gettimeofday". +.P +You use the standard C calling conventions when calling +any of these functions. +No need to worry about weird register or stack behavior. +.SH NOTES +.SS Source +When you compile the kernel, +it will automatically compile and link the vDSO code for you. +You will frequently find it under the architecture-specific directory: +.P +.in +4n +.EX +find arch/$ARCH/ \-name \[aq]*vdso*.so*\[aq] \-o \-name \[aq]*gate*.so*\[aq] +.EE +.in +.\" +.SS vDSO names +The name of the vDSO varies across architectures. +It will often show up in things like glibc's +.BR ldd (1) +output. +The exact name should not matter to any code, so do not hardcode it. +.if t \{\ +.ft CW +\} +.TS +l l. +user ABI vDSO name +_ +aarch64 linux\-vdso.so.1 +arm linux\-vdso.so.1 +ia64 linux\-gate.so.1 +mips linux\-vdso.so.1 +ppc/32 linux\-vdso32.so.1 +ppc/64 linux\-vdso64.so.1 +riscv linux\-vdso.so.1 +s390 linux\-vdso32.so.1 +s390x linux\-vdso64.so.1 +sh linux\-gate.so.1 +i386 linux\-gate.so.1 +x86-64 linux\-vdso.so.1 +x86/x32 linux\-vdso.so.1 +.TE +.if t \{\ +.in +.ft P +\} +.SS strace(1), seccomp(2), and the vDSO +When tracing system calls with +.BR strace (1), +symbols (system calls) that are exported by the vDSO will +.I not +appear in the trace output. +Those system calls will likewise not be visible to +.BR seccomp (2) +filters. +.SH ARCHITECTURE-SPECIFIC NOTES +The subsections below provide architecture-specific notes +on the vDSO. +.P +Note that the vDSO that is used is based on the ABI of your user-space code +and not the ABI of the kernel. +Thus, for example, +when you run an i386 32-bit ELF binary, +you'll get the same vDSO regardless of whether you run it under +an i386 32-bit kernel or under an x86-64 64-bit kernel. +Therefore, the name of the user-space ABI should be used to determine +which of the sections below is relevant. +.SS ARM functions +.\" See linux/arch/arm/vdso/vdso.lds.S +.\" Commit: 8512287a8165592466cb9cb347ba94892e9c56a5 +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__vdso_gettimeofday LINUX_2.6 (exported since Linux 4.1) +__vdso_clock_gettime LINUX_2.6 (exported since Linux 4.1) +.TE +.if t \{\ +.in +.ft P +\} +.P +.\" See linux/arch/arm/kernel/entry-armv.S +.\" See linux/Documentation/arm/kernel_user_helpers.rst +Additionally, the ARM port has a code page full of utility functions. +Since it's just a raw page of code, there is no ELF information for doing +symbol lookups or versioning. +It does provide support for different versions though. +.P +For information on this code page, +it's best to refer to the kernel documentation +as it's extremely detailed and covers everything you need to know: +.IR Documentation/arm/kernel_user_helpers.rst . +.SS aarch64 functions +.\" See linux/arch/arm64/kernel/vdso/vdso.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_rt_sigreturn LINUX_2.6.39 +__kernel_gettimeofday LINUX_2.6.39 +__kernel_clock_gettime LINUX_2.6.39 +__kernel_clock_getres LINUX_2.6.39 +.TE +.if t \{\ +.in +.ft P +\} +.SS bfin (Blackfin) functions (port removed in Linux 4.17) +.\" See linux/arch/blackfin/kernel/fixed_code.S +.\" See http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:fixed-code +As this CPU lacks a memory management unit (MMU), +it doesn't set up a vDSO in the normal sense. +Instead, it maps at boot time a few raw functions into +a fixed location in memory. +User-space applications then call directly into that region. +There is no provision for backward compatibility +beyond sniffing raw opcodes, +but as this is an embedded CPU, it can get away with things\[em]some of the +object formats it runs aren't even ELF based (they're bFLT/FLAT). +.P +For information on this code page, +it's best to refer to the public documentation: +.br +http://docs.blackfin.uclinux.org/doku.php?id=linux\-kernel:fixed\-code +.SS mips functions +.\" See linux/arch/mips/vdso/vdso.ld.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_gettimeofday LINUX_2.6 (exported since Linux 4.4) +__kernel_clock_gettime LINUX_2.6 (exported since Linux 4.4) +.TE +.if t \{\ +.in +.ft P +\} +.SS ia64 (Itanium) functions +.\" See linux/arch/ia64/kernel/gate.lds.S +.\" Also linux/arch/ia64/kernel/fsys.S and linux/Documentation/ia64/fsys.rst +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_sigtramp LINUX_2.5 +__kernel_syscall_via_break LINUX_2.5 +__kernel_syscall_via_epc LINUX_2.5 +.TE +.if t \{\ +.in +.ft P +\} +.P +The Itanium port is somewhat tricky. +In addition to the vDSO above, it also has "light-weight system calls" +(also known as "fast syscalls" or "fsys"). +You can invoke these via the +.I __kernel_syscall_via_epc +vDSO helper. +The system calls listed here have the same semantics as if you called them +directly via +.BR syscall (2), +so refer to the relevant +documentation for each. +The table below lists the functions available via this mechanism. +.if t \{\ +.ft CW +\} +.TS +l. +function +_ +clock_gettime +getcpu +getpid +getppid +gettimeofday +set_tid_address +.TE +.if t \{\ +.in +.ft P +\} +.SS parisc (hppa) functions +.\" See linux/arch/parisc/kernel/syscall.S +.\" See linux/Documentation/parisc/registers.rst +The parisc port has a code page with utility functions +called a gateway page. +Rather than use the normal ELF auxiliary vector approach, +it passes the address of +the page to the process via the SR2 register. +The permissions on the page are such that merely executing those addresses +automatically executes with kernel privileges and not in user space. +This is done to match the way HP-UX works. +.P +Since it's just a raw page of code, there is no ELF information for doing +symbol lookups or versioning. +Simply call into the appropriate offset via the branch instruction, +for example: +.P +.in +4n +.EX +ble (%sr2, %r0) +.EE +.in +.if t \{\ +.ft CW +\} +.TS +l l. +offset function +_ +00b0 lws_entry (CAS operations) +00e0 set_thread_pointer (used by glibc) +0100 linux_gateway_entry (syscall) +.TE +.if t \{\ +.in +.ft P +\} +.SS ppc/32 functions +.\" See linux/arch/powerpc/kernel/vdso32/vdso32.lds.S +The table below lists the symbols exported by the vDSO. +The functions marked with a +.I * +are available only when the kernel is +a PowerPC64 (64-bit) kernel. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_clock_getres LINUX_2.6.15 +__kernel_clock_gettime LINUX_2.6.15 +__kernel_clock_gettime64 LINUX_5.11 +__kernel_datapage_offset LINUX_2.6.15 +__kernel_get_syscall_map LINUX_2.6.15 +__kernel_get_tbfreq LINUX_2.6.15 +__kernel_getcpu \fI*\fR LINUX_2.6.15 +__kernel_gettimeofday LINUX_2.6.15 +__kernel_sigtramp_rt32 LINUX_2.6.15 +__kernel_sigtramp32 LINUX_2.6.15 +__kernel_sync_dicache LINUX_2.6.15 +__kernel_sync_dicache_p5 LINUX_2.6.15 +.TE +.if t \{\ +.in +.ft P +\} +.P +Before Linux 5.6, +.\" commit 654abc69ef2e69712e6d4e8a6cb9292b97a4aa39 +the +.B CLOCK_REALTIME_COARSE +and +.B CLOCK_MONOTONIC_COARSE +clocks are +.I not +supported by the +.I __kernel_clock_getres +and +.I __kernel_clock_gettime +interfaces; +the kernel falls back to the real system call. +.SS ppc/64 functions +.\" See linux/arch/powerpc/kernel/vdso64/vdso64.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_clock_getres LINUX_2.6.15 +__kernel_clock_gettime LINUX_2.6.15 +__kernel_datapage_offset LINUX_2.6.15 +__kernel_get_syscall_map LINUX_2.6.15 +__kernel_get_tbfreq LINUX_2.6.15 +__kernel_getcpu LINUX_2.6.15 +__kernel_gettimeofday LINUX_2.6.15 +__kernel_sigtramp_rt64 LINUX_2.6.15 +__kernel_sync_dicache LINUX_2.6.15 +__kernel_sync_dicache_p5 LINUX_2.6.15 +.TE +.if t \{\ +.in +.ft P +\} +.P +Before Linux 4.16, +.\" commit 5c929885f1bb4b77f85b1769c49405a0e0f154a1 +the +.B CLOCK_REALTIME_COARSE +and +.B CLOCK_MONOTONIC_COARSE +clocks are +.I not +supported by the +.I __kernel_clock_getres +and +.I __kernel_clock_gettime +interfaces; +the kernel falls back to the real system call. +.SS riscv functions +.\" See linux/arch/riscv/kernel/vdso/vdso.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__vdso_rt_sigreturn LINUX_4.15 +__vdso_gettimeofday LINUX_4.15 +__vdso_clock_gettime LINUX_4.15 +__vdso_clock_getres LINUX_4.15 +__vdso_getcpu LINUX_4.15 +__vdso_flush_icache LINUX_4.15 +.TE +.if t \{\ +.in +.ft P +\} +.SS s390 functions +.\" See linux/arch/s390/kernel/vdso32/vdso32.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_clock_getres LINUX_2.6.29 +__kernel_clock_gettime LINUX_2.6.29 +__kernel_gettimeofday LINUX_2.6.29 +.TE +.if t \{\ +.in +.ft P +\} +.SS s390x functions +.\" See linux/arch/s390/kernel/vdso64/vdso64.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_clock_getres LINUX_2.6.29 +__kernel_clock_gettime LINUX_2.6.29 +__kernel_gettimeofday LINUX_2.6.29 +.TE +.if t \{\ +.in +.ft P +\} +.SS sh (SuperH) functions +.\" See linux/arch/sh/kernel/vsyscall/vsyscall.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_rt_sigreturn LINUX_2.6 +__kernel_sigreturn LINUX_2.6 +__kernel_vsyscall LINUX_2.6 +.TE +.if t \{\ +.in +.ft P +\} +.SS i386 functions +.\" See linux/arch/x86/vdso/vdso32/vdso32.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__kernel_sigreturn LINUX_2.5 +__kernel_rt_sigreturn LINUX_2.5 +__kernel_vsyscall LINUX_2.5 +.\" Added in 7a59ed415f5b57469e22e41fc4188d5399e0b194 and updated +.\" in 37c975545ec63320789962bf307f000f08fabd48. +__vdso_clock_gettime LINUX_2.6 (exported since Linux 3.15) +__vdso_gettimeofday LINUX_2.6 (exported since Linux 3.15) +__vdso_time LINUX_2.6 (exported since Linux 3.15) +.TE +.if t \{\ +.in +.ft P +\} +.SS x86-64 functions +.\" See linux/arch/x86/vdso/vdso.lds.S +The table below lists the symbols exported by the vDSO. +All of these symbols are also available without the "__vdso_" prefix, but +you should ignore those and stick to the names below. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__vdso_clock_gettime LINUX_2.6 +__vdso_getcpu LINUX_2.6 +__vdso_gettimeofday LINUX_2.6 +__vdso_time LINUX_2.6 +.TE +.if t \{\ +.in +.ft P +\} +.SS x86/x32 functions +.\" See linux/arch/x86/vdso/vdso32.lds.S +The table below lists the symbols exported by the vDSO. +.if t \{\ +.ft CW +\} +.TS +l l. +symbol version +_ +__vdso_clock_gettime LINUX_2.6 +__vdso_getcpu LINUX_2.6 +__vdso_gettimeofday LINUX_2.6 +__vdso_time LINUX_2.6 +.TE +.if t \{\ +.in +.ft P +\} +.SS History +The vDSO was originally just a single function\[em]the vsyscall. +In older kernels, you might see that name +in a process's memory map rather than "vdso". +Over time, people realized that this mechanism +was a great way to pass more functionality +to user space, so it was reconceived as a vDSO in the current format. +.SH SEE ALSO +.BR syscalls (2), +.BR getauxval (3), +.BR proc (5) +.P +The documents, examples, and source code in the Linux source code tree: +.P +.in +4n +.EX +Documentation/ABI/stable/vdso +Documentation/ia64/fsys.rst +Documentation/vDSO/* (includes examples of using the vDSO) +.P +find arch/ \-iname \[aq]*vdso*\[aq] \-o \-iname \[aq]*gate*\[aq] +.EE +.in diff --git a/man/man7/vsock.7 b/man/man7/vsock.7 new file mode 100644 index 0000000..015e9db --- /dev/null +++ b/man/man7/vsock.7 @@ -0,0 +1,232 @@ +.\" Copyright (C) 2018, Stefan Hajnoczi +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH vsock 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +vsock \- Linux VSOCK address family +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);" +.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);" +.fi +.SH DESCRIPTION +The VSOCK address family facilitates communication between virtual machines and +the host they are running on. +This address family is used by guest agents and +hypervisor services that need a communications channel that is independent of +virtual machine network configuration. +.P +Valid socket types are +.B SOCK_STREAM +and +.BR SOCK_DGRAM . +.B SOCK_STREAM +provides connection-oriented byte streams with guaranteed, in-order delivery. +.B SOCK_DGRAM +provides a connectionless datagram packet service with best-effort delivery and +best-effort ordering. +Availability of these socket types is dependent on the +underlying hypervisor. +.P +A new socket is created with +.P +.in +4n +.EX +socket(AF_VSOCK, socket_type, 0); +.EE +.in +.P +When a process wants to establish a connection, it calls +.BR connect (2) +with a given destination socket address. +The socket is automatically bound to a free port if unbound. +.P +A process can listen for incoming connections by first binding to a socket +address using +.BR bind (2) +and then calling +.BR listen (2). +.P +Data is transmitted using the +.BR send (2) +or +.BR write (2) +families of system calls and data is received using the +.BR recv (2) +or +.BR read (2) +families of system calls. +.SS Address format +A socket address is defined as a combination of a 32-bit Context Identifier +(CID) and a 32-bit port number. +The CID identifies the source or destination, +which is either a virtual machine or the host. +The port number differentiates between multiple services running on +a single machine. +.P +.in +4n +.EX +struct sockaddr_vm { + sa_family_t svm_family; /* Address family: AF_VSOCK */ + unsigned short svm_reserved1; + unsigned int svm_port; /* Port # in host byte order */ + unsigned int svm_cid; /* Address in host byte order */ + unsigned char svm_zero[sizeof(struct sockaddr) \- + sizeof(sa_family_t) \- + sizeof(unsigned short) \- + sizeof(unsigned int) \- + sizeof(unsigned int)]; +}; +.EE +.in +.P +.I svm_family +is always set to +.BR AF_VSOCK . +.I svm_reserved1 +is always set to 0. +.I svm_port +contains the port number in host byte order. +The port numbers below 1024 are called +.IR "privileged ports" . +Only a process with the +.B CAP_NET_BIND_SERVICE +capability may +.BR bind (2) +to these port numbers. +.I svm_zero +must be zero-filled. +.P +There are several special addresses: +.B VMADDR_CID_ANY +(\-1U) +means any address for binding; +.B VMADDR_CID_HYPERVISOR +(0) is reserved for services built into the hypervisor; +.B VMADDR_CID_LOCAL +(1) is the well-known address for local communication (loopback); +.B VMADDR_CID_HOST +(2) +is the well-known address of the host. +.P +The special constant +.B VMADDR_PORT_ANY +(\-1U) +means any port number for binding. +.SS Live migration +Sockets are affected by live migration of virtual machines. +Connected +.B SOCK_STREAM +sockets become disconnected when the virtual machine migrates to a new host. +Applications must reconnect when this happens. +.P +The local CID may change across live migration if the old CID is +not available on the new host. +Bound sockets are automatically updated to the new CID. +.SS Ioctls +The following ioctls are available on the +.I /dev/vsock +device. +.TP +.B IOCTL_VM_SOCKETS_GET_LOCAL_CID +Get the CID of the local machine. +The argument is a pointer to an +.IR "unsigned int" . +.IP +.in +4n +.EX +ioctl(fd, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid); +.EE +.in +.IP +Consider using +.B VMADDR_CID_ANY +when binding instead of getting the local CID with +.BR IOCTL_VM_SOCKETS_GET_LOCAL_CID . +.SS Local communication +.B VMADDR_CID_LOCAL +(1) directs packets to the same host that generated them. +This is useful +for testing applications on a single host and for debugging. +.P +The local CID obtained with +.B IOCTL_VM_SOCKETS_GET_LOCAL_CID +can be used for the same purpose, but it is preferable to use +.BR VMADDR_CID_LOCAL . +.SH ERRORS +.TP +.B EACCES +Unable to bind to a privileged port without the +.B CAP_NET_BIND_SERVICE +capability. +.TP +.B EADDRINUSE +Unable to bind to a port that is already in use. +.TP +.B EADDRNOTAVAIL +Unable to find a free port for binding or unable to bind to a nonlocal CID. +.TP +.B EINVAL +Invalid parameters. +This includes: +attempting to bind a socket that is already bound, providing an invalid struct +.IR sockaddr_vm , +and other input validation errors. +.TP +.B ENOPROTOOPT +Invalid socket option in +.BR setsockopt (2) +or +.BR getsockopt (2). +.TP +.B ENOTCONN +Unable to perform operation on an unconnected socket. +.TP +.B EOPNOTSUPP +Operation not supported. +This includes: +the +.B MSG_OOB +flag that is not implemented for the +.BR send (2) +family of syscalls and +.B MSG_PEEK +for the +.BR recv (2) +family of syscalls. +.TP +.B EPROTONOSUPPORT +Invalid socket protocol number. +The protocol should always be 0. +.TP +.B ESOCKTNOSUPPORT +Unsupported socket type in +.BR socket (2). +Only +.B SOCK_STREAM +and +.B SOCK_DGRAM +are valid. +.SH VERSIONS +Support for VMware (VMCI) has been available since Linux 3.9. +KVM (virtio) is supported since Linux 4.8. +Hyper-V is supported since Linux 4.14. +.P +.B VMADDR_CID_LOCAL +is supported since Linux 5.6. +.\" commit ef343b35d46667668a099655fca4a5b2e43a5dfe +Local communication in the guest and on the host is available since Linux 5.6. +Previous versions supported only local communication within a guest +(not on the host), and with only some transports (VMCI and virtio). +.SH SEE ALSO +.BR bind (2), +.BR connect (2), +.BR listen (2), +.BR recv (2), +.BR send (2), +.BR socket (2), +.BR capabilities (7) diff --git a/man/man7/x25.7 b/man/man7/x25.7 new file mode 100644 index 0000000..920865c --- /dev/null +++ b/man/man7/x25.7 @@ -0,0 +1,124 @@ +.\" SPDX-License-Identifier: Linux-man-pages-1-para +.\" +.\" This man page is Copyright (C) 1998 Heiner Eisen. +.\" +.\" $Id: x25.7,v 1.4 1999/05/18 10:35:12 freitag Exp $ +.\" +.TH x25 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +x25 +\- +ITU-T X.25 / ISO/IEC\~8208 protocol interface +.SH SYNOPSIS +.nf +.B #include +.B #include +.P +.IB x25_socket " = socket(AF_X25, SOCK_SEQPACKET, 0);" +.fi +.SH DESCRIPTION +X25 sockets provide an interface to the X.25 packet layer protocol. +This allows applications to +communicate over a public X.25 data network as standardized by +International Telecommunication Union's recommendation X.25 +(X.25 DTE-DCE mode). +X25 sockets can also be used for communication +without an intermediate X.25 network (X.25 DTE-DTE mode) as described +in ISO/IEC\~8208. +.P +Message boundaries are preserved \[em] a +.BR read (2) +from a socket will +retrieve the same chunk of data as output with the corresponding +.BR write (2) +to the peer socket. +When necessary, the kernel takes care +of segmenting and reassembling long messages by means of +the X.25 M-bit. +There is no hard-coded upper limit for the +message size. +However, reassembling of a long message might fail if +there is a temporary lack of system resources or when other constraints +(such as socket memory or buffer size limits) become effective. +If that +occurs, the X.25 connection will be reset. +.SS Socket addresses +The +.B AF_X25 +socket address family uses the +.I struct sockaddr_x25 +for representing network addresses as defined in ITU-T +recommendation X.121. +.P +.in +4n +.EX +struct sockaddr_x25 { + sa_family_t sx25_family; /* must be AF_X25 */ + x25_address sx25_addr; /* X.121 Address */ +}; +.EE +.in +.P +.I sx25_addr +contains a char array +.I x25_addr[] +to be interpreted as a null-terminated string. +.I sx25_addr.x25_addr[] +consists of up to 15 (not counting the terminating null byte) ASCII +characters forming the X.121 address. +Only the decimal digit characters from \[aq]0\[aq] to \[aq]9\[aq] are allowed. +.SS Socket options +The following X.25-specific socket options can be set by using +.BR setsockopt (2) +and read with +.BR getsockopt (2) +with the +.I level +argument set to +.BR SOL_X25 . +.TP +.B X25_QBITINCL +Controls whether the X.25 Q-bit (Qualified Data Bit) is accessible by the +user. +It expects an integer argument. +If set to 0 (default), +the Q-bit is never set for outgoing packets and the Q-bit of incoming +packets is ignored. +If set to 1, an additional first byte is prepended +to each message read from or written to the socket. +For data read from +the socket, a 0 first byte indicates that the Q-bits of the corresponding +incoming data packets were not set. +A first byte with value 1 indicates +that the Q-bit of the corresponding incoming data packets was set. +If the first byte of the data written to the socket is 1, the Q-bit of the +corresponding outgoing data packets will be set. +If the first byte is 0, +the Q-bit will not be set. +.SH VERSIONS +The AF_X25 protocol family is a new feature of Linux 2.2. +.SH BUGS +Plenty, as the X.25 PLP implementation is +.BR CONFIG_EXPERIMENTAL . +.P +This man page is incomplete. +.P +There is no dedicated application programmer's header file yet; +you need to include the kernel header file +.IR . +.B CONFIG_EXPERIMENTAL +might also imply that future versions of the +interface are not binary compatible. +.P +X.25 N-Reset events are not propagated to the user process yet. +Thus, +if a reset occurred, data might be lost without notice. +.SH SEE ALSO +.BR socket (2), +.BR socket (7) +.P +Jonathan Simon Naylor: +\[lq]The Re-Analysis and Re-Implementation of X.25.\[rq] +The URL is +.UR ftp://ftp.pspt.fi\:/pub\:/ham\:/linux\:/ax25\:/x25doc.tgz +.UE . diff --git a/man/man7/xattr.7 b/man/man7/xattr.7 new file mode 100644 index 0000000..02381ca --- /dev/null +++ b/man/man7/xattr.7 @@ -0,0 +1,180 @@ +.\" Extended attributes manual page +.\" +.\" Copyright (C) 2000, 2002, 2007 Andreas Gruenbacher +.\" Copyright (C) 2001, 2002, 2004, 2007 Silicon Graphics, Inc. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH xattr 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +xattr \- Extended attributes +.SH DESCRIPTION +Extended attributes are name:value pairs associated permanently with +files and directories, similar to the environment strings associated +with a process. +An attribute may be defined or undefined. +If it is defined, its value may be empty or non-empty. +.P +Extended attributes are extensions to the normal attributes which are +associated with all inodes in the system (i.e., the +.BR stat (2) +data). +They are often used to provide additional functionality +to a filesystem\[em]for example, additional security features such as +Access Control Lists (ACLs) may be implemented using extended attributes. +.P +Users with search access to a file or directory may use +.BR listxattr (2) +to retrieve a list of attribute names defined for that file or directory. +.P +Extended attributes are accessed as atomic objects. +Reading +.RB ( getxattr (2)) +retrieves the whole value of an attribute and stores it in a buffer. +Writing +.RB ( setxattr (2)) +replaces any previous value with the new value. +.P +Space consumed for extended attributes may be counted towards the disk quotas +of the file owner and file group. +.SS Extended attribute namespaces +Attribute names are null-terminated strings. +The attribute name is always specified in the fully qualified +.I namespace.attribute +form, for example, +.IR user.mime_type , +.IR trusted.md5sum , +.IR system.posix_acl_access , +or +.IR security.selinux . +.P +The namespace mechanism is used to define different classes of extended +attributes. +These different classes exist for several reasons; +for example, the permissions +and capabilities required for manipulating extended attributes of one +namespace may differ to another. +.P +Currently, the +.IR security , +.IR system , +.IR trusted , +and +.I user +extended attribute classes are defined as described below. +Additional classes may be added in the future. +.SS Extended security attributes +The security attribute namespace is used by kernel security modules, +such as Security Enhanced Linux, and also to implement file capabilities (see +.BR capabilities (7)). +Read and write access permissions to security attributes depend on the +policy implemented for each security attribute by the security module. +When no security module is loaded, all processes have read access to +extended security attributes, and write access is limited to processes +that have the +.B CAP_SYS_ADMIN +capability. +.SS System extended attributes +System extended attributes are used by the kernel to store system +objects such as Access Control Lists. +Read and write +access permissions to system attributes depend on the policy implemented +for each system attribute implemented by filesystems in the kernel. +.SS Trusted extended attributes +Trusted extended attributes are visible and accessible only to processes that +have the +.B CAP_SYS_ADMIN +capability. +Attributes in this class are used to implement mechanisms in user +space (i.e., outside the kernel) which keep information in extended attributes +to which ordinary processes should not have access. +.SS User extended attributes +User extended attributes may be assigned to files and directories for +storing arbitrary additional information such as the mime type, +character set or encoding of a file. +The access permissions for user +attributes are defined by the file permission bits: +read permission is required to retrieve the attribute value, +and writer permission is required to change it. +.P +The file permission bits of regular files and directories are +interpreted differently from the file permission bits of special files +and symbolic links. +For regular files and directories the file +permission bits define access to the file's contents, while for device special +files they define access to the device described by the special file. +The file permissions of symbolic links are not used in access checks. +These differences would allow users to consume filesystem resources in +a way not controllable by disk quotas for group or world writable +special files and directories. +.P +For this reason, +user extended attributes are allowed only for regular files and directories, +and access to user extended attributes is restricted to the +owner and to users with appropriate capabilities for directories with the +sticky bit set (see the +.BR chmod (1) +manual page for an explanation of the sticky bit). +.SS Filesystem differences +The kernel and the filesystem may place limits on the maximum number +and size of extended attributes that can be associated with a file. +The VFS-imposed limits on attribute names and values are 255 bytes +and 64\ kB, respectively. +The list of attribute names that +can be returned is also limited to 64\ kB +(see BUGS in +.BR listxattr (2)). +.P +Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), +require the filesystem to be mounted with the +.B user_xattr +mount option in order for user extended attributes to be used. +.P +In the current ext2, ext3, and ext4 filesystem implementations, +the total bytes used by the names and values of all of a file's +extended attributes must fit in a single filesystem block (1024, 2048 +or 4096 bytes, depending on the block size specified when the +filesystem was created). +.P +In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no +practical limit on the number of extended attributes +associated with a file, and the algorithms used to store extended +attribute information on disk are scalable. +.P +In the JFS, XFS, and Reiserfs filesystem implementations, +the limit on bytes used in an EA value is the ceiling imposed by the VFS. +.P +In the Btrfs filesystem implementation, +the total bytes used for the name, value, and implementation overhead bytes +is limited to the filesystem +.I nodesize +value (16\ kB by default). +.SH STANDARDS +Extended attributes are not specified in POSIX.1, but some other systems +(e.g., the BSDs and Solaris) provide a similar feature. +.SH NOTES +Since the filesystems on which extended attributes are stored might also +be used on architectures with a different byte order and machine word +size, care should be taken to store attribute values in an +architecture-independent format. +.P +This page was formerly named +.BR attr (5). +.\" .SH AUTHORS +.\" Andreas Gruenbacher, +.\" .RI < a.gruenbacher@bestbits.at > +.\" and the SGI XFS development team, +.\" .RI < linux-xfs@oss.sgi.com >. +.SH SEE ALSO +.BR attr (1), +.BR getfattr (1), +.BR setfattr (1), +.BR getxattr (2), +.BR ioctl_iflags (2), +.BR listxattr (2), +.BR removexattr (2), +.BR setxattr (2), +.BR acl (5), +.BR capabilities (7), +.BR selinux (8) diff --git a/man/man8/iconvconfig.8 b/man/man8/iconvconfig.8 new file mode 100644 index 0000000..c7e962e --- /dev/null +++ b/man/man8/iconvconfig.8 @@ -0,0 +1,92 @@ +.\" Copyright (C) 2014 Marko Myllynen +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH iconvconfig 8 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iconvconfig \- create iconv module configuration cache +.SH SYNOPSIS +.B iconvconfig +.RI [ options ] +.RI [ directory ]... +.SH DESCRIPTION +The +.BR iconv (3) +function internally uses +.I gconv +modules to convert to and from a character set. +A configuration file is used to determine the needed modules +for a conversion. +Loading and parsing such a configuration file would slow down +programs that use +.BR iconv (3), +so a caching mechanism is employed. +.P +The +.B iconvconfig +program reads iconv module configuration files and writes +a fast-loading gconv module configuration cache file. +.P +In addition to the system provided gconv modules, the user can specify +custom gconv module directories with the environment variable +.BR GCONV_PATH . +However, iconv module configuration caching is used only when +the environment variable +.B GCONV_PATH +is not set. +.SH OPTIONS +.TP +.B "\-\-nostdlib" +Do not search the system default gconv directory, +only the directories provided on the command line. +.TP +.BI \-\-output= outputfile +.TQ +.BI \-o\~ outputfile +Use +.I outputfile +for output instead of the system default cache location. +.TP +.BI \-\-prefix= pathname +Set the prefix to be prepended to the system pathnames. +See FILES, below. +By default, the prefix is empty. +Setting the prefix to +.IR foo , +the gconv module configuration would be read from +.I foo/usr/lib/gconv/gconv\-modules +and the cache would be written to +.IR foo/usr/lib/gconv/gconv\-modules.cache . +.TP +.B \-\-help +.TQ +.B \-? +Print a usage summary and exit. +.TP +.B \-\-usage +Print a short usage summary and exit. +.TP +.B \-\-version +.TQ +.B \-V +Print the version number, license, and disclaimer of warranty for +.BR iconv . +.SH EXIT STATUS +Zero on success, nonzero on errors. +.SH FILES +.TP +.I /usr/lib/gconv +Usual default gconv module path. +.TP +.I /usr/lib/gconv/gconv\-modules +Usual system default gconv module configuration file. +.TP +.I /usr/lib/gconv/gconv\-modules.cache +Usual system gconv module configuration cache. +.P +Depending on the architecture, +the above files may instead be located at directories with the path prefix +.IR /usr/lib64 . +.SH SEE ALSO +.BR iconv (1), +.BR iconv (3) diff --git a/man/man8/intro.8 b/man/man8/intro.8 new file mode 100644 index 0000000..1affa45 --- /dev/null +++ b/man/man8/intro.8 @@ -0,0 +1,29 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" and Copyright (C) 2007 Michael Kerrisk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:35:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" 2007-10-23 mtk: minor rewrites, and added paragraph on exit status +.\" +.TH intro 8 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intro \- introduction to administration and privileged commands +.SH DESCRIPTION +Section 8 of the manual describes commands +which either can be or are used only by the superuser, +like system-administration commands, daemons, +and hardware-related commands. +.P +As with the commands described in Section 1, the commands described +in this section terminate with an exit status that indicates +whether the command succeeded or failed. +See +.BR intro (1) +for more information. +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! diff --git a/man/man8/ld-linux.8 b/man/man8/ld-linux.8 new file mode 100644 index 0000000..c575620 --- /dev/null +++ b/man/man8/ld-linux.8 @@ -0,0 +1 @@ +.so man8/ld.so.8 diff --git a/man/man8/ld-linux.so.8 b/man/man8/ld-linux.so.8 new file mode 100644 index 0000000..c575620 --- /dev/null +++ b/man/man8/ld-linux.so.8 @@ -0,0 +1 @@ +.so man8/ld.so.8 diff --git a/man/man8/ld.so.8 b/man/man8/ld.so.8 new file mode 100644 index 0000000..b464448 --- /dev/null +++ b/man/man8/ld.so.8 @@ -0,0 +1,929 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This is in the public domain +.\" %%%LICENSE_END +.\" Various parts: +.\" Copyright (C) 2007-9, 2013, 2016 Michael Kerrisk +.\" +.TH ld.so 8 2024-05-08 "Linux man-pages (unreleased)" +.SH NAME +ld.so, ld\-linux.so \- dynamic linker/loader +.SH SYNOPSIS +The dynamic linker can be run either indirectly by running some +dynamically linked program or shared object +(in which case no command-line options +to the dynamic linker can be passed and, in the ELF case, the dynamic linker +which is stored in the +.B .interp +section of the program is executed) or directly by running: +.P +.I /lib/ld\-linux.so.* +[OPTIONS] [PROGRAM [ARGUMENTS]] +.SH DESCRIPTION +The programs +.B ld.so +and +.B ld\-linux.so* +find and load the shared objects (shared libraries) needed by a program, +prepare the program to run, and then run it. +.P +Linux binaries require dynamic linking (linking at run time) +unless the +.B \-static +option was given to +.BR ld (1) +during compilation. +.P +The program +.B ld.so +handles a.out binaries, a binary format used long ago. +The program +.B ld\-linux.so* +(\fI/lib/ld\-linux.so.1\fP for libc5, \fI/lib/ld\-linux.so.2\fP for glibc2) +handles binaries that are in the more modern ELF format. +Both programs have the same behavior, and use the same +support files and programs +.RB ( ldd (1), +.BR ldconfig (8), +and +.IR /etc/ld.so.conf ). +.P +When resolving shared object dependencies, +the dynamic linker first inspects each dependency +string to see if it contains a slash (this can occur if +a shared object pathname containing slashes was specified at link time). +If a slash is found, then the dependency string is interpreted as +a (relative or absolute) pathname, +and the shared object is loaded using that pathname. +.P +If a shared object dependency does not contain a slash, +then it is searched for in the following order: +.IP (1) 5 +Using the directories specified in the +DT_RPATH dynamic section attribute +of the binary if present and DT_RUNPATH attribute does not exist. +.IP (2) +Using the environment variable +.BR LD_LIBRARY_PATH , +unless the executable is being run in secure-execution mode (see below), +in which case this variable is ignored. +.IP (3) +Using the directories specified in the +DT_RUNPATH dynamic section attribute +of the binary if present. +Such directories are searched only to +find those objects required by DT_NEEDED (direct dependencies) entries +and do not apply to those objects' children, +which must themselves have their own DT_RUNPATH entries. +This is unlike DT_RPATH, which is applied +to searches for all children in the dependency tree. +.IP (4) +From the cache file +.IR /etc/ld.so.cache , +which contains a compiled list of candidate shared objects previously found +in the augmented library path. +If, however, the binary was linked with the +.B \-z nodefaultlib +linker option, shared objects in the default paths are skipped. +Shared objects installed in hardware capability directories (see below) +are preferred to other shared objects. +.IP (5) +In the default path +.IR /lib , +and then +.IR /usr/lib . +(On some 64-bit architectures, the default paths for 64-bit shared objects are +.IR /lib64 , +and then +.IR /usr/lib64 .) +If the binary was linked with the +.B \-z nodefaultlib +linker option, this step is skipped. +.\" +.SS Dynamic string tokens +In several places, the dynamic linker expands dynamic string tokens: +.IP \[bu] 3 +In the environment variables +.BR LD_LIBRARY_PATH , +.BR LD_PRELOAD , +and +.BR LD_AUDIT , +.IP \[bu] +inside the values of the dynamic section tags +.BR DT_NEEDED , +.BR DT_RPATH , +.BR DT_RUNPATH , +.BR DT_AUDIT , +and +.B DT_DEPAUDIT +of ELF binaries, +.IP \[bu] +in the arguments to the +.B ld.so +command line options +.BR \-\-audit , +.BR \-\-library\-path , +and +.B \-\-preload +(see below), and +.IP \[bu] +in the filename arguments to the +.BR dlopen (3) +and +.BR dlmopen (3) +functions. +.P +The substituted tokens are as follows: +.TP +.IR $ORIGIN " (or equivalently " ${ORIGIN} ) +This expands to +the directory containing the program or shared object. +Thus, an application located in +.I somedir/app +could be compiled with +.IP +.in +4n +.EX +gcc \-Wl,\-rpath,\[aq]$ORIGIN/../lib\[aq] +.EE +.in +.IP +so that it finds an associated shared object in +.I somedir/lib +no matter where +.I somedir +is located in the directory hierarchy. +This facilitates the creation of "turn-key" applications that +do not need to be installed into special directories, +but can instead be unpacked into any directory +and still find their own shared objects. +.TP +.IR $LIB " (or equivalently " ${LIB} ) +This expands to +.I lib +or +.I lib64 +depending on the architecture +(e.g., on x86-64, it expands to +.I lib64 +and +on x86-32, it expands to +.IR lib ). +.TP +.IR $PLATFORM " (or equivalently " ${PLATFORM} ) +This expands to a string corresponding to the processor type +of the host system (e.g., "x86_64"). +On some architectures, the Linux kernel doesn't provide a platform +string to the dynamic linker. +The value of this string is taken from the +.B AT_PLATFORM +value in the auxiliary vector (see +.BR getauxval (3)). +.\" To get an idea of the places that $PLATFORM would match, +.\" look at the output of the following: +.\" +.\" mkdir /tmp/d +.\" LD_LIBRARY_PATH=/tmp/d strace -e open /bin/date 2>&1 | grep /tmp/d +.\" +.\" ld.so lets names be abbreviated, so $O will work for $ORIGIN; +.\" Don't do this!! +.P +Note that the dynamic string tokens have to be quoted properly when +set from a shell, +to prevent their expansion as shell or environment variables. +.SH OPTIONS +.TP +.BR \-\-argv0 " \fIstring\fP (since glibc 2.33)" +Set +.I argv[0] +to the value +.I string +before running the program. +.TP +.BI \-\-audit " list" +Use objects named in +.I list +as auditors. +The objects in +.I list +are delimited by colons. +.TP +.BI \-\-glibc-hwcaps-mask " list" +only search built-in subdirectories if in +.IR list . +.TP +.BI \-\-glibc-hwcaps-prepend " list" +Search glibc-hwcaps subdirectories in +.IR list . +.TP +.B \-\-inhibit\-cache +Do not use +.IR /etc/ld.so.cache . +.TP +.BI \-\-library\-path " path" +Use +.I path +instead of +.B LD_LIBRARY_PATH +environment variable setting (see below). +The names +.IR ORIGIN , +.IR LIB , +and +.I PLATFORM +are interpreted as for the +.B LD_LIBRARY_PATH +environment variable. +.TP +.BI \-\-inhibit\-rpath " list" +Ignore RPATH and RUNPATH information in object names in +.IR list . +This option is ignored when running in secure-execution mode (see below). +The objects in +.I list +are delimited by colons or spaces. +.TP +.B \-\-list +List all dependencies and how they are resolved. +.TP +.BR \-\-list\-diagnostics " (since glibc 2.33)" +Print system diagnostic information in a machine-readable format, +such as some internal loader variables, +the auxiliary vector +(see +.BR getauxval (3)), +and the environment variables. +On some architectures, +the command might print additional information +(like the cpu features used in GNU indirect function selection on x86). +.BR \-\-list\-tunables " (since glibc 2.33)" +Print the names and values of all tunables, +along with the minimum and maximum allowed values. +.TP +.BR \-\-preload " \fIlist\fP (since glibc 2.30)" +Preload the objects specified in +.IR list . +The objects in +.I list +are delimited by colons or spaces. +The objects are preloaded as explained in the description of the +.B LD_PRELOAD +environment variable below. +.IP +By contrast with +.BR LD_PRELOAD , +the +.B \-\-preload +option provides a way to perform preloading for a single executable +without affecting preloading performed in any child process that executes +a new program. +.TP +.B \-\-verify +Verify that program is dynamically linked and this dynamic linker can handle +it. +.SH ENVIRONMENT +Various environment variables influence the operation of the dynamic linker. +.\" +.SS Secure-execution mode +For security reasons, +if the dynamic linker determines that a binary should be +run in secure-execution mode, +the effects of some environment variables are voided or modified, +and furthermore those environment variables are stripped from the environment, +so that the program does not even see the definitions. +Some of these environment variables affect the operation of +the dynamic linker itself, and are described below. +Other environment variables treated in this way include: +.BR GCONV_PATH , +.BR GETCONF_DIR , +.BR HOSTALIASES , +.BR LOCALDOMAIN , +.BR LD_AUDIT , +.BR LD_DEBUG , +.BR LD_DEBUG_OUTPUT , +.BR LD_DYNAMIC_WEAK , +.BR LD_HWCAP_MASK , +.BR LD_LIBRARY_PATH , +.BR LD_ORIGIN_PATH , +.BR LD_PRELOAD , +.BR LD_PROFILE , +.BR LD_SHOW_AUXV , +.BR LOCALDOMAIN , +.BR LOCPATH , +.BR MALLOC_TRACE , +.BR NIS_PATH , +.BR NLSPATH , +.BR RESOLV_HOST_CONF , +.BR RES_OPTIONS , +.BR TMPDIR , +and +.BR TZDIR . +.P +A binary is executed in secure-execution mode if the +.B AT_SECURE +entry in the auxiliary vector (see +.BR getauxval (3)) +has a nonzero value. +This entry may have a nonzero value for various reasons, including: +.IP \[bu] 3 +The process's real and effective user IDs differ, +or the real and effective group IDs differ. +This typically occurs as a result of executing +a set-user-ID or set-group-ID program. +.IP \[bu] +A process with a non-root user ID executed a binary that +conferred capabilities to the process. +.IP \[bu] +A nonzero value may have been set by a Linux Security Module. +.\" +.SS Environment variables +Among the more important environment variables are the following: +.TP +.BR LD_ASSUME_KERNEL " (from glibc 2.2.3 to glibc 2.36)" +Each shared object can inform the dynamic linker of the minimum kernel ABI +version that it requires. +(This requirement is encoded in an ELF note section that is viewable via +.I readelf\~\-n +as a section labeled +.BR NT_GNU_ABI_TAG .) +At run time, +the dynamic linker determines the ABI version of the running kernel and +will reject loading shared objects that specify minimum ABI versions +that exceed that ABI version. +.IP +.B LD_ASSUME_KERNEL +can be used to +cause the dynamic linker to assume that it is running on a system with +a different kernel ABI version. +For example, the following command line causes the +dynamic linker to assume it is running on Linux 2.2.5 when loading +the shared objects required by +.IR myprog : +.IP +.in +4n +.EX +$ \fBLD_ASSUME_KERNEL=2.2.5 ./myprog\fP +.EE +.in +.IP +On systems that provide multiple versions of a shared object +(in different directories in the search path) that have +different minimum kernel ABI version requirements, +.B LD_ASSUME_KERNEL +can be used to select the version of the object that is used +(dependent on the directory search order). +.IP +Historically, the most common use of the +.B LD_ASSUME_KERNEL +feature was to manually select the older +LinuxThreads POSIX threads implementation on systems that provided both +LinuxThreads and NPTL +(which latter was typically the default on such systems); +see +.BR pthreads (7). +.TP +.BR LD_BIND_NOW " (since glibc 2.1.1)" +If set to a nonempty string, +causes the dynamic linker to resolve all symbols +at program startup instead of deferring function call resolution to the point +when they are first referenced. +This is useful when using a debugger. +.TP +.B LD_LIBRARY_PATH +A list of directories in which to search for +ELF libraries at execution time. +The items in the list are separated by either colons or semicolons, +and there is no support for escaping either separator. +A zero-length directory name indicates the current working directory. +.IP +This variable is ignored in secure-execution mode. +.IP +Within the pathnames specified in +.BR LD_LIBRARY_PATH , +the dynamic linker expands the tokens +.IR $ORIGIN , +.IR $LIB , +and +.I $PLATFORM +(or the versions using curly braces around the names) +as described above in +.IR "Dynamic string tokens" . +Thus, for example, +the following would cause a library to be searched for in either the +.I lib +or +.I lib64 +subdirectory below the directory containing the program to be executed: +.IP +.in +4n +.EX +$ \fBLD_LIBRARY_PATH=\[aq]$ORIGIN/$LIB\[aq] prog\fP +.EE +.in +.IP +(Note the use of single quotes, which prevent expansion of +.I $ORIGIN +and +.I $LIB +as shell variables!) +.TP +.B LD_PRELOAD +A list of additional, user-specified, ELF shared +objects to be loaded before all others. +This feature can be used to selectively override functions +in other shared objects. +.IP +The items of the list can be separated by spaces or colons, +and there is no support for escaping either separator. +The objects are searched for using the rules given under DESCRIPTION. +Objects are searched for and added to the link map in the left-to-right +order specified in the list. +.IP +In secure-execution mode, +preload pathnames containing slashes are ignored. +Furthermore, shared objects are preloaded only +from the standard search directories and only +if they have set-user-ID mode bit enabled (which is not typical). +.IP +Within the names specified in the +.B LD_PRELOAD +list, the dynamic linker understands the tokens +.IR $ORIGIN , +.IR $LIB , +and +.I $PLATFORM +(or the versions using curly braces around the names) +as described above in +.IR "Dynamic string tokens" . +(See also the discussion of quoting under the description of +.BR LD_LIBRARY_PATH .) +.\" Tested with the following: +.\" +.\" LD_PRELOAD='$LIB/libmod.so' LD_LIBRARY_PATH=. ./prog +.\" +.\" which will preload the libmod.so in 'lib' or 'lib64', using it +.\" in preference to the version in '.'. +.IP +There are various methods of specifying libraries to be preloaded, +and these are handled in the following order: +.RS +.IP (1) 5 +The +.B LD_PRELOAD +environment variable. +.IP (2) +The +.B \-\-preload +command-line option when invoking the dynamic linker directly. +.IP (3) +The +.I /etc/ld.so.preload +file (described below). +.RE +.TP +.B LD_TRACE_LOADED_OBJECTS +If set (to any value), causes the program to list its dynamic +dependencies, as if run by +.BR ldd (1), +instead of running normally. +.P +Then there are lots of more or less obscure variables, +many obsolete or only for internal use. +.TP +.BR LD_AUDIT " (since glibc 2.4)" +A list of user-specified, ELF shared objects +to be loaded before all others in a separate linker namespace +(i.e., one that does not intrude upon the normal symbol bindings that +would occur in the process) +These objects can be used to audit the operation of the dynamic linker. +The items in the list are colon-separated, +and there is no support for escaping the separator. +.IP +.B LD_AUDIT +is ignored in secure-execution mode. +.IP +The dynamic linker will notify the audit +shared objects at so-called auditing checkpoints\[em]for example, +loading a new shared object, resolving a symbol, +or calling a symbol from another shared object\[em]by +calling an appropriate function within the audit shared object. +For details, see +.BR rtld\-audit (7). +The auditing interface is largely compatible with that provided on Solaris, +as described in its +.IR "Linker and Libraries Guide" , +in the chapter +.IR "Runtime Linker Auditing Interface" . +.IP +Within the names specified in the +.B LD_AUDIT +list, the dynamic linker understands the tokens +.IR $ORIGIN , +.IR $LIB , +and +.I $PLATFORM +(or the versions using curly braces around the names) +as described above in +.IR "Dynamic string tokens" . +(See also the discussion of quoting under the description of +.BR LD_LIBRARY_PATH .) +.IP +Since glibc 2.13, +.\" commit 8e9f92e9d5d7737afdacf79b76d98c4c42980508 +in secure-execution mode, +names in the audit list that contain slashes are ignored, +and only shared objects in the standard search directories that +have the set-user-ID mode bit enabled are loaded. +.TP +.BR LD_BIND_NOT " (since glibc 2.1.95)" +If this environment variable is set to a nonempty string, +do not update the GOT (global offset table) and PLT (procedure linkage table) +after resolving a function symbol. +By combining the use of this variable with +.B LD_DEBUG +(with the categories +.I bindings +and +.IR symbols ), +one can observe all run-time function bindings. +.TP +.BR LD_DEBUG " (since glibc 2.1)" +Output verbose debugging information about operation of the dynamic linker. +The content of this variable is one of more of the following categories, +separated by colons, commas, or (if the value is quoted) spaces: +.RS +.TP 12 +.I help +Specifying +.I help +in the value of this variable does not run the specified program, +and displays a help message about which categories can be specified in this +environment variable. +.TP +.I all +Print all debugging information (except +.I statistics +and +.IR unused ; +see below). +.TP +.I bindings +Display information about which definition each symbol is bound to. +.TP +.I files +Display progress for input file. +.TP +.I libs +Display library search paths. +.TP +.I reloc +Display relocation processing. +.TP +.I scopes +Display scope information. +.TP +.I statistics +Display relocation statistics. +.TP +.I symbols +Display search paths for each symbol look-up. +.TP +.I unused +Determine unused DSOs. +.TP +.I versions +Display version dependencies. +.RE +.IP +Since glibc 2.3.4, +.B LD_DEBUG +is ignored in secure-execution mode, unless the file +.I /etc/suid\-debug +exists (the content of the file is irrelevant). +.TP +.BR LD_DEBUG_OUTPUT " (since glibc 2.1)" +By default, +.B LD_DEBUG +output is written to standard error. +If +.B LD_DEBUG_OUTPUT +is defined, then output is written to the pathname specified by its value, +with the suffix "." (dot) followed by the process ID appended to the pathname. +.IP +.B LD_DEBUG_OUTPUT +is ignored in secure-execution mode. +.TP +.BR LD_DYNAMIC_WEAK " (since glibc 2.1.91)" +By default, when searching shared libraries to resolve a symbol reference, +the dynamic linker will resolve to the first definition it finds. +.IP +Old glibc versions (before glibc 2.2), provided a different behavior: +if the linker found a symbol that was weak, +it would remember that symbol and +keep searching in the remaining shared libraries. +If it subsequently found a strong definition of the same symbol, +then it would instead use that definition. +(If no further symbol was found, +then the dynamic linker would use the weak symbol that it initially found.) +.IP +The old glibc behavior was nonstandard. +(Standard practice is that the distinction between +weak and strong symbols should have effect only at static link time.) +In glibc 2.2, +.\" More precisely 2.1.92 +.\" See weak handling +.\" https://www.sourceware.org/ml/libc-hacker/2000-06/msg00029.html +.\" To: GNU libc hacker +.\" Subject: weak handling +.\" From: Ulrich Drepper +.\" Date: 07 Jun 2000 20:08:12 -0700 +.\" Reply-To: drepper at cygnus dot com (Ulrich Drepper) +the dynamic linker was modified to provide the current behavior +(which was the behavior that was provided by most other implementations +at that time). +.IP +Defining the +.B LD_DYNAMIC_WEAK +environment variable (with any value) provides +the old (nonstandard) glibc behavior, +whereby a weak symbol in one shared library may be overridden by +a strong symbol subsequently discovered in another shared library. +(Note that even when this variable is set, +a strong symbol in a shared library will not override +a weak definition of the same symbol in the main program.) +.IP +Since glibc 2.3.4, +.B LD_DYNAMIC_WEAK +is ignored in secure-execution mode. +.TP +.BR LD_HWCAP_MASK " (from glibc 2.1 to glibc 2.38)" +Mask for hardware capabilities. +Since glibc 2.26, +the option might be ignored +if glibc does not support tunables. +.TP +.BR LD_ORIGIN_PATH " (since glibc 2.1)" +Path where the binary is found. +.\" Used only if $ORIGIN can't be determined by normal means +.\" (from the origin path saved at load time, or from /proc/self/exe)? +.IP +Since glibc 2.4, +.B LD_ORIGIN_PATH +is ignored in secure-execution mode. +.TP +.BR LD_POINTER_GUARD " (from glibc 2.4 to glibc 2.22)" +Set to 0 to disable pointer guarding. +Any other value enables pointer guarding, which is also the default. +Pointer guarding is a security mechanism whereby some pointers to code +stored in writable program memory (return addresses saved by +.BR setjmp (3) +or function pointers used by various glibc internals) are mangled +semi-randomly to make it more difficult for an attacker to hijack +the pointers for use in the event of a buffer overrun or +stack-smashing attack. +Since glibc 2.23, +.\" commit a014cecd82b71b70a6a843e250e06b541ad524f7 +.B LD_POINTER_GUARD +can no longer be used to disable pointer guarding, +which is now always enabled. +.TP +.BR LD_PROFILE " (since glibc 2.1)" +The name of a (single) shared object to be profiled, +specified either as a pathname or a soname. +Profiling output is appended to the file whose name is: +.RI \%$LD_PROFILE_OUTPUT /\: $LD_PROFILE .profile . +.IP +Since glibc 2.2.5, +.B LD_PROFILE +uses a different default path in secure-execution mode. +.TP +.BR LD_PROFILE_OUTPUT " (since glibc 2.1)" +Directory where +.B LD_PROFILE +output should be written. +If this variable is not defined, or is defined as an empty string, +then the default is +.IR /var/tmp . +.IP +.B LD_PROFILE_OUTPUT +is ignored in secure-execution mode; instead +.I /var/profile +is always used. +.TP +.BR LD_SHOW_AUXV " (since glibc 2.1)" +If this environment variable is defined (with any value), +show the auxiliary array passed up from the kernel (see also +.BR getauxval (3)). +.IP +Since glibc 2.3.4, +.B LD_SHOW_AUXV +is ignored in secure-execution mode. +.TP +.BR LD_TRACE_PRELINKING " (from glibc 2.4 to glibc 2.35)" +If this environment variable is defined, +trace prelinking of the object whose name is assigned to +this environment variable. +(Use +.BR ldd (1) +to get a list of the objects that might be traced.) +If the object name is not recognized, +.\" (This is what seems to happen, from experimenting) +then all prelinking activity is traced. +.TP +.BR LD_USE_LOAD_BIAS " (from glibc 2.3.3 to glibc 2.35)" +.\" http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html +.\" Subject: [PATCH] Support LD_USE_LOAD_BIAS +.\" Jakub Jelinek +By default (i.e., if this variable is not defined), +executables and prelinked +shared objects will honor base addresses of their dependent shared objects +and (nonprelinked) position-independent executables (PIEs) +and other shared objects will not honor them. +If +.B LD_USE_LOAD_BIAS +is defined with the value 1, both executables and PIEs +will honor the base addresses. +If +.B LD_USE_LOAD_BIAS +is defined with the value 0, +neither executables nor PIEs will honor the base addresses. +.IP +Since glibc 2.3.3, this variable is ignored in secure-execution mode. +.TP +.BR LD_VERBOSE " (since glibc 2.1)" +If set to a nonempty string, +output symbol versioning information about the +program if the +.B LD_TRACE_LOADED_OBJECTS +environment variable has been set. +.TP +.BR LD_WARN " (since glibc 2.1.3)" +If set to a nonempty string, warn about unresolved symbols. +.TP +.BR LD_PREFER_MAP_32BIT_EXEC " (x86-64 only; since glibc 2.23)" +According to the Intel Silvermont software optimization guide, for 64-bit +applications, branch prediction performance can be negatively impacted +when the target of a branch is more than 4\ GB away from the branch. +If this environment variable is set (to any value), +the dynamic linker +will first try to map executable pages using the +.BR mmap (2) +.B MAP_32BIT +flag, and fall back to mapping without that flag if that attempt fails. +NB: MAP_32BIT will map to the low 2\ GB (not 4\ GB) of the address space. +.IP +Because +.B MAP_32BIT +reduces the address range available for address space layout +randomization (ASLR), +.B LD_PREFER_MAP_32BIT_EXEC +is always disabled in secure-execution mode. +.SH FILES +.TP +.I /lib/ld.so +a.out dynamic linker/loader +.TP +.IR /lib/ld\-linux.so. { 1 , 2 } +ELF dynamic linker/loader +.TP +.I /etc/ld.so.cache +File containing a compiled list of directories in which to search for +shared objects and an ordered list of candidate shared objects. +See +.BR ldconfig (8). +.TP +.I /etc/ld.so.preload +File containing a whitespace-separated list of ELF shared objects to +be loaded before the program. +See the discussion of +.B LD_PRELOAD +above. +If both +.B LD_PRELOAD +and +.I /etc/ld.so.preload +are employed, the libraries specified by +.B LD_PRELOAD +are preloaded first. +.I /etc/ld.so.preload +has a system-wide effect, +causing the specified libraries to be preloaded for +all programs that are executed on the system. +(This is usually undesirable, +and is typically employed only as an emergency remedy, for example, +as a temporary workaround to a library misconfiguration issue.) +.TP +.I lib*.so* +shared objects +.SH NOTES +.SS Legacy Hardware capabilities (from glibc 2.5 to glibc 2.37) +Some shared objects are compiled using hardware-specific instructions which do +not exist on every CPU. +Such objects should be installed in directories whose names define the +required hardware capabilities, such as +.IR /usr/lib/sse2/ . +The dynamic linker checks these directories against the hardware of the +machine and selects the most suitable version of a given shared object. +Hardware capability directories can be cascaded to combine CPU features. +The list of supported hardware capability names depends on the CPU. +The following names are currently recognized: +.\" Presumably, this info comes from sysdeps/i386/dl-procinfo.c and +.\" similar files +.TP +.B Alpha +ev4, ev5, ev56, ev6, ev67 +.TP +.B MIPS +loongson2e, loongson2f, octeon, octeon2 +.TP +.B PowerPC +4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle, +fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601, +ppc64, smt, spe, ucache, vsx +.TP +.B SPARC +flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2 +.TP +.B s390 +dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle, +z900, z990, z9-109, z10, zarch +.TP +.B x86 (32-bit only) +acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx, +mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm +.P +The legacy hardware capabilities support has the drawback that +each new feature added grows the search path exponentially, +because it has to be added to +every combination of the other existing features. +.P +For instance, on x86 32-bit, +if the hardware supports +.B i686 +and +.BR sse2 , +the resulting search path will be +.BR i686/sse2:i686:sse2:. . +A new capability +.B newcap +will set the search path to +.BR newcap/i686/sse2:newcap/i686:newcap/sse2:newcap:i686/sse2:i686:sse2: . +.\" +.SS glibc Hardware capabilities (from glibc 2.33) +.TP +.\" The initial discussion on various pitfalls of the old scheme is +.\" +.\" and the patchset that proposes the glibc-hwcap support is +.\" +glibc 2.33 added a new hardware capability scheme, +where under each CPU architecture, +certain levels can be defined, +grouping support for certain features or special instructions. +Each architecture level has +a fixed set of paths that it adds to the dynamic linker search list, +depending on the hardware of the machine. +Since each new architecture level is +not combined with previously existing ones, +the new scheme does not have the drawback of +growing the dynamic linker search list uncontrollably. +.P +For instance, on x86 64-bit, +if the hardware supports +.B x86_64-v3 +(for instance Intel Haswell or AMD Excavator), +the resulting search path will be +.B glibc-hwcaps/x86-64-v3:glibc-hwcaps/x86-64-v2:. +.\" The x86_64 architectures levels are defined the official ABI: +.\" +.\" The PowerPC and s390x are glibc defined ones based on chip +.\" support (which maps to ISA levels). +The following paths are currently supported, in priority order. +.TP +.B PowerPC (64-bit little-endian only) +power10, power9 +.TP +.B s390 (64-bit only) +z16, z15, z14, z13 +.TP +.B x86 (64-bit only) +x86-64-v4, x86-64-v3, x86-64-v2 +.P +glibc 2.37 removed support for the legacy hardware capabilities. +.\" +.SH SEE ALSO +.BR ld (1), +.BR ldd (1), +.BR pldd (1), +.BR sprof (1), +.BR dlopen (3), +.BR getauxval (3), +.BR elf (5), +.BR capabilities (7), +.BR rtld\-audit (7), +.BR ldconfig (8), +.BR sln (8) +.\" .SH AUTHORS +.\" ld.so: David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus +.\" Torvalds, Lars Wirzenius and Mitch D'Souza +.\" ld\-linux.so: Roland McGrath, Ulrich Drepper and others. +.\" +.\" In the above, (libc5) stands for David Engel's ld.so/ld\-linux.so. diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8 new file mode 100644 index 0000000..a614164 --- /dev/null +++ b/man/man8/ldconfig.8 @@ -0,0 +1,204 @@ +.\" Copyright 1999 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, 6 May 2002, Michael Kerrisk, +.\" Change listed order of /usr/lib and /lib +.TH ldconfig 8 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ldconfig \- configure dynamic linker run-time bindings +.SH SYNOPSIS +.SY /sbin/ldconfig +.\" TODO?: -c, --format, -i, --ignore-aux-cache, --print-cache, +.\" --verbose, -V, --version, -?, --help, --usage +.RB [ \-nNvVX ] +.RB [ \-C\~\c +.IR cache ] +.RB [ \-f\~\c +.IR conf ] +.RB [ \-r\~\c +.IR root ] +.IR directory \~.\|.\|. +.YS +.SY /sbin/ldconfig +.B \-l +.RB [ \-v ] +.IR library \~.\|.\|. +.YS +.SY /sbin/ldconfig +.B \-p +.YS +.SH DESCRIPTION +.B \%ldconfig +creates the necessary links and cache to the most recent shared +libraries found in the directories specified on the command line, +in the file +.IR /etc/ld.so.conf , +and in the trusted directories, +.I /lib +and +.IR /usr/lib . +On some 64-bit architectures such as x86-64, +.I /lib +and +.I /usr/lib +are the trusted directories for 32-bit libraries, +while +.I /lib64 +and +.I /usr/lib64 +are used for 64-bit libraries. +.P +The cache is used by the run-time linker, +.I ld.so +or +.IR ld\-linux.so . +.B \%ldconfig +checks the header and filenames of the libraries it encounters when +determining which versions should have their links updated. +.\" Support for libc4 and libc5 dropped in +.\" 8ee878592c4a642937152c8308b8faef86bcfc40 (2022-07-14) as "obsolete +.\" for over twenty years". +.B \%ldconfig +should normally be run by the superuser as it may require write +permission on some root owned directories and files. +.P +.B \%ldconfig +will look only at files that are named +.I lib*.so* +(for regular shared objects) or +.I ld\-*.so* +(for the dynamic loader itself). +Other files will be ignored. +Also, +.B \%ldconfig +expects a certain pattern to how the symbolic links are set up, +like this example, +where the middle file +.RB ( libfoo.so.1 +here) is the SONAME for the library: +.P +.in +4n +.EX +libfoo.so \-> libfoo.so.1 \-> libfoo.so.1.12 +.EE +.in +.P +Failure to follow this pattern may result in compatibility issues +after an upgrade. +.SH OPTIONS +.TP +.BI \-\-format= fmt +.TQ +.BI \-c\~ fmt +(Since glibc 2.2) +.\" commit 45eca4d141c047950db48c69c8941163d0a61fcd +Use cache format +.IR fmt , +which is one of +.BR old , +.BR new , +or +.BR \%compat . +Since glibc 2.32, +the default is +.BR new . +.\" commit cad64f778aced84efdaa04ae64f8737b86f063ab +Before that, +it was +.BR \%compat . +.TP +.BI \-C\~ cache +Use +.I cache +instead of +.IR /etc/ld.so.cache . +.TP +.BI \-f\~ conf +Use +.I conf +instead of +.IR /etc/ld.so.conf . +.TP +.B \-\-ignore\-aux\-cache +.TQ +.B \-i +(Since glibc 2.7) +.\" commit 27d9ffda17df4d2388687afd12897774fde39bcc +Ignore auxiliary cache file. +.TP +.B \-l +(Since glibc 2.2) +Interpret each operand as a library name and configure its links. +Intended for use only by experts. +.TP +.B \-n +Process only the directories specified on the command line; +don't process the trusted directories, +nor those specified in +.IR /etc/ld.so.conf . +Implies +.BR \-N . +.TP +.B \-N +Don't rebuild the cache. +Unless +.B \-X +is also specified, +links are still updated. +.TP +.B \-\-print\-cache +.TQ +.B \-p +Print the lists of directories and candidate libraries stored in +the current cache. +.TP +.BI \-r\~ root +Change to and use +.I root +as the root directory. +.TP +.B \-\-verbose +.TQ +.B \-v +Verbose mode. +Print current version number, +the name of each directory as it is scanned, +and any links that are created. +Overrides quiet mode. +.TP +.B \-\-version +.TQ +.B \-V +Print program version. +.TP +.B \-X +Don't update links. +Unless +.B \-N +is also specified, +the cache is still rebuilt. +.SH FILES +.\" FIXME Since glibc-2.3.4, "include" directives are supported in ld.so.conf +.\" +.\" FIXME Since glibc-2.4, "hwcap" directives are supported in ld.so.conf +.PD 0 +.TP +.I /lib/ld.so +is the run-time linker/loader. +.TP +.I /etc/ld.so.conf +contains a list of directories, +one per line, +in which to search for libraries. +.TP +.I /etc/ld.so.cache +contains an ordered list of libraries found in the directories +specified in +.IR /etc/ld.so.conf , +as well as those found in the trusted directories. +.PD +.SH SEE ALSO +.BR ldd (1), +.BR ld.so (8) diff --git a/man/man8/nscd.8 b/man/man8/nscd.8 new file mode 100644 index 0000000..07d365c --- /dev/null +++ b/man/man8/nscd.8 @@ -0,0 +1,84 @@ +.\" Copyright 1999 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2008-12-05 Petr Baudis +.\" Rewrite the NOTES section to reflect modern reality +.\" +.TH nscd 8 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nscd \- name service cache daemon +.SH DESCRIPTION +.B nscd +is a daemon that provides a cache for the most common name service +requests. +The default configuration file, +.IR /etc/nscd.conf , +determines the behavior of the cache daemon. +See +.BR nscd.conf (5). +.P +.B nscd +provides caching for accesses of the +.BR passwd (5), +.BR group (5), +.BR hosts (5) +.BR services (5) +and +.I netgroup +databases through standard libc interfaces, such as +.BR getpwnam (3), +.BR getpwuid (3), +.BR getgrnam (3), +.BR getgrgid (3), +.BR gethostbyname (3), +and others. +.P +There are two caches for each database: +a positive one for items found, and a negative one +for items not found. +Each cache has a separate TTL (time-to-live) +period for its data. +Note that the shadow file is specifically not cached. +.BR getspnam (3) +calls remain uncached as a result. +.SH OPTIONS +.TP +.B "\-\-help" +will give you a list with all options and what they do. +.SH NOTES +The daemon will try to watch for changes in configuration files +appropriate for each database (e.g., +.I /etc/passwd +for the +.I passwd +database or +.I /etc/hosts +and +.I /etc/resolv.conf +for the +.I hosts +database), and flush the cache when these are changed. +However, this will happen only after a short delay (unless the +.BR inotify (7) +mechanism is available and glibc 2.9 or later is available), +and this auto-detection does not cover configuration files +required by nonstandard NSS modules, if any are specified in +.IR /etc/nsswitch.conf . +In that case, you need to run the following command +after changing the configuration file of the database so that +.B nscd +invalidates its cache: +.P +.in +4n +.EX +$ \fBnscd \-i\fP \fI\fP +.EE +.in +.SH SEE ALSO +.BR nscd.conf (5), +.BR nsswitch.conf (5) +.\" .SH AUTHOR +.\" .B nscd +.\" was written by Thorsten Kukuk and Ulrich Drepper. diff --git a/man/man8/sln.8 b/man/man8/sln.8 new file mode 100644 index 0000000..0bb74c8 --- /dev/null +++ b/man/man8/sln.8 @@ -0,0 +1,44 @@ +.\" Copyright (c) 2013 by Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sln 8 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sln \- create symbolic links +.SH SYNOPSIS +.nf +.BI sln " source dest" +.BI sln " filelist" +.fi +.SH DESCRIPTION +The +.B sln +program creates symbolic links. +Unlike the +.BR ln (1) +program, it is statically linked. +This means that if for some reason the dynamic linker is not working, +.B sln +can be used to make symbolic links to dynamic libraries. +.P +The command line has two forms. +In the first form, it creates +.I dest +as a new symbolic link to +.IR source . +.P +In the second form, +.I filelist +is a list of space-separated pathname pairs, +and the effect is as if +.B sln +was executed once for each line of the file, +with the two pathnames as the arguments. +.P +The +.B sln +program supports no command-line options. +.SH SEE ALSO +.BR ln (1), +.BR ld.so (8), +.BR ldconfig (8) diff --git a/man/man8/tzselect.8 b/man/man8/tzselect.8 new file mode 100644 index 0000000..ee03161 --- /dev/null +++ b/man/man8/tzselect.8 @@ -0,0 +1,125 @@ +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. +.TH tzselect 8 "" "Time Zone Database" +.SH NAME +tzselect \- select a timezone +.SH SYNOPSIS +.ie \n(.g .ds - \f(CR-\fP +.el .ds - \- +.ds d " degrees +.ds m " minutes +.ds s " seconds +.ds _ " \& +.if t \{\ +. if \n(.g .if c \(de .if c \(fm .if c \(sd \{\ +. ds d \(de +. ds m \(fm +. ds s \(sd +. ds _ \| +. \} +.\} +.B tzselect +[ +.B \*-c +.I coord +] [ +.B \*-n +.I limit +] [ +.B \*-\*-help +] [ +.B \*-\*-version +] +.SH DESCRIPTION +The +.B tzselect +program asks the user for information about the current location, +and outputs the resulting timezone to standard output. +The output is suitable as a value for the TZ environment variable. +.PP +All interaction with the user is done via standard input and standard error. +.SH OPTIONS +.TP +.BI "\*-c " coord +Instead of asking for continent and then country and then city, +ask for selection from time zones whose largest cities +are closest to the location with geographical coordinates +.I coord. +Use ISO 6709 notation for +.I coord, +that is, a latitude immediately followed by a longitude. The latitude +and longitude should be signed integers followed by an optional +decimal point and fraction: positive numbers represent north and east, +negative south and west. Latitudes with two and longitudes with three +integer digits are treated as degrees; latitudes with four or six and +longitudes with five or seven integer digits are treated as +.I "DDMM, DDDMM, DDMMSS," +or +.I DDDMMSS +representing +.I DD +or +.I DDD +degrees, +.I MM +minutes, +and zero or +.I SS +seconds, with any trailing fractions represent fractional minutes or +(if +.I SS +is present) seconds. The decimal point is that of the current locale. +For example, in the (default) C locale, +.B "\*-c\ +40.689\*-074.045" +specifies 40.689\*d\*_N, 74.045\*d\*_W, +.B "\*-c\ +4041.4\*-07402.7" +specifies 40\*d\*_41.4\*m\*_N, 74\*d\*_2.7\*m\*_W, and +.B "\*-c\ +404121\*-0740240" +specifies 40\*d\*_41\*m\*_21\*s\*_N, 74\*d\*_2\*m\*_40\*s\*_W. +If +.I coord +is not one of the documented forms, the resulting behavior is unspecified. +.TP +.BI "\*-n " limit +When +.B \*-c +is used, display the closest +.I limit +locations (default 10). +.TP +.B "\*-\*-help" +Output help information and exit. +.TP +.B "\*-\*-version" +Output version information and exit. +.SH "ENVIRONMENT VARIABLES" +.TP +\f3AWK\fP +Name of a POSIX-compliant +.B awk +program (default: +.BR awk ). +.TP +\f3TZDIR\fP +Name of the directory containing timezone data files (default: +.BR /usr/share/zoneinfo ). +.SH FILES +.TP +\f2TZDIR\fP\f3/iso3166.tab\fP +Table of ISO 3166 2-letter country codes and country names. +.TP +\f2TZDIR\fP\f3/zone1970.tab\fP +Table of country codes, latitude and longitude, timezones, and +descriptive comments. +.TP +\f2TZDIR\fP\f3/\fP\f2TZ\fP +Timezone data file for timezone \f2TZ\fP. +.SH "EXIT STATUS" +The exit status is zero if a timezone was successfully obtained from the user, +nonzero otherwise. +.SH "SEE ALSO" +newctime(3), tzfile(5), zdump(8), zic(8) +.SH NOTES +Applications should not assume that +.BR tzselect 's +output matches the user's political preferences. diff --git a/man/man8/zdump.8 b/man/man8/zdump.8 new file mode 100644 index 0000000..c3f0bba --- /dev/null +++ b/man/man8/zdump.8 @@ -0,0 +1,230 @@ +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. +.TH zdump 8 "" "Time Zone Database" +.SH NAME +zdump \- timezone dumper +.SH SYNOPSIS +.B zdump +[ +.I option +\&... ] [ +.I timezone +\&... ] +.SH DESCRIPTION +.ie '\(lq'' .ds lq \&"\" +.el .ds lq \(lq\" +.ie '\(rq'' .ds rq \&"\" +.el .ds rq \(rq\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +.ie \n(.g .ds - \f(CR-\fP +.el .ds - \- +The +.B zdump +program prints the current time in each +.I timezone +named on the command line. +.SH OPTIONS +.TP +.B \*-\*-version +Output version information and exit. +.TP +.B \*-\*-help +Output short usage message and exit. +.TP +.B \*-i +Output a description of time intervals. For each +.I timezone +on the command line, output an interval-format description of the +timezone. See +.q "INTERVAL FORMAT" +below. +.TP +.B \*-v +Output a verbose description of time intervals. +For each +.I timezone +on the command line, +print the times at the two extreme time values, +the times (if present) at and just beyond the boundaries of years that +.BR localtime (3) +and +.BR gmtime (3) +can represent, and +the times both one second before and exactly at +each detected time discontinuity. +Each line is followed by +.BI isdst= D +where +.I D +is positive, zero, or negative depending on whether +the given time is daylight saving time, standard time, +or an unknown time type, respectively. +Each line is also followed by +.BI gmtoff= N +if the given local time is known to be +.I N +seconds east of Greenwich. +.TP +.B \*-V +Like +.BR \*-v , +except omit output concerning extreme time and year values. +This generates output that is easier to compare to that of +implementations with different time representations. +.TP +.BI "\*-c " \fR[\fIloyear , \fR]\fIhiyear +Cut off interval output at the given year(s). +Cutoff times are computed using the proleptic Gregorian calendar with year 0 +and with Universal Time (UT) ignoring leap seconds. +Cutoffs are at the start of each year, where the lower-bound +timestamp is inclusive and the upper is exclusive; for example, +.B "\*-c 1970,2070" +selects transitions on or after 1970-01-01 00:00:00 UTC +and before 2070-01-01 00:00:00 UTC. +The default cutoff is +.BR \*-500,2500 . +.TP +.BI "\*-t " \fR[\fIlotime , \fR]\fIhitime +Cut off interval output at the given time(s), +given in decimal seconds since 1970-01-01 00:00:00 +Coordinated Universal Time (UTC). +The +.I timezone +determines whether the count includes leap seconds. +As with +.BR \*-c , +the cutoff's lower bound is inclusive and its upper bound is exclusive. +.SH "INTERVAL FORMAT" +The interval format is a compact text representation that is intended +to be both human- and machine-readable. It consists of an empty line, +then a line +.q "TZ=\fIstring\fP" +where +.I string +is a double-quoted string giving the timezone, a second line +.q "\*- \*- \fIinterval\fP" +describing the time interval before the first transition if any, and +zero or more following lines +.q "\fIdate time interval\fP", +one line for each transition time and following interval. Fields are +separated by single tabs. +.PP +Dates are in +.IR yyyy - mm - dd +format and times are in 24-hour +.IR hh : mm : ss +format where +.IR hh <24. +Times are in local time immediately after the transition. A +time interval description consists of a UT offset in signed +.RI \(+- hhmmss +format, a time zone abbreviation, and an isdst flag. An abbreviation +that equals the UT offset is omitted; other abbreviations are +double-quoted strings unless they consist of one or more alphabetic +characters. An isdst flag is omitted for standard time, and otherwise +is a decimal integer that is unsigned and positive (typically 1) for +daylight saving time and negative for unknown. +.PP +In times and in UT offsets with absolute value less than 100 hours, +the seconds are omitted if they are zero, and +the minutes are also omitted if they are also zero. Positive UT +offsets are east of Greenwich. The UT offset \*-00 denotes a UT +placeholder in areas where the actual offset is unspecified; by +convention, this occurs when the UT offset is zero and the time zone +abbreviation begins with +.q "\*-" +or is +.q "zzz". +.PP +In double-quoted strings, escape sequences represent unusual +characters. The escape sequences are \es for space, and \e", \e\e, +\ef, \en, \er, \et, and \ev with their usual meaning in the C +programming language. E.g., the double-quoted string +\*(lq"CET\es\e"\e\e"\*(rq represents the character sequence \*(lqCET +"\e\*(rq.\"" +.PP +.ne 9 +Here is an example of the output, with the leading empty line omitted. +(This example is shown with tab stops set far enough apart so that the +tabbed columns line up.) +.nf +.sp +.if \n(.g .ft CR +.in +2 +.nr w \w'1896-01-13 'u+\n(.i +.ta \w'1896-01-13\0\0'u +\w'12:01:26\0\0'u +\w'-103126\0\0'u +\w'HWT\0\0'u +TZ="Pacific/Honolulu" +- - -103126 LMT +1896-01-13 12:01:26 -1030 HST +1933-04-30 03 -0930 HDT 1 +1933-05-21 11 -1030 HST +1942-02-09 03 -0930 HWT 1 +1945-08-14 13:30 -0930 HPT 1 +1945-09-30 01 -1030 HST +1947-06-08 02:30 -10 HST +.in +.if \n(.g .ft +.sp +.fi +Here, local time begins 10 hours, 31 minutes and 26 seconds west of +UT, and is a standard time abbreviated LMT. Immediately after the +first transition, the date is 1896-01-13 and the time is 12:01:26, and +the following time interval is 10.5 hours west of UT, a standard time +abbreviated HST. Immediately after the second transition, the date is +1933-04-30 and the time is 03:00:00 and the following time interval is +9.5 hours west of UT, is abbreviated HDT, and is daylight saving time. +Immediately after the last transition the date is 1947-06-08 and the +time is 02:30:00, and the following time interval is 10 hours west of +UT, a standard time abbreviated HST. +.PP +.ne 10 +Here are excerpts from another example: +.nf +.sp +.if \n(.g .ft CR +.if t .in +.5i +.if n .in +2 +TZ="Europe/Astrakhan" +- - +031212 LMT +1924-04-30 23:47:48 +03 +1930-06-21 01 +04 +1981-04-01 01 +05 1 +1981-09-30 23 +04 +\&... +2014-10-26 01 +03 +2016-03-27 03 +04 +.in +.if \n(.g .ft +.sp +.fi +This time zone is east of UT, so its UT offsets are positive. Also, +many of its time zone abbreviations are omitted since they duplicate +the text of the UT offset. +.SH LIMITATIONS +Time discontinuities are found by sampling the results returned by +.BR localtime (3) +at twelve-hour intervals. +This works in all real-world cases; +one can construct artificial time zones for which this fails. +.PP +In the +.B \*-v +and +.B \*-V +output, +.q "UT" +denotes the value returned by +.BR gmtime (3), +which uses UTC for modern timestamps and some other UT flavor for +timestamps that predate the introduction of UTC. +No attempt is currently made to have the output use +.q "UTC" +for newer and +.q "UT" +for older timestamps, partly because the exact date of the +introduction of UTC is problematic. +.SH SEE ALSO +.BR tzfile (5), +.BR zic (8) diff --git a/man/man8/zic.8 b/man/man8/zic.8 new file mode 100644 index 0000000..0ad373a --- /dev/null +++ b/man/man8/zic.8 @@ -0,0 +1,894 @@ +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. +.TH zic 8 "" "Time Zone Database" +.SH NAME +zic \- timezone compiler +.SH SYNOPSIS +.B zic +[ +.I option +\&... ] [ +.I filename +\&... ] +.SH DESCRIPTION +.ie '\(lq'' .ds lq \&"\" +.el .ds lq \(lq\" +.ie '\(rq'' .ds rq \&"\" +.el .ds rq \(rq\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +.ie '\(la'' .ds < < +.el .ds < \(la +.ie '\(ra'' .ds > > +.el .ds > \(ra +.ie \n(.g \{\ +. ds : \: +. ds - \f(CR-\fP +.\} +.el \{\ +. ds : +. ds - \- +.\} +.ds d " degrees +.ds m " minutes +.ds s " seconds +.ds _ " \& +.if t \{\ +. if \n(.g .if c \(de .if c \(fm .if c \(sd \{\ +. ds d \(de +. ds m \(fm +. ds s \(sd +. ds _ \| +. \} +.\} +The +.B zic +program reads text from the file(s) named on the command line +and creates the timezone information format (TZif) files +specified in this input. +If a +.I filename +is +.q "\*-" , +standard input is read. +.SH OPTIONS +.TP +.B "\*-\*-version" +Output version information and exit. +.TP +.B \*-\*-help +Output short usage message and exit. +.TP +.BI "\*-b " bloat +Output backward-compatibility data as specified by +.IR bloat . +If +.I bloat +is +.BR fat , +generate additional data entries that work around potential bugs or +incompatibilities in older software, such as software that mishandles +the 64-bit generated data. +If +.I bloat +is +.BR slim , +keep the output files small; this can help check for the bugs +and incompatibilities. +The default is +.BR slim , +as software that mishandles 64-bit data typically +mishandles timestamps after the year 2038 anyway. +Also see the +.B \*-r +option for another way to alter output size. +.TP +.BI "\*-d " directory +Create time conversion information files in the named directory rather than +in the standard directory named below. +.TP +.BI "\*-l " timezone +Use +.I timezone +as local time. +.B zic +will act as if the input contained a link line of the form +.sp +.ti +2 +.ta \w'Link\0\0'u +\w'\fItimezone\fP\0\0'u +Link \fItimezone\fP localtime +.sp +If +.I timezone +is +.BR \*- , +any already-existing link is removed. +.TP +.BI "\*-L " leapsecondfilename +Read leap second information from the file with the given name. +If this option is not used, +no leap second information appears in output files. +.TP +.BI "\*-p " timezone +Use +.IR timezone 's +rules when handling nonstandard +TZ strings like "EET\*-2EEST" that lack transition rules. +.B zic +will act as if the input contained a link line of the form +.sp +.ti +2 +Link \fItimezone\fP posixrules +.sp +If +.I timezone +is +.q "\*-" +(the default), any already-existing link is removed. +.sp +Unless +.I timezone is +.q "\*-" , +this option is obsolete and poorly supported. +Among other things it should not be used for timestamps after the year 2037, +and it should not be combined with +.B "\*-b slim" +if +.IR timezone 's +transitions are at standard time or Universal Time (UT) instead of local time. +.TP +.BR "\*-r " "[\fB@\fP\fIlo\fP][\fB/@\fP\fIhi\fP]" +Limit the applicability of output files +to timestamps in the range from +.I lo +(inclusive) to +.I hi +(exclusive), where +.I lo +and +.I hi +are possibly signed decimal counts of seconds since the Epoch +(1970-01-01 00:00:00 UTC). +Omitted counts default to extreme values. +The output files use UT offset 0 and abbreviation +.q "\*-00" +in place of the omitted timestamp data. +For example, +.q "zic \*-r @0" +omits data intended for negative timestamps (i.e., before the Epoch), and +.q "zic \*-r @0/@2147483648" +outputs data intended only for nonnegative timestamps that fit into +31-bit signed integers. +On platforms with GNU +.BR date , +.q "zic \*-r @$(date +%s)" +omits data intended for past timestamps. +Although this option typically reduces the output file's size, +the size can increase due to the need to represent the timestamp range +boundaries, particularly if +.I hi +causes a TZif file to contain explicit entries for +.RI pre- hi +transitions rather than concisely representing them +with an extended POSIX.1-2017 TZ string. +Also see the +.B "\*-b slim" +option for another way to shrink output size. +.TP +.BI "\*-R @" hi +Generate redundant trailing explicit transitions for timestamps +that occur less than +.I hi +seconds since the Epoch, even though the transitions could be +more concisely represented via the extended POSIX.1-2017 TZ string. +This option does not affect the represented timestamps. +Although it accommodates nonstandard TZif readers +that ignore the extended POSIX.1-2017 TZ string, +it increases the size of the altered output files. +.TP +.BI "\*-t " file +When creating local time information, put the configuration link in +the named file rather than in the standard location. +.TP +.B \*-v +Be more verbose, and complain about the following situations: +.RS +.PP +The input specifies a link to a link, +something not supported by some older parsers, including +.B zic +itself through release 2022e. +.PP +A year that appears in a data file is outside the range +of representable years. +.PP +A time of 24:00 or more appears in the input. +Pre-1998 versions of +.B zic +prohibit 24:00, and pre-2007 versions prohibit times greater than 24:00. +.PP +A rule goes past the start or end of the month. +Pre-2004 versions of +.B zic +prohibit this. +.PP +A time zone abbreviation uses a +.B %z +format. +Pre-2015 versions of +.B zic +do not support this. +.PP +A timestamp contains fractional seconds. +Pre-2018 versions of +.B zic +do not support this. +.PP +The input contains abbreviations that are mishandled by pre-2018 versions of +.B zic +due to a longstanding coding bug. +These abbreviations include +.q L +for +.q Link , +.q mi +for +.q min , +.q Sa +for +.q Sat , +and +.q Su +for +.q Sun . +.PP +The output file does not contain all the information about the +long-term future of a timezone, because the future cannot be summarized as +an extended POSIX.1-2017 TZ string. For example, as of 2023 this problem +occurs for Morocco's daylight-saving rules, as these rules are based +on predictions for when Ramadan will be observed, something that +an extended POSIX.1-2017 TZ string cannot represent. +.PP +The output contains data that may not be handled properly by client +code designed for older +.B zic +output formats. These compatibility issues affect only timestamps +before 1970 or after the start of 2038. +.PP +The output contains a truncated leap second table, +which can cause some older TZif readers to misbehave. +This can occur if the +.B "\*-L" +option is used, and either an Expires line is present or +the +.B "\*-r" +option is also used. +.PP +The output file contains more than 1200 transitions, +which may be mishandled by some clients. +The current reference client supports at most 2000 transitions; +pre-2014 versions of the reference client support at most 1200 +transitions. +.PP +A time zone abbreviation has fewer than 3 or more than 6 characters. +POSIX requires at least 3, and requires implementations to support +at least 6. +.PP +An output file name contains a byte that is not an ASCII letter, +.q "\*-" , +.q "/" , +or +.q "_" ; +or it contains a file name component that contains more than 14 bytes +or that starts with +.q "\*-" . +.RE +.SH FILES +Input files use the format described in this section; output files use +.BR tzfile (5) +format. +.PP +Input files should be text files, that is, they should be a series of +zero or more lines, each ending in a newline byte and containing at +most 2048 bytes counting the newline, and without any NUL bytes. +The input text's encoding +is typically UTF-8 or ASCII; it should have a unibyte representation +for the POSIX Portable Character Set (PPCS) +\* +and the encoding's non-unibyte characters should consist entirely of +non-PPCS bytes. Non-PPCS characters typically occur only in comments: +although output file names and time zone abbreviations can contain +nearly any character, other software will work better if these are +limited to the restricted syntax described under the +.B \*-v +option. +.PP +Input lines are made up of fields. +Fields are separated from one another by one or more white space characters. +The white space characters are space, form feed, carriage return, newline, +tab, and vertical tab. +Leading and trailing white space on input lines is ignored. +An unquoted sharp character (#) in the input introduces a comment which extends +to the end of the line the sharp character appears on. +White space characters and sharp characters may be enclosed in double quotes +(") if they're to be used as part of a field. +Any line that is blank (after comment stripping) is ignored. +Nonblank lines are expected to be of one of three types: +rule lines, zone lines, and link lines. +.PP +Names must be in English and are case insensitive. +They appear in several contexts, and include month and weekday names +and keywords such as +.BR "maximum" , +.BR "only" , +.BR "Rolling" , +and +.BR "Zone" . +A name can be abbreviated by omitting all but an initial prefix; any +abbreviation must be unambiguous in context. +.PP +A rule line has the form +.nf +.ti +2 +.ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00w\0\0'u +\w'1:00d\0\0'u +.sp +Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S +.sp +For example: +.ti +2 +.sp +Rule US 1967 1973 \*- Apr lastSun 2:00w 1:00d D +.sp +.fi +The fields that make up a rule line are: +.TP +.B NAME +Gives the name of the rule set that contains this line. +The name must start with a character that is neither +an ASCII digit nor +.q \*- +nor +.q + . +To allow for future extensions, +an unquoted name should not contain characters from the set +.ie \n(.g .q \f(CR!$%&\(aq()*,/:;<=>?@[\e]\(ha\(ga{|}\(ti\fP . +.el .ie t .q \f(CW!$%&'()*,/:;<=>?@[\e]^\(ga{|}~\fP . +.el .q !$%&'()*,/:;<=>?@[\e]^`{|}~ . +.TP +.B FROM +Gives the first year in which the rule applies. +Any signed integer year can be supplied; the proleptic Gregorian calendar +is assumed, with year 0 preceding year 1. +Rules can describe times that are not representable as time values, +with the unrepresentable times ignored; this allows rules to be portable +among hosts with differing time value types. +.TP +.B TO +Gives the final year in which the rule applies. +The word +.B maximum +(or an abbreviation) means the indefinite future, and the word +.B only +(or an abbreviation) +may be used to repeat the value of the +.B FROM +field. +.TP +.B \*- +Is a reserved field and should always contain +.q \*- +for compatibility with older versions of +.BR zic . +It was previously known as the +.B TYPE +field, which could contain values to allow a +separate script to further restrict in which +.q types +of years the rule would apply. +.TP +.B IN +Names the month in which the rule takes effect. +Month names may be abbreviated. +.TP +.B ON +Gives the day on which the rule takes effect. +Recognized forms include: +.nf +.in +2 +.sp +.ta \w'Sun<=25\0\0'u +5 the fifth of the month +lastSun the last Sunday in the month +lastMon the last Monday in the month +Sun>=8 first Sunday on or after the eighth +Sun<=25 last Sunday on or before the 25th +.fi +.in +.sp +A weekday name (e.g., +.BR "Sunday" ) +or a weekday name preceded by +.q "last" +(e.g., +.BR "lastSunday" ) +may be abbreviated or spelled out in full. +There must be no white space characters within the +.B ON +field. +The +.q <= +and +.q >= +constructs can result in a day in the neighboring month; +for example, the IN-ON combination +.q "Oct Sun>=31" +stands for the first Sunday on or after October 31, +even if that Sunday occurs in November. +.TP +.B AT +Gives the time of day at which the rule takes effect, +relative to 00:00, the start of a calendar day. +Recognized forms include: +.nf +.in +2 +.sp +.ta \w'00:19:32.13\0\0'u +2 time in hours +2:00 time in hours and minutes +01:28:14 time in hours, minutes, and seconds +00:19:32.13 time with fractional seconds +12:00 midday, 12 hours after 00:00 +15:00 3 PM, 15 hours after 00:00 +24:00 end of day, 24 hours after 00:00 +260:00 260 hours after 00:00 +\*-2:30 2.5 hours before 00:00 +\*- equivalent to 0 +.fi +.in +.sp +Although +.B zic +rounds times to the nearest integer second +(breaking ties to the even integer), the fractions may be useful +to other applications requiring greater precision. +The source format does not specify any maximum precision. +Any of these forms may be followed by the letter +.B w +if the given time is local or +.q "wall clock" +time, +.B s +if the given time is standard time without any adjustment for daylight saving, +or +.B u +(or +.B g +or +.BR z ) +if the given time is universal time; +in the absence of an indicator, +local (wall clock) time is assumed. +These forms ignore leap seconds; for example, +if a leap second occurs at 00:59:60 local time, +.q "1:00" +stands for 3601 seconds after local midnight instead of the usual 3600 seconds. +The intent is that a rule line describes the instants when a +clock/calendar set to the type of time specified in the +.B AT +field would show the specified date and time of day. +.TP +.B SAVE +Gives the amount of time to be added to local standard time when the rule is in +effect, and whether the resulting time is standard or daylight saving. +This field has the same format as the +.B AT +field +except with a different set of suffix letters: +.B s +for standard time and +.B d +for daylight saving time. +The suffix letter is typically omitted, and defaults to +.B s +if the offset is zero and to +.B d +otherwise. +Negative offsets are allowed; in Ireland, for example, daylight saving +time is observed in winter and has a negative offset relative to +Irish Standard Time. +The offset is merely added to standard time; for example, +.B zic +does not distinguish a 10:30 standard time plus an 0:30 +.B SAVE +from a 10:00 standard time plus a 1:00 +.BR SAVE . +.TP +.B LETTER/S +Gives the +.q "variable part" +(for example, the +.q "S" +or +.q "D" +in +.q "EST" +or +.q "EDT" ) +of time zone abbreviations to be used when this rule is in effect. +If this field is +.q \*- , +the variable part is null. +.PP +A zone line has the form +.sp +.nf +.ti +2 +.ta \w'Zone\0\0'u +\w'Asia/Amman\0\0'u +\w'STDOFF\0\0'u +\w'Jordan\0\0'u +\w'FORMAT\0\0'u +Zone NAME STDOFF RULES FORMAT [UNTIL] +.sp +For example: +.sp +.ti +2 +Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 01:00 +.sp +.fi +The fields that make up a zone line are: +.TP +.B NAME +The name of the timezone. +This is the name used in creating the time conversion information file for the +timezone. +It should not contain a file name component +.q ".\&" +or +.q ".." ; +a file name component is a maximal substring that does not contain +.q "/" . +.TP +.B STDOFF +The amount of time to add to UT to get standard time, +without any adjustment for daylight saving. +This field has the same format as the +.B AT +and +.B SAVE +fields of rule lines, except without suffix letters; +begin the field with a minus sign if time must be subtracted from UT. +.TP +.B RULES +The name of the rules that apply in the timezone or, +alternatively, a field in the same format as a rule-line SAVE column, +giving the amount of time to be added to local standard time +and whether the resulting time is standard or daylight saving. +If this field is +.B \*- +then standard time always applies. +When an amount of time is given, only the sum of standard time and +this amount matters. +.TP +.B FORMAT +The format for time zone abbreviations. +The pair of characters +.B %s +is used to show where the +.q "variable part" +of the time zone abbreviation goes. +Alternatively, a format can use the pair of characters +.B %z +to stand for the UT offset in the form +.RI \(+- hh , +.RI \(+- hhmm , +or +.RI \(+- hhmmss , +using the shortest form that does not lose information, where +.IR hh , +.IR mm , +and +.I ss +are the hours, minutes, and seconds east (+) or west (\-) of UT. +Alternatively, +a slash (/) +separates standard and daylight abbreviations. +To conform to POSIX, a time zone abbreviation should contain only +alphanumeric ASCII characters, +.q "+" +and +.q "\*-". +By convention, the time zone abbreviation +.q "\*-00" +is a placeholder that means local time is unspecified. +.TP +.B UNTIL +The time at which the UT offset or the rule(s) change for a location. +It takes the form of one to four fields YEAR [MONTH [DAY [TIME]]]. +If this is specified, +the time zone information is generated from the given UT offset +and rule change until the time specified, which is interpreted using +the rules in effect just before the transition. +The month, day, and time of day have the same format as the IN, ON, and AT +fields of a rule; trailing fields can be omitted, and default to the +earliest possible value for the missing fields. +.IP +The next line must be a +.q "continuation" +line; this has the same form as a zone line except that the +string +.q "Zone" +and the name are omitted, as the continuation line will +place information starting at the time specified as the +.q "until" +information in the previous line in the file used by the previous line. +Continuation lines may contain +.q "until" +information, just as zone lines do, indicating that the next line is a further +continuation. +.PP +If a zone changes at the same instant that a rule would otherwise take +effect in the earlier zone or continuation line, the rule is ignored. +A zone or continuation line +.I L +with a named rule set starts with standard time by default: +that is, any of +.IR L 's +timestamps preceding +.IR L 's +earliest rule use the rule in effect after +.IR L 's +first transition into standard time. +In a single zone it is an error if two rules take effect at the same +instant, or if two zone changes take effect at the same instant. +.PP +If a continuation line subtracts +.I N +seconds from the UT offset after a transition that would be +interpreted to be later if using the continuation line's UT offset and +rules, the +.q "until" +time of the previous zone or continuation line is interpreted +according to the continuation line's UT offset and rules, and any rule +that would otherwise take effect in the next +.I N +seconds is instead assumed to take effect simultaneously. +For example: +.br +.ne 7 +.nf +.in +2 +.ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'2006\0\0'u +\w'\*-\0\0'u +\w'Oct\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u +.sp +# Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S +Rule US 1967 2006 - Oct lastSun 2:00 0 S +Rule US 1967 1973 - Apr lastSun 2:00 1:00 D +.ta \w'# Zone\0\0'u +\w'America/Menominee\0\0'u +\w'STDOFF\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u +# Zone NAME STDOFF RULES FORMAT [UNTIL] +Zone America/Menominee \*-5:00 \*- EST 1973 Apr 29 2:00 + \*-6:00 US C%sT +.sp +.in +.fi +Here, an incorrect reading would be there were two clock changes on 1973-04-29, +the first from 02:00 EST (\*-05) to 01:00 CST (\*-06), +and the second an hour later from 02:00 CST (\*-06) to 03:00 CDT (\*-05). +However, +.B zic +interprets this more sensibly as a single transition from 02:00 CST (\*-05) to +02:00 CDT (\*-05). +.PP +A link line has the form +.sp +.nf +.ti +2 +.ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u +Link TARGET LINK-NAME +.sp +For example: +.sp +.ti +2 +Link Europe/Istanbul Asia/Istanbul +.sp +.fi +The +.B TARGET +field should appear as the +.B NAME +field in some zone line or as the +.B LINK-NAME +field in some link line. +The +.B LINK-NAME +field is used as an alternative name for that zone; +it has the same syntax as a zone line's +.B NAME +field. +Links can chain together, although the behavior is unspecified if a +chain of one or more links does not terminate in a Zone name. +A link line can appear before the line that defines the link target. +For example: +.sp +.ne 3 +.nf +.in +2 +.ta \w'Zone\0\0'u +\w'Greenwich\0\0'u +Link Greenwich G_M_T +Link Etc/GMT Greenwich +Zone Etc/GMT\0\00\0\0\*-\0\0GMT +.sp +.in +.fi +The two links are chained together, and G_M_T, Greenwich, and Etc/GMT +all name the same zone. +.PP +Except for continuation lines, +lines may appear in any order in the input. +However, the behavior is unspecified if multiple zone or link lines +define the same name. +.PP +The file that describes leap seconds can have leap lines and an +expiration line. +Leap lines have the following form: +.nf +.ti +2 +.ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u +.sp +Leap YEAR MONTH DAY HH:MM:SS CORR R/S +.sp +For example: +.ti +2 +.sp +Leap 2016 Dec 31 23:59:60 + S +.sp +.fi +The +.BR YEAR , +.BR MONTH , +.BR DAY , +and +.B HH:MM:SS +fields tell when the leap second happened. +The +.B CORR +field +should be +.q "+" +if a second was added +or +.q "\*-" +if a second was skipped. +The +.B R/S +field +should be (an abbreviation of) +.q "Stationary" +if the leap second time given by the other fields should be interpreted as UTC +or +(an abbreviation of) +.q "Rolling" +if the leap second time given by the other fields should be interpreted as +local (wall clock) time. +.PP +Rolling leap seconds were implemented back when it was not +clear whether common practice was rolling or stationary, +with concerns that one would see +Times Square ball drops where there'd be a +.q "3... 2... 1... leap... Happy New Year" +countdown, placing the leap second at +midnight New York time rather than midnight UTC. +However, this countdown style does not seem to have caught on, +which means rolling leap seconds are not used in practice; +also, they are not supported if the +.B \*-r +option is used. +.PP +The expiration line, if present, has the form: +.nf +.ti +2 +.ta \w'Expires\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +.sp +Expires YEAR MONTH DAY HH:MM:SS +.sp +For example: +.ti +2 +.sp +Expires 2020 Dec 28 00:00:00 +.sp +.fi +The +.BR YEAR , +.BR MONTH , +.BR DAY , +and +.B HH:MM:SS +fields give the expiration timestamp in UTC for the leap second table. +.br +.ne 22 +.SH "EXTENDED EXAMPLE" +Here is an extended example of +.B zic +input, intended to illustrate many of its features. +.nf +.in +2 +.ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u +.sp +# Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S +Rule Swiss 1941 1942 \*- May Mon>=1 1:00 1:00 S +Rule Swiss 1941 1942 \*- Oct Mon>=1 2:00 0 \*- +.sp .5 +Rule EU 1977 1980 \*- Apr Sun>=1 1:00u 1:00 S +Rule EU 1977 only \*- Sep lastSun 1:00u 0 \*- +Rule EU 1978 only \*- Oct 1 1:00u 0 \*- +Rule EU 1979 1995 \*- Sep lastSun 1:00u 0 \*- +Rule EU 1981 max \*- Mar lastSun 1:00u 1:00 S +Rule EU 1996 max \*- Oct lastSun 1:00u 0 \*- +.sp +.ta \w'# Zone\0\0'u +\w'Europe/Zurich\0\0'u +\w'0:29:45.50\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u +# Zone NAME STDOFF RULES FORMAT [UNTIL] +Zone Europe/Zurich 0:34:08 \*- LMT 1853 Jul 16 + 0:29:45.50 \*- BMT 1894 Jun + 1:00 Swiss CE%sT 1981 + 1:00 EU CE%sT +.sp +Link Europe/Zurich Europe/Vaduz +.sp +.in +.fi +In this example, the EU rules are for the European Union +and for its predecessor organization, the European Communities. +The timezone is named Europe/Zurich and it has the alias Europe/Vaduz. +This example says that Zurich was 34 minutes and 8 +seconds east of UT until 1853-07-16 at 00:00, when the legal offset +was changed to +7\*d\*_26\*m\*_22.50\*s, +which works out to 0:29:45.50; +.B zic +treats this by rounding it to 0:29:46. +After 1894-06-01 at 00:00 the UT offset became one hour +and Swiss daylight saving rules (defined with lines beginning with +.q "Rule Swiss") +apply. From 1981 to the present, EU daylight saving rules have +applied, and the UTC offset has remained at one hour. +.PP +In 1941 and 1942, daylight saving time applied from the first Monday +in May at 01:00 to the first Monday in October at 02:00. +The pre-1981 EU daylight-saving rules have no effect +here, but are included for completeness. Since 1981, daylight +saving has begun on the last Sunday in March at 01:00 UTC. +Until 1995 it ended the last Sunday in September at 01:00 UTC, +but this changed to the last Sunday in October starting in 1996. +.PP +For purposes of display, +.q "LMT" +and +.q "BMT" +were initially used, respectively. Since +Swiss rules and later EU rules were applied, the time zone abbreviation +has been CET for standard time and CEST for daylight saving +time. +.SH FILES +.TP +.I /etc/localtime +Default local timezone file. +.TP +.I /usr/share/zoneinfo +Default timezone information directory. +.SH NOTES +For areas with more than two types of local time, +you may need to use local standard time in the +.B AT +field of the earliest transition time's rule to ensure that +the earliest transition time recorded in the compiled file is correct. +.PP +If, +for a particular timezone, +a clock advance caused by the start of daylight saving +coincides with and is equal to +a clock retreat caused by a change in UT offset, +.B zic +produces a single transition to daylight saving at the new UT offset +without any change in local (wall clock) time. +To get separate transitions +use multiple zone continuation lines +specifying transition instants using universal time. +.SH SEE ALSO +.BR tzfile (5), +.BR zdump (8) -- cgit v1.2.3